@ai-gui/plugin-physics 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @ai-gui/plugin-physics
+
+## 0.10.0
+
+### Minor Changes
+
+- New: force and vector diagrams for teaching mechanics.
+
+  A ```physics block declares bodies, surfaces, vectors and angles, and the plugin draws them as SVG —
+  the picture a textbook draws for a block on an incline, with the forces labelled and one of them
+  resolved into components.
+
+  It is a drawing, not a simulation. A rigid-body engine produces a collision that looks right and
+  gives a teacher no way to label the intermediate quantities, stop at three seconds, or show a force
+  in equilibrium that never moves anything. Coordinates in, faithful picture out; the numbers are the
+  model's to get right.
+
+  y increases upwards and angles run counter-clockwise from the positive x axis, because that is how a
+  mechanics problem states them — "60° above the horizontal", "gravity at -90". Colours come from CSS
+  custom properties over currentColor, so a diagram follows the page it is on.
+
+### Patch Changes
+
+- @ai-gui/core@0.10.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/dist/index.cjs

@@ -0,0 +1,370 @@
+"use strict";
+
+//#region src/index.ts
+const DEFAULTS = {
+	width: 460,
+	height: 340,
+	maxSourceBytes: 8 * 1024,
+	maxElements: 40
+};
+/** Colours are named through currentColor and CSS custom properties so a host's theme decides. */
+const STYLE_VAR = {
+	force: "--aigui-physics-force",
+	velocity: "--aigui-physics-velocity",
+	acceleration: "--aigui-physics-acceleration",
+	component: "--aigui-physics-component",
+	dimension: "--aigui-physics-dimension"
+};
+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;
+}
+/**
+* Read a diagram out of a block, rejecting anything that is not one.
+*
+* Strict, like the other plugins that accept model output: a diagram that half-parses would draw a
+* confident picture of something the model did not mean.
+*/
+function parsePhysicsDiagram(source, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	if (new TextEncoder().encode(source).byteLength > limits.maxSourceBytes) return {
+		valid: false,
+		issues: ["Diagram is too large."]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return {
+			valid: false,
+			issues: ["Diagram must be valid JSON."]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		valid: false,
+		issues: ["Diagram must be a JSON object."]
+	};
+	const value = parsed;
+	if (value.version !== 1) return {
+		valid: false,
+		issues: ["Diagram must declare \"version\": 1."]
+	};
+	const issues = [];
+	const list = (key, read) => {
+		const raw = value[key];
+		if (raw === void 0) return [];
+		if (!Array.isArray(raw)) {
+			issues.push(`$.${key} must be an array.`);
+			return [];
+		}
+		if (raw.length > limits.maxElements) {
+			issues.push(`$.${key} has more than ${limits.maxElements} entries.`);
+			return [];
+		}
+		const out = [];
+		raw.forEach((item, index) => {
+			if (typeof item !== "object" || item === null || Array.isArray(item)) {
+				issues.push(`$.${key}[${index}] must be an object.`);
+				return;
+			}
+			const read_ = read(item, `$.${key}[${index}]`);
+			if (read_ !== void 0) out.push(read_);
+		});
+		return out;
+	};
+	const bodies = list("bodies", (item, path) => {
+		if (!isFinitePoint(item.at)) {
+			issues.push(`${path}.at must be two finite numbers.`);
+			return void 0;
+		}
+		const shape = item.shape === void 0 ? "box" : item.shape;
+		if (shape !== "box" && shape !== "circle" && shape !== "point") {
+			issues.push(`${path}.shape must be box, circle, or point.`);
+			return void 0;
+		}
+		return {
+			at: item.at,
+			shape,
+			width: num(item.width, 60),
+			height: num(item.height, 40),
+			radius: num(item.radius, 22),
+			rotation: num(item.rotation, 0),
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	const vectors = list("vectors", (item, path) => {
+		const hasTo = isFinitePoint(item.to);
+		const hasPolar = typeof item.magnitude === "number" && Number.isFinite(item.magnitude);
+		if (!hasTo && !hasPolar) {
+			issues.push(`${path} needs either "to" or "magnitude" with "angle".`);
+			return void 0;
+		}
+		const style = item.style === void 0 ? "force" : item.style;
+		if (typeof style !== "string" || !Object.hasOwn(STYLE_VAR, style)) {
+			issues.push(`${path}.style is not one of ${Object.keys(STYLE_VAR).join(", ")}.`);
+			return void 0;
+		}
+		return {
+			...isFinitePoint(item.from) ? { from: item.from } : {},
+			...hasTo ? { to: item.to } : {},
+			...hasPolar ? {
+				magnitude: item.magnitude,
+				angle: num(item.angle, 0)
+			} : {},
+			style,
+			dashed: item.dashed === true,
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	const surfaces = list("surfaces", (item, path) => {
+		if (!isFinitePoint(item.from) || !isFinitePoint(item.to)) {
+			issues.push(`${path}.from and ${path}.to must be two finite numbers each.`);
+			return void 0;
+		}
+		return {
+			from: item.from,
+			to: item.to,
+			hatch: item.hatch !== false,
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	const angles = list("angles", (item, path) => {
+		if (!isFinitePoint(item.at)) {
+			issues.push(`${path}.at must be two finite numbers.`);
+			return void 0;
+		}
+		if (typeof item.from !== "number" || typeof item.to !== "number") {
+			issues.push(`${path}.from and ${path}.to must be angles in degrees.`);
+			return void 0;
+		}
+		return {
+			at: item.at,
+			from: item.from,
+			to: item.to,
+			radius: num(item.radius, 28),
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	if (bodies.length + vectors.length + surfaces.length === 0) issues.push("Diagram must contain at least one body, vector, or surface.");
+	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((v) => typeof v === "number" && Number.isFinite(v)) ? { view: value.view } : {},
+			...typeof value.title === "string" ? { title: value.title } : {},
+			bodies,
+			vectors,
+			surfaces,
+			angles
+		}
+	};
+}
+/** The box the diagram occupies, widened to hold everything it draws. */
+function viewBoxOf(diagram) {
+	if (diagram.view) return diagram.view;
+	const xs = [];
+	const ys = [];
+	const note = (point) => {
+		xs.push(point[0]);
+		ys.push(point[1]);
+	};
+	for (const body of diagram.bodies ?? []) {
+		const halfWidth = (body.shape === "circle" ? body.radius ?? 22 : body.width ?? 60) / 2;
+		const halfHeight = (body.shape === "circle" ? body.radius ?? 22 : body.height ?? 40) / 2;
+		note([body.at[0] - halfWidth, body.at[1] - halfHeight]);
+		note([body.at[0] + halfWidth, body.at[1] + halfHeight]);
+	}
+	for (const surface of diagram.surfaces ?? []) {
+		note(surface.from);
+		note(surface.to);
+	}
+	for (const vector of diagram.vectors ?? []) {
+		const start = vector.from ?? diagram.bodies?.[0]?.at ?? [0, 0];
+		note(start);
+		note(tipOf(vector, start));
+	}
+	if (xs.length === 0) return [
+		0,
+		0,
+		100,
+		100
+	];
+	const pad = 40;
+	return [
+		Math.min(...xs) - pad,
+		Math.min(...ys) - pad,
+		Math.max(...xs) + pad,
+		Math.max(...ys) + pad
+	];
+}
+/** Where a vector ends, whether it was given as a point or as a magnitude and angle. */
+function tipOf(vector, start) {
+	if (vector.to) return vector.to;
+	const radians = (vector.angle ?? 0) * Math.PI / 180;
+	const length = vector.magnitude ?? 0;
+	return [start[0] + length * Math.cos(radians), start[1] + length * Math.sin(radians)];
+}
+function round(value) {
+	return (Math.round(value * 100) / 100).toString();
+}
+/**
+* Draw the diagram.
+*
+* The y axis is flipped once, in the outer transform, so a declaration can say "gravity points to
+* y = -1" and mean down — a mechanics problem is stated in maths coordinates, not screen ones.
+*/
+function renderPhysicsSVG(diagram, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	const [minX, minY, maxX, maxY] = viewBoxOf(diagram);
+	const width = Math.max(1, maxX - minX);
+	const height = Math.max(1, maxY - minY);
+	const parts = [];
+	for (const surface of diagram.surfaces ?? []) {
+		parts.push(`<line x1="${round(surface.from[0])}" y1="${round(surface.from[1])}" x2="${round(surface.to[0])}" y2="${round(surface.to[1])}" class="aigui-physics-surface" />`);
+		if (surface.hatch) {
+			const dx = surface.to[0] - surface.from[0];
+			const dy = surface.to[1] - surface.from[1];
+			const span = Math.hypot(dx, dy) || 1;
+			const steps = Math.min(limits.maxElements, Math.max(2, Math.floor(span / 14)));
+			const nx = -dy / span;
+			const ny = dx / span;
+			for (let step = 0; step <= steps; step += 1) {
+				const t = step / steps;
+				const x = surface.from[0] + dx * t;
+				const y = surface.from[1] + dy * t;
+				parts.push(`<line x1="${round(x)}" y1="${round(y)}" x2="${round(x - nx * 9 - dx / span * 6)}" y2="${round(y - ny * 9 - dy / span * 6)}" class="aigui-physics-hatch" />`);
+			}
+		}
+		if (surface.label) parts.push(`<text x="${round((surface.from[0] + surface.to[0]) / 2)}" y="${round((surface.from[1] + surface.to[1]) / 2 - 12)}" class="aigui-physics-label" transform="scale(1,-1)" transform-origin="${round((surface.from[0] + surface.to[0]) / 2)} ${round((surface.from[1] + surface.to[1]) / 2 - 12)}">${escapeHtml(surface.label)}</text>`);
+	}
+	for (const angle of diagram.angles ?? []) {
+		const radius = angle.radius ?? 28;
+		const start = angle.from * Math.PI / 180;
+		const end = angle.to * Math.PI / 180;
+		const large = Math.abs(angle.to - angle.from) > 180 ? 1 : 0;
+		const sweep = angle.to > angle.from ? 1 : 0;
+		const x1 = angle.at[0] + radius * Math.cos(start);
+		const y1 = angle.at[1] + radius * Math.sin(start);
+		const x2 = angle.at[0] + radius * Math.cos(end);
+		const y2 = angle.at[1] + radius * Math.sin(end);
+		parts.push(`<path d="M ${round(x1)} ${round(y1)} A ${round(radius)} ${round(radius)} 0 ${large} ${sweep} ${round(x2)} ${round(y2)}" class="aigui-physics-angle" />`);
+		if (angle.label) {
+			const mid = (start + end) / 2;
+			const lx = angle.at[0] + (radius + 14) * Math.cos(mid);
+			const ly = angle.at[1] + (radius + 14) * Math.sin(mid);
+			parts.push(`<text x="${round(lx)}" y="${round(ly)}" class="aigui-physics-label" transform="scale(1,-1)" transform-origin="${round(lx)} ${round(ly)}">${escapeHtml(angle.label)}</text>`);
+		}
+	}
+	for (const body of diagram.bodies ?? []) {
+		const rotate = body.rotation ? ` transform="rotate(${round(body.rotation)} ${round(body.at[0])} ${round(body.at[1])})"` : "";
+		if (body.shape === "circle") parts.push(`<circle cx="${round(body.at[0])}" cy="${round(body.at[1])}" r="${round(body.radius ?? 22)}" class="aigui-physics-body"${rotate} />`);
+		else if (body.shape === "point") parts.push(`<circle cx="${round(body.at[0])}" cy="${round(body.at[1])}" r="4" class="aigui-physics-point"${rotate} />`);
+		else {
+			const w = body.width ?? 60;
+			const h = body.height ?? 40;
+			parts.push(`<rect x="${round(body.at[0] - w / 2)}" y="${round(body.at[1] - h / 2)}" width="${round(w)}" height="${round(h)}" class="aigui-physics-body"${rotate} />`);
+		}
+		if (body.label) parts.push(`<text x="${round(body.at[0])}" y="${round(body.at[1])}" class="aigui-physics-body-label" transform="scale(1,-1)" transform-origin="${round(body.at[0])} ${round(body.at[1])}">${escapeHtml(body.label)}</text>`);
+	}
+	for (const vector of diagram.vectors ?? []) {
+		const start = vector.from ?? diagram.bodies?.[0]?.at ?? [0, 0];
+		const tip = tipOf(vector, start);
+		const style = vector.style ?? "force";
+		const dash = vector.dashed ? " stroke-dasharray=\"6 4\"" : "";
+		parts.push(`<line x1="${round(start[0])}" y1="${round(start[1])}" x2="${round(tip[0])}" y2="${round(tip[1])}" class="aigui-physics-vector" style="stroke:var(${STYLE_VAR[style]}, currentColor)" marker-end="url(#aigui-physics-arrow-${style})"${dash} />`);
+		if (vector.label) {
+			const lx = tip[0] + (tip[0] - start[0]) * .08 + 8;
+			const ly = tip[1] + (tip[1] - start[1]) * .08;
+			parts.push(`<text x="${round(lx)}" y="${round(ly)}" class="aigui-physics-label" style="fill:var(${STYLE_VAR[style]}, currentColor)" transform="scale(1,-1)" transform-origin="${round(lx)} ${round(ly)}">${escapeHtml(vector.label)}</text>`);
+		}
+	}
+	const markers = Object.entries(STYLE_VAR).map(([style, variable]) => `<marker id="aigui-physics-arrow-${style}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="var(${variable}, currentColor)" /></marker>`).join("");
+	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 ?? "Physics diagram")}" data-aigui-physics="diagram">`,
+		title,
+		`<defs>${markers}</defs>`,
+		`<g transform="translate(0, ${round(minY + maxY)}) scale(1, -1)">`,
+		parts.join(""),
+		"</g></svg>"
+	].join("");
+}
+function physicsPromptSpec(options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	return [
+		"Force and vector diagrams (one fenced block): ```physics <strict JSON>```.",
+		"Root: {\"version\":1,\"title\":\"...\"?,\"view\":[minX,minY,maxX,maxY]?,\"bodies\":[...]?,\"surfaces\":[...]?,\"vectors\":[...]?,\"angles\":[...]?}. No unknown fields.",
+		"Body: {\"at\":[x,y],\"shape\":\"box|circle|point\"?,\"width\":n?,\"height\":n?,\"radius\":n?,\"rotation\":deg?,\"label\":\"...\"?}.",
+		"Surface: {\"from\":[x,y],\"to\":[x,y],\"hatch\":true?,\"label\":\"...\"?} — hatching marks the solid side.",
+		"Vector: {\"from\":[x,y]?,\"to\":[x,y]?,\"magnitude\":n?,\"angle\":deg?,\"style\":\"force|velocity|acceleration|component|dimension\"?,\"dashed\":true?,\"label\":\"...\"?}. Give either \"to\" or \"magnitude\" with \"angle\". Omit \"from\" to start at the first body.",
+		"Angle: {\"at\":[x,y],\"from\":deg,\"to\":deg,\"radius\":n?,\"label\":\"...\"?}.",
+		"y increases upwards and angles are counter-clockwise from the positive x axis, as a mechanics problem states them: gravity points at angle -90.",
+		`Diagram source is local JSON only, at most ${limits.maxSourceBytes} UTF-8 bytes. Never emit URLs, scripts, remote resources, HTML, or executable content.`,
+		"Use this for free-body diagrams, resolved components, inclines and projectile setups — the picture a textbook draws. It is a drawing, not a simulation: state the coordinates you mean."
+	].join("\n");
+}
+const physicsCss = `
+[data-aigui-physics] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }
+[data-aigui-physics] .aigui-physics-body { fill: var(--aigui-physics-body, color-mix(in srgb, currentColor 12%, transparent)); stroke: currentColor; stroke-width: 1.5; }
+[data-aigui-physics] .aigui-physics-point { fill: currentColor; stroke: none; }
+[data-aigui-physics] .aigui-physics-surface { stroke: currentColor; stroke-width: 2; }
+[data-aigui-physics] .aigui-physics-hatch { stroke: currentColor; stroke-width: 1; opacity: .55; }
+[data-aigui-physics] .aigui-physics-angle { fill: none; stroke: var(--aigui-physics-dimension, currentColor); stroke-width: 1.2; }
+[data-aigui-physics] .aigui-physics-vector { stroke-width: 2; stroke-linecap: round; }
+[data-aigui-physics] .aigui-physics-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; }
+[data-aigui-physics] .aigui-physics-body-label { font-size: 13px; font-family: inherit; text-anchor: middle; dominant-baseline: middle; fill: currentColor; }
+`;
+function errorHtml(issue) {
+	return {
+		kind: "html",
+		html: `<pre data-aigui-physics-error>${escapeHtml(issue)}</pre>`
+	};
+}
+function physics(options = {}) {
+	const render = (node) => {
+		const parsed = parsePhysicsDiagram(node.content ?? "", options);
+		if (!parsed.valid) return errorHtml(parsed.issues[0] ?? "Invalid diagram.");
+		try {
+			return {
+				kind: "html",
+				html: renderPhysicsSVG(parsed.data, options),
+				trusted: true
+			};
+		} catch {
+			return errorHtml("Diagram could not be drawn.");
+		}
+	};
+	return {
+		name: "physics",
+		nodeRenderers: { physics: render },
+		css: physicsCss,
+		promptSpec: physicsPromptSpec(options)
+	};
+}
+
+//#endregion
+exports.parsePhysicsDiagram = parsePhysicsDiagram
+exports.physics = physics
+exports.physicsCss = physicsCss
+exports.physicsPromptSpec = physicsPromptSpec
+exports.renderPhysicsSVG = renderPhysicsSVG

