@schlessera/brain-ui-react 0.35.0 → 0.36.0

package/src/components/layout/mobile-tab-bar.tsx

@@ -1,184 +1,107 @@
 import { useEffect, useRef, useState } from "react";
-import {
-  Activity,
-  Brain,
-  RefreshCw,
-  History,
-  SlidersHorizontal,
-  FolderTree,
-  SquarePen,
-  MoreHorizontal,
-  Waypoints,
-} from "lucide-react";
+import { BottomSheet, ListRow, TabBar, type TabItem } from "@schlessera/brain-ui-kit";
 import { useUIStore } from "../../stores/ui-store.js";
-import { useChatStore } from "../../stores/chat-store.js";
+import { useChatStore, activeChat, pendingApprovals } from "../../stores/chat-store.js";
 import { useActivityStore } from "../../stores/activity-store.js";
-import { cn } from "../../lib/utils.js";
-import { CountBadge } from "../activity/span-bits.js";
+import { useConnectionStore } from "../../stores/connection-store.js";
+import { useChatCommands } from "../chat/use-chat-commands.js";
 
+/**
+ * The phone's bottom navigation, on the kit's `TabBar`. The five slots are
+ * the desktop rail's five destinations with Settings folded into More (D37):
+ * Chat · Actions · Files · Graph · More. Six into five does not go, and the
+ * one you live in least is the one to fold — never one of the four you live
+ * in. New chat is not a slot: a tab is a place and starting a chat is an
+ * act, so it is the Chat header's primary action and a ⌘K command.
+ *
+ * More is the kit `BottomSheet`, docked over a scrim, holding Settings and
+ * the acts — Sessions, Sync, Daily briefing, Brain statistics — as kit
+ * `ListRow`s. The sheet is a sibling of the bar rather than a child of the
+ * More slot, because a kit tab is a leaf and cannot host it.
+ */
 export function MobileTabBar() {
   const activeView = useUIStore((s) => s.activeView);
   const setActiveView = useUIStore((s) => s.setActiveView);
-  const toggleSessionPanel = useUIStore((s) => s.toggleSessionPanel);
-  const toggleSyncPanel = useUIStore((s) => s.toggleSyncPanel);
   const toggleFilePanel = useUIStore((s) => s.toggleFilePanel);
-  const toggleSettingsPanel = useUIStore((s) => s.toggleSettingsPanel);
-  const clearMessages = useChatStore((s) => s.clearMessages);
+  const setSessionPanelOpen = useUIStore((s) => s.setSessionPanelOpen);
+  const setSettingsPanelOpen = useUIStore((s) => s.setSettingsPanelOpen);
   const inboxCount = useActivityStore((s) => s.inbox.length);
-
-  /** Chat-scoped panels live in the chat page — surface it before opening them. */
-  function inChat(toggle: () => void) {
-    return () => {
-      if (activeView !== "chat") setActiveView("chat");
-      toggle();
-    };
-  }
+  const approvalCount = useChatStore((s) => pendingApprovals(s).length);
+  const isStreaming = useChatStore((s) => activeChat(s).isStreaming);
+  const connected = useConnectionStore((s) => s.wsStatus === "connected");
+  const runCommand = useChatCommands();
+  const needsYou = inboxCount + approvalCount;
 
   const [moreOpen, setMoreOpen] = useState(false);
   const moreRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
     if (!moreOpen) return;
-    function onDocClick(e: MouseEvent) {
-      if (!moreRef.current?.contains(e.target as Node)) setMoreOpen(false);
-    }
     function onKey(e: KeyboardEvent) {
       if (e.key === "Escape") setMoreOpen(false);
     }
-    document.addEventListener("mousedown", onDocClick);
     document.addEventListener("keydown", onKey);
-    return () => {
-      document.removeEventListener("mousedown", onDocClick);
-      document.removeEventListener("keydown", onKey);
-    };
+    // The sheet's first row takes focus; the More slot gets it back on close.
+    moreRef.current?.querySelector<HTMLElement>('[role="button"]')?.focus();
+    return () => document.removeEventListener("keydown", onKey);
   }, [moreOpen]);
 
