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

package/dist/ink/render.d.ts

@@ -1,191 +0,0 @@
-import type { ReactNode } from "react";
-import type { DOMElement } from "./dom.d.ts";
-import type { RenderMetrics } from "./ink/ink.d.ts";
-import Ink from "./ink/ink.d.ts";
-import type { KittyKeyboardOptions } from "./kitty-keyboard.d.ts";
-export type RenderOptions = {
-    /**
-     * 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
-     */
-    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
-     */
-    concurrent?: boolean;
-    /**
-     * If true, each update will be rendered as separate output, without replacing the previous one.
-     * @default false
-     */
-    debug?: boolean;
-    /**
-     * Configure whether Ink should listen for Ctrl+C keyboard input and exit the app. This is needed in case `process.stdin` is in raw mode, because then Ctrl+C is ignored by default and the process is expected to handle it manually.
-     * @default true
-     */
-    exitOnCtrlC?: boolean;
-    /**
-     * Enable incremental rendering mode which only updates changed lines instead of redrawing the entire output.
-     *This can reduce flickering and improve performance for frequently updating UIs.
-     * @default false
-     */
-    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)
-     */
-    interactive?: boolean;
-    /**
-     * Enable screen reader support. See https://github.com/vadimdemedes/ink/blob/master/readme.md#screen-reader-support
-     * @default process.env['INK_SCREEN_READER'] === 'true'
-     */
-    isScreenReaderEnabled?: boolean;
-    /**
-     * Configure kitty keyboard protocol support for enhanced keyboard input.
-     * Enables additional modifiers (super, hyper, capsLock, numLock) and
-     *disambiguated key events in terminals that support the protocol.
-     * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
-     */
-    kittyKeyboard?: KittyKeyboardOptions;
-    /**
-     * Maximum frames per second for render updates.
-     * This controls how frequently the UI can update to prevent excessive re-rendering.
-     *Higher values allow more frequent updates but may impact performance.
-     * @default 30
-     */
-    maxFps?: number;
-    /**
-     * Runs the given callback after each render and re-render with render metrics.
-     *
-     * Note: this callback runs after Ink commits a frame, but it does not wait for `stdout`/`stderr` stream callbacks.
-     * To run code after output is flushed, use `waitUntilRenderFlush()`.
-     */
-    onRender?: (metrics: RenderMetrics) => void;
-    /**
-     * Patch console methods to ensure console output doesn't mix with Ink's output.
-     *
-     *Note: Once unmount starts, Ink restores the native console before React cleanup runs. Teardown-time `console.*` output then follows the normal console behavior instead of being rerouted through Ink.
-     * @default true
-     */
-    patchConsole?: boolean;
-    /**
-     * If true, Ink defers frame output until after React's commit phase completes,
-     * ensuring `useLayoutEffect` hooks run before the frame is written to the terminal.
-     *
-     * This eliminates the one-frame flicker when components measure layout
-     * (e.g., scroll position, element size) in `useLayoutEffect` and adjust state.
-     *
-     * **Warning:** Incompatible with the `<Static>` component, which relies on
-     * immediate render timing to append output.
-     * @default false
-     */
-    standardReactLayoutTiming?: boolean;
-    /**
-     * Error stream.
-     * @default process.stderr
-     */
-    stderr?: NodeJS.WriteStream;
-    /**
-     * Input stream where app will listen for input.
-     * @default process.stdin
-     */
-    stdin?: NodeJS.ReadStream;
-    /**
-     * Output stream where the app will be rendered.
-     * @default process.stdout
-     */
-    stdout?: NodeJS.WriteStream;
-    /**
-     * Use the native Rust cell-diff renderer for terminal output.
-     * Produces a Uint32Array buffer that the Rust renderer diffs cell-by-cell,
-     * generating minimal ANSI escape sequences. Reduces GC pressure and
-     * improves rendering performance for complex UIs.
-     *
-     * Falls back to string-based rendering if native bindings are not available.
-     * @default false
-     */
-    useNativeRenderer?: boolean;
-};
-export type Instance = {
-    /**
-     * Unmount the current app and remove the internal Ink instance for this stdout.
-     *
-     * This is mostly useful for advanced cases where you need `render()` to create a fresh instance for the same stream without leaving terminal state such as the alternate screen behind.
-     */
-    cleanup: () => void;
-    /**
-     * Clear output.
-     */
-    clear: () => void;
-    /**
-     * Replace the previous root node with a new one or update props of the current root node.
-     */
-    rerender: Ink["render"];
-    /**
-     * The root DOM element of the rendered tree.
-     * Useful for programmatic DOM inspection and advanced measurement.
-     */
-    rootNode: DOMElement;
-    /**
-     * Manually unmount the whole Ink app.
-     */
-    unmount: Ink["unmount"];
-    /**
-     * Returns a promise that settles when the app is unmounted.
-     *
-     * It resolves with the value passed to `exit(value)` and rejects with the error passed to `exit(error)`.
-     *When `unmount()` is called manually, it settles after unmount-related stdout writes complete.
-     * @example
-     * ```jsx
-     * const {unmount, waitUntilExit} = render(<MyApp />);
-     *
-     * setTimeout(unmount, 1000);
-     *
-     * await waitUntilExit(); // resolves after `unmount()` is called
-     * ```
-     */
-    waitUntilExit: Ink["waitUntilExit"];
-    /**
-     * Returns a promise that settles after pending render output is flushed to stdout.
-     *
-     *This can be used after `rerender()` when you need to run code only after the frame is written.
-     * @example
-     * ```jsx
-     * const {rerender, waitUntilRenderFlush} = render(<MyApp step="loading" />);
-     *
-     * rerender(<MyApp step="ready" />);
-     * await waitUntilRenderFlush(); // output for "ready" is flushed
-     *
-     * runNextCommand();
-     * ```
-     */
-    waitUntilRenderFlush: Ink["waitUntilRenderFlush"];
-};
-/**
- * Mount a component and render the output.
- */
-declare const render: (node: ReactNode, options?: NodeJS.WriteStream | RenderOptions) => Instance;
-export default render;

