@deepseek-harness-tui/dsh-tui 0.5.0

package/lib/types/ink/hooks/use-animation-frame.d.ts

@@ -0,0 +1,27 @@
+import type { DOMElement } from '../dom.js';
+/**
+ * Hook for synchronized animations that pause when offscreen.
+ *
+ * Returns a ref to attach to the animated element and the current animation time.
+ * All instances share the same clock, so animations stay in sync.
+ * The clock only runs when at least one keepAlive subscriber exists.
+ *
+ * Pass `null` to pause — unsubscribes from the clock so no ticks fire.
+ * Time freezes at the last value and resumes from the current clock time
+ * when a number is passed again.
+ *
+ * @param intervalMs - How often to update, or null to pause
+ * @returns [ref, time] - Ref to attach to element, elapsed time in ms
+ *
+ * @example
+ * function Spinner() {
+ *   const [ref, time] = useAnimationFrame(120)
+ *   const frame = Math.floor(time / 120) % FRAMES.length
+ *   return <Box ref={ref}>{FRAMES[frame]}</Box>
+ * }
+ *
+ * The clock automatically slows when the terminal is blurred,
+ * so consumers don't need to handle focus state.
+ */
+export declare function useAnimationFrame(intervalMs?: number | null): [ref: (element: DOMElement | null) => void, time: number];
+//# sourceMappingURL=use-animation-frame.d.ts.map

package/lib/types/ink/hooks/use-animation-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-animation-frame.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-animation-frame.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAG3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,GAAE,MAAM,GAAG,IAAS,GAC7B,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAyB3D"}

package/lib/types/ink/hooks/use-animation-frame.js

@@ -0,0 +1,48 @@
+import { useContext, useEffect, useState } from 'react';
+import { ClockContext } from '../components/ClockContext.js';
+import { useTerminalViewport } from './use-terminal-viewport.js';
+/**
+ * Hook for synchronized animations that pause when offscreen.
+ *
+ * Returns a ref to attach to the animated element and the current animation time.
+ * All instances share the same clock, so animations stay in sync.
+ * The clock only runs when at least one keepAlive subscriber exists.
+ *
+ * Pass `null` to pause — unsubscribes from the clock so no ticks fire.
+ * Time freezes at the last value and resumes from the current clock time
+ * when a number is passed again.
+ *
+ * @param intervalMs - How often to update, or null to pause
+ * @returns [ref, time] - Ref to attach to element, elapsed time in ms
+ *
+ * @example
+ * function Spinner() {
+ *   const [ref, time] = useAnimationFrame(120)
+ *   const frame = Math.floor(time / 120) % FRAMES.length
+ *   return <Box ref={ref}>{FRAMES[frame]}</Box>
+ * }
+ *
+ * The clock automatically slows when the terminal is blurred,
+ * so consumers don't need to handle focus state.
+ */
+export function useAnimationFrame(intervalMs = 16) {
+    const clock = useContext(ClockContext);
+    const [viewportRef, { isVisible }] = useTerminalViewport();
+    const [time, setTime] = useState(() => clock?.now() ?? 0);
+    const active = isVisible && intervalMs !== null;
+    useEffect(() => {
+        if (!clock || !active)
+            return;
+        let lastUpdate = clock.now();
+        const onChange = () => {
+            const now = clock.now();
+            if (now - lastUpdate >= intervalMs) {
+                lastUpdate = now;
+                setTime(now);
+            }
+        };
+        // keepAlive: true — visible animations drive the clock
+        return clock.subscribe(onChange, true);
+    }, [clock, intervalMs, active]);
+    return [viewportRef, time];
+}

package/lib/types/ink/hooks/use-app.d.ts

@@ -0,0 +1,8 @@
+import { type Props } from '../components/AppContext.js';
+/**
+ * React hook exposing the manual app-exit function from `AppContext`.
+ * @returns the `AppContext` value, whose `exit` function unmounts the app.
+ */
+declare const useApp: () => Props;
+export default useApp;
+//# sourceMappingURL=use-app.d.ts.map

