@ai-gui/plugin-figure 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @ai-gui/plugin-figure
+
+## 0.11.0
+
+### Patch Changes
+
+- Updated dependencies [58d1b6c]
+  - @ai-gui/core@0.11.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,55 @@
+# @ai-gui/plugin-figure
+
+Labelled figures for [AIGUI](../../README.md). The plugin claims one `figure` fence and draws the parts it declares as SVG, with leader-line callouts naming each one.
+
+This is the diagram whose point is what the parts are *called*: a cell with its organelles named, a leaf's layers, apparatus with the parts a method refers to, a labelled cross-section. Use `mermaid` for boxes joined by arrows and `chart` for data.
+
+## Install
+
+```sh
+pnpm add @ai-gui/plugin-figure
+```
+
+## Usage
+
+```tsx
+import { figure, figureCss } from "@ai-gui/plugin-figure"
+import { AIRenderer } from "@ai-gui/react"
+
+<style>{figureCss}</style>
+<AIRenderer plugins={[figure()]} />
+```
+
+    ```figure
+    {"version":1,"title":"动物细胞","caption":"图 1 动物细胞的基本结构","parts":[
+      {"at":[0,0],"width":220,"height":160,"fill":"none","label":"细胞膜","note":"控制物质进出"},
+      {"at":[-20,10],"width":70,"height":60,"fill":"solid","label":"细胞核","note":"储存 DNA"},
+      {"at":[55,-30],"width":40,"height":22,"rotation":25,"label":"线粒体","note":"供能"},
+      {"shape":"polygon","points":[[-70,-40],[-40,-55],[-30,-30],[-60,-20]],"label":"高尔基体"}
+    ]}
+    ```
+
+Labels are laid out for you. Omit `labelAt` and each callout goes out to the side its part is already on, stacked down that side in top-to-bottom order — so a model can name six organelles without also solving a layout problem whose result it cannot see. Give `labelAt` to place one yourself.
+
+`y` increases upwards, the same convention as [`@ai-gui/plugin-physics`](../plugin-physics), so a lesson that draws both does not hold two conventions at once.
+
+Complex outlines are a `polygon`: a point list can be validated, where hand-written path data cannot. Nothing is shipped as artwork, so nothing here decides which figures a curriculum may teach.
+
+## API
+
+- `figure(options?)` creates the AIGUI plugin.
+- `figurePromptSpec(options?)` returns the model-facing protocol description.
+- `parseFigure(source, options?)` strictly parses and validates a block.
+- `renderFigureSVG(diagram, options?)` renders a parsed figure.
+- `figureCss` contains the package styling.
+
+## Options
+
+- `width?: number`: the rendered maximum width in px, default `480`.
+- `height?: number`: the rendered maximum height in px, default `360`.
+- `maxParts?: number`: default `32`.
+- `maxSourceBytes?: number`: default 8 KiB.
+
+Unknown fields, URLs, non-finite coordinates, unknown shapes and fills, polygons under three points, and oversized blocks are rejected, and the block renders an error in place rather than a confident drawing of something the model did not mean.
+
+Colours come from `currentColor` and `--aigui-figure-*` custom properties, so a figure on a dark page is not drawn in ink chosen for a light one. Output is marked `trusted` because it is built from coordinates rather than from model markup; a sanitizer would otherwise strip the drawing.

package/dist/index.cjs

