@sayknow-cli/tui 0.3.5 → 0.3.6

package/dist/types/kill-ring.d.ts

@@ -1,27 +0,0 @@
-/**
- * Ring buffer for Emacs-style kill/yank operations.
- *
- * Tracks killed (deleted) text entries. Consecutive kills can accumulate
- * into a single entry. Supports yank (paste most recent) and yank-pop
- * (cycle through older entries).
- */
-export declare class KillRing {
-    #private;
-    /**
-     * Add text to the kill ring.
-     *
-     * @param text - The killed text to add
-     * @param opts - Push options
-     * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
-     * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
-     */
-    push(text: string, opts: {
-        prepend: boolean;
-        accumulate?: boolean;
-    }): void;
-    /** Get most recent entry without modifying the ring. */
-    peek(): string | undefined;
-    /** Move last entry to front (for yank-pop cycling). */
-    rotate(): void;
-    get length(): number;
-}

package/dist/types/metrics.d.ts

@@ -1,85 +0,0 @@
-/** Number of consecutive unexpected full redraws that constitute a "storm". */
-export declare const REPAINT_STORM_THRESHOLD = 3;
-/** Hard cap on retained metric label keys; overflow is aggregated under `other`. */
-export declare const MAX_LABEL_MAP_ENTRIES = 128;
-export interface DurationStats {
-    count: number;
-    meanMs: number;
-    p50Ms: number;
-    p95Ms: number;
-    p99Ms: number;
-    maxMs: number;
-}
-export interface RssStats {
-    samples: number;
-    baselineBytes: number | null;
-    lastBytes: number | null;
-    peakBytes: number;
-    growthBytes: number;
-    /** RSS sampled after the run + a forced GC (informational). */
-    returnBytes: number | null;
-    /** Heap used at baseline and after the run + forced GC (reclaimable signal). */
-    heapBaselineBytes: number | null;
-    heapReturnBytes: number | null;
-    /** (heapReturn - heapBaseline) / heapBaseline; <= tolerance means heap returned. */
-    returnWithinBaselineFraction: number | null;
-}
-export interface HelperStat {
-    count: number;
-    totalMs: number;
-    meanMs: number;
-}
-export interface LineCountGauge {
-    last: number;
-    max: number;
-}
-export interface RenderMetricsSnapshot {
-    enabled: boolean;
-    renderCount: number;
-    renderDurations: DurationStats;
-    durationsTruncated: boolean;
-    requestSources: Record<string, number>;
-    fullRedrawCount: number;
-    fullRedrawCauses: Record<string, number>;
-    repaintStorms: number;
-    maxConsecutiveFullRedraws: number;
-    rss: RssStats;
-    ownerGauges: Record<string, number>;
-    timerGauges: Record<string, number>;
-    helperStats: Record<string, HelperStat>;
-    lineCounts: Record<string, LineCountGauge>;
-}
-export declare class RenderMetrics {
-    #private;
-    constructor(enabled?: boolean);
-    get enabled(): boolean;
-    enable(): void;
-    disable(): void;
-    /** Reset all collected data (keeps the enabled state). */
-    reset(): void;
-    /** High-resolution clock for timing render passes. Returns 0 when disabled. */
-    now(): number;
-    /** Record that a render was requested, attributed to a caller source. */
-    recordRequest(source?: string): void;
-    /** Record one completed `#doRender` pass duration (ms). */
-    recordRender(durationMs: number): void;
-    /** Record a full-redraw event and classify its cause for storm detection. */
-    recordFullRedraw(cause: string): void;
-    /** Sample current RSS. Records baseline on first sample, tracks peak/last. */
-    sampleRss(): number;
-    setOwnerGauge(name: string, value: number): void;
-    setTimerGauge(name: string, value: number): void;
-    /** Accumulate timing/count for a named render helper (e.g. "renderTree"). */
-    recordHelper(name: string, durationMs: number): void;
-    /** Record a per-render line-count gauge (e.g. "rendered", "normalized", "diffed"). */
-    recordLineCount(name: string, value: number): void;
-    /**
-     * Force a GC when the runtime exposes one and sample RSS as the post-run
-     * "return" value used by the memory-leak gate. Callers should drop large
-     * references before calling so reclaimable memory is actually freed.
-     */
-    sampleReturn(): number;
-    snapshot(): RenderMetricsSnapshot;
-}
-/** Shared metrics instance used by the TUI render loop. */
-export declare const renderMetrics: RenderMetrics;

