@ai-gui/plugin-molecule 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @ai-gui/plugin-molecule
+
+## 0.4.0
+
+### Minor Changes
+
+- Add plugin authoring helpers, secure source citation blocks, revisioned artifacts, bounded declarative AI-generated UI trees, molecular structures, and interactive maps.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ai-gui/core@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- Add strict, complete-gated molecular structure rendering for SMILES and Molfile definitions.
+- Add sanitized responsive OpenChemLib 2D SVG output and lazily loaded interactive 3Dmol rendering with deterministic styles and lifecycle cleanup.
+- Add public parsing, validation, prompt, option, result, error, definition, and CSS APIs.

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,52 @@
+# @ai-gui/plugin-molecule
+
+Safe molecular structure rendering for [AIGUI](../../README.md). The plugin claims one complete-gated `molecule` fence and renders validated SMILES or Molfile source as responsive 2D SVG or an interactive 3D viewer.
+
+## Install
+
+```sh
+pnpm add @ai-gui/plugin-molecule
+```
+
+## Usage
+
+```tsx
+import { molecule, moleculeCss } from "@ai-gui/plugin-molecule"
+import { AIRenderer } from "@ai-gui/react"
+
+<style>{moleculeCss}</style>
+<AIRenderer plugins={[molecule({ enable3D: true })]} />
+```
+
+SMILES is supported for 2D structures only:
+
+    ```molecule
+    {"version":1,"format":"smiles","source":"CCO","view":"2d","atomLabels":"standard","highlight":{"atoms":[2]}}
+    ```
+
+Molfile supports 2D and 3D. A 3D structure must contain finite, genuinely non-flat z coordinates:
+
+    ```molecule
+    {"version":1,"format":"molfile","source":"...local Molfile text...","view":"3d","style":"ball-and-stick"}
+    ```
+
+The protocol accepts only `version`, `format`, `source`, `view`, optional `style`, optional `atomLabels`, and optional `highlight`. Unknown fields, URLs, class instances, cycles, sparse arrays, duplicate indexes, unsafe integers, nonfinite values, malformed chemistry, and oversized structures are rejected with a generic non-reflective error.
+
+## API
+
+- `molecule(options?)` creates the AIGUI plugin.
+- `moleculePromptSpec(options?)` returns the model-facing protocol description.
+- `parseMoleculeDefinition(source, options?)` strictly parses and validates JSON and chemistry.
+- `validateMoleculeDefinition(value, options?)` validates an existing value and its chemistry.
+- `moleculeCss` contains optional package styling.
+
+## Options
+
+- `width?: number`: 160 to 1200, default `600`.
+- `height?: number`: 160 to 900, default `400`.
+- `enable3D?: boolean`: default `true`.
+- `maxAtoms?: number`: 1 to 1024, default `256`.
+- `maxBonds?: number`: 0 to 2048, default `512`.
+- `maxSourceBytes?: number`: 1 to 256 KiB, default 64 KiB.
+
+Both OpenChemLib and 3Dmol are loaded dynamically. Importing this package in Node does not load browser chemistry libraries. 3D rendering passes only validated local Molfile text to `addModel`; it never calls remote loading, download, fetch, get, or autoload APIs.

package/dist/index.cjs

