@askdkc/dsh-cli 0.11.3

package/lib/types/ink/frame.d.ts

@@ -0,0 +1,128 @@
+import type { Cursor } from './cursor.js';
+import type { Size } from './layout/geometry.js';
+import type { ScrollHint } from './render-node-to-output.js';
+import type { TerminalImagePlacement } from './terminal-image.js';
+import { type CharPool, type HyperlinkPool, type Screen, type StylePool } from './screen.js';
+/**
+ * A complete rendered frame: the painted screen buffer plus the viewport
+ * size and cursor position for this render.
+ */
+export type Frame = {
+    readonly screen: Screen;
+    readonly viewport: Size;
+    readonly cursor: Cursor;
+    /** Terminal graphics requested by laid-out image nodes in this frame. */
+    readonly images?: readonly TerminalImagePlacement[];
+    /** DECSTBM scroll optimization hint (alt-screen only, null otherwise). */
+    readonly scrollHint?: ScrollHint | null;
+    /** A ScrollBox has remaining pendingScrollDelta — schedule another frame. */
+    readonly scrollDrainPending?: boolean;
+    /**
+     * An absolute overlay shrank/moved this frame and vacated cells were
+     * blitted stale from prevScreen: the NEXT frame must render without
+     * prevScreen (full re-derive) and be scheduled explicitly.
+     */
+    readonly poisonNextFrame?: boolean;
+};
+/**
+ * Create an empty frame with a zero-size screen, the given viewport, and a
+ * visible cursor at the origin.
+ * @param rows - the viewport height in rows.
+ * @param columns - the viewport width in columns.
+ * @param stylePool - the style pool backing the new screen.
+ * @param charPool - the character pool backing the new screen.
+ * @param hyperlinkPool - the hyperlink pool backing the new screen.
+ * @returns a frame with an empty screen and the given viewport.
+ */
+export declare function emptyFrame(rows: number, columns: number, stylePool: StylePool, charPool: CharPool, hyperlinkPool: HyperlinkPool): Frame;
+/** The reason a full screen clear is triggered: viewport resize, content overflowing the terminal, or an explicit clear. */
+export type FlickerReason = 'resize' | 'offscreen' | 'clear';
+/**
+ * Timing and flicker telemetry for one rendered frame, reported through
+ * the onFrame option when frame-timing instrumentation is enabled.
+ */
+export type FrameEvent = {
+    durationMs: number;
+    /** Phase breakdown in ms + patch count. Populated when the ink instance
+     *  has frame-timing instrumentation enabled (via onFrame wiring). */
+    phases?: {
+        /** createRenderer output: DOM → yoga layout → screen buffer */
+        renderer: number;
+        /** LogUpdate.render(): screen diff → Patch[] (the hot path this PR optimizes) */
+        diff: number;
+        /** optimize(): patch merge/dedupe */
+        optimize: number;
+        /** writeDiffToTerminal(): serialize patches → ANSI → stdout */
+        write: number;
+        /** Pre-optimize patch count (proxy for how much changed this frame) */
+        patches: number;
+        /** yoga calculateLayout() time (runs in resetAfterCommit, before onRender) */
+        yoga: number;
+        /** React reconcile time: scrollMutated → resetAfterCommit. 0 if no commit. */
+        commit: number;
+        /** layoutNode() calls this frame (recursive, includes cache-hit returns) */
+        yogaVisited: number;
+        /** measureFunc (text wrap/width) calls — the expensive part */
+        yogaMeasured: number;
+        /** early returns via _hasL single-slot cache */
+        yogaCacheHits: number;
+        /** total yoga Node instances alive (create - free). Growth = leak. */
+        yogaLive: number;
+    };
+    flickers: Array<{
+        desiredHeight: number;
+        availableHeight: number;
+        reason: FlickerReason;
+    }>;
+};
+/** A single terminal write operation emitted for one frame. */
+export type Patch = {
+    type: 'stdout';
+    content: string;
+} | {
+    type: 'clear';
+    count: number;
+} | {
+    type: 'clearTerminal';
+    reason: FlickerReason;
+    debug?: {
+        triggerY: number;
+        prevLine: string;
+        nextLine: string;
+    };
+} | {
+    type: 'cursorHide';
+} | {
+    type: 'cursorShow';
+} | {
+    type: 'cursorMove';
+    x: number;
+    y: number;
+} | {
+    type: 'cursorTo';
+    col: number;
+} | {
+    type: 'carriageReturn';
+} | {
+    type: 'hyperlink';
+    uri: string;
+} | {
+    type: 'styleStr';
+    str: string;
+};
+/** The ordered list of patches that update the terminal for one frame. */
+export type Diff = Patch[];
+/**
+ * Determines whether the screen should be cleared based on the current and previous frame.
+ * Returns the reason for clearing, or undefined if no clear is needed.
+ *
+ * Screen clearing is triggered when:
+ * 1. Terminal has been resized (viewport dimensions changed) → 'resize'
+ * 2. Current frame screen height exceeds available terminal rows → 'offscreen'
+ * 3. Previous frame screen height exceeded available terminal rows → 'offscreen'
+ * @param prevFrame - the previously rendered frame.
+ * @param frame - the frame about to be rendered.
+ * @returns the clearing reason, or undefined when no clear is needed.
+ */
+export declare function shouldClearScreen(prevFrame: Frame, frame: Frame): FlickerReason | undefined;
+//# sourceMappingURL=frame.d.ts.map