package/lib/types/ink/hooks/use-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-app.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-app.ts"],"names":[],"mappings":"AACA,OAAmB,EAAE,KAAK,KAAK,EAAE,MAAM,6BAA6B,CAAA;AAEpE;;;GAGG;AACH,QAAA,MAAM,MAAM,QAAO,KAA+B,CAAA;AAClD,eAAe,MAAM,CAAA"}

package/lib/types/ink/hooks/use-app.js

@@ -0,0 +1,8 @@
+import { useContext } from 'react';
+import AppContext from '../components/AppContext.js';
+/**
+ * React hook exposing the manual app-exit function from `AppContext`.
+ * @returns the `AppContext` value, whose `exit` function unmounts the app.
+ */
+const useApp = () => useContext(AppContext);
+export default useApp;

package/lib/types/ink/hooks/use-copy-on-select.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copy-on-select: when a drag finishes (or a double/triple click, or a
+ * shift+arrow extension, lands a selection), copy the selected text to the
+ * clipboard — OSC 52 plus the native-utility fallback — then clear the
+ * highlight so the copy reads as a completed action.
+ *
+ * Implemented as a subscription rather than a mouse-release hook so every
+ * path that settles a selection (release, lost-release recovery, focus-out
+ * recovery, multi-click, keyboard extension) funnels through the same
+ * `notifySelectionChange` and fires the copy exactly once per settle.
+ *
+ * No-op outside fullscreen: without mouse tracking no selection can ever
+ * exist, and `useSelection` returns stubs when there is no Ink instance.
+ * Mount once near the app root (e.g. Chat) — the copy itself is gated on
+ * `hasSelection`, so an always-mounted hook costs one no-op callback per
+ * selection notification.
+ * @param onCopied - called with the copied text after each successful copy
+ *   (e.g. to show a toast). Stored in a ref, so an inline closure is fine
+ *   and never re-subscribes.
+ */
+export declare function useCopyOnSelect(onCopied?: (text: string) => void): void;
+//# sourceMappingURL=use-copy-on-select.d.ts.map

package/lib/types/ink/hooks/use-copy-on-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-copy-on-select.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-copy-on-select.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAevE"}

package/lib/types/ink/hooks/use-copy-on-select.js

@@ -0,0 +1,40 @@
+import { useEffect, useRef } from 'react';
+import { hasSelection } from '../selection.js';
+import { useSelection } from './use-selection.js';
+/**
+ * Copy-on-select: when a drag finishes (or a double/triple click, or a
+ * shift+arrow extension, lands a selection), copy the selected text to the
+ * clipboard — OSC 52 plus the native-utility fallback — then clear the
+ * highlight so the copy reads as a completed action.
+ *
+ * Implemented as a subscription rather than a mouse-release hook so every
+ * path that settles a selection (release, lost-release recovery, focus-out
+ * recovery, multi-click, keyboard extension) funnels through the same
+ * `notifySelectionChange` and fires the copy exactly once per settle.
+ *
+ * No-op outside fullscreen: without mouse tracking no selection can ever
+ * exist, and `useSelection` returns stubs when there is no Ink instance.
+ * Mount once near the app root (e.g. Chat) — the copy itself is gated on
+ * `hasSelection`, so an always-mounted hook costs one no-op callback per
+ * selection notification.
+ * @param onCopied - called with the copied text after each successful copy
+ *   (e.g. to show a toast). Stored in a ref, so an inline closure is fine
+ *   and never re-subscribes.
+ */
+export function useCopyOnSelect(onCopied) {
+    const { subscribe, getState, copySelection } = useSelection();
+    const onCopiedRef = useRef(onCopied);
+    onCopiedRef.current = onCopied;
+    useEffect(() => {
+        return subscribe(() => {
+            const state = getState();
+            // Mid-drag notifications (every motion event) skip the copy; the
+            // release notification arrives with isDragging already cleared.
+            if (state && !state.isDragging && hasSelection(state)) {
+                const text = copySelection();
+                if (text)
+                    onCopiedRef.current?.(text);
+            }
+        });
+    }, [subscribe, getState, copySelection]);
+}

package/lib/types/ink/hooks/use-declared-cursor.d.ts

