@iaforged/context-code 1.0.72 → 1.0.74

package/dist/src/ink/hooks/use-declared-cursor.js

@@ -0,0 +1,60 @@
+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.
+ */
+export function useDeclaredCursor({ line, column, active, }) {
+    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/dist/src/ink/hooks/use-input.js

@@ -0,0 +1,70 @@
+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 …
+ * };
+ * ```
+ */
+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/dist/src/ink/hooks/use-interval.js

@@ -0,0 +1,54 @@
+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.
+ */
+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.
+ */
+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/dist/src/ink/hooks/use-search-highlight.js

@@ -0,0 +1,32 @@
+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.
+ */
+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/dist/src/ink/hooks/use-selection.js

@@ -0,0 +1,60 @@
+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.
+ */
+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).
+ */
+export function useHasSelection() {
+    useContext(StdinContext);
+    const ink = instances.get(process.stdout);
+    return useSyncExternalStore(ink ? ink.subscribeToSelectionChange : NO_SUBSCRIBE, ink ? ink.hasTextSelection : ALWAYS_FALSE);
+}

package/dist/src/ink/hooks/use-stdin.js

@@ -0,0 +1,7 @@
+import { useContext } from 'react';
+import StdinContext from '../components/StdinContext.js';
+/**
+ * `useStdin` is a React hook, which exposes stdin stream.
+ */
+const useStdin = () => useContext(StdinContext);
+export default useStdin;

package/dist/src/ink/hooks/use-tab-status.js

@@ -0,0 +1,57 @@
+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.
+ */
+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/dist/src/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/dist/src/ink/hooks/use-terminal-title.js

@@ -0,0 +1,29 @@
+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.
+ */
+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/dist/src/ink/hooks/use-terminal-viewport.js

@@ -0,0 +1,77 @@
+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>
+ */
+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];
+}