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.