catherd-cli 0.2.1 → 1.1.0

package/src/entry/tui/providers/app.tsx

@@ -0,0 +1,162 @@
+import type { Clock } from "@opentui/core";
+import { useKeymap } from "@opentui/keymap/react";
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
+import type { ProfileDoc } from "../../../domain/profile.ts";
+import type { Effects } from "../effects.ts";
+import { type Action, type AppState, type Purpose, reduce } from "../state.ts";
+import { setModal } from "./keymap.tsx";
+import { type Toast, useToasts } from "./toast.tsx";
+
+export type BackKind = "input" | "view";
+
+/** What an answer carries besides its value. */
+interface AnswerExtra {
+  /** the save dialog's: the profile file as its last preview read it, the only one the save may write over */
+  shown?: ProfileDoc;
+  /** the save dialog's: reads the file again and shows the new preview with the changed-on-disk notice */
+  changed?: () => void;
+}
+
+export type DialogHandler = (purpose: Purpose, value: string, extra: AnswerExtra) => void | Promise<void>;
+
+export interface AppApi {
+  /** the state this render drew */
+  state: AppState;
+  /** the state now, after every dispatch so far: what a command handler must read */
+  getState(): AppState;
+  /** runs the reducer now, so the keymap's mode follows the dialog stack before the next key */
+  dispatch(a: Action): void;
+  effects: Effects;
+  clock: Clock;
+  toast(t: Toast): void;
+  /** lines printed to stdout once the TUI has exited: what the user must keep (spec §9.4); a line held already is dropped */
+  keep(lines: string[]): void;
+  exit(code: number): void;
+  /** copies to the clipboard (OSC 52); false when the terminal cannot */
+  copy(text: string): boolean;
+  /** answers the top dialog: runs the handler registered for its purpose */
+  answer(value: string, extra?: AnswerExtra): void;
+  onDialog(type: Purpose["type"], fn: DialogHandler): () => void;
+  /**
+   * esc runs the newest back handler (clear a filter, leave a run); ctrl+c runs only the newest one that
+   * clears a text input.
+   */
+  onBack(fn: () => void, kind: BackKind): () => void;
+  back(kind?: BackKind): boolean;
+}
+
+const AppContext = createContext<AppApi | null>(null);
+
+export function useApp(): AppApi {
+  const app = useContext(AppContext);
+  if (!app) throw new Error("useApp must be used inside AppProvider");
+  return app;
+}
+
+export function AppProvider(props: {
+  effects: Effects;
+  clock: Clock;
+  initial: AppState;
+  copy: (text: string) => boolean;
+  onExit: (code: number, kept: string[]) => void;
+  children: ReactNode;
+}) {
+  const keymap = useKeymap();
+  const toasts = useToasts();
+  const [state, setState] = useState(props.initial);
+  const stateRef = useRef(props.initial);
+  const kept = useRef<string[]>([]);
+  const handlers = useRef(new Map<string, DialogHandler[]>());
+  const backs = useRef<{ fn: () => void; kind: BackKind }[]>([]);
+  const propsRef = useRef(props);
+  propsRef.current = props;
+  const api = useMemo<Omit<AppApi, "state">>(
+    () => ({
+      getState: () => stateRef.current,
+      dispatch(a) {
+        const next = reduce(stateRef.current, a);
+        if (next === stateRef.current) return;
+        stateRef.current = next;
+        setModal(keymap, next.dialogs.length > 0);
+        setState(next);
+      },
+      effects: props.effects,
+      clock: props.clock,
+      toast: (t) => toasts.show(t),
+      keep(lines) {
+        // a line already kept (an agent linked by both Save and Make active) prints once
+        for (const l of lines) if (!kept.current.includes(l)) kept.current.push(l);
+      },
+      exit: (code) => propsRef.current.onExit(code, kept.current),
+      copy: (text) => propsRef.current.copy(text),
+      answer(value, extra = {}) {
+        const top = stateRef.current.dialogs.at(-1);
+        if (!top) return;
+        const fn = handlers.current.get(top.purpose.type)?.at(-1);
+        if (fn) void fn(top.purpose, value, extra);
+      },
+      onDialog(type, fn) {
+        const list = handlers.current.get(type) ?? [];
+        handlers.current.set(type, [...list, fn]);
+        return () =>
+          handlers.current.set(
+            type,
+            (handlers.current.get(type) ?? []).filter((f) => f !== fn),
+          );
+      },
+      onBack(fn, kind) {
+        const entry = { fn, kind };
+        backs.current.push(entry);
+        return () => {
+          backs.current = backs.current.filter((b) => b !== entry);
+        };
+      },
+      back(kind) {
+        const b = backs.current.findLast((x) => kind === undefined || x.kind === kind);
+        if (!b) return false;
+        b.fn();
+        return true;
+      },
+    }),
+    // the toast api and the keymap are stable for the app's life
+    [keymap, props.effects, props.clock, toasts.show],
+  );
+  const value = useMemo(() => ({ ...api, state }), [api, state]);
+  return <AppContext.Provider value={value}>{props.children}</AppContext.Provider>;
+}
+
+/** Registers the handler for a dialog purpose while the caller is mounted. */
+export function useDialogHandler(type: Purpose["type"], fn: DialogHandler): void {
+  const app = useApp();
+  const ref = useRef(fn);
+  ref.current = fn;
+  useEffect(() => app.onDialog(type, (p, v, x) => ref.current(p, v, x)), [app.onDialog, type]);
+}
+
+/** Registers a back handler while `active`: `input` clears a text input, `view` leaves a view. */
+export function useBack(active: boolean, kind: BackKind, fn: () => void): void {
+  const app = useApp();
+  const ref = useRef(fn);
+  ref.current = fn;
+  useEffect(() => (active ? app.onBack(() => ref.current(), kind) : undefined), [active, kind, app.onBack]);
+}
+
+/** The clock's time, re-read every `everyMs` (for "updated 3s ago"). */
+export function useNow(everyMs: number): number {
+  const { clock } = useApp();
+  const [, tick] = useReducer((n: number) => n + 1, 0);
+  useEffect(() => {
+    const h = clock.setInterval(tick, everyMs);
+    return () => clock.clearInterval(h);
+  }, [clock, everyMs]);
+  return clock.now();
+}

