@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/hooks/useAppInputBindings.ts

@@ -0,0 +1,145 @@
+import { useApp, useInput } from 'ink';
+import { useEffect } from 'react';
+
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+import { useScreenReader } from '../screen-reader-context.js';
+import { handleInterrupt } from '../shutdown-signal.js';
+import { useScreenReaderTurnSignals } from './useScreenReaderTurnSignals.js';
+
+import type { IPendingPermissionRequest } from '../types.js';
+import type { IActionRequest, TSessionEndReason } from '@robota-sdk/agent-core';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+interface IOptions {
+  readonly isThinking: boolean;
+  readonly isShuttingDown: boolean;
+  readonly permissionRequest: IPendingPermissionRequest | null;
+  readonly pendingUserAction: IActionRequest | null;
+  readonly pluginVisible: boolean;
+  readonly transportVisible: boolean;
+  readonly sessionPickerVisible: boolean;
+  readonly workspaceSwitcherVisible: boolean;
+  /** SCREEN-1993: the history-search overlay owns Esc and the switcher key while open. */
+  readonly historySearchOpen: boolean;
+  readonly selectedEntry: IExecutionWorkspaceEntry | undefined;
+  readonly backgroundListFocused: boolean;
+  readonly mainThreadEntryId: string | undefined;
+  readonly activeTools: readonly IToolState[];
+  readonly abort: () => void;
+  readonly stopWaitingLoop: () => Promise<void>;
+  readonly toggleWorkspaceSwitcher: () => void;
+  readonly selectWorkspaceEntry: (entryId: string) => void;
+  readonly shutdown: (reason?: TSessionEndReason) => Promise<void>;
+  readonly recoveryError: string | undefined;
+  readonly recoveryPending: boolean;
+  readonly coordinationBlocked: boolean;
+  /** SCREEN-2002: the theme picker owns its keys while it is open, like every sibling overlay. */
+  readonly themePickerVisible: boolean;
+  readonly retryRecovery: () => void;
+}
+
+function overlaysBlockKeys(options: IOptions): boolean {
+  return Boolean(
+    options.permissionRequest ||
+    options.pendingUserAction ||
+    options.pluginVisible ||
+    options.transportVisible ||
+    options.sessionPickerVisible ||
+    options.workspaceSwitcherVisible ||
+    options.historySearchOpen ||
+    options.themePickerVisible ||
+    options.coordinationBlocked,
+  );
+}
+
+function useEscapeBindings(options: IOptions): void {
+  const context = options.isThinking ? 'thinking' : 'background-detail';
+  useKeybindingActions(context, (actions) => {
+    if (overlaysBlockKeys(options)) return;
+    if (actions.includes('abort') && options.isThinking) {
+      options.abort();
+      return;
+    }
+    const selected = options.selectedEntry;
+    if (
+      actions.includes('return-to-main') &&
+      selected &&
+      selected.kind !== 'main_thread' &&
+      options.mainThreadEntryId
+    ) {
+      options.selectWorkspaceEntry(options.mainThreadEntryId);
+      return;
+    }
+    if (actions.includes('return-to-main') && !options.backgroundListFocused) {
+      void options.stopWaitingLoop();
+    }
+  });
+}
+
+function useWorkspaceSwitcherBinding(options: IOptions): void {
+  useKeybindingActions('app', (actions) => {
+    if (!actions.includes('open-workspace-switcher')) return;
+    if (
+      options.permissionRequest ||
+      options.pendingUserAction ||
+      options.pluginVisible ||
+      options.sessionPickerVisible ||
+      options.historySearchOpen ||
+      options.themePickerVisible ||
+      options.coordinationBlocked ||
+      options.isShuttingDown
+    )
+      return;
+    options.toggleWorkspaceSwitcher();
+  });
+}
+
+function useRecoveryBinding(options: IOptions): void {
+  useKeybindingActions('recovery', (actions) => {
+    if (
+      options.recoveryError !== undefined &&
+      !options.recoveryPending &&
+      actions.includes('retry')
+    ) {
+      options.retryRecovery();
+    }
+  });
+}
+
+function useShutdownBindings(options: IOptions): void {
+  const { exit } = useApp();
+  const requestShutdown = (reason: TSessionEndReason): void => {
+    handleInterrupt({
+      isShuttingDown: options.isShuttingDown,
+      graceful: () => void options.shutdown(reason).finally(() => exit()),
+    });
+  };
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') requestShutdown('prompt_input_exit');
+  });
+  useEffect(() => {
+    const onSignal = (): void => requestShutdown('other');
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    return () => {
+      process.off('SIGINT', onSignal);
+      process.off('SIGTERM', onSignal);
+    };
+  });
+}
+
+export function useAppInputBindings(options: IOptions): boolean {
+  useEscapeBindings(options);
+  useRecoveryBinding(options);
+  useWorkspaceSwitcherBinding(options);
+  useShutdownBindings(options);
+  const screenReader = useScreenReader();
+  useScreenReaderTurnSignals({
+    enabled: screenReader,
+    isThinking: options.isThinking,
+    activeTools: options.activeTools,
+    awaitingAnswer: options.permissionRequest !== null || options.pendingUserAction !== null,
+  });
+  return screenReader;
+}

