@fractaal/pi-tui 0.85.3 → 0.86.1

package/dist/terminal-colors.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-colors.js","sourceRoot":"","sources":["../src/terminal-colors.ts"],"names":[],"mappings":"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","sourcesContent":["export interface RgbColor {\n\tr: number;\n\tg: number;\n\tb: number;\n}\n\nexport type TerminalColorScheme = \"dark\" | \"light\";\n\nfunction hexToRgb(hex: string): RgbColor {\n\tconst normalized = hex.startsWith(\"#\") ? hex.slice(1) : hex;\n\tconst r = parseInt(normalized.slice(0, 2), 16);\n\tconst g = parseInt(normalized.slice(2, 4), 16);\n\tconst b = parseInt(normalized.slice(4, 6), 16);\n\treturn { r, g, b };\n}\n\nfunction parseOscHexChannel(channel: string): number | undefined {\n\tif (!/^[0-9a-f]+$/i.test(channel)) {\n\t\treturn undefined;\n\t}\n\tconst max = 16 ** channel.length - 1;\n\tif (max <= 0) {\n\t\treturn undefined;\n\t}\n\treturn Math.round((parseInt(channel, 16) / max) * 255);\n}\n\nconst OSC11_BACKGROUND_COLOR_RESPONSE_PATTERN = /^\\x1b\\]11;([^\\x07\\x1b]*)(?:\\x07|\\x1b\\\\)$/i;\nconst COLOR_SCHEME_REPORT_PATTERN = /^\\x1b\\[\\?997;(1|2)n$/;\n\nexport function isOsc11BackgroundColorResponse(data: string): boolean {\n\treturn OSC11_BACKGROUND_COLOR_RESPONSE_PATTERN.test(data);\n}\n\nexport function parseOsc11BackgroundColor(data: string): RgbColor | undefined {\n\tconst match = data.match(OSC11_BACKGROUND_COLOR_RESPONSE_PATTERN);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\n\tconst value = match[1].trim();\n\tif (value.startsWith(\"#\")) {\n\t\tconst hex = value.slice(1);\n\t\tif (/^[0-9a-f]{6}$/i.test(hex)) {\n\t\t\treturn hexToRgb(value);\n\t\t}\n\t\tif (/^[0-9a-f]{12}$/i.test(hex)) {\n\t\t\tconst r = parseOscHexChannel(hex.slice(0, 4));\n\t\t\tconst g = parseOscHexChannel(hex.slice(4, 8));\n\t\t\tconst b = parseOscHexChannel(hex.slice(8, 12));\n\t\t\treturn r !== undefined && g !== undefined && b !== undefined ? { r, g, b } : undefined;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tconst rgbValue = value.replace(/^rgba?:/i, \"\");\n\tconst [red, green, blue] = rgbValue.split(\"/\");\n\tif (red === undefined || green === undefined || blue === undefined) {\n\t\treturn undefined;\n\t}\n\tconst r = parseOscHexChannel(red);\n\tconst g = parseOscHexChannel(green);\n\tconst b = parseOscHexChannel(blue);\n\treturn r !== undefined && g !== undefined && b !== undefined ? { r, g, b } : undefined;\n}\n\nexport function parseTerminalColorSchemeReport(data: string): TerminalColorScheme | undefined {\n\tconst match = data.match(COLOR_SCHEME_REPORT_PATTERN);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn match[1] === \"2\" ? \"light\" : \"dark\";\n}\n"]}
+{"version":3,"file":"terminal-colors.js","sourceRoot":"","sources":["../src/terminal-colors.ts"],"names":[],"mappings":"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","sourcesContent":["export interface RgbColor {\n\tr: number;\n\tg: number;\n\tb: number;\n}\n\nexport type TerminalColorScheme = \"dark\" | \"light\";\n\n/** Colors the terminal reports for its current theme. */\nexport interface TerminalColors {\n\t/** Default foreground (OSC 10). */\n\tforeground?: RgbColor;\n\t/** Default background (OSC 11). */\n\tbackground?: RgbColor;\n\t/** ANSI colors 0-15 (OSC 4). Only set when the terminal reported all 16. */\n\tpalette?: RgbColor[];\n}\n\nfunction hexToRgb(hex: string): RgbColor {\n\tconst normalized = hex.startsWith(\"#\") ? hex.slice(1) : hex;\n\tconst r = parseInt(normalized.slice(0, 2), 16);\n\tconst g = parseInt(normalized.slice(2, 4), 16);\n\tconst b = parseInt(normalized.slice(4, 6), 16);\n\treturn { r, g, b };\n}\n\nfunction parseOscHexChannel(channel: string): number | undefined {\n\tif (!/^[0-9a-f]+$/i.test(channel)) {\n\t\treturn undefined;\n\t}\n\tconst max = 16 ** channel.length - 1;\n\tif (max <= 0) {\n\t\treturn undefined;\n\t}\n\treturn Math.round((parseInt(channel, 16) / max) * 255);\n}\n\n/** What an OSC color reply reports: the default foreground (OSC 10), background (OSC 11), or a palette index (OSC 4). */\nexport type OscColorTarget = \"foreground\" | \"background\" | number;\n\nconst OSC_COLOR_RESPONSE_PATTERN = /^\\x1b\\](?:(1[01])|4;(\\d{1,3}));([^\\x07\\x1b]*)(?:\\x07|\\x1b\\\\)$/i;\nconst COLOR_SCHEME_REPORT_PATTERN = /^(?:\\x1b\\[\\?997;(1|2)n)+$/;\n\n/**\n * Parse an OSC 10, 11, or 4 color reply. Returns undefined when `data` is not such a reply;\n * `rgb` is undefined when it is a reply with an unparseable color.\n */\nexport function parseOscColorResponse(data: string): { target: OscColorTarget; rgb: RgbColor | undefined } | undefined {\n\tconst match = data.match(OSC_COLOR_RESPONSE_PATTERN);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\tconst target: OscColorTarget =\n\t\tmatch[1] === \"10\" ? \"foreground\" : match[1] === \"11\" ? \"background\" : Number.parseInt(match[2], 10);\n\treturn { target, rgb: parseOscColorValue(match[3]) };\n}\n\nfunction parseOscColorValue(rawValue: string): RgbColor | undefined {\n\tconst value = rawValue.trim();\n\tif (value.startsWith(\"#\")) {\n\t\tconst hex = value.slice(1);\n\t\tif (/^[0-9a-f]{6}$/i.test(hex)) {\n\t\t\treturn hexToRgb(value);\n\t\t}\n\t\tif (/^[0-9a-f]{12}$/i.test(hex)) {\n\t\t\tconst r = parseOscHexChannel(hex.slice(0, 4));\n\t\t\tconst g = parseOscHexChannel(hex.slice(4, 8));\n\t\t\tconst b = parseOscHexChannel(hex.slice(8, 12));\n\t\t\treturn r !== undefined && g !== undefined && b !== undefined ? { r, g, b } : undefined;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tconst rgbValue = value.replace(/^rgba?:/i, \"\");\n\tconst [red, green, blue] = rgbValue.split(\"/\");\n\tif (red === undefined || green === undefined || blue === undefined) {\n\t\treturn undefined;\n\t}\n\tconst r = parseOscHexChannel(red);\n\tconst g = parseOscHexChannel(green);\n\tconst b = parseOscHexChannel(blue);\n\treturn r !== undefined && g !== undefined && b !== undefined ? { r, g, b } : undefined;\n}\n\nexport function parseTerminalColorSchemeReport(data: string): TerminalColorScheme | undefined {\n\tconst match = data.match(COLOR_SCHEME_REPORT_PATTERN);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn match[1] === \"2\" ? \"light\" : \"dark\";\n}\n"]}

