Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/web-ui/shape.md
iris 797e6e3137 swarm ui: the messages cards move to the swarm page and the messages tab goes
The broadcast, schedules and message log cards now sit on the swarm page, after the notification router; the message log opens its stream on its first open instead of when the page loads, and its connection badge moves into its filter bar. The messages tab is removed from the header, and the old /messages address redirects to /swarm next to /schedules, which now does too. MessagesPage becomes MessageCards, and comments, tests and the swarm UI docs say the swarm page where they said the messages tab.
2026-11-20 22:10:42 +01:00

194 lines
10 KiB
Markdown

# Shape (shared by both)
> Part of [Hives](../../2-handbook/hives/README.md). See also:
> [Dashboard reference](dashboard.md) · [Per-agent page reference](agent-page.md)
## Shared routes
- `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` — that fallback serves anything not
matched by an API or action route from the dist. Dashboard dist lives at
`${frontend}/dashboard`; per-agent dist is the merged
`services.hyperhive.agent.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 rows + Catppuccin palette + typography
from `@hive/shared` (was `hive-fr0nt`); the dashboard ships
`colors.css` + `theme.css` + `common.css` + `dashboard.css`;
`common.css` inlines `@hive/shared`'s
`base.css` + `terminal.css` + `tabs.css` +
`pill.css` via esbuild's `@import` resolution.
Terminal rows come from `@hive/shared`'s Preact `Row`, `linkify` and
`markdown` modules (see "Shared terminal pane" below).
- `GET /api/state` → JSON snapshot the JS app renders into the
DOM.
- `GET /api/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 (`transient_set` / `transient_cleared`). The
agent's own stream is `GET /events/stream`.
**One unified channel**: browsers cap concurrent SSE
connections per origin (~6 in Chrome). Using one channel per
domain would exhaust this budget on a live hive; dispatching
by `kind` on the client is a one-liner. Per-domain splits are
reserved for high-volume sub-streams most consumers skip (none
exist yet). Broker messages don't ride it: the broker's intra-process
channel only wakes `recv_blocking_batch`.
**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 (for example 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
Preact components in `@hive/shared` draw the terminal log
(`frontend/packages/shared/src/terminal/`): `Row.tsx` draws one row, `linkify.tsx`
turns bare `http(s)://` URLs in row text into new-tab links (text nodes, so no
`innerHTML`), and `markdown.ts` turns a markdown body into HTML with `marked`
and then `DOMPurify.sanitize()` before `Row.tsx` assigns it. Untrusted row text
(peer messages, agent-written state files) can carry raw HTML through markdown,
so the sanitiser is what keeps that path safe, where the text-node `linkify`
path is safe by construction. Links open in a new tab.
A row with a body is a collapsible `<details>` row, open by default when the
operator's expand-tool-output preference is on. A row's `kind` (see `termMsg.ts`)
picks its look, and `row-visibility.ts` decides which rows show given the "show
thinking" and "hide developer details" preferences.
The consumers are the swarm UI's `AgentTermPreview` (the card preview and the full
terminal tab) and `MessageCards`. Each reads rows off a stream,
keeps the scroll pinned to the newest row until the operator scrolls more than
48 px up, and renders through `Row`.
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 the handler doesn't rely on a
re-render), call `refreshState()`. State shapes live in
`hive-c0re/src/dashboard/state_snapshot.rs::StateSnapshot` and
`web_ui/state.rs::StateSnapshot` — when
adding state fields, plumb through the snapshot struct and the
relevant domain module (`agents.js`, `permissions.js`, etc.) 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, so the intermediate empty state is never
visible — clearing and re-appending directly into the live root can
leave it empty for a paint (on async builders) or a whole frame (on
large synchronous ones), which reads as a visible flash on every
poll cycle. Builders receive the fragment as their
`root`, so existing renderer code carries over unchanged; early
returns inside the builder still commit whatever it appended
before returning.
**Keyed DOM caching:** for sections whose rows hold interactive state
(textarea drafts, checkboxes, focused inputs) `paintAtomic` isn't
enough — wiping and rebuilding still destroys the state even if
`paintAtomic` hides the flash. The keyed pattern keeps a
`Map<id, {el, fingerprint}>` where the fingerprint is
`JSON.stringify({...visible fields...})`. On each render, the pattern
reuses cache-hit rows verbatim (preserving textarea draft, checkbox
state, and event listeners) and rebuilds only cache-miss rows. Used for: containers (`containerRowCache`),
rebuild-queue entries (`rebuildQueueRowCache`). The spawn-form input+focus
uses a lighter snapshot-then-restore pattern (snapshot
before `replaceChildren`, restore after) since it's a single
value rather than a per-row cache.
<!-- vale write-good.Passive = NO -->
**`<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. The
dashboard's own answered-questions history list was the only
`<details data-restore-key>` consumer and is gone
— `snapshotOpenDetails()` / `restoreOpenDetails()` currently have
nothing to restore, kept in place for the next collapsible section
that needs it rather than ripped out along with their one caller.
<!-- vale write-good.Passive = YES -->
## 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) so an nspawn restart that races
the previous process's socket release resolves itself, but the two
binaries differ on the attempt budget. The dashboard's
`bind_with_retry` (`hive-c0re/src/dashboard/mod.rs`) has **no
attempt cap** — retrying forever is deliberate, since
`lifecycle::{spawn,rebuild}` preflights genuine port collisions
host-side (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. Its 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's `bind_with_retry`
(`hive-agent/src/web_ui/mod.rs`) instead gives up after
`MAX_BIND_ATTEMPTS` (12) and returns the `AddrInUse` error rather
than looping forever.
The per-agent UI optionally binds a `UnixListener` instead of
TCP when the nix module sets `HIVE_WEB_SOCKET` — 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/4-implementation/networking/gateway.md::Per-agent unix-socket
upstream`](../networking/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/main.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/screen` (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`, …) keep their absolute
paths server-side. Only the browser-facing URLs key off the
mount prefix.
The router serves subpages (`screen`) without a trailing slash so
the relative-path resolution stays correct: `static/agent.css` from
`/screen` becomes `/static/agent.css` (last segment `screen` gets
replaced), not `/screen/static/agent.css`. Adding a trailing slash to
those routes would break the resolution; either keep them
slash-less or use `<base href>` injection at serve time.