@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/tree-picker-state.test.js

@@ -0,0 +1,303 @@
+import { describe, expect, it } from 'vitest';
+import { buildInitialState, buildPickerTree, canToggle, clearExpiredTransientHint, filterTree, flattenSelection, hasPartialChildren, moveCursor, reducer, selectAllVisible, selectNone, toggleChecked, visibleNodeIds, } from './tree-picker-state.js';
+const IDS = {
+    engineering: '11111111-1111-1111-1111-111111111111',
+    architecture: '22222222-2222-2222-2222-222222222222',
+    onboarding: '33333333-3333-3333-3333-333333333333',
+    marketing: '44444444-4444-4444-4444-444444444444',
+    journal: '55555555-5555-5555-5555-555555555555',
+    orphan: '66666666-6666-6666-6666-666666666666',
+    duplicate: '77777777-7777-7777-7777-777777777777',
+    cycleA: '88888888-8888-8888-8888-888888888888',
+    cycleB: '99999999-9999-9999-9999-999999999999',
+};
+function pages() {
+    return [
+        { id: IDS.marketing, title: 'Marketing', archived: false, parentId: null },
+        { id: IDS.onboarding, title: 'Onboarding', archived: false, parentId: IDS.engineering },
+        { id: IDS.engineering, title: 'Engineering Docs', archived: false, parentId: null },
+        { id: IDS.architecture, title: 'Architecture', archived: false, parentId: IDS.engineering },
+        { id: IDS.journal, title: 'Daily journal', archived: true, parentId: IDS.marketing },
+        { id: IDS.orphan, title: '', archived: false, parentId: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' },
+        { id: IDS.duplicate, title: 'Original duplicate', archived: false, parentId: null },
+        { id: IDS.duplicate, title: 'Ignored duplicate', archived: true, parentId: IDS.marketing },
+        { id: IDS.cycleA, title: 'Cycle A', archived: false, parentId: IDS.cycleB },
+        { id: IDS.cycleB, title: 'Cycle B', archived: false, parentId: IDS.cycleA },
+    ];
+}
+describe('buildPickerTree', () => {
+    it('deduplicates nodes, sorts siblings, preserves archived flags, roots orphans, and breaks cycles', () => {
+        const tree = buildPickerTree(pages());
+        const byId = new Map(tree.map((node) => [node.id, node]));
+        expect(tree.map((node) => node.title)).toEqual([
+            'Cycle A',
+            'Cycle B',
+            'Engineering Docs',
+            'Architecture',
+            'Onboarding',
+            'Marketing',
+            'Daily journal',
+            'Original duplicate',
+            'Untitled',
+        ]);
+        expect(byId.get(IDS.engineering)?.childIds).toEqual([IDS.architecture, IDS.onboarding]);
+        expect(byId.get(IDS.architecture)).toMatchObject({
+            depth: 1,
+            parentId: IDS.engineering,
+            path: 'Engineering Docs / Architecture',
+        });
+        expect(byId.get(IDS.journal)).toMatchObject({
+            archived: true,
+            depth: 1,
+            path: 'Marketing / Daily journal',
+        });
+        expect(byId.get(IDS.orphan)).toMatchObject({
+            title: 'Untitled',
+            parentId: null,
+            depth: 0,
+            path: 'Untitled',
+        });
+        expect(byId.get(IDS.duplicate)).toMatchObject({
+            title: 'Original duplicate',
+            archived: false,
+            parentId: null,
+        });
+        expect(byId.get(IDS.cycleA)?.parentId).toBeNull();
+        expect(byId.get(IDS.cycleB)?.parentId).toBe(IDS.cycleA);
+    });
+});
+describe('selection invariants', () => {
+    it('checking a parent locks descendants and keeps checked ids minimal', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        });
+        const checkedParent = toggleChecked(state, IDS.engineering, 1000);
+        expect([...checkedParent.checked]).toEqual([IDS.engineering]);
+        expect(canToggle(IDS.architecture, checkedParent)).toEqual({
+            ok: false,
+            reason: "Locked by 'Engineering Docs' - uncheck parent first",
+        });
+        const lockedChildAttempt = toggleChecked(checkedParent, IDS.architecture, 2000);
+        expect([...lockedChildAttempt.checked]).toEqual([IDS.engineering]);
+        expect(lockedChildAttempt.transientHint).toEqual({
+            text: "Locked by 'Engineering Docs' - uncheck parent first",
+            expiresAt: 4500,
+        });
+        const uncheckedParent = toggleChecked(lockedChildAttempt, IDS.engineering, 3000);
+        expect([...uncheckedParent.checked]).toEqual([]);
+        expect(canToggle(IDS.architecture, uncheckedParent)).toEqual({ ok: true });
+    });
+    it('reports stale stored ids via the caller-supplied warning, expands checked ancestors, and flattens descendants', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [IDS.engineering, IDS.architecture, 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'],
+            staleWarning: (staleCount) => `${staleCount} stored root_page_ids no longer visible`,
+        });
+        expect([...state.checked]).toEqual([IDS.engineering]);
+        expect([...state.expanded]).toEqual([]);
+        expect(state.cursorId).toBe(IDS.cycleA);
+        expect(state.preLoadWarnings).toEqual(['1 stored root_page_ids no longer visible']);
+        expect(flattenSelection(new Set([IDS.engineering, IDS.architecture]), state.byId)).toEqual([IDS.engineering]);
+    });
+    it('falls back to a generic stale warning when no warning factory is supplied', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: ['aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'],
+        });
+        expect(state.preLoadWarnings).toEqual(['1 stored selections no longer visible']);
+    });
+});
+describe('hasPartialChildren', () => {
+    const ROOT = 'r0000000-0000-0000-0000-000000000000';
+    const CHILD_A = 'a0000000-0000-0000-0000-000000000000';
+    const CHILD_B = 'b0000000-0000-0000-0000-000000000000';
+    const GRANDCHILD = 'g0000000-0000-0000-0000-000000000000';
+    const LEAF = 'l0000000-0000-0000-0000-000000000000';
+    function tree() {
+        return buildPickerTree([
+            { id: ROOT, title: 'Root', parentId: null },
+            { id: CHILD_A, title: 'Child A', parentId: ROOT },
+            { id: CHILD_B, title: 'Child B', parentId: ROOT },
+            { id: GRANDCHILD, title: 'Grandchild', parentId: CHILD_A },
+            { id: LEAF, title: 'Leaf', parentId: null },
+        ]);
+    }
+    function byId() {
+        return new Map(tree().map((node) => [node.id, node]));
+    }
+    it('returns false for a leaf node with no children', () => {
+        expect(hasPartialChildren(LEAF, new Set(), byId())).toBe(false);
+        expect(hasPartialChildren(LEAF, new Set([LEAF]), byId())).toBe(false);
+    });
+    it('returns false when the node itself is checked', () => {
+        expect(hasPartialChildren(ROOT, new Set([ROOT]), byId())).toBe(false);
+    });
+    it('returns false when an ancestor is checked (node is locked)', () => {
+        expect(hasPartialChildren(CHILD_A, new Set([ROOT]), byId())).toBe(false);
+    });
+    it('returns true when a direct child is checked', () => {
+        expect(hasPartialChildren(ROOT, new Set([CHILD_A]), byId())).toBe(true);
+    });
+    it('returns true when a deep descendant is checked', () => {
+        expect(hasPartialChildren(ROOT, new Set([GRANDCHILD]), byId())).toBe(true);
+    });
+    it('returns false when no descendant is checked', () => {
+        expect(hasPartialChildren(ROOT, new Set([LEAF]), byId())).toBe(false);
+        expect(hasPartialChildren(ROOT, new Set(), byId())).toBe(false);
+    });
+});
+describe('search and cursor movement', () => {
+    it('filters by title and path while deriving auto-expanded ancestors', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        });
+        const searching = {
+            ...state,
+            search: { editing: false, query: 'architecture' },
+        };
+        expect(filterTree(searching)).toEqual({
+            visibleIds: new Set([IDS.engineering, IDS.architecture]),
+            autoExpand: new Set([IDS.engineering]),
+        });
+        expect(visibleNodeIds(searching)).toEqual([IDS.engineering, IDS.architecture]);
+    });
+    it('moves the cursor through visible nodes and implements left/right tree semantics', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        });
+        const atEngineering = {
+            ...state,
+            cursorId: IDS.engineering,
+            expanded: new Set([IDS.engineering]),
+        };
+        expect(moveCursor(atEngineering, 'down').cursorId).toBe(IDS.architecture);
+        expect(moveCursor({ ...atEngineering, cursorId: IDS.architecture }, 'up').cursorId).toBe(IDS.engineering);
+        expect(moveCursor(atEngineering, 'right').cursorId).toBe(IDS.architecture);
+        expect(moveCursor({ ...atEngineering, cursorId: IDS.architecture }, 'left').cursorId).toBe(IDS.engineering);
+        expect([...moveCursor(atEngineering, 'left').expanded]).toEqual([]);
+        expect([...moveCursor({ ...state, cursorId: IDS.marketing }, 'right').expanded]).toContain(IDS.marketing);
+    });
+});
+describe('bulk actions and reducer effects', () => {
+    it('selects only matching visible roots under search and clears selection', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [IDS.marketing],
+        });
+        const searching = {
+            ...state,
+            search: { editing: false, query: 'architecture' },
+        };
+        const selected = selectAllVisible(searching);
+        expect(flattenSelection(selected.checked, selected.byId)).toEqual([IDS.architecture, IDS.marketing]);
+        expect([...selectNone(selected).checked]).toEqual([]);
+    });
+    it('toggle-select-all-visible selects all visible roots, then clears on repeat', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        });
+        const firstPress = reducer(state, 'toggle-select-all-visible').next;
+        expect(firstPress.checked.size).toBeGreaterThan(0);
+        const allSelectedIds = [...firstPress.checked].sort();
+        const secondPress = reducer(firstPress, 'toggle-select-all-visible').next;
+        expect([...secondPress.checked]).toEqual([]);
+        const thirdPress = reducer(secondPress, 'toggle-select-all-visible').next;
+        expect([...thirdPress.checked].sort()).toEqual(allSelectedIds);
+    });
+    it('saves immediately when confirm is not required and prompts confirmation when requireConfirmOnSave is true', () => {
+        const noConfirm = toggleChecked(buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        }), IDS.marketing, 1000);
+        expect(reducer(noConfirm, 'save-request')).toEqual({
+            next: noConfirm,
+            effect: 'save',
+        });
+        const confirmRequired = {
+            ...noConfirm,
+            requireConfirmOnSave: true,
+        };
+        const confirm = reducer(confirmRequired, 'save-request');
+        expect(confirm).toEqual({
+            next: { ...confirmRequired, pendingConfirm: 'save-confirm' },
+            effect: null,
+        });
+        expect(reducer(confirm.next, 'save-cancel')).toEqual({
+            next: { ...confirmRequired, pendingConfirm: null },
+            effect: null,
+        });
+        expect(reducer(confirm.next, 'save-confirm')).toEqual({
+            next: { ...confirmRequired, pendingConfirm: null },
+            effect: 'save',
+        });
+    });
+    it('prompts skip-empty confirmation on empty save, updates search state, and quits without saving', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        });
+        const emptySave = reducer(state, 'save-request');
+        expect(emptySave).toEqual({
+            next: { ...state, pendingConfirm: 'skip-empty' },
+            effect: null,
+        });
+        expect(reducer(emptySave.next, 'save-confirm')).toEqual({
+            next: { ...state, pendingConfirm: null },
+            effect: 'quit-without-save',
+        });
+        expect(reducer(emptySave.next, 'save-cancel')).toEqual({
+            next: { ...state, pendingConfirm: null },
+            effect: null,
+        });
+        expect(reducer(reducer(reducer(state, 'search-start').next, { type: 'search-input', value: 'a' }).next, 'search-submit').next.search).toEqual({ editing: false, query: 'a' });
+        expect(reducer(state, 'quit')).toEqual({
+            next: state,
+            effect: 'quit-without-save',
+        });
+    });
+    it('treats skip-empty confirmation as a save with empty selection when skipEmptyAction is save-empty', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+            skipEmptyAction: 'save-empty',
+        });
+        const emptySave = reducer(state, 'save-request');
+        expect(emptySave).toEqual({
+            next: { ...state, pendingConfirm: 'skip-empty' },
+            effect: null,
+        });
+        expect(reducer(emptySave.next, 'save-confirm')).toEqual({
+            next: { ...state, pendingConfirm: null },
+            effect: 'save',
+        });
+    });
+    it('clears transient hints only when their expiry time has passed', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingSelectedIds: [],
+        });
+        const withHint = {
+            ...state,
+            transientHint: {
+                text: 'Select at least one item or press esc to cancel',
+                expiresAt: 11500,
+            },
+        };
+        expect(clearExpiredTransientHint(withHint, 11499)).toBe(withHint);
+        expect(clearExpiredTransientHint(withHint, 11500)).toEqual({
+            ...withHint,
+            transientHint: null,
+        });
+        expect(reducer(withHint, 'clear-transient-hint', 11501)).toEqual({
+            next: {
+                ...withHint,
+                transientHint: null,
+            },
+            effect: null,
+        });
+    });
+});

