@wizardingcode/shibaox-tui 0.1.0

package/src/component/tabs.tsx

@@ -0,0 +1,116 @@
+import { TextAttributes } from '@opentui/core';
+import { createEffect, createSignal, For, type JSX, onCleanup } from 'solid-js';
+import { useData } from '../context/data.js';
+import { shortId } from '../model/format.js';
+import { statusOf } from '../model/status.js';
+import { useMotion } from '../motion/config.js';
+import { completionPulseOpacity } from '../motion/pulse.js';
+import { useTheme } from '../theme/context.js';
+import { tint } from './logo.js';
+
+const PULSE_MS = 1200;
+const PULSES = 3;
+
+/** 0..1 pulse level for an unread tab: three attack/decay beats, then rest (motion only). */
+function usePulse(unread: () => boolean) {
+  const motion = useMotion();
+  const [level, setLevel] = createSignal(0);
+  createEffect(() => {
+    if (!unread() || !motion()) {
+      setLevel(0);
+      return;
+    }
+    const started = performance.now();
+    const t = setInterval(() => {
+      const elapsed = performance.now() - started;
+      if (elapsed >= PULSE_MS * PULSES) {
+        setLevel(0);
+        clearInterval(t);
+        return;
+      }
+      setLevel(completionPulseOpacity((elapsed % PULSE_MS) / PULSE_MS));
+    }, 50);
+    onCleanup(() => clearInterval(t));
+  });
+  return level;
+}
+
+function Tab(props: { runId?: string }): JSX.Element {
+  const data = useData();
+  const theme = useTheme();
+  const active = () => data.state.active === props.runId;
+  const unread = () => (props.runId ? data.state.unread[props.runId] : undefined);
+  const pulse = usePulse(() => !!unread());
+  const summary = () =>
+    props.runId ? data.state.runs.find((r) => r.runId === props.runId) : undefined;
+  const status = () =>
+    (props.runId
+      ? (data.state.ended[props.runId] ??
+        data.state.states[props.runId]?.status ??
+        summary()?.status)
+      : undefined) ?? 'queued';
+  const look = () => statusOf({ status: status() });
+  const feedback = () => {
+    const f = look().feedback;
+    return f === 'muted' ? theme.text.muted : theme.text.feedback[f];
+  };
+  const pulseColor = () =>
+    unread() === 'needs' ? theme.text.feedback.warning : theme.text.feedback.success;
+  const bg = () => {
+    const base = active() ? theme.background.raised.high : theme.background.raised.base;
+    return pulse() > 0 ? tint(base, pulseColor(), pulse() * 0.5) : base;
+  };
+  const label = () =>
+    props.runId
+      ? `${look().symbol} ${shortId(props.runId)} ${summary()?.workflow ?? ''}${unread() ? ' •' : ''}`
+      : '⌂';
+  return (
+    <box
+      flexDirection="row"
+      flexShrink={0}
+      height={1}
+      paddingLeft={2}
+      paddingRight={2}
+      backgroundColor={bg()}
+      onMouseUp={() => data.activate(props.runId)}
+    >
+      <text
+        fg={props.runId ? (active() ? theme.text.base : theme.text.muted) : theme.text.base}
+        attributes={active() ? TextAttributes.BOLD : undefined}
+        wrapMode="none"
+      >
+        {props.runId ? '' : label()}
+      </text>
+      {props.runId ? (
+        <>
+          <text fg={feedback()} wrapMode="none">{`${look().symbol} `}</text>
+          <text
+            fg={active() ? theme.text.base : theme.text.muted}
+            attributes={active() ? TextAttributes.BOLD : undefined}
+            wrapMode="none"
+          >
+            {`${shortId(props.runId)} ${summary()?.workflow ?? ''}${unread() ? ' •' : ''}`}
+          </text>
+        </>
+      ) : null}
+    </box>
+  );
+}
+
+/** One line of tabs on top: home, then every open run. Only shown while runs are open. */
+export function Tabs(): JSX.Element {
+  const data = useData();
+  const theme = useTheme();
+  return (
+    <box
+      height={1}
+      flexShrink={0}
+      flexDirection="row"
+      width="100%"
+      backgroundColor={theme.background.raised.base}
+    >
+      <Tab />
+      <For each={data.state.open}>{(id) => <Tab runId={id} />}</For>
+    </box>
+  );
+}