@@ -0,0 +1,494 @@
+"use strict";
+
+//#region src/index.ts
+const DEFAULTS = {
+	width: 600,
+	height: 400,
+	enable3D: true,
+	maxAtoms: 256,
+	maxBonds: 512,
+	maxSourceBytes: 64 * 1024
+};
+const MAX_SOURCE_BYTES = 256 * 1024;
+const MAX_ATOMS = 1024;
+const MAX_BONDS = 2048;
+const DEFINITION_KEYS = new Set([
+	"version",
+	"format",
+	"source",
+	"view",
+	"style",
+	"atomLabels",
+	"highlight"
+]);
+const HIGHLIGHT_KEYS = new Set(["atoms", "bonds"]);
+const OPTION_KEYS = new Set([
+	"width",
+	"height",
+	"enable3D",
+	"maxAtoms",
+	"maxBonds",
+	"maxSourceBytes"
+]);
+const DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+const encoder = new TextEncoder();
+let oclPromise = null;
+const loadOpenChemLib = () => oclPromise ??= import("openchemlib");
+function invalid() {
+	return {
+		ok: false,
+		error: {
+			code: "invalid-definition",
+			message: "Molecule definition is invalid."
+		}
+	};
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function isDenseUniqueIndexes(value) {
+	if (!Array.isArray(value)) return false;
+	const seen = new Set();
+	for (let index = 0; index < value.length; index++) {
+		if (!(index in value)) return false;
+		const item = value[index];
+		if (!Number.isSafeInteger(item) || item < 0 || seen.has(item)) return false;
+		seen.add(item);
+	}
+	return true;
+}
+function isStructurallySafe(value, seen = new Set()) {
+	if (typeof value === "number") return Number.isFinite(value);
+	if (value === null || ["string", "boolean"].includes(typeof value)) return true;
+	if (typeof value !== "object") return false;
+	if (seen.has(value)) return false;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) if (!(i in value) || !isStructurallySafe(value[i], seen)) return false;
+		seen.delete(value);
+		return true;
+	}
+	if (!isPlainObject(value)) return false;
+	for (const key of Object.keys(value)) if (DANGEROUS_KEYS.has(key) || !isStructurallySafe(value[key], seen)) return false;
+	seen.delete(value);
+	return true;
+}
+function resolveOptions(options = {}) {
+	if (!isPlainObject(options)) throw new TypeError("Molecule options must be a plain object");
+	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key) || DANGEROUS_KEYS.has(key)) throw new TypeError("Unknown molecule option");
+	const resolved = {
+		...DEFAULTS,
+		...options
+	};
+	const boundedInteger = (name, min, max) => {
+		const value = resolved[name];
+		if (!Number.isSafeInteger(value) || value < min || value > max) throw new TypeError(`${name} is out of range`);
+	};
+	boundedInteger("width", 160, 1200);
+	boundedInteger("height", 160, 900);
+	boundedInteger("maxAtoms", 1, MAX_ATOMS);
+	boundedInteger("maxBonds", 0, MAX_BONDS);
+	boundedInteger("maxSourceBytes", 1, MAX_SOURCE_BYTES);
+	if (typeof resolved.enable3D !== "boolean") throw new TypeError("enable3D must be boolean");
+	return resolved;
+}
+function validateShape(value, options) {
+	if (!isStructurallySafe(value) || !isPlainObject(value)) return null;
+	const keys = Object.keys(value);
+	if (keys.some((key) => !DEFINITION_KEYS.has(key) || DANGEROUS_KEYS.has(key))) return null;
+	if (value.version !== 1 || value.format !== "smiles" && value.format !== "molfile") return null;
+	if (typeof value.source !== "string" || encoder.encode(value.source).byteLength > options.maxSourceBytes) return null;
+	if (value.view !== "2d" && value.view !== "3d") return null;
+	if (value.atomLabels !== void 0 && value.atomLabels !== "standard" && value.atomLabels !== "all") return null;
+	if (value.highlight !== void 0) {
+		if (!isPlainObject(value.highlight)) return null;
+		if (Object.keys(value.highlight).some((key) => !HIGHLIGHT_KEYS.has(key) || DANGEROUS_KEYS.has(key))) return null;
+		if (value.highlight.atoms !== void 0 && !isDenseUniqueIndexes(value.highlight.atoms)) return null;
+		if (value.highlight.bonds !== void 0 && !isDenseUniqueIndexes(value.highlight.bonds)) return null;
+	}
+	if (value.view === "2d") {
+		if (value.style !== void 0) return null;
+	} else {
+		if (value.format !== "molfile" || !options.enable3D) return null;
+		if (value.style !== void 0 && value.style !== "ball-and-stick" && value.style !== "space-filling") return null;
+	}
+	return value;
+}
+async function validateChemistry(definition, options) {
+	try {
+		const OCL = await loadOpenChemLib();
+		const parsed = definition.format === "smiles" ? OCL.Molecule.fromSmiles(definition.source) : OCL.Molecule.fromMolfile(definition.source);
+		const atomCount = parsed.getAllAtoms();
+		const bondCount = parsed.getAllBonds();
+		if (!Number.isSafeInteger(atomCount) || atomCount < 1 || atomCount > options.maxAtoms) return null;
+		if (!Number.isSafeInteger(bondCount) || bondCount < 0 || bondCount > options.maxBonds) return null;
+		if (definition.highlight?.atoms?.some((index) => index >= atomCount)) return null;
+		if (definition.highlight?.bonds?.some((index) => index >= bondCount)) return null;
+		if (definition.view === "3d") {
+			let minZ = Number.POSITIVE_INFINITY;
+			let maxZ = Number.NEGATIVE_INFINITY;
+			for (let atom = 0; atom < atomCount; atom++) {
+				const x = parsed.getAtomX(atom);
+				const y = parsed.getAtomY(atom);
+				const z = parsed.getAtomZ(atom);
+				if (![
+					x,
+					y,
+					z
+				].every(Number.isFinite)) return null;
+				minZ = Math.min(minZ, z);
+				maxZ = Math.max(maxZ, z);
+			}
+			if (maxZ - minZ <= 1e-6) return null;
+		}
+		return {
+			definition,
+			molecule: parsed,
+			atomCount,
+			bondCount
+		};
+	} catch {
+		return null;
+	}
+}
+async function validateMoleculeDefinition(value, options = {}) {
+	let resolved;
+	try {
+		resolved = resolveOptions(options);
+	} catch {
+		throw new TypeError("Invalid molecule options");
+	}
+	const definition = validateShape(value, resolved);
+	if (!definition) return invalid();
+	const chemistry = await validateChemistry(definition, resolved);
+	return chemistry ? {
+		ok: true,
+		value: chemistry.definition
+	} : invalid();
+}
+async function parseMoleculeDefinition(source, options = {}) {
+	if (typeof source !== "string") return invalid();
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return invalid();
+	}
+	return validateMoleculeDefinition(value, options);
+}
+function loadingOutput() {
+	return {
+		kind: "html",
+		html: "<div data-aigui-molecule-loading aria-label=\"Loading molecule\"></div>"
+	};
+}
+function errorOutput() {
+	return {
+		kind: "html",
+		html: "<div data-aigui-molecule-error role=\"img\" aria-label=\"Molecule could not be rendered.\">Molecule could not be rendered.</div>"
+	};
+}
+const SAFE_SVG_ELEMENTS = new Set([
+	"svg",
+	"g",
+	"path",
+	"line",
+	"polyline",
+	"polygon",
+	"circle",
+	"ellipse",
+	"rect",
+	"text",
+	"tspan",
+	"defs",
+	"clipPath"
+]);
+const SAFE_SVG_ATTRIBUTES = new Set([
+	"viewBox",
+	"width",
+	"height",
+	"x",
+	"y",
+	"x1",
+	"x2",
+	"y1",
+	"y2",
+	"cx",
+	"cy",
+	"r",
+	"rx",
+	"ry",
+	"d",
+	"points",
+	"fill",
+	"fill-opacity",
+	"stroke",
+	"stroke-width",
+	"stroke-linecap",
+	"stroke-linejoin",
+	"stroke-opacity",
+	"font-family",
+	"font-size",
+	"font-weight",
+	"text-anchor",
+	"dominant-baseline",
+	"transform",
+	"clip-path",
+	"id",
+	"class",
+	"style",
+	"xmlns"
+]);
+function safeSvgElement(svgSource, width, height) {
+	const parsed = new DOMParser().parseFromString(svgSource, "image/svg+xml");
+	if (parsed.querySelector("parsererror") || parsed.documentElement.localName !== "svg") return null;
+	for (const element of Array.from(parsed.querySelectorAll("*"))) {
+		if (!SAFE_SVG_ELEMENTS.has(element.localName)) {
+			element.remove();
+			continue;
+		}
+		for (const attribute of Array.from(element.attributes)) {
+			const value = attribute.value;
+			if (!SAFE_SVG_ATTRIBUTES.has(attribute.name) || /^on/i.test(attribute.name) || /url\s*\(|javascript:|data:/i.test(value)) element.removeAttribute(attribute.name);
+		}
+	}
+	const svg = document.importNode(parsed.documentElement, true);
+	svg.setAttribute("width", "100%");
+	svg.removeAttribute("height");
+	svg.setAttribute("role", "img");
+	svg.setAttribute("aria-label", "Molecular structure");
+	svg.setAttribute("style", `display:block;width:100%;height:auto;max-width:${width}px;max-height:${height}px;margin:auto`);
+	return svg;
+}
+function mount2D(svgSource, options) {
+	return {
+		kind: "mount",
+		mount(host) {
+			host.replaceChildren();
+			host.setAttribute("data-aigui-molecule", "2d");
+			const svg = safeSvgElement(svgSource, options.width, options.height);
+			if (!svg) {
+				host.appendChild(moleculeErrorElement());
+				return () => host.replaceChildren();
+			}
+			host.appendChild(svg);
+			let disposed = false;
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				host.replaceChildren();
+			};
+		}
+	};
+}
+const ELEMENT_COLORS = {
+	H: 16777215,
+	C: 9474192,
+	N: 3166456,
+	O: 16715021,
+	F: 9494608,
+	P: 16744448,
+	S: 16777008,
+	Cl: 2093087,
+	Br: 10889513,
+	I: 9699476
+};
+function mount3D(definition, options) {
+	return {
+		kind: "mount",
+		mount(host) {
+			let disposed = false;
+			let viewer;
+			let observer;
+			let reset;
+			host.replaceChildren();
+			host.setAttribute("data-aigui-molecule", "3d");
+			host.style.position = "relative";
+			host.style.width = "100%";
+			host.style.maxWidth = `${options.width}px`;
+			host.style.height = `${options.height}px`;
+			const viewport = document.createElement("div");
+			viewport.style.width = "100%";
+			viewport.style.height = "100%";
+			reset = document.createElement("button");
+			reset.type = "button";
+			reset.textContent = "Reset";
+			reset.setAttribute("data-aigui-molecule-reset", "");
+			const onReset = () => {
+				if (disposed || !viewer) return;
+				viewer.zoomTo();
+				viewer.render();
+			};
+			reset.addEventListener("click", onReset);
+			host.append(viewport, reset);
+			import("3dmol").then((module$1) => {
+				if (disposed) return;
+				const createViewer = module$1.createViewer;
+				viewer = createViewer(viewport, {
+					backgroundColor: "white",
+					defaultcolors: ELEMENT_COLORS
+				});
+				if (disposed) return;
+				viewer.addModel(definition.source, "mol");
+				const style = definition.style ?? "ball-and-stick";
+				viewer.setStyle({}, style === "space-filling" ? { sphere: {
+					scale: 1,
+					colorscheme: "default"
+				} } : {
+					stick: {
+						radius: .18,
+						colorscheme: "default"
+					},
+					sphere: {
+						scale: .28,
+						colorscheme: "default"
+					}
+				});
+				if (definition.highlight?.atoms?.length) viewer.addStyle({ index: definition.highlight.atoms }, { sphere: {
+					color: 16761856,
+					scale: .48
+				} });
+				if (definition.highlight?.bonds?.length) validateChemistry(definition, options).then((chemistry) => {
+					if (disposed || !viewer || !chemistry) return;
+					const atoms = new Set();
+					for (const bond of definition.highlight?.bonds ?? []) {
+						atoms.add(chemistry.molecule.getBondAtom(0, bond));
+						atoms.add(chemistry.molecule.getBondAtom(1, bond));
+					}
+					viewer.addStyle({ index: [...atoms] }, { stick: {
+						color: 16761856,
+						radius: .3
+					} });
+					viewer.render();
+				}).catch(() => void 0);
+				viewer.zoomTo();
+				viewer.render();
+				if (typeof ResizeObserver !== "undefined") {
+					observer = new ResizeObserver(() => {
+						if (!disposed && viewer) viewer.resize();
+					});
+					observer.observe(host);
+				}
+			}).catch(() => {
+				if (disposed) return;
+				host.replaceChildren(moleculeErrorElement());
+			});
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				reset?.removeEventListener("click", onReset);
+				observer?.disconnect();
+				if (viewer) {
+					let canvas;
+					try {
+						canvas = viewer.getCanvas();
+					} catch {
+						canvas = void 0;
+					}
+					try {
+						viewer.removeAllLabels();
+					} catch {}
+					try {
+						viewer.removeAllShapes();
+					} catch {}
+					try {
+						viewer.removeAllModels();
+					} catch {}
+					try {
+						viewer.clear();
+					} catch {}
+					try {
+						const gl = canvas?.getContext("webgl2") ?? canvas?.getContext("webgl");
+						gl?.getExtension("WEBGL_lose_context")?.loseContext();
+					} catch {}
+				}
+				viewer = void 0;
+				host.replaceChildren();
+			};
+		}
+	};
+}
+async function createOutput(node, options) {
+	if (node.complete !== true) return loadingOutput();
+	let value;
+	try {
+		value = JSON.parse(node.content ?? "");
+	} catch {
+		return errorOutput();
+	}
+	const definition = validateShape(value, options);
+	if (!definition) return errorOutput();
+	const chemistry = await validateChemistry(definition, options);
+	if (!chemistry) return errorOutput();
+	if (definition.view === "3d") return mount3D(definition, options);
+	try {
+		for (const atom of definition.highlight?.atoms ?? []) chemistry.molecule.setAtomSelection(atom, true);
+		for (const bond of definition.highlight?.bonds ?? []) {
+			chemistry.molecule.setAtomSelection(chemistry.molecule.getBondAtom(0, bond), true);
+			chemistry.molecule.setAtomSelection(chemistry.molecule.getBondAtom(1, bond), true);
+		}
+		const svg = chemistry.molecule.toSVG(options.width, options.height, void 0, {
+			showAtomNumber: definition.atomLabels === "all",
+			autoCrop: false
+		});
+		return mount2D(svg, options);
+	} catch {
+		return errorOutput();
+	}
+}
+function moleculePromptSpec(options = {}) {
+	const resolved = resolveOptions(options);
+	return [
+		"Molecules (one complete-gated fenced block): ```molecule <strict JSON>```.",
+		"Exact root fields: {\"version\":1,\"format\":\"smiles|molfile\",\"source\":\"...\",\"view\":\"2d|3d\",\"style\":\"ball-and-stick|space-filling\"?,\"atomLabels\":\"standard|all\"?,\"highlight\":{\"atoms\":[0],\"bonds\":[0]}?}. No unknown fields.",
+		"SMILES supports 2d only. Molfile supports 2d and 3d; 3d requires genuine finite non-flat z coordinates.",
+		`Source is local text only and must be at most ${resolved.maxSourceBytes} UTF-8 bytes. Atom and bond indexes are zero-based unique nonnegative integers.`,
+		"Never emit URLs, scripts, network requests, remote resources, HTML, credentials, download/get/autoload/fetch instructions, or executable content."
+	].join("\n");
+}
+const moleculeCss = `
+[data-aigui-molecule]{box-sizing:border-box;max-width:100%;overflow:hidden}
+[data-aigui-molecule="2d"] svg{display:block;max-width:100%;height:auto}
+[data-aigui-molecule="3d"] canvas{display:block;max-width:100%}
+[data-aigui-molecule-reset]{position:absolute;right:.5rem;bottom:.5rem;z-index:1;padding:.35rem .65rem;border:1px solid currentColor;border-radius:.35rem;background:Canvas;color:CanvasText;cursor:pointer}
+[data-aigui-molecule-loading]{min-height:10rem;border-radius:.5rem;background:linear-gradient(90deg,transparent,rgba(127,127,127,.12),transparent);background-size:200% 100%;animation:aigui-molecule-loading 1.2s linear infinite}
+[data-aigui-molecule-error]{padding:1rem;border:1px solid currentColor;border-radius:.5rem}
+@keyframes aigui-molecule-loading{to{background-position:-200% 0}}
+`.trim();
+function molecule(options = {}) {
+	const resolved = resolveOptions(options);
+	const outputs = new WeakMap();
+	const render = (node) => {
+		const cached = outputs.get(node);
+		if (cached) return cached;
+		const output = createOutput(node, resolved).catch(() => errorOutput());
+		outputs.set(node, output);
+		return output;
+	};
+	return {
+		name: "molecule",
+		nodeRenderers: { molecule: render },
+		promptSpec: moleculePromptSpec(resolved)
+	};
+}
+function moleculeErrorElement() {
+	const error = document.createElement("div");
+	error.setAttribute("data-aigui-molecule-error", "");
+	error.setAttribute("role", "img");
+	error.setAttribute("aria-label", "Molecule could not be rendered.");
+	error.textContent = "Molecule could not be rendered.";
+	return error;
+}
+
+//#endregion
+exports.molecule = molecule
+exports.moleculeCss = moleculeCss
+exports.moleculePromptSpec = moleculePromptSpec
+exports.parseMoleculeDefinition = parseMoleculeDefinition
+exports.validateMoleculeDefinition = validateMoleculeDefinition

