diff --git a/docs/4-implementation/web-ui/shape.md b/docs/4-implementation/web-ui/shape.md index 0709ab393..c40e185eb 100644 --- a/docs/4-implementation/web-ui/shape.md +++ b/docs/4-implementation/web-ui/shape.md @@ -15,29 +15,14 @@ `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 + 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.js` exports `{ create, linkify }` as ES module - members; a back-compat shim in the IIFE bodies still exposes - a `window.HiveTerminal` global for callers that need it. The - per-agent `#live` log runs on - this terminal — sticky-bottom autoscroll, "↓ 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 go through - `marked` (npm dep, replacing the vendored UMD bundle) and then - `DOMPurify.sanitize()` before hitting `innerHTML` — untrusted row - text (peer-agent / matrix-relayed message bodies, agent-authored - state files) can carry arbitrary HTML/script via markdown, so - `DOMPurify.sanitize()` cleans the markdown path rather than it being - XSS-safe by construction the way the text-node `linkify` path is. - Rendered ``s are rewritten to `target="_blank"`. + 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` @@ -77,117 +62,24 @@ ## Shared terminal pane -The shared terminal factory in `@hive/shared/terminal.js` backs the -scrollable log stream. The factory wires up -sticky-bottom autoscroll, 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: +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. -- `api.row(cls, text, icon?)` — single-line row with an inline `linkify` - pass over the text; optional `icon` lands in a fixed-width `.row-glyph` - cell so glyphs of varying rendered width all align. -- `api.details(cls, summary, body, icon?)` — collapsible `
` with - a `
` body (used by long tool-results and stack traces).
-- `api.detailsDiff(cls, summary, body, icon?)` — 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.
-- `api.placeholder(text)` — replaces the log with a single muted row,
-  cleared automatically when the next real row arrives.
-- `api.fromHistory` — `true` while backfill replay is running; renderers
-  use it to suppress live-only side effects.
+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. - - -**`create(opts)` options:** `logEl` (log container element), `streamUrl` -(SSE endpoint), `historyUrl?` (optional replay endpoint — skipped if absent -or if the fetch fails), `renderers` (kind→fn map; unknown kinds fall through -to `renderers._default`, itself defaulting to a JSON-dump note row), -`onLiveEvent?(ev)` (live-only side effects), `onAnyEvent?(ev, {fromHistory})` -(runs for both replay and live — use for derived views that need the full -event picture), `onBackfillDone?(count)` (one-shot after replay; `count=0` on -failed/skipped fetch), `onStreamOpen?()` (fires on every EventSource -(re)connect — use to re-sync snapshot-derived state after a reconnect gap), -`pillAnchor?` (parent element for the "↓ N new" pill; defaults to -`logEl.parentElement`), `expandDetails?` (boolean or zero-arg function -returning one, re-read on every `api.details`/`api.detailsDiff` call rather -than captured once — lets a page default otherwise-collapsed panels open -per a live browser-local preference; renderers that force a row open -regardless, for example message-bearing tool_use, are unaffected either way). - - - -**Sticky-bottom + snap animation.** `stickToBottom` is the -operator's intent: true means "keep snapping to bottom on every -mutation," false means "the operator scrolled up, leave them 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. One caveat: if live events -arrive faster than the animation window (< 220ms apart), the -MutationObserver keeps re-firing `snapToBottom()` which perpetually -re-arms the gate — trapping the operator at the bottom with no way -to scroll up or trigger `loadMore()`. Safety valve: even inside the -guard the handler checks `isNearBottom()`; if the operator has -scrolled away from the bottom, `stickToBottom` is immediately forced -false. The MO's `if (stickToBottom)` check then stops re-arming -snaps, and the gate expires within ≤220ms. - -**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 — the client silently -drops events with `seq <= snapshot.seq` from the SSE stream -(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 `` -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, then -`DOMPurify.sanitize()` on the resulting HTML before it's assigned to -`innerHTML` (see `mdNode` in `app.js` / `common.js`) — -`DOMPurify.sanitize()` cleans this path rather than it being -text-node-safe like `linkify`, since markdown can carry raw HTML. -Rendered ``s get the same target rewrite. +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 diff --git a/frontend/packages/dashboard/src/index.html b/frontend/packages/dashboard/src/index.html index 6a57a84aa..9000ef8ef 100644 --- a/frontend/packages/dashboard/src/index.html +++ b/frontend/packages/dashboard/src/index.html @@ -187,9 +187,7 @@ - + diff --git a/frontend/packages/shared/package.json b/frontend/packages/shared/package.json index dc365ca7f..a2322acee 100644 --- a/frontend/packages/shared/package.json +++ b/frontend/packages/shared/package.json @@ -2,24 +2,20 @@ "name": "@hive/shared", "version": "0.0.0", "private": true, - "description": "Shared frontend modules used by both the dashboard and the per-agent UI: terminal log pane, Catppuccin palette, base typography. Imported by sibling workspaces; not bundled standalone.", + "description": "Shared frontend modules used by both the dashboard and the per-agent UI: terminal log rows, Catppuccin palette, base typography. Imported by sibling workspaces; not bundled standalone.", "type": "module", - "main": "./src/index.js", "dependencies": { "dompurify": "^3.2.4", "marked": "18.1.3", "preact": "11.2.0" }, "exports": { - ".": "./src/index.js", - "./terminal.js": "./src/terminal/terminal.js", "./term-msg.js": "./src/terminal/termMsg.ts", "./term-row.js": "./src/terminal/Row.tsx", "./term-linkify.js": "./src/terminal/linkify.tsx", "./term-markdown.js": "./src/terminal/markdown.ts", "./tabs.js": "./src/tabs/tabs.js", "./tabs.css": "./src/tabs/tabs.css", - "./hive-tab-strip.js": "./src/tabs/hive-tab-strip.js", "./colors.css": "./src/colors.css", "./theme.css": "./src/theme.css", "./base.css": "./src/base.css", diff --git a/frontend/packages/shared/src/badge/Badge.tsx b/frontend/packages/shared/src/badge/Badge.tsx index 391f4012a..883f1a619 100644 --- a/frontend/packages/shared/src/badge/Badge.tsx +++ b/frontend/packages/shared/src/badge/Badge.tsx @@ -31,10 +31,8 @@ export type BadgeTone = * `'default'` — the filled pill every status/picker badge has always * been. `'quiet'` — no permanent fill, only a background on hover/ * `expanded`; for an icon-only trigger that should read as chrome (a - * header button) rather than a status chip — mara: "link and settings - * button should not have the badge bg" against both the agent page's - * `MetaNav` and the shared `SettingsMenu` (swarm-ui + agent both use - * it). Same `variant` naming/shape as `Button`'s + * header button) rather than a status chip, as the shared + * `SettingsMenu` trigger does. Same `variant` naming/shape as `Button`'s * `ButtonVariant` (`../../swarm-ui/src/ui/button/Button.tsx`) — visual * weight is orthogonal to `tone` (color semantics), so it's its own prop * rather than a new `tone` value. diff --git a/frontend/packages/shared/src/colors.css b/frontend/packages/shared/src/colors.css index 2be296306..c95ee9a27 100644 --- a/frontend/packages/shared/src/colors.css +++ b/frontend/packages/shared/src/colors.css @@ -139,8 +139,8 @@ } } -/* Per-user override (swarm-ui's `SettingsMenu` / `lib/theme-apply.ts` - sets `data-theme` on ``; unset/`"system"` removes the +/* Per-user override (`SettingsMenu` and `settings/theme-apply.ts` + set `data-theme` on ``; unset/`"system"` removes the attribute and lets the media query above decide, same as before this existed). `:root[data-theme='light']` has higher specificity than the plain `:root` inside the media query above (an attribute diff --git a/frontend/packages/shared/src/dropdown/Dropdown.tsx b/frontend/packages/shared/src/dropdown/Dropdown.tsx index 5162af9d4..dbd344483 100644 --- a/frontend/packages/shared/src/dropdown/Dropdown.tsx +++ b/frontend/packages/shared/src/dropdown/Dropdown.tsx @@ -49,8 +49,7 @@ export interface DropdownProps { * reopens it instead of closing it"). Passing the same ref the * caller's wrapper div already needs for CSS positioning excludes * clicks on the trigger from the outside-click check, matching how - * `MetaNav`'s own hand-rolled popover (which wraps trigger+popover in - * one ref) already avoids this. + * a popover that wraps its trigger and popup in one ref avoids this. */ anchorRef?: RefObject; } diff --git a/frontend/packages/shared/src/icons.tsx b/frontend/packages/shared/src/icons.tsx index 4eca7592e..a33303b20 100644 --- a/frontend/packages/shared/src/icons.tsx +++ b/frontend/packages/shared/src/icons.tsx @@ -12,13 +12,8 @@ // lucide-style line icons, `currentColor` stroke so they pick up // whatever text colour the surrounding `Badge`/button already has. // -// Originated in swarm-ui's `shell/SettingsMenu.tsx` (gear) and -// `shell/LinksMenu.tsx` (link chain) as separate inline copies; moved -// here once the agent page's `MetaNav`/`SettingsMenu` needed the exact -// same icons too (mara: the settings trigger went back to a text glyph -// when `SettingsMenu` was extracted into `@hive/shared`, undoing this -// fix — restoring the SVG here, in the shared component this time, -// fixes it for both pages at once instead of just one). +// Shared here so `SettingsMenu`, `LinksMenu` and the swarm UI's shell draw the +// settings gear and the link chain from one place. import type { ComponentChildren } from "preact"; export function GearIcon() { diff --git a/frontend/packages/shared/src/index.js b/frontend/packages/shared/src/index.js deleted file mode 100644 index 1a18382a9..000000000 --- a/frontend/packages/shared/src/index.js +++ /dev/null @@ -1,3 +0,0 @@ -// Convenience re-export so consumers can `import { create, linkify } -// from '@hive/shared'` without naming the sub-module path. -export { create, linkify } from "./terminal/terminal.js"; diff --git a/frontend/packages/shared/src/prefs.ts b/frontend/packages/shared/src/prefs.ts index f36a70807..971f5ba51 100644 --- a/frontend/packages/shared/src/prefs.ts +++ b/frontend/packages/shared/src/prefs.ts @@ -3,8 +3,8 @@ // exact same key name for free via the browser's shared per-origin // storage, rather than an independent copy that could drift. // `ExpandDetailsSetting` / `HideDebugSetting` / `ShowThinkingSetting` (the -// settings popover rows of the per-agent page and of the swarm UI) are the only -// writers today; `Row.tsx` is the only reader of any of them. +// settings popover rows of the swarm UI) are the only writers today; `Row.tsx` +// and the swarm UI's `useHideDebug` read them. const EXPAND_DETAILS_KEY = "hive-agent-expand-details"; diff --git a/frontend/packages/shared/src/settings/HideDebugSetting.tsx b/frontend/packages/shared/src/settings/HideDebugSetting.tsx index b04208b13..af824b4c1 100644 --- a/frontend/packages/shared/src/settings/HideDebugSetting.tsx +++ b/frontend/packages/shared/src/settings/HideDebugSetting.tsx @@ -1,7 +1,6 @@ // Settings-menu row: "hide developer details". Rendered as a `` -// child (`./SettingsMenu.js`) by each page that has a terminal, the -// per-agent page and the swarm UI, rather than as a prop on the menu: the -// caller owns its row. Both read the same preference (`../prefs.js`), which +// child (`./SettingsMenu.js`) by the swarm UI's shell, rather than as a prop on +// the menu: the caller owns its row. The preference (`../prefs.js`) is the one // `../terminal/Row.tsx` follows as it changes — mara: "add a setting to not // display verbose output... like the grey colored debug stuff." import { useState } from "preact/hooks"; diff --git a/frontend/packages/shared/src/settings/SettingsMenu.css b/frontend/packages/shared/src/settings/SettingsMenu.css index 2a88bdfd9..e66613010 100644 --- a/frontend/packages/shared/src/settings/SettingsMenu.css +++ b/frontend/packages/shared/src/settings/SettingsMenu.css @@ -1,8 +1,7 @@ /* popover — matches `@hive/shared`'s `Dropdown` (`../dropdown/Dropdown.css`, `.ui-dropdown`) values exactly - (background/border/radius/shadow), same "reuse the values, not the - component" call `MetaNav` already made for its own - popover: this one holds `` rows, not `Dropdown`'s command-dispatch `