@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/components/wizard-step.ts

@@ -1,5 +1,9 @@
 import type { MouseRoutable, SgrMouseEvent } from "../mouse";
+import { col } from "../native/describe";
+import { sameItems } from "../native/memo";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
+import { spaceForRows } from "./spacer";
 
 /** Semantic role of a wizard step's primary interactive content. */
 export type WizardStepKind = "input" | "choice" | "confirm" | "async" | "custom";
@@ -37,14 +41,6 @@ function isMouseRoutable(component: Component): component is Component & MouseRo
 	return "routeMouse" in component && typeof component.routeMouse === "function";
 }
 
-function sameLines(left: readonly string[], right: readonly string[]): boolean {
-	if (left.length !== right.length) return false;
-	for (let i = 0; i < left.length; i++) {
-		if (left[i] !== right[i]) return false;
-	}
-	return true;
-}
-
 /**
  * Reusable presentation for input, choice, confirmation, and asynchronous
  * wizard steps. Controllers retain state transitions; this component owns the
@@ -68,6 +64,7 @@ export class WizardStep implements Component, MouseRoutable {
 	#contentRowStart = -1;
 	#contentRowCount = 0;
 	#cachedLines: readonly string[] | undefined;
+	#native: { slots: readonly Component[]; node: NativeNode } | undefined;
 
 	constructor(options: WizardStepOptions) {
 		this.#kind = options.kind;
@@ -163,6 +160,18 @@ export class WizardStep implements Component, MouseRoutable {
 		content.routeMouse(event, line - this.#contentRowStart, col);
 	}
 
+	/**
+	 * The slots in order as a spaced `col`; the height budget and optional
+	 * preview collapse are the terminal's (it scrolls instead of clipping).
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const slots = this.debugChildren;
+		if (sameItems(this.#native?.slots, slots)) return this.#native!.node;
+		const described = col(slots, { gap: spaceForRows(this.#gap) });
+		this.#native = { slots, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		const safeWidth = Math.max(1, width);
 		const gap = this.#gap;
@@ -217,7 +226,7 @@ export class WizardStep implements Component, MouseRoutable {
 			lines.push(...slot.lines);
 		}
 		const bounded = maxHeight === undefined || lines.length <= maxHeight ? lines : lines.slice(0, maxHeight);
-		if (this.#cachedLines && sameLines(this.#cachedLines, bounded)) return this.#cachedLines;
+		if (this.#cachedLines && sameItems(this.#cachedLines, bounded)) return this.#cachedLines;
 		this.#cachedLines = bounded;
 		return bounded;
 	}

package/src/debug-server.ts

@@ -1,7 +1,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
 import { type Component, isFocusable, type OverlayOptions, type TUI } from "./tui";
-import { replaceTabs } from "./utils";
+import { plainText } from "./native/spans";
 
 export interface TuiDebugTreeNode {
 	kind: string;
@@ -63,10 +63,6 @@ const SPECIAL_KEYS: Readonly<Record<string, string>> = {
 	f12: "\x1b[24~",
 };
 
-function plainLine(line: string): string {
-	return replaceTabs(Bun.stripANSI(line)).replace(/[\x00-\x1f\x7f-\x9f]/g, "");
-}
-
 function errorMessage(error: unknown): string {
 	try {
 		return error instanceof Error ? error.message : String(error);
@@ -326,14 +322,25 @@ export class TuiDebugServer {
 				if (paint === undefined) return { ok: false, error: "no frame painted yet" };
 				return {
 					ok: true,
-					lines: paint.lines.map(plainLine),
+					lines: paint.lines.map(plainText),
 					window_top: paint.windowTop,
 					alt_screen: paint.altScreen,
 					...(paint.cursor === undefined ? {} : { cursor: paint.cursor }),
 				};
 			}
 			case "frame":
-				return { ok: true, lines: this.#tui.getDebugDocument().map(plainLine) };
+				return { ok: true, lines: this.#tui.getDebugDocument().map(plainText) };
+			case "doc": {
+				// The document a Tern Surface Protocol terminal should hold: every sent
+				// frame applied by the reference applier.
+				const doc = this.#tui.getNativeDocument();
+				if (doc === undefined) return { ok: false, error: "no native surface" };
+				return { ok: true, doc, rows: this.#tui.nativeFallbackCount };
+			}
+			case "tsp": {
+				const count = typeof request.n === "number" && request.n > 0 ? Math.trunc(request.n) : undefined;
+				return { ok: true, native: this.#tui.nativeRendering, frames: this.#tui.getNativeFrames(count) };
+			}
 			case "tree":
 				return { ok: true, tree: this.#tree() };
 			case "values":

package/src/hotkeys-markdown.ts

@@ -1,24 +1,67 @@
-import {
-	type AppKeybinding,
-	formatKeyHint,
-	formatKeyHints,
-	type KeybindingsManager,
-	keyHintPlatform,
-} from "./app-keybindings";
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import { type AppKeybinding, formatKeyHint, type KeybindingsManager, keyHintPlatform } from "./app-keybindings";
+import { Markdown } from "./components/markdown";
+import { matchesSelectCancel } from "./keybinding-matchers";
+import type { KeyName } from "./key-hint-format";
 import { canonicalKeyId } from "./keybindings";
+import { col, node, span } from "./native/describe";
+import type { NativeNode, NativeUiEvent } from "./native/node";
+import { actionBar, actionButton } from "./native/overlay";
+import { getMarkdownTheme } from "./theme/theme";
+import type { Component } from "./tui";
 
 /** Effective keybinding operations used to render the hotkey reference. */
 export interface HotkeysMarkdownBindings {
 	keybindings: Pick<KeybindingsManager, "getDisplayString" | "getKeys" | "matchesCanonical">;
 }
 