-  return (
-    <nav className="md:hidden fixed bottom-0 inset-x-0 z-30 flex h-14 items-center justify-around border-t border-border bg-surface px-1 pb-[env(safe-area-inset-bottom)]">
-      <TabIcon
-        icon={Brain}
-        label="Chat"
-        active={activeView === "chat"}
-        onClick={() => setActiveView("chat")}
-      />
-      <TabIcon
-        icon={SquarePen}
-        label="New chat"
-        onClick={() => {
-          setMoreOpen(false);
-          setActiveView("chat");
-          clearMessages();
-        }}
-      />
-      {/* Activity holds the tab-bar slot; Graph moved into the More menu —
-          the phone glance-check ("is real work happening?") is the headline
-          flow and must stay one tap away (planning decision). */}
-      <TabIcon
-        icon={Activity}
-        label="Activity"
-        active={activeView === "activity"}
-        badge={inboxCount}
-        onClick={() => setActiveView("activity")}
-      />
-      <TabIcon icon={FolderTree} label="Files" onClick={toggleFilePanel} />
-      <div ref={moreRef} className="relative">
-        <TabIcon
-          icon={MoreHorizontal}
-          label="More"
-          active={moreOpen}
-          onClick={() => setMoreOpen((v) => !v)}
-        />
-        {moreOpen && (
-          <div
-            role="menu"
-            className="absolute bottom-full right-0 z-50 mb-2 min-w-[10rem] overflow-hidden rounded-xl border border-border bg-surface-overlay py-1 shadow-2xl"
-          >
-            <MoreItem
-              icon={Waypoints}
-              label="Graph"
-              onClick={() => {
-                setMoreOpen(false);
-                setActiveView("graph");
-              }}
-            />
-            <MoreItem
-              icon={RefreshCw}
-              label="Sync"
-              onClick={() => {
-                setMoreOpen(false);
-                inChat(toggleSyncPanel)();
-              }}
-            />
-            <MoreItem
-              icon={History}
-              label="History"
-              onClick={() => {
-                setMoreOpen(false);
-                inChat(toggleSessionPanel)();
-              }}
-            />
-            <MoreItem
-              icon={SlidersHorizontal}
-              label="Settings"
-              onClick={() => {
-                setMoreOpen(false);
-                toggleSettingsPanel();
-              }}
-            />
-          </div>
-        )}
-      </div>
-    </nav>
-  );
-}
+  /** An act from the sheet: close it, land on chat, run. */
+  function act(fn: () => void) {
+    return () => {
+      setMoreOpen(false);
+      setActiveView("chat");
+      fn();
+    };
+  }
 
-function TabIcon({
-  icon: Icon,
-  label,
-  active,
-  onClick,
-  badge,
-}: {
-  icon: typeof Brain;
-  label: string;
-  active?: boolean;
-  onClick?: () => void;
-  /** Unread-count dot (the inbox badge). Hidden at 0. */
-  badge?: number;
-}) {
-  return (
-    <button
-      onClick={onClick}
-      className={cn(
-        "relative flex flex-col items-center gap-0.5 px-2 py-1 text-[10px]",
-        active ? "text-primary" : "text-muted-foreground"
-      )}
-    >
-      <Icon className="h-5 w-5" />
-      {badge !== undefined && <CountBadge count={badge} className="right-0 top-0" />}
-      {label}
-    </button>
-  );
-}
+  const items: TabItem[] = [
+    { icon: "brain", label: "Chat", onClick: () => setActiveView("chat") },
+    {
+      icon: "resolved",
+      label: "Actions",
+      badge: needsYou > 0 ? (needsYou > 9 ? "9+" : String(needsYou)) : undefined,
+      onClick: () => setActiveView("activity"),
+    },
+    { icon: "files", label: "Files", onClick: toggleFilePanel },
+    { icon: "graph", label: "Graph", onClick: () => setActiveView("graph") },
+    { icon: "more", label: "More", onClick: () => setMoreOpen((v) => !v) },
+  ];
+  // The amber slot. -1 is "none", which the kit renders as no active item
+  // and still keeps the bar reachable (its stop falls back to the first
+  // eligible slot).
+  const active = moreOpen ? 4 : activeView === "chat" ? 0 : activeView === "activity" ? 1 : activeView === "graph" ? 3 : -1;
+  const quiet = connected && !isStreaming;
 