package/lib/types/ink/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../../src/ink/frame.ts"],"names":[],"mappings":"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"}

package/lib/types/ink/frame.js

@@ -0,0 +1,43 @@
+import { createScreen, } from './screen.js';
+/**
+ * Create an empty frame with a zero-size screen, the given viewport, and a
+ * visible cursor at the origin.
+ * @param rows - the viewport height in rows.
+ * @param columns - the viewport width in columns.
+ * @param stylePool - the style pool backing the new screen.
+ * @param charPool - the character pool backing the new screen.
+ * @param hyperlinkPool - the hyperlink pool backing the new screen.
+ * @returns a frame with an empty screen and the given viewport.
+ */
+export function emptyFrame(rows, columns, stylePool, charPool, hyperlinkPool) {
+    return {
+        screen: createScreen(0, 0, stylePool, charPool, hyperlinkPool),
+        viewport: { width: columns, height: rows },
+        cursor: { x: 0, y: 0, visible: true },
+    };
+}
+/**
+ * Determines whether the screen should be cleared based on the current and previous frame.
+ * Returns the reason for clearing, or undefined if no clear is needed.
+ *
+ * Screen clearing is triggered when:
+ * 1. Terminal has been resized (viewport dimensions changed) → 'resize'
+ * 2. Current frame screen height exceeds available terminal rows → 'offscreen'
+ * 3. Previous frame screen height exceeded available terminal rows → 'offscreen'
+ * @param prevFrame - the previously rendered frame.
+ * @param frame - the frame about to be rendered.
+ * @returns the clearing reason, or undefined when no clear is needed.
+ */
+export function shouldClearScreen(prevFrame, frame) {
+    const didResize = frame.viewport.height !== prevFrame.viewport.height ||
+        frame.viewport.width !== prevFrame.viewport.width;
+    if (didResize) {
+        return 'resize';
+    }
+    const currentFrameOverflows = frame.screen.height >= frame.viewport.height;
+    const previousFrameOverflowed = prevFrame.screen.height >= prevFrame.viewport.height;
+    if (currentFrameOverflows || previousFrameOverflowed) {
+        return 'offscreen';
+    }
+    return undefined;
+}

package/lib/types/ink/geometry-trace.d.ts