package/dist/ink/renderer.d.ts

@@ -1,17 +0,0 @@
-import type { DOMElement } from "./dom.d.ts";
-import type { CursorPosition } from "./log-update.d.ts";
-import type { Selection } from "./selection.d.ts";
-type Result = {
-    cursorPosition: CursorPosition | undefined;
-    cursorRequested: boolean;
-    output: string;
-    outputBuffer?: Uint32Array;
-    outputHeight: number;
-    outputWidth?: number;
-    staticOutput: string;
-};
-declare const renderer: (node: DOMElement, isScreenReaderEnabled: boolean, options?: {
-    selection?: Selection;
-    useNativeRenderer?: boolean;
-}) => Result;
-export default renderer;

package/dist/ink/resize-observer.d.ts

@@ -1,44 +0,0 @@
-/**
- * ResizeObserver API for terminal UI elements.
- *
- * Mirrors the browser ResizeObserver API, allowing components to react
- * to size changes of DOM elements after layout computation.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-import type { DOMElement } from "./dom.d.ts";
-export type ResizeObserverCallback = (entries: ResizeObserverEntry[], observer: ResizeObserver) => void;
-export declare class ResizeObserverEntry {
-    readonly target: DOMElement;
-    readonly contentRect: Readonly<{
-        height: number;
-        width: number;
-    }>;
-    constructor(target: DOMElement, contentRect: Readonly<{
-        height: number;
-        width: number;
-    }>);
-}
-declare class ResizeObserver {
-    private readonly callback;
-    private readonly observedElements;
-    constructor(callback: ResizeObserverCallback);
-    observe(element: DOMElement): void;
-    unobserve(element: DOMElement): void;
-    disconnect(): void;
-    /**
-     * Internal method called by the layout engine after computing layout.
-     */
-    internalTrigger(entries: ResizeObserverEntry[]): void;
-}
-/**
- * Measure a node and collect resize observer entries for it.
- * Used by both the main render loop and static render processing.
- */
-export declare function measureAndExtractObservers(node: DOMElement, observerEntries: Map<ResizeObserver, ResizeObserverEntry[]>, forceCache?: boolean): void;
-/**
- * Traverse a node tree, measure all nodes, and trigger resize observers.
- * Skips into static/cached subtrees to avoid double-counting.
- */
-export declare function triggerResizeObservers(node: DOMElement, forceCache?: boolean): void;
-export default ResizeObserver;

