@ai-gui/image 0.31.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @ai-gui/image
+
+Render [AIGUI](../../README.md) markdown blocks — ECharts charts, Mermaid diagrams, KaTeX math, tables, cards, dashboards — to PNG, by running the real `@ai-gui/vanilla` renderer in a headless Chromium and screenshotting each block.
+
+Use it where a channel carries pictures but not markup: WeChat, email, an image-only webhook.
+
+## Install
+
+```sh
+pnpm add @ai-gui/image playwright
+pnpm exec playwright install chromium
+```
+
+Playwright is an optional peer dependency. Without it every render throws `BrowserUnavailableError`, so a host can treat pictures as a bonus rather than a requirement.
+
+On Linux the container also needs CJK faces, or Chinese renders as tofu in the delivered image:
+
+```sh
+apt-get install -y fonts-noto-cjk
+```
+
+Maths needs nothing: KaTeX's stylesheet and all twenty of its font faces are inlined into the page, so formulas typeset correctly with no network and no system fonts. Only CJK text depends on what the host has installed.
+
+## Usage
+
+```ts
+import { renderMarkdownToImages } from "@ai-gui/image"
+
+const { text, images } = await renderMarkdownToImages(answer, { outDir: "/tmp/aigui" })
+// text   — the answer with every rendered block removed
+// images — [{ kind: "chart", path: "/tmp/aigui/aigui-chart-0-83421-0.png", width, height }]
+```
+
+Blocks that fail to render are left in `text` as their original source, so a broken diagram costs a picture, never the answer.
+
+## Exports
+
+- `renderMarkdownToImages(markdown, options)` — the whole job.
+- `selectRenderableBlocks(markdown, options)` / `stripBlocks(markdown, selections)` — the pure parts, if you want to drive rendering yourself.
+- `hasTrigger(markdown)` — a cheap pre-filter for hot paths.
+- `closeBrowser()` — shut the resident Chromium down now instead of waiting for the idle timer.
+- `BrowserUnavailableError` — thrown when Playwright is not installed.
+- Types — `RenderOptions`, `RenderResult`, `RenderedImage`, `BlockSelection`, `RenderableKind`, `SelectOptions` — plus the `DEFAULT_KINDS` / `DEFAULT_WIDTH` / `DEFAULT_SCALE` / `DEFAULT_MAX` / `DEFAULT_TIMEOUT_MS` / `DEFAULT_IDLE_SHUTDOWN_MS` constants backing the defaults below.
+
+## Options
+
+- `outDir` — where PNGs are written (required).
+- `kinds` — which families to draw. Default: all six.
+- `theme` — `"light"` (default) or `"dark"`.
+- `width` — viewport width in CSS pixels. Default 720.
+- `scale` — device pixels per CSS pixel. Default 2, which is what a phone screen wants.
+- `max` — cap on pictures per call. Default 6; the rest stay as text.
+- `timeoutMs` — per-block budget. Default 10000.
+- `idleShutdownMs` — how long the browser stays resident with nothing to do. Default 300000.
+
+## Cost when there is nothing to draw
+
+`renderMarkdownToImages` parses before it launches anything, and returns the source untouched if no block qualifies. The browser is lazy and shuts itself down after five idle minutes, so a process that renders one chart an hour does not hold a Chromium open in between.
+
+## Testing
+
+The screenshot tests need a real browser and are opt-in:
+
+```sh
+pnpm exec playwright install chromium
+AIGUI_IMAGE_E2E=1 pnpm exec vitest run --project image render.e2e
+```

package/dist/index.cjs