@@ -0,0 +1,31 @@
+import type { DOMElement } from '../dom.js';
+/**
+ * Declares where the terminal cursor should be parked after each frame.
+ *
+ * Terminal emulators render IME preedit text at the physical cursor
+ * position, and screen readers / screen magnifiers track the native
+ * cursor — so parking it at the text input's caret makes CJK input
+ * appear inline and lets accessibility tools follow the input.
+ *
+ * Returns a ref callback to attach to the Box that contains the input.
+ * The declared (line, column) is interpreted relative to that Box's
+ * nodeCache rect (populated by renderNodeToOutput).
+ *
+ * Timing: Both ref attach and useLayoutEffect fire in React's layout
+ * phase — after resetAfterCommit calls scheduleRender. scheduleRender
+ * defers onRender via queueMicrotask, so onRender runs AFTER layout
+ * effects commit and reads the fresh declaration on the first frame
+ * (no one-keystroke lag). Test env uses onImmediateRender (synchronous,
+ * no microtask), so tests compensate by calling ink.onRender()
+ * explicitly after render.
+ * @param options - the declared cursor target: `line` and `column` give the
+ *   position relative to the node, `active` controls whether the declaration
+ *   is set or cleared.
+ * @returns a ref callback to attach to the Box that contains the input.
+ */
+export declare function useDeclaredCursor(options: {
+    line: number;
+    column: number;
+    active: boolean;
+}): (element: DOMElement | null) => void;
+//# sourceMappingURL=use-declared-cursor.d.ts.map

package/lib/types/ink/hooks/use-declared-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-declared-cursor.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-declared-cursor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,CAyCvC"}

package/lib/types/ink/hooks/use-declared-cursor.js

@@ -0,0 +1,65 @@
+import { useCallback, useContext, useLayoutEffect, useRef } from 'react';
+import CursorDeclarationContext from '../components/CursorDeclarationContext.js';
+/**
+ * Declares where the terminal cursor should be parked after each frame.
+ *
+ * Terminal emulators render IME preedit text at the physical cursor
+ * position, and screen readers / screen magnifiers track the native
+ * cursor — so parking it at the text input's caret makes CJK input
+ * appear inline and lets accessibility tools follow the input.
+ *
+ * Returns a ref callback to attach to the Box that contains the input.
+ * The declared (line, column) is interpreted relative to that Box's
+ * nodeCache rect (populated by renderNodeToOutput).
+ *
+ * Timing: Both ref attach and useLayoutEffect fire in React's layout
+ * phase — after resetAfterCommit calls scheduleRender. scheduleRender
+ * defers onRender via queueMicrotask, so onRender runs AFTER layout
+ * effects commit and reads the fresh declaration on the first frame
+ * (no one-keystroke lag). Test env uses onImmediateRender (synchronous,
+ * no microtask), so tests compensate by calling ink.onRender()
+ * explicitly after render.
+ * @param options - the declared cursor target: `line` and `column` give the
+ *   position relative to the node, `active` controls whether the declaration
+ *   is set or cleared.
+ * @returns a ref callback to attach to the Box that contains the input.
+ */
+export function useDeclaredCursor(options) {
+    const { line, column, active } = options;
+    const setCursorDeclaration = useContext(CursorDeclarationContext);
+    const nodeRef = useRef(null);
+    const setNode = useCallback((node) => {
+        nodeRef.current = node;
+    }, []);
+    // When active, set unconditionally. When inactive, clear conditionally
+    // (only if the currently-declared node is ours). The node-identity check
+    // handles two hazards:
+    //   1. A memo()ized active instance elsewhere (e.g. the search input in
+    //      a memo'd Footer) doesn't re-render this commit — an inactive
+    //      instance re-rendering here must not clobber it.
+    //   2. Sibling handoff (menu focus moving between list items) — when
+    //      focus moves opposite to sibling order, the newly-inactive item's
+    //      effect runs AFTER the newly-active item's set. Without the node
+    //      check it would clobber.
+    // No dep array: must re-declare every commit so the active instance
+    // re-claims the declaration after another instance's unmount-cleanup or
+    // sibling handoff nulls it.
+    useLayoutEffect(() => {
+        const node = nodeRef.current;
+        if (active && node) {
+            setCursorDeclaration({ relativeX: column, relativeY: line, node });
+        }
+        else {
+            setCursorDeclaration(null, node);
+        }
+    });
+    // Clear on unmount (conditionally — another instance may own by then).
+    // Separate effect with empty deps so cleanup only fires once — not on
+    // every line/column change, which would transiently null between commits.
+    useLayoutEffect(() => {
+        return () => {
+            setCursorDeclaration(null, nodeRef.current);
+        };
+    }, [setCursorDeclaration]);
+    return setNode;
+}

