@visulima/tui 2.0.0 → 2.0.1

package/dist/packem_shared/render.d-DjQhFsiN.d.ts

@@ -0,0 +1,435 @@
+import { ReactNode } from 'react';
+import { D as DOMElement } from "./dom.d-CLGlidfI.js";
+import { T as TerminalSuspension } from "./app-context.d-DMLw5Nxy.js";
+import 'node:stream';
+import { CursorPosition } from "../ink/public/cursor.js";
+declare const kittyFlags: {
+  readonly disambiguateEscapeCodes: 1;
+  readonly reportAllKeysAsEscapeCodes: 8;
+  readonly reportAlternateKeys: 4;
+  readonly reportAssociatedText: 16;
+  readonly reportEventTypes: 2;
+};
+type KittyFlagName = keyof typeof kittyFlags;
+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;
+};
+type KittyKeyboardOptions = {
+  flags?: KittyFlagName[];
+  mode?: "auto" | "enabled" | "disabled";
+};
+/**
+ * Performance metrics for a render operation.
+ */
+type RenderMetrics = {
+  /**
+   * Time spent rendering in milliseconds.
+   */
+  renderTime: number;
+};
+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;
+  stderr: NodeJS.WriteStream;
+  stdin: NodeJS.ReadStream;
+  stdout: NodeJS.WriteStream;
+  /**
+   * Whether to track text selection state during rendering.
+   *
+   * @default false
+   */
+  trackSelection?: boolean;
+  /**
+   * 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>;
+};
+declare 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: DOMElement;
+  private fullStaticOutput;
+  private backbufferNode;
+  private backbufferMultiWarned;
+  private readonly exitPromise;
+  private exitResult;
+  private beforeExitHandler?;
+  private restoreConsole?;
+  private unsubscribeResize?;
+  private readonly throttledOnRender?;
+  private hasPendingThrottledRender;
+  private kittyProtocolEnabled;
+  private kittyFlags?;
+  private isSuspended;
+  private pauseInput?;
+  private resumeInput?;
+  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;
+  /**
+   * Walks 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;
+  handleStaticChange: () => void;
+  /**
+   * Compute the slice of lines that newly scrolled off the top of the single
+   * `overflowToBackbuffer` region and have not yet been flushed into the
+   * terminal's real scrollback. Advances the monotonic
+   * `internal_maxPushedScrollTop` bookkeeping so each line is emitted exactly
+   * once and scrolling back up is a no-op. Returns a newline-terminated
+   * string to write above the live frame, or "" when there is nothing to do.
+   *
+   * No-op outside inline mode (alternate-screen / non-TTY / non-interactive /
+   * screen-reader / debug), since terminal scrollback only exists for an
+   * inline, in-place-updated live region. Debug mode is excluded because it
+   * re-dumps the full grid every frame and never writes this slice — running
+   * it there would advance the monotonic pointer past lines that were never
+   * emitted.
+   */
+  private computeBackbufferOutput;
+  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;
+  registerInputControl: (pauseInput: () => void, resumeInput: () => void) => void;
+  /**
+   * Hand terminal control to a child process, then restore Ink's rendering.
+   * With a callback, the terminal is released for its duration and resumed in a
+   * `finally`. Without one, returns a handle whose `resume()` (or `await using`)
+   * restores.
+   */
+  suspendTerminal: {
+    (callback: () => Promise<void> | void): Promise<undefined>;
+    (): Promise<TerminalSuspension>;
+  };
+  private beginSuspend;
+  private endSuspend;
+  private enableKittyProtocol;
+}
+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 `&lt;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;
+};
+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 { Instance as I, KittyFlagName as K, RenderOptions as R, KittyKeyboardOptions as a, kittyModifiers as b, kittyFlags as k, render as r };

package/dist/packem_shared/{renderToString-DqLFFPvO.js → renderToString-B1LgWcJe.js}

@@ -1,4 +1,4 @@
-import{LegacyRoot as p}from"react-reconciler/constants.js";import N from"yoga-layout";import{c as g}from"./dom-rphpG0kf.js";import{j as l}from"./reconciler-DhUGYWCr.js";import{H as i}from"./renderer-Cs0KEr1o.js";import{calculateScroll as v}from"./calculateScroll-D4Y_JR4H.js";const L=(f,u)=>{const d=u?.columns??80,e=g("ink-root");let a="";e.onComputeLayout=()=>{e.yogaNode.setWidth(d),e.yogaNode.calculateLayout(void 0,void 0,N.DIRECTION_LTR);const o=t=>{if(t.nodeName==="ink-box"){const n=t.style.overflow??"visible",m=t.style.overflowX??n,y=t.style.overflowY??n;(m==="scroll"||y==="scroll")&&v(t)}for(const n of t.childNodes)n.nodeName!=="#text"&&o(n)};o(e)},e.onImmediateRender=()=>{const{staticOutput:o}=i(e,!1);o&&o!==`
+import{LegacyRoot as p}from"react-reconciler/constants.js";import N from"yoga-layout";import{c as g}from"./dom-rphpG0kf.js";import{j as l}from"./reconciler-DkwOtC5B.js";import{H as i}from"./renderer-Cs0KEr1o.js";import{calculateScroll as v}from"./calculateScroll-D4Y_JR4H.js";const L=(f,u)=>{const d=u?.columns??80,e=g("ink-root");let a="";e.onComputeLayout=()=>{e.yogaNode.setWidth(d),e.yogaNode.calculateLayout(void 0,void 0,N.DIRECTION_LTR);const o=t=>{if(t.nodeName==="ink-box"){const n=t.style.overflow??"visible",m=t.style.overflowX??n,y=t.style.overflowY??n;(m==="scroll"||y==="scroll")&&v(t)}for(const n of t.childNodes)n.nodeName!=="#text"&&o(n)};o(e)},e.onImmediateRender=()=>{const{staticOutput:o}=i(e,!1);o&&o!==`
 `&&(a+=o)};let r;const c=l.createContainer(e,p,null,!1,null,"render-to-string",o=>{r??=o},()=>{},()=>{},()=>{});let s=!1;try{l.updateContainerSync(f,c,null,()=>{}),l.flushSyncWork();const{output:o}=i(e,!1);if(l.updateContainerSync(null,c,null,()=>{}),l.flushSyncWork(),s=!0,e.yogaNode.free(),r!==void 0)throw r instanceof Error?r:new Error(String(r));const t=a.endsWith(`
 `)?a.slice(0,-1):a;return t&&o?`${t}
 ${o}`:t||o}finally{if(!s&&e.yogaNode)try{e.yogaNode.freeRecursive()}catch{}}};export{L as default};

