webmanager-mvp/project_docs/SEARCH_V1_DESIGN.md

# Search v1

## 1. Doel

Search voegt nu waarde toe omdat de app inmiddels bruikbaar is als dual-pane file manager, maar nog volledig afhankelijk is van handmatige navigatie. Bij grotere directory trees kost dat te veel stappen.

Search moet passen binnen de bestaande dual-pane workflow:
- zoeken gebeurt vanuit het actieve paneel
- resultaten helpen navigatie versnellen
- de browse-workspace blijft het primaire werkvlak
- search is ondersteunend, geen nieuw hoofdscherm

## 2. Scope

Search v1 ondersteunt:
- zoeken op bestandsnaam
- zoeken op mapnaam
- case-insensitive substring matching

Search v1 ondersteunt niet:
- full-text content search
- indexer of achtergrondindexering
- regex
- geavanceerde querytaal
- saved searches
- fuzzy ranking

Aanbevolen zoekmodel voor v1:
- eenvoudige naamzoeking met substring match
- optioneel later uit te breiden naar glob of prefix filters, maar niet in deze slice

## 3. Zoekbereik

Mogelijke richtingen:
- zoeken vanaf `current path`
- zoeken vanaf de root van het actieve paneel

Aanbeveling voor v1:
- standaard zoeken vanaf `current path` van het actieve paneel

Reden:
- laag regressierisico
- voorspelbaar voor de gebruiker
- technisch goedkoper
- minder kans op trage scans van volledige opslagvolumes
- sluit goed aan op de huidige paneel-context

Gedrag:
- `activePane` bepaalt de zoekcontext
- de query zoekt recursief onder `currentPath` van dat paneel
- resultaten horen dus altijd bij de context van het actieve paneel op het moment van starten

Later uitbreidbaar:
- een simpele scope-toggle `Current folder tree` versus `Current root`

## 4. UI-richting

Aanbevolen v1-richting:
- aparte compacte search-modal
- geen verstoring van de dual-pane layout

Startmechanisme:
- alleen keyboard shortcut
- geen zichtbare knop in topbar
- geen zichtbare knop in functiebalk

Aanbevolen shortcut voor v1:
- Mac: `Cmd+Shift+F`
- Windows/Linux: `Ctrl+Shift+F`

Reden:
- sluit goed aan op bestaande zoekverwachtingen
- vermijdt extra visuele drukte in de UI
- vermijdt conflict met bestaande F1-F8 functiebalklogica

Modal-inhoud:
- titel `Search`
- actieve paneelcontext tonen
- zoekveld
- korte contextregel: `Searching under: <current path>`
- resultatenlijst onder het invoerveld

Gedrag bij resultaatklik:
- klik op resultaat opent de parentlocatie in het actieve paneel
- en selecteert het gevonden item

Voor directories:
- resultaatklik navigeert naar die directory in het actieve paneel

Voor files:
- resultaatklik navigeert naar de parent directory in het actieve paneel
- en selecteert de file

Dit sluit aan op de bestaande browse- en selectieflow zonder extra viewer/open-semantiek.

## 5. Resultaatsemantiek

Minimale velden per resultaat:
- `name`
- `path`
- `type` (`file` of `directory`)
- `parent_path`
- `root` of equivalent contextveld

Weergave in v1:
- primaire regel: naam
- secundaire regel: parent path of volledig path
- compacte type-indicatie (`file` / `dir`)

Aanbevolen presentatie:
- naam prominent
- parent path als muted secundaire regel
- type als kleine badge of label

## 6. Backend-impact

Aanbevolen endpoint:
- `GET /api/search?path=...&query=...`

Waarom een nieuw endpoint nodig is:
- browse-endpoint is contractueel directory listing
- search vereist recursieve traversal en resultaatlimieten
- aparte fout- en limietsemantiek is logisch

Securitymodel:
- `path` moet via bestaande `path_guard`
- zoekroot moet binnen whitelist vallen
- traversal en invalid root alias blijven via bestaande validatie lopen
- geen vrije scan buiten geconfigureerde roots

Implementatierichting:
- backend scant recursief vanaf gevalideerde startdirectory
- vergelijkt naam case-insensitive met query
- retourneert gemaximeerde lijst van matches

## 7. Performance en risico

Grootste risico:
- diepe directory trees op grote volumes

Aanbevolen v1-beheersing:
- result limit, bijvoorbeeld `100`
- optionele harde scan limit op aantal bezochte entries
- geen parallelle scanner
- geen indexer

Aanbevolen gedrag bij limiet:
- response bevat `truncated: true/false`
- als limiet bereikt is, toon alleen eerste resultaten

Timeouts:
- geen aparte timeoutsemantiek nodig in eerste slice als result-limiet en current-path scope klein blijven

## 8. Regressierisico

Belangrijkste risico’s:
- browse-flow mag niet veranderen
- selectieflow mag niet onverwacht resetten buiten het actieve paneel
- keyboardflow mag niet botsen met bestaande shortcuts
- modal focus moet bestaande paneelnavigatie blokkeren zolang search open is

Beperkende keuzes die risico laag houden:
- aparte modal
- zoeken alleen op naam
- starten vanuit actief paneel
- resultaten openen in bestaand paneelgedrag

## 9. Teststrategie

Backend golden tests:
- lege resultaatlijst
- simpele file match
- simpele directory match
- search onder current path
- traversal geblokkeerd
- path not found
- invalid root alias
- result limit / truncated gedrag

UI smoke/regressietests:
- search-modal container aanwezig
- zoekveld aanwezig
- resultaatlijst container aanwezig
- keyboard wiring voor `Cmd/Ctrl+Shift+F`

Handmatige validatie:
- zoeken vanuit links paneel raakt alleen linkse context
- zoeken vanuit rechts paneel raakt alleen rechtse context
- resultaatklik navigeert correct
- resultaatklik op directory opent directory
- resultaatklik op file opent parent + selecteert file
- `Escape` sluit modal

## 10. Aanbeveling

Aanbevolen v1-richting met laag regressierisico:
- nieuw backend-endpoint `GET /api/search`
- recursieve naamzoeking
- scope = `currentPath` van actief paneel
- case-insensitive substring match
- harde result limit, bijvoorbeeld `100`
- aparte compacte search-modal
- resultaatklik hergebruikt bestaande paneelnavigatie en selectie

Niet aanbevelen voor v1:
- root-brede zoeking als default
- content search
- indexer
- regex
- aparte zoekpagina

Dit levert een bruikbare eerste search op zonder de huidige dual-pane file manager semantiek te verstoren.