@sayknow-cli/tui 0.3.7 → 0.3.9

package/dist/types/animation-scheduler.d.ts

@@ -0,0 +1,13 @@
+export type AnimationCadence = 16 | 80;
+type AnimationCallback = (now: number) => void;
+export interface AnimationRegistration {
+    unregister(): void;
+}
+export declare function registerAnimationCallback(callback: AnimationCallback, cadence?: AnimationCadence): AnimationRegistration;
+export declare const __animationSchedulerTestHooks: {
+    getActiveTimerCount(cadence?: AnimationCadence): number;
+    getRegistrantCount(cadence?: AnimationCadence): number;
+    getStartedTimerCount(cadence?: AnimationCadence): number;
+    reset(): void;
+};
+export {};

package/dist/types/autocomplete.d.ts

@@ -1,4 +1,5 @@
 export declare function getSlashCommandMatchRank(query: string, commandName: string): number;
+export declare function extractSlashCommandTokenPrefix(text: string): string | null;
 export interface AutocompleteItem {
     value: string;
     label: string;

package/dist/types/components/editor.d.ts

@@ -1,4 +1,4 @@
-import type { AutocompleteProvider } from "../autocomplete";
+import { type AutocompleteProvider } from "../autocomplete";
 import type { SymbolTheme } from "../symbols";
 import { type Component, type Focusable } from "../tui";
 import { type SelectListTheme } from "./select-list";
@@ -24,6 +24,13 @@ interface HistoryStorage {
     add(prompt: string, cwd?: string): Promise<void>;
     getRecent(limit: number, cwd?: string): HistoryEntry[];
 }
+/** Test-only performance counters for advisory baseline tests. */
+export declare const __editorPerfCounters: {
+    layoutTextInvocations: number;
+    layoutLogicalLinesProcessed: number;
+    visibleWidthMeasurements: number;
+    reset(): void;
+};
 export declare class Editor implements Component, Focusable {
     #private;
     /** Focusable interface - set by TUI when focus changes */
@@ -46,6 +53,7 @@ export declare class Editor implements Component, Focusable {
     onTab?: (text: string) => boolean | undefined;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
+    dispose(): void;
     setAutocompleteProvider(provider: AutocompleteProvider): void;
     getAutocompleteProvider(): AutocompleteProvider | undefined;
     /** Whether the autocomplete dropdown is currently open. */
@@ -66,7 +74,7 @@ export declare class Editor implements Component, Focusable {
     setPlaceholder(placeholder: string | undefined): void;
     /**
      * Get the available width for top border content given a total terminal width.
-     * Accounts for the border characters and horizontal padding when visible.
+     * Accounts for right gutter, border characters, and horizontal padding when visible.
      */
     getTopBorderAvailableWidth(terminalWidth: number): number;
     /**
@@ -76,6 +84,7 @@ export declare class Editor implements Component, Focusable {
     getUseTerminalCursor(): boolean;
     setMaxHeight(maxHeight: number | undefined): void;
     setPaddingX(paddingX: number): void;
+    setRightGutterWidth(width: number): void;
     getAutocompleteMaxVisible(): number;
     setAutocompleteMaxVisible(maxVisible: number): void;
     setHistoryStorage(storage: HistoryStorage): void;

package/dist/types/components/loader.d.ts

@@ -1,11 +1,20 @@
 import type { TUI } from "../tui";
 import { Text } from "./text";
+export interface LoaderOptions {
+    timeDependentColor?: boolean;
+}
+/** Test-only performance counters for advisory baseline tests. */
+export declare const __loaderPerfCounters: {
+    liveIntervals: number;
+    startedIntervals: number;
+    reset(): void;
+};
 export declare class Loader extends Text {
     #private;
     private spinnerColorFn;
     private messageColorFn;
     private message;
-    constructor(ui: TUI, spinnerColorFn: (str: string) => string, messageColorFn: (str: string) => string, message?: string, spinnerFrames?: string[]);
+    constructor(ui: TUI, spinnerColorFn: (str: string) => string, messageColorFn: (str: string) => string, message?: string, spinnerFrames?: string[], options?: LoaderOptions);
     render(width: number): string[];
     start(): void;
     stop(): void;

package/dist/types/components/markdown.d.ts

@@ -1,8 +1,16 @@
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
+/** Test-only clock seam for streaming throttle tests. */
+export declare function __setMarkdownNowForTest(now: (() => number) | undefined): void;
 /** Test/diagnostic seam: number of synchronous highlight invocations since the last reset. */
 export declare function getMarkdownHighlightCallCount(): number;
 export declare function resetMarkdownHighlightCallCount(): void;
+/** Test-only performance counters for advisory baseline tests. */
+export declare const __markdownPerfCounters: {
+    lexerInvocations: number;
+    lexedBytes: number;
+    reset(): void;
+};
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export declare function clearRenderCache(): void;
 /**
@@ -53,7 +61,12 @@ export interface MarkdownTheme {
 export declare class Markdown implements Component {
     #private;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
-    setText(text: string): void;
+    setOnStaleThrottle(callback: (() => void) | undefined): void;
+    setText(text: string, options?: {
+        streaming?: boolean;
+    }): void;
+    setStreaming(streaming: boolean): void;
+    dispose(): void;
     invalidate(): void;
     render(width: number): string[];
 }

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./animation-scheduler";
 export * from "./autocomplete";
 export * from "./components/box";
 export * from "./components/cancellable-loader";

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

@@ -47,13 +47,73 @@ 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;
@@ -68,8 +128,16 @@ export declare function getJpegDimensions(base64Data: string): ImageDimensions |
 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): {
+export interface RenderedImage {
     sequence: string;
     rows: number;
-} | null;
+    /**
+     * 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;

package/dist/types/terminal.d.ts

@@ -32,6 +32,7 @@ export interface Terminal {
     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;
@@ -64,6 +65,7 @@ export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows
  */
 export declare class ProcessTerminal implements Terminal {
     #private;
+    get isProcessTerminal(): boolean;
     get kittyProtocolActive(): boolean;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;

package/dist/types/tui.d.ts

@@ -72,6 +72,15 @@ export interface OverlayMargin {
 }
 /** Value that can be absolute (number) or percentage (string like "50%") */
 export type SizeValue = number | `${number}%`;
+/**
+ * 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%").
@@ -130,6 +139,11 @@ export declare class Container implements Component {
     invalidate(): void;
     render(width: number): string[];
 }
+type TuiRenderCounterSnapshot = {
+    debugRedrawEnvReads: number;
+    debugRedrawAppendWrites: number;
+    differentialGuardVisibleWidthCalls: number;
+};
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -138,6 +152,8 @@ export declare class TUI extends Container {
     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;
@@ -145,6 +161,7 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    dispose(): void;
     get fullRedraws(): number;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
@@ -175,16 +192,17 @@ export declare class TUI extends Container {
     removeInputListener(listener: InputListener): void;
     stop(): void;
     /**
-     * Multiplexer-aware resize render request.
+     * 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. Here we keep force off in multiplexers so `#doRender`'s
-     * height-change branch takes the viewport-only `multiplexerViewportRepaint` path instead.
-     * Set `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy forced redraw.
+     * 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;

package/dist/types/utils.d.ts

@@ -1,9 +1,19 @@
 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;
 /**
@@ -24,6 +34,8 @@ 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

package/package.json

@@ -1,9 +1,9 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.7",
+	"version": "0.3.9",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
+	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
 	"contributors": [
 		"Mario Zechner"
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.7",
-		"@sayknow-cli/utils": "0.3.7",
+		"@sayknow-cli/natives": "0.3.9",
+		"@sayknow-cli/utils": "0.3.9",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/animation-scheduler.ts

@@ -0,0 +1,99 @@
+export type AnimationCadence = 16 | 80;
+
+type TimerHandle = ReturnType<typeof setInterval>;
+type AnimationCallback = (now: number) => void;
+
+interface CadenceBucket {
+	callbacks: Set<AnimationCallback>;
+	timer?: TimerHandle;
+	startedTimers: number;
+}
+
+const buckets = new Map<AnimationCadence, CadenceBucket>();
+
+function getBucket(cadence: AnimationCadence): CadenceBucket {
+	let bucket = buckets.get(cadence);
+	if (!bucket) {
+		bucket = { callbacks: new Set(), startedTimers: 0 };
+		buckets.set(cadence, bucket);
+	}
+	return bucket;
+}
+
+function startBucket(cadence: AnimationCadence, bucket: CadenceBucket): void {
+	if (bucket.timer) return;
+	bucket.timer = setInterval(() => {
+		const now = performance.now();
+		// Snapshot so re-entrant register/unregister during a tick is safe, and
+		// isolate each callback so one throwing registrant cannot starve siblings
+		// or surface as an uncaught exception that kills the shared timer.
+		for (const callback of [...bucket.callbacks]) {
+			try {
+				callback(now);
+			} catch (err) {
+				console.error("[animation-scheduler] callback threw:", err);
+			}
+		}
+	}, cadence);
+	bucket.startedTimers += 1;
+	bucket.timer?.unref?.();
+}
+
+function stopBucket(bucket: CadenceBucket): void {
+	if (!bucket.timer) return;
+	clearInterval(bucket.timer);
+	bucket.timer = undefined;
+}
+
+export interface AnimationRegistration {
+	unregister(): void;
+}
+
+export function registerAnimationCallback(
+	callback: AnimationCallback,
+	cadence: AnimationCadence = 80,
+): AnimationRegistration {
+	const bucket = getBucket(cadence);
+	bucket.callbacks.add(callback);
+	startBucket(cadence, bucket);
+	let registered = true;
+
+	return {
+		unregister(): void {
+			if (!registered) return;
+			registered = false;
+			bucket.callbacks.delete(callback);
+			if (bucket.callbacks.size === 0) stopBucket(bucket);
+		},
+	};
+}
+
+export const __animationSchedulerTestHooks = {
+	getActiveTimerCount(cadence?: AnimationCadence): number {
+		if (cadence !== undefined) return getBucket(cadence).timer ? 1 : 0;
+		let count = 0;
+		for (const bucket of buckets.values()) {
+			if (bucket.timer) count += 1;
+		}
+		return count;
+	},
+	getRegistrantCount(cadence?: AnimationCadence): number {
+		if (cadence !== undefined) return getBucket(cadence).callbacks.size;
+		let count = 0;
+		for (const bucket of buckets.values()) count += bucket.callbacks.size;
+		return count;
+	},
+	getStartedTimerCount(cadence?: AnimationCadence): number {
+		if (cadence !== undefined) return getBucket(cadence).startedTimers;
+		let count = 0;
+		for (const bucket of buckets.values()) count += bucket.startedTimers;
+		return count;
+	},
+	reset(): void {
+		for (const bucket of buckets.values()) {
+			stopBucket(bucket);
+			bucket.callbacks.clear();
+			bucket.startedTimers = 0;
+		}
+	},
+};