@f5-sales-demo/xcsh 19.51.2

package/src/utils/gitstatus.ts

@@ -0,0 +1,140 @@
+/**
+ * High-performance git status via gitstatusd daemon.
+ *
+ * gitstatusd is a C binary that provides git status 10x faster than
+ * `git status --porcelain` by caching dirty file state in memory.
+ * Protocol: named pipes with \x1f field separators and \x1e record terminators.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { logger } from "@f5xc-salesdemos/pi-utils";
+
+export interface GitStatusResult {
+	workdir: string;
+	commit: string;
+	localBranch: string;
+	remoteBranch: string;
+	remoteName: string;
+	remoteUrl: string;
+	action: string;
+	indexSize: number;
+	staged: number;
+	unstaged: number;
+	conflicted: number;
+	untracked: number;
+	ahead: number;
+	behind: number;
+	stashes: number;
+	tag: string;
+	commitSummary: string;
+}
+
+const FIELD_SEP = "\x1f";
+const RECORD_SEP = "\x1e";
+
+let daemon: { proc: ReturnType<typeof Bun.spawn>; requestId: number } | null = null;
+let startAttempted = false;
+
+function findGitstatusd(): string | null {
+	const cacheDir = path.join(os.homedir(), ".cache", "gitstatus");
+	const arch = process.arch === "arm64" ? "aarch64" : "x86_64";
+	const platform = process.platform === "darwin" ? "darwin" : "linux";
+	const binary = path.join(cacheDir, `gitstatusd-${platform}-${arch}`);
+	if (fs.existsSync(binary)) return binary;
+
+	// Fallback: search PATH
+	const result = Bun.spawnSync(["which", "gitstatusd"], { stdout: "pipe" });
+	if (result.exitCode === 0) return result.stdout.toString().trim();
+
+	return null;
+}
+
+function startDaemon(): boolean {
+	if (daemon) return true;
+	if (startAttempted) return false;
+	startAttempted = true;
+
+	const binary = findGitstatusd();
+	if (!binary) {
+		logger.debug("gitstatusd not found, falling back to git CLI");
+		return false;
+	}
+
+	try {
+		const proc = Bun.spawn(
+			[binary, "-G", "v1.5.4", "-s", "-1", "-u", "-1", "-d", "-1", "-c", "-1", "-m", "-1", "-v", "FATAL", "-t", "4"],
+			{ stdin: "pipe", stdout: "pipe", stderr: "ignore" },
+		);
+
+		daemon = { proc, requestId: 0 };
+
+		proc.exited.then(() => {
+			daemon = null;
+		});
+
+		return true;
+	} catch (err) {
+		logger.debug("Failed to start gitstatusd", { error: err instanceof Error ? err.message : String(err) });
+		return false;
+	}
+}
+
+export async function queryGitStatus(directory: string, timeoutMs = 3000): Promise<GitStatusResult | null> {
+	if (!startDaemon()) return null;
+	if (!daemon) return null;
+
+	const reqId = String(++daemon.requestId);
+	const request = `${reqId}${FIELD_SEP}${directory}${RECORD_SEP}`;
+
+	try {
+		const stdin = daemon.proc.stdin as { write(data: string): void; flush(): void };
+		stdin.write(request);
+		stdin.flush();
+
+		const reader = (daemon.proc.stdout as ReadableStream<Uint8Array>).getReader();
+		const timeoutPromise = new Promise<null>(resolve => setTimeout(() => resolve(null), timeoutMs));
+		const readPromise = reader.read().then(({ value }) => (value ? new TextDecoder().decode(value) : null));
+
+		const response = await Promise.race([readPromise, timeoutPromise]);
+		reader.releaseLock();
+
+		if (!response) return null;
+
+		const raw = response.replace(RECORD_SEP, "");
+		const fields = raw.split(FIELD_SEP);
+
+		if (fields.length < 20 || fields[0] !== reqId || fields[1] !== "1") {
+			return null;
+		}
+
+		return {
+			workdir: fields[2] || "",
+			commit: fields[3] || "",
+			localBranch: fields[4] || "",
+			remoteBranch: fields[5] || "",
+			remoteName: fields[6] || "",
+			remoteUrl: fields[7] || "",
+			action: fields[8] || "",
+			indexSize: parseInt(fields[9] || "0", 10),
+			staged: parseInt(fields[10] || "0", 10),
+			unstaged: parseInt(fields[11] || "0", 10),
+			conflicted: parseInt(fields[12] || "0", 10),
+			untracked: parseInt(fields[13] || "0", 10),
+			ahead: parseInt(fields[14] || "0", 10),
+			behind: parseInt(fields[15] || "0", 10),
+			stashes: parseInt(fields[16] || "0", 10),
+			tag: fields[17] || "",
+			commitSummary: fields[27] || "",
+		};
+	} catch {
+		return null;
+	}
+}
+
+export function stopDaemon(): void {
+	if (daemon) {
+		daemon.proc.kill();
+		daemon = null;
+	}
+}

package/src/utils/image-convert.ts

@@ -0,0 +1,27 @@
+import { ImageFormat, PhotonImage } from "@f5xc-salesdemos/pi-natives";
+
+/**
+ * Convert image to PNG format for terminal display.
+ * Kitty graphics protocol requires PNG format (f=100).
+ */
+export async function convertToPng(
+	base64Data: string,
+	mimeType: string,
+): Promise<{ data: string; mimeType: string } | null> {
+	// Already PNG, no conversion needed
+	if (mimeType === "image/png") {
+		return { data: base64Data, mimeType };
+	}
+
+	try {
+		const image = await PhotonImage.parse(new Uint8Array(Buffer.from(base64Data, "base64")));
+		const pngBuffer = await image.encode(ImageFormat.PNG, 100);
+		return {
+			data: Buffer.from(pngBuffer).toBase64(),
+			mimeType: "image/png",
+		};
+	} catch {
+		// Conversion failed
+		return null;
+	}
+}

