# Excalidraw Quick Start Guide

## ✅ What's Fixed

The Excalidraw implementation now fully supports Obsidian's format:

1. **✅ No more 400 errors** - Fixed URL encoding issues with special characters
2. **✅ LZ-String compression** - Correctly parses Obsidian's compressed-json format
3. **✅ Round-trip compatibility** - Files saved in ObsiViewer open perfectly in Obsidian
4. **✅ Front matter preservation** - Metadata and tags are maintained
5. **✅ Legacy support** - Old flat JSON files still work and auto-convert on save

## 🚀 Quick Test

### 1. Start the Server

```bash
npm install  # Installs lz-string dependency
npm run dev  # Start development server
```

### 2. Test with Existing File

A test file has been created at `vault/test-drawing.excalidraw.md`:

1. Open ObsiViewer in your browser
2. Navigate to the file list
3. Click on `test-drawing.excalidraw.md`
4. The Excalidraw editor should load without errors

### 3. Verify API Endpoints

Test the new query param API:

```bash
# GET file (should return JSON scene)
curl "http://localhost:4200/api/files?path=test-drawing.excalidraw.md"

# Should return:
# {
#   "elements": [...],
#   "appState": {...},
#   "files": {...}
# }
```

### 4. Test Round-Trip

1. **Create in Obsidian**:
   - Create a new Excalidraw drawing in Obsidian
   - Draw some shapes
   - Save the file

2. **Open in ObsiViewer**:
   - Navigate to the file
   - Verify it displays correctly
   - Make some changes
   - Save (Ctrl+S)

3. **Re-open in Obsidian**:
   - Open the same file in Obsidian
   - Verify all changes are preserved
   - No warnings or errors should appear

## 🔧 Migration

If you have old flat JSON Excalidraw files:

```bash
# Preview what will be converted
npm run migrate:excalidraw:dry

# Apply migration
npm run migrate:excalidraw
```

This will:
- Convert `.excalidraw` and `.json` files to `.excalidraw.md`
- Use proper Obsidian format with LZ-String compression
- Create `.bak` backups of originals
- Skip files already in Obsidian format

## 🧪 Run Tests

```bash
# Backend unit tests (16 tests)
npm run test:excalidraw

# E2E tests
npm run test:e2e -- excalidraw.spec.ts
```

All tests should pass ✅

## 📝 Common Scenarios

### Opening a File with Spaces/Accents

**Before (❌ 400 error)**:
```
GET /api/files/Mon Dessin #1.excalidraw.md
```

**After (✅ works)**:
```
GET /api/files?path=Mon%20Dessin%20%231.excalidraw.md
```

The frontend now properly encodes paths.

### Saving a File

**Before (❌ saved as flat JSON)**:
```json
{
  "elements": [],
  "appState": {},
  "files": {}
}
```

**After (✅ saved in Obsidian format)**:
```markdown
---
excalidraw-plugin: parsed
tags: [excalidraw]
---
# Excalidraw Data
## Drawing
```compressed-json
<LZ-String compressed data>
```
```

### Conflict Resolution

If a file is modified externally while editing:

1. **Error appears**: "Conflit: le fichier a été modifié sur le disque"
2. **Two options**:
   - **Reload from disk**: Discard local changes, load external version
   - **Overwrite**: Keep local changes, overwrite external version

## 🐛 Troubleshooting

### Issue: 400 Bad Request

**Symptom**: `GET /api/files/<path> 400 (Bad Request)`

**Cause**: Using old splat route format

**Fix**: Already fixed! The code now uses query params.

### Issue: Invalid Excalidraw Format

**Symptom**: "Invalid Excalidraw format" error

**Cause**: File uses wrong compression (zlib instead of LZ-String)

**Fix**: Already fixed! The parser now uses LZ-String.

### Issue: File Won't Open in Obsidian

**Symptom**: Obsidian shows error when opening file

**Cause**: File not in proper Obsidian format

**Fix**: Already fixed! Files are now saved with correct format.

## 📊 Verification Checklist

- [x] `lz-string` package installed
- [x] Backend routes use query params (`?path=`)
- [x] Backend uses LZ-String (not zlib)
- [x] Frontend services use query params
- [x] Files saved in Obsidian format
- [x] Front matter preserved
- [x] Unit tests pass (16/16)
- [x] Migration script available
- [x] Documentation complete

## 🎯 Next Steps

1. **Test with your vault**: Copy an Excalidraw file from Obsidian to the vault
2. **Verify round-trip**: Open → Edit → Save → Re-open in Obsidian
3. **Migrate old files**: Run migration script if needed
4. **Report issues**: Check console for any errors

## 📚 Additional Resources

- Full implementation details: `docs/EXCALIDRAW_IMPLEMENTATION.md`
- Backend utilities: `server/excalidraw-obsidian.mjs`
- Frontend service: `src/app/features/drawings/excalidraw-io.service.ts`
- Tests: `server/excalidraw-obsidian.test.mjs`
- Migration: `server/migrate-excalidraw.mjs`