@@ -0,0 +1,51 @@
+export type FrameCause = 'react-commit' | 'animation' | 'scroll' | 'scroll-drain' | 'overlay-shrink' | 'measure' | 'resize' | 'reanchor' | 'immediate';
+export declare const GEOMETRY_TRACE_ENABLED: boolean;
+export type ScrollGeometryNote = {
+    sticky: boolean;
+    shrunk: boolean;
+    grew: boolean;
+    atBottom: boolean;
+    /** scrollTop captured before at-bottom follow (the user's logical view). */
+    scrollTopBeforeFollow: number;
+    /** scrollTop after pendingScrollDelta drain, before clamps. */
+    cur: number;
+    /** scrollTop written back to the DOM node (post follow/drain, pre virtual clamp). */
+    scrollTop: number;
+    /** What actually gets painted this frame (post cMin/cMax virtual clamp). */
+    renderScrollTop: number;
+    scrollHeight: number;
+    prevScrollHeight: number;
+    innerHeight: number;
+    maxScroll: number;
+    prevMaxScroll: number;
+    clampMin: number | null;
+    clampMax: number | null;
+};
+export type ListGeometryNote = {
+    start: number;
+    end: number;
+    topPad: number;
+    bottomPad: number;
+    /** Estimated total content height from cached row heights. */
+    total: number;
+    base: number;
+    sticky: boolean;
+    pending: number;
+    viewport: number;
+    termRows: number;
+    columns: number;
+    rowCount: number;
+};
+/** Tag the origin of the next painted frame. First note in the window wins. */
+export declare function noteFrameCause(cause: FrameCause): void;
+/** Renderer-side note, one per ScrollBox encountered during the paint. */
+export declare function noteScrollGeometry(note: ScrollGeometryNote): void;
+/** React-side note from MessageList's virtualization pass (latest wins). */
+export declare function noteListGeometry(note: ListGeometryNote): void;
+/** Scalar forensics (PromptInput content rows, …). Latest wins. */
+export declare function noteAuxNumber(key: string, value: number): void;
+/** Paint begins: just tag the frame id — inter-frame notes belong to it. */
+export declare function beginGeometryFrame(frame: number): void;
+/** Paint ends: flush one JSON line and reset the inter-frame window. */
+export declare function endGeometryFrame(durationMs: number): void;
+//# sourceMappingURL=geometry-trace.d.ts.map

package/lib/types/ink/geometry-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry-trace.d.ts","sourceRoot":"","sources":["../../../src/ink/geometry-trace.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,WAAW,GACX,QAAQ,GACR,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,QAAQ,GACR,UAAU,GACV,WAAW,CAAA;AAEf,eAAO,MAAM,sBAAsB,SACQ,CAAA;AAI3C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,EAAE,OAAO,CAAA;IACjB,4EAA4E;IAC5E,qBAAqB,EAAE,MAAM,CAAA;IAC7B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAA;IACX,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAkBD,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAGtD;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAGjE;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAG7D;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG9D;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAmBzD"}

package/lib/types/ink/geometry-trace.js

@@ -0,0 +1,83 @@
+/**
+ * Geometry forensics — per-frame scroll-geometry trace (issues #421/#433).
+ *
+ * `DSH_TUI_GEOMETRY_TRACE=<file>` appends one JSON line per painted frame:
+ * the frame's trigger cause, every ScrollBox's resolved geometry (scrollTop
+ * before/after follow + drain + virtual clamp, scrollHeight/maxScroll
+ * prev/cur, sticky/shrunk/grew flags, clamp bounds), the MessageList
+ * virtualization window, and aux counters (e.g. PromptInput content rows).
+ *
+ * Zero overhead when the env is unset: every entry point returns on a
+ * module-const boolean, so the disabled path is a single predictable branch.
+ *
+ * Ordering contract: causes and React-side notes (list geometry, aux) land
+ * BETWEEN frames — at event/commit time, before the throttled paint. The
+ * renderer adds scroll geometry during the paint; endGeometryFrame flushes
+ * and resets. First-noted cause wins (the origin of the frame chain); no
+ * note at paint time means a plain reconciler commit.
+ */
+import { appendFileSync } from 'node:fs';
+export const GEOMETRY_TRACE_ENABLED = process.env.DSH_TUI_GEOMETRY_TRACE !== undefined &&
+    process.env.DSH_TUI_GEOMETRY_TRACE !== '';
+const TRACE_PATH = process.env.DSH_TUI_GEOMETRY_TRACE ?? '';
+let state = {
+    frame: -1,
+    cause: null,
+    scroll: [],
+    list: null,
+    aux: {}
+};
+/** Tag the origin of the next painted frame. First note in the window wins. */
+export function noteFrameCause(cause) {
+    if (!GEOMETRY_TRACE_ENABLED)
+        return;
+    if (state.cause === null)
+        state.cause = cause;
+}
+/** Renderer-side note, one per ScrollBox encountered during the paint. */
+export function noteScrollGeometry(note) {
+    if (!GEOMETRY_TRACE_ENABLED)
+        return;
+    state.scroll.push(note);
+}
+/** React-side note from MessageList's virtualization pass (latest wins). */
+export function noteListGeometry(note) {
+    if (!GEOMETRY_TRACE_ENABLED)
+        return;
+    state.list = note;
+}
+/** Scalar forensics (PromptInput content rows, …). Latest wins. */
+export function noteAuxNumber(key, value) {
+    if (!GEOMETRY_TRACE_ENABLED)
+        return;
+    state.aux[key] = value;
+}
+/** Paint begins: just tag the frame id — inter-frame notes belong to it. */
+export function beginGeometryFrame(frame) {
+    if (!GEOMETRY_TRACE_ENABLED)
+        return;
+    state.frame = frame;
+}
+/** Paint ends: flush one JSON line and reset the inter-frame window. */
+export function endGeometryFrame(durationMs) {
+    if (!GEOMETRY_TRACE_ENABLED)
+        return;
+    if (state.frame >= 0) {
+        const line = JSON.stringify({
+            t: new Date().toISOString(),
+            frame: state.frame,
+            cause: state.cause ?? 'react-commit',
+            ms: Math.round(durationMs * 10) / 10,
+            scroll: state.scroll,
+            list: state.list,
+            aux: state.aux
+        });
+        try {
+            appendFileSync(TRACE_PATH, line + '\n');
+        }
+        catch {
+            // Unwritable path etc. — forensics must never break rendering.
+        }
+    }
+    state = { frame: -1, cause: null, scroll: [], list: null, aux: {} };
+}