-function MoreItem({
-  icon: Icon,
-  label,
-  onClick,
-}: {
-  icon: typeof Brain;
-  label: string;
-  onClick: () => void;
-}) {
   return (
-    <button
-      role="menuitem"
-      type="button"
-      onClick={onClick}
-      className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-xs text-foreground transition-colors hover:bg-surface-raised"
+    <nav
+      aria-label="Primary"
+      className="tablet:hidden fixed bottom-0 inset-x-0 z-30 pb-[env(safe-area-inset-bottom)]"
+      // The safe-area strip below the bar takes the bar's own ground, from the
+      // kit's token so it follows the theme.
+      style={{ background: "var(--bk-color-surface)" }}
     >
-      <Icon className="h-4 w-4 shrink-0 text-muted-foreground" />
-      {label}
-    </button>
+      {moreOpen && (
+        <div
+          className="fixed inset-0 z-40 bg-black/60"
+          onMouseDown={(e) => {
+            if (e.target === e.currentTarget) setMoreOpen(false);
+          }}
+        >
+          <div ref={moreRef} role="dialog" aria-label="More" className="absolute inset-x-0 bottom-0">
+            <BottomSheet title="More" subtitle="Settings, and the things you run rather than visit." docked>
+              <div className="flex flex-col">
+                <ListRow variant="group" icon="settings" iconTone="neutral" title="Settings" chevron onClick={() => { setMoreOpen(false); setSettingsPanelOpen(true); }} />
+                <ListRow variant="group" icon="history" iconTone="blue" title="Sessions" subtitle="Resume an earlier conversation" chevron onClick={act(() => setSessionPanelOpen(true))} />
+                <ListRow variant="group" icon="repeat" iconTone="amber" title="Sync the brain" subtitle={quiet ? "Pull and push the repository" : "needs the host"} value={quiet ? "sync" : undefined} valueTone="amber" onClick={quiet ? act(() => runCommand("sync")) : undefined} />
+                <ListRow variant="group" icon="sunrise" iconTone="gold" title="Daily briefing" subtitle={quiet ? "What happened since you looked" : "needs the host"} onClick={quiet ? act(() => runCommand("whatsup")) : undefined} />
+                <ListRow variant="group" icon="ledger" iconTone="neutral" title="Brain statistics" subtitle={quiet ? "Documents, tags and links" : "needs the host"} last onClick={quiet ? act(() => runCommand("stats")) : undefined} />
+              </div>
+            </BottomSheet>
+          </div>
+        </div>
+      )}
+      <TabBar items={items} active={active} />
+    </nav>
   );
 }

package/src/components/layout/shortcut-switch.tsx

