# 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 `
` 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 `MessagesPage`. 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` 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. **`
` open-state preservation:** any collapsible element tagged with `data-restore-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 `
` 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. ## 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//` 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 `` injection at serve time.