package/src/hooks/useAppInteractionState.ts

@@ -0,0 +1,81 @@
+import { useAppInputBindings } from './useAppInputBindings.js';
+import { useAppOverlays } from './useAppOverlays.js';
+import { useAppSubmissionState } from './useAppSubmissionState.js';
+
+import type { IAppOverlays } from './useAppOverlays.js';
+import type { IAppScreenState } from './useAppScreenState.js';
+import type { IAppSubmissionState } from './useAppSubmissionState.js';
+import type { ITuiChannelState } from './useTuiChannel.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+interface IOptions {
+  readonly cwd: string;
+  readonly state: ITuiChannelState;
+  readonly shell: IAppScreenState;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly pluginAdapter: ICommandPluginAdapter | undefined;
+  readonly transportRegistry: ITransportRegistryView | undefined;
+  readonly recoveryError: string | undefined;
+  readonly recoveryPending: boolean;
+  readonly coordinationBlocked: boolean;
+  readonly retryRecovery: () => void;
+}
+
+export interface IAppInteractionState {
+  readonly submission: IAppSubmissionState;
+  readonly overlays: IAppOverlays;
+  readonly screenReader: boolean;
+}
+
+export function useAppInteractionState(options: IOptions): IAppInteractionState {
+  const { screens, workspace } = options.shell;
+  const submission = useAppSubmissionState({
+    selectedEntry: workspace.background.selectedEntry,
+    submit: screens.handleSubmit,
+    sendAgentJob: options.state.sendAgentJob,
+    isThinking: options.state.isThinking,
+  });
+  const screenReader = useAppInputBindings({
+    isThinking: options.state.isThinking,
+    isShuttingDown: options.state.isShuttingDown,
+    permissionRequest: options.state.permissionRequest,
+    pendingUserAction: options.state.pendingUserAction,
+    pluginVisible: screens.showPluginTUI,
+    transportVisible: screens.showTransportTUI,
+    sessionPickerVisible: screens.showSessionPicker,
+    workspaceSwitcherVisible: workspace.background.switcherVisible,
+    historySearchOpen: options.shell.historySearchOpen,
+    themePickerVisible: screens.showThemePicker,
+    selectedEntry: workspace.background.selectedEntry,
+    backgroundListFocused: workspace.isBackgroundListFocused,
+    mainThreadEntryId: workspace.mainThreadEntryId,
+    activeTools: options.state.activeTools,
+    abort: options.state.handleAbort,
+    stopWaitingLoop: options.state.handleStopWaitingLoop,
+    toggleWorkspaceSwitcher: workspace.toggleSwitcher,
+    selectWorkspaceEntry: options.state.selectExecutionWorkspaceEntry,
+    shutdown: options.state.handleShutdown,
+    recoveryError: options.recoveryError,
+    recoveryPending: options.recoveryPending,
+    coordinationBlocked: options.coordinationBlocked,
+    retryRecovery: options.retryRecovery,
+  });
+  const overlays = useAppOverlays({
+    cwd: options.cwd,
+    pluginAdapter: options.pluginAdapter,
+    pluginVisible: screens.showPluginTUI,
+    setPluginVisible: screens.setShowPluginTUI,
+    transportRegistry: options.transportRegistry,
+    transportVisible: screens.showTransportTUI,
+    setTransportVisible: screens.setShowTransportTUI,
+    sessionStore: options.sessionStore,
+    sessionPickerVisible: screens.showSessionPicker,
+    setSessionPickerVisible: screens.setShowSessionPicker,
+    onSessionSwitch: options.onSessionSwitch,
+    addEntry: options.state.addEntry,
+  });
+  return { submission, overlays, screenReader };
+}

