@m4ike1/ion-tui 0.1.0

package/dist/terminal-colors.js.map

@@ -0,0 +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"]}

package/dist/terminal-image.d.ts

@@ -0,0 +1,118 @@
+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;
+    /** Whether Kitty should apply its default cursor movement after placement. */
+    moveCursor?: boolean;
+}
+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 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;
+/**
+ * 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 declare function allocateImageId(): number;
+export declare function encodeKitty(base64Data: string, options?: {
+    columns?: number;
+    rows?: number;
+    imageId?: number;
+    /** Whether Kitty should apply its default cursor movement after placement. Default: true. */
+    moveCursor?: boolean;
+}): string;
+/**
+ * Delete a Kitty graphics image by ID.
+ * Uses uppercase 'I' to also free the image data.
+ */
+export declare function deleteKittyImage(imageId: number): string;
+/**
+ * Delete all visible Kitty graphics images.
+ * 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;
+    name?: string;
+    preserveAspectRatio?: boolean;
+    inline?: boolean;
+}): string;
+export interface ImageCellSize {
+    columns: number;
+    rows: number;
+}
+export interface KittyImageMetadata extends ImageCellSize {
+    imageId: number;
+    widthPx: number;
+    heightPx: number;
+}
+export interface KittyImagePlacement {
+    imageId: number;
+    transmissionGeneration: number;
+    transmissionBytes: number;
+    estimatedDecodedBytes: number;
+    sequence: string;
+    replacementLine: string;
+}
+export declare function registerKittyImageMetadata(metadata: KittyImageMetadata): void;
+export declare function getKittyImageMetadata(line: string): KittyImageMetadata | 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): 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;
+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): {
+    sequence: string;
+    columns: number;
+    rows: number;
+    imageId?: number;
+} | null;
+/**
+ * Wrap text in an OSC 8 hyperlink sequence.
+ * The text is rendered as a clickable hyperlink in terminals that support OSC 8
+ * (Ghostty, Kitty, WezTerm, iTerm2, VSCode, and others).
+ * In terminals that do not support OSC 8, the escape sequences are ignored
+ * and only the plain text is displayed.
+ *
+ * @param text - The visible text to display
+ * @param url - The URL to link to
+ */
+export declare function hyperlink(text: string, url: string): string;
+/**
+ * Text fallback when the terminal cannot render inline images.
+ * Absolute paths are shown shortened (~/...) and, when OSC 8 hyperlinks are
+ * available, linked to file:// so the full path remains openable.
+ */
+export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+//# sourceMappingURL=terminal-image.d.ts.map

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

