@sayknow-cli/tui 0.4.1 → 0.4.3

package/dist/types/tui.d.ts

@@ -0,0 +1,304 @@
+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 type MouseEvent = {
+    kind: "wheel" | "click";
+    direction?: -1 | 1;
+    button?: 0;
+    /** Terminal cell coordinates, one-based. */
+    x: number;
+    y: number;
+    /** Focused-overlay cell coordinates, one-based when dispatched to an overlay. */
+    localX?: number;
+    localY?: number;
+};
+type OverlayMouseBounds = {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+    termWidth: number;
+    termHeight: number;
+};
+/** Parse xterm SGR mouse reports. Drag and button-release reports are ignored. */
+export declare function parseSgrMouseEvent(data: string): MouseEvent | undefined;
+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;
+    /** Optional handler for terminal mouse events when component has focus. */
+    handleMouse?(event: MouseEvent): 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 };
+/** Durable source identifier for a semantically anchored viewport row. */
+export type ViewportAnchorId = string;
+export interface ViewportAnchorRow {
+    id: ViewportAnchorId;
+    graphemeStart: number;
+    graphemeEnd: number;
+    cellStart: number;
+    cellEnd: number;
+}
+export interface ViewportAnchorRender {
+    lines: string[];
+    anchors: Array<ViewportAnchorRow | null>;
+}
+export interface ViewportAnchorProvider extends Component {
+    renderWithViewportAnchors(width: number): ViewportAnchorRender;
+}
+export interface ViewportAnchorSource {
+    id: ViewportAnchorId;
+}
+export interface ViewportAnchorSourceRenderer extends Component {
+    renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
+}
+export declare function isViewportAnchorProvider(component: Component): component is ViewportAnchorProvider;
+export declare function isViewportAnchorSourceRenderer(component: Component): component is ViewportAnchorSourceRenderer;
+export declare function renderComponentWithViewportAnchors(component: Component, width: number): ViewportAnchorRender;
+export declare function renderComponentWithViewportAnchorSource(component: Component, width: number, source: ViewportAnchorSource): ViewportAnchorRender;
+/**
+ * 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}%`;
+/**
+ * Startup sixel capability probe policy (pure; exported for tests):
+ * - Never probe when PI_FORCE_IMAGE_PROTOCOL is set — an explicit
+ *   configuration (including "off") is authoritative.
+ * - Never probe inside a terminal multiplexer: tmux advertises DA1 ";4"
+ *   whenever it was compiled with sixel support, regardless of whether the
+ *   attached client terminal can render sixel, so a positive reply is not
+ *   end-to-end evidence. Graphics under a multiplexer are strictly opt-in
+ *   via PI_FORCE_IMAGE_PROTOCOL=sixel.
+ * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
+ */
+export declare function shouldProbeSixelCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * True when repainting only the live viewport is safer than clearing/replaying
+ * the full transcript. Real process terminals are viewport-sensitive because
+ * their native scrollback position is not observable by the renderer. Native
+ * Windows console hosts are also recognized from platform identity when that
+ * process-terminal capability is unavailable.
+ */
+export declare function shouldUseViewportRepaintForHost(env?: Record<string, string | undefined>, platform?: NodeJS.Platform, options?: {
+    includeNativeWindows?: boolean;
+    includeProcessTerminal?: boolean;
+}): boolean;
+/**
+ * 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 ViewportAnchorProvider {
+    #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;
+    /** Registers a direct child as eligible for semantic viewport anchoring. */
+    setViewportAnchorSource(component: Component, source: ViewportAnchorSource | null): void;
+    dispose(): void;
+    invalidate(): void;
+    render(width: number): string[];
+    renderWithViewportAnchors(width: number): ViewportAnchorRender;
+}
+type TuiRenderCounterSnapshot = {
+    debugRedrawEnvReads: number;
+    debugRedrawAppendWrites: number;
+    differentialGuardVisibleWidthCalls: number;
+};
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    #private;
+    private readonly options;
+    terminal: Terminal;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    static resetRenderCountersForTest(): void;
+    static getRenderCountersForTest(): TuiRenderCounterSnapshot;
+    overlayStack: {
+        component: Component;
+        options?: OverlayOptions;
+        preFocus: Component | null;
+        hidden: boolean;
+        mouseBounds?: OverlayMouseBounds;
+    }[];
+    constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: {
+        enableMouse?: boolean;
+    });
+    dispose(): void;
+    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;
+    /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
+    setViewportAnchorComponent(component: Component | null): void;
+    /** Clear manual viewport ownership before replacing the transcript identity namespace. */
+    resetViewportAnchorIntent(): void;
+    /** Allow one semantic-neighbor reconciliation after a definitive same-transcript rebuild. */
+    prepareViewportAnchorForTranscriptRebuild(): void;
+    /** Reveal a semantic viewport anchor without changing the rendered content width. */
+    revealViewportAnchor(id: ViewportAnchorId, alignment: "top" | "center" | "bottom"): boolean;
+    scrollViewportPages(direction: -1 | 1): boolean;
+    followLiveViewport(): boolean;
+    /**
+     * 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;
+    /**
+     * Viewport-repaint-aware resize render request.
+     *
+     * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
+     * to -1, which makes `#doRender` treat the frame as a width change and fall into the
+     * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
+     * `3J` escape (users navigate scrollback history), so replaying every transcript line
+     * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
+     * high speed" resize storm. Windows Terminal/ConPTY can also visibly jump to
+     * the transcript top during streaming redraws, so viewport-repaint sessions
+     * keep force off and let `#doRender` repaint only the live viewport. Set
+     * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
+     */
+    requestResizeRender(): void;
+    requestRender(force?: boolean, source?: string): void;
+    getLineRenderCacheStats(): {
+        normalizationSize: number;
+        truncationSize: number;
+        normalizationLimit: number;
+        truncationLimit: number;
+    };
+    /** Retain terminal cleanup until a write succeeds, even after its component is disposed. */
+    queueTerminalCleanup(payload: string, onDelivered?: () => void): void;
+    /** Retry queued terminal cleanup after terminal recovery or before shutdown. */
+    flushTerminalCleanup(): void;
+    /**
+     * Register an emitter whose escape payload is appended to every render
+     * write (inside its own synchronized-output block, cursor saved/restored).
+     * Used for absolute-positioned overlays such as pixel-image pets that live
+     * outside the line-based component model. Return null to emit nothing.
+     */
+    setPostRenderEmitter(emitter: (() => string | null) | undefined): void;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,110 @@
+import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@sayknow-cli/natives";
+export { Ellipsis } from "@sayknow-cli/natives";
+export { getDefaultTabWidth, getIndentation } from "@sayknow-cli/utils";
+/** Test-only performance counters for advisory baseline tests. */
+export declare const __textHelperPerfCounters: {
+    truncateToWidthCalls: number;
+    wrapTextWithAnsiCalls: number;
+    truncateLinesToWidthCalls: number;
+    visibleWidthsCalls: number;
+    reset(): void;
+};
+export declare function invalidateTabWidthCache(): void;
+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 truncateLinesToWidth(lines: readonly 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 interface ViewportAnchorSpan {
+    graphemeStart: number;
+    graphemeEnd: number;
+    cellStart: number;
+    cellEnd: number;
+}
+export interface ViewportAnchorAnnotation {
+    text: string;
+    nextGrapheme: number;
+    nextCell: number;
+    token: string;
+}
+export declare const VIEWPORT_ANCHOR_PREFIX = "\u001B_ASKC_ANCHOR:";
+/**
+ * Tag every visible grapheme with an APC marker that survives ANSI-aware
+ * wrapping. The marker contains source grapheme and monotonic cell offsets.
+ */
+export declare function annotateViewportAnchorGraphemes(text: string, startGrapheme?: number, startCell?: number, token?: `${string}-${string}-${string}-${string}-${string}`): ViewportAnchorAnnotation;
+/** Remove viewport anchor markers and return the exact marked span for each row. */
+export declare function extractViewportAnchorRows(lines: readonly string[], token: string): {
+    lines: string[];
+    spans: Array<ViewportAnchorSpan | null>;
+};
+export declare function visibleWidthRaw(str: string): number;
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export declare function visibleWidth(str: string): number;
+export declare function visibleWidthsNative(lines: readonly string[]): number[];
+export declare function visibleWidths(lines: readonly 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;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -27,7 +27,7 @@
 		"cli"
 	],
 	"main": "./src/index.ts",
-	"types": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.4.1",
-		"@sayknow-cli/utils": "0.4.1",
+		"@sayknow-cli/natives": "0.4.3",
+		"@sayknow-cli/utils": "0.4.3",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},
@@ -53,19 +53,20 @@
 	"files": [
 		"src",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"dist/types"
 	],
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
+			"types": "./dist/types/index.d.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./src/*.ts",
+			"types": "./dist/types/*.d.ts",
 			"import": "./src/*.ts"
 		},
 		"./components/*": {
-			"types": "./src/components/*.ts",
+			"types": "./dist/types/components/*.d.ts",
 			"import": "./src/components/*.ts"
 		},
 		"./*.js": "./src/*.ts"