settings: move the theme/motion panel into @hive/shared, add motion to agent

Review feedback on this PR (mara): "i think the component should be
shared. motion setting is missing." Both addressed:

- `settings-storage.ts` (generic localStorage hook), `theme-apply.ts`,
  `motion-apply.ts`, and `SettingsMenu.tsx`/`.css` all move from
  swarm-ui's `lib/`/`shell/` into `@hive/shared/src/settings/` —
  agent's previous local copies are deleted outright rather than kept
  as a second implementation. One component, `Badge` trigger
  everywhere (already used elsewhere in swarm-ui, so not a new visual
  language there either) — storage keys stay caller-owned (`themeKey`/
  `motionKey` props + matching `useApplyThemeOverride`/
  `useApplyMotionOverride` calls at each package's single mount point)
  so agent and swarm-ui keep fully independent, non-colliding
  persisted settings.
- Agent's settings menu now includes the motion row, matching
  swarm-ui's. No animation in the agent package is gated behind
  `data-motion` yet — same as when swarm-ui first built this plumbing
  ahead of having a consumer — so it's currently inert there, ready for
  whenever agent grows a motion-guarded animation.
- swarm-ui's own theme default flips to `'dark'` as part of this move
  (`theme-apply.ts`'s new default), superseding PR #3715 — that PR
  becomes redundant once this lands and will be closed rather than
  merged, to avoid the two colliding on the same file.

Verified end-to-end with real screenshots on both pages: shared
component renders identically (Badge trigger, theme+motion rows, dark
default) on agent's mock server and a static rebuild of swarm-ui's
dist.

frontend/packages/shared/package.json

@@ -40,7 +40,12 @@
     "./badge.js": "./src/badge/Badge.tsx",
     "./badge.css": "./src/badge/Badge.css",
     "./dropdown.js": "./src/dropdown/Dropdown.tsx",
-    "./dropdown.css": "./src/dropdown/Dropdown.css"
+    "./dropdown.css": "./src/dropdown/Dropdown.css",
+    "./settings-storage.js": "./src/settings/settings-storage.ts",
+    "./theme-apply.js": "./src/settings/theme-apply.ts",
+    "./motion-apply.js": "./src/settings/motion-apply.ts",
+    "./settings-menu.js": "./src/settings/SettingsMenu.tsx",
+    "./settings-menu.css": "./src/settings/SettingsMenu.css"
   },
   "files": [
     "src/"

frontend/packages/shared/src/settings/SettingsMenu.css

@@ -0,0 +1,46 @@
+/* <SettingsMenu> 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`/`.login-card` already made for their own
+   popovers: this one holds `<select>` rows, not `Dropdown`'s
+   command-dispatch `<button>`s. Right-anchored — this trigger lives at
+   the end of a header's icon-trigger cluster in every page that mounts
+   it, so a left anchor would push it off-screen. */
+.settings-menu-anchor {
+  position: relative;
+  display: inline-block;
+}
+.settings-menu-popover {
+  position: absolute;
+  top: calc(100% + 0.25em);
+  right: 0;
+  left: auto;
+  z-index: 20;
+  display: flex;
+  flex-direction: column;
+  gap: 0.15em;
+  min-width: 12em;
+  padding: 0.5em;
+  background: var(--bg-elev);
+  border: 1px solid var(--border);
+  border-radius: 0.5em;
+  box-shadow: 0 0.4em 1em rgba(0, 0, 0, 0.35);
+}
+.settings-menu-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75em;
+  min-height: 2.75em;
+  padding: 0 0.3em;
+  color: var(--fg);
+}
+.settings-menu-row select {
+  min-height: 2.75em;
+  padding: 0 0.4em;
+  border: 1px solid var(--border);
+  border-radius: 0.35em;
+  background: var(--bg);
+  color: var(--fg);
+  font: inherit;
+}

frontend/packages/shared/src/settings/SettingsMenu.tsx

@@ -0,0 +1,95 @@
+// <SettingsMenu> — a single header icon-button + popover holding the
+// client-local overrides a page has (theme, reduced motion). Originated
+// in swarm-ui (its own `shell/SettingsMenu.tsx`, trigger a raw SVG
+// gear icon); the agent terminal page needed the identical panel
+// (mara: "agent terminal page should get the settings panel from swarm
+// ui as well"). First pass duplicated it with an agent-specific trigger
+// (`Badge`, matching the rest of that page's header pills — `MetaNav`
+// already established `Badge` as the one interactive-chip language
+// there); mara's review on that PR: "i think the component should be
+// shared. motion setting is missing." — this is that: one component,
+// both pages import it, `Badge` trigger everywhere (already a
+// `@hive/shared` component itself, and already used elsewhere in
+// swarm-ui — `pages/ComponentsPage.tsx` etc. — so this isn't a new
+// visual language for that package either), motion included
+// unconditionally rather than agent-only.
+//
+// Storage keys are the caller's responsibility (`themeKey`/`motionKey`
+// props), not derived here — a page mounts `useApplyThemeOverride`/
+// `useApplyMotionOverride` (`./theme-apply.js`/`./motion-apply.js`)
+// once, high in its tree, with the SAME key strings passed to this
+// component, so the two stay in sync without this component owning any
+// page-specific naming decision.
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { Badge } from '../badge/Badge.js';
+import { useThemeOverride, type ThemeOverride } from './theme-apply.js';
+import { useMotionOverride, type MotionOverride } from './motion-apply.js';
+import './SettingsMenu.css';
+
+const THEME_OPTIONS: ThemeOverride[] = ['system', 'light', 'dark'];
+const MOTION_OPTIONS: MotionOverride[] = ['system', 'allow', 'reduce'];
+
+export interface SettingsMenuProps {
+  themeKey: string;
+  motionKey: string;
+}
+
+export function SettingsMenu({ themeKey, motionKey }: SettingsMenuProps) {
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const [theme, setTheme] = useThemeOverride(themeKey);
+  const [motion, setMotion] = useMotionOverride(motionKey);
+
+  // Close on an outside click or Escape — only listens while open.
+  useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (rootRef.current && e.target instanceof Node && !rootRef.current.contains(e.target)) setOpen(false);
+    }
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown, true);
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown, true);
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [open]);
+
+  return (
+    <div class="settings-menu-anchor" ref={rootRef}>
+      <Badge value="⚙" title="settings" onClick={() => setOpen((v) => !v)} expanded={open} />
+      {open ? (
+        <div class="settings-menu-popover" role="menu" aria-label="settings">
+          <label class="settings-menu-row">
+            <span>theme</span>
+            <select
+              value={theme}
+              onChange={(e) => setTheme((e.target as HTMLSelectElement).value as ThemeOverride)}
+            >
+              {THEME_OPTIONS.map((o) => (
+                <option key={o} value={o}>
+                  {o}
+                </option>
+              ))}
+            </select>
+          </label>
+          <label class="settings-menu-row">
+            <span>motion</span>
+            <select
+              value={motion}
+              onChange={(e) => setMotion((e.target as HTMLSelectElement).value as MotionOverride)}
+            >
+              {MOTION_OPTIONS.map((o) => (
+                <option key={o} value={o}>
+                  {o}
+                </option>
+              ))}
+            </select>
+          </label>
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/packages/shared/src/settings/motion-apply.ts

@@ -0,0 +1,36 @@
+// Applies a stored reduced-motion override as a `data-motion="reduce"|
+// "allow"` attribute on `<html>`, cleared when the override is "system"
+// (letting `prefers-reduced-motion` alone decide). Ported from swarm-ui
+// verbatim, only the storage key is now caller-supplied instead of a
+// module constant — see `theme-apply.ts`'s file comment for why.
+//
+// A consumer's CSS gates an animation with the three-rule shape this
+// was built for:
+//   @media (prefers-reduced-motion: reduce) { ... }
+//   :root[data-motion='reduce'] { ... same rule ... }
+//   :root[data-motion='allow'] { /* opt back in despite OS-level reduce */ }
+// (see swarm-ui's `shell/Shell.css` file-top comment for a worked
+// example). A page with no motion-gated animation yet can still mount
+// this — the attribute is simply inert until something reads it.
+import { useEffect } from 'preact/hooks';
+import { useLocalSetting } from './settings-storage.js';
+
+export type MotionOverride = 'system' | 'reduce' | 'allow';
+
+export function useMotionOverride(key: string, fallback: MotionOverride = 'system') {
+  return useLocalSetting<MotionOverride>(key, fallback);
+}
+
+// Mounted once alongside `useApplyThemeOverride` — same single-mount-
+// point rationale.
+export function useApplyMotionOverride(key: string, fallback: MotionOverride = 'system'): void {
+  const [override] = useMotionOverride(key, fallback);
+  useEffect(() => {
+    const root = document.documentElement;
+    if (override === 'system') {
+      delete root.dataset.motion;
+    } else {
+      root.dataset.motion = override;
+    }
+  }, [override]);
+}

frontend/packages/shared/src/settings/settings-storage.ts

@@ -0,0 +1,79 @@
+// Generic localStorage-backed setting — the shared plumbing a theme
+// override and a reduced-motion override both need ("read a stored
+// value, react to it changing, write a new one") rather than each
+// caller reinventing its own key handling. Not settings-page-specific:
+// any client-local preference reaches for `useLocalSetting` directly.
+// Originated in swarm-ui's own `lib/settings-storage.ts`; moved here
+// once the per-agent page needed the identical mechanism (mara: "i
+// think the component should be shared" — see `SettingsMenu.tsx`'s
+// file comment for the full story).
+//
+// `localStorage`'s own `storage` event only fires in *other* tabs, never
+// the tab that made the write — so two components in the same tab both
+// watching the same key (e.g. `SettingsMenu` writing, a top-level effect
+// reading) need their own same-tab signal. The tiny module-level pub/sub
+// below is that signal; it's deliberately not exported, callers only see
+// the hook.
+import { useEffect, useState } from 'preact/hooks';
+
+const listeners = new Map<string, Set<() => void>>();
+
+function subscribe(key: string, onChange: () => void): () => void {
+  let set = listeners.get(key);
+  if (!set) {
+    set = new Set();
+    listeners.set(key, set);
+  }
+  set.add(onChange);
+  return () => {
+    set!.delete(onChange);
+    if (set!.size === 0) listeners.delete(key);
+  };
+}
+
+function notify(key: string): void {
+  listeners.get(key)?.forEach((fn) => fn());
+}
+
+// Reads outside a component (e.g. an early top-level check) can call
+// this directly; `useLocalSetting` builds on it rather than duplicating
+// the try/catch.
+export function readLocalSetting<T>(key: string, fallback: T): T {
+  try {
+    const raw = localStorage.getItem(key);
+    return raw === null ? fallback : (JSON.parse(raw) as T);
+  } catch {
+    // Private-browsing storage bans, a corrupted value, quota errors —
+    // all the same answer: behave as if nothing were stored.
+    return fallback;
+  }
+}
+
+function writeLocalSetting<T>(key: string, value: T): void {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    // Best-effort: the setting just won't persist this time, not worth
+    // surfacing an error for a client-local preference.
+  }
+  notify(key);
+}
+
+// `[value, setValue]`, same shape as `useState` — deliberately, so a
+// caller that later needs to swap a plain `useState` for a persisted
+// setting (or vice versa) changes one line, not its whole call site.
+//
+// `setValue` only writes + notifies; it doesn't also call this
+// component's own `setValue` state setter directly. The subscription
+// below already fires for a same-instance write (it's in the same
+// `listeners` set as every other subscriber), so a self-write reaches
+// this component's state through the identical "react to a change"
+// path every other subscriber uses — one path, not two that have to
+// agree.
+export function useLocalSetting<T>(key: string, fallback: T): [T, (value: T) => void] {
+  const [value, setValue] = useState<T>(() => readLocalSetting(key, fallback));
+
+  useEffect(() => subscribe(key, () => setValue(readLocalSetting(key, fallback))), [key]);
+
+  return [value, (next: T) => writeLocalSetting(key, next)];
+}

frontend/packages/shared/src/settings/theme-apply.ts

@@ -0,0 +1,40 @@
+// Applies a stored theme override by setting `data-theme="light"|"dark"`
+// on `<html>`, cleared when the override is "system" (letting the
+// `prefers-color-scheme` media query in `./colors.css` resume control).
+// No palette values live here — `colors.css`'s own
+// `:root[data-theme='light']` / `:root[data-theme='dark']` blocks are
+// what actually apply the colours.
+//
+// Callers own their own storage key (kept in their own small constant,
+// not derived here) so two pages never silently share one browser-local
+// setting by accident. `fallback` defaults to `'dark'`: `prefers-color-
+// scheme` has no real "unset" value the way `prefers-reduced-motion`
+// does, so a browser with no explicit dark-mode toggle reports `light`
+// — `'system'` as a default silently reads as light-by-default for most
+// first-time visitors (mara: "light mode seems to be default"). Still
+// fully overridable per caller if a page ever wants a different default.
+import { useEffect } from 'preact/hooks';
+import { useLocalSetting } from './settings-storage.js';
+
+export type ThemeOverride = 'system' | 'light' | 'dark';
+
+export function useThemeOverride(key: string, fallback: ThemeOverride = 'dark') {
+  return useLocalSetting<ThemeOverride>(key, fallback);
+}
+
+// Mounted once, high in the tree — one mount point applies the override
+// regardless of what else is rendering, and `useLocalSetting`'s
+// same-tab subscription means `SettingsMenu` changing the value re-runs
+// this effect without either component needing to know about the other
+// directly.
+export function useApplyThemeOverride(key: string, fallback: ThemeOverride = 'dark'): void {
+  const [override] = useThemeOverride(key, fallback);
+  useEffect(() => {
+    const root = document.documentElement;
+    if (override === 'system') {
+      delete root.dataset.theme;
+    } else {
+      root.dataset.theme = override;
+    }
+  }, [override]);
+}