package/dist/index.d.cts

@@ -0,0 +1,110 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/**
+* Force and vector diagrams, drawn from a declaration rather than simulated.
+*
+* A mechanics lesson needs the picture a textbook draws: a body, the forces on it as labelled
+* arrows, their angles, and often one force resolved into components. What it does not need is a
+* rigid-body engine — a simulation produces a collision that *looks* right and gives a teacher no
+* way to label the intermediate quantities, stop at three seconds, or show a force that is in
+* equilibrium and therefore never moves anything. So this takes coordinates and draws them.
+*
+* The numbers are the model's to get right; the drawing is faithful to what it declared.
+*/
+/**
+ * Force and vector diagrams, drawn from a declaration rather than simulated.
+ *
+ * A mechanics lesson needs the picture a textbook draws: a body, the forces on it as labelled
+ * arrows, their angles, and often one force resolved into components. What it does not need is a
+ * rigid-body engine — a simulation produces a collision that *looks* right and gives a teacher no
+ * way to label the intermediate quantities, stop at three seconds, or show a force that is in
+ * equilibrium and therefore never moves anything. So this takes coordinates and draws them.
+ *
+ * The numbers are the model's to get right; the drawing is faithful to what it declared.
+ */
+type VectorStyle = "force" | "velocity" | "acceleration" | "component" | "dimension";
+interface PhysicsVector {
+  /** Where the arrow starts, in diagram units. Defaults to the body's centre. */
+  from?: [number, number];
+  /**
+   * Either the arrow's tip, or a magnitude and angle.
+   *
+   * Angles are in degrees, counter-clockwise from the positive x axis, because that is how a
+   * mechanics problem states them ("a 30° incline", "60° above the horizontal").
+   */
+  to?: [number, number];
+  magnitude?: number;
+  angle?: number;
+  label?: string;
+  style?: VectorStyle;
+  /** Drawn as a dashed line, for a component or a construction line. */
+  dashed?: boolean;
+}
+interface PhysicsBody {
+  at: [number, number];
+  /** A block, a ball, or a point mass. */
+  shape?: "box" | "circle" | "point";
+  width?: number;
+  height?: number;
+  radius?: number;
+  label?: string;
+  /** Degrees, counter-clockwise — an inclined block is drawn tilted. */
+  rotation?: number;
+}
+interface PhysicsSurface {
+  from: [number, number];
+  to: [number, number];
+  /** Hatching on the far side, the convention for ground or a wall. */
+  hatch?: boolean;
+  label?: string;
+}
+interface PhysicsAngle {
+  at: [number, number];
+  /** Degrees, counter-clockwise from the positive x axis. */
+  from: number;
+  to: number;
+  radius?: number;
+  label?: string;
+}
+interface PhysicsDiagram {
+  version: 1;
+  /** The coordinate box the diagram is drawn in: [minX, minY, maxX, maxY]. */
+  view?: [number, number, number, number];
+  title?: string;
+  bodies?: PhysicsBody[];
+  vectors?: PhysicsVector[];
+  surfaces?: PhysicsSurface[];
+  angles?: PhysicsAngle[];
+}
+interface PhysicsOptions {
+  width?: number;
+  height?: number;
+  maxSourceBytes?: number;
+  /** How many of each element to draw before refusing — a runaway block is not a diagram. */
+  maxElements?: number;
+}
+/**
+ * Read a diagram out of a block, rejecting anything that is not one.
+ *
+ * Strict, like the other plugins that accept model output: a diagram that half-parses would draw a
+ * confident picture of something the model did not mean.
+ */
+declare function parsePhysicsDiagram(source: string, options?: PhysicsOptions): {
+  valid: true;
+  data: PhysicsDiagram;
+} | {
+  valid: false;
+  issues: string[];
+};
+/**
+ * Draw the diagram.
+ *
+ * The y axis is flipped once, in the outer transform, so a declaration can say "gravity points to
+ * y = -1" and mean down — a mechanics problem is stated in maths coordinates, not screen ones.
+ */
+declare function renderPhysicsSVG(diagram: PhysicsDiagram, options?: PhysicsOptions): string;
+declare function physicsPromptSpec(options?: PhysicsOptions): string;
+declare const physicsCss = "\n[data-aigui-physics] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }\n[data-aigui-physics] .aigui-physics-body { fill: var(--aigui-physics-body, color-mix(in srgb, currentColor 12%, transparent)); stroke: currentColor; stroke-width: 1.5; }\n[data-aigui-physics] .aigui-physics-point { fill: currentColor; stroke: none; }\n[data-aigui-physics] .aigui-physics-surface { stroke: currentColor; stroke-width: 2; }\n[data-aigui-physics] .aigui-physics-hatch { stroke: currentColor; stroke-width: 1; opacity: .55; }\n[data-aigui-physics] .aigui-physics-angle { fill: none; stroke: var(--aigui-physics-dimension, currentColor); stroke-width: 1.2; }\n[data-aigui-physics] .aigui-physics-vector { stroke-width: 2; stroke-linecap: round; }\n[data-aigui-physics] .aigui-physics-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; }\n[data-aigui-physics] .aigui-physics-body-label { font-size: 13px; font-family: inherit; text-anchor: middle; dominant-baseline: middle; fill: currentColor; }\n";
+declare function physics(options?: PhysicsOptions): AIGuiPlugin; //#endregion
+export { PhysicsAngle, PhysicsBody, PhysicsDiagram, PhysicsOptions, PhysicsSurface, PhysicsVector, VectorStyle, parsePhysicsDiagram, physics, physicsCss, physicsPromptSpec, renderPhysicsSVG };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/**
+* Force and vector diagrams, drawn from a declaration rather than simulated.
+*
+* A mechanics lesson needs the picture a textbook draws: a body, the forces on it as labelled
+* arrows, their angles, and often one force resolved into components. What it does not need is a
+* rigid-body engine — a simulation produces a collision that *looks* right and gives a teacher no
+* way to label the intermediate quantities, stop at three seconds, or show a force that is in
+* equilibrium and therefore never moves anything. So this takes coordinates and draws them.
+*
+* The numbers are the model's to get right; the drawing is faithful to what it declared.
+*/
+/**
+ * Force and vector diagrams, drawn from a declaration rather than simulated.
+ *
+ * A mechanics lesson needs the picture a textbook draws: a body, the forces on it as labelled
+ * arrows, their angles, and often one force resolved into components. What it does not need is a
+ * rigid-body engine — a simulation produces a collision that *looks* right and gives a teacher no
+ * way to label the intermediate quantities, stop at three seconds, or show a force that is in
+ * equilibrium and therefore never moves anything. So this takes coordinates and draws them.
+ *
+ * The numbers are the model's to get right; the drawing is faithful to what it declared.
+ */
+type VectorStyle = "force" | "velocity" | "acceleration" | "component" | "dimension";
+interface PhysicsVector {
+  /** Where the arrow starts, in diagram units. Defaults to the body's centre. */
+  from?: [number, number];
+  /**
+   * Either the arrow's tip, or a magnitude and angle.
+   *
+   * Angles are in degrees, counter-clockwise from the positive x axis, because that is how a
+   * mechanics problem states them ("a 30° incline", "60° above the horizontal").
+   */
+  to?: [number, number];
+  magnitude?: number;
+  angle?: number;
+  label?: string;
+  style?: VectorStyle;
+  /** Drawn as a dashed line, for a component or a construction line. */
+  dashed?: boolean;
+}
+interface PhysicsBody {
+  at: [number, number];
+  /** A block, a ball, or a point mass. */
+  shape?: "box" | "circle" | "point";
+  width?: number;
+  height?: number;
+  radius?: number;
+  label?: string;
+  /** Degrees, counter-clockwise — an inclined block is drawn tilted. */
+  rotation?: number;
+}
+interface PhysicsSurface {
+  from: [number, number];
+  to: [number, number];
+  /** Hatching on the far side, the convention for ground or a wall. */
+  hatch?: boolean;
+  label?: string;
+}
+interface PhysicsAngle {
+  at: [number, number];
+  /** Degrees, counter-clockwise from the positive x axis. */
+  from: number;
+  to: number;
+  radius?: number;
+  label?: string;
+}
+interface PhysicsDiagram {
+  version: 1;
+  /** The coordinate box the diagram is drawn in: [minX, minY, maxX, maxY]. */
+  view?: [number, number, number, number];
+  title?: string;
+  bodies?: PhysicsBody[];
+  vectors?: PhysicsVector[];
+  surfaces?: PhysicsSurface[];
+  angles?: PhysicsAngle[];
+}
+interface PhysicsOptions {
+  width?: number;
+  height?: number;
+  maxSourceBytes?: number;
+  /** How many of each element to draw before refusing — a runaway block is not a diagram. */
+  maxElements?: number;
+}
+/**
+ * Read a diagram out of a block, rejecting anything that is not one.
+ *
+ * Strict, like the other plugins that accept model output: a diagram that half-parses would draw a
+ * confident picture of something the model did not mean.
+ */
+declare function parsePhysicsDiagram(source: string, options?: PhysicsOptions): {
+  valid: true;
+  data: PhysicsDiagram;
+} | {
+  valid: false;
+  issues: string[];
+};
+/**
+ * Draw the diagram.
+ *
+ * The y axis is flipped once, in the outer transform, so a declaration can say "gravity points to
+ * y = -1" and mean down — a mechanics problem is stated in maths coordinates, not screen ones.
+ */
+declare function renderPhysicsSVG(diagram: PhysicsDiagram, options?: PhysicsOptions): string;
+declare function physicsPromptSpec(options?: PhysicsOptions): string;
+declare const physicsCss = "\n[data-aigui-physics] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }\n[data-aigui-physics] .aigui-physics-body { fill: var(--aigui-physics-body, color-mix(in srgb, currentColor 12%, transparent)); stroke: currentColor; stroke-width: 1.5; }\n[data-aigui-physics] .aigui-physics-point { fill: currentColor; stroke: none; }\n[data-aigui-physics] .aigui-physics-surface { stroke: currentColor; stroke-width: 2; }\n[data-aigui-physics] .aigui-physics-hatch { stroke: currentColor; stroke-width: 1; opacity: .55; }\n[data-aigui-physics] .aigui-physics-angle { fill: none; stroke: var(--aigui-physics-dimension, currentColor); stroke-width: 1.2; }\n[data-aigui-physics] .aigui-physics-vector { stroke-width: 2; stroke-linecap: round; }\n[data-aigui-physics] .aigui-physics-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; }\n[data-aigui-physics] .aigui-physics-body-label { font-size: 13px; font-family: inherit; text-anchor: middle; dominant-baseline: middle; fill: currentColor; }\n";
+declare function physics(options?: PhysicsOptions): AIGuiPlugin; //#endregion
+export { PhysicsAngle, PhysicsBody, PhysicsDiagram, PhysicsOptions, PhysicsSurface, PhysicsVector, VectorStyle, parsePhysicsDiagram, physics, physicsCss, physicsPromptSpec, renderPhysicsSVG };

