@deepseek-harness-tui/dsh-tui 0.5.0

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

@@ -0,0 +1,64 @@
+import { useContext, useMemo, useSyncExternalStore } from 'react';
+import StdinContext from '../components/StdinContext.js';
+import instances from '../instances.js';
+import { shiftAnchor, } 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 function useSelection() {
+    // Look up the Ink instance via stdout — same pattern as instances map.
+    // StdinContext is available (it's always provided), and the Ink instance
+    // is keyed by stdout which we can get from process.stdout since there's
+    // only one Ink instance per process in practice.
+    useContext(StdinContext); // anchor to App subtree for hook rules
+    const ink = instances.get(process.stdout);
+    // Memoize so callers can safely use the return value in dependency arrays.
+    // ink is a singleton per stdout — stable across renders.
+    return useMemo(() => {
+        if (!ink) {
+            return {
+                copySelection: () => '',
+                copySelectionNoClear: () => '',
+                clearSelection: () => { },
+                hasSelection: () => false,
+                getState: () => null,
+                subscribe: () => () => { },
+                shiftAnchor: () => { },
+                shiftSelection: () => { },
+                moveFocus: () => { },
+                captureScrolledRows: () => { },
+                setSelectionBgColor: () => { },
+            };
+        }
+        return {
+            copySelection: () => ink.copySelection(),
+            copySelectionNoClear: () => ink.copySelectionNoClear(),
+            clearSelection: () => ink.clearTextSelection(),
+            hasSelection: () => ink.hasTextSelection(),
+            getState: () => ink.selection,
+            subscribe: (cb) => ink.subscribeToSelectionChange(cb),
+            shiftAnchor: (dRow, minRow, maxRow) => shiftAnchor(ink.selection, dRow, minRow, maxRow),
+            shiftSelection: (dRow, minRow, maxRow) => ink.shiftSelectionForScroll(dRow, minRow, maxRow),
+            moveFocus: (move) => ink.moveSelectionFocus(move),
+            captureScrolledRows: (firstRow, lastRow, side) => ink.captureScrolledRows(firstRow, lastRow, side),
+            setSelectionBgColor: (color) => ink.setSelectionBgColor(color),
+        };
+    }, [ink]);
+}
+const NO_SUBSCRIBE = () => () => { };
+const ALWAYS_FALSE = () => false;
+/**
+ * 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 function useHasSelection() {
+    useContext(StdinContext);
+    const ink = instances.get(process.stdout);
+    return useSyncExternalStore(ink ? ink.subscribeToSelectionChange : NO_SUBSCRIBE, ink ? ink.hasTextSelection : ALWAYS_FALSE);
+}

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

@@ -0,0 +1,8 @@
+import { type Props } from '../components/StdinContext.js';
+/**
+ * React hook exposing the stdin stream and raw-mode helpers from `StdinContext`.
+ * @returns the `StdinContext` value.
+ */
+declare const useStdin: () => Props;
+export default useStdin;
+//# sourceMappingURL=use-stdin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-stdin.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-stdin.ts"],"names":[],"mappings":"AACA,OAAqB,EAAE,KAAK,KAAK,EAAE,MAAM,+BAA+B,CAAA;AAExE;;;GAGG;AACH,QAAA,MAAM,QAAQ,QAAO,KAAiC,CAAA;AACtD,eAAe,QAAQ,CAAA"}

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

@@ -0,0 +1,8 @@
+import { useContext } from 'react';
+import StdinContext from '../components/StdinContext.js';
+/**
+ * React hook exposing the stdin stream and raw-mode helpers from `StdinContext`.
+ * @returns the `StdinContext` value.
+ */
+const useStdin = () => useContext(StdinContext);
+export default useStdin;

package/lib/types/ink/hooks/use-tab-status.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The kind of tab-status indicator: 'idle', 'busy', or 'waiting'.
+ */
+export type TabStatusKind = 'idle' | 'busy' | 'waiting';
+/**
+ * Declaratively set the tab-status indicator (OSC 21337).
+ *
+ * Emits a colored dot + short status text to the tab sidebar. Terminals
+ * that don't support OSC 21337 discard the sequence silently, so this is
+ * safe to call unconditionally. Wrapped for tmux/screen passthrough.
+ *
+ * Pass `null` to opt out. If a status was previously set, transitioning to
+ * `null` emits CLEAR_TAB_STATUS so toggling off mid-session doesn't leave
+ * a stale dot. Process-exit cleanup is handled by ink.tsx's unmount path.
+ * @param kind - the status kind to display, or null to opt out.
+ */
+export declare function useTabStatus(kind: TabStatusKind | null): void;
+//# sourceMappingURL=use-tab-status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-tab-status.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-tab-status.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AA+BvD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAmB7D"}

