@deepseek-harness-tui/dsh-tui 0.5.0

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

@@ -0,0 +1,74 @@
+import type { DOMElement } from './dom.js';
+import { FocusEvent } from './events/focus-event.js';
+/**
+ * DOM-like focus manager for the Ink terminal UI.
+ *
+ * Pure state — tracks activeElement and a focus stack. Has no reference
+ * to the tree; callers pass the root when tree walks are needed.
+ *
+ * Stored on the root DOMElement so any node can reach it by walking
+ * parentNode (like browser's `node.ownerDocument`).
+ */
+export declare class FocusManager {
+    /** The element that currently has focus, or null when nothing is focused. */
+    activeElement: DOMElement | null;
+    private dispatchFocusEvent;
+    private enabled;
+    private focusStack;
+    constructor(dispatchFocusEvent: (target: DOMElement, event: FocusEvent) => boolean);
+    /**
+     * Move focus to a node.
+     * @param node - the element to focus.
+     */
+    focus(node: DOMElement): void;
+    /** Drop focus from the active element, dispatching a blur event. */
+    blur(): void;
+    /**
+     * Called by the reconciler when a node is removed from the tree.
+     * Handles both the exact node and any focused descendant within
+     * the removed subtree. Dispatches blur and restores focus from stack.
+     * @param node - the removed element.
+     * @param root - the tree root used to test whether elements are still mounted.
+     */
+    handleNodeRemoved(node: DOMElement, root: DOMElement): void;
+    /**
+     * Focus a node on mount when it requests auto-focus.
+     * @param node - the element to focus.
+     */
+    handleAutoFocus(node: DOMElement): void;
+    /**
+     * Focus a node when it is clicked, provided it carries a numeric `tabIndex`.
+     * @param node - the clicked element.
+     */
+    handleClickFocus(node: DOMElement): void;
+    /** Re-enable focus tracking after a disable. */
+    enable(): void;
+    /** Disable focus tracking: focus requests are ignored until re-enabled. */
+    disable(): void;
+    /**
+     * Move focus to the next tabbable element within the tree.
+     * @param root - the tree root whose tabbable elements are cycled.
+     */
+    focusNext(root: DOMElement): void;
+    /**
+     * Move focus to the previous tabbable element within the tree.
+     * @param root - the tree root whose tabbable elements are cycled.
+     */
+    focusPrevious(root: DOMElement): void;
+    private moveFocus;
+}
+/**
+ * Walk up to root and return it. The root is the node that holds
+ * the FocusManager — like browser's `node.getRootNode()`.
+ * @param node - the node to walk up from.
+ * @returns the nearest ancestor holding a FocusManager.
+ */
+export declare function getRootNode(node: DOMElement): DOMElement;
+/**
+ * Walk up to root and return its FocusManager.
+ * Like browser's `node.ownerDocument` — focus belongs to the root.
+ * @param node - the node to walk up from.
+ * @returns the root's FocusManager.
+ */
+export declare function getFocusManager(node: DOMElement): FocusManager;
+//# sourceMappingURL=focus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../../src/ink/focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAIpD;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,6EAA6E;IAC7E,aAAa,EAAE,UAAU,GAAG,IAAI,CAAO;IACvC,OAAO,CAAC,kBAAkB,CAAoD;IAC9E,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,UAAU,CAAmB;gBAGnC,kBAAkB,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO;IAKxE;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAiB7B,oEAAoE;IACpE,IAAI,IAAI,IAAI;IAQZ;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IA2B3D;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIvC;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAMxC,gDAAgD;IAChD,MAAM,IAAI,IAAI;IAId,2EAA2E;IAC3E,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIjC;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIrC,OAAO,CAAC,SAAS;CAsBlB;AA8BD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAOxD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,CAE9D"}

package/lib/types/ink/focus.js

