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

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