silvery 0.21.0 → 0.23.0

package/dist/{bound-term-0sPrrzH1.d.mts → mouse-events-B2z5tbsL.d.mts}

@@ -1,5 +1,4 @@
-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";
+import { B as TerminalProfile, F as TerminalCaps, M as RGB$1, N as TerminalNotificationProtocol, P as UnderlineStyle$2, bt as TerminalEmulator, ht as Theme, j as ColorLevel } from "./index-377zdPLP.mjs";
 
 //#region packages/ag/src/viewport-types.d.ts
 /**
@@ -480,6 +479,41 @@ interface IslandMouseEvent {
   shift?: boolean;
   alt?: boolean;
 }
+/**
+ * Host command-prefix reservation for a focused input-capable island (the tmux
+ * `Ctrl-b` model, @hab/.../20349). When set on a focused island, the runtime
+ * routes a matching key to the HOST (it falls through to the app's `useInput`)
+ * instead of feeding the guest — letting a multi-pane host (e.g. a deck shell
+ * pane) keep a command prefix while a full-screen guest owns every other key.
+ *
+ * This is a deliberately NARROW concept — it names host-owned deck/control keys,
+ * not arbitrary interception. A key is reserved for the host iff it matches
+ * `hotkey`, one of `reservedHotkeys`, OR `capturing` is true.
+ */
+interface IslandCommandPrefix {
+  /**
+   * The always-reserved prefix hotkey, in {@link import("./keys").parseHotkey}
+   * syntax (e.g. `"ctrl+g"`, `"Control+b"`). Matched against each key via
+   * {@link import("./keys").matchHotkey}. The prefix never reaches the guest
+   * while the island is focused.
+   */
+  hotkey: string;
+  /**
+   * Additional single-step host hotkeys reserved even when the host is not
+   * mid-command. Use this for direct deck navigation shortcuts that must not
+   * leak into a focused full-screen guest (for example Option+h/j/k/l pane
+   * focus). These keys fall through to host `useInput` just like `hotkey`.
+   */
+  reservedHotkeys?: readonly string[];
+  /**
+   * Host is mid-command (a chord/menu is pending). While `true`, EVERY key is
+   * reserved for the host (routed to `useInput`, not the guest) so multi-key
+   * chord follow-ups reach the host until it clears the flag. A deck typically
+   * binds this to its `chordPending` state. Default behavior when omitted:
+   * `false` — only the `hotkey` and `reservedHotkeys` are reserved.
+   */
+  capturing?: boolean;
+}
 /**
  * Modes owner — host queries which protocol modes the guest currently wants
  * active (alt-screen, bracketed-paste, mouse-tracking SGR, Kitty keyboard,
@@ -719,6 +753,28 @@ interface IslandNodeState {
   focusable: boolean;
   /** True iff this island is currently in the focused subtree. */
   focused: boolean;
+  /**
+   * Host-designated cursor activation, INDEPENDENT of input focus
+   * (@km/silvery/19426). When true, `findActiveCursorRect` renders this
+   * island's guest cursor (`handle.output.cursor` + `cursorVisible`) as the
+   * host hardware caret, translated into the island's screen rect. The host
+   * is responsible for the one-cursor invariant — at most one island should
+   * carry `cursorActive` at a time (e.g. silvermux sets it for the focused
+   * pane only). Lets a host show a pane caret without giving the island input
+   * focus (which would route keys away from the host's own input handler).
+   */
+  cursorActive?: boolean;
+  /**
+   * Host command prefix (tmux model, @hab/.../20349). When set and this island
+   * is the focused input target, the runtime reserves a matching key for the
+   * host — it falls through to the app's `useInput` instead of feeding the
+   * guest. A key is reserved iff it matches `commandPrefix.hotkey`, one of
+   * `commandPrefix.reservedHotkeys`, OR `commandPrefix.capturing` is true.
+   * Absent ⇒ the guest captures every key (default behavior). Lets a host keep
+   * command keys (e.g. `Ctrl-G`, Option pane navigation) while a full-screen
+   * guest owns the rest. Set by `<Island commandPrefix={…}>`.
+   */
+  commandPrefix?: IslandCommandPrefix;
   /**
    * Effective palette policy. Frozen palette: snapshot held in
    * `frozenPalette`. Inherit: `null` (host theme cascades).
@@ -752,15 +808,21 @@ interface IslandNodeState {
 interface DragEventPayload {
   /** The node being dragged */
   source: AgNode;
-  /** Current terminal position of the pointer */
+  /** Current Silvery layout-space position of the pointer */
   position: {
     x: number;
     y: number;
   };
