@visual-z/xeno 0.2.0 → 0.3.0

package/src/tui/ui/composer.ts

@@ -0,0 +1,199 @@
+/**
+ * The one editor (D20). It lives inside the input box at the bottom of the
+ * screen and is never recreated: pickers and forms open in the same box
+ * above it and give focus back, so the draft, undo history and cursor stay
+ * (docs/tasks/refactor-tui-dock-layout.md DoD 1). Typing, undo and paste are
+ * OpenTUI's; submission and history are the app's.
+ *
+ * Completion is state here and drawn by the screen above the box, where it
+ * takes layout space instead of covering the transcript.
+ */
+import { BoxRenderable, type CliRenderer } from "@opentui/core";
+import { AtomicDraftArea, type DraftAtom } from "./atomic-draft.ts";
+import { Canvas } from "./canvas.ts";
+import type { UiColors } from "./colors.ts";
+import { draftRows, type DraftRows } from "./draft.ts";
+import type { ListItem } from "./list-model.ts";
+
+export interface Completion {
+  /** Replace text[start, end) with an item's value. */
+  readonly start: number;
+  readonly end: number;
+  readonly items: readonly ListItem[];
+}
+
+/**
+ * The tallest the draft grows before it scrolls inside the box: a third of
+ * the terminal, at least 5 rows. Peers cap by screen fraction rather than a
+ * constant (pi 30% min 5, OpenCode ⅓ min 6, Grok ½, Codex ⅔); a third keeps
+ * most of the transcript in view while a paragraph still fits.
+ */
+export function draftMaxLines(terminalRows: number): number {
+  return Math.max(5, Math.floor(terminalRows / 3));
+}
+const MAX_LINES = 5;
+export const PLACEHOLDER = "What would you like to work on?";
+
+/**
+ * The textarea, plus a hook after each of its frames. The editor scrolls to
+ * its cursor while it renders, and its own render() skips renderAfter, so
+ * this is the one place the visible part of a tall draft is known.
+ */
+export class Composer {
+  /** `›` and the editor. Its height is the editor's own measurement of the wrapped draft. */
+  readonly row: BoxRenderable;
+  readonly area: AtomicDraftArea;
+  private draftRevision = 0;
+  private readonly prompt: Canvas;
+  private completion: Completion | undefined;
+  private completionIndex = 0;
+  private history: string[] = [];
+  private historyAt = -1;
+  private historyDraft = "";
+  private maxLines = MAX_LINES;
+  private shape: DraftRows = { rows: 1, above: 0, below: 0 };
+  onChange: ((text: string) => void) | undefined;
+  onCursor: (() => void) | undefined;
+  /** The row count changed (the box above must re-layout). */
+  onResize: (() => void) | undefined;
+  /** Rows hidden above or below the visible draft changed (the box edge shows them). */
+  onOverflow: (() => void) | undefined;
+
+  constructor(renderer: CliRenderer, colors: UiColors) {
+    this.row = new BoxRenderable(renderer, { id: "composer", flexDirection: "row", flexShrink: 0 });
+    this.prompt = new Canvas(renderer, { id: "composer-prompt", width: 2, height: 1, flexShrink: 0, colors });
+    this.prompt.setRows([[{ text: "›", role: "accent", bold: true }]]);
+    const area = new AtomicDraftArea(renderer, {
+      id: "composer-area", flexGrow: 1, minHeight: 1, maxHeight: MAX_LINES, wrapMode: "word",
+      textColor: colors.text, focusedTextColor: colors.text, backgroundColor: "transparent", focusedBackgroundColor: "transparent",
+      selectionBg: colors.selectionBg, selectionFg: colors.selectionFg,
+      placeholder: PLACEHOLDER, placeholderColor: colors.muted,
+      // Enter, Shift+Enter, Up/Down are the app's (submit, history); remove them from the textarea.
+      keyBindings: [{ name: "return", action: "move-left" }, { name: "_", ctrl: true, action: "undo" }, { name: "/", ctrl: true, action: "undo" }],
+    });
+    this.area = area;
+    // Height comes from the editor's native measurement of its wrapped text, capped by
+    // maxHeight (the way OpenCode's prompt grows). Nothing here sets a height, so width
+    // changes re-wrap and re-measure on their own (fix-tui-composer-growth).
+    this.area.onContentChange = () => { this.draftRevision++; this.onChange?.(this.text); };
+    this.area.onCursorChange = () => { this.draftRevision++; this.onCursor?.(); };
+    this.area.onSizeChange = () => this.measured();
+    // Which rows scrolled out of a tall draft is known only after the editor drew itself.
+    area.onRendered = () => this.measured();
+    this.row.add(this.prompt); this.row.add(this.area);
+  }
+
+  get text(): string { return this.area.plainText; }
+  get cursor(): number { return this.area.textCursor; }
+  get revision(): number { return this.draftRevision; }
+  setAtoms(spans: (text: string) => readonly DraftAtom[]): void { this.area.atoms = spans; }
+  get completing(): boolean { return this.completion !== undefined && this.completion.items.length > 0; }
+  /** What the completion list shows (screen draws it). */
+  get completionView(): { readonly items: readonly ListItem[]; readonly selected: number } | undefined {
+    return this.completion ? { items: this.completion.items, selected: this.completionIndex } : undefined;
+  }
+  get historyEntries(): readonly string[] { return this.history; }
+  get rows(): number { return Math.max(1, this.area.height); }
+  /** Wrapped rows of the draft hidden above / below the box (0 when it all fits). */
+  get overflow(): { readonly above: number; readonly below: number } { return { above: this.shape.above, below: this.shape.below }; }
+
+  setColors(colors: UiColors): void {
+    this.area.textColor = colors.text;
+    this.area.focusedTextColor = colors.text;
+    this.area.placeholderColor = colors.muted;
+    this.area.selectionBg = colors.selectionBg;
+    this.area.selectionFg = colors.selectionFg;
+    this.prompt.setColors(colors);
+  }
+
+  setText(text: string): void {
+    this.draftRevision++;
+    this.area.setText(text);
+    this.area.gotoBufferEnd();
+  }
+
+  insert(text: string): void { this.draftRevision++; this.area.insertText(text); }
+  removeAtom(label: string): void { this.draftRevision++; this.area.replaceText(this.text.split(label).join("")); }
+  resetDraft(project: (text: string) => string): void {
+    this.history = this.history.map(project).filter(Boolean);
+    this.historyAt = -1; this.historyDraft = ""; this.area.clearKilledText(); this.setText("");
+  }
+  focus(): void { this.area.focus(); }
+
+  remember(entry: string): void {
+    if (!entry.trim()) return;
+    if (this.history[0] !== entry) this.history.unshift(entry);
+    this.history = this.history.slice(0, 200);
+    this.historyAt = -1;
+  }
+
+  /** Up/Down walk history only when the cursor is on the first/last line, so multi-line drafts stay editable. */
+  historyStep(direction: -1 | 1): boolean {
+    const text = this.area.plainText;
+    const offset = this.area.cursorOffset;
+    const firstLine = !text.slice(0, offset).includes("\n");
+    const lastLine = !text.slice(offset).includes("\n");
+    if (direction < 0 && !firstLine) return false;
+    if (direction > 0 && !lastLine) return false;
+    if (direction < 0) {
+      if (this.historyAt + 1 >= this.history.length) return true;
+      if (this.historyAt === -1) this.historyDraft = text;
+      this.historyAt++;
+      this.setText(this.history[this.historyAt]!);
+      return true;
+    }
+    if (this.historyAt < 0) return false;
+    this.historyAt--;
+    this.setText(this.historyAt < 0 ? this.historyDraft : this.history[this.historyAt]!);
+    return true;
+  }
+
+  setCompletion(completion: Completion | undefined): void {
+    const next = completion && completion.items.length ? completion : undefined;
+    if (!next && !this.completion) return;
+    this.completion = next;
+    this.completionIndex = 0;
+    this.onResize?.();
+  }
+  moveCompletion(delta: number): void {
+    if (!this.completion) return;
+    const n = this.completion.items.length;
+    this.completionIndex = (this.completionIndex + delta + n) % n;
+    this.onResize?.();
+  }
+  /** Apply the selected completion; returns the applied item. */
+  acceptCompletion(): ListItem | undefined {
+    const completion = this.completion;
+    const item = completion?.items[this.completionIndex];
+    if (!completion || !item) return undefined;
+    const text = this.area.plainText;
+    this.area.setText(text.slice(0, completion.start) + item.value + text.slice(completion.end));
+    this.area.cursorOffset = completion.start + item.value.length;
+    this.setCompletion(undefined);
+    return item;
+  }
+
+  /** The tallest the draft may grow, so the box never pushes the transcript off a short screen. */
+  /** The screen's limit for this terminal size (draftMaxLines, then whatever space is left). */
+  setMaxLines(lines: number): void {
+    const next = Math.max(1, Math.floor(lines));
+    if (next === this.maxLines) return;
+    this.maxLines = next;
+    this.area.maxHeight = next;
+  }
+
+  /**
+   * After layout or a frame: report a new height and what scrolled out of
+   * view. `virtualLineCount` is only the viewport's visible rows (always 1 in
+   * a one-row box, which is how the box used to stay one row); the editor
+   * view's total is the whole wrapped draft. Writes only on change, so a
+   * quiet frame costs two native reads.
+   */
+  private measured(): void {
+    const next = draftRows(this.area.editorView.getTotalVirtualLineCount(), this.area.scrollY, Math.max(1, Math.min(this.maxLines, this.area.height || 1)));
+    const previous = this.shape;
+    this.shape = next;
+    if (next.rows !== previous.rows) this.onResize?.();
+    if (next.above !== previous.above || next.below !== previous.below) this.onOverflow?.();
+  }
+}

