@sayknow-cli/tui 0.3.13 → 0.3.15

package/dist/types/tui.d.ts

@@ -0,0 +1,269 @@
+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 };
+/** 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. Native Windows console hosts are included even when
+ * WT_SESSION is absent because PowerShell/ConPTY launch chains can drop terminal
+ * identity variables while keeping the same scroll-jump behavior.
+ */
+export declare function shouldUseViewportRepaintForHost(env?: Record<string, string | undefined>, platform?: NodeJS.Platform, options?: {
+    includeNativeWindows?: 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;
+    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;
+    }[];
+    constructor(terminal: Terminal, showHardwareCursor?: 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;
+    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;
+    };
+    /**
+     * 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.3.13",
+	"version": "0.3.15",
 	"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.3.13",
-		"@sayknow-cli/utils": "0.3.13",
+		"@sayknow-cli/natives": "0.3.15",
+		"@sayknow-cli/utils": "0.3.15",
 		"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"

package/src/terminal-capabilities.ts

@@ -53,6 +53,35 @@ export function isNotificationSuppressed(): boolean {
 	return value === "off" || value === "0" || value === "false";
 }
 
+const MULTIPLEXER_DISABLED_ENV_VALUES = new Set(["0", "false", "off", "no"]);
+
+function multiplexerEnvEnabled(value: string | undefined): boolean {
+	const normalized = value?.trim().toLowerCase();
+	return normalized !== undefined && normalized.length > 0 && !MULTIPLEXER_DISABLED_ENV_VALUES.has(normalized);
+}
+
+/**
+ * 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 function isUnderTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (
+		multiplexerEnvEnabled(env.TMUX) ||
+		multiplexerEnvEnabled(env.TMUX_PANE) ||
+		multiplexerEnvEnabled(env.STY) ||
+		multiplexerEnvEnabled(env.ZELLIJ) ||
+		multiplexerEnvEnabled(env.SKC_TMUX_LAUNCHED)
+	) {
+		return true;
+	}
+	const term = env.TERM?.trim().toLowerCase() ?? "";
+	return term.startsWith("tmux") || term.startsWith("screen");
+}
+
 let terminalGraphicsFallbackDepth = 0;
 let cursorNeutralImageAllowedDepth = 0;
 
@@ -105,6 +134,15 @@ function getForcedImageProtocol(): ImageProtocol | null | undefined {
 	return null;
 }
 
+/**
+ * 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 function isImageProtocolForced(): boolean {
+	return getForcedImageProtocol() !== undefined;
+}
+
 function parseMajorMinorVersion(versionRaw?: string): { major: number; minor: number } | null {
 	if (!versionRaw) return null;
 	const match = /^(\d+)\.(\d+)/u.exec(versionRaw.trim());
@@ -137,7 +175,7 @@ function getFallbackImageProtocol(terminalId: TerminalId): ImageProtocol | null
 	if (!process.stdout.isTTY) return null;
 	if (terminalId === "vscode" || terminalId === "alacritty") return null;
 	const term = Bun.env.TERM?.toLowerCase() ?? "";
-	if (term.includes("screen") || term.includes("tmux") || term.includes("ghostty")) {
+	if (term.includes("ghostty")) {
 		return ImageProtocol.Kitty;
 	}
 	return null;
@@ -220,10 +258,10 @@ export const TERMINAL = (() => {
 			);
 		}
 	}
+	const underMultiplexer = isUnderTerminalMultiplexer();
 	// tmux and screen multiplexers do not reliably forward OSC 8 hyperlinks
 	// to the outer terminal, so force them off regardless of detected terminal.
-	const term = Bun.env.TERM?.toLowerCase() ?? "";
-	if (resolved.hyperlinks && (Bun.env.TMUX || term.startsWith("tmux") || term.startsWith("screen"))) {
+	if (resolved.hyperlinks && underMultiplexer) {
 		resolved = new TerminalInfo(
 			resolved.id,
 			resolved.imageProtocol,
@@ -232,6 +270,17 @@ export const TERMINAL = (() => {
 			resolved.notifyProtocol,
 		);
 	}
+	// Multiplexers (tmux/screen/zellij) consume raw kitty/iTerm2 graphics
+	// escapes instead of forwarding them (no DCS passthrough wrapping is
+	// emitted), so a detected image protocol draws nothing while its
+	// out-of-band cursor writes corrupt the frame. Graphics are therefore
+	// unconditionally suppressed under a multiplexer; the runtime sixel probe
+	// never runs there (tmux advertises DA1 ";4" from compile-time support
+	// regardless of the attached client), and PI_FORCE_IMAGE_PROTOCOL=sixel
+	// is the only opt-in for chains that render sixel end-to-end.
+	if (resolved.imageProtocol && forcedImageProtocol === undefined && underMultiplexer) {
+		resolved = new TerminalInfo(resolved.id, null, resolved.trueColor, resolved.hyperlinks, resolved.notifyProtocol);
+	}
 	return resolved;
 })();
 
@@ -239,11 +288,35 @@ type MutableTerminalInfo = {
 	imageProtocol: ImageProtocol | null;
 };
 
+type ImageProtocolChangeListener = (imageProtocol: ImageProtocol | null) => void;
+const imageProtocolChangeListeners = new Set<ImageProtocolChangeListener>();
+
+/**
+ * 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 function onImageProtocolChanged(listener: ImageProtocolChangeListener): () => void {
+	imageProtocolChangeListeners.add(listener);
+	return () => {
+		imageProtocolChangeListeners.delete(listener);
+	};
+}
+
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
 export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void {
-	(TERMINAL as unknown as MutableTerminalInfo).imageProtocol = imageProtocol;
+	const mutable = TERMINAL as unknown as MutableTerminalInfo;
+	if (mutable.imageProtocol === imageProtocol) return;
+	mutable.imageProtocol = imageProtocol;
+	for (const listener of imageProtocolChangeListeners) {
+		try {
+			listener(imageProtocol);
+		} catch {
+			// Listener failures must not break protocol switching.
+		}
+	}
 }
 
 export function getTerminalInfo(terminalId: TerminalId): TerminalInfo {