@@ -0,0 +1,188 @@
+import { FocusEvent } from './events/focus-event.js';
+const MAX_FOCUS_STACK = 32;
+/**
+ * DOM-like focus manager for the Ink terminal UI.
+ *
+ * Pure state — tracks activeElement and a focus stack. Has no reference
+ * to the tree; callers pass the root when tree walks are needed.
+ *
+ * Stored on the root DOMElement so any node can reach it by walking
+ * parentNode (like browser's `node.ownerDocument`).
+ */
+export class FocusManager {
+    /** The element that currently has focus, or null when nothing is focused. */
+    activeElement = null;
+    dispatchFocusEvent;
+    enabled = true;
+    focusStack = [];
+    constructor(dispatchFocusEvent) {
+        this.dispatchFocusEvent = dispatchFocusEvent;
+    }
+    /**
+     * Move focus to a node.
+     * @param node - the element to focus.
+     */
+    focus(node) {
+        if (node === this.activeElement)
+            return;
+        if (!this.enabled)
+            return;
+        const previous = this.activeElement;
+        if (previous) {
+            // Deduplicate before pushing to prevent unbounded growth from Tab cycling
+            const idx = this.focusStack.indexOf(previous);
+            if (idx !== -1)
+                this.focusStack.splice(idx, 1);
+            this.focusStack.push(previous);
+            if (this.focusStack.length > MAX_FOCUS_STACK)
+                this.focusStack.shift();
+            this.dispatchFocusEvent(previous, new FocusEvent('blur', node));
+        }
+        this.activeElement = node;
+        this.dispatchFocusEvent(node, new FocusEvent('focus', previous));
+    }
+    /** Drop focus from the active element, dispatching a blur event. */
+    blur() {
+        if (!this.activeElement)
+            return;
+        const previous = this.activeElement;
+        this.activeElement = null;
+        this.dispatchFocusEvent(previous, new FocusEvent('blur', null));
+    }
+    /**
+     * Called by the reconciler when a node is removed from the tree.
+     * Handles both the exact node and any focused descendant within
+     * the removed subtree. Dispatches blur and restores focus from stack.
+     * @param node - the removed element.
+     * @param root - the tree root used to test whether elements are still mounted.
+     */
+    handleNodeRemoved(node, root) {
+        // Remove the node and any descendants from the stack
+        this.focusStack = this.focusStack.filter(n => n !== node && isInTree(n, root));
+        // Check if activeElement is the removed node OR a descendant
+        if (!this.activeElement)
+            return;
+        if (this.activeElement !== node && isInTree(this.activeElement, root)) {
+            return;
+        }
+        const removed = this.activeElement;
+        this.activeElement = null;
+        this.dispatchFocusEvent(removed, new FocusEvent('blur', null));
+        // Restore focus to the most recent still-mounted element
+        while (this.focusStack.length > 0) {
+            const candidate = this.focusStack.pop();
+            if (isInTree(candidate, root)) {
+                this.activeElement = candidate;
+                this.dispatchFocusEvent(candidate, new FocusEvent('focus', removed));
+                return;
+            }
+        }
+    }
+    /**
+     * Focus a node on mount when it requests auto-focus.
+     * @param node - the element to focus.
+     */
+    handleAutoFocus(node) {
+        this.focus(node);
+    }
+    /**
+     * Focus a node when it is clicked, provided it carries a numeric `tabIndex`.
+     * @param node - the clicked element.
+     */
+    handleClickFocus(node) {
+        const tabIndex = node.attributes['tabIndex'];
+        if (typeof tabIndex !== 'number')
+            return;
+        this.focus(node);
+    }
+    /** Re-enable focus tracking after a disable. */
+    enable() {
+        this.enabled = true;
+    }
+    /** Disable focus tracking: focus requests are ignored until re-enabled. */
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Move focus to the next tabbable element within the tree.
+     * @param root - the tree root whose tabbable elements are cycled.
+     */
+    focusNext(root) {
+        this.moveFocus(1, root);
+    }
+    /**
+     * Move focus to the previous tabbable element within the tree.
+     * @param root - the tree root whose tabbable elements are cycled.
+     */
+    focusPrevious(root) {
+        this.moveFocus(-1, root);
+    }
+    moveFocus(direction, root) {
+        if (!this.enabled)
+            return;
+        const tabbable = collectTabbable(root);
+        if (tabbable.length === 0)
+            return;
+        const currentIndex = this.activeElement
+            ? tabbable.indexOf(this.activeElement)
+            : -1;
+        const nextIndex = currentIndex === -1
+            ? direction === 1
+                ? 0
+                : tabbable.length - 1
+            : (currentIndex + direction + tabbable.length) % tabbable.length;
+        const next = tabbable[nextIndex];
+        if (next) {
+            this.focus(next);
+        }
+    }
+}
+function collectTabbable(root) {
+    const result = [];
+    walkTree(root, result);
+    return result;
+}
+function walkTree(node, result) {
+    const tabIndex = node.attributes['tabIndex'];
+    if (typeof tabIndex === 'number' && tabIndex >= 0) {
+        result.push(node);
+    }
+    for (const child of node.childNodes) {
+        if (child.nodeName !== '#text') {
+            walkTree(child, result);
+        }
+    }
+}
+function isInTree(node, root) {
+    let current = node;
+    while (current) {
+        if (current === root)
+            return true;
+        current = current.parentNode;
+    }
+    return false;
+}
+/**
+ * Walk up to root and return it. The root is the node that holds
+ * the FocusManager — like browser's `node.getRootNode()`.
+ * @param node - the node to walk up from.
+ * @returns the nearest ancestor holding a FocusManager.
+ */
+export function getRootNode(node) {
+    let current = node;
+    while (current) {
+        if (current.focusManager)
+            return current;
+        current = current.parentNode;
+    }
+    throw new Error('Node is not in a tree with a FocusManager');
+}
+/**
+ * Walk up to root and return its FocusManager.
+ * Like browser's `node.ownerDocument` — focus belongs to the root.
+ * @param node - the node to walk up from.
+ * @returns the root's FocusManager.
+ */
+export function getFocusManager(node) {
+    return getRootNode(node).focusManager;
+}

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