package/lib/types/ink/hooks/use-tab-status.js

@@ -0,0 +1,58 @@
+import { useContext, useEffect, useRef } from 'react';
+import { CLEAR_TAB_STATUS, supportsTabStatus, tabStatus, wrapForMultiplexer, } from '../termio/osc.js';
+import { TerminalWriteContext } from '../useTerminalNotification.js';
+const rgb = (r, g, b) => ({
+    type: 'rgb',
+    r,
+    g,
+    b,
+});
+// Per the OSC 21337 usage guide's suggested mapping.
+const TAB_STATUS_PRESETS = {
+    idle: {
+        indicator: rgb(0, 215, 95),
+        status: 'Idle',
+        statusColor: rgb(136, 136, 136),
+    },
+    busy: {
+        indicator: rgb(255, 149, 0),
+        status: 'Working…',
+        statusColor: rgb(255, 149, 0),
+    },
+    waiting: {
+        indicator: rgb(95, 135, 255),
+        status: 'Waiting',
+        statusColor: rgb(95, 135, 255),
+    },
+};
+/**
+ * Declaratively set the tab-status indicator (OSC 21337).
+ *
+ * Emits a colored dot + short status text to the tab sidebar. Terminals
+ * that don't support OSC 21337 discard the sequence silently, so this is
+ * safe to call unconditionally. Wrapped for tmux/screen passthrough.
+ *
+ * Pass `null` to opt out. If a status was previously set, transitioning to
+ * `null` emits CLEAR_TAB_STATUS so toggling off mid-session doesn't leave
+ * a stale dot. Process-exit cleanup is handled by ink.tsx's unmount path.
+ * @param kind - the status kind to display, or null to opt out.
+ */
+export function useTabStatus(kind) {
+    const writeRaw = useContext(TerminalWriteContext);
+    const prevKindRef = useRef(null);
+    useEffect(() => {
+        // When kind transitions from non-null to null (e.g. user toggles off
+        // showStatusInTerminalTab mid-session), clear the stale dot.
+        if (kind === null) {
+            if (prevKindRef.current !== null && writeRaw && supportsTabStatus()) {
+                writeRaw(wrapForMultiplexer(CLEAR_TAB_STATUS));
+            }
+            prevKindRef.current = null;
+            return;
+        }
+        prevKindRef.current = kind;
+        if (!writeRaw || !supportsTabStatus())
+            return;
+        writeRaw(wrapForMultiplexer(tabStatus(TAB_STATUS_PRESETS[kind])));
+    }, [kind, writeRaw]);
+}

package/lib/types/ink/hooks/use-terminal-focus.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook to check if the terminal has focus.
+ *
+ * Uses DECSET 1004 focus reporting - the terminal sends escape sequences
+ * when it gains or loses focus. These are handled automatically
+ * by Ink and filtered from useInput.
+ *
+ * @returns true if the terminal is focused (or focus state is unknown)
+ */
+export declare function useTerminalFocus(): boolean;
+//# sourceMappingURL=use-terminal-focus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-terminal-focus.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-focus.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAG1C"}

package/lib/types/ink/hooks/use-terminal-focus.js

@@ -0,0 +1,15 @@
+import { useContext } from 'react';
+import TerminalFocusContext from '../components/TerminalFocusContext.js';
+/**
+ * Hook to check if the terminal has focus.
+ *
+ * Uses DECSET 1004 focus reporting - the terminal sends escape sequences
+ * when it gains or loses focus. These are handled automatically
+ * by Ink and filtered from useInput.
+ *
+ * @returns true if the terminal is focused (or focus state is unknown)
+ */
+export function useTerminalFocus() {
+    const { isTerminalFocused } = useContext(TerminalFocusContext);
+    return isTerminalFocused;
+}