package/dist/index.js

@@ -0,0 +1,364 @@
+//#region src/index.ts
+const DEFAULTS = {
+	width: 460,
+	height: 340,
+	maxSourceBytes: 8 * 1024,
+	maxElements: 40
+};
+/** Colours are named through currentColor and CSS custom properties so a host's theme decides. */
+const STYLE_VAR = {
+	force: "--aigui-physics-force",
+	velocity: "--aigui-physics-velocity",
+	acceleration: "--aigui-physics-acceleration",
+	component: "--aigui-physics-component",
+	dimension: "--aigui-physics-dimension"
+};
+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;
+}
+/**
+* Read a diagram out of a block, rejecting anything that is not one.
+*
+* Strict, like the other plugins that accept model output: a diagram that half-parses would draw a
+* confident picture of something the model did not mean.
+*/
+function parsePhysicsDiagram(source, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	if (new TextEncoder().encode(source).byteLength > limits.maxSourceBytes) return {
+		valid: false,
+		issues: ["Diagram is too large."]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return {
+			valid: false,
+			issues: ["Diagram must be valid JSON."]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		valid: false,
+		issues: ["Diagram must be a JSON object."]
+	};
+	const value = parsed;
+	if (value.version !== 1) return {
+		valid: false,
+		issues: ["Diagram must declare \"version\": 1."]
+	};
+	const issues = [];
+	const list = (key, read) => {
+		const raw = value[key];
+		if (raw === void 0) return [];
+		if (!Array.isArray(raw)) {
+			issues.push(`$.${key} must be an array.`);
+			return [];
+		}
+		if (raw.length > limits.maxElements) {
+			issues.push(`$.${key} has more than ${limits.maxElements} entries.`);
+			return [];
+		}
+		const out = [];
+		raw.forEach((item, index) => {
+			if (typeof item !== "object" || item === null || Array.isArray(item)) {
+				issues.push(`$.${key}[${index}] must be an object.`);
+				return;
+			}
+			const read_ = read(item, `$.${key}[${index}]`);
+			if (read_ !== void 0) out.push(read_);
+		});
+		return out;
+	};
+	const bodies = list("bodies", (item, path) => {
+		if (!isFinitePoint(item.at)) {
+			issues.push(`${path}.at must be two finite numbers.`);
+			return void 0;
+		}
+		const shape = item.shape === void 0 ? "box" : item.shape;
+		if (shape !== "box" && shape !== "circle" && shape !== "point") {
+			issues.push(`${path}.shape must be box, circle, or point.`);
+			return void 0;
+		}
+		return {
+			at: item.at,
+			shape,
+			width: num(item.width, 60),
+			height: num(item.height, 40),
+			radius: num(item.radius, 22),
+			rotation: num(item.rotation, 0),
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	const vectors = list("vectors", (item, path) => {
+		const hasTo = isFinitePoint(item.to);
+		const hasPolar = typeof item.magnitude === "number" && Number.isFinite(item.magnitude);
+		if (!hasTo && !hasPolar) {
+			issues.push(`${path} needs either "to" or "magnitude" with "angle".`);
+			return void 0;
+		}
+		const style = item.style === void 0 ? "force" : item.style;
+		if (typeof style !== "string" || !Object.hasOwn(STYLE_VAR, style)) {
+			issues.push(`${path}.style is not one of ${Object.keys(STYLE_VAR).join(", ")}.`);
+			return void 0;
+		}
+		return {
+			...isFinitePoint(item.from) ? { from: item.from } : {},
+			...hasTo ? { to: item.to } : {},
+			...hasPolar ? {
+				magnitude: item.magnitude,
+				angle: num(item.angle, 0)
+			} : {},
+			style,
+			dashed: item.dashed === true,
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	const surfaces = list("surfaces", (item, path) => {
+		if (!isFinitePoint(item.from) || !isFinitePoint(item.to)) {
+			issues.push(`${path}.from and ${path}.to must be two finite numbers each.`);
+			return void 0;
+		}
+		return {
+			from: item.from,
+			to: item.to,
+			hatch: item.hatch !== false,
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	const angles = list("angles", (item, path) => {
+		if (!isFinitePoint(item.at)) {
+			issues.push(`${path}.at must be two finite numbers.`);
+			return void 0;
+		}
+		if (typeof item.from !== "number" || typeof item.to !== "number") {
+			issues.push(`${path}.from and ${path}.to must be angles in degrees.`);
+			return void 0;
+		}
+		return {
+			at: item.at,
+			from: item.from,
+			to: item.to,
+			radius: num(item.radius, 28),
+			...typeof item.label === "string" ? { label: item.label } : {}
+		};
+	});
+	if (bodies.length + vectors.length + surfaces.length === 0) issues.push("Diagram must contain at least one body, vector, or surface.");
+	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((v) => typeof v === "number" && Number.isFinite(v)) ? { view: value.view } : {},
+			...typeof value.title === "string" ? { title: value.title } : {},
+			bodies,
+			vectors,
+			surfaces,
+			angles
+		}
+	};
+}
+/** The box the diagram occupies, widened to hold everything it draws. */
+function viewBoxOf(diagram) {
+	if (diagram.view) return diagram.view;
+	const xs = [];
+	const ys = [];
+	const note = (point) => {
+		xs.push(point[0]);
+		ys.push(point[1]);
+	};
+	for (const body of diagram.bodies ?? []) {
+		const halfWidth = (body.shape === "circle" ? body.radius ?? 22 : body.width ?? 60) / 2;
+		const halfHeight = (body.shape === "circle" ? body.radius ?? 22 : body.height ?? 40) / 2;
+		note([body.at[0] - halfWidth, body.at[1] - halfHeight]);
+		note([body.at[0] + halfWidth, body.at[1] + halfHeight]);
+	}
+	for (const surface of diagram.surfaces ?? []) {
+		note(surface.from);
+		note(surface.to);
+	}
+	for (const vector of diagram.vectors ?? []) {
+		const start = vector.from ?? diagram.bodies?.[0]?.at ?? [0, 0];
+		note(start);
+		note(tipOf(vector, start));
+	}
+	if (xs.length === 0) return [
+		0,
+		0,
+		100,
+		100
+	];
+	const pad = 40;
+	return [
+		Math.min(...xs) - pad,
+		Math.min(...ys) - pad,
+		Math.max(...xs) + pad,
+		Math.max(...ys) + pad
+	];
+}
+/** Where a vector ends, whether it was given as a point or as a magnitude and angle. */
+function tipOf(vector, start) {
+	if (vector.to) return vector.to;
+	const radians = (vector.angle ?? 0) * Math.PI / 180;
+	const length = vector.magnitude ?? 0;
+	return [start[0] + length * Math.cos(radians), start[1] + length * Math.sin(radians)];
+}
+function round(value) {
+	return (Math.round(value * 100) / 100).toString();
+}
+/**
+* Draw the diagram.
+*
+* The y axis is flipped once, in the outer transform, so a declaration can say "gravity points to
+* y = -1" and mean down — a mechanics problem is stated in maths coordinates, not screen ones.
+*/
+function renderPhysicsSVG(diagram, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	const [minX, minY, maxX, maxY] = viewBoxOf(diagram);
+	const width = Math.max(1, maxX - minX);
+	const height = Math.max(1, maxY - minY);
+	const parts = [];
+	for (const surface of diagram.surfaces ?? []) {
+		parts.push(`<line x1="${round(surface.from[0])}" y1="${round(surface.from[1])}" x2="${round(surface.to[0])}" y2="${round(surface.to[1])}" class="aigui-physics-surface" />`);
+		if (surface.hatch) {
+			const dx = surface.to[0] - surface.from[0];
+			const dy = surface.to[1] - surface.from[1];
+			const span = Math.hypot(dx, dy) || 1;
+			const steps = Math.min(limits.maxElements, Math.max(2, Math.floor(span / 14)));
+			const nx = -dy / span;
+			const ny = dx / span;
+			for (let step = 0; step <= steps; step += 1) {
+				const t = step / steps;
+				const x = surface.from[0] + dx * t;
+				const y = surface.from[1] + dy * t;
+				parts.push(`<line x1="${round(x)}" y1="${round(y)}" x2="${round(x - nx * 9 - dx / span * 6)}" y2="${round(y - ny * 9 - dy / span * 6)}" class="aigui-physics-hatch" />`);
+			}
+		}
+		if (surface.label) parts.push(`<text x="${round((surface.from[0] + surface.to[0]) / 2)}" y="${round((surface.from[1] + surface.to[1]) / 2 - 12)}" class="aigui-physics-label" transform="scale(1,-1)" transform-origin="${round((surface.from[0] + surface.to[0]) / 2)} ${round((surface.from[1] + surface.to[1]) / 2 - 12)}">${escapeHtml(surface.label)}</text>`);
+	}
+	for (const angle of diagram.angles ?? []) {
+		const radius = angle.radius ?? 28;
+		const start = angle.from * Math.PI / 180;
+		const end = angle.to * Math.PI / 180;
+		const large = Math.abs(angle.to - angle.from) > 180 ? 1 : 0;
+		const sweep = angle.to > angle.from ? 1 : 0;
+		const x1 = angle.at[0] + radius * Math.cos(start);
+		const y1 = angle.at[1] + radius * Math.sin(start);
+		const x2 = angle.at[0] + radius * Math.cos(end);
+		const y2 = angle.at[1] + radius * Math.sin(end);
+		parts.push(`<path d="M ${round(x1)} ${round(y1)} A ${round(radius)} ${round(radius)} 0 ${large} ${sweep} ${round(x2)} ${round(y2)}" class="aigui-physics-angle" />`);
+		if (angle.label) {
+			const mid = (start + end) / 2;
+			const lx = angle.at[0] + (radius + 14) * Math.cos(mid);
+			const ly = angle.at[1] + (radius + 14) * Math.sin(mid);
+			parts.push(`<text x="${round(lx)}" y="${round(ly)}" class="aigui-physics-label" transform="scale(1,-1)" transform-origin="${round(lx)} ${round(ly)}">${escapeHtml(angle.label)}</text>`);
+		}
+	}
+	for (const body of diagram.bodies ?? []) {
+		const rotate = body.rotation ? ` transform="rotate(${round(body.rotation)} ${round(body.at[0])} ${round(body.at[1])})"` : "";
+		if (body.shape === "circle") parts.push(`<circle cx="${round(body.at[0])}" cy="${round(body.at[1])}" r="${round(body.radius ?? 22)}" class="aigui-physics-body"${rotate} />`);
+		else if (body.shape === "point") parts.push(`<circle cx="${round(body.at[0])}" cy="${round(body.at[1])}" r="4" class="aigui-physics-point"${rotate} />`);
+		else {
+			const w = body.width ?? 60;
+			const h = body.height ?? 40;
+			parts.push(`<rect x="${round(body.at[0] - w / 2)}" y="${round(body.at[1] - h / 2)}" width="${round(w)}" height="${round(h)}" class="aigui-physics-body"${rotate} />`);
+		}
+		if (body.label) parts.push(`<text x="${round(body.at[0])}" y="${round(body.at[1])}" class="aigui-physics-body-label" transform="scale(1,-1)" transform-origin="${round(body.at[0])} ${round(body.at[1])}">${escapeHtml(body.label)}</text>`);
+	}
+	for (const vector of diagram.vectors ?? []) {
+		const start = vector.from ?? diagram.bodies?.[0]?.at ?? [0, 0];
+		const tip = tipOf(vector, start);
+		const style = vector.style ?? "force";
+		const dash = vector.dashed ? " stroke-dasharray=\"6 4\"" : "";
+		parts.push(`<line x1="${round(start[0])}" y1="${round(start[1])}" x2="${round(tip[0])}" y2="${round(tip[1])}" class="aigui-physics-vector" style="stroke:var(${STYLE_VAR[style]}, currentColor)" marker-end="url(#aigui-physics-arrow-${style})"${dash} />`);
+		if (vector.label) {
+			const lx = tip[0] + (tip[0] - start[0]) * .08 + 8;
+			const ly = tip[1] + (tip[1] - start[1]) * .08;
+			parts.push(`<text x="${round(lx)}" y="${round(ly)}" class="aigui-physics-label" style="fill:var(${STYLE_VAR[style]}, currentColor)" transform="scale(1,-1)" transform-origin="${round(lx)} ${round(ly)}">${escapeHtml(vector.label)}</text>`);
+		}
+	}
+	const markers = Object.entries(STYLE_VAR).map(([style, variable]) => `<marker id="aigui-physics-arrow-${style}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="var(${variable}, currentColor)" /></marker>`).join("");
+	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 ?? "Physics diagram")}" data-aigui-physics="diagram">`,
+		title,
+		`<defs>${markers}</defs>`,
+		`<g transform="translate(0, ${round(minY + maxY)}) scale(1, -1)">`,
+		parts.join(""),
+		"</g></svg>"
+	].join("");
+}
+function physicsPromptSpec(options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	return [
+		"Force and vector diagrams (one fenced block): ```physics <strict JSON>```.",
+		"Root: {\"version\":1,\"title\":\"...\"?,\"view\":[minX,minY,maxX,maxY]?,\"bodies\":[...]?,\"surfaces\":[...]?,\"vectors\":[...]?,\"angles\":[...]?}. No unknown fields.",
+		"Body: {\"at\":[x,y],\"shape\":\"box|circle|point\"?,\"width\":n?,\"height\":n?,\"radius\":n?,\"rotation\":deg?,\"label\":\"...\"?}.",
+		"Surface: {\"from\":[x,y],\"to\":[x,y],\"hatch\":true?,\"label\":\"...\"?} — hatching marks the solid side.",
+		"Vector: {\"from\":[x,y]?,\"to\":[x,y]?,\"magnitude\":n?,\"angle\":deg?,\"style\":\"force|velocity|acceleration|component|dimension\"?,\"dashed\":true?,\"label\":\"...\"?}. Give either \"to\" or \"magnitude\" with \"angle\". Omit \"from\" to start at the first body.",
+		"Angle: {\"at\":[x,y],\"from\":deg,\"to\":deg,\"radius\":n?,\"label\":\"...\"?}.",
+		"y increases upwards and angles are counter-clockwise from the positive x axis, as a mechanics problem states them: gravity points at angle -90.",
+		`Diagram source is local JSON only, at most ${limits.maxSourceBytes} UTF-8 bytes. Never emit URLs, scripts, remote resources, HTML, or executable content.`,
+		"Use this for free-body diagrams, resolved components, inclines and projectile setups — the picture a textbook draws. It is a drawing, not a simulation: state the coordinates you mean."
+	].join("\n");
+}
+const physicsCss = `
+[data-aigui-physics] { max-width: 100%; height: auto; overflow: visible; color: currentColor; }
+[data-aigui-physics] .aigui-physics-body { fill: var(--aigui-physics-body, color-mix(in srgb, currentColor 12%, transparent)); stroke: currentColor; stroke-width: 1.5; }
+[data-aigui-physics] .aigui-physics-point { fill: currentColor; stroke: none; }
+[data-aigui-physics] .aigui-physics-surface { stroke: currentColor; stroke-width: 2; }
+[data-aigui-physics] .aigui-physics-hatch { stroke: currentColor; stroke-width: 1; opacity: .55; }
+[data-aigui-physics] .aigui-physics-angle { fill: none; stroke: var(--aigui-physics-dimension, currentColor); stroke-width: 1.2; }
+[data-aigui-physics] .aigui-physics-vector { stroke-width: 2; stroke-linecap: round; }
+[data-aigui-physics] .aigui-physics-label { font-size: 13px; font-family: inherit; dominant-baseline: middle; }
+[data-aigui-physics] .aigui-physics-body-label { font-size: 13px; font-family: inherit; text-anchor: middle; dominant-baseline: middle; fill: currentColor; }
+`;
+function errorHtml(issue) {
+	return {
+		kind: "html",
+		html: `<pre data-aigui-physics-error>${escapeHtml(issue)}</pre>`
+	};
+}
+function physics(options = {}) {
+	const render = (node) => {
+		const parsed = parsePhysicsDiagram(node.content ?? "", options);
+		if (!parsed.valid) return errorHtml(parsed.issues[0] ?? "Invalid diagram.");
+		try {
+			return {
+				kind: "html",
+				html: renderPhysicsSVG(parsed.data, options),
+				trusted: true
+			};
+		} catch {
+			return errorHtml("Diagram could not be drawn.");
+		}
+	};
+	return {
+		name: "physics",
+		nodeRenderers: { physics: render },
+		css: physicsCss,
+		promptSpec: physicsPromptSpec(options)
+	};
+}
+
+//#endregion
+export { parsePhysicsDiagram, physics, physicsCss, physicsPromptSpec, renderPhysicsSVG };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ai-gui/plugin-physics",
+  "version": "0.10.0",
+  "description": "Force and vector diagrams for teaching mechanics, rendered as SVG from a declarative block.",
+  "keywords": [
+    "llm",
+    "ai",
+    "chemistry",
+    "molecule",
+    "smiles",
+    "molfile",
+    "3d",
+    "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-molecule"
+  },
+  "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.10.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project plugin-physics",
+    "typecheck": "tsc --noEmit"
+  }
+}