package/src/entry/tui/providers/boundary.tsx

@@ -0,0 +1,57 @@
+import { useTerminalDimensions } from "@opentui/react";
+import { Component, type ReactNode, useEffect } from "react";
+import { errorMessage, isCatherdError } from "../../../domain/errors.ts";
+import { wrap } from "../text.ts";
+import { Line } from "../widgets/line.tsx";
+import { useApp } from "./app.tsx";
+import { setModal, useCommandLayer, useKeymap } from "./keymap.tsx";
+
+/**
+ * What shows when a view throws while drawing: the error, its fix and a way out. Everything under the
+ * boundary is gone, with its keys, so this registers its own quit: q or ctrl+c exits 1 and prints the
+ * error after the terminal is given back.
+ */
+function Crashed(props: { error: unknown }) {
+  const app = useApp();
+  const keymap = useKeymap();
+  const dims = useTerminalDimensions();
+  const e = props.error;
+  const message = errorMessage(e);
+  const fix = isCatherdError(e) ? e.fix : undefined;
+  // a dialog open when it broke is gone with the rest: its modal mode would keep q from reaching quit
+  useEffect(() => setModal(keymap, false), [keymap]);
+  const quit = () => {
+    app.keep([`catherd: ${message}`, ...(fix ? [`fix: ${fix}`] : [])]);
+    app.exit(1);
+  };
+  useCommandLayer("global", { "app.interrupt": quit });
+  useCommandLayer("app", { "app.quit": quit });
+  const w = Math.max(10, dims.width - 2);
+  const lines: { text: string; tone?: "error" | "muted" }[] = [
+    { text: "" },
+    ...wrap(`catherd stopped: ${message}`, w).map((text) => ({ text, tone: "error" as const })),
+    ...(fix ? wrap(`fix: ${fix}`, w).map((text) => ({ text, tone: "muted" as const })) : []),
+    { text: "" },
+    { text: "press q or ctrl+c to quit; unsaved changes are lost", tone: "muted" },
+  ];
+  return (
+    <box flexDirection="column" width={dims.width} height={dims.height}>
+      {lines.map((l, i) => (
+        <Line key={i} width={dims.width} parts={[{ text: ` ${l.text}`, tone: l.tone }]} />
+      ))}
+    </box>
+  );
+}
+
+/** Catches an error thrown while drawing, so the user keeps a way out of the alternate screen. */
+export class AppErrorBoundary extends Component<{ children: ReactNode }, { error: unknown }> {
+  override state: { error: unknown } = { error: null };
+
+  static getDerivedStateFromError(error: unknown): { error: unknown } {
+    return { error: error ?? new Error("unknown error") };
+  }
+
+  override render(): ReactNode {
+    return this.state.error !== null ? <Crashed error={this.state.error} /> : this.props.children;
+  }
+}