package/dist/packem_shared/{selection.d-KWphH--_.d.ts → selection.d-BSAWa4ey.d.ts}

@@ -1,13 +1,13 @@
-import { b as DOMNode, e as StyledLine } from "./dom.d-g-nsYquD.js";
+import { b as DOMNode, e as StyledLine } from "./dom.d-CLGlidfI.js";
 /**
-* 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.
-*/
+ * 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.
+ */
 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.
-*/
+ * A Range represents a contiguous portion of the DOM tree.
+ * Modeled after the browser's Range API.
+ */
 declare class Range {
   startContainer: DOMNode | undefined;
   startOffset: number;
@@ -25,9 +25,9 @@ declare class Range {
   private updateCommonAncestor;
 }
 /**
-* Manages multiple Range objects and provides high-level selection operations.
-* Modeled after the browser's Selection API.
-*/
+ * Manages multiple Range objects and provides high-level selection operations.
+ * Modeled after the browser's Selection API.
+ */
 declare class Selection {
   anchorNode: DOMNode | undefined;
   anchorOffset: number;
@@ -49,12 +49,12 @@ declare class Selection {
   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.
-*/
+ * 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.
+ */
 declare const applySelectionToStyledLine: (line: StyledLine, range: {
   end: number;
   start: number;

package/dist/packem_shared/stderr-context-CR2LLec6.js

@@ -0,0 +1 @@
+import{createRequire as c}from"node:module";import{createContext as t}from"react";const e=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,r=e,s=t({stderr:r.stderr,write(){}});s.displayName="InternalStderrContext";export{s as t};

package/dist/packem_shared/stdin-context-BjMA9Sbi.js

@@ -0,0 +1 @@
+import{createRequire as s}from"node:module";import{createContext as l}from"react";let o;const i=t=>(o??=s(import.meta.url))(t),e=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,c=t=>{if(typeof e<"u"&&e.versions&&e.versions.node){const[n,r]=e.versions.node.split(".").map(Number);if(n>22||n===22&&r>=3||n===20&&r>=16)return e.getBuiltinModule(t)}return i(t)},{EventEmitter:a}=c("node:events"),d=e,u=l({internal_eventEmitter:new a,internal_exitOnCtrlC:!0,isRawModeSupported:!1,setBracketedPasteMode(){},setRawMode(){},stdin:d.stdin});u.displayName="InternalStdinContext";export{u as e};

package/dist/packem_shared/stdout-context-DAAlQct2.js

@@ -0,0 +1 @@
+import{createRequire as c}from"node:module";import{createContext as o}from"react";const e=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,t=e,r=o({stdout:t.stdout,write(){}});r.displayName="InternalStdoutContext";export{r as t};