@gajae-code/tui 0.18.12 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-10-22
+
+### Fixed
+
+- Kitty and iTerm2 image encoders now reject a payload that is not RFC 4648 base64 before writing the terminal escape, so an early APC or OSC terminator in the image data cannot inject further control sequences.
+
+- Normalize local Markdown links to absolute, percent-encoded `file://` OSC 8 destinations, resolving relative paths from the active working directory and `~/` paths from the home directory. Link destinations are read as URI references, so percent-escapes are decoded and `#fragment` / `?query` suffixes (for example `src/file.ts#L12`) stay URI components. Network-path references (`//host/path`) are left unchanged rather than read as local absolute paths. Targets containing control characters remain non-clickable.
+
+- The Gajae Pet sprite is uploaded as a single-escape lossless PNG instead of chunked kitty raw RGBA (`f=32`), and every kitty escape is bounded to the protocol's 4096-byte limit in both the pet and inline-image paths. A pet animation frame used to emit several ~4 KB raw-RGBA chunk continuations per tick; when the terminal dropped one mid-payload the remaining base64 was painted into the transcript as text and the frame desynchronized. A sprite frame now costs a few hundred payload characters inside one complete escape.
+
 ## [0.18.12] - 2026-10-16
 
 ### Added

package/dist/types/components/gajae-pet.d.ts

