webmanager-mvp/project_docs/PDF_VIEWER_V1_DESIGN.md

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.