package/src/entry/tui/providers/data.tsx

@@ -0,0 +1,160 @@
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { errorMessage, isCatherdError } from "../../../domain/errors.ts";
+import type { DoctorReport } from "../../../services/doctor.ts";
+import type { Effects, RunRow, SessionRow } from "../effects.ts";
+import { useApp } from "./app.tsx";
+
+export interface Polled<T> {
+  value: T | null;
+  error: string | null;
+  /** what to do about `error`, when the failure says (a CatherdError's fix) */
+  fix: string | null;
+  /** clock time of the last good read, null before the first */
+  at: number | null;
+  refresh(): void;
+}
+
+/**
+ * Reads `read` now and every `everyMs` while not paused, off the render path (spec §9.4: runs data is
+ * polled off the render path): a read runs in a timer callback, never while React renders. It reads at once
+ * when it mounts, when `key` changes, on `refresh`, when it resumes and when it is turned back on; a new
+ * cadence or a pause only reschedules. `off`: no read at all (the data is not shown).
+ */
+export function usePoll<T>(
+  read: () => T,
+  everyMs: number,
+  o: { paused?: boolean; key?: string; off?: boolean } = {},
+): Polled<T> {
+  const { clock } = useApp();
+  const [state, setState] = useState<{
+    value: T | null;
+    error: string | null;
+    fix: string | null;
+    at: number | null;
+  }>({ value: null, error: null, fix: null, at: null });
+  const readRef = useRef(read);
+  readRef.current = read;
+  const [nonce, setNonce] = useState(0);
+  // what the last effect run read for: a read at once is due only when this moves on
+  const last = useRef<{ clock: unknown; key: string | undefined; nonce: number; paused: boolean } | null>(
+    null,
+  );
+  const paused = o.paused ?? false;
+  useEffect(() => {
+    if (o.off) {
+      last.current = null;
+      return;
+    }
+    const was = last.current;
+    last.current = { clock, key: o.key, nonce, paused };
+    const now =
+      was === null ||
+      was.clock !== clock ||
+      was.key !== o.key ||
+      was.nonce !== nonce ||
+      (was.paused && !paused);
+    const run = () => {
+      try {
+        setState({ value: readRef.current(), error: null, fix: null, at: clock.now() });
+      } catch (e) {
+        // `at` stays the time of the last good read: old rows must not read as fresh
+        setState((s) => ({
+          ...s,
+          error: errorMessage(e),
+          fix: isCatherdError(e) && e.fix ? e.fix : null,
+        }));
+      }
+    };
+    const first = now ? clock.setTimeout(run, 0) : null;
+    const every = paused ? null : clock.setInterval(run, everyMs);
+    return () => {
+      if (first !== null) clock.clearTimeout(first);
+      if (every !== null) clock.clearInterval(every);
+    };
+  }, [clock, everyMs, paused, o.key, o.off, nonce]);
+  return { ...state, refresh: () => setNonce((n) => n + 1) };
+}
+
+/** `read` once, off the render path, and again whenever `key` changes or `refresh` is called. */
+export function useLoad<T>(read: () => T, key = ""): Polled<T> {
+  return usePoll(read, 0, { paused: true, key });
+}
+
+/** How often the run list is read again, unless paused (spec §9.1 Runs: "updated Ns ago"; `p` pauses). */
+export const RUNS_EVERY_MS = 2_000;
+
+export interface Data {
+  report: DoctorReport | null;
+  checking: boolean;
+  checkedAt: number | null;
+  checkError: string | null;
+  recheck(): void;
+  runs: Polled<{ rows: RunRow[]; warnings: string[] }>;
+  /** spec §4: the Runs tab's sessions, read on the runs' cadence while their list is shown */
+  sessions: Polled<{ rows: SessionRow[]; warnings: string[] }>;
+  /** the profile names and the active one; read on the runs' cadence and after every profile write */
+  profiles: Polled<ReturnType<Effects["profiles"]>>;
+}
+
+const DataContext = createContext<Data | null>(null);
+
+export function useData(): Data {
+  const d = useContext(DataContext);
+  if (!d) throw new Error("useData must be used inside DataProvider");
+  return d;
+}
+
+/** Spec §9.4 providers: the data every tab and the header share, read off the render path. */
+export function DataProvider(props: { children: ReactNode }) {
+  const app = useApp();
+  const [report, setReport] = useState<DoctorReport | null>(null);
+  const [checking, setChecking] = useState(false);
+  const [checkedAt, setCheckedAt] = useState<number | null>(null);
+  const [checkError, setCheckError] = useState<string | null>(null);
+  const [nonce, setNonce] = useState(0);
+  useEffect(() => {
+    let live = true;
+    setChecking(true);
+    const h = app.clock.setTimeout(() => {
+      app.effects
+        .doctor()
+        .then((r) => {
+          if (!live) return;
+          setReport(r);
+          setCheckError(null);
+        })
+        .catch((e: unknown) => live && setCheckError(errorMessage(e)))
+        .finally(() => {
+          if (!live) return;
+          setChecking(false);
+          setCheckedAt(app.clock.now());
+        });
+    }, 0);
+    return () => {
+      live = false;
+      app.clock.clearTimeout(h);
+    };
+  }, [app.effects, app.clock, nonce]);
+  const runs = usePoll(() => app.effects.runs(), RUNS_EVERY_MS, { paused: app.state.paused });
+  // spec §9.4: reading the sessions scans every run, so only while their list is on screen
+  const sessions = usePoll(() => app.effects.sessions(), RUNS_EVERY_MS, {
+    paused: app.state.paused,
+    off: app.state.tab !== "runs" || app.state.session !== null,
+  });
+  // cheap (a directory listing and two small reads), and another terminal may change them at any time
+  const profiles = usePoll(() => app.effects.profiles(), RUNS_EVERY_MS);
+  const value = useMemo(
+    () => ({
+      report,
+      checking,
+      checkedAt,
+      checkError,
+      recheck: () => setNonce((n) => n + 1),
+      runs,
+      sessions,
+      profiles,
+    }),
+    [report, checking, checkedAt, checkError, runs, sessions, profiles],
+  );
+  return <DataContext.Provider value={value}>{props.children}</DataContext.Provider>;
+}