@@ -0,0 +1,395 @@
+"use strict";
+
+//#region src/index.ts
+const DEFAULTS = {
+	width: 480,
+	height: 360,
+	maxSourceBytes: 8 * 1024,
+	maxParts: 32
+};
+const FILLS = [
+	"none",
+	"tint",
+	"solid"
+];
+const SHAPES = [
+	"ellipse",
+	"rect",
+	"polygon",
+	"point"
+];
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function isFinitePoint(value) {
+	return Array.isArray(value) && value.length === 2 && value.every((part) => typeof part === "number" && Number.isFinite(part));
+}
+function num(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function round(value) {
+	return (Math.round(value * 100) / 100).toString();
+}
+/**
+* Read a figure out of a block, rejecting anything that is not one.
+*
+* Strict, like the other plugins that accept model output: a figure that half-parses would label a
+* shape the model did not mean, and a mislabelled diagram teaches the wrong thing confidently.
+*/
+function parseFigure(source, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	if (new TextEncoder().encode(source).byteLength > limits.maxSourceBytes) return {
+		valid: false,
+		issues: ["Figure is too large."]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return {
+			valid: false,
+			issues: ["Figure must be valid JSON."]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		valid: false,
+		issues: ["Figure must be a JSON object."]
+	};
+	const value = parsed;
+	if (value.version !== 1) return {
+		valid: false,
+		issues: ["Figure must declare \"version\": 1."]
+	};
+	if (!Array.isArray(value.parts)) return {
+		valid: false,
+		issues: ["$.parts must be an array."]
+	};
+	if (value.parts.length === 0) return {
+		valid: false,
+		issues: ["Figure must contain at least one part."]
+	};
+	if (value.parts.length > limits.maxParts) return {
+		valid: false,
+		issues: [`$.parts has more than ${limits.maxParts} entries.`]
+	};
+	const issues = [];
+	const parts = [];
+	value.parts.forEach((raw, index) => {
+		const path = `$.parts[${index}]`;
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+			issues.push(`${path} must be an object.`);
+			return;
+		}
+		const item = raw;
+		const shape = item.shape === void 0 ? "ellipse" : item.shape;
+		if (typeof shape !== "string" || !SHAPES.includes(shape)) {
+			issues.push(`${path}.shape must be one of ${SHAPES.join(", ")}.`);
+			return;
+		}
+		const fill = item.fill === void 0 ? "tint" : item.fill;
+		if (typeof fill !== "string" || !FILLS.includes(fill)) {
+			issues.push(`${path}.fill must be one of ${FILLS.join(", ")}.`);
+			return;
+		}
+		if (shape === "polygon") {
+			if (!Array.isArray(item.points) || item.points.length < 3) {
+				issues.push(`${path}.points must be at least three [x,y] pairs.`);
+				return;
+			}
+			if (item.points.length > 200) {
+				issues.push(`${path}.points has more than 200 points.`);
+				return;
+			}
+			if (!item.points.every(isFinitePoint)) {
+				issues.push(`${path}.points must all be two finite numbers.`);
+				return;
+			}
+		} else if (!isFinitePoint(item.at)) {
+			issues.push(`${path}.at must be two finite numbers.`);
+			return;
+		}
+		parts.push({
+			shape,
+			fill,
+			...isFinitePoint(item.at) ? { at: item.at } : {},
+			...shape === "polygon" ? { points: item.points } : {},
+			width: num(item.width, 80),
+			height: num(item.height, 60),
+			rotation: num(item.rotation, 0),
+			...typeof item.label === "string" ? { label: item.label } : {},
+			...typeof item.note === "string" ? { note: item.note } : {},
+			...isFinitePoint(item.labelAt) ? { labelAt: item.labelAt } : {}
+		});
+	});
+	if (issues.length > 0) return {
+		valid: false,
+		issues
+	};
+	return {
+		valid: true,
+		data: {
+			version: 1,
+			...Array.isArray(value.view) && value.view.length === 4 && value.view.every((part) => typeof part === "number" && Number.isFinite(part)) ? { view: value.view } : {},
+			...typeof value.title === "string" ? { title: value.title } : {},
+			...typeof value.caption === "string" ? { caption: value.caption } : {},
+			parts
+		}
+	};
+}
+/** Where a part sits, and how far it reaches. */
+function boundsOf(part) {
+	if (part.shape === "polygon" && part.points) {
+		const xs = part.points.map((point) => point[0]);
+		const ys = part.points.map((point) => point[1]);
+		const minX = Math.min(...xs);
+		const maxX = Math.max(...xs);
+		const minY = Math.min(...ys);
+		const maxY = Math.max(...ys);
+		return {
+			at: [(minX + maxX) / 2, (minY + maxY) / 2],
+			halfWidth: (maxX - minX) / 2,
+			halfHeight: (maxY - minY) / 2
+		};
+	}
+	const at = part.at ?? [0, 0];
+	if (part.shape === "point") return {
+		at,
+		halfWidth: 4,
+		halfHeight: 4
+	};
+	return {
+		at,
+		halfWidth: (part.width ?? 80) / 2,
+		halfHeight: (part.height ?? 60) / 2
+	};
+}
+/** The box the figure occupies, before room is made for the labels beside it. */
+function figureBounds(diagram) {
+	const xs = [];
+	const ys = [];
+	for (const part of diagram.parts) {
+		const { at, halfWidth, halfHeight } = boundsOf(part);
+		xs.push(at[0] - halfWidth, at[0] + halfWidth);
+		ys.push(at[1] - halfHeight, at[1] + halfHeight);
+	}
+	if (xs.length === 0) return [
+		0,
+		0,
+		100,
+		100
+	];
+	return [
+		Math.min(...xs),
+		Math.min(...ys),
+		Math.max(...xs),
+		Math.max(...ys)
+	];
+}
+/**
+* Decide where each label goes.
+*
+* A label the model placed is left where it put it. The rest go out to the side the part is already
+* on and are stacked down it, evenly spread and in the order they appear top to bottom — the
+* arrangement a textbook plate uses, so a model can name six organelles without also solving a
+* layout problem whose result it cannot see.
+*
+* The side has to follow the part, not its turn in the list. Alternating sides sends the leader for
+* a part on the left out to the right, straight across everything drawn in between, and a figure
+* whose lines cross the thing they are labelling cannot be read.
+*/
+function layOutCallouts(diagram, bounds) {
+	const [minX, minY, maxX, maxY] = bounds;
+	const centreX = (minX + maxX) / 2;
+	const labelled = diagram.parts.filter((part) => part.label !== void 0);
+	const placed = [];
+	const gutter = 56;
+	const automatic = [];
+	for (const part of labelled) {
+		if (part.labelAt) {
+			const { at: at$1 } = boundsOf(part);
+			placed.push({
+				part,
+				at: part.labelAt,
+				side: part.labelAt[0] < at$1[0] ? "left" : "right"
+			});
+			continue;
+		}
+		const { at } = boundsOf(part);
+		automatic.push({
+			part,
+			side: at[0] <= centreX ? "left" : "right",
+			y: at[1]
+		});
+	}
+	for (const side of ["left", "right"]) {
+		const column = automatic.filter((entry) => entry.side === side);
+		column.sort((left, right) => right.y - left.y);
+		const span = maxY - minY;
+		const step = column.length > 1 ? span / (column.length - 1) : 0;
+		column.forEach((entry, index) => {
+			const y = column.length > 1 ? maxY - index * step : (minY + maxY) / 2;
+			placed.push({
+				part: entry.part,
+				at: [side === "left" ? minX - gutter : maxX + gutter, y],
+				side
+			});
+		});
+	}
+	return placed;
+}
+/** The point on a part's edge a leader line should meet, coming from `towards`. */
+function anchorOn(part, towards) {
+	const { at, halfWidth, halfHeight } = boundsOf(part);
+	const dx = towards[0] - at[0];
+	const dy = towards[1] - at[1];
+	const distance = Math.hypot(dx, dy);
+	if (distance === 0) return at;
+	const scale = Math.min(1, Math.hypot(halfWidth, halfHeight) / distance);
+	return [at[0] + dx * scale * .95, at[1] + dy * scale * .95];
+}
+/**
+* Draw the figure.
+*
+* The y axis is flipped once in the outer transform, the same way `@ai-gui/plugin-physics` does it,
+* so a lesson that draws both does not have to hold two conventions at once. Every text node flips
+* back so it stays upright.
+*/
+function renderFigureSVG(diagram, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	const bounds = figureBounds(diagram);
+	const callouts = layOutCallouts(diagram, bounds);
+	const parts = [];
+	for (const part of diagram.parts) {
+		const rotation = part.rotation && part.shape !== "polygon" ? ` transform="rotate(${round(part.rotation)} ${round((part.at ?? [0, 0])[0])} ${round((part.at ?? [0, 0])[1])})"` : "";
+		const fill = ` class="aigui-figure-part aigui-figure-fill-${part.fill ?? "tint"}"`;
+		if (part.shape === "polygon" && part.points) {
+			const points = part.points.map((point) => `${round(point[0])},${round(point[1])}`).join(" ");
+			parts.push(`<polygon points="${points}"${fill} />`);
+		} else if (part.shape === "point") {
+			const at = part.at ?? [0, 0];
+			parts.push(`<circle cx="${round(at[0])}" cy="${round(at[1])}" r="4" class="aigui-figure-point" />`);
+		} else if (part.shape === "rect") {
+			const at = part.at ?? [0, 0];
+			const width$1 = part.width ?? 80;
+			const height$1 = part.height ?? 60;
+			parts.push(`<rect x="${round(at[0] - width$1 / 2)}" y="${round(at[1] - height$1 / 2)}" width="${round(width$1)}" height="${round(height$1)}" rx="4"${fill}${rotation} />`);
+		} else {
+			const at = part.at ?? [0, 0];
+			parts.push(`<ellipse cx="${round(at[0])}" cy="${round(at[1])}" rx="${round((part.width ?? 80) / 2)}" ry="${round((part.height ?? 60) / 2)}"${fill}${rotation} />`);
+		}
+	}
+	for (const callout of callouts) {
+		const anchor = anchorOn(callout.part, callout.at);
+		const elbowX = callout.side === "left" ? callout.at[0] + 12 : callout.at[0] - 12;
+		parts.push(`<path d="M ${round(anchor[0])} ${round(anchor[1])} L ${round(elbowX)} ${round(callout.at[1])} L ${round(callout.at[0])} ${round(callout.at[1])}" class="aigui-figure-leader" />`, `<circle cx="${round(anchor[0])}" cy="${round(anchor[1])}" r="2.5" class="aigui-figure-leader-dot" />`);
+		const anchorAttribute = callout.side === "left" ? "end" : "start";
+		const flip = `transform="scale(1,-1)" transform-origin="${round(callout.at[0])} ${round(callout.at[1])}"`;
+		parts.push(`<text x="${round(callout.at[0])}" y="${round(callout.at[1])}" class="aigui-figure-label" text-anchor="${anchorAttribute}" ${flip}>${escapeHtml(callout.part.label ?? "")}</text>`);
+		if (callout.part.note) parts.push(`<text x="${round(callout.at[0])}" y="${round(callout.at[1] - 15)}" class="aigui-figure-note" text-anchor="${anchorAttribute}" transform="scale(1,-1)" transform-origin="${round(callout.at[0])} ${round(callout.at[1] - 15)}">${escapeHtml(callout.part.note)}</text>`);
+	}
+	const view = diagram.view ?? viewWithCallouts(bounds, callouts, Boolean(diagram.caption));
+	const [minX, minY, maxX, maxY] = view;
+	const width = Math.max(1, maxX - minX);
+	const height = Math.max(1, maxY - minY);
+	if (diagram.caption) {
+		const y = minY + 14;
+		parts.push(`<text x="${round((minX + maxX) / 2)}" y="${round(y)}" class="aigui-figure-caption" text-anchor="middle" transform="scale(1,-1)" transform-origin="${round((minX + maxX) / 2)} ${round(y)}">${escapeHtml(diagram.caption)}</text>`);
+	}
+	const title = diagram.title ? `<title>${escapeHtml(diagram.title)}</title>` : "";
+	return [
+		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="${round(minX)} ${round(minY)} ${round(width)} ${round(height)}"`,
+		` width="100%" style="max-width:${limits.width}px;max-height:${limits.height}px;display:block;margin:auto"`,
+		` role="img" aria-label="${escapeHtml(diagram.title ?? diagram.caption ?? "Labelled figure")}" data-aigui-figure="diagram">`,
+		title,
+		`<g transform="translate(0, ${round(minY + maxY)}) scale(1, -1)">`,
+		parts.join(""),
+		"</g></svg>"
+	].join("");
+}
+/** Widen the drawing box until every callout, and the caption, is inside it. */
+function viewWithCallouts(bounds, callouts, hasCaption) {
+	const textRoom = 120;
+	const xs = [bounds[0], bounds[2]];
+	const ys = [bounds[1], bounds[3]];
+	for (const callout of callouts) {
+		xs.push(callout.side === "left" ? callout.at[0] - textRoom : callout.at[0] + textRoom);
+		ys.push(callout.at[1] - 20, callout.at[1] + 12);
+	}
+	const pad = 12;
+	return [
+		Math.min(...xs) - pad,
+		Math.min(...ys) - pad - (hasCaption ? 22 : 0),
+		Math.max(...xs) + pad,
+		Math.max(...ys) + pad
+	];
+}
+function figurePromptSpec(options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	return [
+		"Labelled figures (one fenced block): ```figure <strict JSON>```.",
+		"Root: {\"version\":1,\"title\":\"...\"?,\"caption\":\"...\"?,\"view\":[minX,minY,maxX,maxY]?,\"parts\":[...]}. No unknown fields.",
+		"Part: {\"shape\":\"ellipse|rect|polygon|point\"?,\"at\":[x,y],\"width\":n?,\"height\":n?,\"points\":[[x,y],...]?,\"rotation\":deg?,\"fill\":\"none|tint|solid\"?,\"label\":\"...\"?,\"note\":\"...\"?,\"labelAt\":[x,y]?}.",
+		"Give \"at\" for ellipse, rect and point; give \"points\" (three or more) for polygon. Default shape is ellipse, default fill is tint.",
+		"\"label\" is what the part is called and \"note\" is a shorter second line saying what it does. Omit \"labelAt\" and the labels are stacked down both sides with leader lines drawn for you.",
+		"Draw containers before the parts inside them, so an enclosing outline does not cover them.",
+		"y increases upwards, the same convention as ```physics.",
+		`Figure source is local JSON only, at most ${limits.maxSourceBytes} UTF-8 bytes. Never emit URLs, scripts, remote resources, HTML, or executable content.`,
+		"Use this when naming the parts is the lesson: cell organelles, a leaf's layers, apparatus, a labelled cross-section. Use ```mermaid for boxes joined by arrows and ```chart for data."
+	].join("\n");
+}
+const figureCss = `
+[data-aigui-figure] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }
+[data-aigui-figure] .aigui-figure-part { stroke: currentColor; stroke-width: 1.5; }
+[data-aigui-figure] .aigui-figure-fill-none { fill: none; }
+[data-aigui-figure] .aigui-figure-fill-tint { fill: var(--aigui-figure-tint, color-mix(in srgb, currentColor 10%, transparent)); }
+[data-aigui-figure] .aigui-figure-fill-solid { fill: var(--aigui-figure-solid, color-mix(in srgb, currentColor 28%, transparent)); }
+[data-aigui-figure] .aigui-figure-point { fill: currentColor; stroke: none; }
+[data-aigui-figure] .aigui-figure-leader { fill: none; stroke: var(--aigui-figure-leader, currentColor); stroke-width: 1; opacity: .6; }
+[data-aigui-figure] .aigui-figure-leader-dot { fill: var(--aigui-figure-leader, currentColor); opacity: .8; }
+[data-aigui-figure] .aigui-figure-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; fill: currentColor; }
+[data-aigui-figure] .aigui-figure-note { font-size: 11px; font-family: inherit; dominant-baseline: middle; fill: currentColor; opacity: .7; }
+[data-aigui-figure] .aigui-figure-caption { font-size: 12px; font-family: inherit; fill: currentColor; opacity: .75; }
+`;
+function errorHtml(issue) {
+	return {
+		kind: "html",
+		html: `<pre data-aigui-figure-error>${escapeHtml(issue)}</pre>`
+	};
+}
+function figure(options = {}) {
+	const render = (node) => {
+		const parsed = parseFigure(node.content ?? "", options);
+		if (!parsed.valid) return errorHtml(parsed.issues[0] ?? "Invalid figure.");
+		try {
+			return {
+				kind: "html",
+				html: renderFigureSVG(parsed.data, options),
+				trusted: true
+			};
+		} catch {
+			return errorHtml("Figure could not be drawn.");
+		}
+	};
+	return {
+		name: "figure",
+		nodeRenderers: { figure: render },
+		css: figureCss,
+		promptSpec: figurePromptSpec(options)
+	};
+}
+
+//#endregion
+exports.figure = figure
+exports.figureCss = figureCss
+exports.figurePromptSpec = figurePromptSpec
+exports.parseFigure = parseFigure
+exports.renderFigureSVG = renderFigureSVG

package/dist/index.d.cts

@@ -0,0 +1,94 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/**
+* Labelled figures: the diagram whose whole point is what the parts are called.
+*
+* A cell with its organelles named, a leaf's layers, a piece of apparatus with the parts a method
+* refers to. Mermaid draws boxes joined by arrows and a chart draws data; neither draws a shape with
+* "细胞核 — 储存 DNA" on a leader line pointing into it, which is the figure a biology lesson is
+* built around.
+*
+* The model composes the shapes and writes the callouts. Nothing is shipped as artwork, so nothing
+* here decides which figures a curriculum is allowed to teach — an ellipse inside an ellipse is a
+* crude cell, but it is the learner's cell, labelled with what this lesson is about. Complex
+* outlines are a polygon: a point list can be checked, where a hand-written path cannot.
+*/
+/**
+ * Labelled figures: the diagram whose whole point is what the parts are called.
+ *
+ * A cell with its organelles named, a leaf's layers, a piece of apparatus with the parts a method
+ * refers to. Mermaid draws boxes joined by arrows and a chart draws data; neither draws a shape with
+ * "细胞核 — 储存 DNA" on a leader line pointing into it, which is the figure a biology lesson is
+ * built around.
+ *
+ * The model composes the shapes and writes the callouts. Nothing is shipped as artwork, so nothing
+ * here decides which figures a curriculum is allowed to teach — an ellipse inside an ellipse is a
+ * crude cell, but it is the learner's cell, labelled with what this lesson is about. Complex
+ * outlines are a polygon: a point list can be checked, where a hand-written path cannot.
+ */
+type PartShape = "ellipse" | "rect" | "polygon" | "point";
+/** How much a part's interior is filled, so nesting reads as nesting. */
+type PartFill = "none" | "tint" | "solid";
+interface FigurePart {
+  shape?: PartShape;
+  /** Centre, for an ellipse, a rect or a point. */
+  at?: [number, number];
+  width?: number;
+  height?: number;
+  /** The outline, for a polygon. Closed automatically. */
+  points?: [number, number][];
+  /** Degrees, counter-clockwise. */
+  rotation?: number;
+  fill?: PartFill;
+  /** What this part is called. Omit for a part that is only there to be drawn. */
+  label?: string;
+  /** A second, quieter line under the label: what it does, why it matters. */
+  note?: string;
+  /**
+   * Where the callout text sits. Omitted, labels are stacked down the sides of the figure with
+   * leader lines drawn to them — the arrangement a textbook plate uses.
+   */
+  labelAt?: [number, number];
+}
+interface FigureDiagram {
+  version: 1;
+  /** The coordinate box the figure is drawn in: [minX, minY, maxX, maxY]. */
+  view?: [number, number, number, number];
+  title?: string;
+  /** A line under the figure: what it is a figure of. */
+  caption?: string;
+  parts: FigurePart[];
+}
+interface FigureOptions {
+  width?: number;
+  height?: number;
+  maxSourceBytes?: number;
+  /** How many parts to draw before refusing — a runaway block is not a figure. */
+  maxParts?: number;
+}
+/**
+ * Read a figure out of a block, rejecting anything that is not one.
+ *
+ * Strict, like the other plugins that accept model output: a figure that half-parses would label a
+ * shape the model did not mean, and a mislabelled diagram teaches the wrong thing confidently.
+ */
+declare function parseFigure(source: string, options?: FigureOptions): {
+  valid: true;
+  data: FigureDiagram;
+} | {
+  valid: false;
+  issues: string[];
+};
+/**
+ * Draw the figure.
+ *
+ * The y axis is flipped once in the outer transform, the same way `@ai-gui/plugin-physics` does it,
+ * so a lesson that draws both does not have to hold two conventions at once. Every text node flips
+ * back so it stays upright.
+ */
+declare function renderFigureSVG(diagram: FigureDiagram, options?: FigureOptions): string;
+declare function figurePromptSpec(options?: FigureOptions): string;
+declare const figureCss = "\n[data-aigui-figure] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }\n[data-aigui-figure] .aigui-figure-part { stroke: currentColor; stroke-width: 1.5; }\n[data-aigui-figure] .aigui-figure-fill-none { fill: none; }\n[data-aigui-figure] .aigui-figure-fill-tint { fill: var(--aigui-figure-tint, color-mix(in srgb, currentColor 10%, transparent)); }\n[data-aigui-figure] .aigui-figure-fill-solid { fill: var(--aigui-figure-solid, color-mix(in srgb, currentColor 28%, transparent)); }\n[data-aigui-figure] .aigui-figure-point { fill: currentColor; stroke: none; }\n[data-aigui-figure] .aigui-figure-leader { fill: none; stroke: var(--aigui-figure-leader, currentColor); stroke-width: 1; opacity: .6; }\n[data-aigui-figure] .aigui-figure-leader-dot { fill: var(--aigui-figure-leader, currentColor); opacity: .8; }\n[data-aigui-figure] .aigui-figure-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; fill: currentColor; }\n[data-aigui-figure] .aigui-figure-note { font-size: 11px; font-family: inherit; dominant-baseline: middle; fill: currentColor; opacity: .7; }\n[data-aigui-figure] .aigui-figure-caption { font-size: 12px; font-family: inherit; fill: currentColor; opacity: .75; }\n";
+declare function figure(options?: FigureOptions): AIGuiPlugin; //#endregion
+export { FigureDiagram, FigureOptions, FigurePart, PartFill, PartShape, figure, figureCss, figurePromptSpec, parseFigure, renderFigureSVG };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/**
+* Labelled figures: the diagram whose whole point is what the parts are called.
+*
+* A cell with its organelles named, a leaf's layers, a piece of apparatus with the parts a method
+* refers to. Mermaid draws boxes joined by arrows and a chart draws data; neither draws a shape with
+* "细胞核 — 储存 DNA" on a leader line pointing into it, which is the figure a biology lesson is
+* built around.
+*
+* The model composes the shapes and writes the callouts. Nothing is shipped as artwork, so nothing
+* here decides which figures a curriculum is allowed to teach — an ellipse inside an ellipse is a
+* crude cell, but it is the learner's cell, labelled with what this lesson is about. Complex
+* outlines are a polygon: a point list can be checked, where a hand-written path cannot.
+*/
+/**
+ * Labelled figures: the diagram whose whole point is what the parts are called.
+ *
+ * A cell with its organelles named, a leaf's layers, a piece of apparatus with the parts a method
+ * refers to. Mermaid draws boxes joined by arrows and a chart draws data; neither draws a shape with
+ * "细胞核 — 储存 DNA" on a leader line pointing into it, which is the figure a biology lesson is
+ * built around.
+ *
+ * The model composes the shapes and writes the callouts. Nothing is shipped as artwork, so nothing
+ * here decides which figures a curriculum is allowed to teach — an ellipse inside an ellipse is a
+ * crude cell, but it is the learner's cell, labelled with what this lesson is about. Complex
+ * outlines are a polygon: a point list can be checked, where a hand-written path cannot.
+ */
+type PartShape = "ellipse" | "rect" | "polygon" | "point";
+/** How much a part's interior is filled, so nesting reads as nesting. */
+type PartFill = "none" | "tint" | "solid";
+interface FigurePart {
+  shape?: PartShape;
+  /** Centre, for an ellipse, a rect or a point. */
+  at?: [number, number];
+  width?: number;
+  height?: number;
+  /** The outline, for a polygon. Closed automatically. */
+  points?: [number, number][];
+  /** Degrees, counter-clockwise. */
+  rotation?: number;
+  fill?: PartFill;
+  /** What this part is called. Omit for a part that is only there to be drawn. */
+  label?: string;
+  /** A second, quieter line under the label: what it does, why it matters. */
+  note?: string;
+  /**
+   * Where the callout text sits. Omitted, labels are stacked down the sides of the figure with
+   * leader lines drawn to them — the arrangement a textbook plate uses.
+   */
+  labelAt?: [number, number];
+}
+interface FigureDiagram {
+  version: 1;
+  /** The coordinate box the figure is drawn in: [minX, minY, maxX, maxY]. */
+  view?: [number, number, number, number];
+  title?: string;
+  /** A line under the figure: what it is a figure of. */
+  caption?: string;
+  parts: FigurePart[];
+}
+interface FigureOptions {
+  width?: number;
+  height?: number;
+  maxSourceBytes?: number;
+  /** How many parts to draw before refusing — a runaway block is not a figure. */
+  maxParts?: number;
+}
+/**
+ * Read a figure out of a block, rejecting anything that is not one.
+ *
+ * Strict, like the other plugins that accept model output: a figure that half-parses would label a
+ * shape the model did not mean, and a mislabelled diagram teaches the wrong thing confidently.
+ */
+declare function parseFigure(source: string, options?: FigureOptions): {
+  valid: true;
+  data: FigureDiagram;
+} | {
+  valid: false;
+  issues: string[];
+};
+/**
+ * Draw the figure.
+ *
+ * The y axis is flipped once in the outer transform, the same way `@ai-gui/plugin-physics` does it,
+ * so a lesson that draws both does not have to hold two conventions at once. Every text node flips
+ * back so it stays upright.
+ */
+declare function renderFigureSVG(diagram: FigureDiagram, options?: FigureOptions): string;
+declare function figurePromptSpec(options?: FigureOptions): string;
+declare const figureCss = "\n[data-aigui-figure] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }\n[data-aigui-figure] .aigui-figure-part { stroke: currentColor; stroke-width: 1.5; }\n[data-aigui-figure] .aigui-figure-fill-none { fill: none; }\n[data-aigui-figure] .aigui-figure-fill-tint { fill: var(--aigui-figure-tint, color-mix(in srgb, currentColor 10%, transparent)); }\n[data-aigui-figure] .aigui-figure-fill-solid { fill: var(--aigui-figure-solid, color-mix(in srgb, currentColor 28%, transparent)); }\n[data-aigui-figure] .aigui-figure-point { fill: currentColor; stroke: none; }\n[data-aigui-figure] .aigui-figure-leader { fill: none; stroke: var(--aigui-figure-leader, currentColor); stroke-width: 1; opacity: .6; }\n[data-aigui-figure] .aigui-figure-leader-dot { fill: var(--aigui-figure-leader, currentColor); opacity: .8; }\n[data-aigui-figure] .aigui-figure-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; fill: currentColor; }\n[data-aigui-figure] .aigui-figure-note { font-size: 11px; font-family: inherit; dominant-baseline: middle; fill: currentColor; opacity: .7; }\n[data-aigui-figure] .aigui-figure-caption { font-size: 12px; font-family: inherit; fill: currentColor; opacity: .75; }\n";
+declare function figure(options?: FigureOptions): AIGuiPlugin; //#endregion
+export { FigureDiagram, FigureOptions, FigurePart, PartFill, PartShape, figure, figureCss, figurePromptSpec, parseFigure, renderFigureSVG };

package/dist/index.js

@@ -0,0 +1,389 @@
+//#region src/index.ts
+const DEFAULTS = {
+	width: 480,
+	height: 360,
+	maxSourceBytes: 8 * 1024,
+	maxParts: 32
+};
+const FILLS = [
+	"none",
+	"tint",
+	"solid"
+];
+const SHAPES = [
+	"ellipse",
+	"rect",
+	"polygon",
+	"point"
+];
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function isFinitePoint(value) {
+	return Array.isArray(value) && value.length === 2 && value.every((part) => typeof part === "number" && Number.isFinite(part));
+}
+function num(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function round(value) {
+	return (Math.round(value * 100) / 100).toString();
+}
+/**
+* Read a figure out of a block, rejecting anything that is not one.
+*
+* Strict, like the other plugins that accept model output: a figure that half-parses would label a
+* shape the model did not mean, and a mislabelled diagram teaches the wrong thing confidently.
+*/
+function parseFigure(source, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	if (new TextEncoder().encode(source).byteLength > limits.maxSourceBytes) return {
+		valid: false,
+		issues: ["Figure is too large."]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return {
+			valid: false,
+			issues: ["Figure must be valid JSON."]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		valid: false,
+		issues: ["Figure must be a JSON object."]
+	};
+	const value = parsed;
+	if (value.version !== 1) return {
+		valid: false,
+		issues: ["Figure must declare \"version\": 1."]
+	};
+	if (!Array.isArray(value.parts)) return {
+		valid: false,
+		issues: ["$.parts must be an array."]
+	};
+	if (value.parts.length === 0) return {
+		valid: false,
+		issues: ["Figure must contain at least one part."]
+	};
+	if (value.parts.length > limits.maxParts) return {
+		valid: false,
+		issues: [`$.parts has more than ${limits.maxParts} entries.`]
+	};
+	const issues = [];
+	const parts = [];
+	value.parts.forEach((raw, index) => {
+		const path = `$.parts[${index}]`;
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+			issues.push(`${path} must be an object.`);
+			return;
+		}
+		const item = raw;
+		const shape = item.shape === void 0 ? "ellipse" : item.shape;
+		if (typeof shape !== "string" || !SHAPES.includes(shape)) {
+			issues.push(`${path}.shape must be one of ${SHAPES.join(", ")}.`);
+			return;
+		}
+		const fill = item.fill === void 0 ? "tint" : item.fill;
+		if (typeof fill !== "string" || !FILLS.includes(fill)) {
+			issues.push(`${path}.fill must be one of ${FILLS.join(", ")}.`);
+			return;
+		}
+		if (shape === "polygon") {
+			if (!Array.isArray(item.points) || item.points.length < 3) {
+				issues.push(`${path}.points must be at least three [x,y] pairs.`);
+				return;
+			}
+			if (item.points.length > 200) {
+				issues.push(`${path}.points has more than 200 points.`);
+				return;
+			}
+			if (!item.points.every(isFinitePoint)) {
+				issues.push(`${path}.points must all be two finite numbers.`);
+				return;
+			}
+		} else if (!isFinitePoint(item.at)) {
+			issues.push(`${path}.at must be two finite numbers.`);
+			return;
+		}
+		parts.push({
+			shape,
+			fill,
+			...isFinitePoint(item.at) ? { at: item.at } : {},
+			...shape === "polygon" ? { points: item.points } : {},
+			width: num(item.width, 80),
+			height: num(item.height, 60),
+			rotation: num(item.rotation, 0),
+			...typeof item.label === "string" ? { label: item.label } : {},
+			...typeof item.note === "string" ? { note: item.note } : {},
+			...isFinitePoint(item.labelAt) ? { labelAt: item.labelAt } : {}
+		});
+	});
+	if (issues.length > 0) return {
+		valid: false,
+		issues
+	};
+	return {
+		valid: true,
+		data: {
+			version: 1,
+			...Array.isArray(value.view) && value.view.length === 4 && value.view.every((part) => typeof part === "number" && Number.isFinite(part)) ? { view: value.view } : {},
+			...typeof value.title === "string" ? { title: value.title } : {},
+			...typeof value.caption === "string" ? { caption: value.caption } : {},
+			parts
+		}
+	};
+}
+/** Where a part sits, and how far it reaches. */
+function boundsOf(part) {
+	if (part.shape === "polygon" && part.points) {
+		const xs = part.points.map((point) => point[0]);
+		const ys = part.points.map((point) => point[1]);
+		const minX = Math.min(...xs);
+		const maxX = Math.max(...xs);
+		const minY = Math.min(...ys);
+		const maxY = Math.max(...ys);
+		return {
+			at: [(minX + maxX) / 2, (minY + maxY) / 2],
+			halfWidth: (maxX - minX) / 2,
+			halfHeight: (maxY - minY) / 2
+		};
+	}
+	const at = part.at ?? [0, 0];
+	if (part.shape === "point") return {
+		at,
+		halfWidth: 4,
+		halfHeight: 4
+	};
+	return {
+		at,
+		halfWidth: (part.width ?? 80) / 2,
+		halfHeight: (part.height ?? 60) / 2
+	};
+}
+/** The box the figure occupies, before room is made for the labels beside it. */
+function figureBounds(diagram) {
+	const xs = [];
+	const ys = [];
+	for (const part of diagram.parts) {
+		const { at, halfWidth, halfHeight } = boundsOf(part);
+		xs.push(at[0] - halfWidth, at[0] + halfWidth);
+		ys.push(at[1] - halfHeight, at[1] + halfHeight);
+	}
+	if (xs.length === 0) return [
+		0,
+		0,
+		100,
+		100
+	];
+	return [
+		Math.min(...xs),
+		Math.min(...ys),
+		Math.max(...xs),
+		Math.max(...ys)
+	];
+}
+/**
+* Decide where each label goes.
+*
+* A label the model placed is left where it put it. The rest go out to the side the part is already
+* on and are stacked down it, evenly spread and in the order they appear top to bottom — the
+* arrangement a textbook plate uses, so a model can name six organelles without also solving a
+* layout problem whose result it cannot see.
+*
+* The side has to follow the part, not its turn in the list. Alternating sides sends the leader for
+* a part on the left out to the right, straight across everything drawn in between, and a figure
+* whose lines cross the thing they are labelling cannot be read.
+*/
+function layOutCallouts(diagram, bounds) {
+	const [minX, minY, maxX, maxY] = bounds;
+	const centreX = (minX + maxX) / 2;
+	const labelled = diagram.parts.filter((part) => part.label !== void 0);
+	const placed = [];
+	const gutter = 56;
+	const automatic = [];
+	for (const part of labelled) {
+		if (part.labelAt) {
+			const { at: at$1 } = boundsOf(part);
+			placed.push({
+				part,
+				at: part.labelAt,
+				side: part.labelAt[0] < at$1[0] ? "left" : "right"
+			});
+			continue;
+		}
+		const { at } = boundsOf(part);
+		automatic.push({
+			part,
+			side: at[0] <= centreX ? "left" : "right",
+			y: at[1]
+		});
+	}
+	for (const side of ["left", "right"]) {
+		const column = automatic.filter((entry) => entry.side === side);
+		column.sort((left, right) => right.y - left.y);
+		const span = maxY - minY;
+		const step = column.length > 1 ? span / (column.length - 1) : 0;
+		column.forEach((entry, index) => {
+			const y = column.length > 1 ? maxY - index * step : (minY + maxY) / 2;
+			placed.push({
+				part: entry.part,
+				at: [side === "left" ? minX - gutter : maxX + gutter, y],
+				side
+			});
+		});
+	}
+	return placed;
+}
+/** The point on a part's edge a leader line should meet, coming from `towards`. */
+function anchorOn(part, towards) {
+	const { at, halfWidth, halfHeight } = boundsOf(part);
+	const dx = towards[0] - at[0];
+	const dy = towards[1] - at[1];
+	const distance = Math.hypot(dx, dy);
+	if (distance === 0) return at;
+	const scale = Math.min(1, Math.hypot(halfWidth, halfHeight) / distance);
+	return [at[0] + dx * scale * .95, at[1] + dy * scale * .95];
+}
+/**
+* Draw the figure.
+*
+* The y axis is flipped once in the outer transform, the same way `@ai-gui/plugin-physics` does it,
+* so a lesson that draws both does not have to hold two conventions at once. Every text node flips
+* back so it stays upright.
+*/
+function renderFigureSVG(diagram, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	const bounds = figureBounds(diagram);
+	const callouts = layOutCallouts(diagram, bounds);
+	const parts = [];
+	for (const part of diagram.parts) {
+		const rotation = part.rotation && part.shape !== "polygon" ? ` transform="rotate(${round(part.rotation)} ${round((part.at ?? [0, 0])[0])} ${round((part.at ?? [0, 0])[1])})"` : "";
+		const fill = ` class="aigui-figure-part aigui-figure-fill-${part.fill ?? "tint"}"`;
+		if (part.shape === "polygon" && part.points) {
+			const points = part.points.map((point) => `${round(point[0])},${round(point[1])}`).join(" ");
+			parts.push(`<polygon points="${points}"${fill} />`);
+		} else if (part.shape === "point") {
+			const at = part.at ?? [0, 0];
+			parts.push(`<circle cx="${round(at[0])}" cy="${round(at[1])}" r="4" class="aigui-figure-point" />`);
+		} else if (part.shape === "rect") {
+			const at = part.at ?? [0, 0];
+			const width$1 = part.width ?? 80;
+			const height$1 = part.height ?? 60;
+			parts.push(`<rect x="${round(at[0] - width$1 / 2)}" y="${round(at[1] - height$1 / 2)}" width="${round(width$1)}" height="${round(height$1)}" rx="4"${fill}${rotation} />`);
+		} else {
+			const at = part.at ?? [0, 0];
+			parts.push(`<ellipse cx="${round(at[0])}" cy="${round(at[1])}" rx="${round((part.width ?? 80) / 2)}" ry="${round((part.height ?? 60) / 2)}"${fill}${rotation} />`);
+		}
+	}
+	for (const callout of callouts) {
+		const anchor = anchorOn(callout.part, callout.at);
+		const elbowX = callout.side === "left" ? callout.at[0] + 12 : callout.at[0] - 12;
+		parts.push(`<path d="M ${round(anchor[0])} ${round(anchor[1])} L ${round(elbowX)} ${round(callout.at[1])} L ${round(callout.at[0])} ${round(callout.at[1])}" class="aigui-figure-leader" />`, `<circle cx="${round(anchor[0])}" cy="${round(anchor[1])}" r="2.5" class="aigui-figure-leader-dot" />`);
+		const anchorAttribute = callout.side === "left" ? "end" : "start";
+		const flip = `transform="scale(1,-1)" transform-origin="${round(callout.at[0])} ${round(callout.at[1])}"`;
+		parts.push(`<text x="${round(callout.at[0])}" y="${round(callout.at[1])}" class="aigui-figure-label" text-anchor="${anchorAttribute}" ${flip}>${escapeHtml(callout.part.label ?? "")}</text>`);
+		if (callout.part.note) parts.push(`<text x="${round(callout.at[0])}" y="${round(callout.at[1] - 15)}" class="aigui-figure-note" text-anchor="${anchorAttribute}" transform="scale(1,-1)" transform-origin="${round(callout.at[0])} ${round(callout.at[1] - 15)}">${escapeHtml(callout.part.note)}</text>`);
+	}
+	const view = diagram.view ?? viewWithCallouts(bounds, callouts, Boolean(diagram.caption));
+	const [minX, minY, maxX, maxY] = view;
+	const width = Math.max(1, maxX - minX);
+	const height = Math.max(1, maxY - minY);
+	if (diagram.caption) {
+		const y = minY + 14;
+		parts.push(`<text x="${round((minX + maxX) / 2)}" y="${round(y)}" class="aigui-figure-caption" text-anchor="middle" transform="scale(1,-1)" transform-origin="${round((minX + maxX) / 2)} ${round(y)}">${escapeHtml(diagram.caption)}</text>`);
+	}
+	const title = diagram.title ? `<title>${escapeHtml(diagram.title)}</title>` : "";
+	return [
+		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="${round(minX)} ${round(minY)} ${round(width)} ${round(height)}"`,
+		` width="100%" style="max-width:${limits.width}px;max-height:${limits.height}px;display:block;margin:auto"`,
+		` role="img" aria-label="${escapeHtml(diagram.title ?? diagram.caption ?? "Labelled figure")}" data-aigui-figure="diagram">`,
+		title,
+		`<g transform="translate(0, ${round(minY + maxY)}) scale(1, -1)">`,
+		parts.join(""),
+		"</g></svg>"
+	].join("");
+}
+/** Widen the drawing box until every callout, and the caption, is inside it. */
+function viewWithCallouts(bounds, callouts, hasCaption) {
+	const textRoom = 120;
+	const xs = [bounds[0], bounds[2]];
+	const ys = [bounds[1], bounds[3]];
+	for (const callout of callouts) {
+		xs.push(callout.side === "left" ? callout.at[0] - textRoom : callout.at[0] + textRoom);
+		ys.push(callout.at[1] - 20, callout.at[1] + 12);
+	}
+	const pad = 12;
+	return [
+		Math.min(...xs) - pad,
+		Math.min(...ys) - pad - (hasCaption ? 22 : 0),
+		Math.max(...xs) + pad,
+		Math.max(...ys) + pad
+	];
+}
+function figurePromptSpec(options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	return [
+		"Labelled figures (one fenced block): ```figure <strict JSON>```.",
+		"Root: {\"version\":1,\"title\":\"...\"?,\"caption\":\"...\"?,\"view\":[minX,minY,maxX,maxY]?,\"parts\":[...]}. No unknown fields.",
+		"Part: {\"shape\":\"ellipse|rect|polygon|point\"?,\"at\":[x,y],\"width\":n?,\"height\":n?,\"points\":[[x,y],...]?,\"rotation\":deg?,\"fill\":\"none|tint|solid\"?,\"label\":\"...\"?,\"note\":\"...\"?,\"labelAt\":[x,y]?}.",
+		"Give \"at\" for ellipse, rect and point; give \"points\" (three or more) for polygon. Default shape is ellipse, default fill is tint.",
+		"\"label\" is what the part is called and \"note\" is a shorter second line saying what it does. Omit \"labelAt\" and the labels are stacked down both sides with leader lines drawn for you.",
+		"Draw containers before the parts inside them, so an enclosing outline does not cover them.",
+		"y increases upwards, the same convention as ```physics.",
+		`Figure source is local JSON only, at most ${limits.maxSourceBytes} UTF-8 bytes. Never emit URLs, scripts, remote resources, HTML, or executable content.`,
+		"Use this when naming the parts is the lesson: cell organelles, a leaf's layers, apparatus, a labelled cross-section. Use ```mermaid for boxes joined by arrows and ```chart for data."
+	].join("\n");
+}
+const figureCss = `
+[data-aigui-figure] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }
+[data-aigui-figure] .aigui-figure-part { stroke: currentColor; stroke-width: 1.5; }
+[data-aigui-figure] .aigui-figure-fill-none { fill: none; }
+[data-aigui-figure] .aigui-figure-fill-tint { fill: var(--aigui-figure-tint, color-mix(in srgb, currentColor 10%, transparent)); }
+[data-aigui-figure] .aigui-figure-fill-solid { fill: var(--aigui-figure-solid, color-mix(in srgb, currentColor 28%, transparent)); }
+[data-aigui-figure] .aigui-figure-point { fill: currentColor; stroke: none; }
+[data-aigui-figure] .aigui-figure-leader { fill: none; stroke: var(--aigui-figure-leader, currentColor); stroke-width: 1; opacity: .6; }
+[data-aigui-figure] .aigui-figure-leader-dot { fill: var(--aigui-figure-leader, currentColor); opacity: .8; }
+[data-aigui-figure] .aigui-figure-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; fill: currentColor; }
+[data-aigui-figure] .aigui-figure-note { font-size: 11px; font-family: inherit; dominant-baseline: middle; fill: currentColor; opacity: .7; }
+[data-aigui-figure] .aigui-figure-caption { font-size: 12px; font-family: inherit; fill: currentColor; opacity: .75; }
+`;
+function errorHtml(issue) {
+	return {
+		kind: "html",
+		html: `<pre data-aigui-figure-error>${escapeHtml(issue)}</pre>`
+	};
+}
+function figure(options = {}) {
+	const render = (node) => {
+		const parsed = parseFigure(node.content ?? "", options);
+		if (!parsed.valid) return errorHtml(parsed.issues[0] ?? "Invalid figure.");
+		try {
+			return {
+				kind: "html",
+				html: renderFigureSVG(parsed.data, options),
+				trusted: true
+			};
+		} catch {
+			return errorHtml("Figure could not be drawn.");
+		}
+	};
+	return {
+		name: "figure",
+		nodeRenderers: { figure: render },
+		css: figureCss,
+		promptSpec: figurePromptSpec(options)
+	};
+}
+
+//#endregion
+export { figure, figureCss, figurePromptSpec, parseFigure, renderFigureSVG };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ai-gui/plugin-figure",
+  "version": "0.11.0",
+  "description": "Labelled figures — regions with leader-line callouts — rendered as SVG from a declarative block.",
+  "keywords": [
+    "llm",
+    "ai",
+    "diagram",
+    "figure",
+    "labels",
+    "biology",
+    "anatomy",
+    "teaching",
+    "svg",
+    "plugin",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/plugin-figure"
+  },
+  "homepage": "https://github.com/liliang-cn/aigui#readme",
+  "bugs": "https://github.com/liliang-cn/aigui/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-gui/core": "0.11.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project plugin-figure",
+    "typecheck": "tsc --noEmit"
+  }
+}