@linxiraos/pi-tui 1.1.27 → 1.2.0

package/src/chat/svg-figure.ts

@@ -0,0 +1,399 @@
+/**
+ * A ```svg fence drawn as an inline terminal image. The source is rasterized
+ * off the JS thread and shown through {@link Image}; while the fence streams,
+ * each throttled revision repairs the partial source and replaces the
+ * previous raster, which stays on screen until the next one lands.
+ *
+ * Sizing is natural rather than preview-capped: one terminal row spans
+ * {@link UNITS_PER_ROW} SVG user units, so `font-size="14"` text lands near
+ * the terminal's own glyph size and the figure takes as many columns as its
+ * drawing needs — up to the full width, and a viewport-relative height. The
+ * raster is drawn at the terminal's device pixels per unit, padded to whole
+ * cells, and redrawn when the room it is shown in changes, so the terminal
+ * places it 1:1: any resampling, even 0.99×, blurs every glyph edge.
+ */
+import { rasterizeSvg } from "@linxiraos/pi-natives";
+import { hexToOklch, hueDistance, logger, oklchCusp, oklchToHex } from "@linxiraos/pi-utils";
+import { Image, type ImageBudget, imageMaxColumns } from "../components/image";
+import { fencedCode, type Markdown } from "../components/markdown";
+import { type CellDimensions, getCellDimensions, getImageDimensions } from "../terminal-capabilities";
+import { getThemeEpoch, type ThemeColor, theme } from "../theme";
+import type { Component } from "../tui";
+import { closePartialSvg, prepareSvg } from "./svg-source";
+
+/** SVG user units per terminal row; a 1000-unit-wide drawing spans ~125 columns of 1:2 cells. */
+const UNITS_PER_ROW = 16;
+/** Least time between rasters of a fence that is still streaming. */
+const STREAM_INTERVAL_MS = 200;
+/** Longest raster edge; the native rasterizer caps the surface at 4096² pixels. */
+const MAX_EDGE_PX = 4096;
+/** Share of the terminal's rows one figure may fill, so it fits on screen whole. */
+const MAX_VIEWPORT_SHARE = 0.8;
+
+/**
+ * Foreground theme colors behind the figure tokens (`var(--name)`); `surface`
+ * is the selection background and `c1`…`c6` come from {@link seriesColors}.
+ */
+const PALETTE: Readonly<Record<string, ThemeColor>> = {
+	fg: "text",
+	muted: "muted",
+	border: "borderMuted",
+	accent: "accent",
+	success: "success",
+	warning: "warning",
+	error: "error",
+};
+
+/** Hue families (OKLCH degrees) the series colors draw from: blue, orange, green, purple, pink, teal. */
+const SERIES_HUES = [255, 55, 145, 305, 0, 200];
+/** Gold, for a sixth series when the accent's hue crowds out two families. */
+const RESERVE_HUE = 90;
+/** Least hue distance between a family and the accent's hue for both to lead series. */
+const MIN_SERIES_HUE_GAP = 30;
+/** Chroma below which the accent reads as gray and blue leads instead. */
+const MIN_ACCENT_CHROMA = 0.04;
+/** Lightness band of series colors: deep enough for labels on light surfaces, bright enough on dark ones. */
+const SERIES_LIGHTNESS = { light: [0.52, 0.66], dark: [0.68, 0.82] } as const;
+/** Chroma ceiling: vivid, not neon. */
+const SERIES_CHROMA = 0.19;
+
+/** The active theme's color per figure token, for resolving a figure with `prepareSvg`. */
+export function svgFigurePalette(): Record<string, string> {
+	const palette: Record<string, string> = { surface: theme.getBgHex("selectedBg") };
+	for (const token in PALETTE) palette[token] = theme.getColorHex(PALETTE[token]!);
+	seriesColors(palette.accent!, theme.isLight).forEach((color, at) => {
+		palette[`c${at + 1}`] = color;
+	});
+	return palette;
+}
+
+/**
+ * Six series colors of even visual weight, in the manner of Apple's system
+ * palette: led by the theme accent's hue (blue when the accent is gray), each
+ * next hue the family farthest from those already taken. Every hue sits at
+ * its gamut cusp clamped into the theme's {@link SERIES_LIGHTNESS} band, so
+ * orange stays orange and blue stays deep.
+ */
+function seriesColors(accent: string, light: boolean): string[] {
+	const { c, h } = hexToOklch(accent);
+	const lead = c >= MIN_ACCENT_CHROMA ? h : SERIES_HUES[0]!;
+	const hues = [lead];
+	const pool = SERIES_HUES.filter(hue => hueDistance(hue, lead) >= MIN_SERIES_HUE_GAP);
+	while (pool.length > 0) {
+		const gaps = pool.map(hue => Math.min(...hues.map(taken => hueDistance(hue, taken))));
+		hues.push(pool.splice(gaps.indexOf(Math.max(...gaps)), 1)[0]!);
+	}
+	if (hues.length < 6) hues.push(RESERVE_HUE);
+	const [low, high] = SERIES_LIGHTNESS[light ? "light" : "dark"];
+	return hues.slice(0, 6).map(hue => {
+		const cusp = oklchCusp(hue);
+		return oklchToHex({ l: Math.min(high, Math.max(low, cusp.l)), c: Math.min(SERIES_CHROMA, cusp.c), h: hue });
+	});
+}
+
+let figuresEnabled = true;
+
+/** Turn lifting ```svg fences into images on or off (the host's `tui.renderSvg`); the host rebuilds the transcript after. */
+export function setSvgFigureRendering(enabled: boolean): void {
+	figuresEnabled = enabled;
+}
+
+/** Whether assistant ```svg fences render as images where the terminal can show them. */
+export function svgFigureRendering(): boolean {
+	return figuresEnabled;
+}
+
+export interface SvgFigureOptions {
+	/**
+	 * Markdown for the fenced-code fallback shown when the final source does not
+	 * render. Without it the figure decorates content shown elsewhere (a chart
+	 * under its table): it stays blank until drawn, and when it cannot be.
+	 */
+	markdown?: (text: string) => Markdown;
+	/** Shared inline-image budget; superseded rasters are released from it. */
+	budget?: ImageBudget;
+	/** The figure's rows changed outside a text update: a raster landed or rendering fell back to code. */
+	onChange: () => void;
+}
+
+/** Cells a figure may fill. */
+interface Limits {
+	columns: number;
+	rows: number;
+}
+
+/** One rasterized revision and the inputs that produced it. */
+interface Raster {
+	source: string;
+	/** Cell size the raster was padded to; its pixels are whole cells of it. */
+	cell: CellDimensions;
+	limits: Limits;
+	themeEpoch: number;
+	/** Base64 PNG. */
+	data: string;
+	widthPx: number;
+	heightPx: number;
+	/** Budget key; one per revision so a new raster is a new terminal image. */
+	key: string;
+}
+
+/** Inputs of a raster attempt, successful or not. */
+interface Attempt {
+	source: string;
+	cell: CellDimensions;
+	limits: Limits;
+	themeEpoch: number;
+	final: boolean;
+}
+
+let nextFigureId = 0;
+
+/** Cells a figure rendered at `width` may fill: the image's width, a share of the viewport, and the raster edge cap. */
+function limitsFor(width: number, cell: CellDimensions): Limits {
+	const viewportRows = Math.floor((process.stdout.rows || 24) * MAX_VIEWPORT_SHARE);
+	return {
+		columns: Math.min(imageMaxColumns(width), Math.floor(MAX_EDGE_PX / cell.widthPx)),
+		rows: Math.max(1, Math.min(viewportRows, Math.floor(MAX_EDGE_PX / cell.heightPx))),
+	};
+}
+
+export class SvgFigure implements Component {
+	readonly #options: SvgFigureOptions;
+	readonly #id = nextFigureId++;
+	#source = "";
+	/** No more text arrives for this fence: no throttling, and a failed raster falls back to code. */
+	#final = false;
+	#revision = 0;
+	#raster: Raster | undefined;
+	#attempt: Attempt | undefined;
+	/** Final source that could not be drawn; rendered as a fenced code block. */
+	#failed: string | undefined;
+	#rasterizing = false;
+	#startedAt = Number.NEGATIVE_INFINITY;
+	#timer: NodeJS.Timeout | undefined;
+	/** A {@link #schedule} is queued for the end of the current task. */
+	#queued = false;
+	#disposed = false;
+	/** Last render width; rasters wait for the first render to know their room. */
+	#width: number | undefined;
+	#image: { raster: Raster; component: Image } | undefined;
+	#fallback: { source: string; md: Markdown } | undefined;
+	#placeholder: readonly string[] | undefined;
+
+	constructor(options: SvgFigureOptions) {
+		this.#options = options;
+	}
+
+	/** Feed the fence body; `final` once the fence closed or the message stopped streaming. */
+	update(source: string, final: boolean): void {
+		if (source === this.#source && final === this.#final) return;
+		this.#source = source;
+		this.#final = final;
+		// Deferred: a block built mid-stream is marked streaming right after it
+		// is built, and must not first rasterize (and fail) its prefix as final.
+		if (this.#queued) return;
+		this.#queued = true;
+		queueMicrotask(() => {
+			this.#queued = false;
+			this.#schedule();
+		});
+	}
+
+	/** Whether the final source still waits for its raster (or for failing to render). */
+	get pending(): boolean {
+		return this.#final && this.#raster?.source !== this.#source && this.#failed !== this.#source;
+	}
+
+	render(width: number): readonly string[] {
+		// Width, cell size and theme are render-time inputs; a change re-rasterizes.
+		this.#width = width;
+		this.#schedule();
+		if (this.#failed === this.#source) return this.#fallbackRows(width);
+		const raster = this.#raster;
+		if (!raster) {
+			if (!this.#options.markdown) return [];
+			this.#placeholder ??= [` ${theme.fg("dim", "Drawing SVG…")}`];
+			return this.#placeholder;
+		}
+		return this.#imageFor(raster).render(width);
+	}
+
+	invalidate(): void {
+		this.#placeholder = undefined;
+		this.#image?.component.invalidate();
+		// Rebuilt through the Markdown factory, which may carry a new theme.
+		this.#fallback = undefined;
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+		clearTimeout(this.#timer);
+		this.#timer = undefined;
+	}
+
+	debugState(): Record<string, unknown> {
+		return {
+			final: this.#final,
+			failed: this.#failed === this.#source,
+			raster: this.#raster ? `${this.#raster.widthPx}x${this.#raster.heightPx}` : null,
+			current: this.#raster?.source === this.#source,
+		};
+	}
+
+	/** Whether the current source, cell size, theme or room at `width` has not been attempted yet. */
+	#stale(width: number): boolean {
+		const attempt = this.#attempt;
+		if (this.#failed === this.#source) return false;
+		const cell = getCellDimensions();
+		const limits = limitsFor(width, cell);
+		return (
+			attempt === undefined ||
+			attempt.source !== this.#source ||
+			attempt.cell.widthPx !== cell.widthPx ||
+			attempt.cell.heightPx !== cell.heightPx ||
+			attempt.themeEpoch !== getThemeEpoch() ||
+			// A streaming attempt that failed is retried once as final.
+			(this.#final && !attempt.final && this.#raster?.source !== this.#source) ||
+			((attempt.limits.columns !== limits.columns || attempt.limits.rows !== limits.rows) && this.#outgrown(limits))
+		);
+	}
+
+	/**
+	 * Whether the current raster would come out differently in `limits`. One
+	 * below both of its limits drew at its natural size and redraws only once
+	 * it no longer fits; one that filled a limit redraws whenever they change.
+	 */
+	#outgrown(limits: Limits): boolean {
+		const raster = this.#raster;
+		if (raster?.source !== this.#source) return false;
+		const columns = raster.widthPx / raster.cell.widthPx;
+		const rows = raster.heightPx / raster.cell.heightPx;
+		if (columns < raster.limits.columns && rows < raster.limits.rows) {
+			return columns > limits.columns || rows > limits.rows;
+		}
+		return raster.limits.columns !== limits.columns || raster.limits.rows !== limits.rows;
+	}
+
+	/** Start a raster when one is due: single-flight, throttled while streaming, immediate once final. */
+	#schedule(): void {
+		const width = this.#width;
+		if (this.#disposed || this.#rasterizing || width === undefined) return;
+		if (this.#final && this.#timer) {
+			clearTimeout(this.#timer);
+			this.#timer = undefined;
+		}
+		if (this.#timer || !this.#stale(width)) return;
+		const wait = this.#final ? 0 : this.#startedAt + STREAM_INTERVAL_MS - performance.now();
+		if (wait > 0) {
+			this.#timer = setTimeout(() => {
+				this.#timer = undefined;
+				this.#schedule();
+			}, wait);
+			this.#timer.unref?.();
+			return;
+		}
+		void this.#rasterize(width);
+	}
+
+	async #rasterize(width: number): Promise<void> {
+		const cell = getCellDimensions();
+		const attempt: Attempt = {
+			source: this.#source,
+			cell,
+			limits: limitsFor(width, cell),
+			themeEpoch: getThemeEpoch(),
+			final: this.#final,
+		};
+		this.#attempt = attempt;
+		const svg = closePartialSvg(attempt.source);
+		let png: Uint8Array | undefined;
+		if (svg !== null) {
+			this.#rasterizing = true;
+			this.#startedAt = performance.now();
+			try {
+				const prepared = prepareSvg(svg, svgFigurePalette());
+				png = await rasterizeSvg(
+					new TextEncoder().encode(prepared),
+					attempt.limits.columns * cell.widthPx,
+					attempt.limits.rows * cell.heightPx,
+					cell.heightPx / UNITS_PER_ROW,
+					cell,
+				);
+			} catch (error) {
+				// A streaming prefix that does not parse yet keeps the previous raster.
+				if (attempt.final) logger.debug("SVG figure did not render", { error: String(error) });
+			} finally {
+				this.#rasterizing = false;
+			}
+		}
+		if (this.#disposed) return;
+		const data = png?.toBase64();
+		const size = data ? getImageDimensions(data, "image/png") : null;
+		if (data && size) {
+			this.#show(attempt, data, size.widthPx, size.heightPx);
+		} else if (attempt.final) {
+			this.#failed = attempt.source;
+			this.#options.onChange();
+		}
+		// The source, cell size, theme or room moved on while this raster ran.
+		this.#schedule();
+	}
+
+	#show(attempt: Attempt, data: string, widthPx: number, heightPx: number): void {
+		const previous = this.#raster;
+		this.#raster = {
+			source: attempt.source,
+			cell: attempt.cell,
+			limits: attempt.limits,
+			themeEpoch: attempt.themeEpoch,
+			data,
+			widthPx,
+			heightPx,
+			key: `svg${this.#id}:${++this.#revision}`,
+		};
+		// A streaming revision is gone for good: free its terminal image now
+		// rather than letting it crowd older images out of the store. A
+		// re-raster of the same source (cell size, theme or room change) may still be
+		// standing in scrollback, so the residency sweep keeps deciding for it.
+		if (previous && previous.source !== attempt.source) this.#options.budget?.release(previous.key);
+		this.#options.onChange();
+	}
+
+	/**
+	 * The image for `raster` over the whole cells it was padded to. At the
+	 * cell size and room it was drawn for that box is its pixels exactly; a
+	 * raster outdated by a resize is scaled by {@link Image} until its redraw lands.
+	 */
+	#imageFor(raster: Raster): Image {
+		const current = this.#image;
+		if (current?.raster === raster) return current.component;
+		const columns = raster.widthPx / raster.cell.widthPx;
+		const rows = raster.heightPx / raster.cell.heightPx;
+		const component = new Image(
+			raster.data,
+			"image/png",
+			{ fallbackColor: (text: string) => theme.fg("toolOutput", text) },
+			{
+				maxWidthCells: columns,
+				maxHeightCells: rows,
+				filename: "svg",
+				budget: this.#options.budget,
+				imageKey: raster.key,
+				requestRender: this.#options.onChange,
+			},
+			{ widthPx: raster.widthPx, heightPx: raster.heightPx },
+		);
+		this.#image = { raster, component };
+		return component;
+	}
+
+	/** The source as the fenced code block it was written as, fenced longer than any backtick run inside. */
+	#fallbackRows(width: number): readonly string[] {
+		const source = this.#source;
+		if (!this.#options.markdown) return [];
+		if (this.#fallback?.source !== source) {
+			this.#fallback = { source, md: this.#options.markdown(fencedCode("svg", source)) };
+		}
+		return this.#fallback.md.render(width);
+	}
+}

package/src/chat/svg-source.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Source-level handling of ```svg fences in assistant Markdown: splitting
+ * prose around them ({@link splitSvgFences}), turning a fence that is still
+ * streaming into a document an SVG parser accepts ({@link closePartialSvg}),
+ * and resolving the theme tokens figures color themselves with
+ * ({@link prepareSvg}). `FigureMarkdown` lifts the fences out as `SvgFigure`
+ * images.
+ */
+/** One run of an assistant text block: prose, or the body of a ```svg fence. */
+export type FigureSegment = {
+    readonly kind: "markdown";
+    readonly text: string;
+}
+/** `closed` once the fence's closing line arrived. */
+ | {
+    readonly kind: "svg";
+    readonly source: string;
+    readonly closed: boolean;
+};
+/** Whether `markdown` holds a ```svg fence {@link splitSvgFences} would lift. */
+export declare function hasSvgFence(markdown: string): boolean;
+/**
+ * Split `markdown` into prose and ```svg fence bodies, in order. Only
+ * top-level fences lift; an svg fence nested in another fence, a list's
+ * indented block or a blockquote stays prose. Blank prose runs are dropped.
+ * An svg fence still open at the end is the last segment, `closed: false`.
+ */
+export declare function splitSvgFences(markdown: string): FigureSegment[];
+/**
+ * Turn a possibly truncated SVG source into a well-formed document: cut the
+ * trailing construct still being written (a tag without its `>`, an
+ * unterminated comment, CDATA section, processing instruction or declaration,
+ * a dangling `&entity`) and close every element left open, innermost first.
+ * A complete document passes through unchanged. Returns null until the root
+ * `<svg …>` start tag is complete — before that there is nothing to draw.
+ */
+export declare function closePartialSvg(source: string): string | null;
+/**
+ * Make a figure's source what an SVG rasterizer draws as written, in the
+ * reader's theme. Rasterizers resolve neither CSS custom properties nor an
+ * inherited text color, and reject a root without the SVG namespace, so:
+ * - `var(--name)` / `var(--name, fallback)` become `palette[name]` (an
+ *   unknown name takes its fallback, else `palette.fg`);
+ * - a root `<svg>` lacking them gets `color` = `palette.fg` (so
+ *   `currentColor` follows the theme), a sans-serif `font-family` (instead
+ *   of the rasterizer's Times), `xmlns`, and `xmlns:xlink` when the source
+ *   uses `xlink:` attributes.
+ */
+export declare function prepareSvg(svg: string, palette: Readonly<Record<string, string>>): string;

package/src/chat/svg-source.ts

@@ -0,0 +1,188 @@
+/**
+ * Source-level handling of ```svg fences in assistant Markdown: splitting
+ * prose around them ({@link splitSvgFences}), turning a fence that is still
+ * streaming into a document an SVG parser accepts ({@link closePartialSvg}),
+ * and resolving the theme tokens figures color themselves with
+ * ({@link prepareSvg}). `FigureMarkdown` lifts the fences out as `SvgFigure`
+ * images.
+ */
+
+/** One run of an assistant text block: prose, or the body of a ```svg fence. */
+export type FigureSegment =
+	| { readonly kind: "markdown"; readonly text: string }
+	/** `closed` once the fence's closing line arrived. */
+	| { readonly kind: "svg"; readonly source: string; readonly closed: boolean };
+
+/** A top-level (≤3-space indent) ```svg / ~~~svg fence opener, info string compared ASCII-case-insensitively. */
+const SVG_FENCE = /^ {0,3}(?:`{3,}|~{3,})[ \t]*svg(?:[ \t]|$)/im;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+/** Whether `markdown` holds a ```svg fence {@link splitSvgFences} would lift. */
+export function hasSvgFence(markdown: string): boolean {
+	return markdown.includes("svg") && SVG_FENCE.test(markdown);
+}
+
+/**
+ * Split `markdown` into prose and ```svg fence bodies, in order. Only
+ * top-level fences lift; an svg fence nested in another fence, a list's
+ * indented block or a blockquote stays prose. Blank prose runs are dropped.
+ * An svg fence still open at the end is the last segment, `closed: false`.
+ */
+export function splitSvgFences(markdown: string): FigureSegment[] {
+	const segments: FigureSegment[] = [];
+	/** Open fence: its marker run, and where an svg fence's body starts (-1 for other fences). */
+	let fence: { marker: string; body: number } | undefined;
+	let proseStart = 0;
+	let lineStart = 0;
+	while (lineStart <= markdown.length) {
+		const newline = markdown.indexOf("\n", lineStart);
+		const lineEnd = newline < 0 ? markdown.length : newline;
+		const next = newline < 0 ? markdown.length + 1 : newline + 1;
+		const line = markdown.slice(lineStart, lineEnd);
+		if (fence) {
+			if (closesFence(line, fence.marker)) {
+				if (fence.body >= 0) {
+					segments.push({ kind: "svg", source: markdown.slice(fence.body, lineStart), closed: true });
+					proseStart = Math.min(next, markdown.length);
+				}
+				fence = undefined;
+			}
+		} else {
+			const open = FENCE_OPEN.exec(line);
+			// A backtick fence's info string cannot hold backticks (CommonMark).
+			if (open && !(open[1]![0] === "`" && open[2]!.includes("`"))) {
+				const isSvg = open[2]!.trim().split(/[ \t]/, 1)[0]!.toLowerCase() === "svg";
+				if (isSvg) {
+					const prose = markdown.slice(proseStart, lineStart);
+					if (prose.trim()) segments.push({ kind: "markdown", text: prose });
+					fence = { marker: open[1]!, body: Math.min(next, markdown.length) };
+				} else {
+					fence = { marker: open[1]!, body: -1 };
+				}
+			}
+		}
+		lineStart = next;
+	}
+	if (fence && fence.body >= 0) {
+		segments.push({ kind: "svg", source: markdown.slice(fence.body), closed: false });
+	} else if (markdown.slice(proseStart).trim()) {
+		segments.push({ kind: "markdown", text: markdown.slice(proseStart) });
+	}
+	return segments;
+}
+
+/** Whether `line` closes a fence opened by `marker`: same character, at least as long, nothing after. */
+function closesFence(line: string, marker: string): boolean {
+	let index = 0;
+	while (index < 3 && line[index] === " ") index++;
+	let run = 0;
+	while (line[index + run] === marker[0]) run++;
+	return run >= marker.length && line.slice(index + run).trim() === "";
+}
+
+/**
+ * Turn a possibly truncated SVG source into a well-formed document: cut the
+ * trailing construct still being written (a tag without its `>`, an
+ * unterminated comment, CDATA section, processing instruction or declaration,
+ * a dangling `&entity`) and close every element left open, innermost first.
+ * A complete document passes through unchanged. Returns null until the root
+ * `<svg …>` start tag is complete — before that there is nothing to draw.
+ */
+export function closePartialSvg(source: string): string | null {
+	const open: string[] = [];
+	let rootSeen = false;
+	let end = 0;
+	let index = 0;
+	for (;;) {
+		const lt = source.indexOf("<", index);
+		if (lt < 0) {
+			// Trailing text: an entity reference still being written would not parse.
+			const amp = source.lastIndexOf("&");
+			end = amp >= index && !source.includes(";", amp) ? amp : source.length;
+			break;
+		}
+		end = lt;
+		const close = constructEnd(source, lt);
+		if (close < 0) break;
+		if (source.startsWith("</", lt)) {
+			const name = source.slice(lt + 2, close - 1).trim();
+			const at = open.lastIndexOf(name);
+			if (at >= 0) open.length = at;
+		} else if (source[lt + 1] !== "!" && source[lt + 1] !== "?") {
+			const name = /^<([^\s/>]+)/.exec(source.slice(lt, close))?.[1];
+			if (name !== undefined) {
+				if (source[close - 2] !== "/") open.push(name);
+				if (!rootSeen && (name === "svg" || name.endsWith(":svg"))) rootSeen = true;
+			}
+		}
+		index = close;
+		end = close;
+	}
+	if (!rootSeen) return null;
+	let document = source.slice(0, end);
+	for (let at = open.length - 1; at >= 0; at--) document += `</${open[at]}>`;
+	return document;
+}
+
+/** `var(--name)` / `var(--name, fallback)`; the fallback may hold one level of parentheses (`rgb(…)`). */
+const VAR_REFERENCE = /var\(\s*--([\w-]+)\s*(?:,\s*((?:[^()]|\([^()]*\))*))?\)/g;
+/** The first `<svg …>` start tag (namespace prefix allowed). */
+const ROOT_TAG = /<(?:[\w.-]+:)?svg(?=[\s/>])[^>]*>/;
+
+/**
+ * Make a figure's source what an SVG rasterizer draws as written, in the
+ * reader's theme. Rasterizers resolve neither CSS custom properties nor an
+ * inherited text color, and reject a root without the SVG namespace, so:
+ * - `var(--name)` / `var(--name, fallback)` become `palette[name]` (an
+ *   unknown name takes its fallback, else `palette.fg`);
+ * - a root `<svg>` lacking them gets `color` = `palette.fg` (so
+ *   `currentColor` follows the theme), a sans-serif `font-family` (instead
+ *   of the rasterizer's Times), `xmlns`, and `xmlns:xlink` when the source
+ *   uses `xlink:` attributes.
+ */
+export function prepareSvg(svg: string, palette: Readonly<Record<string, string>>): string {
+	const fg = palette.fg ?? "currentColor";
+	const resolved = svg.replace(
+		VAR_REFERENCE,
+		(_match, name: string, fallback: string | undefined) => palette[name] ?? (fallback?.trim() || fg),
+	);
+	const usesXlink = resolved.includes("xlink:");
+	return resolved.replace(ROOT_TAG, tag => {
+		let added = "";
+		if (!/\scolor\s*=/.test(tag)) added += ` color="${fg}"`;
+		if (!/\sfont-family\s*=/.test(tag)) added += ` font-family="sans-serif"`;
+		if (!/\sxmlns\s*=/.test(tag)) added += ` xmlns="http://www.w3.org/2000/svg"`;
+		if (usesXlink && !/\sxmlns:xlink\s*=/.test(tag)) added += ` xmlns:xlink="http://www.w3.org/1999/xlink"`;
+		return added ? tag.replace(/^<[^\s/>]+/, `$&${added}`) : tag;
+	});
+}
+
+/** Index just past the markup construct starting at `<` (`lt`), or -1 when it is not complete yet. */
+function constructEnd(source: string, lt: number): number {
+	const after = (terminator: string, from: number): number => {
+		const at = source.indexOf(terminator, from);
+		return at < 0 ? -1 : at + terminator.length;
+	};
+	if (source.startsWith("<!--", lt)) return after("-->", lt + 4);
+	if (source.startsWith("<![CDATA[", lt)) return after("]]>", lt + 9);
+	if (source.startsWith("<?", lt)) return after("?>", lt + 2);
+	// Tags and declarations end at the first `>` outside a quoted value; a
+	// doctype's internal subset (`[…]`) may hold `>` of its own.
+	let quote: string | undefined;
+	let subset = false;
+	for (let at = lt + 1; at < source.length; at++) {
+		const char = source[at];
+		if (quote !== undefined) {
+			if (char === quote) quote = undefined;
+		} else if (char === '"' || char === "'") {
+			quote = char;
+		} else if (char === "[" && source[lt + 1] === "!") {
+			subset = true;
+		} else if (char === "]") {
+			subset = false;
+		} else if (char === ">" && !subset) {
+			return at + 1;
+		}
+	}
+	return -1;
+}