package/lib/types/ink/hooks/use-input.d.ts

@@ -0,0 +1,41 @@
+import type { InputEvent, Key } from '../events/input-event.js';
+type Handler = (input: string, key: Key, event: InputEvent) => void;
+type Options = {
+    /**
+     * Enable or disable capturing of user input.
+     * Useful when there are multiple useInput hooks used at once to avoid handling the same input several times.
+     *
+     * @default true
+     */
+    isActive?: boolean;
+};
+/**
+ * This hook is used for handling user input.
+ * It's a more convenient alternative to using `StdinContext` and listening to `data` events.
+ * The callback you pass to `useInput` is called for each character when user enters any input.
+ * However, if user pastes text and it's more than one character, the callback will be called only once and the whole string will be passed as `input`.
+ *
+ * ```
+ * import {useInput} from 'ink';
+ *
+ * const UserInput = () => {
+ *   useInput((input, key) => {
+ *     if (input === 'q') {
+ *       // Exit program
+ *     }
+ *
+ *     if (key.leftArrow) {
+ *       // Left arrow key pressed
+ *     }
+ *   });
+ *
+ *   return …
+ * };
+ * ```
+ * @param inputHandler - called for each user input with the input string,
+ *   parsed key flags, and the originating event.
+ * @param options - hook options; `isActive: false` disables input capture.
+ */
+declare const useInput: (inputHandler: Handler, options?: Options) => void;
+export default useInput;
+//# sourceMappingURL=use-input.d.ts.map

package/lib/types/ink/hooks/use-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-input.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-input.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,0BAA0B,CAAA;AAG/D,KAAK,OAAO,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;AAEnE,KAAK,OAAO,GAAG;IACb;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,QAAA,MAAM,QAAQ,GAAI,cAAc,OAAO,EAAE,UAAS,OAAY,KAAG,IAgDhE,CAAA;AAED,eAAe,QAAQ,CAAA"}

package/lib/types/ink/hooks/use-input.js