package/dist/index.d.cts

@@ -0,0 +1,57 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+type MoleculeFormat = "smiles" | "molfile";
+type MoleculeView = "2d" | "3d";
+type MoleculeStyle = "ball-and-stick" | "space-filling";
+type MoleculeAtomLabels = "standard" | "all";
+interface MoleculeHighlight {
+  atoms?: number[];
+  bonds?: number[];
+}
+interface Molecule2DDefinition {
+  version: 1;
+  format: MoleculeFormat;
+  source: string;
+  view: "2d";
+  atomLabels?: MoleculeAtomLabels;
+  highlight?: MoleculeHighlight;
+}
+interface Molecule3DDefinition {
+  version: 1;
+  format: "molfile";
+  source: string;
+  view: "3d";
+  style?: MoleculeStyle;
+  atomLabels?: MoleculeAtomLabels;
+  highlight?: MoleculeHighlight;
+}
+type MoleculeDefinition = Molecule2DDefinition | Molecule3DDefinition;
+interface MoleculeOptions {
+  width?: number;
+  height?: number;
+  enable3D?: boolean;
+  maxAtoms?: number;
+  maxBonds?: number;
+  maxSourceBytes?: number;
+}
+type MoleculeErrorCode = "invalid-definition" | "invalid-options";
+interface MoleculeError {
+  code: MoleculeErrorCode;
+  message: string;
+}
+type MoleculeResult<T = MoleculeDefinition> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: MoleculeError;
+};
+declare function validateMoleculeDefinition(value: unknown, options?: MoleculeOptions): Promise<MoleculeResult>;
+declare function parseMoleculeDefinition(source: string, options?: MoleculeOptions): Promise<MoleculeResult>;
+declare function moleculePromptSpec(options?: MoleculeOptions): string;
+declare const moleculeCss: string;
+declare function molecule(options?: MoleculeOptions): AIGuiPlugin;
+
+//#endregion
+export { Molecule2DDefinition, Molecule3DDefinition, MoleculeAtomLabels, MoleculeDefinition, MoleculeError, MoleculeErrorCode, MoleculeFormat, MoleculeHighlight, MoleculeOptions, MoleculeResult, MoleculeStyle, MoleculeView, molecule, moleculeCss, moleculePromptSpec, parseMoleculeDefinition, validateMoleculeDefinition };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+type MoleculeFormat = "smiles" | "molfile";
+type MoleculeView = "2d" | "3d";
+type MoleculeStyle = "ball-and-stick" | "space-filling";
+type MoleculeAtomLabels = "standard" | "all";
+interface MoleculeHighlight {
+  atoms?: number[];
+  bonds?: number[];
+}
+interface Molecule2DDefinition {
+  version: 1;
+  format: MoleculeFormat;
+  source: string;
+  view: "2d";
+  atomLabels?: MoleculeAtomLabels;
+  highlight?: MoleculeHighlight;
+}
+interface Molecule3DDefinition {
+  version: 1;
+  format: "molfile";
+  source: string;
+  view: "3d";
+  style?: MoleculeStyle;
+  atomLabels?: MoleculeAtomLabels;
+  highlight?: MoleculeHighlight;
+}
+type MoleculeDefinition = Molecule2DDefinition | Molecule3DDefinition;
+interface MoleculeOptions {
+  width?: number;
+  height?: number;
+  enable3D?: boolean;
+  maxAtoms?: number;
+  maxBonds?: number;
+  maxSourceBytes?: number;
+}
+type MoleculeErrorCode = "invalid-definition" | "invalid-options";
+interface MoleculeError {
+  code: MoleculeErrorCode;
+  message: string;
+}
+type MoleculeResult<T = MoleculeDefinition> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: MoleculeError;
+};
+declare function validateMoleculeDefinition(value: unknown, options?: MoleculeOptions): Promise<MoleculeResult>;
+declare function parseMoleculeDefinition(source: string, options?: MoleculeOptions): Promise<MoleculeResult>;
+declare function moleculePromptSpec(options?: MoleculeOptions): string;
+declare const moleculeCss: string;
+declare function molecule(options?: MoleculeOptions): AIGuiPlugin;
+
+//#endregion
+export { Molecule2DDefinition, Molecule3DDefinition, MoleculeAtomLabels, MoleculeDefinition, MoleculeError, MoleculeErrorCode, MoleculeFormat, MoleculeHighlight, MoleculeOptions, MoleculeResult, MoleculeStyle, MoleculeView, molecule, moleculeCss, moleculePromptSpec, parseMoleculeDefinition, validateMoleculeDefinition };

