@agimon-ai/doompi-web 0.0.1-alpha.0

package/src/web/lib/sessionSummary.ts

@@ -0,0 +1,58 @@
+import type { SessionPhase } from '../../types/hub.ts';
+
+/** The rail's view of one session's attach state; offline means the page lost the hub. */
+export type AttachPhase = 'offline' | 'connecting' | 'attached' | 'refused' | 'detached' | 'closed';
+
+export interface StatusLineInput {
+  attach: AttachPhase;
+  phase: SessionPhase;
+  /** ISO 8601 timestamp of the last phase change. */
+  phaseSince: string;
+  awaitingInput: boolean;
+  everPrompted: boolean;
+  /** Set once any run finished; a settled session is not "fresh" even unprompted. */
+  lastSettledAt?: string;
+}
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+
+export function formatRunDuration(elapsedMs: number): string {
+  if (elapsedMs < MINUTE_MS) return '<1m';
+  if (elapsedMs < HOUR_MS) return `${Math.floor(elapsedMs / MINUTE_MS)}m`;
+  const hours = Math.floor(elapsedMs / HOUR_MS);
+  const minutes = Math.floor((elapsedMs % HOUR_MS) / MINUTE_MS);
+  return `${hours}h ${String(minutes).padStart(2, '0')}m`;
+}
+
+/**
+ * The one mapping from session facts to the rail's status copy.
+ *
+ * Priority order: a refusal outranks everything because nothing else the card
+ * says can be trusted while another client holds the session; a question to
+ * the user outranks "running" because the run is blocked on them.
+ */
+export function sessionStatusLine(input: StatusLineInput, now: number): string {
+  if (input.attach === 'refused') return 'another cockpit holds this session';
+  if (input.awaitingInput) return 'waiting for your input';
+  if (input.phase !== 'idle') {
+    const since = Date.parse(input.phaseSince);
+    return `running · ${formatRunDuration(Number.isFinite(since) ? Math.max(0, now - since) : 0)}`;
+  }
+  if (!input.everPrompted && input.lastSettledAt === undefined) return 'fresh session · nothing sent yet';
+  return 'done · waiting for you';
+}
+
+/** Sessions counted as running by the rail header and the top bar chip. */
+export function runningCount(phases: Iterable<SessionPhase>): number {
+  let count = 0;
+  for (const phase of phases) if (phase !== 'idle') count += 1;
+  return count;
+}
+
+/** Shortens a home-rooted cwd the way a shell prompt would. */
+export function abbreviateCwd(cwd: string): string {
+  const match = /^\/(?:Users|home)\/[^/]+/u.exec(cwd);
+  if (!match) return cwd;
+  return `~${cwd.slice(match[0].length)}`;
+}

package/src/web/lib/settingsSections.ts

@@ -0,0 +1,21 @@
+/**
+ * The settings menu, as data: the rail's gear and the settings page both
+ * need to name a section, and neither feature may import the other.
+ */
+export interface SettingsSection {
+  id: string;
+  label: string;
+  detail: string;
+}
+
+export const SETTINGS_SECTIONS: readonly SettingsSection[] = [
+  { id: 'providers', label: 'providers', detail: 'sign in to the model providers Pi can use' },
+  { id: 'appearance', label: 'appearance', detail: 'pick the theme the cockpit renders with' },
+  { id: 'plugins', label: 'plugins', detail: 'the web plugins this bundle carries and what their install resolved' },
+];
+
+export const DEFAULT_SETTINGS_SECTION = SETTINGS_SECTIONS[0].id;
+
+export function settingsSection(id: string | undefined): SettingsSection | undefined {
+  return SETTINGS_SECTIONS.find((section) => section.id === id);
+}

package/src/web/lib/statusLine.ts

