webmanager-mvp/project_docs/PREFERRED_STARTUP_PATHS_V2.md

Preferred Startup Paths v2

1. Doel

Aparte startup paths voor links en rechts voegen waarde toe omdat de huidige app inmiddels duidelijk als dual-pane workspace wordt gebruikt, niet meer als een enkel browservenster met twee toevallige kolommen. In de praktijk wil een gebruiker vaak een vaste bronlocatie links en een vaste doellocatie rechts, of twee verschillende werkcontexten die bij elke start direct beschikbaar zijn.

Dit past goed binnen de huidige dual-pane workflow zolang het startup-model voorspelbaar blijft:

• links en rechts worden onafhankelijk bepaald
• elke paneelstart heeft een veilige fallback
• invalidatie van het ene paneel mag het andere paneel niet blokkeren

Het doel van v2 is dus niet om sessieherstel te bouwen, maar om de bestaande v1-setting uit te breiden naar een net paneelspecifiek model.

2. Scope

Voor v2 is de scope expliciet:

• twee aparte settings
  • preferred_startup_path_left
  • preferred_startup_path_right
• beide persistent opgeslagen in de bestaande SQLite settings-opslag
• configureerbaar via F1 -> Settings -> General
• geen browser storage
• geen profielensysteem
• geen "laatst gebruikte map" logica

Niet in scope:

• startup-profielen
• per root presets
• per gebruiker verschillende defaults
• automatisch synchroniseren van links en rechts
• migratie naar een complexer settings-schema dan nodig

3. Paneelgedrag

Aanbevolen v2-keuze:

• linkerpaneel gebruikt preferred_startup_path_left als die geldig is
• rechterpaneel gebruikt preferred_startup_path_right als die geldig is
• per paneel geldt onafhankelijk:
  • leeg -> fallback naar /Volumes
  • ongeldig -> fallback naar /Volumes

Dit is de meest directe uitbreiding op v1 en heeft het laagste regressierisico, omdat het huidige startupgedrag al paneelspecifiek wordt bepaald.

Expliciet niet aanbevolen voor v2:

• één setting die intern naar beide panelen gespiegeld wordt
• een "alleen links instelbaar, rechts afgeleid" model
• complexe koppellogica zoals "rechts gebruikt automatisch andere root"

Die varianten introduceren impliciete regels en maken debugging moeilijker.

4. Validatie

Per veld geldt exact dezelfde validatie als in v1:

• pad moet bestaan
• pad moet een directory zijn
• pad moet binnen toegestane roots vallen
• traversal wordt geblokkeerd
• invalid root alias wordt geblokkeerd
• file paths zijn niet toegestaan

Semantiek:

• lege waarde betekent null
• null betekent: voor dat paneel geen voorkeurpad, dus fallback naar /Volumes

Belangrijk onderscheid tussen write en read:

• write-validatie blijft streng
• read-gedrag blijft tolerant

Dat betekent:

• ongeldige invoer wordt niet opgeslagen
• eerder opgeslagen waarden die later ongeldig worden, worden bij startup niet blind vertrouwd maar ook niet direct uit de database verwijderd

5. Fallback-gedrag

Veilig en voorspelbaar fallbackmodel voor v2:

• links:
  • geldig preferred_startup_path_left -> gebruik dat pad
  • anders -> /Volumes
• rechts:
  • geldig preferred_startup_path_right -> gebruik dat pad
  • anders -> /Volumes

Gemengde gevallen moeten expliciet ondersteund worden:

• links geldig, rechts ongeldig -> links op voorkeurpad, rechts op /Volumes
• links ongeldig, rechts geldig -> links op /Volumes, rechts op voorkeurpad
• beide ongeldig -> beide op /Volumes

Dit voorkomt dat één corrupte setting de hele appstart breekt.

6. Settings UI

Plaatsing blijft:

• F1 -> Settings -> General

Aanbevolen v2-weergave:

• twee aparte tekstvelden
• labels:
  • Preferred startup path (left)
  • Preferred startup path (right)

Opslaggedrag:

• opslaan via dezelfde bestaande settings-save flow
• beide velden mogen tegelijk opgeslagen worden
• leegmaken van een veld zet alleen dat veld naar null

Aanbevolen foutweergave:

• compact maar duidelijk per veld, of als één compacte General-error als de huidige modal daar al op ingericht is
• bij voorkeur per veld omdat links en rechts onafhankelijk valide kunnen zijn

Als per-veld foutweergave te veel UI-ruis oplevert, is een compacte foutregel in de General-tab acceptabel, mits duidelijk is welk veld faalt.

