@ai-gui/image 0.31.0

package/dist/index.js

@@ -0,0 +1,371 @@
+import { baseCss, collectPluginStyles, createParserWithMetadata } from "@ai-gui/core";
+import { chart } from "@ai-gui/plugin-chart";
+import { dashboard } from "@ai-gui/plugin-dashboard";
+import { katex } from "@ai-gui/plugin-katex";
+import { mermaid } from "@ai-gui/plugin-mermaid";
+import { mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { katexInlineCss } from "@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 [
+		chart({
+			interactive: false,
+			width: inner,
+			height: Math.round(inner * .625)
+		}),
+		mermaid(),
+		katex({ css: "" }),
+		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 = 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 = createRequire(import.meta.url);
+	const fontDir = join(dirname(require_$1.resolve("katex/package.json")), "dist", "fonts");
+	const inlined = new Map();
+	for (const file of readdirSync(fontDir)) {
+		if (!file.endsWith(".woff2")) continue;
+		inlined.set(file, `data:font/woff2;base64,${readFileSync(join(fontDir, file)).toString("base64")}`);
+	}
+	let 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 = 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}
+${baseCss}
+${katexCss()}
+${pluginCss}
+</style></head><body><div id="root"></div></body></html>`;
+}
+
+//#endregion
+//#region src/render.ts
+const require_ = createRequire(import.meta.url);
+/** The built browser bundle that ships alongside this module. */
+function pageBundlePath() {
+	return 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 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 = 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
+export { BrowserUnavailableError, DEFAULT_IDLE_SHUTDOWN_MS, DEFAULT_KINDS, DEFAULT_MAX, DEFAULT_SCALE, DEFAULT_TIMEOUT_MS, DEFAULT_WIDTH, closeBrowser, hasTrigger, renderMarkdownToImages, selectRenderableBlocks, stripBlocks };