webmanager-mvp/project_docs/THUMBNAIL_V1_DESIGN.md_OUD

# Thumbnail v1 Design

## 1. Doel
Thumbnails voegen vooral waarde toe in directories met veel afbeeldingsbestanden: de gebruiker kan sneller visueel herkennen welk bestand relevant is zonder elk bestand afzonderlijk te openen. Binnen de huidige dual-pane workflow moet dit ondersteunend blijven en niet omslaan naar een galerij-UI. De lijst blijft primair een file-managerlijst.

Een aan/uit instelling is nodig omdat thumbnails extra I/O, extra requests en visuele drukte toevoegen. Sommige gebruikers willen maximale performance en een compactere lijst, vooral op grote directories of netwerkvolumes.

## 2. Scope
Aanbevolen veilige v1-scope:
- Wel:
  - image thumbnails voor `jpg`, `jpeg`, `png`, `webp`
- Niet in v1:
  - video thumbnails
  - pdf thumbnails
  - generieke document thumbnails
  - server-side media processing pipeline
  - embedded metadata-based speciale rendering

Aanbeveling: beperk v1 strikt tot browser-native renderbare image files. Dat houdt de backend klein, voorkomt extra dependencies en minimaliseert regressierisico.

## 3. UI-gedrag
### Thumbnail / icoon positie
Thumbnails of iconen komen altijd links van de bestandsnaam, in een vaste visuele slot binnen de naamkolom.

### Vaste uitlijning
Elke rij krijgt altijd dezelfde linker mediaslot:
- thumbnail als beschikbaar en thumbnails ingeschakeld zijn
- anders een passend icoon of placeholder

Dit geldt voor alle rijen, zodat naamkolom en tekstuitlijning stabiel blijven.

Aanbevolen gedrag:
- vaste slotbreedte, bijvoorbeeld 20 tot 28 px voor compacte v1
- thumbnails klein en uniform
- directories gebruiken een folder-icoon
- non-image files gebruiken een file-icoon
- image files zonder thumbnail of met thumbnails uit: ook file-icoon of neutrale image-placeholder

### Gedrag als thumbnails uit staan
Als `Show thumbnails` uit staat:
- directories tonen een folder-icoon
- files tonen een file-icoon
- de mediaslot links blijft bestaan
- de lijstuitlijning blijft identiek aan de toestand met thumbnails aan

Dit voorkomt visuele sprongen tussen beide modi.

## 4. Settings-integratie
De instelling komt in:
- `F1` -> `Settings` -> `General`
- settingnaam: `Show thumbnails`

Belangrijk:
- niet opslaan in browser `localStorage`
- wel persistent opslaan via backend in SQLite
- frontend leest de instelling bij app-start of bij openen van de settingsmodal
- wijziging wordt via backend opgeslagen en daarna direct toegepast in de UI

Aanbevolen model:
- aparte `settings` tabel in SQLite met key/value opslag
- minimaal sleutelgebruik in v1: `show_thumbnails`

## 5. Backend-impact
Aanbevolen minimale backenduitbreiding:
- aparte `settings` tabel
- eenvoudige read/write API, bijvoorbeeld:
  - `GET /api/settings`
  - `POST /api/settings`
- apart read-only thumbnail-endpoint, bijvoorbeeld:
  - `GET /api/files/thumbnail?path=...`

Waarom apart endpoint:
- browse-responses blijven klein
- thumbnail-fetches kunnen lazy gebeuren
- bestaande `path_guard` en whitelist-validatie blijven leidend

## 6. Thumbnail-bron
Aanbevolen v1-richting:
- aparte read-only thumbnail/image route
- geen inline base64 in browse-response
- geen volledige browse-response verrijken met binaire data

Veilige v1-aanpak:
- thumbnails alleen voor ondersteunde image files
- kleine preview in vaste slot
- als server-side downscale zonder dependency niet goed haalbaar is, dan liever een eenvoudige image-serving route gecombineerd met kleine frontendweergave en lazy loading

Geen aparte disk-cache in v1.

## 7. Lijstlayout en selectie-impact
### Mediaslot / icoon-slot
De naamkolom krijgt links een compacte vaste structuur:
- selectievakje
- mediaslot (thumbnail of icoon)
- naamtekst

Dat houdt de UI voorspelbaar en ondersteunt zowel thumbnail- als niet-thumbnailweergave.

### Selectie-UX
De bestaande selectie-UX moet leidend blijven:
- row highlight voor selectie
- current row styling
- active pane styling
- checkbox-toggle
- `Cmd/Ctrl+klik`
- `Shift+Arrow`
- wildcard-selectie
- keyboardnavigatie