package/lib/types/ink/hooks/use-terminal-size.d.ts

@@ -0,0 +1,6 @@
+import { type TerminalSize } from '../components/TerminalSizeContext.js';
+/** Terminal dimensions from the Ink app shell (ported from the leak).
+ * @returns the current terminal dimensions.
+ */
+export declare function useTerminalSize(): TerminalSize;
+//# sourceMappingURL=use-terminal-size.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-terminal-size.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-size.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,YAAY,EAElB,MAAM,sCAAsC,CAAA;AAE7C;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAQ9C"}

package/lib/types/ink/hooks/use-terminal-size.js

@@ -0,0 +1,12 @@
+import { useContext } from 'react';
+import { TerminalSizeContext, } from '../components/TerminalSizeContext.js';
+/** Terminal dimensions from the Ink app shell (ported from the leak).
+ * @returns the current terminal dimensions.
+ */
+export function useTerminalSize() {
+    const size = useContext(TerminalSizeContext);
+    if (!size) {
+        throw new Error('useTerminalSize must be used within an Ink App component');
+    }
+    return size;
+}

package/lib/types/ink/hooks/use-terminal-title.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Declaratively set the terminal tab/window title.
+ *
+ * Pass a string to set the title. ANSI escape sequences are stripped
+ * automatically so callers don't need to know about terminal encoding.
+ * Pass `null` to opt out — the hook becomes a no-op and leaves the
+ * terminal title untouched.
+ *
+ * On Windows, uses `process.title` (classic conhost doesn't support OSC).
+ * Elsewhere, writes OSC 0 (set title+icon) via Ink's stdout.
+ * @param title - the title to set, or null to opt out.
+ */
+export declare function useTerminalTitle(title: string | null): void;
+//# sourceMappingURL=use-terminal-title.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-terminal-title.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-title.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAc3D"}

package/lib/types/ink/hooks/use-terminal-title.js

@@ -0,0 +1,30 @@
+import { useContext, useEffect } from 'react';
+import stripAnsi from 'strip-ansi';
+import { OSC, osc } from '../termio/osc.js';
+import { TerminalWriteContext } from '../useTerminalNotification.js';
+/**
+ * Declaratively set the terminal tab/window title.
+ *
+ * Pass a string to set the title. ANSI escape sequences are stripped
+ * automatically so callers don't need to know about terminal encoding.
+ * Pass `null` to opt out — the hook becomes a no-op and leaves the
+ * terminal title untouched.
+ *
+ * On Windows, uses `process.title` (classic conhost doesn't support OSC).
+ * Elsewhere, writes OSC 0 (set title+icon) via Ink's stdout.
+ * @param title - the title to set, or null to opt out.
+ */
+export function useTerminalTitle(title) {
+    const writeRaw = useContext(TerminalWriteContext);
+    useEffect(() => {
+        if (title === null || !writeRaw)
+            return;
+        const clean = stripAnsi(title);
+        if (process.platform === 'win32') {
+            process.title = clean;
+        }
+        else {
+            writeRaw(osc(OSC.SET_TITLE_AND_ICON, clean));
+        }
+    }, [title, writeRaw]);
+}

package/lib/types/ink/hooks/use-terminal-viewport.d.ts

@@ -0,0 +1,32 @@
+import type { DOMElement } from '../dom.js';
+type ViewportEntry = {
+    /**
+     * Whether the element is currently within the terminal viewport
+     */
+    isVisible: boolean;
+};
+/**
+ * Hook to detect if a component is within the terminal viewport.
+ *
+ * Returns a callback ref and a viewport entry object.
+ * Attach the ref to the component you want to track.
+ *
+ * The entry is updated during the layout phase (useLayoutEffect) so callers
+ * always read fresh values during render. Visibility changes do NOT trigger
+ * re-renders on their own — callers that re-render for other reasons (e.g.
+ * animation ticks, state changes) will pick up the latest value naturally.
+ * This avoids infinite update loops when combined with other layout effects
+ * that also call setState.
+ *
+ * @example
+ * const [ref, entry] = useTerminalViewport()
+ * return <Box ref={ref}><Animation enabled={entry.isVisible}>...</Animation></Box>
+ * @returns a tuple of a ref callback to attach to the tracked element and the
+ *   current viewport entry object.
+ */
+export declare function useTerminalViewport(): [
+    ref: (element: DOMElement | null) => void,
+    entry: ViewportEntry
+];
+export {};
+//# sourceMappingURL=use-terminal-viewport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-terminal-viewport.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-viewport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,KAAK,aAAa,GAAG;IACnB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,IAAI;IACrC,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI;IACzC,KAAK,EAAE,aAAa;CACrB,CAgEA"}

package/lib/types/ink/hooks/use-terminal-viewport.js

@@ -0,0 +1,79 @@
+import { useCallback, useContext, useLayoutEffect, useRef } from 'react';
+import { TerminalSizeContext } from '../components/TerminalSizeContext.js';
+/**
+ * Hook to detect if a component is within the terminal viewport.
+ *
+ * Returns a callback ref and a viewport entry object.
+ * Attach the ref to the component you want to track.
+ *
+ * The entry is updated during the layout phase (useLayoutEffect) so callers
+ * always read fresh values during render. Visibility changes do NOT trigger
+ * re-renders on their own — callers that re-render for other reasons (e.g.
+ * animation ticks, state changes) will pick up the latest value naturally.
+ * This avoids infinite update loops when combined with other layout effects
+ * that also call setState.
+ *
+ * @example
+ * const [ref, entry] = useTerminalViewport()
+ * return <Box ref={ref}><Animation enabled={entry.isVisible}>...</Animation></Box>
+ * @returns a tuple of a ref callback to attach to the tracked element and the
+ *   current viewport entry object.
+ */
+export function useTerminalViewport() {
+    const terminalSize = useContext(TerminalSizeContext);
+    const elementRef = useRef(null);
+    const entryRef = useRef({ isVisible: true });
+    const setElement = useCallback((el) => {
+        elementRef.current = el;
+    }, []);
+    // Runs on every render because yoga layout values can change
+    // without React being aware. Only updates the ref — no setState
+    // to avoid cascading re-renders during the commit phase.
+    // Walks the DOM ancestor chain fresh each time to avoid holding stale
+    // references after yoga tree rebuilds.
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element?.yogaNode || !terminalSize) {
+            return;
+        }
+        const height = element.yogaNode.getComputedHeight();
+        const rows = terminalSize.rows;
+        // Walk the DOM parent chain (not yoga.getParent()) so we can detect
+        // scroll containers and subtract their scrollTop. Yoga computes layout
+        // positions without scroll offset — scrollTop is applied at render time.
+        // Without this, an element inside a ScrollBox whose yoga position exceeds
+        // terminalRows would be considered offscreen even when scrolled into view
+        // (e.g., the spinner in fullscreen mode after enough messages accumulate).
+        let absoluteTop = element.yogaNode.getComputedTop();
+        let parent = element.parentNode;
+        let root = element.yogaNode;
+        while (parent) {
+            if (parent.yogaNode) {
+                absoluteTop += parent.yogaNode.getComputedTop();
+                root = parent.yogaNode;
+            }
+            // scrollTop is only ever set on scroll containers (by ScrollBox + renderer).
+            // Non-scroll nodes have undefined scrollTop → falsy fast-path.
+            if (parent.scrollTop)
+                absoluteTop -= parent.scrollTop;
+            parent = parent.parentNode;
+        }
+        // Only the root's height matters
+        const screenHeight = root.getComputedHeight();
+        const bottom = absoluteTop + height;
+        // When content overflows the viewport (screenHeight > rows), the
+        // cursor-restore at frame end scrolls one extra row into scrollback.
+        // log-update.ts accounts for this with scrollbackRows = viewportY + 1.
+        // We must match, otherwise an element at the boundary is considered
+        // "visible" here (animation keeps ticking) but its row is treated as
+        // scrollback by log-update (content change → full reset → flicker).
+        const cursorRestoreScroll = screenHeight > rows ? 1 : 0;
+        const viewportY = Math.max(0, screenHeight - rows) + cursorRestoreScroll;
+        const viewportBottom = viewportY + rows;
+        const visible = bottom > viewportY && absoluteTop < viewportBottom;
+        if (visible !== entryRef.current.isVisible) {
+            entryRef.current = { isVisible: visible };
+        }
+    });
+    return [setElement, entryRef.current];
+}