feat: pdf viewer toegevoegd

project_docs/PDF_VIEWER_V1_DESIGN.md

@@ -0,0 +1,127 @@
+# PDF Viewer v1
+
+## 1. Doel
+PDF-viewing voegt nu directe waarde toe omdat PDF-bestanden in de huidige file manager al zichtbaar en selecteerbaar zijn, maar nog niet in de webui bekeken kunnen worden zonder externe tooling of downloadstap. Dat past logisch naast de bestaande text-viewer en video-viewer: elk veelvoorkomend bestandstype krijgt een passende read-only viewer, terwijl de dual-pane workflow intact blijft.
+
+## 2. Startgedrag
+Aanbevolen v1-gedrag:
+- `F3` opent de PDF viewer voor exact 1 geselecteerd PDF-bestand.
+- De bestaande `View`-knop hergebruikt dezelfde centrale view-dispatch en opent bij een PDF dezelfde PDF viewer.
+- Dit geldt alleen bij exact 1 geselecteerd item met extensie `.pdf`.
+- Bij geen selectie, multi-select, of niet-PDF blijft `F3` het bestaande view-gedrag respecteren of niets doen als `View` disabled zou zijn.
+- Gewone `Enter`-semantiek blijft intact en wordt niet gewijzigd voor PDF.
+
+## 3. Scope
+In scope voor v1:
+- alleen PDF
+- read-only
+- bekijken in modal
+- browser-native scrollen binnen de viewer
+- sluiten via `X` en `Escape`
+
+Niet in scope:
+- edit
+- annotatie
+- OCR
+- losse downloadfeature
+- page thumbnails
+- search in PDF-documenten
+- print-specifieke UI
+
+## 4. Viewer-richting
+Aanbevolen v1-richting: browser-native embedded PDF-view in een aparte modal.
+
+Concreet:
+- frontend opent een aparte PDF-modal
+- modal bevat een embedded viewer via `iframe` of `embed` naar een read-only backend endpoint
+- paginaweergave en scrollen worden aan de browser-PDF-viewer overgelaten
+- sluiten werkt via `X`, `Escape`, en eventueel overlay-click als dat consistent is met bestaande modals
+
+Waarom deze richting:
+- laag regressierisico
+- geen extra dependencies nodig
+- geen custom PDF rendering stack nodig
+- sluit aan op het bestaande modalmodel
+
+Niet aanbevolen voor v1:
+- eigen PDF-rendering met `pdf.js` of vergelijkbaar, tenzij later blijkt dat browser-native gedrag onvoldoende is
+- dat zou extra assets, integratie en regressierisico introduceren
+
+## 5. Backend-impact
+Aanbevolen: een apart read-only PDF endpoint, analoog aan video/view.
+
+Voorstel:
+- `GET /api/files/pdf?path=...`
+
+Eisen:
+- padvalidatie via bestaande `path_guard`
+- alleen files
+- directory -> bestaande `type_conflict`
+- path not found -> bestaande not-found fout
+- traversal / invalid root alias / outside whitelist -> bestaande securityfouten
+- `Content-Type: application/pdf`
+- streaming/read-only gedrag zonder onnodige buffering
+
+Waarom een apart endpoint:
+- expliciete content-type-afhandeling voor PDF
+- scheiding van concerns ten opzichte van tekst-view en video-streaming
+- eenvoudige frontend-integratie in een PDF-modal
+
+## 6. Frontend-impact
+Aanbevolen:
+- aparte PDF-modal, niet hergebruik van text-view modal
+- wel hergebruik van bestaande modalstijl en focusregels
+
+Gedrag:
+- `F3` en `View` dispatchen op bestandstype
+- tekstbestanden blijven naar text viewer gaan
+- video blijft naar video viewer gaan
+- PDF gaat naar PDF viewer
+- editorflow blijft ongemoeid
+
+Dat voorkomt regressie op bestaande viewers en houdt de semantiek per bestandstype helder.
+
+## 7. Risico's
+Belangrijkste risico's:
+- browserverschillen in ingebouwde PDF-weergave
+- sommige browsers of embedded contexten kunnen PDF anders tonen of beperkter ondersteunen
+- grote PDF-bestanden kunnen trager laden, maar browser-native streaming is nog steeds lichter dan custom rendering
+- security moet strikt read-only blijven via bestaande whitelist/path-guards
+- regressierisico in bestaande `F3`/`View` dispatchlogica als filetype-routing rommelig wordt geïmplementeerd
+
+Beperking voor v1:
+- geen garantie op identieke UX in elke browser
+- wel een veilige, kleine baseline voor moderne browsers met ingebouwde PDF-viewer
+
+## 8. Teststrategie
+Backend golden tests:
+- PDF endpoint success
+- directory -> `type_conflict`
+- path not found
+- traversal blocked
+- invalid root alias
+- non-pdf blocked of routed naar duidelijke fout
+
+UI smoke/regressietests:
+- PDF-modal container aanwezig
+- `F3` / `View` wiring aanwezig voor PDF-flow
+- bestaande text/video modal containers blijven aanwezig
+- geen regressie op huidige view-dispatch
+
+Handmatige validatie:
+- PDF openen via `F3`
+- PDF openen via `View`
+- sluiten via `X` en `Escape`
+- gewone `Enter` blijft ongewijzigd
+- text/video viewers blijven correct openen
+- groot PDF-bestand laadt zonder de UI te blokkeren
+
+## 9. Aanbeveling
+Aanbevolen v1-richting met laag regressierisico:
+- gebruik een apart read-only backend endpoint voor PDF
+- gebruik browser-native embedded PDF-weergave in een aparte modal
+- laat `F3` en `View` dezelfde type-dispatch gebruiken
+- houd PDF strikt read-only
+- voeg geen externe PDF-library of rendering stack toe in v1
+
+Dit levert de kleinste veilige stap op: bruikbare PDF-viewing, minimale architectuurimpact, en geen onnodige verbreding van scope.