@@ -0,0 +1,119 @@
+import type { Cursor } from './cursor.js';
+import type { Size } from './layout/geometry.js';
+import type { ScrollHint } from './render-node-to-output.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;
+    /** DECSTBM scroll optimization hint (alt-screen only, null otherwise). */
+    readonly scrollHint?: ScrollHint | null;
+    /** A ScrollBox has remaining pendingScrollDelta — schedule another frame. */
+    readonly scrollDrainPending?: 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/get-max-width.d.ts

@@ -0,0 +1,20 @@
+import { type LayoutNode } from './layout/node.js';
+/**
+ * Returns the yoga node's content width (computed width minus padding and
+ * border).
+ *
+ * Warning: can return a value WIDER than the parent container. In a
+ * column-direction flex parent, width is the cross axis — align-items:
+ * stretch never shrinks children below their intrinsic size, so the text
+ * node overflows (standard CSS behavior). Yoga measures leaf nodes in two
+ * passes: the AtMost pass determines width, the Exactly pass determines
+ * height. getComputedWidth() reflects the wider AtMost result while
+ * getComputedHeight() reflects the narrower Exactly result. Callers that
+ * use this for wrapping should clamp to actual available screen space so
+ * the rendered line count stays consistent with the layout height.
+ * @param yogaNode - the laid-out node to measure.
+ * @returns the node's content width: computed width minus 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,EAAc,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,WAAW,GAAI,UAAU,UAAU,KAAG,MAQ3C,CAAA;AAED,eAAe,WAAW,CAAA"}

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

@@ -0,0 +1,25 @@
+import { LayoutEdge } from './layout/node.js';
+/**
+ * Returns the yoga node's content width (computed width minus padding and
+ * border).
+ *
+ * Warning: can return a value WIDER than the parent container. In a
+ * column-direction flex parent, width is the cross axis — align-items:
+ * stretch never shrinks children below their intrinsic size, so the text
+ * node overflows (standard CSS behavior). Yoga measures leaf nodes in two
+ * passes: the AtMost pass determines width, the Exactly pass determines
+ * height. getComputedWidth() reflects the wider AtMost result while
+ * getComputedHeight() reflects the narrower Exactly result. Callers that
+ * use this for wrapping should clamp to actual available screen space so
+ * the rendered line count stays consistent with the layout height.
+ * @param yogaNode - the laid-out node to measure.
+ * @returns the node's content width: computed width minus padding and border.
+ */
+const getMaxWidth = (yogaNode) => {
+    return (yogaNode.getComputedWidth() -
+        yogaNode.getComputedPadding(LayoutEdge.Left) -
+        yogaNode.getComputedPadding(LayoutEdge.Right) -
+        yogaNode.getComputedBorder(LayoutEdge.Left) -
+        yogaNode.getComputedBorder(LayoutEdge.Right));
+};
+export default getMaxWidth;

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