@@ -0,0 +1,90 @@
+export interface Selection {
+  /** Empty when the session runs without a profile, which is a valid choice. */
+  profile: string;
+  majorMode: string;
+  domains: string[];
+  /** True while a mode switch is journaled but not yet applied. */
+  pending: boolean;
+}
+
+export const emptySelection: Selection = { profile: '', majorMode: '', domains: [], pending: false };
+
+interface Segment {
+  text: string;
+  rgb: [number, number, number] | null;
+}
+
+// The escape is the point of this parser, so the control character is
+// deliberate; spelled as a Unicode escape to keep it readable.
+// oxlint-disable-next-line no-control-regex
+const SGR = /\u001B\[([0-9;]*)m/gu;
+
+/** Splits an ANSI string into runs of text carrying the truecolor in force. */
+export function ansiSegments(input: string): Segment[] {
+  const segments: Segment[] = [];
+  let current: [number, number, number] | null = null;
+  let index = 0;
+
+  SGR.lastIndex = 0;
+  for (let match = SGR.exec(input); match !== null; match = SGR.exec(input)) {
+    const text = input.slice(index, match.index);
+    if (text) segments.push({ text, rgb: current });
+    const codes = match[1].split(';').map((code) => Number.parseInt(code, 10));
+    if (codes[0] === 38 && codes[1] === 2) current = [codes[2], codes[3], codes[4]];
+    else if (codes[0] === 39 || codes[0] === 0 || Number.isNaN(codes[0])) current = null;
+    index = match.index + match[0].length;
+  }
+  const tail = input.slice(index);
+  if (tail) segments.push({ text: tail, rgb: current });
+  return segments;
+}
+
+export function stripAnsi(input: string): string {
+  return input.replace(SGR, '');
+}
+
+// The values doom-pi-dark.json binds to `warning` and `accent`. DoomPi ships one
+// theme, so comparing against both and taking the nearer one reports pending
+// accurately, and falls back to "not pending" when it cannot tell.
+const WARNING: [number, number, number] = [236, 190, 123];
+const ACCENT: [number, number, number] = [81, 175, 239];
+
+function distance(a: [number, number, number], b: [number, number, number]): number {
+  return (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+}
+
+/**
+ * Reads DoomPi's footer status line.
+ *
+ * The line is the only place the session publishes its selection, so this
+ * parses the shape `*profile*:[major-mode]:domains` structurally and uses the
+ * colour of the mode segment solely to tell a pending switch from a settled one.
+ */
+export function parseSelection(statusText: string): Selection {
+  const segments = ansiSegments(statusText);
+  const plain = stripAnsi(statusText).trim();
+  if (!plain) return emptySelection;
+
+  const profileMatch = /\*([^*]+)\*/u.exec(plain);
+  const modeMatch = /\[([^\]]+)\]/u.exec(plain);
+
+  const afterMode = modeMatch ? plain.slice(plain.indexOf(modeMatch[0]) + modeMatch[0].length) : '';
+  const domains = afterMode
+    .replace(/^:/u, '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  const modeSegment = segments.find((segment) => segment.text.includes('['));
+  const pending =
+    modeSegment?.rgb !== undefined && modeSegment?.rgb !== null
+      ? distance(modeSegment.rgb, WARNING) < distance(modeSegment.rgb, ACCENT)
+      : false;
+
+  return {
+    profile: profileMatch ? profileMatch[1] : '',
+    majorMode: modeMatch ? modeMatch[1] : '',
+    domains,
+    pending,
+  };
+}

package/src/web/lib/threadRenderer.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+
+type ThreadRenderer = (sessionId: string, threadId: string) => ReactNode;
+
+let render: ThreadRenderer | undefined;
+
+/**
+ * Holds the host's thread view for the plugin props to render.
+ *
+ * The view is a feature built on the timeline, while the props are assembled
+ * below it; the composition root binds the one to the other, the same
+ * indirection the transport uses for the socket.
+ */
+export function bindThreadRenderer(renderer: ThreadRenderer): void {
+  render = renderer;
+}
+
+export function releaseThreadRenderer(): void {
+  render = undefined;
+}
+
+/** The bound view, or nothing while none is bound (before the app mounts, and in unit tests). */
+export function renderThread(sessionId: string, threadId: string): ReactNode {
+  return render?.(sessionId, threadId) ?? null;
+}

package/src/web/lib/toolMessageProps.ts

@@ -0,0 +1,21 @@
+import type { ToolMessageRenderProps, WebPluginSlotProps } from '@agimon-ai/doompi-web-contracts';
+import type { ToolEntry } from './sessionModel.ts';
+
+/** The props a tool's message renderer receives: the slot actions plus the call and its newest result. */
+export function toolMessageProps(
+  slotProps: WebPluginSlotProps,
+  entry: ToolEntry,
+  statuses: Readonly<Record<string, string>>,
+): ToolMessageRenderProps {
+  return {
+    ...slotProps,
+    toolCallId: entry.toolCallId,
+    toolName: entry.name,
+    args: entry.args,
+    statuses,
+    result: entry.result,
+    output: entry.output,
+    running: entry.running,
+    isError: entry.isError,
+  };
+}

package/src/web/lib/transport.ts

@@ -0,0 +1,30 @@
+import { sessionCommand } from '../../types/hub.ts';
+
+type Frame = Record<string, unknown>;
+
+let send: ((frame: object) => void) | undefined;
+
+/**
+ * Holds the live socket sender.
+ *
+ * The socket is owned by the composition root but commands are issued from
+ * feature code, and this keeps that one indirection explicit instead of
+ * threading a sender through every component.
+ */
+export function bindTransport(sender: (frame: object) => void): void {
+  send = sender;
+}
+
+export function releaseTransport(): void {
+  send = undefined;
+}
+
+/** Sends one command frame to a session's agent, enveloped for the hub. */
+export function sendFrame(sessionId: string, frame: Frame): void {
+  send?.(sessionCommand(sessionId, frame));
+}
+
+/** Sends one hub-level frame (subscribe, unsubscribe) as-is. */
+export function sendHubFrame(frame: object): void {
+  send?.(frame);
+}

package/src/web/lib/wsClient.ts

@@ -0,0 +1,73 @@
+type Frame = Record<string, unknown>;
+
+export interface SessionSocket {
+  send(frame: object): void;
+  close(): void;
+}
+
+export interface SessionSocketHandlers {
+  onFrame(frame: Frame): void;
+  onOpen(): void;
+  onClose(): void;
+}
+
+const RECONNECT_MS = 700;
+
+export function sessionSocketUrl(location: { protocol: string; host: string }): string {
+  const scheme = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${scheme}//${location.host}/api/session`;
+}
+
+/**
+ * Keeps a WebSocket to the bridge open for the life of the page.
+ *
+ * Reconnecting is unconditional because the bridge, not the browser, decides
+ * whether the session is still there; the page's job is to keep offering.
+ */
+export function createSessionSocket(url: string, handlers: SessionSocketHandlers): SessionSocket {
+  let socket: WebSocket | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+
+  const open = (): void => {
+    if (stopped) return;
+    const next = new WebSocket(url);
+    socket = next;
+
+    next.addEventListener('open', () => handlers.onOpen());
+
+    next.addEventListener('message', (event: MessageEvent<string>) => {
+      if (typeof event.data !== 'string') return;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        handlers.onFrame(parsed as Frame);
+      }
+    });
+
+    next.addEventListener('close', () => {
+      handlers.onClose();
+      if (stopped) return;
+      timer = setTimeout(open, RECONNECT_MS);
+    });
+
+    next.addEventListener('error', () => next.close());
+  };
+
+  open();
+
+  return {
+    send(frame) {
+      if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify(frame));
+    },
+    close() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      socket?.close();
+    },
+  };
+}

