feat: thumbnails added

project_docs/THUMBNAIL_V1_DESIGN.md_OUD

@@ -0,0 +1,213 @@
+# 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.