package/src/entry/tui/providers/keymap.tsx

@@ -0,0 +1,166 @@
+// Adapted from anomalyco/opencode packages/tui/src/context/keymap.tsx (MIT, © 2025 opencode);
+// see THIRD_PARTY_NOTICES.md.
+import type { CliRenderer, KeyEvent, Renderable } from "@opentui/core";
+import type { Keymap } from "@opentui/keymap";
+import {
+  registerBackspacePopsPendingSequence,
+  registerCommaBindings,
+  registerEscapeClearsPendingSequence,
+  registerTimedLeader,
+} from "@opentui/keymap/addons/opentui";
+import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui";
+import { KeymapProvider, useBindings, useKeymap } from "@opentui/keymap/react";
+import { flushSync, useRenderer } from "@opentui/react";
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useReducer, useRef } from "react";
+import {
+  type CommandDef,
+  type CommandId,
+  commandsIn,
+  DEFAULT_KEYS,
+  isGuarded,
+  isPrintable,
+  type Keybinds,
+  LEADER,
+  LEADER_TIMEOUT_MS,
+  type Scope,
+} from "../commands.ts";
+
+export type AppKeymap = Keymap<Renderable, KeyEvent>;
+export type Handlers = Partial<Record<CommandId, () => void>>;
+
+/** The keymap data key that holds the mode: `base`, or `modal` while a dialog is open (spec §9.2). */
+export const MODE = "catherd.mode";
+
+/** opencode's keymap setup: comma lists, esc and backspace for pending sequences, the timed leader, modes. */
+export function createAppKeymap(renderer: CliRenderer): AppKeymap {
+  const k = createDefaultOpenTuiKeymap(renderer);
+  registerCommaBindings(k);
+  registerEscapeClearsPendingSequence(k);
+  registerBackspacePopsPendingSequence(k);
+  registerTimedLeader(k, { trigger: LEADER, name: "leader", timeoutMs: LEADER_TIMEOUT_MS });
+  k.setData(MODE, "base");
+  // a layer names its mode; "global" layers are live in every mode
+  k.registerLayerFields({
+    mode(value, ctx) {
+      if (value !== "global") ctx.require(MODE, value);
+    },
+  });
+  const attr = (name: string) => (value: unknown, ctx: { attr(n: string, v: unknown): void }) =>
+    ctx.attr(name, value);
+  k.registerCommandFields({
+    palette: attr("palette"),
+    suggested: attr("suggested"),
+    hint: attr("hint"),
+    short: attr("short"),
+    scope: attr("scope"),
+    cli: attr("cli"),
+  });
+  return k;
+}
+
+/** Puts the keymap in modal mode while a dialog is open; synchronous, so a key right after sees it. */
+export const setModal = (k: AppKeymap, modal: boolean): void => k.setData(MODE, modal ? "modal" : "base");
+
+const KeybindsContext = createContext<Keybinds>(DEFAULT_KEYS);
+export const useKeybinds = (): Keybinds => useContext(KeybindsContext);
+
+/** The keymap for the renderer, and the keys in force. */
+export function AppKeymapProvider(props: { keybinds: Keybinds; keymap?: AppKeymap; children: ReactNode }) {
+  const renderer = useRenderer();
+  const keymap = useMemo(() => props.keymap ?? createAppKeymap(renderer), [props.keymap, renderer]);
+  return (
+    <KeymapProvider keymap={keymap}>
+      <KeybindsContext.Provider value={props.keybinds}>{props.children}</KeybindsContext.Provider>
+    </KeymapProvider>
+  );
+}
+
+const modeOf = (scope: Scope): "global" | "modal" | "base" =>
+  scope === "global" ? "global" : scope === "dialog" ? "modal" : "base";
+
+/**
+ * Registers the commands of `scope` that have a handler, bound to their keys, while the calling component
+ * is mounted. Printable keys of guarded scopes, and every key of a `row.*` scope, go quiet while a text
+ * input has focus, so the input gets them as text; a `filter` layer is live only then.
+ */
+export function useCommandLayer(scope: Scope, handlers: Handlers): void {
+  const renderer = useRenderer();
+  const keys = useKeybinds();
+  const ref = useRef(handlers);
+  ref.current = handlers;
+  const ids = commandsIn(scope)
+    .filter((c) => handlers[c.id as CommandId])
+    .map((c) => c.id as CommandId);
+  const idsKey = ids.join(" ");
+  const mode = modeOf(scope);
+  const typing = () => renderer.currentFocusedEditor !== null;
+  const layerEnabled = scope === "filter" ? typing : scope.startsWith("row.") ? () => !typing() : () => true;
+  const command = (c: CommandDef) => ({
+    name: c.id,
+    title: c.title,
+    group: c.group,
+    scope: c.scope,
+    ...(c.palette ? { palette: true } : {}),
+    ...(c.suggested ? { suggested: true } : {}),
+    ...(c.hint !== undefined ? { hint: c.hint } : {}),
+    ...(c.short ? { short: c.short } : {}),
+    ...(c.cli ? { cli: c.cli } : {}),
+    // a key's update is drawn before the next key of the same chunk is read: a dialog or a filter it
+    // opens has its input mounted and focused by then, so no letter typed right after it is lost
+    run: () => {
+      flushSync(() => ref.current[c.id as CommandId]?.());
+    },
+  });
+  const defs = commandsIn(scope).filter((c) => ids.includes(c.id as CommandId));
+  const guarded = isGuarded(scope);
+  const bindingsFor = (printable: boolean) =>
+    defs.flatMap((c) =>
+      keys[c.id as CommandId]
+        .filter((k) => (guarded ? isPrintable(k) === printable : !printable))
+        .map((k) => ({ key: k, cmd: c.id })),
+    );
+  useBindings(
+    () => ({ mode, enabled: layerEnabled, commands: defs.map(command), bindings: bindingsFor(false) }),
+    [scope, idsKey, keys],
+  );
+  // printable keys of a guarded scope: their own layer, quiet while a text input has focus
+  useBindings(
+    () => ({ mode, enabled: () => !typing(), bindings: guarded ? bindingsFor(true) : [] }),
+    [scope, idsKey, keys],
+  );
+}
+
+export interface CommandEntry {
+  id: CommandId;
+  title: string;
+  group: string;
+  palette: boolean;
+  suggested: boolean;
+  hint: number | null;
+  short: string | null;
+  cli: string | null;
+}
+
+/** The commands a key could run right now, or that `dispatch` could; what the palette and help list. */
+export function reachableCommands(k: AppKeymap): CommandEntry[] {
+  return k.getCommandEntries({ visibility: "reachable" }).map(({ command: c }) => ({
+    id: c.name as CommandId,
+    title: String(c.title ?? c.name),
+    group: String(c.group ?? ""),
+    palette: c.palette === true,
+    suggested: c.suggested === true,
+    hint: typeof c.hint === "number" ? c.hint : null,
+    short: typeof c.short === "string" ? c.short : null,
+    cli: typeof c.cli === "string" ? c.cli : null,
+  }));
+}
+
+/** Re-renders the caller whenever the keymap's live bindings change (a layer, a mode, focus). */
+export function useKeymapVersion(): number {
+  const k = useKeymap();
+  const [v, bump] = useReducer((n: number) => n + 1, 0);
+  useEffect(() => k.on("state", () => bump()), [k]);
+  return v;
+}
+
+export { useKeymap };

