@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.12

package/src/components/story.ts

@@ -0,0 +1,66 @@
+/**
+ * The story contract (#86). Every component file in components/ ships a
+ * colocated *.stories.tsx that exports `meta` plus named Story objects.
+ * The catalog IS the regression suite: stories.test.tsx walks every story,
+ * snapshots its char frame, and asserts declared colors against the styled
+ * spans; the `bun run stories` TUI renders the same objects interactively.
+ */
+
+import type React from "react";
+
+export interface StoryMeta {
+  /** Catalog path, e.g. "primitives/Card". */
+  title: string;
+}
+
+export interface Story {
+  render: () => React.ReactNode;
+  /**
+   * Colors (hex tokens) that must appear among the rendered frame's styled
+   * spans - the color regression net for color-bearing stories.
+   */
+  expectedColors?: string[];
+  /** Virtual terminal size; defaults to 80x24. */
+  size?: { width: number; height: number };
+}
+
+export interface LoadedStory {
+  moduleTitle: string;
+  storyName: string;
+  story: Story;
+}
+
+export function isStory(value: unknown): value is Story {
+  return typeof value === "object" && value !== null && typeof (value as Story).render === "function";
+}
+
+/** Import every *.stories.tsx next to the components and flatten the exports. */
+export async function loadStories(): Promise<LoadedStory[]> {
+  const glob = new Bun.Glob("**/*.stories.tsx");
+  const files = [...glob.scanSync({ cwd: import.meta.dir })].sort();
+  const loaded: LoadedStory[] = [];
+  for (const file of files) {
+    const moduleExports = (await import(`${import.meta.dir}/${file}`)) as Record<string, unknown>;
+    const meta = moduleExports["meta"] as StoryMeta | undefined;
+    const moduleTitle = meta?.title ?? file.replace(/\.stories\.tsx$/, "");
+    for (const [exportName, exported] of Object.entries(moduleExports)) {
+      if (exportName === "meta" || !isStory(exported)) continue;
+      loaded.push({ moduleTitle, storyName: exportName, story: exported });
+    }
+  }
+  return loaded;
+}
+
+/** Component files that must carry stories: every .tsx that is not a story/test. */
+export function componentFilesMissingStories(): string[] {
+  const componentGlob = new Bun.Glob("**/*.tsx");
+  const files = [...componentGlob.scanSync({ cwd: import.meta.dir })];
+  const missing: string[] = [];
+  for (const file of files) {
+    if (file.endsWith(".stories.tsx") || file.endsWith(".test.tsx")) continue;
+    if (file === "stories-app.tsx") continue;
+    const storiesSibling = file.replace(/\.tsx$/, ".stories.tsx");
+    if (!files.includes(storiesSibling)) missing.push(file);
+  }
+  return missing;
+}

package/src/components/syntax-highlight.ts

@@ -0,0 +1,57 @@
+/**
+ * Code highlighting tokens (#86): the theme's named tokens projected onto
+ * tree-sitter capture names for the native code renderable. One SyntaxStyle
+ * per theme object, cached, so every code block on screen shares a handle.
+ * Unknown languages simply render unstyled - highlighting is an enhancement,
+ * never a blocker.
+ */
+
+import { SyntaxStyle, infoStringToFiletype } from "@opentui/core";
+import type { Theme } from "../theme";
+
+/** Markdown fence info -> tree-sitter filetype, with the aliases we accept. */
+export function filetypeFor(language?: string): string | undefined {
+  const info = (language ?? "").toLowerCase();
+  if (!info) return undefined;
+  const aliases: Record<string, string> = {
+    ts: "typescript",
+    js: "javascript",
+    py: "python",
+    rb: "ruby",
+    rs: "rust",
+    sh: "bash",
+    shell: "bash",
+    zsh: "bash",
+    yml: "yaml",
+  };
+  return infoStringToFiletype(aliases[info] ?? info) ?? aliases[info] ?? info;
+}
+
+const syntaxStyleCache = new WeakMap<Theme, SyntaxStyle>();
+
+export function syntaxStyleFor(theme: Theme): SyntaxStyle {
+  const cached = syntaxStyleCache.get(theme);
+  if (cached) return cached;
+  const style = SyntaxStyle.fromStyles({
+    default: { fg: theme.textMuted },
+    comment: { fg: theme.textDim, italic: true },
+    string: { fg: theme.green },
+    number: { fg: theme.blue },
+    constant: { fg: theme.blue },
+    boolean: { fg: theme.blue },
+    keyword: { fg: theme.accent },
+    operator: { fg: theme.textDim },
+    punctuation: { fg: theme.textDim },
+    function: { fg: theme.text },
+    method: { fg: theme.text },
+    type: { fg: theme.blue },
+    constructor: { fg: theme.blue },
+    variable: { fg: theme.textMuted },
+    property: { fg: theme.textMuted },
+    parameter: { fg: theme.textMuted },
+    tag: { fg: theme.accent },
+    attribute: { fg: theme.blue },
+  });
+  syntaxStyleCache.set(theme, style);
+  return style;
+}

