@visulima/tui 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/ink/hooks/use-text-selection.d.ts

@@ -1,45 +0,0 @@
-/**
- * React hook for managing text selection with keyboard and clipboard integration.
- *
- * Builds on the existing Selection/Range classes from `../selection.ts` and
- * provides a high-level API for Shift+Arrow selection and copy-to-clipboard.
- */
-import type { RefObject } from "react";
-import type { DOMElement } from "../dom.d.ts";
-import { Selection } from "../selection.d.ts";
-export type UseTextSelectionOptions = {
-    /**
-     * Automatically copy selected text to clipboard when selection changes.
-     * @default false
-     */
-    readonly copyOnSelect?: boolean;
-    /**
-     * Enable or disable text selection.
-     * @default true
-     */
-    readonly isActive?: boolean;
-    /**
-     * Called whenever the selection changes.
-     */
-    readonly onSelectionChange?: (selectedText: string) => void;
-};
-export type UseTextSelectionResult = {
-    /** Clear the current selection. */
-    readonly clearSelection: () => void;
-    /** Select all content within the referenced element. */
-    readonly selectAll: () => void;
-    /** The currently selected text. */
-    readonly selectedText: string;
-    /** The underlying Selection instance. */
-    readonly selection: Selection;
-};
-/**
- * Hook for managing text selection on a DOM element.
- *
- * ```tsx
- * const ref = useRef(null);
- * const { selectedText, selectAll, clearSelection } = useTextSelection(ref);
- * ```
- */
-declare const useTextSelection: (ref: RefObject<DOMElement | null>, options?: UseTextSelectionOptions) => UseTextSelectionResult;
-export default useTextSelection;

package/dist/ink/hooks/use-timer.d.ts

@@ -1,49 +0,0 @@
-export type UseTimerOptions = {
-    /**
-     * Whether to start the timer immediately.
-     *
-     * @default false
-     */
-    readonly autoStart?: boolean;
-    /**
-     * Total countdown duration in milliseconds.
-     */
-    readonly duration: number;
-    /**
-     * Tick interval in milliseconds.
-     *
-     * @default 1000
-     */
-    readonly interval?: number;
-    /**
-     * Called once when the timer reaches zero.
-     */
-    readonly onTimeout?: () => void;
-};
-export type UseTimerResult = {
-    /** Whether the countdown has reached zero. */
-    readonly isFinished: boolean;
-    /** Whether the timer is currently counting down. */
-    readonly isRunning: boolean;
-    /** Milliseconds remaining (clamped to >= 0). */
-    readonly remaining: number;
-    /** Reset the timer to the original duration and stop it. */
-    readonly reset: () => void;
-    /** Start the countdown. */
-    readonly start: () => void;
-    /** Stop (pause) the countdown. */
-    readonly stop: () => void;
-    /** Toggle between running and stopped. */
-    readonly toggle: () => void;
-};
-/**
- * A countdown timer hook built on `useAnimation`.
- *
- * ```tsx
- * const { remaining, isRunning, start, stop, reset, isFinished } = useTimer({
- *   duration: 60_000,
- *   onTimeout: () => console.log("Time's up!"),
- * });
- * ```
- */
-export default function useTimer(options: UseTimerOptions): UseTimerResult;

package/dist/ink/hooks/use-window-size.d.ts

@@ -1,18 +0,0 @@
-/**
- * Dimensions of the terminal window.
- */
-export type WindowSize = {
-    /**
-     * Number of columns (horizontal character cells).
-     */
-    readonly columns: number;
-    /**
-     * Number of rows (vertical character cells).
-     */
-    readonly rows: number;
-};
-/**
- * A React hook that returns the current terminal window dimensions and re-renders the component whenever the terminal is resized.
- */
-declare const useWindowSize: () => WindowSize;
-export default useWindowSize;

package/dist/ink/ime-utils.d.ts