package/dist/index.js

@@ -0,0 +1,488 @@
+//#region src/index.ts
+const DEFAULTS = {
+	width: 600,
+	height: 400,
+	enable3D: true,
+	maxAtoms: 256,
+	maxBonds: 512,
+	maxSourceBytes: 64 * 1024
+};
+const MAX_SOURCE_BYTES = 256 * 1024;
+const MAX_ATOMS = 1024;
+const MAX_BONDS = 2048;
+const DEFINITION_KEYS = new Set([
+	"version",
+	"format",
+	"source",
+	"view",
+	"style",
+	"atomLabels",
+	"highlight"
+]);
+const HIGHLIGHT_KEYS = new Set(["atoms", "bonds"]);
+const OPTION_KEYS = new Set([
+	"width",
+	"height",
+	"enable3D",
+	"maxAtoms",
+	"maxBonds",
+	"maxSourceBytes"
+]);
+const DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+const encoder = new TextEncoder();
+let oclPromise = null;
+const loadOpenChemLib = () => oclPromise ??= import("openchemlib");
+function invalid() {
+	return {
+		ok: false,
+		error: {
+			code: "invalid-definition",
+			message: "Molecule definition is invalid."
+		}
+	};
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function isDenseUniqueIndexes(value) {
+	if (!Array.isArray(value)) return false;
+	const seen = new Set();
+	for (let index = 0; index < value.length; index++) {
+		if (!(index in value)) return false;
+		const item = value[index];
+		if (!Number.isSafeInteger(item) || item < 0 || seen.has(item)) return false;
+		seen.add(item);
+	}
+	return true;
+}
+function isStructurallySafe(value, seen = new Set()) {
+	if (typeof value === "number") return Number.isFinite(value);
+	if (value === null || ["string", "boolean"].includes(typeof value)) return true;
+	if (typeof value !== "object") return false;
+	if (seen.has(value)) return false;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) if (!(i in value) || !isStructurallySafe(value[i], seen)) return false;
+		seen.delete(value);
+		return true;
+	}
+	if (!isPlainObject(value)) return false;
+	for (const key of Object.keys(value)) if (DANGEROUS_KEYS.has(key) || !isStructurallySafe(value[key], seen)) return false;
+	seen.delete(value);
+	return true;
+}
+function resolveOptions(options = {}) {
+	if (!isPlainObject(options)) throw new TypeError("Molecule options must be a plain object");
+	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key) || DANGEROUS_KEYS.has(key)) throw new TypeError("Unknown molecule option");
+	const resolved = {
+		...DEFAULTS,
+		...options
+	};
+	const boundedInteger = (name, min, max) => {
+		const value = resolved[name];
+		if (!Number.isSafeInteger(value) || value < min || value > max) throw new TypeError(`${name} is out of range`);
+	};
+	boundedInteger("width", 160, 1200);
+	boundedInteger("height", 160, 900);
+	boundedInteger("maxAtoms", 1, MAX_ATOMS);
+	boundedInteger("maxBonds", 0, MAX_BONDS);
+	boundedInteger("maxSourceBytes", 1, MAX_SOURCE_BYTES);
+	if (typeof resolved.enable3D !== "boolean") throw new TypeError("enable3D must be boolean");
+	return resolved;
+}
+function validateShape(value, options) {
+	if (!isStructurallySafe(value) || !isPlainObject(value)) return null;
+	const keys = Object.keys(value);
+	if (keys.some((key) => !DEFINITION_KEYS.has(key) || DANGEROUS_KEYS.has(key))) return null;
+	if (value.version !== 1 || value.format !== "smiles" && value.format !== "molfile") return null;
+	if (typeof value.source !== "string" || encoder.encode(value.source).byteLength > options.maxSourceBytes) return null;
+	if (value.view !== "2d" && value.view !== "3d") return null;
+	if (value.atomLabels !== void 0 && value.atomLabels !== "standard" && value.atomLabels !== "all") return null;
+	if (value.highlight !== void 0) {
+		if (!isPlainObject(value.highlight)) return null;
+		if (Object.keys(value.highlight).some((key) => !HIGHLIGHT_KEYS.has(key) || DANGEROUS_KEYS.has(key))) return null;
+		if (value.highlight.atoms !== void 0 && !isDenseUniqueIndexes(value.highlight.atoms)) return null;
+		if (value.highlight.bonds !== void 0 && !isDenseUniqueIndexes(value.highlight.bonds)) return null;
+	}
+	if (value.view === "2d") {
+		if (value.style !== void 0) return null;
+	} else {
+		if (value.format !== "molfile" || !options.enable3D) return null;
+		if (value.style !== void 0 && value.style !== "ball-and-stick" && value.style !== "space-filling") return null;
+	}
+	return value;
+}
+async function validateChemistry(definition, options) {
+	try {
+		const OCL = await loadOpenChemLib();
+		const parsed = definition.format === "smiles" ? OCL.Molecule.fromSmiles(definition.source) : OCL.Molecule.fromMolfile(definition.source);
+		const atomCount = parsed.getAllAtoms();
+		const bondCount = parsed.getAllBonds();
+		if (!Number.isSafeInteger(atomCount) || atomCount < 1 || atomCount > options.maxAtoms) return null;
+		if (!Number.isSafeInteger(bondCount) || bondCount < 0 || bondCount > options.maxBonds) return null;
+		if (definition.highlight?.atoms?.some((index) => index >= atomCount)) return null;
+		if (definition.highlight?.bonds?.some((index) => index >= bondCount)) return null;
+		if (definition.view === "3d") {
+			let minZ = Number.POSITIVE_INFINITY;
+			let maxZ = Number.NEGATIVE_INFINITY;
+			for (let atom = 0; atom < atomCount; atom++) {
+				const x = parsed.getAtomX(atom);
+				const y = parsed.getAtomY(atom);
+				const z = parsed.getAtomZ(atom);
+				if (![
+					x,
+					y,
+					z
+				].every(Number.isFinite)) return null;
+				minZ = Math.min(minZ, z);
+				maxZ = Math.max(maxZ, z);
+			}
+			if (maxZ - minZ <= 1e-6) return null;
+		}
+		return {
+			definition,
+			molecule: parsed,
+			atomCount,
+			bondCount
+		};
+	} catch {
+		return null;
+	}
+}
+async function validateMoleculeDefinition(value, options = {}) {
+	let resolved;
+	try {
+		resolved = resolveOptions(options);
+	} catch {
+		throw new TypeError("Invalid molecule options");
+	}
+	const definition = validateShape(value, resolved);
+	if (!definition) return invalid();
+	const chemistry = await validateChemistry(definition, resolved);
+	return chemistry ? {
+		ok: true,
+		value: chemistry.definition
+	} : invalid();
+}
+async function parseMoleculeDefinition(source, options = {}) {
+	if (typeof source !== "string") return invalid();
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return invalid();
+	}
+	return validateMoleculeDefinition(value, options);
+}
+function loadingOutput() {
+	return {
+		kind: "html",
+		html: "<div data-aigui-molecule-loading aria-label=\"Loading molecule\"></div>"
+	};
+}
+function errorOutput() {
+	return {
+		kind: "html",
+		html: "<div data-aigui-molecule-error role=\"img\" aria-label=\"Molecule could not be rendered.\">Molecule could not be rendered.</div>"
+	};
+}
+const SAFE_SVG_ELEMENTS = new Set([
+	"svg",
+	"g",
+	"path",
+	"line",
+	"polyline",
+	"polygon",
+	"circle",
+	"ellipse",
+	"rect",
+	"text",
+	"tspan",
+	"defs",
+	"clipPath"
+]);
+const SAFE_SVG_ATTRIBUTES = new Set([
+	"viewBox",
+	"width",
+	"height",
+	"x",
+	"y",
+	"x1",
+	"x2",
+	"y1",
+	"y2",
+	"cx",
+	"cy",
+	"r",
+	"rx",
+	"ry",
+	"d",
+	"points",
+	"fill",
+	"fill-opacity",
+	"stroke",
+	"stroke-width",
+	"stroke-linecap",
+	"stroke-linejoin",
+	"stroke-opacity",
+	"font-family",
+	"font-size",
+	"font-weight",
+	"text-anchor",
+	"dominant-baseline",
+	"transform",
+	"clip-path",
+	"id",
+	"class",
+	"style",
+	"xmlns"
+]);
+function safeSvgElement(svgSource, width, height) {
+	const parsed = new DOMParser().parseFromString(svgSource, "image/svg+xml");
+	if (parsed.querySelector("parsererror") || parsed.documentElement.localName !== "svg") return null;
+	for (const element of Array.from(parsed.querySelectorAll("*"))) {
+		if (!SAFE_SVG_ELEMENTS.has(element.localName)) {
+			element.remove();
+			continue;
+		}
+		for (const attribute of Array.from(element.attributes)) {
+			const value = attribute.value;
+			if (!SAFE_SVG_ATTRIBUTES.has(attribute.name) || /^on/i.test(attribute.name) || /url\s*\(|javascript:|data:/i.test(value)) element.removeAttribute(attribute.name);
+		}
+	}
+	const svg = document.importNode(parsed.documentElement, true);
+	svg.setAttribute("width", "100%");
+	svg.removeAttribute("height");
+	svg.setAttribute("role", "img");
+	svg.setAttribute("aria-label", "Molecular structure");
+	svg.setAttribute("style", `display:block;width:100%;height:auto;max-width:${width}px;max-height:${height}px;margin:auto`);
+	return svg;
+}
+function mount2D(svgSource, options) {
+	return {
+		kind: "mount",
+		mount(host) {
+			host.replaceChildren();
+			host.setAttribute("data-aigui-molecule", "2d");
+			const svg = safeSvgElement(svgSource, options.width, options.height);
+			if (!svg) {
+				host.appendChild(moleculeErrorElement());
+				return () => host.replaceChildren();
+			}
+			host.appendChild(svg);
+			let disposed = false;
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				host.replaceChildren();
+			};
+		}
+	};
+}
+const ELEMENT_COLORS = {
+	H: 16777215,
+	C: 9474192,
+	N: 3166456,
+	O: 16715021,
+	F: 9494608,
+	P: 16744448,
+	S: 16777008,
+	Cl: 2093087,
+	Br: 10889513,
+	I: 9699476
+};
+function mount3D(definition, options) {
+	return {
+		kind: "mount",
+		mount(host) {
+			let disposed = false;
+			let viewer;
+			let observer;
+			let reset;
+			host.replaceChildren();
+			host.setAttribute("data-aigui-molecule", "3d");
+			host.style.position = "relative";
+			host.style.width = "100%";
+			host.style.maxWidth = `${options.width}px`;
+			host.style.height = `${options.height}px`;
+			const viewport = document.createElement("div");
+			viewport.style.width = "100%";
+			viewport.style.height = "100%";
+			reset = document.createElement("button");
+			reset.type = "button";
+			reset.textContent = "Reset";
+			reset.setAttribute("data-aigui-molecule-reset", "");
+			const onReset = () => {
+				if (disposed || !viewer) return;
+				viewer.zoomTo();
+				viewer.render();
+			};
+			reset.addEventListener("click", onReset);
+			host.append(viewport, reset);
+			import("3dmol").then((module) => {
+				if (disposed) return;
+				const createViewer = module.createViewer;
+				viewer = createViewer(viewport, {
+					backgroundColor: "white",
+					defaultcolors: ELEMENT_COLORS
+				});
+				if (disposed) return;
+				viewer.addModel(definition.source, "mol");
+				const style = definition.style ?? "ball-and-stick";
+				viewer.setStyle({}, style === "space-filling" ? { sphere: {
+					scale: 1,
+					colorscheme: "default"
+				} } : {
+					stick: {
+						radius: .18,
+						colorscheme: "default"
+					},
+					sphere: {
+						scale: .28,
+						colorscheme: "default"
+					}
+				});
+				if (definition.highlight?.atoms?.length) viewer.addStyle({ index: definition.highlight.atoms }, { sphere: {
+					color: 16761856,
+					scale: .48
+				} });
+				if (definition.highlight?.bonds?.length) validateChemistry(definition, options).then((chemistry) => {
+					if (disposed || !viewer || !chemistry) return;
+					const atoms = new Set();
+					for (const bond of definition.highlight?.bonds ?? []) {
+						atoms.add(chemistry.molecule.getBondAtom(0, bond));
+						atoms.add(chemistry.molecule.getBondAtom(1, bond));
+					}
+					viewer.addStyle({ index: [...atoms] }, { stick: {
+						color: 16761856,
+						radius: .3
+					} });
+					viewer.render();
+				}).catch(() => void 0);
+				viewer.zoomTo();
+				viewer.render();
+				if (typeof ResizeObserver !== "undefined") {
+					observer = new ResizeObserver(() => {
+						if (!disposed && viewer) viewer.resize();
+					});
+					observer.observe(host);
+				}
+			}).catch(() => {
+				if (disposed) return;
+				host.replaceChildren(moleculeErrorElement());
+			});
+			return () => {
+				if (disposed) return;
+				disposed = true;
+				reset?.removeEventListener("click", onReset);
+				observer?.disconnect();
+				if (viewer) {
+					let canvas;
+					try {
+						canvas = viewer.getCanvas();
+					} catch {
+						canvas = void 0;
+					}
+					try {
+						viewer.removeAllLabels();
+					} catch {}
+					try {
+						viewer.removeAllShapes();
+					} catch {}
+					try {
+						viewer.removeAllModels();
+					} catch {}
+					try {
+						viewer.clear();
+					} catch {}
+					try {
+						const gl = canvas?.getContext("webgl2") ?? canvas?.getContext("webgl");
+						gl?.getExtension("WEBGL_lose_context")?.loseContext();
+					} catch {}
+				}
+				viewer = void 0;
+				host.replaceChildren();
+			};
+		}
+	};
+}
+async function createOutput(node, options) {
+	if (node.complete !== true) return loadingOutput();
+	let value;
+	try {
+		value = JSON.parse(node.content ?? "");
+	} catch {
+		return errorOutput();
+	}
+	const definition = validateShape(value, options);
+	if (!definition) return errorOutput();
+	const chemistry = await validateChemistry(definition, options);
+	if (!chemistry) return errorOutput();
+	if (definition.view === "3d") return mount3D(definition, options);
+	try {
+		for (const atom of definition.highlight?.atoms ?? []) chemistry.molecule.setAtomSelection(atom, true);
+		for (const bond of definition.highlight?.bonds ?? []) {
+			chemistry.molecule.setAtomSelection(chemistry.molecule.getBondAtom(0, bond), true);
+			chemistry.molecule.setAtomSelection(chemistry.molecule.getBondAtom(1, bond), true);
+		}
+		const svg = chemistry.molecule.toSVG(options.width, options.height, void 0, {
+			showAtomNumber: definition.atomLabels === "all",
+			autoCrop: false
+		});
+		return mount2D(svg, options);
+	} catch {
+		return errorOutput();
+	}
+}
+function moleculePromptSpec(options = {}) {
+	const resolved = resolveOptions(options);
+	return [
+		"Molecules (one complete-gated fenced block): ```molecule <strict JSON>```.",
+		"Exact root fields: {\"version\":1,\"format\":\"smiles|molfile\",\"source\":\"...\",\"view\":\"2d|3d\",\"style\":\"ball-and-stick|space-filling\"?,\"atomLabels\":\"standard|all\"?,\"highlight\":{\"atoms\":[0],\"bonds\":[0]}?}. No unknown fields.",
+		"SMILES supports 2d only. Molfile supports 2d and 3d; 3d requires genuine finite non-flat z coordinates.",
+		`Source is local text only and must be at most ${resolved.maxSourceBytes} UTF-8 bytes. Atom and bond indexes are zero-based unique nonnegative integers.`,
+		"Never emit URLs, scripts, network requests, remote resources, HTML, credentials, download/get/autoload/fetch instructions, or executable content."
+	].join("\n");
+}
+const moleculeCss = `
+[data-aigui-molecule]{box-sizing:border-box;max-width:100%;overflow:hidden}
+[data-aigui-molecule="2d"] svg{display:block;max-width:100%;height:auto}
+[data-aigui-molecule="3d"] canvas{display:block;max-width:100%}
+[data-aigui-molecule-reset]{position:absolute;right:.5rem;bottom:.5rem;z-index:1;padding:.35rem .65rem;border:1px solid currentColor;border-radius:.35rem;background:Canvas;color:CanvasText;cursor:pointer}
+[data-aigui-molecule-loading]{min-height:10rem;border-radius:.5rem;background:linear-gradient(90deg,transparent,rgba(127,127,127,.12),transparent);background-size:200% 100%;animation:aigui-molecule-loading 1.2s linear infinite}
+[data-aigui-molecule-error]{padding:1rem;border:1px solid currentColor;border-radius:.5rem}
+@keyframes aigui-molecule-loading{to{background-position:-200% 0}}
+`.trim();
+function molecule(options = {}) {
+	const resolved = resolveOptions(options);
+	const outputs = new WeakMap();
+	const render = (node) => {
+		const cached = outputs.get(node);
+		if (cached) return cached;
+		const output = createOutput(node, resolved).catch(() => errorOutput());
+		outputs.set(node, output);
+		return output;
+	};
+	return {
+		name: "molecule",
+		nodeRenderers: { molecule: render },
+		promptSpec: moleculePromptSpec(resolved)
+	};
+}
+function moleculeErrorElement() {
+	const error = document.createElement("div");
+	error.setAttribute("data-aigui-molecule-error", "");
+	error.setAttribute("role", "img");
+	error.setAttribute("aria-label", "Molecule could not be rendered.");
+	error.textContent = "Molecule could not be rendered.";
+	return error;
+}
+
+//#endregion
+export { molecule, moleculeCss, moleculePromptSpec, parseMoleculeDefinition, validateMoleculeDefinition };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ai-gui/plugin-molecule",
+  "version": "0.4.0",
+  "description": "Safe 2D and 3D molecular structure rendering plugin for AIGUI.",
+  "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": {
+    "openchemlib": "^9.24.0",
+    "3dmol": "^2.5.5",
+    "@ai-gui/core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project plugin-molecule",
+    "typecheck": "tsc --noEmit"
+  }
+}