@@ -0,0 +1,32 @@
+import { Icon, Toggle } from "@schlessera/brain-ui-kit";
+import { useId } from "react";
+import { useUIStore } from "../../stores/ui-store.js";
+
+/**
+ * The off switch for single-key shortcuts (D36, D37). WCAG 2.1.4 asks that
+ * a single-character shortcut can be turned off, remapped, or made active
+ * only on focus; the design chose focus scope AND an off switch, because a
+ * reader whose screen reader or speech input types letters into a focused
+ * card still needs the switch. Modifier shortcuts are not governed by it.
+ *
+ * Drawn as D5 draws it: a group row — icon, title, the mono hint as the
+ * subtitle — with the kit `Toggle` trailing, named by the row's title. The
+ * kit `ListRow`'s own toggle is decorative, so the row is composed here.
+ */
+export function ShortcutSwitch() {
+  const on = useUIStore((s) => s.singleKeyShortcuts);
+  const set = useUIStore((s) => s.setSingleKeyShortcuts);
+  const id = useId();
+  return (
+    <div className="flex items-center gap-3 px-3 py-3">
+      <Icon icon="capability" size={17} color="var(--bk-amber-ink)" />
+      <span className="min-w-0 flex-1">
+        <span id={id} className="block text-[12.5px] font-semibold text-foreground">Single-key shortcuts</span>
+        <span className="mt-0.5 block font-[family-name:var(--font-mono)] text-[10px] text-muted-foreground">
+          a d on a focused approval · j k in a list
+        </span>
+      </span>
+      <Toggle on={on} tone="amber" labelledBy={id} onClick={() => set(!on)} />
+    </div>
+  );
+}

package/src/components/layout/side-rail.tsx

@@ -1,169 +1,89 @@
-import {
-  Activity,
-  Brain,
-  RefreshCw,
-  Newspaper,
-  History,
-  SlidersHorizontal,
-  SquarePen,
-  FolderTree,
-  Waypoints,
-} from "lucide-react";
+import { SideRail as KitSideRail, type RailItem } from "@schlessera/brain-ui-kit";
+import { useEffect } from "react";
 import { useConnectionStore } from "../../stores/connection-store.js";
 import { useActivityStore } from "../../stores/activity-store.js";
+import { useChatStore, pendingApprovals } from "../../stores/chat-store.js";
 import { useUIStore } from "../../stores/ui-store.js";
-import { useChatStore, activeChat } from "../../stores/chat-store.js";
-import { cn } from "../../lib/utils.js";
-import { CountBadge } from "../activity/span-bits.js";
+import { useMediaQuery } from "../../hooks/use-media-query.js";
 