@@ -1,25 +0,0 @@
-/**
- * Detect whether a string contains non-ASCII characters that are likely
- * IME (Input Method Editor) composition input — CJK ideographs, Hangul,
- * Thai, Vietnamese diacritics, etc.
- */
-declare const isIMEInput: (data: string) => boolean;
-type IMECompositionBufferOptions = {
-    onFlush: (text: string) => void;
-    timeout: number;
-};
-/**
- * Buffers rapid multi-byte character input from IME and flushes the
- * accumulated text after a configurable timeout.
- */
-declare class IMECompositionBuffer {
-    private buffer;
-    private timer;
-    private readonly onFlush;
-    private readonly timeout;
-    constructor({ onFlush, timeout }: IMECompositionBufferOptions);
-    add(text: string): void;
-    flush(): void;
-    destroy(): void;
-}
-export { IMECompositionBuffer, isIMEInput };

package/dist/ink/ink.d.ts

@@ -1,189 +0,0 @@
-import type { ReactNode } from "react";
-import * as dom from "./dom.d.ts";
-import type { KittyKeyboardOptions } from "./kitty-keyboard.d.ts";
-import type { CursorPosition } from "./log-update.d.ts";
-/**
- * Performance metrics for a render operation.
- */
-export type RenderMetrics = {
-    /**
-     * Time spent rendering in milliseconds.
-     */
-    renderTime: number;
-};
-export type Options = {
-    /**
-     * Render the app in the terminal's alternate screen buffer. When enabled, the app renders on a separate screen, and the original terminal content is restored when the app exits. This is the same mechanism used by programs like vim, htop, and less.
-     *
-     * Note: The terminal's scrollback buffer is not available while in the alternate screen. This is standard terminal behavior; programs like vim use the alternate screen specifically to avoid polluting the user's scrollback history.
-     *
-     * Note: Ink intentionally treats alternate-screen teardown output as disposable. It does not preserve or replay teardown-time frames, hook writes, or `console.*` output after restoring the primary screen.
-     *
-    Only works in interactive mode. Ignored when `interactive` is `false` or in a non-interactive environment (CI, piped stdout).
-     
-    Note: Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change this option or create a fresh instance.
-     
-    @default false
-     
-    @see {@link RenderOptions.alternateScreen}
-     */
-    alternateScreen?: boolean;
-    /**
-     * Enable React Concurrent Rendering mode.
-     *
-     * When enabled:
-     * - Suspense boundaries work correctly with async data
-     * - `useTransition` and `useDeferredValue` are fully functional
-    - Updates can be interrupted for higher priority work
-     
-    Note: Concurrent mode changes the timing of renders. Some tests may need to use `act()` to properly await updates. Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change the rendering mode or create a fresh instance.
-     
-    @default false
-    @experimental
-     */
-    concurrent?: boolean;
-    debug: boolean;
-    exitOnCtrlC: boolean;
-    incrementalRendering?: boolean;
-    /**
-     * Override automatic interactive mode detection.
-     *
-     * By default, Ink detects whether the environment is interactive based on CI detection (via [`is-in-ci`](https://github.com/sindresorhus/is-in-ci)) and `stdout.isTTY`. Most users should not need to set this.
-     *
-     * When non-interactive, Ink disables ANSI erase sequences, cursor manipulation, synchronized output, resize handling, and kitty keyboard auto-detection, writing only the final frame at unmount.
-     *
-    Set to `false` to force non-interactive mode or `true` to force interactive mode when the automatic detection doesn't suit your use case.
-     
-    Note: Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change this option or create a fresh instance.
-     
-    @default true (false if in CI or `stdout.isTTY` is falsy)
-     
-    @see {@link RenderOptions.interactive}
-     */
-    interactive?: boolean;
-    isScreenReaderEnabled?: boolean;
-    kittyKeyboard?: KittyKeyboardOptions;
-    maxFps?: number;
-    onRender?: (metrics: RenderMetrics) => void;
-    patchConsole: boolean;
-    standardReactLayoutTiming?: boolean;
-    /**
-     * Whether to track text selection state during rendering.
-     *
-     * @default false
-     */
-    trackSelection?: boolean;
-    stderr: NodeJS.WriteStream;
-    stdin: NodeJS.ReadStream;
-    stdout: NodeJS.WriteStream;
-    /**
-     * Use the native Rust cell-diff renderer instead of ANSI string-based log-update.
-     * Produces a Uint32Array buffer that the Rust renderer diffs cell-by-cell,
-     * generating minimal ANSI escape sequences. Significantly reduces GC pressure
-     * and improves rendering performance for complex UIs.
-     *
-     * Falls back to the string-based path if native bindings are not available.
-     * @default false
-     */
-    useNativeRenderer?: boolean;
-    waitUntilExit?: () => Promise<unknown>;
-};
-export default class Ink {
-    /**
-     * Whether this instance is using concurrent rendering mode.
-     */
-    readonly isConcurrent: boolean;
-    private readonly options;
-    private readonly log;
-    private manualCursorPosition;
-    private renderedCursorPosition;
-    private renderedCursorRequested;
-    private readonly throttledLog;
-    private readonly isScreenReaderEnabled;
-    private readonly interactive;
-    private readonly renderThrottleMs;
-    private alternateScreen;
-    private isUnmounted;
-    private isUnmounting;
-    private lastOutput;
-    private lastOutputToRender;
-    private lastOutputHeight;
-    private lastTerminalWidth;
-    private readonly nativeLog;
-    private readonly useNativeRenderer;
-    private readonly container;
-    readonly rootNode: dom.DOMElement;
-    private fullStaticOutput;
-    private readonly exitPromise;
-    private exitResult;
-    private beforeExitHandler?;
-    private restoreConsole?;
-    private unsubscribeResize?;
-    private readonly throttledOnRender?;
-    private hasPendingThrottledRender;
-    private kittyProtocolEnabled;
-    private cancelKittyDetection?;
-    private nextRenderCommit?;
-    private deferredInitDone;
-    constructor(options: Options);
-    /**
-     * Perform deferred initialization on the first render frame.
-     * Kitty keyboard auto-detection is deferred here because the CSI ? u
-     * query sets up a synchronous stdin listener with a 200ms timeout.
-     * "enabled" mode runs immediately in the constructor (it's just a write).
-     */
-    private runDeferredInit;
-    resized: () => void;
-    resolveExitPromise: (result?: unknown) => void;
-    rejectExitPromise: (reason?: Error) => void;
-    unsubscribeExit: () => void;
-    handleAppExit: (errorOrResult?: unknown) => void;
-    getActiveCursorPosition: () => CursorPosition | undefined;
-    setCursorPosition: (position: CursorPosition | undefined) => void;
-    restoreLastOutput: () => void;
-    calculateLayout: () => void;
-    private calculateScrollAndTriggerObservers;
-    /**
-     * Force a full layout recalculation by marking all text nodes dirty.
-     * Useful when the string width function changes or terminal font changes.
-     */
-    recalculateLayout(): void;
-    /**
-     * Walk the DOM tree before Yoga layout to handle StaticRender nodes:
-     * - Re-attach Yoga children if a cached render was invalidated
-     * - Pre-render ink-static-render nodes that don't have a cached render yet
-     */
-    private prepareYogaTree;
-    private markAllTextNodesDirty;
-    onRender: () => void;
-    private accessibilityContextValue;
-    render(node: ReactNode): void;
-    writeToStdout: (data: string) => void;
-    writeToStderr: (data: string) => void;
-    unmount: (error?: Error | number | null) => void;
-    waitUntilExit(): Promise<unknown>;
-    waitUntilRenderFlush(): Promise<void>;
-    clear(): void;
-    patchConsole(): void;
-    private setAlternateScreen;
-    private resolveInteractiveOption;
-    private resolveAlternateScreenOption;
-    private shouldSync;
-    private writeBestEffort;
-    private awaitExit;
-    private hasPendingConcurrentWork;
-    private awaitNextRender;
-    private renderInteractiveFrame;
-    /**
-     * Handle kitty keyboard "enabled" mode immediately (just a stdout.write).
-     * Called from the constructor.
-     */
-    private initImmediateKittyKeyboard;
-    /**
-     * Handle kitty keyboard "auto" mode detection. Deferred to first render
-     * because the CSI ? u query sets up a stdin listener with a 200ms timeout.
-     */
-    private initDeferredKittyKeyboard;
-    private confirmKittySupport;
-    private enableKittyProtocol;
-}

