webmanager-mvp/project_docs/IMAGE_VIEWER_AND_INFO_V1.md

IMAGE_VIEWER_AND_INFO_V1.md

1. Doel

Een volledige image viewer voegt nu directe waarde toe omdat de app al image-bestanden kan tonen in de lijst, thumbnails kent, en type-specifieke viewers heeft voor tekst, video en PDF. Voor afbeeldingen ontbreekt nog de logische volgende stap: het geselecteerde bestand volledig bekijken zonder download- of externe viewerstap.

Een kleine uitbreiding van File Info met image-specifieke metadata voegt ook waarde toe. Voor afbeeldingen zijn afmetingen vaak net zo relevant als naam, grootte en modified time. Dat helpt bij snelle selectie, kwaliteitscontrole en onderscheid tussen vergelijkbare bestanden.

Dit past goed binnen de bestaande dual-pane workflow zolang:

• openen een lichte modalactie blijft
• de browse-flow niet verandert
• de info-uitbreiding read-only en goedkoop blijft

2. Scope

In scope voor v1:

• volledige image viewer voor:
  • jpg
  • jpeg
  • png
  • webp
  • gif
  • bmp
  • avif als browser-native rendering zonder extra complexiteit werkt
• aparte image-modal
• read-only
• standaard fit-to-view
• basis zoom:
  • zoom in
  • zoom out
  • reset
• File Info uitbreiding met:
  • width
  • height

Niet in scope:

• edit
• crop/rotate
• slideshow
• metadata editor
• EXIF-inspectie als brede feature
• thumbnails in de viewer
• multi-image navigation

Aanbevolen v1-richting:

• jpg/jpeg/png/webp/gif/bmp volwaardig ondersteunen
• avif best-effort, zonder extra garanties
• geen extra dependency alleen om avif of exotische metadata te forceren

3. Startgedrag

Aanbevolen v1-gedrag:

• F3 opent de image viewer bij exact 1 geselecteerd image-bestand
• de bestaande View-knop gebruikt dezelfde centrale type-dispatch
• gewone Enter-semantiek blijft intact

Concreet:

• F3 / View dispatch:
  • tekst -> text viewer
  • video -> video viewer
  • pdf -> pdf viewer
  • image -> image viewer
• bij geen selectie of multi-select doet F3 niets als View disabled zou zijn
• directory-open gedrag via gewone Enter of directorynaam blijft onaangetast

4. Viewer-richting

Aanbevolen v1-richting: aparte image-modal met browser-native afbeeldingselement (img) en lichte frontend-zoom.

Waarom:

• geen extra dependency nodig
• laag regressierisico
• goed te combineren met bestaande modalarchitectuur
• voldoende voor een bruikbare eerste viewer

Aanbevolen UX:

• afbeelding centraal in een aparte modal
• standaard fit-to-view
• controls:
  • Zoom in
  • Zoom out
  • Reset
• sluiten via:
  • X
  • Escape
• overlay-click alleen meenemen als dat geen conflict geeft met zoom/pan-interactie; anders weglaten in v1

Pannen/slepen:

• optioneel in v1
• alleen toevoegen als licht en stabiel
• geen ingewikkelde canvas/viewer-stack bouwen

Aanbevolen minimalistische v1:

• CSS transform zoom
• centreren zolang mogelijk
• eventueel natuurlijke browser-scroll/pan bij grotere zoom, in plaats van custom drag-logica

5. Backend-impact

Aanbevolen backendrichting:

• nieuw read-only image endpoint, analoog aan PDF/video, bijvoorbeeld:
  • GET /api/files/image?path=...

Waarom een apart endpoint beter is dan hergebruik van random file-serving:

• consistente foutmapping
• duidelijke content-type-afhandeling
• hergebruik van bestaande path_guard
• expliciete scheiding van concerns per viewertype

Eisen:

• padvalidatie via bestaand path_guard
• alleen files
• directory -> bestaande type_conflict
• path not found -> bestaande not-found fout
• traversal / invalid root alias / outside whitelist -> bestaande securityfouten
• streaming/serving zonder onnodige buffering
• passend Content-Type

Geen nieuwe backendsemantiek nodig buiten een read-only route.

6. Frontend-impact

Aanbevolen frontendrichting:

• aparte image-modal
• geen hergebruik van text/video/pdf modalbody
• wel dezelfde modalstructuur en focusregels als bestaande viewers

Waarom een aparte modal:

• image viewing heeft eigen interactie (fit/zoom)
• voorkomt rommelige uitzonderingslogica in de bestaande text viewer
• houdt type-dispatch helder

Focusgedrag:

• terwijl image-modal open is, geen paneelkeyboardnavigatie
• Escape sluit modal
• F3 en View blijven via dezelfde dispatch werken

7. File Info uitbreiding

Aanbevolen extra velden voor image-bestanden in v1:

• width
• height
• content_type

Optioneel, maar niet nodig voor v1:

• kleurprofiel
• EXIF orientation
• camera metadata
• creation date uit EXIF

Aanbevolen aanpak:

• alleen goedkope metadata
• afmetingen server-side afleiden zonder zware analyse
• geen brede EXIF feature

Voor niet-image bestanden blijven width en height gewoon null.

8. Regressierisico

Belangrijkste risico's:

• view-dispatch wordt rommeliger als image niet netjes als eigen type wordt behandeld
• modalfocus kan bestaande keyboardflow blokkeren of laten lekken
• grote afbeeldingen kunnen trager laden of veel viewport-ruimte vragen
• File Info response-uitbreiding moet backward-compatible blijven

Mitigatie:

• aparte image-modal
• eigen isImageSelection(...) helper in dezelfde dispatchstijl als video/pdf
• geen wijziging aan gewone Enter
• alleen extra velden aan File Info toevoegen, geen bestaande velden wijzigen
• zoom klein en beheersbaar houden

9. Teststrategie

Backend golden tests:

• image endpoint success voor ondersteund imagebestand
• directory -> type_conflict
• path not found
• traversal blocked
• invalid root alias
• non-image blocked of duidelijke unsupported fout
• File Info success voor imagebestand met width/height
• File Info voor niet-image met width/height = null

UI smoke/regressietests:

• image-modal container aanwezig
• image viewer wiring aanwezig in F3/View dispatch
• text/video/pdf modal containers blijven aanwezig
• File Info modal blijft aanwezig
• geen extra zichtbare knop toegevoegd

Handmatige validatie:

• F3 opent image viewer bij exact 1 image
• View opent dezelfde image viewer
• zoom in/out/reset werkt
• sluiten via X en Escape werkt
• gewone Enter blijft directory/open-semantiek houden
• File Info toont width/height voor images
• grote afbeelding blijft bruikbaar zonder layoutbreuk

10. Aanbeveling

Aanbevolen v1-richting met laag regressierisico:

• nieuw read-only image endpoint
• aparte image-modal met browser-native img
• lichte zoombediening zonder externe image-viewer library
• F3 en View gebruiken de bestaande centrale type-dispatch
• File Info uitbreiden met alleen goedkope image metadata:
  • width
  • height
  • bestaand content_type
• avif alleen best-effort, zonder extra dependency of browsergarantie

Dit houdt de stap klein, veilig en consistent met de bestaande architectuur:

• viewers blijven type-specifiek
• File Info blijft read-only
• browse- en keyboardflow blijven intact