package/src/component/too-small.tsx

@@ -0,0 +1,15 @@
+import type { JSX } from 'solid-js';
+import { useTheme } from '../theme/context.js';
+import { MIN_COLS, MIN_ROWS } from '../ui/layout.js';
+
+/** Replaces the page when the terminal is under 60×15. */
+export function TooSmall(): JSX.Element {
+  const theme = useTheme();
+  return (
+    <box width="100%" height="100%" alignItems="center" justifyContent="center">
+      <text
+        fg={theme.text.feedback.warning}
+      >{`Terminal too small (${MIN_COLS}×${MIN_ROWS} minimum)`}</text>
+    </box>
+  );
+}

package/src/context/client.tsx

@@ -0,0 +1,54 @@
+import type { ProjectProfile, RunState } from '@wizardingcode/shibaox-core';
+import type {
+  DiffResult,
+  Envelope,
+  Health,
+  InboxItem,
+  KeyRow,
+  ModelChoice,
+  OrgConfig,
+  OrgConfigPatch,
+  RunSummaryPlus,
+  SubmitRequest,
+} from '@wizardingcode/shibaox-daemon';
+import { createContext, type JSX, type ParentProps, useContext } from 'solid-js';
+
+/** The subset of the daemon client the dashboard uses; the fake implements it in tests. */
+export interface DaemonClientLike {
+  health(): Promise<Health>;
+  listRuns(q?: { status?: string; org?: string }): Promise<RunSummaryPlus[]>;
+  getRun(id: string): Promise<RunState>;
+  events(
+    id: string,
+    o?: { since?: string; signal?: AbortSignal; historyOnly?: boolean },
+  ): AsyncIterable<Envelope>;
+  inbox(): Promise<InboxItem[]>;
+  answer(
+    id: string,
+    a: { approved: boolean; note?: string; via?: 'cli' | 'api' },
+  ): Promise<{ runId: string; kind: 'human' | 'approval' }>;
+  cancel(id: string): Promise<RunState>;
+  resume(id: string, o?: { budgetUsd?: number }): Promise<RunState>;
+  submitRun(req: SubmitRequest): Promise<{ runId: string; warnings: string[] }>;
+  diff(id: string): Promise<DiffResult>;
+  projectProfile(path: string, orgRoot?: string): Promise<ProjectProfile>;
+  models(): Promise<ModelChoice[]>;
+  orgConfig(root: string): Promise<OrgConfig>;
+  setOrgConfig(root: string, patch: OrgConfigPatch): Promise<OrgConfig>;
+  defaultOrg(): Promise<{ root: string; created: boolean }>;
+  keys(): Promise<KeyRow[]>;
+  setKey(name: string, value: string): Promise<{ name: string; set: true }>;
+  unsetKey(name: string): Promise<{ name: string; removed: boolean }>;
+}
+
+const Context = createContext<DaemonClientLike>();
+
+export function ClientProvider(props: ParentProps<{ client: DaemonClientLike }>): JSX.Element {
+  return <Context.Provider value={props.client}>{props.children}</Context.Provider>;
+}
+
+export function useClient(): DaemonClientLike {
+  const c = useContext(Context);
+  if (!c) throw new Error('useClient outside ClientProvider');
+  return c;
+}

package/src/context/commands.tsx