package/src/hooks/useAppLifecycleState.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { useTerminalTitle } from '../use-terminal-title.js';
+import { useTerminalHandoffSuspension } from './useTerminalHandoffSuspension.js';
+
+import type { ITuiAppChannelPort } from '../tui-app-channel-port.js';
+
+export interface IAppLifecycleState {
+  readonly sessionName: string | undefined;
+  readonly setSessionName: (name: string) => void;
+  readonly handoffSuspended: boolean;
+  readonly updateNotice: string | undefined;
+  readonly startError: string | undefined;
+  readonly startPending: boolean;
+  readonly retryStart: () => void;
+}
+
+function useChannelLifecycle(channel: ITuiAppChannelPort): {
+  startError: string | undefined;
+  startPending: boolean;
+  retryStart: () => void;
+} {
+  const [startError, setStartError] = useState<string | undefined>();
+  const [startPending, setStartPending] = useState(true);
+  const retryStart = useCallback((): void => {
+    setStartPending(true);
+    void channel
+      .start()
+      .then(() => setStartError(undefined))
+      .catch((cause) => {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        setStartError(`TUI start failed: ${message}`);
+      })
+      .finally(() => setStartPending(false));
+  }, [channel]);
+  useEffect(() => {
+    retryStart();
+  }, [channel, retryStart]);
+  return { startError, startPending, retryStart };
+}
+
+function useStartupUpdateNotice(source?: Promise<string | undefined>): string | undefined {
+  const [notice, setNotice] = useState<string | undefined>();
+  useEffect(() => {
+    let mounted = true;
+    source
+      ?.then((value) => {
+        if (mounted && value !== undefined) setNotice(value);
+      })
+      .catch(() => {
+        // Startup update checks are best-effort and must not disrupt the TUI.
+      });
+    return () => {
+      mounted = false;
+    };
+  }, [source]);
+  return notice;
+}
+
+export function useAppLifecycleState(
+  channel: ITuiAppChannelPort,
+  startupUpdateNotice?: Promise<string | undefined>,
+): IAppLifecycleState {
+  const channelLifecycle = useChannelLifecycle(channel);
+  const [sessionName, setSessionName] = useState<string | undefined>(channel.sessionName);
+  useEffect(() => {
+    if (channel.sessionName !== undefined && channel.sessionName !== sessionName) {
+      setSessionName(channel.sessionName);
+    }
+  }, [channel, channel.sessionName, sessionName]);
+  useTerminalTitle(sessionName);
+  const handoffSuspended = useTerminalHandoffSuspension(channel.terminalHandoffController);
+  const updateNotice = useStartupUpdateNotice(startupUpdateNotice);
+  return {
+    sessionName,
+    setSessionName,
+    handoffSuspended,
+    updateNotice,
+    ...channelLifecycle,
+  };
+}