package/dist/ink/input-parser.d.ts

@@ -1,10 +0,0 @@
-export type InputEvent = string | {
-    readonly paste: string;
-};
-export type InputParser = {
-    flushPendingEscape: () => string | undefined;
-    hasPendingEscape: () => boolean;
-    push: (chunk: string) => InputEvent[];
-    reset: () => void;
-};
-export declare const createInputParser: () => InputParser;

package/dist/ink/input-utils.d.ts

@@ -1,16 +0,0 @@
-/**
- * Shared input filtering utilities for text input components.
- */
-/**
- * Check if a character is a C0 control character or DEL.
- */
-export declare const isControlCharacter: (input: string) => boolean;
-/**
- * Determine whether the input should be inserted as text.
- * Filters out modifier chords (Ctrl+S, Meta+S, etc.) while allowing
- * AltGr-produced symbols (Ctrl+Meta+@, Ctrl+Meta+€) on international keyboards.
- */
-export declare const isInsertableInput: (input: string, key: {
-    ctrl: boolean;
-    meta: boolean;
-}) => boolean;

package/dist/ink/instances.d.ts

@@ -1,3 +0,0 @@
-import type Ink from "./ink/ink.d.ts";
-declare const instances: WeakMap<NodeJS.WriteStream, Ink>;
-export default instances;

