Files
pipelines/web/README.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

6.0 KiB

Pipelines web client

The browser client for the Pipelines server: the Android app's feature set, rendered for the web, against the same WebSocket protocol and the same words. web/PARITY.md is the acceptance checklist and the single source of truth for what is done; this file covers how to run, test and verify it.

  • Dependency-free. Plain ES modules in the browser, hand-written CSS. No framework, no bundler, no build step, no npm install.
  • Browser-native transport. The page opens one WebSocket to /connect, matched by request id, with the same server-URL rules as the Android client.
  • Verified in a real browser. UI claims are backed by PNGs captured from headless Chrome against a live server (test/ui-smoke.mjs); a unit test alone never marks a parity row done.

Safety (unchanged from the Android client)

  • Trusted LAN/VPN only. The Pipelines API has no authentication and is not internet-safe. Do not expose the server or this page to untrusted networks.
  • No secrets. The page stores only the server URL and its own small UI preferences (sort/filter choices, attention dismissals, device-local chat overrides) in localStorage; nothing is sent anywhere but the configured server.
  • No hardcoded server. The URL is entered by the user, prefilled from the page origin, and can be overridden.

Run it

cd web
node serve.mjs                    # http://127.0.0.1:8090/ (proxies /connect -> 127.0.0.1:8080)
node serve.mjs --host 0.0.0.0     # reachable from other devices (trusted LAN/VPN)
node serve.mjs --port 8095 --pipelines 127.0.0.1:8080

The page's Server URL field (in Settings → Connection) prefills with ws://<this page's host><port>/connect — the proxy. Press Connect there the first time; the endpoint is then remembered and re-opened on later loads. Nothing is baked in.

On a deployment where ntfy already uses 8090, pick another port for the page (e.g. --port 8095). The page is a foreground Node process, not a service.

Test it

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/captures                # browser, live, screenshots

node --test covers the ported URL rules, the transport, and the pure feature logic (filters, sorting, diffs, graph layout, markdown, chat folding, routing, attention, alerts). It needs no server.

smoke.mjs drives the real client against a running server: ping, list_pipelines, list_runs, get_pipeline, get_run, artifact HEAD.

ui-smoke.mjs starts serve.mjs on an OS-assigned free port (so concurrent checks never collide), launches the installed Chrome headless, drives the real page and writes PNGs. That is the UI evidence: a review reports capture paths, not what it thinks would render. Set CHROME_PATH if Chrome is not at the default macOS location, and use --port/WEB_UI_PORT to pin a port.

Captures are deliberately gitignored: they are review evidence, not source, and keeping them out of the tree keeps a delivery checkout clean.

Layout

Area Where
Wire protocol, URL rules src/protocol.js, src/serverUrl.js
Transport (DOM-free, reused by the smoke test) src/client.js
Typed requests src/repository.js
Feature logic and models src/runs.js, src/runDetail.js, src/changes.js, src/artifacts.js, src/pipelines.js, src/templates.js, src/graph.js, src/chat.js, src/markdown.js, src/search.js, src/attention.js, src/actions.js, src/connection.js, src/settings.js, src/notify.js, src/runEvents.js, src/routes.js
Shell and views src/app.js (boot, state, navigation, render dispatch), view modules under src/views/
Styling per-area stylesheets linked from index.html
Server + /connect proxy serve.mjs
Tests test/*.test.mjs, test/smoke.mjs, test/browser.mjs, test/ui-smoke.mjs
Acceptance gate PARITY.md
Working map AGENTS.md

Keep client.js DOM-free: the smoke test and the page must drive the same transport module. Every server-derived string is set with textContent, never innerHTML — the transcript and diffs are untrusted model output.

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:

HTTP/1.1 403 Forbidden
request Origin "HOST:8090" is not authorized for Host "HOST:8080"

A Node or curl client sends no Origin and is accepted — which is why the protocol smoke can pass while a browser cannot. serve.mjs 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 between a random web page and an unauthenticated control API. Keep the proxy.

To open the page from another device, bind --host 0.0.0.0 and use this machine's LAN or Tailscale address for the page (e.g. http://100.85.25.33:8095/), then press Connect in Settings. Both hops are plaintext, so there is no mixed-content block; only do this on a trusted tailnet/VPN.

Verification notes

  • The browser is the gate, never a phone or emulator. No ADB, no device.
  • Artifact URLs resolve against the configured server (resolveArtifactUrl); the page opens them in a tab rather than embedding an Android WebView.
  • Where the browser genuinely cannot match Android (system-tray notifications need a secure context; pipelines:// links become URL routes), the parity row says so instead of pretending otherwise.
  • Feature checks that create server state (a chat, a pipeline) either use a scratch server or the server's explicit ephemeral flag, so verification never leaves clutter in the operator's lists.