package/src/web/main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { Providers } from './app/Providers.tsx';
+import { applyStoredTheme } from './stores/themeStore.ts';
+import './styles/app.css';
+
+const container = document.getElementById('root');
+if (!container) throw new Error('The cockpit needs a #root element.');
+
+// Before the first paint, so the remembered theme never flashes the default.
+applyStoredTheme();
+
+createRoot(container).render(
+  <StrictMode>
+    <Providers />
+  </StrictMode>,
+);

package/src/web/public/favicon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="DoomPi">
+  <rect width="32" height="32" rx="7" fill="#1c1f24"/>
+  <g fill="#ecbe7b">
+    <path d="M7.0 10.0 Q6.2 4.2 9.3 3.0 Q10.4 6.3 12.1 9.6 Z"/>
+    <path d="M25.0 10.0 Q25.8 4.2 22.7 3.0 Q21.6 6.3 19.9 9.6 Z"/>
+  </g>
+  <g fill="#c678dd">
+    <rect x="3.2" y="8.6" width="25.6" height="7.6" rx="3.4"/>
+    <rect x="6.9" y="14.0" width="5.5" height="13.0" rx="2.5"/>
+    <rect x="19.6" y="14.0" width="5.5" height="13.0" rx="2.5"/>
+  </g>
+  <g fill="#1c1f24">
+    <circle cx="10.9" cy="12.3" r="1.9"/>
+    <circle cx="21.1" cy="12.3" r="1.9"/>
+  </g>
+</svg>

