@valyrianjs/terminal 0.1.0 → 0.1.2

package/src/session.ts

@@ -0,0 +1,1260 @@
+import { ANSI_ENTER_ALTERNATE_SCREEN, ANSI_EXIT_ALTERNATE_SCREEN, ANSI_HIDE_CURSOR, ANSI_SHOW_CURSOR, createAnsiDiffWriter, formatPlainFrame, toAnsiFrame } from "./ansi.js";
+import { createSystemClipboardAdapter } from "./clipboard.js";
+import { createEditorState, insertEditorText, moveEditorCursor, removeEditorBackward, removeEditorForward } from "./editor-state.js";
+import { copySelection, hasSelection, insertText, moveCursorEnd, moveCursorHome, moveCursorLeft, moveCursorRight, moveCursorWordLeft, moveCursorWordRight, normalizeInputState, parseTerminalKey, removeBackward, removeForward, selectAll } from "./events.js";
+import { createResolvedTerminalKeymap, resolveTerminalKeyBinding } from "./keymap.js";
+import { mergeVertical } from "./layout.js";
+import { cursorFromHitbox, parseTerminalInput, resolvePointerTarget } from "./mouse.js";
+import { createOutputWriter } from "./output-writer.js";
+import { parseBracketedPaste } from "./paste.js";
+import { renderTerminalFrame } from "./render.js";
+import { createRenderScheduler } from "./scheduler.js";
+import { plainText, stripTerminalControls } from "./text.js";
+import { collectActiveFocusScopeFocusableNodes, collectDirectOverlayFocusableNodes, collectFocusableNodes, findFocusableById, findFocused } from "./tree.js";
+import { createValyrianTerminalRuntime } from "./runtime.js";
+
+import type { TerminalRenderContext } from "./render.js";
+
+import type { EditorState } from "./editor-state.js";
+
+import type {
+  InputInteractionState,
+  TerminalCommand,
+  TerminalCommandContext,
+  TerminalCaptureEventPayload,
+  TerminalClipboardAdapter,
+  TerminalFocusNode,
+  TerminalListChangeEventPayload,
+  TerminalListPressEventPayload,
+  TerminalMountOptions,
+  TerminalOutputStream,
+  TerminalNode,
+  TerminalPointerSource,
+  TerminalRowPointerEventPayload,
+  TerminalSession,
+  TerminalSize
+} from "./types.js";
+
+type TerminalInputStream = NonNullable<TerminalMountOptions["stdin"]>;
+
+interface ResolvedRuntimeOptions {
+  runtime: "app" | "headless";
+  stdin?: TerminalInputStream;
+  stdout?: TerminalOutputStream;
+  alternateScreen: boolean;
+  hideCursor: boolean;
+  writesAnsi: boolean;
+}
+
+const DEFAULT_TERMINAL_SIZE: TerminalSize = { cols: 80, rows: 24 };
+const BRACKETED_PASTE_START = "\u001b[200~";
+const KNOWN_TERMINAL_KEY_SEQUENCES = [
+  "\u001b[13;2u",
+  "\u001b[13;130u",
+  "\u001b[13;129u",
+  "\u001b[27;2;13~",
+  "\u001b[13;2~",
+  "\u001b[1;2C",
+  "\u001b[1;2D",
+  "\u001b[1;3C",
+  "\u001b[1;3D",
+  "\u001b[3~",
+  "\u001b[Z",
+  "\u001b[A",
+  "\u001b[B",
+  "\u001b[C",
+  "\u001b[D",
+  "\u001b[H",
+  "\u001b[F",
+  "\u001bf",
+  "\u001bb"
+];
+const ESCAPE = "\u001b";
+const CSI_PREFIX = "\u001b[";
+
+function isBracketedPasteStartPrefix(value: string) {
+  return value.length > 0 && value.length < BRACKETED_PASTE_START.length && BRACKETED_PASTE_START.startsWith(value);
+}
+
+function isDisambiguatedBracketedPasteStartPrefix(value: string) {
+  return isBracketedPasteStartPrefix(value) && value.length > CSI_PREFIX.length;
+}
+
+function isKnownTerminalKeySequencePrefix(value: string) {
+  return KNOWN_TERMINAL_KEY_SEQUENCES.some((sequence) => value.length > 0 && value.length < sequence.length && sequence.startsWith(value));
+}
+
+function canContinueEscapeSequence(value: string) {
+  return value.startsWith("[") || value.startsWith("b") || value.startsWith("f");
+}
+
+function validateTerminalDimension(name: "cols" | "rows", value: number) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`Invalid terminal ${name}: expected an integer >= 1`);
+  }
+  return value;
+}
+
+function isValidTerminalDimension(value: number | undefined): value is number {
+  return Number.isInteger(value) && Number(value) >= 1;
+}
+
+
+function getProcessStdin(): TerminalInputStream | undefined {
+  const candidate = globalThis.process?.stdin as TerminalInputStream | undefined;
+  return candidate && typeof candidate.on === "function" ? candidate : undefined;
+}
+
+function getProcessStdout(): TerminalOutputStream | undefined {
+  const candidate = globalThis.process?.stdout as TerminalOutputStream | undefined;
+  return candidate && typeof candidate.write === "function" ? candidate : undefined;
+}
+
+function isInteractiveTTY(stdin: TerminalInputStream | undefined, stdout: TerminalOutputStream | undefined) {
+  return Boolean(stdin?.isTTY && stdout?.isTTY);
+}
+
+function resolveRuntimeOptions(options: TerminalMountOptions): ResolvedRuntimeOptions {
+  const processStdin = getProcessStdin();
+  const processStdout = getProcessStdout();
+  const canUseProcessTTY = isInteractiveTTY(processStdin, processStdout);
+  const runtime = options.runtime ?? (canUseProcessTTY || options.stdin || options.stdout ? "app" : "headless");
+  const stdin = options.stdin ?? (runtime === "app" && canUseProcessTTY ? processStdin : undefined);
+  const stdout = options.stdout ?? (runtime === "app" && canUseProcessTTY ? processStdout : undefined);
+  const ownsInteractiveTTY = runtime === "app" && isInteractiveTTY(stdin, stdout);
+
+  return {
+    runtime,
+    stdin,
+    stdout,
+    alternateScreen: options.alternateScreen ?? ownsInteractiveTTY,
+    hideCursor: options.hideCursor ?? ownsInteractiveTTY,
+    writesAnsi: runtime === "app" && Boolean(stdout)
+  };
+}
+
+function resolveTerminalSize(options: TerminalMountOptions, stdout?: TerminalOutputStream): TerminalSize {
+  const cols = options.cols ?? stdout?.columns ?? DEFAULT_TERMINAL_SIZE.cols;
+  const rows = options.rows ?? stdout?.rows ?? DEFAULT_TERMINAL_SIZE.rows;
+  return {
+    cols: validateTerminalDimension("cols", cols),
+    rows: validateTerminalDimension("rows", rows)
+  };
+}
+
+function applyInteractiveState(
+  nodes: TerminalNode[],
+  focusedId: string | null,
+  inputStateById: Map<string, InputInteractionState>,
+  editorStateById: Map<string, EditorState>,
+  listIndexById: Map<string, number>,
+  scrollOffsetById: Map<string, number>,
+  listHoverById: Map<string, number>,
+  scrollHoverRowById: Map<string, number>
+) {
+  for (let i = 0; i < nodes.length; i += 1) {
+    const node = nodes[i];
+    if (node.type !== "element") {
+      continue;
+    }
+
+    const id = node.props.id;
+    node.props.__focused = Boolean(focusedId && id === focusedId);
+    if (node.tag === "terminal-input" && id) {
+      const value = plainText(node.props.value ?? "");
+      const current = normalizeInputState(inputStateById.get(id), value.length);
+      inputStateById.set(id, current);
+      node.props.__inputState = current;
+    }
+    if (node.tag === "terminal-editor" && id) {
+      const value = plainText(node.props.value ?? "");
+      const previous = editorStateById.get(id);
+      const current = createEditorState(value, previous?.cursor, previous?.desiredColumn);
+      editorStateById.set(id, current);
+      node.props.__editorState = current;
+    }
+    if (node.tag === "terminal-list" && id) {
+      node.props.__selectedIndex = listIndexById.get(id) || 0;
+      if (listHoverById.has(id)) {
+        node.props.__hoveredIndex = listHoverById.get(id);
+      }
+    }
+    if (node.tag === "terminal-scroll" && id) {
+      node.props.__scrollOffset = scrollOffsetById.get(id) || 0;
+      if (scrollHoverRowById.has(id)) {
+        node.props.__hoveredRow = scrollHoverRowById.get(id);
+      }
+    }
+    applyInteractiveState(node.children, focusedId, inputStateById, editorStateById, listIndexById, scrollOffsetById, listHoverById, scrollHoverRowById);
+  }
+}
+
+export function mountTerminal(input: any, options: TerminalMountOptions = {}): TerminalSession {
+  let focusedId: string | null = null;
+  let skipFocusContainmentOnce = false;
+  let clipboardValue = "";
+  let mouseSelectionId: string | null = null;
+  let pointerCaptureId: string | null = null;
+  let pendingPasteChunk = "";
+  let pendingKeyChunk = "";
+  let pendingEscapeFlush: ReturnType<typeof setTimeout> | null = null;
+  let destroyed = false;
+  let autoProjectionEnabled = false;
+  let suppressAutoProjection = false;
+  const clipboardAdapter: TerminalClipboardAdapter | null = options.clipboard === false ? null : options.clipboard || createSystemClipboardAdapter();
+  const inputStateById = new Map<string, InputInteractionState>();
+  const editorStateById = new Map<string, EditorState>();
+  const listIndexById = new Map<string, number>();
+  const scrollOffsetById = new Map<string, number>();
+  const listHoverById = new Map<string, number>();
+  const scrollHoverRowById = new Map<string, number>();
+  const keyBindings = createResolvedTerminalKeymap(options.keymap?.bindings);
+  const runtimeOptions = resolveRuntimeOptions(options);
+  let terminalSize = resolveTerminalSize(options, runtimeOptions.stdout);
+  const terminalRuntime = createValyrianTerminalRuntime(input, () => {
+    if (!autoProjectionEnabled || suppressAutoProjection || destroyed) {
+      return;
+    }
+    renderNow();
+  });
+  let currentTree = terminalRuntime.project();
+  applyInteractiveState(currentTree, focusedId, inputStateById, editorStateById, listIndexById, scrollOffsetById, listHoverById, scrollHoverRowById);
+  let currentFrame = renderTreeFrame(currentTree);
+  let currentOutput = formatPlainFrame(currentFrame, { theme: options.theme }).trimEnd();
+  let currentHitboxes = currentFrame.hitboxes;
+
+  const outputWriter = createOutputWriter(runtimeOptions.stdout);
+  const toAnsiDiff = createAnsiDiffWriter({ showCursor: !runtimeOptions.hideCursor, showCursorWhenFrameHasCursor: true, theme: options.theme });
+  const renderScheduler = createRenderScheduler(renderNow);
+  const outputResizeScheduler = createRenderScheduler(applyPendingOutputResize);
+  let cleanupOutputResize: (() => void) | null = null;
+  let pendingOutputResize: TerminalSize | null = null;
+
+  function renderContext(): TerminalRenderContext {
+    return { ...terminalSize, theme: options.theme };
+  }
+
+  function renderTreeFrame(nodes: TerminalNode[]) {
+    const context = renderContext();
+    return mergeVertical(nodes.map((node) => renderTerminalFrame(node, context)));
+  }
+
+  function emitLifecycleSetup() {
+    const writes: string[] = [];
+    if (runtimeOptions.alternateScreen) {
+      writes.push(ANSI_ENTER_ALTERNATE_SCREEN);
+    }
+    if (runtimeOptions.hideCursor) {
+      writes.push(ANSI_HIDE_CURSOR);
+    }
+    if (writes.length > 0) {
+      outputWriter.write(writes.join(""), { force: true });
+    }
+  }
+
+  function emitLifecycleRestore() {
+    if (options.restoreOnDestroy === false) {
+      return;
+    }
+    const writes: string[] = [];
+    if (runtimeOptions.hideCursor) {
+      writes.push(ANSI_SHOW_CURSOR);
+    }
+    if (runtimeOptions.alternateScreen) {
+      writes.push(ANSI_EXIT_ALTERNATE_SCREEN);
+    }
+    if (writes.length > 0) {
+      outputWriter.write(writes.join(""), { force: true });
+    }
+  }
+
+  function emitOutput() {
+    if (!destroyed) {
+      outputWriter.write(runtimeOptions.writesAnsi ? toAnsiDiff(currentFrame.lines, currentFrame.cursor, currentFrame.spans) : currentOutput);
+    }
+  }
+
+  function renderNow() {
+    currentTree = terminalRuntime.project();
+    const focusables: TerminalFocusNode[] = [];
+    collectFocusableNodes(currentTree, focusables);
+    const overlayFocusables: TerminalFocusNode[] = [];
+    collectDirectOverlayFocusableNodes(currentTree, overlayFocusables);
+    const scopedFocusables: TerminalFocusNode[] = [];
+    collectActiveFocusScopeFocusableNodes(currentTree, focusedId, scopedFocusables);
+    const activeFocusables = overlayFocusables.length ? overlayFocusables : scopedFocusables.length ? scopedFocusables : focusables;
+    if (!skipFocusContainmentOnce && focusedId && !activeFocusables.some((node) => node.props.id === focusedId)) {
+      focusedId = activeFocusables[0]?.props.id || null;
+    }
+    skipFocusContainmentOnce = false;
+    applyInteractiveState(currentTree, focusedId, inputStateById, editorStateById, listIndexById, scrollOffsetById, listHoverById, scrollHoverRowById);
+    currentFrame = renderTreeFrame(currentTree);
+    currentOutput = formatPlainFrame(currentFrame, { theme: options.theme }).trimEnd();
+    currentHitboxes = currentFrame.hitboxes;
+    emitOutput();
+    return currentOutput;
+  }
+
+  function rerender() {
+    if (destroyed) {
+      return currentOutput;
+    }
+    suppressAutoProjection = true;
+    try {
+      terminalRuntime.update();
+    } finally {
+      suppressAutoProjection = false;
+    }
+    renderScheduler.requestRender();
+    renderScheduler.flush();
+    return currentOutput;
+  }
+
+  function orderedFocusables() {
+    const overlayFocusables: TerminalFocusNode[] = [];
+    collectDirectOverlayFocusableNodes(currentTree, overlayFocusables);
+    if (overlayFocusables.length) {
+      return overlayFocusables;
+    }
+
+    const scopedFocusables: TerminalFocusNode[] = [];
+    collectActiveFocusScopeFocusableNodes(currentTree, focusedId, scopedFocusables);
+    if (scopedFocusables.length) {
+      return scopedFocusables;
+    }
+
+    const out: TerminalFocusNode[] = [];
+    collectFocusableNodes(currentTree, out);
+    return out;
+  }
+
+  function readClipboard() {
+    if (!clipboardAdapter || typeof clipboardAdapter.readText !== "function") {
+      return clipboardValue;
+    }
+    try {
+      const nextValue = clipboardAdapter.readText();
+      if (typeof nextValue === "string") {
+        clipboardValue = nextValue;
+      }
+    } catch {
+      return clipboardValue;
+    }
+    return clipboardValue;
+  }
+
+  function writeClipboard(value: string) {
+    clipboardValue = String(value);
+    if (!clipboardAdapter || typeof clipboardAdapter.writeText !== "function") {
+      return clipboardValue;
+    }
+    try {
+      clipboardAdapter.writeText(clipboardValue);
+    } catch {
+      return clipboardValue;
+    }
+    return clipboardValue;
+  }
+
+  function setInputCursor(id: string, cursor: number, extendSelection = false) {
+    const node = findFocusableById(currentTree, id);
+    const value = stripTerminalControls(node?.props.value ?? "");
+    const current = normalizeInputState(inputStateById.get(id), value.length);
+    inputStateById.set(id, extendSelection ? { cursor: Math.max(0, Math.min(value.length, cursor)), anchor: current.anchor } : { cursor: Math.max(0, Math.min(value.length, cursor)), anchor: Math.max(0, Math.min(value.length, cursor)) });
+  }
+
+  function replaceInputState(id: string, state: InputInteractionState) {
+    const node = findFocusableById(currentTree, id);
+    const value = stripTerminalControls(node?.props.value ?? "");
+    inputStateById.set(id, normalizeInputState(state, value.length));
+  }
+
+  function dispatchNodeEvent(node: TerminalFocusNode, type: string, payload: Record<string, any>) {
+    const id = String(node.props.id || "");
+    if (!id) {
+      return false;
+    }
+    return terminalRuntime.dispatchTerminalEvent(id, type, payload);
+  }
+
+  function updateInputByState(node: TerminalFocusNode, next: { value: string; state: InputInteractionState }) {
+    const id = String(node.props.id || "");
+    dispatchNodeEvent(node, "change", { type: "change", id, value: next.value });
+    inputStateById.set(id, next.state);
+    return rerender();
+  }
+
+  function replaceEditorState(id: string, state: EditorState) {
+    const node = findFocusableById(currentTree, id);
+    const value = plainText(node?.props.value ?? "");
+    editorStateById.set(id, createEditorState(value, state.cursor, state.desiredColumn));
+  }
+
+  function updateEditorValue(node: TerminalFocusNode, nextValue: string) {
+    const id = String(node.props.id || "");
+    dispatchNodeEvent(node, "change", { type: "change", id, value: plainText(nextValue) });
+  }
+
+  function updateEditorByState(node: TerminalFocusNode, next: { value: string; state: EditorState }) {
+    const id = String(node.props.id || "");
+    updateEditorValue(node, next.value);
+    editorStateById.set(id, next.state);
+    return rerender();
+  }
+
+  function submitEditor(node: TerminalFocusNode) {
+    const id = String(node.props.id || "");
+    dispatchNodeEvent(node, "submit", { type: "submit", id, value: plainText(node.props.value ?? "") });
+  }
+
+  function cancelEditor(node: TerminalFocusNode) {
+    const id = String(node.props.id || "");
+    dispatchNodeEvent(node, "cancel", { type: "cancel", id, value: plainText(node.props.value ?? "") });
+  }
+
+  function setCursorFromHitbox(id: string, x: number, extendSelection = false) {
+    const hitbox = currentHitboxes.find((box) => box.id === id && box.tag === "terminal-input");
+    if (!hitbox) {
+      return currentOutput;
+    }
+    const nextCursor = cursorFromHitbox(hitbox, x);
+    setInputCursor(id, nextCursor, extendSelection);
+    return rerender();
+  }
+
+  function visibleScrollLines(node: TerminalFocusNode) {
+    const context = renderContext();
+    const lines = mergeVertical(node.children.map((child) => renderTerminalFrame(child, context))).lines;
+    const offset = Number(node.props.__scrollOffset || 0);
+    const height = Number(node.props.height || lines.length || 0);
+    return lines.slice(offset, offset + height).map((line) => line.trimEnd());
+  }
+
+  function rowCountForNode(node: TerminalFocusNode) {
+    if (node.tag === "terminal-list") {
+      const items = Array.isArray(node.props.items) ? node.props.items : [];
+      return Math.max(1, items.length);
+    }
+    if (node.tag === "terminal-scroll") {
+      return Math.max(1, visibleScrollLines(node).length);
+    }
+    return 1;
+  }
+
+  function sourceRowFromHitbox(node: TerminalFocusNode, hitbox: { itemOffset?: number; y1: number }, y: number) {
+    const visibleRow = Math.max(1, y - hitbox.y1 + 1);
+    if (node.tag !== "terminal-list") {
+      return Math.max(1, Math.min(rowCountForNode(node), visibleRow));
+    }
+
+    return Math.max(1, Math.min(rowCountForNode(node), visibleRow + (hitbox.itemOffset || 0)));
+  }
+
+  function shouldPointerCapture(node: TerminalFocusNode) {
+    return Boolean(node.props.pointerCapture && (node.tag === "terminal-list" || node.tag === "terminal-scroll"));
+  }
+
+  function hoveredRowForNode(node: TerminalFocusNode | null) {
+    if (!node?.props.id) {
+      return null;
+    }
+    if (node.tag === "terminal-list") {
+      const hoveredIndex = listHoverById.get(node.props.id);
+      return typeof hoveredIndex === "number" ? hoveredIndex + 1 : null;
+    }
+    if (node.tag === "terminal-scroll") {
+      const hoveredRow = scrollHoverRowById.get(node.props.id);
+      return typeof hoveredRow === "number" ? hoveredRow : null;
+    }
+    return null;
+  }
+
+  function emitCaptureEvent(node: TerminalFocusNode | null, type: TerminalCaptureEventPayload["type"], source: TerminalPointerSource, row: number | null = null, x: number | null = null, y: number | null = null) {
+    if (!node || !node.props.id) {
+      return;
+    }
+    const payload: TerminalCaptureEventPayload = { type, id: node.props.id, source, row, x, y };
+    dispatchNodeEvent(node, type, payload);
+  }
+
+  function setPointerCapture(id: string | null, source: TerminalPointerSource, row: number | null = null, x: number | null = null, y: number | null = null) {
+    if (pointerCaptureId === id) {
+      return;
+    }
+    const previous = pointerCaptureId ? findFocusableById(currentTree, pointerCaptureId) : null;
+    pointerCaptureId = id;
+    const next = id ? findFocusableById(currentTree, id) : null;
+    if (previous && previous.props.id !== next?.props.id) {
+      emitCaptureEvent(previous, "captureend", source, row ?? hoveredRowForNode(previous), x, y);
+    }
+    if (next && previous?.props.id !== next.props.id) {
+      emitCaptureEvent(next, "capturestart", source, row ?? hoveredRowForNode(next), x, y);
+    }
+  }
+
+  function emitMouseRowEvent(node: TerminalFocusNode, type: TerminalRowPointerEventPayload["type"], row: number, x: number | null = null, y: number | null = null) {
+    if (!node.props.id) {
+      return;
+    }
+
+    if (node.tag === "terminal-list") {
+      const items = Array.isArray(node.props.items) ? node.props.items : [];
+      const index = Math.max(0, Math.min(items.length - 1, row - 1));
+      if (typeof items[index] === "undefined") {
+        return;
+      }
+      const payload: TerminalRowPointerEventPayload = { type, id: node.props.id, row: index + 1, index, value: items[index], x, y };
+      dispatchNodeEvent(node, type, payload);
+      return;
+    }
+
+    if (node.tag === "terminal-scroll") {
+      const lines = visibleScrollLines(node);
+      const index = Math.max(0, Math.min(lines.length - 1, row - 1));
+      if (typeof lines[index] === "undefined") {
+        return;
+      }
+      const payload: TerminalRowPointerEventPayload = { type, id: node.props.id, row: index + 1, value: lines[index], x, y };
+      dispatchNodeEvent(node, type, payload);
+    }
+  }
+
+  function clearSemanticHover(exceptId?: string, x: number | null = null, y: number | null = null) {
+    for (const [id, hoveredIndex] of listHoverById.entries()) {
+      if (id === exceptId) {
+        continue;
+      }
+      const node = findFocusableById(currentTree, id);
+      if (node) {
+        emitMouseRowEvent(node, "rowleave", hoveredIndex + 1, x, y);
+      }
+      listHoverById.delete(id);
+    }
+
+    for (const [id, hoveredRow] of scrollHoverRowById.entries()) {
+      if (id === exceptId) {
+        continue;
+      }
+      const node = findFocusableById(currentTree, id);
+      if (node) {
+        emitMouseRowEvent(node, "rowleave", hoveredRow, x, y);
+      }
+      scrollHoverRowById.delete(id);
+    }
+  }
+
+  function setSemanticHoverFromHitbox(id: string, x: number | null, y: number) {
+    const hitbox = currentHitboxes.find((box) => box.id === id);
+    const node = findFocusableById(currentTree, id);
+    if (!hitbox || !node) {
+      clearSemanticHover(undefined, x, y);
+      return;
+    }
+
+    clearSemanticHover(id, x, y);
+
+    const row = sourceRowFromHitbox(node, hitbox, y);
+    if (node.tag === "terminal-list") {
+      const nextIndex = row - 1;
+      const prevIndex = listHoverById.get(id);
+      if (typeof prevIndex === "number" && prevIndex !== nextIndex) {
+        emitMouseRowEvent(node, "rowleave", prevIndex + 1, x, y);
+      }
+      if (prevIndex !== nextIndex) {
+        listHoverById.set(id, nextIndex);
+        emitMouseRowEvent(node, "rowenter", row, x, y);
+      }
+      emitMouseRowEvent(node, "hover", row, x, y);
+    }
+    if (node.tag === "terminal-scroll") {
+      const prevRow = scrollHoverRowById.get(id);
+      if (typeof prevRow === "number" && prevRow !== row) {
+        emitMouseRowEvent(node, "rowleave", prevRow, x, y);
+      }
+      if (prevRow !== row) {
+        scrollHoverRowById.set(id, row);
+        emitMouseRowEvent(node, "rowenter", row, x, y);
+      }
+      emitMouseRowEvent(node, "hover", row, x, y);
+      return;
+    }
+
+    if (node.tag !== "terminal-list") {
+      clearSemanticHover(undefined, x, y);
+    }
+  }
+
+  function hoverAt(x: number, y: number) {
+    const hitbox = resolvePointerTarget(currentHitboxes, x, y);
+    if (!hitbox) {
+      if (pointerCaptureId) {
+        setSemanticHoverFromHitbox(pointerCaptureId, x, y);
+        return rerender();
+      }
+      clearSemanticHover(undefined, x, y);
+      return rerender();
+    }
+    const node = findFocusableById(currentTree, hitbox.id);
+    if (node && shouldPointerCapture(node)) {
+      setPointerCapture(hitbox.id, "drag", sourceRowFromHitbox(node, hitbox, y), x, y);
+    }
+    setSemanticHoverFromHitbox(hitbox.id, x, y);
+    return rerender();
+  }
+
+  function changeListSelection(node: TerminalFocusNode, direction: -1 | 1) {
+    const id = node.props.id;
+    if (!id) {
+      return currentOutput;
+    }
+    const items = Array.isArray(node.props.items) ? node.props.items : [];
+    const currentIndex = listIndexById.get(id) || 0;
+    const nextIndex = direction < 0 ? Math.max(0, currentIndex - 1) : Math.min(items.length - 1, currentIndex + 1);
+    listIndexById.set(id, nextIndex);
+    const payload: TerminalListChangeEventPayload = { type: "change", id, index: nextIndex, value: items[nextIndex] };
+    dispatchNodeEvent(node, "change", payload);
+    return rerender();
+  }
+
+  function pressListSelection(node: TerminalFocusNode) {
+    const id = node.props.id;
+    if (!id) {
+      return currentOutput;
+    }
+    const items = Array.isArray(node.props.items) ? node.props.items : [];
+    const currentIndex = listIndexById.get(id) || 0;
+    const payload: TerminalListPressEventPayload = { type: "press", id, index: currentIndex, value: items[currentIndex] };
+    dispatchNodeEvent(node, "press", payload);
+    return rerender();
+  }
+
+  function scrollFocusedNode(node: TerminalFocusNode, direction: -1 | 1) {
+    const id = node.props.id;
+    if (!id) {
+      return currentOutput;
+    }
+    const context = renderContext();
+    const rendered = mergeVertical(node.children.map((child) => renderTerminalFrame(child, context)));
+    const height = Number(node.props.height || rendered.lines.length || 0);
+    const currentOffset = scrollOffsetById.get(id) || 0;
+    const maxOffset = Math.max(0, rendered.lines.length - height);
+    scrollOffsetById.set(id, direction < 0 ? Math.max(0, currentOffset - 1) : Math.min(maxOffset, currentOffset + 1));
+    return rerender();
+  }
+
+  function wheelAt(x: number, y: number, direction: -1 | 1) {
+    const hitbox = resolvePointerTarget(currentHitboxes, x, y);
+    if (!hitbox) {
+      return currentOutput;
+    }
+
+    setSemanticHoverFromHitbox(hitbox.id, x, y);
+    const node = findFocusableById(currentTree, hitbox.id);
+    if (node?.tag === "terminal-scroll") {
+      return scrollFocusedNode(node, direction);
+    }
+    if (node?.tag === "terminal-list" && node.props.virtualized) {
+      return changeListSelection(node, direction);
+    }
+    return rerender();
+  }
+
+  function runInputCommand(node: TerminalFocusNode, command: TerminalCommand) {
+    const id = node.props.id;
+    if (!id) {
+      return currentOutput;
+    }
+
+    const currentValue = stripTerminalControls(node.props.value ?? "");
+    const state = normalizeInputState(inputStateById.get(id), currentValue.length);
+
+    switch (command.id) {
+      case "input.submit":
+        dispatchNodeEvent(node, "submit", { type: "submit", id, value: stripTerminalControls(node.props.value ?? "") });
+        return rerender();
+      case "input.cursorLeft":
+        replaceInputState(id, moveCursorLeft(state, currentValue.length));
+        return rerender();
+      case "input.cursorRight":
+        replaceInputState(id, moveCursorRight(state, currentValue.length));
+        return rerender();
+      case "input.selectLeft":
+        replaceInputState(id, moveCursorLeft(state, currentValue.length, true));
+        return rerender();
+      case "input.selectRight":
+        replaceInputState(id, moveCursorRight(state, currentValue.length, true));
+        return rerender();
+      case "input.wordLeft":
+        replaceInputState(id, moveCursorWordLeft(currentValue, state));
+        return rerender();
+      case "input.wordRight":
+        replaceInputState(id, moveCursorWordRight(currentValue, state));
+        return rerender();
+      case "input.home":
+        replaceInputState(id, moveCursorHome(state, currentValue.length));
+        return rerender();
+      case "input.end":
+        replaceInputState(id, moveCursorEnd(state, currentValue.length));
+        return rerender();
+      case "input.selectAll":
+        replaceInputState(id, selectAll(currentValue));
+        return rerender();
+      case "input.copy":
+        writeClipboard(copySelection(currentValue, state));
+        return rerender();
+      case "input.cut":
+        writeClipboard(copySelection(currentValue, state));
+        if (hasSelection(state)) {
+          return updateInputByState(node, insertText(currentValue, state, ""));
+        }
+        return currentOutput;
+      case "input.paste":
+        return updateInputByState(node, insertText(currentValue, state, stripTerminalControls(readClipboard())));
+      case "input.pasteText":
+        return updateInputByState(node, insertText(currentValue, state, stripTerminalControls(command.text ?? "")));
+      case "input.backspace":
+        return updateInputByState(node, removeBackward(currentValue, state));
+      case "input.delete":
+        return updateInputByState(node, removeForward(currentValue, state));
+      case "input.insertText":
+        return updateInputByState(node, insertText(currentValue, state, stripTerminalControls(command.text ?? "")));
+      default:
+        return currentOutput;
+    }
+  }
+
+  function isBuiltInInputCommand(command: TerminalCommand) {
+    return command.id === "input.submit"
+      || command.id === "input.cursorLeft"
+      || command.id === "input.cursorRight"
+      || command.id === "input.selectLeft"
+      || command.id === "input.selectRight"
+      || command.id === "input.wordLeft"
+      || command.id === "input.wordRight"
+      || command.id === "input.home"
+      || command.id === "input.end"
+      || command.id === "input.selectAll"
+      || command.id === "input.copy"
+      || command.id === "input.cut"
+      || command.id === "input.paste"
+      || command.id === "input.pasteText"
+      || command.id === "input.backspace"
+      || command.id === "input.delete"
+      || command.id === "input.insertText";
+  }
+
+  function runEditorCommand(node: TerminalFocusNode, command: TerminalCommand) {
+    const id = node.props.id;
+    if (!id) {
+      return currentOutput;
+    }
+
+    const currentValue = plainText(node.props.value ?? "");
+    const previous = editorStateById.get(id);
+    const state = createEditorState(currentValue, previous?.cursor, previous?.desiredColumn);
+
+    switch (command.id) {
+      case "editor.submit":
+        submitEditor(node);
+        return rerender();
+      case "editor.cancel":
+        cancelEditor(node);
+        return rerender();
+      case "editor.newline":
+        return updateEditorByState(node, insertEditorText(currentValue, state, "\n"));
+      case "editor.backspace":
+        return updateEditorByState(node, removeEditorBackward(currentValue, state));
+      case "editor.delete":
+        return updateEditorByState(node, removeEditorForward(currentValue, state));
+      case "editor.cursorLeft":
+        replaceEditorState(id, moveEditorCursor(currentValue, state, "left"));
+        return rerender();
+      case "editor.cursorRight":
+        replaceEditorState(id, moveEditorCursor(currentValue, state, "right"));
+        return rerender();
+      case "editor.cursorUp":
+        replaceEditorState(id, moveEditorCursor(currentValue, state, "up"));
+        return rerender();
+      case "editor.cursorDown":
+        replaceEditorState(id, moveEditorCursor(currentValue, state, "down"));
+        return rerender();
+      case "editor.home":
+        replaceEditorState(id, moveEditorCursor(currentValue, state, "home"));
+        return rerender();
+      case "editor.end":
+        replaceEditorState(id, moveEditorCursor(currentValue, state, "end"));
+        return rerender();
+      case "editor.paste":
+        return updateEditorByState(node, insertEditorText(currentValue, state, plainText(readClipboard())));
+      case "editor.pasteText":
+      case "editor.insertText":
+        return updateEditorByState(node, insertEditorText(currentValue, state, plainText(command.text ?? "")));
+      default:
+        return currentOutput;
+    }
+  }
+
+  function isBuiltInEditorCommand(command: TerminalCommand) {
+    return command.id === "editor.submit"
+      || command.id === "editor.cancel"
+      || command.id === "editor.newline"
+      || command.id === "editor.backspace"
+      || command.id === "editor.delete"
+      || command.id === "editor.cursorLeft"
+      || command.id === "editor.cursorRight"
+      || command.id === "editor.cursorUp"
+      || command.id === "editor.cursorDown"
+      || command.id === "editor.home"
+      || command.id === "editor.end"
+      || command.id === "editor.paste"
+      || command.id === "editor.pasteText"
+      || command.id === "editor.insertText";
+  }
+
+  function runCommand(command: TerminalCommand, node: TerminalFocusNode | null, context: TerminalCommandContext) {
+    switch (command.id) {
+      case "focus.next":
+        session.focusNext();
+        return currentOutput;
+      case "focus.prev":
+        session.focusPrev();
+        return currentOutput;
+      case "button.press":
+        if (node?.tag === "terminal-button") {
+          const id = String(node.props.id || "");
+          dispatchNodeEvent(node, "press", { type: "press", id });
+          return rerender();
+        }
+        return currentOutput;
+      case "list.prev":
+        return node?.tag === "terminal-list" ? changeListSelection(node, -1) : currentOutput;
+      case "list.next":
+        return node?.tag === "terminal-list" ? changeListSelection(node, 1) : currentOutput;
+      case "list.press":
+        return node?.tag === "terminal-list" ? pressListSelection(node) : currentOutput;
+      case "scroll.up":
+        return node?.tag === "terminal-scroll" ? scrollFocusedNode(node, -1) : currentOutput;
+      case "scroll.down":
+        return node?.tag === "terminal-scroll" ? scrollFocusedNode(node, 1) : currentOutput;
+      default:
+        if (node?.tag === "terminal-input" && isBuiltInInputCommand(command)) {
+          return runInputCommand(node, command);
+        }
+        if (node?.tag === "terminal-editor" && isBuiltInEditorCommand(command)) {
+          return runEditorCommand(node, command);
+        }
+        if (typeof options.keymap?.onCommand === "function") {
+          const consumed = options.keymap.onCommand(command, context);
+          return consumed ? rerender() : currentOutput;
+        }
+        return currentOutput;
+    }
+  }
+
+  const session: TerminalSession = {
+    size() {
+      return { ...terminalSize };
+    },
+    resize(cols: number, rows: number) {
+      const nextSize = {
+        cols: validateTerminalDimension("cols", cols),
+        rows: validateTerminalDimension("rows", rows)
+      };
+      pendingOutputResize = null;
+      outputResizeScheduler.cancel();
+      if (nextSize.cols === terminalSize.cols && nextSize.rows === terminalSize.rows) {
+        return;
+      }
+      terminalSize = nextSize;
+      rerender();
+    },
+    update() {
+      return rerender();
+    },
+    output() {
+      return currentOutput;
+    },
+    ansiOutput() {
+      return toAnsiFrame(currentFrame.lines, currentFrame.cursor, currentFrame.spans, { showCursor: !options.hideCursor, showCursorWhenFrameHasCursor: true, theme: options.theme });
+    },
+    tree() {
+      return currentTree;
+    },
+    focus(id: string) {
+      const node = findFocusableById(currentTree, id);
+      if (!node) {
+        return false;
+      }
+      focusedId = id;
+      rerender();
+      return true;
+    },
+    focusAt(x: number, y: number) {
+      const hitbox = resolvePointerTarget(currentHitboxes, x, y);
+      if (!hitbox) {
+        clearSemanticHover(undefined, x, y);
+        return false;
+      }
+      setSemanticHoverFromHitbox(hitbox.id, x, y);
+      const node = findFocusableById(currentTree, hitbox.id);
+      if (!node) {
+        return false;
+      }
+      focusedId = node.props.id || focusedId;
+      skipFocusContainmentOnce = true;
+      rerender();
+      return true;
+    },
+    focusNext() {
+      const focusables = orderedFocusables();
+      if (!focusables.length) {
+        return false;
+      }
+      const currentIndex = focusables.findIndex((node) => node.props.id === focusedId);
+      focusedId = focusables[(currentIndex + 1 + focusables.length) % focusables.length].props.id || null;
+      rerender();
+      return true;
+    },
+    focusPrev() {
+      const focusables = orderedFocusables();
+      if (!focusables.length) {
+        return false;
+      }
+      const currentIndex = focusables.findIndex((node) => node.props.id === focusedId);
+      const nextIndex = currentIndex <= 0 ? focusables.length - 1 : currentIndex - 1;
+      focusedId = focusables[nextIndex].props.id || null;
+      rerender();
+      return true;
+    },
+    dispatchKey(key: string) {
+      const node = findFocused(currentTree, focusedId);
+      const context: TerminalCommandContext = { key, focusedId: node?.props.id, focusedTag: node?.tag };
+      let command = resolveTerminalKeyBinding(keyBindings, context);
+      if (!command && node?.tag === "terminal-editor" && key.length === 1) {
+        command = { id: "editor.insertText", text: key };
+      }
+      if (!command && node?.tag === "terminal-editor" && key === "CTRL_V") {
+        command = { id: "editor.paste" };
+      }
+      return command ? runCommand(command, node, context) : currentOutput;
+    },
+    click(id?: string) {
+      const node = id ? findFocusableById(currentTree, id) : findFocused(currentTree, focusedId);
+      if (!node || node.tag !== "terminal-button") {
+        return currentOutput;
+      }
+      if (id) {
+        focusedId = node.props.id || focusedId;
+      }
+      dispatchNodeEvent(node, "press", { type: "press", id: String(node.props.id || "") });
+      return rerender();
+    },
+    clickAt(x: number, y: number) {
+      const hitbox = resolvePointerTarget(currentHitboxes, x, y);
+      if (!hitbox) {
+        clearSemanticHover(undefined, x, y);
+        return currentOutput;
+      }
+      if (hitbox.tag === "terminal-button") {
+        return this.click(hitbox.id);
+      }
+      setSemanticHoverFromHitbox(hitbox.id, x, y);
+      focusedId = hitbox.id;
+      if (hitbox.tag === "terminal-input") {
+        mouseSelectionId = hitbox.id;
+        return setCursorFromHitbox(hitbox.id, x, false);
+      }
+      rerender();
+      return currentOutput;
+    },
+    clipboard() {
+      return clipboardValue;
+    },
+    setClipboard(value: string) {
+      return writeClipboard(value);
+    },
+    selectAll() {
+      const node = findFocused(currentTree, focusedId);
+      if (!node || node.tag !== "terminal-input" || !node.props.id) {
+        return currentOutput;
+      }
+      replaceInputState(node.props.id, selectAll(String(node.props.value ?? "")));
+      return rerender();
+    },
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      cancelPendingEscapeFlush();
+      cleanupOutputResize?.();
+      cleanupOutputResize = null;
+      outputResizeScheduler.cancel();
+      renderScheduler.cancel();
+      terminalRuntime.destroy();
+      emitLifecycleRestore();
+      outputWriter.destroy();
+      if (runtimeOptions.stdin) {
+        if (typeof runtimeOptions.stdin.off === "function") {
+          runtimeOptions.stdin.off("data", onData);
+        } else if (typeof runtimeOptions.stdin.removeListener === "function") {
+          runtimeOptions.stdin.removeListener("data", onData);
+        }
+        runtimeOptions.stdin.setRawMode?.(false);
+        runtimeOptions.stdin.pause?.();
+      }
+    }
+  };
+
+  function dispatchPasteText(text: string) {
+    const node = findFocused(currentTree, focusedId);
+    if (node?.tag === "terminal-editor") {
+      runCommand({ id: "editor.pasteText", text }, node, { key: text, focusedId: node.props.id, focusedTag: node.tag });
+    } else if (node?.tag === "terminal-input") {
+      runCommand({ id: "input.pasteText", text }, node, { key: text, focusedId: node.props.id, focusedTag: node.tag });
+    }
+  }
+
+  function cancelPendingEscapeFlush() {
+    if (pendingEscapeFlush) {
+      clearTimeout(pendingEscapeFlush);
+      pendingEscapeFlush = null;
+    }
+  }
+
+  function flushPendingEscape() {
+    cancelPendingEscapeFlush();
+    if (destroyed || !pendingKeyChunk.startsWith(ESCAPE)) {
+      return;
+    }
+    const buffered = pendingKeyChunk;
+    pendingKeyChunk = "";
+    session.dispatchKey(parseTerminalKey(ESCAPE));
+    processInputStream(buffered.slice(ESCAPE.length));
+  }
+
+  function schedulePendingEscapeFlush() {
+    cancelPendingEscapeFlush();
+    pendingEscapeFlush = setTimeout(flushPendingEscape, 0);
+  }
+
+  function processKeyStream(value: string) {
+    if (!value) {
+      return;
+    }
+
+    for (const sequence of KNOWN_TERMINAL_KEY_SEQUENCES) {
+      if (value.startsWith(sequence)) {
+        session.dispatchKey(parseTerminalKey(sequence));
+        processInputStream(value.slice(sequence.length));
+        return;
+      }
+    }
+
+    if (value === ESCAPE) {
+      pendingKeyChunk = value;
+      schedulePendingEscapeFlush();
+      return;
+    }
+
+    if (isDisambiguatedBracketedPasteStartPrefix(value)) {
+      pendingPasteChunk = value;
+      return;
+    }
+
+    if (isKnownTerminalKeySequencePrefix(value)) {
+      pendingKeyChunk = value;
+      schedulePendingEscapeFlush();
+      return;
+    }
+
+    const paste = parseBracketedPaste(value);
+    if (paste) {
+      dispatchPasteText(paste.text);
+      processInputStream(paste.rest);
+      return;
+    }
+
+    const escapeIndex = value.indexOf("\u001b");
+    if (escapeIndex > 0) {
+      for (const char of value.slice(0, escapeIndex)) {
+        session.dispatchKey(parseTerminalKey(char));
+      }
+      processInputStream(value.slice(escapeIndex));
+      return;
+    }
+
+    const parsedKey = parseTerminalKey(value);
+    if (parsedKey !== value) {
+      session.dispatchKey(parsedKey);
+      return;
+    }
+
+    if (value.startsWith("\u001b")) {
+      session.dispatchKey(value);
+      return;
+    }
+
+    for (const char of value) {
+      session.dispatchKey(parseTerminalKey(char));
+    }
+  }
+
+  function processInputStream(value: string) {
+    if (!value) {
+      return;
+    }
+
+    if (pendingPasteChunk) {
+      pendingPasteChunk += value;
+      const paste = parseBracketedPaste(pendingPasteChunk);
+      if (!paste && isBracketedPasteStartPrefix(pendingPasteChunk)) {
+        return;
+      }
+      if (!paste) {
+        const buffered = pendingPasteChunk;
+        pendingPasteChunk = "";
+        processKeyStream(buffered);
+        return;
+      }
+      pendingPasteChunk = "";
+      dispatchPasteText(paste.text);
+      processInputStream(paste.rest);
+      return;
+    }
+
+    if (pendingKeyChunk) {
+      if (pendingKeyChunk === ESCAPE && !canContinueEscapeSequence(value)) {
+        flushPendingEscape();
+        processInputStream(value);
+        return;
+      }
+      const buffered = pendingKeyChunk + value;
+      cancelPendingEscapeFlush();
+      pendingKeyChunk = "";
+      processKeyStream(buffered);
+      return;
+    }
+
+    if (value === ESCAPE) {
+      processKeyStream(value);
+      return;
+    }
+
+    if (isBracketedPasteStartPrefix(value)) {
+      pendingPasteChunk = value;
+      return;
+    }
+
+    if (value.startsWith(BRACKETED_PASTE_START)) {
+      const paste = parseBracketedPaste(value);
+      if (!paste) {
+        pendingPasteChunk = value;
+        return;
+      }
+      dispatchPasteText(paste.text);
+      processInputStream(paste.rest);
+      return;
+    }
+
+    const parsed = parseTerminalInput(value);
+    if (parsed.type === "mouse") {
+      if (parsed.action === "press") {
+        const hitbox = resolvePointerTarget(currentHitboxes, parsed.x, parsed.y);
+        if (hitbox?.tag === "terminal-input") {
+          mouseSelectionId = hitbox.id;
+        }
+        const node = hitbox ? findFocusableById(currentTree, hitbox.id) : null;
+        if (hitbox && node && shouldPointerCapture(node)) {
+          setPointerCapture(hitbox.id, "press", sourceRowFromHitbox(node, hitbox, parsed.y), parsed.x, parsed.y);
+        }
+        session.clickAt(parsed.x, parsed.y);
+      } else if (parsed.action === "drag") {
+        if (mouseSelectionId) {
+          setCursorFromHitbox(mouseSelectionId, parsed.x, true);
+        } else {
+          hoverAt(parsed.x, parsed.y);
+        }
+      } else if (parsed.action === "release") {
+        mouseSelectionId = null;
+        const capturedId = pointerCaptureId;
+        const releaseHitbox = resolvePointerTarget(currentHitboxes, parsed.x, parsed.y);
+        const releaseNode = releaseHitbox ? findFocusableById(currentTree, releaseHitbox.id) : null;
+        const releaseRow = releaseHitbox && releaseNode
+          ? sourceRowFromHitbox(releaseNode, releaseHitbox, parsed.y)
+          : null;
+        setPointerCapture(null, "release", capturedId && releaseHitbox?.id === capturedId ? releaseRow : null, parsed.x, parsed.y);
+        const hitbox = resolvePointerTarget(currentHitboxes, parsed.x, parsed.y);
+        if (capturedId && hitbox && hitbox.id === capturedId && (hitbox.tag === "terminal-list" || hitbox.tag === "terminal-scroll")) {
+          setSemanticHoverFromHitbox(hitbox.id, parsed.x, parsed.y);
+          rerender();
+        } else {
+          clearSemanticHover(undefined, parsed.x, parsed.y);
+          rerender();
+        }
+      } else if (parsed.action === "wheel-up") {
+        wheelAt(parsed.x, parsed.y, -1);
+      } else if (parsed.action === "wheel-down") {
+        wheelAt(parsed.x, parsed.y, 1);
+      }
+      return;
+    }
+
+    processKeyStream(value);
+  }
+
+  const onData = (chunk: string | Uint8Array) => {
+    const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    processInputStream(value);
+  };
+
+  if (runtimeOptions.stdin) {
+    runtimeOptions.stdin.on("data", onData);
+    runtimeOptions.stdin.setRawMode?.(true);
+    runtimeOptions.stdin.resume?.();
+  }
+
+  function subscribeOutputResize() {
+    const stdout = runtimeOptions.stdout;
+    if (!stdout || typeof stdout.on !== "function") {
+      return;
+    }
+    const removeResizeListener = typeof stdout.off === "function" ? stdout.off.bind(stdout) : stdout.removeListener?.bind(stdout);
+    if (!removeResizeListener) {
+      return;
+    }
+    const onResize = () => {
+      const cols = stdout.columns;
+      const rows = stdout.rows;
+      if (!isValidTerminalDimension(cols) || !isValidTerminalDimension(rows)) {
+        return;
+      }
+      pendingOutputResize = { cols, rows };
+      outputResizeScheduler.requestRender();
+    };
+    try {
+      stdout.on("resize", onResize);
+    } catch {
+      return;
+    }
+    cleanupOutputResize = () => removeResizeListener("resize", onResize);
+  }
+
+  function applyPendingOutputResize() {
+    const nextSize = pendingOutputResize;
+    pendingOutputResize = null;
+    if (!nextSize || destroyed || (nextSize.cols === terminalSize.cols && nextSize.rows === terminalSize.rows)) {
+      return;
+    }
+    terminalSize = nextSize;
+    rerender();
+  }
+
+  subscribeOutputResize();
+
+  emitLifecycleSetup();
+  emitOutput();
+  autoProjectionEnabled = true;
+
+  return session;
+}