@askdkc/dsh-cli 0.11.3

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-images.d.ts

@@ -0,0 +1,14 @@
+import type { TerminalCellSize } from '../terminal-image.js';
+interface TerminalImages {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): boolean;
+    getCellSize?(): TerminalCellSize | undefined;
+    request(): () => void;
+}
+/** Only measured pixels qualify for an original-pixel (100%) image view. */
+export declare function useTerminalImageCellSize(): TerminalCellSize | undefined;
+export declare const TerminalImagesContext: import("react").Context<TerminalImages>;
+/** Request the renderer's capability probe before reading or decoding pixels. */
+export declare function useTerminalImages(requested?: boolean): boolean;
+export {};
+//# sourceMappingURL=use-terminal-images.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-terminal-images.d.ts","sourceRoot":"","sources":["../../../../src/ink/hooks/use-terminal-images.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,UAAU,cAAc;IACtB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,WAAW,IAAI,OAAO,CAAA;IACtB,WAAW,CAAC,IAAI,gBAAgB,GAAG,SAAS,CAAA;IAC5C,OAAO,IAAI,MAAM,IAAI,CAAA;CACtB;AAID,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,gBAAgB,GAAG,SAAS,CAGvE;AAED,eAAO,MAAM,qBAAqB,yCAIhC,CAAA;AAEF,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,SAAS,UAAO,GAAG,OAAO,CAO3D"}

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

@@ -0,0 +1,22 @@
+import { createContext, useContext, useEffect, useSyncExternalStore } from 'react';
+const noCellSize = () => undefined;
+/** Only measured pixels qualify for an original-pixel (100%) image view. */
+export function useTerminalImageCellSize() {
+    const images = useContext(TerminalImagesContext);
+    return useSyncExternalStore(images.subscribe, images.getCellSize ?? noCellSize);
+}
+export const TerminalImagesContext = createContext({
+    subscribe: () => () => { },
+    getSnapshot: () => false,
+    request: () => () => { },
+});
+/** Request the renderer's capability probe before reading or decoding pixels. */
+export function useTerminalImages(requested = true) {
+    const images = useContext(TerminalImagesContext);
+    const available = useSyncExternalStore(images.subscribe, images.getSnapshot);
+    useEffect(() => {
+        if (requested)
+            return images.request();
+    }, [images, requested]);
+    return requested && available;
+}

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.
+ * @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.
+ * @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];
+}