@sayknow-cli/tui 0.3.13 → 0.3.15

package/dist/types/metrics.d.ts

@@ -0,0 +1,85 @@
+/** 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

@@ -0,0 +1,50 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,187 @@
+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 whether the process runs under a terminal multiplexer (tmux, GNU
+ * screen, or zellij). Recognizes the same host markers as the renderer's
+ * multiplexer predicate in tui.ts so capability selection and viewport-repaint
+ * policy agree on what counts as a multiplexed host. Multiplexers intercept
+ * graphics escapes and OSC 8 hyperlinks instead of forwarding them to the
+ * outer terminal.
+ */
+export declare function isUnderTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
+export interface TerminalGraphicsFallbackOptions {
+    /**
+     * Permit cursor-neutral image escapes (kitty `a=p,C=1` placements) to render
+     * inside this fallback scope. Cursor-advancing protocols (iTerm2/SIXEL)
+     * remain suppressed. A nested scope without this option revokes the
+     * permission for its own subtree.
+     */
+    allowCursorNeutralImages?: boolean;
+}
+/**
+ * Synchronously suppress terminal graphics while rendering a text-only surface.
+ * Nested scopes remain active until the outermost scope exits.
+ */
+export declare function withTerminalGraphicsFallback<T>(fn: () => T, options?: TerminalGraphicsFallbackOptions): T;
+/** Returns whether terminal graphics are currently suppressed by a render scope. */
+export declare function isTerminalGraphicsFallbackActive(): boolean;
+/**
+ * Returns whether cursor-neutral image escapes may render despite an active
+ * graphics-fallback scope. True only when every active fallback scope opted in.
+ */
+export declare function isCursorNeutralImagePermittedInFallback(): boolean;
+/**
+ * Returns whether PI_FORCE_IMAGE_PROTOCOL explicitly configures the image
+ * protocol, including an explicit "off". An explicit configuration is
+ * authoritative: runtime capability probes must not override it.
+ */
+export declare function isImageProtocolForced(): 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;
+type ImageProtocolChangeListener = (imageProtocol: ImageProtocol | null) => void;
+/**
+ * Subscribe to runtime image-protocol changes (e.g. the asynchronous sixel
+ * capability probe enabling graphics after startup). Returns an unsubscribe
+ * function. Listeners fire only on actual changes.
+ */
+export declare function onImageProtocolChanged(listener: ImageProtocolChangeListener): () => void;
+/**
+ * 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;
+    /**
+     * Kitty-only: stable placement id (`p=`). Re-emitting the same image id +
+     * placement id *replaces* the existing placement instead of stacking a new
+     * copy, which makes diff-renderer repaints idempotent. Callers that render
+     * a persistent component should allocate one id per component instance.
+     */
+    placementId?: number;
+    /**
+     * Kitty-only: stable image id (`i=`). Defaults to a content hash of the
+     * base64 payload ({@link kittyImageId}). Pass a precomputed id to avoid
+     * re-hashing large payloads on every render.
+     */
+    imageId?: number;
+    /**
+     * Kitty-only: sink for the out-of-band data transmission (`a=t`) emitted
+     * the first time an image id is rendered. Defaults to the process-wide
+     * writer configured via {@link setKittyTransmitWriter} (stdout).
+     */
+    onTransmit?: (sequence: string) => void;
+}
+/**
+ * Derive a stable 32-bit non-zero kitty image id (`i=`) from image content
+ * (FNV-1a over the base64 payload). Identical content maps to the same id, so
+ * retransmission replaces the stored image instead of accumulating copies.
+ */
+export declare function kittyImageId(base64Data: string): number;
+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;
+    placementId?: number;
+}): string;
+/** Test hook: forget which kitty image ids were transmitted. */
+export declare function resetKittyTransmissions(): void;
+/**
+ * Override where out-of-band kitty data transmissions (`a=t`) are written.
+ * The default writes directly to stdout: a transmit-only escape is
+ * cursor-neutral (it uploads pixel data without drawing anything), so the
+ * only ordering requirement is that it reaches the terminal before the
+ * placement escape that references it — which the synchronous write during
+ * render guarantees. Tests use this to capture transmissions.
+ */
+export declare function setKittyTransmitWriter(writer: (sequence: string) => void): void;
+/**
+ * Encode a kitty transmit-only (`a=t`) escape: uploads image data under a
+ * stable id without creating a placement. Chunked at 4096 bytes per spec.
+ *
+ * This is deliberately separate from placement: re-sending data (`a=t`/`a=T`)
+ * for an existing image id deletes the image and ALL of its placements, so
+ * data must be uploaded exactly once per id and repaints must go through
+ * {@link encodeKittyPlacement} only.
+ */
+export declare function encodeKittyTransmit(base64Data: string, imageId: number): string;
+/**
+ * Encode a kitty placement-only (`a=p`) escape referencing previously
+ * transmitted data. Re-emitting the same i=/p= pair replaces that one
+ * placement (never stacks, never touches sibling placements), and C=1
+ * keeps the cursor where it is so the escape can be emitted from the
+ * component's first row without cursor-up tricks.
+ */
+export declare function encodeKittyPlacement(options: {
+    imageId: number;
+    placementId: number;
+    columns: number;
+    rows: 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 interface RenderedImage {
+    sequence: string;
+    rows: number;
+    /**
+     * True when the escape neither moves the cursor nor carries pixel data
+     * (kitty `a=p,C=1` placements). Cursor-neutral sequences can be emitted
+     * from the component's first row; cursor-advancing protocols
+     * (iTerm2/SIXEL) must draw from the last reserved row instead.
+     */
+    cursorNeutral?: boolean;
+}
+export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): RenderedImage | null;
+export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+export {};

package/dist/types/terminal.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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;
+    readonly isProcessTerminal?: 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;
+}
+interface TerminalSizeStream {
+    columns?: number;
+    rows?: number;
+    getWindowSize?: () => [number, number] | number[];
+}
+export declare function resolveTerminalColumns(stream?: TerminalSizeStream, envColumns?: string | undefined): number;
+export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows?: string | undefined): number;
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export declare class ProcessTerminal implements Terminal {
+    #private;
+    get isProcessTerminal(): boolean;
+    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;
+}
+export {};

package/dist/types/ttyid.d.ts

@@ -0,0 +1,9 @@
+/** 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;