+/**
+ * The desktop navigation, on the kit's `SideRail`. The kit owns the rail —
+ * the one roving tab stop, the amber destination, the badge, the collapsed
+ * and expanded widths; this file owns what the destinations DO, which of
+ * them is "here", and the ⌘1–⌘5 keys the design prints beside them (D36:
+ * anything global takes a modifier).
+ *
+ * The five destinations are the design's (D37): Chat · Actions · Files ·
+ * Graph · Settings, the same five and the same order as the phone bar.
+ * Activity is not among them — "what needs me" and "what has been happening"
+ * are two lenses on one queue, so the Actions pane carries a filter and the
+ * badge counts what needs you: pending approvals plus the inbox. The acts
+ * the old rail carried (New chat, Sessions, Sync, the briefing) live in the
+ * ⌘K palette and the Chat header.
+ *
+ * Widths follow D22's ladder: the phone bar to 479px, this rail collapsed
+ * to 60px from 480 (`tablet:`), expanded to 208px from 900 (`laptop:`). The
+ * rail appears at the breakpoint the phone bar disappears at, so the two
+ * never show together.
+ *
+ * The connection status takes the wordmark's line: teal while live, amber
+ * while reconnecting, red when the socket is gone. No spend meter — the app
+ * tracks no spend — and the ⌘K cap is real, because the palette is.
+ */
 export function SideRail() {
   const wsStatus = useConnectionStore((s) => s.wsStatus);
   const activeView = useUIStore((s) => s.activeView);
   const setActiveView = useUIStore((s) => s.setActiveView);
-  const toggleSessionPanel = useUIStore((s) => s.toggleSessionPanel);
-  const toggleSyncPanel = useUIStore((s) => s.toggleSyncPanel);
-  const toggleWhatsupPanel = useUIStore((s) => s.toggleWhatsupPanel);
+  const filePanelOpen = useUIStore((s) => s.filePanelOpen);
+  const settingsPanelOpen = useUIStore((s) => s.settingsPanelOpen);
   const toggleFilePanel = useUIStore((s) => s.toggleFilePanel);
   const toggleSettingsPanel = useUIStore((s) => s.toggleSettingsPanel);
-  const clearMessages = useChatStore((s) => s.clearMessages);
-  const hasMessages = useChatStore((s) => activeChat(s).messages.length > 0);
-  const isStreaming = useChatStore((s) => activeChat(s).isStreaming);
   const inboxCount = useActivityStore((s) => s.inbox.length);
+  const approvalCount = useChatStore((s) => pendingApprovals(s).length);
+  const needsYou = inboxCount + approvalCount;
+  const expanded = useMediaQuery("(min-width: 900px)");
 
-  /** Chat-scoped panels live in the chat page — surface it before opening them. */
-  function inChat(toggle: () => void) {
-    return () => {
-      if (activeView !== "chat") setActiveView("chat");
-      toggle();
-    };
-  }
+  const items: RailItem[] = [
+    { icon: "brain", label: "Chat", shortcut: "⌘1", onClick: () => setActiveView("chat") },
+    {
+      icon: "resolved",
+      label: "Actions",
+      shortcut: "⌘2",
+      badge: needsYou > 0 ? (needsYou > 9 ? "9+" : String(needsYou)) : undefined,
+      onClick: () => setActiveView("activity"),
+    },
+    { icon: "files", label: "Files", shortcut: "⌘3", onClick: toggleFilePanel },
+    { icon: "graph", label: "Graph", shortcut: "⌘4", onClick: () => setActiveView("graph") },
+    { icon: "settings", label: "Settings", shortcut: "⌘5", onClick: toggleSettingsPanel },
+  ];
 
-  return (
-    <nav className="hidden md:flex w-16 shrink-0 flex-col items-center border-r border-border bg-surface py-4 gap-1">
-      {/* Logo */}
-      <div className="mb-4">
-        <Brain className="h-7 w-7 text-primary" />
-      </div>
-
-      {/* New chat */}
-      {hasMessages && (
-        <RailButton
-          icon={SquarePen}
-          label="New chat"
-          onClick={clearMessages}
-        />
-      )}
-
-      {/* Divider */}
-      <div className="my-2 h-px w-8 bg-border" />
-
-      {/* Quick actions */}
-      <RailButton
-        icon={RefreshCw}
-        label="Sync"
-        onClick={inChat(toggleSyncPanel)}
-        disabled={isStreaming}
-      />
-      <RailButton
-        icon={Newspaper}
-        label="Whatsup"
-        onClick={inChat(toggleWhatsupPanel)}
-        disabled={isStreaming}
-      />
-      <RailButton
-        icon={FolderTree}
-        label="Files"
-        onClick={toggleFilePanel}
-      />
-      <RailButton
-        icon={Waypoints}
-        label="Graph"
-        active={activeView === "graph"}
-        onClick={() =>
-          setActiveView(activeView === "graph" ? "chat" : "graph")
-        }
-      />
-      <RailButton
-        icon={Activity}
-        label="Activity"
-        active={activeView === "activity"}
-        badge={inboxCount}
-        onClick={() =>
-          setActiveView(activeView === "activity" ? "chat" : "activity")
-        }
-      />
+  // A panel over the view is "here" while it is open; otherwise the view is.
+  const active = filePanelOpen ? 2 : settingsPanelOpen ? 4 : activeView === "chat" ? 0 : activeView === "activity" ? 1 : 3;
 
-      {/* Spacer */}
-      <div className="flex-1" />
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    function onKey(e: KeyboardEvent) {
+      if (!(e.metaKey || e.ctrlKey) || e.altKey || e.shiftKey) return;
+      const n = Number(e.key);
+      if (!Number.isInteger(n) || n < 1 || n > items.length) return;
+      e.preventDefault();
+      items[n - 1]!.onClick?.();
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  });
 
-      {/* History */}
-      <RailButton
-        icon={History}
-        label="Sessions"
-        onClick={inChat(toggleSessionPanel)}
-      />
-
-      {/* Settings (models, passkeys, sign out) */}
-      <RailButton
-        icon={SlidersHorizontal}
-        label="Settings"
-        onClick={toggleSettingsPanel}
+  return (
+    <nav aria-label="Primary" className="hidden tablet:flex shrink-0">
+      <KitSideRail
+        items={items}
+        active={active}
+        expanded={expanded}
+        status={wsStatus === "connected" ? "live" : wsStatus === "connecting" ? "reconnecting" : "offline"}
+        statusTone={wsStatus === "connected" ? "teal" : wsStatus === "connecting" ? "amber" : "red"}
+        spendPct={null}
+        hint="Command palette"
       />
-
-      {/* Connection status */}
-      <div className="mt-2 flex flex-col items-center gap-1">
-        <span
-          className={cn(
-            "inline-block h-2 w-2 rounded-full",
-            wsStatus === "connected" && "bg-green-500",
-            wsStatus === "connecting" && "bg-primary animate-pulse",
-            wsStatus === "disconnected" && "bg-destructive"
-          )}
-        />
-        <span className="text-[10px] text-muted-foreground">
-          {wsStatus === "connected"
-            ? "Live"
-            : wsStatus === "connecting"
-              ? "..."
-              : "Off"}
-        </span>
-      </div>
     </nav>
   );
 }
