swarm-ui: page shell + layout primitives

Structural foundation split out of hyperhive#3118 per mara's steer:
structure first so the real overview page (hive roster) and later
routes (swarm-wide agent roster) land as content changes rather than
each reinventing chrome + nav + a table/panel/chip shape.

- <Shell>: header bar (branding) + nav row, wraps every route. Route
  list lives in Shell itself (one small SPA, one place to know its
  own nav).
- ui/Panel, ui/StatusChip, ui/Table: the three primitives the
  overview page's actual scope (hive roster: name/domain/status,
  linking out to each hive's own dashboard) calls for, nothing
  speculative beyond that.

Preact-native styling (plain CSS files imported via swarm-ui.css, no
shadow DOM — this package renders into light DOM) — not
@hive/shared's chrome.css, which is the old MPA dashboard's visual
language. Same base16/Catppuccin color tokens via theme.css/colors.css
so it still reads as hyperhive.

npm run build (whole frontend workspace) + npm run typecheck both
clean. Verified with a real headless-chromium screenshot against the
built dist, not just source-reading.

Fixes hyperhive#3211

frontend/packages/swarm-ui/src/App.tsx

@@ -1,35 +1,34 @@
-// Root shell component. Empty start page for now — functionality
-// (swarm roster, target-state view, whatever the swarm-controller
-// epic eventually needs) is out of scope until auth against authelia
-// is figured out. What's here IS in scope: a real router + deep-link
-// shape that the per-hive dashboard's vanilla-JS + custom-element MPA
-// doesn't have, so later work has a shell to land routes into instead
-// of bolting routing on after the fact.
+// Root shell component. Real route (`/`) is still a placeholder — the
+// swarm's hive roster is the next piece of work to land into it — but
+// it now mounts inside <Shell> and uses the ui/ primitives, so that
+// page lands as a content change, not a structural one.
 import { Route, Switch } from 'wouter-preact';
+import { Shell } from './shell/Shell.js';
+import { Panel } from './ui/Panel.js';
 
 function Home() {
   return (
-    <main class="swarm-ui-empty">
-      <h1>swarm ui</h1>
-      <p>nothing here yet — project-bootstrap placeholder.</p>
-    </main>
+    <Panel title="overview">
+      <p>hive roster lands here, sequenced after this shell.</p>
+    </Panel>
   );
 }
 
 function NotFound() {
   return (
-    <main class="swarm-ui-empty">
-      <h1>404</h1>
+    <Panel title="404">
       <p>no route here.</p>
-    </main>
+    </Panel>
   );
 }
 
 export function App() {
   return (
-    <Switch>
-      <Route path="/" component={Home} />
-      <Route component={NotFound} />
-    </Switch>
+    <Shell>
+      <Switch>
+        <Route path="/" component={Home} />
+        <Route component={NotFound} />
+      </Switch>
+    </Shell>
   );
 }

frontend/packages/swarm-ui/src/shell/Shell.css

@@ -0,0 +1,40 @@
+/* <Shell> — header bar + nav row + the content column every route
+   renders into. Colour vars come from ../theme.css (same base16 slots
+   the per-hive dashboard uses, so this reads as recognizably
+   hyperhive) — the layout itself is this package's own, not
+   @hive/shared's chrome.css. */
+.shell-header {
+  display: flex;
+  align-items: center;
+  gap: 1.5em;
+  padding: 0.75em 1.25em;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-elev);
+}
+.shell-brand {
+  font-weight: 600;
+  color: var(--purple);
+  letter-spacing: 0.02em;
+}
+.shell-nav {
+  display: flex;
+  gap: 1em;
+}
+.shell-nav-link {
+  color: var(--muted);
+  text-decoration: none;
+  padding: 0.25em 0;
+  border-bottom: 2px solid transparent;
+}
+.shell-nav-link:hover {
+  color: var(--fg);
+}
+.shell-nav-link-active {
+  color: var(--fg);
+  border-bottom-color: var(--purple);
+}
+.shell-body {
+  max-width: 60em;
+  margin: 0 auto;
+  padding: 1.5em 1.25em;
+}

frontend/packages/swarm-ui/src/shell/Shell.tsx

@@ -0,0 +1,41 @@
+// <Shell> — page chrome every swarm-ui route mounts inside: a header
+// bar (swarm branding) plus a nav row linking the app's real routes.
+// Preact-native styling (shell/Shell.css, imported globally via
+// ../swarm-ui.css) — deliberately not @hive/shared's chrome.css
+// page-header pattern, which is the per-hive MPA dashboard's visual
+// language. This package is a clean field, not an inheritor of that
+// look.
+//
+// Route list lives here, not prop-drilled from App — one small SPA
+// has exactly one place that needs to know its own nav, and this is
+// it. Grows additively as real routes land (a swarm-wide agent roster
+// is next); no speculative entries.
+import type { ComponentChildren } from 'preact';
+import { Link, useRoute } from 'wouter-preact';
+
+const NAV_ITEMS: { href: string; label: string }[] = [{ href: '/', label: 'overview' }];
+
+function NavLink({ href, label }: { href: string; label: string }) {
+  const [active] = useRoute(href);
+  return (
+    <Link href={href} className={'shell-nav-link' + (active ? ' shell-nav-link-active' : '')}>
+      {label}
+    </Link>
+  );
+}
+
+export function Shell({ children }: { children: ComponentChildren }) {
+  return (
+    <div class="shell">
+      <header class="shell-header">
+        <span class="shell-brand">hyperhive swarm</span>
+        <nav class="shell-nav">
+          {NAV_ITEMS.map((item) => (
+            <NavLink key={item.href} href={item.href} label={item.label} />
+          ))}
+        </nav>
+      </header>
+      <div class="shell-body">{children}</div>
+    </div>
+  );
+}

