Take main's newer smoke behaviour where they met: the binary capture is run 449 (opened through openRunDetail), and a running run must show no aggregate Changes section. Keep the layout's shell-aware checks and its L2-L4 rows; L7 stays todo with the view-level fixes recorded.
5.5 KiB
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. - Trusted LAN/VPN only. The server has no authentication; the page stores
nothing but the server URL in
localStorage. Never bake in a server address, never store secrets, never expose the API to an untrusted network.
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
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
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.mdin the same commit when a row's status changes. node --checkevery file you touch;node --test test/must stay green.