package/lib/types/ink/get-max-width.d.ts

@@ -0,0 +1,12 @@
+import type { LayoutNode } from './layout/node.js';
+/**
+ * Return the text constraint that produced the laid-out height. Pixel-grid
+ * rounding can widen the painted box; wrapping at that rounded width would
+ * produce fewer rows than Yoga reserved and leave blank space at the bottom.
+ * The layout engine retains this constraint through its cache-hit paths.
+ * @param yogaNode - a laid-out text node with a measure function.
+ * @returns content width, already excluding padding and border.
+ */
+declare const getMaxWidth: (yogaNode: LayoutNode) => number;
+export default getMaxWidth;
+//# sourceMappingURL=get-max-width.d.ts.map

package/lib/types/ink/get-max-width.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-max-width.d.ts","sourceRoot":"","sources":["../../../src/ink/get-max-width.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;;;;;;GAOG;AACH,QAAA,MAAM,WAAW,GAAI,UAAU,UAAU,KAAG,MAE3C,CAAA;AAED,eAAe,WAAW,CAAA"}

package/lib/types/ink/get-max-width.js

@@ -0,0 +1,12 @@
+/**
+ * Return the text constraint that produced the laid-out height. Pixel-grid
+ * rounding can widen the painted box; wrapping at that rounded width would
+ * produce fewer rows than Yoga reserved and leave blank space at the bottom.
+ * The layout engine retains this constraint through its cache-hit paths.
+ * @param yogaNode - a laid-out text node with a measure function.
+ * @returns content width, already excluding padding and border.
+ */
+const getMaxWidth = (yogaNode) => {
+    return yogaNode.getComputedMeasureWidth();
+};
+export default getMaxWidth;

package/lib/types/ink/hit-test.d.ts

