mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: sort the top-level directories into five sections by what the reader wants

Browse source 
Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.
This commit is contained in:
iris 2026-11-06 18:30:12 +01:00 • committed by mara
commit 6739bb903d
33 changed files with 736 additions and 701 deletions
Download patch file Download diff file Expand all files Collapse all files

6
frontend/packages/agent/src/agent.css
View file

@ -16,7 +16,7 @@
/* ─── full-screen layout overrides ─────────────────────────────────
The agent page mounts a full-viewport terminal under a fixed
frosted-glass header. See docs/web-ui/agent.md::Per-agent
frosted-glass header. See docs/2-handbook/web-ui/agent.md::Per-agent
page for the layer / pill / side-panel structure; rules below
override the in-page defaults from @hive/shared. */
@ -184,7 +184,7 @@ h3 {
}
.agent-icon {
/* Square identity anchor — explicit 5em sizing + align-self.
See docs/web-ui/agent.md::Per-agent page (Agent icon) for the
See docs/2-handbook/web-ui/agent.md::Per-agent page (Agent icon) for the
intrinsic-dim-pushes-parent-flex-open + sticks-to-top
rationale. */
width: 5em;
@ -684,7 +684,7 @@ pre.diff {
/* Tail pill (↓ N new): z-index bumped above the floating chrome so the
pill sits on the top layer instead of being clipped by it. (Pill is anchored in
`.agent-main` rather than `.terminal-wrap` — see
docs/web-ui/agent.md::Per-agent page Terminal-wrap paragraph for the
docs/2-handbook/web-ui/agent.md::Per-agent page Terminal-wrap paragraph for the
backdrop-filter stacking-context rationale.) */
.agent-main .tail-pill {
bottom: 0.6em;

2
frontend/packages/agent/src/colors.css
View file

@ -2,5 +2,5 @@
esbuild emits its own `dist/static/colors.css`, linked first by every
agent page (before theme.css). This is the theme swap contract: a
stylix-generated variant replaces only this file. See
@hive/shared/colors.css + docs/web-ui/css-vars.md. */
@hive/shared/colors.css + docs/4-implementation/web-ui/css-vars.md. */
@import "@hive/shared/colors.css";

2
frontend/packages/agent/src/components/Header.tsx
View file

@ -53,7 +53,7 @@ export interface HeaderProps {
* a variable pill count) grows to fit badges+pills together, keeping
* the header a stable height even on widescreen. Meta-nav
* (`<MetaNav>`) lives here too, as a fixed-size trigger, not an
* inline link list in the title row (docs/web-ui/agent.md). */
* inline link list in the title row (docs/2-handbook/web-ui/agent.md). */
pills?: ComponentChildren;
}

2
frontend/packages/agent/src/index.html
View file

@ -19,7 +19,7 @@
<body class="agent-shell">
<!-- The Preact rewrite owns everything below — header, terminal,
side panel. See main.tsx/Root.tsx for the component
tree; docs/web-ui/agent.md for the design. -->
tree; docs/2-handbook/web-ui/agent.md for the design. -->
<div id="preact-root"></div>
<script type="module" src="static/main.js" defer></script>

6
frontend/packages/agent/src/screen.html
View file

@ -36,7 +36,7 @@
<script>
// Minimal RFB-over-WebSocket renderer. Connects to `screen/ws` on
// the same host; the harness relays raw RFB bytes to the VNC server
// running inside the container. See docs/web-ui/agent.md (GET /screen)
// running inside the container. See docs/2-handbook/web-ui/agent.md (GET /screen)
// for the design rationale + canvas-sizing implementation notes.
(function () {
@ -61,7 +61,7 @@
});
// --- Fit-to-window toggle ---
// See docs/web-ui/agent.md::Per-agent endpoints (GET /screen) for the
// See docs/2-handbook/web-ui/agent.md::Per-agent endpoints (GET /screen) for the
// localStorage persistence + canvas-intrinsic-resolution +
// pointer-rescale model.
let fitMode = localStorage.getItem("screen-fit") !== "off";
@ -105,7 +105,7 @@
// Sends an RFB SetDesktopSize request so the VNC server (weston)
// changes its actual output resolution to match the browser
// viewport — sharper than fit-mode's CSS downscale. Gated on the
// server's ExtendedDesktopSize advert; see docs/web-ui/agent.md::Per-agent
// server's ExtendedDesktopSize advert; see docs/2-handbook/web-ui/agent.md::Per-agent
// endpoints (GET /screen).
let extDesktopSupported = false;
let screenId = 1; // captured from the server's ExtendedDesktopSize advert

2
frontend/packages/agent/src/theme.css
View file

@ -2,5 +2,5 @@
esbuild emits it as its own `dist/static/theme.css`, linked by every
agent page right after colors.css. The base16 slots it derives from
live in colors.css (the swap contract); a theme swap replaces only
that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
that file. See @hive/shared/theme.css + docs/4-implementation/web-ui/css-vars.md. */
@import "@hive/shared/theme.css";

2
frontend/packages/agent/src/types.ts
View file

@ -40,7 +40,7 @@ export interface AgentState {
// in the agent page header (stats/screen/forge/config + any
// `services.hyperhive.agent.dashboardLinks` extras). `agent_links()` on the backend
// is the single source of truth for what links an agent exposes; see
// docs/web-ui/agent.md::Header for the kind → URL resolution table.
// docs/2-handbook/web-ui/agent.md::Header for the kind → URL resolution table.
export interface AgentLink {
url: string;
icon: string;

20
frontend/packages/dashboard/src/agents.js
View file

@ -1,7 +1,7 @@
// 4G3NTS (containers) domain — extracted from tabs.js.
// Agent topology, container-row rendering, selection bar, and all
// live-update apply handlers for container-state, transient, and
// job-queue-rollup ops. See docs/web-ui/dashboard.md::Container row for the
// job-queue-rollup ops. See docs/2-handbook/web-ui/dashboard.md::Container row for the
// rendering contract.
import { $, form, fmtAgeSecs } from "./common.js";
@ -37,14 +37,14 @@ const containerRowCache = new Map();
// by agent name -> Map<transient_kind, since_unix>: an agent can hold
// several pills at once (every *running* node naming the agent lights
// one now, not just a curated "worth surfacing" subset — see
// docs/web-ui/dashboard.md::Container row), keyed the same way the backend's
// docs/2-handbook/web-ui/dashboard.md::Container row), keyed the same way the backend's
// own tombstone map is, `(agent, label)`, so a clear only removes the
// specific pill it names rather than guessing. `since_unix` is
// wall-clock so the elapsed-seconds badge ticks without polling.
const transientsState = new Map();
// In-memory set of selected agent logical names backing the sticky
// #selection-bar. See docs/web-ui/dashboard.md::Selection bar for the
// #selection-bar. See docs/2-handbook/web-ui/dashboard.md::Selection bar for the
// interaction model (icon-click toggle, Esc/clear button drop,
// tab-gated visibility).
const selectionState = new Set();
@ -225,7 +225,7 @@ function derivePortConflicts(containers) {
}
// ─── container ordering ──────────────────────────────────────────────────────
// Flat alphabetical sort — see docs/web-ui/dashboard.md::C0NTAINERS.
// Flat alphabetical sort — see docs/2-handbook/web-ui/dashboard.md::C0NTAINERS.
function sortedContainerRows(containers) {
// Close any open context menu before replacing the DOM tree — the
@ -285,7 +285,7 @@ function buildContainerLi(c, opts) {
// Agent icon: 5em square wrapper with an absolutely-positioned
// <img> + fire-and-forget load with /favicon.svg fallback. The
// wrapper doubles as the selection toggle (click / keyboard).
// See docs/web-ui/dashboard.md::Container row for the layout + load-strategy
// See docs/2-handbook/web-ui/dashboard.md::Container row for the layout + load-strategy
// rationale.
const iconImg = el("img", { class: "container-icon-img", alt: "" });
const icon = el(
@ -478,7 +478,7 @@ function buildContainerLi(c, opts) {
// dashboard-state fetch above.
if (pending.length) {
// One badge per pill — an agent can carry several transients at
// once now (see docs/web-ui/dashboard.md::Container row), each rendered
// once now (see docs/2-handbook/web-ui/dashboard.md::Container row), each rendered
// independently rather than collapsed into one label.
for (const label of pending) {
head.append(
@ -561,7 +561,7 @@ function buildContainerLi(c, opts) {
// Per-card action buttons (R3ST4RT / ST0P / ST4RT / R3BU1LD /
// DESTR0Y / PURG3) live on the selection bar, not here — see
// docs/web-ui/dashboard.md::Selection bar. The contextual `needs update ↻`
// docs/2-handbook/web-ui/dashboard.md::Selection bar. The contextual `needs update ↻`
// chip in the head row stays — it's a state-hint, not an
// action button.
@ -632,7 +632,7 @@ export function renderContainers(s) {
// TCP fallback — the gateway proxies the prefix to the per-agent
// harness (unix-domain via `agent-sockets.json`, or a computed TCP
// loopback port while the socket marker is absent). See
// `docs/web-ui/dashboard.md::Container row` + `docs/networking/gateway.md::Vhost map`.
// `docs/2-handbook/web-ui/dashboard.md::Container row` + `docs/4-implementation/networking/gateway.md::Vhost map`.
const gatewayLinks = !!(s && s.gateway_enabled);
// Forge public URL: state.forge_public_url (set by the NixOS module
// from services.hyperhive.swarm.forge.publicUrl) or null — never guessed
@ -658,7 +658,7 @@ export function renderContainers(s) {
// full stop (mara, on review: "remove the per agent pending stuff -
// only show what is running"; rendered one badge per pill — mara,
// earlier: "show all running nodes that name the agent"). See
// docs/web-ui/dashboard.md::Container row.
// docs/2-handbook/web-ui/dashboard.md::Container row.
const transientKindsMap = transientsState.get(c.name);
// Sorted for stable badge order across renders — Map iteration
// order is insertion order, which shifts as pills clear/re-add.
@ -725,7 +725,7 @@ export function renderContainers(s) {
// ─── selection bar ───────────────────────────────────────────────────────────
// Sticky-bottom strip; visible when >=1 agent selected on the 4G3NTS
// tab. See docs/web-ui/dashboard.md::Selection bar for the interaction model
// tab. See docs/2-handbook/web-ui/dashboard.md::Selection bar for the interaction model
// and the per-action availability rules (disabled-with-tooltip for
// actions that don't apply to the full selection). Actions POST per
// agent in a loop (endpoints are individually idempotent /

2
frontend/packages/dashboard/src/colors.css
View file

@ -2,5 +2,5 @@
esbuild emits its own `dist/static/colors.css`, linked first by every
dashboard page (before theme.css). This is the theme swap contract: a
stylix-generated variant replaces only this file. See
@hive/shared/colors.css + docs/web-ui/css-vars.md. */
@hive/shared/colors.css + docs/4-implementation/web-ui/css-vars.md. */
@import "@hive/shared/colors.css";

2
frontend/packages/dashboard/src/common.css
View file

@ -247,7 +247,7 @@ code {
}
/* M0V3 affordance (selection bar) — mauve reads as "structural
change" rather than the destructive red / amber chrome of
destroy / rebuild. See docs/web-ui/dashboard.md::Selection bar. */
destroy / rebuild. See docs/2-handbook/web-ui/dashboard.md::Selection bar. */
.btn-move {
color: var(--purple);
border-color: var(--purple);

4
frontend/packages/dashboard/src/common.js
View file

@ -63,7 +63,7 @@ export const form = (
// ─── shared-worker SSE pipe ─────────────────────────────────────────────
// Returns an EventSource-shaped facade backed by a SharedWorker that
// holds one upstream `new EventSource(url)` and fans events out to
// every connected tab. See docs/web-ui/shape.md (SSE multiplexing paragraph)
// every connected tab. See docs/4-implementation/web-ui/shape.md (SSE multiplexing paragraph)
// for the design + Firefox throttling motivation; graceful fallback to
// direct EventSource on environments without SharedWorker.
//
@ -100,7 +100,7 @@ function getSharedPort() {
// SharedWorker death detection: pings from the worker bump the
// activity clock; a visibility-gated watchdog polls and re-subscribes
// on a fresh port if the page has been silent past the threshold.
// See docs/web-ui/shape.md (Worker-death self-heal paragraph) for the
// See docs/4-implementation/web-ui/shape.md (Worker-death self-heal paragraph) for the
// timing rationale + Firefox reclaim symptom.
const WORKER_DEAD_THRESHOLD_MS = 90_000;
const WORKER_WATCHDOG_INTERVAL_MS = 15_000;

2
frontend/packages/dashboard/src/dashboard.css
View file

@ -12,7 +12,7 @@
/* ─── tabbed dashboard chrome ──────────────────────────────────────
Top-of-page sticky header with banner + tab strip. SSE stays
alive across tab switches. See docs/web-ui/dashboard.md::Chrome header + Tab strip for the
alive across tab switches. See docs/2-handbook/web-ui/dashboard.md::Chrome header + Tab strip for the
routing model. */
body.dashboard-shell {

2
frontend/packages/dashboard/src/index.html
View file

@ -165,7 +165,7 @@
<!-- Selection action bar. Sticky-bottom strip that slides into
view when one or more agent cards is selected (click the icon
to toggle). See docs/web-ui/dashboard.md::Selection bar for the bulk
to toggle). See docs/2-handbook/web-ui/dashboard.md::Selection bar for the bulk
action gating + clear semantics. -->
<div
id="selection-bar"

2
frontend/packages/dashboard/src/stream-worker.js
View file

@ -1,6 +1,6 @@
// SharedWorker that holds ONE EventSource per stream URL and fans
// every server-sent event out to every connected tab via MessagePort.
// Design rationale: docs/web-ui/shape.md (SSE multiplexing paragraph).
// Design rationale: docs/4-implementation/web-ui/shape.md (SSE multiplexing paragraph).
//
// Wire protocol (port.postMessage payloads):
//

4
frontend/packages/dashboard/src/tabs.js
View file

@ -2,7 +2,7 @@
// Reads /api/state on cold load and after every async-form submit; live
// updates run through `applyXxx` mutation handlers triggered by the
// dashboard event stream (subscribed via `openStream` from common.js). See
// docs/web-ui/shape.md::Shape (shared by both) for the broader contract.
// docs/4-implementation/web-ui/shape.md::Shape (shared by both) for the broader contract.
//
// Pure helpers (DOM, side panel, path linkification)
// live in `./common.js`.
@ -213,7 +213,7 @@ import { renderUserMenu } from "./user-menu.js";
(function bindDashboardStream() {
// Route through the SharedWorker so all open hyperhive tabs on the
// SAME kinds= filter share one upstream SSE connection — see
// docs/web-ui/shape.md (SSE multiplexing paragraph) for the design
// docs/4-implementation/web-ui/shape.md (SSE multiplexing paragraph) for the design
// + Firefox throttling motivation. `openStream` returns an
// EventSource-shaped facade with a graceful direct-EventSource
// fallback when SharedWorker isn't supported.

2
frontend/packages/dashboard/src/theme.css
View file

@ -2,5 +2,5 @@
esbuild emits it as its own `dist/static/theme.css`, linked by every
dashboard page right after colors.css. The base16 slots it derives
from live in colors.css (the swap contract); a theme swap replaces
only that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
only that file. See @hive/shared/theme.css + docs/4-implementation/web-ui/css-vars.md. */
@import "@hive/shared/theme.css";

2
frontend/packages/shared/src/badge/Badge.tsx
View file

@ -17,7 +17,7 @@
// them with no real distinction to justify it. Lives in `shared` because both
// swarm-ui *and* the per-agent page need the interactive shape, and
// `shared` is the one package both already depend on (see
// `docs/web-ui/design-guide.md`'s component-first + junk-drawer rules).
// `docs/5-project/web-ui/design-guide.md`'s component-first + junk-drawer rules).
import type { ComponentChildren } from "preact";
import "./Badge.css";

2
frontend/packages/shared/src/base.css
View file

@ -2,7 +2,7 @@
web UI. The colour variables it references (`--bg`, `--fg`, …) live in
the standalone `theme.css` (Catppuccin Mocha), linked separately by
every page BEFORE this file so the `:root` vars resolve — see
`theme.css` + docs/web-ui/css-vars.md. Per-page stylesheets append on
`theme.css` + docs/4-implementation/web-ui/css-vars.md. Per-page stylesheets append on
top of this and must NOT redeclare the colour variables; `theme.css`
is the one source of truth. */
body {

2
frontend/packages/shared/src/colors.css
View file

@ -9,7 +9,7 @@
Kept as its own standalone stylesheet (not @import-ed into theme.css)
so a swap replaces just this file — `theme.css` and the page bundles
stay untouched. Every page links this BEFORE `theme.css`. See
docs/web-ui/css-vars.md.
docs/4-implementation/web-ui/css-vars.md.
Two raw palettes, one declaration each — `--mocha-baseNN` (dark,
Catppuccin Mocha) and `--latte-baseNN` (light, Catppuccin-Latte-

2
frontend/packages/shared/src/dropdown/Dropdown.tsx
View file

@ -2,7 +2,7 @@
// the `Badge` that opened it (../badge/Badge.tsx) so the control is
// visually attached to the thing it affects, instead of living three
// clicks away in a catch-all menu (the junk-drawer pattern
// `docs/web-ui/design-guide.md` calls out by name). Not a native `<dialog>` — a
// `docs/5-project/web-ui/design-guide.md` calls out by name). Not a native `<dialog>` — a
// `showModal()` dialog's backdrop would visually detach it from its
// anchor badge, and a non-modal `show()` gets no click-outside-to-close
// for free, so this hand-rolls the same "outside click or Escape

Some files were not shown because too many files have changed in this diff Show more