@gajae-code/tui 0.18.11 → 0.19.0

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,5 +1,9 @@
+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";
 import type { SymbolTheme } from "../symbols";
 import { TERMINAL } from "../terminal-capabilities";
 import type { Component } from "../tui";
@@ -327,10 +331,12 @@ export function resetMarkdownHighlightCallCount(): void {
 export const __markdownPerfCounters = {
 	lexerInvocations: 0,
 	lexedBytes: 0,
+	svgFenceDetectionCalls: 0,
 	highlightAdmissionScans: 0,
 	reset(): void {
 		this.lexerInvocations = 0;
 		this.lexedBytes = 0;
+		this.svgFenceDetectionCalls = 0;
 		this.highlightAdmissionScans = 0;
 	},
 };
@@ -420,9 +426,29 @@ export interface MarkdownTheme {
 	 * Return null to fall back to fenced code rendering.
 	 */
 	resolveMermaidAscii?: (source: string) => string | null;
+	/**
+	 * Resolve an SVG figure component by fenced block source text. Components
+	 * are retained by fence order. Return null for a stable fenced-code fallback
+	 * that disposes a previous component; return undefined for a fallback that
+	 * preserves the previous component and should be retried on the next render.
+	 */
+	resolveSvgFigure?: (source: string, context: SvgFigureResolveContext) => Component | null | undefined;
 	symbols: SymbolTheme;
 }
 
+export interface SvgFigureResolveContext {
+	/** Whether the containing message is still streaming. */
+	streaming: boolean;
+	/** The individual code fence has received its closing marker. */
+	closed: boolean;
+	/** Request a repaint after the figure's asynchronous output changes. */
+	onChange: () => void;
+	/** Available render width in terminal cells. */
+	width: number;
+	/** The component previously resolved for this fence position, if any. */
+	previous?: Component;
+}
+
 interface InlineStyleContext {
 	applyText: (text: string) => string;
 	stylePrefix: string;
@@ -432,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 {
@@ -496,6 +583,16 @@ export class Markdown implements Component {
 	#lastFullParseAt = 0;
 	#onStaleThrottle?: () => void;
 	#staleThrottleTimer?: ReturnType<typeof setTimeout>;
+	#mayHaveDynamicSvgFigures: boolean;
+	#svgFenceDetectionPending = false;
+	#svgResolverAvailable: boolean;
+	#hasActiveDynamicSvgFigures = false;
+	#hasRetryableSvgFigureFallback = false;
+	#cachedImageProtocol: typeof TERMINAL.imageProtocol | undefined;
+	#cachedLinkContextKey?: string;
+	#dynamicFigures = new Map<number, Component>();
+	#nextDynamicFigureIndex = 0;
+	#disposed = false;
 
 	constructor(
 		text: string,
@@ -506,6 +603,9 @@ export class Markdown implements Component {
 		codeBlockIndent: number = 2,
 	) {
 		this.#text = text;
+		this.#svgResolverAvailable = theme.resolveSvgFigure !== undefined;
+		if (this.#svgResolverAvailable) __markdownPerfCounters.svgFenceDetectionCalls++;
+		this.#mayHaveDynamicSvgFigures = this.#svgResolverAvailable && hasSvgFence(text);
 		this.#paddingX = paddingX;
 		this.#paddingY = paddingY;
 		this.#theme = theme;
@@ -522,7 +622,23 @@ export class Markdown implements Component {
 			this.setStreaming(options.streaming);
 		}
 		if (this.#text !== text) this.#rejectedParseKey = undefined;
+		const textChanged = this.#text !== text;
 		this.#text = text;
+		const svgResolverAvailable = this.#theme.resolveSvgFigure !== undefined;
+		const svgResolverChanged = svgResolverAvailable !== this.#svgResolverAvailable;
+		this.#svgResolverAvailable = svgResolverAvailable;
+		if (!svgResolverAvailable) {
+			this.#mayHaveDynamicSvgFigures = false;
+			this.#svgFenceDetectionPending = false;
+		} else if (this.#streaming) {
+			// Streaming writes already feed the throttled lexer; don't rescan the growing
+			// document here before that parse budget gets a chance to run.
+			if (textChanged || svgResolverChanged) this.#svgFenceDetectionPending = true;
+		} else {
+			__markdownPerfCounters.svgFenceDetectionCalls++;
+			this.#mayHaveDynamicSvgFigures = hasSvgFence(text);
+			this.#svgFenceDetectionPending = false;
+		}
 		if (this.#streaming) {
 			return;
 		}
@@ -560,9 +676,11 @@ export class Markdown implements Component {
 	}
 
 	dispose(): void {
+		this.#disposed = true;
 		this.#clearStaleThrottleTimer();
 		this.#currentParse = undefined;
 		this.#rejectedParseKey = undefined;
+		this.#disposeDynamicFiguresFrom(0);
 	}
 
 	invalidate(): void {
@@ -570,6 +688,48 @@ export class Markdown implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
 		this.#cachedAnchorSpans = undefined;
+		this.#lastFullParseAt = 0;
+		this.#clearStaleThrottleTimer();
+	}
+
+	#disposeDynamicFiguresFrom(startIndex: number): void {
+		for (const [index, component] of this.#dynamicFigures) {
+			if (index < startIndex) continue;
+			this.#dynamicFigures.delete(index);
+			component.dispose?.();
+		}
+	}
+
+	#resolveDynamicFigure(source: string, closed: boolean, width: number): Component | undefined {
+		const index = this.#nextDynamicFigureIndex++;
+		const previous = this.#dynamicFigures.get(index);
+		const component = this.#theme.resolveSvgFigure?.(source, {
+			streaming: this.#streaming,
+			closed,
+			width,
+			onChange: () => {
+				if (this.#disposed) return;
+				this.invalidate();
+				this.#onStaleThrottle?.();
+			},
+			previous,
+		});
+		if (component) {
+			if (previous && previous !== component) previous.dispose?.();
+			this.#dynamicFigures.set(index, component);
+			this.#hasActiveDynamicSvgFigures = true;
+			return component;
+		}
+		if (component === undefined) {
+			this.#hasRetryableSvgFigureFallback = true;
+			if (previous) this.#dynamicFigures.set(index, previous);
+		} else if (previous) {
+			// A stable fallback no longer needs the component or any raster data it
+			// retains. A future source change can create a fresh component.
+			this.#dynamicFigures.delete(index);
+			previous.dispose?.();
+		}
+		return undefined;
 	}
 
 	#exceedsHighlightCap(code: string): boolean {
@@ -635,13 +795,22 @@ export class Markdown implements Component {
 	}
 
 	#render(width: number, includeAnchors: boolean): { lines: string[]; spans?: Array<ViewportAnchorSpan | null> } {
+		if (!this.#mayHaveDynamicSvgFigures) this.#disposeDynamicFiguresFrom(0);
+
 		// 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 &&
+			!this.#svgFenceDetectionPending &&
 			this.#cachedLines &&
 			this.#cachedText === this.#text &&
 			this.#cachedWidth === width &&
+			this.#cachedImageProtocol === TERMINAL.imageProtocol &&
+			this.#cachedLinkContextKey === linkContextKey &&
 			this.#cachedCopyEnabled === copyEnabled &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
 		) {
@@ -652,9 +821,13 @@ export class Markdown implements Component {
 		const contentWidth = Math.max(1, width - this.#paddingX * 2);
 
 		if (
+			!this.#hasActiveDynamicSvgFigures &&
+			!this.#hasRetryableSvgFigureFallback &&
 			this.#streaming &&
 			this.#cachedLines &&
 			this.#cachedWidth === width &&
+			this.#cachedImageProtocol === TERMINAL.imageProtocol &&
+			this.#cachedLinkContextKey === linkContextKey &&
 			this.#cachedCopyEnabled === copyEnabled &&
 			this.#lastFullParseAt > 0 &&
 			(!includeAnchors || this.#cachedAnchorSpans !== undefined)
@@ -666,9 +839,15 @@ export class Markdown implements Component {
 			}
 		}
 
+		this.#hasActiveDynamicSvgFigures = false;
+		this.#hasRetryableSvgFigureFallback = false;
+
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
 			this.#currentParse = undefined;
+			this.#mayHaveDynamicSvgFigures = false;
+			this.#svgFenceDetectionPending = false;
+			this.#disposeDynamicFiguresFrom(0);
 			const result: string[] = [];
 			// Update per-instance cache
 			this.#cachedText = this.#text;
@@ -676,6 +855,8 @@ export class Markdown implements Component {
 			this.#cachedLines = result;
 			this.#cachedCopyEnabled = copyEnabled;
 			this.#cachedAnchorSpans = includeAnchors ? [] : undefined;
+			this.#cachedImageProtocol = TERMINAL.imageProtocol;
+			this.#cachedLinkContextKey = linkContextKey;
 			return { lines: result, spans: this.#cachedAnchorSpans };
 		}
 
@@ -701,9 +882,12 @@ 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 &&
+			!this.#svgFenceDetectionPending &&
 			cached !== undefined &&
 			cached.source === renderCacheSource &&
 			(!includeAnchors || cached.anchorSpans !== undefined)
@@ -714,6 +898,8 @@ export class Markdown implements Component {
 			const lines = this.#bindCopySource(cached.lines, copyEnabled);
 			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 };
 		}
@@ -732,6 +918,13 @@ export class Markdown implements Component {
 			__markdownPerfCounters.lexedBytes += normalizedText.length;
 			tokens = markdownParser.lexer(normalizedText);
 		}
+		this.#mayHaveDynamicSvgFigures =
+			this.#theme.resolveSvgFigure !== undefined &&
+			tokens.some(token => {
+				if (token.type !== "code") return false;
+				return token.lang?.trim().split(/[ \t]/, 1)[0]?.toLowerCase() === "svg";
+			});
+		this.#svgFenceDetectionPending = false;
 		if (this.#streaming && this.#text === renderedText) {
 			this.#currentParse = { source: normalizedText, tokens };
 		}
@@ -778,6 +971,7 @@ export class Markdown implements Component {
 			codeSource?: string;
 		}> = [];
 		let srcOffset = 0;
+		this.#nextDynamicFigureIndex = 0;
 
 		for (let i = 0; i < tokens.length; i++) {
 			const token = tokens[i];
@@ -810,6 +1004,7 @@ export class Markdown implements Component {
 					codeTexts.length > 0 && codeTexts.every(text => text !== undefined) ? codeTexts.join("\n") : undefined,
 			});
 		}
+		this.#disposeDynamicFiguresFrom(this.#nextDynamicFigureIndex);
 
 		let wrappedLines: string[];
 		let wrappedSpans: Array<ViewportAnchorSpan | null> | undefined;
@@ -1104,17 +1299,30 @@ export class Markdown implements Component {
 		}
 		if (!this.#streaming || this.#text !== renderedText) this.#currentParse = undefined;
 
-		// Update L1 per-instance cache
-		this.#cachedText = renderedText;
-		this.#cachedWidth = width;
+		// Active figures and retryable fallbacks must render again. A stable
+		// fenced-code fallback is safe in this instance's L1 cache, but possible
+		// SVG fences stay out of shared L2 because resolver state can vary by instance.
 		const copyBoundResult = this.#bindCopySource(result, copyEnabled);
-		this.#cachedLines = copyBoundResult;
-		this.#cachedAnchorSpans = anchorSpans;
-		this.#lastFullParseAt = markdownNow();
+		if (this.#hasActiveDynamicSvgFigures || this.#hasRetryableSvgFigureFallback) {
+			this.#cachedText = undefined;
+			this.#cachedWidth = undefined;
+			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();
+		}
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		if (!this.#streaming) {
+		if (!this.#streaming && !this.#mayHaveDynamicSvgFigures) {
 			renderCache.set(cacheKey, {
 				source: renderCacheSource,
 				lines: result,
@@ -1229,6 +1437,7 @@ export class Markdown implements Component {
 		nextTokenType?: string,
 		styleContext?: InlineStyleContext,
 		units?: number[],
+		allowSvgFigure = true,
 	): string[] {
 		const lines: string[] = [];
 
@@ -1278,6 +1487,22 @@ export class Markdown implements Component {
 					}
 				}
 
+				// Handle SVG figures when available. Marked keeps the complete info
+				// string in token.lang, so match its normalized language token.
+				const language = token.lang?.trim().split(/[ \t]/, 1)[0]?.toLowerCase();
+				if (allowSvgFigure && language === "svg" && this.#theme.resolveSvgFigure) {
+					const figure = this.#resolveDynamicFigure(token.text, isClosedSvgFence(token.raw), width);
+					if (figure) {
+						// SVG figures are components that render directly
+						const figureLines = figure.render(width);
+						lines.push(...figureLines);
+						if (nextTokenType && nextTokenType !== "space") {
+							lines.push("");
+						}
+						break;
+					}
+				}
+
 				const codeIndent = padding(this.#codeBlockIndent);
 				this.#emitCodeBlock(lines, token, token.text, token.lang || "", codeIndent);
 				if (nextTokenType && nextTokenType !== "space") {
@@ -1334,6 +1559,8 @@ export class Markdown implements Component {
 						quoteContentWidth,
 						nextQuoteToken?.type,
 						quoteInlineStyleContext,
+						undefined,
+						false,
 					);
 					for (let c = 0; c < childLines.length; c++) quoteLineUnit.push(i);
 					renderedQuoteLines.push(...childLines);