package/dist/terminal-image.d.ts

@@ -1,3 +1,4 @@
+import type { TerminalColorMode } from "./colors.ts";
 export type ImageProtocol = "kitty" | "iterm2" | null;
 export interface TerminalCapabilities {
     images: ImageProtocol;
@@ -25,7 +26,10 @@ export declare function getCellDimensions(): CellDimensions;
 export declare function setCellDimensions(dims: CellDimensions): void;
 export declare function detectCapabilities(tmuxForwardsHyperlink?: () => boolean): TerminalCapabilities;
 export declare function getCapabilities(): TerminalCapabilities;
+export declare function getTerminalColorMode(capabilities?: TerminalCapabilities): TerminalColorMode;
 export declare function resetCapabilitiesCache(): void;
+/** Override selected auto-detected capabilities. */
+export declare function setCapabilityOverrides(overrides: Partial<TerminalCapabilities>): void;
 /** Override the cached capabilities. Useful in tests to exercise both code paths. */
 export declare function setCapabilities(caps: TerminalCapabilities): void;
 export declare function isImageLine(line: string): boolean;
@@ -52,6 +56,8 @@ export declare function deleteKittyImage(imageId: number): string;
  * Uses uppercase 'A' to also free the image data.
  */
 export declare function deleteAllKittyImages(): string;
+/** Delete all visible Kitty placements while retaining their uploaded image data. */
+export declare function deleteAllKittyPlacements(): string;
 export declare function encodeITerm2(base64Data: string, options?: {
     width?: number | string;
     height?: number | string;
@@ -63,7 +69,28 @@ export interface ImageCellSize {
     columns: number;
     rows: number;
 }
-export declare function calculateImageCellSize(imageDimensions: ImageDimensions, maxWidthCells: number, maxHeightCells?: number, cellDimensions?: CellDimensions): ImageCellSize;
+export interface KittyImageMetadata extends ImageCellSize {
+    imageId: number;
+    widthPx: number;
+    heightPx: number;
+}
+export interface KittyImagePlacement {
+    imageId: number;
+    transmissionGeneration: number;
+    transmissionBytes: number;
+    estimatedDecodedBytes: number;
+    rows: number;
+    sequence: string;
+    replacementLine: string;
+}
+export declare function registerKittyImageMetadata(metadata: KittyImageMetadata): void;
+export declare function getKittyImageMetadata(line: string): KittyImageMetadata | undefined;
+/** Read the number of rows covered by an image placement without scanning its payload. */
+export declare function getKittyImagePlacementRows(line: string): number | undefined;
+/** Build a placement-only command for an image line emitted by {@link renderImage}. */
+export declare function getKittyImagePlacement(line: string): KittyImagePlacement | undefined;
+export declare function cropKittyImageLine(line: string, hiddenRows: number, visibleRows: number): string;
+export declare function calculateImageCellSize(imageDimensions: ImageDimensions, maxWidthCells: number, maxHeightCells?: number, cellDimensions?: CellDimensions, optimizeAspectRatio?: boolean): ImageCellSize;
 export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
 export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
 export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
@@ -72,6 +99,7 @@ export declare function getWebpDimensions(base64Data: string): ImageDimensions |
 export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
 export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
     sequence: string;
+    columns: number;
     rows: number;
     imageId?: number;
 } | null;

package/dist/terminal-image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-image.d.ts","sourceRoot":"","sources":["../src/terminal-image.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from \"node:child_process\";\nimport { homedir } from \"node:os\";\nimport { isAbsolute } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\n\nexport type ImageProtocol = \"kitty\" | \"iterm2\" | null;\n\nexport interface TerminalCapabilities {\n\timages: ImageProtocol;\n\ttrueColor: boolean;\n\thyperlinks: boolean;\n}\n\nexport interface CellDimensions {\n\twidthPx: number;\n\theightPx: number;\n}\n\nexport interface ImageDimensions {\n\twidthPx: number;\n\theightPx: number;\n}\n\nexport interface ImageRenderOptions {\n\tmaxWidthCells?: number;\n\tmaxHeightCells?: number;\n\tpreserveAspectRatio?: boolean;\n\t/** Kitty image ID. If provided, reuses/replaces existing image with this ID. */\n\timageId?: number;\n\t/** Whether Kitty should apply its default cursor movement after placement. */\n\tmoveCursor?: boolean;\n}\n\nlet cachedCapabilities: TerminalCapabilities | null = null;\n\n// Default cell dimensions - updated by TUI when terminal responds to query\nlet cellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 };\n\nexport function getCellDimensions(): CellDimensions {\n\treturn cellDimensions;\n}\n\nexport function setCellDimensions(dims: CellDimensions): void {\n\tcellDimensions = dims;\n}\n\n/**\n * Checks whether the attached tmux client forwards OSC 8 hyperlinks to the\n * outer terminal. tmux only re-emits them when its `client_termfeatures` lists\n * `hyperlinks`, and strips them otherwise. On any error fallbacks `false`.\n */\nfunction probeTmuxHyperlinks(): boolean {\n\ttry {\n\t\tconst termfeatures = execSync(\"tmux display-message -p '#{client_termfeatures}'\", {\n\t\t\tencoding: \"utf8\",\n\t\t\ttimeout: 250,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"ignore\"],\n\t\t});\n\t\treturn termfeatures\n\t\t\t.split(\",\")\n\t\t\t.map((feature) => feature.trim())\n\t\t\t.includes(\"hyperlinks\");\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function detectCapabilities(tmuxForwardsHyperlink: () => boolean = probeTmuxHyperlinks): TerminalCapabilities {\n\tconst termProgram = process.env.TERM_PROGRAM?.toLowerCase() || \"\";\n\tconst terminalEmulator = process.env.TERMINAL_EMULATOR?.toLowerCase() || \"\";\n\tconst term = process.env.TERM?.toLowerCase() || \"\";\n\tconst colorTerm = process.env.COLORTERM?.toLowerCase() || \"\";\n\tconst hasTrueColorHint = colorTerm === \"truecolor\" || colorTerm === \"24bit\";\n\n\t// Emit OSC 8 hyperlinks only when tmux confirms it forwards.\n\t// Image protocols are unreliable under tmux, so leave `images: null`.\n\tif (process.env.TMUX || term.startsWith(\"tmux\")) {\n\t\treturn { images: null, trueColor: hasTrueColorHint, hyperlinks: tmuxForwardsHyperlink() };\n\t}\n\n\t// screen does not forward OSC 8 hyperlinks, so keep them off there.\n\tif (term.startsWith(\"screen\")) {\n\t\treturn { images: null, trueColor: hasTrueColorHint, hyperlinks: false };\n\t}\n\n\tif (process.env.KITTY_WINDOW_ID || termProgram === \"kitty\") {\n\t\treturn { images: \"kitty\", trueColor: true, hyperlinks: true };\n\t}\n\n\tif (termProgram === \"ghostty\" || term.includes(\"ghostty\") || process.env.GHOSTTY_RESOURCES_DIR) {\n\t\treturn { images: \"kitty\", trueColor: true, hyperlinks: true };\n\t}\n\n\tif (process.env.WEZTERM_PANE || termProgram === \"wezterm\") {\n\t\treturn { images: \"kitty\", trueColor: true, hyperlinks: true };\n\t}\n\n\t// Warp supports the Kitty graphics protocol and OSC 8 hyperlinks.\n\tif (termProgram === \"warpterminal\" || process.env.WARP_SESSION_ID || process.env.WARP_TERMINAL_SESSION_UUID) {\n\t\treturn { images: \"kitty\", trueColor: true, hyperlinks: true };\n\t}\n\n\tif (process.env.ITERM_SESSION_ID || termProgram === \"iterm.app\") {\n\t\treturn { images: \"iterm2\", trueColor: true, hyperlinks: true };\n\t}\n\n\tif (process.env.WT_SESSION) {\n\t\treturn { images: null, trueColor: true, hyperlinks: true };\n\t}\n\n\tif (termProgram === \"vscode\") {\n\t\treturn { images: null, trueColor: true, hyperlinks: true };\n\t}\n\n\tif (termProgram === \"alacritty\") {\n\t\treturn { images: null, trueColor: true, hyperlinks: true };\n\t}\n\n\tif (terminalEmulator === \"jetbrains-jediterm\") {\n\t\treturn { images: null, trueColor: true, hyperlinks: false };\n\t}\n\n\t// Unknown terminal: be conservative. OSC 8 is rendered invisibly as \"just\n\t// text\" on terminals that swallow it, which means the URL disappears from\n\t// the rendered output. Default to the legacy `text (url)` behavior unless we\n\t// have positively identified a hyperlink-capable terminal above.\n\treturn { images: null, trueColor: hasTrueColorHint, hyperlinks: false };\n}\n\nexport function getCapabilities(): TerminalCapabilities {\n\tif (!cachedCapabilities) {\n\t\tcachedCapabilities = detectCapabilities();\n\t}\n\treturn cachedCapabilities;\n}\n\nexport function resetCapabilitiesCache(): void {\n\tcachedCapabilities = null;\n}\n\n/** Override the cached capabilities. Useful in tests to exercise both code paths. */\nexport function setCapabilities(caps: TerminalCapabilities): void {\n\tcachedCapabilities = caps;\n}\n\nconst KITTY_PREFIX = \"\\x1b_G\";\nconst ITERM2_PREFIX = \"\\x1b]1337;File=\";\n\nexport function isImageLine(line: string): boolean {\n\t// Fast path: sequence at line start (single-row images)\n\tif (line.startsWith(KITTY_PREFIX) || line.startsWith(ITERM2_PREFIX)) {\n\t\treturn true;\n\t}\n\t// Slow path: sequence elsewhere (multi-row images have cursor-up prefix)\n\treturn line.includes(KITTY_PREFIX) || line.includes(ITERM2_PREFIX);\n}\n\n/**\n * Generate a random image ID for Kitty graphics protocol.\n * Uses random IDs to avoid collisions between different module instances\n * (e.g., main app vs extensions).\n */\nexport function allocateImageId(): number {\n\t// Use random ID in range [1, 0xffffffff] to avoid collisions\n\treturn Math.floor(Math.random() * 0xfffffffe) + 1;\n}\n\nexport function encodeKitty(\n\tbase64Data: string,\n\toptions: {\n\t\tcolumns?: number;\n\t\trows?: number;\n\t\timageId?: number;\n\t\t/** Whether Kitty should apply its default cursor movement after placement. Default: true. */\n\t\tmoveCursor?: boolean;\n\t} = {},\n): string {\n\tconst CHUNK_SIZE = 4096;\n\n\tconst params: string[] = [\"a=T\", \"f=100\", \"q=2\"];\n\n\tif (options.moveCursor === false) params.push(\"C=1\");\n\tif (options.columns) params.push(`c=${options.columns}`);\n\tif (options.rows) params.push(`r=${options.rows}`);\n\tif (options.imageId) params.push(`i=${options.imageId}`);\n\n\tif (base64Data.length <= CHUNK_SIZE) {\n\t\treturn `\\x1b_G${params.join(\",\")};${base64Data}\\x1b\\\\`;\n\t}\n\n\tconst chunks: string[] = [];\n\tlet offset = 0;\n\tlet isFirst = true;\n\n\twhile (offset < base64Data.length) {\n\t\tconst chunk = base64Data.slice(offset, offset + CHUNK_SIZE);\n\t\tconst isLast = offset + CHUNK_SIZE >= base64Data.length;\n\n\t\tif (isFirst) {\n\t\t\tchunks.push(`\\x1b_G${params.join(\",\")},m=1;${chunk}\\x1b\\\\`);\n\t\t\tisFirst = false;\n\t\t} else if (isLast) {\n\t\t\tchunks.push(`\\x1b_Gm=0;${chunk}\\x1b\\\\`);\n\t\t} else {\n\t\t\tchunks.push(`\\x1b_Gm=1;${chunk}\\x1b\\\\`);\n\t\t}\n\n\t\toffset += CHUNK_SIZE;\n\t}\n\n\treturn chunks.join(\"\");\n}\n\n/**\n * Delete a Kitty graphics image by ID.\n * Uses uppercase 'I' to also free the image data.\n */\nexport function deleteKittyImage(imageId: number): string {\n\treturn `\\x1b_Ga=d,d=I,i=${imageId},q=2\\x1b\\\\`;\n}\n\n/**\n * Delete all visible Kitty graphics images.\n * Uses uppercase 'A' to also free the image data.\n */\nexport function deleteAllKittyImages(): string {\n\treturn \"\\x1b_Ga=d,d=A,q=2\\x1b\\\\\";\n}\n\nexport function encodeITerm2(\n\tbase64Data: string,\n\toptions: {\n\t\twidth?: number | string;\n\t\theight?: number | string;\n\t\tname?: string;\n\t\tpreserveAspectRatio?: boolean;\n\t\tinline?: boolean;\n\t} = {},\n): string {\n\tconst params: string[] = [`inline=${options.inline !== false ? 1 : 0}`];\n\n\tif (options.width !== undefined) params.push(`width=${options.width}`);\n\tif (options.height !== undefined) params.push(`height=${options.height}`);\n\tif (options.name) {\n\t\tconst nameBase64 = Buffer.from(options.name).toString(\"base64\");\n\t\tparams.push(`name=${nameBase64}`);\n\t}\n\tif (options.preserveAspectRatio === false) {\n\t\tparams.push(\"preserveAspectRatio=0\");\n\t}\n\n\treturn `\\x1b]1337;File=${params.join(\";\")}:${base64Data}\\x07`;\n}\n\nexport interface ImageCellSize {\n\tcolumns: number;\n\trows: number;\n}\n\nexport function calculateImageCellSize(\n\timageDimensions: ImageDimensions,\n\tmaxWidthCells: number,\n\tmaxHeightCells?: number,\n\tcellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 },\n): ImageCellSize {\n\tconst maxWidth = Math.max(1, Math.floor(maxWidthCells));\n\tconst maxHeight = maxHeightCells === undefined ? undefined : Math.max(1, Math.floor(maxHeightCells));\n\tconst imageWidth = Math.max(1, imageDimensions.widthPx);\n\tconst imageHeight = Math.max(1, imageDimensions.heightPx);\n\n\tconst widthScale = (maxWidth * cellDimensions.widthPx) / imageWidth;\n\tconst heightScale = maxHeight === undefined ? widthScale : (maxHeight * cellDimensions.heightPx) / imageHeight;\n\tconst scale = Math.min(widthScale, heightScale);\n\n\tconst scaledWidthPx = imageWidth * scale;\n\tconst scaledHeightPx = imageHeight * scale;\n\tconst columns = Math.ceil(scaledWidthPx / cellDimensions.widthPx);\n\tconst rows = Math.ceil(scaledHeightPx / cellDimensions.heightPx);\n\n\treturn {\n\t\tcolumns: Math.max(1, Math.min(maxWidth, columns)),\n\t\trows: Math.max(1, maxHeight === undefined ? rows : Math.min(maxHeight, rows)),\n\t};\n}\n\nexport function calculateImageRows(\n\timageDimensions: ImageDimensions,\n\ttargetWidthCells: number,\n\tcellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 },\n): number {\n\treturn calculateImageCellSize(imageDimensions, targetWidthCells, undefined, cellDimensions).rows;\n}\n\nexport function getPngDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 24) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst width = buffer.readUInt32BE(16);\n\t\tconst height = buffer.readUInt32BE(20);\n\n\t\treturn { widthPx: width, heightPx: height };\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getJpegDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 2) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (buffer[0] !== 0xff || buffer[1] !== 0xd8) {\n\t\t\treturn null;\n\t\t}\n\n\t\tlet offset = 2;\n\t\twhile (offset < buffer.length - 9) {\n\t\t\tif (buffer[offset] !== 0xff) {\n\t\t\t\toffset++;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst marker = buffer[offset + 1];\n\n\t\t\tif (marker >= 0xc0 && marker <= 0xc2) {\n\t\t\t\tconst height = buffer.readUInt16BE(offset + 5);\n\t\t\t\tconst width = buffer.readUInt16BE(offset + 7);\n\t\t\t\treturn { widthPx: width, heightPx: height };\n\t\t\t}\n\n\t\t\tif (offset + 3 >= buffer.length) {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\tconst length = buffer.readUInt16BE(offset + 2);\n\t\t\tif (length < 2) {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\toffset += 2 + length;\n\t\t}\n\n\t\treturn null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getGifDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 10) {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst sig = buffer.slice(0, 6).toString(\"ascii\");\n\t\tif (sig !== \"GIF87a\" && sig !== \"GIF89a\") {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst width = buffer.readUInt16LE(6);\n\t\tconst height = buffer.readUInt16LE(8);\n\n\t\treturn { widthPx: width, heightPx: height };\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getWebpDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 30) {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst riff = buffer.slice(0, 4).toString(\"ascii\");\n\t\tconst webp = buffer.slice(8, 12).toString(\"ascii\");\n\t\tif (riff !== \"RIFF\" || webp !== \"WEBP\") {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst chunk = buffer.slice(12, 16).toString(\"ascii\");\n\t\tif (chunk === \"VP8 \") {\n\t\t\tif (buffer.length < 30) return null;\n\t\t\tconst width = buffer.readUInt16LE(26) & 0x3fff;\n\t\t\tconst height = buffer.readUInt16LE(28) & 0x3fff;\n\t\t\treturn { widthPx: width, heightPx: height };\n\t\t} else if (chunk === \"VP8L\") {\n\t\t\tif (buffer.length < 25) return null;\n\t\t\tconst bits = buffer.readUInt32LE(21);\n\t\t\tconst width = (bits & 0x3fff) + 1;\n\t\t\tconst height = ((bits >> 14) & 0x3fff) + 1;\n\t\t\treturn { widthPx: width, heightPx: height };\n\t\t} else if (chunk === \"VP8X\") {\n\t\t\tif (buffer.length < 30) return null;\n\t\t\tconst width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;\n\t\t\tconst height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;\n\t\t\treturn { widthPx: width, heightPx: height };\n\t\t}\n\n\t\treturn null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null {\n\tif (mimeType === \"image/png\") {\n\t\treturn getPngDimensions(base64Data);\n\t}\n\tif (mimeType === \"image/jpeg\") {\n\t\treturn getJpegDimensions(base64Data);\n\t}\n\tif (mimeType === \"image/gif\") {\n\t\treturn getGifDimensions(base64Data);\n\t}\n\tif (mimeType === \"image/webp\") {\n\t\treturn getWebpDimensions(base64Data);\n\t}\n\treturn null;\n}\n\nexport function renderImage(\n\tbase64Data: string,\n\timageDimensions: ImageDimensions,\n\toptions: ImageRenderOptions = {},\n): { sequence: string; rows: number; imageId?: number } | null {\n\tconst caps = getCapabilities();\n\n\tif (!caps.images) {\n\t\treturn null;\n\t}\n\n\tconst maxWidth = options.maxWidthCells ?? 80;\n\tconst size = calculateImageCellSize(imageDimensions, maxWidth, options.maxHeightCells, getCellDimensions());\n\n\tif (caps.images === \"kitty\") {\n\t\tconst sequence = encodeKitty(base64Data, {\n\t\t\tcolumns: size.columns,\n\t\t\trows: size.rows,\n\t\t\timageId: options.imageId,\n\t\t\tmoveCursor: options.moveCursor,\n\t\t});\n\t\treturn { sequence, rows: size.rows, imageId: options.imageId };\n\t}\n\n\tif (caps.images === \"iterm2\") {\n\t\tconst sequence = encodeITerm2(base64Data, {\n\t\t\twidth: size.columns,\n\t\t\theight: \"auto\",\n\t\t\tpreserveAspectRatio: options.preserveAspectRatio ?? true,\n\t\t});\n\t\treturn { sequence, rows: size.rows };\n\t}\n\n\treturn null;\n}\n\n/**\n * Wrap text in an OSC 8 hyperlink sequence.\n * The text is rendered as a clickable hyperlink in terminals that support OSC 8\n * (Ghostty, Kitty, WezTerm, iTerm2, VSCode, and others).\n * In terminals that do not support OSC 8, the escape sequences are ignored\n * and only the plain text is displayed.\n *\n * @param text - The visible text to display\n * @param url - The URL to link to\n */\nexport function hyperlink(text: string, url: string): string {\n\treturn `\\x1b]8;;${url}\\x1b\\\\${text}\\x1b]8;;\\x1b\\\\`;\n}\n\n/** Shorten home-prefixed absolute paths to ~/... for compact display. */\nfunction shortenImagePath(filename: string): string {\n\tconst home = homedir();\n\tif (home && (filename === home || filename.startsWith(`${home}/`) || filename.startsWith(`${home}\\\\`))) {\n\t\treturn `~${filename.slice(home.length)}`;\n\t}\n\treturn filename;\n}\n\n/**\n * Text fallback when the terminal cannot render inline images.\n * Absolute paths are shown shortened (~/...) and, when OSC 8 hyperlinks are\n * available, linked to file:// so the full path remains openable.\n */\nexport function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string {\n\tconst parts: string[] = [];\n\tif (filename) {\n\t\tconst display = shortenImagePath(filename);\n\t\tif (getCapabilities().hyperlinks && isAbsolute(filename)) {\n\t\t\tparts.push(hyperlink(display, pathToFileURL(filename).href));\n\t\t} else {\n\t\t\tparts.push(display);\n\t\t}\n\t}\n\tparts.push(`[${mimeType}]`);\n\tif (dimensions) parts.push(`${dimensions.widthPx}x${dimensions.heightPx}`);\n\treturn `[Image: ${parts.join(\" \")}]`;\n}\n"]}
+{"version":3,"file":"terminal-image.d.ts","sourceRoot":"","sources":["../src/terminal-image.ts"],"names":[],"mappings":"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"}