package/src/web/routes/CockpitPage.tsx

@@ -0,0 +1,98 @@
+import { Button } from '@agimon-ai/doompi-web-components';
+import { useStore } from '@tanstack/react-store';
+import { useNavigate, useParams } from '@tanstack/react-router';
+import { useEffect } from 'react';
+import { PluginSurface } from '../components/PluginSurface.tsx';
+import { usePluginSlotProps } from '../stores/usePluginSlotProps.ts';
+import { ActivityDock } from '../features/activity/ActivityDock.tsx';
+import { RefusedCard } from '../features/connection/RefusedCard.tsx';
+import { DialogOverlay } from '../features/dialogs/DialogOverlay.tsx';
+import { CommandPalette } from '../features/leader/CommandPalette.tsx';
+import { SelectionBar } from '../features/selection/SelectionBar.tsx';
+import { Composer } from '../features/session/Composer.tsx';
+import { SessionRail } from '../features/sessions/SessionRail.tsx';
+import { Timeline } from '../features/session/Timeline.tsx';
+import { TopBar } from '../features/status/TopBar.tsx';
+import { HOST_SLOTS, webTabs } from '../lib/pluginRegistry.ts';
+import { sessionsStore, setActiveSession } from '../stores/sessionsStore.ts';
+import { findTransientTab, transientTabsStore } from '../stores/transientTabsStore.ts';
+import { setDockOpen, uiStore } from '../stores/uiStore.ts';
+
+export function CockpitPage() {
+  const dockOpen = useStore(uiStore, (state) => state.dockOpen);
+  const { sessionId, tabId } = useParams({ strict: false });
+  const navigate = useNavigate();
+  const slotProps = usePluginSlotProps(sessionId ?? null);
+  const order = useStore(sessionsStore, (state) => state.order);
+  const hydrated = useStore(sessionsStore, (state) => state.hydrated);
+  // A declared tab first, then one a plugin opened at runtime for this session.
+  const transientTab = useStore(transientTabsStore, (state) => findTransientTab(state, sessionId, tabId));
+  const tab = (tabId === undefined ? undefined : webTabs().find((entry) => entry.id === tabId)) ?? transientTab;
+
+  // The route is the source of focus; the store follows it.
+  useEffect(() => {
+    setActiveSession(sessionId ?? null);
+  }, [sessionId]);
+
+  // Landing on / focuses the first session; a focused session that
+  // disappeared falls back the same way, and an unknown tab id falls back to
+  // the conversation. Before hydration the URL is left alone so a deep link
+  // survives the socket connecting.
+  useEffect(() => {
+    if (!hydrated) return;
+    if (sessionId !== undefined && order.includes(sessionId)) {
+      if (tabId !== undefined && tab === undefined) {
+        void navigate({ to: '/session/$sessionId', params: { sessionId }, replace: true });
+      }
+      return;
+    }
+    const first = order[0];
+    if (first !== undefined) {
+      void navigate({ to: '/session/$sessionId', params: { sessionId: first }, replace: true });
+    } else if (sessionId !== undefined) {
+      void navigate({ to: '/', replace: true });
+    }
+  }, [hydrated, sessionId, tabId, tab, order, navigate]);
+
+  return (
+    <div data-testid="cockpit" className="relative flex h-full overflow-hidden">
+      <aside className="flex w-[300px] shrink-0 flex-col overflow-y-auto border-r border-doom-border bg-doom-rail">
+        <SessionRail />
+      </aside>
+      <main className="flex min-w-0 flex-1 flex-col">
+        <TopBar view={tab?.id ?? 'conversation'} />
+        {/* The composer and the selection bar address the session's agent, so
+            they belong to the conversation alone. A plugin panel is a view of
+            something else, and a prompt box under it would send somewhere the
+            reader is not looking. */}
+        {tab ? (
+          <tab.panel {...slotProps} />
+        ) : (
+          <>
+            <Timeline />
+            <Composer />
+            <SelectionBar />
+          </>
+        )}
+      </main>
+      {dockOpen ? (
+        <ActivityDock onClose={() => setDockOpen(false)} />
+      ) : (
+        <Button
+          variant="ghost"
+          data-testid="activity-show"
+          title="show the activity dock"
+          onClick={() => setDockOpen(true)}
+          className="h-auto shrink-0 rounded-none border-l border-doom-border bg-doom-rail px-2 py-3 text-[9px] tracking-widest text-doom-dim hover:bg-doom-rail"
+          style={{ writingMode: 'vertical-rl' }}
+        >
+          ACTIVITY
+        </Button>
+      )}
+      <DialogOverlay />
+      <RefusedCard />
+      <CommandPalette />
+      <PluginSurface slot={HOST_SLOTS.overlay} sessionId={sessionId ?? null} />
+    </div>
+  );
+}