7. Backend-impact

Deze uitbreiding past logisch in de bestaande settings-opslag en settings-API.

Aanbevolen uitbreiding:

• bestaande settings-uitbreiding met:
  • preferred_startup_path_left: string | null
  • preferred_startup_path_right: string | null

Backward compatibility met bestaande single setting

Hier is een expliciete keuze nodig.

Aanbevolen richting met laag regressierisico:

• de oude single setting preferred_startup_path tijdelijk blijven ondersteunen als legacy input
• nieuwe code leest primair:
  • preferred_startup_path_left
  • preferred_startup_path_right
• als deze ontbreken, maar oude preferred_startup_path bestaat nog:
  • gebruik die alleen als fallback voor links
  • rechts blijft /Volumes
• bij de eerste expliciete save vanuit v2 UI schrijft de app alleen de nieuwe left/right keys
• de oude key hoeft in v2 niet direct verwijderd te worden

Waarom dit de beste v2-keuze is:

• bestaande gebruikers van v1 verliezen hun startup-voorkeur niet
• er is geen harde migratiestap nodig
• de migratielogica blijft klein en begrijpelijk

Expliciet niet aanbevolen:

• de oude key hard verwijderen zonder read-compatibiliteit
• een automatische destructieve migratie bij startup
• dezelfde oude key dupliceren naar links én rechts

Dat laatste zou te verrassend zijn, omdat het beide panelen plots op dezelfde map laat starten.

8. Frontend-impact

Frontendstartup moet worden uitgebreid van:

• één preferred path voor links naar:
• twee onafhankelijke preferred paths

Aanbevolen init-volgorde:

1. laad settings via backend
2. bepaal startup path voor links
3. bepaal startup path voor rechts
4. initialiseeer panelen met die twee waarden
5. browse laden
6. per paneel veilig fallbacken naar /Volumes als browse init voor dat pad mislukt

Belangrijk voor regressiebehoud:

• dubbele initialisatie vermijden waar mogelijk
• links en rechts los fallbacken
• huidige /Volumes defaultlogica niet verwijderen maar als veilige basis behouden

9. Regressierisico

Belangrijkste risico’s:

• invalid stored path voor één paneel veroorzaakt misleidende first render
• mixed valid/invalid links/rechts levert inconsistente startup op als fallbacklogica niet per paneel gebeurt
• /Volumes hostlaag en alias-mapping moeten consistent blijven
• legacy single setting kan per ongeluk genegeerd worden

Laag-risico aanpak:

• per paneel apart resolven en fallbacken
• legacy key alleen als tijdelijke read-fallback voor links
• write alleen naar nieuwe keys
• /Volumes als harde veilige fallback behouden
• geen semantische wijziging aan browse buiten startup

10. Teststrategie

Backend golden tests

• GET /api/settings met default:
  • preferred_startup_path_left = null
  • preferred_startup_path_right = null
• geldig left path opslaan
• geldig right path opslaan
• beide tegelijk opslaan
• file path blokkeren per veld
• traversal blokkeren per veld
• invalid root alias blokkeren per veld
• missing directory blokkeren per veld
• lege waarde zet veld terug naar null

UI smoke/regressietests

• Settings > General bevat beide velden
• app init leest beide settings via backend
• linker en rechter paneel krijgen onafhankelijke startupwaarden
• fallback naar /Volumes blijft intact per paneel
• legacy v1-pad breekt appinit niet

Handmatige validatie

• links en rechts verschillende geldige paden opslaan en app herstarten
• links geldig, rechts leeg
• links ongeldig opgeslagen legacy/v2 waarde simuleren
• rechts ongeldig opgeslagen v2 waarde simuleren
• beide ongeldig -> beide /Volumes
• v1-upgrade scenario:
  • alleen oude preferred_startup_path aanwezig
  • links start daarop, rechts op /Volumes

11. Aanbeveling

Aanbevolen v2-richting met laag regressierisico:

• voeg twee nieuwe settings toe:
  • preferred_startup_path_left
  • preferred_startup_path_right
• valideer beide op dezelfde manier als v1
• leeg veld = null
• fallback per paneel = /Volumes
• behoud tijdelijke read-compatibiliteit met de bestaande v1-key preferred_startup_path
  • alleen als fallback voor links
• schrijf vanuit v2 UI alleen nog de nieuwe left/right settings

Dit geeft een nette evolutie van v1 naar een volwaardige dual-pane startupconfiguratie, zonder bestaande gebruikers onverwacht te breken en zonder onnodige migratiecomplexiteit.