silvery 0.21.0 → 0.23.0

package/dist/wrap-measurer-registration-IV2HtcCd.d.mts

@@ -0,0 +1,3106 @@
+import { D as enableKittyKeyboard$1, E as disableMouse$1, F as TerminalCaps, O as enableMouse$1, T as disableKittyKeyboard$1, j as ColorLevel } from "./index-377zdPLP.mjs";
+import { Ct as Decoration, Ht as LayoutNode$1, Q as UnderlineStyle, S as Term, Tt as EventSource, X as Style, Z as TerminalBuffer, _ as BoundTerm, gt as AgNodeType, ht as AgNode, jt as Rect, nt as FrameCell, ut as FocusManager, wt as Event, xt as CursorShape$1 } from "./mouse-events-B2z5tbsL.mjs";
+import React, { ReactElement, ReactNode } from "react";
+
+//#region packages/ag-term/src/unicode.d.ts
+/**
+ * Run a function with a specific measurer as the active scope.
+ * Module-level convenience functions (graphemeWidth, displayWidth, etc.)
+ * will use this measurer instead of the lazy default for the duration.
+ */
+declare function runWithMeasurer<T>(measurer: Measurer, fn: () => T): T;
+/**
+ * Check if text sizing mode is currently enabled.
+ * Returns the default (false) since globals have been removed.
+ * Use measurer.textSizing for scoped queries.
+ */
+declare function isTextSizingEnabled(): boolean;
+/**
+ * Width measurement functions scoped to specific terminal capabilities.
+ * Created by createMeasurer() from TerminalCaps.
+ */
+interface Measurer {
+  readonly maybeWideEmojis: boolean;
+  readonly textSizing: boolean;
+  /** Height of one line in measurement units. Terminal: 1 (one cell row). Canvas pixel: e.g. 20. */
+  readonly lineHeight: number;
+  displayWidth(text: string): number;
+  displayWidthAnsi(text: string): number;
+  graphemeWidth(grapheme: string): number;
+  wrapText(text: string, width: number, trim?: boolean, hard?: boolean, truncateAtomicOverflow?: boolean): string[];
+  sliceByWidth(text: string, maxWidth: number): string;
+  sliceByWidthFromEnd(text: string, maxWidth: number): string;
+}
+/**
+ * Create a width measurer scoped to terminal capabilities.
+ * Each measurer has its own caches (no shared global state).
+ */
+declare function createMeasurer(caps?: {
+  maybeWideEmojis?: boolean;
+  textSizing?: boolean;
+}): Measurer;
+/**
+ * Split a string into grapheme clusters.
+ * Each grapheme is a user-perceived character that may consist of
+ * multiple Unicode code points.
+ *
+ * Examples:
+ * - "cafe\u0301" (café with combining accent) -> ["c", "a", "f", "e\u0301"]
+ * - "👨‍👩‍👧" (family emoji) -> ["👨‍👩‍👧"]
+ * - "한국어" -> ["한", "국", "어"]
+ */
+declare function splitGraphemes(text: string): string[];
+/**
+ * Count the number of graphemes in a string.
+ */
+declare function graphemeCount(text: string): number;
+/**
+ * Append VS16 (U+FE0F) to emoji characters that have default text presentation.
+ *
+ * Use this to normalize icon characters for consistent terminal rendering.
+ * Characters that already have emoji presentation or VS16 are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * ensureEmojiPresentation('⚠')  // '⚠\uFE0F' (⚠️)
+ * ensureEmojiPresentation('☑')  // '☑\uFE0F' (☑️)
+ * ensureEmojiPresentation('☐')  // '☐' (unchanged, not an emoji)
+ * ensureEmojiPresentation('📁') // '📁' (unchanged, already emoji presentation)
+ * ```
+ */
+declare function ensureEmojiPresentation(char: string): string;
+/**
+ * Get the display width of a string (number of terminal columns).
+ * Uses string-width which handles:
+ * - Wide characters (CJK) -> 2 columns
+ * - Regular ASCII -> 1 column
+ * - Zero-width characters (combining, ZWJ) -> 0 columns
+ * - Emoji -> varies (1 or 2)
+ * - ANSI escape sequences -> 0 columns (stripped)
+ *
+ * Corrects string-width for text-presentation emoji characters
+ * (e.g., ⚠ U+26A0) that terminals render as 2 columns wide.
+ *
+ * Results are cached for performance.
+ */
+declare function displayWidth(text: string): number;
+/**
+ * Get the display width of a single grapheme.
+ *
+ * Overrides string-width for characters that are Extended_Pictographic with
+ * default text presentation. These characters (e.g., ⚠ U+26A0, ☑ U+2611)
+ * are reported as width 1 by string-width (per Unicode EAW tables), but most
+ * modern terminals render them as 2 columns wide using emoji glyphs.
+ *
+ * The mismatch causes text after these characters to be placed at the wrong
+ * column, leading to truncation or overlap.
+ */
+declare function graphemeWidth(grapheme: string): number;
+/**
+ * Check if a grapheme is a wide character (takes 2 columns).
+ */
+declare function isWideGrapheme(grapheme: string): boolean;
+/**
+ * Check if a grapheme is zero-width (combining character, ZWJ, etc.).
+ */
+declare function isZeroWidthGrapheme(grapheme: string): boolean;
+/**
+ * Truncate a string to fit within a given display width.
+ * Handles wide characters and ANSI escape sequences (including OSC 8 hyperlinks) correctly.
+ *
+ * @param text - The text to truncate (may contain ANSI escape sequences)
+ * @param maxWidth - Maximum display width
+ * @param ellipsis - Ellipsis to append if truncated (default: "...")
+ * @returns Truncated string
+ */
+declare function truncateText(text: string, maxWidth: number, ellipsis?: string): string;
+/**
+ * Pad a string to a given display width.
+ *
+ * @param text - The text to pad
+ * @param width - Target display width
+ * @param align - Alignment: 'left', 'right', or 'center'
+ * @param padChar - Character to use for padding (default: space)
+ * @returns Padded string
+ */
+declare function padText(text: string, width: number, align?: "left" | "right" | "center", padChar?: string): string;
+/**
+ * Constrain text to width and height limits.
+ * Combines wrapping and truncation to fit text in a box.
+ *
+ * @param text - Text to constrain (may contain ANSI codes)
+ * @param width - Maximum display width per line
+ * @param maxLines - Maximum number of lines
+ * @param pad - If true, pad lines to full width
+ * @param ellipsis - Custom ellipsis character (default: "…")
+ * @returns Object with lines array and truncated flag
+ */
+declare function constrainText(text: string, width: number, maxLines: number, pad?: boolean, ellipsis?: string): {
+  lines: string[];
+  truncated: boolean;
+};
+/**
+ * Wrap text to fit within a given width.
+ *
+ * Implements word-boundary wrapping:
+ * 1. Breaks at word boundaries (spaces, hyphens) when possible
+ * 2. Falls back to character wrap only when necessary (very long words)
+ * 3. Handles CJK text properly (can break anywhere since CJK has no word spaces)
+ * 4. Preserves intentional line breaks
+ *
+ * @param text - The text to wrap (may contain ANSI escape sequences)
+ * @param width - Maximum display width per line
+ * @param preserveNewlines - Whether to preserve existing newlines
+ * @param trim - Trim trailing spaces on broken lines and skip leading spaces on continuation lines (useful for rendering)
+ * @param truncateAtomicOverflow - When true, an unbreakable token wider than
+ *   `width` (no soft-break separator) ends with a Unicode `…` ellipsis on
+ *   the offending line and the rest of the token is dropped, instead of
+ *   character-wrapping. Implements the `wrap="wrap-truncate"` mode —
+ *   CSS-equivalent `overflow-wrap: break-word` + `text-overflow: ellipsis`.
+ *   Default `false` preserves existing character-wrap fallback (`wrap="wrap"`).
+ * @returns Array of wrapped lines
+ */
+declare function wrapText(text: string, width: number, preserveNewlines?: boolean, trim?: boolean, truncateAtomicOverflow?: boolean): string[];
+/**
+ * Slice text by display width (from start).
+ * Returns the first `maxWidth` columns of text.
+ * Uses the default measurer for width calculations.
+ * Handles both ANSI-styled and plain text.
+ *
+ * @param text - The text to slice
+ * @param maxWidth - Maximum display width to keep from the start
+ * @returns Sliced string from the start
+ */
+declare function sliceByWidth(text: string, maxWidth: number): string;
+/**
+ * Slice a string by display width range.
+ * Like string.slice() but works with display columns.
+ *
+ * @param text - The text to slice
+ * @param start - Start display column (inclusive)
+ * @param end - End display column (exclusive)
+ * @returns Sliced string
+ */
+declare function sliceByWidthRange(text: string, start: number, end?: number): string;
+/**
+ * Slice text by display width from the end.
+ * Returns the last `maxWidth` columns of text.
+ * Uses the default measurer for width calculations.
+ *
+ * @param text - The text to slice
+ * @param maxWidth - Maximum display width to keep from the end
+ * @returns Sliced string from the end
+ */
+declare function sliceByWidthFromEnd(text: string, maxWidth: number): string;
+/**
+ * Write styled text to a terminal buffer.
+ *
+ * Handles:
+ * - Multi-byte graphemes (emoji, combining characters)
+ * - Wide characters (CJK) that take 2 cells
+ * - Zero-width characters (appended to previous cell)
+ *
+ * @param buffer - The buffer to write to
+ * @param x - Starting column
+ * @param y - Row
+ * @param text - Text to write
+ * @param style - Style to apply
+ * @returns The ending column (x + display_width)
+ */
+declare function writeTextToBuffer(buffer: TerminalBuffer, x: number, y: number, text: string, style?: Style): number;
+/**
+ * Write styled text to a buffer with automatic truncation.
+ *
+ * @param buffer - The buffer to write to
+ * @param x - Starting column
+ * @param y - Row
+ * @param text - Text to write
+ * @param maxWidth - Maximum width (truncate if exceeded)
+ * @param style - Style to apply
+ * @param ellipsis - Ellipsis for truncated text
+ */
+declare function writeTextTruncated(buffer: TerminalBuffer, x: number, y: number, text: string, maxWidth: number, style?: Style, ellipsis?: string): void;
+/**
+ * Write multiple lines of styled text to a buffer.
+ *
+ * @param buffer - The buffer to write to
+ * @param x - Starting column
+ * @param y - Starting row
+ * @param lines - Lines to write
+ * @param style - Style to apply
+ */
+declare function writeLinesToBuffer(buffer: TerminalBuffer, x: number, y: number, lines: string[], style?: Style): void;
+/**
+ * Strip all ANSI escape codes from a string.
+ *
+ * Handles:
+ * - CSI sequences (cursor movement, colors, SGR, etc.)
+ * - OSC sequences (window titles, hyperlinks)
+ * - Single-character escape sequences
+ * - Character set selection
+ */
+declare function stripAnsi(text: string): string;
+/**
+ * Get display width of text with ANSI sequences.
+ * ANSI sequences don't contribute to display width.
+ */
+declare function displayWidthAnsi(text: string): number;
+/**
+ * Truncate text that may contain ANSI sequences.
+ * Preserves ANSI codes while truncating visible characters.
+ *
+ * Note: This is a simplified implementation that strips ANSI before
+ * truncation. For proper ANSI-aware truncation, consider using
+ * slice-ansi or similar library.
+ */
+declare function truncateAnsi(text: string, maxWidth: number, ellipsis?: string): string;
+/** Styled text segment with associated ANSI colors/attributes */
+interface StyledSegment {
+  text: string;
+  fg?: number | null;
+  bg?: number | null;
+  /**
+   * Underline color (SGR 58).
+   * Same format as fg/bg: packed RGB with 0x1000000 marker, or 256-color index.
+   */
+  underlineColor?: number | null;
+  bold?: boolean;
+  dim?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  /**
+   * Underline style variant (SGR 4:x).
+   * Uses UnderlineStyle from buffer.ts.
+   */
+  underlineStyle?: UnderlineStyle;
+  inverse?: boolean;
+  /** Strikethrough (SGR 9 on, SGR 29 off). */
+  strikethrough?: boolean;
+  /** Overline (SGR 53 on, SGR 55 off). */
+  overline?: boolean;
+  bgOverride?: boolean;
+  /**
+   * OSC 8 hyperlink URL.
+   * Set when the segment is inside an OSC 8 hyperlink sequence.
+   */
+  hyperlink?: string;
+  /**
+   * True when the foreground color was specified using colon-separated SGR
+   * (e.g., `38:2::255:100:0m` instead of `38;2;255;100;0m`).
+   * Used to preserve the original format in round-trip output.
+   */
+  colonFg?: boolean;
+  /**
+   * True when the background color was specified using colon-separated SGR.
+   */
+  colonBg?: boolean;
+}
+/**
+ * Parse text with ANSI escape sequences into styled segments.
+ * Handles basic SGR (Select Graphic Rendition) codes including:
+ * - Standard colors (30-37, 40-47, 90-97, 100-107)
+ * - Extended colors (38;5;N, 48;5;N for 256-color, 38;2;r;g;b, 48;2;r;g;b for RGB)
+ * - Underline styles (4:x where x = 0-5)
+ * - Underline color (58;5;N for 256-color, 58;2;r;g;b for RGB)
+ */
+declare function parseAnsiText(text: string): StyledSegment[];
+/**
+ * Check if text contains ANSI escape sequences (SGR or OSC).
+ * Detects both ESC-based (7-bit) and C1 (8-bit) forms:
+ * - ESC [ params final (CSI)
+ * - ESC ] (OSC)
+ * - U+009B params final (C1 CSI)
+ * - U+009D (C1 OSC)
+ */
+declare function hasAnsi(text: string): boolean;
+/**
+ * Measure the dimensions of multi-line text.
+ *
+ * @param text - Text to measure (may contain newlines)
+ * @returns { width, height } in display columns and rows
+ */
+declare function measureText(text: string): {
+  width: number;
+  height: number;
+};
+/**
+ * Check if a string contains any wide characters.
+ */
+declare function hasWideCharacters(text: string): boolean;
+/**
+ * Check if a string contains any combining/zero-width characters.
+ */
+declare function hasZeroWidthCharacters(text: string): boolean;
+/**
+ * Normalize string for consistent handling.
+ * Applies Unicode NFC normalization.
+ */
+declare function normalizeText(text: string): string;
+/**
+ * Get the first code point of a string.
+ */
+declare function getFirstCodePoint(str: string): number;
+/**
+ * Check if a grapheme is likely an emoji.
+ * Note: This is a heuristic, not comprehensive.
+ */
+declare function isLikelyEmoji(grapheme: string): boolean;
+/**
+ * Check if a grapheme is a CJK character.
+ */
+declare function isCJK(grapheme: string): boolean;
+//#endregion
+//#region packages/ag-term/src/clipboard.d.ts
+/**
+ * Clipboard Backend Abstraction
+ *
+ * Pluggable clipboard system with support for multiple backends.
+ * The default backend uses OSC 52 for terminal clipboard access.
+ *
+ * Architecture:
+ * - ClipboardBackend: interface for clipboard read/write
+ * - ClipboardData: multi-format clipboard content (text, markdown, html, internal)
+ * - createOsc52Backend: OSC 52 terminal clipboard (default)
+ * - createInternalClipboardBackend: in-memory store for rich app-internal paste
+ * - createCompositeClipboard: fan-out writes to multiple backends
+ *
+ * OSC 52 Protocol:
+ * - Copy:    ESC ] 52 ; c ; <base64> BEL
+ * - Query:   ESC ] 52 ; c ; ? BEL
+ * - Response: ESC ] 52 ; c ; <base64> BEL  (or ST terminator)
+ *
+ * Supported by: Ghostty, Kitty, WezTerm, iTerm2, xterm, foot, tmux
+ */
+/**
+ * Multi-format clipboard content.
+ *
+ * Plain text is always present. Optional rich formats allow applications
+ * to provide structured data for within-app paste without losing it
+ * through the plain-text-only system clipboard.
+ */
+interface ClipboardData {
+  /** Plain text content (always present) */
+  text: string;
+  /** Markdown representation */
+  markdown?: string;
+  /** HTML representation */
+  html?: string;
+  /** App-specific structured data (e.g., node tree for structured paste) */
+  internal?: unknown;
+}
+/**
+ * Clipboard backend capabilities.
+ *
+ * `text` is always true — every backend supports plain text.
+ * Rich format support is backend-dependent.
+ */
+interface ClipboardCapabilities {
+  readonly text: true;
+  readonly html?: boolean;
+  readonly markdown?: boolean;
+  readonly internal?: boolean;
+}
+/**
+ * Pluggable clipboard backend.
+ *
+ * Backends handle the transport of clipboard data to/from the system
+ * or an in-memory store. The framework writes ClipboardData; the backend
+ * decides what formats it can actually carry.
+ */
+interface ClipboardBackend {
+  /** Write clipboard data. Backends may ignore formats they don't support. */
+  write(data: ClipboardData): void | Promise<void>;
+  /** Read clipboard contents as plain text. Not all backends support read. */
+  read?(): Promise<string>;
+  /** What formats this backend supports */
+  readonly capabilities: ClipboardCapabilities;
+}
+/** Minimal writable interface for clipboard output */
+interface Writable {
+  write(data: string): boolean | void;
+}
+/**
+ * Upper bound on the decoded size of an OSC 52 clipboard payload.
+ *
+ * OSC 52 responses are attacker-influenceable: a hostile program on the far end
+ * of an SSH session, or a malicious terminal emulator, can emit an arbitrary
+ * base64 blob that arrives on stdin and is decoded here (see the
+ * `input-owner.ts` clipboard-response path that fires it as a paste). Node's
+ * base64 decoder never throws and imposes no size limit, so without a cap a
+ * single response could force an arbitrarily large allocation and then be fed
+ * into a focused guest as pasted input. Real clipboards are small — terminals
+ * themselves cap OSC 52 payloads around ~100 KB (see the `createOsc52Backend`
+ * quirks note) — so 1 MiB sits comfortably above any legitimate clipboard while
+ * keeping the decode bounded.
+ */
+/**
+ * Create an OSC 52 clipboard backend.
+ *
+ * Writes plain text to the system clipboard via the terminal's OSC 52 support.
+ * Works across SSH sessions. Rich formats (markdown, html, internal) are
+ * silently ignored — OSC 52 only carries plain text.
+ *
+ * Quirks:
+ * - Some terminals limit payload size (~100KB)
+ * - tmux requires `set -g set-clipboard on`
+ * - Some terminals only support BEL terminator (not ST)
+ */
+declare function createOsc52Backend(stdout: Writable): ClipboardBackend;
+/**
+ * In-memory clipboard store for within-app paste.
+ *
+ * Stores the full ClipboardData including rich formats that OSC 52 can't carry.
+ * Used alongside OSC 52 so plain text goes to the system clipboard while
+ * rich data is available for internal paste operations.
+ */
+declare function createInternalClipboardBackend(): ClipboardBackend & {
+  /** Get the stored clipboard data, or null if empty */getData(): ClipboardData | null; /** Get the timestamp of the last write */
+  getTimestamp(): number;
+};
+/**
+ * Create a composite clipboard that writes to multiple backends.
+ *
+ * Writes fan out to all backends. Reads come from the first backend
+ * that supports read (in order). This lets you do OSC 52 + internal
+ * store simultaneously: plain text goes to system clipboard, rich
+ * data stays in memory for structured paste.
+ */
+declare function createCompositeClipboard(...backends: ClipboardBackend[]): ClipboardBackend;
+/**
+ * Parse an OSC 52 clipboard response and decode the base64 content.
+ *
+ * Return semantics (see {@link ProtocolError} for the full contract):
+ * - `null` — input is NOT an OSC 52 clipboard response (no prefix, or a
+ *   query marker `?` rather than a response). Callers in a discriminator
+ *   chain treat this as "next parser please."
+ * - `throw ProtocolError` — input HAS the OSC 52 prefix (we committed to
+ *   this protocol) but is malformed (e.g., missing terminator). Loud
+ *   failure is required by bead 15127 acceptance line 22.
+ *
+ * Handles both BEL (\x07) and ST (ESC \) terminators.
+ */
+declare function parseClipboardResponse(input: string): string | null;
+//#endregion
+//#region packages/headless/src/pointer.d.ts
+interface Position {
+  x: number;
+  y: number;
+}
+//#endregion
+//#region packages/ag-term/src/drag-events.d.ts
+/**
+ * Active drag session state.
+ * Created when pointer state machine emits startDrag, updated on updateDrag,
+ * cleared on finishDrag/cancelDrag.
+ */
+interface DragState {
+  /** Whether a drag is currently active */
+  active: boolean;
+  /** The node being dragged (has draggable=true) */
+  source: AgNode;
+  /** Terminal position where the drag started */
+  startPos: Position;
+  /** Current drag position (updated on every pointer move) */
+  currentPos: Position;
+  /** Node currently under the cursor that accepts drops (has onDrop handler), or null */
+  dropTarget: AgNode | null;
+}
+//#endregion
+//#region packages/headless/src/copy-mode.d.ts
+/**
+ * Copy-mode state machine — pure TEA `(action, state) → [state, effects[]]`.
+ *
+ * Keyboard-driven selection mode (vim-like visual mode).
+ * When active, h/j/k/l navigate a cursor, v/V toggle visual selection,
+ * y yanks (copies) the selection and exits.
+ */
+interface CopyModePosition {
+  col: number;
+  row: number;
+}
+interface CopyModeState {
+  /** Whether copy-mode is active */
+  active: boolean;
+  /** Current cursor position */
+  cursor: CopyModePosition;
+  /** Character-wise visual mode (v) */
+  visual: boolean;
+  /** Line-wise visual mode (V) */
+  visualLine: boolean;
+  /** Start of visual selection (set when visual mode is entered) */
+  anchor: CopyModePosition | null;
+  /** Buffer dimensions for boundary clamping */
+  bufferWidth: number;
+  bufferHeight: number;
+}
+//#endregion
+//#region packages/ag-term/src/output.d.ts
+/**
+ * Generate ANSI sequence to move cursor to position.
+ * Terminal positions are 1-indexed.
+ */
+declare function moveCursor$1(x: number, y: number): string;
+/**
+ * Generate ANSI sequence to move cursor up N lines.
+ */
+declare function cursorUp(n: number): string;
+/**
+ * Generate ANSI sequence to move cursor down N lines.
+ */
+declare function cursorDown(n: number): string;
+/**
+ * Generate ANSI sequence to move cursor right N columns.
+ */
+declare function cursorRight(n: number): string;
+/**
+ * Generate ANSI sequence to move cursor left N columns.
+ */
+declare function cursorLeft(n: number): string;
+/**
+ * Generate ANSI sequence to move cursor to column.
+ */
+declare function cursorToColumn(x: number): string;
+/**
+ * Terminal cursor shape. Combined with blink parameter in setCursorStyle().
+ */
+type CursorShape = "block" | "underline" | "bar";
+/**
+ * Set the terminal cursor shape via DECSCUSR (CSI Ps SP q).
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, iTerm2, Alacritty, foot.
+ * Terminals that don't support it safely ignore the sequence.
+ *
+ * @param shape - "block", "underline", or "bar"
+ * @param blink - Whether the cursor should blink (default: false)
+ */
+declare function setCursorStyle(shape: CursorShape, blink?: boolean): string;
+/**
+ * Reset the terminal cursor style to the terminal's default (DECSCUSR 0).
+ */
+declare function resetCursorStyle(): string;
+declare const enableMouse: typeof enableMouse$1;
+declare const disableMouse: typeof disableMouse$1;
+/**
+ * Kitty keyboard protocol flags (bitfield).
+ *
+ * | Flag | Bit | Description                                    |
+ * | ---- | --- | ---------------------------------------------- |
+ * | 1    | 0   | Disambiguate escape codes                      |
+ * | 2    | 1   | Report event types (press/repeat/release)      |
+ * | 4    | 2   | Report alternate keys                          |
+ * | 8    | 3   | Report all keys as escape codes                |
+ * | 16   | 4   | Report associated text                         |
+ */
+declare const KittyFlags: {
+  readonly DISAMBIGUATE: 1;
+  readonly REPORT_EVENTS: 2;
+  readonly REPORT_ALTERNATE: 4;
+  readonly REPORT_ALL_KEYS: 8;
+  readonly REPORT_TEXT: 16;
+};
+/**
+ * Enable Kitty keyboard protocol (push mode).
+ * Sends CSI > flags u to opt into the specified modes.
+ * Default flags=11 (DISAMBIGUATE | REPORT_EVENTS | REPORT_ALL_KEYS) —
+ * enables modifier-only key reporting needed for useModifierKeys() Cmd tracking.
+ * Supported: Ghostty, Kitty, WezTerm, foot. Ignored by unsupported terminals.
+ *
+ * @param flags Bitfield of KittyFlags (default: DISAMBIGUATE)
+ */
+declare const enableKittyKeyboard: typeof enableKittyKeyboard$1;
+declare function queryKittyKeyboard(): string;
+declare const disableKittyKeyboard: typeof disableKittyKeyboard$1;
+/** BEL character — audible bell and legacy OSC string terminator. */
+declare const BEL = "\u0007";
+/**
+ * Set the terminal window title using OSC 2 (window title only).
+ * Does not affect icon title (tab name in some terminals).
+ * Widely supported: xterm, Ghostty, iTerm2, Kitty, WezTerm, Alacritty, foot.
+ */
+declare function setWindowTitle(stdout: NodeJS.WriteStream, title: string): void;
+/**
+ * Set both the window title and icon title using OSC 0.
+ * Some terminals treat OSC 0 as equivalent to OSC 2; others also change the
+ * dock/taskbar icon name.
+ */
+declare function setWindowAndIconTitle(stdout: NodeJS.WriteStream, title: string): void;
+/**
+ * Reset the terminal window title by sending an empty OSC 2 sequence.
+ * The terminal typically reverts to its default title (shell command, etc.).
+ */
+declare function resetWindowTitle(stdout: NodeJS.WriteStream): void;
+/** Report current working directory to the terminal via OSC 7.
+ * Used by terminals (iTerm2, Ghostty, WezTerm) for tab/split directory inheritance.
+ */
+declare function reportDirectory(stdout: NodeJS.WriteStream, path: string): void;
+/**
+ * Mouse cursor shape names for OSC 22.
+ *
+ * Uses X11/CSS cursor names. Supported by: Ghostty, Kitty (>=0.33), foot,
+ * WezTerm (partial). Terminals that don't support OSC 22 safely ignore it.
+ */
+type MouseCursorShape = "default" | "text" | "pointer" | "crosshair" | "move" | "not-allowed" | "wait" | "help" | "grab" | "grabbing" | "col-resize" | "row-resize" | "ew-resize" | "ns-resize";
+/**
+ * Generate OSC 22 sequence to set the mouse cursor shape.
+ *
+ * @param shape - X11/CSS cursor name
+ * @returns ANSI escape sequence string
+ */
+declare function setMouseCursorShape(shape: MouseCursorShape): string;
+/**
+ * Generate OSC 22 sequence to reset mouse cursor to default.
+ *
+ * @returns ANSI escape sequence string
+ */
+declare function resetMouseCursorShape(): string;
+declare const ANSI: {
+  readonly ESC: "\u001B";
+  readonly CSI: "\u001B[";
+  readonly CURSOR_HIDE: "\u001B[?25l";
+  readonly CURSOR_SHOW: "\u001B[?25h";
+  readonly CURSOR_HOME: "\u001B[H";
+  readonly SYNC_BEGIN: "\u001B[?2026h";
+  readonly SYNC_END: "\u001B[?2026l";
+  readonly RESET: "\u001B[0m";
+  readonly SGR: {
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly italic: 3;
+    readonly underline: 4;
+    readonly blink: 5;
+    readonly inverse: 7;
+    readonly hidden: 8;
+    readonly strikethrough: 9;
+    readonly boldOff: 22;
+    readonly italicOff: 23;
+    readonly underlineOff: 24;
+    readonly blinkOff: 25;
+    readonly inverseOff: 27;
+    readonly hiddenOff: 28;
+    readonly strikethroughOff: 29;
+    readonly fgDefault: 39;
+    readonly fgBlack: 30;
+    readonly fgRed: 31;
+    readonly fgGreen: 32;
+    readonly fgYellow: 33;
+    readonly fgBlue: 34;
+    readonly fgMagenta: 35;
+    readonly fgCyan: 36;
+    readonly fgWhite: 37;
+    readonly fgBrightBlack: 90;
+    readonly fgBrightRed: 91;
+    readonly fgBrightGreen: 92;
+    readonly fgBrightYellow: 93;
+    readonly fgBrightBlue: 94;
+    readonly fgBrightMagenta: 95;
+    readonly fgBrightCyan: 96;
+    readonly fgBrightWhite: 97;
+    readonly bgDefault: 49;
+    readonly bgBlack: 40;
+    readonly bgRed: 41;
+    readonly bgGreen: 42;
+    readonly bgYellow: 43;
+    readonly bgBlue: 44;
+    readonly bgMagenta: 45;
+    readonly bgCyan: 46;
+    readonly bgWhite: 47;
+    readonly bgBrightBlack: 100;
+    readonly bgBrightRed: 101;
+    readonly bgBrightGreen: 102;
+    readonly bgBrightYellow: 103;
+    readonly bgBrightBlue: 104;
+    readonly bgBrightMagenta: 105;
+    readonly bgBrightCyan: 106;
+    readonly bgBrightWhite: 107;
+  };
+  readonly moveCursor: typeof moveCursor$1;
+  readonly cursorUp: typeof cursorUp;
+  readonly cursorDown: typeof cursorDown;
+  readonly cursorLeft: typeof cursorLeft;
+  readonly cursorRight: typeof cursorRight;
+  readonly cursorToColumn: typeof cursorToColumn;
+};
+//#endregion
+//#region packages/ag-react/src/hooks/useCursor.d.ts
+interface CursorPosition {
+  /** Column offset within the component (0-indexed) */
+  col: number;
+  /** Row offset within the component (0-indexed) */
+  row: number;
+  /** Whether the cursor should be visible. Default: true */
+  visible?: boolean;
+  /** Terminal cursor shape (DECSCUSR). Default: terminal default */
+  shape?: CursorShape;
+}
+interface CursorState {
+  /** Absolute terminal X position (0-indexed) */
+  x: number;
+  /** Absolute terminal Y position (0-indexed) */
+  y: number;
+  /** Whether cursor is visible */
+  visible: boolean;
+  /** Terminal cursor shape (DECSCUSR) */
+  shape?: CursorShape;
+  /**
+   * Identity of the `useCursor` instance that last wrote this state. Set
+   * automatically by the hook on each store write. Used by the
+   * clear-on-unmount + clear-on-hide branches to skip the clear when
+   * THIS instance no longer owns the state — preventing the last-writer-
+   * wins stomp where an inactive sibling instance clears the active
+   * one's cursor. See bead `@km/silvery/13011-usecursor-race`. Optional
+   * because legacy external writes (Ink compat, direct store pokes) may
+   * omit it.
+   */
+  owner?: number;
+}
+/**
+ * Imperative cursor accessors for non-React code (scheduler, output phase).
+ * Created by createCursorStore() and threaded to consumers that can't use hooks.
+ */
+interface CursorAccessors {
+  getCursorState(): CursorState | null;
+  subscribeCursor(listener: () => void): () => void;
+}
+interface CursorStore {
+  state: CursorState | null;
+  listeners: Set<() => void>;
+  accessors: CursorAccessors;
+  setCursorState(state: CursorState | null): void;
+}
+/**
+ * Create an isolated cursor store. Each silvery instance gets one.
+ * Returns the store (for CursorProvider) and accessors (for scheduler/output).
+ */
+declare function createCursorStore(): CursorStore;
+/**
+ * Provider that gives its subtree an isolated cursor store.
+ * Wrap your silvery app root in this to isolate cursor state per instance.
+ */
+declare function CursorProvider({
+  store,
+  children
+}: {
+  store: CursorStore;
+  children?: ReactNode;
+}): React.FunctionComponentElement<React.ProviderProps<CursorStore | null>>;
+/** For testing -- reset global fallback state between tests. */
+declare function resetCursorState(): void;
+/**
+ * Show and position the terminal's blinking cursor within this component.
+ *
+ * The cursor position is relative to the component's screen position.
+ * Only one cursor can be active per silvery instance -- last caller with visible=true wins.
+ *
+ * Uses CursorContext if a CursorProvider is present (per-instance isolation).
+ * Falls back to module-level globals otherwise (backward compat).
+ *
+ * @deprecated Phase 2 of `km-silvery.view-as-layout-output` migrated cursor
+ * positioning from a React-effect-chain (`useCursor` → `useScrollRect` →
+ * `setCursorState`) to a layout-output prop (`<Box cursorOffset={…}>`). The
+ * prop path resolves absolute coordinates synchronously during the layout
+ * phase, so the very first frame after a conditional mount emits correct
+ * cursor ANSI — fixing `km-silvercode.cursor-startup-position` end-to-end.
+ *
+ * Migrate consumers by deleting the `useCursor({col, row, visible})` call
+ * and adding `cursorOffset={{col, row, visible}}` to the surrounding Box. The
+ * layout phase applies border + padding offsets automatically, so consumers
+ * no longer need to add `borderColOffset` / `borderRowOffset` manually.
+ *
+ * This hook remains as a back-compat wrapper that writes to the cursor
+ * store; the scheduler still reads the store as a fallback when no
+ * `cursorOffset` prop is set on any node. Slated for deletion once all
+ * in-tree consumers migrate (TextArea + TextInput already migrated; Ink
+ * compat goes through the store directly and is unaffected). See bead
+ * `km-silvery.delete-cursor-globals`.
+ */
+declare function useCursor(position: CursorPosition): void;
+//#endregion
+//#region packages/ag-term/src/pipeline/output-phase.d.ts
+interface OutputPhaseDiagnostics {
+  reason: "first-render" | "inline-first-render" | "inline-resize-incremental" | "inline-incremental" | "forced-full-render" | "dimension-mismatch" | "zero-diff" | "diff" | "native-scroll-diff";
+  mode: "fullscreen" | "inline";
+  width: number;
+  height: number;
+  prevWidth: number;
+  prevHeight: number;
+  changedCells?: number;
+  rawChangedCells?: number;
+  dirtyRows?: number;
+}
+/**
+ * Output-phase capabilities type.
+ *
+ * Post km-silvery.text-box-attr-props (2026-04-23):
+ * `underlineStyles` is now the per-style set (not just a boolean), so the
+ * output phase can downgrade individual styles — e.g. `"curly"` requested on
+ * a terminal that only supports `"single"` emits plain `SGR 4` instead of
+ * the unsupported `4:3`.
+ *
+ * Accepts either form at construction for backwards compatibility:
+ * - `boolean` — back-compat shorthand. `true` = all styles supported
+ *   (modern terminals); `false` = only plain `SGR 4` works.
+ * - `readonly UnderlineStyle[]` — per-style granular set, matches
+ *   `TerminalCaps.underlineStyles` directly.
+ *
+ * Internally the output phase always sees the array form (resolved by the
+ * ctx factory). Consumers check per-style via the `supportsUnderlineStyle`
+ * helper, or check "any extended support" via `caps.underlineStyles.length > 0`.
+ */
+type OutputUnderlineStylesCap = boolean | readonly UnderlineStyle[];
+interface OutputCaps {
+  /**
+   * Per-style underline support. Array form so the output phase can
+   * downgrade individual unsupported styles to plain SGR 4 (single).
+   * Empty array = plain SGR 4 only.
+   */
+  readonly underlineStyles: readonly UnderlineStyle[];
+  readonly underlineColor: boolean;
+  /**
+   * SGR 53 (overline) support. When false, the output phase skips
+   * emitting SGR 53/55 — the cell attr is still packed/diffed, but no
+   * escape sequence reaches the terminal. Defaults to true for modern
+   * terminals (Ghostty, iTerm2, xterm with extended attrs enabled).
+   */
+  readonly overline: boolean;
+  readonly colorLevel: TerminalCaps["colorLevel"];
+}
+/** Output phase function signature. */
+interface OutputPhaseFn {
+  (prev: TerminalBuffer | null, next: TerminalBuffer, mode?: "fullscreen" | "inline", scrollbackOffset?: number, termRows?: number, cursorPos?: CursorState | null): string;
+  /** Reset inline cursor state. Used by useScrollback to clear cursor tracking on resize. */
+  resetInlineState?: () => void;
+  /** Get the current inline cursor row (relative to render region start). -1 if unknown. */
+  getInlineCursorRow?: () => number;
+  /** Promote frozen content to scrollback. Called by useScrollback to queue
+   *  frozen content for the next render — the output phase writes frozen + live
+   *  content in a single target.write() to avoid flicker. */
+  promoteScrollback?: (frozenContent: string, frozenLineCount: number) => void;
+}
+interface OutputMeasurer {
+  graphemeWidth(grapheme: string): number;
+  readonly textSizing: boolean;
+}
+/**
+ * Create a scoped output phase that uses specific terminal capabilities.
+ *
+ * @param caps - Terminal capabilities for SGR code generation. Accepts
+ *   `underlineStyles` as either a boolean (back-compat) or the per-style
+ *   array form; see {@link OutputUnderlineStylesCap}.
+ * @param measurer - Width measurer for graphemeWidth/textSizing (avoids dual-module-loading issues)
+ */
+declare function createOutputPhase(caps: {
+  underlineStyles?: OutputUnderlineStylesCap;
+  underlineColor?: boolean;
+  overline?: boolean;
+  colorLevel?: TerminalCaps["colorLevel"];
+}, measurer?: OutputMeasurer): OutputPhaseFn;
+//#endregion
+//#region packages/ag-term/src/pipeline/types.d.ts
+/**
+ * Context threaded through the render pipeline.
+ *
+ * Carries per-render resources that were previously accessed via module-level
+ * globals (e.g., `_scopedMeasurer` + `runWithMeasurer()`). Threading context
+ * explicitly eliminates save/restore patterns and makes the pipeline pure.
+ *
+ * Phase 1: measurer only.
+ * Phase 2: NodeRenderState for per-node params.
+ * Phase 3: instrumentation/diagnostics fields (optional — fall back to
+ *   module-level globals when absent for backward compat).
+ */
+interface PipelineContext {
+  readonly measurer: Measurer;
+  readonly instrumentEnabled?: boolean;
+  readonly stats?: RenderPhaseStats;
+  readonly nodeTrace?: NodeTraceEntry[];
+  readonly nodeTraceEnabled?: boolean;
+  readonly bgConflictMode?: BgConflictMode;
+  readonly warnedBgConflicts?: Set<string>;
+}
+/**
+ * Background conflict detection mode.
+ * Set via SILVERY_BG_CONFLICT env var: 'ignore' | 'warn' | 'throw'
+ */
+type BgConflictMode = "ignore" | "warn" | "throw";
+/**
+ * Per-node trace entry for SILVERY_STRICT diagnosis.
+ */
+interface NodeTraceEntry {
+  id: string;
+  type: string;
+  depth: number;
+  rect: string;
+  prevLayout: string;
+  hasPrev: boolean;
+  ancestorCleared: boolean;
+  flags: string;
+  decision: string;
+  layoutChanged: boolean;
+  contentAreaAffected?: boolean;
+  contentRegionCleared?: boolean;
+  childrenNeedFreshRender?: boolean;
+  childHasPrev?: boolean;
+  childAncestorCleared?: boolean;
+  skipBgFill?: boolean;
+  bgColor?: string;
+}
+/**
+ * Mutable stats counters for render phase instrumentation.
+ * Reset after each renderPhase call.
+ */
+interface RenderPhaseStats {
+  nodesVisited: number;
+  nodesRendered: number;
+  nodesSkipped: number;
+  textNodes: number;
+  boxNodes: number;
+  clearOps: number;
+  /**
+   * Count of text nodes that took the per-segment style-only restyle fast path
+   * (skips collectTextWithBg→formatTextLines→renderGraphemes; restyles existing
+   * cells in place per child span). See render-text.ts `restyleTextSegments`.
+   */
+  textRestyleFastPath: number;
+  noPrevBuffer: number;
+  flagContentDirty: number;
+  flagStylePropsDirty: number;
+  flagLayoutChanged: number;
+  flagSubtreeDirty: number;
+  flagChildrenDirty: number;
+  flagChildPositionChanged: number;
+  flagAncestorLayoutChanged: number;
+  scrollContainerCount: number;
+  scrollViewportCleared: number;
+  scrollClearReason: string;
+  normalChildrenRepaint: number;
+  normalRepaintReason: string;
+  /**
+   * Count of children force-rendered because an earlier first-pass sibling's
+   * boxRect overlapped them. CSS paint order requires later siblings to win
+   * at any overlap; on incremental renders the earlier sibling's painting
+   * destroys the later sibling's pixels in the cloned buffer, so the later
+   * sibling must repaint even when its own dirty flags are clean.
+   */
+  siblingOverlapForced: number;
+  cascadeMinDepth: number;
+  cascadeNodes: string;
+  _noopSkip: number;
+  _prevBufferNull: number;
+  _prevBufferDimMismatch: number;
+  _hasPrevBuffer: number;
+  _layoutW: number;
+  _layoutH: number;
+  _prevW: number;
+  _prevH: number;
+  _callCount: number;
+}
+//#endregion
+//#region packages/ag-term/src/render-adapter.d.ts
+/**
+ * Render Adapter Abstraction
+ *
+ * This module defines the interfaces that allow silvery to render to different
+ * targets (terminal, canvas, etc.) while keeping the core layout and
+ * reconciliation logic portable.
+ */
+interface TextMeasureStyle {
+  bold?: boolean;
+  italic?: boolean;
+  fontSize?: number;
+  fontFamily?: string;
+}
+interface TextMeasureResult {
+  width: number;
+  height: number;
+}
+interface TextMeasurer {
+  /**
+   * Measure text dimensions.
+   * Returns width in adapter units (cells for terminal, pixels for canvas).
+   */
+  measureText(text: string, style?: TextMeasureStyle): TextMeasureResult;
+  /**
+   * Get the line height for the given style.
+   */
+  getLineHeight(style?: TextMeasureStyle): number;
+}
+interface RenderStyle {
+  /** Cross-target hyperlink carried by the rendered text cells. */
+  hyperlink?: string;
+  fg?: string;
+  bg?: string;
+  attrs?: {
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    underlineStyle?: "single" | "double" | "curly" | "dotted" | "dashed";
+    underlineColor?: string; /** Overline — SGR 53/55. Independent of underline. */
+    overline?: boolean;
+    strikethrough?: boolean;
+    inverse?: boolean;
+  };
+}
+interface RenderBuffer {
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Fill a rectangle with a style.
+   */
+  fillRect(x: number, y: number, width: number, height: number, style: RenderStyle): void;
+  /**
+   * Draw text at a position.
+   */
+  drawText(x: number, y: number, text: string, style: RenderStyle): void;
+  /**
+   * Draw a single character at a position.
+   */
+  drawChar(x: number, y: number, char: string, style: RenderStyle): void;
+  /**
+   * Check if coordinates are within bounds.
+   */
+  inBounds(x: number, y: number): boolean;
+  /**
+   * Draw a filled rounded rectangle with optional border stroke.
+   * Canvas-only — terminal adapters don't implement this.
+   */
+  fillRoundedRect?(x: number, y: number, width: number, height: number, radius: number, fill: string | undefined, stroke: string | undefined, lineWidth?: number): void;
+}
+interface BorderChars {
+  topLeft: string;
+  topRight: string;
+  bottomLeft: string;
+  bottomRight: string;
+  horizontal: string;
+  vertical: string;
+  /** Bottom horizontal character. When absent, falls back to `horizontal`. */
+  bottomHorizontal?: string;
+  /** Right vertical character. When absent, falls back to `vertical`. */
+  rightVertical?: string;
+}
+interface RenderAdapter {
+  /** Adapter name for debugging */
+  name: string;
+  /** Text measurement for this adapter */
+  measurer: TextMeasurer;
+  /**
+   * Create a buffer for rendering.
+   */
+  createBuffer(width: number, height: number): RenderBuffer;
+  /**
+   * Flush the buffer to the output (terminal, canvas, etc.).
+   * For terminal: returns ANSI diff string.
+   * For canvas: draws directly, returns void.
+   */
+  flush(buffer: RenderBuffer, prevBuffer: RenderBuffer | null): string | void;
+  /**
+   * Get border characters for the given style.
+   */
+  getBorderChars(style: string): BorderChars;
+}
+//#endregion
+//#region packages/ag/src/layout-signals.d.ts
+/**
+ * Writable signal — call with no args to read, call with value to write.
+ */
+type WritableSignal<T> = {
+  (): T;
+  (value: T): void;
+};
+/**
+ * Reactive projection of `AgNode.scrollState` — the layout-phase's pixel-space
+ * truth about what's visible in an `overflow="scroll"` container.
+ *
+ * This is the **single source of truth** that virtualization consumers (like
+ * `useVirtualizer` + `ListView`) read to decide which items to render. By
+ * subscribing to this signal instead of independently computing their own
+ * visible range, consumers cannot diverge from what layout-phase actually
+ * laid out on screen.
+ *
+ * Fields are pixel-space integers already rounded by the layout engine —
+ * re-using them (instead of recomputing via `sumHeights`) guarantees
+ * `leadingHeight == scrollOffset` by construction.
+ *
+ * `null` for non-scroll containers and for scroll containers before the first
+ * layout pass (bootstrap state — virtualizers must fall back to estimates).
+ */
+interface ScrollStateSnapshot {
+  /** Current scroll offset in terminal rows (pixel-space, pre-rounded). */
+  readonly offset: number;
+  /** Total content height (all children) in rows. */
+  readonly contentHeight: number;
+  /** Visible height (container height minus borders/padding). */
+  readonly viewportHeight: number;
+  /** Index of the first visible child (flexbox-measured). */
+  readonly firstVisibleChild: number;
+  /** Index of the last visible child (flexbox-measured). */
+  readonly lastVisibleChild: number;
+  /** Count of items hidden above the viewport. */
+  readonly hiddenAbove: number;
+  /** Count of items hidden below the viewport. */
+  readonly hiddenBelow: number;
+}
+/**
+ * Caret rect — absolute terminal coordinates of the caret declared on a
+ * Box via `cursorOffset`, computed during the layout phase as the peer of
+ * `scrollRect` / `screenRect` / `boxRect` / `contentRect`.
+ *
+ * Width/height are always 1 (the caret occupies a single cell). The
+ * `visible` flag is a separate property because layout still computes the
+ * coordinates even when the caret is hidden — that lets toggling
+ * `visible` re-emit the caret without re-running layout.
+ *
+ * `shape` is **deprecated** — the terminal layer now derives the shape
+ * from focus + editable state via `resolveCaretStyle` in `@silvery/ag-term`.
+ * The field is kept for one cycle so external readers that were already
+ * forwarding `cursor.shape` to DECSCUSR keep working; new code MUST NOT
+ * branch on this field. See bead `km-silvery.cursor-invariants` invariant 6.
+ */
+interface CursorRect {
+  /** Absolute terminal X column (0-indexed) */
+  readonly x: number;
+  /** Absolute terminal Y row (0-indexed) */
+  readonly y: number;
+  /** Whether the caret should be visible on this frame. */
+  readonly visible: boolean;
+  /**
+   * @deprecated Target-specific. Read focus state from the active cursor
+   * node via `resolveCaretStyle` in `@silvery/ag-term` instead. Removed in
+   * the next cycle.
+   */
+  readonly shape?: CursorShape$1;
+}
+/**
+ * All reactive signals for an AgNode.
+ *
+ * Combined rect signals (layout outputs) + node signals (content/state).
+ * One interface, one WeakMap, one sync function.
+ */
+interface LayoutSignals {
+  readonly boxRect: WritableSignal<Rect | null>;
+  readonly scrollRect: WritableSignal<Rect | null>;
+  readonly screenRect: WritableSignal<Rect | null>;
+  readonly boxRectCommitted: WritableSignal<Rect | null>;
+  readonly scrollRectCommitted: WritableSignal<Rect | null>;
+  readonly screenRectCommitted: WritableSignal<Rect | null>;
+  /**
+   * Content-box rect — `boxRect` minus border and padding (CSS content area).
+   * Peer of `boxRect`/`scrollRect`/`screenRect`, synced after layout. Null
+   * when the node has no boxRect yet (pre-layout) or is not a Box.
+   *
+   * This is the canonical origin for caret positioning, popover anchors,
+   * selection fragments, and any feature that needs to draw "inside" a Box's
+   * content area without re-deriving the border/padding math at the call
+   * site. `computeCursorRect` reads from this rect — Phase 4 / overlay-anchor
+   * work will too. See `km-silvery.cursor-invariants` invariant 3.
+   */
+  readonly contentRect: WritableSignal<Rect | null>;
+  /**
+   * Absolute terminal coordinates of the caret declared by this node's
+   * `BoxProps.cursorOffset`. Null when the node has no cursorOffset prop, or
+   * before the first layout pass populates `scrollRect`.
+   *
+   * Phase 2 of `km-silvery.view-as-layout-output` — the scheduler reads this
+   * signal (rather than `cursorStore.getCursorState()`) to emit caret
+   * positioning ANSI. Because layout phase runs synchronously before each
+   * render, the very first frame after mount sees the correct caret — no
+   * effect-chain stale-read on conditional mounts.
+   */
+  readonly cursorRect: WritableSignal<CursorRect | null>;
+  /**
+   * Focused-node id declared by this node's `BoxProps.focused`. The value is
+   * the node's `id` (preferred) or `testID` when `props.focused === true`,
+   * else `null`. Phase 4a of `km-silvery.view-as-layout-output` — the
+   * focus-renderer reads this signal (and/or `findActiveFocusedNodeId(root)`)
+   * to paint focus styling without going through the `useFocus` →
+   * `FocusManager` → `useSyncExternalStore` effect chain.
+   *
+   * Per-node by design (peer of `cursorRect`): each Box that participates in
+   * focus carries its own declared id here, and the tree-walk lookup picks
+   * the deepest visible declarer. Unmount is handled by WeakMap GC + the
+   * per-frame recompute in `syncRectSignals` clearing back to null when the
+   * prop is removed. See bead `km-silvery.phase4-split-focus-selection`.
+   */
+  readonly focusedNodeId: WritableSignal<string | null>;
+  /**
+   * Geometric output of `BoxProps.selectionIntent` — the list of rectangles
+   * (one per visual line spanned) that the selection renderer should paint
+   * with highlight bg this frame. Empty array when the node declares no
+   * `selectionIntent` or when the intent is collapsed (`from === to`).
+   *
+   * Phase 4b of `km-silvery.view-as-layout-output` — peer of `cursorRect`
+   * (caret) and `focusedNodeId` (focus). The selection renderer reads this
+   * signal (and/or `findActiveSelectionFragments(root)`) to paint highlight
+   * styling without going through the legacy `SelectionFeature` capability
+   * + `useSelection` `useSyncExternalStore` chain.
+   *
+   * Per-node by design: each Box that participates in selection carries its
+   * own fragments here. The aggregator (`findActiveSelectionFragments`)
+   * concatenates fragments across all mounted declarers — multi-node
+   * selection composes for free. Stale-cleanup is handled by WeakMap GC +
+   * the per-frame recompute in `syncRectSignals` clearing back to the empty
+   * sentinel when the prop is removed (mirrors cursor invariant 5 + focus
+   * invariant 3). See bead `km-silvery.phase4-split-focus-selection`.
+   */
+  readonly selectionFragments: WritableSignal<readonly Rect[]>;
+  readonly scrollState: WritableSignal<ScrollStateSnapshot | null>;
+  /**
+   * Geometric output of `BoxProps.anchorRef` — the rect that other Boxes'
+   * decorations resolve to when they reference this anchor by id. The
+   * registered rect is the Box's `contentRect` (border + padding excluded);
+   * edge-specific rects are derived by `placeFloating` at consumption time.
+   *
+   * Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1) — peer
+   * of `cursorRect`/`focusedNodeId`/`selectionFragments`. The tree-walk
+   * lookup `findAnchor(root, id)` reads this signal (and falls back to
+   * `computeAnchorRect` for nodes without signals).
+   *
+   * Null when:
+   *   - the node has no `anchorRef` BoxProp, OR
+   *   - `contentRect` is unavailable (pre-layout / clipped to zero size).
+   */
+  readonly anchorRect: WritableSignal<Rect | null>;
+  /**
+   * Absolute terminal coordinates of the HARDWARE-PARK cell declared by this
+   * node's `BoxProps.parkOffset` — where a managed frame parks (then hides) the
+   * hardware cursor when this node owns the frame. Position-only (1×1 rect);
+   * null when the node has no `parkOffset` prop or before the first layout pass.
+   *
+   * Peer of `cursorRect`, but NON-focus-gated: the tree-walk lookup
+   * `findActiveParkRect(root)` picks the deepest declarer regardless of focus or
+   * visibility, so a managed frame always has a benign park cell and never falls
+   * back to the box origin / `home(0,0)` (@km/code/v0.2/19702).
+   */
+  readonly parkRect: WritableSignal<Rect | null>;
+  /**
+   * Geometric output of `BoxProps.decorations` — the resolved per-decoration
+   * rect list this frame. Each entry carries the source kind, id, and rects
+   * (popover/tooltip → one rect at the placed position; highlight → one rect
+   * within the owning Box's content area).
+   *
+   * v1 emits one rect per decoration. The list mirrors the BoxProp's order so
+   * paint order is deterministic. When an anchor lookup fails (popover/tooltip
+   * with no matching `anchorRef`), the entry's `rects` is empty — the
+   * renderer skips it.
+   *
+   * Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+   */
+  readonly decorationRects: WritableSignal<readonly DecorationRect[]>;
+  readonly textContent: WritableSignal<string | undefined>;
+  readonly focused: WritableSignal<boolean>;
+}
+/**
+ * Geometric output of one `Decoration` entry — the resolved rects for paint
+ * time, plus the source kind/id so the renderer can dispatch by kind.
+ *
+ * Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+ *
+ * v1 emits one rect per decoration. Soft-wrap aware highlight fragmentation
+ * (multiple rects per highlight) is deferred to v2 — same path as
+ * `selectionFragments` once the find/replace consumer ships.
+ *
+ * `rects` may be empty when an anchor lookup failed (popover/tooltip with a
+ * missing `anchorId`); consumers SHOULD skip empty entries rather than
+ * paint a 0×0 rect.
+ */
+interface DecorationRect {
+  /** Decoration kind from the source `Decoration` entry. */
+  readonly kind: Decoration["kind"];
+  /** Stable id from the source `Decoration` entry. */
+  readonly id: string;
+  /** Resolved rects in absolute terminal cell space. May be empty. */
+  readonly rects: readonly Rect[];
+}
+//#endregion
+//#region packages/ag-term/src/pipeline/index.d.ts
+/**
+ * Options for render pipeline callers.
+ */
+interface ExecuteRenderOptions {
+  /**
+   * Render mode: fullscreen or inline.
+   * Default: 'fullscreen'
+   */
+  mode?: "fullscreen" | "inline";
+  /**
+   * Skip notifying layout subscribers.
+   * Use for static/one-shot renders where layout feedback isn't needed.
+   * Default: false
+   */
+  skipLayoutNotifications?: boolean;
+  /**
+   * Skip scroll state updates.
+   * Use for fresh render comparisons (SILVERY_STRICT) to avoid mutating state.
+   * Default: false
+   */
+  skipScrollStateUpdates?: boolean;
+  /**
+   * Number of lines written to stdout between renders (inline mode only).
+   * Used to adjust cursor positioning when external code (e.g., useScrollback)
+   * writes directly to stdout between renders.
+   * Default: 0
+   */
+  scrollbackOffset?: number;
+  /**
+   * Terminal height in rows (inline mode only).
+   * Used to clamp cursor-up offset when content exceeds terminal height.
+   * Without this, content taller than the terminal causes rendering corruption
+   * because cursor-up can't reach lines that scrolled off screen.
+   */
+  termRows?: number;
+  /**
+   * Cursor position from useCursor() (inline mode only).
+   * When provided, the output phase positions the real terminal cursor
+   * at this location instead of leaving it at the end of content.
+   */
+  cursorPos?: CursorState | null;
+}
+/**
+ * Pipeline configuration from withRender().
+ * Carries term-scoped width measurer and output phase.
+ */
+interface PipelineConfig {
+  /** Width measurer scoped to terminal capabilities */
+  readonly measurer: Measurer;
+  /** Output phase function scoped to terminal capabilities */
+  readonly outputPhaseFn: OutputPhaseFn;
+}
+//#endregion
+//#region packages/ag/src/cls.d.ts
+/**
+ * Why a layout shift happened. Used to filter "expected" shifts (the user
+ * scrolled, content arrived in a streaming view) from "unexpected" shifts
+ * (a code fence resized mid-stream, a status line bounced) — only the
+ * latter fail CLS strict checks.
+ */
+type ReflowReason = "user-action" | "unexpected" | "animation" | "content-arrival";
+/**
+ * Classifier function — given a block + rect transition, returns the
+ * reflow reason. The capture API passes a classifier that inspects layout
+ * context (user-action vs streamed content vs unsolicited reflow). Default
+ * classifier returns "unexpected" — most pessimistic, captures the bug
+ * class CLS is designed to detect.
+ */
+type ReasonClassifier = (blockId: string, fromRect: Rect, toRect: Rect, frameTimestamp: number) => ReflowReason;
+interface LayoutShift {
+  /** Stable identifier for the shifted block. */
+  blockId: string;
+  /** Position + size in the previous frame. */
+  fromRect: Rect;
+  /** Position + size in the current frame. */
+  toRect: Rect;
+  /** Wall-clock timestamp at frame end (ms since epoch). */
+  frameTimestamp: number;
+  /** Why the shift happened — see ReflowReason for taxonomy. */
+  reflowReason: ReflowReason;
+}
+interface CLSReport {
+  /** All shifts observed in the capture window. */
+  shifts: readonly LayoutShift[];
+  /** Sum of (area × distance) over all shifts (CLS metric proper). */
+  cumulativeScore: number;
+  /** Subset of shifts with reflowReason="unexpected" — the actionable ones. */
+  unexpectedShifts: readonly LayoutShift[];
+}
+//#endregion
+//#region packages/ag-react/src/debug/render-path.d.ts
+/**
+ * A summary of one node in a render-path or mount-tree dump.
+ * The shape is JSON-serializable for snapshot tests.
+ */
+interface RenderPathNode {
+  /** Component name (data-component prop, or `${hostType}#${testID|id}`, or hostType) */
+  name: string;
+  /** AgNode host type (silvery-box, silvery-text, silvery-root) */
+  type: AgNodeType;
+  /** Optional content-relative position from layout phase */
+  boxRect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+}
+/** Recursive mount tree — name + children for snapshot-friendly dumps. */
+interface MountTree extends RenderPathNode {
+  children: MountTree[];
+}
+//#endregion
+//#region packages/test/src/auto-locator.d.ts
+/**
+ * Filter options for locator narrowing
+ */
+interface FilterOptions {
+  /** Match nodes containing this text */
+  hasText?: string | RegExp;
+  /** Match nodes with this testID */
+  hasTestId?: string;
+  /** Match nodes with this attribute value */
+  has?: {
+    attr: string;
+    value?: string;
+  };
+}
+/**
+ * AutoLocator interface - lazy, self-refreshing reference to nodes
+ */
+interface AutoLocator {
+  getByText(text: string | RegExp): AutoLocator;
+  getByTestId(id: string): AutoLocator;
+  locator(selector: string): AutoLocator;
+  filter(options: FilterOptions): AutoLocator;
+  filter(predicate: (node: AgNode) => boolean): AutoLocator;
+  first(): AutoLocator;
+  last(): AutoLocator;
+  nth(index: number): AutoLocator;
+  resolve(): AgNode | null;
+  resolveAll(): AgNode[];
+  count(): number;
+  textContent(): string;
+  getAttribute(name: string): string | undefined;
+  boundingBox(): Rect | null;
+  isVisible(): boolean;
+}
+/**
+ * Create an AutoLocator from a container getter function.
+ * The getter is called fresh on each resolution.
+ */
+declare function createAutoLocator(getContainer: () => AgNode, opts?: {
+  strict?: boolean;
+}): AutoLocator;
+//#endregion
+//#region packages/ag-term/src/app.d.ts
+/**
+ * App interface - unified return type from render()
+ */
+/**
+ * Fluent chain of App actions. Each action method returns `ChainableApp`
+ * — a `PromiseLike<App>` that exposes the same action methods so calls
+ * can be composed without explicit `await` between every step.
+ *
+ * ```ts
+ * await app.keyDown("Super").hover(x, y).keyUp("Super")
+ * ```
+ *
+ * The returned chain `.then`-s into the App, so existing `await
+ * app.action(...)` calls continue to receive the App instance — the
+ * change is purely additive at the call site.
+ *
+ * Bead: @km/silvery/fluent-chain-actions.
+ */
+interface ChainableApp extends PromiseLike<App> {
+  press(key: string): ChainableApp;
+  keyDown(key: string): ChainableApp;
+  keyUp(key: string): ChainableApp;
+  pressSequence(...keys: string[]): ChainableApp;
+  type(text: string): ChainableApp;
+  click(x: number, y: number, options?: {
+    button?: number;
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  doubleClick(x: number, y: number, options?: {
+    button?: number;
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  hover(x: number, y: number, options?: {
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  wheel(x: number, y: number, delta: number, options?: {
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+}
+interface App {
+  /** Full rendered text (no ANSI codes) */
+  readonly text: string;
+  /** Full rendered text with ANSI styling */
+  readonly ansi: string;
+  /** Per-line plain text array (no ANSI codes) */
+  readonly lines: string[];
+  /** Frame width in terminal columns */
+  readonly width: number;
+  /** Frame height in terminal rows */
+  readonly height: number;
+  /** Get the cell at the given column and row (resolved styling) */
+  cell(col: number, row: number): FrameCell;
+  /** Check whether the plain text contains the given substring */
+  containsText(text: string): boolean;
+  /** Get node at content coordinates */
+  nodeAt(x: number, y: number): AgNode | null;
+  /** Get locator by testID attribute */
+  getByTestId(id: string): AutoLocator;
+  /** Get locator by text content */
+  getByText(text: string | RegExp): AutoLocator;
+  /** Get locator by CSS-style selector */
+  locator(selector: string): AutoLocator;
+  /**
+   * Send a single key press. Emits the bare Kitty CSI u shape
+   * (no `:eventType` byte) — the parser defaults to "press" without
+   * one. Equivalent to a full down+up keystroke for tests asserting
+   * "user typed key X". For held-state scenarios (Cmd-hover popovers,
+   * multi-key chords) use `keyDown` / `keyUp` which emit explicit
+   * `:1` (press) and `:3` (release) event-type bytes.
+   *
+   * Both bare-press and explicit-`:1` shapes parse to
+   * `{ eventType: "press" | undefined }` respectively; consumers that
+   * test `eventType !== "release"` see them identically. The shape
+   * difference is intentional: bare = transient single event, typed =
+   * paired down/up lifecycle. Bead:
+   * @km/silvery/keydown-keyup-test-primitives.
+   */
+  press(key: string): ChainableApp;
+  /**
+   * Send a key DOWN event without auto-release. Useful for held-modifier
+   * scenarios — e.g., `app.keyDown("Super")` then `app.hover(x, y)` then
+   * `app.keyUp("Super")` to drive a Cmd-hover popover that opens after a
+   * dwell timer reads the (still-held) modifier from the input store.
+   *
+   * Requires Kitty keyboard protocol (`kittyMode: true`) for modifier keys —
+   * legacy ANSI cannot represent Super (Cmd) alone.
+   *
+   * For a single press+release event (the common case) use `press()`. Bead:
+   * @km/silvery/keydown-keyup-test-primitives.
+   */
+  keyDown(key: string): ChainableApp;
+  /**
+   * Send a key UP event. Pairs with `keyDown(key)`. Drops the implicit
+   * modifier state (mouseState.keyboardModifiers + the input-store
+   * modifier tracker) so subsequent events run without the modifier
+   * asserted. Bead: @km/silvery/keydown-keyup-test-primitives.
+   */
+  keyUp(key: string): ChainableApp;
+  /** Send multiple key presses */
+  pressSequence(...keys: string[]): ChainableApp;
+  /** Type text input */
+  type(text: string): ChainableApp;
+  /** Simulate a mouse click at (x, y) terminal coordinates */
+  click(x: number, y: number, options?: {
+    button?: number;
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  /** Simulate a double-click at (x, y) terminal coordinates */
+  doubleClick(x: number, y: number, options?: {
+    button?: number;
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  /** Simulate a mouse move/hover at (x, y) terminal coordinates */
+  hover(x: number, y: number, options?: {
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  /** Simulate a mouse wheel event at (x, y) with delta (-1=up, +1=down) */
+  wheel(x: number, y: number, delta: number, options?: {
+    shift?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    cmd?: boolean;
+  }): ChainableApp;
+  /** Resize the virtual terminal and re-render. Only available in test renderer. */
+  resize(cols: number, rows: number): void;
+  /** Wait until app exits */
+  run(): Promise<void>;
+  /** Bound terminal for screen-space access */
+  readonly term: BoundTerm;
+  /** Re-render with a new element */
+  rerender(element: ReactNode): void;
+  /** Unmount the component and clean up */
+  unmount(): void;
+  /** Dispose (alias for unmount) — enables `using` */
+  [Symbol.dispose](): void;
+  /** Promise that resolves when the app exits (alias for run()) */
+  waitUntilExit(): Promise<void>;
+  /**
+   * Drain additional commit / layout cycles until layout reports stable
+   * (no node dirty, no pending React commit) OR a budget cap is reached
+   * (default 20 passes / 50ms wall clock).
+   *
+   * The default test harness exposes the post-`MAX_CONVERGENCE_PASSES`
+   * frame — matching what production silvery commits on first paint.
+   * Most tests don't need to wait further: keyboard / mouse input each
+   * runs its own bounded-convergence loop, so an assertion after `press()`
+   * already sees post-convergence state for that batch.
+   *
+   * This method is for assertions on layout state IMMEDIATELY after mount
+   * that require chains needing more than `MAX_CONVERGENCE_PASSES` passes
+   * to settle (rare with the layout-signals primitive, common with older
+   * useState+onLayout chains). Returns once stable so tests can assert
+   * post-convergence text/layout.
+   *
+   * Resolves without throwing even when the cap is hit — an infinitely
+   * non-converging app is a structural bug surfaced by SILVERY_STRICT's
+   * `assertBoundedConvergence`, not a test-author concern here.
+   *
+   * Bead: `@km/silvery/test-harness-convergence-cap-parity`.
+   */
+  waitForLayoutStable(opts?: {
+    timeoutMs?: number;
+    maxPasses?: number;
+  }): Promise<void>;
+  /**
+   * Begin a CLS capture window. Layout shifts that occur between this call
+   * and the next `endCLSCapture()` are recorded with the supplied
+   * `ReasonClassifier` (default: every shift labeled "unexpected"). Use
+   * `waitForLayoutStable()` to drain pending layout passes before reading
+   * the report.
+   *
+   * Throws if a capture is already active — call `endCLSCapture()` or
+   * `cancelCLSCapture()` first. The capture is process-wide (single active
+   * recorder per process); two parallel captures on different App
+   * instances is not supported by design.
+   *
+   * Bead: km-silvery.cls-instrumentation-primitive
+   */
+  beginCLSCapture(classifier?: ReasonClassifier): void;
+  /**
+   * End the active CLS capture and return the aggregated report. When
+   * `SILVERY_STRICT=cls` (or tier 2+) is enabled, throws
+   * `UnexpectedLayoutShiftError` if any shift has reflowReason="unexpected"
+   * — failing-fast under STRICT lets close-gate tests skip explicit
+   * assertions and rely on the umbrella env var.
+   *
+   * Throws if no capture is active.
+   *
+   * Bead: km-silvery.cls-instrumentation-primitive
+   */
+  endCLSCapture(): CLSReport;
+  /**
+   * Cancel the active CLS capture without producing a report. Idempotent
+   * — safe to call when no capture is active. Used by test-cleanup paths
+   * that need to bail without asserting.
+   *
+   * Bead: km-silvery.cls-instrumentation-primitive
+   */
+  cancelCLSCapture(): void;
+  /** Clear the terminal output */
+  clear(): void;
+  /** Render current buffer to PNG. Requires Playwright (lazy-loaded on first call). */
+  screenshot(outputPath?: string): Promise<Buffer>;
+  /** Print component tree to console */
+  debug(): void;
+  /** Render the current tree from scratch (no incremental buffer reuse).
+   *  Returns the fresh buffer without updating incremental state.
+   *  Only available in test renderer - throws otherwise. */
+  freshRender(): TerminalBuffer;
+  /** Check if exit() was called */
+  exitCalled(): boolean;
+  /** Get error passed to exit() */
+  exitError(): Error | undefined;
+  /** Send raw stdin input (for sync test helpers; prefer app.press() for new code) */
+  readonly stdin: {
+    write: (data: string) => void;
+  };
+  /** All rendered frames (internal) */
+  readonly frames: string[];
+  /** Get last frame with ANSI codes (internal - use app.ansi instead) */
+  lastFrame(): string | undefined;
+  /** Get last buffer (internal - use app.term.buffer instead) */
+  lastBuffer(): TerminalBuffer | undefined;
+  /** Get last frame as plain text (internal - use app.text instead) */
+  lastFrameText(): string | undefined;
+  /** Get container root node (internal - use app.locator() instead) */
+  getContainer(): AgNode;
+  /** Focus a node by testID */
+  focus(testID: string): void;
+  /** Get the focus path from focused node to root (testID[]) */
+  getFocusPath(): string[];
+  /** Direct access to the FocusManager instance */
+  readonly focusManager: FocusManager;
+  /** Get the current cursor state for this silvery instance (per-instance, not global). */
+  getCursorState(): CursorState | null;
+  /**
+   * Return the parent chain from the container root down to the first
+   * AgNode whose component name matches `componentName`. Empty array if
+   * not found. Useful for asserting structural invariants in tests and
+   * for bead-investigation static traces ("does ToolBlock actually
+   * render inside Content.Body[width=full]?").
+   *
+   * See `@silvery/ag-react/debug/render-path` for the underlying API.
+   */
+  renderPath(componentName: string): RenderPathNode[];
+  /**
+   * Recursive JSON dump of the entire mount tree. Useful for snapshot
+   * tests asserting on structural invariants.
+   */
+  mountTree(): MountTree;
+}
+//#endregion
+//#region packages/ag-term/src/layout-engine.d.ts
+/**
+ * Branded types prevent accidentally mixing up layout constant categories.
+ * E.g., you can't pass an AlignValue where a FlexDirectionValue is expected.
+ */
+type FlexDirectionValue = number & {
+  readonly __brand: "FlexDirection";
+};
+type WrapValue = number & {
+  readonly __brand: "Wrap";
+};
+type AlignValue = number & {
+  readonly __brand: "Align";
+};
+type JustifyValue = number & {
+  readonly __brand: "Justify";
+};
+type EdgeValue = number & {
+  readonly __brand: "Edge";
+};
+type GutterValue = number & {
+  readonly __brand: "Gutter";
+};
+type DisplayValue = number & {
+  readonly __brand: "Display";
+};
+type PositionTypeValue = number & {
+  readonly __brand: "PositionType";
+};
+type OverflowValue = number & {
+  readonly __brand: "Overflow";
+};
+type DirectionValue = number & {
+  readonly __brand: "Direction";
+};
+type MeasureModeValue = number & {
+  readonly __brand: "MeasureMode";
+};
+/**
+ * Constants for layout configuration.
+ * These are the same across Yoga and Flexily.
+ * Uses branded types for compile-time safety.
+ */
+interface LayoutConstants {
+  FLEX_DIRECTION_COLUMN: FlexDirectionValue;
+  FLEX_DIRECTION_COLUMN_REVERSE: FlexDirectionValue;
+  FLEX_DIRECTION_ROW: FlexDirectionValue;
+  FLEX_DIRECTION_ROW_REVERSE: FlexDirectionValue;
+  WRAP_NO_WRAP: WrapValue;
+  WRAP_WRAP: WrapValue;
+  WRAP_WRAP_REVERSE: WrapValue;
+  ALIGN_AUTO: AlignValue;
+  ALIGN_FLEX_START: AlignValue;
+  ALIGN_CENTER: AlignValue;
+  ALIGN_FLEX_END: AlignValue;
+  ALIGN_STRETCH: AlignValue;
+  ALIGN_BASELINE: AlignValue;
+  ALIGN_SPACE_BETWEEN: AlignValue;
+  ALIGN_SPACE_AROUND: AlignValue;
+  ALIGN_SPACE_EVENLY: AlignValue;
+  JUSTIFY_FLEX_START: JustifyValue;
+  JUSTIFY_CENTER: JustifyValue;
+  JUSTIFY_FLEX_END: JustifyValue;
+  JUSTIFY_SPACE_BETWEEN: JustifyValue;
+  JUSTIFY_SPACE_AROUND: JustifyValue;
+  JUSTIFY_SPACE_EVENLY: JustifyValue;
+  EDGE_LEFT: EdgeValue;
+  EDGE_TOP: EdgeValue;
+  EDGE_RIGHT: EdgeValue;
+  EDGE_BOTTOM: EdgeValue;
+  EDGE_HORIZONTAL: EdgeValue;
+  EDGE_VERTICAL: EdgeValue;
+  EDGE_ALL: EdgeValue;
+  GUTTER_COLUMN: GutterValue;
+  GUTTER_ROW: GutterValue;
+  GUTTER_ALL: GutterValue;
+  DISPLAY_FLEX: DisplayValue;
+  DISPLAY_NONE: DisplayValue;
+  POSITION_TYPE_STATIC: PositionTypeValue;
+  POSITION_TYPE_RELATIVE: PositionTypeValue;
+  POSITION_TYPE_ABSOLUTE: PositionTypeValue;
+  OVERFLOW_VISIBLE: OverflowValue;
+  OVERFLOW_HIDDEN: OverflowValue;
+  OVERFLOW_SCROLL: OverflowValue;
+  DIRECTION_LTR: DirectionValue;
+  MEASURE_MODE_UNDEFINED: MeasureModeValue;
+  MEASURE_MODE_EXACTLY: MeasureModeValue;
+  MEASURE_MODE_AT_MOST: MeasureModeValue;
+}
+/**
+ * Declares which engine-native primitives a `LayoutEngine` supports.
+ *
+ * silvery is engine-pluggable — `flexily` (pure JS) and `yoga` (WASM) ship as peer
+ * adapters. The responsive-layout reframe (Phase A0.1+) adds engine-native container
+ * queries, fitWidth, size containment, cq* units, and CSS math functions. These
+ * primitives can only be implemented in `flexily` (yoga's WASM boundary doesn't expose
+ * inter-pass child-style mutation).
+ *
+ * Each adapter declares which capabilities it supports. Consumers (`<Box fitWidth>`,
+ * `<Box containerQueries>`, etc.) gate on capability presence via `requireCapability()`
+ * — under yoga, those primitives THROW at first paint with a one-line fix instruction
+ * (switch via `SILVERY_ENGINE=flexily`).
+ */
+interface EngineCapabilities {
+  /** Container queries: `<Box containerQueries={...}>` + `containerType` / `containerName` */
+  readonly containerQueries: boolean;
+  /** Size containment: `<Box containSize>` */
+  readonly containSize: boolean;
+  /** Container-query units in style values: `cqi`, `cqmin`, `cqb`, `cqmax` */
+  readonly containerQueryUnits: boolean;
+  /** fitWidth Box prop: `<Box fitWidth={[80, 120, "100cqi"]}>` */
+  readonly fitWidth: boolean;
+  /** CSS math functions in style values: `min()`, `max()`, `clamp()` */
+  readonly styleMathFunctions: boolean;
+  /** Inter-pass child-style mutation hook (underlying mechanism for CQ + fitWidth) */
+  readonly childStyleMutation: boolean;
+}
+/**
+ * Abstract layout engine interface.
+ * Implementations can wrap Yoga, Flexily, or other layout engines.
+ */
+interface LayoutEngine {
+  /** Create a new layout node */
+  createNode(): LayoutNode$1;
+  /** Layout constants for this engine */
+  readonly constants: LayoutConstants;
+  /** Engine name for debugging */
+  readonly name: string;
+  /** Which engine-native primitives this adapter supports (Phase A0.0.5+). */
+  readonly capabilities: EngineCapabilities;
+}
+/**
+ * Set the global layout engine instance.
+ * Must be called before rendering.
+ */
+declare function setLayoutEngine(engine: LayoutEngine): void;
+/**
+ * Check if a layout engine is initialized.
+ */
+declare function isLayoutEngineInitialized(): boolean;
+/**
+ * Layout engine type for configuration.
+ *
+ * - 'flexily': Zero-allocation Flexily (default, optimized for high-frequency layout)
+ * - 'flexily-classic': Classic Flexily algorithm (for debugging/compatibility)
+ * - 'yoga': Facebook's WASM-based flexbox (most mature)
+ */
+type LayoutEngineType = "flexily" | "yoga";
+//#endregion
+//#region packages/ag-term/src/adapters/canvas-adapter.d.ts
+interface CanvasAdapterConfig {
+  /** Font size in pixels (default: 14) */
+  fontSize?: number;
+  /** Font family (default: 'monospace') */
+  fontFamily?: string;
+  /** Line height multiplier (default: 1.2) */
+  lineHeight?: number;
+  /** Background color (default: '#1e1e1e') */
+  backgroundColor?: string;
+  /** Default foreground color (default: '#d4d4d4') */
+  foregroundColor?: string;
+  /** Monospace mode (default: true). When false, uses proportional font measurement. */
+  monospace?: boolean;
+  /** Device pixel ratio for sharp rendering on HiDPI displays (default: 1) */
+  dpr?: number;
+}
+declare class CanvasRenderBuffer implements RenderBuffer {
+  readonly width: number;
+  readonly height: number;
+  readonly canvas: OffscreenCanvas | HTMLCanvasElement;
+  private ctx;
+  private config;
+  private readonly charWidth;
+  private readonly cellHeight;
+  constructor(width: number, height: number, config: Required<CanvasAdapterConfig>);
+  fillRect(x: number, y: number, width: number, height: number, style: RenderStyle): void;
+  drawText(x: number, y: number, text: string, style: RenderStyle): void;
+  /**
+   * Draw underline decorations at pixel coordinates.
+   * Note: px, py are already in pixel coordinates.
+   */
+  private drawUnderline;
+  drawChar(x: number, y: number, char: string, style: RenderStyle): void;
+  inBounds(x: number, y: number): boolean;
+  fillRoundedRect(x: number, y: number, width: number, height: number, radius: number, fill: string | undefined, stroke: string | undefined, lineWidth?: number): void;
+}
+declare function createCanvasAdapter(config?: CanvasAdapterConfig): RenderAdapter;
+//#endregion
+//#region packages/ag-term/src/adapters/dom-adapter.d.ts
+interface DOMAdapterConfig {
+  /** Font size in pixels (default: 14) */
+  fontSize?: number;
+  /** Font family (default: 'monospace') */
+  fontFamily?: string;
+  /** Line height multiplier (default: 1.2) */
+  lineHeight?: number;
+  /** Background color (default: '#1e1e1e') */
+  backgroundColor?: string;
+  /** Default foreground color (default: '#d4d4d4') */
+  foregroundColor?: string;
+  /** CSS class prefix (default: 'silvery') */
+  classPrefix?: string;
+}
+declare class DOMRenderBuffer implements RenderBuffer {
+  readonly width: number;
+  readonly height: number;
+  private config;
+  private lines;
+  private backgrounds;
+  private readonly charWidth;
+  private readonly cellHeight;
+  private container;
+  constructor(width: number, height: number, config: Required<DOMAdapterConfig>);
+  /**
+   * Set the container element for rendering.
+   */
+  setContainer(container: HTMLElement): void;
+  /**
+   * Get the container element.
+   */
+  getContainer(): HTMLElement | null;
+  fillRect(x: number, y: number, width: number, height: number, style: RenderStyle): void;
+  drawText(x: number, y: number, text: string, style: RenderStyle): void;
+  drawChar(x: number, y: number, char: string, style: RenderStyle): void;
+  inBounds(x: number, y: number): boolean;
+  /**
+   * Render the buffer to the container element.
+   * Coordinates in the buffer are in cell units (cols/rows).
+   * This method converts them to pixel coordinates for DOM positioning.
+   */
+  render(): void;
+  /**
+   * Clear the buffer.
+   */
+  clear(): void;
+}
+declare function createDOMAdapter(config?: DOMAdapterConfig): RenderAdapter;
+/**
+ * Inject global CSS styles for silvery DOM rendering.
+ * Call once at application startup if you want default styling.
+ */
+declare function injectDOMStyles(classPrefix?: string): void;
+//#endregion
+//#region packages/ag-term/src/bracketed-paste.d.ts
+/**
+ * Bracketed Paste Mode
+ *
+ * Enables bracketed paste so the terminal wraps pasted text with markers.
+ * This lets the app distinguish pasted text from typed input and receive
+ * it as a single event rather than individual keystrokes.
+ *
+ * Protocol: DEC private mode 2004
+ * - Enable:  CSI ? 2004 h
+ * - Disable: CSI ? 2004 l
+ * - Paste start marker: CSI 200 ~
+ * - Paste end marker:   CSI 201 ~
+ *
+ * Supported by: Ghostty, Kitty, WezTerm, iTerm2, Alacritty, xterm, tmux, foot
+ */
+/** Escape sequence that marks the beginning of pasted text */
+declare const PASTE_START = "\u001B[200~";
+/** Escape sequence that marks the end of pasted text */
+declare const PASTE_END = "\u001B[201~";
+/**
+ * Enable bracketed paste mode.
+ * Writes CSI ? 2004 h to the output stream.
+ */
+declare function enableBracketedPaste(stdout: NodeJS.WriteStream): void;
+/**
+ * Disable bracketed paste mode.
+ * Writes CSI ? 2004 l to the output stream.
+ */
+declare function disableBracketedPaste(stdout: NodeJS.WriteStream): void;
+/** Result of parsing a bracketed paste sequence */
+interface BracketedPasteResult {
+  type: "paste";
+  content: string;
+}
+/**
+ * Detect and extract bracketed paste content from raw terminal input.
+ *
+ * Return semantics (see {@link ProtocolError} for the full contract):
+ * - `null` — input contains no PASTE_START marker (this is not bracketed
+ *   paste input). Discriminator-chain "next parser please" signal.
+ * - `throw ProtocolError` — input HAS PASTE_START (we committed to
+ *   bracketed paste) but no PASTE_END follows. This indicates either a
+ *   stream-split paste (caller should buffer and retry on the next chunk)
+ *   or a protocol violation. Loud failure surfaces the gap; the dispatch
+ *   layer catches and decides whether to buffer or log.
+ */
+declare function parseBracketedPaste(input: string): BracketedPasteResult | null;
+//#endregion
+//#region packages/ag-term/src/osc-markers.d.ts
+/**
+ * OSC 133 Semantic Prompt Markers
+ *
+ * Shell integration protocol that marks prompts and commands in terminal output.
+ * Terminals like iTerm2, Kitty, and WezTerm use these markers to provide
+ * "jump to previous/next prompt" navigation (Cmd+Up/Cmd+Down in iTerm2).
+ *
+ * Protocol: OSC 133
+ * - Prompt start:         ESC ] 133 ; A BEL     (before user input)
+ * - Prompt end:           ESC ] 133 ; B BEL     (after user input, before command output)
+ * - Command output start: ESC ] 133 ; C BEL     (before command output)
+ * - Command output end:   ESC ] 133 ; D ; N BEL (after command output, N = exit code)
+ *
+ * For a chat-style app, each "exchange" (user prompt + assistant response) maps to:
+ * - 133;A before the user's message
+ * - 133;B after the user's message
+ * - 133;C before the assistant's response
+ * - 133;D;0 after the assistant's response
+ *
+ * Supported by: iTerm2, Kitty, WezTerm, foot, Ghostty
+ */
+declare const OSC133: {
+  /** Mark prompt start (before user input) */readonly promptStart: "\u001B]133;A\u0007"; /** Mark prompt end (after user input, before command output) */
+  readonly promptEnd: "\u001B]133;B\u0007"; /** Mark command output start */
+  readonly commandStart: "\u001B]133;C\u0007"; /** Mark command output end (exit code defaults to 0 = success) */
+  readonly commandEnd: (exitCode?: number) => string;
+};
+//#endregion
+//#region packages/ag-term/src/kitty-detect.d.ts
+interface KittyDetectResult {
+  /** Whether the terminal responded to the Kitty protocol query */
+  supported: boolean;
+  /** Bitfield of KittyFlags the terminal reported supporting (0 if unsupported) */
+  flags: number;
+  /** Any non-response data that was read during detection (regular input that arrived) */
+  buffered?: string;
+}
+/**
+ * Detect Kitty keyboard protocol support.
+ *
+ * Sends CSI ? u to the terminal and waits for a response.
+ * Supported terminals respond with CSI ? flags u.
+ * Unsupported terminals either ignore the query or echo it.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin (should resolve with data or null on timeout)
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+declare function detectKittySupport(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<KittyDetectResult>;
+/**
+ * Detect Kitty support using real stdin/stdout.
+ * Convenience wrapper around detectKittySupport.
+ */
+declare function detectKittyFromStdio(stdout: {
+  write: (s: string) => boolean | void;
+}, stdin: NodeJS.ReadStream, timeoutMs?: number): Promise<KittyDetectResult>;
+//#endregion
+//#region packages/ag-term/src/termtest.d.ts
+/**
+ * Terminal Capability Test
+ *
+ * Renders labeled test patterns for each terminal feature.
+ * Run in any terminal to visually verify what it supports.
+ *
+ * Usage:
+ *   import { runTermtest } from "@silvery/ag-react"
+ *   runTermtest()                    // all sections
+ *   runTermtest({ sections: ["emoji", "colors"] })  // specific sections
+ *
+ * Compare output across terminals to build/verify profiles.
+ */
+/** Available test sections */
+declare const TERMTEST_SECTIONS: readonly ["sgr", "underline", "colors", "256", "truecolor", "unicode", "emoji", "borders", "inverse", "profile"];
+type TermtestSection = (typeof TERMTEST_SECTIONS)[number];
+interface TermtestOptions {
+  /** Writable stream (defaults to process.stdout) */
+  output?: {
+    write(s: string): boolean;
+  };
+  /** Show only these sections. Omit or empty = all sections. */
+  sections?: TermtestSection[];
+}
+/**
+ * Run the terminal capability test.
+ * Pass section names to filter: `runTermtest({ sections: ["emoji"] })`
+ */
+declare function runTermtest(options?: TermtestOptions): void;
+//#endregion
+//#region packages/ag-term/src/text-sizing.d.ts
+/**
+ * Text Sizing Protocol (OSC 66) -- Kitty v0.40+
+ *
+ * Lets the app specify how many cells a character should occupy.
+ * This solves the measurement/rendering mismatch for Private Use Area (PUA)
+ * characters (nerdfont icons, powerline symbols) that `string-width` reports
+ * as 1-cell but terminals render as 2-cell.
+ *
+ * When OSC 66 is used with w=2, both the app's layout engine and the terminal
+ * agree on the character width, eliminating truncation and misalignment.
+ *
+ * Protocol format:
+ *   ESC ] 66 ; w=<width> ; <text> BEL
+ *
+ * Post km-silvery.unicode-plateau Phase 2 (2026-04-23): this module reads
+ * ZERO environment variables. Capability detection lives entirely in
+ * `@silvery/ansi`'s `createTerminalProfile`. Consumers pass `TerminalCaps`
+ * (or an explicit fingerprint string for the probe cache) so the module is
+ * pure w.r.t. environment and browser/canvas targets aren't broken.
+ *
+ * @see https://sw.kovidgoyal.net/kitty/text-sizing-protocol/
+ */
+/**
+ * Wrap text in an OSC 66 sequence that tells the terminal to render it
+ * in exactly `width` cells.
+ */
+declare function textSized(text: string, width: number): string;
+/**
+ * Check if a code point is in the Private Use Area (PUA).
+ * Covers BMP PUA (U+E000-U+F8FF) and Supplementary PUA-A/B.
+ */
+declare function isPrivateUseArea(cp: number): boolean;
+/**
+ * Structural subset of the terminal profile's emulator the fingerprint helper
+ * needs. Accepts any object with `program` + `version` strings (typically
+ * `profile.emulator` or `term.emulator`).
+ */
+interface FingerprintEmulator {
+  readonly program: string;
+  readonly version: string;
+}
+/**
+ * Build a terminal fingerprint for cache keying. Combines `program` +
+ * `version` from the supplied emulator to uniquely identify the terminal
+ * type. Different versions may add/remove OSC 66 support, so version is part
+ * of the key.
+ *
+ * Post unicode-plateau Phase 2: the emulator argument is required — the
+ * legacy env-reading variant is gone. Callers building fingerprints from a
+ * one-shot probe can use `createTerminalProfile().emulator` upstream.
+ */
+declare function getTerminalFingerprint(emulator: FingerprintEmulator): string;
+/** Result of text sizing probe */
+interface TextSizingProbeResult {
+  supported: boolean;
+  widthOnly: boolean;
+}
+/**
+ * Detect terminal support for the text sizing protocol.
+ * Uses cursor position reports (CPR) to check if OSC 66 advances the cursor
+ * by the specified width.
+ *
+ * Results are cached by fingerprint so the probe only runs once per terminal
+ * type per process.
+ *
+ * @param write - Writer function (TUI output)
+ * @param read - Reader function (CPR response source)
+ * @param fingerprint - Cache key. Derived via {@link getTerminalFingerprint}
+ *   from `TerminalCaps`; callers inside a running session typically compute
+ *   it once from `term.profile.caps`.
+ * @param timeout - Per-probe timeout in ms (default 1000)
+ * @returns Object with `supported` and `widthOnly` flags:
+ * - supported=true, widthOnly=false: full support (scale + width)
+ * - supported=true, widthOnly=true: width mode only
+ * - supported=false: no support
+ */
+declare function detectTextSizingSupport(write: (data: string) => void, read: () => Promise<string>, fingerprint: string, timeout?: number): Promise<TextSizingProbeResult>;
+//#endregion
+//#region packages/ag-term/src/cursor-query.d.ts
+/**
+ * CSI 6n Cursor Position Query
+ *
+ * Queries the terminal for the current cursor position using the standard
+ * Device Status Report (DSR) mechanism.
+ *
+ * Protocol:
+ * - Query:    CSI 6 n  (\x1b[6n)
+ * - Response: CSI {row} ; {col} R  (\x1b[{row};{col}R)
+ *
+ * Row and column are 1-indexed in the protocol response.
+ *
+ * Supported by: virtually all terminals (VT100+)
+ */
+/**
+ * Query the terminal cursor position.
+ *
+ * Sends CSI 6n and parses the CPR response.
+ * Returns 1-indexed row and column.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin (resolves with data or null on timeout)
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+declare function queryCursorPosition(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<{
+  row: number;
+  col: number;
+} | null>;
+/**
+ * Query cursor position using real stdin/stdout.
+ * Convenience wrapper around queryCursorPosition.
+ */
+declare function queryCursorFromStdio(stdout: {
+  write: (s: string) => boolean | void;
+}, stdin: NodeJS.ReadStream, timeoutMs?: number): Promise<{
+  row: number;
+  col: number;
+} | null>;
+//#endregion
+//#region packages/ag-term/src/device-attrs.d.ts
+/**
+ * Device Attributes (DA1/DA2/DA3) + XTVERSION Queries
+ *
+ * Provides functions to query terminal identity and capabilities using
+ * the standard VT device attribute escape sequences.
+ *
+ * Protocols:
+ *
+ * DA1 (Primary Device Attributes):
+ *   Query:    CSI c       (\x1b[c)
+ *   Response: CSI ? Ps ; Ps ; ... c
+ *
+ * DA2 (Secondary Device Attributes):
+ *   Query:    CSI > c     (\x1b[>c)
+ *   Response: CSI > Pt ; Pv ; Pc c
+ *   Where Pt=terminal type, Pv=firmware version, Pc=ROM cartridge id
+ *
+ * DA3 (Tertiary Device Attributes):
+ *   Query:    CSI = c     (\x1b[=c)
+ *   Response: DCS ! | hex-encoded-id ST  (\x1bP!|{hex}\x1b\\)
+ *
+ * XTVERSION (Terminal Name + Version):
+ *   Query:    CSI > 0 q   (\x1b[>0q)
+ *   Response: DCS > | name(version) ST  (\x1bP>|{text}\x1b\\)
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, foot, VTE-based terminals
+ */
+/**
+ * Query primary device attributes (DA1).
+ *
+ * Returns the list of attribute parameters the terminal reports.
+ * Common params: 1=132-cols, 4=sixel, 6=selective-erase, 22=ANSI-color
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+declare function queryPrimaryDA(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<{
+  params: number[];
+} | null>;
+/**
+ * Query secondary device attributes (DA2).
+ *
+ * Returns terminal type, firmware version, and ROM cartridge id.
+ * Common type values: 0=VT100, 1=VT220, 41=xterm, 65=VT500
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+declare function querySecondaryDA(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<{
+  type: number;
+  version: number;
+  id: number;
+} | null>;
+/**
+ * Query tertiary device attributes (DA3).
+ *
+ * Returns a hex-encoded unit ID string. Decode with Buffer.from(hex, 'hex').
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+declare function queryTertiaryDA(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<string | null>;
+/**
+ * Query the terminal name and version via XTVERSION.
+ *
+ * Returns the version string as reported by the terminal, e.g.:
+ * - "xterm(388)"
+ * - "tmux 3.4"
+ * - "WezTerm 20230712-072601-f4abf8fd"
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ */
+declare function queryTerminalVersion(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<string | null>;
+/** Combined device attributes result. */
+interface DeviceAttributes {
+  da1: {
+    params: number[];
+  } | null;
+  da2: {
+    type: number;
+    version: number;
+    id: number;
+  } | null;
+  version: string | null;
+}
+/**
+ * Query all device attributes: DA1, DA2, and XTVERSION.
+ *
+ * Convenience wrapper that queries all three sequentially.
+ * DA3 is omitted from the combined query as it's rarely needed.
+ *
+ * @param stdout Writable stream (e.g., process.stdout)
+ * @param stdin Readable stream (e.g., process.stdin)
+ * @param timeoutMs Per-query timeout (default: 200ms)
+ */
+declare function queryDeviceAttributes(stdout: {
+  write: (s: string) => boolean | void;
+}, stdin: NodeJS.ReadStream, timeoutMs?: number): Promise<DeviceAttributes>;
+//#endregion
+//#region packages/ag-term/src/focus-reporting.d.ts
+/**
+ * Focus Reporting (CSI ?1004h)
+ *
+ * Enables/disables terminal focus-in/focus-out event reporting.
+ * When enabled, the terminal sends CSI I on focus-in and CSI O on focus-out.
+ *
+ * Protocol:
+ * - Enable:    CSI ? 1004 h
+ * - Disable:   CSI ? 1004 l
+ * - Focus In:  CSI I  (\x1b[I)
+ * - Focus Out: CSI O  (\x1b[O)
+ *
+ * Supported by: xterm (v282+), Ghostty, Kitty, WezTerm, iTerm2, foot, VTE
+ */
+/**
+ * Enable terminal focus reporting.
+ * After enabling, the terminal will send CSI I / CSI O sequences
+ * when the terminal window gains or loses focus.
+ */
+declare function enableFocusReporting(write: (data: string) => void): void;
+/**
+ * Disable terminal focus reporting.
+ */
+declare function disableFocusReporting(write: (data: string) => void): void;
+/**
+ * Parse a focus event from terminal input.
+ *
+ * Return semantics (see ProtocolError in @silvery/ansi for the full contract):
+ * - `null` — input contains neither `CSI I` nor `CSI O` markers (not a
+ *   focus event). Discriminator-chain "next parser please" signal.
+ *
+ * The bead 15127 audit listed this parser for review, but there is no
+ * "committed but malformed" branch — the marker either appears in the
+ * input or it doesn't. No ProtocolError throw needed.
+ *
+ * @param input Raw terminal input string
+ * @returns Parsed focus event, or null if not a focus sequence
+ */
+declare function parseFocusEvent(input: string): {
+  type: "focus-in" | "focus-out";
+} | null;
+//#endregion
+//#region packages/ag-term/src/mode-query.d.ts
+/**
+ * DECRQM — DEC Private Mode Query
+ *
+ * Queries the terminal for the state of DEC private modes.
+ *
+ * Protocol:
+ * - Query:    CSI ? {mode} $ p
+ * - Response: CSI ? {mode} ; {Ps} $ y
+ *
+ * Where Ps is:
+ *   1 = set (mode is enabled)
+ *   2 = reset (mode is disabled)
+ *   0 = not recognized (unknown mode)
+ *   3 = permanently set
+ *   4 = permanently reset
+ *
+ * We normalize 3→"set" and 4→"reset" for simplicity.
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, foot, VTE-based terminals
+ */
+/** Well-known DEC private mode constants. */
+declare const DecMode: {
+  /** DEC cursor visible (DECTCEM) */readonly CURSOR_VISIBLE: 25; /** Alternate screen buffer (DECSET 1049) */
+  readonly ALT_SCREEN: 1049; /** Normal mouse tracking (X10) */
+  readonly MOUSE_TRACKING: 1000; /** Bracketed paste mode */
+  readonly BRACKETED_PASTE: 2004; /** Synchronized output */
+  readonly SYNC_OUTPUT: 2026; /** Focus reporting */
+  readonly FOCUS_REPORTING: 1004;
+};
+type ModeState = "set" | "reset" | "unknown";
+/**
+ * Query the state of a single DEC private mode.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param mode DEC private mode number (e.g., DecMode.ALT_SCREEN)
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ * @returns "set", "reset", or "unknown"
+ */
+declare function queryMode(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, mode: number, timeoutMs?: number): Promise<ModeState>;
+/**
+ * Query the state of multiple DEC private modes.
+ *
+ * Queries each mode sequentially and returns a Map of results.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param modes Array of DEC private mode numbers
+ * @param timeoutMs Per-query timeout (default: 200ms)
+ */
+declare function queryModes(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, modes: number[], timeoutMs?: number): Promise<Map<number, ModeState>>;
+//#endregion
+//#region packages/ag-term/src/pixel-size.d.ts
+/**
+ * CSI 14t/18t — Terminal Pixel and Text Area Size Queries
+ *
+ * Queries the terminal for window dimensions in pixels and characters.
+ *
+ * Protocols:
+ *
+ * Text Area Pixels (CSI 14t):
+ *   Query:    CSI 14 t
+ *   Response: CSI 4 ; height ; width t
+ *
+ * Text Area Size in Characters (CSI 18t):
+ *   Query:    CSI 18 t
+ *   Response: CSI 8 ; rows ; cols t
+ *
+ * Cell size can be derived by dividing pixel dimensions by character dimensions.
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, foot, iTerm2
+ */
+/**
+ * Query the terminal text area size in pixels.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ * @returns Width and height in pixels, or null on timeout/unsupported
+ */
+declare function queryTextAreaPixels(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<{
+  width: number;
+  height: number;
+} | null>;
+/**
+ * Query the terminal text area size in characters (rows x columns).
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs How long to wait for response (default: 200ms)
+ * @returns Rows and columns, or null on timeout/unsupported
+ */
+declare function queryTextAreaSize(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<{
+  cols: number;
+  rows: number;
+} | null>;
+/**
+ * Query the terminal cell size in pixels by querying both pixel
+ * dimensions and character dimensions, then dividing.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param timeoutMs Per-query timeout (default: 200ms)
+ * @returns Cell width and height in pixels, or null if either query fails
+ */
+declare function queryCellSize(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<{
+  width: number;
+  height: number;
+} | null>;
+//#endregion
+//#region packages/ag-term/src/term-def.d.ts
+/**
+ * Minimal surface for configuring render().
+ *
+ * TermDef provides a simple way to configure rendering without requiring
+ * a full Term instance. It's useful for:
+ * - Static rendering (just width/height, no events)
+ * - Testing (mock dimensions and events)
+ * - Quick scripts (auto-detect everything from stdin/stdout)
+ *
+ * The presence of `events` (or `stdin` which auto-creates events)
+ * determines the render mode:
+ * - No events → static mode (render until stable)
+ * - Has events → interactive mode (render until exit() called)
+ *
+ * @example
+ * ```tsx
+ * // Static render with custom width
+ * const output = await render(<App />, { width: 100 })
+ *
+ * // Interactive with stdin/stdout
+ * await render(<App />, { stdin: process.stdin, stdout: process.stdout })
+ *
+ * // Custom events
+ * await render(<App />, { events: myEventSource })
+ * ```
+ */
+interface TermDef {
+  /** Output stream (used for dimensions if not specified) */
+  stdout?: NodeJS.WriteStream;
+  /** Width in columns (default: stdout?.columns ?? 80) */
+  width?: number;
+  /** Height in rows (default: stdout?.rows ?? 24) */
+  height?: number;
+  /**
+   * Color support (true=detect, false=mono, or specific {@link ColorLevel}).
+   *
+   * `null` is accepted as a compat alias for `"mono"` (pre-terminal-profile-plateau
+   * no-color spelling).
+   */
+  colors?: boolean | ColorLevel | null;
+  /**
+   * Event source for interactive mode.
+   *
+   * When present, render runs until exit() is called.
+   * When absent, render completes when UI is stable.
+   */
+  events?: AsyncIterable<Event> | EventSource;
+  /**
+   * Standard input stream.
+   *
+   * When provided (and events is not), automatically creates input events
+   * from stdin, enabling interactive mode.
+   */
+  stdin?: NodeJS.ReadStream;
+}
+/**
+ * Check if a value is a Term instance (duck typing).
+ *
+ * Post km-silvery.caps-restructure Phase 7: the legacy hasCursor/hasInput/
+ * hasColor methods were removed — caps/profile/write/size are the canonical
+ * Term surface.
+ */
+declare function isTerm(value: unknown): value is Term;
+/**
+ * Create an async iterable of input events from a stdin stream.
+ *
+ * This enables interactive mode by providing a source of keyboard events.
+ */
+declare function createInputEvents(stdin: NodeJS.ReadStream): AsyncIterable<Event>;
+//#endregion
+//#region packages/ag-term/src/non-tty.d.ts
+/**
+ * Non-TTY Mode Support for Silvery
+ *
+ * Provides detection and rendering modes for non-interactive environments:
+ * - Piped output (process.stdout.isTTY === false)
+ * - CI environments
+ * - TERM=dumb
+ *
+ * When in non-TTY mode, silvery avoids cursor positioning codes that garble
+ * output in non-interactive environments.
+ *
+ * Modes:
+ * - 'auto': Detect based on environment (default)
+ * - 'tty': Force TTY mode (normal cursor positioning)
+ * - 'line-by-line': Simple newline-separated output, no cursor movement
+ * - 'static': Single output at end (no updates)
+ * - 'plain': Strip all ANSI codes
+ */
+/**
+ * Non-TTY rendering mode.
+ *
+ * - 'auto': Auto-detect based on environment
+ * - 'tty': Force TTY mode with cursor positioning
+ * - 'line-by-line': Output lines without cursor repositioning
+ * - 'static': Single final output only
+ * - 'plain': Strip all ANSI escape codes
+ */
+type NonTTYMode = "auto" | "tty" | "line-by-line" | "static" | "plain";
+/**
+ * Options for non-TTY output.
+ */
+interface NonTTYOptions {
+  /** The rendering mode. Default: 'auto' */
+  mode?: NonTTYMode;
+  /** Output stream to check for TTY status. Default: process.stdout */
+  stdout?: NodeJS.WriteStream;
+}
+/**
+ * Resolved non-TTY mode after auto-detection.
+ */
+type ResolvedNonTTYMode = Exclude<NonTTYMode, "auto">;
+/**
+ * Check if the environment is a TTY.
+ *
+ * Returns false if:
+ * - stdout.isTTY is false or undefined
+ * - TERM=dumb
+ * - CI environment variables are set
+ *
+ * Pass `emulator` (from `term.emulator` or a TerminalEmulator fixture) when
+ * available to avoid a redundant env read. Without it, the TERM=dumb check
+ * delegates to {@link createTerminalProfile} — the canonical single-source-
+ * of-truth entry in `@silvery/ansi/profile`. CI env vars remain read
+ * directly because they are orthogonal to terminal capabilities (a CI
+ * runner's TTY status doesn't describe what the terminal can render).
+ */
+declare function isTTY(stdout?: NodeJS.WriteStream, /** Structural emulator — `{ TERM }` is the only field this helper reads. */
+
+emulator?: {
+  TERM: string;
+}): boolean;
+/**
+ * Resolve the non-TTY mode based on options and environment.
+ *
+ * When mode is 'auto':
+ * - If TTY detected: returns 'tty'
+ * - If non-TTY detected: returns 'line-by-line'
+ */
+declare function resolveNonTTYMode(options?: NonTTYOptions): ResolvedNonTTYMode;
+//#endregion
+//#region packages/ag-term/src/errors.d.ts
+/** Structured mismatch data attached to the error (mirrors MismatchDebugContext shape) */
+interface MismatchErrorData {
+  /** Render-phase instrumentation snapshot (nodes visited/rendered/skipped, per-flag breakdown) */
+  renderPhaseStats?: RenderPhaseStats;
+  /** Debug context for the mismatched cell (from debug-mismatch.ts) */
+  mismatchContext?: unknown;
+}
+/**
+ * Error thrown when SILVERY_STRICT detects a mismatch.
+ * This error should NOT be caught by general error handlers - it indicates
+ * a bug in incremental rendering that needs to be fixed.
+ *
+ * When SILVERY_STRICT fires, the error automatically includes:
+ * - Render-phase instrumentation (nodes visited/rendered/skipped, per-flag breakdown)
+ * - Cell attribution (which node owns the mismatched cell, dirty flags, scroll context)
+ */
+declare class IncrementalRenderMismatchError extends Error {
+  /** Render-phase instrumentation snapshot */
+  renderPhaseStats?: RenderPhaseStats;
+  /** Debug context for the mismatched cell */
+  mismatchContext?: unknown;
+  constructor(message: string, data?: MismatchErrorData);
+}
+//#endregion
+//#region packages/ag-term/src/scheduler.d.ts
+interface RenderStats {
+  /** Number of renders executed */
+  renderCount: number;
+  /** Number of renders skipped (batched) */
+  skippedCount: number;
+  /** Last render duration in ms */
+  lastRenderTime: number;
+  /** Average render time in ms */
+  avgRenderTime: number;
+}
+//#endregion
+//#region packages/ag-term/src/inspector.d.ts
+interface InspectorOptions {
+  /** Output stream (default: process.stderr) */
+  output?: NodeJS.WritableStream;
+  /** Log file path (overrides output stream) */
+  logFile?: string;
+  /** Include layout rects in tree dump */
+  showLayout?: boolean;
+  /** Include style info in tree dump */
+  showStyles?: boolean;
+}
+/** Enable the silvery inspector. */
+declare function enableInspector(options?: InspectorOptions): void;
+/** Disable the inspector. */
+declare function disableInspector(): void;
+/** Check if inspector is active. */
+declare function isInspectorEnabled(): boolean;
+/**
+ * Log render stats after each frame.
+ *
+ * Called by the scheduler after doRender completes. When the inspector
+ * is disabled this is a no-op (zero overhead).
+ */
+declare function inspectFrame(stats: RenderStats): void;
+/**
+ * Dump the component tree structure as indented text.
+ *
+ * Walks the SilveryNode tree and formats each node with its type, testID,
+ * layout rect, and dirty flags.
+ */
+declare function inspectTree(rootNode: AgNode, options?: {
+  depth?: number;
+  showLayout?: boolean;
+}): string;
+/**
+ * Auto-enable if SILVERY_DEV=1 is set.
+ *
+ * Call this at startup to respect the environment variable convention.
+ */
+declare function autoEnableInspector(): void;
+//#endregion
+//#region packages/ag-term/src/measurer.d.ts
+/**
+ * Term extended with measurement capabilities.
+ */
+interface MeasuredTerm extends Term, Measurer {}
+/**
+ * Extend a Term with measurement capabilities.
+ *
+ * Creates a width measurer from the term's caps and adds measurement
+ * methods (displayWidth, graphemeWidth, wrapText, etc.) to the term.
+ */
+declare function withMeasurer(term: Term): MeasuredTerm;
+/**
+ * Create a pipeline configuration from caps and/or measurer.
+ *
+ * This is the single factory for PipelineConfig -- use it instead of
+ * manually constructing { measurer, outputPhaseFn }.
+ *
+ * @param options.caps - Terminal capabilities (for output phase SGR generation).
+ *   Reads `caps.maybeWideEmojis` (text-presentation emoji width) and
+ *   `caps.textSizing` for measurement.
+ * @param options.measurer - Explicit measurer (if omitted, created from caps)
+ */
+declare function createPipeline(options?: {
+  caps?: TerminalCaps;
+  measurer?: Measurer;
+}): PipelineConfig;
+//#endregion
+//#region packages/ag-term/src/scroll-utils.d.ts
+/**
+ * Scroll Utilities
+ *
+ * Shared functions for edge-based scrolling behavior across VirtualList,
+ * HorizontalVirtualList, and other scroll-aware components.
+ */
+/**
+ * Calculate edge-based scroll offset.
+ *
+ * Only scrolls when cursor approaches the edge of the visible area.
+ * This provides smoother scrolling by starting to scroll before hitting
+ * the absolute edge, maintaining context around the selected item.
+ *
+ * ## Algorithm
+ *
+ * The viewport is divided into zones:
+ * ```
+ * |<padding>|<------ safe zone ------>|<padding>|
+ * |  scroll |    no scroll needed     | scroll  |
+ * |  if <   |                         | if >    |
+ * ```
+ *
+ * When the selected item enters a padding zone, the viewport scrolls
+ * to keep the item visible with margin.
+ *
+ * ## Asymmetry Note
+ *
+ * The +1 in the "scroll down/right" case is intentional:
+ * - Offset points to the TOP/LEFT of the viewport
+ * - We want the selected item to be `padding` items from the BOTTOM/RIGHT
+ * - Formula: `selectedIndex - visibleCount + padding + 1`
+ *
+ * Example: visibleCount=10, padding=2, selectedIndex=15
+ *   offset = 15 - 10 + 2 + 1 = 8
+ *   viewport shows items 8-17, selected item 15 is at position 7 (2 from bottom)
+ *
+ * @param selectedIndex - Currently selected item index
+ * @param currentOffset - Current scroll offset (topmost/leftmost visible item)
+ * @param visibleCount - Number of items visible in viewport
+ * @param totalCount - Total number of items
+ * @param padding - Items to keep visible before/after cursor (default: 1)
+ * @returns New scroll offset
+ */
+declare function calcEdgeBasedScrollOffset(selectedIndex: number, currentOffset: number, visibleCount: number, totalCount: number, padding?: number): number;
+//#endregion
+//#region packages/ag-term/src/scroll-region.d.ts
+/**
+ * Terminal scroll region (DECSTBM) utilities.
+ *
+ * Scroll regions tell the terminal to natively scroll content within
+ * a defined row range, which is faster than re-rendering all cells.
+ *
+ * DECSTBM (DEC Set Top and Bottom Margins) is supported by most modern
+ * terminal emulators: xterm, iTerm2, Kitty, Ghostty, WezTerm, etc.
+ */
+/** Set terminal scroll region (1-indexed top and bottom rows). */
+declare function setScrollRegion(stdout: NodeJS.WriteStream, top: number, bottom: number): void;
+/** Reset scroll region to full terminal. */
+declare function resetScrollRegion(stdout: NodeJS.WriteStream): void;
+/** Scroll content up by N lines within the current scroll region. */
+declare function scrollUp(stdout: NodeJS.WriteStream, lines?: number): void;
+/** Scroll content down by N lines within the current scroll region. */
+declare function scrollDown(stdout: NodeJS.WriteStream, lines?: number): void;
+/** Move cursor to a specific position (1-indexed row and column). */
+declare function moveCursor(stdout: NodeJS.WriteStream, row: number, col: number): void;
+interface ScrollRegionConfig {
+  /** Top row of the scrollable area (0-indexed). */
+  top: number;
+  /** Bottom row of the scrollable area (0-indexed). */
+  bottom: number;
+  /** Whether scroll region optimization is enabled. */
+  enabled: boolean;
+}
+/**
+ * Detect if the terminal likely supports DECSTBM scroll regions.
+ *
+ * Most modern terminals do (xterm, iTerm2, Kitty, Ghostty, WezTerm, etc.)
+ * but some (e.g., Linux console) may not handle them correctly.
+ *
+ * Pass `emulator` (via `term.emulator` or a test fixture) when in scope.
+ * Without it, this falls back to {@link createTerminalProfile} — the canonical
+ * single-source-of-truth entry point in `@silvery/ansi/profile`. Direct
+ * reads of terminal-signal env vars (TERM / TERM_PROGRAM / …) are banned
+ * outside that module — see `scripts/lint-env-reads.ts`.
+ */
+declare function supportsScrollRegions(/** Structural emulator — `{ program, TERM }` is all this helper reads. */
+
+emulator?: {
+  program: string;
+  TERM: string;
+}): boolean;
+//#endregion
+//#region packages/ag-term/src/pane-manager.d.ts
+/**
+ * Pane Manager - Pure functions for manipulating split layout trees.
+ *
+ * All functions are pure: they return new layout trees, never mutate.
+ * The layout tree is a binary tree where leaves are panes and internal
+ * nodes are splits (horizontal or vertical) with a ratio.
+ */
+type LayoutNode = {
+  type: "leaf";
+  id: string;
+} | {
+  type: "split";
+  direction: "horizontal" | "vertical";
+  ratio: number;
+  first: LayoutNode;
+  second: LayoutNode;
+};
+/** Create a single-pane layout */
+declare function createLeaf(id: string): LayoutNode;
+/** Get all leaf pane IDs in depth-first left-to-right order */
+declare function getPaneIds(layout: LayoutNode): string[];
+/** Find the next/previous pane in tab order (depth-first left-to-right) */
+declare function getTabOrder(layout: LayoutNode): string[];
+/**
+ * Split a pane into two. Returns new layout tree with the target pane split.
+ * The original pane becomes the first child; the new pane becomes the second.
+ */
+declare function splitPane(layout: LayoutNode, targetPaneId: string, direction: "horizontal" | "vertical", newPaneId: string, ratio?: number): LayoutNode;
+/**
+ * Remove a pane from the layout. The sibling takes the full space.
+ * Returns null if the removed pane was the last one.
+ */
+declare function removePane(layout: LayoutNode, paneId: string): LayoutNode | null;
+/** Swap two panes' positions in the layout */
+declare function swapPanes(layout: LayoutNode, paneId1: string, paneId2: string): LayoutNode;
+/**
+ * Resize a split: adjust the ratio of the nearest ancestor split
+ * that contains the target pane as its first child.
+ * Positive delta = grow (first child gets more), negative = shrink.
+ */
+declare function resizeSplit(layout: LayoutNode, paneId: string, delta: number): LayoutNode;
+/**
+ * Find the pane adjacent to the given pane in a direction.
+ *
+ * For left/right: looks for siblings in horizontal splits.
+ * For up/down: looks for siblings in vertical splits.
+ *
+ * Returns null if no adjacent pane exists in that direction.
+ */
+declare function findAdjacentPane(layout: LayoutNode, paneId: string, direction: "left" | "right" | "up" | "down"): string | null;
+//#endregion
+//#region packages/headless/src/find.d.ts
+interface FindMatch {
+  row: number;
+  startCol: number;
+  endCol: number;
+}
+/**
+ * Result from a FindProvider's model-level search.
+ * Represents a match within a virtual list item that may not be on screen.
+ */
+interface FindResult {
+  /** Virtual list item identifier */
+  itemId: string;
+  /** Character offset within item text */
+  offset: number;
+  /** Match length */
+  length: number;
+  /** Screen row — set after reveal() makes the item visible */
+  row?: number;
+  /** Screen start column — set after reveal() */
+  startCol?: number;
+}
+interface FindState {
+  /** Current search query, or null if find is not active */
+  query: string | null;
+  /** All matches in the visible buffer */
+  matches: FindMatch[];
+  /** Index of the currently focused match (-1 if no matches) */
+  currentIndex: number;
+  /** Whether find mode is active */
+  active: boolean;
+  /** Provider-level results (when FindProvider is present) */
+  providerResults: FindResult[];
+  /** Whether provider search is in progress */
+  providerSearching: boolean;
+}
+//#endregion
+//#region packages/ag-term/src/history-buffer.d.ts
+/**
+ * Ring buffer for frozen scrollback items.
+ *
+ * Each item represents a rendered list entry (card, row, etc.) with its
+ * ANSI snapshot, split rows, and plain-text rows for searching.
+ * When total rows or cached ANSI bytes exceed capacity, the oldest items are
+ * evicted. The byte count tracks the serialized string payload; it is a
+ * deterministic cache budget, not an exact process heap measurement.
+ */
+interface HistoryItem {
+  key: string | number;
+  ansi: string;
+  rows: string[];
+  plainTextRows: string[];
+  width: number;
+}
+interface HistoryBuffer {
+  push(item: HistoryItem): void;
+  readonly totalRows: number;
+  readonly totalBytes: number;
+  readonly itemCount: number;
+  getRows(startRow: number, count: number): string[];
+  getPlainTextRows(startRow: number, count: number): string[];
+  search(query: string): number[];
+  getItemAtRow(row: number): {
+    item: HistoryItem;
+    localRow: number;
+  } | null;
+  clear(): void;
+  readonly capacity: number;
+  readonly capacityBytes: number | null;
+}
+//#endregion
+//#region packages/ag-term/src/viewport-compositor.d.ts
+interface ComposedViewport {
+  /** History rows to overlay at top of viewport */
+  overlayRows: string[];
+  /** Number of top rows occupied by history */
+  overlayRowCount: number;
+  /** Number of bottom rows for live content */
+  liveRowsVisible: number;
+  /** Whether viewing history */
+  isScrolledUp: boolean;
+  /** Total scrollable height */
+  totalHeight: number;
+}
+//#endregion
+//#region packages/ag-term/src/search-overlay.d.ts
+/**
+ * Search overlay state machine for virtual inline mode.
+ *
+ * Pure TEA: (action, state) -> [state, effects[]]
+ * Provides incremental search-as-you-type with match navigation.
+ */
+interface SearchMatch {
+  row: number;
+  startCol: number;
+  endCol: number;
+}
+/**
+ * A single contiguous character range within a string that matched a search
+ * query. `start` is inclusive, `end` is exclusive — same convention as
+ * `String.prototype.slice(start, end)`.
+ */
+interface MatchRange {
+  start: number;
+  end: number;
+}
+/**
+ * Find all case-insensitive occurrences of `query` inside `text` and return
+ * their character offsets. Empty query or empty text returns `[]`.
+ *
+ * This is the canonical silvery search-match algorithm. The same logic runs
+ * inside `ListView`'s registered Searchable (to find matches across items)
+ * and is exposed to consumers that render multi-segment items — a LogRow
+ * whose searchable text is a concatenation of field values, but whose visual
+ * rendering splits those fields across separate Text nodes, needs per-segment
+ * ranges to highlight without re-implementing the semantics.
+ *
+ * Ranges are returned in ascending `start` order; overlapping matches are
+ * not produced (`indexOf(..., start = last.start + 1)` advances past each
+ * match start, not past its full length, preserving overlapping runs of
+ * short queries — e.g. `"aa"` in `"aaaa"` yields `[0..2], [1..3], [2..4]`).
+ *
+ * Offsets are CHARACTER offsets into the input string. They are not column
+ * offsets — multi-column wide glyphs are counted as one character here, the
+ * same way the SearchProvider's match-row computation does.
+ */
+declare function computeMatchRanges(text: string, query: string): MatchRange[];
+//#endregion
+//#region packages/ag-term/src/runtime/wrap-measurer-registration.d.ts
+/**
+ * Wrap-measurer registration for `@silvery/ag-term`.
+ *
+ * `@silvery/ag` exposes a process-level wrap-measurer registry
+ * (`setWrapMeasurer` / `getWrapMeasurer`) so geometry helpers like
+ * `computeSelectionFragments` can ask the active terminal runtime for
+ * grapheme-correct soft-wrap slices. Without registration, the geometry
+ * layer falls back to `\n`-only line splitting — fine for pure-framework
+ * unit tests, wrong for real apps where a 60-char paragraph at width 20
+ * needs to emit 3 fragments.
+ *
+ * **Registration shape (Option B per `hub/silvery/design/overlay-anchor-system.md`
+ * § 8)**: terminal-side `wrapTextWithOffsets` adapts to the registry's
+ * `wrapText(text, maxWidth) → readonly WrapSlice[]` contract. The slice
+ * shape is structurally identical (`text` + `startOffset` + `endOffset`),
+ * so the adapter is a passthrough — no allocation, no reformatting.
+ *
+ * **Lifecycle**: registration happens at module load — see the side-effect
+ * call below. The adapter reads the active scoped measurer (terminal caps,
+ * wide-emoji heuristics, text-sizing) at call time, so caps changes during
+ * a session (e.g., post-DA1 width-detection toggling `maybeWideEmojis`)
+ * are picked up automatically.
+ *
+ * **Test isolation**: tests that need the `\n`-only fallback (pure-`ag`
+ * pathway) call `setWrapMeasurer(null)` in `beforeEach`/`afterEach` and
+ * `restoreDefaultWrapMeasurer()` in `afterAll`. Tests that exercise the
+ * registered path do nothing — the import-time side effect already wired
+ * it up.
+ *
+ * **Multi-Term**: v1 is module-level singleton — see `@silvery/ag/wrap-measurer.ts`
+ * file header for the upgrade path. Single Term-per-process is the
+ * production reality; multi-Term scenarios are research / future work.
+ *
+ * Tracking: bead `km-silvery.softwrap-selection-fragments` (closes Phase
+ * 4b deferred wrap-spanning).
+ */
+/**
+ * Install the terminal-runtime wrap measurer into `@silvery/ag`'s registry.
+ *
+ * Reads the live registry (`getWrapMeasurer()`) — not a local boolean — to
+ * decide whether to install. This makes the function safe to call after a
+ * `setWrapMeasurer(null)` teardown that bypassed `uninstallTerminalWrapMeasurer`
+ * (e.g. tests that drop the registration through `@silvery/ag`'s own API).
+ *
+ * Idempotent: when our adapter is already the registered measurer, this
+ * is a no-op. When a foreign measurer is registered (rare — only seen if
+ * a test or alternate runtime registered its own), this overwrites it
+ * with our adapter, matching v1's "single Term-per-process" assumption.
+ *
+ * Called automatically at module load (see side-effect below); exported
+ * for tests that want to re-arm after a `setWrapMeasurer(null)` teardown.
+ */
+declare function installTerminalWrapMeasurer(): void;
+/**
+ * Reset registration when our adapter is the active measurer. After
+ * calling this, the `@silvery/ag` registry is empty (`getWrapMeasurer()`
+ * returns null) and `computeSelectionFragments` falls back to `\n`-only
+ * splitting. Tests use this to exercise the fallback path; runtime
+ * teardown uses it on Term dispose.
+ *
+ * No-op when a foreign measurer is registered — clearing it would surprise
+ * whoever installed it. Call `setWrapMeasurer(null)` directly if the goal
+ * is to clear unconditionally.
+ */
+declare function uninstallTerminalWrapMeasurer(): void;
+/**
+ * Test helper: restore the registry to its post-import-time default
+ * state. Equivalent to `installTerminalWrapMeasurer()` but reads more
+ * naturally in `afterEach` / `afterAll` blocks.
+ */
+declare function restoreDefaultWrapMeasurer(): void;
+/**
+ * Read whether the terminal measurer is currently the active registration.
+ * Sources truth from the live registry so a concurrent test that called
+ * `setWrapMeasurer(null)` is observed correctly.
+ */
+declare function isTerminalWrapMeasurerInstalled(): boolean;
+//#endregion
+export { enableFocusReporting as $, hasWideCharacters as $n, RenderStyle as $t, withMeasurer as A, setCursorStyle as An, injectDOMStyles as At, ResolvedNonTTYMode as B, createOsc52Backend as Bn, App as Bt, scrollDown as C, enableKittyKeyboard as Cn, PASTE_START as Ct, calcEdgeBasedScrollOffset as D, resetCursorStyle as Dn, DOMAdapterConfig as Dt, supportsScrollRegions as E, reportDirectory as En, parseBracketedPaste as Et, inspectFrame as F, DragState as Fn, LayoutConstants as Ft, isTerm as G, createMeasurer as Gn, LayoutShift as Gt, resolveNonTTYMode as H, Measurer as Hn, FilterOptions as Ht, inspectTree as I, ClipboardBackend as In, LayoutEngine as It, queryTextAreaSize as J, ensureEmojiPresentation as Jn, ExecuteRenderOptions as Jt, queryCellSize as K, displayWidth as Kn, ReasonClassifier as Kt, isInspectorEnabled as L, ClipboardCapabilities as Ln, LayoutEngineType as Lt, autoEnableInspector as M, setWindowAndIconTitle as Mn, CanvasRenderBuffer as Mt, disableInspector as N, setWindowTitle as Nn, createCanvasAdapter as Nt, MeasuredTerm as O, resetMouseCursorShape as On, DOMRenderBuffer as Ot, enableInspector as P, CopyModeState as Pn, EngineCapabilities as Pt, disableFocusReporting as Q, hasAnsi as Qn, RenderBuffer as Qt, IncrementalRenderMismatchError as R, createCompositeClipboard as Rn, isLayoutEngineInitialized as Rt, resetScrollRegion as S, disableMouse as Sn, PASTE_END as St, setScrollRegion as T, queryKittyKeyboard as Tn, enableBracketedPaste as Tt, TermDef as U, StyledSegment as Un, createAutoLocator as Ut, isTTY as V, parseClipboardResponse as Vn, AutoLocator as Vt, createInputEvents as W, constrainText as Wn, CLSReport as Wt, queryMode as X, graphemeCount as Xn, LayoutSignals as Xt, DecMode as Y, getFirstCodePoint as Yn, PipelineConfig as Yt, queryModes as Z, graphemeWidth as Zn, BorderChars as Zt, resizeSplit as _, BEL as _n, truncateText as _r, KittyDetectResult as _t, MatchRange as a, OutputPhaseDiagnostics as an, isZeroWidthGrapheme as ar, queryTerminalVersion as at, ScrollRegionConfig as b, MouseCursorShape as bn, writeTextToBuffer as br, OSC133 as bt, ComposedViewport as c, CursorAccessors as cn, padText as cr, queryCursorPosition as ct, LayoutNode as d, CursorState as dn, sliceByWidth as dr, isPrivateUseArea as dt, TextMeasureResult as en, hasZeroWidthCharacters as er, parseFocusEvent as et, createLeaf as f, CursorStore as fn, sliceByWidthFromEnd as fr, textSized as ft, removePane as g, ANSI as gn, truncateAnsi as gr, runTermtest as gt, getTabOrder as h, useCursor as hn, stripAnsi as hr, TermtestSection as ht, uninstallTerminalWrapMeasurer as i, OutputCaps as in, isWideGrapheme as ir, querySecondaryDA as it, InspectorOptions as j, setMouseCursorShape as jn, CanvasAdapterConfig as jt, createPipeline as k, resetWindowTitle as kn, createDOMAdapter as kt, HistoryBuffer as l, CursorPosition as ln, parseAnsiText as lr, detectTextSizingSupport as lt, getPaneIds as m, resetCursorState as mn, splitGraphemes as mr, TermtestOptions as mt, isTerminalWrapMeasurerInstalled as n, TextMeasurer as nn, isLikelyEmoji as nr, queryDeviceAttributes as nt, SearchMatch as o, OutputPhaseFn as on, measureText as or, queryTertiaryDA as ot, findAdjacentPane as p, createCursorStore as pn, sliceByWidthRange as pr, TERMTEST_SECTIONS as pt, queryTextAreaPixels as q, displayWidthAnsi as qn, ReflowReason as qt, restoreDefaultWrapMeasurer as r, PipelineContext as rn, isTextSizingEnabled as rr, queryPrimaryDA as rt, computeMatchRanges as s, createOutputPhase as sn, normalizeText as sr, queryCursorFromStdio as st, installTerminalWrapMeasurer as t, TextMeasureStyle as tn, isCJK as tr, DeviceAttributes as tt, FindState as u, CursorProvider as un, runWithMeasurer as ur, getTerminalFingerprint as ut, splitPane as v, CursorShape as vn, wrapText as vr, detectKittyFromStdio as vt, scrollUp as w, enableMouse as wn, disableBracketedPaste as wt, moveCursor as x, disableKittyKeyboard as xn, writeTextTruncated as xr, BracketedPasteResult as xt, swapPanes as y, KittyFlags as yn, writeLinesToBuffer as yr, detectKittySupport as yt, NonTTYOptions as z, createInternalClipboardBackend as zn, setLayoutEngine as zt };
+//# sourceMappingURL=wrap-measurer-registration-IV2HtcCd.d.mts.map