ObsiViewer/docs/EXCALIDRAW/EXCALIDRAW_QUICK_START.md

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

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:

# 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:

# 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

# 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):

{
  "elements": [],
  "appState": {},
  "files": {}
}

After (✅ saved in Obsidian format):

---
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`