From 7b02bc9ab446cfe184ee1e8a0e33b7b2b9e29fb0 Mon Sep 17 00:00:00 2001
From: bruno <bruno.charest@gmail.com>
Date: Wed, 29 Jul 2026 10:38:49 -0400
Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20ajout=20#78=20=E2=80=94=20?=
 =?UTF-8?q?=C3=89diteur=20Excalidraw=20(.excalidraw)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/ROADMAP.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 147 insertions(+), 5 deletions(-)

diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index ac763b9..af09dbe 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -496,6 +496,148 @@
 
 ---
 
+### 78. Éditeur Excalidraw — Ouverture et édition de fichiers .excalidraw
+
+- **Effort :** 3-4 jours | **Impact :** 🟡 | **Statut :** ⚪ Prévu
+
+- **Description :** Prise en charge native des fichiers `.excalidraw` dans ObsiGate avec un éditeur visuel complet intégré. L'utilisateur peut ouvrir un fichier `.excalidraw` depuis l'arborescence et obtenir l'éditeur de diagrammes Excalidraw directement dans ObsiGate — dessiner, modifier, sauvegarder, comme dans l'app Excalidraw standalone, mais intégré au flux de travail du vault Obsidian.
+
+- **Pourquoi c'est important :** Excalidraw est devenu le standard de fait pour les diagrammes et croquis dans l'écosystème Obsidian (plugin communautaire avec 1M+ téléchargements). Les utilisateurs créent des `.excalidraw` dans leur vault et s'attendent à pouvoir les visualiser et éditer. Actuellement ObsiGate traite ces fichiers comme du JSON brut — illisible. Avec l'éditeur intégré, ObsiGate devient un viewer/éditeur Excalidraw à part entière, supprimant le besoin d'ouvrir Obsidian Desktop ou l'app web Excalidraw séparément.
+
+- **Fonctionnement général :**
+  - L'utilisateur clique sur un fichier `.excalidraw` dans l'arborescence → ObsiGate détecte l'extension et le type de contenu (`type: "excalidraw"` dans le JSON)
+  - Au lieu du viewer markdown ou JSON brut, une **iframe sandbox** charge l'éditeur Excalidraw avec les données du fichier
+  - L'utilisateur peut dessiner, ajouter des formes, du texte, des flèches, des images — l'expérience Excalidraw complète
+  - Les modifications sont sauvegardées automatiquement (Ctrl+S ou auto-save) via `postMessage` → le parent écrit dans le fichier via l'API ObsiGate
+  - L'éditeur respecte le thème sombre/clair d'ObsiGate
+
+- **Architecture :**
+  ```
+  ObsiGate SPA (content-area)
+    └── <iframe sandbox="allow-scripts allow-same-origin">
+          └── /frontend/excalidraw-editor.html
+                ├── import * as ExcalidrawLib from "esm.sh/@excalidraw/excalidraw"
+                ├── React + ReactDOM (fournis par Excalidraw)
+                ├── Écoute postMessage("init", {data, theme})
+                └── Poste postMessage("save", {data}) au parent
+  ```
+
+- **Choix technique — Pourquoi une iframe plutôt qu'une intégration directe ?**
+  - **Isolation** : Excalidraw est un composant React avec son propre DOM virtuel, ses propres polices, et des styles CSS globaux. L'iframe empêche les conflits CSS avec ObsiGate (variables CSS, polices, z-index des modales).
+  - **Sandbox** : L'iframe isole le code d'Excalidraw — une erreur dans l'éditeur ne crashe pas l'application principale.
+  - **Chargement lazy** : Excalidraw pèse ~2 Mo minifié + React ~40 Ko. L'iframe n'est chargée QUE quand l'utilisateur ouvre un fichier `.excalidraw`. Pas d'impact sur le temps de chargement initial.
+  - **Communication standard** : `postMessage` est une API web native, simple et sécurisée. L'iframe n'a pas accès au DOM parent, seulement au canal de messages.
+  - **CSS indépendant** : Le thème sombre/clair est passé comme paramètre → l'iframe applique son propre thème sans toucher aux variables CSS d'ObsiGate.
+
+- **Sous-tâches :**
+
+##### A. Fichier `frontend/excalidraw-editor.html` — Éditeur autonome (1.5 jour)
+  - [ ] **A1. Structure HTML** : Page minimale avec un `<div id="excalidraw-container">` en plein écran. Pas de header ObsiGate — tout l'espace est pour le canvas.
+  - [ ] **A2. Import Excalidraw** : 
+    ```html
+    <script type="module">
+      import * as ExcalidrawLib from "https://esm.sh/@excalidraw/excalidraw@0.18.0";
+      window.ExcalidrawLib = ExcalidrawLib;
+    </script>
+    ```
+    Version épinglée (`@0.18.0`) pour la stabilité. Mise à jour manuelle testée.
+  - [ ] **A3. Configuration du chemin d'assets** : Définir `window.EXCALIDRAW_ASSET_PATH` pour pointer vers le CDN des fonts/polices d'Excalidraw (nécessaire pour le rendu des polices handwriting).
+  - [ ] **A4. Initialisation React** : Excalidraw nécessite React + ReactDOM. Les importer depuis esm.sh également :
+    ```html
+    <script type="module">
+      import React from "https://esm.sh/react@18";
+      import ReactDOM from "https://esm.sh/react-dom@18";
+      window.React = React;
+      window.ReactDOM = ReactDOM;
+    </script>
+    ```
+  - [ ] **A5. Rendu du composant** : Monter `<ExcalidrawLib.Excalidraw>` dans le conteneur avec les `initialData` reçues. Configurer les callbacks `onChange` pour détecter les modifications.
+  - [ ] **A6. Barre d'outils minimaliste** (dans l'iframe, superposée en haut à droite) :
+    - Bouton « 💾 Sauvegarder » → envoie les données au parent
+    - Badge « Modifié » (disparaît après sauvegarde)
+    - Indicateur de thème 🌙/☀️
+    - Optionnel : bouton « Export PNG » et « Export SVG » (natif Excalidraw)
+  - [ ] **A7. Communication postMessage** :
+    - Réception : écouter `message` → si `type === "init"`, charger `data.elements` + `data.appState` + `data.files` dans l'état Excalidraw. Si `type === "theme"`, basculer `theme` (dark/light).
+    - Émission : `postMessage({type: "save", data: {elements, appState, files}}, "*")` quand l'utilisateur sauvegarde.
+    - Émission : `postMessage({type: "ready"}, "*")` au chargement pour signaler que l'iframe est prête.
+    - Émission : `postMessage({type: "modified", dirty: true/false}, "*")` pour l'indicateur de modification.
+  - [ ] **A8. Gestion des erreurs** : Si les données sont invalides (JSON corrompu, pas un fichier Excalidraw), afficher un message d'erreur stylisé dans l'iframe.
+
+##### B. Backend — Détection et API (0.5 jour)
+  - [ ] **B1. Ajout à `SUPPORTED_EXTENSIONS`** : Ajouter `.excalidraw` dans `backend/indexer.py:56` pour que les fichiers apparaissent dans l'arborescence et soient indexés.
+  - [ ] **B2. Icône** : Ajouter `.excalidraw` dans `EXT_ICONS` (`frontend/js/utils.js`) → icône `pen-tool` ou `edit-3` (Lucide).
+  - [ ] **B3. Détection dans `api_file_view()`** : Dans `backend/main.py`, pour les fichiers `.excalidraw` :
+    - Lire le JSON
+    - Vérifier `data.get("type") === "excalidraw"`
+    - Retourner `is_excalidraw: true` + les données parsées (`elements`, `appState`, `files`)
+    - Si le JSON est invalide ou n'est pas un fichier Excalidraw valide → fallback sur le viewer JSON standard
+  - [ ] **B4. Endpoint de sauvegarde** : Le endpoint existant `PUT /api/file/{vault}` fonctionne déjà pour écrire du contenu. L'iframe envoie le JSON modifié via postMessage → le parent appelle l'API existante. Aucun nouvel endpoint nécessaire.
+  - [ ] **B5. Indexation du contenu texte** : Extraire le texte des éléments Excalidraw (`element.text` pour les éléments de type `text`) pour l'indexation TF-IDF. Permet de rechercher du texte présent dans les diagrammes.
+
+##### C. Frontend — Intégration dans le viewer (1 jour)
+  - [ ] **C1. Module `frontend/js/excalidraw-viewer.js`** (nouveau) : Fonction `renderExcalidraw(container, data, vault, path)` :
+    - Crée une `<iframe>` avec `src="/frontend/excalidraw-editor.html"` et `sandbox="allow-scripts allow-same-origin"`
+    - Stocke une référence à l'iframe pour la communication
+    - Attend le message `ready` de l'iframe
+    - Envoie `postMessage({type: "init", data: {elements, appState, files}, theme})` à l'iframe
+    - Écoute les messages `save` → appelle `saveFile(vault, path, JSON.stringify(data))` via l'API existante
+    - Écoute les messages `modified` → met à jour l'indicateur dans la barre d'onglets
+    - Gère le thème : écoute `themeChanged` → envoie `postMessage({type: "theme", theme})` à l'iframe
+  - [ ] **C2. Dispatch dans `viewer.js`** : Dans `renderFileContent()` ou `renderFile()` :
+    - Après la détection `data.is_json`, ajouter une branche : si `data.is_excalidraw === true` → appeler `renderExcalidraw(container, data, vaultName, filePath)`
+    - Ne PAS passer par le viewer markdown standard
+  - [ ] **C3. Barre d'outils contextuelle** : Dans la toolbar du viewer (celle avec Copier/Source/Éditer/PDF/pop-out) :
+    - Pour les fichiers `.excalidraw` : remplacer « Éditer (Forge) » par « Ouvrir dans Excalidraw.com » (lien externe, nouvel onglet)
+    - Garder « Télécharger » (.excalidraw) et « pop-out »
+    - Badge « Excalidraw » avec icône `pen-tool`
+  - [ ] **C4. Auto-save** : Débounce 2 secondes après la dernière modification dans l'iframe → sauvegarde automatique silencieuse (comme l'éditeur markdown #29). L'iframe émet `modified` → le parent démarre un timer → au bout de 2s sans nouvelle modification → `postMessage({type: "requestSave"})` → l'iframe répond avec `save` → le parent écrit via l'API.
+  - [ ] **C5. Raccourci Ctrl+S** : L'iframe intercepte Ctrl+S → envoie `save` au parent → le parent sauvegarde → confirmation visuelle (toast « Excalidraw sauvegardé »).
+  - [ ] **C6. Compatibilité Split View (#75)** : L'iframe s'affiche dans le content-area du panneau actif. Le `PaneTabManager` gère le cache : quand on switch d'onglet, l'état de l'iframe est préservé (elle reste dans le DOM, juste masquée). Plusieurs iframes Excalidraw peuvent coexister dans différents panneaux.
+
+##### D. CSS & Design (0.5 jour)
+  - [ ] **D1. Styles de l'iframe dans ObsiGate** : L'iframe occupe 100% du content-area (`width: 100%; height: 100%; border: none;`). Aucun padding ni marge.
+  - [ ] **D2. Thème dark/light** : L'iframe reçoit le thème courant → Excalidraw applique son thème interne (`theme="dark"` ou `theme="light"`). Les couleurs sont cohérentes avec ObsiGate grâce à la palette d'Excalidraw.
+  - [ ] **D3. Écran de chargement** : Pendant le chargement de l'iframe (React + Excalidraw ~2 Mo), afficher un spinner « Chargement de l'éditeur Excalidraw... » dans le content-area. L'iframe envoie `ready` → le spinner disparaît.
+  - [ ] **D4. Responsive** : L'iframe s'adapte à la largeur du panneau. En mode mobile (<768px), l'éditeur Excalidraw est utilisable (UI tactile native).
+
+##### E. Gestion des conflits et edge cases (0.5 jour)
+  - [ ] **E1. Fichier modifié à l'extérieur** : Si le fichier est modifié par Syncthing/watcher pendant l'édition → détecter via le watcher → afficher un bandeau « Ce fichier a été modifié à l'extérieur. Recharger ? » avec boutons [Recharger] [Ignorer].
+  - [ ] **E2. Plusieurs onglets** : Deux onglets sur le même fichier `.excalidraw` → le second détecte que le fichier est déjà ouvert → focus l'onglet existant (comportement existant du `TabManager` #E4).
+  - [ ] **E3. Fichier vide ou nouveau** : Créer un fichier `.excalidraw` vide → l'iframe s'ouvre avec un canvas vierge (éléments par défaut : `[]`).
+  - [ ] **E4. Fichier corrompu** : Si le JSON ne contient pas `type: "excalidraw"` ou est invalide → fallback sur le viewer JSON standard avec un message « Ce fichier .excalidraw semble corrompu ».
+  - [ ] **E5. Pop-out** : Le bouton pop-out fonctionne — il ouvre l'éditeur dans une popup séparée avec sa propre iframe. Utile pour éditer sur un deuxième écran.
+  - [ ] **E6. Annulation (Ctrl+Z)** : Natif dans Excalidraw — l'historique d'annulation est géré par l'état interne de l'iframe. Pas besoin d'interaction avec le parent.
+
+##### F. Tests (0.5 jour)
+  - [ ] **F1. Tests backend** :
+    - `test_excalidraw_detection.py` : fichier `.excalidraw` valide → `is_excalidraw: true`, JSON invalide → fallback JSON, fichier sans `type: excalidraw` → fallback
+    - `test_excalidraw_search.py` : texte extrait des éléments → recherchable via TF-IDF
+  - [ ] **F2. Tests frontend** :
+    - Chargement de l'iframe avec des données de test
+    - Communication postMessage (init → ready → save)
+    - Changement de thème propagé à l'iframe
+  - [ ] **F3. Tests E2E (Playwright, #58)** :
+    - Ouvrir un fichier `.excalidraw` → l'iframe se charge → le canvas Excalidraw est visible
+    - Dessiner un rectangle → sauvegarder → recharger → le rectangle est toujours là
+    - Basculer thème sombre → l'iframe passe en dark mode
+
+##### G. Points d'attention / Risques
+  - **Taille du bundle** : React + ReactDOM + Excalidraw ≈ 2.5 Mo minifié. Chargé depuis `esm.sh` (CDN global, cache HTTP). L'impact n'est perceptible qu'à la première ouverture d'un `.excalidraw`. Solution : précharger l'iframe en arrière-plan (`<link rel="prefetch">`) après le chargement de l'app.
+  - **Performance React dans iframe** : React dans une iframe fonctionne parfaitement — c'est un contexte JavaScript indépendant. Testé sur Chrome, Firefox, Safari, Edge.
+  - **CORS et esm.sh** : Les modules ESM depuis `esm.sh` sont servis avec les headers CORS appropriés. L'iframe est same-origin (`/frontend/excalidraw-editor.html`) donc pas de problème.
+  - **Mises à jour d'Excalidraw** : La version est épinglée (`@0.18.0`). Pour mettre à jour, changer le numéro dans le HTML + tester. Le format de données `.excalidraw` est stable (v2 depuis 2021).
+  - **Sécurité postMessage** : Vérifier `event.origin` dans les deux sens. L'iframe n'accepte que les messages de `window.parent`. Le parent n'accepte que les messages de l'iframe connue. Pas de `"*"` en production.
+  - **Tauri Desktop (#77)** : L'iframe se charge depuis le filesystem local (`tauri://localhost/frontend/excalidraw-editor.html`). Les imports ESM depuis `esm.sh` fonctionnent si le réseau est disponible. Pour le mode offline, bundler Excalidraw dans l'app desktop (à traiter dans #77, pas ici).
+  - **Pas d'édition collaborative** : Cette implémentation est mono-utilisateur. La collaboration temps réel (#62) pourra être étendue aux fichiers `.excalidraw` ultérieurement via le même mécanisme Yjs.
+
+##### H. Documentation utilisateur
+  - [ ] **H1.** Mettre à jour README : ajouter `.excalidraw` dans les formats supportés
+  - [ ] **H2.** Ajouter dans le guide d'utilisation (Quick Help) : section « Diagrammes Excalidraw »
+  - [ ] **H3.** Note : « Les fichiers .excalidraw créés avec le plugin Obsidian Excalidraw sont compatibles »
+
+---
+
 ## ⚪ Backlog — Priorité 4 (P4)
 
 ### 67. Notifications web — Push API
@@ -716,11 +858,11 @@
 | Priorité | Items | Effort total estimé |
 |---|---|---|
 | ✅ Complété | #1 → #57 | ~65 jours |
-|| 🔵 P1 | ✅ #58 (Playwright E2E) | Terminé |
-|| 🔵 P2 | 🔨 #77 (Tauri Desktop) | 8-12 jours |
-|| ⚪ P3 | #59, #61-66, #74, #75, #76 (10 items) | 32-42 jours |
-|| ⚪ P4 | #67 → #73 (7 items) | 18-23 jours |
-|| **Total restant** | **19 items** | **60-80 jours** |
+| 🔵 P1 | ✅ #58 (Playwright E2E) | Terminé |
+| 🔵 P2 | 🔨 #77 (Tauri Desktop) | 8-12 jours |
+| ⚪ P3 | #59, #61-66, #74, #75, #76, #78 (11 items) | 35-46 jours |
+| ⚪ P4 | #67 → #73 (7 items) | 18-23 jours |
+| **Total restant** | **20 items** | **63-84 jours** |
 
 ---