-function hotkeyLabel(bindings: HotkeysMarkdownBindings, action: AppKeybinding): string {
-	return bindings.keybindings.getDisplayString(action) || "Disabled";
+/**
+ * One piece of a shortcut cell: formatted key hints (alternatives, one keycap
+ * each), a literal typed token (`#<number>`, `!!`), or connecting prose.
+ */
+type HotkeyPart =
+	| {
+			/** Formatted for the markdown table (`⌃R`); `Disabled` when unbound. */
+			keys: readonly string[];
+			/** Key ids (`ctrl+r`) for native keycaps, which the terminal draws with platform glyphs. */
+			ids: readonly KeyName[];
+			action?: AppKeybinding;
+	  }
+	| { token: string }
+	| { text: string };
+
+interface HotkeyRow {
+	readonly keys: readonly HotkeyPart[];
+	readonly action: string;
 }
 
-/** Build the platform-aware Markdown reference for effective application hotkeys. */
-export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string {
+interface HotkeyGroup {
+	readonly title: string;
+	readonly rows: readonly HotkeyRow[];
+}
+
+/** Formatted hints for key ids. */
+function hints(keys: readonly KeyName[]): HotkeyPart {
+	return { keys: keys.map(formatKeyHint), ids: keys };
+}
+
+/** The markdown cell text of a part; key alternatives join with `/` as `formatKeyHints` does. */
+function markdownPart(bindings: HotkeysMarkdownBindings, part: HotkeyPart): string {
+	if ("text" in part) return part.text;
+	if ("token" in part) return `\`${part.token}\``;
+	const label = part.action ? bindings.keybindings.getDisplayString(part.action) || "Disabled" : part.keys.join("/");
+	return `\`${label}\``;
+}
+
+/** The shortcut groups, built from the effective bindings. */
+function hotkeyGroups(bindings: HotkeysMarkdownBindings): HotkeyGroup[] {
 	const isMac = keyHintPlatform() === "darwin";
+	// An action's effective keys, one keycap each; `Disabled` when unbound.
+	const act = (action: AppKeybinding): HotkeyPart => {
+		const keys = bindings.keybindings.getKeys(action);
+		if (keys.length > 0) return { keys: keys.map(formatKeyHint), ids: keys, action };
+		return { keys: [bindings.keybindings.getDisplayString(action) || "Disabled"], ids: [], action };
+	};
 	// CustomEditor tests the chord that was actually pressed, so exit keys split by role: a key
 	// that also carries tui.editor.deleteCharForward (the readline `^D` overlap) forward-deletes
 	// while the prompt holds a draft, any other exit key quits immediately. Mixed bindings such as
@@ -31,67 +74,206 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 	const quittingExitKeys = exitKeys.filter(
 		key => !bindings.keybindings.matchesCanonical(canonicalKeyId(key), "tui.editor.deleteCharForward"),
 	);
-	const exitRows: string[] = [];
+	const exitRows: HotkeyRow[] = [];
 	if (deletingExitKeys.length > 0) {
-		exitRows.push(
-			`| \`${formatKeyHints(deletingExitKeys)}\` | Delete char forward (with draft) / exit (empty prompt) |`,
-		);
+		exitRows.push({
+			keys: [hints(deletingExitKeys)],
+			action: "Delete char forward (with draft) / exit (empty prompt)",
+		});
 	}
 	// An unbound exit action still gets its row, mirroring the `Disabled` hint every other row uses.
 	if (quittingExitKeys.length > 0 || deletingExitKeys.length === 0) {
-		exitRows.push(`| \`${formatKeyHints(quittingExitKeys) || "Disabled"}\` | Exit |`);
+		exitRows.push({
+			keys: [quittingExitKeys.length > 0 ? hints(quittingExitKeys) : { keys: ["Disabled"], ids: [] }],
+			action: "Exit",
+		});
+	}
+	const groups: HotkeyGroup[] = [
+		{
+			title: "Navigation",
+			rows: [
+				{
+					keys: [hints(["up", "down", "left", "right"])],
+					action: `Move cursor / browse history (${formatKeyHint("up")} when empty)`,
+				},
+				{ keys: [hints(["alt+left", "alt+right"])], action: "Move by word" },
+				{
+					keys: [hints(isMac ? ["ctrl+a", "home", "super+left"] : ["ctrl+a", "home"])],
+					action: "Start of line",
+				},
+				{ keys: [hints(isMac ? ["ctrl+e", "end", "super+right"] : ["ctrl+e", "end"])], action: "End of line" },
+			],
+		},
+		{
+			title: "Editing",
+			rows: [
+				{ keys: [hints(["enter"])], action: "Send message" },
+				{ keys: [hints(["shift+enter", "alt+enter"])], action: "New line" },
+				{ keys: [hints(["ctrl+w", "alt+backspace"])], action: "Delete word backwards" },
+				{ keys: [hints(["ctrl+u"])], action: "Delete to start of line" },
+				{ keys: [hints(["ctrl+k"])], action: "Delete to end of line" },
+				{ keys: [act("app.clipboard.copyLine")], action: "Copy current line" },
+				{ keys: [act("app.clipboard.copyPrompt")], action: "Copy whole prompt" },
+			],
+		},
+		{
+			title: "Other",
+			rows: [
+				{ keys: [hints(["tab"])], action: "Path completion / accept autocomplete" },
+				{ keys: [act("app.interrupt")], action: "Cancel autocomplete / interrupt active work" },
+				{ keys: [act("app.clear")], action: "Clear editor (first) / exit (second)" },
+				...exitRows,
+				{ keys: [act("app.suspend")], action: "Suspend to background" },
+				{ keys: [act("app.display.reset")], action: "Reset terminal display" },
+				{ keys: [act("app.thinking.cycle")], action: "Cycle thinking level" },
+				{ keys: [act("app.model.cycleForward")], action: "Cycle role models (slow/default/smol)" },
+				{ keys: [act("app.model.cycleBackward")], action: "Cycle role models (backward)" },
+				{ keys: [act("app.model.selectTemporary")], action: "Select model (temporary)" },
+				{ keys: [act("app.model.select")], action: "Select model (set roles)" },
+				{ keys: [act("app.plan.toggle")], action: "Toggle plan mode" },
+				{ keys: [act("app.history.search")], action: "Search prompt history" },
+				{ keys: [act("app.tools.expand")], action: "Toggle tool output expansion" },
+				{ keys: [act("app.tools.toggleVisibility")], action: "Toggle tool activity visibility" },
+				{ keys: [act("app.thinking.toggle")], action: "Toggle thinking block visibility" },
+				{ keys: [act("app.editor.external")], action: "Edit message in external editor" },
+				{ keys: [act("app.retry")], action: "Retry last failed assistant turn" },
+				{ keys: [act("app.clipboard.pasteImage")], action: "Paste image or text from clipboard" },
+				{
+					keys: [{ text: "Hold " }, hints(["space"])],
+					action: "Speech-to-text (push-to-talk): hold to record, release to transcribe",
+				},
+				{ keys: [act("app.live.toggle")], action: "Start/stop live voice mode (/live)" },
+				{
+					keys: [
+						act("app.agents.hub"),
+						{ text: " / " },
+						act("app.session.observe"),
+						{ text: " / double-tap " },
+						hints(["left"]),
+						{ text: " (empty editor)" },
+					],
+					action: "Open the agent hub",
+				},
+				{ keys: [{ token: "#<number>" }], action: "GitHub issue/PR reference (e.g. `#3164` → `pr://`/`issue://`)" },
+				{
+					keys: [{ token: "#" }, { text: " / " }, { token: "#<text>" }],
+					action: "Prompt actions (copy / undo / move cursor)",
+				},
+				{ keys: [{ token: "/" }], action: "Slash commands" },
+				{ keys: [{ token: "!" }], action: "Run bash command" },
+				{ keys: [{ token: "!!" }], action: "Run bash command (excluded from context)" },
+				{ keys: [{ token: "$" }], action: "Run Python in shared kernel" },
+				{ keys: [{ token: "$$" }], action: "Run Python (excluded from context)" },
+			],
+		},
+	];
+	return groups;
+}
+
+/** Build the platform-aware Markdown reference for effective application hotkeys. */
+export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string {
+	const lines: string[] = [];
+	for (const [index, group] of hotkeyGroups(bindings).entries()) {
+		if (index > 0) lines.push("");
+		lines.push(`**${group.title}**`, "| Key | Action |", "|-----|--------|");
+		for (const row of group.rows) {
+			const keys = row.keys.map(part => markdownPart(bindings, part)).join("");
+			lines.push(`| ${keys} | ${row.action} |`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * A shortcut cell as spans: each key alternative a `key` span holding its key
+ * id (`ctrl+r`, drawn as a keycap like `kbd`), literal tokens as code, prose dim.
+ */
+function keySpans(parts: readonly HotkeyPart[]): TspSpan[] {
+	const spans: TspSpan[] = [];
+	for (const part of parts) {
+		if ("text" in part) spans.push(span(part.text, "dim"));
+		else if ("token" in part) spans.push(span(part.token, "code"));
+		else if (part.ids.length === 0) spans.push(span(part.keys.join("/"), "dim"));
+		else {
+			for (const [index, id] of part.ids.entries()) {
+				if (index > 0) spans.push(span(" ", "dim"));
+				spans.push(span(id, "key"));
+			}
+		}
+	}
+	return spans;
+}
+
+/** Inline markdown (backticks) of an action description as spans: code runs mono, the rest plain. */
+function actionSpans(action: string): TspSpan[] {
+	return action.split(/(`[^`]+`)/).flatMap(piece => {
+		if (piece === "") return [];
+		return piece.startsWith("`") && piece.endsWith("`") ? [span(piece.slice(1, -1), "code")] : [span(piece)];
+	});
+}
+
+/**
+ * `/hotkeys` under a native terminal: a large sheet "Keyboard shortcuts" with
+ * one section per group, each a two-column table whose key cells carry `key`
+ * spans (Tern draws them as keycaps). Esc (or Close) dismisses it. Terminals
+ * without the native surface get the transcript markdown panel instead.
+ */
+export class HotkeysSheetComponent implements Component {
+	readonly nativeOverlay = { role: "omp.overlay.hotkeys", size: "lg", head: "Keyboard shortcuts" } as const;
+	readonly #bindings: HotkeysMarkdownBindings;
+	readonly #onClose: () => void;
+	#native: NativeNode | undefined;
+	#markdown: Markdown | undefined;
+
+	constructor(bindings: HotkeysMarkdownBindings, onClose: () => void) {
+		this.#bindings = bindings;
+		this.#onClose = onClose;
+	}
+
+	describe(): NativeNode {
+		if (this.#native) return this.#native;
+		const sections = hotkeyGroups(this.#bindings).map((group, index) =>
+			node(
+				"section",
+				{ head: group.title, role: "omp.hotkeys.group" },
+				[
+					node("table", {
+						role: "omp.hotkeys.table",
+						cols: [
+							{ id: "keys", head: "Key" },
+							{ id: "action", head: "Action", grow: 1 },
+						],
+						rows: group.rows.map((row, rowIndex) => ({
+							id: String(rowIndex),
+							cells: { keys: keySpans(row.keys), action: actionSpans(row.action) },
+						})),
+					}),
+				],
+				`g${index}`,
+			),
+		);
+		const close = actionButton("Close", "close", { keys: "escape" });
+		this.#native = col([...sections, actionBar([null, close])], { gap: "lg" });
+		return this.#native;
+	}
+
+	/** The markdown reference, for a terminal that falls back to rows. */
+	render(width: number): readonly string[] {
+		this.#markdown ??= new Markdown(buildHotkeysMarkdown(this.#bindings), 1, 1, getMarkdownTheme());
+		return this.#markdown.render(width);
+	}
+
+	invalidate(): void {
+		this.#native = undefined;
+		this.#markdown = undefined;
+	}
+
+	handleInput(data: string): void {
+		if (matchesSelectCancel(data)) this.#onClose();
+	}
+
+	/** Close runs what Esc runs. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "close") this.#onClose();
 	}
-	return [
-		"**Navigation**",
-		"| Key | Action |",
-		"|-----|--------|",
-		`| \`${formatKeyHints(["up", "down", "left", "right"])}\` | Move cursor / browse history (${formatKeyHint("up")} when empty) |`,
-		`| \`${formatKeyHints(["alt+left", "alt+right"])}\` | Move by word |`,
-		`| \`${formatKeyHints(isMac ? ["ctrl+a", "home", "super+left"] : ["ctrl+a", "home"])}\` | Start of line |`,
-		`| \`${formatKeyHints(isMac ? ["ctrl+e", "end", "super+right"] : ["ctrl+e", "end"])}\` | End of line |`,
-		"",
-		"**Editing**",
-		"| Key | Action |",
-		"|-----|--------|",
-		`| \`${formatKeyHint("enter")}\` | Send message |`,
-		`| \`${formatKeyHints(["shift+enter", "alt+enter"])}\` | New line |`,
-		`| \`${formatKeyHints(["ctrl+w", "alt+backspace"])}\` | Delete word backwards |`,
-		`| \`${formatKeyHint("ctrl+u")}\` | Delete to start of line |`,
-		`| \`${formatKeyHint("ctrl+k")}\` | Delete to end of line |`,
-		`| \`${hotkeyLabel(bindings, "app.clipboard.copyLine")}\` | Copy current line |`,
-		`| \`${hotkeyLabel(bindings, "app.clipboard.copyPrompt")}\` | Copy whole prompt |`,
-		"",
-		"**Other**",
-		"| Key | Action |",
-		"|-----|--------|",
-		`| \`${formatKeyHint("tab")}\` | Path completion / accept autocomplete |`,
-		`| \`${hotkeyLabel(bindings, "app.interrupt")}\` | Cancel autocomplete / interrupt active work |`,
-		`| \`${hotkeyLabel(bindings, "app.clear")}\` | Clear editor (first) / exit (second) |`,
-		...exitRows,
-		`| \`${hotkeyLabel(bindings, "app.suspend")}\` | Suspend to background |`,
-		`| \`${hotkeyLabel(bindings, "app.display.reset")}\` | Reset terminal display |`,
-		`| \`${hotkeyLabel(bindings, "app.thinking.cycle")}\` | Cycle thinking level |`,
-		`| \`${hotkeyLabel(bindings, "app.model.cycleForward")}\` | Cycle role models (slow/default/smol) |`,
-		`| \`${hotkeyLabel(bindings, "app.model.cycleBackward")}\` | Cycle role models (backward) |`,
-		`| \`${hotkeyLabel(bindings, "app.model.selectTemporary")}\` | Select model (temporary) |`,
-		`| \`${hotkeyLabel(bindings, "app.model.select")}\` | Select model (set roles) |`,
-		`| \`${hotkeyLabel(bindings, "app.plan.toggle")}\` | Toggle plan mode |`,
-		`| \`${hotkeyLabel(bindings, "app.history.search")}\` | Search prompt history |`,
-		`| \`${hotkeyLabel(bindings, "app.tools.expand")}\` | Toggle tool output expansion |`,
-		`| \`${hotkeyLabel(bindings, "app.tools.toggleVisibility")}\` | Toggle tool activity visibility |`,
-		`| \`${hotkeyLabel(bindings, "app.thinking.toggle")}\` | Toggle thinking block visibility |`,
-		`| \`${hotkeyLabel(bindings, "app.editor.external")}\` | Edit message in external editor |`,
-		`| \`${hotkeyLabel(bindings, "app.retry")}\` | Retry last failed assistant turn |`,
-		`| \`${hotkeyLabel(bindings, "app.clipboard.pasteImage")}\` | Paste image or text from clipboard |`,
-		`| Hold \`${formatKeyHint("space")}\` | Speech-to-text (push-to-talk): hold to record, release to transcribe |`,
-		`| \`${hotkeyLabel(bindings, "app.live.toggle")}\` | Start/stop live voice mode (/live) |`,
-		`| \`${hotkeyLabel(bindings, "app.agents.hub")}\` / \`${hotkeyLabel(bindings, "app.session.observe")}\` / double-tap \`${formatKeyHint("left")}\` (empty editor) | Open the agent hub |`,
-		"| `#<number>` | GitHub issue/PR reference (e.g. `#3164` → `pr://`/`issue://`) |",
-		"| `#` / `#<text>` | Prompt actions (copy / undo / move cursor) |",
-		"| `/` | Slash commands |",
-		"| `!` | Run bash command |",
-		"| `!!` | Run bash command (excluded from context) |",
-		"| `$` | Run Python in shared kernel |",
-		"| `$$` | Run Python (excluded from context) |",
-	].join("\n");
 }

package/src/index.ts

@@ -57,6 +57,12 @@ export * from "./latex-block";
 export * from "./latex-to-unicode";
 // SGR mouse report parsing
 export * from "./mouse";
+// Tern Surface Protocol: describe contract, builders, blobs, settling, render state
+export * from "./native/blobs";
+export * from "./native/describe";
+export type * from "./native/node";
+export * from "./native/settle";
+export * from "./native/state";
 // Mermaid diagram support
 // Input buffering for batch splitting
 export * from "./stdin-buffer";

package/src/latex-block.ts

@@ -23,6 +23,8 @@
 // scratch here on this module's ANSI-aware Box model.
 
 import { latexColorScope, latexToUnicode, MATH_FONT_COMMANDS } from "./latex-to-unicode";
+import { node } from "./native/describe";
+import type { NativeNode } from "./native/node";
 import { visibleWidth } from "./utils";
 
 /**
@@ -1428,6 +1430,15 @@ function splitLines(src: string): string[] {
 	return lines;
 }
 
+/**
+ * The native form of {@link latexToBlock}: the TeX source as a `math` node
+ * the terminal typesets (display style by default, `display: false` for
+ * inline `$…$` math).
+ */
+export function describeLatex(src: string, display = true): NativeNode {
+	return node("math", { text: src, display });
+}
+
 /**
  * Render a display LaTeX math fragment to lines with full 2-D layout: stacked
  * fractions, stretchy delimiters, matrix grids, operator limits, drawn

package/src/loop-watchdog.ts

@@ -64,6 +64,8 @@ export class LoopWatchdog {
 	#expected = 0;
 	#expectedCpu = 0;
 	#wasBlocked = false;
+	// When the most recent late tick ran — the moment a detected block ended.
+	#stallEndedAt = Number.NEGATIVE_INFINITY;
 	#running = false;
 	// Bumped by stop(); each scheduled tick captures the generation it was armed
 	// under and no-ops if it no longer matches, so a start()→stop()→start() cycle
@@ -94,17 +96,40 @@ export class LoopWatchdog {
 		if (this.#running) return;
 		this.#running = true;
 		this.#wasBlocked = false;
+		this.#stallEndedAt = Number.NEGATIVE_INFINITY;
 		this.#armTick();
 	}
 
 	stop(): void {
 		this.#running = false;
 		this.#wasBlocked = false;
+		this.#stallEndedAt = Number.NEGATIVE_INFINITY;
 		this.#generation++;
 		this.#handle?.cancel?.();
 		this.#handle = undefined;
 	}
 
+	/**
+	 * Whether the loop is blocked right now — the armed tick is already more
+	 * than `thresholdMs` overdue — or a detected block ended within the last
+	 * `thresholdMs`. Input read at such a moment may be keystrokes the block
+	 * batched into one read. Resolves both orders in which a resumed loop can
+	 * run the late tick and the queued stdin read. A suspended-process gap is
+	 * not a stall, and a stopped watchdog never reports one.
+	 */
+	isStalled(): boolean {
+		if (!this.#running) return false;
+		const now = this.#now();
+		if (now - this.#stallEndedAt <= this.#thresholdMs) return true;
+		const overdueMs = now - this.#expected;
+		return overdueMs > this.#thresholdMs && !this.#isSuspension(overdueMs, this.#cpuNow() - this.#expectedCpu);
+	}
+
+	/** A long gap the process spent negligible CPU on: it was suspended, not blocked. */
+	#isSuspension(blockedMs: number, cpuMs: number): boolean {
+		return blockedMs > this.#sleepMs && cpuMs < blockedMs * CPU_BUSY_RATIO;
+	}
+
 	#armTick(): void {
 		const generation = this.#generation;
 		this.#expected = this.#now() + this.#intervalMs;
@@ -115,23 +140,26 @@ export class LoopWatchdog {
 
 	#tick(generation: number): void {
 		if (!this.#running || generation !== this.#generation) return;
-		const blockedMs = this.#now() - this.#expected;
+		const now = this.#now();
+		const blockedMs = now - this.#expected;
 		const cpuMs = this.#cpuNow() - this.#expectedCpu;
 		// Consume the recent phase every tick (block or not) so attribution is
 		// scoped to the just-elapsed interval and never carries a stale phase
 		// forward to a later, phase-less block.
 		const phase = takeRecentLoopPhase();
 		if (blockedMs > this.#thresholdMs) {
-			if (blockedMs > this.#sleepMs && cpuMs < blockedMs * CPU_BUSY_RATIO) {
-				// A long gap the process did not spend CPU on: it was suspended.
+			if (this.#isSuspension(blockedMs, cpuMs)) {
 				this.#wasBlocked = false;
-			} else if (!this.#wasBlocked) {
-				this.#wasBlocked = true;
-				logger.warn("ui.loop-blocked", {
-					blockedMs: Math.round(blockedMs),
-					cpuMs: Math.round(cpuMs),
-					phase: phase ?? "unknown",
-				});
+			} else {
+				this.#stallEndedAt = now;
+				if (!this.#wasBlocked) {
+					this.#wasBlocked = true;
+					logger.warn("ui.loop-blocked", {
+						blockedMs: Math.round(blockedMs),
+						cpuMs: Math.round(cpuMs),
+						phase: phase ?? "unknown",
+					});
+				}
 			}
 		} else {
 			this.#wasBlocked = false;