package/src/web/routes/SettingsPage.tsx

@@ -0,0 +1,60 @@
+import { Button } from '@agimon-ai/doompi-web-components';
+import { Link, useNavigate, useParams } from '@tanstack/react-router';
+import { useStore } from '@tanstack/react-store';
+import { useEffect } from 'react';
+import { SessionRail } from '../features/sessions/SessionRail.tsx';
+import { AppearanceSettings } from '../features/settings/AppearanceSettings.tsx';
+import { PluginSettings } from '../features/settings/PluginSettings.tsx';
+import { ProviderSettings } from '../features/settings/ProviderSettings.tsx';
+import { SettingsMenu } from '../features/settings/SettingsMenu.tsx';
+import { DEFAULT_SETTINGS_SECTION, settingsSection } from '../lib/settingsSections.ts';
+import { sessionsStore } from '../stores/sessionsStore.ts';
+
+/**
+ * The settings pages, in the cockpit's frame: the rail stays so a session is
+ * one click away, and the main column becomes a section menu and its page.
+ * An unknown section falls back to the first one.
+ */
+export function SettingsPage() {
+  const { section } = useParams({ strict: false });
+  const navigate = useNavigate();
+  const activeId = useStore(sessionsStore, (state) => state.activeId);
+  const current = settingsSection(section);
+
+  useEffect(() => {
+    if (current) return;
+    void navigate({ to: '/settings/$section', params: { section: DEFAULT_SETTINGS_SECTION }, replace: true });
+  }, [current, navigate]);
+
+  return (
+    <div data-testid="settings" className="relative flex h-full overflow-hidden">
+      <aside className="flex w-[300px] shrink-0 flex-col overflow-y-auto border-r border-doom-border bg-doom-rail">
+        <SessionRail />
+      </aside>
+      <main className="flex min-w-0 flex-1 flex-col">
+        <header className="flex h-12 shrink-0 items-center justify-between border-b border-doom-border px-5">
+          <span className="text-[13px] font-bold text-doom-hi">settings</span>
+          <Button asChild variant="ghost" size="sm">
+            {activeId !== null ? (
+              <Link to="/session/$sessionId" params={{ sessionId: activeId }} data-testid="settings-close">
+                back to session
+              </Link>
+            ) : (
+              <Link to="/" data-testid="settings-close">
+                back
+              </Link>
+            )}
+          </Button>
+        </header>
+        <div className="flex min-h-0 flex-1">
+          <SettingsMenu active={current?.id} />
+          <section data-testid="settings-content" className="min-w-0 flex-1 overflow-y-auto px-6 py-5">
+            {current?.id === 'providers' ? <ProviderSettings /> : null}
+            {current?.id === 'appearance' ? <AppearanceSettings /> : null}
+            {current?.id === 'plugins' ? <PluginSettings /> : null}
+          </section>
+        </div>
+      </main>
+    </div>
+  );
+}

package/src/web/routes/routeTree.tsx