package/dist/ink/kitty-keyboard.d.ts

@@ -1,23 +0,0 @@
-export declare const kittyFlags: {
-    readonly disambiguateEscapeCodes: 1;
-    readonly reportAllKeysAsEscapeCodes: 8;
-    readonly reportAlternateKeys: 4;
-    readonly reportAssociatedText: 16;
-    readonly reportEventTypes: 2;
-};
-export type KittyFlagName = keyof typeof kittyFlags;
-export declare function resolveFlags(flags: KittyFlagName[]): number;
-export declare const kittyModifiers: {
-    readonly alt: 2;
-    readonly capsLock: 64;
-    readonly ctrl: 4;
-    readonly hyper: 16;
-    readonly meta: 32;
-    readonly numLock: 128;
-    readonly shift: 1;
-    readonly super: 8;
-};
-export type KittyKeyboardOptions = {
-    flags?: KittyFlagName[];
-    mode?: "auto" | "enabled" | "disabled";
-};

package/dist/ink/layout.d.ts

@@ -1,26 +0,0 @@
-import type { DOMElement, DOMNode } from "./dom.d.ts";
-import type { TextFragment } from "./measure-element.d.ts";
-type Position = {
-    x: number;
-    y: number;
-};
-declare const getAbsolutePosition: (node: DOMElement) => Position | undefined;
-declare const getAbsoluteContentPosition: (node: DOMElement) => Position | undefined;
-/**
- * Generic layout tree walker with callbacks for text, newline, and space events.
- * Used by selection.ts for extracting text from the DOM tree with proper layout positioning.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export type LayoutCallbacks<T> = {
-    initialState: () => T;
-    onNewline: (count: number, state: T) => void;
-    onSpace: (count: number, state: T) => void;
-    onText: (fragment: TextFragment, state: T) => void;
-};
-export declare const processLayout: <T>(node: DOMNode, callbacks: LayoutCallbacks<T>) => {
-    lineBottom: number;
-    state: T;
-};
-export type { Position };
-export { getAbsoluteContentPosition, getAbsolutePosition };

package/dist/ink/log-update-native.d.ts

@@ -1,14 +0,0 @@
-export type NativeLogUpdate = {
-    clear: () => void;
-    destroy: () => void;
-    render: (buffer: Uint32Array, width: number, height: number) => void;
-    resize: (width: number, height: number) => void;
-};
-/**
- * Create a native (Rust-backed) renderer for Ink's output.
- *
- * The native binding is loaded lazily — if it's not available (e.g., unsupported
- * platform), `createNative` returns `undefined`. The binding lookup is cached
- * at the module level so subsequent calls avoid the try-catch + require overhead.
- */
-export declare const createNative: (stream: NodeJS.WriteStream) => NativeLogUpdate | undefined;