@@ -0,0 +1,181 @@
+import type { DOMElement } from './dom.js';
+import type { DragEvent } from './events/drag-event.js';
+/**
+ * Find the deepest DOM element whose rendered rect contains (col, row).
+ *
+ * Uses the nodeCache populated by renderNodeToOutput — rects are in screen
+ * coordinates with all offsets (including scrollTop translation) already
+ * applied. Children are traversed in reverse so later siblings (painted on
+ * top) win. Nodes not in nodeCache (not rendered this frame, or lacking a
+ * yogaNode) are skipped along with their subtrees.
+ *
+ * Ancestor containment is NOT required: an unclipped node's children can
+ * paint (and receive hits) outside the parent's rect — negative margins
+ * (the PageMargin bleed row: the transcript gutter rail sits at the
+ * terminal edge while its ancestors end at the content column) and plain
+ * overflow. Pruning at such a node would leave the overflow region dead to
+ * the mouse. Only clipped nodes (overflow hidden/scroll) confine their
+ * subtree and prune. Each node still gates on its OWN rect, so the walk
+ * stays cheap whenever the point falls inside a clipped subtree (the
+ * transcript ScrollBox prunes everything below it).
+ *
+ * Returns the hit node even if it has no onClick — dispatchClick walks up
+ * via parentNode to find handlers.
+ * @param node - the subtree root to test.
+ * @param col - the screen column to test.
+ * @param row - the screen row to test.
+ * @returns the deepest element whose rect contains (col, row), or null.
+ */
+export declare function hitTest(node: DOMElement, col: number, row: number): DOMElement | null;
+/**
+ * Number of hitTestWithOverlays calls since the last reset (or module load).
+ * @returns the call count.
+ */
+export declare function getHitTestWithOverlaysCount(): number;
+/** Reset the hitTestWithOverlays call counter (test instrumentation). */
+export declare function resetHitTestWithOverlaysCount(): void;
+/**
+ * hitTest, but overlay-aware: absolute-positioned nodes can paint OUTSIDE
+ * every ancestor's rect (OverlayAbove's `bottom:'100%'` pickers float over
+ * the transcript), so the plain containment recursion never reaches them —
+ * a click on the picker lands in the ScrollBox's rows instead. Check the
+ * frame's absolute hit list FIRST, in reverse paint order (later = visually
+ * on top), then fall back to the in-flow tree.
+ * @param root - the tree root for the in-flow fallback.
+ * @param col - the screen column to test.
+ * @param row - the screen row to test.
+ * @returns the deepest element at (col, row), or null.
+ */
+export declare function hitTestWithOverlays(root: DOMElement, col: number, row: number): DOMElement | null;
+/**
+ * Hit-test the root at (col, row) and bubble a ClickEvent from the deepest
+ * containing node up through parentNode. Only nodes with an onClick handler
+ * fire. Stops when a handler calls stopImmediatePropagation(). Returns
+ * true if at least one onClick handler fired.
+ *
+ * Each handler call is isolated: a throwing handler is logged and the
+ * bubbling continues, so one broken onClick cannot swallow the click from
+ * its ancestors or the rest of the input batch.
+ *
+ * @param root - the tree root to hit-test.
+ * @param col - the screen column of the click.
+ * @param row - the screen row of the click.
+ * @param cellIsBlank - whether the clicked cell is blank, reported on the event.
+ * @param button - raw SGR release byte (carries shift/alt/ctrl modifier bits).
+ * @returns true when at least one onClick handler fired.
+ */
+export declare function dispatchClick(root: DOMElement, col: number, row: number, cellIsBlank?: boolean, button?: number): boolean;
+/**
+ * Hit-test the root at (col, row) and bubble a ContextMenuEvent from the
+ * deepest containing node up through parentNode. Only nodes with an
+ * onContextMenu handler fire. Stops when a handler calls
+ * stopImmediatePropagation(). Returns true if at least one onContextMenu
+ * handler fired.
+ *
+ * Unlike dispatchClick this does NOT move focus: the menu is a press-time
+ * affordance and the target's own handler decides whether focus follows.
+ * Handler isolation matches dispatchClick — a throwing handler is logged
+ * and the bubbling continues.
+ *
+ * @param root - the tree root to hit-test.
+ * @param col - the screen column of the press.
+ * @param row - the screen row of the press.
+ * @param button - raw SGR press byte (low bits 2 = right button, carries
+ *   shift/alt/ctrl modifier bits).
+ * @returns true when at least one onContextMenu handler fired.
+ */
+export declare function dispatchContextMenu(root: DOMElement, col: number, row: number, button?: number): boolean;
+/**
+ * Find the drag target at (col, row): hit-test the root (overlay-aware,
+ * like dispatchClick), then walk the ancestor chain from the deepest hit
+ * node and return the FIRST node carrying an onDragStart handler. That
+ * node is captured as the drag session target — subsequent dragmove/
+ * dragend events bubble from it even when the pointer leaves its rect.
+ *
+ * @param root - the tree root to hit-test.
+ * @param col - the screen column of the press.
+ * @param row - the screen row of the press.
+ * @returns the deepest node with an onDragStart handler, or null when no
+ *   ancestor of the hit node is a drag target.
+ */
+export declare function findDragTarget(root: DOMElement, col: number, row: number): DOMElement | null;
+/**
+ * Bubble a drag event (dragstart/dragmove/dragend) from the captured
+ * drag session target up through parentNode. The handler prop is looked
+ * up per event type (onDragStart/onDragMove/onDragEnd). Stops when a
+ * handler calls stopImmediatePropagation(). Handler isolation matches
+ * dispatchClick — a throwing handler is logged and the bubbling
+ * continues.
+ *
+ * Unlike dispatchClick the target comes from the drag session captured
+ * at press time, NOT a fresh hit-test: like DOM element capture, the
+ * drag source keeps receiving events for the whole gesture.
+ *
+ * @param target - the captured drag session target node.
+ * @param event - the drag event to dispatch.
+ */
+export declare function dispatchDragEvent(target: DOMElement, event: DragEvent): void;
+/**
+ * Fire onMouseLeave on every tracked hover node, then empty the set.
+ *
+ * The pointer-state resets (alt-screen swap, terminal resize) drop the hover
+ * set because the geometry it was computed against is gone. But the React
+ * components behind those nodes still hold their `hovered=true` state: a bare
+ * `set.clear()` never tells them the pointer "left", so every row crossed
+ * before the reset keeps its highlight forever — the next motion event only
+ * fires enter on the new row (the old nodes are no longer in the set, so no
+ * diff ever produces their leave). Firing leave first is what makes the
+ * reset invisible to the rows.
+ *
+ * @param hovered - the tracked hover set; emptied in place.
+ * @param col - pointer column for the synthetic leave events (-1 = unknown).
+ * @param row - pointer row for the synthetic leave events.
+ */
+export declare function clearHovered(hovered: Set<DOMElement>, col?: number, row?: number): void;
+/**
+ * Route a wheel event to the ScrollBox (or any onWheel handler) under the
+ * pointer. Dispatches through the shared Dispatcher at continuous priority
+ * so the event bubbles from the deepest hit node and React schedules any
+ * state updates at the right lane.
+ *
+ * @param root - the tree root to hit-test.
+ * @param col - the screen column of the wheel event.
+ * @param row - the screen row of the wheel event.
+ * @param deltaY - rows to scroll (positive = scroll down).
+ * @param deltaX - columns to scroll (positive = right; informational).
+ * @param button - raw SGR byte (carries modifier bits).
+ * @returns true when an onWheel handler existed under the pointer.
+ */
+export declare function dispatchWheel(root: DOMElement, col: number, row: number, deltaY: number, deltaX?: number, button?: number): boolean;
+/**
+ * Install or clear the hover-interest probe.
+ * @param probe - the interest predicate, or null to clear it.
+ */
+export declare function setHoverInterestProbe(probe: ((node: DOMElement) => boolean) | null): void;
+/**
+ * Drop the cached no-interest rect. Call at every render commit and at the
+ * start of every render pass (see the cache doc above); also call from
+ * pointer-state resets. Idempotent and effectively free.
+ */
+export declare function invalidateNoInterestRect(): void;
+/**
+ * Fire onMouseEnter/onMouseLeave as the pointer moves. Like DOM
+ * mouseenter/mouseleave: does NOT bubble — moving between children does
+ * not re-fire on the parent. Walks up from the hit node collecting every
+ * ancestor with a hover handler; diffs against the previous hovered set;
+ * fires leave on the nodes exited, enter on the nodes entered.
+ *
+ * Handlers receive a PointerEvent ('hover') with the pointer position;
+ * existing `() => void` handlers simply ignore the argument. Each call is
+ * isolated so one throwing handler cannot break the rest of the diff.
+ *
+ * Mutates `hovered` in place so the caller (App instance) can hold it
+ * across calls. Clears the set when the hit is null (cursor moved into a
+ * non-rendered gap or off the root rect).
+ * @param root - the tree root to hit-test.
+ * @param col - the screen column of the pointer.
+ * @param row - the screen row of the pointer.
+ * @param hovered - the previously hovered element set; updated in place.
+ */
+export declare function dispatchHover(root: DOMElement, col: number, row: number, hovered: Set<DOMElement>): void;
+//# sourceMappingURL=hit-test.d.ts.map

package/lib/types/ink/hit-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hit-test.d.ts","sourceRoot":"","sources":["../../../src/ink/hit-test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AASvD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,UAAU,GAAG,IAAI,CA8BnB;AAOD;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAEpD;AAED,yEAAyE;AACzE,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,UAAU,GAAG,IAAI,CAmBnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,WAAW,UAAQ,EACnB,MAAM,SAAI,GACT,OAAO,CA2CT;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,MAAM,SAAI,GACT,OAAO,CA8BT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,UAAU,GAAG,IAAI,CAQnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,SAAS,GACf,IAAI,CAON;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,EACxB,GAAG,SAAK,EACR,GAAG,SAAK,GACP,IAAI,CAiBN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,MAAM,SAAI,EACV,MAAM,SAAI,GACT,OAAO,CAcT;AA6BD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,IAAI,GAC5C,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAqED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,GACvB,IAAI,CA4FN"}