-  /** The node under the cursor (the drop target receiving this event) */
+  /** The current or final drop target under the pointer, when one exists */
   dropTarget: AgNode | null;
 }
 interface DragEventProps {
+  /** Fired on the draggable source when the pointer crosses the drag threshold */
+  onDragStart?: (event: DragEventPayload) => void;
+  /** Fired on the draggable source after pointer release, whether or not a drop target exists */
+  onDragEnd?: (event: DragEventPayload) => void;
+  /** Fired on the draggable source when an active drag is canceled */
+  onDragCancel?: (event: DragEventPayload) => void;
   /** Fired when a dragged node enters this node's bounds */
   onDragEnter?: (event: DragEventPayload) => void;
   /** Fired when a dragged node leaves this node's bounds */
@@ -781,15 +843,17 @@ interface DragEventProps {
  *
  * parseKey() returns `[input, key]` where these serve DIFFERENT purposes:
  *
- * - `input` is **normalized for keybinding matching**. Shifted punctuation is
+ * - `input` is **normalized for physical 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.
+ *   like 'shift+3' can match. Uppercase letters retain their casing and set 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.
+ *   insertion or literal-character hotkeys, use it instead of normalized `input`.
+ *   `key.text ?? input` ensures Shift+3 inserts '#', opt+e inserts '´', and IME
+ *   output inserts the composed string.
  *
- * Rule: keybinding resolution uses `input`. Text insertion uses `key.text`.
+ * Rule: physical keybindings use `input` plus modifiers. Literal-character hotkeys
+ * and text insertion use `key.text`; matchHotkey() handles both representations.
  * Never reconstruct characters from key codes — trust what the terminal sent.
  *
  * - KEY_MAP: Playwright key names -> ANSI sequences (for sending input)
@@ -897,6 +961,32 @@ interface ParsedHotkey {
   super: boolean;
   hyper: boolean;
 }
+/**
+ * Convert Playwright-style key string to ANSI sequence.
+ *
+ * Supports:
+ * - Single characters: 'a', 'A', '1', etc.
+ * - Named keys: 'Enter', 'ArrowUp', 'Escape', etc.
+ * - Modifier combos: 'Control+c', 'Shift+Tab', 'Control+Shift+a'
+ * - Lowercase modifier aliases: 'ctrl+c', 'shift+Tab', 'alt+x'
+ *
+ * @example
+ * ```tsx
+ * keyToAnsi('Enter')       // '\r'
+ * keyToAnsi('ArrowUp')     // '\x1b[A'
+ * keyToAnsi('Control+c')   // '\x03'
+ * keyToAnsi('j')           // 'j'
+ * ```
+ */
+declare function keyToAnsi(key: string): string;
+/**
+ * ANSI escape code suffix -> key name mapping.
+ * Used by useInput to parse incoming key sequences.
+ *
+ * The key is the escape sequence suffix (after ESC or ESC[).
+ * Multiple terminal emulators may use different sequences for the same key.
+ */
+declare const CODE_TO_KEY: Record<string, string>;
 interface ParsedKeypress {
   name: string;
   ctrl: boolean;
@@ -997,6 +1087,24 @@ declare function parseHotkey(keyStr: string): ParsedHotkey;
  * @returns true if the hotkey matches the key event
  */
 declare function matchHotkey(hotkey: ParsedHotkey, key: Key, input?: string): boolean;
+/**
+ * Convert a Playwright-style key string to a Kitty keyboard protocol ANSI sequence.
+ *
+ * Uses the appropriate Kitty format for each key type:
+ * - Regular keys: CSI codepoint ; modifiers u
+ * - Arrow/nav keys: CSI 1 ; modifiers letter (enhanced special key format)
+ * - Tilde keys: CSI number ; modifiers ~ (enhanced special key format)
+ *
+ * @example
+ * ```tsx
+ * keyToKittyAnsi('a')            // '\x1b[97u'       (no modifiers → bare)
+ * keyToKittyAnsi('Enter')        // '\x1b[13u'
+ * keyToKittyAnsi('Control+c')    // '\x1b[99;5u'     (ctrl = 4, modifier = 5)
+ * keyToKittyAnsi('Shift+Enter')  // '\x1b[13;2u'     (shift = 1, modifier = 2)
+ * keyToKittyAnsi('ArrowUp')      // '\x1b[1;1A'      (enhanced special key)
+ * ```
+ */
+declare function keyToKittyAnsi(key: string): string;
 //#endregion
 //#region packages/ag/src/focus-events.d.ts
 /**
@@ -1285,9 +1393,13 @@ interface SilveryMouseEvent {
  * Synthetic wheel event, extending SilveryMouseEvent with scroll deltas.
  */
 interface SilveryWheelEvent extends SilveryMouseEvent {
-  /** Vertical scroll: -1 (up) or +1 (down) */
+  /** Vertical scroll: -1 (up), +1 (down), or 0 for a pure-horizontal wheel */
   deltaY: number;
-  /** Horizontal scroll: always 0 for terminals */
+  /**
+   * Horizontal scroll: -1 (left), +1 (right), or 0 for a pure-vertical wheel.
+   * Sourced from SGR mouse buttons 66/67 (trackpad / tilt-wheel horizontal
+   * scroll); 0 on terminals or input devices that never emit them.
+   */
   deltaX: number;
 }
 interface MouseEventProps {
@@ -1317,6 +1429,14 @@ interface MouseEventProps {
  * keeps its CSS meaning as an explicit hard boundary.
  */
 type UserSelect = "auto" | "none" | "text" | "contain";
+/**
+ * Semantic mouse pointer intent for the region occupied by a Box.
+ *
+ * Terminal renderers map this to OSC 22 cursor names; DOM/canvas targets can
+ * map the same vocabulary to CSS cursor values. Unsupported terminal targets
+ * silently ignore the emitted OSC sequence.
+ */
+type MouseCursorShape = "default" | "text" | "pointer" | "crosshair" | "move" | "not-allowed" | "wait" | "help" | "grab" | "grabbing" | "col-resize" | "row-resize" | "ew-resize" | "ns-resize";
 /**
  * A rectangle with position and size.
  * All values are in terminal columns/rows (integers).
@@ -1798,8 +1918,9 @@ interface BoxProps extends FlexboxProps, StyleProps, TestProps, MouseEventProps,
   /**
    * 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.
+   * instead of text selection. The prop is not inherited, but pointer hits on
+   * descendants resolve to their nearest draggable ancestor, matching DOM drag
+   * targeting for content-bearing cards and rows.
    */
   draggable?: boolean;
   /**
@@ -1812,6 +1933,22 @@ interface BoxProps extends FlexboxProps, StyleProps, TestProps, MouseEventProps,
    * narrow draggable controls such as scrollbars.
    */
   mouseCapture?: boolean;
+  /**
+   * Semantic mouse cursor for this hit-test region.
+   *
+   * The deepest hovered node with a cursor wins; if the deepest hit node has no
+   * cursor, the resolver walks ancestors so a parent region can provide the
+   * default affordance for its children. During `mouseCapture`, the capture
+   * target owns the cursor so drags keep their grab/resize shape outside the
+   * original one-cell hit box.
+   *
+   * When omitted, activation handlers derive `"pointer"` and selectable text
+   * derives `"text"`. Explicit values always win; pass `"default"` to opt out
+   * of semantic defaults and restore the target's native cursor.
+   *
+   * @default Derived from interaction semantics.
+   */
+  mouseCursor?: MouseCursorShape;
   onLayout?: (layout: Rect) => void;
   /**
    * Show scroll overflow indicators (▲N / ▼N) for scrollable containers.
@@ -1868,9 +2005,13 @@ interface BoxProps extends FlexboxProps, StyleProps, TestProps, MouseEventProps,
    * 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.
+   * 1. Focused cursor owner wins — a Box that has `cursorOffset` and either
+   *    `focused === true` or focus-manager `interactiveState.focused === true`
+   *    always beats a non-focused declarer, even when
+   *    `cursorOffset.visible === false`. Hidden focused owners still carry a
+   *    position so terminal renderers can move there before hiding the
+   *    hardware cursor.
+   * 2. Otherwise deepest visible in paint order (post-order tree walk) wins.
    * 3. Otherwise null.
    *
    * **Clipping** (invariant #4): if the caret falls outside the nearest
@@ -1879,6 +2020,23 @@ interface BoxProps extends FlexboxProps, StyleProps, TestProps, MouseEventProps,
    * clip edge is treated as visible.
    */
   cursorOffset?: CursorOffset;
+  /**
+   * Component-relative HARDWARE-PARK cell. Declares where a managed terminal
+   * frame parks (then hides) the hardware cursor when this Box owns the frame —
+   * position-only (`col`/`row`; `visible`/`shape` are ignored — the visible
+   * caret is `cursorOffset`'s job).
+   *
+   * UNLIKE `cursorOffset`, park is **not focus-gated**: an editable declares its
+   * input cell here whether or not it (or the window) is focused, so a managed
+   * frame ALWAYS has a benign park cell. This is the structural fix for the
+   * recurring "hardware cursor parks one row above the prompt" bug
+   * (@km/code/v0.2/19702): with no park declaration the frame fell back to the
+   * box origin / `home(0,0)`, and a multiplexer that dropped the cursor-hide
+   * surfaced the parked cursor there. Resolved by `computeParkRect` + the
+   * non-focus-gated tree walk `findActiveParkRect`; consumed by
+   * `managedCursorSuffix`.
+   */
+  parkOffset?: CursorOffset;
   /**
    * Semantic selection intent — the user's selected substring within this
    * Box's text content, declared as character offsets `{ from, to }`. The
@@ -2096,6 +2254,67 @@ interface TextFlexItemProps {
   /** CSS `max-height`. */
   maxHeight?: number | string;
 }
+/**
+ * Cell-width-aware measurement helpers handed to a {@link TextTruncateHook}.
+ * Every method counts display columns (CJK / emoji are 2 cells), never code
+ * units — so a hook can implement its own elision policy without re-deriving
+ * width math. Backed by the active pipeline measurer when present, module-level
+ * fallbacks otherwise.
+ */
+interface TextMeasure {
+  /** Display width (terminal columns) of `text`. */
+  width(text: string): number;
+  /** Longest prefix of `text` whose display width is <= `max` columns. */
+  sliceByWidth(text: string, max: number): string;
+  /** Longest suffix of `text` whose display width is <= `max` columns. */
+  sliceByWidthFromEnd(text: string, max: number): string;
+}
+/**
+ * Rich result a {@link TextTruncateHook} may return instead of a bare string,
+ * so a policy hook can mark which spans of its fitted line are elision-marker
+ * CHROME (e.g. a `" … "` separator) rather than content. Marker spans render
+ * with {@link TextProps.truncateMarkerColor} (default `"$fg-muted"`), making
+ * the elision read as quiet chrome instead of competing with the surrounding
+ * text.
+ *
+ * A bare `string` return is exactly equivalent to `{ text }` with no markers —
+ * today's behavior, no marker styling of hook output.
+ */
+interface TextTruncateResult {
+  /** The fitted line. Same contract as a bare-string return — defensively
+   *  hard-clipped if it still overflows, so the hook can never paint past the
+   *  box edge. */
+  text: string;
+  /**
+   * JS string-index `[start, end)` ranges within `text` that are
+   * elision-marker chrome, rendered with {@link TextProps.truncateMarkerColor}.
+   * Indices are UTF-16 offsets into `text` (the PLAIN visible string the hook
+   * was handed and returned — never the inline-ANSI form). Out-of-bounds or
+   * overlapping ranges are clamped / ignored defensively (a STRICT-mode warning
+   * is emitted); a malformed `markers` array never throws in production paths.
+   */
+  markers?: readonly {
+    start: number;
+    end: number;
+  }[];
+}
+/**
+ * Per-line truncation hook for `wrap` truncate modes. Only consulted when the
+ * line OVERFLOWS the available width; receives the overflowing `line`, the
+ * available cell `width`, and a cell-width-aware {@link TextMeasure}.
+ *
+ * Return the fitted line (bare `string`), a {@link TextTruncateResult} to also
+ * mark marker-chrome spans, or `null` to fall back to the built-in truncation
+ * for the active mode. The returned text is NOT trusted blindly — if it still
+ * overflows, the pipeline hard-clips it via `measure.sliceByWidth`, so a hook
+ * can never paint past the box edge. Returning `null` MUST be cheap and safe;
+ * the hook runs once per overflowing line, every render.
+ *
+ * This is where width-dependent elision policy lives (e.g. a tail-length
+ * formula derived from `width`), which a static data prop cannot express.
+ * Function-prop precedent in `TextProps`: the mouse handlers.
+ */
+type TextTruncateHook = (line: string, width: number, measure: TextMeasure) => string | TextTruncateResult | null;
 interface TextProps extends StyleProps, TextFlexItemProps, TestProps, MouseEventProps {
   children?: React.ReactNode;
   /**
@@ -2119,6 +2338,47 @@ interface TextProps extends StyleProps, TextFlexItemProps, TestProps, MouseEvent
    *   cells).
    */
   wrap?: "wrap" | "wrap-truncate" | "hard" | "even" | "truncate" | "truncate-start" | "truncate-middle" | "truncate-end" | "clip" | boolean;
+  /**
+   * Per-line truncation hook. Only consulted when `wrap` is a truncate mode
+   * (`"truncate"` / `"truncate-start"` / `"truncate-middle"` / `"truncate-end"`)
+   * AND the line overflows the available width. Lets the consumer supply a
+   * width-dependent elision policy (custom separator, token-boundary breaks,
+   * slug rescue) the built-in modes can't express. Returns the fitted line or
+   * `null` to use the built-in truncation. An overwide return value is
+   * defensively hard-clipped — the hook can never paint past the box edge.
+   * See {@link TextTruncateHook}.
+   */
+  truncate?: TextTruncateHook;
+  /**
+   * Color for elision-marker CHROME in truncated output — the inserted "…" of
+   * the built-in truncate modes (`"truncate"` / `"truncate-end"` /
+   * `"truncate-start"` / `"truncate-middle"` / `"wrap-truncate"`) AND any
+   * marker ranges a {@link TextTruncateHook} returns via
+   * {@link TextTruncateResult.markers}. Styling the marker separately from the
+   * surrounding text lets the elision read as quiet chrome, not content.
+   *
+   * Accepts the same color forms as {@link StyleProps.color} (`$token`, hex,
+   * named, `rgb(...)`, `mix(...)`), resolved against the active theme at paint
+   * time. Does NOT affect the surrounding text — only the marker cells.
+   *
+   * Defaults to `"$fg-muted"` (the standard low/dim fg slot), NOT `"$muted"` —
+   * in the default pipeline theme `"$muted"` resolves to the same value as
+   * `"$fg"`, so it would never dim against `$fg`-colored text.
+   *
+   * @default "$fg-muted"
+   */
+  truncateMarkerColor?: string;
+  /** @internal Hyperlink carried as cell metadata; use Link instead. */
+  internal_hyperlink?: string;
+  /**
+   * @internal Faint/dim text — SGR 2. Intentionally NOT a public style prop:
+   * the design system is token-first, so reach for a semantic token
+   * (`$fg-muted`, `$muted`, …) instead. This escape hatch exists only for
+   * chrome on surfaces with no matching token tier (e.g. dimmed text on the
+   * `$bg-inverse` band). Prefer tokens everywhere a token exists. Inherited by
+   * nested `<Text>`; a child's explicit value wins.
+   */
+  internal_dim?: boolean;
   /** Internal transform function applied to each rendered line. Used by Transform component. */
   internal_transform?: (line: string, index: number) => string;
   /**
@@ -2142,6 +2402,16 @@ interface TextProps extends StyleProps, TextFlexItemProps, TestProps, MouseEvent
    * global mode (`SILVERY_BG_CONFLICT`, default `"throw"`).
    */
   bgConflict?: "ignore" | "warn" | "throw";
+  /**
+   * Semantic mouse cursor for this text hit-test region.
+   *
+   * Uses the same resolver as `BoxProps.mouseCursor`: explicit hovered
+   * regions win, activation ancestors derive `"pointer"`, and selectable text
+   * derives `"text"`. Pass `"default"` to opt out of those defaults.
+   *
+   * @default Derived from interaction semantics.
+   */
+  mouseCursor?: MouseCursorShape;
 }
 /**
  * The core Silvery node - represents an element in the render tree.
@@ -2465,6 +2735,146 @@ interface EventSource {
   [Symbol.asyncIterator](): AsyncIterator<Event>;
 }
 //#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;
+  /**
+   * Handle a mounted node's props/state being updated.
+   * If the active focus target is no longer focusable or has become hidden,
+   * clear focus so focused-element input dispatch falls back to host handlers.
+   * Symmetrically, if VIRTUAL focus is pending (`activeId` set, no
+   * `activeElement`) and this update made the matching node focusable, promote
+   * it to real focus (Law 3 — looks-focused ≡ receives-input; 20992 f2).
+   */
+  handleNodeUpdated(updatedNode: AgNode): void;
+  /**
+   * Handle a subtree being ATTACHED to the tree (commit-phase mount or move).
+   * If virtual focus is pending and the subtree carries a focusable node whose
+   * testID matches `activeId`, promote it to real focus — the intent landed
+   * before the node existed, and no consumer retry should be needed (the hab
+   * 20989 looks-focused-but-no-input class; 20992 f2). O(1) unless virtual
+   * focus is actually pending.
+   */
+  handleSubtreeAttached(attachedRoot: 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/ag-term/src/mouse.d.ts
 /**
  * SGR mouse event parsing (mode 1006) and SGR-Pixels parsing (mode 1016).
@@ -2503,8 +2913,18 @@ interface ParsedMouse {
   coordinateMode: "cell" | "pixel";
   /** Event action */
   action: "down" | "up" | "move" | "wheel";
-  /** Wheel delta: -1 for up, +1 for down */
+  /**
+   * Vertical wheel delta (deltaY): -1 for wheel-up, +1 for wheel-down, 0 for a
+   * pure-horizontal wheel. DOM-style sign convention (down is positive).
+   */
   delta?: number;
+  /**
+   * Horizontal wheel delta (deltaX): -1 for wheel-left, +1 for wheel-right, 0
+   * for a pure-vertical wheel. DOM-style sign convention (right is positive).
+   * SGR buttons 66 (left) / 67 (right) decode here; consumers that only read
+   * `delta`/`deltaY` are unaffected.
+   */
+  deltaX?: number;
   /** Shift was held */
   shift: boolean;
   /** Alt/Meta was held */
@@ -2675,12 +3095,22 @@ interface TermEmulatorBackend {
  * @packageDocumentation
  */
 /**
- * RGB color value (0-255 per channel).
+ * RGB color value (0-255 per channel), with optional palette provenance.
+ *
+ * `r`/`g`/`b` are always present and resolved — painters read them
+ * unconditionally. `index` optionally preserves the origin 256-color palette
+ * slot (0-255) when the color came from an indexed entry (`ansi256(N)`, or an
+ * engine cell carrying identity-preserving color); only identity-aware code
+ * (differs, re-emitters, comparators) touches it. This shape is structurally
+ * compatible with termless's `Color = { r, g, b, index? }` — the two are
+ * compared by shape, never imported across the silvery↔termless boundary.
  */
 interface RGB {
   r: number;
   g: number;
   b: number;
+  /** Origin 256-color palette slot (0-255), when the color was indexed. */
+  index?: number;
 }
 /**
  * A single cell in a TextFrame with resolved styling.
@@ -2746,13 +3176,6 @@ interface TextFrame {
 }
 //#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
@@ -2790,8 +3213,11 @@ interface CellAttrs {
 }
 /**
  * Color representation.
- * - number: 256-color index (0-255)
- * - RGB object: true color
+ * - number: 256-color index (0-255) — silvery's compact indexed form
+ * - RGB object: true color; may carry `index` to preserve palette provenance
+ *   (identity-preserving color — the shape the terminal-flow engine produces).
+ *   When `index` is a valid 0-255 slot it is honored ahead of r/g/b, so the
+ *   color packs and re-emits as indexed SGR rather than a truecolor bake.
  * - null: default/inherit
  * - DEFAULT_BG: terminal's default background (SGR 49), opaque but uses terminal's own bg color
  */
@@ -2799,6 +3225,7 @@ type Color = number | {
   r: number;
   g: number;
   b: number;
+  index?: number;
 } | null;
 /**
  * A single cell in the terminal buffer.
@@ -2865,6 +3292,19 @@ interface RowMetadata {
   softWrapped: boolean;
   /** Rightmost column with non-space content (for trailing space trimming) */
   lastContentCol: number;
+  /**
+   * Only meaningful when `softWrapped` is true. Records whether the soft-wrap
+   * break to the next row consumed a whitespace character (word wrap) versus a
+   * forced mid-word break (a token longer than the line, or `wrap="hard"`).
+   *
+   * `trim`-mode rendering (the default) strips the breaking space from BOTH
+   * rows, so copy extraction must reinsert exactly one separator when rejoining
+   * the visual rows into their logical line: a single space when
+   * `wrapJoinSpace` is true, nothing when it is false/undefined. Without this,
+   * "alpha beta gamma"+"delta" rejoins as "alpha beta gammadelta" (lost space)
+   * and "verylong"+"word" would gain a spurious space.
+   */
+  wrapJoinSpace?: boolean;
 }
 /**
  * Efficient terminal cell buffer.
@@ -3112,6 +3552,18 @@ declare class TerminalBuffer {
    * the runtime's prevBuffer skipped intermediate buffers).
    */
   markAllRowsDirty(): void;
+  /**
+   * Mark a single row as dirty (no-op if out of bounds).
+   *
+   * Used by the managed-caret overlay-clear path: when a composited caret is
+   * suppressed or moves off a row whose CONTENT is otherwise static (and thus
+   * clean in this incremental buffer), the prior caret's row must be made dirty
+   * so `diffBuffers` re-scans it and clears the stale `inverse` overlay cell.
+   * Without this, the dirty-row gate (`diffBuffers`: `if (!next.isRowDirty(y))
+   * continue`) skips the row and the prior frame's reverse-video block strands
+   * on screen — the @km/code/v0.2/19702 cursor-above-composer signature.
+   */
+  markRowDirty(y: number): void;
   /**
    * Check if two cells at given positions are equal.
    * Used for diffing.
@@ -3138,6 +3590,105 @@ declare class TerminalBuffer {
    */
   rowExtrasEquals(y: number, other: TerminalBuffer): boolean;
 }
+/**
+ * Convert a terminal buffer to plain text (no ANSI codes).
+ * Useful for snapshot testing and text-based assertions.
+ *
+ * @param buffer The buffer to convert
+ * @param options.trimTrailingWhitespace Remove trailing spaces from each line (default: true)
+ * @param options.trimEmptyLines Remove trailing empty lines (default: true)
+ * @returns Plain text representation of the buffer
+ */
+declare function bufferToText(buffer: TerminalBuffer, options?: {
+  trimTrailingWhitespace?: boolean;
+  trimEmptyLines?: boolean;
+}): string;
+/**
+ * Convert a terminal buffer to styled ANSI text.
+ * Unlike bufferToAnsi, this doesn't include cursor control sequences,
+ * making it suitable for displaying in terminals or saving to files.
+ *
+ * @param buffer The buffer to convert
+ * @param options.trimTrailingWhitespace Remove trailing spaces from each line (default: true)
+ * @param options.trimEmptyLines Remove trailing empty lines (default: true)
+ * @returns ANSI-styled text (no cursor control)
+ */
+declare function bufferToStyledText(buffer: TerminalBuffer, options?: {
+  trimTrailingWhitespace?: boolean;
+  trimEmptyLines?: boolean;
+  colorLevel?: ColorLevel;
+}): string;
+/**
+ * Convert a terminal buffer to a full HTML document.
+ * Suitable for rendering as a screenshot via headless browser.
+ *
+ * @param buffer The buffer to convert
+ * @param options.fontFamily CSS font-family (default: 'JetBrains Mono, Menlo, monospace')
+ * @param options.fontSize CSS font-size in px (default: 14)
+ * @param options.theme Color scheme (default: 'dark')
+ * @returns Complete HTML document string
+ */
+declare function bufferToHTML(buffer: TerminalBuffer, options?: {
+  fontFamily?: string;
+  fontSize?: number;
+  theme?: "dark" | "light";
+}): string;
+//#endregion
+//#region packages/ag-term/src/ansi/notification.d.ts
+type NotificationUrgency = "low" | "normal" | "critical";
+/** Target-neutral action shown alongside a desktop notification. */
+interface NotificationAction {
+  /** Stable application-owned id returned by activation events. */
+  readonly id: string;
+  readonly label: string;
+}
+/** Protocol-neutral notification data accepted by a Term. */
+interface NotificationRequest {
+  /** Stable identifier used by protocols that support replacement. */
+  readonly id?: string;
+  readonly title?: string;
+  readonly body: string;
+  readonly urgency?: NotificationUrgency;
+  /** Optional actions. The terminal target supports these only through OSC 99. */
+  readonly actions?: readonly NotificationAction[];
+  /** Ask the target to report a click on the notification itself. */
+  readonly reportActivation?: boolean;
+}
+type NotificationUnsupportedReason = "notifications" | "notification-actions" | "notification-activation";
+/** Target-neutral delivery result shared by terminal and future DOM targets. */
+type NotificationDelivery = {
+  readonly status: "emitted";
+} | {
+  readonly status: "unsupported";
+  readonly reason: NotificationUnsupportedReason;
+};
+/** Terminal refinement that preserves exact protocol evidence for Term callers. */
+type TerminalNotificationDelivery = {
+  readonly status: "emitted";
+  readonly protocol: TerminalNotificationProtocol;
+} | {
+  readonly status: "unsupported";
+  readonly reason: NotificationUnsupportedReason;
+};
+/** Target-neutral activation projected from the target's native reply. */
+type NotificationActivation = {
+  readonly id: string;
+  readonly kind: "notification";
+} | {
+  readonly id: string;
+  readonly kind: "action";
+  readonly actionId: string;
+};
+/** Cross-target notification capability. A future DOM target implements this same shape. */
+interface NotificationTarget {
+  notify(request: NotificationRequest): NotificationDelivery;
+  onNotificationActivation(handler: (event: NotificationActivation) => void): () => void;
+}
+/** OSC 99 reply after protocol parsing, before domain action-id projection. */
+interface TerminalNotificationActivation {
+  readonly id: string;
+  readonly button?: number;
+}
 //#endregion
 //#region packages/signals/src/index.d.ts
 /**
@@ -3228,6 +3779,23 @@ interface Modes extends Disposable {
   readonly mouse: Signal<MouseTrackingMode>;
   /** Focus-in / focus-out reporting (DEC 1004). */
   readonly focusReporting: Signal<boolean>;
+  /**
+   * Disable DEC private mode 1007 (alternate-scroll) with `CSI ?1007l`.
+   *
+   * Alternate-scroll makes the terminal translate wheel events into cursor
+   * (arrow) keys while the alternate screen is active and mouse tracking is
+   * OFF. For a silvery app that deliberately turned mouse tracking off, those
+   * synthesized arrows move the cursor/selection on every wheel tick — the
+   * recurring "wheel jumps the cursor" bug. Disabling 1007 turns the wheel
+   * into a benign no-op instead.
+   *
+   * One-way by design, unlike the callable-signal modes above: we emit
+   * `?1007l` at most once and never re-enable on dispose. 1007's prior state
+   * is unknowable (we never query it), so a blind `?1007h` on teardown could
+   * wrongly enable a mode the user had off; and it is moot once we leave the
+   * alt screen, which is where 1007 has any effect. Idempotent across calls.
+   */
+  disableAlternateScroll(): void;
   /**
    * Enable a mode and return a `Disposable` that restores the mode to its
    * prior value on disposal. Complements the per-mode signals for callers
@@ -3329,6 +3897,13 @@ interface InputOwner extends Disposable {
    * unsubscribe function.
    */
   onFocus(handler: (event: FocusEvent) => void): () => void;
+  /** Subscribe to parsed OSC 99 activation replies. */
+  onNotificationActivationReply(handler: (event: TerminalNotificationActivation) => void): () => void;
+  /**
+   * Inject raw terminal input through the canonical parser. Emulator-backed
+   * Terms use this instead of maintaining a second protocol parser.
+   */
+  sendRaw(data: string | Buffer): void;
   /**
    * Inject a synthetic key event. Used by emulator-backed terms
    * (`createTerm({ cols, rows, emulator })`) and test helpers to fan out to
@@ -3365,11 +3940,12 @@ interface InputOwnerOptions {
   /**
    * 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.
+   * set for a caller-managed handoff.
    *
-   * Use this when the owner is the pre-session probe window AND a follow-up
-   * stdin consumer will re-set raw=true immediately.
+   * Silvery's runtime does not use this escape hatch: probes and normal input
+   * share one owner instead. Removing a listener while raw mode remains set
+   * creates an ownerless interval unless the caller supplies stronger atomic
+   * handoff machinery than Node streams provide.
    */
   retainRawModeOnDispose?: boolean;
   /**
@@ -3831,7 +4407,7 @@ readonly [K in ChalkStyleName]: StyleChain } & {
  * await run(<App />, term)
  * ```
  */
-interface Term extends Disposable, StyleChain {
+interface Term extends Disposable, StyleChain, NotificationTarget {
   /**
    * Terminal capabilities profile.
    *
@@ -3894,7 +4470,7 @@ interface Term extends Disposable, StyleChain {
   /**
    * 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.
+   * and its typed key/mouse/paste/focus subscriptions for normal input.
    *
    * Replaces direct `process.stdin.setRawMode` / `stdin.on('data', …)` —
    * those patterns race under async (the 2026-04-22 wasRaw class).
@@ -3994,6 +4570,10 @@ interface Term extends Disposable, StyleChain {
    * Write string to stdout.
    */
   write(str: string): void;
+  /** Emit a desktop notification through the capability-proven protocol. */
+  notify(request: NotificationRequest): TerminalNotificationDelivery;
+  /** Subscribe to target-neutral notification and action activations. */
+  onNotificationActivation(handler: (event: NotificationActivation) => void): () => void;
   /**
    * Write string followed by newline to stdout.
    */
@@ -4102,136 +4682,14 @@ declare function createTerm(emulator: TermEmulator, opts?: {
 //#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;
+//#region packages/headless/src/selection.d.ts
+interface SelectionPosition {
+  col: number;
+  row: number;
 }
-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;
+interface SelectionRange {
+  anchor: SelectionPosition;
+  head: SelectionPosition;
 }
 /**
  * Rectangular boundary for scoped selection.
@@ -4257,162 +4715,23 @@ interface TerminalSelectionState {
   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.
- */
+//#region packages/ag-term/src/bound-term.d.ts
 /**
- * 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).
+ * BoundTerm interface - terminal with node awareness
  */
-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;
+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;
 }
-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
 /**
@@ -4552,89 +4871,171 @@ declare const Z_INDEX: {
   readonly TOOLTIP: 200;
 };
 //#endregion
-//#region packages/ag-term/src/hit-registry.d.ts
+//#region packages/ag-term/src/mouse-events.d.ts
 /**
- * Context for accessing the HitRegistry.
- * Components use this to register their hit regions.
+ * 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 const HitRegistryContext: _$react.Context<HitRegistry | null>;
+declare function createMouseEvent(type: SilveryMouseEvent["type"], x: number, y: number, target: AgNode, parsed: ParsedMouse, keyboardMods?: KeyboardModifierState): SilveryMouseEvent;
 /**
- * Hook to get the HitRegistry from context.
- *
- * @returns The HitRegistry instance, or null if not in a HitRegistryContext
+ * Create a synthetic wheel event.
  */
-declare function useHitRegistry(): HitRegistry | null;
+declare function createWheelEvent(x: number, y: number, target: AgNode, parsed: ParsedMouse, keyboardMods?: KeyboardModifierState): SilveryWheelEvent;
 /**
- * Hook to register a hit region based on component's screen position.
+ * Tree-based hit test: find the deepest node whose scrollRect contains (x, y).
  *
- * Automatically registers on mount and when position changes,
- * and unregisters on unmount.
+ * Uses reverse child order (last sibling wins = highest z-order, like DOM).
+ * Respects overflow:hidden clipping and pointerEvents="none".
  *
- * @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)
+ * ### Absolute-positioned nodes escape parent bounds
  *
- * @example
- * ```tsx
- * function Card({ nodeId }: { nodeId: string }) {
- *   const rect = useScrollRect();
+ * 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.
  *
- *   useHitRegion(
- *     { type: 'node', nodeId },
- *     rect,
- *     10 // z-index for cards
- *   );
+ * 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.
  *
- *   return <Box>...</Box>;
- * }
- * ```
+ * 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 useHitRegion(target: HitTarget, rect: Rect | null, zIndex?: number, enabled?: boolean): void;
+declare function hitTest(node: AgNode, x: number, y: number): AgNode | null;
 /**
- * Hook to register a hit region using a callback for screen position.
+ * Dispatch a mouse event through the render tree with DOM-style bubbling.
  *
- * Similar to useHitRegion but works with useScrollRect for
- * better performance in large lists (avoids re-renders).
+ * 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.
  *
- * @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
+ * 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).
  *
- * @example
- * ```tsx
- * function Card({ nodeId }: { nodeId: string }) {
- *   const onLayout = useHitRegionCallback(
- *     { type: 'node', nodeId },
- *     10 // z-index
- *   );
+ * `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`.
  *
- *   useScrollRect(onLayout);
+ * @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.
  *
- *   return <Box>...</Box>;
- * }
- * ```
+ * 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 useHitRegionCallback(target: HitTarget, zIndex?: number, enabled?: boolean): (rect: Rect) => void;
-//#endregion
-//#region packages/ag-term/src/bound-term.d.ts
+declare function computeEnterLeave(prevPath: AgNode[], nextPath: AgNode[]): {
+  entered: AgNode[];
+  left: AgNode[];
+};
 /**
- * BoundTerm interface - terminal with node awareness
+ * Options for creating a mouse event processor.
  */
-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;
+interface MouseEventProcessorOptions {
+  /** Optional focus manager — enables click-to-focus behavior.
+   *  On mousedown, the deepest focusable ancestor of the hit target is focused. */
+  focusManager?: FocusManager;
+  /**
+   * Called when the semantic cursor resolved from the hit-test region changes.
+   * `null` means reset to the default target cursor.
+   */
+  onMouseCursorChange?: (shape: BoxProps["mouseCursor"] | null) => void;
+}
+/**
+ * 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;
+  /** Last emitted semantic mouse cursor shape. */
+  lastMouseCursor: BoxProps["mouseCursor"] | null;
+  /** Optional callback for terminal/canvas/DOM cursor sinks. */
+  onMouseCursorChange?: (shape: BoxProps["mouseCursor"] | null) => void;
 }
+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
-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
+export { bufferToHTML as $, InputHandler as $t, SignalOnOptions as A, IslandSignalsOwner as An, Placement as At, Modes as B, SilveryMouseEvent as Bt, createTerm as C, IslandMouseEvent as Cn, Decoration as Ct, createConsole as D, IslandPalettePolicy as Dn, InteractiveState as Dt, ConsoleStats as E, IslandPaletteOwner as En, FocusEvent$1 as Et, InputOwnerOptions as F, ViewportProps as Fn, TextProps as Ft, NotificationRequest as G, FocusEventProps as Gt, NotificationAction as H, LayoutNode as Ht, createInputOwner as I, ViewportRect as In, TextTruncateHook as It, NotificationUrgency as J, createFocusEvent as Jt, NotificationTarget as K, SilveryFocusEvent as Kt, CreateModesOptions as L, ViewportRef as Ln, TextTruncateResult as Lt, Signals as M, CellBuffer as Mn, ResizeEvent as Mt, createSignals as N, ForeignSource as Nn, SignalEvent as Nt, CreateSignalsOptions as O, IslandProtocolModes as On, KeyEvent$1 as Ot, InputOwner as P, ViewportPalette as Pn, TextMeasure as Pt, UnderlineStyle as Q, CODE_TO_KEY as Qt, KittyFlags as R, UserSelect as Rt, Term as S, IslandModesOwner as Sn, CustomEvent as St, ConsoleCaptureOptions as T, IslandOutputOwner as Tn, EventSource as Tt, NotificationActivation as U, MeasureFunc as Ut, createModes as V, SilveryWheelEvent as Vt, NotificationDelivery as W, MeasureMode as Wt, Style as X, dispatchFocusEvent as Xt, Cell as Y, createKeyEvent as Yt, TerminalBuffer as Z, dispatchKeyEvent as Zt, BoundTerm as _, IslandHandle as _n, BlurEvent as _t, createDoubleClickState as a, keyToKittyAnsi as an, ParseMouseOptions as at, term as b, IslandInputOwner as bn, CollisionStrategy as bt, createWheelEvent as c, matchHotkey as cn, parseMouseSequence as ct, processMouseEvent as d, parseKeypress as dn, FocusManagerOptions as dt, Key as en, bufferToStyledText as et, HitRegion as f, IslandCapabilities as fn, FocusOrigin as ft, resetHitRegionIdCounter as g, IslandGuest as gn, AgNodeType as gt, Z_INDEX as h, IslandCursorState as hn, AgNode as ht, computeEnterLeave as i, keyToAnsi as in, ConsoleEntry as it, SignalUnregister as j, IslandSizeOwner as jn, Rect as jt, SignalName as k, IslandSignal as kn, MouseEvent as kt, dispatchMouseEvent as l, parseHotkey as ln, FocusChangeCallback as lt, HitTarget as m, IslandContext as mn, createFocusManager as mt, MouseEventProcessorState as n, ParsedKeypress as nn, FrameCell as nt, createMouseEvent as o, keyToModifiers as on, ParsedMouse as ot, HitRegistry as p, IslandCommandPrefix as pn, FocusSnapshot as pt, NotificationUnsupportedReason as q, SilveryKeyEvent as qt, checkDoubleClick as r, emptyKey as rn, TextFrame as rt, createMouseEventProcessor as s, keyToName as sn, isMouseSequence as st, MouseEventProcessorOptions as t, ParsedHotkey as tn, bufferToText as tt, hitTest as u, parseKey as un, FocusManager as ut, SelectionRange as v, IslandHydrate as vn, BoxProps as vt, Console as w, IslandNodeState as wn, Event as wt, StyleChain as x, IslandKeyEvent as xn, CursorShape as xt, TerminalSelectionState as y, IslandInputEvent as yn, Cell$1 as yt, ModeName as z, MouseEventProps as zt };
+//# sourceMappingURL=mouse-events-B2z5tbsL.d.mts.map