Files
pipelines/web/AGENTS.md
T
alan 84e136436c web: app shell — left destination rail, settings-hosted connection, viewport panes
The layout item's work plus the two defects its review found:
- the wide grid sized the list track from its MAX, so at 600-759px the detail pane
  was clipped to 40-199px; cap the list below 900px and narrow the rail there
  (measured now: detail 232px at 600, 332 at 700, 340 at 900, 880 at 1440);
- the shell said 'Not connected' on a fresh page because the prefilled proxy URL
  validated; the status now reflects a SAVED endpoint ('Not configured' until then)
  and refreshes as the draft changes.

Includes the rail + bottom dock, connection moved into Settings, viewport-only
scrolling with panes that scroll themselves, tab semantics, skip link, h1 per
route, and the design tokens.
2026-10-19 20:03:56 +01:00

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