526c19fc21
- Persist chat stars in the operator-session registry (chat_star) so every browser/device shows the same Starred group; migrate old local stars once. - Add a compact pipeline graph shape to list responses and draw a lightweight list miniature; replace the cryptic id/version line with the stage count. - Surface OpenCode form questions as a chat card (chat_answer), replay a pending form to late subscribers, and notify for background questions. - Make the mobile dock's Search cell equal to every destination, keep the tab row visible with 100svh, and let Source use the full pane height. - Let a fresh sign-in auto-connect to its own origin; use a Lax session cookie with Expires so Remember me survives app/link launches. - Keep shipped starters and the skill agnostic: no repository paths, project areas or personal device commands; add Diagnose/Fix and Research starters. - Refresh the installed skill and document the new browser conventions.
106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# The web client — working map
|
|
|
|
Read this before touching `web/`. This is the browser client for the Pipelines
|
|
server. Its target is **feature parity with the Android app** (`android/`), not a
|
|
reimplementation of it: same features, the same wire protocol, the same words,
|
|
rendered for a browser. `web/PARITY.md` is the acceptance checklist; that file,
|
|
not this one, decides whether a feature is done.
|
|
|
|
## What it is
|
|
|
|
- **Browser-native** (plain ES modules in the browser). Deliberately **no
|
|
framework and no runtime dependency** — no React/Vue/Svelte, no bundler
|
|
required. Keep it that way unless a concrete feature cannot be built without
|
|
one, and say why in the item's note.
|
|
- **Simple but beautiful**: hand-written CSS split by area (`base.css`,
|
|
`lists.css`, `run-detail.css`, `chat.css`, `graph.css`, `dialogs.css`,
|
|
`settings.css`), the app's dark palette and spacing, real attention to
|
|
hierarchy and detail. "Simple" is about the stack, never about the finish.
|
|
- **Authenticated proxy, not a public API.** `serve.mjs` gates pages, assets,
|
|
artifacts and `/connect` behind a signed session cookie. The Pipelines server
|
|
and the agent harness remain unauthenticated control APIs; bind them to
|
|
loopback and expose only the authenticated proxy. The browser stores no
|
|
credentials. Tests that start their own proxy use
|
|
`PIPELINES_WEB_AUTH=disabled`; never run a real service that way.
|
|
|
|
## Layout
|
|
|
|
| File | Android counterpart | Notes |
|
|
| --- | --- | --- |
|
|
| `src/protocol.js` | `data/protocol/Message.kt` | message type constants, `#success`/`#failure` |
|
|
| `src/serverUrl.js` | `data/transport/ServerUrl.kt` | `validateServerUrl`, `resolveArtifactUrl` |
|
|
| `src/client.js` | `data/transport/PipelinesClient.kt` | one reused socket, id matching, timeout, backoff. **DOM-free** |
|
|
| `src/repository.js` | `data/PipelinesRepository.kt` | typed request builders |
|
|
| `src/app.js` | `ui/**` | page shell: boot, state, client wiring, navigation/routes, render dispatch, persistent rail/workspace/dock |
|
|
| `src/shell.js` | `ui/WindowSize.kt`, `ui/components/DetailTabs.kt` | pure shell model: destinations, view/route mapping, roving-tabindex arithmetic, status words |
|
|
| `src/dom.js` | — | `h()`, shared DOM helpers and clipboard/share actions |
|
|
| `src/format.js` | `ui/Format.kt` (DOM-facing bits) | status tone and error-text helpers |
|
|
| `src/views/*.js` | `ui/**` | one module per destination/dialog surface: attention, settings, pipelines, templates, runs, runDetail, chat, search, dialogs |
|
|
| `index.html`, `*.css` | — | shell + area styles linked in a fixed order |
|
|
| `serve.mjs` | — | static server + `/connect` proxy |
|
|
| `test/*.test.mjs` | `app/src/test/**` | `node --test`, no server needed (including the shell/tab helpers) |
|
|
| `test/smoke.mjs` | — | protocol smoke against a live server |
|
|
| `test/browser.mjs` | — | zero-dep Chrome DevTools driver |
|
|
| `test/ui-smoke.mjs` | UI review captures | live browser check + screenshots |
|
|
|
|
Keep `client.js` DOM-free: the smoke tests and the page must drive the **same**
|
|
transport module.
|
|
|
|
## Build and run
|
|
|
|
```sh
|
|
cd web
|
|
node serve.mjs # http://127.0.0.1:8090/ (proxies /connect -> 127.0.0.1:8080)
|
|
node serve.mjs --port 8091 --pipelines 127.0.0.1:8080
|
|
```
|
|
|
|
There is no build step and nothing to compile. `node serve.mjs` is the whole
|
|
"install".
|
|
|
|
## Test
|
|
|
|
```sh
|
|
cd web
|
|
node --test test/ # unit tests, no server
|
|
PIPELINES_WS_URL=ws://127.0.0.1:8080/connect node test/smoke.mjs # protocol, live
|
|
node test/ui-smoke.mjs --out /path/to/run/artifacts # browser, live, screenshots
|
|
```
|
|
|
|
`ui-smoke.mjs` starts `serve.mjs`, launches the installed Chrome headless, drives
|
|
the real page and writes PNGs into `--out`. It picks a free port unless one is
|
|
given, so concurrent checks never collide.
|
|
|
|
`capture-manifest.mjs` compares two capture directories. A behaviour-preserving
|
|
refactor must keep the same capture SET; `--compare BEFORE AFTER` exits non-zero
|
|
when a capture is missing or unexpected and lists the files whose pixels drifted
|
|
(live durations legitimately change bytes, so inspect that list by eye). **That is the UI evidence**: a review
|
|
stage must run it (or an extension of it) and report the capture paths, not
|
|
describe what it thinks would render. Set `CHROME_PATH` if Chrome is not at the
|
|
default macOS location.
|
|
|
|
## Why the page connects through `serve.mjs`, not the server directly
|
|
|
|
`internal/server/websocket.go` calls `websocket.Accept(w, r, nil)`, which rejects
|
|
an upgrade whose `Origin` host does not match the request `Host`. A page served
|
|
from port 8090 opening `ws://HOST:8080/connect` is refused with **403**. The
|
|
static server therefore also proxies `/connect` (dropping `Origin`), so the page
|
|
and the socket are one origin. It proxies `/artifacts/` too: artifact URLs resolve
|
|
against the configured server (the page origin when proxied), so without it images,
|
|
the viewer and `session.html` 404 even though the socket works. **Do not "fix" this by relaxing the server's Origin
|
|
check** — that check is the only thing standing between a random web page and an
|
|
unauthenticated control API. Keep the proxy.
|
|
|
|
The web server is spawned alongside the Pipelines server; it is not part of the
|
|
Go binary and needs no server change.
|
|
|
|
## Rules
|
|
|
|
- One small, independently verifiable change per item; keep the diff tight.
|
|
- Match the Android app's wording and behaviour; where the browser genuinely
|
|
cannot match (local notifications need HTTPS, deep links become URL routes),
|
|
say so in the parity row rather than inventing a difference.
|
|
- Every new user-visible state needs a capture from `ui-smoke.mjs`.
|
|
- Do not edit `android/` from this workstream.
|
|
- Update `web/PARITY.md` in the same commit when a row's status changes.
|
|
- `node --check` every file you touch; `node --test test/` must stay green.
|