@@ -0,0 +1,73 @@
+import { useEffect, useLayoutEffect } from 'react';
+import { useEventCallback } from 'usehooks-ts';
+import useStdin from './use-stdin.js';
+/**
+ * This hook is used for handling user input.
+ * It's a more convenient alternative to using `StdinContext` and listening to `data` events.
+ * The callback you pass to `useInput` is called for each character when user enters any input.
+ * However, if user pastes text and it's more than one character, the callback will be called only once and the whole string will be passed as `input`.
+ *
+ * ```
+ * import {useInput} from 'ink';
+ *
+ * const UserInput = () => {
+ *   useInput((input, key) => {
+ *     if (input === 'q') {
+ *       // Exit program
+ *     }
+ *
+ *     if (key.leftArrow) {
+ *       // Left arrow key pressed
+ *     }
+ *   });
+ *
+ *   return …
+ * };
+ * ```
+ * @param inputHandler - called for each user input with the input string,
+ *   parsed key flags, and the originating event.
+ * @param options - hook options; `isActive: false` disables input capture.
+ */
+const useInput = (inputHandler, options = {}) => {
+    const { setRawMode, internal_exitOnCtrlC, internal_eventEmitter } = useStdin();
+    // useLayoutEffect (not useEffect) so that raw mode is enabled synchronously
+    // during React's commit phase, before render() returns. With useEffect, raw
+    // mode setup is deferred to the next event loop tick via React's scheduler,
+    // leaving the terminal in cooked mode — keystrokes echo and the cursor is
+    // visible until the effect fires.
+    useLayoutEffect(() => {
+        if (options.isActive === false) {
+            return;
+        }
+        setRawMode(true);
+        return () => {
+            setRawMode(false);
+        };
+    }, [options.isActive, setRawMode]);
+    // Register the listener once on mount so its slot in the EventEmitter's
+    // listener array is stable. If isActive were in the effect's deps, the
+    // listener would re-append on false→true, moving it behind listeners
+    // that registered while it was inactive — breaking
+    // stopImmediatePropagation() ordering. useEventCallback keeps the
+    // reference stable while reading latest isActive/inputHandler from
+    // closure (it syncs via useLayoutEffect, so it's compiler-safe).
+    const handleData = useEventCallback((event) => {
+        if (options.isActive === false) {
+            return;
+        }
+        const { input, key } = event;
+        // If app is not supposed to exit on Ctrl+C, then let input listener handle it
+        // Note: discreteUpdates is called at the App level when emitting events,
+        // so all listeners are already within a high-priority update context.
+        if (!(input === 'c' && key.ctrl) || !internal_exitOnCtrlC) {
+            inputHandler(input, key, event);
+        }
+    });
+    useEffect(() => {
+        internal_eventEmitter?.on('input', handleData);
+        return () => {
+            internal_eventEmitter?.removeListener('input', handleData);
+        };
+    }, [internal_eventEmitter, handleData]);
+};
+export default useInput;

package/lib/types/ink/hooks/use-interval.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the clock time, updating at the given interval.
+ * Subscribes as non-keepAlive — won't keep the clock alive on its own,
+ * but updates whenever a keepAlive subscriber (e.g. the spinner)
+ * is driving the clock.
+ *
+ * Use this to drive pure time-based computations (shimmer position,
+ * frame index) from the shared clock.
+ * @param intervalMs - the minimum interval between updates, in milliseconds.
+ * @returns the current clock time in milliseconds.
+ */
+export declare function useAnimationTimer(intervalMs: number): number;
+/**
+ * Interval hook backed by the shared Clock.
+ *
+ * Unlike `useInterval` from `usehooks-ts` (which creates its own setInterval),
+ * this piggybacks on the single shared clock so all timers consolidate into
+ * one wake-up. Pass `null` for intervalMs to pause.
+ * @param callback - invoked each time the interval elapses.
+ * @param intervalMs - the interval in milliseconds, or null to pause.
+ */
+export declare function useInterval(callback: () => void, intervalMs: number | null): void;
+//# sourceMappingURL=use-interval.d.ts.map

package/lib/types/ink/hooks/use-interval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-interval.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-interval.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAqB5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,IAAI,EACpB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,IAAI,CAqBN"}

package/lib/types/ink/hooks/use-interval.js

@@ -0,0 +1,58 @@
+import { useContext, useEffect, useRef, useState } from 'react';
+import { ClockContext } from '../components/ClockContext.js';
+/**
+ * Returns the clock time, updating at the given interval.
+ * Subscribes as non-keepAlive — won't keep the clock alive on its own,
+ * but updates whenever a keepAlive subscriber (e.g. the spinner)
+ * is driving the clock.
+ *
+ * Use this to drive pure time-based computations (shimmer position,
+ * frame index) from the shared clock.
+ * @param intervalMs - the minimum interval between updates, in milliseconds.
+ * @returns the current clock time in milliseconds.
+ */
+export function useAnimationTimer(intervalMs) {
+    const clock = useContext(ClockContext);
+    const [time, setTime] = useState(() => clock?.now() ?? 0);
+    useEffect(() => {
+        if (!clock)
+            return;
+        let lastUpdate = clock.now();
+        const onChange = () => {
+            const now = clock.now();
+            if (now - lastUpdate >= intervalMs) {
+                lastUpdate = now;
+                setTime(now);
+            }
+        };
+        return clock.subscribe(onChange, false);
+    }, [clock, intervalMs]);
+    return time;
+}
+/**
+ * Interval hook backed by the shared Clock.
+ *
+ * Unlike `useInterval` from `usehooks-ts` (which creates its own setInterval),
+ * this piggybacks on the single shared clock so all timers consolidate into
+ * one wake-up. Pass `null` for intervalMs to pause.
+ * @param callback - invoked each time the interval elapses.
+ * @param intervalMs - the interval in milliseconds, or null to pause.
+ */
+export function useInterval(callback, intervalMs) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    const clock = useContext(ClockContext);
+    useEffect(() => {
+        if (!clock || intervalMs === null)
+            return;
+        let lastUpdate = clock.now();
+        const onChange = () => {
+            const now = clock.now();
+            if (now - lastUpdate >= intervalMs) {
+                lastUpdate = now;
+                callbackRef.current();
+            }
+        };
+        return clock.subscribe(onChange, false);
+    }, [clock, intervalMs]);
+}

