silvery 0.19.2 → 0.21.0

package/dist/bound-term-0sPrrzH1.d.mts

@@ -0,0 +1,4640 @@
+import { M as RGB$1, N as UnderlineStyle$2, P as TerminalCaps, j as ColorLevel, mt as Theme, yt as TerminalEmulator, z as TerminalProfile } from "./index-CSQf13CI.mjs";
+import * as _$react from "react";
+
+//#region packages/ag/src/viewport-types.d.ts
+/**
+ * Read-only cell-grid view — the source-of-truth for a Viewport's painted
+ * content. Written by a {@link ForeignSource}, blitted into the parent buffer
+ * at output-phase time.
+ *
+ * Structurally a read-only subset of the silvery `TerminalBuffer` but with
+ * `cols`/`rows` naming (matching {@link ViewportProps}) instead of
+ * `width`/`height`. The Cell shape is reused verbatim from `@silvery/ag` so
+ * sources can construct buffers without depending on a separate cell vocabulary.
+ */
+interface CellBuffer {
+  readonly cols: number;
+  readonly rows: number;
+  /** Read a single cell at Viewport-local `(col, row)`. */
+  getCell(col: number, row: number): Cell$1;
+}
+/**
+ * Rectangle within a Viewport's cell grid. Origin `(0, 0)` is the top-left
+ * cell of the Viewport's content area — NOT an absolute terminal coordinate.
+ *
+ * Kept distinct from the global {@link Rect} so the pipeline can translate
+ * Viewport-local rects to absolute cells at blit time without ambiguity.
+ *
+ * Field naming uses `row`/`col` (not `x`/`y`) for the same reason: the global
+ * Rect uses Cartesian terminology; cells are addressed in (row, col) order
+ * across the rest of the cell-buffer surface.
+ */
+interface ViewportRect {
+  readonly row: number;
+  readonly col: number;
+  readonly width: number;
+  readonly height: number;
+}
+/**
+ * Viewport-internal cursor style hint. The Viewport's cursor is painted INTO
+ * its cells (the source decides where), then composited into the parent
+ * frame. Independent of the silvery host cursor that lives in
+ * {@link LayoutSignals}.
+ */
+type ViewportCursorStyle = "block" | "underline" | "bar";
+/**
+ * Input mode requested by a {@link ForeignSource}. The parent owns global
+ * terminal modes (mouse-tracking SGR, raw mode, bracketed paste, focus
+ * reporting) and multiplexes events to whichever Viewport is currently
+ * focused. Sources declare which event classes they care about so the parent
+ * can switch protocol modes deterministically.
+ *
+ * - `"none"`: source consumes no input (replay frames, static snapshots).
+ * - `"keys"`: source wants forwarded key events when its Viewport is focused.
+ * - `"mouse"`: source wants normalized `(row, col)` mouse events.
+ * - `"all"`: source wants both.
+ */
+type ViewportInputMode = "none" | "keys" | "mouse" | "all";
+/**
+ * Frozen color palette handed to a Viewport at mount. Independent of the
+ * parent silvery theme — a Viewport speaks raw colors, not `$tokens`.
+ *
+ * The source is responsible for mapping its own color model (xtermjs 256-color
+ * indices, replay-frame RGB, etc.) onto this palette when it needs theme
+ * coherence with the host. Sources that have their own complete color
+ * vocabulary (mirroring a real terminal session) may ignore this entirely.
+ */
+interface ViewportPalette {
+  /** Default background color (any silvery-acceptable color string). */
+  background: string;
+  /** Default foreground color. */
+  foreground: string;
+  /** Optional 16-color ANSI map. Index `0..7` = standard, `8..15` = bright. */
+  ansi16?: readonly string[];
+}
+/**
+ * Handle passed to a {@link ForeignSource} at `connect()` time — the
+ * thin remote the source uses to push cell content, move the cursor, and
+ * negotiate input mode with the parent Viewport.
+ *
+ * One `ViewportContext` exists per mounted Viewport. The source uses it for
+ * the lifetime of the connection; after `disconnect()` the context is
+ * invalidated and calls become no-ops.
+ */
+interface ViewportContext {
+  /** Current Viewport dimensions in cells. */
+  dimensions(): {
+    cols: number;
+    rows: number;
+  };
+  /**
+   * Blit cell content into the Viewport's buffer at the given dirty rects.
+   * Rects are in Viewport-local coordinates (origin = `(0, 0)` at top-left).
+   * The buffer's `(col, row)` indices are absolute within the buffer — the
+   * source decides what cells to read for each rect.
+   */
+  blit(dirtyRects: readonly ViewportRect[], buffer: CellBuffer): void;
+  /** Move the Viewport's internal cursor. */
+  setCursor(pos: {
+    row: number;
+    col: number;
+  }, style?: ViewportCursorStyle): void;
+  /** Force a full Viewport repaint on the next frame. */
+  invalidateAll(): void;
+  /**
+   * Ask the parent to route input events of the given mode into this
+   * Viewport when it's focused. Parent owns global terminal modes; the
+   * request is advisory unless the Viewport is the focused leaf.
+   */
+  requestInputMode(mode: ViewportInputMode): void;
+  /**
+   * Optional: source emits a window title (xtermjs OSC 0/2). Reserved for
+   * future — host may surface it via app chrome, ignored otherwise.
+   */
+  emitTitle?(title: string): void;
+}
+/**
+ * The contract a foreign rendering engine implements to live inside a
+ * Viewport.
+ *
+ * Lifecycle: `<Viewport>` calls `connect(ctx)` on mount and `disconnect()` on
+ * unmount. The source then writes into the context at its own cadence —
+ * input-driven (xtermjs PTY mirror), timer-driven (replay), or
+ * frame-driven (snapshot). The Viewport never polls the source.
+ *
+ * Implementations (planned):
+ * - `XtermAdapter` (Phase B): wraps `@xterm/headless`, mirrors a PTY child.
+ * - `ReplaySource`: animation frames for inline previews.
+ * - `SnapshotSource`: static frames (GIF encoder, test fixtures).
+ * - `LocalSource` (post-MVP): render a silvery subtree INTO a Viewport buffer.
+ */
+interface ForeignSource {
+  /** Called once at mount. Source captures `ctx` for the connection lifetime. */
+  connect(ctx: ViewportContext): void;
+  /** Called once at unmount. Source releases all resources tied to the context. */
+  disconnect(): void;
+  /**
+   * Optional intrinsic size hint. The Viewport MAY snap its dimensions to
+   * this on mount — apps that want pixel-perfect chrome should set explicit
+   * `cols`/`rows` on `<Viewport>` and ignore the hint.
+   */
+  desiredSize?(): {
+    cols: number;
+    rows: number;
+  };
+}
+/**
+ * Imperative handle returned by `<Viewport ref={...}>`. Apps use this to push
+ * content into the Viewport without binding a {@link ForeignSource} — useful
+ * for one-shot snapshot blits, test fixtures, or app-driven mirroring where a
+ * full source lifecycle would be over-engineered.
+ *
+ * Both paths can coexist: a source binding and a ref handle on the same
+ * Viewport write into the same underlying buffer (last-write-wins per cell).
+ */
+interface ViewportRef {
+  /** Write cells into the Viewport at the given dirty rects. */
+  writeCells(dirtyRects: readonly ViewportRect[], buffer: CellBuffer): void;
+  /**
+   * Convenience: feed raw ANSI bytes. The Viewport's internal terminal
+   * emulator (xtermjs in v1) parses them and updates the cell buffer.
+   * Apps that already speak the cell vocabulary should prefer
+   * {@link writeCells} — `writeAnsi` is for the "I have a PTY producing
+   * ANSI bytes" case.
+   */
+  writeAnsi(chunk: Uint8Array): void;
+  /** Move the Viewport's internal cursor. */
+  setCursor(pos: {
+    row: number;
+    col: number;
+  }, style?: ViewportCursorStyle): void;
+  /**
+   * Resize the Viewport (re-runs parent layout; `onResize` fires; bound
+   * {@link ForeignSource} sees new dimensions on its next `blit()`).
+   */
+  resize(cols: number, rows: number): void;
+  /**
+   * Capture the current Viewport buffer as an immutable {@link CellBuffer}
+   * snapshot. Used by GIF encoders, snapshot tests, and replay capture.
+   */
+  snapshot(): CellBuffer;
+}
+/**
+ * Per-instance state attached to a `silvery-viewport` AgNode. Owned by the
+ * `<Viewport>` React component; read by the pipeline render phase to blit
+ * cells into the parent buffer.
+ *
+ * Lazily created at mount (the host node has no `viewportState` until
+ * `<Viewport>` runs its mount effect). After unmount the slot may be
+ * cleared, but the AgNode is also torn down at that point.
+ *
+ * @internal — public callers should not touch this directly; the props +
+ * ref handle on `<Viewport>` are the supported surface.
+ */
+interface ViewportNodeState {
+  /** Backing cell buffer (mutable; the renderer reads via the `CellBuffer` upcast). */
+  buffer: CellBuffer;
+  /** Latest internal cursor position (in Viewport-local cells), or null when hidden. */
+  cursor: {
+    row: number;
+    col: number;
+    style: ViewportCursorStyle;
+  } | null;
+  /** Whether the Viewport's internal cursor should paint at all. */
+  cursorVisible: boolean;
+  /** Last input mode the source asked for (or "none" if no source). */
+  inputMode: ViewportInputMode;
+}
+/**
+ * Public props for `<Viewport>` (v1 — termless-rec target).
+ *
+ * The MVP shape. See bead `@km/silvery/15513-surface-nested-composition-primitive`
+ * for the full defer list (transparency, nested viewports, `LocalSource`,
+ * IME composition, full bidi).
+ */
+interface ViewportProps {
+  /** Viewport width in cells. Required — Viewport is a leaf with fixed size. */
+  cols: number;
+  /** Viewport height in cells. */
+  rows: number;
+  /**
+   * Optional ForeignSource bound at mount. May be omitted when the app pushes
+   * content imperatively via {@link ViewportRef}.
+   */
+  source?: ForeignSource;
+  /** Whether the Viewport can receive focus. Default: `false`. */
+  focusable?: boolean;
+  /**
+   * Input modes the Viewport requests when focused. The parent enables the
+   * matching protocol modes (mouse SGR, raw input, etc.) only when this
+   * Viewport is the focused leaf. Default: `"none"`.
+   */
+  captureInput?: ViewportInputMode;
+  /**
+   * Scrollback line count for the internal cell buffer. Default: `0`
+   * (overlays don't need history; pure mirror use cases keep memory tight).
+   */
+  scrollback?: number;
+  /**
+   * Clip overflow content to the Viewport's rect (vs. allowing oversize
+   * content to escape into the parent). Default: `true`.
+   */
+  clip?: boolean;
+  /** Show the Viewport's internal cursor. Default: `true`. */
+  cursorVisible?: boolean;
+  /**
+   * Frozen palette for the Viewport's internal color resolution. Set ONCE at
+   * mount — does NOT cascade from the parent theme. Pass a derived value if
+   * theme coherence with the host is desired; pass `undefined` for the
+   * Viewport to use its own defaults (the source decides).
+   */
+  palette?: ViewportPalette;
+  /** Fired when the Viewport is resized (parent layout change or `ref.resize`). */
+  onResize?: (cols: number, rows: number) => void;
+  /**
+   * Fired when an external consumer (GIF encoder, snapshot test) requests
+   * a buffer capture. Returns the current cell buffer for projection.
+   */
+  onSnapshot?: () => CellBuffer;
+}
+//#endregion
+//#region packages/ag/src/island-types.d.ts
+/**
+ * Lifecycle signals emitted by an {@link IslandGuest} via `ctx.emit()`.
+ *
+ * The host subscribes via `createIsland({ onSignal })`. Always serializable
+ * — replay guests reconstruct sessions by replaying these.
+ */
+type IslandSignal = {
+  type: "ready";
+} | {
+  type: "exit";
+  code?: number;
+  reason?: string;
+} | {
+  type: "error";
+  error: Error;
+};
+/**
+ * Capabilities a guest declares to the host. Drives whether the host renders
+ * input routing, resize negotiation, and palette ownership for this island.
+ *
+ * Per-island prop capability overrides (set on `<Island capabilities={...}>`)
+ * intersect with per-guest capability declarations — intersection wins
+ * (host never offers a capability the guest can't fulfill).
+ */
+interface IslandCapabilities {
+  /** Guest accepts input events from the host (key / mouse / paste). */
+  input?: boolean;
+  /** Guest manages cursor-shape / alt-screen / bracketed-paste / mouse-tracking modes. */
+  modes?: boolean;
+  /** Guest can resize dynamically (host calls {@link IslandSizeOwner.requestResize}). */
+  resize?: boolean;
+  /** Guest owns its palette (OSC 4 / 10 / 11). Default: host freezes palette. */
+  palette?: boolean;
+}
+/**
+ * Per-island hydration policy — Astro-borrowed. Default: `"load"`.
+ *
+ * - `"load"`: guest.init() fires synchronously at mount.
+ * - `"idle"`: defer until `requestIdleCallback` (or microtask fallback).
+ * - `"visible"`: defer until the island's rect intersects the viewport.
+ * - `"only-on-focus"`: defer until the island first receives focus; tear
+ *   down on blur. Cheapest for multi-pane hosts (silvercode panes).
+ */
+type IslandHydrate = "load" | "idle" | "visible" | "only-on-focus";
+/**
+ * Palette ownership policy per island.
+ *
+ * - `"freeze"` — host snapshots the current theme palette at mount; guest
+ *   sees a frozen view. Default for PTY / snapshot guests (compositing
+ *   isolation; theme drift cannot leak into recorded content).
+ * - `"inherit"` — guest inherits the host theme palette; theme changes
+ *   cascade live. Default for sub-silvery / Vue / Solid guests (semantic
+ *   theme coherence is the point).
+ * - `{ custom }` — explicit {@link ViewportPalette}. Overrides both.
+ */
+type IslandPalettePolicy = "freeze" | "inherit" | {
+  custom: ViewportPalette;
+};
+/**
+ * Size owner — exposes guest dimensions; host requests resize via
+ * `requestResize()`; guest acknowledges by emitting on its next paint.
+ *
+ * Two-phase resize protocol (the P0 landmine /pro caught):
+ *   1. Host calls `requestResize(cols, rows)` (advisory).
+ *   2. Guest decides; if accepted, writes content at new dims on its next
+ *      `output.writeCells()`.
+ *   3. Host reads new `cols` / `rows` after the guest acknowledges via
+ *      `output` — never assumes resize was accepted synchronously.
+ *
+ * `island-resize-race` STRICT slug catches violations of this protocol.
+ */
+interface IslandSizeOwner {
+  readonly cols: number;
+  readonly rows: number;
+  /** Subscribe to size changes (alien-signals compatible). */
+  subscribe(listener: (size: {
+    cols: number;
+    rows: number;
+  }) => void): () => void;
+  /** Host-side: ask the guest to resize. Guest acknowledges via next paint. */
+  requestResize(cols: number, rows: number): void;
+}
+/**
+ * Output owner — guest writes cells / cursor / mode hints to the host.
+ * Host renders via the pipeline render phase.
+ *
+ * The buffer is read-only from the host's perspective (upcast to
+ * {@link CellBuffer}). Guests own the underlying mutable buffer.
+ *
+ * `island-paint-oob` STRICT slug catches guest writes outside the island's
+ * declared rect; `island-paint-budget` STRICT slug catches runaway paint
+ * cadence (per-frame byte budget).
+ */
+interface IslandOutputOwner {
+  /** Current cell buffer (read-only upcast for host blit). */
+  readonly buffer: CellBuffer;
+  /**
+   * Last-known guest cursor position + style; null when hidden.
+   * Host renders this WITHIN the island's rect; the host cursor is
+   * suppressed inside an island (cursor un-apply on blur — see Modes owner).
+   */
+  readonly cursor: IslandCursorState | null;
+  /** True if guest wants its cursor painted in the host frame. */
+  readonly cursorVisible: boolean;
+  /**
+   * Subscribe to output-relevant changes (new cells, cursor move, mode
+   * change). Host marks the island's rect dirty on each callback.
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Guest-side: write cells at the given island-local dirty rects. The
+   * supplied buffer is the guest's source; cells outside the dirty rects
+   * are unchanged.
+   *
+   * Origin `(0, 0)` = top-left of island content area (NOT absolute
+   * terminal). Host translates at blit time.
+   */
+  writeCells(dirtyRects: readonly ViewportRect[], buffer: CellBuffer): void;
+  /** Guest-side: force a full island repaint on the next frame. */
+  invalidateAll(): void;
+}
+/**
+ * Guest-internal cursor descriptor (style + position).
+ * Style values match {@link import("./viewport-types").ViewportCursorStyle}.
+ */
+interface IslandCursorState {
+  row: number;
+  col: number;
+  style: "block" | "underline" | "bar";
+}
+/**
+ * Input owner — host routes input events to the guest when the island is
+ * focused. Exposes typed `on*` callbacks (canonical) AND an `events()`
+ * AsyncIterable (restored ergonomic wrapper from pre-14991; zero behavioral
+ * cost — see `@km/silvery/15646` decision row "Restore input.events()").
+ *
+ * The host translates host-coordinate mouse events to island-local
+ * `(row, col)` before delivery — the P0 landmine /pro caught.
+ *
+ * Synchronous focus severance: when focus moves to a different island, the
+ * host stops delivering events to the previous island AT the focus-change
+ * tick. No queue / drop / forward-after-blur surprise modes.
+ *
+ * `input.sendEof()` / `signals.sendSigint()` / `signals.sendSigtstp()` are
+ * DISTINCT: Ctrl-D ≠ Ctrl-C ≠ Ctrl-Z. The 15645 sketch wrongly mapped
+ * Ctrl-D → "interrupt"; islands gets it right.
+ */
+interface IslandInputOwner {
+  /** Key event (mapped through host's Kitty / mouse / focus protocol layers). */
+  onKey?(handler: (event: IslandKeyEvent) => void): () => void;
+  /** Mouse event with island-local coordinates (host-translated). */
+  onMouse?(handler: (event: IslandMouseEvent) => void): () => void;
+  /** Bracketed-paste content (host-decoded; no \x1b[200~ sequences). */
+  onPaste?(handler: (text: string) => void): () => void;
+  /**
+   * Raw byte feed for guests that speak ANSI directly (PTY pipe). Most
+   * guests should prefer typed `on*` events; `feed()` is the escape hatch
+   * for "I have an xterm.js process and want every byte."
+   */
+  feed?(bytes: Uint8Array): void;
+  /**
+   * AsyncIterable view over all input events. Restored ergonomic wrapper
+   * for the `for await (const ev of island.input.events()) {...}` idiom.
+   * Yields the same event objects as the typed `on*` callbacks.
+   */
+  events?(): AsyncIterable<IslandInputEvent>;
+  /**
+   * Send EOT (Ctrl-D, U+0004) to the guest. Distinct from `signals.sendSigint()`.
+   * EOT closes the guest's stdin (or signals end-of-stream); signal verbs
+   * deliver actual POSIX signals.
+   */
+  sendEof?(): void;
+}
+/** Discriminated union of all input event types. */
+type IslandInputEvent = (IslandKeyEvent & {
+  kind: "key";
+}) | (IslandMouseEvent & {
+  kind: "mouse";
+}) | {
+  kind: "paste";
+  text: string;
+} | {
+  kind: "feed";
+  bytes: Uint8Array;
+};
+/**
+ * Key event delivered to a focused island. Mirrors the host's parsed
+ * {@link import("./keys").Key} shape — re-exported here so guests don't
+ * have to depend on `@silvery/ag/keys` for its public surface.
+ */
+interface IslandKeyEvent {
+  /** Plain character (for printable keys), or empty for special keys. */
+  input: string;
+  /** Named key (e.g. "escape", "enter", "tab", "f1"); empty for printable. */
+  name?: string;
+  /** Modifier state. */
+  ctrl?: boolean;
+  meta?: boolean;
+  alt?: boolean;
+  shift?: boolean;
+  super?: boolean;
+  /** Event type — only "press" / "repeat" delivered; "release" filtered by host. */
+  eventType?: "press" | "repeat";
+}
+/**
+ * Mouse event with ISLAND-LOCAL coordinates. Origin `(0, 0)` = top-left of
+ * island content area. Host translates from absolute terminal coords before
+ * delivery — guests never see host-relative positions.
+ */
+interface IslandMouseEvent {
+  /** Island-local row (0 = top of island content). */
+  row: number;
+  /** Island-local column (0 = left of island content). */
+  col: number;
+  /** Button: "left" | "middle" | "right" | "wheel-up" | "wheel-down" | "release". */
+  button: string;
+  /** Held modifiers at event time. */
+  ctrl?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+}
+/**
+ * Modes owner — host queries which protocol modes the guest currently wants
+ * active (alt-screen, bracketed-paste, mouse-tracking SGR, Kitty keyboard,
+ * focus-reporting, cursor shape + visibility).
+ *
+ * Host AGGREGATES modes from all focused-subtree islands into one global
+ * protocol-mode set. When focus moves, the aggregator recomputes; modes
+ * the new focus wants are enabled, modes only the previous focus wanted
+ * are disabled. THIS is what replaces the 15 `!inputDisabled` gating sites
+ * in `create-app.tsx` (Unit C deletion).
+ *
+ * `island-mode-leak` STRICT slug catches modes that stay enabled after
+ * the requesting island unmounts or loses focus.
+ */
+interface IslandModesOwner {
+  /** Current desired modes (host reads). */
+  readonly modes: IslandProtocolModes;
+  /** Subscribe to mode changes. Host re-aggregates on each callback. */
+  subscribe(listener: (modes: IslandProtocolModes) => void): () => void;
+}
+/**
+ * Protocol modes a focused island can request the host enable. None are
+ * defaults — host enables only modes some focused island asks for.
+ */
+interface IslandProtocolModes {
+  altScreen?: boolean;
+  bracketedPaste?: boolean;
+  mouseTracking?: "off" | "click" | "drag" | "any";
+  kittyKeyboard?: boolean;
+  focusReporting?: boolean;
+  /** Guest's desired cursor shape + visibility. Un-applied on blur. */
+  cursor?: {
+    shape: "block" | "underline" | "bar";
+    visible: boolean;
+  };
+}
+/**
+ * Signals owner — delivers POSIX signals to the guest. PTY-backed guests
+ * forward to the child process; snapshot / replay guests typically have
+ * no signal handlers and ignore (capabilities.input = false hides this
+ * owner from the host).
+ *
+ * Distinct verbs per signal — explicitly NOT a single `send(signal)`
+ * because the call sites have semantic differences the host needs to
+ * route correctly (Ctrl-C from `signals.sendSigint()` is different from
+ * EOT via `input.sendEof()`).
+ */
+interface IslandSignalsOwner {
+  /** Send SIGINT (Ctrl-C). */
+  sendSigint(): void;
+  /** Send SIGTSTP (Ctrl-Z, suspend). */
+  sendSigtstp(): void;
+  /** Send SIGTERM (graceful termination). */
+  sendSigterm(): void;
+  /** Send SIGKILL (immediate). Last-resort. */
+  sendSigkill(): void;
+  /** Exit-code stream (resolves when guest reports exit). */
+  readonly exit: Promise<{
+    code?: number;
+    reason?: string;
+  }>;
+}
+/**
+ * Palette owner — OSC 4 / 10 / 11 query + response + snapshot. Present only
+ * when `capabilities.palette = true` (guest owns palette) AND the island's
+ * `palettePolicy !== "freeze"`.
+ *
+ * Frozen-palette islands (the default for PTY / snapshot guests) get a
+ * read-only snapshot at mount and no palette owner — palette queries
+ * inside the guest are responded to from the snapshot, not the live host.
+ */
+interface IslandPaletteOwner {
+  /** Current palette (live, or the frozen snapshot if `palettePolicy="freeze"`). */
+  readonly palette: ViewportPalette;
+  /** Subscribe to palette changes (only fires when not frozen). */
+  subscribe(listener: (palette: ViewportPalette) => void): () => void;
+  /**
+   * Guest-side: respond to an OSC 4 / 10 / 11 query. Host typically routes
+   * these to a real terminal probe; islands compose by chaining through
+   * the `sandbox` wrapper.
+   */
+  respondToQuery?(query: string): string | undefined;
+}
+/**
+ * Imperative handle returned by an {@link IslandGuest}'s `init()`. The host
+ * stores this on the AgNode's {@link IslandNodeState} and reads through it
+ * each render frame.
+ *
+ * Sub-owners are optional per `capabilities`: a snapshot guest with no
+ * input may return `{ size, output, dispose }` and nothing else. The
+ * `<Island>` React binding propagates the right defaults; the host
+ * aggregator (Unit C) treats absent owners as "no requested modes /
+ * no input routing."
+ */
+interface IslandHandle {
+  /** Required — every island has a size. */
+  readonly size: IslandSizeOwner;
+  /** Required — every island has output (even if empty). */
+  readonly output: IslandOutputOwner;
+  /** Present when `capabilities.input = true`. */
+  readonly input?: IslandInputOwner;
+  /** Present when `capabilities.modes = true`. */
+  readonly modes?: IslandModesOwner;
+  /** Present when the guest can deliver signals (PTY-backed). */
+  readonly signals?: IslandSignalsOwner;
+  /**
+   * Present when `capabilities.palette = true` AND `palettePolicy !== "freeze"`.
+   * Frozen-palette islands respond to OSC queries from the snapshot — no
+   * live owner needed.
+   */
+  readonly palette?: IslandPaletteOwner;
+  /**
+   * Tear down the guest. Called on unmount (`<Island>` cleanup), on focus
+   * loss for `hydrate: "only-on-focus"` islands, and on ErrorBoundary
+   * catches. MUST be idempotent.
+   *
+   * `island-dispose-leak` STRICT slug catches guests that retain resources
+   * (timers, sockets, FDs) past dispose.
+   */
+  dispose(): void | Promise<void>;
+}
+/**
+ * Context passed to {@link IslandGuest.init}. The guest captures this for
+ * the lifetime of its connection and uses it to push lifecycle signals,
+ * request resize, execute host-fulfilled OSC ops, and read monotonic time.
+ *
+ * One `IslandContext` exists per mounted island. `abortSignal` fires on
+ * unmount (or on focus-loss for `hydrate: "only-on-focus"` islands) — the
+ * guest MUST release resources tied to this context when it aborts.
+ */
+interface IslandContext {
+  /** Initial island dimensions in cells. */
+  readonly cols: number;
+  readonly rows: number;
+  /**
+   * Emit a lifecycle signal. Host forwards to the `onSignal` callback set
+   * on `createIsland({ onSignal })`.
+   */
+  emit(signal: IslandSignal): void;
+  /**
+   * Ask the host to resize the island. Host confirms via {@link
+   * IslandSizeOwner} on the next layout tick — guest MUST wait for the
+   * confirmation before writing content at new dims (two-phase protocol;
+   * `island-resize-race` STRICT slug catches violations).
+   */
+  requestResize(cols: number, rows: number): void;
+  /**
+   * Host-fulfilled OS side-effect: guest sends an OSC string (e.g.
+   * `\x1b]52;c;<base64>\x07` for clipboard), host parses + executes +
+   * returns the response (if any). Otherwise OSC 52 / 4 / 10 / 11 ops
+   * from inside the guest would vanish into the island's cell grid.
+   */
+  execOSC(command: string): Promise<string | void>;
+  /**
+   * Aborts on unmount (or on focus-loss for `hydrate: "only-on-focus"`).
+   * Guests MUST release resources on signal — sockets closed, FDs freed,
+   * timers cleared.
+   */
+  readonly abortSignal: AbortSignal;
+  /**
+   * Monotonic time source. Replay guests use this for deterministic
+   * playback; live guests can use `performance.now()` directly.
+   */
+  now(): number;
+}
+/**
+ * The runtime-agnostic guest contract. Current factories include
+ * `snapshotGuest` and `sandbox(guest)` in `@silvery/ag/island-guests`, plus
+ * package-specific guests such as `xtermGuest` and silvermux's `tmuxGuest`.
+ * Planned or external guests include `replayGuest`, `silveryGuest` (embedded
+ * sub-instance), `inkGuest` (legacy adapter), `vueGuest`, `solidGuest`, and
+ * other author-provided implementations.
+ *
+ * Silvery does NOT ship per-framework adapters beyond core helpers such as
+ * `snapshotGuest` / a `sandbox(guest)` wrapper. Community frameworks
+ * implement the contract directly; the contract is the integration surface.
+ *
+ * `init()` returns `Promise` externally — backend authors get one clear
+ * shape (the /pro decision); sync internals are handled by `Promise.resolve()`
+ * at mount.
+ */
+interface IslandGuest {
+  /**
+   * Initialize the guest. Called once at mount (or on first focus for
+   * `hydrate: "only-on-focus"`). Returns an {@link IslandHandle} the host
+   * uses to render the island.
+   *
+   * If `init()` rejects, the silvery ErrorBoundary catches; if `onError`
+   * is set on the `<Island>`, it receives the error; otherwise it throws
+   * up to the parent boundary.
+   */
+  init(ctx: IslandContext): Promise<IslandHandle>;
+  /**
+   * Capabilities this guest CAN provide. Host intersects with per-island
+   * prop overrides — guest never has to fulfill what it didn't declare.
+   *
+   * Omitted = no capabilities (snapshot-only).
+   */
+  capabilities?: IslandCapabilities;
+}
+/**
+ * Per-instance state attached to a `silvery-island` AgNode. Owned by the
+ * `createIsland()` factory (or the `<Island>` React binding); read by the
+ * pipeline render phase to blit the guest's cell buffer at the node's
+ * `boxRect` and route input/mode aggregation.
+ *
+ * Lazily created at mount (the host node has no `islandState` until the
+ * factory runs its mount effect). After unmount the slot may be cleared,
+ * but the AgNode is also torn down at that point.
+ *
+ * Mirrors {@link import("./viewport-types").ViewportNodeState} structurally
+ * — the migration story is: `Viewport` is `Island`'s special-case for
+ * "snapshot-only" + "no input"; Island generalizes by exposing the full
+ * sub-owner contract.
+ *
+ * @internal — public callers should use the `<Island>` props + ref handle;
+ * direct AgNode access is for the pipeline + STRICT-mode checks only.
+ */
+interface IslandNodeState {
+  /**
+   * The guest's handle, or `null` until `init()` resolves (deferred-hydrate
+   * islands hold `null` until first focus / visibility).
+   */
+  handle: IslandHandle | null;
+  /**
+   * The guest contract — kept on the node so deferred-hydrate islands can
+   * re-init on focus / visibility transitions.
+   */
+  guest: IslandGuest;
+  /**
+   * Effective capabilities (per-island intersection of guest declarations
+   * with per-island prop overrides). Computed once at mount; recomputed
+   * on capability prop change.
+   */
+  capabilities: IslandCapabilities;
+  /** Whether this island can receive focus. Read by host focus manager. */
+  focusable: boolean;
+  /** True iff this island is currently in the focused subtree. */
+  focused: boolean;
+  /**
+   * Effective palette policy. Frozen palette: snapshot held in
+   * `frozenPalette`. Inherit: `null` (host theme cascades).
+   */
+  palettePolicy: IslandPalettePolicy;
+  /** Frozen palette snapshot (set only when policy = "freeze"). */
+  frozenPalette: ViewportPalette | null;
+  /** Hydration policy; drives when `init()` fires. */
+  hydrate: IslandHydrate;
+  /**
+   * Lifecycle state — drives the render phase + STRICT mode checks.
+   * - `"pending"`: handle not yet created (deferred hydrate, or init in flight).
+   * - `"ready"`: handle live, guest producing content.
+   * - `"errored"`: init or runtime threw; ErrorBoundary handles display.
+   * - `"disposed"`: dispose() called; AgNode awaiting unmount.
+   */
+  lifecycle: "pending" | "ready" | "errored" | "disposed";
+  /** Last error reported by the guest (set in `"errored"` state). */
+  lastError: Error | null;
+  /**
+   * Abort controller fed to the guest's `IslandContext.abortSignal`. Host
+   * aborts on unmount / focus-loss (for "only-on-focus" hydrate) / dispose.
+   */
+  abortController: AbortController;
+}
+//#endregion
+//#region packages/ag/src/drag-event-types.d.ts
+/**
+ * Drag event payload passed to handler props.
+ */
+interface DragEventPayload {
+  /** The node being dragged */
+  source: AgNode;
+  /** Current terminal position of the pointer */
+  position: {
+    x: number;
+    y: number;
+  };
+  /** The node under the cursor (the drop target receiving this event) */
+  dropTarget: AgNode | null;
+}
+interface DragEventProps {
+  /** Fired when a dragged node enters this node's bounds */
+  onDragEnter?: (event: DragEventPayload) => void;
+  /** Fired when a dragged node leaves this node's bounds */
+  onDragLeave?: (event: DragEventPayload) => void;
+  /** Fired repeatedly as a dragged node moves over this node */
+  onDragOver?: (event: DragEventPayload) => void;
+  /** Fired when a dragged node is dropped on this node */
+  onDrop?: (event: DragEventPayload) => void;
+}
+//#endregion
+//#region packages/ag/src/keys.d.ts
+/**
+ * Keyboard Constants and Utilities
+ *
+ * Single source of truth for all key parsing, mapping, and matching in silvery.
+ *
+ * ## Two-Layer Input Architecture
+ *
+ * parseKey() returns `[input, key]` where these serve DIFFERENT purposes:
+ *
+ * - `input` is **normalized for keybinding matching**. Shifted punctuation is
+ *   decomposed: '#' becomes input='3' with key.shift=true, so keybindings
+ *   like 'shift-3' can match. Uppercase letters become lowercase + shift.
+ *
+ * - `key.text` is the **actual typed character** (pre-normalization). For text
+ *   insertion, always use `key.text ?? input` — this ensures Shift+3 inserts
+ *   '#', opt+e inserts '´', and IME output inserts the composed string.
+ *
+ * Rule: keybinding resolution uses `input`. Text insertion uses `key.text`.
+ * Never reconstruct characters from key codes — trust what the terminal sent.
+ *
+ * - KEY_MAP: Playwright key names -> ANSI sequences (for sending input)
+ * - CODE_TO_KEY: ANSI escape suffixes -> key names (for parsing input)
+ * - Key interface: structured key object with boolean flags
+ * - parseKeypress(): raw terminal input -> ParsedKeypress
+ * - parseKey(): raw terminal input -> [input, Key]
+ * - keyToAnsi(): Playwright key string -> ANSI sequence
+ * - keyToName(): Key object -> named key string
+ * - keyToModifiers(): Key object -> modifier flags
+ * - parseHotkey(): "ctrl+shift+a" -> ParsedHotkey
+ * - matchHotkey(): match ParsedHotkey against Key
+ *
+ * @example
+ * ```tsx
+ * import { keyToAnsi } from '@silvery/test'
+ *
+ * // Convert key names to ANSI
+ * keyToAnsi('Enter')       // '\r'
+ * keyToAnsi('ArrowUp')     // '\x1b[A'
+ * keyToAnsi('Control+c')   // '\x03'
+ * keyToAnsi('a')           // 'a'
+ * ```
+ */
+/**
+ * Key object describing which special keys/modifiers were pressed.
+ */
+interface Key {
+  /** Up arrow key was pressed */
+  upArrow: boolean;
+  /** Down arrow key was pressed */
+  downArrow: boolean;
+  /** Left arrow key was pressed */
+  leftArrow: boolean;
+  /** Right arrow key was pressed */
+  rightArrow: boolean;
+  /** Page Down key was pressed */
+  pageDown: boolean;
+  /** Page Up key was pressed */
+  pageUp: boolean;
+  /** Home key was pressed */
+  home: boolean;
+  /** End key was pressed */
+  end: boolean;
+  /** Return (Enter) key was pressed */
+  return: boolean;
+  /** Escape key was pressed */
+  escape: boolean;
+  /** Ctrl key was pressed */
+  ctrl: boolean;
+  /** Shift key was pressed */
+  shift: boolean;
+  /** Tab key was pressed */
+  tab: boolean;
+  /** Backspace key was pressed */
+  backspace: boolean;
+  /** Delete key was pressed */
+  delete: boolean;
+  /** Meta key (Alt/Option on macOS, Alt on other platforms) was pressed */
+  meta: boolean;
+  /** Super key (Cmd on macOS, Win on Windows) was pressed. Requires Kitty protocol. */
+  super: boolean;
+  /** Hyper key was pressed. Requires Kitty protocol. */
+  hyper: boolean;
+  /** CapsLock is active. Requires Kitty protocol. */
+  capsLock: boolean;
+  /** NumLock is active. Requires Kitty protocol. */
+  numLock: boolean;
+  /** Kitty event type. Only set with Kitty flag 2 (report events). */
+  eventType?: "press" | "repeat" | "release";
+  /** The actual text character typed (pre-normalization). For text insertion,
+   *  use this instead of the normalized `input` which maps shifted chars to base keys. */
+  text?: string;
+  /** True when the key is a modifier pressed alone (Shift, Ctrl, Alt, Super, Hyper, Meta).
+   *  Set during parsing for Kitty protocol modifier-only events. */
+  isModifierOnly?: boolean;
+  /**
+   * Internal Kitty key name (e.g. "leftsuper", "rightcontrol",
+   * "leftshift") for modifier-only events. Surfaced so the modifier-state
+   * tracker (`useModifierKeys`) can drop the matching flag on release —
+   * Kitty release events keep the modifier bit set, so the bit alone
+   * doesn't say which key was lifted.
+   *
+   * Optional + only set for modifier-only events to avoid bloating the
+   * public surface for non-modifier keys (use the existing flag fields
+   * `upArrow`, `escape`, etc. for those). Bead:
+   * @km/silvery/keydown-keyup-test-primitives.
+   */
+  modifierName?: string;
+}
+/**
+ * Input handler callback type.
+ * Return 'exit' to exit the app.
+ */
+type InputHandler = (input: string, key: Key) => void | "exit";
+/**
+ * Parsed hotkey from a string like "ctrl+shift+a" or "Control+ArrowUp".
+ */
+interface ParsedHotkey {
+  key: string;
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+  alt: boolean;
+  super: boolean;
+  hyper: boolean;
+}
+interface ParsedKeypress {
+  name: string;
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+  option: boolean;
+  super: boolean;
+  hyper: boolean;
+  /** Kitty event type. Only set with Kitty flag 2 (report events). */
+  eventType?: "press" | "repeat" | "release";
+  /** The character when Shift is held. From Kitty shifted_codepoint. */
+  shiftedKey?: string;
+  /** The key on a standard US layout (for non-Latin keyboards). From Kitty base_layout_key. */
+  baseLayoutKey?: string;
+  /** CapsLock is active. Kitty modifier bit 6. */
+  capsLock?: boolean;
+  /** NumLock is active. Kitty modifier bit 7. */
+  numLock?: boolean;
+  /** Decoded text from Kitty REPORT_TEXT mode. */
+  associatedText?: string;
+  sequence: string;
+  /** Raw input string, identical to sequence for most keys. */
+  raw?: string;
+  code?: string;
+  /** Whether this key was parsed from the Kitty keyboard protocol. */
+  isKittyProtocol?: boolean;
+  /**
+   * Whether this key represents printable text input.
+   * When false, the key is a control/function/modifier key that should not
+   * produce text input (e.g., arrows, function keys, capslock, media keys).
+   * Only set by the kitty protocol parser.
+   */
+  isPrintable?: boolean;
+  /**
+   * Text associated with the key.
+   * For printable kitty keys, defaults to the character from the codepoint.
+   * When REPORT_TEXT flag is active, contains the decoded text-as-codepoints.
+   */
+  text?: string;
+}
+/**
+ * Parse a raw input sequence into a structured keypress object.
+ * Accepts string or Buffer (Buffer support for stdin compatibility).
+ */
+declare function parseKeypress(s: string | Buffer): ParsedKeypress;
+/**
+ * Parse raw terminal input into a Key object and cleaned input string.
+ *
+ * @param rawInput Raw terminal input (string or Buffer)
+ * @returns Tuple of [cleanedInput, Key]
+ */
+declare function parseKey(rawInput: string | Buffer): [string, Key];
+/**
+ * Create an empty Key object (all fields false).
+ */
+declare function emptyKey(): Key;
+/**
+ * Convert a Key object to a named key string.
+ *
+ * Returns the Playwright-compatible name for special keys (ArrowUp, Enter, etc.)
+ * or "" if no special key is pressed.
+ */
+declare function keyToName(key: Key): string;
+/**
+ * Extract modifier flags from a Key object.
+ * `alt` is always false (terminals cannot distinguish alt from meta).
+ */
+declare function keyToModifiers(key: Key): {
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+  alt: boolean;
+  super: boolean;
+  hyper: boolean;
+};
+/**
+ * Parse a hotkey string into base key and modifiers.
+ *
+ * Supports Playwright-style ("Control+c", "Shift+ArrowUp") and
+ * lowercase aliases ("ctrl+c", "shift+tab", "cmd+a").
+ *
+ * @example
+ * ```tsx
+ * parseHotkey('j')           // { key: 'j', ctrl: false, meta: false, shift: false, alt: false }
+ * parseHotkey('Control+c')   // { key: 'c', ctrl: true, ... }
+ * parseHotkey('Shift+ArrowUp') // { key: 'ArrowUp', shift: true, ... }
+ * parseHotkey('⌘j')          // { key: 'j', super: true, ... } (macOS symbol prefix)
+ * parseHotkey('⌃⇧a')         // { key: 'a', ctrl: true, shift: true, ... }
+ * ```
+ */
+declare function parseHotkey(keyStr: string): ParsedHotkey;
+/**
+ * Match a parsed hotkey against a Key object and input string.
+ *
+ * @param hotkey Parsed hotkey to match
+ * @param key Key object from input event
+ * @param input Optional input string (for matching character keys)
+ * @returns true if the hotkey matches the key event
+ */
+declare function matchHotkey(hotkey: ParsedHotkey, key: Key, input?: string): boolean;
+//#endregion
+//#region packages/ag/src/focus-events.d.ts
+/**
+ * Synthetic keyboard event, mirroring React.KeyboardEvent / DOM KeyboardEvent.
+ */
+interface SilveryKeyEvent {
+  /** The printable character, or "" for non-printable keys */
+  key: string;
+  /** Raw terminal input string */
+  input: string;
+  /** Modifier keys */
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+  super: boolean;
+  hyper: boolean;
+  /** Kitty event type */
+  eventType?: "press" | "repeat" | "release";
+  /** Deepest focusable node that received this event */
+  target: AgNode;
+  /** Node whose handler is currently firing (changes during capture/bubble) */
+  currentTarget: AgNode;
+  /** Stop event from propagating further */
+  stopPropagation(): void;
+  /** Prevent default behavior */
+  preventDefault(): void;
+  /** Whether stopPropagation() was called */
+  readonly propagationStopped: boolean;
+  /** Whether preventDefault() was called */
+  readonly defaultPrevented: boolean;
+  /** Raw parsed key data */
+  nativeEvent: {
+    input: string;
+    key: Key;
+  };
+}
+/**
+ * Synthetic focus event, mirroring React.FocusEvent / DOM FocusEvent.
+ */
+interface SilveryFocusEvent {
+  /** The node gaining or losing focus */
+  target: AgNode;
+  /** The other node involved (losing focus on 'focus', gaining on 'blur') */
+  relatedTarget: AgNode | null;
+  /** Event type */
+  type: "focus" | "blur";
+  /** Node whose handler is currently firing (changes during bubble) */
+  currentTarget: AgNode;
+  /** Stop event from bubbling to parent nodes */
+  stopPropagation(): void;
+  /** Whether stopPropagation() was called */
+  readonly propagationStopped: boolean;
+}
+interface FocusEventProps {
+  /** Whether this node can receive focus */
+  focusable?: boolean;
+  /** Whether this node should receive focus on mount */
+  autoFocus?: boolean;
+  /** Whether this node creates a focus scope (focus trapping boundary) */
+  focusScope?: boolean;
+  /** ID of the node to focus when pressing Up from this node */
+  nextFocusUp?: string;
+  /** ID of the node to focus when pressing Down from this node */
+  nextFocusDown?: string;
+  /** ID of the node to focus when pressing Left from this node */
+  nextFocusLeft?: string;
+  /** ID of the node to focus when pressing Right from this node */
+  nextFocusRight?: string;
+  /** Called when this node gains focus */
+  onFocus?: (event: SilveryFocusEvent) => void;
+  /** Called when this node loses focus */
+  onBlur?: (event: SilveryFocusEvent) => void;
+  /** Called on key down (bubble phase) */
+  onKeyDown?: (event: SilveryKeyEvent, dispatch?: (msg: unknown) => void) => void;
+  /** Called on key up (bubble phase) */
+  onKeyUp?: (event: SilveryKeyEvent, dispatch?: (msg: unknown) => void) => void;
+  /** Called on key down (capture phase — fires before target) */
+  onKeyDownCapture?: (event: SilveryKeyEvent) => void;
+}
+/**
+ * Create a synthetic keyboard event.
+ */
+declare function createKeyEvent(input: string, key: Key, target: AgNode): SilveryKeyEvent;
+/**
+ * Create a synthetic focus event.
+ */
+declare function createFocusEvent(type: "focus" | "blur", target: AgNode, relatedTarget: AgNode | null): SilveryFocusEvent;
+/**
+ * Dispatch a keyboard event through the render tree with DOM-style
+ * capture/target/bubble phases.
+ *
+ * For press/repeat events:
+ *   1. Capture phase: root → target (onKeyDownCapture props)
+ *   2. Target phase: target's onKeyDown
+ *   3. Bubble phase: target parent → root (onKeyDown props)
+ *
+ * For release events:
+ *   1. Target phase: target's onKeyUp
+ *   2. Bubble phase: target parent → root (onKeyUp props)
+ *   (No capture phase for keyUp — deliberate simplification; React DOM has onKeyUpCapture)
+ *
+ * stopPropagation() halts traversal at any phase.
+ */
+declare function dispatchKeyEvent(event: SilveryKeyEvent, dispatch?: (msg: unknown) => void): void;
+/**
+ * Dispatch a focus event through the render tree.
+ *
+ * Fires onFocus/onBlur on the target, then bubbles to ancestors.
+ */
+declare function dispatchFocusEvent(event: SilveryFocusEvent): void;
+//#endregion
+//#region packages/ag/src/layout-types.d.ts
+/**
+ * Layout Type Abstractions
+ *
+ * Pure type interfaces for layout engines (Yoga, Flexily, etc.)
+ * These live in @silvery/ag because they're used by core types (AgNode).
+ * The runtime layout engine management lives in @silvery/ag-term/layout-engine.
+ */
+/**
+ * Measure mode determines how the width/height constraint should be interpreted.
+ *
+ * - "undefined": no constraint — return max-content (natural unconstrained size).
+ * - "at-most":   constrain to at most `width`/`height`. Used for Yoga/CSS
+ *                shrink-wrap and for cross-axis sizing in column/row layouts.
+ * - "exactly":   exactly `width`/`height` — used when a definite size has
+ *                been resolved.
+ * - "min-content": flexily-only extension. Asks the measurer for its
+ *                CSS min-content size — longest unbreakable token for
+ *                wrappable text, naturalWidth for non-wrappable. Used by
+ *                CSS §4.5 auto-min-size derivation. Measurers that don't
+ *                recognize this mode should treat it as "at-most" with
+ *                width/height = 0 (the conservative fallback).
+ */
+type MeasureMode = "undefined" | "exactly" | "at-most" | "min-content";
+/**
+ * Measure function callback for intrinsic sizing.
+ * Called when a node needs to determine its size based on content.
+ */
+type MeasureFunc = (width: number, widthMode: MeasureMode, height: number, heightMode: MeasureMode) => {
+  width: number;
+  height: number;
+};
+/**
+ * A fit-width lane entry: either a plain number (cells, treated as CSS points)
+ * or a `{ value, unit }` object for container-query units.
+ *
+ * String values (`"100cqi"`) are parsed at the React seam (`applyBoxProps`)
+ * into this shape before reaching the LayoutNode adapter; the adapter itself
+ * receives only the parsed form.
+ */
+type FitWidthLane = number | {
+  value: number;
+  unit: "cqi" | "cqmin";
+};
+/**
+ * Abstract layout node interface.
+ * Represents a single node in the layout tree.
+ */
+interface LayoutNode {
+  insertChild(child: LayoutNode, index: number): void;
+  removeChild(child: LayoutNode): void;
+  free(): void;
+  setMeasureFunc(measureFunc: MeasureFunc): void;
+  markDirty(): void;
+  isDirty(): boolean;
+  setWidth(value: number): void;
+  setWidthPercent(value: number): void;
+  setWidthAuto(): void;
+  setWidthFitContent(): void;
+  setWidthSnugContent(): void;
+  setHeight(value: number): void;
+  setHeightPercent(value: number): void;
+  setHeightAuto(): void;
+  setMinWidth(value: number): void;
+  setMinWidthPercent(value: number): void;
+  setMinHeight(value: number): void;
+  setMinHeightPercent(value: number): void;
+  setMaxWidth(value: number): void;
+  setMaxWidthPercent(value: number): void;
+  setMaxHeight(value: number): void;
+  setMaxHeightPercent(value: number): void;
+  setFlexGrow(value: number): void;
+  setFlexShrink(value: number): void;
+  setFlexBasis(value: number): void;
+  setFlexBasisPercent(value: number): void;
+  setFlexBasisAuto(): void;
+  setFlexDirection(direction: number): void;
+  setFlexWrap(wrap: number): void;
+  setAlignItems(align: number): void;
+  setAlignSelf(align: number): void;
+  setAlignContent(align: number): void;
+  setJustifyContent(justify: number): void;
+  setPadding(edge: number, value: number): void;
+  setMargin(edge: number, value: number): void;
+  setBorder(edge: number, value: number): void;
+  setGap(gutter: number, value: number): void;
+  setDisplay(display: number): void;
+  setPositionType(positionType: number): void;
+  setPosition(edge: number, value: number): void;
+  setPositionPercent(edge: number, value: number): void;
+  setOverflow(overflow: number): void;
+  setAspectRatio(value: number): void;
+  /** CSS container-type. Maps to flexily's CONTAINER_TYPE_NORMAL | CONTAINER_TYPE_INLINE_SIZE. */
+  setContainerType(containerType: number): void;
+  /** CSS contain: size. True = block intrinsic propagation on the inline axis. */
+  setContainSize(value: boolean): void;
+  /**
+   * Fit-width lanes (A0.2). Single-pass lane snap; consumes children's
+   * max-content and picks the smallest lane that fits (else last). Each
+   * entry is either a plain number (cells) or a `{ value, unit }` object
+   * for cqi/cqmin entries. Pass `undefined` to disable.
+   *
+   * Engine requirement: this maps to flexily's `setFitWidth` directly.
+   * Adapters without the capability MUST implement as a no-op; the user-facing
+   * throw fires at the React layer via `requireCapability("fitWidth", ...)`.
+   */
+  setFitWidth(lanes: readonly FitWidthLane[] | undefined): void;
+  calculateLayout(width: number, height: number, direction?: number): void;
+  getComputedLeft(): number;
+  getComputedTop(): number;
+  getComputedWidth(): number;
+  getComputedHeight(): number;
+}
+//#endregion
+//#region packages/ag/src/mouse-event-types.d.ts
+/**
+ * Synthetic mouse event, mirroring React.MouseEvent / DOM MouseEvent.
+ */
+interface SilveryMouseEvent {
+  /**
+   * Silvery layout X coordinate, comparable to Rect.x.
+   * In terminal renderers this is measured in terminal cells and may be
+   * fractional when SGR-Pixels mouse mode is active.
+   */
+  x: number;
+  /**
+   * Silvery layout Y coordinate, comparable to Rect.y.
+   * In terminal renderers this is measured in terminal cells and may be
+   * fractional when SGR-Pixels mouse mode is active.
+   */
+  y: number;
+  /** Physical pixel X coordinate when the backend provides one. */
+  clientX?: number;
+  /** Physical pixel Y coordinate when the backend provides one. */
+  clientY?: number;
+  /** Mouse button: 0=left, 1=middle, 2=right */
+  button: number;
+  /** Modifier keys */
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+  /** Deepest node under cursor */
+  target: AgNode;
+  /** Node whose handler is currently firing (changes during bubble) */
+  currentTarget: AgNode;
+  /** Event type */
+  type: "click" | "dblclick" | "tripleclick" | "mousedown" | "mouseup" | "mousemove" | "mouseenter" | "mouseleave" | "wheel";
+  /** Monotonic timestamp for the input event. */
+  timeStamp?: number;
+  /** Monotonic id shared by events parsed from the same terminal input chunk. */
+  inputBatchId?: number;
+  /**
+   * Click count for `click` / `dblclick` / `tripleclick` events
+   * (mirrors DOM `MouseEvent.detail`).
+   *
+   * - 1 on a fresh click (`type === "click"`)
+   * - 2 on a double-click (`type === "dblclick"`)
+   * - 3 on a triple-click (`type === "tripleclick"`)
+   * - undefined on non-click events
+   */
+  detail?: 1 | 2 | 3;
+  /** Stop event from bubbling to parent nodes */
+  stopPropagation(): void;
+  /** Prevent default behavior */
+  preventDefault(): void;
+  /** Whether stopPropagation() was called */
+  readonly propagationStopped: boolean;
+  /** Whether preventDefault() was called */
+  readonly defaultPrevented: boolean;
+  /** Raw parsed mouse data from terminal protocol */
+  nativeEvent: unknown;
+}
+/**
+ * Synthetic wheel event, extending SilveryMouseEvent with scroll deltas.
+ */
+interface SilveryWheelEvent extends SilveryMouseEvent {
+  /** Vertical scroll: -1 (up) or +1 (down) */
+  deltaY: number;
+  /** Horizontal scroll: always 0 for terminals */
+  deltaX: number;
+}
+interface MouseEventProps {
+  onClick?: (event: SilveryMouseEvent) => void;
+  onDoubleClick?: (event: SilveryMouseEvent) => void;
+  /** Triple-click handler — fires after `onDoubleClick` when the user
+   *  produces a third click within 300ms / 2 cells of the first two. */
+  onTripleClick?: (event: SilveryMouseEvent) => void;
+  onMouseDown?: (event: SilveryMouseEvent) => void;
+  onMouseUp?: (event: SilveryMouseEvent) => void;
+  onMouseMove?: (event: SilveryMouseEvent) => void;
+  onMouseEnter?: (event: SilveryMouseEvent) => void;
+  onMouseLeave?: (event: SilveryMouseEvent) => void;
+  onWheel?: (event: SilveryWheelEvent) => void;
+}
+//#endregion
+//#region packages/ag/src/types.d.ts
+/**
+ * CSS user-select equivalent for controlling text selectability.
+ * - "auto": inherit from parent (root resolves to "text")
+ * - "none": not selectable
+ * - "text": force selectable (overrides parent "none")
+ * - "contain": selectable, but selection cannot escape this node's bounds
+ *
+ * Mouse selection is document/tree-aware by default: the active scope is the
+ * nearest common selectable ancestor of the drag anchor and focus. `contain`
+ * keeps its CSS meaning as an explicit hard boundary.
+ */
+type UserSelect = "auto" | "none" | "text" | "contain";
+/**
+ * A rectangle with position and size.
+ * All values are in terminal columns/rows (integers).
+ */
+interface Rect {
+  /** X position (0-indexed terminal column) */
+  x: number;
+  /** Y position (0-indexed terminal row) */
+  y: number;
+  /** Width in terminal columns */
+  width: number;
+  /** Height in terminal rows */
+  height: number;
+}
+/**
+ * Terminal cursor shape (DECSCUSR).
+ *
+ * @deprecated Target-specific. Lives in core only as a back-compat alias for the
+ * `CursorOffset.shape` deprecation cycle (see {@link CursorOffset.shape}). The
+ * canonical home is `@silvery/ag-term/output#CursorShape`. Cross-target
+ * renderers (canvas / DOM) must not branch on this enum — instead, they read
+ * the focused-editable bit from `LayoutSignals` and map to whatever caret
+ * concept their target supports. Removed in the next cycle.
+ *
+ * Lower-case names match the DECSCUSR vocabulary: `block` (steady #2),
+ * `underline` (steady #4), `bar` (steady #6).
+ */
+type CursorShape = "block" | "underline" | "bar";
+/**
+ * Component-relative caret position declared as a Box prop.
+ *
+ * When set on a Box, the layout phase computes the absolute terminal
+ * coordinates by adding the parent's `scrollRect` + the box's border + padding
+ * + this offset. The result is exposed via `LayoutSignals.cursorRect` and read
+ * by the scheduler's cursor-suffix emission. The caret naming reflects the
+ * cross-target nature: in the terminal it manifests as the hardware cursor,
+ * but on canvas/DOM targets it's the text-input caret rectangle.
+ *
+ * This is the "caret as layout output" path — it bypasses the React effect
+ * chain entirely (`useCursor` → `useScrollRect` → `setCursorState`) so the
+ * very first frame after mount emits the correct caret positioning ANSI.
+ * See bead `km-silvery.view-as-layout-output` (Phase 2),
+ * `km-silvery.cursor-invariants`, and `km-silvercode.cursor-startup-position`.
+ */
+interface CursorOffset {
+  /** Column offset within the box's content area (0-indexed) */
+  col: number;
+  /** Row offset within the box's content area (0-indexed) */
+  row: number;
+  /** Whether the caret should be visible. Default: true */
+  visible?: boolean;
+  /**
+   * Terminal cursor shape (DECSCUSR).
+   *
+   * @deprecated Target-specific — DO NOT use in new code. The terminal layer
+   * (`@silvery/ag-term`) derives the shape from focus + editable state at
+   * scheduler/output time via the caretStyle map. Cross-target consumers
+   * (canvas / DOM) ignore this field. Accepted for one cycle for back-compat;
+   * removed in the next major. See `km-silvery.cursor-invariants` invariant 6.
+   */
+  shape?: CursorShape;
+}
+/**
+ * Semantic selection intent declared on a Box — the user's "selected
+ * substring" within this node's text content, expressed as character offsets.
+ *
+ * This is the **input** half of the selection-as-overlay model (Phase 4b of
+ * `km-silvery.view-as-layout-output`):
+ *
+ *  - **Input** (this type): `selectionIntent` — what the user wants selected.
+ *  - **Output** (`LayoutSignals.selectionFragments`): the resolved list of
+ *    rectangles (one per visual line spanned). Computed during the layout
+ *    pass; consumed by the selection renderer to paint highlight bg.
+ *
+ * Mirrors `CursorOffset`'s shape: a small declarative payload on the owning
+ * Box. The layout phase runs `computeSelectionFragments(node)` to derive the
+ * geometric fragments and pushes them onto the per-node signal. Components
+ * like `TextArea`, `Text` (when selectable), or any node with a selected
+ * substring can declare this prop.
+ *
+ * **Rules**:
+ *  - `from` and `to` are character offsets into the rendered text content of
+ *    the owning node (post-render, post-wrap). The fragment computation
+ *    walks the node's text layout to map offsets to visual rectangles.
+ *  - `from <= to`. A collapsed selection (`from === to`) produces zero
+ *    fragments — caret rendering is `cursorOffset`'s job.
+ *  - `null`/`undefined` on a Box means "no selection on this node" — that
+ *    node contributes no fragments.
+ *  - Multiple Boxes may declare `selectionIntent` simultaneously; the
+ *    aggregator (`findActiveSelectionFragments(root)`) concatenates fragments
+ *    from all currently-mounted declarers (Phase 4b — multi-node selection
+ *    is left for a future enhancement; v1 concatenation already covers the
+ *    "two adjacent nodes both selected" case).
+ *
+ * **Cross-target hygiene**: this type is purely semantic (offsets only). The
+ * resolved `Rect[]` output and the actual highlight bg color stay terminal-
+ * specific (or canvas/DOM-specific in future targets). Tracking bead:
+ * `km-silvery.phase4-split-focus-selection`.
+ */
+interface SelectionIntent {
+  /**
+   * Inclusive start offset (character index into the owning node's rendered
+   * text content). Must be `>= 0` and `<= text.length`.
+   */
+  from: number;
+  /**
+   * Exclusive end offset (character index). Must be `>= from` and
+   * `<= text.length`. When `from === to` the selection is collapsed and
+   * produces zero fragments.
+   */
+  to: number;
+}
+/**
+ * Twelve-placement vocabulary for floating decorations relative to an anchor
+ * rect. The first segment names the side of the anchor the floating element
+ * lives on; the second segment names the alignment along the perpendicular
+ * axis (start, center, end). Mirrors Floating UI / Popper.js's vocabulary so
+ * apps moving between targets can carry placement intent verbatim.
+ *
+ * The placement string maps deterministically to a rect via `placeFloating`.
+ * Collision-aware auto-flip + auto-shift are layered on top by
+ * `resolveFloatingPlacement` and opt in via `Decoration.collisionStrategy`.
+ */
+type Placement = "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "left-start" | "left-center" | "left-end" | "right-start" | "right-center" | "right-end";
+/**
+ * Collision policy for floating overlays. Mirrors the common Floating UI /
+ * Popper progression while staying terminal-cell deterministic:
+ *
+ * - `"none"`: preserve the requested placement even if it overflows.
+ * - `"flip"`: try the opposite side when the requested side overflows.
+ * - `"shift"`: keep the requested side, but clamp the rect inside the boundary.
+ * - `"flip-then-shift"`: flip if that improves the side-axis overflow, then clamp.
+ * - `"hide"`: emit no rect when the requested placement cannot fit.
+ */
+type CollisionStrategy = "none" | "flip" | "shift" | "flip-then-shift" | "hide";
+/**
+ * Declarative overlay attached to a Box. The substrate v1 shipped here covers
+ * three kinds — popover, tooltip, highlight — that share the "decoration
+ * derived from semantic intent during layout" shape. Caret / focus / selection
+ * keep their dedicated BoxProps (`cursorOffset`, `focused`, `selectionIntent`)
+ * for ergonomic + back-compat reasons; everything else routes through
+ * `decorations`.
+ *
+ * **`kind`** drives the geometry computation:
+ *   - `"popover"` and `"tooltip"`: anchor-relative placement via
+ *     `placeFloating(anchorRect, size, placement)`. The `placement` field is
+ *     required (no implicit default — apps must say where they want it).
+ *     `content` is opaque to the substrate — the renderer owns rendering.
+ *   - `"highlight"`: a rect-list output describing visible-line fragments
+ *     within the owning Box's content area. v1 ships only the bounding rect;
+ *     soft-wrap aware fragmentation is implemented in the same way as
+ *     `selectionFragments` (Phase 4b) and arrives in v2 once the find/replace
+ *     match-highlight first consumer ships.
+ *
+ * **`id`** is app-chosen, must be unique within a frame, and stable across
+ * re-renders (consumers may key React-side state off it).
+ *
+ * Coordinate space is the same absolute terminal-cell space used by every
+ * other rect signal (`cursorRect`, `selectionFragments`, etc.).
+ *
+ * **Out of scope for v1** (deferred to v2):
+ *   - Generic `kind: "custom"` extension hook
+ *   - Z-index / paint-order overrides (paint order is fixed: caret > focus >
+ *     selection > decorations > anchors)
+ *
+ * See `hub/silvery/design/overlay-anchor-system.md` for the design context.
+ */
+type Decoration = {
+  kind: "popover";
+  id: string; /** Anchor target by id, looked up via `findAnchor(root, anchorId)`. */
+  anchorId?: string;
+  placement?: Placement; /** Intrinsic size for the floating rect (cells). Required for placement math. */
+  size?: {
+    width: number;
+    height: number;
+  }; /** Optional gap along the placement axis (cells). */
+  offset?: number; /** Optional offset along the alignment axis (cells). */
+  alignOffset?: number; /** Optional viewport collision policy. Default: "none". */
+  collisionStrategy?: CollisionStrategy; /** Renderer-owned content. The substrate doesn't inspect this. */
+  content?: unknown;
+} | {
+  kind: "tooltip";
+  id: string;
+  anchorId?: string;
+  placement?: Placement;
+  size?: {
+    width: number;
+    height: number;
+  };
+  offset?: number;
+  alignOffset?: number;
+  collisionStrategy?: CollisionStrategy;
+  content?: unknown;
+} | {
+  kind: "highlight";
+  id: string;
+  /**
+   * Highlight rect within the owning Box's content area, expressed in the
+   * Box's local content-relative coordinates (origin = contentRect.{x,y},
+   * size in cells). v1 emits one rect; soft-wrap fragmentation lands in
+   * v2 alongside the find/replace consumer.
+   */
+  rect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+};
+/**
+ * Layout-anchor identifier — names this Box as a lookup target so other
+ * Boxes' decorations can reference it via `Decoration.anchorId`.
+ *
+ * The id is app-chosen, must be unique within a tree, and stable enough across
+ * re-renders to survive React reconciliation without identity churn (use a
+ * literal string from props, not a `useId()` value, unless you persist it).
+ *
+ * Anchors are recorded into a tree-scoped map at the end of layout phase by
+ * `findAnchor(root, id)`. The map's value is the Box's `contentRect` (full
+ * inner area) — placement math then derives edge rects via `placeFloating`.
+ */
+interface AnchorRef {
+  id: string;
+}
+/**
+ * Per-node interactive state — written by pointer/selection/focus state machines,
+ * read by theme/render for automatic styling.
+ *
+ * These are plain mutable booleans, NOT reactive signals. State machines set them
+ * synchronously during event processing, and the next render reads them.
+ * React re-renders are driven by the event processing, not signal subscriptions.
+ *
+ * The object is lazily created on first write to avoid overhead on non-interactive nodes.
+ */
+interface InteractiveState {
+  /** Pointer is over this node (mouseenter/mouseleave) */
+  hovered: boolean;
+  /** Pointer-down on this node, awaiting pointer-up (will receive click) */
+  armed: boolean;
+  /** Node is in the current selection set */
+  selected: boolean;
+  /** Node has keyboard focus */
+  focused: boolean;
+  /** A drag operation is hovering over this node */
+  dropTarget: boolean;
+}
+/**
+ * Silvery node types - the primitive elements in the render tree.
+ *
+ * - `silvery-viewport` is a leaf node hosting a foreign cell domain
+ *   (xtermjs PTY, replay frames, snapshot). See {@link viewport-types.ts}
+ *   and bead `@km/silvery/15513-surface-nested-composition-primitive`.
+ * - `silvery-island` is the runtime-agnostic cell-grid mount primitive —
+ *   sibling of `silvery-box` / `silvery-text`. Holds an
+ *   {@link import("./island-types").IslandHandle} ref + per-node lifecycle.
+ *   Supersedes `silvery-viewport` in epic
+ *   `@km/silvery/15646-islands` (Phase 4 deletes `silvery-viewport`).
+ */
+type AgNodeType = "silvery-root" | "silvery-box" | "silvery-text" | "silvery-viewport" | "silvery-island";
+/**
+ * Flexbox properties that can be applied to Box nodes.
+ */
+interface FlexboxProps {
+  width?: number | string;
+  height?: number | string;
+  minWidth?: number | string;
+  minHeight?: number | string;
+  maxWidth?: number | string;
+  maxHeight?: number | string;
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: number | string;
+  flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+  flexWrap?: "nowrap" | "wrap" | "wrap-reverse";
+  alignItems?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+  alignSelf?: "auto" | "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+  alignContent?: "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-around" | "space-evenly";
+  justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
+  padding?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  paddingX?: number;
+  paddingY?: number;
+  margin?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  marginRight?: number;
+  marginX?: number;
+  marginY?: number;
+  gap?: number;
+  columnGap?: number;
+  rowGap?: number;
+  position?: "relative" | "absolute" | "sticky" | "static";
+  top?: number | string;
+  left?: number | string;
+  bottom?: number | string;
+  right?: number | string;
+  stickyTop?: number;
+  stickyBottom?: number;
+  aspectRatio?: number;
+  display?: "flex" | "none";
+  overflow?: "visible" | "hidden" | "scroll";
+  overflowX?: "visible" | "hidden";
+  overflowY?: "visible" | "hidden";
+  /**
+   * Child index to ensure visible. Declarative — the Box fires edge-based
+   * ensure-visible when this value CHANGES (or on mount). Re-renders with
+   * the same value are no-ops; content-height changes do not re-trigger
+   * the ensure-visible pass.
+   *
+   * This "fire on change" semantic prevents viewport jumps when a visible
+   * child grows (e.g. user clicks to expand a collapsible row): the Box no
+   * longer re-anchors on every render. Matches the convention used by
+   * `@tanstack/virtual`, `react-window`, iOS `UIScrollView.setContentOffset`
+   * — imperative intent is separate from declarative anchor state.
+   *
+   * To re-fire ensure-visible against the SAME target (e.g. "scroll to
+   * cursor, even though cursor didn't change"), toggle the value via undefined
+   * first, or drive scroll via the explicit `scrollOffset` prop.
+   */
+  scrollTo?: number;
+  /** Explicit scroll offset in rows (used when scrollTo is undefined for frozen scroll state) */
+  scrollOffset?: number;
+}
+/**
+ * Props for testing and identification.
+ * These props are stored in the node for DOM query access.
+ */
+interface TestProps {
+  /** Element ID for DOM queries and visual debugging */
+  id?: string;
+  /** Test ID for querying nodes (like Playwright's data-testid) */
+  testID?: string;
+  /** Allow arbitrary data-* attributes for testing */
+  [key: `data-${string}`]: unknown;
+}
+/**
+ * Underline style variants (SGR 4:x codes).
+ * - false: no underline
+ * - 'single': standard underline (SGR 4 or 4:1)
+ * - 'double': double underline (SGR 4:2)
+ * - 'curly': curly/wavy underline (SGR 4:3)
+ * - 'dotted': dotted underline (SGR 4:4)
+ * - 'dashed': dashed underline (SGR 4:5)
+ */
+type UnderlineStyle$1 = false | "single" | "double" | "curly" | "dotted" | "dashed";
+/**
+ * Named underline styles — the string half of `underline: boolean | UnderlineStyleName`.
+ * Excludes `false` so the boolean-or-string union doesn't have two falsy branches.
+ */
+type UnderlineStyleName = Exclude<UnderlineStyle$1, false>;
+/**
+ * Style properties for text rendering.
+ */
+interface StyleProps {
+  color?: string;
+  backgroundColor?: string;
+  bold?: boolean;
+  italic?: boolean;
+  /**
+   * Enable underline. Accepts:
+   * - `true` — standard single underline (equivalent to `"single"`)
+   * - `false` — no underline
+   * - `"single" | "double" | "curly" | "dotted" | "dashed"` — specific style variant
+   *
+   * A style name is equivalent to setting `underline=true` with that style.
+   */
+  underline?: boolean | UnderlineStyleName;
+  /**
+   * @deprecated Pass the style name directly to `underline` instead
+   * (e.g. `underline="curly"`). `underlineStyle` is retained for backwards
+   * compatibility and still takes precedence over `underline` when both are set.
+   * Will be removed in a future major.
+   */
+  underlineStyle?: UnderlineStyle$1;
+  /**
+   * Underline color (independent of text color).
+   * Uses SGR 58 (underline color). Falls back to text color if not specified.
+   */
+  underlineColor?: string;
+  /**
+   * Overline the cell — SGR 53/55. Independent of underline.
+   *
+   * SGR 53 places a line ABOVE the character cell; SGR 55 removes it.
+   * Use this for top-edge indicators (e.g. overscroll-at-top), where an
+   * underline on the first row would read as "this row is underlined" rather
+   * than "you're bumped against the top". Overline on the top row and
+   * underline on the bottom row are the semantically correct pair.
+   *
+   * Supported by most modern terminals (Ghostty, iTerm2, xterm with
+   * `allowExtendedUnderlines` equivalent). The output phase skips SGR 53/55
+   * when {@link TerminalCaps#overline} is false.
+   */
+  overline?: boolean;
+  /**
+   * Overline color — reserved. Currently not plumbed through the pipeline;
+   * see bead `km-silvery.overline-color` for the follow-up that mirrors
+   * {@link underlineColor}'s SGR 58 wiring for overline. Setting this today
+   * is a no-op.
+   */
+  overlineColor?: string;
+  strikethrough?: boolean;
+  inverse?: boolean;
+  /**
+   * Text size scale factor via OSC 66 (Kitty v0.40+).
+   *
+   * Float multiplier: 2.0 = double (headings), 1.0 = normal, 0.5 = half (small print).
+   * The terminal renders subsequent text at this scale until reset.
+   * Requires a terminal that supports the kitty text sizing protocol.
+   * Terminals without support silently ignore the escape sequence.
+   */
+  textSize?: number;
+}
+/**
+ * Props for Box component.
+ */
+interface BoxProps extends FlexboxProps, StyleProps, TestProps, MouseEventProps, DragEventProps, FocusEventProps {
+  /** Text truncation mode for child text content (passed through to Text children). */
+  wrap?: "wrap" | "wrap-truncate" | "hard" | "even" | "truncate" | "truncate-start" | "truncate-middle" | "truncate-end" | "clip" | boolean;
+  borderStyle?: "single" | "double" | "round" | "bold" | "singleDouble" | "doubleSingle" | "classic";
+  borderColor?: string;
+  /** Background color for all border sides (shorthand). Per-side props override this. */
+  borderBackgroundColor?: string;
+  /** Background color for the top border (overrides borderBackgroundColor). */
+  borderTopBackgroundColor?: string;
+  /** Background color for the bottom border (overrides borderBackgroundColor). */
+  borderBottomBackgroundColor?: string;
+  /** Background color for the left border (overrides borderBackgroundColor). */
+  borderLeftBackgroundColor?: string;
+  /** Background color for the right border (overrides borderBackgroundColor). */
+  borderRightBackgroundColor?: string;
+  borderTop?: boolean;
+  borderBottom?: boolean;
+  borderLeft?: boolean;
+  borderRight?: boolean;
+  /**
+   * Outline style — renders border characters OUTSIDE the box without affecting layout.
+   *
+   * Unlike `borderStyle` which adds border dimensions inside the box (shrinking the
+   * content area), `outlineStyle` draws one cell beyond each edge — in the gap/margin
+   * space between siblings. The layout engine sees no border at all.
+   *
+   * This matches CSS `outline` semantics: outside the border box, no layout impact.
+   *
+   * Use cases: focus rings, hover highlights, selection indicators, edit bounds —
+   * anything that should visually frame a box without affecting layout or content.
+   */
+  outlineStyle?: "single" | "double" | "round" | "bold" | "singleDouble" | "doubleSingle" | "classic";
+  /** Foreground color for the outline */
+  outlineColor?: string;
+  /** Apply dim styling to the outline */
+  outlineDimColor?: boolean;
+  /** Show top outline edge (default: true) */
+  outlineTop?: boolean;
+  /** Show bottom outline edge (default: true) */
+  outlineBottom?: boolean;
+  /** Show left outline edge (default: true) */
+  outlineLeft?: boolean;
+  /** Show right outline edge (default: true) */
+  outlineRight?: boolean;
+  /**
+   * Override theme for this subtree — $token colors resolve against this theme.
+   * Pushed onto the context theme stack during render phase tree walk.
+   */
+  theme?: Theme;
+  /** CSS pointer-events equivalent. "none" makes this node and its subtree invisible to hit testing. */
+  pointerEvents?: "auto" | "none";
+  /**
+   * CSS user-select equivalent. Controls whether text in this node is selectable.
+   * - "auto" (default): inherit from parent. Root resolves to "text".
+   * - "none": not selectable. Mouse-drag on this node does not start text selection.
+   * - "text": force selectable, even if parent is "none".
+   * - "contain": selectable, but selection range cannot escape this node's bounds.
+   */
+  userSelect?: UserSelect;
+  /**
+   * Whether this node can be dragged via mouse.
+   * When true, mousedown + drag past threshold initiates a node drag gesture
+   * instead of text selection. Not inherited — only the node with draggable=true
+   * is draggable, not its children.
+   */
+  draggable?: boolean;
+  /**
+   * Capture pointer-style mouse events after mousedown.
+   *
+   * When true, a mousedown inside this node makes subsequent mousemove and
+   * mouseup events for that press bubble from this node even if the cursor
+   * leaves its one-cell hit box. Hover enter/leave still follows the real
+   * cursor target. This is the terminal equivalent of pointer capture for
+   * narrow draggable controls such as scrollbars.
+   */
+  mouseCapture?: boolean;
+  onLayout?: (layout: Rect) => void;
+  /**
+   * Show scroll overflow indicators (▲N / ▼N) for scrollable containers.
+   *
+   * For bordered containers, indicators appear on the border.
+   * For borderless containers, indicators overlay the content at top-right/bottom-right.
+   *
+   * Only applies when overflow='scroll'.
+   */
+  overflowIndicator?: boolean;
+  /**
+   * Declarative focus marker — "this Box is focused." When set on a Box, the
+   * layout phase writes the node's id (or testID) to `LayoutSignals.focusedNodeId`
+   * and the focus-renderer reads from that signal to paint the focus ring /
+   * dim styling — bypassing the `useFocus` → `FocusManager` → `useSyncExternalStore`
+   * chain on the first frame after mount.
+   *
+   * This is the **focus-as-layout-output** path (Phase 4a of
+   * `km-silvery.view-as-layout-output`). It mirrors `cursorOffset` exactly:
+   * a semantic boolean declared on the outer Box, resolved into a layout
+   * signal during `syncRectSignals`, with a tree-walk lookup
+   * (`findActiveFocusedNodeId`) that the renderer / scheduler consumes.
+   *
+   * **Precedence across nodes** (mirrors cursor invariant 1):
+   * 1. Deepest visible focused declarer in paint-order wins. If two siblings
+   *    both have `focused === true`, the post-order tree walk picks the
+   *    later-rendered one — consistent with cursor's deepest-wins fallback.
+   * 2. Otherwise null.
+   *
+   * **Identity**: the signal value is the node's `id` if present, else its
+   * `testID`, else null. Apps that need stable focus identity should set one
+   * of those props alongside `focused={true}`.
+   *
+   * **Cross-target hygiene**: `focused` is a semantic boolean. Terminal-specific
+   * focus styling (dim, bold borders, focus ring) lives in `@silvery/ag-term`
+   * or component-level styling. Canvas/DOM targets read the same id-level
+   * signal but render their own focus indicator.
+   *
+   * **Back-compat**: `useFocus` continues to work as a deprecated wrapper that
+   * routes through the legacy `FocusManager` path. Migrate to `focused={…}`
+   * to opt into the layout-output path.
+   */
+  focused?: boolean;
+  /**
+   * Component-relative caret position. When set, the layout phase computes
+   * absolute terminal coordinates (border + padding + offset relative to the
+   * box's `scrollRect`) and writes them to `LayoutSignals.cursorRect`. The
+   * scheduler reads this value to emit caret positioning ANSI on the very
+   * first frame after mount — bypassing the React effect chain that
+   * `useCursor` relies on.
+   *
+   * This is the "caret as layout output" path. The legacy `useCursor` hook
+   * remains as a back-compat wrapper but its signal-effect bridge is unsafe
+   * across conditional mounts (see `km-silvercode.cursor-startup-position`).
+   *
+   * **Precedence across nodes** (locked by `km-silvery.cursor-invariants` #1):
+   * 1. Focused-editable wins — a Box that is `focused` AND has visible
+   *    `cursorOffset` always beats a non-focused declarer.
+   * 2. Otherwise deepest-in-paint-order (post-order tree walk) wins.
+   * 3. Otherwise null.
+   *
+   * **Clipping** (invariant #4): if the caret falls outside the nearest
+   * `overflow="scroll"` / `"hidden"` ancestor's visible region, it is hidden
+   * (no caret ANSI emitted, signal returns null). Caret rect at the exact
+   * clip edge is treated as visible.
+   */
+  cursorOffset?: CursorOffset;
+  /**
+   * Semantic selection intent — the user's selected substring within this
+   * Box's text content, declared as character offsets `{ from, to }`. The
+   * layout phase resolves this into a list of rectangles
+   * (`LayoutSignals.selectionFragments`) that the selection renderer reads
+   * to paint highlight bg.
+   *
+   * This is the **selection-as-overlay** path (Phase 4b of
+   * `km-silvery.view-as-layout-output`). It mirrors `cursorOffset` exactly:
+   * a semantic declaration on the outer Box, resolved into geometric output
+   * during `syncRectSignals`, with a tree-walk lookup
+   * (`findActiveSelectionFragments`) that the renderer consumes.
+   *
+   * **Geometry**:
+   * - Collapsed (`from === to`) → zero fragments. Caret rendering is
+   *   `cursorOffset`'s responsibility, not selection's.
+   * - Single visual line → one rectangle from `from` to `to`.
+   * - Multi-line (text contains `\n` characters) → one rectangle per visual
+   *   line: the first runs from `from` to end-of-line, middle lines span the
+   *   full content area width, the last runs from start-of-line to `to`.
+   * - Wrap-aware fragment computation across word-wrapped visual lines is
+   *   limited in v1 — only embedded `\n` produces multi-line fragments. A
+   *   future iteration will register a wrap measurer so soft-wrapped text
+   *   produces the correct per-visual-line fragments. Track at
+   *   `km-silvery.overlay-anchor-system` (Phase 4c).
+   *
+   * **Multi-node selection**: each Box declares its own intent;
+   * `findActiveSelectionFragments(root)` concatenates fragments across all
+   * mounted declarers. Two adjacent nodes both selected is supported. Full
+   * cross-node range selection (selecting from middle of node A through
+   * node B) is a future enhancement.
+   *
+   * **Cross-target hygiene**: `selectionIntent` is purely semantic. The
+   * resolved `Rect[]` is purely geometric. Terminal-specific bg highlight
+   * styling lives in `@silvery/ag-term` (selection-renderer); canvas/DOM
+   * targets read the same fragments and render their own highlight.
+   *
+   * **Back-compat**: `useSelection` continues to work as a deprecated
+   * wrapper that reads from the legacy `SelectionFeature` capability.
+   * Migrate to `selectionIntent={…}` to opt into the layout-output path.
+   */
+  selectionIntent?: SelectionIntent;
+  /**
+   * Names this Box as a layout-anchor lookup target. Other Boxes' decorations
+   * can reference the id via `Decoration.anchorId` and the substrate resolves
+   * the position via `findAnchor(root, id)`.
+   *
+   * Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1). The
+   * registered rect is the Box's `contentRect` (border + padding excluded);
+   * edge-specific rects are derived by `placeFloating` at consumption time.
+   *
+   * Pass a string for the simple case (`anchorRef="dropdown-trigger"`) or an
+   * AnchorRef object if a future v2 wants to extend with edge metadata.
+   *
+   * **Stability**: ids should be stable across re-renders — React reconciler
+   * preserves the AgNode identity, but registering a new id per render makes
+   * `findAnchor` flap and breaks decoration layout. Use a literal string from
+   * props, not a `useId()` value, unless persisted.
+   */
+  anchorRef?: string | AnchorRef;
+  /**
+   * Declarative overlays attached to this Box — popovers, tooltips,
+   * highlights. Each entry is resolved into a geometric `DecorationRect` in
+   * `LayoutSignals.decorationRects` during layout phase, and aggregated into
+   * the per-frame `OverlayLayer` artifact returned alongside `term.frame`.
+   *
+   * Phase 4c of `km-silvery.view-as-layout-output` (overlay-anchor v1).
+   *
+   * **Paint order** is fixed (no z-index): caret > focus > selection >
+   * decorations > anchors. Within `decorations` itself, list order determines
+   * paint order (later entries paint on top of earlier ones).
+   *
+   * **Anchor lookup**: popover/tooltip kinds reference an `anchorId`; the
+   * substrate calls `findAnchor(root, id)` at layout time. If the anchor
+   * isn't found this frame, the decoration emits an empty rect list (the
+   * renderer skips it). By default placement is fixed; opt into viewport
+   * collision handling with `collisionStrategy`.
+   *
+   * **Stable identity**: pass a memoized array if React's referential equality
+   * matters for downstream consumers; the substrate itself recomputes
+   * decoration rects every layout pass, so referential identity isn't load-
+   * bearing on the substrate side.
+   */
+  decorations?: readonly Decoration[];
+  /**
+   * Virtualization-internal: set only by virtual list placeholders (e.g.
+   * ListView's leading/trailing spacer Boxes). **Do not set on ordinary Box
+   * children** — the default (1 visual = 1 logical item) is correct.
+   *
+   * For a child of an `overflow="scroll"` container: declare that this child
+   * is a placeholder representing multiple logical items. When the child is
+   * fully scrolled out above/below the viewport, the parent's
+   * `hiddenAbove`/`hiddenBelow` count is incremented by this value instead of
+   * 1, so `▲N`/`▼N` indicators reflect real items rather than rendered
+   * placeholder boxes.
+   *
+   * Only read by the parent scroll container. Defaults to 1 (treat as a
+   * single visual item). Must be >= 0.
+   *
+   * @internal
+   */
+  representsItems?: number;
+  /**
+   * Declare this Box as a container-query container (A0.1).
+   *
+   * Descendants' `cqi` / `cqmin` values resolve against this Box's frozen
+   * inline-size, captured during layout Pass 1. Combined with `containSize`,
+   * this Box's inline-size is invariant under children's CQ branch flips.
+   *
+   * `"inline-size"` — equivalent to CSS `container-type: inline-size`. Maps to
+   *   `flexily.CONTAINER_TYPE_INLINE_SIZE` at the engine layer.
+   * `"normal"` — opt out (default). Phase 1 supports only the two values.
+   */
+  containerType?: "normal" | "inline-size";
+  /**
+   * Enable CSS `contain: size` on this Box (A0.1).
+   *
+   * When true, children's intrinsic sizes do not propagate into this Box's
+   * inline-size. Required pairing with `containerType: "inline-size"` for a
+   * sound CQ container — without it, child sizes feed back into container
+   * size and break the two-phase invariance guarantee. The dev-mode
+   * `intrinsic-leak` assertion throws on the unsound configuration.
+   *
+   * Phase 1 contains inline-size only.
+   */
+  containSize?: boolean;
+  /**
+   * Container name (CSS `container-name`) — referenced by `@container <name>`
+   * queries. Phase 1 is informational only (single anonymous container per
+   * subtree); named-container resolution arrives with the silvery-layer CQ
+   * matcher.
+   */
+  containerName?: string;
+  /**
+   * Container-query branches — declarative responsive styling against this
+   * Box's frozen inline-size (A0.1 substrate). Phase 1 ships the engine hook;
+   * the matcher that interprets `containerQueries` and applies branch styles
+   * to children lands as part of Phase A (silvery layer).
+   *
+   * Until the matcher ships, the prop is reserved for forward-compat — passing
+   * it does not yet apply branch styles. Use cqi units directly for now.
+   */
+  containerQueries?: readonly ContainerQueryBranch[];
+  /**
+   * Single-pass fit-content lane snap (A0.2). The engine-resolved lane
+   * primitive — no React round-trip, no measurement subtree.
+   *
+   * Box's inline-size snaps to the smallest lane that fits its children's
+   * max-content. Lane entries accept numbers (treated as cells) or strings
+   * like `"100cqi"` / `"50cqi"` / `"100cqmin"` (parsed at this layer into
+   * the engine's unit form).
+   *
+   * If max-content exceeds every lane, the LAST lane is used — by convention
+   * place lanes in ascending order so this behaves as "biggest lane wins".
+   *
+   * Example (chat content lanes):
+   *   <Box fitWidth={[80, 120, "100cqi"]}>
+   *     {messageBlocks}
+   *   </Box>
+   *
+   * Engine requirement: flexily-only. Under yoga, throws at first paint via
+   * `requireCapability("fitWidth", ...)`.
+   */
+  fitWidth?: readonly (number | string)[];
+}
+/**
+ * A container-query branch (A0.1 substrate; matcher in Phase A).
+ *
+ * Matches against the container's frozen inline-size. Phase 1 supports
+ * width-based conditions only.
+ */
+interface ContainerQueryBranch {
+  /** Match when container inline-size is at least this many cells. */
+  readonly minWidth?: number;
+  /** Match when container inline-size is at most this many cells. */
+  readonly maxWidth?: number;
+  /** Match when container inline-size equals this many cells. */
+  readonly width?: number;
+  /**
+   * Branch styles applied to descendants when this condition matches. Subset
+   * of `BoxProps` / `TextProps` style fields; full schema arrives with the
+   * matcher.
+   */
+  readonly apply: Record<string, unknown>;
+}
+/**
+ * Props for Text component.
+ */
+/**
+ * Flex item subset of FlexboxProps — the props that make sense on a leaf
+ * (Text). Box accepts the full FlexboxProps; Text only accepts the props
+ * that affect how it participates as a flex item (sizing, growth, shrink)
+ * — not props that affect how it lays out its non-existent children
+ * (flexDirection, justifyContent, alignItems, gap, ...).
+ *
+ * This is the canonical CSS escape hatch: instead of wrapping Text in a
+ * Box to apply `flexShrink={0}` or `minWidth={0}`, set them directly on
+ * the Text. See bead km-silvery.text-intrinsic-vs-render.
+ */
+interface TextFlexItemProps {
+  /** CSS `flex-grow` — proportion of free positive space along main axis. */
+  flexGrow?: number;
+  /** CSS `flex-shrink` — proportion of negative free space along main axis. */
+  flexShrink?: number;
+  /** CSS `flex-basis` — initial main-size before grow/shrink distribution. */
+  flexBasis?: number | string;
+  /** Cross-axis self-alignment override. */
+  alignSelf?: "auto" | "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+  /** CSS `min-width` — floor for shrink distribution. */
+  minWidth?: number | string;
+  /** CSS `min-height`. */
+  minHeight?: number | string;
+  /** CSS `max-width` — ceiling for grow distribution. */
+  maxWidth?: number | string;
+  /** CSS `max-height`. */
+  maxHeight?: number | string;
+}
+interface TextProps extends StyleProps, TextFlexItemProps, TestProps, MouseEventProps {
+  children?: React.ReactNode;
+  /**
+   * Wrap / truncate mode. Each value bundles the CSS-equivalent
+   * `white-space` + `overflow-wrap` + `text-overflow` axes into one
+   * named composite. See `vendor/silvery/docs/components/Text.md` for the
+   * full table.
+   *
+   * - `"wrap"` (default): word-aware multi-line wrap, soft-break separators
+   *   for path-style tokens, character wrap as last-resort fallback.
+   * - `"wrap-truncate"`: same as `"wrap"` but ellipsis-truncates the
+   *   offending line when an unbreakable atomic token would otherwise
+   *   character-wrap. CSS analogue
+   *   `overflow-wrap: break-word` + `text-overflow: ellipsis`.
+   * - `"truncate"` / `"truncate-end"` / `"truncate-start"` /
+   *   `"truncate-middle"`: single-line, ellipsis at the named position.
+   * - `"clip"`: single-line, hard clip without ellipsis.
+   * - `"hard"`: character-wrap regardless of word boundaries (Ink compat).
+   * - `"even"`: optimal Knuth-Plass wrapping (minimize raggedness).
+   * - `false`: no wrap / no clip (overflows container — avoid in bordered
+   *   cells).
+   */
+  wrap?: "wrap" | "wrap-truncate" | "hard" | "even" | "truncate" | "truncate-start" | "truncate-middle" | "truncate-end" | "clip" | boolean;
+  /** Internal transform function applied to each rendered line. Used by Transform component. */
+  internal_transform?: (line: string, index: number) => string;
+  /**
+   * Per-node background-conflict policy. Overrides the global / context
+   * `BgConflictMode` for the cells this Text node paints.
+   *
+   * Background conflicts (ANSI bg in text content layered over an silvery
+   * `backgroundColor`) normally `throw` — that strictness is the right
+   * safety net for an silvery app's own pipeline bugs. But a component
+   * mirroring arbitrary EXTERNAL ANSI (e.g. `<Terminal>` re-encoding a
+   * captured terminal grid, where chalk status bars are conflict-rich by
+   * nature) *expects* conflicts. Such a component sets `bgConflict="ignore"`
+   * on the `<Text>` rows it paints so the global throw stays a safety net
+   * everywhere else.
+   *
+   * - `"ignore"`: no detection for this node's cells.
+   * - `"warn"`: log a deduplicated warning instead of throwing.
+   * - `"throw"`: throw (the default behavior when unset).
+   *
+   * When unset, the pipeline falls back to the context mode, then the
+   * global mode (`SILVERY_BG_CONFLICT`, default `"throw"`).
+   */
+  bgConflict?: "ignore" | "warn" | "throw";
+}
+/**
+ * The core Silvery node - represents an element in the render tree.
+ *
+ * Each node has:
+ * - A Yoga node for layout calculation
+ * - Computed layout after Yoga runs
+ * - Subscribers that get notified when layout changes
+ * - Dirty flags for incremental updates
+ */
+interface AgNode {
+  /** Node type */
+  type: AgNodeType;
+  /** Props passed to this node */
+  props: BoxProps | TextProps | Record<string, unknown>;
+  /** Child nodes */
+  children: AgNode[];
+  /** Parent node (null for root) */
+  parent: AgNode | null;
+  /** The layout node for layout calculation (null for raw text nodes) */
+  layoutNode: LayoutNode | null;
+  /** Computed layout from previous render (for change detection) */
+  prevLayout: Rect | null;
+  /**
+   * Content-relative position (like CSS offsetTop/offsetLeft).
+   * Position within the scrollable content, ignoring scroll offsets.
+   * Set after layout phase.
+   */
+  boxRect: Rect | null;
+  /**
+   * Screen-relative position (like CSS getBoundingClientRect).
+   * Actual position on the terminal screen, accounting for scroll offsets.
+   * Set after screen rect phase.
+   *
+   * Note: For sticky children, this reflects the node's layout position
+   * adjusted for scroll offsets, NOT the actual render position. Use
+   * `screenRect` for the actual pixel position on screen.
+   */
+  scrollRect: Rect | null;
+  /** Previous screen rect (for change detection in notifyLayoutSubscribers) */
+  prevScrollRect: Rect | null;
+  /**
+   * Actual render position on the terminal screen.
+   * For non-sticky nodes, this equals `scrollRect`.
+   * For sticky nodes (position="sticky"), this accounts for sticky render
+   * offsets — the position where pixels are actually painted.
+   *
+   * Use this for hit testing, cursor positioning, and any feature that
+   * needs to know where a node visually appears on screen.
+   * Set after screen rect phase.
+   */
+  screenRect: Rect | null;
+  /** Previous render rect (for change detection) */
+  prevScreenRect: Rect | null;
+  /** Epoch when layout changed (position or size).
+   *  Set by propagateLayout in layout phase. Compared against renderEpoch by render phase.
+   *  This is the authoritative signal for "did layout change?" — unlike
+   *  !rectEqual(prevLayout, boxRect) which becomes stale when layout
+   *  phase skips (no dirty nodes).
+   *  Value: renderEpoch when dirty, INITIAL_EPOCH (-1) when clean. */
+  layoutChangedThisFrame: number;
+  /**
+   * Bit-packed dirty flags for the current epoch.
+   *
+   * Seven dirty flags packed into a single number:
+   *   bit 0 (CONTENT_BIT):        content changed (text content or content-affecting props)
+   *   bit 1 (STYLE_PROPS_BIT):    visual props changed (color, bg, border, etc.)
+   *   bit 2 (BG_BIT):             backgroundColor specifically changed
+   *   bit 3 (CHILDREN_BIT):       direct children added/removed/reordered
+   *   bit 4 (SUBTREE_BIT):        this node or any descendant has dirty content/layout
+   *   bit 5 (ABS_CHILD_BIT):      absolute child had structural changes
+   *   bit 6 (DESC_OVERFLOW_BIT):  descendant overflow changed
+   *
+   * Outlines do NOT get a dirty bit — the decoration phase redraws them
+   * every frame with per-cell snapshots (see pipeline/decoration-phase.ts).
+   *
+   * Check: `isDirty(node.dirtyBits, node.dirtyEpoch, BIT)`
+   * Set:   `node.dirtyBits = setDirtyBit(node.dirtyBits, node.dirtyEpoch, BIT); node.dirtyEpoch = getRenderEpoch()`
+   * Clear: `advanceRenderEpoch()` — all nodes instantly become clean
+   *
+   * NOTE: measure phase may clear CONTENT_BIT — STYLE_PROPS_BIT acts as the
+   * surviving witness for style changes. See render-phase.ts contentAreaAffected.
+   */
+  dirtyBits: number;
+  /**
+   * Epoch when dirtyBits was last written.
+   * When `dirtyEpoch !== renderEpoch`, all bits are stale (node is clean).
+   * Value: renderEpoch when any bit is dirty, INITIAL_EPOCH (-1) when clean.
+   */
+  dirtyEpoch: number;
+  /** Text content for text nodes */
+  textContent?: string;
+  /** True if this is a raw text node (created by createTextInstance) */
+  isRawText?: boolean;
+  /** True if this node is hidden (for Suspense support) */
+  hidden?: boolean;
+  /** Sticky children with computed render positions (for non-scroll containers).
+   *  When a parent has sticky children but is NOT a scroll container, this array
+   *  holds the computed render offsets. Same shape as scrollState.stickyChildren. */
+  stickyChildren?: Array<{
+    /** Index of the sticky child */index: number; /** Computed Y offset to render at (relative to parent content area) */
+    renderOffset: number; /** Original natural Y position (relative to parent content area) */
+    naturalTop: number; /** Height of the sticky element */
+    height: number;
+  }>;
+  /** Inline rects for virtual text nodes (no layout node). Computed during text rendering.
+   *  Array for wrapped text (one rect per line fragment). Enables hit testing on nested Text. */
+  inlineRects?: Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }> | null;
+  /**
+   * Render-phase flag: "did this Box have an attr overlay (underline /
+   * strikethrough / etc.) applied in the previous frame?" Written by the
+   * render phase after `applyBoxAttrOverlay`. Read next frame to decide
+   * whether `stylePropsDirty` on the Box must escalate to `contentAreaAffected`
+   * (so the prev-frame merge-attr bits can be cleared via re-render).
+   *
+   * `mergeAttrsInRect` OR-combines — it can't clear bits. So when a Box's
+   * attr overlay goes away (true → false, or style change), the clone buffer
+   * still carries the old attr bits. This flag lets us detect the "had overlay
+   * in prev frame" case without storing prev props.
+   *
+   * Only meaningful for silvery-box nodes. Defaults to undefined / false.
+   * @internal
+   */
+  hadBoxAttrOverlay?: boolean;
+  /**
+   * Interactive state signals — written by pointer/selection/focus state machines,
+   * read by theme/render for automatic styling (hover highlights, focus rings, etc.).
+   *
+   * Lazily created on first write. Null means no interactive state has been set.
+   * See InteractiveState for field docs.
+   */
+  interactiveState?: InteractiveState | null;
+  /**
+   * Viewport state for silvery-viewport nodes. Lazily created by the
+   * `<Viewport>` React component at mount; read by the pipeline render
+   * phase to blit the foreign cell buffer at the node's boxRect.
+   * See `viewport-types.ts` and bead `@km/silvery/15513`.
+   *
+   * Deprecated by `<Island>` / {@link islandState} in epic
+   * `@km/silvery/15646-islands`; Phase 4 deletes this slot.
+   */
+  viewportState?: ViewportNodeState | null;
+  /**
+   * Island state for silvery-island nodes. Lazily created by `createIsland()`
+   * / `<Island>` at mount; read by the pipeline render phase to blit the
+   * guest's cell buffer at the node's boxRect, and by the host aggregator
+   * (create-app.tsx) to derive focused-subtree protocol modes.
+   * See `island-types.ts` and bead `@km/silvery/15646-islands`.
+   */
+  islandState?: IslandNodeState | null;
+  /** Scroll state for overflow='scroll' containers */
+  scrollState?: {
+    /** Current scroll offset (in terminal rows) */offset: number; /** Previous scroll offset from last render (for incremental rendering) */
+    prevOffset: number;
+    /**
+     * The `scrollTo` prop value processed in the previous frame.
+     *
+     * Used to distinguish "new intent" (scrollTo changed — user pressed a key
+     * or an external setter moved the target) from "same intent" (scrollTo
+     * unchanged — this frame is just a re-render caused by content growth or
+     * style changes).
+     *
+     * Edge-based ensure-visible fires for NEW intent. Same intent skips
+     * re-anchoring when the target's top edge is still in the viewport —
+     * otherwise growing a visible item would shift the viewport down and
+     * push content above it out of view ("the whole page jumps on click").
+     */
+    prevScrollTo?: number; /** Total content height (all children) */
+    contentHeight: number; /** Visible height (container height minus borders/padding) */
+    viewportHeight: number; /** Index of first visible child */
+    firstVisibleChild: number; /** Index of last visible child */
+    lastVisibleChild: number; /** Previous first visible child from last render (for incremental rendering) */
+    prevFirstVisibleChild: number; /** Previous last visible child from last render (for incremental rendering) */
+    prevLastVisibleChild: number; /** Count of items hidden above viewport */
+    hiddenAbove: number; /** Count of items hidden below viewport */
+    hiddenBelow: number; /** Sticky children with their computed render positions */
+    stickyChildren?: Array<{
+      /** Index of the sticky child */index: number; /** Computed Y offset to render at (relative to viewport, not content) */
+      renderOffset: number; /** Original natural Y position (before sticky adjustment) */
+      naturalTop: number; /** Height of the sticky element */
+      height: number;
+    }>;
+  };
+}
+/**
+ * Text attributes that can be applied to a cell.
+ */
+interface CellAttrs$1 {
+  bold?: boolean;
+  dim?: boolean;
+  italic?: boolean;
+  /** Simple underline flag (for backwards compatibility) */
+  underline?: boolean;
+  /**
+   * Underline style: 'single' | 'double' | 'curly' | 'dotted' | 'dashed'.
+   * When set, takes precedence over the underline boolean.
+   */
+  underlineStyle?: UnderlineStyle$1;
+  strikethrough?: boolean;
+  inverse?: boolean;
+}
+/**
+ * A single cell in the terminal buffer.
+ */
+interface Cell$1 {
+  /** The character (grapheme cluster) in this cell */
+  char: string;
+  /** Foreground color (ANSI code or RGB) */
+  fg: string | null;
+  /** Background color (ANSI code or RGB) */
+  bg: string | null;
+  /** Text attributes */
+  attrs: CellAttrs$1;
+  /** True if this is a wide character (CJK) that takes 2 cells */
+  wide: boolean;
+  /** True if this cell is the continuation of a wide character */
+  continuation: boolean;
+}
+/**
+ * Keyboard event with key information and modifiers.
+ */
+interface KeyEvent$1 {
+  type: "key";
+  /** The key pressed (character or key name like 'ArrowUp') */
+  key: string;
+  /** Ctrl modifier was held */
+  ctrl?: boolean;
+  /** Meta/Alt modifier was held */
+  meta?: boolean;
+  /** Shift modifier was held */
+  shift?: boolean;
+  /** Alt/Option modifier was held */
+  alt?: boolean;
+  /** Super/Cmd modifier was held. Requires Kitty protocol. */
+  super?: boolean;
+  /** Hyper modifier was held. Requires Kitty protocol. */
+  hyper?: boolean;
+  /** Kitty event type. Requires Kitty flag 2. */
+  eventType?: "press" | "repeat" | "release";
+  /** CapsLock is active. Kitty modifier bit 6. */
+  capsLock?: boolean;
+  /** NumLock is active. Kitty modifier bit 7. */
+  numLock?: boolean;
+}
+/**
+ * Mouse event with position and button information.
+ */
+interface MouseEvent {
+  type: "mouse";
+  /** X position in terminal columns (0-indexed) */
+  x: number;
+  /** Y position in terminal rows (0-indexed) */
+  y: number;
+  /** Mouse button (0=left, 1=middle, 2=right) */
+  button: number;
+  /** Event action */
+  action: "down" | "up" | "move" | "wheel";
+  /** Wheel delta for scroll events */
+  delta?: number;
+}
+/**
+ * Terminal resize event.
+ */
+interface ResizeEvent {
+  type: "resize";
+  /** New width in columns */
+  width: number;
+  /** New height in rows */
+  height: number;
+}
+/**
+ * Terminal focus event.
+ */
+interface FocusEvent$1 {
+  type: "focus";
+}
+/**
+ * Terminal blur event.
+ */
+interface BlurEvent {
+  type: "blur";
+}
+/**
+ * Signal event (SIGINT, SIGTERM, etc.).
+ */
+interface SignalEvent {
+  type: "signal";
+  /** Signal name (e.g., 'SIGINT', 'SIGTERM') */
+  signal: string;
+}
+/**
+ * Custom event for extensibility.
+ */
+interface CustomEvent {
+  type: "custom";
+  /** Event name */
+  name: string;
+  /** Event data */
+  data: unknown;
+}
+/**
+ * Union of all event types.
+ *
+ * Events drive the render loop in interactive mode. When events are present,
+ * the render loop runs until exit() is called. When events are absent,
+ * the render completes when the UI is stable.
+ */
+type Event = KeyEvent$1 | MouseEvent | ResizeEvent | FocusEvent$1 | BlurEvent | SignalEvent | CustomEvent;
+/**
+ * Event source that can be subscribed to and unsubscribed from.
+ */
+interface EventSource {
+  /** Subscribe to events, returns unsubscribe function */
+  subscribe(handler: (event: Event) => void): () => void;
+  /** Convert to async iterable */
+  [Symbol.asyncIterator](): AsyncIterator<Event>;
+}
+//#endregion
+//#region packages/ag-term/src/mouse.d.ts
+/**
+ * SGR mouse event parsing (mode 1006) and SGR-Pixels parsing (mode 1016).
+ *
+ * SGR format: CSI < button;x;y M (press) or CSI < button;x;y m (release)
+ *
+ * Button encoding:
+ * - Bits 0-1: 0=left, 1=middle, 2=right, 3=release (X10 only, not SGR)
+ * - Bit 2 (+4): Shift held
+ * - Bit 3 (+8): Meta/Alt held
+ * - Bit 4 (+16): Ctrl held
+ * - Bit 5 (+32): Motion event (mouse moved while button held)
+ * - Bits 6-7: 64=wheel-up, 65=wheel-down, 66=wheel-left, 67=wheel-right
+ */
+/**
+ * Parsed mouse event from SGR mouse protocol.
+ */
+interface ParsedMouse {
+  /** Mouse button: 0=left, 1=middle, 2=right */
+  button: number;
+  /**
+   * Silvery layout X coordinate, in terminal cells.
+   * Integer in SGR 1006 mode; fractional when parsed from SGR-Pixels 1016.
+   */
+  x: number;
+  /**
+   * Silvery layout Y coordinate, in terminal cells.
+   * Integer in SGR 1006 mode; fractional when parsed from SGR-Pixels 1016.
+   */
+  y: number;
+  /** Physical pixel X coordinate, present only for SGR-Pixels 1016. */
+  clientX?: number;
+  /** Physical pixel Y coordinate, present only for SGR-Pixels 1016. */
+  clientY?: number;
+  /** Coordinate mode used by the parser. */
+  coordinateMode: "cell" | "pixel";
+  /** Event action */
+  action: "down" | "up" | "move" | "wheel";
+  /** Wheel delta: -1 for up, +1 for down */
+  delta?: number;
+  /** Shift was held */
+  shift: boolean;
+  /** Alt/Meta was held */
+  meta: boolean;
+  /** Ctrl was held */
+  ctrl: boolean;
+  /** Monotonic timestamp when the terminal input chunk was received. */
+  receivedAt?: number;
+  /** Monotonic id shared by events parsed from the same terminal input chunk. */
+  inputBatchId?: number;
+}
+interface ParseMouseOptions {
+  coordinateMode?: "cell" | "pixel";
+  cellSize?: {
+    width: number;
+    height: number;
+  };
+}
+/**
+ * Parse an SGR mouse sequence.
+ *
+ * Return semantics (see ProtocolError in @silvery/ansi for the full contract):
+ * - `null` — input does not match the SGR mouse shape `CSI < B;X;Y [Mm]`.
+ *   No "committed but malformed" branch exists here: either the full SGR
+ *   shape matches (parse succeeds) or it doesn't (null = next-parser-please).
+ *
+ * The bead 15127 audit listed this parser for review, but the regex-based
+ * shape match means there's no place where the parser commits to "this is
+ * a mouse event" and then fails on body validation — both happen at the
+ * same point. Loud-error tightening here would require a stricter
+ * sub-grammar (e.g. validating button-code ranges), tracked separately.
+ *
+ * @returns ParsedMouse or null if not a valid mouse sequence
+ */
+declare function parseMouseSequence(input: string, options?: ParseMouseOptions): ParsedMouse | null;
+/** Check if a raw input string is a mouse sequence */
+declare function isMouseSequence(input: string): boolean;
+//#endregion
+//#region packages/ag-term/src/ansi/types.d.ts
+/**
+ * Console method names that can be intercepted.
+ */
+type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug";
+/**
+ * Entry captured from console.
+ */
+interface ConsoleEntry {
+  method: ConsoleMethod;
+  args: unknown[];
+  stream: "stdout" | "stderr";
+}
+/**
+ * Options for createTerm().
+ */
+interface CreateTermOptions {
+  stdout?: NodeJS.WriteStream;
+  stdin?: NodeJS.ReadStream;
+  colorLevel?: ColorLevel | null;
+  unicode?: boolean;
+  cursor?: boolean;
+  caps?: Partial<TerminalCaps>;
+  /** Mouse parser options for terminal-backed input owners. */
+  mouse?: ParseMouseOptions;
+  /**
+   * Opt out of silvery's stdin ownership entirely.
+   *
+   * When `false`, `term.input` resolves to `undefined`. The lazy
+   * `InputOwner` is never constructed: raw mode is never flipped, no
+   * data listener is attached to stdin, and no probe writes touch
+   * stdin. The Term still owns stdout, modes, size, signals, and
+   * console — only stdin ownership is suppressed.
+   *
+   * Use case: a host process needs to pipe its own stdin to a child
+   * (e.g. a PTY for a recording overlay) while still using silvery to
+   * render visuals around the child's grid. Without this opt-out the
+   * host and silvery race for stdin and silvery's `setRawMode(true)`
+   * eats the child's keystrokes.
+   *
+   * Pair with `render(..., term, { input: false })` to mirror the
+   * opt-out at the render pipeline level — the runtime then skips the
+   * text-sizing + width-detection probes and never attaches its own
+   * stdin listener.
+   *
+   * Default: undefined (silvery owns stdin via the lazy InputOwner —
+   * the canonical contract). Only `false` is meaningful — `true` is the
+   * default and not a separate code path, so it is not accepted.
+   *
+   * See `docs/design/terminal-component.md` § "render({ input: false })"
+   * for the full rationale.
+   */
+  input?: false;
+  /**
+   * Trailing-edge debounce for stdout `resize` events, in ms.
+   *
+   * Real terminals fire SIGWINCH bursts (tmux/cmux/Ghostty multiplexer
+   * resizes can produce 4-6 events at ~80 ms intervals). The default
+   * (200 ms) coalesces these bursts to a single layout reflow.
+   *
+   * Test and emulator paths drive resize explicitly via `term.resize(...)`
+   * and don't experience SIGWINCH bursts — they want the resize signal to
+   * propagate immediately so layout reflows before the test's settle window
+   * expires. Pass `0` (or any value shorter than the test's settle) to opt
+   * out of debouncing.
+   *
+   * See `createSize` in `runtime/devices/size.ts` for the underlying contract.
+   */
+  resizeCoalesceMs?: number;
+}
+/**
+ * A screen region — duck-type matching termless RegionView.
+ * Provides text content, line access, and cell-level queries for assertions.
+ */
+interface TermScreen {
+  getText(): string;
+  getLines(): string[];
+  containsText?(text: string): boolean;
+  /** Cell-level access — row-first order. Returns resolved RGB colors.
+   *  Only available on emulator-backed terms (createTermless). */
+  cell?(row: number, col: number): {
+    readonly fg: unknown;
+    readonly bg: unknown;
+    readonly char: string;
+  };
+}
+/**
+ * A terminal emulator — duck-type matching termless Terminal.
+ * Accepts ANSI output, provides screen/scrollback for inspection.
+ */
+interface TermEmulator {
+  readonly cols: number;
+  readonly rows: number;
+  readonly screen: TermScreen;
+  readonly scrollback: TermScreen;
+  feed(data: Uint8Array | string): void;
+  resize(cols: number, rows: number): void;
+  close(): Promise<void>;
+}
+/**
+ * A terminal emulator backend — duck-type matching termless TerminalBackend.
+ * Raw backend that needs initialization. Pass to createTerm(backend, { cols, rows }).
+ *
+ * @example
+ * ```ts
+ * import { createXtermBackend } from "@termless/xtermjs"
+ * using term = createTerm(createXtermBackend(), { cols: 80, rows: 24 })
+ * ```
+ */
+interface TermEmulatorBackend {
+  readonly name: string;
+  init(opts: {
+    cols: number;
+    rows: number;
+    scrollbackLimit?: number;
+  }): void;
+  destroy(): void;
+  feed(data: Uint8Array): void;
+  resize(cols: number, rows: number): void;
+}
+//#endregion
+//#region packages/ag/src/text-frame.d.ts
+/**
+ * TextFrame — Unified interface for a rectangular area of styled terminal text.
+ *
+ * Used by App, RunHandle, term.screen, term.scrollback — one shape everywhere.
+ * Provides plain text, ANSI-styled text, per-line access, cell-level queries,
+ * and text search.
+ *
+ * @packageDocumentation
+ */
+/**
+ * RGB color value (0-255 per channel).
+ */
+interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+/**
+ * A single cell in a TextFrame with resolved styling.
+ *
+ * Colors are resolved to RGB (or null for default/inherit).
+ * Attributes are flattened booleans for easy testing.
+ */
+interface FrameCell {
+  /** The character/grapheme in this cell */
+  readonly char: string;
+  /** Resolved foreground color, or null for default */
+  readonly fg: RGB | null;
+  /** Resolved background color, or null for default */
+  readonly bg: RGB | null;
+  /** Bold attribute */
+  readonly bold: boolean;
+  /** Dim/faint attribute */
+  readonly dim: boolean;
+  /** Italic attribute */
+  readonly italic: boolean;
+  /** Underline style — false if none */
+  readonly underline: UnderlineStyle$1;
+  /** Underline color (independent of fg), or null to use fg */
+  readonly underlineColor: RGB | null;
+  /** Overline attribute — SGR 53. Independent of underline. */
+  readonly overline: boolean;
+  /** Strikethrough attribute */
+  readonly strikethrough: boolean;
+  /** Inverse/reverse video attribute */
+  readonly inverse: boolean;
+  /** Blink attribute */
+  readonly blink: boolean;
+  /** Hidden/invisible attribute */
+  readonly hidden: boolean;
+  /** True if this is a wide character (CJK, emoji) */
+  readonly wide: boolean;
+  /** True if this cell is the continuation of a wide character */
+  readonly continuation: boolean;
+  /** OSC 8 hyperlink URL, or null if none */
+  readonly hyperlink: string | null;
+}
+/**
+ * Unified interface for a rectangular area of styled terminal text.
+ *
+ * Implemented by App, RunHandle, and terminal views (screen, scrollback).
+ * Provides consistent access to text content, styling, and cell-level data.
+ */
+interface TextFrame {
+  /** Plain text content (no ANSI codes). Lines separated by newlines. */
+  readonly text: string;
+  /** Text with ANSI styling escape codes. */
+  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. */
+  cell(col: number, row: number): FrameCell;
+  /** Check whether the plain text contains the given substring. */
+  containsText(text: string): boolean;
+}
+//#endregion
+//#region packages/ag-term/src/buffer.d.ts
+/**
+ * Terminal buffer implementation for Silvery.
+ *
+ * Uses packed Uint32Array for efficient cell metadata storage,
+ * with separate string array for character storage (needed for
+ * multi-byte Unicode graphemes and combining characters).
+ */
+/**
+ * Underline style variants (SGR 4:x codes).
+ * - false: no underline
+ * - 'single': standard underline (SGR 4 or 4:1)
+ * - 'double': double underline (SGR 4:2)
+ * - 'curly': curly/wavy underline (SGR 4:3)
+ * - 'dotted': dotted underline (SGR 4:4)
+ * - 'dashed': dashed underline (SGR 4:5)
+ */
+type UnderlineStyle = false | "single" | "double" | "curly" | "dotted" | "dashed";
+/**
+ * Text attributes that can be applied to a cell.
+ */
+interface CellAttrs {
+  bold?: boolean;
+  dim?: boolean;
+  italic?: boolean;
+  /** Simple underline flag (for backwards compatibility) */
+  underline?: boolean;
+  /**
+   * Underline style: 'single' | 'double' | 'curly' | 'dotted' | 'dashed'.
+   * When set, takes precedence over the underline boolean.
+   */
+  underlineStyle?: UnderlineStyle;
+  /**
+   * Overline (SGR 53/55). A line ABOVE the character cell, independent of
+   * underline. Used for top-edge indicators where underline would read as
+   * "this row is underlined content" instead of "you're at the top".
+   */
+  overline?: boolean;
+  blink?: boolean;
+  inverse?: boolean;
+  hidden?: boolean;
+  strikethrough?: boolean;
+}
+/**
+ * Color representation.
+ * - number: 256-color index (0-255)
+ * - RGB object: true color
+ * - null: default/inherit
+ * - DEFAULT_BG: terminal's default background (SGR 49), opaque but uses terminal's own bg color
+ */
+type Color = number | {
+  r: number;
+  g: number;
+  b: number;
+} | null;
+/**
+ * A single cell in the terminal buffer.
+ */
+interface Cell {
+  /** The character/grapheme in this cell */
+  char: string;
+  /** Foreground color */
+  fg: Color;
+  /** Background color */
+  bg: Color;
+  /**
+   * Underline color (independent of fg).
+   * Uses SGR 58. If null, underline uses fg color.
+   */
+  underlineColor: Color;
+  /** Text attributes */
+  attrs: CellAttrs;
+  /** True if this is a wide character (CJK, emoji, etc.) */
+  wide: boolean;
+  /** True if this is the continuation cell after a wide character */
+  continuation: boolean;
+  /**
+   * OSC 8 hyperlink URL.
+   * When set, the cell is part of a clickable hyperlink in supporting terminals.
+   */
+  hyperlink?: string;
+}
+/**
+ * Partial cell update accepted by buffer write APIs.
+ *
+ * `selectable` is render metadata, not a visual cell property: it controls the
+ * SELECTABLE_FLAG bit used by app-level semantic text selection. It is carried
+ * on write payloads so selectability is explicit per mutation rather than an
+ * ambient buffer mode.
+ */
+type CellPatch = Partial<Cell> & {
+  selectable?: boolean;
+};
+/**
+ * Style information for a cell (excludes char and position flags).
+ */
+interface Style {
+  fg: Color;
+  bg: Color;
+  /**
+   * Underline color (independent of fg).
+   * Uses SGR 58. If null, underline uses fg color.
+   */
+  underlineColor?: Color;
+  attrs: CellAttrs;
+  /**
+   * OSC 8 hyperlink URL.
+   * When set, the cell is part of a clickable hyperlink in supporting terminals.
+   */
+  hyperlink?: string;
+}
+/**
+ * Per-row metadata for text extraction correctness.
+ * Maintained by the render phase during text rendering.
+ */
+interface RowMetadata {
+  /** True if this row continues on the next row (soft wrap, not hard break) */
+  softWrapped: boolean;
+  /** Rightmost column with non-space content (for trailing space trimming) */
+  lastContentCol: number;
+}
+/**
+ * Efficient terminal cell buffer.
+ *
+ * Uses packed Uint32Array for cell metadata and separate string array
+ * for characters. This allows efficient diffing while supporting
+ * full Unicode grapheme clusters.
+ */
+declare class TerminalBuffer {
+  /** Packed cell metadata */
+  private cells;
+  /** Character storage (one per cell, may be multi-byte grapheme) */
+  private chars;
+  /** True color foreground storage (only for cells with true color fg) */
+  private fgColors;
+  /** True color background storage (only for cells with true color bg) */
+  private bgColors;
+  /** Underline color storage (independent of fg, for SGR 58) */
+  private underlineColors;
+  /** OSC 8 hyperlink URL storage (only for cells that are part of a hyperlink) */
+  private hyperlinks;
+  /**
+   * Per-row dirty tracking for diff optimization.
+   * When set, diffBuffers() can skip clean rows entirely.
+   * 0 = clean (unchanged since last resetDirtyRows), 1 = dirty (modified).
+   */
+  private _dirtyRows;
+  /** Bounding box: first dirty row (inclusive). -1 when no rows are dirty. */
+  private _minDirtyRow;
+  /** Bounding box: last dirty row (inclusive). -1 when no rows are dirty. */
+  private _maxDirtyRow;
+  /**
+   * Per-row metadata for text extraction (soft wrap, last content column).
+   * Set by the render phase, read by extractText.
+   */
+  private _rowMetadata;
+  readonly width: number;
+  readonly height: number;
+  constructor(width: number, height: number);
+  /**
+   * Get the index for a cell position.
+   */
+  private index;
+  /**
+   * Check if coordinates are within bounds.
+   */
+  inBounds(x: number, y: number): boolean;
+  /**
+   * Get a cell at the given position.
+   */
+  getCell(x: number, y: number): Cell;
+  /**
+   * Count cells that are not default-empty.
+   *
+   * A cell is "painted" iff any of these differs from default-empty:
+   *   - char !== " "
+   *   - packed metadata is non-zero (any fg, bg, attr, wide/cont/truecolor flag)
+   *
+   * Used by the degenerate-frame canary in `render()` (renderer.ts) and by
+   * test helpers that want to assert a fixture renders meaningful content.
+   *
+   * O(W*H) — single pass over the packed Uint32Array + chars array.
+   */
+  countPaintedCells(): number;
+  /**
+   * Get just the character at a cell position (no object allocation).
+   * Returns " " for out-of-bounds positions.
+   */
+  getCellChar(x: number, y: number): string;
+  /**
+   * Get just the background color at a cell position (no object allocation).
+   * Returns null for out-of-bounds positions.
+   */
+  getCellBg(x: number, y: number): Color;
+  /**
+   * Get just the foreground color at a cell position (no object allocation).
+   * Returns null for out-of-bounds positions.
+   */
+  getCellFg(x: number, y: number): Color;
+  /**
+   * Get the raw packed metadata at a cell position (no unpackAttrs allocation).
+   * Returns 0 for out-of-bounds positions. The packed value contains color
+   * indices, attr bits, underline style, and flags in a single Uint32.
+   */
+  getCellAttrs(x: number, y: number): number;
+  /**
+   * Check if a cell is a wide character (no object allocation).
+   * Returns false for out-of-bounds positions.
+   */
+  isCellWide(x: number, y: number): boolean;
+  /**
+   * Check if a cell is a continuation of a wide character (no object allocation).
+   * Returns false for out-of-bounds positions.
+   */
+  isCellContinuation(x: number, y: number): boolean;
+  /**
+   * Check if a cell is selectable (SELECTABLE_FLAG is set, no object allocation).
+   * Returns false for out-of-bounds positions.
+   */
+  isCellSelectable(x: number, y: number): boolean;
+  /**
+   * Set metadata for a row (soft wrap, last content column).
+   * Called by the render phase during text rendering.
+   */
+  setRowMeta(row: number, meta: Partial<RowMetadata>): void;
+  /**
+   * Get metadata for a row. Returns default values for out-of-bounds rows.
+   */
+  getRowMeta(row: number): RowMetadata;
+  /**
+   * Get the full row metadata array (for bulk access during text extraction).
+   */
+  getRowMetadataArray(): readonly RowMetadata[];
+  /**
+   * Read cell data into a caller-provided Cell object (zero-allocation).
+   * For hot loops that need the full Cell, reuse a single object:
+   *
+   *   const cell = createMutableCell()
+   *   for (...) { buffer.readCellInto(x, y, cell) }
+   *
+   * Returns the same `out` object for chaining convenience.
+   */
+  readCellInto(x: number, y: number, out: Cell): Cell;
+  /**
+   * Set a cell at the given position.
+   *
+   * Optimized: resolves defaults and packs metadata inline to avoid
+   * allocating an intermediate Cell object.
+   */
+  setCell(x: number, y: number, cell: CellPatch): void;
+  /**
+   * Fill a region with a cell.
+   *
+   * Optimized: packs cell metadata once and assigns directly to arrays,
+   * avoiding O(width*height) intermediate object allocations from setCell().
+   */
+  fill(x: number, y: number, width: number, height: number, cell: CellPatch): void;
+  /**
+   * Restyle a rectangular region — update fg, bg, and attrs on existing cells
+   * without changing character content (char, wide, continuation, hyperlink).
+   *
+   * This is the style-only fast path: when only visual props changed (color,
+   * bold, dim, inverse, etc.) but text content and layout are identical, we
+   * can skip text collection/formatting and just update the style metadata.
+   *
+   * @param x      Left column (inclusive)
+   * @param y      Top row (inclusive)
+   * @param width  Region width
+   * @param height Region height
+   * @param style  New style to apply (fg, bg, attrs, underlineColor)
+   */
+  restyleRegion(x: number, y: number, width: number, height: number, style: Style): void;
+  /**
+   * Fill only the background color of a region — update bg on existing cells
+   * without changing character content, foreground, or attributes.
+   *
+   * Unlike fill() which writes space characters, this preserves existing chars.
+   * Used by the style-only fast path: when a Box's backgroundColor changes but
+   * children are unchanged, fillBg() paints the new bg without destroying child
+   * chars. Clean children can then be skipped (their chars are correct from the
+   * clone, their bg was updated by fillBg).
+   *
+   * @param x      Left column (inclusive)
+   * @param y      Top row (inclusive)
+   * @param width  Region width
+   * @param height Region height
+   * @param bg     New background color
+   */
+  fillBg(x: number, y: number, width: number, height: number, bg: Color): void;
+  /**
+   * OR-combine SGR attribute bits into every cell in a rectangular region —
+   * WITHOUT modifying glyphs, fg, bg, wide flags, selectable flag, or any
+   * other per-cell state.
+   *
+   * This is the transparent-overlay primitive. It lets a Box (or any caller)
+   * layer an underline / strikethrough / bold / etc. onto existing content
+   * without overwriting what's underneath.
+   *
+   * Semantics:
+   * - `attrs.underlineStyle` (or `attrs.underline: true` via attrsToNumber)
+   *   REPLACES any existing underline style on each cell — 3-bit field, one
+   *   value wins. This matches CSS `text-decoration` overlay semantics where
+   *   a decoration container sets the decoration.
+   * - All other attr bits (bold/dim/italic/blink/inverse/hidden/strikethrough)
+   *   OR-in — existing attrs are preserved, new attrs add to them.
+   * - `underlineColor` is applied only when explicitly provided; otherwise
+   *   each cell keeps its existing underline color.
+   *
+   * Use cases:
+   * - Overscroll indicator: `<Box underline="single" position="absolute" />`
+   *   overlays an underline on the last row without touching the text.
+   * - Error squiggly across a paragraph: `<Box underline="curly">`.
+   * - Heading visual emphasis: `<Box underline="double">`.
+   *
+   * @param x      Left column (inclusive)
+   * @param y      Top row (inclusive)
+   * @param width  Region width
+   * @param height Region height
+   * @param attrs  Attributes to merge onto every cell
+   * @param underlineColor Optional underline color — when provided, replaces the
+   *   existing underlineColor on each cell. `null` clears it. `undefined`
+   *   leaves it untouched.
+   */
+  mergeAttrsInRect(x: number, y: number, width: number, height: number, attrs: CellAttrs, underlineColor?: Color): void;
+  /**
+   * Clear the buffer (fill with empty cells).
+   */
+  clear(): void;
+  /**
+   * Copy a region from another buffer.
+   */
+  copyFrom(source: TerminalBuffer, srcX: number, srcY: number, destX: number, destY: number, width: number, height: number): void;
+  /**
+   * Shift content within a rectangular region vertically by `delta` rows.
+   * Positive delta = shift content UP (scroll down), negative = shift DOWN (scroll up).
+   * Exposed rows (at the bottom for positive delta, top for negative) are filled
+   * with the given background cell.
+   *
+   * Uses Uint32Array.copyWithin for the packed cells (native memcpy) and
+   * Array splice for the character array.
+   */
+  scrollRegion(x: number, y: number, regionWidth: number, regionHeight: number, delta: number, clearCell?: CellPatch): void;
+  /**
+   * Clone this buffer.
+   */
+  clone(): TerminalBuffer;
+  /**
+   * Check if a row has been modified since the last resetDirtyRows() call.
+   * Used by diffBuffers() to skip unchanged rows.
+   */
+  isRowDirty(y: number): boolean;
+  /** First dirty row (inclusive), or -1 if no rows are dirty. */
+  get minDirtyRow(): number;
+  /** Last dirty row (inclusive), or -1 if no rows are dirty. */
+  get maxDirtyRow(): number;
+  /**
+   * Reset all dirty row flags to clean.
+   * Call after diffing to prepare for the next frame's modifications.
+   */
+  resetDirtyRows(): void;
+  /**
+   * Mark all rows as dirty.
+   * Used when the buffer's dirty rows may not cover all changes relative
+   * to a different prev buffer (e.g., after multiple doRender calls where
+   * the runtime's prevBuffer skipped intermediate buffers).
+   */
+  markAllRowsDirty(): void;
+  /**
+   * Check if two cells at given positions are equal.
+   * Used for diffing.
+   */
+  cellEquals(x: number, y: number, other: TerminalBuffer): boolean;
+  /**
+   * Fast check: are all packed metadata values identical for a row?
+   * This is a bulk pre-check before per-cell comparison. If metadata differs,
+   * we still need per-cell diffing. If metadata matches, we only need to
+   * check chars, true color maps, underline colors, and hyperlinks.
+   * Returns true if all packed 32-bit values in the row are identical.
+   */
+  rowMetadataEquals(y: number, other: TerminalBuffer): boolean;
+  /**
+   * Fast check: are all characters identical for a row?
+   * Companion to rowMetadataEquals for a two-phase row comparison.
+   */
+  rowCharsEquals(y: number, other: TerminalBuffer): boolean;
+  /**
+   * Check Map-based extras for a row: true color fg/bg, underline colors, hyperlinks.
+   * Must be called AFTER rowMetadataEquals confirms packed metadata matches.
+   * Only checks cells that have true color flags set (the Maps are only populated
+   * for those cells). Also checks underline colors and hyperlinks for all cells.
+   */
+  rowExtrasEquals(y: number, other: TerminalBuffer): boolean;
+}
+//#endregion
+//#region packages/signals/src/index.d.ts
+/**
+ * A reactive value — callable getter/setter.
+ *
+ * - `sig()` reads the current value (and subscribes the active effect/computed).
+ * - `sig(next)` writes a new value; subscribers re-run only if `next !== current`.
+ *
+ * Matches the return shape of `signal<T>(initial)` from alien-signals, so any
+ * `signal()` result is assignable to `Signal<T>`.
+ */
+type Signal<T> = {
+  (): T;
+  (value: T): void;
+};
+/**
+ * A read-only reactive value — callable getter that subscribes the active
+ * effect/computed but cannot be written to. Matches the return shape of
+ * `computed<T>(fn)` from alien-signals.
+ */
+type ReadSignal<T> = () => T;
+//#endregion
+//#region packages/ag-term/src/runtime/devices/modes.d.ts
+/**
+ * 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;
+};
+/**
+ * Mode names that can be passed to `modes.enable(...)`. These cover every
+ * toggleable mode on the `Modes` owner. `kittyKeyboard` accepts a bitfield
+ * rather than `true` and is handled via the per-mode signal directly (see
+ * the `kittyKeyboard` signal below) — it's intentionally excluded from
+ * `enable()` because the "on" value is not a single fixed boolean.
+ */
+type ModeName = "rawMode" | "altScreen" | "bracketedPaste" | "mouse" | "focusReporting";
+type MouseTrackingMode = boolean | "pixel";
+/**
+ * Terminal protocol modes sub-owner.
+ *
+ * Each property is a callable alien-signals `Signal`:
+ * - read:      `modes.altScreen()` → `boolean`
+ * - write:     `modes.altScreen(true)` — internal effect emits ANSI on change
+ * - subscribe: `effect(() => modes.altScreen())`
+ *
+ * `dispose()` writes `false` to every signal that was ever activated, which
+ * drives the same effects to emit the disable ANSI. Mode signals that were
+ * never touched stay `false` — no ANSI is emitted for them, matching the
+ * shared-stdin safety contract.
+ *
+ * For scope-style ownership (`scope.use(modes.enable("altScreen"))`), use
+ * `enable()` — it returns a `Disposable` that restores the mode to whatever
+ * it was before the call, independent of the owner's full `dispose()`.
+ */
+interface Modes extends Disposable {
+  /**
+   * stdin raw mode.
+   *
+   * wasRaw note: prefer a single `modes.rawMode(true)` at session start; do
+   * not capture-and-restore around async work. See
+   * `vendor/silvery/CLAUDE.md` "Anti-pattern: wasRaw".
+   */
+  readonly rawMode: Signal<boolean>;
+  /** Alternate screen buffer (DEC 1049). */
+  readonly altScreen: Signal<boolean>;
+  /** Bracketed paste (DEC 2004). */
+  readonly bracketedPaste: Signal<boolean>;
+  /**
+   * Kitty keyboard protocol flags. Bitfield (see `KittyFlags`) to enable,
+   * `false` to disable. A change from one non-false bitfield to another
+   * emits a fresh `CSI > flags u` write.
+   */
+  readonly kittyKeyboard: Signal<number | false>;
+  /** SGR mouse tracking (xterm modes 1003 + 1006, or 1003 + 1006 + 1016). */
+  readonly mouse: Signal<MouseTrackingMode>;
+  /** Focus-in / focus-out reporting (DEC 1004). */
+  readonly focusReporting: Signal<boolean>;
+  /**
+   * Enable a mode and return a `Disposable` that restores the mode to its
+   * prior value on disposal. Complements the per-mode signals for callers
+   * that want scope-style ownership:
+   *
+   * ```ts
+   * scope.use(term.modes.enable("altScreen"))
+   * // …later, when the scope disposes, altScreen flips back to its
+   * // pre-enable value.
+   * ```
+   *
+   * Idempotent across repeated `enable(name)` calls (alien-signals equality
+   * short-circuits same-value writes). Disposing the returned handle twice
+   * is a no-op. The kitty keyboard bitfield is intentionally not covered —
+   * write `modes.kittyKeyboard(flags)` directly for that shape.
+   */
+  enable(name: ModeName): Disposable;
+}
+/**
+ * Options for `createModes()`.
+ *
+ * The owner needs:
+ * - a write function for ANSI sequences (routes through Output if activated,
+ *   else bare `stdout.write`)
+ * - the stdin stream (for `rawMode` — termios toggle, not ANSI)
+ */
+interface CreateModesOptions {
+  /** Write raw ANSI bytes to stdout. */
+  write: (data: string) => void;
+  /** stdin stream — used only for raw-mode termios toggles. */
+  stdin: NodeJS.ReadStream;
+}
+/**
+ * Create a `Modes` sub-owner. Does not emit any ANSI at construction — all
+ * sequences are written lazily on the first change to a mode signal.
+ */
+declare function createModes(opts: CreateModesOptions): Modes;
+//#endregion
+//#region packages/ag-term/src/runtime/input-owner.d.ts
+/** Structured key event — input string + parsed Key metadata. */
+interface KeyEvent {
+  input: string;
+  key: Key;
+}
+/** Structured paste event — the text that was pasted (without markers). */
+interface PasteEvent {
+  text: string;
+}
+/** Structured focus event — whether the terminal gained or lost focus. */
+interface FocusEvent {
+  focused: boolean;
+}
+interface InputOwner extends Disposable {
+  /**
+   * Write a query to stdout, accumulate stdin response bytes, run `parse`
+   * against the accumulated buffer on each chunk. Resolves with the first
+   * non-null parse result; resolves with `null` if `timeoutMs` elapses first.
+   *
+   * Consumed bytes (`consumed` from the parse result) are spliced out of the
+   * shared buffer. Bytes before/after the consumed region remain available
+   * to subsequent probes and/or the event parser.
+   */
+  probe<T>(opts: {
+    /** Bytes to write to stdout. May be "" for pure-listen probes. */query: string;
+    /**
+     * Run on the accumulated buffer each time new bytes arrive.
+     * Return `null` when the buffer doesn't contain a parseable response yet;
+     * return `{ result, consumed }` to resolve the probe with `result` and
+     * splice `consumed` bytes out of the buffer.
+     *
+     * NOTE: `consumed` need not equal the full buffer length; probes may
+     * consume a prefix or a middle slice. The owner splices the FIRST
+     * `consumed` bytes from the buffer — parsers that match a non-prefix
+     * region should locate + return the exact consumed prefix length.
+     */
+    parse: (acc: string) => {
+      result: T;
+      consumed: number;
+    } | null; /** Maximum wait in ms before resolving with `null`. */
+    timeoutMs: number;
+  }): Promise<T | null>;
+  /**
+   * Subscribe to parsed key events (press, repeat, release — handler filters
+   * as needed). Returns an unsubscribe function.
+   */
+  onKey(handler: (event: KeyEvent) => void): () => void;
+  /**
+   * Subscribe to parsed mouse events (SGR-encoded button + motion). Returns
+   * an unsubscribe function.
+   */
+  onMouse(handler: (event: ParsedMouse) => void): () => void;
+  /**
+   * Subscribe to bracketed-paste events. The `text` field holds the pasted
+   * content with markers stripped. Returns an unsubscribe function.
+   */
+  onPaste(handler: (event: PasteEvent) => void): () => void;
+  /**
+   * Subscribe to focus-in / focus-out events (CSI I / CSI O). Returns an
+   * unsubscribe function.
+   */
+  onFocus(handler: (event: FocusEvent) => void): () => void;
+  /**
+   * Inject a synthetic key event. Used by emulator-backed terms
+   * (`createTerm({ cols, rows, emulator })`) and test helpers to fan out to
+   * the same subscribers as real stdin parsing would.
+   */
+  sendKey(event: KeyEvent): void;
+  /**
+   * Inject a synthetic mouse event (same rationale as sendKey).
+   */
+  sendMouse(event: ParsedMouse): void;
+  /**
+   * Inject a synthetic paste event (same rationale as sendKey).
+   */
+  sendPaste(event: PasteEvent): void;
+  /**
+   * Inject a synthetic focus event (same rationale as sendKey).
+   */
+  sendFocus(event: FocusEvent): void;
+  /** True once construction succeeded and dispose() hasn't run. */
+  readonly active: boolean;
+  /** Number of probes successfully resolved (result, not null) since activation. */
+  readonly resolvedCount: number;
+  /** Number of probes that timed out since activation. */
+  readonly timedOutCount: number;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+interface InputOwnerOptions {
+  /**
+   * Alternate writer for outgoing query bytes (e.g. `output.write`). Defaults
+   * to `stdout.write.bind(stdout)`.
+   */
+  writeStdout?: (data: string) => boolean | void;
+  /**
+   * When true, `dispose()` does NOT drop raw mode. The listener is still
+   * removed and pending probes still resolve with null, but raw mode stays
+   * set so the next owner (typically the term-provider's events() generator)
+   * can take over seamlessly.
+   *
+   * Use this when the owner is the pre-session probe window AND a follow-up
+   * stdin consumer will re-set raw=true immediately.
+   */
+  retainRawModeOnDispose?: boolean;
+  /**
+   * Shared Modes owner (from Term). When provided, the input owner drives
+   * `stdin.setRawMode` + bracketed paste through `modes.rawMode(true/false)`
+   * + `modes.bracketedPaste(true/false)` so there is exactly one writer.
+   * Fallback to direct stdin calls + no bracketed-paste toggle when absent
+   * keeps the standalone/tests path working without a full Term.
+   */
+  modes?: Modes;
+  /**
+   * Enable bracketed paste at construction. Defaults to true when `modes`
+   * is provided and the owner is TTY-backed. Set to false for unit tests
+   * that don't want any protocol bytes written to stdout.
+   */
+  enableBracketedPaste?: boolean;
+  /**
+   * Mouse coordinate parser options. Use this when the terminal has been put
+   * into SGR-Pixels mode 1016 and cell metrics are known.
+   */
+  mouse?: ParseMouseOptions;
+}
+declare function createInputOwner(stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream, options?: InputOwnerOptions): InputOwner;
+//#endregion
+//#region packages/ag-term/src/runtime/devices/console-router.d.ts
+/** Shape a tap handler receives on every console.* call. */
+interface ConsoleCall {
+  method: ConsoleMethod;
+  args: unknown[];
+}
+/** Sink policy registered by a consumer (e.g. Output's alt-screen guard). */
+interface ConsoleSinkPolicy {
+  /**
+   * If true, the call is dropped (no forward to original, no redirect).
+   * Default: false.
+   */
+  suppress?: boolean;
+  /**
+   * If set, a single-line formatted copy of the call is written via
+   * `fs.writeSync(redirectFd, …)`. Typical use: redirect console.* to
+   * DEBUG_LOG during alt-screen. Mutually exclusive with `suppress: true`
+   * at the semantic level (if both are set, `suppress` wins).
+   */
+  redirectFd?: number | null;
+}
+/**
+ * Public shape of a ConsoleRouter.
+ */
+interface ConsoleRouter extends Disposable {
+  /**
+   * Register a tap: called on every console.* call in registration order,
+   * before sink policy. Tap handlers are pure observers. Returns an
+   * unregister function.
+   */
+  registerTap(handler: (call: ConsoleCall) => void): () => void;
+  /**
+   * Register a sink policy. The most recently registered sink is the
+   * active one (stack semantics). Unregister pops the stack back to the
+   * prior sink. Returns an unregister function.
+   */
+  registerSink(policy: ConsoleSinkPolicy): () => void;
+  /** True while at least one tap OR sink is registered (i.e. wrappers installed). */
+  readonly active: boolean;
+  /** Dispose — restore originals, clear taps + sinks. Idempotent. */
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region packages/ag-term/src/runtime/devices/output.d.ts
+interface Output extends Disposable {
+  /** Write data to stdout. When active, bypasses the intercept (silvery's render
+   * pipeline writes go through here). When inactive, forwards to the raw
+   * stdout.write. */
+  write(data: string | Uint8Array): boolean;
+  /**
+   * Whether intercepts are currently installed — a `ReadSignal<boolean>`.
+   * Call `output.active()` to read; subscribe with
+   * `effect(() => output.active())`. The owner writes it internally from
+   * `activate()` / `deactivate()`.
+   */
+  readonly active: ReadSignal<boolean>;
+  /** Activate intercepts: installs stdout/stderr/console patches. Idempotent —
+   * no-op if already active. Options override those passed at construction. */
+  activate(options?: OutputOptions): void;
+  /** Deactivate intercepts: restores original stdout/stderr/console methods.
+   * Idempotent. Closes stderr log fd if open. */
+  deactivate(): void;
+  /** Number of stdout writes suppressed since construction (cumulative across
+   * activate/deactivate cycles). Plain getter — changes on every write, not
+   * worth the reactive cost. */
+  readonly suppressedCount: number;
+  /** Number of stderr writes redirected since construction (cumulative across
+   * activate/deactivate cycles). Plain getter — changes on every write. */
+  readonly redirectedCount: number;
+  /** Final cleanup: deactivates + any teardown. Idempotent. */
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+interface OutputOptions {
+  /** File path to redirect stderr to (default: process.env.DEBUG_LOG) */
+  stderrLog?: string;
+  /** If true, buffer stderr and flush on deactivate instead of redirecting to file */
+  bufferStderr?: boolean;
+}
+//#endregion
+//#region packages/ag-term/src/runtime/devices/size.d.ts
+/** Snapshot of terminal dimensions. */
+interface SizeSnapshot {
+  readonly cols: number;
+  readonly rows: number;
+}
+/**
+ * Terminal size sub-owner.
+ *
+ * `cols`, `rows`, and `snapshot` are alien-signals `ReadSignal`s — call them
+ * as functions to read the current value and, inside an `effect`, to
+ * subscribe to changes. The first read (inside or outside an effect)
+ * installs the lazy `stdout.on("resize")` listener.
+ *
+ * ```ts
+ * // Read once
+ * const { cols, rows } = term.size.snapshot()
+ *
+ * // Subscribe to changes
+ * effect(() => {
+ *   layout(term.size.cols(), term.size.rows())  // re-runs on every resize
+ * })
+ *
+ * // React
+ * const cols = useSignal(term.size.cols)
+ * ```
+ */
+interface Size extends Disposable {
+  /** Current terminal width in columns. */
+  readonly cols: ReadSignal<number>;
+  /** Current terminal height in rows. */
+  readonly rows: ReadSignal<number>;
+  /** Current dimensions as a plain snapshot. */
+  readonly snapshot: ReadSignal<SizeSnapshot>;
+}
+//#endregion
+//#region packages/ag-term/src/runtime/devices/signals.d.ts
+/**
+ * term.signals — single SignalScope per Term lifetime with topologically-ordered
+ * teardown.
+ *
+ * ## Why
+ *
+ * The 2026-04-22 shared-global audit found 78 `process.on("SIGINT" | "SIGTERM" |
+ * "SIGTSTP" | "SIGWINCH" | "exit" | "beforeExit" | …)` registrations across km
+ * + silvery with no documented cleanup order. Handlers fire in registration
+ * order. If an earlier handler crashes, the Node.js default behaviour may skip
+ * later handlers or the process may exit before their cleanup runs — the same
+ * class of resource-leak race that the `wasRaw` finding exposed for raw mode.
+ *
+ * Signals is the same META-fix as Output / Modes / Input: one owner per Term
+ * mediates every registration for a given signal. On dispose (or on signal
+ * delivery) handlers fire in priority / dependency order, each wrapped in
+ * try/catch so a single failing handler doesn't block the rest.
+ *
+ * ## API shape
+ *
+ *   const unregister = term.signals.on("SIGINT", () => closeDb(), {
+ *     priority: 10,             // lower = runs first
+ *     before: ["flush-logs"],   // or explicit dep graph
+ *     after: ["save-state"],
+ *     name: "close-db",         // optional handle for before/after
+ *   })
+ *   term.signals.dispose()       // cascades from term.dispose()
+ *
+ * `priority` is a simple sort key (number, default 0). `before` / `after`
+ * reference handler `name`s. `dispose()` runs every registered handler in
+ * topological order, catches errors, and is idempotent.
+ *
+ * The return value of `on()` is both callable (`unregister()`) and
+ * `Disposable` (`using sub = term.signals.on(...)` and
+ * `scope.use(term.signals.on(...))`). All three forms unregister the handler
+ * without firing it.
+ *
+ * ## Not covered by this owner
+ *
+ * - `apps/km-tui/src/state/raw-signals.ts::restoreTerminal` stays as the
+ *   emergency last-ditch crash handler (runs on `uncaughtException`). It
+ *   must run even if the Term (and its Signals) has already been disposed.
+ *
+ * Bead: km-silvery.term-sub-owners (Phase 6).
+ */
+/** Process signal / lifecycle event the owner understands. */
+type SignalName = NodeJS.Signals | "exit" | "beforeExit" | "uncaughtException" | "unhandledRejection";
+/** Options per registration. */
+interface SignalOnOptions {
+  /**
+   * Sort key — lower runs first on dispose / signal delivery. Default 0.
+   *
+   * Rule of thumb:
+   *  - 0–9:   app-level cleanup (close DB, cancel pending work)
+   *  - 10–19: runtime cleanup (stop schedulers, drain queues)
+   *  - 20–29: terminal cleanup (restore modes, leave alt screen)
+   *  - 30+:   emergency / last-ditch
+   *
+   * `before` / `after` take precedence — priority is only a tiebreaker.
+   */
+  priority?: number;
+  /**
+   * Handler name — required if you want `before`/`after` to reference this
+   * handler. If omitted, a unique id is generated.
+   */
+  name?: string;
+  /** Handler names that must run AFTER this one. */
+  before?: string[];
+  /** Handler names that must run BEFORE this one. */
+  after?: string[];
+  /**
+   * If `true`, the handler also runs on `dispose()` (before any process-level
+   * signal handler is detached). Default: true — dispose is the primary
+   * teardown path.
+   */
+  onDispose?: boolean;
+  /**
+   * If `true`, the handler runs when the named signal is delivered to the
+   * process (via `process.on(signal, …)`). Default: true.
+   */
+  onSignal?: boolean;
+}
+/**
+ * Unregister function returned by `signals.on(...)`. Callable as a plain
+ * function (backward-compat: `unregister()`) and also implements both
+ * `Symbol.dispose` and `Symbol.asyncDispose` so it works with sync `using`,
+ * async `await using`, and `Scope` (which is `AsyncDisposableStack`-based
+ * and only accepts values with `Symbol.asyncDispose`). All three forms
+ * remove the handler from the owner's registry without firing it.
+ */
+type SignalUnregister = (() => void) & Disposable & AsyncDisposable;
+/**
+ * Signals sub-owner.
+ *
+ * One per Term. Mediates every `process.on(signalName, …)` registration for
+ * the Term's lifetime, running handlers in priority/dependency order on
+ * signal delivery or on `dispose()`.
+ */
+interface Signals extends Disposable {
+  /**
+   * Register a handler for a process signal or lifecycle event. Returns a
+   * `SignalUnregister` — a callable `Disposable`. Either `unregister()` or
+   * `unregister[Symbol.dispose]()` (implicitly via `using` / `scope.use`)
+   * removes the handler from this owner's registry (does not fire the handler).
+   *
+   * The first registration for a given signal installs a shared
+   * `process.on(signal, …)` listener; subsequent registrations reuse it.
+   * `dispose()` removes the shared listener.
+   */
+  on(signal: SignalName, handler: () => void | Promise<void>, opts?: SignalOnOptions): SignalUnregister;
+  /**
+   * Synchronous teardown. Runs every registered handler (with `onDispose:
+   * true`, the default) in priority/dependency order, catching errors so one
+   * failing handler can't block the rest. Idempotent.
+   *
+   * Handlers that return Promises are awaited best-effort via a microtask —
+   * but `dispose()` itself is synchronous because it runs under `using` /
+   * Symbol.dispose semantics, and on signal delivery the process may exit
+   * before any async work resolves.
+   */
+  dispose(): void;
+  /** True after `dispose()` / `Symbol.dispose` has run. */
+  readonly isDisposed: boolean;
+  /** Number of live registrations across all signals. */
+  readonly size: number;
+}
+/**
+ * Options for `createSignals`.
+ */
+interface CreateSignalsOptions {
+  /**
+   * Override the process-level event source. Tests pass a fake `process`
+   * to drive signal delivery without touching real signals.
+   * Defaults to Node's `process` global.
+   */
+  process?: NodeJS.Process;
+  /**
+   * Error hook — called for every handler that throws. Default: swallow.
+   * Tests use this to assert isolation semantics.
+   */
+  onError?: (error: unknown, entry: {
+    name: string;
+    signal: SignalName;
+  }) => void;
+}
+/**
+ * Create a `Signals` sub-owner. Installs no process-level listeners until the
+ * first `on()` call; removes them on `dispose()`.
+ */
+declare function createSignals(opts?: CreateSignalsOptions): Signals;
+//#endregion
+//#region packages/ag-term/src/runtime/devices/console.d.ts
+/**
+ * Aggregate counts of captured console output by severity.
+ */
+interface ConsoleStats {
+  total: number;
+  errors: number;
+  warnings: number;
+}
+/**
+ * Options for `console.capture()`.
+ */
+interface ConsoleCaptureOptions {
+  /**
+   * Suppress forwarding to the original console methods.
+   * Use in TUI / alt-screen mode where the raw output would corrupt the display.
+   * Default: false.
+   */
+  suppress?: boolean;
+  /**
+   * Store full entries in memory (default: true).
+   * Set false for count-only mode — `getSnapshot()` returns empty, but
+   * `getStats()` still tracks counts. Avoids unbounded memory growth for
+   * long-running sessions where you only care about warning/error badges.
+   */
+  capture?: boolean;
+}
+/**
+ * Console — single-owner console.* capture + replay for a silvery session.
+ *
+ * Constructed lazily by `createTerm()` (no patching until `capture()`).
+ * `subscribe` + `getSnapshot` are shaped for React's `useSyncExternalStore` —
+ * each change produces a new array reference.
+ */
+interface Console extends Disposable {
+  /**
+   * Start patching `console.log/info/warn/error/debug`. Idempotent — calling
+   * while already capturing is a no-op (options are ignored on re-entry;
+   * `restore()` then `capture()` again to change behaviour).
+   */
+  capture(options?: ConsoleCaptureOptions): void;
+  /**
+   * Restore original console methods. Idempotent. Subscribers survive; you can
+   * `capture()` again without re-subscribing. `dispose()` is the terminal
+   * variant that also clears subscribers.
+   */
+  restore(): void;
+  /**
+   * Whether `capture()` is currently active — a `ReadSignal<boolean>`.
+   * Call `console.capturing()` to read; subscribe via
+   * `effect(() => console.capturing())`. The owner writes it internally from
+   * `capture()` / `restore()`.
+   */
+  readonly capturing: ReadSignal<boolean>;
+  /**
+   * Notification signal — increments by 1 per captured entry (stats.total).
+   * Cheap: no array copy, no object allocation. Consumers subscribe via
+   * `effect(() => console.count())` and pull the full list lazily (via
+   * `entriesSnapshot()`) only when they need it — typically on a debounce
+   * flush in a React hook. Replaces the per-entry frozen-slice publish that
+   * degraded to O(n²) for long sessions (Pro review 2026-04-22 P1-9).
+   */
+  readonly count: ReadSignal<number>;
+  /**
+   * Return a frozen snapshot of captured entries at this moment. Slices on
+   * demand — callers pay O(n) only when they actually need the list, not
+   * on every log. Returns an empty frozen array when `capture=false` was
+   * passed.
+   */
+  entriesSnapshot(): readonly ConsoleEntry[];
+  /** Aggregate counts. Tracked even when `capture=false`. */
+  getStats(): ConsoleStats;
+  /**
+   * Replay captured entries to explicit streams (typically `process.stdout` +
+   * `process.stderr` after exiting alt-screen). Entries whose stream was
+   * `'stderr'` go to the stderr stream; the rest go to stdout. Does not clear
+   * entries — call this alongside `dispose()` at TUI exit.
+   */
+  replay(stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+/**
+ * Create a Console owner backed by a ConsoleRouter. Starts in the restored
+ * (non-capturing) state — call `capture()` to register the tap and (when
+ * `suppress: true`) also push a suppress sink policy on the router.
+ *
+ * When no router is provided, Console constructs a private one patched
+ * against the given `target` console global. Production Term factories
+ * should pass a shared router so Console's tap and Output's sink layer
+ * deterministically via a single patch site.
+ */
+declare function createConsole(target?: globalThis.Console, router?: ConsoleRouter): Console;
+//#endregion
+//#region packages/ag-term/src/ansi/term.d.ts
+/**
+ * All chalk style method names that can be chained.
+ */
+type ChalkStyleName = "reset" | "bold" | "dim" | "italic" | "underline" | "overline" | "inverse" | "hidden" | "strikethrough" | "visible" | "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "grey" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright" | "bgBlack" | "bgRed" | "bgGreen" | "bgYellow" | "bgBlue" | "bgMagenta" | "bgCyan" | "bgWhite" | "bgGray" | "bgGrey" | "bgBlackBright" | "bgRedBright" | "bgGreenBright" | "bgYellowBright" | "bgBlueBright" | "bgMagentaBright" | "bgCyanBright" | "bgWhiteBright";
+/**
+ * StyleChain provides chainable styling methods.
+ * Each property returns a new chain, and the chain is callable.
+ */
+type StyleChain = {
+  /**
+   * Apply styles to text.
+   */
+  (text: string): string;
+  (template: TemplateStringsArray, ...values: unknown[]): string;
+  /**
+   * RGB foreground color.
+   */
+  rgb(r: number, g: number, b: number): StyleChain;
+  /**
+   * Hex foreground color.
+   */
+  hex(color: string): StyleChain;
+  /**
+   * 256-color foreground.
+   */
+  ansi256(code: number): StyleChain;
+  /**
+   * RGB background color.
+   */
+  bgRgb(r: number, g: number, b: number): StyleChain;
+  /**
+   * Hex background color.
+   */
+  bgHex(color: string): StyleChain;
+  /**
+   * 256-color background.
+   */
+  bgAnsi256(code: number): StyleChain;
+} & {
+  /**
+   * Chainable style properties.
+   */
+readonly [K in ChalkStyleName]: StyleChain } & {
+  curlyUnderline(text: string): string;
+  dottedUnderline(text: string): string;
+  dashedUnderline(text: string): string;
+  doubleUnderline(text: string): string;
+  underlineColor(r: number, g: number, b: number, text: string): string;
+  styledUnderline(name: UnderlineStyle$2, rgb: RGB$1, text: string): string;
+};
+/**
+ * Term — the central abstraction for terminal interaction.
+ *
+ * Term is both a styling helper (chainable ANSI via Proxy) and the umbrella
+ * for typed sub-owners (input / output / modes / size / signals / console).
+ * Pass it to `run()` or `createApp()`.
+ *
+ * Provides:
+ * - Capability detection (cached on creation)
+ * - Dimensions (shorthand getters over `term.size`)
+ * - I/O (write, writeLine + the per-resource sub-owners)
+ * - Sub-owners: input (stdin/probes/events), output (stdout guard),
+ *   modes (raw/alt-screen/paste/kitty/mouse/focus), size (dims + resize),
+ *   signals (process signal scope), console (console.* capture)
+ * - Styling (chainable via Proxy)
+ * - Disposable lifecycle
+ *
+ * @example
+ * ```ts
+ * using term = createTerm()
+ * await run(<App />, term)
+ * ```
+ */
+interface Term extends Disposable, StyleChain {
+  /**
+   * Terminal capabilities profile.
+   *
+   * Always populated — every Term constructor commits to a full TerminalCaps.
+   * Node-backed Terms with TTY stdin detect from the environment; non-TTY
+   * Node terms, headless Terms, and emulator-backed Terms use sensible
+   * deterministic defaults (`defaultCaps()` — truecolor, unicode, no kitty
+   * keyboard). Override via `createTerm({ caps: { … } })`.
+   *
+   * Post km-silvery.terminal-profile-plateau Phase 2 this is non-optional —
+   * callers no longer need `term.caps ?? detectTerminalCaps()` guards.
+   *
+   * Equivalent to `term.profile.caps`. The two views are guaranteed identical
+   * — every Term constructor seeds `profile` from `caps` (or vice versa) via
+   * `createTerminalProfile({ caps })` so there's only one source of truth.
+   */
+  readonly caps: TerminalCaps;
+  /**
+   * Fully-resolved {@link TerminalProfile} for this Term — `caps`, `colorLevel`,
+   * `colorForced`, and `colorProvenance` bundled into the single value
+   * downstream consumers should pass through the pipeline.
+   *
+   * Every Term variant owns its profile. Node-backed Terms build it from the
+   * TTY/env detection that populated `caps`; headless and emulator-backed
+   * Terms build it from their deterministic caps. The profile's
+   * `colorProvenance` is always `"caller-caps"` (and `colorForced` is `false`)
+   * when the Term constructed it from `caps` — Term construction is not an
+   * opportunity for env precedence (that happens at `run()` / `createApp()`
+   * where `colorLevel` / `NO_COLOR` are applied).
+   *
+   * Prefer this over `term.caps` when calling downstream pipeline entry
+   * points that accept a profile. run.tsx's Term branch reads it directly
+   * instead of rebuilding via `createTerminalProfile({ caps: term.caps })`
+   * — one detection, one profile, no double-pass.
+   *
+   * Post km-silvery.plateau-term-owns-profile (H15 of the /big review
+   * 2026-04-23).
+   */
+  readonly profile: TerminalProfile;
+  /**
+   * Environment identity — `program`, `version`, `TERM`. Convenience mirror
+   * of `profile.emulator`. Callers that only need "who is the terminal?"
+   * (diagnostics, probe-cache keys) read this instead of sitting on the full
+   * protocol-flags surface of {@link caps}.
+   *
+   * Post km-silvery.plateau-naming-polish (2026-04-23): renamed from
+   * `term.identity`; `TerminalIdentity` → `TerminalEmulator`.
+   */
+  readonly emulator: TerminalEmulator;
+  /**
+   * Terminal width in columns.
+   * Undefined if not a TTY or dimensions unavailable.
+   */
+  readonly cols: number | undefined;
+  /**
+   * Terminal height in rows.
+   * Undefined if not a TTY or dimensions unavailable.
+   */
+  readonly rows: number | undefined;
+  /**
+   * Input owner — mediates ALL stdin reads + raw-mode + data subscription.
+   * Use `term.input.probe(…)` for terminal queries (color, cursor, kitty, etc.)
+   * and `term.input.onData(…)` for primary key/mouse stream consumers.
+   *
+   * Replaces direct `process.stdin.setRawMode` / `stdin.on('data', …)` —
+   * those patterns race under async (the 2026-04-22 wasRaw class).
+   *
+   * Lazily constructed on first access for Node-backed Terms.
+   * Undefined for headless Terms (no stdin to own).
+   */
+  readonly input: InputOwner | undefined;
+  /**
+   * Output owner — single-owner stdout/stderr/console mediator.
+   * Use `term.output.write(…)` for render-pipeline output.
+   *
+   * When activated (after protocol setup), intercepts `process.stdout` /
+   * `process.stderr` / `console.*` so only silvery's render pipeline reaches
+   * the terminal. Non-silvery writes are suppressed (stdout) or redirected to
+   * `DEBUG_LOG` / buffered (stderr). One stable owner per Term, toggled via
+   * `activate()` / `deactivate()` for pause/resume cycles.
+   *
+   * Lazily constructed on first access for Node-backed Terms.
+   * Undefined for headless and emulator-backed Terms (no real stdout to own).
+   */
+  readonly output: Output | undefined;
+  /**
+   * Size owner — single source of truth for terminal dimensions, exposed as
+   * alien-signals `ReadSignal`s.
+   *
+   * `term.size.cols()` / `term.size.rows()` / `term.size.snapshot()` read the
+   * current value and, inside `computed` / `effect`, subscribe to changes.
+   * The first read installs the stdout `resize` listener; SIGWINCH bursts
+   * coalesce through the Size owner's 200ms trailing debounce.
+   *
+   * Replaces direct `process.stdout.columns` / `stdout.rows` reads — those
+   * return stale snapshots under concurrent resize and scatter coalescing
+   * logic across every consumer.
+   *
+   * `term.cols` / `term.rows` remain as shorthand getters that delegate to
+   * this owner; they are slated for removal alongside `term.stdin/stdout` in
+   * Phase 8.
+   */
+  readonly size: Size;
+  /**
+   * Modes owner — single authority for terminal protocol modes, exposed as
+   * alien-signals `Signal<T>`s.
+   *
+   * Each mode is a callable signal: `term.modes.rawMode`, `altScreen`,
+   * `bracketedPaste`, `kittyKeyboard` (`number | false`), `mouse`,
+   * `focusReporting`. Read via `modes.altScreen()`, write via
+   * `modes.altScreen(true)`, subscribe via `effect(() => modes.altScreen())`.
+   * Same-value writes don't re-emit ANSI (alien-signals equality). `dispose`
+   * restores exactly what this owner activated.
+   *
+   * Replaces the scattered `enableMouse()` / `enableKittyKeyboard()` /
+   * `enableBracketedPaste()` / `enableFocusReporting()` call sites that
+   * previously toggled terminal state from every subsystem. Those shared
+   * globals are the same leak vector that produced the 2026-04-22 wasRaw
+   * race class — concentrating them behind one owner makes them race-free.
+   */
+  readonly modes: Modes;
+  /**
+   * Signals owner — single coordinator for every process-signal handler
+   * bound to this Term's lifetime.
+   *
+   * `term.signals.on("SIGINT", handler, { priority, before, after, name })`
+   * registers a teardown handler. One shared `process.on(signal, …)` listener
+   * is installed per signal, regardless of how many handlers the owner
+   * manages. On `dispose()` (called from `term[Symbol.dispose]`), every
+   * handler runs in priority / dependency order, each wrapped in try/catch
+   * so one failure doesn't block the rest.
+   *
+   * Replaces ad-hoc `process.on("SIGINT", …)` / `process.once("SIGTERM", …)`
+   * call sites scattered across runtime + apps. The 2026-04-22 shared-global
+   * audit found 78 such sites with no documented cleanup order — late
+   * handlers could crash while earlier handlers' resources leaked. The owner
+   * gives every Term exactly one entry-point to the signal graph.
+   *
+   * Present on every Term variant — even headless / emulator-backed — since
+   * signal handling is cross-cutting and benefits from consistent teardown
+   * semantics in tests as well as production.
+   */
+  readonly signals: Signals;
+  /**
+   * Console owner — single-owner console.* interceptor for the Term's lifetime.
+   *
+   * Starts inert. Call `term.console.capture({suppress:true})` once the alt
+   * screen is active to route `console.log/info/warn/error/debug` into a
+   * buffer instead of the screen; then `term.console.replay(stdout, stderr)`
+   * on exit to re-emit captured entries to the normal streams. React apps
+   * read via `subscribe` + `getSnapshot` (see `<Console>` + `useConsole`).
+   *
+   * Replaces the standalone console-patching helper — same implementation,
+   * Term-owned lifecycle. Undefined for Terms that don't own a real console
+   * (headless dims + emulator-backed), which never render through the global
+   * terminal and therefore have nothing to corrupt.
+   */
+  readonly console: Console | undefined;
+  /**
+   * Write string to stdout.
+   */
+  write(str: string): void;
+  /**
+   * Write string followed by newline to stdout.
+   */
+  writeLine(str: string): void;
+  /**
+   * Strip ANSI escape codes from string.
+   */
+  stripAnsi(str: string): string;
+  /**
+   * Visible screen region. Only available when created with a terminal backend.
+   * Provides getText(), getLines(), containsText() for assertions.
+   */
+  readonly screen?: TermScreen;
+  /**
+   * Scrollback region. Only available when created with a terminal backend.
+   * Provides getText(), getLines(), containsText() for assertions.
+   */
+  readonly scrollback?: TermScreen;
+  /**
+   * Cell-level access for the visible screen — row-first order.
+   * Returns resolved RGB colors, attributes, wide-char info.
+   * Only available on emulator-backed terms (createTermless).
+   */
+  cell?(row: number, col: number): {
+    readonly fg: unknown;
+    readonly bg: unknown;
+    readonly char: string;
+  };
+  /**
+   * Row-level access for the visible screen.
+   * Only available on emulator-backed terms (createTermless).
+   */
+  row?(n: number): {
+    getText(): string;
+    cell(col: number): {
+      readonly fg: unknown;
+      readonly bg: unknown;
+      readonly char: string;
+    };
+  };
+  /**
+   * Resize the terminal emulator. Only available when created with a terminal backend.
+   * Resizes the underlying emulator and triggers a re-render in the app.
+   */
+  resize?(cols: number, rows: number): void;
+  /**
+   * Paint a rendered buffer to produce ANSI output.
+   * Diffs buffer against prev (fresh render if prev is null).
+   * Updates term.frame with an immutable TextFrame snapshot.
+   * Returns the ANSI output string.
+   * For emulator backends, also feeds the output to the emulator.
+   * For headless terms, returns empty string.
+   */
+  paint?(buffer: TerminalBuffer, prev: TerminalBuffer | null): string;
+  /**
+   * Last painted TextFrame. Set after each paint() call.
+   * Immutable snapshot with cell-level access and resolved RGB colors.
+   */
+  readonly frame?: TextFrame;
+}
+/**
+ * Create a Term instance.
+ *
+ * Factory overloads:
+ * - `createTerm()` — Node.js terminal (auto-detect from process.stdin/stdout)
+ * - `createTerm({ stdout, stdin, ... })` — Node.js with custom streams/overrides
+ * - `createTerm({ cols, rows })` — Headless for testing (no I/O, fixed dims)
+ * - `createTerm(backend, { cols, rows })` — Terminal emulator backend (termless) for testing
+ * - `createTerm(emulator)` — Pre-created termless Terminal
+ *
+ * Detection results are cached at creation time for consistency.
+ *
+ * @example
+ * ```ts
+ * // Full terminal app
+ * using term = createTerm()
+ * await run(<App />, term)
+ *
+ * // Headless for testing
+ * const term = createTerm({ cols: 80, rows: 24 })
+ *
+ * // Terminal emulator (termless) for full ANSI testing
+ * using term = createTerm(createXtermBackend(), { cols: 80, rows: 24 })
+ * await run(<App />, term)
+ * expect(term.screen).toContainText("Hello")
+ *
+ * // Custom streams
+ * const term = createTerm({ stdout: customStream })
+ * ```
+ */
+declare function createTerm(options?: CreateTermOptions): Term;
+declare function createTerm(dims: {
+  cols: number;
+  rows: number;
+  caps?: Partial<TerminalCaps>;
+}): Term;
+declare function createTerm(backend: TermEmulatorBackend, dims: {
+  cols: number;
+  rows: number;
+  caps?: Partial<TerminalCaps>;
+}): Term;
+declare function createTerm(emulator: TermEmulator, opts?: {
+  caps?: Partial<TerminalCaps>;
+}): Term;
+//#endregion
+//#region packages/ag-term/src/ansi/index.d.ts
+declare const term: Term;
+//#endregion
+//#region packages/ag/src/focus-manager.d.ts
+type FocusOrigin = "keyboard" | "mouse" | "programmatic";
+/**
+ * Callback fired when focus changes. Used by the runtime to dispatch
+ * DOM-level focus/blur events without coupling FocusManager to the event system.
+ *
+ * @param oldNode - The node losing focus (null if nothing was focused)
+ * @param newNode - The node gaining focus (null on blur)
+ * @param origin - How focus was acquired
+ */
+type FocusChangeCallback = (oldNode: AgNode | null, newNode: AgNode | null, origin: FocusOrigin | null) => void;
+interface FocusSnapshot {
+  activeId: string | null;
+  previousId: string | null;
+  focusOrigin: FocusOrigin | null;
+  scopeStack: readonly string[];
+  /** The currently active peer scope (WPF FocusScope model) */
+  activeScopeId: string | null;
+}
+interface FocusManagerOptions {
+  /** Called when focus changes — wire up event dispatch here */
+  onFocusChange?: FocusChangeCallback;
+}
+/**
+ * Options for registering a hook-based (virtual) focusable.
+ *
+ * Hook focusables are registered via React hooks (e.g. `useFocus()` in the
+ * Ink compat layer) rather than by the `focusable` prop on a tree node. They
+ * participate in Tab cycling but don't have a backing `AgNode` — activeId
+ * tracking is by id only, and `activeElement` is null when a hook focusable
+ * is the active target.
+ */
+interface HookFocusableOptions {
+  /** Registration is inert when false — skipped in tab order, never reports focused */
+  isActive?: boolean;
+  /** Focus this id when registered (only when isActive !== false) */
+  autoFocus?: boolean;
+}
+interface FocusManager {
+  /** Currently focused node */
+  readonly activeElement: AgNode | null;
+  /** testID of the currently focused node */
+  readonly activeId: string | null;
+  /** Previously focused node */
+  readonly previousElement: AgNode | null;
+  /** testID of the previously focused node */
+  readonly previousId: string | null;
+  /** How focus was most recently acquired */
+  readonly focusOrigin: FocusOrigin | null;
+  /** Stack of active focus scope IDs */
+  readonly scopeStack: readonly string[];
+  /** Map of scope ID -> last focused testID within that scope */
+  readonly scopeMemory: Readonly<Record<string, string>>;
+  /** Focus a specific node */
+  focus(node: AgNode, origin?: FocusOrigin): void;
+  /** Focus a node by testID (requires root for tree search) */
+  focusById(id: string, root: AgNode, origin?: FocusOrigin): void;
+  /**
+   * Focus a hook-registered (virtual) id directly without tree traversal.
+   * Unlike `focusById`, this never needs a root — used by `useFocus()` hooks
+   * that track focus by id only.
+   */
+  focusVirtualId(id: string, origin?: FocusOrigin): void;
+  /** Clear focus */
+  blur(): void;
+  /**
+   * Register a hook-based focusable id (e.g. from `useFocus()` in Ink compat).
+   *
+   * Hook focusables form a flat list alongside the tree-based focusables.
+   * `focusNext`/`focusPrev` interleave: tree focusables come first (document
+   * order), then hook focusables (registration order). A single unified tab
+   * cycle walks both.
+   *
+   * Returns an unregister callback (safe to call on effect cleanup).
+   */
+  registerHookFocusable(id: string, options?: HookFocusableOptions): () => void;
+  /** Update an existing hook-focusable's active state. */
+  setHookFocusableActive(id: string, isActive: boolean): void;
+  /** Whether any hook focusables are currently registered. */
+  readonly hasHookFocusables: boolean;
+  /**
+   * Global focus enable (Ink compat). When false, `focusNext`/`focusPrev`
+   * become no-ops for hook-registered focusables. Tree-based focusables
+   * ignore this flag — apps using `useFocusable` are not affected.
+   */
+  readonly hookFocusEnabled: boolean;
+  setHookFocusEnabled(enabled: boolean): void;
+  /**
+   * Handle a subtree being removed from the tree.
+   * If the focused node (or previous node) is within the removed subtree,
+   * clear the reference to prevent dead node retention and broken navigation.
+   */
+  handleSubtreeRemoved(removedRoot: AgNode): void;
+  /** Push a focus scope onto the stack */
+  enterScope(scopeId: string): void;
+  /** Pop the current focus scope */
+  exitScope(): void;
+  /** The currently active peer scope ID (WPF FocusScope model) */
+  readonly activeScopeId: string | null;
+  /**
+   * Activate a peer focus scope. Saves current focus in the old scope's memory,
+   * switches to the new scope, and restores the remembered focus (or focuses
+   * the first focusable element in the scope subtree).
+   */
+  activateScope(scopeId: string, root: AgNode): void;
+  /** Get the testID path from focused node to root */
+  getFocusPath(root: AgNode): string[];
+  /** Check if a subtree rooted at testID contains the focused node */
+  hasFocusWithin(root: AgNode, testID: string): boolean;
+  /** Focus the next focusable node in tab order */
+  focusNext(root: AgNode, scope?: AgNode): void;
+  /** Focus the previous focusable node in tab order */
+  focusPrev(root: AgNode, scope?: AgNode): void;
+  /** Focus in a spatial direction (up/down/left/right) */
+  focusDirection(root: AgNode, direction: "up" | "down" | "left" | "right", layoutFn?: (node: AgNode) => Rect | null): void;
+  /** Subscribe for React integration (useSyncExternalStore) */
+  subscribe(listener: () => void): () => void;
+  /** Get immutable snapshot for useSyncExternalStore */
+  getSnapshot(): FocusSnapshot;
+}
+declare function createFocusManager(options?: FocusManagerOptions): FocusManager;
+//#endregion
+//#region packages/headless/src/selection.d.ts
+interface SelectionPosition {
+  col: number;
+  row: number;
+}
+interface SelectionRange {
+  anchor: SelectionPosition;
+  head: SelectionPosition;
+}
+/**
+ * Rectangular boundary for scoped selection.
+ * Derived by the runtime from the active document-selection ancestor's
+ * scrollRect, or from a `userSelect="contain"` hard boundary.
+ */
+interface SelectionScope {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+type SelectionGranularity = "character" | "word" | "line";
+interface TerminalSelectionState {
+  range: SelectionRange | null;
+  /** True while mouse button is held */
+  selecting: boolean;
+  /** Who initiated the selection */
+  source: "mouse" | "keyboard" | null;
+  /** Current selection granularity */
+  granularity: SelectionGranularity;
+  /** Active document/contain boundary — selection range is clamped to this rect */
+  scope: SelectionScope | null;
+}
+//#endregion
+//#region packages/ag-term/src/mouse-events.d.ts
+/**
+ * Create a synthetic mouse event.
+ *
+ * Modifier keys are merged from two sources:
+ * - SGR mouse protocol: reports Ctrl, Alt/Meta, Shift (reliable)
+ * - Keyboard tracking: reports Super/Cmd, Hyper, CapsLock, NumLock (via Kitty protocol)
+ *
+ * `metaKey` = keyboard-tracked Super (Cmd on macOS). SGR "meta" maps to `altKey`.
+ */
+declare function createMouseEvent(type: SilveryMouseEvent["type"], x: number, y: number, target: AgNode, parsed: ParsedMouse, keyboardMods?: KeyboardModifierState): SilveryMouseEvent;
+/**
+ * Create a synthetic wheel event.
+ */
+declare function createWheelEvent(x: number, y: number, target: AgNode, parsed: ParsedMouse, keyboardMods?: KeyboardModifierState): SilveryWheelEvent;
+/**
+ * Tree-based hit test: find the deepest node whose scrollRect contains (x, y).
+ *
+ * Uses reverse child order (last sibling wins = highest z-order, like DOM).
+ * Respects overflow:hidden clipping and pointerEvents="none".
+ *
+ * ### Absolute-positioned nodes escape parent bounds
+ *
+ * Absolute descendants participate in hit-testing by GEOMETRY, not by
+ * tree order / parent rect containment. An absolute child can be placed
+ * outside its parent's bounding rect (e.g., a popover anchored near a
+ * viewport edge); it still occupies screen cells at its own geometry and
+ * must be hittable.
+ *
+ * The hit test runs an "absolute pass" first that walks the whole subtree
+ * for absolute descendants and returns the latest-in-tree hit (matching
+ * the three-pass render order where absolute children paint on top of
+ * normal + sticky content). If no absolute descendant covers the point,
+ * it falls through to standard in-flow DFS.
+ *
+ * A recursive sub-call (via `hitTest(absolute, ...)`) would re-run the
+ * absolute pass on that absolute's subtree — which is correct: nested
+ * absolutes also need geometry-based hit testing.
+ */
+declare function hitTest(node: AgNode, x: number, y: number): AgNode | null;
+/**
+ * Dispatch a mouse event through the render tree with DOM-style bubbling.
+ *
+ * Bubbles from target → root, calling the appropriate handler on each node.
+ * stopPropagation() halts bubbling. mouseenter/mouseleave do NOT bubble (DOM spec).
+ */
+declare function dispatchMouseEvent(event: SilveryMouseEvent): void;
+/**
+ * Click-count state tracker.
+ *
+ * Counts up to 3 consecutive clicks within `MULTI_CLICK_TIME_MS` and
+ * `MULTI_CLICK_DISTANCE` cells of each other on the same button. After
+ * count reaches 3, the next click resets to 1 (matching DOM behavior:
+ * `MouseEvent.detail` increments to 3, then a new click chain starts).
+ *
+ * `DoubleClickState` is kept as a backwards-compatible alias.
+ */
+interface ClickCountState {
+  lastClickTime: number;
+  lastClickX: number;
+  lastClickY: number;
+  lastClickButton: number;
+  /** Number of consecutive clicks in the current chain (1, 2, or 3). */
+  count: number;
+}
+/** @deprecated Use `ClickCountState` instead — kept as an alias for callers
+ *  that haven't migrated to the count-based API. */
+type DoubleClickState = ClickCountState;
+declare function createClickCountState(): ClickCountState;
+/** @deprecated Use `createClickCountState()` instead. */
+declare const createDoubleClickState: typeof createClickCountState;
+/**
+ * Check if a click qualifies as a double-click. Backwards-compatible
+ * wrapper around `checkClickCount`.
+ *
+ * @deprecated Use `checkClickCount` and inspect the returned count
+ *   (`=== 2` for dblclick, `=== 3` for tripleclick).
+ */
+declare function checkDoubleClick(state: ClickCountState, x: number, y: number, button: number, now?: number): boolean;
+/**
+ * Compute mouseenter/mouseleave transitions between two ancestor paths.
+ *
+ * Returns { entered, left } — arrays of nodes that were entered or left.
+ * Mirrors the DOM spec: fire mouseleave on nodes in prevPath not in nextPath,
+ * and mouseenter on nodes in nextPath not in prevPath.
+ */
+declare function computeEnterLeave(prevPath: AgNode[], nextPath: AgNode[]): {
+  entered: AgNode[];
+  left: AgNode[];
+};
+/**
+ * Options for creating a mouse event processor.
+ */
+interface MouseEventProcessorOptions {
+  /** Optional focus manager — enables click-to-focus behavior.
+   *  On mousedown, the deepest focusable ancestor of the hit target is focused. */
+  focusManager?: FocusManager;
+}
+/**
+ * State for the mouse event processor.
+ */
+/**
+ * Keyboard modifier state tracked from Kitty protocol key events.
+ * Merged into mouse events to provide accurate modifier detection
+ * (SGR mouse protocol reports Ctrl/Alt/Shift but NOT Cmd/Super).
+ */
+interface KeyboardModifierState {
+  super: boolean;
+  hyper: boolean;
+  capsLock: boolean;
+  numLock: boolean;
+}
+interface MouseEventProcessorState {
+  doubleClick: DoubleClickState;
+  /** Previous hover path (for enter/leave tracking) */
+  hoverPath: AgNode[];
+  /** Whether the left button is currently down (for click detection) */
+  mouseDownTarget: AgNode | null;
+  /** Optional ancestor that captures move/up for the active mouse press. */
+  mouseCaptureTarget: AgNode | null;
+  /** Grace timer for captured drags that briefly leave the terminal bounds. */
+  outsideCaptureReleaseTimer: ReturnType<typeof setTimeout> | null;
+  /** Last no-target mouse event observed while the grace timer is armed. */
+  outsideCaptureReleaseMouse: ParsedMouse | null;
+  /** Optional focus manager for click-to-focus */
+  focusManager?: FocusManager;
+  /** Modifier state from Kitty keyboard events, merged into mouse events */
+  keyboardModifiers: KeyboardModifierState;
+  /** Aggregate `defaultPrevented` from the most recent click/dblclick/tripleclick
+   *  dispatch chain. Set by `processMouseEvent` on every mouseup so callers
+   *  (e.g., the runtime selection wiring) can gate auto-select on whether the
+   *  component tree consumed the click. Reset to false at the start of each
+   *  mouseup dispatch. */
+  lastClickPrevented: boolean;
+  /** Last observed pointer coordinates (terminal cells). Updated on every
+   *  mouse event so consumers can re-hit-test after layout changes — e.g.
+   *  scroll-wheel events that reposition content under a stationary cursor.
+   *  null means the pointer has left the terminal bounds (clearHoverPath
+   *  ran) or no mouse event has arrived yet. */
+  lastPointer: {
+    x: number;
+    y: number;
+  } | null;
+}
+declare function createMouseEventProcessor(options?: MouseEventProcessorOptions): MouseEventProcessorState;
+/**
+ * Process a raw ParsedMouse event and dispatch DOM-level events on the render tree.
+ *
+ * Call this for every SGR mouse event received. It handles:
+ * - mousedown / mouseup
+ * - click (on mouseup if same target as mousedown)
+ * - dblclick (based on timing)
+ * - mousemove + mouseenter/mouseleave
+ * - wheel
+ */
+declare function processMouseEvent(state: MouseEventProcessorState, parsed: ParsedMouse, root: AgNode): boolean;
+//#endregion
+//#region packages/ag-term/src/hit-registry-core.d.ts
+/**
+ * Hit Registry Core — Pure logic for mouse hit testing.
+ *
+ * This module contains the React-free core of the hit registry:
+ * types, registry class, z-index constants, and ID counter.
+ *
+ * React hooks and context live in ./hit-registry (which re-exports everything
+ * from here plus adds useHitRegion, useHitRegionCallback, HitRegistryContext).
+ *
+ * The @silvery/ag-term barrel imports from this file to stay React-free.
+ * Consumers who need React hooks should import from @silvery/ag-term/hit-registry.
+ */
+/**
+ * Target type for hit testing.
+ * Each type represents a different clickable element in the UI.
+ */
+interface HitTarget {
+  /** The type of element that was clicked */
+  type: "node" | "fold-toggle" | "link" | "column-header" | "scroll-area" | "button";
+  /** Column index (for column-header, or items within a column) */
+  colIndex?: number;
+  /** Card index within a column */
+  cardIndex?: number;
+  /** Sub-item index within a card (e.g., checklist items) */
+  subIndex?: number;
+  /** Node ID for node-specific targets */
+  nodeId?: string;
+  /** URL for link targets */
+  linkUrl?: string;
+  /** Custom action identifier */
+  action?: string;
+}
+/**
+ * A registered hit region with position, size, target, and z-index.
+ */
+interface HitRegion {
+  /** X position on screen (0-indexed column) */
+  x: number;
+  /** Y position on screen (0-indexed row) */
+  y: number;
+  /** Width in columns */
+  width: number;
+  /** Height in rows */
+  height: number;
+  /** The target to return when this region is clicked */
+  target: HitTarget;
+  /** Z-index for layering (higher values are on top) */
+  zIndex: number;
+}
+/**
+ * Registry for managing hit regions.
+ *
+ * Components register their screen regions with targets, and the registry
+ * resolves mouse clicks to the appropriate target based on position and z-index.
+ *
+ * @example
+ * ```typescript
+ * const registry = new HitRegistry();
+ *
+ * // Register a card region
+ * registry.register('card-1', {
+ *   x: 10, y: 5, width: 30, height: 8,
+ *   target: { type: 'node', nodeId: 'abc123' },
+ *   zIndex: 10
+ * });
+ *
+ * // Hit test a click
+ * const target = registry.hitTest(15, 7);
+ * // Returns { type: 'node', nodeId: 'abc123' }
+ * ```
+ */
+declare class HitRegistry {
+  private regions;
+  /**
+   * Register a hit region with a unique ID.
+   *
+   * @param id - Unique identifier for the region (used for unregistration)
+   * @param region - The region definition including position, size, target, and z-index
+   */
+  register(id: string, region: HitRegion): void;
+  /**
+   * Unregister a hit region by ID.
+   *
+   * @param id - The ID used when registering the region
+   */
+  unregister(id: string): void;
+  /**
+   * Clear all registered regions.
+   * Useful when the UI is completely redrawn.
+   */
+  clear(): void;
+  /**
+   * Get the number of registered regions.
+   * Useful for debugging.
+   */
+  get size(): number;
+  /**
+   * Test a screen position and return the highest z-index matching target.
+   *
+   * @param screenX - X position on screen (0-indexed column)
+   * @param screenY - Y position on screen (0-indexed row)
+   * @returns The target of the highest z-index region containing the point, or null if none
+   */
+  hitTest(screenX: number, screenY: number): HitTarget | null;
+  /**
+   * Get all regions that contain a point, sorted by z-index (highest first).
+   * Useful for debugging or when you need to know all overlapping elements.
+   *
+   * @param screenX - X position on screen (0-indexed column)
+   * @param screenY - Y position on screen (0-indexed row)
+   * @returns Array of matching regions, sorted by z-index descending
+   */
+  hitTestAll(screenX: number, screenY: number): HitRegion[];
+  /**
+   * Debug helper: get all registered regions.
+   */
+  getAllRegions(): Map<string, HitRegion>;
+}
+/**
+ * Reset the ID counter (useful for testing).
+ */
+declare function resetHitRegionIdCounter(): void;
+/**
+ * Recommended z-index values for different UI layers.
+ */
+declare const Z_INDEX: {
+  /** Background elements */readonly BACKGROUND: 0; /** Column headers */
+  readonly COLUMN_HEADER: 5; /** Cards in the main view */
+  readonly CARD: 10; /** Fold toggles (above cards for easier clicking) */
+  readonly FOLD_TOGGLE: 15; /** Links within cards */
+  readonly LINK: 20; /** Floating elements */
+  readonly FLOATING: 50; /** Modal dialogs */
+  readonly DIALOG: 100; /** Dropdown menus */
+  readonly DROPDOWN: 150; /** Tooltips */
+  readonly TOOLTIP: 200;
+};
+//#endregion
+//#region packages/ag-term/src/hit-registry.d.ts
+/**
+ * Context for accessing the HitRegistry.
+ * Components use this to register their hit regions.
+ */
+declare const HitRegistryContext: _$react.Context<HitRegistry | null>;
+/**
+ * Hook to get the HitRegistry from context.
+ *
+ * @returns The HitRegistry instance, or null if not in a HitRegistryContext
+ */
+declare function useHitRegistry(): HitRegistry | null;
+/**
+ * Hook to register a hit region based on component's screen position.
+ *
+ * Automatically registers on mount and when position changes,
+ * and unregisters on unmount.
+ *
+ * @param target - The target to return when this region is clicked
+ * @param rect - The screen rectangle (from useScrollRect or similar)
+ * @param zIndex - Z-index for layering (default: 0)
+ * @param enabled - Whether the region is active (default: true)
+ *
+ * @example
+ * ```tsx
+ * function Card({ nodeId }: { nodeId: string }) {
+ *   const rect = useScrollRect();
+ *
+ *   useHitRegion(
+ *     { type: 'node', nodeId },
+ *     rect,
+ *     10 // z-index for cards
+ *   );
+ *
+ *   return <Box>...</Box>;
+ * }
+ * ```
+ */
+declare function useHitRegion(target: HitTarget, rect: Rect | null, zIndex?: number, enabled?: boolean): void;
+/**
+ * Hook to register a hit region using a callback for screen position.
+ *
+ * Similar to useHitRegion but works with useScrollRect for
+ * better performance in large lists (avoids re-renders).
+ *
+ * @param target - The target to return when this region is clicked
+ * @param zIndex - Z-index for layering (default: 0)
+ * @param enabled - Whether the region is active (default: true)
+ * @returns A callback to pass to useScrollRect
+ *
+ * @example
+ * ```tsx
+ * function Card({ nodeId }: { nodeId: string }) {
+ *   const onLayout = useHitRegionCallback(
+ *     { type: 'node', nodeId },
+ *     10 // z-index
+ *   );
+ *
+ *   useScrollRect(onLayout);
+ *
+ *   return <Box>...</Box>;
+ * }
+ * ```
+ */
+declare function useHitRegionCallback(target: HitTarget, zIndex?: number, enabled?: boolean): (rect: Rect) => void;
+//#endregion
+//#region packages/ag-term/src/bound-term.d.ts
+/**
+ * BoundTerm interface - terminal with node awareness
+ */
+interface BoundTerm {
+  /** Get cell at screen coordinates */
+  cell(x: number, y: number): Cell;
+  /** Get node at screen coordinates */
+  nodeAt(x: number, y: number): AgNode | null;
+  /** Get visible text (plain, no ANSI) */
+  readonly text: string;
+  /** Terminal dimensions */
+  readonly columns: number;
+  readonly rows: number;
+  /** Access underlying buffer */
+  readonly buffer: TerminalBuffer;
+}
+//#endregion
+export { TerminalBuffer as $, IslandGuest as $t, term as A, MeasureFunc as At, SignalOnOptions as B, Key as Bt, TerminalSelectionState as C, ResizeEvent as Ct, FocusOrigin as D, SilveryMouseEvent as Dt, FocusManagerOptions as E, MouseEventProps as Et, ConsoleCaptureOptions as F, createFocusEvent as Ft, InputOwnerOptions as G, keyToName as Gt, Signals as H, ParsedKeypress as Ht, ConsoleStats as I, createKeyEvent as It, KittyFlags as J, parseKey as Jt, createInputOwner as K, matchHotkey as Kt, createConsole as L, dispatchFocusEvent as Lt, Term as M, FocusEventProps as Mt, createTerm as N, SilveryFocusEvent as Nt, FocusSnapshot as O, SilveryWheelEvent as Ot, Console as P, SilveryKeyEvent as Pt, Style as Q, IslandCursorState as Qt, CreateSignalsOptions as R, dispatchKeyEvent as Rt, SelectionRange as S, Rect as St, FocusManager as T, TextProps as Tt, createSignals as U, emptyKey as Ut, SignalUnregister as V, ParsedHotkey as Vt, InputOwner as W, keyToModifiers as Wt, Modes as X, IslandCapabilities as Xt, ModeName as Y, parseKeypress as Yt, createModes as Z, IslandContext as Zt, createMouseEventProcessor as _, ViewportProps as _n, FocusEvent$1 as _t, useHitRegistry as a, IslandModesOwner as an, isMouseSequence as at, hitTest as b, MouseEvent as bt, HitTarget as c, IslandOutputOwner as cn, AgNodeType as ct, MouseEventProcessorOptions as d, IslandProtocolModes as dn, CollisionStrategy as dt, IslandHandle as en, UnderlineStyle as et, MouseEventProcessorState as f, IslandSignal as fn, CursorShape as ft, createMouseEvent as g, ViewportPalette as gn, EventSource as gt, createDoubleClickState as h, ForeignSource as hn, Event as ht, useHitRegionCallback as i, IslandKeyEvent as in, ParsedMouse as it, StyleChain as j, MeasureMode as jt, createFocusManager as k, LayoutNode as kt, Z_INDEX as l, IslandPaletteOwner as ln, BlurEvent as lt, computeEnterLeave as m, IslandSizeOwner as mn, Decoration as mt, HitRegistryContext as n, IslandInputEvent as nn, ConsoleEntry as nt, HitRegion as o, IslandMouseEvent as on, parseMouseSequence as ot, checkDoubleClick as p, IslandSignalsOwner as pn, CustomEvent as pt, CreateModesOptions as q, parseHotkey as qt, useHitRegion as r, IslandInputOwner as rn, ParseMouseOptions as rt, HitRegistry as s, IslandNodeState as sn, AgNode as st, BoundTerm as t, IslandHydrate as tn, FrameCell as tt, resetHitRegionIdCounter as u, IslandPalettePolicy as un, BoxProps as ut, createWheelEvent as v, ViewportRef as vn, InteractiveState as vt, FocusChangeCallback as w, SignalEvent as wt, processMouseEvent as x, Placement as xt, dispatchMouseEvent as y, KeyEvent$1 as yt, SignalName as z, InputHandler as zt };
+//# sourceMappingURL=bound-term-0sPrrzH1.d.mts.map