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.