package/src/tui/ui/dialog.ts

@@ -0,0 +1,379 @@
+/**
+ * Dialogs open inside the input box, stacked (docs/tasks/refactor-tui-dock-layout.md).
+ * Escape pops one level (back); popping the last returns focus to the editor.
+ *
+ * The box keeps its place at the bottom and grows upward; the dialog's
+ * title and any non-obvious keys go into the box's top edge (`title`,
+ * `edgeHint`), so there is no separate frame or hint row. Every picker and
+ * form in the app is one of these kinds:
+ *   list     grouped rows (+ checkboxes), search on the input row, action keys
+ *   form     one text field; `secret` keeps the value out of every renderable
+ *   confirm  yes / no
+ *   message  read-only lines (ANSI allowed)
+ *   busy     the activity glyph while the app awaits IO
+ *   lines    an app- or extension-rendered block with its own key handler
+ */
+import { BoxRenderable, InputRenderable, TextRenderable, type CliRenderer, type Renderable } from "@opentui/core";
+import { Canvas } from "./canvas.ts";
+import type { UiColors } from "./colors.ts";
+import { bound, type Bindings, type KeyPress } from "./keys.ts";
+import type { ListItem } from "./list-model.ts";
+import { ListView } from "./list-view.ts";
+import { ansiText, parts } from "./styled.ts";
+
+export interface ListAction { readonly key: string; readonly label: string; run(item: ListItem | undefined, dialog: ListHandle): void | Promise<void> }
+export interface ListHandle { setItems(items: readonly ListItem[], selected?: string): void; readonly current: ListItem | undefined; readonly checked: ReadonlySet<string>; readonly query: string }
+
+export type DialogSpec =
+  | { kind: "list"; title: string; items: readonly ListItem[]; selected?: string; multi?: boolean; checked?: readonly string[]; search?: boolean; placeholder?: string; empty?: string; rows?: number;
+      /** Lines above the list (approval command, context). ANSI allowed. */
+      intro?: readonly string[];
+      /** Stay on the stack after a pick, so a drill-down's Esc returns here. */
+      keep?: boolean;
+      /** The box border colour: "warning" for decisions that run something (approval). */
+      tone?: "warning";
+      hint?: string; actions?: readonly ListAction[]; onPick?(item: ListItem, dialog: ListHandle): void | Promise<void>;
+      onSubmitChecked?(values: string[]): void | Promise<void>; onMove?(item: ListItem | undefined): void; onCancel?(): void }
+  | { kind: "form"; title: string; label: string; value?: string; secret?: boolean; hint?: string; intro?: readonly string[]; keep?: boolean; validate?(value: string): string | undefined; onSubmit(value: string): void | Promise<void>; onCancel?(): void }
+  | { kind: "confirm"; title: string; message: string; yes?: string; no?: string; onAnswer(yes: boolean): void | Promise<void> }
+  | { kind: "message"; title: string; lines: readonly string[]; onDone?(): void | Promise<void> }
+  | { kind: "busy"; title: string; message: string; onCancel?(): void }
+  | { kind: "lines"; title: string; render(width: number): string[]; handleKey?(key: KeyPress): boolean | Promise<boolean>; hint?: string; onCancel?(): void };
+
+interface Open {
+  spec: DialogSpec;
+  list?: ListView;
+  input?: InputRenderable;
+  secret?: string;
+  error?: string | undefined;
+  yes?: boolean;
+}
+
+/**
+ * Hint clauses everyone already knows (Enter confirms, Esc goes back, arrows
+ * move). Only the rest earns a place on the edge (refactor-tui-chrome-cleanup).
+ */
+const OBVIOUS = /^(enter|esc|↑↓|←→|↑|↓)\b/;
+export function edgeHint(hint: string | undefined): string {
+  return (hint ?? "").split(" · ").map(clause => clause.trim()).filter(clause => clause && !OBVIOUS.test(clause)).join(" · ");
+}
+
+let serial = 0;
+
+export class DialogHost {
+  private readonly renderer: CliRenderer;
+  private colors: UiColors;
+  private readonly bindings: () => Bindings;
+  private readonly slot: BoxRenderable;
+  private readonly availableRows: () => number;
+  private readonly glyph: () => string;
+  private stack: Open[] = [];
+  private readonly work = new Set<Promise<unknown>>();
+  /** Nodes built for the current view; persistent ones (lists, inputs) live on their Open. */
+  private ephemeral: Renderable[] = [];
+  private shownTitle = "";
+  private shownHint = "";
+  onOpened: (() => void) | undefined;
+  /** Called when the stack becomes empty (focus returns to the editor). */
+  onClosed: (() => void) | undefined;
+  /** Title, hint or tone changed: the box edge repaints. */
+  onChrome: (() => void) | undefined;
+  /** Errors thrown by dialog callbacks, surfaced by the app as notices. */
+  onError: ((error: unknown) => void) | undefined;
+
+  constructor(renderer: CliRenderer, colors: UiColors, bindings: () => Bindings, slot: BoxRenderable, availableRows: () => number, glyph: () => string = () => "●") {
+    this.renderer = renderer;
+    this.colors = colors;
+    this.bindings = bindings;
+    this.slot = slot;
+    this.availableRows = availableRows;
+    this.glyph = glyph;
+  }
+
+  get open(): boolean { return this.stack.length > 0; }
+  get busy(): boolean { return this.work.size > 0; }
+  /** Resolves when every callback started by a key has finished (tests, shutdown). */
+  async idle(): Promise<void> { while (this.work.size) await Promise.all([...this.work]); }
+  get depth(): number { return this.stack.length; }
+  get top(): DialogSpec | undefined { return this.stack.at(-1)?.spec; }
+  /** The list of the top dialog, for callers that update it after async loads. */
+  get list(): ListHandle | undefined { return this.stack.at(-1)?.list; }
+  /** The top list's view (tests read its drawn rows). */
+  get listView(): ListView | undefined { return this.stack.at(-1)?.list; }
+  /** What the box's top edge shows while a dialog is open. */
+  get title(): string { return this.shownTitle; }
+  get edgeHint(): string { return this.shownHint; }
+  get tone(): "warning" | undefined { const spec = this.top; return spec?.kind === "list" ? spec.tone : undefined; }
+  /** A busy dialog shows the activity glyph, which needs the clock running. */
+  get animated(): boolean { return this.top?.kind === "busy"; }
+
+  setColors(colors: UiColors): void {
+    this.colors = colors;
+    for (const open of this.stack) {
+      open.list?.setColors(colors);
+      if (open.input) { open.input.textColor = colors.text; open.input.focusedTextColor = colors.text; open.input.placeholderColor = colors.muted; }
+    }
+    if (this.open) this.show();
+  }
+
+  dispose(): void { this.clearView(); }
+
+  push(spec: DialogSpec, replace = false): void {
+    if (replace) this.stack.pop();
+    this.stack.push(this.build(spec));
+    this.onOpened?.();
+    this.show();
+  }
+
+  /** Replace the whole stack (e.g. after a save there is nothing to go back to). */
+  reset(spec: DialogSpec): void { this.stack = []; this.push(spec); }
+
+  pop(): void {
+    const top = this.stack.pop();
+    if (top) {
+      const spec = top.spec;
+      if ((spec.kind === "list" || spec.kind === "form" || spec.kind === "busy" || spec.kind === "lines") && spec.onCancel) this.guard(() => spec.onCancel!());
+      if (spec.kind === "confirm") this.guard(() => spec.onAnswer(false));
+    }
+    this.show();
+  }
+
+  /** Remove one dialog by its spec without running its callbacks (an extension request that timed out). */
+  remove(spec: DialogSpec): void {
+    const at = this.stack.findIndex(open => open.spec === spec);
+    if (at < 0) return;
+    this.stack.splice(at, 1);
+    this.show();
+  }
+
+  /**
+   * Close everything (session switch, shutdown). Cancel callbacks run, top
+   * first, so anything awaiting an answer resolves as "cancelled" instead of
+   * hanging forever.
+   */
+  clear(): void {
+    const open = this.stack.reverse();
+    this.stack = [];
+    for (const entry of open) {
+      const spec = entry.spec;
+      if ((spec.kind === "list" || spec.kind === "form" || spec.kind === "busy" || spec.kind === "lines") && spec.onCancel) void this.guard(() => spec.onCancel!());
+      if (spec.kind === "confirm") void this.guard(() => spec.onAnswer(false));
+    }
+    this.show();
+  }
+
+  /** Rebuild the top dialog's view (after its spec's data changed). */
+  refresh(): void { if (this.open) this.show(); }
+
+  private build(spec: DialogSpec): Open {
+    const open: Open = { spec };
+    if (spec.kind === "list") {
+      const list = new ListView(this.renderer, { colors: this.colors, ...(spec.rows ? { rows: spec.rows } : {}), search: spec.search !== false, multi: spec.multi ?? false,
+        ...(spec.placeholder ? { placeholder: spec.placeholder } : {}), ...(spec.empty ? { empty: spec.empty } : {}) });
+      for (const value of spec.checked ?? []) list.checked.add(value);
+      list.setItems(spec.items, spec.selected);
+      list.onChange = () => { spec.onMove?.(list.current); this.paintChrome(); };
+      open.list = list;
+    }
+    if (spec.kind === "form" && !spec.secret) {
+      open.input = new InputRenderable(this.renderer, { id: `dialog-input-${serial++}`, value: spec.value ?? "", textColor: this.colors.text,
+        focusedTextColor: this.colors.text, backgroundColor: "transparent", focusedBackgroundColor: "transparent", flexGrow: 1 });
+      // Prefilled values are edited from their end (a URL gets a path appended).
+      open.input.gotoBufferEnd();
+    }
+    if (spec.kind === "form" && spec.secret) open.secret = "";
+    if (spec.kind === "confirm") open.yes = true;
+    return open;
+  }
+
+  /** Re-fit the top list to the rows the screen can spare. */
+  layout(): void {
+    const top = this.stack.at(-1);
+    if (top?.spec.kind !== "list") return;
+    const overhead = (top.spec.search === false ? 0 : 2) + (top.spec.intro?.length ? introRows(top.spec.intro) + 1 : 0);
+    top.list?.setRowLimit(Math.min(top.spec.rows ?? 10, Math.max(1, this.availableRows() - overhead)));
+  }
+
+  private clearView(): void {
+    for (const child of this.slot.getChildren()) this.slot.remove(child);
+    for (const node of this.ephemeral) node.destroyRecursively();
+    this.ephemeral = [];
+  }
+
+  private add(node: Renderable): void { this.ephemeral.push(node); this.slot.add(node); }
+
+  private show(): void {
+    this.clearView();
+    const top = this.stack.at(-1);
+    if (!top) {
+      this.slot.visible = false;
+      this.shownTitle = ""; this.shownHint = "";
+      this.onClosed?.();
+      this.onChrome?.();
+      this.renderer.requestRender();
+      return;
+    }
+    this.slot.visible = true;
+    const c = this.colors, spec = top.spec;
+    const text = (content: ReturnType<typeof parts>, extra: Record<string, unknown> = {}) => new TextRenderable(this.renderer, { id: `dialog-text-${serial++}`, content, wrapMode: "word", ...extra });
+    const canvas = (rows: Parameters<Canvas["setRows"]>[0]) => { const node = new Canvas(this.renderer, { id: `dialog-canvas-${serial++}`, height: rows.length, colors: c, glyph: this.glyph }); node.setRows(rows); return node; };
+    switch (spec.kind) {
+      case "list": {
+        if (spec.intro?.length) this.add(text(ansiText(spec.intro), { marginBottom: 1 }));
+        this.slot.add(top.list!);
+        this.layout();
+        top.list!.searchInput?.focus();
+        if (!top.list!.searchInput) this.renderer.currentFocusedRenderable?.blur();
+        break;
+      }
+      case "form": {
+        if (spec.intro?.length) this.add(text(ansiText(spec.intro), { marginBottom: 1 }));
+        const row = new BoxRenderable(this.renderer, { id: `form-row-${serial++}`, flexDirection: "row", height: 1 });
+        row.add(new TextRenderable(this.renderer, { id: `form-label-${serial++}`, content: parts({ text: `${spec.label} › `, fg: c.muted }), flexShrink: 0 }));
+        if (top.input) { row.add(top.input); top.input.focus(); }
+        else {
+          // The secret never reaches a renderable: only its length does.
+          const mask = canvas([[{ text: "•".repeat(Math.min(top.secret!.length, 48)), role: "text" }, { text: "▏", role: "accent" }]]);
+          mask.flexGrow = 1;
+          row.add(mask);
+          this.renderer.currentFocusedRenderable?.blur();
+        }
+        this.add(row);
+        if (top.error) this.add(text(parts({ text: top.error, fg: c.error })));
+        break;
+      }
+      case "confirm":
+        this.add(text(parts({ text: spec.message, fg: c.text })));
+        // The choice is marked by shape and weight; nothing is painted behind it.
+        this.add(canvas([[
+          { text: top.yes ? "▸ " : "  ", role: "accent", bold: true }, { text: spec.yes ?? "Yes", role: top.yes ? "accent" : "text", bold: top.yes === true },
+          { text: "    ", role: "text" },
+          { text: !top.yes ? "▸ " : "  ", role: "accent", bold: true }, { text: spec.no ?? "No", role: !top.yes ? "accent" : "text", bold: top.yes !== true },
+        ]]));
+        this.renderer.currentFocusedRenderable?.blur();
+        break;
+      case "message":
+        this.add(text(ansiText(spec.lines)));
+        this.renderer.currentFocusedRenderable?.blur();
+        break;
+      case "busy":
+        this.add(canvas([[{ text: "●", role: "accent", spin: true }, { text: ` ${spec.message.split("\n")[0] ?? ""}`, role: "text" }]]));
+        if (spec.message.includes("\n")) this.add(text(parts({ text: spec.message.split("\n").slice(1).join("\n"), fg: c.muted })));
+        this.renderer.currentFocusedRenderable?.blur();
+        break;
+      case "lines": {
+        const width = Math.max(10, this.renderer.width - 8);
+        this.add(text(ansiText(this.guardRender(() => spec.render(width))), { wrapMode: "none" }));
+        this.renderer.currentFocusedRenderable?.blur();
+        break;
+      }
+    }
+    this.paintChrome();
+    this.renderer.requestRender();
+  }
+
+  private paintChrome(): void {
+    const top = this.stack.at(-1);
+    const spec = top?.spec;
+    let hint = "";
+    if (spec?.kind === "list") {
+      const keys = (spec.actions ?? []).map(action => `${action.key} ${action.label}`);
+      hint = [edgeHint(spec.hint), ...(spec.hint ? [] : [...(spec.multi ? ["space toggle"] : []), ...keys]), top!.list!.scrollPosition].filter(Boolean).join(" · ");
+    } else if (spec?.kind === "form" || spec?.kind === "lines") hint = edgeHint(spec.hint);
+    const title = spec?.title ?? "";
+    if (title === this.shownTitle && hint === this.shownHint) return;
+    this.shownTitle = title; this.shownHint = hint;
+    this.onChrome?.();
+  }
+
+  /** Paste goes to the focused Input natively; a secret form takes it here. */
+  paste(text: string): boolean {
+    const top = this.stack.at(-1);
+    if (!top) return false;
+    if (top.secret !== undefined) { top.secret += text.replace(/[\r\n]+/g, ""); top.error = undefined; this.show(); return true; }
+    return top.input !== undefined || top.list?.searchInput !== undefined;
+  }
+
+  /** Returns true when the key was consumed (the caller then stops propagation). Synchronous so
+   * the caller can preventDefault inside the key event; callbacks run as tracked work. */
+  key(key: KeyPress): boolean {
+    const top = this.stack.at(-1);
+    if (!top) return false;
+    const b = this.bindings();
+    const spec = top.spec;
+    const run = (action: () => unknown) => { const job = this.guard(action).finally(() => { this.work.delete(job); this.refreshIfTop(top); }); this.work.add(job); };
+    const leave = () => { const at = this.stack.indexOf(top); if (at >= 0) this.stack.splice(at, 1); this.show(); };
+    if (bound(b, "list.cancel", key) || key.chord === "escape") { this.pop(); return true; }
+    switch (spec.kind) {
+      case "list": {
+        const list = top.list!;
+        if (bound(b, "list.up", key)) { list.move(-1); return true; }
+        if (bound(b, "list.down", key)) { list.move(1); return true; }
+        if (bound(b, "list.pageUp", key)) { list.page(-1); return true; }
+        if (bound(b, "list.pageDown", key)) { list.page(1); return true; }
+        if (spec.multi && bound(b, "list.toggle", key)) { list.toggle(); return true; }
+        if (spec.multi && key.chord === "ctrl+a") { list.toggleAllVisible(); return true; }
+        const action = spec.actions?.find(entry => entry.key === key.chord);
+        if (action) { run(() => action.run(list.current, list)); return true; }
+        if (bound(b, "list.confirm", key)) {
+          if (spec.multi) { const values = [...list.checked]; if (!spec.keep) leave(); run(() => spec.onSubmitChecked?.(values)); return true; }
+          const item = list.current;
+          // The dialog leaves the stack before its callback runs, so a callback
+          // that opens another dialog (or closes everything) wins.
+          if (item && !item.disabled) { if (!spec.keep) leave(); run(() => spec.onPick?.(item, list)); }
+          return true;
+        }
+        return false; // printable keys reach the focused search Input
+      }
+      case "form": {
+        if (key.chord === "enter") {
+          const value = (top.input ? top.input.value : top.secret!).trim();
+          const error = spec.validate?.(value);
+          if (error) { top.error = error; this.show(); return true; }
+          if (!spec.keep) leave();
+          run(() => spec.onSubmit(value));
+          return true;
+        }
+        if (top.secret !== undefined) {
+          if (key.chord === "backspace") top.secret = top.secret.slice(0, -1);
+          else if (key.chord === "ctrl+u") top.secret = "";
+          else if (key.text) top.secret += key.text;
+          else return true;
+          top.error = undefined;
+          this.show();
+          return true;
+        }
+        if (top.error) { top.error = undefined; this.show(); }
+        return false;
+      }
+      case "confirm":
+        if (["left", "right", "tab", "h", "l"].includes(key.chord)) { top.yes = !top.yes; this.show(); return true; }
+        if (key.chord === "y" || key.chord === "n" || key.chord === "enter") {
+          const yes = key.chord === "enter" ? top.yes! : key.chord === "y";
+          leave();
+          run(() => spec.onAnswer(yes));
+        }
+        return true;
+      case "message":
+        if (key.chord === "enter") { leave(); run(() => spec.onDone?.()); }
+        return true;
+      case "busy":
+        return true;
+      case "lines":
+        if (spec.handleKey) run(() => spec.handleKey!(key));
+        return true;
+    }
+  }
+
+  private refreshIfTop(open: Open): void { if (this.stack.at(-1) === open) this.show(); }
+
+  private async guard<T>(run: () => T | Promise<T>): Promise<T | undefined> {
+    try { return await run(); } catch (error) { this.onError?.(error); return undefined; }
+  }
+  private guardRender(run: () => string[]): string[] {
+    try { return run(); } catch (error) { this.onError?.(error); return ["(this block failed to render)"]; }
+  }
+}
+
+/** Rows an intro block takes before wrapping (wrapping only adds rows; the list shrinks to fit). */
+function introRows(intro: readonly string[]): number { return intro.length; }

package/src/tui/ui/draft.ts

@@ -0,0 +1,23 @@
+/**
+ * How tall the draft is and what scrolled out of it (docs/tasks/fix-tui-composer-growth.md). Pure.
+ *
+ * `total` is the draft's wrapped row count, `offset` the editor's first
+ * visible row, `max` the tallest the box may grow. The box shows
+ * min(total, max) rows; whatever does not fit is reported on the box's top
+ * edge as "↑ N more" / "↓ N more", the way pi marks a scrolled editor.
+ */
+export interface DraftRows {
+  /** Rows the editor occupies. */
+  readonly rows: number;
+  /** Wrapped rows hidden above the visible part. */
+  readonly above: number;
+  /** Wrapped rows hidden below it. */
+  readonly below: number;
+}
+
+export function draftRows(total: number, offset: number, max: number): DraftRows {
+  const t = Math.max(1, Math.floor(total) || 1), m = Math.max(1, Math.floor(max) || 1);
+  const rows = Math.min(t, m);
+  const above = Math.max(0, Math.min(Math.floor(offset) || 0, t - rows));
+  return { rows, above, below: t - rows - above };
+}