package/src/utils/image-loading.ts

@@ -0,0 +1,98 @@
+import * as fs from "node:fs/promises";
+import type { ImageContent } from "@f5xc-salesdemos/pi-ai";
+import { formatBytes, readImageMetadata, SUPPORTED_IMAGE_MIME_TYPES } from "@f5xc-salesdemos/pi-utils";
+import { resolveReadPath } from "../tools/path-utils";
+import { convertToPng } from "./image-convert";
+import { formatDimensionNote, resizeImage } from "./image-resize";
+
+export const MAX_IMAGE_INPUT_BYTES = 20 * 1024 * 1024;
+export const SUPPORTED_INPUT_IMAGE_MIME_TYPES = SUPPORTED_IMAGE_MIME_TYPES;
+
+export interface LoadImageInputOptions {
+	path: string;
+	cwd: string;
+	autoResize: boolean;
+	maxBytes?: number;
+	resolvedPath?: string;
+	detectedMimeType?: string;
+}
+
+export interface LoadedImageInput {
+	resolvedPath: string;
+	mimeType: string;
+	data: string;
+	textNote: string;
+	dimensionNote?: string;
+	bytes: number;
+}
+
+export class ImageInputTooLargeError extends Error {
+	readonly bytes: number;
+	readonly maxBytes: number;
+
+	constructor(bytes: number, maxBytes: number) {
+		super(`Image file too large: ${formatBytes(bytes)} exceeds ${formatBytes(maxBytes)} limit.`);
+		this.name = "ImageInputTooLargeError";
+		this.bytes = bytes;
+		this.maxBytes = maxBytes;
+	}
+}
+
+export async function ensureSupportedImageInput(image: ImageContent): Promise<ImageContent | null> {
+	if (SUPPORTED_INPUT_IMAGE_MIME_TYPES.has(image.mimeType)) {
+		return image;
+	}
+	const converted = await convertToPng(image.data, image.mimeType);
+	return converted ? { type: "image", data: converted.data, mimeType: converted.mimeType } : null;
+}
+
+export async function loadImageInput(options: LoadImageInputOptions): Promise<LoadedImageInput | null> {
+	const maxBytes = options.maxBytes ?? MAX_IMAGE_INPUT_BYTES;
+	const resolvedPath = options.resolvedPath ?? resolveReadPath(options.path, options.cwd);
+	const metadata = options.detectedMimeType
+		? { mimeType: options.detectedMimeType }
+		: await readImageMetadata(resolvedPath);
+	const mimeType = metadata?.mimeType;
+	if (!mimeType) return null;
+
+	const stat = await Bun.file(resolvedPath).stat();
+	if (stat.size > maxBytes) {
+		throw new ImageInputTooLargeError(stat.size, maxBytes);
+	}
+
+	const inputBuffer = await fs.readFile(resolvedPath);
+	if (inputBuffer.byteLength > maxBytes) {
+		throw new ImageInputTooLargeError(inputBuffer.byteLength, maxBytes);
+	}
+
+	let outputData = Buffer.from(inputBuffer).toBase64();
+	let outputMimeType = mimeType;
+	let outputBytes = inputBuffer.byteLength;
+	let dimensionNote: string | undefined;
+
+	if (options.autoResize) {
+		try {
+			const resized = await resizeImage({ type: "image", data: outputData, mimeType });
+			outputData = resized.data;
+			outputMimeType = resized.mimeType;
+			outputBytes = resized.buffer.byteLength;
+			dimensionNote = formatDimensionNote(resized);
+		} catch {
+			// keep original image when resize fails
+		}
+	}
+
+	let textNote = `Read image file [${outputMimeType}]`;
+	if (dimensionNote) {
+		textNote += `\n${dimensionNote}`;
+	}
+
+	return {
+		resolvedPath,
+		mimeType: outputMimeType,
+		data: outputData,
+		textNote,
+		dimensionNote,
+		bytes: outputBytes,
+	};
+}

