webmanager-mvp/project_docs/THUMBNAIL_V1_DESIGN.md

# 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.

Belangrijke afbakening voor deze stap:
- Thumbnail v1 gaat alleen over:
  - thumbnails voor image files
  - een vaste mediaslot links van de naam
  - iconen/placeholder als er geen thumbnail is
  - een persistente setting in `Settings > General`
  - het voorlopig behouden van het bestaande selectievakje

## 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
  - wijziging van selectiegedrag
  - verwijderen van het selectievakje

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 blijft leidend:
- row highlight voor selectie
- current row styling
- active pane styling
- checkbox-toggle
- `Cmd/Ctrl+klik`
- `Shift+Arrow`
- wildcard-selectie
- keyboardnavigatie

### Checkbox behouden of verwijderen?
Voor Thumbnail v1 is de keuze expliciet:
- **checkbox blijft voorlopig bestaan**

Dit is een tijdelijke concessie voor regressiebeheersing, niet de definitieve eindrichting.

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

Expliciete afbakening:
- checkbox-verwijdering is **niet** in scope voor Thumbnail v1
- checkbox-verwijdering wordt **niet** stilzwijgend meegenomen in deze stap
- checkbox-verwijdering vereist een aparte latere UX-slice met eigen regressie-evaluatie

## 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
- checkbox-verwijdering zou onbedoeld mee kunnen liften op 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 blijft voorlopig bestaan
- 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 positionering:
- de huidige keuze om checkbox te behouden is **tijdelijk** en **regressiegedreven**
- de gewenste compactere eindrichting zonder checkbox kan later apart ontworpen worden
- die stap hoort niet bij Thumbnail v1 en moet als aparte UX-slice worden behandeld

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