@@ -0,0 +1,44 @@
+import {
+  type Accessor,
+  createContext,
+  createSignal,
+  type JSX,
+  type ParentProps,
+  useContext,
+} from 'solid-js';
+
+/** An action the palette can run; `when` hides it while false. */
+export interface Command {
+  id: string;
+  label: string;
+  keys: string;
+  run: () => void;
+  when?: () => boolean;
+}
+
+interface Registry {
+  commands: Accessor<Command[]>;
+  register(cmds: Command[]): () => void;
+}
+
+const Context = createContext<Registry>();
+
+/** Screens register their commands here so the palette and help can list them. */
+export function CommandsProvider(props: ParentProps): JSX.Element {
+  const [all, setAll] = createSignal<Command[][]>([]);
+  const register = (cmds: Command[]) => {
+    setAll((a) => [...a, cmds]);
+    return () => setAll((a) => a.filter((c) => c !== cmds));
+  };
+  return (
+    <Context.Provider value={{ commands: () => all().flat(), register }}>
+      {props.children}
+    </Context.Provider>
+  );
+}
+
+export function useCommands(): Registry {
+  const c = useContext(Context);
+  if (!c) throw new Error('useCommands outside CommandsProvider');
+  return c;
+}

package/src/context/config.tsx

@@ -0,0 +1,22 @@
+import { createContext, type JSX, type ParentProps, useContext } from 'solid-js';
+
+/** Where this instance runs: the CLI version, the shibaox home and the directory it was launched from. */
+export interface AppConfig {
+  version: string;
+  home: string;
+  cwd: string;
+  /** The environment the dashboard was launched with (PATH decides the default adapter). */
+  env: NodeJS.ProcessEnv;
+}
+
+const Context = createContext<AppConfig>();
+
+export function ConfigProvider(props: ParentProps<{ config: AppConfig }>): JSX.Element {
+  return <Context.Provider value={props.config}>{props.children}</Context.Provider>;
+}
+
+export function useConfig(): AppConfig {
+  const c = useContext(Context);
+  if (!c) throw new Error('useConfig outside ConfigProvider');
+  return c;
+}

package/src/context/data-state.ts

@@ -0,0 +1,41 @@
+import type { RunState, RunStatus } from '@wizardingcode/shibaox-core';
+import type { Health, InboxItem, RunSummaryPlus } from '@wizardingcode/shibaox-daemon';
+
+/** Everything the screens read; fed by the Poller and by user actions. */
+export interface DataState {
+  health?: Health;
+  reachable: boolean;
+  /** When the daemon stopped answering (ms epoch), for the delayed "reconnecting" overlay. */
+  unreachableSince?: number;
+  runs: RunSummaryPlus[];
+  inbox: InboxItem[];
+  states: Record<string, RunState>;
+  /** Bumped whenever a run's frames change (the frames themselves live outside the store). */
+  versions: Record<string, number>;
+  ended: Record<string, RunStatus>;
+  /** Open tabs (root run ids) in order; `active` undefined means the home tab. */
+  open: string[];
+  /** The runs of each tab, oldest first: a tab continues into follow-up runs. */
+  threads: Record<string, string[]>;
+  /** The model chosen with `/model` in a tab, for its next turns. */
+  models: Record<string, string>;
+  active?: string;
+  /** Runs with something the user has not looked at yet (tab pulse). */
+  unread: Record<string, 'done' | 'needs'>;
+}
+
+export const initialData = (): DataState => ({
+  reachable: true,
+  runs: [],
+  inbox: [],
+  states: {},
+  versions: {},
+  ended: {},
+  open: [],
+  threads: {},
+  models: {},
+  unread: {},
+});
+
+/** Frames kept per run (the cards cap at 5000; frames are a few per card). */
+export const FRAME_LIMIT = 20_000;

package/src/context/data.tsx