package/src/utils/image-passthrough.ts

@@ -0,0 +1,118 @@
+import { TERMINAL } from "@f5xc-salesdemos/pi-tui/terminal-capabilities";
+
+// -- Start sequence detection regexes --
+
+const SIXEL_START_REGEX = /\x1bP(?:[0-9;]*)q/u;
+// Match all iTerm2 image sequences: File=, MultipartFile=, FilePart=, FileEnd
+const ITERM2_START_REGEX = /\x1b\]1337;(?:File=|MultipartFile=|FilePart=|FileEnd)/u;
+const KITTY_START_REGEX = /\x1b_G/u;
+
+// -- Full sequence matching regexes (for placeholder/restore) --
+
+const SIXEL_SEQUENCE_REGEX = /\x1bP(?:[0-9;]*)q[\s\S]*?(?:\x1b\\|\x07)/gu;
+// Match all iTerm2 image OSC sequences through their terminator (BEL or ST).
+// Covers File= (inline), MultipartFile= (multipart start), FilePart= (chunks), FileEnd.
+const ITERM2_SEQUENCE_REGEX = /\x1b\]1337;(?:File=|MultipartFile=|FilePart=|FileEnd)[\s\S]*?(?:\x07|\x1b\\)/gu;
+const KITTY_SEQUENCE_REGEX = /\x1b_G[^\x1b]*\x1b\\/gu;
+
+const SIXEL_END_SEQUENCE = "\x1b\\";
+const SIXEL_END_BELL = "\x07";
+
+const PLACEHOLDER_PREFIX = "__OMP_IMAGE_SEQUENCE_";
+
+export function isImagePassthroughEnabled(): boolean {
+	return TERMINAL.imageProtocol !== null;
+}
+
+export function containsImageSequence(text: string): boolean {
+	return SIXEL_START_REGEX.test(text) || ITERM2_START_REGEX.test(text) || KITTY_START_REGEX.test(text);
+}
+
+export function isImageLine(line: string): boolean {
+	return containsImageSequence(line);
+}
+
+export function getImageLineMask(lines: string[]): boolean[] {
+	let inSixelSequence = false;
+	return lines.map(line => {
+		const hasSixelStart = SIXEL_START_REGEX.test(line);
+		const hasIterm2 = ITERM2_START_REGEX.test(line);
+		const hasKitty = KITTY_START_REGEX.test(line);
+
+		if (hasSixelStart) {
+			inSixelSequence = true;
+		}
+
+		const isImage = inSixelSequence || hasIterm2 || hasKitty;
+
+		if (inSixelSequence && (line.includes(SIXEL_END_SEQUENCE) || line.includes(SIXEL_END_BELL))) {
+			inSixelSequence = false;
+		}
+
+		return isImage;
+	});
+}
+
+/**
+ * Extracts base64 image data from iTerm2 multipart sequences in raw output.
+ * Returns the reassembled base64 string and detected mime type, or null
+ * if no multipart image is found.
+ */
+export function extractITerm2ImageData(text: string): { base64: string; mimeType: string } | null {
+	if (!ITERM2_START_REGEX.test(text)) return null;
+
+	// Check for single-part File= first
+	const singleMatch = text.match(/\x1b\]1337;File=([^:]*):([A-Za-z0-9+/=\s]+)(?:\x07|\x1b\\)/u);
+	if (singleMatch) {
+		const base64 = singleMatch[2].replace(/\s/g, "");
+		const mimeType = detectMimeFromBase64(base64);
+		return { base64, mimeType };
+	}
+
+	// Reassemble multipart: collect all FilePart payloads in order
+	const partRegex = /\x1b\]1337;FilePart=([A-Za-z0-9+/=\s]+)(?:\x07|\x1b\\)/gu;
+	const parts: string[] = [];
+	for (;;) {
+		const match = partRegex.exec(text);
+		if (!match) break;
+		parts.push(match[1].replace(/\s/g, ""));
+	}
+
+	if (parts.length === 0) return null;
+
+	const base64 = parts.join("");
+	const mimeType = detectMimeFromBase64(base64);
+	return { base64, mimeType };
+}
+
+function detectMimeFromBase64(base64: string): string {
+	const header = base64.slice(0, 12);
+	if (header.startsWith("iVBOR")) return "image/png";
+	if (header.startsWith("/9j/")) return "image/jpeg";
+	if (header.startsWith("R0lGO")) return "image/gif";
+	if (header.startsWith("UklGR")) return "image/webp";
+	return "image/png";
+}
+
+export function sanitizeWithImagePassthrough(text: string, sanitize: (text: string) => string): string {
+	if (!isImagePassthroughEnabled() || !containsImageSequence(text)) {
+		return sanitize(text);
+	}
+
+	const preservedSequences: string[] = [];
+
+	let tokenized = text;
+	for (const regex of [SIXEL_SEQUENCE_REGEX, ITERM2_SEQUENCE_REGEX, KITTY_SEQUENCE_REGEX]) {
+		tokenized = tokenized.replace(regex, match => {
+			const token = `${PLACEHOLDER_PREFIX}${preservedSequences.length}__`;
+			preservedSequences.push(match);
+			return token;
+		});
+	}
+
+	const sanitized = sanitize(tokenized);
+	return sanitized.replace(/__OMP_IMAGE_SEQUENCE_(\d+)__/gu, (_, indexText: string) => {
+		const index = Number.parseInt(indexText, 10);
+		return preservedSequences[index] ?? "";
+	});
+}

