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.