package/src/components/theme-context.stories.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import { DARK, type Theme } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { ThemeProvider } from "./theme-context";
+import { Card } from "./primitives/Card";
+
+export const meta: StoryMeta = { title: "theme-context" };
+
+/** A high-contrast variant to prove tokens flow through the provider. */
+const HIGH_CONTRAST: Theme = { ...DARK, accent: "#00ffff", elevated: "#000000", border: "#ffffff" };
+
+export const ContextDefault: Story = {
+  render: () => (
+    <Card title=" default dark theme " contentRows={1}>
+      <text>no provider needed</text>
+    </Card>
+  ),
+  expectedColors: [DARK.elevated],
+};
+
+export const ProviderSwap: Story = {
+  render: () => (
+    <ThemeProvider theme={HIGH_CONTRAST}>
+      <Card title=" provider theme " contentRows={1} borderColor={HIGH_CONTRAST.accent}>
+        <text>tokens come from the provider</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff", "#000000"],
+};
+
+export const PropOverride: Story = {
+  render: () => (
+    <ThemeProvider theme={DARK}>
+      <Card title=" prop-overridden theme " contentRows={1} theme={HIGH_CONTRAST} borderColor={HIGH_CONTRAST.accent}>
+        <text>the theme prop beats the context</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff"],
+};

package/src/components/theme-context.tsx

@@ -0,0 +1,30 @@
+/**
+ * Provider theming for the component system (#86). The context default is the
+ * built-in dark theme, so embedding a component (or rendering a story) needs
+ * no provider at all. One ThemeProvider swap switches the live theme; every
+ * component also accepts an optional `theme` prop that overrides the context
+ * for explicit control. Components consume named tokens only - a hardcoded
+ * color inside components/ is a review rejection.
+ */
+
+import React, { createContext, useContext } from "react";
+import { DARK, type Theme } from "../theme";
+
+const ThemeContext = createContext<Theme>(DARK);
+
+export function ThemeProvider({ theme, children }: { theme: Theme; children: React.ReactNode }): React.ReactNode {
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): Theme {
+  return useContext(ThemeContext);
+}
+
+/**
+ * Token resolution for a component: the explicit `theme` prop wins over the
+ * provider context, which defaults to the built-in dark theme.
+ */
+export function useComponentTheme(override?: Theme): Theme {
+  const contextTheme = useContext(ThemeContext);
+  return override ?? contextTheme;
+}

package/src/key-bindings.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Binding resolution and hint generation over @opentui/keymap: config keys
+ * resolve to action names per layer, and the status-line hints derive from
+ * getActiveKeys() so rebinds surface in the hint text.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_KEYS } from "./config";
+import { KeyBindings } from "./key-bindings";
+
+function bindings(context: { overlay?: "none" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
+  const resolver = new KeyBindings(DEFAULT_KEYS);
+  resolver.setContext({ overlay: context.overlay ?? "none", spanMode: context.spanMode ?? false });
+  return resolver;
+}
+
+describe("grammar-layer resolution", () => {
+  const table: [name: string, shift: boolean, action: string | undefined][] = [
+    ["j", false, "down"],
+    ["down", false, "down"],
+    ["k", false, "up"],
+    ["g", false, "top"],
+    ["g", true, "bottom"],
+    ["v", false, "span"],
+    ["c", false, "comment"],
+    ["s", false, "suggest"],
+    ["x", false, "cut"],
+    ["e", false, "edit"],
+    ["n", false, "next_annotation"],
+    ["p", false, "prev_annotation"],
+    ["backspace", false, "delete_annotation"],
+    ["return", false, "submit"],
+    ["enter", false, "submit"],
+    ["q", false, "quit"],
+    ["z", false, undefined],
+  ];
+  for (const [name, shift, action] of table) {
+    test(`${shift ? "shift+" : ""}${name} -> ${action}`, () => {
+      expect(bindings().resolveAction({ name, shift })).toBe(action!);
+    });
+  }
+});
+
+describe("mode layers own their keys", () => {
+  test("span mode resolves the span verbs, not the grammar", () => {
+    const resolver = bindings({ spanMode: true });
+    expect(resolver.resolveAction({ name: "l", shift: false })).toBe("span_grow");
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBe("span_comment");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("span_cancel");
+  });
+
+  test("the compose overlay only knows save and cancel", () => {
+    const resolver = bindings({ overlay: "compose" });
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("save_compose");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("cancel_overlay");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+  });
+
+  test("the submit overlay adds the verdict arrows", () => {
+    const resolver = bindings({ overlay: "submit" });
+    expect(resolver.resolveAction({ name: "left", shift: false })).toBe("cycle_verdict_left");
+    expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
+  });
+});
+
+describe("getActiveKeys-generated status hints", () => {
+  test("normal mode hint matches the locked string", () => {
+    expect(bindings().statusHint("normal")).toBe(
+      "j/k move · v span · drag selects · c comment · s suggest · x cut · e edit · n/p annotations · ⏎ submit · q quit",
+    );
+  });
+
+  test("card-selected hint keeps the locked Cut label", () => {
+    expect(bindings().statusHint("card")).toBe("card · e edit · x Cut · n/p cards · esc deselect · ⏎ submit");
+  });
+
+  test("span hint", () => {
+    expect(bindings({ spanMode: true }).statusHint("span")).toBe(
+      "span · l/h grow/shrink · w/b slide · $ end · c comment · s suggest · esc",
+    );
+  });
+
+  test("compose hint", () => {
+    expect(bindings({ overlay: "compose" }).statusHint("compose")).toBe("typing · ⏎ save · esc cancel");
+  });
+
+  test("submit hint", () => {
+    expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe("verdict ←/→ · ⏎ submit · esc cancel");
+  });
+
+  test("read-only hint", () => {
+    expect(bindings().statusHint("read-only")).toBe("observer - read-only · j/k move · n/p annotations · q quit");
+  });
+
+  test("a rebound key shows its real binding in the hint", () => {
+    const resolver = new KeyBindings({ ...DEFAULT_KEYS, comment: ["m"] });
+    resolver.setContext({ overlay: "none", spanMode: false });
+    expect(resolver.resolveAction({ name: "m", shift: false })).toBe("comment");
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+    expect(resolver.statusHint("normal")).toContain("m comment");
+  });
+});

package/src/key-bindings.ts

@@ -0,0 +1,332 @@
+/**
+ * Binding resolution over @opentui/keymap (#86): the loaded config keymap
+ * registers as layers (grammar, span, compose, submit, completion) on one
+ * Keymap instance, key events resolve to action names through its dispatch,
+ * and the status-line hints generate from getActiveKeys() - a rebound key
+ * shows its real binding in the hints. The pure intent reducer (keymap.ts)
+ * stays the dispatch layer beneath: this module answers "which action", the
+ * reducer answers "which intents".
+ */
+
+import { Keymap, type KeymapEvent, type KeymapHost } from "@opentui/keymap";
+import { registerDefaultKeys } from "@opentui/keymap/addons";
+import type { KeyState } from "./keymap";
+
+export interface ResolvableKey {
+  name: string;
+  shift: boolean;
+}
+
+/** The layer-activation slice of the view state. */
+export interface KeyLayerContext {
+  overlay: KeyState["overlay"];
+  spanMode: boolean;
+}
+
+/** Hint templates keyed by the same view states the status line shows. */
+export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "read-only";
+
+type HintEntry =
+  | { text: string }
+  | { commands: string[]; label: string; labelFirst?: boolean };
+
+const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
+  normal: [
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["span"], label: "span" },
+    { text: "drag selects" },
+    { commands: ["comment"], label: "comment" },
+    { commands: ["suggest"], label: "suggest" },
+    { commands: ["cut"], label: "cut" },
+    { commands: ["edit"], label: "edit" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["submit"], label: "submit" },
+    { commands: ["quit"], label: "quit" },
+  ],
+  card: [
+    { text: "card" },
+    { commands: ["edit"], label: "edit" },
+    { commands: ["cut"], label: "Cut" },
+    { commands: ["next_annotation", "prev_annotation"], label: "cards" },
+    { commands: ["deselect"], label: "deselect" },
+    { commands: ["submit"], label: "submit" },
+  ],
+  span: [
+    { text: "span" },
+    { commands: ["span_grow", "span_shrink"], label: "grow/shrink" },
+    { commands: ["span_slide_forward", "span_slide_back"], label: "slide" },
+    { commands: ["span_to_end"], label: "end" },
+    { commands: ["span_comment"], label: "comment" },
+    { commands: ["span_suggest"], label: "suggest" },
+    { commands: ["span_cancel"], label: "" },
+  ],
+  compose: [
+    { text: "typing" },
+    { commands: ["save_compose"], label: "save" },
+    { commands: ["cancel_overlay"], label: "cancel" },
+  ],
+  submit: [
+    { commands: ["cycle_verdict_left", "cycle_verdict_right"], label: "verdict", labelFirst: true },
+    { commands: ["submit_verdict"], label: "submit" },
+    { commands: ["cancel_submit"], label: "cancel" },
+  ],
+  "read-only": [
+    { text: "observer - read-only" },
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["quit"], label: "quit" },
+  ],
+};
+
+/** Status-line glyphs for named keys. */
+const KEY_GLYPHS: Record<string, string> = {
+  return: "⏎",
+  enter: "⏎",
+  escape: "esc",
+  left: "←",
+  right: "→",
+  backspace: "⌫",
+  down: "↓",
+  up: "↑",
+};
+
+function makeKeymapEvent(name: string, shift = false): KeymapEvent {
+  return {
+    name,
+    ctrl: false,
+    shift,
+    meta: false,
+    preventDefault: () => {},
+    stopPropagation: () => {},
+    propagationStopped: false,
+  };
+}
+
+class HeadlessKeymapHost implements KeymapHost<object, KeymapEvent> {
+  readonly metadata = {
+    platform: "unknown" as const,
+    primaryModifier: "unknown" as const,
+    modifiers: {
+      ctrl: "supported" as const,
+      shift: "supported" as const,
+      meta: "supported" as const,
+      super: "unknown" as const,
+      hyper: "unknown" as const,
+    },
+  };
+  readonly rootTarget = {};
+  readonly isDestroyed = false;
+  private readonly pressListeners = new Set<(event: KeymapEvent) => void>();
+
+  getFocusedTarget(): object | null {
+    return null;
+  }
+  getParentTarget(): object | null {
+    return null;
+  }
+  isTargetDestroyed(): boolean {
+    return false;
+  }
+  onKeyPress(listener: (event: KeymapEvent) => void): () => void {
+    this.pressListeners.add(listener);
+    return () => this.pressListeners.delete(listener);
+  }
+  onKeyRelease(): () => void {
+    return () => {};
+  }
+  onFocusChange(): () => void {
+    return () => {};
+  }
+  onTargetDestroy(): () => void {
+    return () => {};
+  }
+  createCommandEvent(): KeymapEvent {
+    return makeKeymapEvent("");
+  }
+  emitKeyPress(event: KeymapEvent): void {
+    for (const listener of this.pressListeners) listener(event);
+  }
+}
+
+/**
+ * Terminal key events name shifted letters either "g"+shift or "G"; the
+ * keymap's canonical form is lowercase + the shift modifier. Non-letter
+ * single characters ("$", "0") already encode their shift in the character.
+ */
+function normalizedEvent(key: ResolvableKey): { name: string; shift: boolean } {
+  if (key.name.length === 1) {
+    if (/[a-zA-Z]/.test(key.name)) {
+      return { name: key.name.toLowerCase(), shift: key.shift || key.name !== key.name.toLowerCase() };
+    }
+    return { name: key.name, shift: false };
+  }
+  return { name: key.name, shift: key.shift };
+}
+
+/** Config combos write shifted letters as uppercase; the parser wants shift+. */
+function bindingKeyFor(combo: string): string {
+  if (combo.length === 1 && /[A-Z]/.test(combo)) return `shift+${combo.toLowerCase()}`;
+  return combo;
+}
+
+/** The grammar actions live in the base layer; these live in mode layers. */
+const SPAN_COMMANDS: [key: string, command: string][] = [
+  ["l", "span_grow"],
+  ["h", "span_shrink"],
+  ["w", "span_slide_forward"],
+  ["b", "span_slide_back"],
+  ["$", "span_to_end"],
+  ["0", "span_to_start"],
+  ["c", "span_comment"],
+  ["s", "span_suggest"],
+  ["escape", "span_cancel"],
+];
+
+export class KeyBindings {
+  private readonly host = new HeadlessKeymapHost();
+  private readonly keymap = new Keymap<object, KeymapEvent>(this.host);
+  private context: KeyLayerContext = { overlay: "none", spanMode: false };
+  private resolvedCommand: string | undefined;
+  private unregisterGrammarLayer: (() => void) | null = null;
+
+  constructor(keys: Record<string, string[]>) {
+    // the standard binding-string parser and event matcher
+    registerDefaultKeys(this.keymap);
+    // binding/layer `when` fields register runtime matchers, so getActiveKeys
+    // and dispatch only see the layer that owns the current mode
+    this.keymap.registerLayerFields({
+      when: (value, fieldContext) => {
+        if (typeof value === "function") fieldContext.activeWhen(value as () => boolean);
+      },
+    });
+    this.registerModeLayers();
+    this.setKeys(keys);
+  }
+
+  /** Rebuild the grammar layer from a (re)loaded config keymap. */
+  setKeys(keys: Record<string, string[]>): void {
+    this.unregisterGrammarLayer?.();
+    const bindings: { key: string; cmd: string }[] = [];
+    const commandNames = new Set<string>();
+    for (const [action, combos] of Object.entries(keys)) {
+      commandNames.add(action);
+      for (const combo of combos) bindings.push({ key: bindingKeyFor(combo), cmd: action });
+    }
+    // deselect is a hardwired escape in the plan grammar; hints show it
+    commandNames.add("deselect");
+    bindings.push({ key: "escape", cmd: "deselect" });
+    this.unregisterGrammarLayer = this.keymap.registerLayer({
+      priority: 0,
+      when: () => this.context.overlay === "none" && !this.context.spanMode,
+      bindings,
+      commands: [...commandNames].map((name) => ({
+        name,
+        run: () => {
+          this.resolvedCommand = name;
+          return true;
+        },
+      })),
+    });
+  }
+
+  private registerModeLayers(): void {
+    const record = (name: string) => ({
+      name,
+      run: () => {
+        this.resolvedCommand = name;
+        return true;
+      },
+    });
+    this.keymap.registerLayer({
+      priority: 10,
+      when: () => this.context.overlay === "none" && this.context.spanMode,
+      bindings: SPAN_COMMANDS.map(([key, command]) => ({ key, cmd: command })),
+      commands: SPAN_COMMANDS.map(([, command]) => record(command)),
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "compose",
+      bindings: [
+        { key: "return", cmd: "save_compose" },
+        { key: "enter", cmd: "save_compose" },
+        { key: "escape", cmd: "cancel_overlay" },
+      ],
+      commands: [record("save_compose"), record("cancel_overlay")],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "submit",
+      bindings: [
+        { key: "return", cmd: "submit_verdict" },
+        { key: "enter", cmd: "submit_verdict" },
+        { key: "left", cmd: "cycle_verdict_left" },
+        { key: "right", cmd: "cycle_verdict_right" },
+        { key: "escape", cmd: "cancel_submit" },
+      ],
+      commands: [
+        record("submit_verdict"),
+        record("cycle_verdict_left"),
+        record("cycle_verdict_right"),
+        record("cancel_submit"),
+      ],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "completion-prompt" || this.context.overlay === "completion-counting",
+      bindings: [
+        { key: "return", cmd: "finish_review" },
+        { key: "enter", cmd: "finish_review" },
+        { key: "q", cmd: "finish_review" },
+        { key: "a", cmd: "opt_in_auto_close" },
+        { key: "escape", cmd: "dismiss_completion" },
+      ],
+      commands: [record("finish_review"), record("opt_in_auto_close"), record("dismiss_completion")],
+    });
+  }
+
+  setContext(context: KeyLayerContext): void {
+    this.context = context;
+  }
+
+  /**
+   * Resolve a key event to its command name through the keymap's dispatch.
+   * In the base grammar layer the command IS the config action name, so the
+   * result feeds straight into the intent reducer.
+   */
+  resolveAction(key: ResolvableKey): string | undefined {
+    const normalized = normalizedEvent(key);
+    this.resolvedCommand = undefined;
+    this.host.emitKeyPress(makeKeymapEvent(normalized.name, normalized.shift));
+    return this.resolvedCommand;
+  }
+
+  /** First active key display for a command, mapped through the glyph table. */
+  private keyDisplayFor(command: string): string | null {
+    for (const activeKey of this.keymap.getActiveKeys({ includeBindings: true })) {
+      const bindingCommand =
+        typeof activeKey.command === "string" ? activeKey.command : activeKey.bindings?.[0]?.command;
+      if (bindingCommand !== command) continue;
+      return KEY_GLYPHS[activeKey.stroke.name] ?? activeKey.display;
+    }
+    return null;
+  }
+
+  /** The status-line hint for a view state, generated from the active keys. */
+  statusHint(mode: HintMode): string {
+    const fragments: string[] = [];
+    for (const entry of HINT_TEMPLATES[mode]) {
+      if ("text" in entry) {
+        fragments.push(entry.text);
+        continue;
+      }
+      const displays = entry.commands
+        .map((command) => this.keyDisplayFor(command))
+        .filter((display): display is string => display !== null);
+      if (!displays.length) continue;
+      const keyPart = displays.join("/");
+      if (!entry.label) fragments.push(keyPart);
+      else fragments.push(entry.labelFirst ? `${entry.label} ${keyPart}` : `${keyPart} ${entry.label}`);
+    }
+    return fragments.join(" · ");
+  }
+}