package/dist/tree-picker-tui.d.ts

@@ -0,0 +1,78 @@
+import { type ReactNode } from 'react';
+import { type PickerCommand, type PickerState } from './tree-picker-state.js';
+import type { KtxCliIo } from './cli-runtime.js';
+export interface TreePickerTuiIo extends KtxCliIo {
+    stdin?: {
+        isTTY?: boolean;
+        setRawMode?(value: boolean): void;
+    };
+    stdout: KtxCliIo['stdout'] & {
+        isTTY?: boolean;
+        columns?: number;
+        rows?: number;
+    };
+}
+interface InkKey {
+    leftArrow?: boolean;
+    rightArrow?: boolean;
+    upArrow?: boolean;
+    downArrow?: boolean;
+    return?: boolean;
+    escape?: boolean;
+    ctrl?: boolean;
+    backspace?: boolean;
+    delete?: boolean;
+}
+export type TreePickerResult = {
+    kind: 'save';
+    selectedIds: string[];
+} | {
+    kind: 'quit';
+};
+export interface TreePickerChrome {
+    title: string;
+    helpText?: string;
+    subtitleLines?: readonly string[];
+    warningLines?: readonly string[];
+    confirmSaveMessage?: (state: PickerState) => string;
+    skipEmptyMessage?: string;
+}
+export interface TreePickerRenderInput {
+    initialState: PickerState;
+    chrome: TreePickerChrome;
+}
+interface TreePickerAppProps extends TreePickerRenderInput {
+    terminalRows?: number;
+    terminalWidth?: number;
+    env?: NodeJS.ProcessEnv;
+    onExit(result: TreePickerResult): void;
+}
+export interface TreePickerInkInstance {
+    rerender(tree: ReactNode): void;
+    unmount(): void;
+    waitUntilExit(): Promise<void>;
+}
+export interface TreePickerInkRenderOptions {
+    stdin?: TreePickerTuiIo['stdin'];
+    stdout: TreePickerTuiIo['stdout'];
+    stderr: TreePickerTuiIo['stderr'];
+    exitOnCtrlC: boolean;
+    patchConsole: boolean;
+    maxFps: number;
+    alternateScreen: boolean;
+}
+export declare function resolveTreePickerWidth(columns: number | undefined): number;
+export declare function sanitizeTreePickerTuiError(error: unknown): string;
+export declare function windowOffset(count: number, selected: number, visible: number): number;
+export declare function windowItems<T>(items: T[], selected: number, visible: number): {
+    items: T[];
+    offset: number;
+};
+export declare function treePickerCommandForInkInput(input: string, key: InkKey, search: PickerState['search'], pendingConfirm: PickerState['pendingConfirm']): PickerCommand | null;
+export declare function TreePickerApp(props: TreePickerAppProps): ReactNode;
+export interface RenderTreePickerOptions {
+    renderInk?: (tree: ReactNode, options: TreePickerInkRenderOptions) => TreePickerInkInstance;
+    scriptedModeHint?: string;
+}
+export declare function renderTreePickerTui(input: TreePickerRenderInput, io: TreePickerTuiIo, options?: RenderTreePickerOptions): Promise<TreePickerResult>;
+export {};

