28d8bdb29d
# Conflicts: # web/PARITY.md # web/src/app.js # web/styles.css
123 lines
24 KiB
Markdown
123 lines
24 KiB
Markdown
# Web client — parity checklist
|
||
|
||
The browser client's acceptance gate. **The target is the Android app's feature
|
||
set** (`android/`), rendered for the web. A row is only `done` when the feature
|
||
works in the browser against a live server **and** a review stage captured the
|
||
rendered result through `test/ui-smoke.mjs` (or an extension of it). A green unit
|
||
test, or a code change without a capture, is `partial` at best.
|
||
|
||
Status legend: `todo` · `partial` (some of it works) · `done` (working + captured).
|
||
|
||
## Transport and connection
|
||
| # | Feature (Android counterpart) | Protocol | Status |
|
||
| --- | --- | --- | --- |
|
||
| T1 | Server-URL entry + validation rules (`data/transport/ServerUrl.kt`) | — | done |
|
||
| T2 | One reused socket, id matching, request timeout, not-connected guard (`PipelinesClient.kt`) | — | done |
|
||
| T3 | Connect / disconnect / manual reconnect | `ping` | done — connect/disconnect captured (`captures/28-connected-banner.png`, the header control reading `Disconnect` while connected); the `Reconnect` control appears beside the URL field while idle/disconnected with a configured endpoint and calls `client.connect`, which resets the attempt/backoff for an immediate re-open (`captures/29-disconnected-banner.png`). `Disconnect` stays available while connected |
|
||
| T4 | Backoff recovery + foreground reconnect after sleep/blur (`ConnectionRecovery.kt`, `ForegroundReconnector.kt`) | — | done — the client's capped backoff is surfaced honestly rather than rewritten: `captures/29-disconnected-banner.png` shows the banner `Disconnected: Connection closed (1006) · retrying with backoff` and the header state badge `disconnected — Connection closed (1006) (attempt N, retrying)`. The attempt number is deliberately **not** in the banner text — `ConnectionBanner.kt`'s own disconnected copy omits it (Android names the attempt only while Connecting) — so the page's badge carries it instead of diverging from the Android wording. The foreground-reconnect **decision** (`foregroundAction`) is unit-tested in `test/connection.test.mjs` (Idle→LeaveAlone; Connecting/Disconnected→Reconnect; Connected→`confirmedAlive ? LeaveAlone : Reconnect`); the **rendered recovery** is captured in `captures/30-reconnect-recovered.png`, where the page (asserted still `Disconnected:`) is pointed back at the live server and the browser's own `online` event drives it to a green Connected. The browser uses its `online`/`visibilitychange` event as the liveness signal, so a still-Connected socket is left alone (no in-page positive ping probe is needed; a documented deviation from `ForegroundReconnector`'s positive ping) |
|
||
| T5 | Connection banner + live badge; build/protocol mismatch warning | `pong` build/protocol | done — a persistent banner in normal document flow under the header (never overlaying content): green `Connected` + `Server build …` (`captures/28-connected-banner.png`) and `Disconnected: … · retrying with backoff` (`captures/29-disconnected-banner.png`); a minimal dot+word live badge in the runs list/detail (`live` / `reconnecting` / `not live`, per `LiveBadge.kt`/`RunStream.kt`, `captures/28-connected-banner.png`). The build line comes from the `pong` in `SettingsScreen.kt`'s own shape, `Server build {version} ({commit})`; a dirty tree is already marked in `version` by `internal/buildinfo` (`-dirty`), so no duplicate `+dirty` marker is added. The protocol-mismatch warning (shown only when both values are present and differ, naming both) is unit-tested (`protocolMismatch`) and not captured because the live server reports `protocol` 1, matching `PROTOCOL_VERSION` |
|
||
| T6 | Artifact URL resolution against the configured server (`resolveArtifactUrl`) | `GET /artifacts/…` | done (URL only) |
|
||
|
||
## Pipelines
|
||
| # | Feature | Protocol | Status |
|
||
| --- | --- | --- | --- |
|
||
| P1 | Pipeline list | `list_pipelines` | done — row: name; `id {id} · v{version} · {N stages}`; `updated d MMM HH:mm`; last-run line joined from `list_runs` (status chip + `{ago} · {duration} · run {id}`, or `no runs recorded`) |
|
||
| P2 | Filter + sort (status/name/updated) | client-side | done — Filter menu (name contains, Runs Any/Has runs/No runs, Last run status over the 7 server states, Clear filters) + Sort menu (Server order default, Name A–Z/Z–A, Most recent run, Fewest/Most stages, Reset); server order preserved |
|
||
| P3 | Pipeline detail: stages, graph, versions, last run, content hash | `get_pipeline` | done — Summary/Graph/Source tabs; Summary shows content hash (monospace), latest version (`v{n}` or blank), created/updated, and a collapsed-by-default Versions section. Graph tab shows the browser guidance note plus the rendered workflow graph (P6) |
|
||
| P4 | Templates gallery + template detail | `list_templates`, `validate` | done |
|
||
| P5 | Create pipeline from a template (validate then submit) | `validate`, `submit` | todo |
|
||
| P6 | Workflow graph rendering (nodes, edges, stage panes) | `get_pipeline` | done (captured 2026-10-19: nodes + labelled outcome edges + success/failure terminals, an opened stage definition pane and the expanded view — `captures/08-pipeline-graph.png`, `captures/08a-pipeline-graph-stage-pane.png`, `captures/08b-pipeline-graph-expanded.png`). Reusable `src/graph.js` (`mount` + pure helpers: layout, edges, `error*`, lanes, fit/clamp/zoom, hit-test, stage-definition fields); the definition view (every route executed, no legend) plus, since R5, a run-mode view driven by `runState` (executed/not-executed stages and routes, the Executed / Not executed legend, the live halo/elapsed badge). Pane labels match the app's own vocabulary (`Outcomes`, `Tools`) rather than the checklist's category words |
|
||
|
||
## Runs
|
||
| # | Feature | Protocol | Status |
|
||
| --- | --- | --- | --- |
|
||
| R1 | Run history list with status roll-up | `list_runs` | done |
|
||
| R2 | Filter by status, sort, "needs you" markers | client-side | done — status/pipeline/time filter + sort implemented and captured (`captures/09-runs-day-groups.png`–`captures/15-runs-sorted.png`); the "needs you" requirement is delivered exactly as the app does it: a bell/badge + sheet (R15), not a per-row mark. No other R2 work is outstanding |
|
||
| R3 | Run detail: run fields, steps/visits, targets, sessions | `get_run` | done — tabbed Summary / Graph / Input / Output / Timeline; the Timeline opens a per-visit stage pane with the headline rows (Status, Outcome, Duration, Visit `{v} / {max}`, Model target, Target, Session), the Verdict block (option chip + reason with inline artifact links) and the visit sections Artifacts / Session / Output / Input / This run / Stage definition. Captured 2026-10-19: `captures/20-run-430-summary.png`, `captures/23-run-430-timeline.png`, `captures/24-run-430-stage-artifacts.png`, `captures/25-run-440-verdict.png` |
|
||
| R4 | Summary tab incl. collapsible **Changes** viewer (raw + rendered diff) | `get_run` file changes | done — a collapsed-by-default **Changes** section in the Summary tab (`{N} file(s) changed · ±stat · partial capture`; the empty variants read `Changes · capture unavailable` / `capture pending` / `partial capture` / `not recorded for this run` / `capture incomplete` / `no changes observed`) whose rows open a full-screen diff viewer with **Rendered** (each `@@` hunk header on a raised surface, old/new gutter numbers, the shared `+`/`-`/space line language) and **Raw patch** forms, Previous/Next file paging (disabled at the ends), a raw-patch copy control, Escape/backdrop/Close close, and honest binary/truncated/no-patch messages instead of a fabricated diff. Pure logic in `src/changes.js`. Captured 2026-10-19: `captures/28-run-438-changes-collapsed.png`, `captures/29-run-438-changes-expanded.png`, `captures/30-run-438-changes-diff-rendered.png`, `captures/31-run-438-changes-diff-raw.png`, `captures/32-run-442-changes-binary.png`, `captures/33-run-450-changes-truncated.png`, `captures/34-run-455-changes-pending.png` |
|
||
| R5 | Graph tab (per-stage panes, verdicts) | `get_run` | done — the run detail's Graph tab (between Summary and Input) mounts the shared `src/graph.js` renderer in run mode with the app's run note: a visited stage is executed (solid fill + border), an unvisited one hollow with a dashed muted border, a terminal executed only when a visit resolved to it, a route executed only when a visit produced that outcome (solid with an arrowhead; success first, error last, others alphabetical, `error*` for a fallback error route), the Executed / Not executed legend (runs only, never the definition view), and — while executing — the current stage's pulsing halo + elapsed badge (a static ring under `prefers-reduced-motion`; nothing for a finished run). Clicking a stage opens the existing visit pane at that stage's latest visit with its Verdict; Back/Escape close it and restore focus. The empty state is the exact `This server did not include the run graph.` (unit-tested; no live run currently carries a graph-less payload). Captured 2026-10-19: `captures/28-run-438-graph.png` (finished run 438: legend + executed styling + dashed untaken routes), `captures/29-run-438-graph-pane.png` (a graph-opened stage pane showing a Verdict), `captures/30-run-440-graph.png` (failed run 440: hollow/dashed not-executed stages) |
|
||
| R6 | Input / Output field sections per stage | `get_run` | done — one collapsed section per recorded entry, expanded as a monospace block (primitives verbatim, arrays `, `-joined, objects `k=v` `, `-joined), empty states "No input recorded." / "No output recorded.". Captured 2026-10-19: `captures/21-run-430-input.png`, `captures/22-run-430-output.png`, `captures/27-run-output-empty.png` |
|
||
| R7 | Timeline | `get_run` | done — one compact row per visit (`{stage} · visit {n}`, stage-outcome chip, paperclip when artifacts recorded, duration, description = first non-blank diagnostic line else `→ {target}`); empty state "No visits recorded.". Captured 2026-10-19: `captures/23-run-430-timeline.png`, `captures/26-run-428-timeline-empty.png` |
|
||
| R8 | Artifacts gallery + full-screen viewer (images inline, others download/open) | `GET /artifacts/…` | done (captured 2026-10-19: `captures/04-run-430-artifacts.png`, `captures/05-artifact-viewer.png`) |
|
||
| R9 | Session export link (read-only `session.html`) | `GET /artifacts/…` | done (captured 2026-10-19: `captures/06-session-export-link.png`) |
|
||
| R10 | Live run updates: subscribe/unsubscribe + event fold | `subscribe`, `unsubscribe`, `run_event` | todo |
|
||
| R11 | Human decision sheet: prompt, options, feedback | `decide_run` | partial — the pure model (`src/actions.js`: `pendingDecision`, `lastWaitingStep`, `waitingPrompt`/`waitingOptions`, `humanOptions`, `decisionTargetLabel`, `DecisionDraft`) and the card + sheet are implemented with the Android copy verbatim: card title `Waiting for your decision`, meta `{stage} · run {id} · {runLabel}`, action `Decide`; sheet title `Decide {stage}`, meta `run {id} · {runLabel}`, the recorded instructions verbatim when non-blank, one selectable row per option in author order showing the option and `→ {target}` only when the declared edge resolves, the `Feedback (optional)` field, and `Cancel` / `Confirm decision` (reading `Sending…` while in flight). Selecting a row sends nothing and Confirm is disabled until a non-blank option is chosen; a refusal keeps the sheet open with the server's exact reason and re-reads the run. The request shape is unit-tested (`decide_run` = `{type, run_id, option, stage?, feedback?}`, stage/feedback omitted when blank, feedback trimmed). **No browser capture yet**: the live server had no `waiting` run when `ui-smoke.mjs` ran (only executing/failed/finished runs), so this row stays `partial`; `test/ui-smoke.mjs` now captures the card, the sheet and the selected state automatically (`captures/41-run-<id>-decision-card.png`, `captures/42-run-<id>-decision-sheet.png`, `captures/43-run-<id>-decision-selected.png`) the moment a waiting run exists |
|
||
| R12 | Cancel run | `cancel_run` | done — `src/actions.js` `canCancel` offers a `Cancel run` action only while the run is `executing`; the confirm dialog is the Android copy verbatim (title `Cancel run {id}?`, `This asks the server to stop the active run.`, confirm `Cancel run`, dismiss `Keep`), and the request is exactly `{type:'cancel_run',run_id}` followed by a silent `get_run` refresh (unit-tested in `test/repository.test.mjs`). Captured `captures/40-run-459-cancel-confirm.png` on the executing run present at capture time. **Shown, not executed**: the only candidate was another live pipeline's executing run, so the dialog was shown and dismissed with `Keep` — no `cancel_run` was sent (a real cancel is only safe against a run started in a scratch workspace, which this stage did not do) |
|
||
| R13 | Retry failed stage (resume) / restart from start | `retry_run` | done — `canRetry` is true only for a loaded, non-executing, `failed` run; the Retry confirm is the Android copy verbatim (title `Retry run {id}?`, `Only failed runs can be retried. The server starts a new run from the same input.`, confirm `Retry`, dismiss `Keep`) and the default send carries only `run_id` + a fresh `request_key` (**no** `retry_mode`, so the server's `resume` default applies exactly like the Android client's mode-less call; unit-tested). Captured `captures/35-run-440-run-actions.png` (failed run 440 offers Retry and no Cancel) and `captures/36-run-440-retry-confirm.png`. **Divergence from the Android UI, stated here**: Android exposes resume only while the protocol has both modes, so the browser adds a clearly-labelled secondary `Restart from start` confirm that states it `replays the whole pipeline from the start instead of resuming the failed stage` and sends `retry_mode:"restart"` (`captures/37-run-440-restart-confirm.png`). Both dialogs were shown and dismissed with `Keep`; no run was started |
|
||
| R14 | Rename a run | `set_run_title` | done — an inline field on the Summary title row (pre-filled with the current title, `Rename` / `Save` / `Cancel`) sending exactly `{type:'set_run_title',run_id,title}` and then refreshing the run and the runs-list row (unit-tested). Captured `captures/38-run-440-rename-field.png`. The one shared `Action failed` dialog was exercised by a real refused rename: `captures/39-run-440-action-failed.png` shows the live server's exact reason `a title with usable text is required` (a blank title mutates nothing). **Divergence from the Android UI, stated here**: Android does not surface `set_run_title` at all (its README records the deliberate omission), so this control is browser-only |
|
||
| R15 | Attention / "Needs you" surface: counts, open, individual dismiss, clear all | derived from `list_runs` + run events | done — the pure `src/attention.js` model mirrors `ui/Attention.kt` and feeds a bell action in the top bar (badge only when non-empty; accessible name `Notifications` / `Notifications, {n} needing attention`) and a bottom sheet titled `Needs you` in `src/app.js`. Only a `waiting` run (kind Decision, rank 0) and a `failed` run (kind Failed, rank 1) qualify; order is kind rank, then recency descending (`finished_at` else `created_at`), then run id descending. Rows carry a status icon, the trimmed-title-else-pipeline label, the exact `{pipeline} · {detail}` line (`Waiting for your decision`, or the trimmed diagnostic else `Run failed`) and a trailing `Dismiss`; tapping a row opens the run, dismissing a Failed row first while a Decision row is left for its answer. Clear all acts only on the snapshot taken when the sheet opened; dismissals persist as one JSON array of `{runId}:{kind}` identities under `pipelines.web.attention.v1` with no expiry (blank/unreadable storage decodes to empty and never throws). Entries are derived from `list_runs` here; R10 will feed the same pure model the pushed `run_event` summaries, with no wording or ordering change. Captured 2026-10-19: `captures/35-attention-bell.png` (bell + badge on the Runs list), `captures/36-attention-sheet.png` (the open sheet), `captures/37-attention-dismissed.png` (one entry individually dismissed, badge 171→170), `captures/38-attention-cleared.png` (Clear all: the empty copy, no Clear all, badge gone). No run was parked in `waiting` on the live server at capture time, so the sheet is exercised with real failed runs and the decision-open path is unit-tested |
|
||
|
||
Two wording decisions in R3's stage pane, recorded here as the app-authoritative
|
||
choice: the visit's exported session is titled **Session** (the item text said
|
||
"Session export"; Android's `STAGE_SESSION_TITLE` is `Session`), and the step's
|
||
`session_id` renders as a **headline** row (Status, Outcome, Duration, Visit,
|
||
Model target, Target, Session), so it is not repeated in the "This run" evidence
|
||
section. R5's Graph tab now renders that same shared graph in run mode (see the
|
||
row above), reusing the visit pane this section describes.
|
||
|
||
One wording decision from R4, recorded here as the app-authoritative choice: the
|
||
Changes disclosure's title **is** `runChangesHeader`, so a run that recorded files
|
||
reads `{N} file(s) changed · ±stat · …` with no `Changes · ` prefix — only the
|
||
empty-capture variants carry the `Changes · ` prefix — while the expanded body's
|
||
own summary line repeats the count and stat. The header is rendered verbatim, not
|
||
re-composed.
|
||
|
||
R11–R14 share one `Action failed` dialog (title `Action failed`, the server's own
|
||
message, a single `OK`), matching `RunDetailScreen.kt`; every server string is set
|
||
with `textContent`, never `innerHTML`. Where a live action was unsafe this stage
|
||
says so rather than mutating shared state: the R12 cancel and the R13 retry/restart
|
||
sends were shown and dismissed with `Keep` (never executed), and R11 has no live
|
||
capture because the server had no waiting run. The request shapes for all four are
|
||
unit-tested in `test/repository.test.mjs` and the model in `test/actions.test.mjs`;
|
||
`test/ui-smoke.mjs` captures the rendered dialogs, the rename field, the refused
|
||
rename's exact server reason and — when a waiting run exists — the decision
|
||
card/sheet.
|
||
|
||
## Search
|
||
| # | Feature | Protocol | Status |
|
||
| --- | --- | --- | --- |
|
||
| S1 | Omni-search across pipelines, versions, runs, steps, fields, artifacts | `search` | done — the top bar's `Search` control opens a full-width panel under it (field autofocused, placeholder `Search pipelines, runs and artifacts`, a `Close search` control; opening and closing leave the current view, selection and loaded data untouched, and Escape closes the field). One flat result list with no kind grouping, over a controls row: the kind select (`All kinds`/`Pipelines`/`Runs`/`Steps`/`Fields`/`Artifacts`/`Versions`), the sort select (`Relevance`/`Newest first`/`Name`), the one-line `{Kind} · {Sort}` summary and a `Clear filter` reset. The request is exactly `{type:"search",search:{query,kind,limit:0}}` — the server's own default cap, never above `SearchMaxLimit` 200 — debounced 250 ms after the last keystroke with Enter sending at once; a blank query clears locally with no request; the previous results stay visible (a thin progress bar above them) while a newer query loads and a stale reply is dropped by token; the first load shows the spinner and `Searching…`; an error takes precedence over the results. Failure copy is `AppViewModel`'s: a rejection naming an unknown command, or an older server's reply without `search_results`, reads `This server does not support search. Update the Pipelines server, then try again.` and any other failure carries the server's own text. Row text and blank fallbacks mirror `OmniSearchResults.searchRow` (a field hit's snippet emphasises the first case-insensitive query occurrence, never via `innerHTML`) and the empty state keeps Android's `No matches for "{query}".` / `No {kind} match "{query}".`. Captured 2026-10-19: `captures/01-search-results.png` (flat mixed list for the query `plan`, the controls row and summary `All kinds · Relevance`), `captures/02-search-kind-filter.png` (the `Pipelines` filter narrowing the list and the summary to `Pipelines · Relevance`) |
|
||
| S2 | Result routing (open the pipeline, run, stage, artifact) | — | done — every selection closes and clears the search first, then routes through the page's existing navigation: a pipeline/version hit opens the pipeline detail at the result version (version 0 = latest); a run hit opens the run detail; a text hit opens the run-detail tab holding the match, resolved from the hit's `matched_field` (`input` → Input, `output` → Output, else Summary — the browser item's deliberate rule, not the recorded field name); a step or artifact hit opens the recorded visit's stage pane (the zero-based visit index within the stage, falling back to the plain run detail when the visit cannot be located); an unknown/absent payload is read-only and never navigates. Captured 2026-10-19, each with the routed destination asserted in the smoke run: `captures/03-search-route-pipeline.png` (`pipeline:24:v5` → `Plan and land` detail), `captures/04-search-route-run.png` (`run:457` → Runs detail), `captures/05-search-route-field.png` (`run:458:3`, `matched_field input` → the Input tab active), `captures/06-search-route-step.png` (`run:457:1` → the `planner` visit stage pane), `captures/07-search-route-artifact.png` (`/artifacts/355/2/…` → the `implementer` visit pane), `captures/08-search-route-version.png` (`pipeline:22:v6` → the `Server` detail) |
|
||
|
||
Two wording decisions in Search, recorded here as the app-authoritative choices:
|
||
the controls summary is exactly `{Kind} · {Sort}` (the browser item's wording, with
|
||
none of the Android panel's ` (in hand)` note), and the kind-filtered empty state
|
||
keeps Android's invariant `No {kind} match "{query}".` — the same sentence shape
|
||
the pipeline list already carries — rather than a pluralised verb.
|
||
|
||
## Chat
|
||
| # | Feature | Protocol | Status |
|
||
| --- | --- | --- | --- |
|
||
| C1 | Session list (operator sessions, closed grouped as history) | `chat_sessions` | todo |
|
||
| C2 | Create a chat (directory picker) | `chat_directories`, `chat_create` | todo |
|
||
| C3 | Open / close / reopen a session | `chat_close`, `chat_reopen` | todo |
|
||
| C4 | History with paging / "load older" | `chat_messages` | todo |
|
||
| C5 | Live transcript: user/assistant text, one reply = one turn | `chat_subscribe`, `chat_event` | todo |
|
||
| C6 | Reasoning block + tool calls with name/input for the whole lifecycle | `chat_event` | todo |
|
||
| C7 | Markdown rendering + code blocks | — | todo |
|
||
| C8 | Composer: send, stop, attachments, draft | `chat_prompt`, `chat_interrupt` | todo |
|
||
| C9 | Slash commands | client-side | todo |
|
||
| C10 | Permission/approval cards (allow once/always/reject) | `chat_permission`, `chat_reply` | todo |
|
||
| C11 | Background tasks bar: running shells only, capped + scrollable, bounded output page | `chat_shells`, `chat_shell_output` | todo |
|
||
| C12 | Human-decision notices inside chat + dismiss | `chat_event` | todo |
|
||
| C13 | Local rename/hide, seen state, persistence to `localStorage` | client-side | todo |
|
||
| C14 | Scroll behaviour: follow newest, "jump to newest", restored position | client-side | todo |
|
||
|
||
## Settings, layout, platform
|
||
| # | Feature | Protocol | Status |
|
||
| --- | --- | --- | --- |
|
||
| L1 | Settings: server URL, workspace | — | todo |
|
||
| L2 | Wide layout: left rail + two panes | client-side | todo |
|
||
| L3 | Narrow layout: bottom section strip + bottom navigation | client-side | todo |
|
||
| L4 | Responsive switch by viewport width (no hardcoded device) | `WindowSize.kt` analogue | todo |
|
||
| L5 | Notifications for failed/waiting runs (browser Notification API; HTTPS/localhost only) | derived | todo |
|
||
| L6 | Deep links to a run (`pipelines://run/…` analogue → URL route) | — | todo |
|
||
| L7 | Accessibility: focus order, labels, keyboard operation | — | todo |
|
||
|
||
## Deliberately out of scope
|
||
- **Operator-only transport** — `inspect_resource`, `reconcile_resource`,
|
||
`inspect_resource_pool`, `configure_resource_pool` are loopback-only and must
|
||
not be exposed by a browser client.
|
||
- **Device/ADB features** — the Android app's device work is the UI reviewer's
|
||
lease-based work, not a client feature.
|