package/dist/types/stdin-buffer.d.ts

@@ -1,50 +0,0 @@
-/**
- * StdinBuffer buffers input and emits complete sequences.
- *
- * This is necessary because stdin data events can arrive in partial chunks,
- * especially for escape sequences like mouse events. Without buffering,
- * partial sequences can be misinterpreted as regular keypresses.
- *
- * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
- * - Event 1: `\x1b`
- * - Event 2: `[<35`
- * - Event 3: `;20;5m`
- *
- * The buffer accumulates these until a complete sequence is detected.
- * Call the `process()` method to feed input data.
- *
- * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
- * MIT License - Copyright (c) 2025 opentui
- */
-import { EventEmitter } from "events";
-export type StdinBufferOptions = {
-    /**
-     * Maximum time to wait for sequence completion (default: 10ms)
-     * After this time, the buffer is flushed even if incomplete
-     */
-    timeout?: number;
-};
-export type StdinBufferEventMap = {
-    data: [string];
-    paste: [string];
-};
-/**
- * Buffers stdin input and emits complete sequences via the 'data' event.
- * Handles partial escape sequences that arrive across multiple chunks.
- *
- * StdinBuffer is the single raw-stdin decoding boundary: raw terminal bytes
- * enter via `process()` and decoded string events leave via the 'data' and
- * 'paste' events. UTF-8 is decoded exactly once here (using a persistent
- * StringDecoder) so multi-byte characters split across chunk boundaries are
- * reassembled rather than corrupted into U+FFFD. All downstream parsing
- * (escape sequences, bracketed paste, Kitty/CSI, OSC/DA1) operates on strings.
- */
-export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
-    #private;
-    constructor(options?: StdinBufferOptions);
-    process(data: string | Buffer): void;
-    flush(): string[];
-    clear(): void;
-    getBuffer(): string;
-    destroy(): void;
-}

package/dist/types/symbols.d.ts

@@ -1,23 +0,0 @@
-export interface BoxSymbols {
-    topLeft: string;
-    topRight: string;
-    bottomLeft: string;
-    bottomRight: string;
-    horizontal: string;
-    vertical: string;
-    teeDown: string;
-    teeUp: string;
-    teeLeft: string;
-    teeRight: string;
-    cross: string;
-}
-export interface SymbolTheme {
-    cursor: string;
-    inputCursor: string;
-    boxRound: Omit<BoxSymbols, "teeDown" | "teeUp" | "teeLeft" | "teeRight" | "cross">;
-    boxSharp: BoxSymbols;
-    table: BoxSymbols;
-    quoteBorder: string;
-    hrChar: string;
-    spinnerFrames: string[];
-}

package/dist/types/terminal-capabilities.d.ts

@@ -1,75 +0,0 @@
-export declare enum ImageProtocol {
-    Kitty = "\u001B_G",
-    Iterm2 = "\u001B]1337;File=",
-    Sixel = "\u001BPq"
-}
-export declare enum NotifyProtocol {
-    Bell = "\u0007",
-    Osc99 = "\u001B]99;;",
-    Osc9 = "\u001B]9;"
-}
-export type TerminalId = "kitty" | "ghostty" | "wezterm" | "iterm2" | "vscode" | "alacritty" | "base" | "trueColor";
-/** Terminal capability details used for rendering and protocol selection. */
-export declare class TerminalInfo {
-    readonly id: TerminalId;
-    readonly imageProtocol: ImageProtocol | null;
-    readonly trueColor: boolean;
-    readonly hyperlinks: boolean;
-    readonly notifyProtocol: NotifyProtocol;
-    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol);
-    isImageLine(line: string): boolean;
-    formatNotification(message: string): string;
-    sendNotification(message: string): void;
-}
-export declare function isNotificationSuppressed(): boolean;
-/**
- * Returns true when running in Windows Terminal with known SIXEL support.
- *
- * Windows Terminal introduced SIXEL support in preview 1.22.
- */
-export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
-export declare const TERMINAL_ID: TerminalId;
-export declare const TERMINAL: TerminalInfo;
-/**
- * Override terminal image protocol at runtime after capability probes complete.
- */
-export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void;
-export declare function getTerminalInfo(terminalId: TerminalId): TerminalInfo;
-export interface CellDimensions {
-    widthPx: number;
-    heightPx: number;
-}
-export interface ImageDimensions {
-    widthPx: number;
-    heightPx: number;
-}
-export interface ImageRenderOptions {
-    maxWidthCells?: number;
-    maxHeightCells?: number;
-    preserveAspectRatio?: boolean;
-}
-export declare function getCellDimensions(): CellDimensions;
-export declare function setCellDimensions(dims: CellDimensions): void;
-export declare function encodeKitty(base64Data: string, options?: {
-    columns?: number;
-    rows?: number;
-    imageId?: number;
-}): string;
-export declare function encodeITerm2(base64Data: string, options?: {
-    width?: number | string;
-    height?: number | string;
-    name?: string;
-    preserveAspectRatio?: boolean;
-    inline?: boolean;
-}): string;
-export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
-export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
-export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
-export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
-export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
-export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
-export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
-    sequence: string;
-    rows: number;
-} | null;
-export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;