@@ -174,7 +174,16 @@ export declare function encodeGridSixel(grid: string[], scale: number, topPaddin
  * pixel box at half size.
  */
 export declare function encodeGridIterm2(grid: string[], scale: number, columns: number, rows: number, topPaddingPx?: number, bottomPaddingPx?: number, leftPaddingPx?: number, rightPaddingPx?: number, palette?: Palette): string;
-/** Encode a bottom-aligned grid as kitty raw RGBA at `scale`. */
+/**
+ * Encode a bottom-aligned grid as a kitty PNG transmission at `scale`.
+ *
+ * The canvas is padded to the full cell block (`cols * cellWidthPx`) so the
+ * square sprite renders 1:1 inside it. A PNG-encoded sprite is a few hundred
+ * base64 characters, so the upload stays inside one APC escape; raw RGBA
+ * (`f=32`) would need several ~4 KB chunk continuations per animation frame,
+ * and a terminal that drops one prints the remaining base64 into the
+ * transcript.
+ */
 export declare function encodeGridKitty(grid: string[], scale: number, imageId: number, cols: number, rows: number, topPaddingPx?: number, cellYOffsetPx?: number, leftPaddingPx?: number, rightPaddingPx?: number, palette?: Palette): string;
 export interface GajaePixelFrames {
     /** escape payload per logical frame (drawn at the current cursor cell) */
@@ -204,7 +213,8 @@ export interface GajaePixelFrames {
  * iTerm2 receives unitless `width=columns;height=rasterRows`, so it resolves the
  * padded block with its live cell metrics. The PNG has that block's pixel aspect
  * ratio, allowing `preserveAspectRatio=0` without stretching the authored square
- * sprite. Kitty and Sixel retain their protocol-specific paths.
+ * sprite. Kitty transmits the same PNG through a single kitty escape; Sixel
+ * keeps its own encoder.
  */
 export declare function buildGajaePixelFrames(options: {
     protocol: "sixel" | "kitty" | "iterm2";

package/dist/types/terminal-capabilities.d.ts

@@ -120,6 +120,14 @@ export interface ImageRenderOptions {
 export declare function kittyImageId(base64Data: string): number;
 export declare function getCellDimensions(): CellDimensions;
 export declare function setCellDimensions(dims: CellDimensions): void;
+/**
+ * Encode one kitty transmission behind `header` (the control string without a
+ * chunk flag), splitting the base64 payload so each escape fits
+ * {@link KITTY_MAX_ESCAPE_CHARS} and each non-final chunk keeps the protocol's
+ * 4-byte base64 quantum. A payload that fits in one escape carries no `m=`
+ * field at all.
+ */
+export declare function encodeKittyTransmission(header: string, base64Data: string): string;
 export declare function encodeKitty(base64Data: string, options?: {
     columns?: number;
     rows?: number;
@@ -136,7 +144,8 @@ export declare function resetKittyTransmissions(): void;
 export declare function setKittyTransmitWriter(writer: (sequence: string) => void): void;
 /**
  * Encode a kitty transmit-only (`a=t`) escape: uploads image data under a
- * stable id without creating a placement. Chunked at 4096 bytes per spec.
+ * stable id without creating a placement. Chunked so every escape stays within
+ * {@link KITTY_MAX_ESCAPE_CHARS}.
  *
  * This is deliberately separate from placement: re-sending data (`a=t`/`a=T`)
  * for an existing image id deletes the image and ALL of its placements, so

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.18.12",
+	"version": "0.19.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.18.12",
-		"@gajae-code/utils": "0.18.12",
+		"@gajae-code/natives": "0.19.0",
+		"@gajae-code/utils": "0.19.0",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/components/gajae-pet.ts

@@ -1,6 +1,6 @@
 import * as zlib from "node:zlib";
 
-import { encodeITerm2Multipart, wrapITerm2RecordsForTmux } from "../terminal-capabilities";
+import { encodeITerm2Multipart, encodeKittyTransmission, wrapITerm2RecordsForTmux } from "../terminal-capabilities";
 import {
 	OUROBOROS_HEART_STEPS,
 	OUROBOROS_IDLE_STEPS,
@@ -110,8 +110,9 @@ const OUROBOROS_PALETTE: Palette = {
 
 // ------------------------------------------------------------------------
 // Real-pixel frames (codex-pets style): the same grids encoded as terminal
-// image escapes, for absolute-positioned overlay rendering. No PNG round
-// trip — sixel and kitty raw-RGBA are generated straight from the grids.
+// image escapes, for absolute-positioned overlay rendering. Sixel is encoded
+// straight from the grids; kitty and iTerm2 both ship a losslessly rasterized
+// PNG so the upload stays a single, small escape.
 // ------------------------------------------------------------------------
 
 // 16x16 full-body grids used by the pixel pet -----------------------------
@@ -737,7 +738,7 @@ function pngChunk(type: string, data: Uint8Array): Uint8Array {
 	return out;
 }
 
-function validatePngGrid(
+function validatePixelGrid(
 	grid: string[],
 	scale: number,
 	topPaddingPx: number,
@@ -755,17 +756,16 @@ function validatePngGrid(
 	const gridHeight = grid.length;
 	const gridWidth = grid[0]?.length ?? 0;
 	if (gridHeight === 0 || gridWidth === 0 || grid.some(row => row.length !== gridWidth)) {
-		throw new Error("iTerm2 pet grid must be non-empty and rectangular");
+		throw new Error("pet grid must be non-empty and rectangular");
 	}
-	if (!Number.isFinite(scale) || scale <= 0) throw new Error("iTerm2 pet scale must be finite and positive");
+	if (!Number.isFinite(scale) || scale <= 0) throw new Error("pet scale must be finite and positive");
 	for (const [name, value] of [
 		["top padding", topPaddingPx],
 		["bottom padding", bottomPaddingPx],
 		["left padding", leftPaddingPx],
 		["right padding", rightPaddingPx],
 	] as const) {
-		if (!Number.isSafeInteger(value) || value < 0)
-			throw new Error(`iTerm2 pet ${name} must be a non-negative integer`);
+		if (!Number.isSafeInteger(value) || value < 0) throw new Error(`pet ${name} must be a non-negative integer`);
 	}
 	const spriteWidth = Math.round(gridWidth * scale);
 	const spriteHeight = Math.round(gridHeight * scale);
@@ -783,46 +783,35 @@ function validatePngGrid(
 		width > MAX_PET_PNG_DIMENSION ||
 		height > MAX_PET_PNG_DIMENSION
 	) {
-		throw new Error("iTerm2 pet PNG dimensions are out of bounds");
+		throw new Error("pet PNG dimensions are out of bounds");
 	}
 	const stride = width * 4 + 1;
 	const rawBytes = stride * height;
 	if (!Number.isSafeInteger(rawBytes) || rawBytes > MAX_PET_PNG_RAW_BYTES) {
-		throw new Error("iTerm2 pet PNG allocation is out of bounds");
+		throw new Error("pet PNG allocation is out of bounds");
 	}
 	return { gridWidth, gridHeight, spriteWidth, spriteHeight, width, height };
 }
 
 /**
- * Encode a grid as an iTerm2 inline PNG spanning a terminal cell block.
+ * Rasterize a pet grid into a lossless PNG canvas.
  *
- * The escape's `width`/`height` are the reserved cell-block footprint in
- * character cells (unitless numbers per the iTerm2 inline-images protocol).
- * iTerm2 resolves cells against its own live font metrics, so the sprite
- * scales with the real terminal geometry — including Retina, where iTerm2
- * divides `Npx` values by the backing-scale factor and would render a fixed
- * pixel box at half size.
+ * Both terminal pixel protocols consume PNG: iTerm2 inline images require it,
+ * and kitty's PNG transmission keeps a 36x36 sprite under ~300 base64
+ * characters — a single APC escape. Kitty raw-RGBA (`f=32`) instead needs
+ * multi-chunk transmissions of ~7 KB per frame, and a terminal that abandons a
+ * chunk mid-payload prints the remaining base64 into the transcript.
  */
-export function encodeGridIterm2(
+function encodePixelPng(
 	grid: string[],
 	scale: number,
-	columns: number,
-	rows: number,
-	topPaddingPx = 0,
-	bottomPaddingPx = 0,
-	leftPaddingPx = 0,
-	rightPaddingPx = 0,
-	palette: Palette = RED_PALETTE,
-): string {
-	for (const [name, value] of [
-		["column count", columns],
-		["row count", rows],
-	] as const) {
-		if (!Number.isSafeInteger(value) || value <= 0) {
-			throw new Error(`iTerm2 pet ${name} must be a positive integer`);
-		}
-	}
-	const { gridWidth, gridHeight, spriteWidth, spriteHeight, width, height } = validatePngGrid(
+	topPaddingPx: number,
+	bottomPaddingPx: number,
+	leftPaddingPx: number,
+	rightPaddingPx: number,
+	palette: Palette,
+): Buffer {
+	const { gridWidth, gridHeight, spriteWidth, spriteHeight, width, height } = validatePixelGrid(
 		grid,
 		scale,
 		topPaddingPx,
@@ -863,6 +852,39 @@ export function encodeGridIterm2(
 		pngChunk("IDAT", compressed),
 		pngChunk("IEND", new Uint8Array()),
 	]);
+	return png;
+}
+
+/**
+ * Encode a grid as an iTerm2 inline PNG spanning a terminal cell block.
+ *
+ * The escape's `width`/`height` are the reserved cell-block footprint in
+ * character cells (unitless numbers per the iTerm2 inline-images protocol).
+ * iTerm2 resolves cells against its own live font metrics, so the sprite
+ * scales with the real terminal geometry — including Retina, where iTerm2
+ * divides `Npx` values by the backing-scale factor and would render a fixed
+ * pixel box at half size.
+ */
+export function encodeGridIterm2(
+	grid: string[],
+	scale: number,
+	columns: number,
+	rows: number,
+	topPaddingPx = 0,
+	bottomPaddingPx = 0,
+	leftPaddingPx = 0,
+	rightPaddingPx = 0,
+	palette: Palette = RED_PALETTE,
+): string {
+	for (const [name, value] of [
+		["column count", columns],
+		["row count", rows],
+	] as const) {
+		if (!Number.isSafeInteger(value) || value <= 0) {
+			throw new Error(`iTerm2 pet ${name} must be a positive integer`);
+		}
+	}
+	const png = encodePixelPng(grid, scale, topPaddingPx, bottomPaddingPx, leftPaddingPx, rightPaddingPx, palette);
 	// Size in character cells, not pixels: iTerm2 applies its own cell metrics
 	// (and divides px values by the Retina backing scale), so cells keep the
 	// padded canvas 1:1 with the reserved block at every geometry.
@@ -872,7 +894,16 @@ export function encodeGridIterm2(
 	return `\x1b]1337;File=${params}:${png.toString("base64")}\x1b\\`;
 }
 
-/** Encode a bottom-aligned grid as kitty raw RGBA at `scale`. */
+/**
+ * Encode a bottom-aligned grid as a kitty PNG transmission at `scale`.
+ *
+ * The canvas is padded to the full cell block (`cols * cellWidthPx`) so the
+ * square sprite renders 1:1 inside it. A PNG-encoded sprite is a few hundred
+ * base64 characters, so the upload stays inside one APC escape; raw RGBA
+ * (`f=32`) would need several ~4 KB chunk continuations per animation frame,
+ * and a terminal that drops one prints the remaining base64 into the
+ * transcript.
+ */
 export function encodeGridKitty(
 	grid: string[],
 	scale: number,
@@ -885,47 +916,13 @@ export function encodeGridKitty(
 	rightPaddingPx = 0,
 	palette: Palette = RED_PALETTE,
 ): string {
-	const gw = grid[0].length;
-	const gh = grid.length;
-	const spriteW = Math.round(gw * scale);
-	// Pad the canvas to the full cell block (cols*cellWidth) so the square sprite
-	// renders 1:1 within it.
-	const w = spriteW + leftPaddingPx + rightPaddingPx;
-	const h = Math.round(gh * scale) + topPaddingPx;
-	const rgba = new Uint8Array(w * h * 4);
-	for (let y = 0; y < h; y++) {
-		for (let x = 0; x < w; x++) {
-			const sourceX = x - leftPaddingPx;
-			const sourceY = y - topPaddingPx;
-			const rgb =
-				sourceX < 0 || sourceX >= spriteW || sourceY < 0
-					? null
-					: palette[
-							grid[Math.min(gh - 1, Math.floor(sourceY / scale))][Math.min(gw - 1, Math.floor(sourceX / scale))]
-						];
-			if (!rgb) continue;
-			const o = (y * w + x) * 4;
-			rgba[o] = rgb[0];
-			rgba[o + 1] = rgb[1];
-			rgba[o + 2] = rgb[2];
-			rgba[o + 3] = 255;
-		}
-	}
-	const data = Buffer.from(rgba).toString("base64");
-	const CHUNK = 4000;
+	const png = encodePixelPng(grid, scale, topPaddingPx, 0, leftPaddingPx, rightPaddingPx, palette);
 	// `Y=` offsets the sprite down by sub-cell pixels within the first cell — the
 	// kitty analogue of the sixel top-padding drop. `C=1` keeps the placement
 	// cursor-neutral so the overlay never nudges the composer's real cursor.
 	const yParam = cellYOffsetPx > 0 ? `,Y=${Math.round(cellYOffsetPx)}` : "";
-	let out = `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
-	for (let off = 0, first = true; off < data.length; off += CHUNK, first = false) {
-		const chunk = data.slice(off, off + CHUNK);
-		const more = off + CHUNK < data.length ? 1 : 0;
-		out += first
-			? `\x1b_Ga=T,f=32,s=${w},v=${h},c=${cols},r=${rows},i=${imageId},q=2,C=1${yParam},m=${more};${chunk}\x1b\\`
-			: `\x1b_Gm=${more};${chunk}\x1b\\`;
-	}
-	return out;
+	const control = `a=T,f=100,c=${cols},r=${rows},i=${imageId},q=2,C=1${yParam}`;
+	return `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\${encodeKittyTransmission(control, png.toString("base64"))}`;
 }
 
 export interface GajaePixelFrames {
@@ -957,7 +954,8 @@ export interface GajaePixelFrames {
  * iTerm2 receives unitless `width=columns;height=rasterRows`, so it resolves the
  * padded block with its live cell metrics. The PNG has that block's pixel aspect
  * ratio, allowing `preserveAspectRatio=0` without stretching the authored square
- * sprite. Kitty and Sixel retain their protocol-specific paths.
+ * sprite. Kitty transmits the same PNG through a single kitty escape; Sixel
+ * keeps its own encoder.
  */
 export function buildGajaePixelFrames(options: {
 	protocol: "sixel" | "kitty" | "iterm2";

package/src/components/markdown.ts

@@ -1,3 +1,6 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
 import { LRUCache } from "lru-cache/raw";
 import { Marked, marked, type Token, Tokenizer, type Tokens } from "marked";
 import { hasSvgFence, isClosedSvgFence } from "../chat/svg-source";
@@ -455,17 +458,78 @@ type ListToken = Token & { items: Array<{ tokens?: Token[] }>; ordered: boolean;
 type TableCellToken = { tokens?: Token[] };
 type TableToken = Token & { header: TableCellToken[]; rows: TableCellToken[][]; raw?: string };
 
+/** Relative markdown links follow the active session's process cwd and home. */
+function markdownLinkContextKey(): string {
+	let cwd = "<unavailable>";
+	let home = "<unavailable>";
+	try {
+		cwd = process.cwd();
+	} catch {}
+	try {
+		home = os.homedir();
+	} catch {}
+	return `${cwd}\x00${home}`;
+}
+
+/** Decodes valid `%XX` runs; a `%` that does not start a valid UTF-8 escape stays a literal percent sign. */
+function decodePercentEscapes(value: string): string {
+	return value.replace(/(?:%[0-9a-f]{2})+/giu, escapes => {
+		try {
+			return decodeURIComponent(escapes);
+		} catch {
+			return escapes;
+		}
+	});
+}
+
+/**
+ * Converts a local Markdown link destination to an absolute `file://` URI. The destination is a URI
+ * reference: its path may be percent-encoded, and `?` or `#` starts the query or fragment, which stay
+ * URI components instead of becoming part of the filename.
+ */
+function localFileUri(target: string): string {
+	const suffixStart = target.search(/[?#]/u);
+	const pathPart = suffixStart === -1 ? target : target.slice(0, suffixStart);
+	const suffix = suffixStart === -1 ? "" : target.slice(suffixStart);
+	const filePath = decodePercentEscapes(pathPart);
+	let absolutePath: string;
+	if (path.isAbsolute(filePath)) {
+		absolutePath = filePath;
+	} else if (filePath === "~") {
+		absolutePath = os.homedir();
+	} else if (filePath.startsWith("~/")) {
+		absolutePath = path.resolve(os.homedir(), filePath.slice(2));
+	} else {
+		absolutePath = path.resolve(process.cwd(), filePath);
+	}
+	const fileUrl = url.pathToFileURL(absolutePath);
+	return suffix ? new URL(suffix, fileUrl).href : fileUrl.href;
+}
+
 function formatHyperlink(text: string, target: string): string {
 	if (!TERMINAL.hyperlinks || !target) {
 		return text;
 	}
 
-	const safeTarget = target.replaceAll("\x1b", "").replaceAll("\x07", "");
-	if (!safeTarget) {
+	if (/[\u0000-\u001f\u007f-\u009f]/u.test(target)) {
 		return text;
 	}
 
-	return `\x1b]8;;${safeTarget}\x07${text}\x1b]8;;\x07`;
+	// `#fragment` and `//authority/path` (network-path reference) are URI references, not local paths.
+	let destination = target;
+	if (
+		!target.startsWith("#") &&
+		!target.startsWith("//") &&
+		(path.isAbsolute(target) || !/^[a-z][a-z\d+.-]*:/iu.test(target))
+	) {
+		try {
+			destination = localFileUri(target);
+		} catch {
+			return text;
+		}
+	}
+
+	return `\x1b]8;;${destination}\x07${text}\x1b]8;;\x07`;
 }
 
 function stripHtmlComments(raw: string): string {
@@ -525,6 +589,7 @@ export class Markdown implements Component {
 	#hasActiveDynamicSvgFigures = false;
 	#hasRetryableSvgFigureFallback = false;
 	#cachedImageProtocol: typeof TERMINAL.imageProtocol | undefined;
+	#cachedLinkContextKey?: string;
 	#dynamicFigures = new Map<number, Component>();
 	#nextDynamicFigureIndex = 0;
 	#disposed = false;
@@ -735,6 +800,8 @@ export class Markdown implements Component {
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
 		const copyEnabled = copyAnnotationsEnabled();
+		// Only bracketed Markdown can contain a link target; plain text stays shared.
+		const linkContextKey = this.#text.includes("]") ? markdownLinkContextKey() : "";
 		if (
 			!this.#hasActiveDynamicSvgFigures &&
 			!this.#hasRetryableSvgFigureFallback &&
@@ -743,6 +810,7 @@ export class Markdown implements Component {
 			this.#cachedText === this.#text &&
 			this.#cachedWidth === width &&
 			this.#cachedImageProtocol === TERMINAL.imageProtocol &&
+			this.#cachedLinkContextKey === linkContextKey &&
 			this.#cachedCopyEnabled === copyEnabled &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
 		) {
@@ -759,6 +827,7 @@ export class Markdown implements Component {
 			this.#cachedLines &&
 			this.#cachedWidth === width &&
 			this.#cachedImageProtocol === TERMINAL.imageProtocol &&
+			this.#cachedLinkContextKey === linkContextKey &&
 			this.#cachedCopyEnabled === copyEnabled &&
 			this.#lastFullParseAt > 0 &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
@@ -787,6 +856,7 @@ export class Markdown implements Component {
 			this.#cachedCopyEnabled = copyEnabled;
 			this.#cachedAnchorSpans = includeAnchors ? [] : undefined;
 			this.#cachedImageProtocol = TERMINAL.imageProtocol;
+			this.#cachedLinkContextKey = linkContextKey;
 			return { lines: result, spans: this.#cachedAnchorSpans };
 		}
 
@@ -812,7 +882,8 @@ export class Markdown implements Component {
 		// and verify it on hit so hash collisions can never serve wrong output.
 		const bgColorProbe = this.#defaultTextStyle?.bgColor ? this.#defaultTextStyle.bgColor("\x01") : "";
 		const headingProbe = this.#theme.heading("");
-		const cacheKey = `${renderContentKey}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
+		const linkContextSuffix = linkContextKey ? `\x00${linkContextKey}` : "";
+		const cacheKey = `${renderContentKey}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}${linkContextSuffix}\x00${bgColorProbe}\x00${headingProbe}`;
 		const cached = renderCache.get(cacheKey);
 		if (
 			!this.#mayHaveDynamicSvgFigures &&
@@ -828,6 +899,7 @@ export class Markdown implements Component {
 			this.#cachedLines = lines;
 			this.#cachedAnchorSpans = cached.anchorSpans;
 			this.#cachedImageProtocol = TERMINAL.imageProtocol;
+			this.#cachedLinkContextKey = linkContextKey;
 			if (!this.#streaming || this.#currentParse?.source !== normalizedText) this.#currentParse = undefined;
 			return { lines, spans: cached.anchorSpans };
 		}
@@ -1237,12 +1309,14 @@ export class Markdown implements Component {
 			this.#cachedLines = undefined;
 			this.#cachedAnchorSpans = undefined;
 			this.#cachedImageProtocol = undefined;
+			this.#cachedLinkContextKey = undefined;
 		} else {
 			this.#cachedText = renderedText;
 			this.#cachedWidth = width;
 			this.#cachedLines = copyBoundResult;
 			this.#cachedAnchorSpans = anchorSpans;
 			this.#cachedImageProtocol = TERMINAL.imageProtocol;
+			this.#cachedLinkContextKey = linkContextKey;
 			this.#lastFullParseAt = markdownNow();
 		}
 

package/src/terminal-capabilities.ts

@@ -404,6 +404,79 @@ export function setCellDimensions(dims: CellDimensions): void {
 	cellDimensions = dims;
 }
 
+/**
+ * Kitty caps a single APC escape at 4096 bytes, and every chunk except the last
+ * must carry a payload that is a multiple of 4 bytes (each chunk is decoded as
+ * its own base64 group). An escape that the terminal abandons mid-payload
+ * surfaces the remaining base64 as printable text in the transcript, so chunks
+ * are sized against the whole escape (introducer + control + `;` + data + ST)
+ * rather than against the data alone.
+ */
+const KITTY_MAX_ESCAPE_CHARS = 4096;
+/** `\x1b_G` + `;` + `\x1b\\` — the bytes around one chunk's control and data. */
+const KITTY_ESCAPE_FRAME_CHARS = 3 + 1 + 2;
+const KITTY_CHUNK_FLAG_CHARS = ",m=1".length;
+
+/**
+ * RFC 4648 base64, the same guard `encodeITerm2Multipart` already applies.
+ * The alphabet excludes ESC, ST, and BEL, so a payload cannot end an APC or OSC early.
+ * A linear scan, not a repeating-group regex: that regex rejects some multi-megabyte
+ * valid payloads in this runtime.
+ */
+function isBase64Alphabet(code: number): boolean {
+	return (
+		(code >= 65 && code <= 90) ||
+		(code >= 97 && code <= 122) ||
+		(code >= 48 && code <= 57) ||
+		code === 43 ||
+		code === 47
+	);
+}
+
+function isRfc4648Base64(value: string): boolean {
+	const length = value.length;
+	if (length % 4 !== 0) return false;
+	let body = length;
+	if (length > 0 && value.charCodeAt(length - 1) === 61) {
+		body = value.charCodeAt(length - 2) === 61 ? length - 2 : length - 1;
+	}
+	for (let index = 0; index < body; index++) {
+		if (!isBase64Alphabet(value.charCodeAt(index))) return false;
+	}
+	return true;
+}
+
+function assertIterm2Base64(value: string): void {
+	if (!isRfc4648Base64(value)) throw new Error("Invalid RFC 4648 base64");
+}
+
+/**
+ * Encode one kitty transmission behind `header` (the control string without a
+ * chunk flag), splitting the base64 payload so each escape fits
+ * {@link KITTY_MAX_ESCAPE_CHARS} and each non-final chunk keeps the protocol's
+ * 4-byte base64 quantum. A payload that fits in one escape carries no `m=`
+ * field at all.
+ */
+export function encodeKittyTransmission(header: string, base64Data: string): string {
+	assertIterm2Base64(base64Data);
+	const whole = `\x1b_G${header};${base64Data}\x1b\\`;
+	if (whole.length <= KITTY_MAX_ESCAPE_CHARS) return whole;
+	const chunks: string[] = [];
+	let offset = 0;
+	let first = true;
+	while (offset < base64Data.length) {
+		const budget =
+			KITTY_MAX_ESCAPE_CHARS - KITTY_ESCAPE_FRAME_CHARS - KITTY_CHUNK_FLAG_CHARS - (first ? header.length : 0);
+		const chunkSize = Math.max(4, budget - (budget % 4));
+		const chunk = base64Data.slice(offset, offset + chunkSize);
+		offset += chunk.length;
+		const more = offset < base64Data.length ? 1 : 0;
+		chunks.push(`\x1b_G${first ? `${header},m=${more}` : `m=${more}`};${chunk}\x1b\\`);
+		first = false;
+	}
+	return chunks.join("");
+}
+
 export function encodeKitty(
 	base64Data: string,
 	options: {
@@ -413,8 +486,6 @@ export function encodeKitty(
 		placementId?: number;
 	} = {},
 ): string {
-	const CHUNK_SIZE = 4096;
-
 	const params: string[] = ["a=T", "f=100", "q=2"];
 
 	if (options.columns) params.push(`c=${options.columns}`);
@@ -427,31 +498,7 @@ export function encodeKitty(
 		if (options.placementId) params.push(`p=${options.placementId}`);
 	}
 
-	if (base64Data.length <= CHUNK_SIZE) {
-		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
-	}
-
-	const chunks: string[] = [];
-	let offset = 0;
-	let isFirst = true;
-
-	while (offset < base64Data.length) {
-		const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
-		const isLast = offset + CHUNK_SIZE >= base64Data.length;
-
-		if (isFirst) {
-			chunks.push(`\x1b_G${params.join(",")},m=1;${chunk}\x1b\\`);
-			isFirst = false;
-		} else if (isLast) {
-			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
-		} else {
-			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
-		}
-
-		offset += CHUNK_SIZE;
-	}
-
-	return chunks.join("");
+	return encodeKittyTransmission(params.join(","), base64Data);
 }
 
 /** Kitty image ids already uploaded to the terminal in this process. */
@@ -477,7 +524,8 @@ export function setKittyTransmitWriter(writer: (sequence: string) => void): void
 
 /**
  * Encode a kitty transmit-only (`a=t`) escape: uploads image data under a
- * stable id without creating a placement. Chunked at 4096 bytes per spec.
+ * stable id without creating a placement. Chunked so every escape stays within
+ * {@link KITTY_MAX_ESCAPE_CHARS}.
  *
  * This is deliberately separate from placement: re-sending data (`a=t`/`a=T`)
  * for an existing image id deletes the image and ALL of its placements, so
@@ -485,34 +533,7 @@ export function setKittyTransmitWriter(writer: (sequence: string) => void): void
  * {@link encodeKittyPlacement} only.
  */
 export function encodeKittyTransmit(base64Data: string, imageId: number): string {
-	const CHUNK_SIZE = 4096;
-	const params = ["a=t", "f=100", "q=2", `i=${imageId}`];
-
-	if (base64Data.length <= CHUNK_SIZE) {
-		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
-	}
-
-	const chunks: string[] = [];
-	let offset = 0;
-	let isFirst = true;
-
-	while (offset < base64Data.length) {
-		const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
-		const isLast = offset + CHUNK_SIZE >= base64Data.length;
-
-		if (isFirst) {
-			chunks.push(`\x1b_G${params.join(",")},m=1;${chunk}\x1b\\`);
-			isFirst = false;
-		} else if (isLast) {
-			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
-		} else {
-			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
-		}
-
-		offset += CHUNK_SIZE;
-	}
-
-	return chunks.join("");
+	return encodeKittyTransmission(["a=t", "f=100", "q=2", `i=${imageId}`].join(","), base64Data);
 }
 
 /**
@@ -603,6 +624,7 @@ export function encodeITerm2(
 		inline?: boolean;
 	} = {},
 ): string {
+	assertIterm2Base64(base64Data);
 	const params: string[] = [`inline=${options.inline !== false ? 1 : 0}`];
 
 	if (options.width !== undefined) params.push(`width=${options.width}`);
@@ -825,6 +847,7 @@ export function renderImage(
 	const fit = calculateImageFit(imageDimensions, options, cellDims);
 
 	if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+		if (!isRfc4648Base64(base64Data)) return null;
 		const imageId = options.imageId ?? kittyImageId(base64Data);
 		const placementId = options.placementId ?? 1;
 		// Upload data once per image id (out-of-band; the transmit escape is
@@ -853,6 +876,7 @@ export function renderImage(
 		}
 	}
 	if (TERMINAL.imageProtocol === ImageProtocol.Iterm2) {
+		if (!isRfc4648Base64(base64Data)) return null;
 		const sequence = encodeITerm2(base64Data, {
 			width: fit.columns,
 			height: "auto",
@@ -896,13 +920,8 @@ export function parseITerm2CapabilityReply(input: Uint8Array | string): Iterm2Ca
 	return complete ? "missing-f" : undefined;
 }
 
-const ITERM2_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
 const ITERM2_MAX_CAPABILITY_BYTES = 4096;
 
-function assertIterm2Base64(value: string): void {
-	if (value.length % 4 !== 0 || !ITERM2_BASE64.test(value)) throw new Error("Invalid RFC 4648 base64");
-}
-
 export function encodeITerm2Multipart(
 	base64Data: string,
 	options: { width?: number | string; height?: number | string } = {},