webmanager-mvp/project_docs/MONACO_EDITOR_V1_DESIGN.md

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.