@@ -0,0 +1,308 @@
+import { conversationOf, type RunState, type RunStatus } from '@wizardingcode/shibaox-core';
+import type { Envelope, InboxId, SubmitRequest } from '@wizardingcode/shibaox-daemon';
+import type { ChatMessage } from '@wizardingcode/shibaox-schemas';
+import {
+  type Accessor,
+  createContext,
+  createEffect,
+  createRoot,
+  type JSX,
+  onCleanup,
+  type ParentProps,
+  useContext,
+} from 'solid-js';
+import { createStore, reconcile } from 'solid-js/store';
+import { money } from '../model/format.js';
+import { type Card, reduceTimeline } from '../model/stream.js';
+import { requestText } from '../routes/session/request.js';
+import type { DaemonClientLike } from './client.js';
+import { useConfig } from './config.js';
+import { type DataState, FRAME_LIMIT, initialData } from './data-state.js';
+import { Poller, type PollerIntervals, type PollerToast } from './poller.js';
+
+export type { DataState } from './data-state.js';
+
+export interface Data {
+  state: DataState;
+  /**
+   * The session cards of a run: reconciled by key on every change, so unchanged cards and
+   * blocks keep their identity and the screen updates in place instead of remounting.
+   */
+  timeline(runId: string): Accessor<Card[]>;
+  /** How many frames of the run are held; undefined once its tab is closed. */
+  frameCount(runId: string): number | undefined;
+  openRun(runId: string): void;
+  closeRun(runId: string): void;
+  /** The runs of the tab that holds `runId`, oldest first. */
+  threadOf(runId: string): string[];
+  /** Submits the next turn in the tab of `rootId` (same org, project, workflow and adapter; the conversation so far travels as `messages`). */
+  continueRun(rootId: string, text: string, o?: { event?: boolean }): Promise<string | undefined>;
+  /** The model the next turns of the tab run on (`/model`). */
+  setModel(rootId: string, ref: string | undefined): void;
+  activate(runId?: string): void;
+  nextTab(direction: 1 | -1): void;
+  markRead(runId: string): void;
+  actions: {
+    answer(id: InboxId, approved: boolean, note?: string): Promise<void>;
+    cancel(runId: string): Promise<void>;
+    resume(runId: string, budgetUsd?: number): Promise<void>;
+    submit(req: SubmitRequest): Promise<string | undefined>;
+  };
+  poller: Poller;
+}
+
+const Context = createContext<Data>();
+
+export function DataProvider(
+  props: ParentProps<{
+    client: DaemonClientLike;
+    intervals?: Partial<PollerIntervals>;
+    now?: () => number;
+    /** Stream mode: subscribe to this run only and never open tabs. */
+    single?: string;
+    /** Where the poller's toasts go (the shell passes `useToast().show`). */
+    toast?: (t: PollerToast) => void;
+    /** Where stream failures and malformed frames are noted. */
+    log?: (line: string) => void;
+  }>,
+): JSX.Element {
+  const [state, set] = createStore<DataState>(initialData());
+  const TERMINAL = new Set<string>(['completed', 'failed', 'cancelled']);
+  // how long a follow-up waits for the previous turn to end (tests shorten it)
+  const turnWaitMs = Number(useConfig().env.SHIBAOX_TURN_WAIT_MS) || 60_000;
+  // frames stay out of the reactive store: a reduce over 20 000 proxied envelopes would
+  // subscribe to every property it reads; `versions` is the only signal
+  const frames = new Map<string, Envelope[]>();
+  const bump = (runId: string) => set('versions', runId, (v = 0) => v + 1);
+  const sink = {
+    reset: (runId: string) => {
+      frames.set(runId, []);
+      bump(runId);
+    },
+    append: (runId: string, batch: Envelope[]) => {
+      const all = [...(frames.get(runId) ?? []), ...batch];
+      frames.set(runId, all.length > FRAME_LIMIT ? all.slice(-FRAME_LIMIT) : all);
+      bump(runId);
+    },
+  };
+  const timelines = new Map<string, { cards: Accessor<Card[]>; dispose: () => void }>();
+
+  const activate = (runId?: string) => {
+    set('active', runId);
+    if (runId) set('unread', runId, undefined as never);
+  };
+  const openRun = (runId: string) => {
+    if (!state.open.includes(runId)) set('open', (o) => [...o, runId]);
+    if (!state.threads[runId]) set('threads', runId, [runId]);
+    for (const id of state.threads[runId] ?? [runId]) poller.subscribe(id);
+    activate(runId);
+  };
+  const threadOf = (runId: string) => state.threads[runId] ?? [runId];
+  /** The conversation turns of a tab: the runs the user talked to (dispatched runs are not turns). */
+  const turnsOf = (rootId: string) =>
+    threadOf(rootId).filter((id) => !state.states[id]?.parentRunId);
+  const replyOf = (id: string) =>
+    timeline(id)()
+      .flatMap((c) => (c.kind === 'node' ? c.blocks : []))
+      .flatMap((b) => (b.kind === 'text' && !b.parentId ? [b.text.trim()] : []))
+      .join('\n')
+      .trim();
+  // turns of a tab go one at a time: the next one builds on the previous one's reply
+  const chains = new Map<string, Promise<unknown>>();
+  const continueRun = (rootId: string, text: string, o: { event?: boolean } = {}) => {
+    const next = (chains.get(rootId) ?? Promise.resolve()).then(
+      () => submitTurn(rootId, text, o),
+      () => submitTurn(rootId, text, o),
+    );
+    chains.set(rootId, next);
+    return next;
+  };
+  /** Waits (bounded) until `runId` is no longer working, so its reply is whole. */
+  const settled = async (runId: string) => {
+    const until = Date.now() + turnWaitMs;
+    while (Date.now() < until) {
+      const st = state.states[runId];
+      if (st && TERMINAL.has(st.status)) return;
+      await new Promise((r) => setTimeout(r, 25));
+    }
+  };
+  const submitTurn = async (rootId: string, text: string, o: { event?: boolean } = {}) => {
+    const turns = turnsOf(rootId);
+    const previousId = turns[turns.length - 1] ?? rootId;
+    await settled(previousId);
+    const previous = state.states[previousId];
+    if (!previous) return undefined;
+    // the conversation so far travels as structured messages; the input is the new turn only.
+    // It builds on the thread the daemon kept for the previous run (it may have compacted
+    // the oldest turns into a summary) plus that run's own request and reply.
+    const reply = replyOf(previousId);
+    const messages: ChatMessage[] = [
+      ...conversationOf(previous.input),
+      { role: 'user' as const, content: requestText(previous.input) },
+      ...(reply ? [{ role: 'assistant' as const, content: reply }] : []),
+    ];
+    const model = state.models[rootId] ?? previous.model;
+    const runId = await poller.submit({
+      orgRoot: previous.orgRoot ?? '',
+      project: previous.project ?? previous.workspace,
+      workflow: previous.workflow,
+      input: text,
+      messages,
+      ...(o.event ? { event: true } : {}),
+      // with a model the daemon derives the adapter from it
+      ...(model ? { model } : {}),
+      adapter: previous.adapter as SubmitRequest['adapter'],
+      workspace: previous.workspaceMode,
+      budgetUsd: previous.budgetUsd,
+    });
+    if (!runId) return undefined;
+    set('threads', rootId, (t = [rootId]) => [...t, runId]);
+    poller.subscribe(runId);
+    return runId;
+  };
+  /** The tab whose thread holds `runId`, when one does. */
+  const rootOf = (runId: string) =>
+    state.open.find((root) => (state.threads[root] ?? [root]).includes(runId));
+  /** What the orchestrator is told when a run it dispatched ends. */
+  const eventText = (st: RunState, status: RunStatus) => {
+    const nodes = Object.entries(st.nodes);
+    const summaries = nodes
+      .filter(([, n]) => n.summary)
+      .map(([id, n]) => `${id}: ${String(n.summary).replace(/\s+/g, ' ').slice(0, 200)}`);
+    const files = timeline(st.runId)().find((c) => c.kind === 'summary');
+    const parts = [
+      `workflow ${st.workflow} finished: ${status}`,
+      `${nodes.length} node${nodes.length === 1 ? '' : 's'}`,
+      money(st.spentUsd),
+      ...(files?.kind === 'summary' && files.files.length > 0
+        ? [`files: ${files.files.slice(0, 20).join(', ')}`]
+        : []),
+      ...(st.branch ? [`branch ${st.branch}`] : []),
+      ...(st.error ? [`error: ${st.error}`] : []),
+      ...summaries,
+    ];
+    return parts.join(' · ').slice(0, 2000);
+  };
+  const poller = new Poller({
+    client: props.client,
+    set,
+    get: () => state,
+    frames: sink,
+    toast: (t) => props.toast?.(t),
+    log: props.log,
+    open: openRun,
+    now: props.now,
+    intervals: props.intervals,
+  });
+  const release = (runId: string) => {
+    timelines.get(runId)?.dispose();
+    timelines.delete(runId);
+    frames.delete(runId);
+    set('versions', runId, undefined as never);
+  };
+  const closeRun = (runId: string) => {
+    const i = state.open.indexOf(runId);
+    if (i < 0) return;
+    set('open', (o) => o.filter((id) => id !== runId));
+    for (const id of threadOf(runId)) {
+      poller.unsubscribe(id);
+      release(id);
+    }
+    set('threads', runId, undefined as never);
+    set('models', runId, undefined as never);
+    if (state.active === runId) activate(state.open[Math.min(i, state.open.length - 1)]);
+  };
+  const nextTab = (direction: 1 | -1) => {
+    const tabs = [undefined, ...state.open];
+    const i = tabs.indexOf(state.active);
+    activate(tabs[(i + direction + tabs.length) % tabs.length]);
+  };
+  const timeline = (runId: string): Accessor<Card[]> => {
+    let entry = timelines.get(runId);
+    if (!entry) {
+      entry = createRoot((dispose) => {
+        const [cards, setCards] = createStore<{ list: Card[] }>({ list: [] });
+        createEffect(() => {
+          state.versions[runId];
+          const run = state.states[runId];
+          // a malformed frame must never take the screen down: keep the last good cards and log
+          try {
+            const next = reduceTimeline(run, frames.get(runId) ?? []);
+            setCards('list', reconcile(next, { key: 'key' }));
+          } catch (e) {
+            props.log?.(`timeline ${runId}: ${e instanceof Error ? e.message : String(e)}`);
+          }
+        });
+        return { cards: () => cards.list, dispose };
+      });
+      timelines.set(runId, entry);
+    }
+    return entry.cards;
+  };
+
+  // children whose end was already history when they joined a tab are never reported again
+  const reported = new Set<string>();
+  // a run dispatched from a conversation (`parentRunId`) joins the tab of its parent
+  createEffect(() => {
+    if (props.single) return;
+    for (const r of state.runs) {
+      if (!r.parentRunId) continue;
+      const root = rootOf(r.parentRunId);
+      if (!root || threadOf(root).includes(r.runId)) continue;
+      if (TERMINAL.has(r.status)) reported.add(r.runId);
+      set('threads', root, (t = [root]) => [...t, r.runId]);
+      poller.subscribe(r.runId);
+    }
+  });
+  // when a dispatched run ends, the conversation continues with an event for the orchestrator
+  createEffect(() => {
+    if (props.single) return;
+    for (const root of state.open)
+      for (const id of state.threads[root] ?? []) {
+        const st = state.states[id];
+        const status = state.ended[id];
+        if (!st?.parentRunId || !status || reported.has(id)) continue;
+        reported.add(id);
+        void continueRun(root, eventText(st, status), { event: true });
+      }
+  });
+
+  poller.start();
+  if (props.single) {
+    set('open', [props.single]);
+    set('active', props.single);
+    poller.subscribe(props.single);
+  }
+  onCleanup(() => {
+    poller.stop();
+    for (const id of [...timelines.keys()]) release(id);
+  });
+
+  const value: Data = {
+    state,
+    timeline,
+    frameCount: (runId) => frames.get(runId)?.length,
+    openRun,
+    closeRun,
+    threadOf,
+    continueRun,
+    setModel: (rootId, ref) => set('models', rootId, ref as never),
+    activate,
+    nextTab,
+    markRead: (runId) => set('unread', runId, undefined as never),
+    actions: {
+      answer: (id, approved, note) => poller.answer(id, approved, note),
+      cancel: (runId) => poller.cancel(runId),
+      resume: (runId, budgetUsd) => poller.resume(runId, budgetUsd),
+      submit: (req) => poller.submit(req),
+    },
+    poller,
+  };
+  return <Context.Provider value={value}>{props.children}</Context.Provider>;
+}
+
+export function useData(): Data {
+  const c = useContext(Context);
+  if (!c) throw new Error('useData outside DataProvider');
+  return c;
+}