package/dist/types/terminal.d.ts

@@ -1,80 +0,0 @@
-/**
- * Whether SKC may reprogram the keyboard with enhanced input protocols
- * (the Kitty keyboard protocol and the xterm modifyOtherKeys fallback).
- *
- * Enabled by default. Set `SKC_TUI_KEYBOARD_PROTOCOL=0` to leave the keyboard in
- * its default mode. Some terminals — notably Android Termius — break IME
- * composition (e.g. Korean/Hangul syllable composition) while these enhanced
- * modes are active, committing every intermediate composing jamo/syllable
- * instead of only the final character. Disabling the protocol restores normal
- * IME behavior, matching how other TUIs that leave the keyboard untouched render
- * Korean correctly.
- */
-export declare function keyboardEnhancementEnabled(): boolean;
-/** Error codes for terminal/pipe write failures that should never crash the process. */
-export declare function isBenignTerminalWriteError(err: unknown): boolean;
-/**
- * Emergency terminal restore - call this from signal/crash handlers
- * Resets terminal state without requiring access to the ProcessTerminal instance
- */
-export declare function emergencyTerminalRestore(): void;
-/** Terminal-reported appearance (dark/light mode). */
-export type TerminalAppearance = "dark" | "light";
-export interface Terminal {
-    start(onInput: (data: string) => void, onResize: () => void): void;
-    stop(): void;
-    /**
-     * Drain stdin before exiting to prevent Kitty key release events from
-     * leaking to the parent shell over slow SSH connections.
-     * @param maxMs - Maximum time to drain (default: 1000ms)
-     * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
-     */
-    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
-    write(data: string): void;
-    get available(): boolean;
-    get columns(): number;
-    get rows(): number;
-    get kittyProtocolActive(): boolean;
-    moveBy(lines: number): void;
-    hideCursor(): void;
-    showCursor(): void;
-    clearLine(): void;
-    clearFromCursor(): void;
-    clearScreen(): void;
-    setTitle(title: string): void;
-    setProgress(active: boolean): void;
-    /**
-     * Register a callback for terminal appearance (dark/light) changes.
-     * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
-     * Fires when the detected appearance changes, including the initial detection.
-     */
-    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
-    /** The last detected terminal appearance, or undefined if not yet known. */
-    get appearance(): TerminalAppearance | undefined;
-}
-/**
- * Real terminal using process.stdin/stdout
- */
-export declare class ProcessTerminal implements Terminal {
-    #private;
-    get kittyProtocolActive(): boolean;
-    get appearance(): TerminalAppearance | undefined;
-    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
-    start(onInput: (data: string) => void, onResize: () => void): void;
-    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
-    stop(): void;
-    write(data: string): void;
-    /** Invoked by the durable module-level stdout write guard (see installStdoutWriteGuard). */
-    markStdoutUnavailable(err: unknown): void;
-    get available(): boolean;
-    get columns(): number;
-    get rows(): number;
-    moveBy(lines: number): void;
-    hideCursor(): void;
-    showCursor(): void;
-    clearLine(): void;
-    clearFromCursor(): void;
-    clearScreen(): void;
-    setTitle(title: string): void;
-    setProgress(active: boolean): void;
-}

package/dist/types/ttyid.d.ts

@@ -1,9 +0,0 @@
-/** Resolve the TTY device path for stdin (fd 0) via POSIX `ttyname(3)`. */
-export declare function getTtyPath(): string | null;
-/**
- * Get a stable identifier for the current terminal.
- * Uses the TTY device path (e.g., /dev/pts/3), falling back to environment
- * variables for terminal multiplexers or terminal emulators.
- * Returns null if no terminal can be identified (e.g., piped input).
- */
-export declare function getTerminalId(): string | null;