package/dist/ink/sanitize-ansi.d.ts

@@ -1,2 +0,0 @@
-declare const sanitizeAnsi: (text: string) => string;
-export default sanitizeAnsi;

package/dist/ink/scroll.d.ts

@@ -1,23 +0,0 @@
-import type { DOMElement } from "./dom.d.ts";
-export type ScrollState = {
-    actualScrollHeight: number;
-    clientHeight: number;
-    clientWidth: number;
-    scrollHeight: number;
-    scrollLeft: number;
-    scrollTop: number;
-    scrollWidth: number;
-};
-export declare const getScrollHeight: (node: DOMElement) => number;
-export declare const getScrollWidth: (node: DOMElement) => number;
-export declare const calculateScroll: (node: DOMElement) => void;
-/**
- * Get the effective scroll top position from the pre-computed scroll state.
- * Falls back to computing from style if scroll state hasn't been calculated yet.
- */
-export declare const getScrollTop: (node: DOMElement) => number;
-/**
- * Get the effective scroll left position from the pre-computed scroll state.
- * Falls back to computing from style if scroll state hasn't been calculated yet.
- */
-export declare const getScrollLeft: (node: DOMElement) => number;

package/dist/ink/selection.d.ts

@@ -1,70 +0,0 @@
-/**
- * DOM-like Selection and Range API for terminal text selection.
- *
- * Provides browser-like Selection/Range classes that operate on the Ink DOM tree,
- * enabling text selection highlighting and copy-to-clipboard functionality.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-import type { DOMNode } from "./dom.d.ts";
-import type { StyledLine } from "./styled-line.d.ts";
-/**
- * Compare the document position of two points in the DOM tree.
- * Returns -1 if A is before B, 0 if equal, 1 if A is after B.
- */
-export declare const comparePoints: (nodeA: DOMNode, offsetA: number, nodeB: DOMNode, offsetB: number) => number;
-/**
- * A Range represents a contiguous portion of the DOM tree.
- * Modeled after the browser's Range API.
- */
-export declare class Range {
-    startContainer: DOMNode | undefined;
-    startOffset: number;
-    endContainer: DOMNode | undefined;
-    endOffset: number;
-    collapsed: boolean;
-    commonAncestorContainer: DOMNode | undefined;
-    setStart(node: DOMNode, offset: number): void;
-    setEnd(node: DOMNode, offset: number): void;
-    collapse(toStart: boolean): void;
-    selectNode(node: DOMNode): void;
-    selectNodeContents(node: DOMNode): void;
-    toString(): string;
-    private updateCollapsed;
-    private updateCommonAncestor;
-}
-/**
- * Manages multiple Range objects and provides high-level selection operations.
- * Modeled after the browser's Selection API.
- */
-export declare class Selection {
-    anchorNode: DOMNode | undefined;
-    anchorOffset: number;
-    focusNode: DOMNode | undefined;
-    focusOffset: number;
-    isCollapsed: boolean;
-    rangeCount: number;
-    private ranges;
-    private readonly listeners;
-    onChange(listener: () => void): () => void;
-    toString(): string;
-    getRangeAt(index: number): Range;
-    addRange(range: Range): void;
-    removeRange(range: Range): void;
-    removeAllRanges(): void;
-    collapse(node: DOMNode, offset: number): void;
-    containsNode(node: DOMNode, allowPartialContainment?: boolean): boolean;
-    private clearState;
-    private notifyChange;
-}
-/**
- * Apply selection highlighting to a range of characters in a StyledLine.
- *
- * Characters whose index falls within [start, end) of the selection range
- * get the INVERSE style flag applied. Returns a new StyledLine with the
- * selection highlighting — the original is not mutated.
- */
-export declare const applySelectionToStyledLine: (line: StyledLine, range: {
-    end: number;
-    start: number;
-}) => StyledLine;