@@ -0,0 +1,49 @@
+import { createRootRoute, createRoute, Outlet } from '@tanstack/react-router';
+import { CockpitPage } from './CockpitPage.tsx';
+import { SettingsPage } from './SettingsPage.tsx';
+
+const rootRoute = createRootRoute({
+  component: () => <Outlet />,
+});
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: CockpitPage,
+});
+
+const sessionRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/session/$sessionId',
+  component: CockpitPage,
+});
+
+// Every plugin tab lives under one parameterized segment, so the route tree
+// stays static while the tab set comes from the plugin registry.
+const sessionTabRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/session/$sessionId/$tabId',
+  component: CockpitPage,
+});
+
+// Settings keep the same shape: one static segment, one parameter for the
+// section, so adding a page never touches the route tree.
+const settingsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/settings',
+  component: SettingsPage,
+});
+
+const settingsSectionRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/settings/$section',
+  component: SettingsPage,
+});
+
+export const routeTree = rootRoute.addChildren([
+  indexRoute,
+  sessionRoute,
+  sessionTabRoute,
+  settingsRoute,
+  settingsSectionRoute,
+]);

package/src/web/stores/menuStore.ts

@@ -0,0 +1,78 @@
+import { Store } from '@tanstack/store';
+
+/** A selection-bar axis name: the built-in 'mode'/'domains', or a plugin-declared axis such as 'profile'. */
+export type MenuKind = string;
+
+export interface MenuClaim {
+  /** The agent dialog rendered as the bar's popover instead of the modal. */
+  dialogId: string;
+  menu: MenuKind;
+}
+
+export interface MenuState {
+  /** Selection-bar button whose command is in flight, if any. */
+  pending: MenuKind | null;
+  /** When it was clicked; a stale anchor must not restyle an unrelated dialog. */
+  at: number;
+  /** The dialog the last click claimed, so the bar and the overlay agree who renders it. */
+  claimed: MenuClaim | null;
+}
+
+const MENU_FRESH_MS = 10_000;
+
+export const menuStore = new Store<MenuState>({ pending: null, at: 0, claimed: null });
+
+let expiry: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * Remembers which selection-bar button asked the agent a question.
+ *
+ * The agent answers with an ordinary select dialog; this is the only signal
+ * that lets the bar render it as its popover menu rather than a centered
+ * modal. The button shows a pending state until the dialog arrives, the run
+ * settles, or the anchor goes stale.
+ */
+export function setPendingMenu(kind: MenuKind): void {
+  menuStore.setState((state) => ({ ...state, pending: kind, at: Date.now() }));
+  if (expiry !== undefined) clearTimeout(expiry);
+  expiry = setTimeout(clearPendingMenu, MENU_FRESH_MS);
+}
+
+export function clearPendingMenu(): void {
+  if (expiry !== undefined) clearTimeout(expiry);
+  expiry = undefined;
+  menuStore.setState((state) => (state.pending === null ? state : { ...state, pending: null, at: 0 }));
+}
+
+/** The menu behind an arriving dialog, or null when none was asked for recently. */
+export function pendingMenuFor(now: number): MenuKind | null {
+  const { pending, at } = menuStore.state;
+  if (pending === null || now - at > MENU_FRESH_MS) return null;
+  return pending;
+}
+
+/**
+ * Spends the pending anchor on an arriving select dialog. Called once per
+ * dialog, at frame time, so every surface reads the same verdict on its
+ * first render and the modal never flashes before the popover takes over.
+ */
+export function claimDialogMenu(dialogId: string, now = Date.now()): MenuClaim | null {
+  const menu = pendingMenuFor(now);
+  const claimed = menu === null ? null : { dialogId, menu };
+  clearPendingMenu();
+  menuStore.setState((state) => ({ ...state, claimed }));
+  return claimed;
+}
+
+/** Forgets a claim once its dialog is gone. */
+export function releaseDialogMenu(dialogId: string): void {
+  menuStore.setState((state) =>
+    state.claimed !== null && state.claimed.dialogId === dialogId ? { ...state, claimed: null } : state,
+  );
+}
+
+/** Test seam. */
+export function resetMenuStore(): void {
+  clearPendingMenu();
+  menuStore.setState(() => ({ pending: null, at: 0, claimed: null }));
+}