# Monaco Editor v1 ## 1. Doel Monaco voegt nu waarde toe omdat de huidige textarea-editor functioneel is, maar beperkt blijft voor code- en configbestanden. Voor deze app is de winst vooral: betere leesbaarheid, syntax highlighting, line numbers, current-line focus en een meer betrouwbare editervaring voor technische bestanden. Dit past naast de bestaande text editor modal als een vervanging van de edit-UI, niet als een nieuwe backendflow. De bestaande backend read/save-flow bestaat al en moet ongewijzigd worden hergebruikt: - initial read via de bestaande edit/view-flow - save via het bestaande save-endpoint - bestaande conflict- en io_error-semantiek blijven leidend Het doel is een "VS Code light"-achtige ervaring voor 1 bestand tegelijk, zonder IDE-verbreding. ## 2. Scope In scope voor v1: - Monaco Editor in een modal - F4 opent Monaco voor ondersteunde tekst/codebestanden - syntax highlighting - line numbers - current line highlight - save via bestaande save-flow - dirty state behouden - conflict handling behouden - light/dark theme-integratie Niet in scope voor v1: - LSP - autocomplete op IDE-niveau - multi-tab editor - diff editor - command palette - file tree in de modal - symbol outline - search panel met geavanceerde editorfeatures - plugin- of extensionmodel ## 3. Integratierichting Aanbevolen route: moderne browser-side Monaco-integratie met de officiële ESM-distributie van `monaco-editor`, gebundeld als statische frontend-assets voor deze app. Aanbevolen technische richting: - Monaco alleen lazy loaden wanneer de edit modal voor het eerst opent - editor-instance per modal-open lifecycle aanmaken - bij sluiten altijd `editor.dispose()` en eventuele model cleanup uitvoeren - per geopend bestand 1 model tegelijk gebruiken - bestaande modal DOM behouden, maar de textarea vervangen door een editor host-container Waarom deze route: - sluit aan op de huidige lichte frontend zonder volledige frameworkmigratie - voorkomt dat Monaco initieel alle schermen vertraagt - houdt lifecycle beheersbaar Belangrijke lifecycle-regels: - editor pas initialiseren nadat modal zichtbaar is en afmetingen stabiel zijn - bij heropenen van een ander bestand geen oude editor hergebruiken zonder expliciete reset - model en listeners bij sluiten expliciet opruimen - resize van modal/viewport koppelen aan `editor.layout()` zolang modal open is ## 4. Taalondersteuning Minimale extensie/bestandsnaammapping voor v1: - `js`, `mjs`, `cjs` -> `javascript` - `ts`, `tsx` -> `typescript` - `json` -> `json` - `css` -> `css` - `html`, `htm` -> `html` - `xml` -> `xml` - `yml`, `yaml` -> `yaml` - `py` -> `python` - `sh`, `bash`, `zsh`, `fish` -> `shell` - `md`, `markdown` -> `markdown` - `txt`, `log`, `ini`, `cfg`, `conf` -> `plaintext` - `Dockerfile`, `Containerfile` -> `dockerfile` V1-verwachting per taal: - syntax highlighting voor alle bovenstaande talen - bracket matching / basic Monaco editor behavior waar Monaco dat standaard biedt - geen extra taalservices of projectintelligentie buiten wat Monaco standaard client-side levert Pragmatische keuze: - v1 focust op highlighting en nette editing - rijkere taalfeatures zijn een bijeffect van Monaco waar beschikbaar, maar geen contract ## 5. Theme-integratie Monaco moet aansluiten op de bestaande light/dark mode. Aanbevolen v1-richting: - dark mode -> Monaco `vs-dark` - light mode -> Monaco `vs` - alleen een custom Monaco theme toevoegen als kleurafwijking zichtbaar storend is Dit houdt regressierisico laag. De rest van de UI blijft leidend; Monaco hoeft in v1 niet pixel-perfect het app-thema te kopieren, zolang het visueel coherent is. ## 6. Modal-UX Aanbevolen editor-modal: - groot, bijna viewport-vullend - duidelijk groter dan de huidige eenvoudige edit-modal - behoud van titelbalk met bestandsnaam/pad - behoud van `Save`, `Cancel` en `X` Gedrag: - `Save` gebruikt bestaande save-flow - `Cancel` sluit alleen zonder prompt als niet dirty - `X` volgt hetzelfde gedrag als `Cancel` - `Escape`: - zonder wijzigingen -> sluit - met wijzigingen -> bestaande discard-waarschuwing behouden Keyboard/focus: - terwijl Monaco open is, mogen paneelshortcuts niet ingrijpen - editor krijgt focus direct na openen - modal blijft de enige actieve interactiezone totdat hij sluit ## 7. Regressiebehoud Moet functioneel behouden blijven: - bestaande F4 edit-semantiek - bestaande backend save/conflict-flow - bestaande optimistic locking / expected_modified gedrag - bestaande dirty-state logica - bestaande text/video/pdf viewers - bestaande browse- en paneelworkflow buiten de modal Niet doen in v1: - backend save-contract wijzigen - nieuwe backend editorfeatures toevoegen - bestaande foutcodes of response-shapes wijzigen ## 8. Performance en risico Belangrijkste risico's: - Monaco vergroot frontend bundle/load - editor initialisatie is zwaarder dan textarea - foutieve dispose kan memory leaks geven - taalbundels kunnen groter zijn dan nodig Laag-risico aanpak: - lazy load alleen bij eerste edit-open - alleen de noodzakelijke Monaco assets shippen - geen extra taalplugins of worker-uitbreidingen toevoegen buiten wat nodig is - editor instance altijd disposer'en bij sluiten Reële tradeoff: - Monaco is zwaarder dan strikt nodig voor een kleine file manager - maar de UX-winst voor code/config editing is groot genoeg als de integratie sober blijft ## 9. Teststrategie UI smoke/regressietests: - Monaco host-container aanwezig in edit modal - F4 wiring blijft aanwezig - `Save`, `Cancel`, `X` blijven aanwezig - bestaande edit modalflow blijft openen/sluiten - light/dark theme blijft editor-opening niet breken Handmatige validatie: - openen van ondersteund codebestand via F4 - syntax highlighting voor representatieve typen: - js - json - yaml - py - markdown - Dockerfile - save success - save conflict - cancel/escape met dirty state - herhaald open/close van editor zonder UI-vertraging of kapotte focus - switch tussen light/dark terwijl editor open of dicht is ## 10. Aanbeveling Aanbevolen v1-richting met laag regressierisico: - vervang de huidige textarea-editor UI door een Monaco-modal - hergebruik ongewijzigd de bestaande backend read/save-flow - beperk v1 tot syntax highlighting, line numbers, current line highlight en nette modal-UX - gebruik Monaco lazy-loaded en dispose correct bij sluiten - gebruik standaard `vs` / `vs-dark` thema's tenzij er een duidelijke mismatch blijkt Niet proberen in v1: - IDE-features najagen - extra backendsemantiek toevoegen - editorflow verbreden naar meerdere bestanden of workspaceconcepten De juiste lat voor v1 is: betere editor-ergonomie zonder de app architectonisch zwaarder te maken dan nodig.