docs(#727): split docs/web-ui.md into shape / dashboard / agent
docs/web-ui.md (1315 lines) split into three sub-files: - docs/web-ui/shape.md — shared SPA skeleton, SSE multiplexing, Worker-death self-heal, terminal pane, listener bind, relative paths, atomic repaint, side panel - docs/web-ui/dashboard.md — SW4RM/Y3R/SYST3M/SCH3DUL3S/S3TT1NGS tabs, container row, topology tree, selection bar, approval card, dashboard endpoints + event channel - docs/web-ui/agent.md — header, terminal, composer, inbox, live view, slash commands, per-agent endpoints, stats page docs/web-ui.md replaced with a thin index linking all three. Section anchors in docs (gateway.md, gotchas.md), Rust doc comments (hive-ag3nt/src/web_ui.rs), and nix/templates/weston-vnc.nix updated to point at the correct sub-file. README and CLAUDE.md file-map updated with sub-file links. Inline // comments in frontend source left unchanged (they reference the index which redirects to the right sub-file).
This commit is contained in:
iris
mara
parent
e1e5195081
commit
c7360cf0bb
10 changed files with 1373 additions and 1319 deletions
270
docs/web-ui/shape.md
Normal file
270
docs/web-ui/shape.md
Normal file
|
|
@ -0,0 +1,270 @@
|
|||
# Shape (shared by both)
|
||||
|
||||
> Part of [Web UI](../web-ui.md). See also:
|
||||
> [Dashboard layout](dashboard.md) · [Per-agent page](agent.md)
|
||||
|
||||
|
||||
- `GET /` → `index.html` from the bundled frontend dist (see
|
||||
`frontend/`). Both binaries' routers declare their dynamic
|
||||
endpoints first and then `fallback_service(ServeDir::new(...))`
|
||||
pointed at `HIVE_STATIC_DIR` — anything not matched by an API or
|
||||
action route is served from the dist. Dashboard dist lives at
|
||||
`${frontend}/dashboard`; per-agent dist is the merged
|
||||
`hyperhive.frontend.mergedDist` (default agent dist + per-agent
|
||||
`extraFiles` overlay).
|
||||
- `GET /static/*` → bundled CSS + JS produced by esbuild
|
||||
(`frontend/packages/{dashboard,agent}/build.mjs`). Both pages
|
||||
pull the shared terminal pane + Catppuccin palette + typography
|
||||
from `@hive/shared` (was `hive-fr0nt`); the CSS bundle inlines
|
||||
`base.css` + `terminal.css` via esbuild's `@import` resolution.
|
||||
`terminal.js` exports `{ create, linkify }` as ES module
|
||||
members (no more `window.HiveTerminal` global outside the
|
||||
back-compat shim the IIFE bodies still use). The dashboard's
|
||||
`#msgflow` and the per-agent `#live` log are both backed by
|
||||
this terminal — sticky-bottom auto-scroll, "↓ N new" pill,
|
||||
history backfill, SSE plumbing all live there. Each page
|
||||
registers a kind→renderer map; unknown kinds fall through to
|
||||
a JSON-dump note row. Bare `http(s)://` URLs in row text are
|
||||
turned into clickable new-tab links by `linkify` (text-node
|
||||
based, no `innerHTML` — XSS-safe); markdown bodies get the
|
||||
same treatment via `marked`'s autolink (npm dep, replacing the
|
||||
vendored UMD bundle), with the rendered `<a>`s rewritten to
|
||||
`target="_blank"`.
|
||||
- `GET /api/state` → JSON snapshot the JS app renders into the
|
||||
DOM. Includes a top-level `seq` (the dashboard event channel's
|
||||
high-water mark at the moment the snapshot was assembled);
|
||||
clients use it to dedupe their buffered SSE traffic against
|
||||
the snapshot (drop frames with `seq <= snapshot.seq`).
|
||||
- `GET /dashboard/stream` (dashboard) / `GET /events/stream`
|
||||
(per-agent) → `text/event-stream` SSE for live updates. The
|
||||
dashboard stream carries broker `Sent` / `Delivered` (mirrored
|
||||
by a forwarder task from the broker's intra-process channel)
|
||||
plus mutation events (`approval_added` / `approval_resolved`,
|
||||
`question_added` / `question_resolved`, `transient_set` /
|
||||
`transient_cleared`). Each frame carries a `seq`. The
|
||||
matching backfill endpoint is `GET /dashboard/history` (last
|
||||
~200 broker messages wrapped in `{ seq, events }`) on the
|
||||
dashboard and `GET /events/history` (last 2000 `LiveEvent`s
|
||||
also wrapped in `{ seq, events }`) on the agent.
|
||||
**SSE multiplexing**: the dashboard uses a
|
||||
`SharedWorker` (`stream-worker.js`) to hold one upstream
|
||||
`EventSource` per URL. All same-origin tabs share this worker
|
||||
— a second dashboard tab joins the existing connection rather
|
||||
than opening a duplicate. The worker fans SSE events out to
|
||||
each subscribed tab via `MessagePort`; on bfcache restore the
|
||||
page re-subscribes (gets a synthetic `open` event immediately
|
||||
if the upstream is already connected). Falls back gracefully
|
||||
when `SharedWorker` is unavailable (e.g. some private-mode
|
||||
browsers). **Worker-death self-heal**: Firefox kills
|
||||
"idle" SharedWorkers under memory pressure with no client-side
|
||||
signal — the port silently goes no-op. The worker now pings
|
||||
every connected port every 30s; the client bumps a
|
||||
last-activity timestamp on every message (incl. pings, which
|
||||
carry no URL — bumped before the URL filter). A
|
||||
visibility-gated watchdog polls every 15s and, if the page is
|
||||
visible AND has active subs AND hasn't heard from the worker
|
||||
in >90s (three missed pings), presumes the worker dead and
|
||||
re-subscribes on a fresh `SharedWorker` port (same code path
|
||||
bfcache-restore uses). Recovery is per-tab; pings are
|
||||
invisible on the healthy path.
|
||||
|
||||
## Shared terminal pane
|
||||
|
||||
Both surfaces' scrollable log streams (`#msgflow` on the dashboard,
|
||||
`#live` on the per-agent page) are backed by the shared terminal
|
||||
factory in `@hive/shared/terminal.js`. The factory wires up
|
||||
sticky-bottom auto-scroll, a "↓ N new" pill, history backfill, and
|
||||
SSE replay. Pages register a `kind → renderer` map; unknown kinds
|
||||
fall through to a JSON-dump note row. The factory ships three row
|
||||
shapes the renderers call:
|
||||
|
||||
- `api.row(cls, text)` — single-line row with an inline `linkify`
|
||||
pass over the text.
|
||||
- `api.details(cls, summary, body)` — collapsible `<details>` with
|
||||
a `<pre>` body (used by long tool-results and stack traces).
|
||||
- `api.detailsDiff(cls, summary, body)` — same shape, splits the
|
||||
body on newlines and tags each line as `diff-add` / `diff-del` /
|
||||
`diff-ctx` so the renderer's diff bodies get coloured without
|
||||
emitting raw HTML.
|
||||
|
||||
**Sticky-bottom + snap animation.** `stickToBottom` is the
|
||||
operator's intent: true means "keep snapping to bottom on every
|
||||
mutation", false means "I scrolled up, leave me alone". The flag
|
||||
flips when a scroll event lands further than `NEAR_BOTTOM_PX = 48`
|
||||
from the bottom. New rows then either snap to bottom (when sticky)
|
||||
or bump the unseen-count and surface the "↓ N new" pill. The snap
|
||||
is a brief 140ms ease-out (`SCROLL_ANIM_MS`) — the browser's
|
||||
default `behavior: 'smooth'` ~500ms reads as "still smooth, but
|
||||
visibly slow"; 140ms feels snap-y while still reading as motion
|
||||
rather than a jump. Distances under `SCROLL_SNAP_PX = 24`
|
||||
short-circuit to instant — animating a 12px nudge would just be
|
||||
jitter. Each new snap cancels the previous `requestAnimationFrame`
|
||||
so a burst of mutations coalesces into one ride to the latest
|
||||
bottom; the per-frame step re-reads `scrollHeight - clientHeight`
|
||||
so mutations landing mid-animation extend the destination smoothly
|
||||
rather than land short.
|
||||
|
||||
**Mid-animation scroll-event guard.** The scroll handler's
|
||||
`isNearBottom` check would flip `stickToBottom` false mid-snap as
|
||||
the smooth animation eases through positions that are technically
|
||||
"not near bottom yet", which would strand the operator partway. A
|
||||
`smoothScrollingUntil` timestamp gates the scroll handler — set to
|
||||
the animation end + ~80ms headroom, re-armed on each fresh snap.
|
||||
Programmatic `scrollTop` writes (the animation's per-frame update)
|
||||
fire scroll events that the gate swallows.
|
||||
|
||||
**Post-append `MutationObserver`.** Renderers commonly call
|
||||
`api.row(cls, text)` to create the row shell then append more
|
||||
children (badges, multi-line bodies, tool result panes) after the
|
||||
factory returned. The initial sticky-snap fires off the row's
|
||||
empty shape; the renderer's later appends grow the row past the
|
||||
visible bottom. A `MutationObserver` on the log subtree fires once
|
||||
per microtask after each batch of synchronous mutations and snaps
|
||||
again when `stickToBottom` is true. Programmatic `scrollTop`
|
||||
writes don't re-trigger the observer (scroll isn't a DOM
|
||||
mutation), so no feedback loop. The pre-append
|
||||
`nearBottomBeforeAppend` snapshot is still useful — it keeps the
|
||||
initial visual lag to one frame instead of one microtask + frame.
|
||||
|
||||
**Backfill + SSE.** Cold load fetches `historyUrl` (replay), then
|
||||
subscribes to `streamUrl` (live tail). Both endpoints return
|
||||
`{ seq, events }` so the client can dedupe — events with
|
||||
`seq <= snapshot.seq` from the SSE stream are dropped silently
|
||||
(the snapshot already covers them). History rows render with a
|
||||
`.no-anim` class so they don't stagger in like live events. The
|
||||
optional `streamFactory(url)` callback lets the dashboard hand
|
||||
the factory a `SharedWorker`-backed `EventSource` facade (so
|
||||
multiple tabs share one upstream connection — see *SSE
|
||||
multiplexing* above); when omitted, the factory falls back to a
|
||||
plain `new EventSource(url)`.
|
||||
|
||||
**`linkify` (text-node based).** Bare `http(s)://` URLs in row
|
||||
text get wrapped in `<a target="_blank" rel="noopener noreferrer">`
|
||||
inside a fresh text node, so the autolinker never touches
|
||||
`innerHTML` and untrusted row content can't smuggle markup. The
|
||||
trailing-punctuation strip keeps `.,;:` outside the link surface.
|
||||
Markdown bodies go through `marked` separately and get the same
|
||||
target rewrite.
|
||||
|
||||
The JS app handles all `form[data-async]` submissions via a delegated
|
||||
listener: read `data-confirm`, swap the button to a spinner, POST
|
||||
`application/x-www-form-urlencoded`, re-enable the button on success
|
||||
(refreshState may keep the form mounted, so we don't rely on a
|
||||
re-render), call `refreshState()`. State shapes live in
|
||||
`dashboard.rs::StateSnapshot` and `web_ui.rs::StateSnapshot` — when
|
||||
adding state fields, plumb through the snapshot struct and the
|
||||
relevant `assets/tabs.js` render function.
|
||||
|
||||
**Focus preservation:** `refreshState` checks whether
|
||||
`document.activeElement` sits inside one of the managed sections
|
||||
and, if so, skips the refresh (defers 2s). The operator never has
|
||||
the form yanked out from under them mid-type; the update lands as
|
||||
soon as they blur.
|
||||
|
||||
**Atomic section repaint:** every managed-section renderer goes
|
||||
through `paintAtomic(liveRoot, build)`: the builder appends into
|
||||
a fresh `DocumentFragment` (off-DOM) and the commit is one
|
||||
`replaceChildren` call. The naive `root.innerHTML = ''; root.append(...)`
|
||||
shape was visibly flashing empty on every poll cycle — on async
|
||||
paths the await yield gave the browser a paint opportunity between
|
||||
the clear and the re-append, and on complex builds (many `el()`
|
||||
allocations) layout could escape the per-task budget even on the
|
||||
synchronous path. The fragment approach keeps the intermediate
|
||||
empty state invisible. Builders receive the fragment as their
|
||||
`root`, so existing renderer code carries over unchanged; early
|
||||
returns inside the builder still commit whatever was appended
|
||||
before they returned.
|
||||
|
||||
**`<details>` open-state preservation:** any collapsible element
|
||||
tagged with `data-restore-key="<stable-key>"` survives the
|
||||
refresh. `snapshotOpenDetails()` walks managed sections before
|
||||
render, `restoreOpenDetails()` re-applies after. Long-content
|
||||
drill-ins (file previews, diffs, journald logs) now open in the
|
||||
**side panel** (see below) rather than expanding inline, so the
|
||||
only restore-keyed `<details>` left is the answered-questions
|
||||
history list.
|
||||
|
||||
**Side panel (dashboard):** long content opens in a drawer that
|
||||
swipes in from the right — a singleton `#side-panel` with a
|
||||
titled header, a close button, and a scrollable body. Closes on
|
||||
the button, a backdrop click, or `Escape`. `Panel.open(title,
|
||||
node)` swaps the body; the JS builders for file previews,
|
||||
approval diffs, and journald logs all render into it. **The
|
||||
drawer width is drag-to-resize**: a thin 6px hit-strip on
|
||||
the left edge captures pointer events, resizes the drawer in
|
||||
real-time (pointer capture keeps dragging even if the cursor
|
||||
outpaces the handle), and persists the chosen width to
|
||||
`localStorage` (key `hyperhive:side-panel-width`) so it
|
||||
survives page reload. Width is clamped to CSS `min-width: 320px`
|
||||
/ `max-width: 96vw`; the viewport-resize handler re-clamps
|
||||
persisted values after a window shrink. File
|
||||
previews are type-aware:
|
||||
|
||||
- **Markdown** (`.md` / `.markdown`) — a `rendered` / `plain`
|
||||
tabbed view: `rendered` (default) is the vendored `marked`
|
||||
bundle (`GET /static/marked.js`), `plain` is the raw source.
|
||||
- **SVG** (`.svg`) — a `rendered` / `source` tabbed view;
|
||||
`rendered` shows the image via an `<img>` `data:` URI (the
|
||||
browser's secure static mode, so an untrusted SVG can't run
|
||||
scripts), `source` shows the raw markup.
|
||||
- **Raster images** (`.png` / `.jpg` / `.gif` / `.webp` /
|
||||
`.bmp` / `.ico` / `.avif`) — render as an `<img>` pointed at
|
||||
`/api/state-file`, which serves them as binary with their
|
||||
real content-type (text files stay UTF-8-lossy `text/plain`).
|
||||
- **Everything else** — raw text in a `<pre>`.
|
||||
|
||||
## Listener bind
|
||||
|
||||
Both bind their TCP listener with `SO_REUSEADDR` via
|
||||
`tokio::net::TcpSocket` plus a retry loop on `AddrInUse`
|
||||
(exponential backoff capped at 2s, **no attempt cap**) so an nspawn
|
||||
restart that races the previous process's socket release resolves
|
||||
itself. The retry is uncapped on purpose: a capped budget once
|
||||
left the harness silently UI-less for the rest of its lifetime
|
||||
when a back-to-back restart held the port longer than the cap
|
||||
allowed. Genuine port collisions are preflighted host-side
|
||||
(`lifecycle::{spawn,rebuild}` refuses with a clear error,
|
||||
surfaced on the dashboard as a banner), so at this layer a
|
||||
persistent `AddrInUse` always reflects a recoverable stale
|
||||
socket — retrying forever is the safe choice. The first 12
|
||||
attempts log at WARN; after that the level drops to INFO so a
|
||||
long-held stale socket doesn't flood the journal.
|
||||
|
||||
The per-agent UI optionally binds a `UnixListener` instead of
|
||||
TCP when `HIVE_WEB_SOCKET` is set — the unix-socket transition
|
||||
mechanics (per-agent `/run/hive-agent/<name>/` bind-mount,
|
||||
`.bound` marker filtering, `agent-sockets.json` consumer on the
|
||||
gateway side) live in [`docs/gateway.md::Per-agent unix-socket
|
||||
upstream`](gateway.md). The env var is opt-in per agent so the
|
||||
two modes coexist while sub-agents transition.
|
||||
|
||||
## Per-agent relative paths
|
||||
|
||||
The per-agent UI uses **document-relative paths everywhere** for
|
||||
assets, API calls, form actions, and the screen WebSocket. Bare
|
||||
references like `static/app.js`, `api/state`, `events/stream`,
|
||||
`screen/ws` resolve against `document.baseURI` — the page's URL
|
||||
without its last path segment.
|
||||
|
||||
That makes the page work under any prefix the agent ends up mounted
|
||||
at without rebuilding the dist. The cases that matter:
|
||||
|
||||
| served at | `api/state` resolves to |
|
||||
|---|---|
|
||||
| `/` (own port, today's shape) | `/api/state` |
|
||||
| `/agent/iris/` (gateway-prefixed) | `/agent/iris/api/state` |
|
||||
| `/agent/iris/stats` (subpage, no trailing slash) | `/agent/iris/api/state` |
|
||||
|
||||
The gateway upstream config strips the prefix before forwarding to
|
||||
the per-agent server, so the agent's Rust routes (`api/state`,
|
||||
`events/stream`, `screen/ws`, `login/start`, …) keep their absolute
|
||||
paths server-side. Only the browser-facing URLs are gated on the
|
||||
mount prefix.
|
||||
|
||||
Subpages (`stats`, `screen`) are served without a trailing slash so
|
||||
the relative-path resolution stays correct: `static/app.js` from
|
||||
`/stats` becomes `/static/app.js` (last segment `stats` gets
|
||||
replaced), not `/stats/static/app.js`. Adding a trailing slash to
|
||||
those routes would break the resolution; either keep them
|
||||
slash-less or use `<base href>` injection at serve time.
|
||||
|
||||
Loading…
Reference in a new issue