package/src/entry/tui/providers/root.tsx

@@ -0,0 +1,45 @@
+import type { Clock } from "@opentui/core";
+import type { ReactNode } from "react";
+import type { Keybinds } from "../commands.ts";
+import type { Effects } from "../effects.ts";
+import type { AppState } from "../state.ts";
+import type { Ui } from "../theme.ts";
+import { AppProvider } from "./app.tsx";
+import { AppErrorBoundary } from "./boundary.tsx";
+import { type AppKeymap, AppKeymapProvider } from "./keymap.tsx";
+import { ThemeProvider } from "./theme.tsx";
+import { ToastProvider } from "./toast.tsx";
+
+/**
+ * Every provider, in dependency order: theme → keymap → toasts → app state (dialogs, handlers), and
+ * under them the boundary that keeps a way out when a view throws.
+ */
+export function Providers(props: {
+  ui: Ui;
+  keybinds: Keybinds;
+  keymap?: AppKeymap;
+  effects: Effects;
+  clock: Clock;
+  initial: AppState;
+  copy: (text: string) => boolean;
+  onExit: (code: number, kept: string[]) => void;
+  children: ReactNode;
+}) {
+  return (
+    <ThemeProvider ui={props.ui}>
+      <AppKeymapProvider keybinds={props.keybinds} keymap={props.keymap}>
+        <ToastProvider clock={props.clock}>
+          <AppProvider
+            effects={props.effects}
+            clock={props.clock}
+            initial={props.initial}
+            copy={props.copy}
+            onExit={props.onExit}
+          >
+            <AppErrorBoundary>{props.children}</AppErrorBoundary>
+          </AppProvider>
+        </ToastProvider>
+      </AppKeymapProvider>
+    </ThemeProvider>
+  );
+}