package/dist/types/tui.d.ts

@@ -1,182 +0,0 @@
-import type { Terminal } from "./terminal";
-import { visibleWidth } from "./utils";
-type InputListenerResult = {
-    consume?: boolean;
-    data?: string;
-} | undefined;
-type InputListener = (data: string) => InputListenerResult;
-/**
- * Component interface - all components must implement this
- */
-export interface Component {
-    /**
-     * Render the component to lines for the given viewport width
-     * @param width - Current viewport width
-     * @returns Array of strings, each representing a line
-     */
-    render(width: number): string[];
-    /**
-     * Optional handler for keyboard input when component has focus
-     */
-    handleInput?(data: string): void;
-    /**
-     * If true, component receives key release events (Kitty protocol).
-     * Default is false - release events are filtered out.
-     */
-    wantsKeyRelease?: boolean;
-    /**
-     * Invalidate any cached rendering state.
-     * Called when theme changes or when component needs to re-render from scratch.
-     */
-    invalidate(): void;
-    /**
-     * Optional cleanup hook. Called once when the component is permanently
-     * removed from the tree via removeChild/clear/dispose. Implementations MUST
-     * be idempotent. Components meant to be re-added should be detached, not
-     * removed/cleared.
-     */
-    dispose?(): void;
-}
-/**
- * Interface for components that can receive focus and display a hardware cursor.
- * When focused, the component should emit CURSOR_MARKER at the cursor position
- * in its render output. TUI will find this marker and position the hardware
- * cursor there for proper IME candidate window positioning.
- */
-export interface Focusable {
-    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
-    focused: boolean;
-}
-/** Type guard to check if a component implements Focusable */
-export declare function isFocusable(component: Component | null): component is Component & Focusable;
-/**
- * Cursor position marker - APC (Application Program Command) sequence.
- * This is a zero-width escape sequence that terminals ignore.
- * Components emit this at the cursor position when focused.
- * TUI finds and strips this marker, then positions the hardware cursor there.
- */
-export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
-export { visibleWidth };
-/**
- * Anchor position for overlays
- */
-export type OverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
-/**
- * Margin configuration for overlays
- */
-export interface OverlayMargin {
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
-}
-/** Value that can be absolute (number) or percentage (string like "50%") */
-export type SizeValue = number | `${number}%`;
-/**
- * Options for overlay positioning and sizing.
- * Values can be absolute numbers or percentage strings (e.g., "50%").
- */
-export interface OverlayOptions {
-    /** Width in columns, or percentage of terminal width (e.g., "50%") */
-    width?: SizeValue;
-    /** Minimum width in columns */
-    minWidth?: number;
-    /** Maximum height in rows, or percentage of terminal height (e.g., "50%") */
-    maxHeight?: SizeValue;
-    /** Anchor point for positioning (default: 'center') */
-    anchor?: OverlayAnchor;
-    /** Horizontal offset from anchor position (positive = right) */
-    offsetX?: number;
-    /** Vertical offset from anchor position (positive = down) */
-    offsetY?: number;
-    /** Row position: absolute number, or percentage (e.g., "25%" = 25% from top) */
-    row?: SizeValue;
-    /** Column position: absolute number, or percentage (e.g., "50%" = centered horizontally) */
-    col?: SizeValue;
-    /** Margin from terminal edges. Number applies to all sides. */
-    margin?: OverlayMargin | number;
-    /**
-     * Control overlay visibility based on terminal dimensions.
-     * If provided, overlay is only rendered when this returns true.
-     * Called each render cycle with current terminal dimensions.
-     */
-    visible?: (termWidth: number, termHeight: number) => boolean;
-}
-/**
- * Handle returned by showOverlay for controlling the overlay
- */
-export interface OverlayHandle {
-    /** Permanently remove the overlay (cannot be shown again) */
-    hide(): void;
-    /** Temporarily hide or show the overlay */
-    setHidden(hidden: boolean): void;
-    /** Check if overlay is temporarily hidden */
-    isHidden(): boolean;
-}
-/**
- * Container - a component that contains other components
- */
-export declare class Container implements Component {
-    #private;
-    children: Component[];
-    addChild(component: Component): void;
-    removeChild(component: Component): void;
-    /** Remove a child without disposing it (for detach-then-readd reuse). */
-    detachChild(component: Component): void;
-    clear(): void;
-    /** Remove all children without disposing them (for detach-then-readd reuse). */
-    detachAll(): void;
-    dispose(): void;
-    invalidate(): void;
-    render(width: number): string[];
-}
-/**
- * TUI - Main class for managing terminal UI with differential rendering
- */
-export declare class TUI extends Container {
-    #private;
-    terminal: Terminal;
-    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
-    onDebug?: () => void;
-    overlayStack: {
-        component: Component;
-        options?: OverlayOptions;
-        preFocus: Component | null;
-        hidden: boolean;
-    }[];
-    constructor(terminal: Terminal, showHardwareCursor?: boolean);
-    get fullRedraws(): number;
-    getShowHardwareCursor(): boolean;
-    setShowHardwareCursor(enabled: boolean): void;
-    getClearOnShrink(): boolean;
-    /**
-     * Set whether to trigger full re-render when content shrinks.
-     * When true (default), empty rows are cleared when content shrinks.
-     * When false, empty rows remain (reduces redraws on slower terminals).
-     */
-    setClearOnShrink(enabled: boolean): void;
-    setFocus(component: Component | null): void;
-    setBottomPinnedComponent(component: Component | null): void;
-    /**
-     * Show an overlay component with configurable positioning and sizing.
-     * Returns a handle to control the overlay's visibility.
-     */
-    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
-    /** Hide the topmost overlay and restore previous focus. */
-    hideOverlay(): void;
-    /** Check if there are any visible overlays */
-    hasOverlay(): boolean;
-    invalidate(): void;
-    start(): void;
-    get terminalAvailable(): boolean;
-    addInputListener(listener: InputListener): () => void;
-    removeInputListener(listener: InputListener): void;
-    stop(): void;
-    requestRender(force?: boolean, source?: string): void;
-    getLineRenderCacheStats(): {
-        normalizationSize: number;
-        truncationSize: number;
-        normalizationLimit: number;
-        truncationLimit: number;
-    };
-}

