5.1 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, connection/banner, navigation/routes, render dispatch, header |
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 |
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. 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.