package/lib/types/ink/hooks/use-search-highlight.d.ts

@@ -0,0 +1,34 @@
+import type { DOMElement } from '../dom.js';
+import type { MatchPosition } from '../render-to-screen.js';
+/**
+ * Set the search highlight query on the Ink instance. Non-empty → all
+ * visible occurrences are inverted on the next frame (SGR 7, screen-buffer
+ * overlay, same damage machinery as selection). Empty → clears.
+ *
+ * This is a screen-space highlight — it matches the RENDERED text, not the
+ * source message text. Works for anything visible (bash output, file paths,
+ * error messages) regardless of where it came from in the message tree. A
+ * query that matched in source but got truncated/ellipsized in rendering
+ * won't highlight; that's acceptable — we highlight what you see.
+ * @returns an object controlling the search highlight: `setQuery` sets the
+ *   query, `scanElement` scans a DOM subtree for matches, and `setPositions`
+ *   drives the position-based highlight.
+ */
+export declare function useSearchHighlight(): {
+    setQuery: (query: string) => void;
+    /** Paint an existing DOM subtree (from the MAIN tree) to a fresh
+     *  Screen at its natural height, scan. Element-relative positions
+     *  (row 0 = element top). Zero context duplication — the element
+     *  IS the one built with all real providers. */
+    scanElement: (el: DOMElement) => MatchPosition[];
+    /** Position-based CURRENT highlight. Every frame writes yellow at
+     *  positions[currentIdx] + rowOffset. The scan-highlight (inverse on
+     *  all matches) still runs — this overlays on top. rowOffset tracks
+     *  scroll; positions stay stable (message-relative). null clears. */
+    setPositions: (state: {
+        positions: MatchPosition[];
+        rowOffset: number;
+        currentIdx: number;
+    } | null) => void;
+};
+//# sourceMappingURL=use-search-highlight.d.ts.map

package/lib/types/ink/hooks/use-search-highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-search-highlight.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-search-highlight.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC;;;oDAGgD;IAChD,WAAW,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,aAAa,EAAE,CAAA;IAChD;;;yEAGqE;IACrE,YAAY,EAAE,CACZ,KAAK,EAAE;QACL,SAAS,EAAE,aAAa,EAAE,CAAA;QAC1B,SAAS,EAAE,MAAM,CAAA;QACjB,UAAU,EAAE,MAAM,CAAA;KACnB,GAAG,IAAI,KACL,IAAI,CAAA;CACV,CAiBA"}

package/lib/types/ink/hooks/use-search-highlight.js