package/src/entry/tui/providers/theme.tsx

@@ -0,0 +1,17 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { paint, type Token, type Ui } from "../theme.ts";
+
+const ThemeContext = createContext<Ui>({ plain: false, color: false, reducedMotion: true, mode: "dark" });
+
+/** Spec §9.4 providers: the theme, one per concern. */
+export function ThemeProvider(props: { ui: Ui; children: ReactNode }) {
+  return <ThemeContext.Provider value={props.ui}>{props.children}</ThemeContext.Provider>;
+}
+
+export const useUi = (): Ui => useContext(ThemeContext);
+
+/** A token's colour for this terminal: undefined under NO_COLOR and --plain. */
+export function useTone(): (t: Token) => string | undefined {
+  const ui = useUi();
+  return (t) => paint(ui, t);
+}

package/src/entry/tui/providers/toast.tsx

@@ -0,0 +1,77 @@
+// Adapted from anomalyco/opencode packages/tui/src/ui/toast.tsx (MIT, © 2025 opencode);
+// see THIRD_PARTY_NOTICES.md.
+import type { Clock } from "@opentui/core";
+import { useRenderer } from "@opentui/react";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { errorMessage, isCatherdError } from "../../../domain/errors.ts";
+
+type ToastVariant = "info" | "success" | "warning" | "error";
+export interface Toast {
+  variant: ToastVariant;
+  message: string;
+  /** the command that fixes it, shown in full on its own lines; the toast stays until the next key */
+  fix?: string;
+}
+
+/** How long a toast stays before the next one in the queue shows (one with a fix waits for a key). */
+export const TOAST_MS = 4_000;
+
+/** An error as a toast: its message, and its fix command when it has one. */
+export const errorToast = (e: unknown): Toast => ({
+  variant: "error",
+  message: errorMessage(e),
+  ...(isCatherdError(e) && e.fix ? { fix: e.fix } : {}),
+});
+
+interface ToastApi {
+  current: Toast | null;
+  queued: number;
+  show(t: Toast): void;
+}
+
+const ToastContext = createContext<ToastApi>({ current: null, queued: 0, show: () => {} });
+
+/**
+ * Spec §9.3: toasts queue at the top right; one shows at a time, for TOAST_MS each. A toast with a fix
+ * command stays until the next key, so the command the user must act on is not gone before it is read.
+ */
+export function ToastProvider(props: { clock: Clock; children: ReactNode }) {
+  const renderer = useRenderer();
+  const [queue, setQueue] = useState<Toast[]>([]);
+  const queueRef = useRef(queue);
+  queueRef.current = queue;
+  const head = queue[0] ?? null;
+  useEffect(() => {
+    if (!head || head.fix) return;
+    const h = props.clock.setTimeout(() => setQueue((q) => q.slice(1)), TOAST_MS);
+    return () => props.clock.clearTimeout(h);
+  }, [head, props.clock]);
+  useEffect(() => {
+    // first in line, before the keymap: a toast the same key shows is not the one it dismisses
+    const onKey = () => {
+      const shown = queueRef.current[0];
+      if (shown?.fix) setQueue((q) => (q[0] === shown ? q.slice(1) : q));
+    };
+    renderer.keyInput.prependListener("keypress", onKey);
+    return () => {
+      renderer.keyInput.off("keypress", onKey);
+    };
+  }, [renderer]);
+  const show = useCallback((t: Toast) => setQueue((q) => [...q, t]), []);
+  const api = useMemo(
+    () => ({ current: head, queued: Math.max(0, queue.length - 1), show }),
+    [head, queue.length, show],
+  );
+  return <ToastContext.Provider value={api}>{props.children}</ToastContext.Provider>;
+}
+
+export const useToasts = (): ToastApi => useContext(ToastContext);