package/dist/tree-picker-tui.js

@@ -0,0 +1,226 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/* @jsxImportSource react */
+import { Box, Text, render as renderInkRuntime, useApp, useInput } from 'ink';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { filterTree, flattenSelection, hasPartialChildren, isAncestorChecked, reducer, visibleNodeIds, } from './tree-picker-state.js';
+const COLOR_THEME = {
+    text: 'white',
+    muted: 'gray',
+    active: 'cyan',
+    selected: 'green',
+    warning: 'yellow',
+};
+const NO_COLOR_THEME = {
+    text: 'white',
+    muted: 'white',
+    active: 'white',
+    selected: 'white',
+    warning: 'white',
+};
+const DEFAULT_TREE_PICKER_HELP_TEXT = 'Right Arrow to expand, Up/Down to move, Space to select or unselect, Slash to filter, Enter to confirm, Escape to go back, or Ctrl+C to exit.';
+const DEFAULT_SKIP_EMPTY_MESSAGE = 'Nothing selected. Skip this step? Press Enter to skip or Escape to go back.';
+function resolveTheme(env = process.env) {
+    return env.NO_COLOR || env.TERM === 'dumb' ? NO_COLOR_THEME : COLOR_THEME;
+}
+export function resolveTreePickerWidth(columns) {
+    const resolvedColumns = columns ?? 100;
+    return Math.max(60, Math.min(120, resolvedColumns - 4));
+}
+function rowMatchesSearch(state, nodeId) {
+    const query = state.search.query.trim().toLocaleLowerCase();
+    if (!query) {
+        return false;
+    }
+    const node = state.byId.get(nodeId);
+    if (!node) {
+        return false;
+    }
+    return node.title.toLocaleLowerCase().includes(query) || node.path.toLocaleLowerCase().includes(query);
+}
+export function sanitizeTreePickerTuiError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message
+        .replace(/[a-z][a-z0-9+.-]*:\/\/[^\s]+/gi, '[redacted-url]')
+        .replace(/\b(api[_-]?key|password|token|secret)=\S+/gi, '[redacted]');
+}
+export function windowOffset(count, selected, visible) {
+    if (count <= visible)
+        return 0;
+    return Math.max(0, Math.min(count - visible, selected - Math.floor(visible / 2)));
+}
+export function windowItems(items, selected, visible) {
+    const offset = windowOffset(items.length, selected, visible);
+    return { items: items.slice(offset, offset + visible), offset };
+}
+function truncateText(value, width) {
+    if (value.length <= width)
+        return value;
+    if (width <= 3)
+        return value.slice(0, width);
+    return `${value.slice(0, width - 3)}...`;
+}
+export function treePickerCommandForInkInput(input, key, search, pendingConfirm) {
+    if (pendingConfirm) {
+        if (input === 'y' || key.return)
+            return 'save-confirm';
+        if (input === 'n' || key.escape)
+            return 'save-cancel';
+        if (key.ctrl === true && input === 'c')
+            return 'quit';
+        return null;
+    }
+    if (search.editing) {
+        if (key.escape)
+            return 'search-cancel';
+        if (key.return)
+            return 'search-submit';
+        if (key.backspace || key.delete)
+            return 'search-backspace';
+        if (key.downArrow)
+            return 'cursor-down';
+        if (key.upArrow)
+            return 'cursor-up';
+        if (input.length === 1 && input >= ' ' && input !== '')
+            return { type: 'search-input', value: input };
+        return null;
+    }
+    if (key.ctrl === true && input === 'c')
+        return 'quit';
+    if (key.upArrow)
+        return 'cursor-up';
+    if (key.downArrow)
+        return 'cursor-down';
+    if (key.leftArrow)
+        return 'cursor-left';
+    if (key.rightArrow)
+        return 'cursor-right';
+    if (key.return)
+        return 'save-request';
+    if (input === ' ')
+        return 'toggle-check';
+    if (input === '/')
+        return 'search-start';
+    if (input === 'a')
+        return 'toggle-select-all-visible';
+    if (input === 'n')
+        return 'select-none';
+    if (key.escape)
+        return 'quit';
+    return null;
+}
+function PickerRow(props) {
+    const node = props.state.byId.get(props.nodeId);
+    if (!node)
+        return null;
+    const focused = props.state.cursorId === node.id;
+    const locked = isAncestorChecked(node.id, props.state.checked, props.state.byId);
+    const checked = props.state.checked.has(node.id);
+    const isSelected = checked || locked;
+    const partial = !isSelected && hasPartialChildren(node.id, props.state.checked, props.state.byId);
+    const glyph = isSelected ? '◼' : partial ? '◧' : '◻';
+    const glyphColor = isSelected || partial ? props.theme.selected : props.theme.muted;
+    const childAffordance = node.childIds.length > 0 ? (props.state.expanded.has(node.id) ? ' ▾' : ` ▸ (${node.childIds.length})`) : '';
+    const indent = ' '.repeat(node.depth * 2);
+    const titleColor = focused ? props.theme.active : props.theme.text;
+    const inverse = rowMatchesSearch(props.state, node.id);
+    const prefixWidth = indent.length + 2 + childAffordance.length;
+    const title = truncateText(node.title, Math.max(10, props.width - prefixWidth));
+    return (_jsxs(Text, { children: [_jsxs(Text, { color: glyphColor, children: [indent, glyph] }), _jsxs(Text, { color: titleColor, strikethrough: node.archived, bold: focused, children: [' ', _jsx(Text, { inverse: inverse, children: title })] }), childAffordance.length > 0 ? _jsx(Text, { color: props.theme.muted, children: childAffordance }) : null] }));
+}
+export function TreePickerApp(props) {
+    const app = useApp();
+    const [state, setState] = useState(props.initialState);
+    const stateRef = useRef(state);
+    const theme = useMemo(() => resolveTheme(props.env), [props.env]);
+    const visibleIds = visibleNodeIds(state);
+    const selectedIndex = Math.max(0, visibleIds.indexOf(state.cursorId));
+    const reservedRows = state.pendingConfirm === 'save-confirm' ? 10 : 9;
+    const visibleRows = Math.max(5, Math.min(12, (props.terminalRows ?? 24) - reservedRows));
+    const rows = windowItems(visibleIds, selectedIndex, visibleRows);
+    const hiddenAbove = rows.offset;
+    const hiddenBelow = Math.max(0, visibleIds.length - rows.offset - rows.items.length);
+    const searchMatchCount = filterTree(state).visibleIds.size;
+    const width = resolveTreePickerWidth(props.terminalWidth);
+    const showSearch = state.search.editing || state.search.query.trim().length > 0;
+    const helpText = props.chrome.helpText ?? DEFAULT_TREE_PICKER_HELP_TEXT;
+    const skipEmptyMessage = props.chrome.skipEmptyMessage ?? DEFAULT_SKIP_EMPTY_MESSAGE;
+    stateRef.current = state;
+    useEffect(() => {
+        const hint = state.transientHint;
+        if (!hint) {
+            return;
+        }
+        const clearHint = () => {
+            setState((current) => {
+                const { next } = reducer(current, 'clear-transient-hint');
+                stateRef.current = next;
+                return next;
+            });
+        };
+        const delay = hint.expiresAt - Date.now();
+        if (delay <= 0) {
+            clearHint();
+            return;
+        }
+        const timeout = setTimeout(clearHint, delay);
+        return () => clearTimeout(timeout);
+    }, [state.transientHint?.expiresAt]);
+    useInput((input, key) => {
+        const command = treePickerCommandForInkInput(input, key, stateRef.current.search, stateRef.current.pendingConfirm);
+        if (!command) {
+            return;
+        }
+        const { next, effect } = reducer(stateRef.current, command);
+        stateRef.current = next;
+        setState(next);
+        if (effect === 'save') {
+            props.onExit({ kind: 'save', selectedIds: flattenSelection(next.checked, next.byId) });
+            app.exit();
+            return;
+        }
+        if (effect === 'quit-without-save') {
+            props.onExit({ kind: 'quit' });
+            app.exit();
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { color: theme.active, children: "\u25C6" }), _jsxs(Text, { bold: true, children: [" ", props.chrome.title] })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderTop: false, borderRight: false, borderBottom: false, borderColor: theme.active, paddingLeft: 1, children: [_jsx(Text, { color: theme.muted, children: helpText }), _jsx(Text, { children: " " }), (props.chrome.subtitleLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.muted, children: line }, `subtitle-${idx}`))), (props.chrome.warningLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.warning, children: line }, `chromewarn-${idx}`))), state.preLoadWarnings.map((warning) => (_jsx(Text, { color: theme.warning, children: warning }, warning))), showSearch ? (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "/ " }), _jsxs(Text, { children: [state.search.query, state.search.editing ? '█' : ''] }), _jsxs(Text, { color: theme.muted, children: ["  (", searchMatchCount, " matches)"] })] })) : null, _jsx(Text, { children: " " }), hiddenAbove > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2191 ", hiddenAbove, " more"] }) : null, rows.items.map((nodeId) => (_jsx(PickerRow, { state: state, nodeId: nodeId, width: width, theme: theme }, nodeId))), hiddenBelow > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2193 ", hiddenBelow, " more"] }) : null, state.pendingConfirm === 'save-confirm' ? (_jsx(Text, { color: theme.warning, children: props.chrome.confirmSaveMessage
+                            ? props.chrome.confirmSaveMessage(state)
+                            : 'Confirm save? Press Enter to confirm or Escape to go back.' })) : null, state.pendingConfirm === 'skip-empty' ? _jsx(Text, { color: theme.warning, children: skipEmptyMessage }) : null, state.transientHint ? _jsx(Text, { color: theme.warning, children: state.transientHint.text }) : null] }), _jsx(Text, { color: theme.active, children: "\u2514" })] }));
+}
+function renderInk(tree, options) {
+    return renderInkRuntime(tree, {
+        stdin: options.stdin,
+        stdout: options.stdout,
+        stderr: options.stderr,
+        exitOnCtrlC: options.exitOnCtrlC,
+        patchConsole: options.patchConsole,
+        maxFps: options.maxFps,
+        alternateScreen: options.alternateScreen,
+    });
+}
+export async function renderTreePickerTui(input, io, options = {}) {
+    let result = { kind: 'quit' };
+    let instance = null;
+    try {
+        instance = (options.renderInk ?? renderInk)(_jsx(TreePickerApp, { ...input, terminalRows: io.stdout.rows ?? process.stdout.rows ?? 24, terminalWidth: io.stdout.columns ?? process.stdout.columns, onExit: (next) => {
+                result = next;
+                instance?.unmount();
+            } }), {
+            stdin: io.stdin,
+            stdout: io.stdout,
+            stderr: io.stderr,
+            exitOnCtrlC: false,
+            patchConsole: false,
+            maxFps: 30,
+            alternateScreen: false,
+        });
+        await instance.waitUntilExit();
+        instance.unmount();
+        return result;
+    }
+    catch (error) {
+        const hint = options.scriptedModeHint ?? 'Picker requires a TTY.';
+        io.stderr.write(`${hint} ${sanitizeTreePickerTuiError(error)}\n`);
+        return { kind: 'quit' };
+    }
+}

package/dist/tree-picker-tui.test.d.ts

@@ -0,0 +1 @@
+export {};