@@ -0,0 +1,35 @@
+import { useContext, useMemo } from 'react';
+import StdinContext from '../components/StdinContext.js';
+import instances from '../instances.js';
+/**
+ * Set the search highlight query on the Ink instance. Non-empty → all
+ * visible occurrences are inverted on the next frame (SGR 7, screen-buffer
+ * overlay, same damage machinery as selection). Empty → clears.
+ *
+ * This is a screen-space highlight — it matches the RENDERED text, not the
+ * source message text. Works for anything visible (bash output, file paths,
+ * error messages) regardless of where it came from in the message tree. A
+ * query that matched in source but got truncated/ellipsized in rendering
+ * won't highlight; that's acceptable — we highlight what you see.
+ * @returns an object controlling the search highlight: `setQuery` sets the
+ *   query, `scanElement` scans a DOM subtree for matches, and `setPositions`
+ *   drives the position-based highlight.
+ */
+export function useSearchHighlight() {
+    useContext(StdinContext); // anchor to App subtree for hook rules
+    const ink = instances.get(process.stdout);
+    return useMemo(() => {
+        if (!ink) {
+            return {
+                setQuery: () => { },
+                scanElement: () => [],
+                setPositions: () => { },
+            };
+        }
+        return {
+            setQuery: (query) => ink.setSearchHighlight(query),
+            scanElement: (el) => ink.scanElementSubtree(el),
+            setPositions: state => ink.setSearchPositions(state),
+        };
+    }, [ink]);
+}

package/lib/types/ink/hooks/use-selection.d.ts

@@ -0,0 +1,44 @@
+import { type FocusMove, type SelectionState } from '../selection.js';
+/**
+ * Access to text selection operations on the Ink instance (fullscreen only).
+ * Returns no-op functions when fullscreen mode is disabled.
+ * @returns an object of selection operations bound to the Ink instance:
+ *   copy, clear, query, subscribe, and scroll/keyboard manipulation.
+ */
+export declare function useSelection(): {
+    copySelection: () => string;
+    /** Copy without clearing the highlight (for copy-on-select). */
+    copySelectionNoClear: () => string;
+    clearSelection: () => void;
+    hasSelection: () => boolean;
+    /** Read the raw mutable selection state (for drag-to-scroll). */
+    getState: () => SelectionState | null;
+    /** Subscribe to selection mutations (start/update/finish/clear). */
+    subscribe: (cb: () => void) => () => void;
+    /** Shift the anchor row by dRow, clamped to [minRow, maxRow]. */
+    shiftAnchor: (dRow: number, minRow: number, maxRow: number) => void;
+    /** Shift anchor AND focus by dRow (keyboard scroll: whole selection
+     *  tracks content). Clamped points get col reset to the full-width edge
+     *  since their content was captured by captureScrolledRows. Reads
+     *  screen.width from the ink instance for the col-reset boundary. */
+    shiftSelection: (dRow: number, minRow: number, maxRow: number) => void;
+    /** Keyboard selection extension (shift+arrow): move focus, anchor fixed.
+     *  Left/right wrap across rows; up/down clamp at viewport edges. */
+    moveFocus: (move: FocusMove) => void;
+    /** Capture text from rows about to scroll out of the viewport (call
+     *  BEFORE scrollBy so the screen buffer still has the outgoing rows). */
+    captureScrolledRows: (firstRow: number, lastRow: number, side: 'above' | 'below') => void;
+    /** Set the selection highlight bg color (theme-piping; solid bg
+     *  replaces the old SGR-7 inverse so syntax highlighting stays readable
+     *  under selection). Call once on mount + whenever theme changes. */
+    setSelectionBgColor: (color: string) => void;
+};
+/**
+ * Reactive selection-exists state. Re-renders the caller when a text
+ * selection is created or cleared. Always returns false outside
+ * fullscreen mode (selection is only available in alt-screen).
+ * @returns true when a text selection currently exists; false outside
+ *   fullscreen mode.
+ */
+export declare function useHasSelection(): boolean;
+//# sourceMappingURL=use-selection.d.ts.map

package/lib/types/ink/hooks/use-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-selection.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-selection.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAA;AAExB;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI;IAC9B,aAAa,EAAE,MAAM,MAAM,CAAA;IAC3B,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,MAAM,CAAA;IAClC,cAAc,EAAE,MAAM,IAAI,CAAA;IAC1B,YAAY,EAAE,MAAM,OAAO,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;IACrC,oEAAoE;IACpE,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;IACzC,iEAAiE;IACjE,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACnE;;;yEAGqE;IACrE,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACtE;wEACoE;IACpE,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACpC;6EACyE;IACzE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,GAAG,OAAO,KACpB,IAAI,CAAA;IACT;;yEAEqE;IACrE,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7C,CA0CA;AAKD;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAOzC"}