package/src/hooks/useAppOverlays.ts

@@ -0,0 +1,74 @@
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import { listResumableSessionSummaries } from '@robota-sdk/agent-framework';
+import { useCallback } from 'react';
+
+import { usePluginCallbacks } from './usePluginCallbacks.js';
+
+import type {
+  IAppPluginViewModel,
+  IAppSessionPickerViewModel,
+  IAppTransportViewModel,
+} from '../app-view-model.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+interface IOptions {
+  readonly cwd: string;
+  readonly pluginAdapter: ICommandPluginAdapter | undefined;
+  readonly pluginVisible: boolean;
+  readonly setPluginVisible: (visible: boolean) => void;
+  readonly transportRegistry: ITransportRegistryView | undefined;
+  readonly transportVisible: boolean;
+  readonly setTransportVisible: (visible: boolean) => void;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly sessionPickerVisible: boolean;
+  readonly setSessionPickerVisible: (visible: boolean) => void;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly addEntry: (entry: IHistoryEntry) => void;
+}
+
+export interface IAppOverlays {
+  readonly plugin: IAppPluginViewModel;
+  readonly transport: IAppTransportViewModel;
+  readonly sessionPicker: IAppSessionPickerViewModel;
+}
+
+export function useAppOverlays(options: IOptions): IAppOverlays {
+  const pluginCallbacks = usePluginCallbacks(options.pluginAdapter);
+  const addPluginMessage = useCallback(
+    (content: string) => options.addEntry(messageToHistoryEntry(createSystemMessage(content))),
+    [options.addEntry],
+  );
+  const selectSession = useCallback(
+    (sessionId: string) => {
+      options.setSessionPickerVisible(false);
+      void options.onSessionSwitch(sessionId);
+    },
+    [options.onSessionSwitch, options.setSessionPickerVisible],
+  );
+  const cancelSessionPicker = useCallback(() => {
+    options.setSessionPickerVisible(false);
+    options.addEntry(messageToHistoryEntry(createSystemMessage('Session resume cancelled.')));
+  }, [options.addEntry, options.setSessionPickerVisible]);
+  return {
+    plugin: {
+      visible: options.pluginVisible,
+      callbacks: pluginCallbacks,
+      close: () => options.setPluginVisible(false),
+      addMessage: addPluginMessage,
+    },
+    transport: {
+      visible: options.transportVisible,
+      registry: options.transportRegistry,
+      close: () => options.setTransportVisible(false),
+    },
+    sessionPicker: {
+      visible: options.sessionPickerVisible,
+      sessions: listResumableSessionSummaries(options.sessionStore, options.cwd),
+      select: selectSession,
+      cancel: cancelSessionPicker,
+    },
+  };
+}

package/src/hooks/useAppScreenState.ts

