# 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 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 ` 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.