@@ -0,0 +1,47 @@
+import type { DOMElement } from './dom.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.
+ *
+ * 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;
+/**
+ * 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.
+ * @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.
+ * @returns true when at least one onClick handler fired.
+ */
+export declare function dispatchClick(root: DOMElement, col: number, row: number, cellIsBlank?: boolean): boolean;
+/**
+ * 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.
+ *
+ * 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;AAK1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,UAAU,GAAG,IAAI,CAmBnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,WAAW,UAAQ,GAClB,OAAO,CAmCT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,GACvB,IAAI,CAuBN"}

package/lib/types/ink/hit-test.js

@@ -0,0 +1,126 @@
+import { ClickEvent } from './events/click-event.js';
+import { nodeCache } from './node-cache.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.
+ *
+ * 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 function hitTest(node, col, row) {
+    const rect = nodeCache.get(node);
+    if (!rect)
+        return null;
+    if (col < rect.x ||
+        col >= rect.x + rect.width ||
+        row < rect.y ||
+        row >= rect.y + rect.height) {
+        return null;
+    }
+    // Later siblings paint on top; reversed traversal returns topmost hit.
+    for (let i = node.childNodes.length - 1; i >= 0; i--) {
+        const child = node.childNodes[i];
+        if (child.nodeName === '#text')
+            continue;
+        const hit = hitTest(child, col, row);
+        if (hit)
+            return hit;
+    }
+    return node;
+}
+/**
+ * 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.
+ * @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.
+ * @returns true when at least one onClick handler fired.
+ */
+export function dispatchClick(root, col, row, cellIsBlank = false) {
+    let target = hitTest(root, col, row) ?? undefined;
+    if (!target)
+        return false;
+    // Click-to-focus: find the closest focusable ancestor and focus it.
+    // root is always ink-root, which owns the FocusManager.
+    if (root.focusManager) {
+        let focusTarget = target;
+        while (focusTarget) {
+            if (typeof focusTarget.attributes['tabIndex'] === 'number') {
+                root.focusManager.handleClickFocus(focusTarget);
+                break;
+            }
+            focusTarget = focusTarget.parentNode;
+        }
+    }
+    const event = new ClickEvent(col, row, cellIsBlank);
+    let handled = false;
+    while (target) {
+        const handler = target._eventHandlers?.onClick;
+        if (handler) {
+            handled = true;
+            const rect = nodeCache.get(target);
+            if (rect) {
+                event.localCol = col - rect.x;
+                event.localRow = row - rect.y;
+            }
+            handler(event);
+            if (event.didStopImmediatePropagation())
+                return true;
+        }
+        target = target.parentNode;
+    }
+    return handled;
+}
+/**
+ * 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.
+ *
+ * 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 function dispatchHover(root, col, row, hovered) {
+    const next = new Set();
+    let node = hitTest(root, col, row) ?? undefined;
+    while (node) {
+        const h = node._eventHandlers;
+        if (h?.onMouseEnter || h?.onMouseLeave)
+            next.add(node);
+        node = node.parentNode;
+    }
+    for (const old of hovered) {
+        if (!next.has(old)) {
+            hovered.delete(old);
+            // Skip handlers on detached nodes (removed between mouse events)
+            if (old.parentNode) {
+                ;
+                old._eventHandlers?.onMouseLeave?.();
+            }
+        }
+    }
+    for (const n of next) {
+        if (!hovered.has(n)) {
+            hovered.add(n);
+            n._eventHandlers?.onMouseEnter?.();
+        }
+    }
+}