@dungle-scrubs/tallow 0.8.21 → 0.8.23

package/packages/tallow-tui/src/terminal-image.ts

@@ -0,0 +1,619 @@
+export type ImageProtocol = "kitty" | "iterm2" | null;
+
+export interface TerminalCapabilities {
+	images: ImageProtocol;
+	trueColor: boolean;
+	hyperlinks: boolean;
+}
+
+export interface CellDimensions {
+	widthPx: number;
+	heightPx: number;
+}
+
+export interface ImageDimensions {
+	widthPx: number;
+	heightPx: number;
+}
+
+export interface ImageRenderOptions {
+	maxWidthCells?: number;
+	maxHeightCells?: number;
+	preserveAspectRatio?: boolean;
+	/** Kitty image ID. If provided, reuses/replaces existing image with this ID. */
+	imageId?: number;
+}
+
+let cachedCapabilities: TerminalCapabilities | null = null;
+
+// Default cell dimensions - updated by TUI when terminal responds to query
+let cellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 };
+
+export function getCellDimensions(): CellDimensions {
+	return cellDimensions;
+}
+
+export function setCellDimensions(dims: CellDimensions): void {
+	if (dims.widthPx > 0 && dims.heightPx > 0) {
+		cellDimensions = dims;
+	}
+}
+
+export function detectCapabilities(): TerminalCapabilities {
+	const termProgram = process.env.TERM_PROGRAM?.toLowerCase() || "";
+	const term = process.env.TERM?.toLowerCase() || "";
+	const colorTerm = process.env.COLORTERM?.toLowerCase() || "";
+
+	if (process.env.KITTY_WINDOW_ID || termProgram === "kitty") {
+		return { images: "kitty", trueColor: true, hyperlinks: true };
+	}
+
+	if (termProgram === "ghostty" || term.includes("ghostty") || process.env.GHOSTTY_RESOURCES_DIR) {
+		return { images: "kitty", trueColor: true, hyperlinks: true };
+	}
+
+	if (process.env.WEZTERM_PANE || termProgram === "wezterm") {
+		return { images: "kitty", trueColor: true, hyperlinks: true };
+	}
+
+	if (process.env.ITERM_SESSION_ID || termProgram === "iterm.app") {
+		return { images: "iterm2", trueColor: true, hyperlinks: true };
+	}
+
+	if (termProgram === "vscode") {
+		return { images: null, trueColor: true, hyperlinks: true };
+	}
+
+	if (termProgram === "alacritty") {
+		return { images: null, trueColor: true, hyperlinks: true };
+	}
+
+	const trueColor = colorTerm === "truecolor" || colorTerm === "24bit";
+	return { images: null, trueColor, hyperlinks: true };
+}
+
+export function getCapabilities(): TerminalCapabilities {
+	if (!cachedCapabilities) {
+		cachedCapabilities = detectCapabilities();
+	}
+	return cachedCapabilities;
+}
+
+export function resetCapabilitiesCache(): void {
+	cachedCapabilities = null;
+}
+
+const KITTY_PREFIX = "\x1b_G";
+const ITERM2_PREFIX = "\x1b]1337;File=";
+
+export function isImageLine(line: string): boolean {
+	// Fast path: sequence at line start (single-row images)
+	if (line.startsWith(KITTY_PREFIX) || line.startsWith(ITERM2_PREFIX)) {
+		return true;
+	}
+	// Slow path: sequence elsewhere (multi-row images have cursor-up prefix)
+	return line.includes(KITTY_PREFIX) || line.includes(ITERM2_PREFIX);
+}
+
+/**
+ * Generate a random image ID for Kitty graphics protocol.
+ * Uses random IDs to avoid collisions between different module instances
+ * (e.g., main app vs extensions).
+ */
+export function allocateImageId(): number {
+	// Use random ID in range [1, 0xffffffff] to avoid collisions
+	return Math.floor(Math.random() * 0xfffffffe) + 1;
+}
+
+export function encodeKitty(
+	base64Data: string,
+	options: {
+		columns?: number;
+		rows?: number;
+		imageId?: number;
+	} = {}
+): string {
+	const CHUNK_SIZE = 4096;
+
+	const params: string[] = ["a=T", "f=100", "q=2"];
+
+	if (options.columns) params.push(`c=${options.columns}`);
+	if (options.rows) params.push(`r=${options.rows}`);
+	if (options.imageId) params.push(`i=${options.imageId}`);
+
+	if (base64Data.length <= CHUNK_SIZE) {
+		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
+	}
+
+	const chunks: string[] = [];
+	let offset = 0;
+	let isFirst = true;
+
+	while (offset < base64Data.length) {
+		const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
+		const isLast = offset + CHUNK_SIZE >= base64Data.length;
+
+		if (isFirst) {
+			chunks.push(`\x1b_G${params.join(",")},m=1;${chunk}\x1b\\`);
+			isFirst = false;
+		} else if (isLast) {
+			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
+		} else {
+			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
+		}
+
+		offset += CHUNK_SIZE;
+	}
+
+	return chunks.join("");
+}
+
+/**
+ * Delete a Kitty graphics image by ID.
+ * Uses uppercase 'I' to also free the image data.
+ */
+export function deleteKittyImage(imageId: number): string {
+	return `\x1b_Ga=d,d=I,i=${imageId}\x1b\\`;
+}
+
+/**
+ * Delete all visible Kitty graphics images.
+ * Uses uppercase 'A' to also free the image data.
+ */
+export function deleteAllKittyImages(): string {
+	return `\x1b_Ga=d,d=A\x1b\\`;
+}
+
+export function encodeITerm2(
+	base64Data: string,
+	options: {
+		width?: number | string;
+		height?: number | string;
+		name?: string;
+		preserveAspectRatio?: boolean;
+		inline?: boolean;
+	} = {}
+): string {
+	const params: string[] = [`inline=${options.inline !== false ? 1 : 0}`];
+
+	if (options.width !== undefined) params.push(`width=${options.width}`);
+	if (options.height !== undefined) params.push(`height=${options.height}`);
+	if (options.name) {
+		const nameBase64 = Buffer.from(options.name).toString("base64");
+		params.push(`name=${nameBase64}`);
+	}
+	if (options.preserveAspectRatio === false) {
+		params.push("preserveAspectRatio=0");
+	}
+
+	return `\x1b]1337;File=${params.join(";")}:${base64Data}\x07`;
+}
+
+/** Layout dimensions for a rendered image in terminal cells. */
+export interface ImageLayout {
+	/** Number of terminal rows the image occupies. */
+	rows: number;
+	/** Number of terminal columns the image occupies. */
+	columns: number;
+}
+
+/**
+ * Pick the closest valid integer terminal cell count for a fractional target.
+ *
+ * @param target - Ideal (fractional) cell count
+ * @param min - Minimum allowed cell count (inclusive)
+ * @param max - Maximum allowed cell count (inclusive)
+ * @returns Closest in-range integer cell count
+ */
+function closestCellCount(target: number, min: number, max: number): number {
+	const lower = Math.max(min, Math.min(max, Math.floor(target)));
+	const upper = Math.max(min, Math.min(max, Math.ceil(target)));
+	if (lower === upper) {
+		return lower;
+	}
+	return Math.abs(target - upper) < Math.abs(target - lower) ? upper : lower;
+}
+
+/**
+ * Calculate the cell layout for an image at a given max width.
+ * Clamps to the image's natural pixel width (prevents upscaling),
+ * then optionally clamps height and back-calculates width to preserve aspect ratio.
+ *
+ * Uses nearest-integer quantization instead of always rounding up to reduce
+ * narrow-width aspect distortion.
+ *
+ * @param imageDimensions - Native pixel dimensions of the image
+ * @param maxWidthCells - Maximum column count for the image
+ * @param cellDims - Terminal cell pixel dimensions
+ * @param maxHeightCells - Optional row cap (portrait images)
+ * @returns Layout with rows and columns the image will occupy
+ */
+export function calculateImageLayout(
+	imageDimensions: ImageDimensions,
+	maxWidthCells: number,
+	cellDims: CellDimensions = { widthPx: 9, heightPx: 18 },
+	maxHeightCells?: number
+): ImageLayout {
+	const safeImageWidthPx = Math.max(1, imageDimensions.widthPx);
+	const safeImageHeightPx = Math.max(1, imageDimensions.heightPx);
+	const safeCellWidthPx = Math.max(1, cellDims.widthPx);
+	const safeCellHeightPx = Math.max(1, cellDims.heightPx);
+	const safeMaxWidthCells = Math.max(1, Math.floor(maxWidthCells));
+	const safeMaxHeightCells =
+		maxHeightCells === undefined ? undefined : Math.max(1, Math.floor(maxHeightCells));
+
+	// Clamp to natural width — prevents upscaling small images.
+	const naturalCols = Math.max(1, Math.ceil(safeImageWidthPx / safeCellWidthPx));
+	const maxColumns = Math.min(safeMaxWidthCells, naturalCols);
+	let columns = maxColumns;
+
+	const idealRows =
+		(columns * safeCellWidthPx * safeImageHeightPx) / (safeImageWidthPx * safeCellHeightPx);
+	let rows = closestCellCount(idealRows, 1, Number.MAX_SAFE_INTEGER);
+
+	// When height-clamped, reduce columns proportionally to preserve aspect ratio.
+	// Without this, the terminal receives a wide column count but the text layer
+	// only reserves maxHeightCells rows, causing the image to overflow or squish.
+	if (safeMaxHeightCells !== undefined && rows > safeMaxHeightCells) {
+		rows = safeMaxHeightCells;
+		const idealColumns =
+			(rows * safeCellHeightPx * safeImageWidthPx) / (safeImageHeightPx * safeCellWidthPx);
+		columns = closestCellCount(idealColumns, 1, maxColumns);
+	}
+
+	return { columns: Math.max(1, columns), rows: Math.max(1, rows) };
+}
+
+export function getPngDimensions(base64Data: string): ImageDimensions | null {
+	try {
+		const buffer = Buffer.from(base64Data, "base64");
+
+		if (buffer.length < 24) {
+			return null;
+		}
+
+		if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {
+			return null;
+		}
+
+		const width = buffer.readUInt32BE(16);
+		const height = buffer.readUInt32BE(20);
+
+		return { widthPx: width, heightPx: height };
+	} catch {
+		return null;
+	}
+}
+
+export function getJpegDimensions(base64Data: string): ImageDimensions | null {
+	try {
+		const buffer = Buffer.from(base64Data, "base64");
+
+		if (buffer.length < 2) {
+			return null;
+		}
+
+		if (buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+			return null;
+		}
+
+		let offset = 2;
+		while (offset < buffer.length - 9) {
+			if (buffer[offset] !== 0xff) {
+				offset++;
+				continue;
+			}
+
+			const marker = buffer[offset + 1];
+
+			if (marker >= 0xc0 && marker <= 0xc2) {
+				const height = buffer.readUInt16BE(offset + 5);
+				const width = buffer.readUInt16BE(offset + 7);
+				return { widthPx: width, heightPx: height };
+			}
+
+			if (offset + 3 >= buffer.length) {
+				return null;
+			}
+			const length = buffer.readUInt16BE(offset + 2);
+			if (length < 2) {
+				return null;
+			}
+			offset += 2 + length;
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export function getGifDimensions(base64Data: string): ImageDimensions | null {
+	try {
+		const buffer = Buffer.from(base64Data, "base64");
+
+		if (buffer.length < 10) {
+			return null;
+		}
+
+		const sig = buffer.slice(0, 6).toString("ascii");
+		if (sig !== "GIF87a" && sig !== "GIF89a") {
+			return null;
+		}
+
+		const width = buffer.readUInt16LE(6);
+		const height = buffer.readUInt16LE(8);
+
+		return { widthPx: width, heightPx: height };
+	} catch {
+		return null;
+	}
+}
+
+export function getWebpDimensions(base64Data: string): ImageDimensions | null {
+	try {
+		const buffer = Buffer.from(base64Data, "base64");
+
+		if (buffer.length < 30) {
+			return null;
+		}
+
+		const riff = buffer.slice(0, 4).toString("ascii");
+		const webp = buffer.slice(8, 12).toString("ascii");
+		if (riff !== "RIFF" || webp !== "WEBP") {
+			return null;
+		}
+
+		const chunk = buffer.slice(12, 16).toString("ascii");
+		if (chunk === "VP8 ") {
+			if (buffer.length < 30) return null;
+			const width = buffer.readUInt16LE(26) & 0x3fff;
+			const height = buffer.readUInt16LE(28) & 0x3fff;
+			return { widthPx: width, heightPx: height };
+		} else if (chunk === "VP8L") {
+			if (buffer.length < 25) return null;
+			const bits = buffer.readUInt32LE(21);
+			const width = (bits & 0x3fff) + 1;
+			const height = ((bits >> 14) & 0x3fff) + 1;
+			return { widthPx: width, heightPx: height };
+		} else if (chunk === "VP8X") {
+			if (buffer.length < 30) return null;
+			const width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;
+			const height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;
+			return { widthPx: width, heightPx: height };
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/** Supported image format identifiers returned by `detectImageFormat`. */
+export type ImageFormat = "png" | "jpeg" | "gif" | "webp";
+
+/**
+ * Detect image format from file header bytes (magic numbers).
+ *
+ * Checks the first few bytes of a buffer for known image signatures:
+ * - PNG: `89 50 4E 47 0D 0A 1A 0A` (8 bytes)
+ * - JPEG: `FF D8 FF` (3 bytes)
+ * - GIF: `47 49 46 38` + `37`/`39` + `61` (GIF87a / GIF89a)
+ * - WebP: `52 49 46 46 ... 57 45 42 50` (RIFF at 0-3, WEBP at 8-11)
+ *
+ * @param buffer - Raw file bytes (only first 12 bytes are inspected)
+ * @returns Detected format string, or null if not a recognized image
+ */
+export function detectImageFormat(buffer: Buffer): ImageFormat | null {
+	if (buffer.length < 3) return null;
+
+	// PNG: 89 50 4E 47 0D 0A 1A 0A
+	if (
+		buffer.length >= 8 &&
+		buffer[0] === 0x89 &&
+		buffer[1] === 0x50 &&
+		buffer[2] === 0x4e &&
+		buffer[3] === 0x47 &&
+		buffer[4] === 0x0d &&
+		buffer[5] === 0x0a &&
+		buffer[6] === 0x1a &&
+		buffer[7] === 0x0a
+	) {
+		return "png";
+	}
+
+	// JPEG: FF D8 FF
+	if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+		return "jpeg";
+	}
+
+	// GIF: 47 49 46 38 (37|39) 61
+	if (
+		buffer.length >= 6 &&
+		buffer[0] === 0x47 &&
+		buffer[1] === 0x49 &&
+		buffer[2] === 0x46 &&
+		buffer[3] === 0x38 &&
+		(buffer[4] === 0x37 || buffer[4] === 0x39) &&
+		buffer[5] === 0x61
+	) {
+		return "gif";
+	}
+
+	// WebP: RIFF....WEBP (bytes 0-3 = "RIFF", bytes 8-11 = "WEBP")
+	if (
+		buffer.length >= 12 &&
+		buffer[0] === 0x52 &&
+		buffer[1] === 0x49 &&
+		buffer[2] === 0x46 &&
+		buffer[3] === 0x46 &&
+		buffer[8] === 0x57 &&
+		buffer[9] === 0x45 &&
+		buffer[10] === 0x42 &&
+		buffer[11] === 0x50
+	) {
+		return "webp";
+	}
+
+	return null;
+}
+
+/**
+ * Map an `ImageFormat` to its standard MIME type string.
+ *
+ * @param format - Detected image format
+ * @returns MIME type (e.g., `"image/png"`)
+ */
+export function imageFormatToMime(format: ImageFormat): string {
+	switch (format) {
+		case "png":
+			return "image/png";
+		case "jpeg":
+			return "image/jpeg";
+		case "gif":
+			return "image/gif";
+		case "webp":
+			return "image/webp";
+	}
+}
+
+/** Metadata about an image's original and display dimensions after processing. */
+export interface ImageMetadata {
+	/** Original pixel width before any resizing. */
+	readonly originalWidth: number;
+	/** Original pixel height before any resizing. */
+	readonly originalHeight: number;
+	/** Display pixel width after resizing (equals original if not resized). */
+	readonly displayWidth: number;
+	/** Display pixel height after resizing (equals original if not resized). */
+	readonly displayHeight: number;
+	/** Whether the image was resized from its original dimensions. */
+	readonly resized: boolean;
+	/** Detected image format (e.g., "png", "jpeg"). */
+	readonly format: ImageFormat | null;
+	/** File size in bytes, if known. */
+	readonly sizeBytes?: number;
+}
+
+/**
+ * Create an `ImageMetadata` object from original and display dimensions.
+ *
+ * Sets `resized` automatically by comparing original and display dimensions.
+ *
+ * @param original - Original pixel dimensions before resizing
+ * @param display - Display pixel dimensions after resizing
+ * @param format - Detected image format, or null if unknown
+ * @param sizeBytes - File size in bytes (optional)
+ * @returns Populated ImageMetadata
+ */
+export function createImageMetadata(
+	original: ImageDimensions,
+	display: ImageDimensions,
+	format: ImageFormat | null,
+	sizeBytes?: number
+): ImageMetadata {
+	return {
+		originalWidth: original.widthPx,
+		originalHeight: original.heightPx,
+		displayWidth: display.widthPx,
+		displayHeight: display.heightPx,
+		resized: original.widthPx !== display.widthPx || original.heightPx !== display.heightPx,
+		format,
+		sizeBytes,
+	};
+}
+
+/**
+ * Format a compact dimension string for display.
+ *
+ * - Not resized: `"1920×1080"`
+ * - Resized: `"3840×2160 → 1920×1080"`
+ *
+ * @param meta - Image metadata with dimension info
+ * @returns Formatted dimension string
+ */
+export function formatImageDimensions(meta: ImageMetadata): string {
+	if (meta.resized) {
+		return `${meta.originalWidth}×${meta.originalHeight} → ${meta.displayWidth}×${meta.displayHeight}`;
+	}
+	return `${meta.originalWidth}×${meta.originalHeight}`;
+}
+
+export function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null {
+	if (mimeType === "image/png") {
+		return getPngDimensions(base64Data);
+	}
+	if (mimeType === "image/jpeg") {
+		return getJpegDimensions(base64Data);
+	}
+	if (mimeType === "image/gif") {
+		return getGifDimensions(base64Data);
+	}
+	if (mimeType === "image/webp") {
+		return getWebpDimensions(base64Data);
+	}
+	return null;
+}
+
+/**
+ * Render an image as a terminal escape sequence (Kitty or iTerm2 protocol).
+ * Returns the escape sequence, the number of rows/columns it occupies, and
+ * an optional Kitty image ID for later cleanup.
+ *
+ * @param base64Data - Base64-encoded image data
+ * @param imageDimensions - Native pixel dimensions
+ * @param options - Width/height caps, aspect ratio, image ID
+ * @returns Rendered sequence with layout info, or null if unsupported
+ */
+export function renderImage(
+	base64Data: string,
+	imageDimensions: ImageDimensions,
+	options: ImageRenderOptions = {}
+): { sequence: string; rows: number; columns: number; imageId?: number } | null {
+	const caps = getCapabilities();
+
+	if (!caps.images) {
+		return null;
+	}
+
+	const maxWidth = options.maxWidthCells ?? 80;
+	const layout = calculateImageLayout(
+		imageDimensions,
+		maxWidth,
+		getCellDimensions(),
+		options.maxHeightCells
+	);
+
+	if (caps.images === "kitty") {
+		// Omit rows — let Kitty auto-calculate from the image's native aspect ratio.
+		// This avoids rounding errors in our row calculation that cause subtle stretching.
+		const sequence = encodeKitty(base64Data, {
+			columns: layout.columns,
+			imageId: options.imageId,
+		});
+		return { sequence, rows: layout.rows, columns: layout.columns, imageId: options.imageId };
+	}
+
+	if (caps.images === "iterm2") {
+		const sequence = encodeITerm2(base64Data, {
+			width: layout.columns,
+			height: "auto",
+			preserveAspectRatio: options.preserveAspectRatio ?? true,
+		});
+		return { sequence, rows: layout.rows, columns: layout.columns };
+	}
+
+	return null;
+}
+
+export function imageFallback(
+	mimeType: string,
+	dimensions?: ImageDimensions,
+	filename?: string
+): string {
+	const parts: string[] = [];
+	if (filename) parts.push(filename);
+	parts.push(`[${mimeType}]`);
+	if (dimensions) parts.push(`${dimensions.widthPx}x${dimensions.heightPx}`);
+	return `[Image: ${parts.join(" ")}]`;
+}