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