Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/web-ui/shape.md
iris a1e5855859 frontend: remove the unused vanilla terminal and tab strip, and fix comments that describe removed UI
shared/src/terminal/terminal.js (and its index.js re-export and package export) had no importer: the Preact Row replaced it. The .tail-pill and .load-more-pill rules were only made by it, and the preview's own tail-pill override styled a pill that no longer exists. hive-tab-strip.js had no importer either. Four constants nobody imports are no longer exported. The shared terminal pane section of the web-ui shape doc now describes Row, linkify and markdown instead of the removed factory. Header comments that named removed components (StatusChips, MetaNav, Root.tsx, the cost badge, four folded sections, a detail dialog) now describe the current code.
2026-11-19 21:47:37 +01:00

10 KiB

Shape (shared by both)

Part of Hives. See also: Dashboard reference · Per-agent page reference

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

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

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