package/dist/ink/squash-text-nodes.d.ts

@@ -1,18 +0,0 @@
-import type { DOMElement, DOMNode } from "./dom.d.ts";
-export type CharOffsetRange = {
-    end: number;
-    start: number;
-};
-export type CharOffsetMap = Map<DOMNode, CharOffsetRange>;
-declare const squashTextNodes: (node: DOMElement) => string;
-export default squashTextNodes;
-/**
- * Squash text nodes while building a character offset map.
- * Each DOM node is mapped to its start/end character offsets in the resulting string.
- * Used for selection text extraction and cursor position calculation.
- *
- * Ported from jacob314/ink fork (Google LLC, Apache-2.0).
- */
-export declare const squashTextNodesWithMap: (node: DOMElement, map: CharOffsetMap, offsetRef: {
-    current: number;
-}) => string;

package/dist/ink/style-flags.d.ts

@@ -1,17 +0,0 @@
-/**
- * Bitmask constants for text formatting flags used by StyledLine.
- *
- * These map 1:1 to SGR (Select Graphic Rendition) attributes and are stored
- * in the `formatFlags` field of StyleSpan objects. The FULL_WIDTH_MASK is
- * also used in StyledLine.charData entries (bit 30 / 0x40000000 of number[]).
- *
- * Ported from jacob314/ink (Google LLC, Apache-2.0).
- */
-export declare const BOLD_MASK: number;
-export declare const DIM_MASK: number;
-export declare const ITALIC_MASK: number;
-export declare const UNDERLINE_MASK: number;
-export declare const STRIKETHROUGH_MASK: number;
-export declare const INVERSE_MASK: number;
-export declare const HIDDEN_MASK: number;
-export declare const FULL_WIDTH_MASK: number;

package/dist/ink/styled-line-factory.d.ts

@@ -1,25 +0,0 @@
-/**
- * Direct text → StyledLine pipeline.
- *
- * Converts ANSI-styled text to StyledLine without the intermediate StyledChar
- * representation, eliminating the `@alcalzone/ansi-tokenize` dependency.
- *
- * The pipeline:
- * 1. tokenizeAnsi() — splits text into ANSI tokens and plain text
- * 2. SGR state machine — tracks active formatting from CSI SGR sequences
- * 3. Grapheme segmenter — handles combining chars, emoji, regional indicators
- * 4. StyledLine.pushChar() — appends each grapheme with its resolved style
- */
-import { StyledLine } from "./styled-line.d.ts";
-/**
- * Convert an ANSI-styled text string directly to a StyledLine.
- *
- * This is the zero-dependency replacement for the chain:
- * tokenize() → styledCharsFromTokens() → styledCharsToStyledLine().
- */
-export declare const textToStyledLine: (text: string) => StyledLine;
-/**
- * Build a StyledLine from plain text (no ANSI codes).
- * Uses a fast ASCII path when possible.
- */
-export declare const plainTextToStyledLine: (text: string) => StyledLine;

package/dist/ink/styled-line-serializer.d.ts

@@ -1,18 +0,0 @@
-/**
- * Serializes a StyledLine to an ANSI-escaped terminal string.
- *
- * Emits only diff-based escape codes — a style code is written only when
- * the formatting changes between adjacent characters. Resets all active
- * styles at the end of the string.
- *
- * Ported from jacob314/ink (Google LLC, Apache-2.0).
- * @license Apache-2.0
- */
-import type { StyledLine } from "./styled-line.d.ts";
-/**
- * Convert a StyledLine to an ANSI-escaped string.
- *
- * Only emits escape codes when the style changes between characters.
- * This produces minimal ANSI output.
- */
-export declare const styledLineToString: (line: StyledLine) => string;

package/dist/ink/styled-line.d.ts