@@ -0,0 +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;\nlet capabilityOverrides: Partial<TerminalCapabilities> = {};\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\nfunction detectCapabilitiesFromEnvironment(tmuxForwardsHyperlink: () => boolean): 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\tconst isWindowsConsole = process.platform === \"win32\";\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 === \"alacritty\" || termProgram === \"vscode\" || termProgram === \"zed\") {\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// Windows Terminal does not always set WT_SESSION, for example when it hosts\n\t// a cmd.exe launched directly from Win+R. Modern Windows consoles support\n\t// truecolor; keep hyperlinks off unless we positively detected support above.\n\tif (isWindowsConsole) {\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\nfunction parseBooleanCapabilityOverride(value: string | undefined): boolean | undefined {\n\treturn value === \"1\" ? true : value === \"0\" ? false : undefined;\n}\n\nexport function detectCapabilities(tmuxForwardsHyperlink: () => boolean = probeTmuxHyperlinks): TerminalCapabilities {\n\tconst hyperlinks = parseBooleanCapabilityOverride(process.env.ION_HYPERLINKS);\n\tconst detected = detectCapabilitiesFromEnvironment(\n\t\thyperlinks === undefined ? tmuxForwardsHyperlink : () => hyperlinks,\n\t);\n\tconst imageProtocol = process.env.ION_IMAGE_PROTOCOL?.toLowerCase();\n\tconst images =\n\t\timageProtocol === \"kitty\" || imageProtocol === \"iterm2\"\n\t\t\t? imageProtocol\n\t\t\t: imageProtocol === \"none\" || imageProtocol === \"0\"\n\t\t\t\t? null\n\t\t\t\t: undefined;\n\tconst trueColor = parseBooleanCapabilityOverride(process.env.ION_TRUE_COLOR);\n\treturn {\n\t\t...detected,\n\t\t...(images !== undefined ? { images } : {}),\n\t\t...(trueColor !== undefined ? { trueColor } : {}),\n\t\t...(hyperlinks !== undefined ? { hyperlinks } : {}),\n\t};\n}\n\nexport function getCapabilities(): TerminalCapabilities {\n\tif (!cachedCapabilities) {\n\t\tconst hyperlinks = capabilityOverrides.hyperlinks;\n\t\tcachedCapabilities = {\n\t\t\t...detectCapabilities(hyperlinks === undefined ? undefined : () => hyperlinks),\n\t\t\t...capabilityOverrides,\n\t\t};\n\t}\n\treturn cachedCapabilities;\n}\n\nexport function resetCapabilitiesCache(): void {\n\tcachedCapabilities = null;\n}\n\n/** Override selected auto-detected capabilities. */\nexport function setCapabilityOverrides(overrides: Partial<TerminalCapabilities>): void {\n\tif (\n\t\tcapabilityOverrides.images === overrides.images &&\n\t\tcapabilityOverrides.trueColor === overrides.trueColor &&\n\t\tcapabilityOverrides.hyperlinks === overrides.hyperlinks\n\t) {\n\t\treturn;\n\t}\n\tcapabilityOverrides = { ...overrides };\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\n/** Delete all visible Kitty placements while retaining their uploaded image data. */\nexport function deleteAllKittyPlacements(): 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[] = [\n\t\t`inline=${options.inline !== false ? 1 : 0}`,\n\t\t`size=${Buffer.byteLength(base64Data, \"base64\")}`,\n\t];\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 interface KittyImageMetadata extends ImageCellSize {\n\timageId: number;\n\twidthPx: number;\n\theightPx: number;\n}\n\ninterface RegisteredKittyImageMetadata extends KittyImageMetadata {\n\ttransmissionGeneration: number;\n}\n\nexport interface KittyImagePlacement {\n\timageId: number;\n\ttransmissionGeneration: number;\n\ttransmissionBytes: number;\n\testimatedDecodedBytes: number;\n\tsequence: string;\n\treplacementLine: string;\n}\n\nconst kittyImageMetadata = new Map<number, RegisteredKittyImageMetadata>();\nlet kittyTransmissionGeneration = 0;\n\nexport function registerKittyImageMetadata(metadata: KittyImageMetadata): void {\n\tkittyTransmissionGeneration += 1;\n\tkittyImageMetadata.delete(metadata.imageId);\n\tkittyImageMetadata.set(metadata.imageId, { ...metadata, transmissionGeneration: kittyTransmissionGeneration });\n\tif (kittyImageMetadata.size > 1000) {\n\t\tconst oldestImageId = kittyImageMetadata.keys().next().value;\n\t\tif (oldestImageId !== undefined) kittyImageMetadata.delete(oldestImageId);\n\t}\n}\n\nfunction getRegisteredKittyImageMetadata(line: string): RegisteredKittyImageMetadata | undefined {\n\tconst controls = /\\x1b_G([^;]*);/.exec(line)?.[1];\n\tif (!controls) return undefined;\n\tconst imageId = /(?:^|,)i=(\\d+)(?:,|$)/.exec(controls)?.[1];\n\treturn imageId === undefined ? undefined : kittyImageMetadata.get(Number.parseInt(imageId, 10));\n}\n\nexport function getKittyImageMetadata(line: string): KittyImageMetadata | undefined {\n\tconst metadata = getRegisteredKittyImageMetadata(line);\n\tif (!metadata) return undefined;\n\treturn {\n\t\timageId: metadata.imageId,\n\t\tcolumns: metadata.columns,\n\t\trows: metadata.rows,\n\t\twidthPx: metadata.widthPx,\n\t\theightPx: metadata.heightPx,\n\t};\n}\n\nconst KITTY_PLACEMENT_CONTROL_KEYS = new Set([\n\t\"i\",\n\t\"p\",\n\t\"x\",\n\t\"y\",\n\t\"w\",\n\t\"h\",\n\t\"X\",\n\t\"Y\",\n\t\"c\",\n\t\"r\",\n\t\"C\",\n\t\"U\",\n\t\"z\",\n\t\"P\",\n\t\"Q\",\n\t\"H\",\n\t\"V\",\n]);\n\n/** Build a placement-only command for an image line emitted by {@link renderImage}. */\nexport function getKittyImagePlacement(line: string): KittyImagePlacement | undefined {\n\tconst match = /\\x1b_G([^;]*);/.exec(line);\n\tconst metadata = getRegisteredKittyImageMetadata(line);\n\tif (!match || !metadata) return undefined;\n\n\tlet commandStart = match.index;\n\tlet commandControls = match[1];\n\tlet transmissionEnd: number;\n\twhile (true) {\n\t\tconst terminator = line.indexOf(\"\\x1b\\\\\", commandStart + KITTY_PREFIX.length);\n\t\tif (terminator === -1) return undefined;\n\t\ttransmissionEnd = terminator + 2;\n\t\tif (!/(?:^|,)m=1(?:,|$)/.test(commandControls)) break;\n\t\tcommandStart = transmissionEnd;\n\t\tif (!line.startsWith(KITTY_PREFIX, commandStart)) return undefined;\n\t\tconst controlsEnd = line.indexOf(\";\", commandStart + KITTY_PREFIX.length);\n\t\tif (controlsEnd === -1) return undefined;\n\t\tcommandControls = line.slice(commandStart + KITTY_PREFIX.length, controlsEnd);\n\t}\n\n\tconst controls = match[1]\n\t\t.split(\",\")\n\t\t.filter((control) => KITTY_PLACEMENT_CONTROL_KEYS.has(control.split(\"=\", 1)[0] ?? \"\"));\n\tconst sequence = `\\x1b_Ga=p,q=2,${controls.join(\",\")}\\x1b\\\\`;\n\treturn {\n\t\timageId: metadata.imageId,\n\t\ttransmissionGeneration: metadata.transmissionGeneration,\n\t\ttransmissionBytes: transmissionEnd - match.index,\n\t\testimatedDecodedBytes: metadata.widthPx * metadata.heightPx * 4,\n\t\tsequence,\n\t\treplacementLine: `${line.slice(0, match.index)}${sequence}${line.slice(transmissionEnd)}`,\n\t};\n}\n\nexport function cropKittyImageLine(line: string, hiddenRows: number, visibleRows: number): string {\n\tconst metadata = getKittyImageMetadata(line);\n\tconst match = /\\x1b_G([^;]*);/.exec(line);\n\tif (!metadata || !match || hiddenRows < 0 || hiddenRows >= metadata.rows || visibleRows <= 0) return line;\n\tconst croppedRows = Math.min(visibleRows, metadata.rows - hiddenRows);\n\tif (hiddenRows === 0 && croppedRows === metadata.rows) return line;\n\tconst sourceY = Math.floor((metadata.heightPx * hiddenRows) / metadata.rows);\n\tconst sourceEnd = Math.ceil((metadata.heightPx * (hiddenRows + croppedRows)) / metadata.rows);\n\tconst sourceHeight = Math.max(1, Math.min(metadata.heightPx, sourceEnd) - sourceY);\n\tconst controls = match[1].split(\",\").filter((control) => !/^[yhr]=/.test(control));\n\tcontrols.push(`y=${sourceY}`, `h=${sourceHeight}`, `r=${croppedRows}`);\n\treturn `${line.slice(0, match.index)}\\x1b_G${controls.join(\",\")};${line.slice(match.index + match[0].length)}`;\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; columns: number; 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\tif (options.imageId !== undefined) {\n\t\t\tregisterKittyImageMetadata({\n\t\t\t\timageId: options.imageId,\n\t\t\t\tcolumns: size.columns,\n\t\t\t\trows: size.rows,\n\t\t\t\twidthPx: imageDimensions.widthPx,\n\t\t\t\theightPx: imageDimensions.heightPx,\n\t\t\t});\n\t\t}\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, columns: size.columns, 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, columns: size.columns, 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"]}