frontend/packages/swarm-ui/src/swarm-ui.css

@@ -1,12 +1,5 @@
 @import "@hive/shared/base.css";
-
-/* Bootstrap placeholder only — real layout comes with the first
-   route that actually needs one. */
-.swarm-ui-empty {
-  max-width: 40em;
-  margin: 4em auto;
-  padding: 0 1em;
-}
-.swarm-ui-empty h1 {
-  color: var(--purple);
-}
+@import "./shell/Shell.css";
+@import "./ui/Panel.css";
+@import "./ui/StatusChip.css";
+@import "./ui/Table.css";

frontend/packages/swarm-ui/src/ui/Panel.css

@@ -0,0 +1,15 @@
+.ui-panel {
+  border: 1px solid var(--border);
+  border-radius: 0.5em;
+  background: var(--bg-elev);
+}
+.ui-panel-title {
+  margin: 0;
+  padding: 0.75em 1em;
+  font-size: 1em;
+  font-weight: 600;
+  border-bottom: 1px solid var(--border);
+}
+.ui-panel-body {
+  padding: 1em;
+}

frontend/packages/swarm-ui/src/ui/Panel.tsx

@@ -0,0 +1,14 @@
+// <Panel> — the one generic container primitive every route needs: a
+// bordered surface with an optional title, no other opinions. Not a
+// card-with-actions/footer/whatever kit — those get added the first
+// time a real page actually needs one, not speculatively ahead of it.
+import type { ComponentChildren } from 'preact';
+
+export function Panel({ title, children }: { title?: string; children: ComponentChildren }) {
+  return (
+    <section class="ui-panel">
+      {title ? <h2 class="ui-panel-title">{title}</h2> : null}
+      <div class="ui-panel-body">{children}</div>
+    </section>
+  );
+}

frontend/packages/swarm-ui/src/ui/StatusChip.css

@@ -0,0 +1,21 @@
+.ui-chip {
+  display: inline-block;
+  padding: 0.15em 0.6em;
+  border-radius: 1em;
+  font-size: 0.85em;
+  line-height: 1.4;
+  background: var(--purple-dim);
+  color: var(--fg);
+}
+.ui-chip-neutral {
+  color: var(--muted);
+}
+.ui-chip-positive {
+  color: var(--green);
+}
+.ui-chip-warning {
+  color: var(--amber);
+}
+.ui-chip-negative {
+  color: var(--red);
+}

frontend/packages/swarm-ui/src/ui/StatusChip.tsx

@@ -0,0 +1,11 @@
+// <StatusChip> — a small labelled state indicator. Generic over
+// `tone` rather than a fixed status vocabulary (`online`/`offline`/…)
+// because the first real caller (the hive roster) starts with a
+// single static "configured" tone and grows real online/stale/offline
+// states once a status rollup lands server-side — same component,
+// richer data later, no rebuild.
+export type ChipTone = 'neutral' | 'positive' | 'warning' | 'negative';
+
+export function StatusChip({ tone = 'neutral', label }: { tone?: ChipTone; label: string }) {
+  return <span class={'ui-chip ui-chip-' + tone}>{label}</span>;
+}

frontend/packages/swarm-ui/src/ui/Table.css

@@ -0,0 +1,18 @@
+.ui-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+.ui-table th {
+  text-align: left;
+  font-weight: 600;
+  color: var(--muted);
+  padding: 0.5em 0.75em;
+  border-bottom: 1px solid var(--border);
+}
+.ui-table td {
+  padding: 0.5em 0.75em;
+  border-bottom: 1px solid var(--border);
+}
+.ui-table tr:last-child td {
+  border-bottom: none;
+}

frontend/packages/swarm-ui/src/ui/Table.tsx

@@ -0,0 +1,43 @@
+// <Table> — a generic column-defined table, the shape the hive roster
+// (name / domain / status chip, one row per hive) needs. Columns own
+// their own cell rendering rather than this component knowing about
+// any particular row shape, so it stays reusable for the swarm-wide
+// agent roster later without a rewrite.
+import type { ComponentChildren } from 'preact';
+
+export interface TableColumn<T> {
+  key: string;
+  header: string;
+  render: (row: T) => ComponentChildren;
+}
+
+export function Table<T>({
+  columns,
+  rows,
+  rowKey,
+}: {
+  columns: TableColumn<T>[];
+  rows: T[];
+  rowKey: (row: T) => string;
+}) {
+  return (
+    <table class="ui-table">
+      <thead>
+        <tr>
+          {columns.map((c) => (
+            <th key={c.key}>{c.header}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={rowKey(row)}>
+            {columns.map((c) => (
+              <td key={c.key}>{c.render(row)}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}