@@ -1,109 +0,0 @@
-/**
- * Columnar data structure for a single line of styled terminal text.
- *
- * Instead of one heap-allocated object per visible character, StyledLine stores:
- *
- * - `text: string` — concatenated raw character values
- * - `charData: number[]` — per-character: 30-bit offset into text | 1-bit full-width flag
- * - `spans: StyleSpan[]` — run-length encoded style information
- *
- * For an 80-column line this reduces allocations from ~80 objects to
- * 1 string + 1 array + typically 1-5 span objects.
- *
- * Ported from jacob314/ink (Google LLC, Apache-2.0).
- * @license Apache-2.0
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-export type StyleSpan = {
-    bgColor?: string;
-    fgColor?: string;
-    formatFlags: number;
-    length: number;
-    link?: string;
-};
-export declare class StyledLine {
-    [Symbol.iterator]: () => Iterator<{
-        bgColor?: string;
-        fgColor?: string;
-        formatFlags: number;
-        fullWidth: boolean;
-        hasStyles: boolean;
-        link?: string;
-        value: string;
-    }>;
-    length: number;
-    private static readonly emptyCache;
-    private text;
-    private charData;
-    private spans;
-    private _cachedTrimmedLength?;
-    static empty(length: number): StyledLine;
-    getValue(index: number): string;
-    /**
-     * Get the raw text for a range of characters as a single string slice.
-     * Much faster than calling getValue() per character.
-     */
-    getTextRange(start: number, end: number): string;
-    getSpan(index: number): StyleSpan | undefined;
-    getFullWidth(index: number): boolean;
-    hasStyles(index: number): boolean;
-    getFormatFlags(index: number): number;
-    getFgColor(index: number): string | undefined;
-    getBgColor(index: number): string | undefined;
-    getLink(index: number): string | undefined;
-    setInverted(index: number, inverted: boolean): void;
-    setBackgroundColor(index: number, color: string | undefined): void;
-    setForegroundColor(index: number, color: string | undefined): void;
-    setChar(index: number, value: string, formatFlags: number, fgColor?: string, bgColor?: string, link?: string): void;
-    /**
-     * Optimized setChar for same-length single-byte replacement.
-     * Skips string rebuild and offset adjustment when old and new values
-     * have the same byte length (the common case for ASCII overwrites on empty lines).
-     */
-    setCharFast(index: number, value: string, formatFlags: number, fgColor?: string, bgColor?: string, link?: string): void;
-    /**
-     * Overwrite a range of this line with content from a source StyledLine.
-     * More efficient than calling setChar() per character because it does
-     * a single span split + rebuild instead of per-character span manipulation.
-     * @param destinationStart — start index in this line
-     * @param source — the StyledLine to copy from
-     * @param srcStart — start index in source (default 0)
-     * @param count — number of characters to copy (default: source.length)
-     */
-    writeFrom(destinationStart: number, source: StyledLine, srcStart?: number, count?: number): void;
-    pushChar(value: string, formatFlags: number, fgColor?: string, bgColor?: string, link?: string): void;
-    clone(): StyledLine;
-    slice(start: number, end?: number): StyledLine;
-    combine(...others: StyledLine[]): StyledLine;
-    getTrimmedLength(): number;
-    trimEnd(): StyledLine;
-    equals(other: StyledLine): boolean;
-    getText(): string;
-    getSpans(): StyleSpan[];
-    getValues(): string[];
-    [Symbol.iterator](): Iterator<{
-        bgColor?: string;
-        fgColor?: string;
-        formatFlags: number;
-        fullWidth: boolean;
-        hasStyles: boolean;
-        link?: string;
-        value: string;
-    }>;
-    /**
-     * Split the span at `index` into a single-char span, apply the updater,
-     * then merge adjacent spans. Shared by setInverted/setBackgroundColor/setForegroundColor.
-     */
-    private updateSpanAt;
-    /**
-     * Grow the line to at least `minWidth` columns, filling new cells with
-     * empty strings (zero-width placeholders). This matches the behavior of
-     * sparse JS arrays in the original ink Output where out-of-bounds writes
-     * created gaps that produced no visible output.
-     */
-    ensureWidth(minWidth: number): void;
-    private ensureInitialized;
-    private splitSpansAt;
-    private mergeSpans;
-}