@sayknow-cli/tui 0.3.11 → 0.3.13

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.11",
+	"version": "0.3.13",
 	"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": "./dist/types/index.d.ts",
+	"types": "./src/index.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.11",
-		"@sayknow-cli/utils": "0.3.11",
+		"@sayknow-cli/natives": "0.3.13",
+		"@sayknow-cli/utils": "0.3.13",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},
@@ -53,20 +53,19 @@
 	"files": [
 		"src",
 		"README.md",
-		"CHANGELOG.md",
-		"dist/types"
+		"CHANGELOG.md"
 	],
 	"exports": {
 		".": {
-			"types": "./dist/types/index.d.ts",
+			"types": "./src/index.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./dist/types/*.d.ts",
+			"types": "./src/*.ts",
 			"import": "./src/*.ts"
 		},
 		"./components/*": {
-			"types": "./dist/types/components/*.d.ts",
+			"types": "./src/components/*.ts",
 			"import": "./src/components/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/components/image.ts

@@ -3,6 +3,8 @@ import {
 	type ImageDimensions,
 	ImageProtocol,
 	imageFallback,
+	isCursorNeutralImagePermittedInFallback,
+	isTerminalGraphicsFallbackActive,
 	kittyImageId,
 	renderImage,
 	TERMINAL,
@@ -28,10 +30,11 @@ export interface ImageOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	filename?: string;
+	refetch?: () => string;
 }
 
 export class Image implements Component {
-	#base64Data: string;
+	#base64Data?: string;
 	#mimeType: string;
 	#dimensions: ImageDimensions;
 	#theme: ImageTheme;
@@ -39,7 +42,8 @@ export class Image implements Component {
 
 	#cachedLines?: string[];
 	#cachedWidth?: number;
-	// Kitty graphics: content-derived image id + per-instance placement id.
+	#cachedFallbackActive?: boolean;
+	#cachedProtocol?: ImageProtocol | null;
 	// Computed lazily so non-kitty terminals never pay the hash cost.
 	#kittyImageId?: number;
 	readonly #kittyPlacementId = allocatePlacementId();
@@ -61,10 +65,40 @@ export class Image implements Component {
 	invalidate(): void {
 		this.#cachedLines = undefined;
 		this.#cachedWidth = undefined;
+		this.#cachedFallbackActive = undefined;
+		this.#cachedProtocol = undefined;
+	}
+
+	get retainedBase64DataForTest(): string | undefined {
+		return this.#base64Data;
+	}
+
+	#fallbackLines(): string[] {
+		const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
+		return [this.#theme.fallbackColor(fallback)];
+	}
+
+	#getBase64Data(): string | undefined {
+		if (this.#base64Data) return this.#base64Data;
+		const refetched = this.#options.refetch?.();
+		if (refetched) this.#base64Data = refetched;
+		return this.#base64Data;
 	}
 
 	render(width: number): string[] {
-		if (this.#cachedLines && this.#cachedWidth === width) {
+		// Kitty placements are cursor-neutral, so an opted-in fallback scope
+		// (e.g. the IRC split) can still render them safely; iTerm2/SIXEL
+		// advance the cursor and stay suppressed.
+		const graphicsSuppressed =
+			isTerminalGraphicsFallbackActive() &&
+			!(TERMINAL.imageProtocol === ImageProtocol.Kitty && isCursorNeutralImagePermittedInFallback());
+		const protocol = TERMINAL.imageProtocol;
+		if (
+			this.#cachedLines &&
+			this.#cachedWidth === width &&
+			this.#cachedFallbackActive === graphicsSuppressed &&
+			this.#cachedProtocol === protocol
+		) {
 			return this.#cachedLines;
 		}
 
@@ -73,51 +107,57 @@ export class Image implements Component {
 
 		let lines: string[];
 
-		if (TERMINAL.imageProtocol) {
-			if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
-				this.#kittyImageId ??= kittyImageId(this.#base64Data);
-			}
-			const result = renderImage(this.#base64Data, this.#dimensions, {
-				maxWidthCells: maxWidth,
-				maxHeightCells: this.#options.maxHeightCells,
-				imageId: this.#kittyImageId,
-				placementId: this.#kittyPlacementId,
-			});
-
-			if (result) {
-				// Return `rows` lines so the TUI accounts for the image height.
-				if (result.cursorNeutral) {
-					// Kitty a=p,C=1 placements neither move the cursor nor carry
-					// pixel data, so the escape lives on the FIRST row — the image
-					// anchors to that cell and no cursor-up trick is needed (the
-					// old CUU approach clamped at the viewport top edge and placed
-					// the image over transcript text when partially scrolled out).
-					lines = [result.sequence];
-					for (let i = 0; i < result.rows - 1; i++) {
-						lines.push("");
+		if (protocol && !graphicsSuppressed) {
+			const base64Data = this.#getBase64Data();
+			if (!base64Data) {
+				lines = this.#fallbackLines();
+			} else {
+				if (protocol === ImageProtocol.Kitty) {
+					this.#kittyImageId ??= kittyImageId(base64Data);
+				}
+				const result = renderImage(base64Data, this.#dimensions, {
+					maxWidthCells: maxWidth,
+					maxHeightCells: this.#options.maxHeightCells,
+					imageId: this.#kittyImageId,
+					placementId: this.#kittyPlacementId,
+				});
+
+				if (result) {
+					// Return `rows` lines so the TUI accounts for the image height.
+					if (result.cursorNeutral) {
+						// Kitty a=p,C=1 placements neither move the cursor nor carry
+						// pixel data, so the escape lives on the FIRST row — the image
+						// anchors to that cell and no cursor-up trick is needed (the
+						// old CUU approach clamped at the viewport top edge and placed
+						// the image over transcript text when partially scrolled out).
+						lines = [result.sequence];
+						for (let i = 0; i < result.rows - 1; i++) {
+							lines.push("");
+						}
+					} else {
+						// iTerm2/SIXEL draw at the cursor and advance it: reserve
+						// rows-1 blank lines (TUI clears them), then move the cursor
+						// up and draw from the last line.
+						lines = [];
+						for (let i = 0; i < result.rows - 1; i++) {
+							lines.push("");
+						}
+						const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
+						lines.push(moveUp + result.sequence);
 					}
+					this.#base64Data = undefined;
 				} else {
-					// iTerm2/SIXEL draw at the cursor and advance it: reserve
-					// rows-1 blank lines (TUI clears them), then move the cursor
-					// up and draw from the last line.
-					lines = [];
-					for (let i = 0; i < result.rows - 1; i++) {
-						lines.push("");
-					}
-					const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
-					lines.push(moveUp + result.sequence);
+					lines = this.#fallbackLines();
 				}
-			} else {
-				const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
-				lines = [this.#theme.fallbackColor(fallback)];
 			}
 		} else {
-			const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
-			lines = [this.#theme.fallbackColor(fallback)];
+			lines = this.#fallbackLines();
 		}
 
 		this.#cachedLines = lines;
 		this.#cachedWidth = width;
+		this.#cachedFallbackActive = graphicsSuppressed;
+		this.#cachedProtocol = protocol;
 
 		return lines;
 	}