package/src/keymap.ts

@@ -64,7 +64,13 @@ function status(msg: string): Intent[] {
   return [{ t: "status", msg }];
 }
 
-export function reduceKey(state: KeyState, key: KeyInput): Intent[] {
+/**
+ * Reduce one key event to intents. `resolvedAction` is the binding-layer
+ * resolution (key-bindings.ts over @opentui/keymap) when the caller has one;
+ * without it the reducer falls back to the plain reverse lookup, so the
+ * grammar stays testable as a pure function.
+ */
+export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: string): Intent[] {
   const name = key.name;
   // compose/submit overlays own the keys via focused inputs; only escape,
   // return, and verdict arrows route through the grammar
@@ -84,7 +90,7 @@ export function reduceKey(state: KeyState, key: KeyInput): Intent[] {
     if (name === "escape") return [{ t: "dismissCompletion" }];
     return [];
   }
-  const action = actionFor(state.keys, name, key.shift);
+  const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
   if (action === "quit") return [{ t: "exit" }];
   // the ONE read-only rule: any mutating attempt answers instead of acting
   // (span-mode c/s are hardwired keys, so they gate by name as well)

package/src/run.ts

@@ -22,7 +22,9 @@ export async function runClient(opts: RunClientOptions): Promise<number> {
         onExit: (code: number) => {
           renderer.destroy();
           resolve(code);
-          process.exit(code);
+          // one microtask between destroy and exit lets the renderer flush
+          // its terminal-restore sequences before the process dies
+          queueMicrotask(() => process.exit(code));
         },
       }),
     );