@@ -0,0 +1,81 @@
+import { useState } from 'react';
+
+import { useAppearanceSettings } from './useAppearanceSettings.js';
+import { useAppWorkspaceState } from './useAppWorkspaceState.js';
+import { useSideEffects } from './useSideEffects.js';
+import { useStatusLineSettings } from './useStatusLineSettings.js';
+
+import type { IUseSideEffectsResult } from './side-effects-types.js';
+import type { IAppWorkspaceState } from './useAppWorkspaceState.js';
+import type { ITuiChannelState } from './useTuiChannel.js';
+import type {
+  IAppearanceSettings,
+  IStatusLineCommandSettings,
+} from '@robota-sdk/agent-interface-command';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+interface IOptions {
+  readonly state: ITuiChannelState;
+  readonly setSessionName: (name: string) => void;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly showSessionPickerOnStart: boolean | undefined;
+  readonly coordinationBlocked: boolean;
+}
+
+export interface IAppScreenState {
+  readonly screens: IUseSideEffectsResult;
+  readonly workspace: IAppWorkspaceState;
+  readonly statusSettings: IStatusLineCommandSettings;
+  /** SCREEN-2002: the persisted appearance, re-read after every slash-command result. */
+  readonly appearance: IAppearanceSettings;
+  /** SCREEN-1993: the input area's history-search overlay is open and owns the keys. */
+  readonly historySearchOpen: boolean;
+  readonly setHistorySearchOpen: (open: boolean) => void;
+}
+
+export function useAppScreenState(options: IOptions): IAppScreenState {
+  const [workspaceSwitcherVisible, setWorkspaceSwitcherVisible] = useState(false);
+  const [historySearchOpen, setHistorySearchOpen] = useState(false);
+  const [statusSettings, refreshStatusSettings] = useStatusLineSettings();
+  const [appearance, refreshAppearance] = useAppearanceSettings();
+  const screens = useSideEffects({
+    uiEventPort: options.state.uiEventPort,
+    baseHandleSubmit: options.state.handleSubmit,
+    setSessionName: options.setSessionName,
+    refreshStatusLineSettings: refreshStatusSettings,
+    refreshAppearanceSettings: refreshAppearance,
+    showSessionPickerOnStart: options.showSessionPickerOnStart,
+    openAgentSwitcher: () => setWorkspaceSwitcherVisible(true),
+  });
+  const navigationEnabled =
+    options.state.permissionRequest === null &&
+    options.state.pendingUserAction === null &&
+    !screens.showPluginTUI &&
+    !screens.showTransportTUI &&
+    !screens.showSessionPicker &&
+    !screens.showThemePicker &&
+    !workspaceSwitcherVisible &&
+    !historySearchOpen &&
+    !options.coordinationBlocked;
+  const workspace = useAppWorkspaceState({
+    snapshot: options.state.executionWorkspaceSnapshot,
+    selectedEntryId: options.state.selectedExecutionEntryId,
+    select: options.state.selectExecutionWorkspaceEntry,
+    read: options.state.readExecutionWorkspaceDetail,
+    sessionStore: options.sessionStore,
+    onSessionSwitch: options.onSessionSwitch,
+    addEntry: options.state.addEntry,
+    navigationEnabled,
+    switcherVisible: workspaceSwitcherVisible,
+    setSwitcherVisible: setWorkspaceSwitcherVisible,
+  });
+  return {
+    screens,
+    workspace,
+    statusSettings,
+    appearance,
+    historySearchOpen,
+    setHistorySearchOpen,
+  };
+}

package/src/hooks/useAppSubmissionState.ts

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+
+interface IOptions {
+  readonly selectedEntry: IExecutionWorkspaceEntry | undefined;
+  readonly submit: (input: string) => Promise<void>;
+  readonly sendAgentJob: (taskId: string, input: string) => Promise<void>;
+  readonly isThinking: boolean;
+}
+
+export interface IAppSubmissionState {
+  readonly submit: (input: string) => Promise<void>;
+  readonly gitRefreshToken: number;
+}
+
+export function useAppSubmissionState(options: IOptions): IAppSubmissionState {
+  const [gitRefreshToken, setGitRefreshToken] = useState(0);
+  const routedSubmit = useCallback(
+    async (input: string): Promise<void> => {
+      const entry = options.selectedEntry;
+      if (entry && entry.kind !== 'main_thread' && entry.controls.includes('send')) {
+        await options.sendAgentJob(entry.sourceId, input);
+        return;
+      }
+      await options.submit(input);
+    },
+    [options.selectedEntry, options.sendAgentJob, options.submit],
+  );
+  const submit = useCallback(
+    async (input: string): Promise<void> => {
+      setGitRefreshToken((token) => token + 1);
+      await routedSubmit(input);
+    },
+    [routedSubmit],
+  );
+  const wasThinkingRef = useRef(false);
+  useEffect(() => {
+    if (wasThinkingRef.current && !options.isThinking) {
+      setGitRefreshToken((token) => token + 1);
+    }
+    wasThinkingRef.current = options.isThinking;
+  }, [options.isThinking]);
+  return { submit, gitRefreshToken };
+}