package/dist/types/utils.d.ts

@@ -1,75 +0,0 @@
-import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@sayknow-cli/natives";
-export { Ellipsis } from "@sayknow-cli/natives";
-export { getDefaultTabWidth, getIndentation } from "@sayknow-cli/utils";
-export declare function isPrintableAscii(text: string): boolean;
-export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
-export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null, pad?: boolean | null): string;
-export declare function wrapTextWithAnsi(text: string, width: number): string[];
-export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;
-/**
- * Tab width in columns for `file`, using `process.cwd()` as the project root for relative paths.
- */
-export declare function getIndentationNoescape(file?: string): number;
-export declare function replaceTabs(text: string, file?: string): string;
-/**
- * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
- */
-export declare function padding(n: number): string;
-/**
- * Get the shared grapheme segmenter instance.
- */
-export declare function getSegmenter(): Intl.Segmenter;
-export declare function visibleWidthRaw(str: string): number;
-/**
- * Calculate the visible width of a string in terminal columns.
- */
-export declare function visibleWidth(str: string): number;
-/**
- * Normalize text for terminal output without changing logical editor content.
- * Some terminals render canonically decomposed Hangul jamo or precomposed
- * Thai/Lao AM vowels inconsistently during differential repaint. Emit a stable
- * terminal form while keeping the component/source strings unchanged.
- */
-export declare function normalizeTerminalOutput(str: string): string;
-/**
- * Check if a character is whitespace.
- */
-export declare function isWhitespaceChar(char: string): boolean;
-/**
- * Check if a character is punctuation.
- */
-export declare function isPunctuationChar(char: string): boolean;
-export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
-/**
- * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
- * This intentionally avoids language-specific word segmentation for predictability across scripts.
- */
-export declare function getWordNavKind(grapheme: string): WordNavKind;
-export declare function isWordNavJoiner(grapheme: string): boolean;
-/**
- * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
- *
- * Returns a new cursor index in the range [0, text.length].
- */
-export declare function moveWordLeft(text: string, cursor: number): number;
-/**
- * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
- *
- * Returns a new cursor index in the range [0, text.length].
- */
-export declare function moveWordRight(text: string, cursor: number): number;
-/**
- * Apply background color to a line, padding to full width.
- *
- * @param line - Line of text (may contain ANSI codes)
- * @param width - Total width to pad to
- * @param bgFn - Background color function
- * @returns Line with background applied and padded to width
- */
-export declare function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string;
-/**
- * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
- *
- * @param strict - If true, exclude wide chars at boundary that would extend past the range
- */
-export declare function sliceByColumn(line: string, startCol: number, length: number, strict?: boolean): string;