@@ -0,0 +1,406 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __ai_gui_core = __toESM(require("@ai-gui/core"));
+const __ai_gui_plugin_chart = __toESM(require("@ai-gui/plugin-chart"));
+const __ai_gui_plugin_dashboard = __toESM(require("@ai-gui/plugin-dashboard"));
+const __ai_gui_plugin_katex = __toESM(require("@ai-gui/plugin-katex"));
+const __ai_gui_plugin_mermaid = __toESM(require("@ai-gui/plugin-mermaid"));
+const node_fs_promises = __toESM(require("node:fs/promises"));
+const node_module = __toESM(require("node:module"));
+const node_path = __toESM(require("node:path"));
+const node_fs = __toESM(require("node:fs"));
+const __ai_gui_plugin_katex_inline_css = __toESM(require("@ai-gui/plugin-katex/inline-css"));
+
+//#region src/types.ts
+const DEFAULT_KINDS = [
+	"chart",
+	"mermaid",
+	"dashboard",
+	"card",
+	"math",
+	"table"
+];
+const DEFAULT_WIDTH = 720;
+const DEFAULT_SCALE = 2;
+const DEFAULT_MAX = 6;
+const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_IDLE_SHUTDOWN_MS = 3e5;
+
+//#endregion
+//#region src/plugins.ts
+/**
+* The plugins an image render understands.
+*
+* `interactive: false` is not a preference. It makes plugin-chart return an SSR SVG in the same
+* tick rather than mounting a live ECharts instance with animations to wait out.
+*
+* The chart is sized to the page rather than left at the plugin's 600x400 default, which would
+* otherwise sit in a 720px column with a band of dead space beside it.
+*/
+function imagePlugins(width = DEFAULT_WIDTH) {
+	const inner = Math.max(200, width - 32);
+	return [
+		(0, __ai_gui_plugin_chart.chart)({
+			interactive: false,
+			width: inner,
+			height: Math.round(inner * .625)
+		}),
+		(0, __ai_gui_plugin_mermaid.mermaid)(),
+		(0, __ai_gui_plugin_katex.katex)({ css: "" }),
+		(0, __ai_gui_plugin_dashboard.dashboard)()
+	];
+}
+
+//#endregion
+//#region src/blocks.ts
+/**
+* A cheap "might there be a picture in here?" test.
+*
+* The point is to spend nothing on the overwhelming majority of replies, which are prose. It is
+* intentionally loose — a sentence that happens to start with a pipe costs one markdown parse,
+* and the parse is what actually decides. Nothing launches a browser on the strength of this.
+*
+* Loose in the right direction, though. A false positive costs a parse; a false negative silently
+* drops a picture the reader asked for. Two shapes earned their own branch for that reason:
+* models write tables without leading pipes at least as often as with them, and they escalate a
+* fence to four backticks whenever the payload contains three.
+*/
+const TRIGGER = /^ {0,3}(?:(?:`{3,}|~{3,})[ \t]*(?:chart|mermaid|dashboard|card:)|\$\$|\||:?-+:?[ \t]*\|)/m;
+function hasTrigger(markdown) {
+	return TRIGGER.test(markdown);
+}
+/**
+* Which picture, if any, a parsed node represents.
+*
+* Charts, diagrams and dashboards announce themselves through the node type, because their
+* plugins register node renderers. Math and tables do not: KaTeX extends markdown-it rather than
+* registering a renderer, and tables are plain markdown-it, so both arrive as generic `html`
+* nodes carrying already-rendered markup. They have to be recognised by what is in that markup.
+*/
+function classify(node) {
+	if (node.type === "chart" || node.type === "mermaid" || node.type === "dashboard") return node.complete ? node.type : void 0;
+	if (node.type === "card") return node.card?.complete && node.card.valid ? "card" : void 0;
+	if (node.type !== "html") return void 0;
+	const html = node.content ?? "";
+	if (/class="[^"]*\bkatex-display\b/.test(html)) return "math";
+	if (/<table[\s>]/.test(html)) return "table";
+	return void 0;
+}
+function selectRenderableBlocks(markdown, options = {}) {
+	const kinds = new Set(options.kinds ?? DEFAULT_KINDS);
+	const max = options.max ?? DEFAULT_MAX;
+	const parse = (0, __ai_gui_core.createParserWithMetadata)({
+		plugins: imagePlugins(),
+		registry: options.registry
+	});
+	const { nodes, blocks } = parse(markdown);
+	const selections = [];
+	for (const block of blocks) {
+		if (selections.length >= max) break;
+		for (let i = block.nodeStart; i < block.nodeEnd; i++) {
+			const kind = classify(nodes[i]);
+			if (!kind || !kinds.has(kind)) continue;
+			selections.push({
+				kind,
+				start: block.start,
+				end: block.end
+			});
+			break;
+		}
+	}
+	return selections;
+}
+/**
+* Cut the rendered blocks out of the text.
+*
+* Back to front, because slicing from the front shifts every offset behind it and silently
+* corrupts the second cut onwards. Runs of blank lines left by the cuts collapse to one, so a
+* message that was mostly pictures does not arrive as a column of empty lines. The collapse has
+* to know about `\r\n` — matching bare `\n` leaves a stray blank line in every CRLF message.
+*/
+function stripBlocks(markdown, selections) {
+	let out = markdown;
+	for (const selection of [...selections].sort((a, b) => b.start - a.start)) out = out.slice(0, selection.start) + out.slice(selection.end);
+	return out.replace(/(?:\r?\n){3,}/g, "\n\n").trim();
+}
+
+//#endregion
+//#region src/browser.ts
+/** Playwright is an optional peer. Its absence is a configuration fact, not a bug. */
+var BrowserUnavailableError = class extends Error {
+	constructor(cause) {
+		super("Playwright is not installed. Run `pnpm add playwright` and `pnpm exec playwright install chromium`.");
+		this.name = "BrowserUnavailableError";
+		this.cause = cause;
+	}
+};
+const defaultLauncher = async () => {
+	const playwright = await import("playwright");
+	return await playwright.chromium.launch({ args: ["--font-render-hinting=none"] });
+};
+let browser;
+let launching;
+let leases = 0;
+let idleTimer;
+function cancelIdle() {
+	if (idleTimer === void 0) return;
+	clearTimeout(idleTimer);
+	idleTimer = void 0;
+}
+/**
+* Close the browser once nobody has wanted one for a while.
+*
+* A gateway can go hours between charts, and a resident Chromium is a few hundred megabytes of
+* nothing. Launching costs about a second, which is affordable on the first chart of a burst and
+* free on the rest.
+*/
+function scheduleIdleShutdown(idleShutdownMs) {
+	cancelIdle();
+	idleTimer = setTimeout(() => {
+		if (leases > 0) return;
+		closeBrowser();
+	}, idleShutdownMs);
+	idleTimer.unref?.();
+}
+async function acquirePage(options = {}) {
+	const launcher = options.launcher ?? defaultLauncher;
+	const idleShutdownMs = options.idleShutdownMs ?? DEFAULT_IDLE_SHUTDOWN_MS;
+	cancelIdle();
+	if (!browser) try {
+		launching ??= launcher();
+		browser = await launching;
+	} catch (error) {
+		throw new BrowserUnavailableError(error);
+	} finally {
+		launching = void 0;
+	}
+	let page;
+	try {
+		page = await browser.newPage({ deviceScaleFactor: options.deviceScaleFactor ?? DEFAULT_SCALE });
+	} catch (error) {
+		browser = void 0;
+		throw error;
+	}
+	leases++;
+	let released = false;
+	return {
+		page,
+		async release() {
+			if (released) return;
+			released = true;
+			leases--;
+			await page.close().catch(() => {});
+			if (leases === 0) scheduleIdleShutdown(idleShutdownMs);
+		}
+	};
+}
+async function closeBrowser() {
+	cancelIdle();
+	const current = browser;
+	browser = void 0;
+	launching = void 0;
+	await current?.close().catch(() => {});
+}
+
+//#endregion
+//#region src/page/fonts.ts
+const PLACEHOLDER = "AIGUI_KATEX_FONTS/";
+/**
+* KaTeX's stylesheet with its fonts inlined as data URIs.
+*
+* Two problems get solved together. The plugin's default `css` is an `@import` of a bare npm
+* specifier, which resolves to nothing inside `page.setContent` — without the real stylesheet a
+* formula renders as flat text, so `\frac{a}{b}` arrives as "ba". And `katexInlineCss({ fontBase })`
+* alone is not enough either: Chromium refuses `file://` subresources from an `about:blank`
+* document, so all twenty faces fail and the maths falls back to a serif. That fallback is
+* legible, but it has no blackboard bold or script faces — `\mathbb{R}` degrades to a bold R.
+*
+* Data URIs need no origin and no network, so the fonts simply work. 296 kB of woff2 becomes
+* roughly 368 kB of CSS, read once and kept for the life of the process.
+*/
+let cached;
+function katexCss() {
+	if (cached !== void 0) return cached;
+	const require_$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+	const fontDir = (0, node_path.join)((0, node_path.dirname)(require_$1.resolve("katex/package.json")), "dist", "fonts");
+	const inlined = new Map();
+	for (const file of (0, node_fs.readdirSync)(fontDir)) {
+		if (!file.endsWith(".woff2")) continue;
+		inlined.set(file, `data:font/woff2;base64,${(0, node_fs.readFileSync)((0, node_path.join)(fontDir, file)).toString("base64")}`);
+	}
+	let css = (0, __ai_gui_plugin_katex_inline_css.katexInlineCss)({ fontBase: PLACEHOLDER });
+	css = css.replace(new RegExp(`url\\(${PLACEHOLDER}([^)]+?)\\.woff2\\)`, "g"), (whole, name) => {
+		const uri = inlined.get(`${name}.woff2`);
+		return uri ? `url(${uri})` : whole;
+	});
+	css = css.replace(new RegExp(`,\\s*url\\(${PLACEHOLDER}[^)]+?\\.(?:woff|ttf)\\)\\s*format\\("(?:woff|truetype)"\\)`, "g"), "");
+	cached = css;
+	return cached;
+}
+
+//#endregion
+//#region src/page/html.ts
+const THEMES = {
+	light: {
+		bg: "#ffffff",
+		fg: "#1a1a1a"
+	},
+	dark: {
+		bg: "#161616",
+		fg: "#e8e8e8"
+	}
+};
+/**
+* The document a block is drawn into.
+*
+* Animation is disabled globally. ECharts is already static here, but Mermaid and the dashboard
+* plugin animate on entry, and an animating element is a coin flip between a finished picture and
+* a half-faded one. The font stack names CJK families explicitly: a screenshot has no fallback
+* chain to fall back to at read time, so a missing face is permanent tofu in the delivered image.
+*/
+function pageHtml(options = {}) {
+	const theme = THEMES[options.theme ?? "light"];
+	const pluginCss = (0, __ai_gui_core.collectPluginStyles)(imagePlugins(options.width)).map((style) => style.css).join("\n");
+	return `<!doctype html>
+<html><head><meta charset="utf-8"><style>
+*,*::before,*::after{animation:none!important;transition:none!important}
+html,body{margin:0;padding:0;background:${theme.bg};color:${theme.fg}}
+body{font-family:-apple-system,"PingFang SC","Hiragino Sans GB","Microsoft YaHei","Noto Sans CJK SC","Noto Sans SC",system-ui,sans-serif;font-size:16px;line-height:1.6}
+#root{display:inline-block;padding:16px;box-sizing:border-box;max-width:${options.width ?? 720}px}
+${__ai_gui_core.baseCss}
+${katexCss()}
+${pluginCss}
+</style></head><body><div id="root"></div></body></html>`;
+}
+
+//#endregion
+//#region src/render.ts
+const require_ = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+/** The built browser bundle that ships alongside this module. */
+function pageBundlePath() {
+	return (0, node_path.join)(require_.resolve("@ai-gui/image/package.json"), "..", "dist", "page", "entry.js");
+}
+function withTimeout(promise, ms, what) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+/**
+* Draw every renderable block in `markdown` and return the leftover text plus the pictures.
+*
+* A block that fails is left alone: its source stays in the text, so a reader gets the raw fence
+* rather than a silently missing answer. Only blocks that actually produced a file are stripped.
+*/
+async function renderMarkdownToImages(markdown, options) {
+	const selections = selectRenderableBlocks(markdown, {
+		kinds: options.kinds,
+		registry: options.registry,
+		max: options.max
+	});
+	if (selections.length === 0) return {
+		text: markdown,
+		images: []
+	};
+	await (0, node_fs_promises.mkdir)(options.outDir, { recursive: true });
+	const acquire = options.acquire ?? ((opts) => acquirePage(opts));
+	const width = options.width ?? DEFAULT_WIDTH;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const lease = await acquire({
+		idleShutdownMs: options.idleShutdownMs,
+		deviceScaleFactor: options.scale ?? DEFAULT_SCALE
+	});
+	const page = lease.page;
+	const images = [];
+	const rendered = [];
+	try {
+		await page.setViewportSize({
+			width,
+			height: 800
+		});
+		await page.setContent(pageHtml({
+			theme: options.theme,
+			width
+		}));
+		await page.addScriptTag({ path: pageBundlePath() });
+		for (const [index, selection] of selections.entries()) {
+			const source = markdown.slice(selection.start, selection.end);
+			const path = (0, node_path.join)(options.outDir, `aigui-${selection.kind}-${index}-${process.pid}-${images.length}.png`);
+			try {
+				const size = await withTimeout(
+					// A real function, not a string. Playwright evaluates a string as an *expression*: it
+					// would produce the function object and never call it, so every render silently
+					// returned undefined. Verified in a live browser — the fake page in the unit tests
+					// cannot distinguish the two, which is exactly why it went unnoticed.
+					page.evaluate((arg) => window.__aiguiRenderBlock(arg.source, {
+						width: arg.width,
+						theme: arg.theme
+					}), {
+						source,
+						width,
+						theme: options.theme
+					}),
+					timeoutMs,
+					`rendering ${selection.kind}`
+);
+				if (size.failed) throw new Error(`${selection.kind} failed to draw`);
+				await withTimeout(page.locator("#root").screenshot({ path }), timeoutMs, `screenshotting ${selection.kind}`);
+				images.push({
+					kind: selection.kind,
+					path,
+					width: size.width,
+					height: size.height
+				});
+				rendered.push(selection);
+			} catch {}
+		}
+	} finally {
+		await lease.release();
+	}
+	return {
+		text: stripBlocks(markdown, rendered),
+		images
+	};
+}
+
+//#endregion
+exports.BrowserUnavailableError = BrowserUnavailableError
+exports.DEFAULT_IDLE_SHUTDOWN_MS = DEFAULT_IDLE_SHUTDOWN_MS
+exports.DEFAULT_KINDS = DEFAULT_KINDS
+exports.DEFAULT_MAX = DEFAULT_MAX
+exports.DEFAULT_SCALE = DEFAULT_SCALE
+exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS
+exports.DEFAULT_WIDTH = DEFAULT_WIDTH
+exports.closeBrowser = closeBrowser
+exports.hasTrigger = hasTrigger
+exports.renderMarkdownToImages = renderMarkdownToImages
+exports.selectRenderableBlocks = selectRenderableBlocks
+exports.stripBlocks = stripBlocks

package/dist/index.d.cts

@@ -0,0 +1,96 @@
+import { CardRegistry } from "@ai-gui/core";
+
+//#region src/types.d.ts
+/** A block family that can be turned into a picture. */
+/** A block family that can be turned into a picture. */
+type RenderableKind = "chart" | "mermaid" | "dashboard" | "card" | "math" | "table";
+/** One block chosen for rendering, with the source range it occupies. */
+interface BlockSelection {
+  kind: RenderableKind;
+  /** Character offset of the block's first character in the source. */
+  start: number;
+  /** Character offset one past the block's last character. */
+  end: number;
+}
+interface RenderedImage {
+  kind: RenderableKind;
+  /** Absolute path of the written PNG. */
+  path: string;
+  width: number;
+  height: number;
+}
+interface RenderOptions {
+  /** Directory the PNGs are written into. Created if missing. */
+  outDir: string;
+  kinds?: RenderableKind[];
+  theme?: "light" | "dark";
+  /** Viewport width in CSS pixels. */
+  width?: number;
+  /** Device pixels per CSS pixel. */
+  scale?: number;
+  /** Cap on how many blocks are rendered. Extra blocks stay as text. */
+  max?: number;
+  timeoutMs?: number;
+  idleShutdownMs?: number;
+}
+interface RenderResult {
+  /** The source with every successfully rendered block removed. */
+  text: string;
+  images: RenderedImage[];
+}
+declare const DEFAULT_KINDS: RenderableKind[];
+declare const DEFAULT_WIDTH = 720;
+declare const DEFAULT_SCALE = 2;
+declare const DEFAULT_MAX = 6;
+declare const DEFAULT_TIMEOUT_MS = 10000;
+declare const DEFAULT_IDLE_SHUTDOWN_MS = 300000; //#endregion
+//#region src/blocks.d.ts
+declare function hasTrigger(markdown: string): boolean;
+interface SelectOptions {
+  kinds?: RenderableKind[];
+  registry?: CardRegistry;
+  max?: number;
+}
+declare function selectRenderableBlocks(markdown: string, options?: SelectOptions): BlockSelection[];
+/**
+ * Cut the rendered blocks out of the text.
+ *
+ * Back to front, because slicing from the front shifts every offset behind it and silently
+ * corrupts the second cut onwards. Runs of blank lines left by the cuts collapse to one, so a
+ * message that was mostly pictures does not arrive as a column of empty lines. The collapse has
+ * to know about `\r\n` — matching bare `\n` leaves a stray blank line in every CRLF message.
+ */
+declare function stripBlocks(markdown: string, selections: BlockSelection[]): string;
+
+//#endregion
+//#region src/browser.d.ts
+/** Playwright is an optional peer. Its absence is a configuration fact, not a bug. */
+declare class BrowserUnavailableError extends Error {
+  constructor(cause: unknown);
+}
+declare function closeBrowser(): Promise<void>;
+
+//#endregion
+//#region src/render.d.ts
+/** Drops all module state. Tests only. */
+interface InternalRenderOptions extends RenderOptions {
+  registry?: CardRegistry;
+  /** Injected in tests. Defaults to the module's own lazy Chromium. */
+  acquire?: (options: {
+    idleShutdownMs?: number;
+    deviceScaleFactor?: number;
+  }) => Promise<{
+    page: unknown;
+    release: () => Promise<void>;
+  }>;
+}
+/**
+ * Draw every renderable block in `markdown` and return the leftover text plus the pictures.
+ *
+ * A block that fails is left alone: its source stays in the text, so a reader gets the raw fence
+ * rather than a silently missing answer. Only blocks that actually produced a file are stripped.
+ */
+declare function renderMarkdownToImages(markdown: string, options: InternalRenderOptions): Promise<RenderResult>;
+
+//#endregion
+export { BlockSelection, BrowserUnavailableError, DEFAULT_IDLE_SHUTDOWN_MS, DEFAULT_KINDS, DEFAULT_MAX, DEFAULT_SCALE, DEFAULT_TIMEOUT_MS, DEFAULT_WIDTH, InternalRenderOptions, RenderOptions, RenderResult, RenderableKind, RenderedImage, SelectOptions, closeBrowser, hasTrigger, renderMarkdownToImages, selectRenderableBlocks, stripBlocks };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { CardRegistry } from "@ai-gui/core";
+
+//#region src/types.d.ts
+/** A block family that can be turned into a picture. */
+/** A block family that can be turned into a picture. */
+type RenderableKind = "chart" | "mermaid" | "dashboard" | "card" | "math" | "table";
+/** One block chosen for rendering, with the source range it occupies. */
+interface BlockSelection {
+  kind: RenderableKind;
+  /** Character offset of the block's first character in the source. */
+  start: number;
+  /** Character offset one past the block's last character. */
+  end: number;
+}
+interface RenderedImage {
+  kind: RenderableKind;
+  /** Absolute path of the written PNG. */
+  path: string;
+  width: number;
+  height: number;
+}
+interface RenderOptions {
+  /** Directory the PNGs are written into. Created if missing. */
+  outDir: string;
+  kinds?: RenderableKind[];
+  theme?: "light" | "dark";
+  /** Viewport width in CSS pixels. */
+  width?: number;
+  /** Device pixels per CSS pixel. */
+  scale?: number;
+  /** Cap on how many blocks are rendered. Extra blocks stay as text. */
+  max?: number;
+  timeoutMs?: number;
+  idleShutdownMs?: number;
+}
+interface RenderResult {
+  /** The source with every successfully rendered block removed. */
+  text: string;
+  images: RenderedImage[];
+}
+declare const DEFAULT_KINDS: RenderableKind[];
+declare const DEFAULT_WIDTH = 720;
+declare const DEFAULT_SCALE = 2;
+declare const DEFAULT_MAX = 6;
+declare const DEFAULT_TIMEOUT_MS = 10000;
+declare const DEFAULT_IDLE_SHUTDOWN_MS = 300000; //#endregion
+//#region src/blocks.d.ts
+declare function hasTrigger(markdown: string): boolean;
+interface SelectOptions {
+  kinds?: RenderableKind[];
+  registry?: CardRegistry;
+  max?: number;
+}
+declare function selectRenderableBlocks(markdown: string, options?: SelectOptions): BlockSelection[];
+/**
+ * Cut the rendered blocks out of the text.
+ *
+ * Back to front, because slicing from the front shifts every offset behind it and silently
+ * corrupts the second cut onwards. Runs of blank lines left by the cuts collapse to one, so a
+ * message that was mostly pictures does not arrive as a column of empty lines. The collapse has
+ * to know about `\r\n` — matching bare `\n` leaves a stray blank line in every CRLF message.
+ */
+declare function stripBlocks(markdown: string, selections: BlockSelection[]): string;
+
+//#endregion
+//#region src/browser.d.ts
+/** Playwright is an optional peer. Its absence is a configuration fact, not a bug. */
+declare class BrowserUnavailableError extends Error {
+  constructor(cause: unknown);
+}
+declare function closeBrowser(): Promise<void>;
+
+//#endregion
+//#region src/render.d.ts
+/** Drops all module state. Tests only. */
+interface InternalRenderOptions extends RenderOptions {
+  registry?: CardRegistry;
+  /** Injected in tests. Defaults to the module's own lazy Chromium. */
+  acquire?: (options: {
+    idleShutdownMs?: number;
+    deviceScaleFactor?: number;
+  }) => Promise<{
+    page: unknown;
+    release: () => Promise<void>;
+  }>;
+}
+/**
+ * Draw every renderable block in `markdown` and return the leftover text plus the pictures.
+ *
+ * A block that fails is left alone: its source stays in the text, so a reader gets the raw fence
+ * rather than a silently missing answer. Only blocks that actually produced a file are stripped.
+ */
+declare function renderMarkdownToImages(markdown: string, options: InternalRenderOptions): Promise<RenderResult>;
+
+//#endregion
+export { BlockSelection, BrowserUnavailableError, DEFAULT_IDLE_SHUTDOWN_MS, DEFAULT_KINDS, DEFAULT_MAX, DEFAULT_SCALE, DEFAULT_TIMEOUT_MS, DEFAULT_WIDTH, InternalRenderOptions, RenderOptions, RenderResult, RenderableKind, RenderedImage, SelectOptions, closeBrowser, hasTrigger, renderMarkdownToImages, selectRenderableBlocks, stripBlocks };