webmanager-mvp/project_docs/PREFERRED_STARTUP_PATH_V1.md

# Preferred Startup Path v1

## 1. Doel
Een voorkeurpad is nuttig omdat de app nu altijd met een vaste startlocatie opent, terwijl de gebruiker in de praktijk vaak steeds in dezelfde map of subtree werkt. Als de app direct op die plek opent, scheelt dat navigatiestappen en sluit het beter aan op een dual-pane file manager workflow waarin de gebruiker vaak een primaire werkmap heeft.

Binnen de huidige app past dit goed zolang de startup-logica eenvoudig en voorspelbaar blijft. Het doel is niet om sessies volledig te herstellen, maar om een veilige, persistente startlocatie te bieden.

## 2. Scope
Voor v1 is de scope expliciet:
- één voorkeurpad
- persistent opgeslagen in de bestaande SQLite settings-opslag
- configureerbaar via `F1 -> Settings -> General`
- geen browser storage
- geen meervoudige profielen of paneelspecifieke presets

Niet in scope:
- meerdere startup-profielen
- per root een aparte default
- laatst bezochte map onthouden per sessie
- aparte startup-paths voor links en rechts

## 3. Paneelgedrag
Aanbevolen v1-keuze met laag regressierisico:
- één voorkeurpad
- toepassen op het linkerpaneel bij startup
- rechterpaneel blijft starten op de huidige veilige default (`/Volumes`)

Reden:
- dit geeft directe waarde zonder de dual-pane logica complex te maken
- het voorkomt dat beide panelen onbedoeld op exact dezelfde diepe map starten
- het behoudt één paneel als neutrale oriëntatie-/navigatiekolom
- het vermindert regressierisico ten opzichte van twee aparte persistente padinstellingen

Alternatieven die bewust niet aanbevolen worden voor v1:
- hetzelfde voorkeurpad voor beide panelen: eenvoudig, maar minder bruikbaar in dual-pane gebruik
- aparte voorkeurpaden voor links en rechts: functioneel aantrekkelijk, maar meer validatie- en fallbackcomplexiteit

## 4. Validatie
Het voorkeurpad moet aan dezelfde veiligheidsregels voldoen als gewone browse-paden:
- binnen whitelist / toegestane roots
- geldig binnen de bestaande `/Volumes` en root/alias-logica
- padvalidatie via bestaande `path_guard`-infrastructuur of equivalente browse-validatie

Validatieregels:
- pad moet resolven naar een toegestane locatie
- pad moet bestaan
- pad moet browsebaar zijn als directory
- file als startup path is niet toegestaan voor v1

Gedrag bij ongeldigheid:
- als het pad niet meer bestaat: instelling blijft opgeslagen, maar startup valt terug op veilige default
- als het pad niet meer toegankelijk is door whitelist/config wijziging: startup valt terug op veilige default
- als het pad syntactisch ongeldig is: backend weigert opslag

## 5. Fallback-gedrag
Veilige en voorspelbare fallback voor v1:
- als preferred startup path ontbreekt of ongeldig is, start de app op `/Volumes`
- rechterpaneel blijft in alle gevallen op `/Volumes`
- linkerpaneel gebruikt alleen het voorkeurpad als de validatie slaagt

Dit houdt het model simpel:
- geldig voorkeurpad -> links opent daar, rechts opent `/Volumes`
- ongeldig voorkeurpad -> beide panelen openen `/Volumes`

## 6. Settings UI
Plaatsing:
- `F1 -> Settings -> General`

Aanbevolen invoervorm voor v1:
- één tekstveld met het volledige pad
- compact helperlabel, bijvoorbeeld: `Preferred startup path`

Waarom tekstveld de laagste risicokeuze is:
- sluit aan op de bestaande padsemantiek in de app
- geen extra browse-picker of tree-selector nodig
- laagste implementatiecomplexiteit

Opslagflow:
- gebruiker voert pad in
- klik op `Save` of bestaande settings-save flow
- backend valideert
- bij succes blijft waarde persistent opgeslagen
- bij fout toont de modal een compacte validatiefout

Aanbevolen foutweergave:
- inline fout onder het veld of in de General-tab
- voorbeelden:
  - `Startup path must be a directory`
  - `Startup path is outside allowed roots`
  - `Startup path does not exist`

## 7. Backend-impact
Dit past logisch in de bestaande settings-API.

Aanbevolen uitbreiding:
- bestaand `settings` model uitbreiden met:
  - `preferred_startup_path: string | null`

Benodigde backendlogica:
- read via bestaande `GET /api/settings`
- write via bestaande `POST /api/settings`
- validatie op write:
  - directory
  - bestaand pad
  - binnen whitelist

Te hergebruiken validatie:
- bestaande `path_guard`
- bestaande browse-/directory-validatie helpers waar aanwezig

Nieuwe endpoint is niet nodig als de bestaande settings-API netjes uitbreidbaar is.

## 8. Frontend-impact
App-initialisatie moet licht aangepast worden:
- app leest settings vroeg in startup
- als `preferred_startup_path` geldig aanwezig is:
  - linker paneel start daar
- anders:
  - linker paneel start op `/Volumes`
- rechter paneel blijft op `/Volumes`

Belangrijk voor regressiebehoud:
- browse-initialisatie mag niet kapotgaan als settings-call faalt
- bij error of lege response moet de app veilig terugvallen op het huidige gedrag

Aanbevolen init-volgorde:
1. laad settings
2. bepaal startup path voor links
3. initialiseeer panelen
4. laad browse data

## 9. Regressierisico
Belangrijkste risico’s:
- ongeldige startup path leidt tot lege of foutieve eerste render
- conflict tussen oude default `/Volumes` en nieuw voorkeurpad
- inconsistent gedrag tussen host-achtige `/Volumes/...` paden en alias-root mapping
- settings laden te laat, waardoor panelen eerst op default en daarna opnieuw renderen

Laag-risico aanpak:
- settings eerst laden
- startup path alleen op links toepassen
- fallback altijd `/Volumes`
- write-validatie streng houden
- read-validatie tolerant houden met veilige fallback

## 10. Teststrategie
Backend golden tests:
- `GET /api/settings` met default `preferred_startup_path = null`
- `POST /api/settings` met geldig startup path
- write-block voor file path i.p.v. directory
- write-block voor traversal / invalid root alias
- write-block voor niet-bestaand pad

UI smoke/regressietests:
- Settings > General bevat veld voor preferred startup path
- app init leest setting uit backend
- geen regressie op huidige `/Volumes` fallback

Handmatige validatie:
- geldig pad opslaan en app herstarten
- ongeldig pad opslaan moet geweigerd worden
- bestaand opgeslagen pad later verwijderen en app opnieuw starten -> fallback naar `/Volumes`
- `/Volumes/...` startup path moet correct resolven en openen

## 11. Aanbeveling
Aanbevolen v1-richting met laag regressierisico:
- voeg één setting toe: `preferred_startup_path`
- persistent in bestaande SQLite settings-opslag
- configureerbaar via tekstveld in `Settings > General`
- toepassen op alleen het linkerpaneel
- rechterpaneel blijft op `/Volumes`
- fallback altijd `/Volumes`

Dit geeft directe waarde met minimale complexiteit. Het houdt dual-pane gedrag bruikbaar, beperkt regressierisico, en laat later nog ruimte voor een v2 met aparte left/right startup paths als daar echte behoefte aan blijkt.