package/src/hooks/useAppThemeState.ts

@@ -0,0 +1,157 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { createThemeRegistry, formatUnknownThemeNotice } from '../theme/theme-registry.js';
+
+import type { ITuiTheme } from '../theme/theme-contracts.js';
+import type { IThemeRegistry, IThemeSkip } from '../theme/theme-registry.js';
+import type {
+  IAppearanceSettings,
+  IThemeAppearanceState,
+  TReducedMotionOverride,
+} from '@robota-sdk/agent-interface-command';
+
+/** The tier that pinned motion for this run and what it pinned — the contract's own pair. */
+type IReducedMotionPin = NonNullable<IThemeAppearanceState['reducedMotionPin']>;
+
+export interface IThemeToggles {
+  readonly syntaxHighlighting: boolean;
+  readonly reducedMotion: boolean;
+}
+
+export interface IAppThemePickerViewModel {
+  readonly visible: boolean;
+  readonly themes: readonly ITuiTheme[];
+  /** Theme files that were found and refused — shown as rows that cannot be chosen. */
+  readonly skipped: readonly IThemeSkip[];
+  /** The id that is PERSISTED — the row the picker returns to when it is cancelled. */
+  readonly activeThemeId: string;
+  /** The PERSISTED toggles the picker seeds itself from and submits alongside the theme. */
+  readonly syntaxHighlighting: boolean;
+  readonly reducedMotion: boolean;
+  /**
+   * Set when a tier above the settings pinned motion for this run — the tier AND what it pinned,
+   * as one value, for the reason `IThemeAppearanceState` states: the tier alone cannot say which
+   * way a run went.
+   */
+  readonly reducedMotionPin?: IReducedMotionPin | undefined;
+  /** Move the highlight: the live region re-renders in that theme, nothing is written. */
+  readonly preview: (id: string) => void;
+  /**
+   * Commit: submits `/theme <id> syntax <on|off> motion <on|off>` — ONE patch through the command
+   * path, because the HOST owns writing the settings document. Three separate submissions would be
+   * three chances to half-apply what the user saw as one decision.
+   */
+  readonly select: (id: string, toggles: IThemeToggles) => void;
+  /** Leave: the preview is dropped and the persisted theme is what remains. */
+  readonly cancel: () => void;
+}
+
+export interface IAppThemeViewModel {
+  /** The theme every component renders with right now — the preview when one is open. */
+  readonly resolved: ITuiTheme;
+  /** Whether motion is suppressed for this run, after the flag/env/settings chain. */
+  readonly reducedMotion: boolean;
+  /** Whether fenced code blocks are highlighted. Every markdown render site reads this. */
+  readonly syntaxHighlighting: boolean;
+  /** Present once, when the persisted id names a theme this build does not have. */
+  readonly unknownThemeNotice?: string;
+  readonly picker: IAppThemePickerViewModel;
+}
+
+interface IOptions {
+  readonly appearance: IAppearanceSettings;
+  readonly registry?: IThemeRegistry | undefined;
+  readonly reducedMotion?: boolean | undefined;
+  /** Which tier decided it, when that was not the settings. */
+  readonly reducedMotionOverride?: TReducedMotionOverride | undefined;
+  readonly visible: boolean;
+  readonly setVisible: (visible: boolean) => void;
+  readonly submit: (input: string) => void;
+}
+
+/**
+ * SCREEN-2002 — which theme the live region renders with, and the picker over it.
+ *
+ * Two inputs, one answer. The PERSISTED appearance is the baseline; a preview is a local overlay
+ * that exists only while the picker is open. Selecting does not write — it submits `/theme <id>`,
+ * so the host applies the patch and the refresh-on-result path re-reads it. That keeps ONE writer
+ * for the settings document and means the picker cannot persist something `/theme` would refuse.
+ *
+ * `reducedMotion` arrives already resolved from the CLI (settings ← env ← flag). It is not
+ * recomputed here, because a second place deciding the same question is how the two start
+ * disagreeing — and it is still not the final say: `useMotion()` gates on the colour gate and
+ * screen-reader mode above it.
+ */
+export function useAppThemeState(options: IOptions): IAppThemeViewModel {
+  const registry = useMemo(() => options.registry ?? createThemeRegistry(), [options.registry]);
+  const [previewId, setPreviewId] = useState<string | undefined>(undefined);
+  const resolution = useMemo(
+    () => registry.resolve(previewId ?? options.appearance.theme),
+    [registry, previewId, options.appearance.theme],
+  );
+
+  const { setVisible, submit } = options;
+  const cancel = useCallback((): void => {
+    setPreviewId(undefined);
+    setVisible(false);
+  }, [setVisible]);
+  const { syntaxHighlighting, reducedMotion } = options.appearance;
+  const select = useCallback(
+    (id: string, toggles: IThemeToggles): void => {
+      setPreviewId(undefined);
+      setVisible(false);
+      const parts = [`/theme ${id}`];
+      // Only what the user actually CHANGED. Sending all three would make choosing a theme report
+      // "syntax highlighting on, motion on" as applied to someone who touched neither — and on a
+      // run with a reduced-motion flag it would also drag out the pinned-for-this-run notice for a
+      // setting they never asked about.
+      if (toggles.syntaxHighlighting !== syntaxHighlighting) {
+        parts.push(`syntax ${toggles.syntaxHighlighting ? 'on' : 'off'}`);
+      }
+      if (toggles.reducedMotion !== reducedMotion) {
+        // `motion on` means ANIMATE, which is `reducedMotion: false` — the inversion lives in the
+        // command's parser, and this is the one place that has to speak its vocabulary.
+        parts.push(`motion ${toggles.reducedMotion ? 'off' : 'on'}`);
+      }
+      submit(parts.join(' '));
+    },
+    [reducedMotion, setVisible, submit, syntaxHighlighting],
+  );
+
+  // A preview of an unknown id is impossible (the rows come from the registry), so the notice can
+  // only be about what is PERSISTED — and it is suppressed while previewing so it does not read as
+  // a complaint about the row the user is looking at.
+  const unknownId = previewId === undefined ? resolution.unknownId : undefined;
+  // One expression for "what motion IS for this run", read by both the view model and the picker:
+  // two copies of the same `??` chain are two things to keep in step.
+  const reducedMotionForRun = options.reducedMotion ?? options.appearance.reducedMotion;
+  return {
+    resolved: resolution.theme,
+    reducedMotion: reducedMotionForRun,
+    syntaxHighlighting: options.appearance.syntaxHighlighting,
+    ...(unknownId === undefined ? {} : { unknownThemeNotice: formatUnknownThemeNotice(unknownId) }),
+    picker: {
+      visible: options.visible,
+      themes: registry.list(),
+      skipped: registry.skipped(),
+      activeThemeId: options.appearance.theme,
+      syntaxHighlighting: options.appearance.syntaxHighlighting,
+      reducedMotion: options.appearance.reducedMotion,
+      // Both halves or neither. A tier with no resolved value would have to be paired with the
+      // PERSISTED one, which is the contradiction this pair exists to stop — so a caller that
+      // supplies only the tier gets no pin rather than a wrong one, and the row simply says
+      // nothing about a pin instead of naming the wrong direction.
+      ...(options.reducedMotionOverride === undefined || options.reducedMotion === undefined
+        ? {}
+        : {
+            reducedMotionPin: {
+              tier: options.reducedMotionOverride,
+              reducedMotion: options.reducedMotion,
+            },
+          }),
+      preview: setPreviewId,
+      select,
+      cancel,
+    },
+  };
+}