feat(app): add native omni-search screen over the search gateway

Pure request/parse/row logic in lib/features/search/domain, a
gateway-backed repository, and Material plus Cupertino bodies.
The header and rows share one scroll view, and the server's
truncation, scan and cap facts stay visible even when a bounded
scan returns no matches.

Tests cover the exact search envelope, token parsing, stale replies,
retry, truncation bounds and platform layouts. A Web-only fixture
and CDP probe support rendered verification; the screen is not yet
registered in the shell.
This commit is contained in:
2026-10-21 16:41:30 +01:00
parent 7ecd3903c0
commit 51140cd3b7
21 changed files with 3020 additions and 0 deletions
+121
View File
@@ -0,0 +1,121 @@
# X1 — Omni-search
## Scope and API
Implemented the `search` feature under `lib/features/search/` with no
`main.dart`, shell, pubspec, server, web or Android edits.
Entry point:
```dart
SearchScreen(
gateway: apiGateway, // required ApiGateway
onOpen: (hit) { ... }, // required ValueChanged<JsonMap>
cupertino: null, // optional; omitted = iOS/macOS Cupertino, else Material
)
```
`onOpen` always receives the server's original result map unchanged, including
its `target`. Unknown/absent payloads and results without a target are
read-only and never call `onOpen`; the client never invents a route or mutates
server state.
Request shape is exact and shared-gateway only:
```json
{"type":"search","search":{"query":"plan","kind":"","limit":0}}
```
`limit` is always `0` (server default cap), never a client-chosen larger value.
## Behaviour
- `t:`/`type:` tokens: unquoted, whitespace-delimited, case-insensitive, last
supported token wins; quoted, escaped, unknown and trailing-punctuation
tokens stay literal. The parser mirrors `web/src/search.js`.
- Kind selector: All kinds / Pipelines / Runs / Steps / Fields / Artifacts /
Versions. Changing it removes recognised type tokens from the field and sends
at once, like the browser's selector.
- Empty text with All kinds clears locally and sends nothing. Blank text with a
valid kind is a kind-only browse, matching the server/browser contract.
- 250 ms debounce; Enter sends at once. Every request carries a monotonically
increasing token, and replies for superseded edits are dropped.
- Loading, searching, retained-results refresh progress, empty (query-specific
and kind-only wording) and error are distinct. A truncated reply with no rows
says the server's scan limit was reached and keeps its truncation/scan bounds
on screen instead of claiming a complete empty; a complete empty has no bounds
line. A reply without `search_results` and an unknown-command rejection use
the server-upgrade sentence; any other failure shows the server's own text.
Error state offers Retry.
- Rows show the kind derived from the server payload (`Unrecognised result` for
an unknown payload), title, snippet (first case-insensitive query occurrence in
bold), and recency. Bounds show result count, cap, scanned steps/bytes, scan
limit and a truncation sentence when the server reports it, including for a
truncated reply with zero rows.
- In-hand results are re-narrowed by the effective kind while a narrowed request
loads, so the list always agrees with the control.
- Standard platform controls only: Material `SearchBar`, dropdown,
`LinearProgressIndicator`, `CircularProgressIndicator`, `ListTile`,
`FilledButton.tonalIcon`; Cupertino `CupertinoSearchTextField`, action-sheet
kind picker, `CupertinoListSection`/`CupertinoListTile`,
`CupertinoActivityIndicator`, `CupertinoButton.filled`. No CSS port, custom
palette, fixed row/bubble dimensions or bespoke buttons. Typography and
colours come from the ambient Material/Cupertino theme; rows and the header
scroll in one `CustomScrollView` so 2× text never clips.
## Automated checks
Run from `app/` with `/Users/alan/development/flutter/bin/flutter`:
- `flutter test test/features/search` — **36 passed** (controller, repository,
query/token parser, row/snippet/routing, Material + Cupertino widget tests).
- `flutter test` — **65 passed** (whole app suite, including existing transport,
runs and shell tests).
- `flutter analyze` — **No issues found**.
- `flutter build web` (default `lib/main.dart`) — **succeeded**.
- `flutter build web -t tool/search_fixture/main.dart` — **succeeded** for the
rendered probe.
- `node --check tool/search_probe.mjs` — passed.
- `git diff --no-index --check /dev/null <file>` on every touched file — no
whitespace errors (all task files are untracked, so plain `git diff --check`
would not see them).
Tests were written before the implementation (initial run failed on missing
symbols). Coverage includes the exact envelope, token parsing, selector token
clearing, no-request empty state, stale success and failure replies,
error/retry, truncation/bounds (including a truncated reply with zero rows),
per-kind row text, snippet spans, read-only hits, `onOpen` targets, and
MaterialApp/CupertinoApp at 390/1000 wide with 2× text.
## Rendered browser evidence
Built the Web-only fixture (`tool/search_fixture/main.dart`) and drove real
headless Chrome through CDP with `tool/search_probe.mjs` on an OS-assigned
loopback port. The probe typed `plan` into the real field, asserted five rows,
the server snippet, recency and truncation/scanned bounds, then clicked the
pipeline row and asserted that the fixture receiver got `pipeline:24`. It also
typed `needle` with no matching fixtures and asserted the Material and Cupertino
truncated-empty copy plus the retained `Results truncated … 0 results … scanned
2000 steps … scan limit 1.0 MiB` line, capturing both.
Captures are in the run's shared artifacts:
- `/Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-material-phone.png` — 390×844, Material controls, five mixed-kind results with recency/snippet/bounds.
- `/Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-material-desktop.png` — 1280×800, same results.
- `/Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-cupertino-phone.png` — 390×844, Cupertino search field/kind picker/grouped rows, dark system theme.
- `/Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-open-target.png` — the row click landing on `Opened pipeline target: pipeline:24`.
- `/Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-truncated-empty.png` — 390×844 Material, zero rows with the server's scan-limit sentence and truncation/scan bounds.
- `/Users/alan/.local/share/pipelines/data/artifacts/49/public/x1-search/x1-search-truncated-empty-cupertino.png` — 390×844 Cupertino dark, the same bounded empty state.
The fixture and probe are development-only entry points; they are not imported
by `lib/main.dart` and are not part of the production routing. The browser run
used a static fake gateway, not a live Pipelines server or operator data.
## Not verified / open items
- No shell registration or navigation wiring was added (manager owns
`main.dart`/`shell/`); the screen is exported for that integration.
- No real server, operator chat/run, or production URL was used.
- Mobile targets (Android/iOS) were **not** built, installed or exercised;
only Web was rendered and tested. Source is kept portable.
- No commit, push, deployment or canonical URL change was made.