### Checkbox behouden of verwijderen?
Aanbevolen keuze voor Thumbnail v1: **checkbox behouden**.

Afweging:
- Screen real estate:
  - ja, checkbox + thumbnail-slot kost ruimte
  - maar de mediaslot kan compact blijven en de checkbox is al onderdeel van de huidige interactie
- Regressierisico:
  - verwijderen van de checkbox verandert zichtbaar en functioneel selectiegedrag
  - dat raakt multi-select en discoverability
- Bestaande multi-select flows:
  - checkbox is nog steeds een directe, expliciete multi-select affordance
- Keyboardgebruik:
  - keyboard blijft werken zonder checkbox, maar checkbox ondersteunt muisgebruikers duidelijk
- Wildcard-selectie / Cmd/Ctrl+klik / Shift+Arrow:
  - die blijven belangrijk, maar vervangen de checkbox niet volledig als expliciete UI affordance

Conclusie:
- checkbox nu verwijderen is een aparte UX-beslissing, geen thumbnailbeslissing
- dat verdient een aparte stap met eigen regressie-evaluatie
- voor Thumbnail v1 is behoud van checkbox de veiligste route met laag regressierisico

## 8. Performance en risico
Belangrijkste risico's:
- directories met veel afbeeldingen genereren veel requests
- grote originele afbeeldingen kunnen de lijst vertragen
- netwerkmounts geven extra latency
- checkbox + mediaslot + naam kan horizontale ruimte krapper maken

Aanbevolen mitigaties in v1:
- thumbnails alleen voor ondersteunde image files
- lazy loading aan frontendzijde
- beperkt aantal gelijktijdige thumbnail-requests
- kleine vaste slotgrootte
- geen server-side cachelaag in v1

## 9. Regressierisico
Belangrijkste regressierisico's:
- bestandslijst wordt te druk
- naamkolom wordt te smal
- selectie/current row styling wordt visueel minder duidelijk
- browse-performance daalt in grote directories
- discussie over checkbox-verwijdering wordt onbedoeld meegesleept in de thumbnailstap

Beheersmaatregelen:
- thumbnails klein houden
- checkbox behouden in v1
- vaste mediaslot gebruiken
- selectie/current row prioriteit geven boven decoratie
- geen wijziging aan klikgedrag, keyboardflow of selection model

## 10. Teststrategie
Backend golden tests:
- settings default response
- settings update persistence
- thumbnail endpoint success voor ondersteund imagebestand
- thumbnail endpoint not found
- traversal blocked
- invalid root alias
- non-image blocked of nette unsupported fout

UI smoke/regressietests:
- `Settings > General` bevat `Show thumbnails`
- instelling wordt opgehaald via backend, niet via localStorage
- mediaslot bestaat ook als thumbnails uit staan
- directories tonen folder-icoon zonder thumbnails
- files tonen file-icoon zonder thumbnails
- lijst blijft renderen met checkbox + mediaslot + naam
- selectie/current row blijven duidelijk

Handmatige validatie:
- toggle aan/uit werkt direct
- instelling blijft behouden na reload/herstart
- grote directory blijft bruikbaar
- image rows tonen thumbnail links van naam
- non-image rows en directories blijven netjes uitgelijnd
- checkbox en selectiegedrag blijven werken

## 11. Aanbeveling
Aanbevolen v1-richting met laag regressierisico:
- scope:
  - alleen `jpg/jpeg/png/webp`
- default instelling:
  - `off`
- opslagmodel:
  - SQLite `settings` tabel met `show_thumbnails`
- UI:
  - vaste mediaslot links van de naam
  - thumbnail waar beschikbaar
  - anders icoon/placeholder
  - checkbox behouden in deze fase
- backend:
  - eenvoudige settings read/write API
  - apart read-only thumbnail-endpoint met bestaande path/securityvalidatie
- performance:
  - lazy loading
  - geen disk-cache of zware thumbnailpipeline in v1

Expliciete aanbeveling over checkbox:
- **niet verwijderen in Thumbnail v1**
- als wenselijk, behandel checkbox-verwijdering als aparte latere UX-slice
- reden: dat onderwerp raakt selectiegedrag en discoverability te sterk om mee te liften op thumbnails

Dit levert een kleine, veilige eerste stap op: thumbnails als optionele verrijking van de bestaande lijst, met stabiele uitlijning, minimale visuele verstoring en zonder onnodige selectie-regressies.