@schlessera/brain-ui-react 0.34.1 → 0.36.0

package/src/components/graph/node-popover.tsx

@@ -1,14 +1,17 @@
-import { X, FileText, Crosshair, Expand } from "lucide-react";
 import type { GraphNodePayload } from "@schlessera/brain-ui-sdk/protocol";
-import { useFileStore } from "../../stores/file-store.js";
-import { useUIStore } from "../../stores/ui-store.js";
-import { useGraphStore } from "../../stores/graph-store.js";
 import { communityColor } from "./lib/graph-helpers.js";
+import { NodeCard } from "./node-card.js";
+import { useGraphTheme } from "./use-graph-theme.js";
+import { useNodeActions } from "./use-node-actions.js";
 
 /**
  * Detail card for the selected node, docked to the bottom-left of the canvas
- * (bottom sheet width on phones). "Open note" hands over to the file viewer
- * panel — the same hand-off the search modal uses.
+ * (bottom sheet width on phones). From `wide:` the D6 right rail draws the
+ * node instead and `SceneBody` does not mount this.
+ *
+ * This is the container (S7): the store reads and the "which actions
+ * apply" rules (`useNodeActions`) live here; `NodeCard` draws the card on
+ * the kit.
  */
 export function NodePopover({
   node,
@@ -17,119 +20,27 @@ export function NodePopover({
   node: GraphNodePayload;
   communityLabel?: string | null;
 }) {
-  const openFile = useFileStore((s) => s.openFile);
-  const setFilePanelOpen = useUIStore((s) => s.setFilePanelOpen);
-  const mode = useGraphStore((s) => s.mode);
-  const select = useGraphStore((s) => s.select);
-  const setMode = useGraphStore((s) => s.setMode);
-  const setLocalParams = useGraphStore((s) => s.setLocalParams);
-  const expandNode = useGraphStore((s) => s.expandNode);
-
+  const actions = useNodeActions(node);
+  const theme = useGraphTheme();
   const isVirtual = node.virtual === true;
 
-  function handleOpen() {
-    setFilePanelOpen(true);
-    void openFile(node.path);
-  }
-
-  function handleFocus() {
-    // Re-center the local view on this node (switching mode when needed).
-    if (mode !== "local") setMode("local");
-    setLocalParams({ center: node.path });
-    select(null);
-  }
-
-  return (
-    <div className="pointer-events-auto absolute inset-x-2 bottom-2 z-10 rounded-xl border border-border bg-surface-overlay/95 p-4 shadow-2xl backdrop-blur md:inset-x-auto md:left-4 md:bottom-4 md:w-80">
-      <div className="flex items-start justify-between gap-2">
-        <div className="min-w-0">
-          <div className="flex items-center gap-2">
-            <span className="shrink-0 rounded bg-surface-raised px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-muted-foreground">
-              {isVirtual ? "root" : node.type}
-            </span>
-            {communityLabel && (
-              <span
-                title="Topic cluster inferred from this note's links"
-                className="flex min-w-0 items-center gap-1 rounded bg-surface-raised px-1.5 py-0.5 text-[10px] text-muted-foreground"
-              >
-                {node.community !== undefined && (
-                  <span
-                    aria-hidden="true"
-                    className="h-1.5 w-1.5 shrink-0 rounded-full"
-                    style={{ backgroundColor: communityColor(node.community) }}
-                  />
-                )}
-                <span className="truncate">Topic: {communityLabel}</span>
-              </span>
-            )}
-          </div>
-          <h3 className="mt-1 truncate text-sm font-medium text-foreground">
-            {node.title || node.path}
-          </h3>
-          <p className="truncate font-mono text-[10px] text-muted-foreground/60">
-            {node.path}
-          </p>
-        </div>
-        <button
-          onClick={() => select(null)}
-          className="shrink-0 rounded p-1 text-muted-foreground transition-colors hover:text-foreground"
-          title="Close"
-        >
-          <X className="h-3.5 w-3.5" />
-        </button>
-      </div>
-
-      <div className="mt-2 flex gap-4 text-[11px] text-muted-foreground">
-        <span>{node.inDegree} in</span>
-        <span>{node.outDegree} out</span>
-        {node.distance !== undefined && node.distance > 0 && (
-          <span>
-            {node.distance} hop{node.distance === 1 ? "" : "s"}
-          </span>
-        )}
-      </div>
-
-      <div className="mt-3 flex flex-wrap gap-2">
-        {!isVirtual && (
-          <ActionButton icon={FileText} label="Open note" onClick={handleOpen} primary />
-        )}
-        {!isVirtual && (mode !== "local" || node.distance !== 0) && (
-          <ActionButton icon={Crosshair} label="Focus here" onClick={handleFocus} />
-        )}
-        {mode === "local" && !isVirtual && node.distance !== 0 && (
-          <ActionButton
-            icon={Expand}
-            label="Expand"
-            onClick={() => void expandNode(node.path)}
-          />
-        )}
-      </div>
-    </div>
-  );
-}
-
-function ActionButton({
-  icon: Icon,
-  label,
-  onClick,
-  primary,
-}: {
-  icon: typeof X;
-  label: string;
-  onClick: () => void;
-  primary?: boolean;
-}) {
   return (
-    <button
-      onClick={onClick}
-      className={
-        primary
-          ? "flex min-h-9 items-center gap-1.5 rounded-lg bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground transition-colors hover:bg-primary/90"
-          : "flex min-h-9 items-center gap-1.5 rounded-lg bg-surface-raised px-3 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-surface-overlay"
-      }
-    >
-      <Icon className="h-3.5 w-3.5" />
-      {label}
-    </button>
+    <NodeCard
+      kind={isVirtual ? "root" : node.type}
+      title={node.title || node.path}
+      path={node.path}
+      topic={communityLabel}
+      topicColor={node.community !== undefined ? communityColor(node.community, theme.palette) : undefined}
+      inDegree={node.inDegree}
+      outDegree={node.outDegree}
+      distance={node.distance}
+      canOpen={actions.canOpen}
+      canFocus={actions.canFocus}
+      canExpand={actions.canExpand}
+      onOpen={actions.open}
+      onFocus={actions.focus}
+      onExpand={actions.expand}
+      onClose={actions.close}
+    />
   );
 }

package/src/components/graph/use-graph-theme.ts

@@ -1,51 +1,88 @@
 import { useMemo } from "react";
+import type { TokenName } from "@schlessera/brain-ui-kit";
+
+import { useColorScheme } from "../../hooks/use-color-scheme.js";
+import { readToken, type ColorScheme } from "../../lib/light-dark.js";
+import type { CanvasPalette } from "./lib/graph-helpers.js";
 
 export interface GraphTheme {
   background: string;
   /** Raised surface used for the hover-label plate (sigma's default is #FFF,
-   * unreadable under our near-white label text). */
+   * unreadable under the dark theme's near-white label text). */
   surfaceOverlay: string;
   node: string;
   nodeSelected: string;
   edge: string;
   edgeHighlight: string;
+  /** Every label is drawn in the ink — never in its node's colour, which is
+   * a value tuned for a 7px mark, not for the one thing you must read. */
   label: string;
   labelMuted: string;
+  /**
+   * The kit's entity colours (its `GraphView`, `PathRef` and inline
+   * mentions): teal a person, blue a company, purple a project, amber the
+   * focus node, and the neutral for any other document type. The three kinds
+   * take the MARK weight, which is the fill in the dark and a darkened step
+   * on paper, where a fill sits under 3:1 against the canvas.
+   */
+  entity: EntityColors;
+  /** The categorical slots, the distance ramp and the fixed roles, resolved
+   * for the scheme in force. See `CanvasPalette`. */
+  palette: CanvasPalette;
 }
 
-const FALLBACK: GraphTheme = {
-  background: "#0c0e12",
-  surfaceOverlay: "#1e2128",
-  node: "#8a8691",
-  nodeSelected: "#e09f3e",
-  edge: "#2a2d35",
-  edgeHighlight: "#5bb5a2",
-  label: "#e8e4df",
-  labelMuted: "#8a8691",
-};
+export interface EntityColors {
+  person: string;
+  company: string;
+  project: string;
+  focus: string;
+  other: string;
+}
 
 /**
- * Resolve the Tailwind theme tokens into concrete colors for the canvas —
- * WebGL cannot read CSS custom properties itself. Read once per mount; the
- * app is dark-only, so tokens do not change at runtime.
+ * Resolve the kit's tokens into concrete colours for the canvas — WebGL and
+ * `fillStyle` cannot read a CSS custom property, and since the kit's light
+ * theme every token is a `light-dark()` pair that `getComputedStyle` returns
+ * verbatim, so each is split on the scheme the page is drawing in.
+ *
+ * Re-resolves when the theme preference or, under `system`, the OS scheme
+ * changes; the canvas re-applies it in place (`graph-canvas.tsx`).
  */
 export function useGraphTheme(): GraphTheme {
-  return useMemo(() => {
-    if (typeof window === "undefined") return FALLBACK;
-    const style = getComputedStyle(document.documentElement);
-    const token = (name: string, fallback: string) => {
-      const value = style.getPropertyValue(name).trim();
-      return value || fallback;
-    };
-    return {
-      background: token("--color-background", FALLBACK.background),
-      surfaceOverlay: token("--color-surface-overlay", FALLBACK.surfaceOverlay),
-      node: token("--color-muted-foreground", FALLBACK.node),
-      nodeSelected: token("--color-primary", FALLBACK.nodeSelected),
-      edge: token("--color-border", FALLBACK.edge),
-      edgeHighlight: token("--color-accent", FALLBACK.edgeHighlight),
-      label: token("--color-foreground", FALLBACK.label),
-      labelMuted: token("--color-muted-foreground", FALLBACK.labelMuted),
-    };
-  }, []);
+  const scheme = useColorScheme();
+  return useMemo(() => graphTheme(scheme), [scheme]);
+}
+
+/** The theme for one scheme, from the tokens. Exported for tests. */
+export function graphTheme(scheme: ColorScheme): GraphTheme {
+  const token = (name: TokenName) => readToken(name, scheme);
+  return {
+    background: token("color-canvas"),
+    surfaceOverlay: token("color-raised"),
+    node: token("color-ink-mute"),
+    nodeSelected: token("canvas-root"),
+    edge: token("color-edge"),
+    edgeHighlight: token("color-teal"),
+    label: token("color-ink"),
+    labelMuted: token("color-ink-mute"),
+    entity: {
+      person: token("teal-mark"),
+      company: token("blue-mark"),
+      project: token("purple-mark"),
+      focus: token("canvas-root"),
+      other: token("canvas-other"),
+    },
+    palette: {
+      slots: [1, 2, 3, 4, 5, 6, 7, 8].map((n) => token(`canvas-slot-${n}` as TokenName)),
+      ramp: [1, 2, 3, 4, 5].map((n) => token(`canvas-ramp-${n}` as TokenName)),
+      root: token("canvas-root"),
+      other: token("canvas-other"),
+      lens: {
+        orphan: token("canvas-lens-orphan"),
+        unreachable: token("canvas-lens-unreachable"),
+        broken: token("canvas-lens-broken"),
+        stale: token("canvas-lens-stale"),
+      },
+    },
+  };
 }

package/src/components/graph/use-node-actions.ts

@@ -0,0 +1,56 @@
+import type { GraphNodePayload } from "@schlessera/brain-ui-sdk/protocol";
+import { useFileStore } from "../../stores/file-store.js";
+import { useUIStore } from "../../stores/ui-store.js";
+import { useGraphStore } from "../../stores/graph-store.js";
+
+/**
+ * The "which actions apply to the selected node" rules, shared by the
+ * floating `NodePopover` (below `laptop:`) and the D6 right rail (from
+ * `wide:`). Both draw the same node; only the surface differs, so the rules
+ * live once.
+ *
+ * - Open note hands over to the file viewer panel — the same hand-off the
+ *   search modal uses. Never for a virtual root (no file behind it).
+ * - Focus here re-centres the Local view on the node, switching mode when
+ *   needed; pointless on the node that already is the centre.
+ * - Expand pulls the node's depth-1 ego into the scene — Local only, and
+ *   not for the centre (its ego is the scene).
+ */
+export function useNodeActions(node: GraphNodePayload) {
+  const openFile = useFileStore((s) => s.openFile);
+  const setFilePanelOpen = useUIStore((s) => s.setFilePanelOpen);
+  const mode = useGraphStore((s) => s.mode);
+  const select = useGraphStore((s) => s.select);
+  const setMode = useGraphStore((s) => s.setMode);
+  const setLocalParams = useGraphStore((s) => s.setLocalParams);
+  const expandNode = useGraphStore((s) => s.expandNode);
+
+  const isVirtual = node.virtual === true;
+
+  return {
+    canOpen: !isVirtual,
+    canFocus: !isVirtual && (mode !== "local" || node.distance !== 0),
+    canExpand: mode === "local" && !isVirtual && node.distance !== 0,
+    open() {
+      setFilePanelOpen(true);
+      void openFile(node.path);
+    },
+    focus() {
+      if (mode !== "local") setMode("local");
+      setLocalParams({ center: node.path });
+      select(null);
+    },
+    expand() {
+      void expandNode(node.path);
+    },
+    close() {
+      select(null);
+    },
+  };
+}
+
+/** `${n} hop`/`${n} hops`, or null at the centre (0) and where unknown. */
+export function hopsLabel(distance: number | undefined): string | null {
+  if (distance === undefined || distance <= 0) return null;
+  return `${distance} hop${distance === 1 ? "" : "s"}`;
+}

package/src/components/images/image-share.ts

@@ -1,3 +1,4 @@
+import type { BrainUiRoot } from "../../root.js";
 import { fetchAsFile, shareFile } from "../../lib/share.js";
 import {
   SHARE_OPTIMIZED,
@@ -20,12 +21,13 @@ import type { ShareOption } from "../share/share-menu.js";
  *   falls back to the original rather than being recompressed for show.
  */
 export function buildImageShareOptions(
+  root: BrainUiRoot,
   url: string,
   filename: string,
   opts: { mime?: string; bytes?: number } = {}
 ): ShareOption[] {
   const shareOriginal = async (): Promise<boolean> => {
-    const file = await fetchAsFile(url, filename, opts.mime);
+    const file = await fetchAsFile(root, url, filename, opts.mime);
     return shareFile(file, { title: filename });
   };
 
@@ -41,7 +43,7 @@ export function buildImageShareOptions(
       label: "Share optimized",
       hint: `JPEG, up to ${SHARE_OPTIMIZED.maxEdge}px · under ${formatBytes(SHARE_OPTIMIZED.maxBytes)}`,
       run: async () => {
-        const original = await fetchAsFile(url, filename, opts.mime);
+        const original = await fetchAsFile(root, url, filename, opts.mime);
         const result = await optimizeImage(original, SHARE_OPTIMIZED);
         // null means "nothing to gain" (already small enough) or "could not be
         // decoded". Either way the original is the right thing to send, and

package/src/components/images/image-viewer.tsx

@@ -1,3 +1,4 @@
+import { useBrainUiRoot } from "../../root-context.js";
 import { useState } from "react";
 import { ShareMenu } from "../share/share-menu.js";
 import { ZoomViewer } from "../viewer/zoom-viewer.js";
@@ -26,6 +27,7 @@ export function ImageViewer({
   bytes?: number;
   onClose: () => void;
 }) {
+  const root = useBrainUiRoot();
   // The natural size is unknown until the decode finishes, and `fit()` measures
   // the DOM — so the load event is what tells the viewer to fit.
   const [loaded, setLoaded] = useState(false);
@@ -38,7 +40,7 @@ export function ImageViewer({
       label={`Image viewer: ${filename}`}
       actions={
         <ShareMenu
-          options={buildImageShareOptions(src, filename, { mime, bytes })}
+          options={buildImageShareOptions(root, src, filename, { mime, bytes })}
           title="Share image"
         />
       }

package/src/components/images/mask-editor.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Eraser, RotateCcw, X } from "lucide-react";
 
-import { apiBase } from "../../lib/backend.js";
+import { useBrainUiRoot } from "../../root-context.js";
 import { useMaskStore } from "../../stores/mask-store.js";
 
 /**
@@ -31,6 +31,7 @@ export function MaskEditor({
   onSubmit: (requestId: string, maskPngBase64: string) => void;
   onCancel: (requestId: string, message: string) => void;
 }) {
+  const root = useBrainUiRoot();
   const request = useMaskStore((s) => s.request);
   const close = useMaskStore((s) => s.close);
 
@@ -43,16 +44,17 @@ export function MaskEditor({
   const [error, setError] = useState<string | null>(null);
 
   const rawUrl = request
-    ? `${apiBase()}/files/content?path=${encodeURIComponent(request.imagePath)}&raw=1`
+    ? `${root.apiBase()}/files/content?path=${encodeURIComponent(request.imagePath)}&raw=1`
     : null;
 
   // Reset per request: a second mask on a different image must not inherit the
   // first one's strokes.
   useEffect(() => {
     setStrokes([]);
+    setDrawing(false);
     setLoaded(false);
     setError(null);
-  }, [request?.requestId]);
+  }, [root, request?.requestId, rawUrl]);
 
   const redraw = useCallback(() => {
     const canvas = canvasRef.current;
@@ -165,6 +167,7 @@ export function MaskEditor({
       <div className="flex min-h-0 flex-1 items-center justify-center p-3">
         {rawUrl && (
           <img
+            key={rawUrl}
             ref={imageRef}
             src={rawUrl}
             alt=""
@@ -207,7 +210,7 @@ export function MaskEditor({
         />
       </div>
 
-      {error && <div className="px-3 pb-1 text-center text-sm text-red-300">{error}</div>}
+      {error && <div className="px-3 pb-1 text-center text-sm text-destructive-fill">{error}</div>}
 
       <div className="flex items-center gap-3 p-3">
         <label className="flex flex-1 items-center gap-2 text-xs text-white/80">

package/src/components/layout/app-shell.tsx

@@ -1,11 +1,15 @@
 import type { ReactNode } from "react";
 import { SideRail } from "./side-rail.js";
 import { MobileTabBar } from "./mobile-tab-bar.js";
+import { DesktopPalette } from "./desktop-palette.js";
 import { useChatStore, activeChat } from "../../stores/chat-store.js";
 import { cn } from "../../lib/utils.js";
+import { OneTimeAgentCredentialDialog } from "../settings/one-time-agent-credential.js";
+import { useApplyTheme } from "./theme.js";
 
 export function AppShell({ children }: { children: ReactNode }) {
   const isStreaming = useChatStore((s) => activeChat(s).isStreaming);
+  useApplyTheme();
 
   return (
     <div className="flex h-[100dvh] bg-background text-foreground">
@@ -15,11 +19,13 @@ export function AppShell({ children }: { children: ReactNode }) {
         <div
           className={cn("filament", isStreaming && "filament--active")}
         />
-        <main className="flex flex-1 flex-col overflow-hidden pb-16 md:pb-0">
+        <main className="flex flex-1 flex-col overflow-hidden pb-16 tablet:pb-0">
           {children}
         </main>
       </div>
       <MobileTabBar />
+      <DesktopPalette />
+      <OneTimeAgentCredentialDialog />
     </div>
   );
 }

package/src/components/layout/desktop-palette.tsx

@@ -0,0 +1,151 @@
+import { CommandPalette, type PaletteGroup, type PaletteItem } from "@schlessera/brain-ui-kit";
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from "react";
+import { useUIStore } from "../../stores/ui-store.js";
+import { useChatStore, activeChat } from "../../stores/chat-store.js";
+import { useConnectionStore } from "../../stores/connection-store.js";
+import { useChatCommands } from "../chat/use-chat-commands.js";
+
+/**
+ * The ⌘K palette, on the kit's `CommandPalette` (D22: "SideRail + ⌘K
+ * palette" is the desktop's navigation). The kit draws the box, the real
+ * query input, the groups, the selected row and its key, and owns ↑↓,
+ * Home/End, ⏎ and esc on the rows; this file owns opening it, the query,
+ * and what the rows do.
+ *
+ * Groups are what ⏎ DOES (D37), not the app's feature areas. **Jump to**:
+ * the five destinations with their ⌘ keys printed, New chat and Sessions —
+ * they move you. **Ask**: Search the brain and Brain statistics — they
+ * answer something. **Run**: Sync (`effect: sync`, it writes the
+ * repository), the Daily briefing (a cost chip: spending is an effect even
+ * when nothing is written) and Add a note (bare — opening a form is not an
+ * effect; its submit carries the write). A command the host cannot serve
+ * right now is shown DISABLED with its reason, never omitted: dropping rows
+ * while the socket is down would teach that the palette's contents are a
+ * guess.
+ *
+ * The app has no cost estimate for the briefing, so its chip says `spends`
+ * rather than an invented figure — the design's `~$0.12` is an example.
+ */
+export function DesktopPalette() {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [selected, setSelected] = useState(0);
+  const boxRef = useRef<HTMLDivElement>(null);
+
+  const setActiveView = useUIStore((s) => s.setActiveView);
+  const toggleFilePanel = useUIStore((s) => s.toggleFilePanel);
+  const toggleSettingsPanel = useUIStore((s) => s.toggleSettingsPanel);
+  const setSessionPanelOpen = useUIStore((s) => s.setSessionPanelOpen);
+  const clearMessages = useChatStore((s) => s.clearMessages);
+  const isStreaming = useChatStore((s) => activeChat(s).isStreaming);
+  const connected = useConnectionStore((s) => s.wsStatus === "connected");
+  const runCommand = useChatCommands();
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    function onKey(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey && e.key.toLowerCase() === "k") {
+        e.preventDefault();
+        setOpen((v) => !v);
+      }
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  function close() {
+    setOpen(false);
+    setQuery("");
+    setSelected(0);
+  }
+  function run(fn: () => void) {
+    return () => {
+      close();
+      fn();
+    };
+  }
+  function inChat(fn: () => void) {
+    return run(() => {
+      setActiveView("chat");
+      fn();
+    });
+  }
+
+  // The reason a row cannot run right now, printed in the row rather than
+  // hiding it. Sync, the briefing and stats talk to the agent over the socket
+  // and need a quiet turn; search and add go over REST and always work.
+  const why = !connected ? "needs the host" : isStreaming ? "a turn is running" : undefined;
+  const jumpTo: PaletteItem[] = [
+    { icon: "brain", label: "Chat", tone: "amber", shortcut: "⌘1", onClick: run(() => setActiveView("chat")) },
+    { icon: "resolved", label: "Actions", tone: "amber", shortcut: "⌘2", onClick: run(() => setActiveView("activity")) },
+    { icon: "files", label: "Files", tone: "teal", shortcut: "⌘3", onClick: run(toggleFilePanel) },
+    { icon: "graph", label: "Graph", tone: "purple", shortcut: "⌘4", onClick: run(() => setActiveView("graph")) },
+    { icon: "settings", label: "Settings", tone: "neutral", shortcut: "⌘5", onClick: run(toggleSettingsPanel) },
+    { icon: "compose", label: "New chat", tone: "amber", onClick: inChat(clearMessages) },
+    { icon: "history", label: "Sessions", tone: "blue", onClick: inChat(() => setSessionPanelOpen(true)) },
+  ];
+  const ask: PaletteItem[] = [
+    { icon: "search", label: "Search the brain", tone: "teal", onClick: inChat(() => runCommand("search")) },
+    { icon: "ledger", label: "Brain statistics", tone: "neutral", why, onClick: inChat(() => runCommand("stats")) },
+  ];
+  const runGroup: PaletteItem[] = [
+    { icon: "repeat", label: "Sync the brain", tone: "amber", effect: "sync", why, onClick: inChat(() => runCommand("sync")) },
+    { icon: "sunrise", label: "Daily briefing", tone: "gold", cost: "spends", why, onClick: inChat(() => runCommand("whatsup")) },
+    { icon: "add", label: "Add a note", tone: "teal", onClick: inChat(() => runCommand("add")) },
+  ];
+  const q = query.trim().toLowerCase();
+  const groups: PaletteGroup[] = [
+    { label: "Jump to", items: jumpTo },
+    { label: "Ask", items: ask },
+    { label: "Run", items: runGroup },
+  ]
+    .map((g) => ({ ...g, items: q ? g.items.filter((it) => it.label.toLowerCase().includes(q)) : g.items }))
+    .filter((g) => g.items.length > 0);
+  const count = groups.reduce((n, g) => n + g.items.length, 0);
+
+  // The query input takes focus when the palette opens; ↓ from it lands on
+  // the selected row, where the kit's own keys take over.
+  useEffect(() => {
+    if (!open) return;
+    boxRef.current?.querySelector<HTMLInputElement>("input")?.focus();
+  }, [open]);
+
+  if (!open) return null;
+
+  function onKeyDown(e: ReactKeyboardEvent) {
+    const target = e.target as HTMLElement;
+    if (target.tagName !== "INPUT") return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      boxRef.current?.querySelector<HTMLElement>('[role="option"][tabindex="0"]')?.focus();
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      boxRef.current?.querySelector<HTMLElement>('[role="option"][tabindex="0"]')?.click();
+    }
+  }
+
+  return (
+    <div
+      className="fixed inset-0 z-50 hidden tablet:block bg-black/60"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) close();
+      }}
+    >
+      <div ref={boxRef} className="mx-auto mt-[110px] w-[560px] max-w-[calc(100vw-2rem)]" onKeyDown={onKeyDown}>
+        <CommandPalette
+          query={query}
+          onQueryChange={(value) => {
+            setQuery(value);
+            setSelected(0);
+          }}
+          groups={groups}
+          selected={Math.min(selected, Math.max(0, count - 1))}
+          footHint="↑↓ move · ⏎ run · esc close"
+          footMeta={count === 1 ? "1 command" : `${count} commands`}
+          onSelect={setSelected}
+          onClose={close}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/layout/key-cap.tsx

@@ -0,0 +1,15 @@
+/**
+ * The printed key on the button it belongs to — "every shortcut is printed
+ * where it applies, never hidden in help" (D36). Decorative to assistive
+ * tech: the key is a sighted shortcut, the button's name is the action.
+ */
+export function KeyCap({ children }: { children: string }) {
+  return (
+    <span
+      aria-hidden="true"
+      className="ml-0.5 rounded border border-current/30 px-1 font-[family-name:var(--font-mono)] text-[9.5px] leading-[1.4] opacity-70"
+    >
+      {children}
+    </span>
+  );
+}