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