package/dist/ink/log-update.d.ts

@@ -1,21 +0,0 @@
-import type { Writable } from "node:stream";
-import type { CursorPosition } from "./cursor-helpers.d.ts";
-export type { CursorPosition } from "./cursor-helpers.d.ts";
-export type LogUpdate = {
-    clear: () => void;
-    done: () => void;
-    isCursorDirty: () => boolean;
-    reset: () => void;
-    setCursorPosition: (position: CursorPosition | undefined) => void;
-    sync: (string_: string) => void;
-    willRender: (string_: string) => boolean;
-    (string_: string): boolean;
-};
-declare const create: (stream: Writable, { incremental, showCursor }?: {
-    incremental?: boolean;
-    showCursor?: boolean;
-}) => LogUpdate;
-declare const logUpdate: {
-    create: typeof create;
-};
-export default logUpdate;

package/dist/ink/measure-element.d.ts

@@ -1,147 +0,0 @@
-import type { DOMElement, DOMNode } from "./dom.d.ts";
-type Output = {
-    /**
-     * Element height.
-     */
-    height: number;
-    /**
-     * Element width.
-     */
-    width: number;
-    /**
-     * Element X position relative to Ink output origin.
-     */
-    x: number;
-    /**
-     * Element Y position relative to Ink output origin.
-     */
-    y: number;
-};
-/**
- * Measure the dimensions of a particular `<Box>` element.
- * Returns an object with `x`, `y`, `width` and `height` properties.
- */
-declare const measureElement: (node: DOMElement) => Output;
-export default measureElement;
-/**
- * Get an element's inner width (excluding borders).
- */
-export declare const getInnerWidth: (node: DOMElement) => number;
-/**
- * Get an element's inner height (excluding borders).
- */
-export declare const getInnerHeight: (node: DOMElement) => number;
-/**
- * Get an element's position and dimensions relative to the root,
- * accounting for scroll offsets of ancestor elements.
- */
-export declare const getBoundingBox: (node: DOMElement) => {
-    height: number;
-    width: number;
-    x: number;
-    y: number;
-};
-/**
- * Get how much scroll height was added by stableScrollback.
- */
-export declare const getAddedScrollHeight: (node: DOMElement) => number;
-export type ScrollbarBoundingBox = {
-    height: number;
-    thumb: {
-        end: number;
-        endHalf: number;
-        height: number;
-        start: number;
-        startHalf: number;
-        width: number;
-        x: number;
-        y: number;
-    };
-    width: number;
-    x: number;
-    y: number;
-};
-export declare const calculateScrollbarThumb: (options: {
-    axis: "horizontal" | "vertical";
-    clientDimension: number;
-    scrollbarDimension: number;
-    scrollDimension: number;
-    scrollPosition: number;
-}) => {
-    endIndex: number;
-    startIndex: number;
-    thumbEndHalf: number;
-    thumbStartHalf: number;
-};
-export declare const calculateScrollbarLayout: (options: {
-    axis: "horizontal" | "vertical";
-    clientDimension: number;
-    hasOppositeScrollbar: boolean;
-    height: number;
-    marginBottom: number;
-    marginRight: number;
-    scrollDimension: number;
-    scrollPosition: number;
-    width: number;
-    x: number;
-    y: number;
-}) => ScrollbarBoundingBox | undefined;
-/**
- * Get the bounding box of the vertical scrollbar.
- */
-export declare const getVerticalScrollbarBoundingBox: (node: DOMElement, offset?: {
-    x: number;
-    y: number;
-}) => ScrollbarBoundingBox | undefined;
-/**
- * Get the bounding box of the horizontal scrollbar.
- */
-export declare const getHorizontalScrollbarBoundingBox: (node: DOMElement, offset?: {
-    x: number;
-    y: number;
-}) => ScrollbarBoundingBox | undefined;
-/**
- * Get the top position of a node relative to a given ancestor.
- * Returns undefined if the ancestor is not in the node's parent chain.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export declare const getRelativeTop: (node: DOMElement, ancestor?: DOMElement) => number | undefined;
-/**
- * Get the left position of a node relative to a given ancestor.
- * Returns undefined if the ancestor is not in the node's parent chain.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export declare const getRelativeLeft: (node: DOMElement, ancestor?: DOMElement) => number | undefined;
-/**
- * A text fragment from the layout tree with its position and dimensions.
- * Used by `processLayout` for text extraction and selection.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export type TextFragment = {
-    height: number;
-    node: DOMElement;
-    text: string;
-    visualX: number;
-    visualY: number;
-    width: number;
-    x: number;
-    y: number;
-};
-/**
- * Get the text content of a DOM node (text node value or squashed children).
- */
-export declare const getText: (node: DOMNode) => string;
-/**
- * Walk the layout tree to collect all text fragments in document order,
- * with their positions adjusted for borders and flex layout.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export declare const collectSortedFragments: (node: DOMNode) => {
-    fragments: TextFragment[];
-    removedHorizontal: number;
-    removedVertical: number;
-};

package/dist/ink/measure-text.d.ts

@@ -1,56 +0,0 @@
-import { StyledLine } from "./styled-line.d.ts";
-export type StringWidthFunction = (text: string) => number;
-type Output = {
-    height: number;
-    width: number;
-};
-/**
- * Enable or disable the StyledLine tokenization cache at runtime.
- * Disabling clears the existing cache.
- */
-export declare const setEnableStyledLineCache: (enabled: boolean) => void;
-/**
- * Clear only the StyledLine tokenization cache.
- */
-export declare const clearStyledLineCache: () => void;
-/**
- * Replace the string width function used for text measurement.
- * Useful for terminals with non-standard character widths.
- * Clears the measurement cache when called.
- */
-export declare const setStringWidthFunction: (function_: StringWidthFunction) => void;
-/**
- * Clear the string width measurement cache. Call this if the terminal
- * environment changes in a way that affects character widths.
- */
-export declare const clearStringWidthCache: () => void;
-/**
- * Get the visual width of a single character, with caching and error handling.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export declare const inkCharacterWidth: (text: string) => number;
-declare const measureText: (text: string) => Output;
-export default measureText;
-/**
- * Convert a text string to a StyledLine, with caching.
- * Uses the direct text → StyledLine pipeline (handles combining chars,
- * tabs, regional indicators, ANSI codes, etc.) without intermediate
- * StyledChar objects.
- */
-export declare const toStyledLine: (text: string) => StyledLine;
-/**
- * Get the total visual width of a StyledLine.
- */
-export declare const styledLineWidth: (line: StyledLine) => number;
-/**
- * Split a StyledLine by newline characters into multiple StyledLines.
- */
-export declare const splitStyledLineByNewline: (line: StyledLine) => StyledLine[];
-/**
- * Measure the dimensions of a StyledLine (width of widest line, height in lines).
- */
-export declare const measureStyledLine: (line: StyledLine) => {
-    height: number;
-    width: number;
-};

package/dist/ink/mouse/Fullscreen.d.ts

@@ -1,8 +0,0 @@
-/**
- * Ported from `\@zenobius/ink-mouse` (https://github.com/zenobi-us/ink-mouse)
- * Copyright Zeno Jiricek, licensed under Apache-2.0
- */
-import type { PropsWithChildren } from "react";
-import React from "react";
-declare const Fullscreen: ({ children }: PropsWithChildren) => React.JSX.Element;
-export default Fullscreen;

package/dist/ink/mouse/MouseProvider.d.ts

@@ -1,11 +0,0 @@
-/**
- * Ported from `\@zenobius/ink-mouse` (https://github.com/zenobi-us/ink-mouse)
- * Copyright Zeno Jiricek, licensed under Apache-2.0
- *
- * Rewritten to integrate with the ink input pipeline instead of
- * listening on process.stdin directly.
- */
-import type { PropsWithChildren } from "react";
-import React from "react";
-declare const MouseProvider: ({ children }: PropsWithChildren) => React.JSX.Element;
-export default MouseProvider;