package/dist/terminal-image.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 let cachedCapabilities = null;
+let capabilityOverrides = {};
 // Default cell dimensions - updated by TUI when terminal responds to query
 let cellDimensions = { widthPx: 9, heightPx: 18 };
 export function getCellDimensions() {
@@ -32,12 +33,13 @@ function probeTmuxHyperlinks() {
         return false;
     }
 }
-export function detectCapabilities(tmuxForwardsHyperlink = probeTmuxHyperlinks) {
+function detectCapabilitiesFromEnvironment(tmuxForwardsHyperlink) {
     const termProgram = process.env.TERM_PROGRAM?.toLowerCase() || "";
     const terminalEmulator = process.env.TERMINAL_EMULATOR?.toLowerCase() || "";
     const term = process.env.TERM?.toLowerCase() || "";
     const colorTerm = process.env.COLORTERM?.toLowerCase() || "";
-    const hasTrueColorHint = colorTerm === "truecolor" || colorTerm === "24bit";
+    const hasTrueColorHint = colorTerm === "truecolor" || colorTerm === "24bit" || term.endsWith("-direct");
+    const isWindowsConsole = process.platform === "win32";
     // Emit OSC 8 hyperlinks only when tmux confirms it forwards.
     // Image protocols are unreliable under tmux, so leave `images: null`.
     if (process.env.TMUX || term.startsWith("tmux")) {
@@ -66,30 +68,70 @@ export function detectCapabilities(tmuxForwardsHyperlink = probeTmuxHyperlinks)
     if (process.env.WT_SESSION) {
         return { images: null, trueColor: true, hyperlinks: true };
     }
-    if (termProgram === "vscode") {
-        return { images: null, trueColor: true, hyperlinks: true };
-    }
-    if (termProgram === "alacritty") {
+    if (termProgram === "alacritty" || termProgram === "vscode" || termProgram === "zed") {
         return { images: null, trueColor: true, hyperlinks: true };
     }
     if (terminalEmulator === "jetbrains-jediterm") {
         return { images: null, trueColor: true, hyperlinks: false };
     }
+    // Windows Terminal does not always set WT_SESSION, for example when it hosts
+    // a cmd.exe launched directly from Win+R. Modern Windows consoles support
+    // truecolor; keep hyperlinks off unless we positively detected support above.
+    if (isWindowsConsole) {
+        return { images: null, trueColor: true, hyperlinks: false };
+    }
     // Unknown terminal: be conservative. OSC 8 is rendered invisibly as "just
     // text" on terminals that swallow it, which means the URL disappears from
     // the rendered output. Default to the legacy `text (url)` behavior unless we
     // have positively identified a hyperlink-capable terminal above.
     return { images: null, trueColor: hasTrueColorHint, hyperlinks: false };
 }
+function parseBooleanCapabilityOverride(value) {
+    return value === "1" ? true : value === "0" ? false : undefined;
+}
+export function detectCapabilities(tmuxForwardsHyperlink = probeTmuxHyperlinks) {
+    const hyperlinks = parseBooleanCapabilityOverride(process.env.PI_HYPERLINKS);
+    const detected = detectCapabilitiesFromEnvironment(hyperlinks === undefined ? tmuxForwardsHyperlink : () => hyperlinks);
+    const imageProtocol = process.env.PI_IMAGE_PROTOCOL?.toLowerCase();
+    const images = imageProtocol === "kitty" || imageProtocol === "iterm2"
+        ? imageProtocol
+        : imageProtocol === "none" || imageProtocol === "0"
+            ? null
+            : undefined;
+    const trueColor = parseBooleanCapabilityOverride(process.env.PI_TRUE_COLOR);
+    return {
+        ...detected,
+        ...(images !== undefined ? { images } : {}),
+        ...(trueColor !== undefined ? { trueColor } : {}),
+        ...(hyperlinks !== undefined ? { hyperlinks } : {}),
+    };
+}
 export function getCapabilities() {
     if (!cachedCapabilities) {
-        cachedCapabilities = detectCapabilities();
+        const hyperlinks = capabilityOverrides.hyperlinks;
+        cachedCapabilities = {
+            ...detectCapabilities(hyperlinks === undefined ? undefined : () => hyperlinks),
+            ...capabilityOverrides,
+        };
     }
     return cachedCapabilities;
 }
+export function getTerminalColorMode(capabilities = getCapabilities()) {
+    return capabilities.trueColor ? "truecolor" : "256color";
+}
 export function resetCapabilitiesCache() {
     cachedCapabilities = null;
 }
+/** Override selected auto-detected capabilities. */
+export function setCapabilityOverrides(overrides) {
+    if (capabilityOverrides.images === overrides.images &&
+        capabilityOverrides.trueColor === overrides.trueColor &&
+        capabilityOverrides.hyperlinks === overrides.hyperlinks) {
+        return;
+    }
+    capabilityOverrides = { ...overrides };
+    cachedCapabilities = null;
+}
 /** Override the cached capabilities. Useful in tests to exercise both code paths. */
 export function setCapabilities(caps) {
     cachedCapabilities = caps;
@@ -161,8 +203,15 @@ export function deleteKittyImage(imageId) {
 export function deleteAllKittyImages() {
     return "\x1b_Ga=d,d=A,q=2\x1b\\";
 }
+/** Delete all visible Kitty placements while retaining their uploaded image data. */
+export function deleteAllKittyPlacements() {
+    return "\x1b_Ga=d,d=a,q=2\x1b\\";
+}
 export function encodeITerm2(base64Data, options = {}) {
-    const params = [`inline=${options.inline !== false ? 1 : 0}`];
+    const params = [
+        `inline=${options.inline !== false ? 1 : 0}`,
+        `size=${Buffer.byteLength(base64Data, "base64")}`,
+    ];
     if (options.width !== undefined)
         params.push(`width=${options.width}`);
     if (options.height !== undefined)
@@ -176,7 +225,141 @@ export function encodeITerm2(base64Data, options = {}) {
     }
     return `\x1b]1337;File=${params.join(";")}:${base64Data}\x07`;
 }
-export function calculateImageCellSize(imageDimensions, maxWidthCells, maxHeightCells, cellDimensions = { widthPx: 9, heightPx: 18 }) {
+const kittyImageMetadata = new Map();
+let kittyTransmissionGeneration = 0;
+export function registerKittyImageMetadata(metadata) {
+    kittyTransmissionGeneration += 1;
+    kittyImageMetadata.delete(metadata.imageId);
+    kittyImageMetadata.set(metadata.imageId, { ...metadata, transmissionGeneration: kittyTransmissionGeneration });
+    if (kittyImageMetadata.size > 1000) {
+        const oldestImageId = kittyImageMetadata.keys().next().value;
+        if (oldestImageId !== undefined)
+            kittyImageMetadata.delete(oldestImageId);
+    }
+}
+function getRegisteredKittyImageMetadataFromControls(controls) {
+    const imageId = /(?:^|,)i=(\d+)(?:,|$)/.exec(controls)?.[1];
+    return imageId === undefined ? undefined : kittyImageMetadata.get(Number.parseInt(imageId, 10));
+}
+function getRegisteredKittyImageMetadata(line) {
+    const controls = /\x1b_G([^;]*);/.exec(line)?.[1];
+    return controls === undefined ? undefined : getRegisteredKittyImageMetadataFromControls(controls);
+}
+function getExplicitKittyImageRows(controls) {
+    const value = /(?:^|,)r=(\d+)(?:,|$)/.exec(controls)?.[1];
+    if (value === undefined)
+        return undefined;
+    const rows = Number.parseInt(value, 10);
+    return rows > 0 ? rows : undefined;
+}
+function getKittyImageRowsFromControls(controls, fallbackRows) {
+    return getExplicitKittyImageRows(controls) ?? fallbackRows;
+}
+export function getKittyImageMetadata(line) {
+    const metadata = getRegisteredKittyImageMetadata(line);
+    if (!metadata)
+        return undefined;
+    return {
+        imageId: metadata.imageId,
+        columns: metadata.columns,
+        rows: metadata.rows,
+        widthPx: metadata.widthPx,
+        heightPx: metadata.heightPx,
+    };
+}
+const KITTY_PLACEMENT_CONTROL_KEYS = new Set([
+    "i",
+    "p",
+    "x",
+    "y",
+    "w",
+    "h",
+    "X",
+    "Y",
+    "c",
+    "r",
+    "C",
+    "U",
+    "z",
+    "P",
+    "Q",
+    "H",
+    "V",
+]);
+/** Read the number of rows covered by an image placement without scanning its payload. */
+export function getKittyImagePlacementRows(line) {
+    const controls = /\x1b_G([^;]*);/.exec(line)?.[1];
+    if (controls === undefined)
+        return undefined;
+    const explicitRows = getExplicitKittyImageRows(controls);
+    if (explicitRows !== undefined)
+        return explicitRows;
+    return getRegisteredKittyImageMetadataFromControls(controls)?.rows;
+}
+/** Build a placement-only command for an image line emitted by {@link renderImage}. */
+export function getKittyImagePlacement(line) {
+    const match = /\x1b_G([^;]*);/.exec(line);
+    if (!match)
+        return undefined;
+    const metadata = getRegisteredKittyImageMetadataFromControls(match[1]);
+    if (!metadata)
+        return undefined;
+    let commandStart = match.index;
+    let commandControls = match[1];
+    let transmissionEnd;
+    while (true) {
+        const terminator = line.indexOf("\x1b\\", commandStart + KITTY_PREFIX.length);
+        if (terminator === -1)
+            return undefined;
+        transmissionEnd = terminator + 2;
+        if (!/(?:^|,)m=1(?:,|$)/.test(commandControls))
+            break;
+        commandStart = transmissionEnd;
+        if (!line.startsWith(KITTY_PREFIX, commandStart))
+            return undefined;
+        const controlsEnd = line.indexOf(";", commandStart + KITTY_PREFIX.length);
+        if (controlsEnd === -1)
+            return undefined;
+        commandControls = line.slice(commandStart + KITTY_PREFIX.length, controlsEnd);
+    }
+    const controls = match[1]
+        .split(",")
+        .filter((control) => KITTY_PLACEMENT_CONTROL_KEYS.has(control.split("=", 1)[0] ?? ""));
+    const sequence = `\x1b_Ga=p,q=2,${controls.join(",")}\x1b\\`;
+    return {
+        imageId: metadata.imageId,
+        transmissionGeneration: metadata.transmissionGeneration,
+        transmissionBytes: transmissionEnd - match.index,
+        estimatedDecodedBytes: metadata.widthPx * metadata.heightPx * 4,
+        rows: getKittyImageRowsFromControls(match[1], metadata.rows),
+        sequence,
+        replacementLine: `${line.slice(0, match.index)}${sequence}${line.slice(transmissionEnd)}`,
+    };
+}
+export function cropKittyImageLine(line, hiddenRows, visibleRows) {
+    const metadata = getKittyImageMetadata(line);
+    const match = /\x1b_G([^;]*);/.exec(line);
+    if (!metadata || !match || hiddenRows < 0 || hiddenRows >= metadata.rows || visibleRows <= 0)
+        return line;
+    const croppedRows = Math.min(visibleRows, metadata.rows - hiddenRows);
+    if (hiddenRows === 0 && croppedRows === metadata.rows)
+        return line;
+    const sourceY = Math.floor((metadata.heightPx * hiddenRows) / metadata.rows);
+    const sourceEnd = Math.ceil((metadata.heightPx * (hiddenRows + croppedRows)) / metadata.rows);
+    const sourceHeight = Math.max(1, Math.min(metadata.heightPx, sourceEnd) - sourceY);
+    const controls = match[1].split(",").filter((control) => !/^[yhr]=/.test(control));
+    controls.push(`y=${sourceY}`, `h=${sourceHeight}`, `r=${croppedRows}`);
+    return `${line.slice(0, match.index)}\x1b_G${controls.join(",")};${line.slice(match.index + match[0].length)}`;
+}
+function chooseLessDistortedCellCount(upperCount, idealCount) {
+    if (upperCount <= 1)
+        return upperCount;
+    const lowerCount = upperCount - 1;
+    const upperDistortion = Math.max(upperCount / idealCount, idealCount / upperCount);
+    const lowerDistortion = Math.max(lowerCount / idealCount, idealCount / lowerCount);
+    return lowerDistortion < upperDistortion ? lowerCount : upperCount;
+}
+export function calculateImageCellSize(imageDimensions, maxWidthCells, maxHeightCells, cellDimensions = { widthPx: 9, heightPx: 18 }, optimizeAspectRatio = false) {
     const maxWidth = Math.max(1, Math.floor(maxWidthCells));
     const maxHeight = maxHeightCells === undefined ? undefined : Math.max(1, Math.floor(maxHeightCells));
     const imageWidth = Math.max(1, imageDimensions.widthPx);
@@ -186,12 +369,24 @@ export function calculateImageCellSize(imageDimensions, maxWidthCells, maxHeight
     const scale = Math.min(widthScale, heightScale);
     const scaledWidthPx = imageWidth * scale;
     const scaledHeightPx = imageHeight * scale;
-    const columns = Math.ceil(scaledWidthPx / cellDimensions.widthPx);
-    const rows = Math.ceil(scaledHeightPx / cellDimensions.heightPx);
-    return {
-        columns: Math.max(1, Math.min(maxWidth, columns)),
-        rows: Math.max(1, maxHeight === undefined ? rows : Math.min(maxHeight, rows)),
-    };
+    let columns = Math.max(1, Math.min(maxWidth, Math.ceil(scaledWidthPx / cellDimensions.widthPx)));
+    const heightRows = scaledHeightPx / cellDimensions.heightPx;
+    let rows = Math.max(1, Math.ceil(heightRows));
+    if (maxHeight !== undefined) {
+        rows = Math.min(maxHeight, rows);
+    }
+    if (!optimizeAspectRatio) {
+        return { columns, rows };
+    }
+    if (widthScale <= heightScale) {
+        const idealRows = (columns * cellDimensions.widthPx * imageHeight) / (imageWidth * cellDimensions.heightPx);
+        rows = chooseLessDistortedCellCount(rows, idealRows);
+    }
+    else {
+        const idealColumns = (rows * cellDimensions.heightPx * imageWidth) / (imageHeight * cellDimensions.widthPx);
+        columns = chooseLessDistortedCellCount(columns, idealColumns);
+    }
+    return { columns, rows };
 }
 export function calculateImageRows(imageDimensions, targetWidthCells, cellDimensions = { widthPx: 9, heightPx: 18 }) {
     return calculateImageCellSize(imageDimensions, targetWidthCells, undefined, cellDimensions).rows;
@@ -328,15 +523,25 @@ export function renderImage(base64Data, imageDimensions, options = {}) {
         return null;
     }
     const maxWidth = options.maxWidthCells ?? 80;
-    const size = calculateImageCellSize(imageDimensions, maxWidth, options.maxHeightCells, getCellDimensions());
+    // Reduce Kitty's cell-aligned distortion without shrinking iTerm2 reservations.
+    const size = calculateImageCellSize(imageDimensions, maxWidth, options.maxHeightCells, getCellDimensions(), caps.images === "kitty");
     if (caps.images === "kitty") {
+        if (options.imageId !== undefined) {
+            registerKittyImageMetadata({
+                imageId: options.imageId,
+                columns: size.columns,
+                rows: size.rows,
+                widthPx: imageDimensions.widthPx,
+                heightPx: imageDimensions.heightPx,
+            });
+        }
         const sequence = encodeKitty(base64Data, {
             columns: size.columns,
             rows: size.rows,
             imageId: options.imageId,
             moveCursor: options.moveCursor,
         });
-        return { sequence, rows: size.rows, imageId: options.imageId };
+        return { sequence, columns: size.columns, rows: size.rows, imageId: options.imageId };
     }
     if (caps.images === "iterm2") {
         const sequence = encodeITerm2(base64Data, {
@@ -344,7 +549,7 @@ export function renderImage(base64Data, imageDimensions, options = {}) {
             height: "auto",
             preserveAspectRatio: options.preserveAspectRatio ?? true,
         });
-        return { sequence, rows: size.rows };
+        return { sequence, columns: size.columns, rows: size.rows };
     }
     return null;
 }