-
-function RailButton({
-  icon: Icon,
-  label,
-  onClick,
-  disabled,
-  active,
-  badge,
-}: {
-  icon: typeof Brain;
-  label: string;
-  onClick: () => void;
-  disabled?: boolean;
-  active?: boolean;
-  /** Unread-count dot (the inbox badge). Hidden at 0. */
-  badge?: number;
-}) {
-  return (
-    <button
-      onClick={onClick}
-      disabled={disabled}
-      title={label}
-      className={cn(
-        "group relative flex h-10 w-10 items-center justify-center rounded-lg transition-all duration-150 hover:bg-surface-raised hover:text-foreground hover:scale-110 disabled:opacity-40 disabled:hover:scale-100",
-        active ? "bg-surface-raised text-primary" : "text-muted-foreground"
-      )}
-    >
-      <Icon className="h-4.5 w-4.5" />
-      {badge !== undefined && <CountBadge count={badge} className="-right-0.5 -top-0.5" />}
-      {/* Tooltip */}
-      <span className="pointer-events-none absolute left-full ml-2 whitespace-nowrap rounded-md bg-surface-overlay px-2.5 py-1 text-xs font-medium text-foreground opacity-0 shadow-lg transition-opacity group-hover:opacity-100 border border-border">
-        {label}
-      </span>
-    </button>
-  );
-}

package/src/components/layout/slide-panel.tsx

@@ -6,17 +6,29 @@ import { cn } from "../../lib/utils.js";
 /** Matches the `duration-300` slide-out below. */
 const SLIDE_OUT_MS = 300;
 