package/src/utils/image-resize.ts

@@ -0,0 +1,272 @@
+import type { ImageContent } from "@f5xc-salesdemos/pi-ai";
+import { ImageFormat, PhotonImage, SamplingFilter } from "@f5xc-salesdemos/pi-natives";
+
+export interface ImageResizeOptions {
+	maxWidth?: number; // Default: 1568
+	maxHeight?: number; // Default: 1568
+	maxBytes?: number; // Default: 500KB
+	jpegQuality?: number; // Default: 75
+}
+
+export interface ResizedImage {
+	buffer: Uint8Array;
+	mimeType: string;
+	originalWidth: number;
+	originalHeight: number;
+	width: number;
+	height: number;
+	wasResized: boolean;
+	get data(): string;
+}
+
+// 500KB target — aggressive compression; Anthropic's 5MB per-image cap is rarely the
+// binding constraint once images are downsized to 1568px (Anthropic's internal threshold).
+const DEFAULT_MAX_BYTES = 500 * 1024;
+
+const DEFAULT_OPTIONS: Required<ImageResizeOptions> = {
+	// 1568px — Anthropic downscales anything larger; OpenAI tiles at 768px;
+	// sending bigger pixels wastes bandwidth the model never sees.
+	maxWidth: 1568,
+	maxHeight: 1568,
+	maxBytes: DEFAULT_MAX_BYTES,
+	jpegQuality: 75,
+};
+
+/** Pick the smallest of N encoded buffers. */
+function pickSmallest(...candidates: Array<{ buffer: Uint8Array; mimeType: string }>): {
+	buffer: Uint8Array;
+	mimeType: string;
+} {
+	return candidates.reduce((best, c) => (c.buffer.length < best.buffer.length ? c : best));
+}
+
+/** Polyfill for Buffer.toBase64, technically since it derives from Uint8Array it should exist but Bun reasons... */
+Buffer.prototype.toBase64 = function (this: Buffer) {
+	return new Uint8Array(this.buffer, this.byteOffset, this.byteLength).toBase64();
+};
+
+/**
+ * Resize and recompress an image to fit within the specified max dimensions and file size.
+ *
+ * Defaults target Anthropic's internal 1568px downscale threshold and produce small
+ * lossy JPEG output suitable for tool-call payloads (~100–500KB typical).
+ *
+ * Strategy:
+ * 1. Fast path — if input already fits dimensions AND is at <=25% of byte budget,
+ *    return as-is. Avoids re-encoding tiny icons/diagrams.
+ * 2. Resize to maxWidth/maxHeight, encode both PNG and JPEG at default quality,
+ *    pick whichever is smaller. PNG wins for line art / few-color UI; JPEG wins
+ *    for photographic content.
+ * 3. If still too large, JPEG-only quality ladder (PNG quality is a no-op).
+ * 4. If still too large, progressively reduce dimensions and retry the JPEG ladder.
+ * 5. Last resort: ship the smallest variant produced.
+ *
+ * On any decode failure, returns the original bytes unchanged with wasResized=false.
+ */
+export async function resizeImage(img: ImageContent, options?: ImageResizeOptions): Promise<ResizedImage> {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const inputBuffer = Buffer.from(img.data, "base64");
+
+	try {
+		const image = await PhotonImage.parse(inputBuffer);
+
+		const originalWidth = image.width;
+		const originalHeight = image.height;
+		const format = img.mimeType?.split("/")[1] ?? "png";
+
+		// Check if already within all limits (dimensions AND size)
+		const originalSize = inputBuffer.length;
+		// Fast path: skip if already within dimensions AND well under budget.
+		// Threshold is 1/4 of budget — if already that compact, don't re-encode.
+		// Avoids wasted work on tiny icons/diagrams while ensuring larger PNGs
+		// still get JPEG-compressed.
+		const comfortableSize = opts.maxBytes / 4;
+		if (originalWidth <= opts.maxWidth && originalHeight <= opts.maxHeight && originalSize <= comfortableSize) {
+			return {
+				buffer: inputBuffer,
+				mimeType: img.mimeType ?? `image/${format}`,
+				originalWidth,
+				originalHeight,
+				width: originalWidth,
+				height: originalHeight,
+				wasResized: false,
+				get data() {
+					return img.data;
+				},
+			};
+		}
+
+		// Calculate initial dimensions respecting max limits
+		let targetWidth = originalWidth;
+		let targetHeight = originalHeight;
+
+		if (targetWidth > opts.maxWidth) {
+			targetHeight = Math.round((targetHeight * opts.maxWidth) / targetWidth);
+			targetWidth = opts.maxWidth;
+		}
+		if (targetHeight > opts.maxHeight) {
+			targetWidth = Math.round((targetWidth * opts.maxHeight) / targetHeight);
+			targetHeight = opts.maxHeight;
+		}
+
+		// First-attempt encoder: try PNG, JPEG, and lossy WebP — return whichever is smallest.
+		// PNG wins for line art / few-color UI; JPEG and WebP win for photographic content;
+		// WebP usually beats JPEG by 25–35% at the same perceptual quality.
+		async function encodeSmallest(
+			width: number,
+			height: number,
+			quality: number,
+		): Promise<{ buffer: Uint8Array; mimeType: string }> {
+			const resized = await image.resize(width, height, SamplingFilter.Lanczos3);
+
+			const [pngBuffer, jpegBuffer, webpBuffer] = await Promise.all([
+				resized.encode(ImageFormat.PNG, quality),
+				resized.encode(ImageFormat.JPEG, quality),
+				resized.encode(ImageFormat.WEBP, quality),
+			]);
+
+			return pickSmallest(
+				{ buffer: pngBuffer, mimeType: "image/png" },
+				{ buffer: jpegBuffer, mimeType: "image/jpeg" },
+				{ buffer: webpBuffer, mimeType: "image/webp" },
+			);
+		}
+
+		// Lossy-only encoder — used in quality/dimension fallback ladders where PNG can't shrink
+		// further (PNG quality is a no-op). Picks the smaller of JPEG vs lossy WebP at the
+		// requested quality.
+		async function encodeLossy(
+			width: number,
+			height: number,
+			quality: number,
+		): Promise<{ buffer: Uint8Array; mimeType: string }> {
+			const resized = await image.resize(width, height, SamplingFilter.Lanczos3);
+			const [jpegBuffer, webpBuffer] = await Promise.all([
+				resized.encode(ImageFormat.JPEG, quality),
+				resized.encode(ImageFormat.WEBP, quality),
+			]);
+			return pickSmallest(
+				{ buffer: jpegBuffer, mimeType: "image/jpeg" },
+				{ buffer: webpBuffer, mimeType: "image/webp" },
+			);
+		}
+
+		// Quality ladder — more aggressive steps for tighter budgets
+		const qualitySteps = [70, 60, 50, 40];
+		const scaleSteps = [1.0, 0.75, 0.5, 0.35, 0.25];
+
+		let best: { buffer: Uint8Array; mimeType: string };
+		let finalWidth = targetWidth;
+		let finalHeight = targetHeight;
+
+		// First attempt: resize to target, try both PNG and JPEG, pick smaller
+		best = await encodeSmallest(targetWidth, targetHeight, opts.jpegQuality);
+
+		if (best.buffer.length <= opts.maxBytes) {
+			return {
+				buffer: best.buffer,
+				mimeType: best.mimeType,
+				originalWidth,
+				originalHeight,
+				width: finalWidth,
+				height: finalHeight,
+				wasResized: true,
+				get data() {
+					return Buffer.from(best.buffer).toBase64();
+				},
+			};
+		}
+
+		// Still too large — lossy ladder (JPEG vs WebP, smallest wins) with decreasing quality
+		for (const quality of qualitySteps) {
+			best = await encodeLossy(targetWidth, targetHeight, quality);
+
+			if (best.buffer.length <= opts.maxBytes) {
+				return {
+					buffer: best.buffer,
+					mimeType: best.mimeType,
+					originalWidth,
+					originalHeight,
+					width: finalWidth,
+					height: finalHeight,
+					wasResized: true,
+					get data() {
+						return Buffer.from(best.buffer).toBase64();
+					},
+				};
+			}
+		}
+
+		// Still too large — reduce dimensions progressively with the lossy ladder
+		for (const scale of scaleSteps) {
+			finalWidth = Math.round(targetWidth * scale);
+			finalHeight = Math.round(targetHeight * scale);
+
+			if (finalWidth < 100 || finalHeight < 100) {
+				break;
+			}
+
+			for (const quality of qualitySteps) {
+				best = await encodeLossy(finalWidth, finalHeight, quality);
+
+				if (best.buffer.length <= opts.maxBytes) {
+					return {
+						buffer: best.buffer,
+						mimeType: best.mimeType,
+						originalWidth,
+						originalHeight,
+						width: finalWidth,
+						height: finalHeight,
+						wasResized: true,
+						get data() {
+							return Buffer.from(best.buffer).toBase64();
+						},
+					};
+				}
+			}
+		}
+
+		// Last resort: return smallest version we produced
+		return {
+			buffer: best.buffer,
+			mimeType: best.mimeType,
+			originalWidth,
+			originalHeight,
+			width: finalWidth,
+			height: finalHeight,
+			wasResized: true,
+			get data() {
+				return Buffer.from(best.buffer).toBase64();
+			},
+		};
+	} catch {
+		// Failed to load image
+		return {
+			buffer: inputBuffer,
+			mimeType: img.mimeType,
+			originalWidth: 0,
+			originalHeight: 0,
+			width: 0,
+			height: 0,
+			wasResized: false,
+			get data() {
+				return img.data;
+			},
+		};
+	}
+}
+
+/**
+ * Format a dimension note for resized images.
+ * This helps the model understand the coordinate mapping.
+ */
+export function formatDimensionNote(result: ResizedImage): string | undefined {
+	if (!result.wasResized) {
+		return undefined;
+	}
+
+	const scale = result.originalWidth / result.width;
+	return `[Image: original ${result.originalWidth}x${result.originalHeight}, displayed at ${result.width}x${
+		result.height
+	}. Multiply coordinates by ${scale.toFixed(2)} to map to original image.]`;
+}

package/src/utils/image-viewer.ts

@@ -0,0 +1,17 @@
+/**
+ * Opens an image in the system's default image viewer.
+ * Returns true if the viewer was launched successfully.
+ */
+export async function openImageExternal(path: string): Promise<boolean> {
+	const command = process.platform === "darwin" ? "open" : "xdg-open";
+	try {
+		const proc = Bun.spawn([command, path], {
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		await proc.exited;
+		return proc.exitCode === 0;
+	} catch {
+		return false;
+	}
+}