package/src/context/exit.tsx

@@ -0,0 +1,13 @@
+import { createContext, type JSX, type ParentProps, useContext } from 'solid-js';
+
+const Context = createContext<(code: number) => void>();
+
+export function ExitProvider(props: ParentProps<{ onExit: (code: number) => void }>): JSX.Element {
+  return <Context.Provider value={props.onExit}>{props.children}</Context.Provider>;
+}
+
+export function useExit(): (code: number) => void {
+  const c = useContext(Context);
+  if (!c) throw new Error('useExit outside ExitProvider');
+  return c;
+}

package/src/context/keys.tsx

@@ -0,0 +1,70 @@
+import { type KeyEvent, TextareaRenderable } from '@opentui/core';
+import { useKeyboard, useRenderer } from '@opentui/solid';
+import { createContext, type JSX, onCleanup, type ParentProps, useContext } from 'solid-js';
+
+export type Scope = 'global' | 'pane' | 'prompt' | 'dialog';
+/** Returns true when the key was consumed. */
+export type KeyHandler = (key: KeyEvent) => boolean | undefined;
+
+interface Entry {
+  scope: Scope;
+  handler: KeyHandler;
+}
+
+const Context = createContext<{ register(e: Entry): () => void }>();
+
+/**
+ * One keyboard listener for the whole app, dispatched by scope: ctrl+q exits always; an open
+ * dialog is modal (only dialog handlers see keys, newest first); a focused text input keeps every
+ * plain key for prompt handlers; otherwise prompt handlers, then pane handlers, then global
+ * handlers, each newest first, until one consumes the key.
+ * ctrl+c exits unless a prompt handler consumes it (clearing its text) or a dialog is open.
+ */
+export function KeysProvider(props: ParentProps<{ onExit: (code: number) => void }>): JSX.Element {
+  const entries: Entry[] = [];
+  const renderer = useRenderer();
+  useKeyboard((key) => {
+    if (key.ctrl && key.name === 'q') return props.onExit(0);
+    // a focused text input owns every plain key: only prompt handlers may look at it
+    // (they still see ctrl/meta chords and escape through the normal dispatch)
+    const typing =
+      renderer.currentFocusedRenderable instanceof TextareaRenderable &&
+      !key.ctrl &&
+      !key.meta &&
+      key.name !== 'escape';
+    if (entries.some((e) => e.scope === 'dialog')) {
+      // modal: every key (ctrl+c included) belongs to the open dialogs, newest handler first
+      for (const e of [...entries].reverse()) if (e.scope === 'dialog' && e.handler(key)) return;
+      return;
+    }
+    const ordered = [...entries].reverse();
+    const dispatch = (scope: Scope) => ordered.some((e) => e.scope === scope && e.handler(key));
+    if (typing) {
+      dispatch('prompt');
+      return;
+    }
+    if (key.ctrl && key.name === 'c') {
+      if (dispatch('prompt')) return;
+      return props.onExit(0);
+    }
+    if (dispatch('prompt')) return;
+    if (dispatch('pane')) return;
+    dispatch('global');
+  });
+  const register = (e: Entry) => {
+    entries.push(e);
+    return () => {
+      const i = entries.indexOf(e);
+      if (i >= 0) entries.splice(i, 1);
+    };
+  };
+  return <Context.Provider value={{ register }}>{props.children}</Context.Provider>;
+}
+
+/** Registers a key handler for this component's lifetime. */
+export function useKeys(scope: Scope, handler: KeyHandler): void {
+  const c = useContext(Context);
+  if (!c) throw new Error('useKeys outside KeysProvider');
+  const off = c.register({ scope, handler });
+  onCleanup(off);
+}