+/**
+ * `drawer` slides in from the right over a backdrop and draws its own header.
+ * `pane` (D5, from `laptop:` up) is the design's settings PANE: a fixed layer
+ * over the content area, offset by the rail's width, with no backdrop and no
+ * header of its own — the children draw the header row, because a pane's
+ * chrome is a `ScreenHeader`, not a drawer's title bar. It renders nothing
+ * while closed: there is no slide to outlive.
+ */
+export type SlidePanelMode = "drawer" | "pane";
+
 export function SlidePanel({
   open,
   onClose,
   title,
   wide,
+  mode = "drawer",
   children,
 }: {
   open: boolean;
   onClose: () => void;
   title: string;
   wide?: boolean;
+  mode?: SlidePanelMode;
   children: ReactNode;
 }) {
   useEffect(() => {
@@ -36,6 +48,18 @@ export function SlidePanel({
    */
   const showContent = useDeferredUnmount(open, SLIDE_OUT_MS);
 
+  if (mode === "pane") {
+    if (!open) return null;
+    return (
+      <section
+        aria-label={title}
+        className="fixed top-0 bottom-0 right-0 tablet:left-[60px] laptop:left-[208px] z-40 flex flex-col overflow-hidden bg-surface"
+      >
+        {children}
+      </section>
+    );
+  }
+
   return (
     <>
       {/* Backdrop */}
@@ -50,8 +74,11 @@ export function SlidePanel({
       <div
         className={cn(
           "fixed right-0 top-0 z-50 flex h-full flex-col border-l border-border bg-surface shadow-[0_16px_48px_rgba(0,0,0,0.5)]",
-          "transform transition-transform duration-300 ease-out",
-          open ? "translate-x-0" : "translate-x-full",
+          "transform transition-[transform,box-shadow] duration-300 ease-out",
+          // A closed drawer sits just past the right edge, and its 48px shadow
+          // would still bleed into the viewport: the shadow fades with the
+          // slide, and a closed drawer takes no clicks.
+          open ? "translate-x-0" : "translate-x-full shadow-none pointer-events-none",
           wide ? "w-full md:w-[480px]" : "w-full md:w-80"
         )}
       >

package/src/components/layout/theme.tsx

@@ -0,0 +1,67 @@
+import { useEffect } from "react";
+import { useUIStore, type ThemePreference } from "../../stores/ui-store.js";
+import { cn } from "../../lib/utils.js";
+
+/**
+ * Writes the stored theme preference to `<html data-theme>`. That attribute
+ * is the whole switch: the kit's `tokens.css` maps it onto `color-scheme`,
+ * every `--bk-*` token is `light-dark()`, and the browser picks the half — so
+ * nothing else in the app has to know. `system` lets `prefers-color-scheme`
+ * decide.
+ *
+ * Runs in an effect, so the first paint of a stored non-default preference
+ * can still flash the default. A host that cares puts a one-line inline
+ * script in its HTML before the stylesheet:
+ *   `document.documentElement.dataset.theme = localStorage.getItem("brain-theme") || "dark"`
+ * (with the root's storage prefix, if it sets one). The kit's README says the
+ * same; the app cannot do it for the host because the host owns the HTML.
+ */
+export function useApplyTheme(): void {
+  const theme = useUIStore((s) => s.theme);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    document.documentElement.dataset.theme = theme;
+  }, [theme]);
+}
+
+const OPTIONS: Array<{ id: ThemePreference; label: string; hint: string }> = [
+  { id: "system", label: "System", hint: "Follow the device" },
+  { id: "light", label: "Paper", hint: "Light, for daylight" },
+  { id: "dark", label: "Dark", hint: "The default" },
+];
+
+/**
+ * The design's three-way toggle, kept in Settings ("respect the system, offer
+ * the override"). One radiogroup, three options, no icon: the label is the
+ * meaning.
+ */
+export function ThemeToggle() {
+  const theme = useUIStore((s) => s.theme);
+  const setTheme = useUIStore((s) => s.setTheme);
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Theme"
+      className="flex items-center gap-1 rounded-lg border border-border bg-surface p-0.5"
+    >
+      {OPTIONS.map((o) => (
+        <button
+          key={o.id}
+          type="button"
+          role="radio"
+          aria-checked={theme === o.id}
+          title={o.hint}
+          onClick={() => setTheme(o.id)}
+          className={cn(
+            "rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+            theme === o.id
+              ? "bg-surface-raised text-foreground"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          {o.label}
+        </button>
+      ))}
+    </div>
+  );
+}