@ai-gui/core 0.1.0

package/dist/index.js

@@ -0,0 +1,611 @@
+import DOMPurify from "dompurify";
+import MarkdownIt from "markdown-it";
+
+//#region src/partial-json.ts
+/**
+* Parse a possibly-incomplete JSON string, as produced by a streaming source.
+*
+* If the input is valid JSON, it is returned with `complete: true`. Otherwise
+* the parser attempts to repair the fragment by dropping any trailing
+* incomplete token (a dangling key, colon, or comma) and auto-closing unclosed
+* strings, objects, and arrays, returning whatever data has arrived so far with
+* `complete: false`. Unparseable input yields `{ data: undefined, complete: false }`
+* and never throws.
+*/
+function parsePartialJSON(input) {
+	const str = input.trim();
+	if (str === "") return {
+		data: void 0,
+		complete: false
+	};
+	try {
+		return {
+			data: JSON.parse(str),
+			complete: true
+		};
+	} catch {}
+	for (const candidate of repair(str)) try {
+		return {
+			data: JSON.parse(candidate),
+			complete: false
+		};
+	} catch {}
+	return {
+		data: void 0,
+		complete: false
+	};
+}
+const LITERAL_CHAR = /[0-9a-zA-Z+.\-]/;
+const WHITESPACE = /\s/;
+function repair(str) {
+	const stack = [];
+	let inString = false;
+	let escaped = false;
+	let stringIsKey = false;
+	let inLiteral = false;
+	let mode = "value";
+	let lastGoodEnd = -1;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") {
+				inString = false;
+				if (stringIsKey) mode = "objColon";
+				else {
+					mode = "afterValue";
+					lastGoodEnd = i + 1;
+				}
+			}
+			continue;
+		}
+		if (inLiteral) {
+			if (LITERAL_CHAR.test(ch)) continue;
+			inLiteral = false;
+			mode = "afterValue";
+			lastGoodEnd = i;
+		}
+		if (WHITESPACE.test(ch)) continue;
+		if (ch === "}" || ch === "]") {
+			stack.pop();
+			mode = "afterValue";
+			lastGoodEnd = i + 1;
+			continue;
+		}
+		switch (mode) {
+			case "value":
+				if (ch === "{") {
+					stack.push("obj");
+					mode = "objKey";
+					lastGoodEnd = i + 1;
+				} else if (ch === "[") {
+					stack.push("arr");
+					mode = "value";
+					lastGoodEnd = i + 1;
+				} else if (ch === "\"") {
+					inString = true;
+					stringIsKey = false;
+				} else inLiteral = true;
+				break;
+			case "objKey":
+				if (ch === "\"") {
+					inString = true;
+					stringIsKey = true;
+				}
+				break;
+			case "objColon":
+				if (ch === ":") mode = "value";
+				break;
+			case "afterValue":
+				if (ch === ",") mode = stack[stack.length - 1] === "obj" ? "objKey" : "value";
+				break;
+		}
+	}
+	if (inString && !stringIsKey) return [closeContainers(str + "\"", stack)];
+	const fallback = lastGoodEnd === -1 ? [] : [closeContainers(str.slice(0, lastGoodEnd), stack)];
+	if (inLiteral) return [closeContainers(str, stack), ...fallback];
+	return fallback;
+}
+function closeContainers(body, stack) {
+	let out = body.replace(/,\s*$/, "");
+	for (let i = stack.length - 1; i >= 0; i--) out += stack[i] === "obj" ? "}" : "]";
+	return out;
+}
+
+//#endregion
+//#region src/repair-markdown.ts
+/**
+* Temporarily repair half-finished markdown so a partial streaming buffer
+* renders smoothly. Operates on a copy of the buffer and returns a new string;
+* it never mutates the input. Pure function, no dependencies.
+*
+* The repairs are intentionally conservative: only unambiguous unclosed
+* inline/fence syntax is completed. Ambiguous constructs (e.g. a dangling
+* link text `[docs`) are left untouched to avoid guessing wrong.
+*/
+function repairMarkdown(buffer) {
+	let out = buffer;
+	const fenceCount = (out.match(/^```/gm) ?? []).length;
+	if (fenceCount % 2 === 1) {
+		if (!out.endsWith("\n")) out += "\n";
+		out += "```";
+		return out;
+	}
+	const tick = (out.match(/`/g) ?? []).length;
+	if (tick % 2 === 1) out += "`";
+	const bold = (out.match(/\*\*/g) ?? []).length;
+	if (bold % 2 === 1) out += "**";
+	const strike = (out.match(/~~/g) ?? []).length;
+	if (strike % 2 === 1) out += "~~";
+	return out;
+}
+
+//#endregion
+//#region src/sanitizer.ts
+/** Escape the HTML-significant characters so a string renders as inert text. */
+function escapeHtml(html) {
+	return html.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+* Sanitize an HTML string, stripping scripts and unsafe attributes.
+*
+* When a DOM is available (browser, or Node with jsdom) DOMPurify is used. In a
+* bare Node environment without a global `window`, DOMPurify cannot run, so we
+* fall back to escaping the HTML-significant characters. This never emits raw
+* markup and never throws.
+*/
+function sanitizeHtml(html) {
+	if (typeof window === "undefined") return escapeHtml(html);
+	return DOMPurify.sanitize(html);
+}
+
+//#endregion
+//#region src/card-registry.ts
+var CardRegistry = class {
+	cards = new Map();
+	register(def) {
+		this.cards.set(def.type, def);
+	}
+	has(type) {
+		return this.cards.has(type);
+	}
+	getRender(type) {
+		return this.cards.get(type)?.render;
+	}
+	parse(type, rawJson) {
+		const def = this.cards.get(type);
+		const { data, complete } = parsePartialJSON(rawJson);
+		if (!def) return {
+			data,
+			complete,
+			valid: false
+		};
+		const valid = complete && this.validate(def, data);
+		return {
+			data,
+			complete,
+			valid
+		};
+	}
+	validate(def, data) {
+		if (def.validate) return def.validate(data);
+		if (def.schema) return validateSchema(def.schema, data);
+		return true;
+	}
+	toPromptSpec() {
+		const lines = ["You can output cards. Format: a ```card:<type> fenced block with JSON inside. Available cards:"];
+		for (const def of this.cards.values()) {
+			lines.push(`- \`card:${def.type}\`: ${def.description}`);
+			if (def.schema?.properties) {
+				const fields = Object.entries(def.schema.properties).map(([k, v]) => `${k}(${v.type ?? "any"})`).join(", ");
+				lines.push(`  fields: ${fields}`);
+			}
+			if (def.example !== void 0) lines.push(`  example: ${JSON.stringify(def.example)}`);
+		}
+		return lines.join("\n");
+	}
+	toJSONSchema() {
+		const properties = {};
+		for (const def of this.cards.values()) if (def.schema) properties[def.type] = def.schema;
+		return {
+			type: "object",
+			properties
+		};
+	}
+};
+/** Minimal JSON Schema validation: covers type / required / properties, enough for cards. */
+function validateSchema(schema, data) {
+	if (schema.type === "object") {
+		if (typeof data !== "object" || data === null || Array.isArray(data)) return false;
+		const obj = data;
+		for (const req of schema.required ?? []) if (!(req in obj)) return false;
+		for (const [key, sub] of Object.entries(schema.properties ?? {})) if (key in obj && !validateSchema(sub, obj[key])) return false;
+		return true;
+	}
+	if (schema.type === "array") {
+		if (!Array.isArray(data)) return false;
+		return schema.items ? data.every((d) => validateSchema(schema.items, d)) : true;
+	}
+	if (schema.type === "string") return typeof data === "string";
+	if (schema.type === "number") return typeof data === "number";
+	if (schema.type === "boolean") return typeof data === "boolean";
+	return true;
+}
+
+//#endregion
+//#region src/plugins.ts
+/** Merge every plugin's `nodeRenderers` into a single map (later plugins win). */
+function collectNodeRenderers(plugins = []) {
+	const map = {};
+	for (const p of plugins) for (const [k, v] of Object.entries(p.nodeRenderers ?? {})) map[k] = v;
+	return map;
+}
+/** The set of node types claimed by the given plugins. */
+function pluginNodeTypes(plugins = []) {
+	return new Set(Object.keys(collectNodeRenderers(plugins)));
+}
+
+//#endregion
+//#region src/parser.ts
+/** Build a parser that turns markdown source into a flat list of ASTNodes. */
+function createParser(options = {}) {
+	const md = new MarkdownIt({
+		html: true,
+		linkify: true
+	});
+	options.configureMd?.(md);
+	for (const plugin of options.plugins ?? []) plugin.extendParser?.(md);
+	const pluginTypes = pluginNodeTypes(options.plugins);
+	return (src) => {
+		const tokens = md.parse(src, {});
+		const nodes = [];
+		let index = 0;
+		for (let i = 0; i < tokens.length; i++) {
+			const t = tokens[i];
+			if (t.type === "fence") {
+				const info = t.info.trim();
+				if (info.startsWith("card:") && options.registry) {
+					const cardType = info.slice(5);
+					const res = options.registry.parse(cardType, t.content);
+					nodes.push({
+						key: `${index++}:card`,
+						type: "card",
+						card: {
+							type: cardType,
+							data: res.data,
+							complete: res.complete,
+							valid: res.valid
+						}
+					});
+				} else if (pluginTypes.has(info)) nodes.push({
+					key: `${index++}:${info}`,
+					type: info,
+					content: t.content,
+					attrs: { info }
+				});
+				else nodes.push({
+					key: `${index++}:code`,
+					type: "code",
+					tag: "code",
+					attrs: info ? { lang: info } : void 0,
+					content: t.content
+				});
+				continue;
+			}
+			if (t.type === "hr") {
+				nodes.push({
+					key: `${index++}:hr`,
+					type: "hr",
+					tag: "hr"
+				});
+				continue;
+			}
+			if (t.type === "code_block") {
+				nodes.push({
+					key: `${index++}:code`,
+					type: "code",
+					tag: "code",
+					content: t.content
+				});
+				continue;
+			}
+			if (t.type === "html_block") {
+				nodes.push({
+					key: `${index++}:html`,
+					type: "html",
+					content: t.content
+				});
+				continue;
+			}
+			if (t.type === "heading_open") {
+				const inline = tokens[i + 1];
+				const raw = inline?.content ?? "";
+				nodes.push({
+					key: `${index++}:heading`,
+					type: "heading",
+					tag: t.tag,
+					content: raw,
+					html: md.renderInline(raw)
+				});
+				i += 2;
+				continue;
+			}
+			if (t.type === "paragraph_open") {
+				const inline = tokens[i + 1];
+				const raw = inline?.content ?? "";
+				nodes.push({
+					key: `${index++}:paragraph`,
+					type: "paragraph",
+					tag: "p",
+					content: raw,
+					html: md.renderInline(raw)
+				});
+				i += 2;
+				continue;
+			}
+			if (t.type.endsWith("_open") && t.level === 0) {
+				const closeType = t.type.replace("_open", "_close");
+				let j = i;
+				let depth = 0;
+				for (; j < tokens.length; j++) {
+					if (tokens[j].type === t.type) depth++;
+					if (tokens[j].type === closeType) {
+						depth--;
+						if (depth === 0) break;
+					}
+				}
+				const slice = tokens.slice(i, j + 1);
+				nodes.push({
+					key: `${index++}:${t.type}`,
+					type: "html",
+					content: md.renderer.render(slice, md.options, {})
+				});
+				i = j;
+				continue;
+			}
+			if (t.block && t.level === 0) {
+				nodes.push({
+					key: `${index++}:${t.type}`,
+					type: "html",
+					content: md.renderer.render([t], md.options, {})
+				});
+				continue;
+			}
+		}
+		return nodes;
+	};
+}
+
+//#endregion
+//#region src/diff.ts
+/** Produce a minimal set of patches turning `prev` into `next`, keyed by node key. */
+function diffAst(prev, next) {
+	const patches = [];
+	const prevByKey = new Map(prev.map((n) => [n.key, n]));
+	const nextKeys = new Set(next.map((n) => n.key));
+	next.forEach((node, index) => {
+		const old = prevByKey.get(node.key);
+		if (!old) patches.push({
+			op: "insert",
+			index,
+			node
+		});
+		else if (!nodeEqual(old, node)) patches.push({
+			op: "update",
+			key: node.key,
+			node
+		});
+	});
+	for (const node of prev) if (!nextKeys.has(node.key)) patches.push({
+		op: "remove",
+		key: node.key
+	});
+	return patches;
+}
+function nodeEqual(a, b) {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+//#endregion
+//#region src/renderer.ts
+/**
+* Streaming render orchestrator: accumulate incoming markdown chunks, repair the
+* partial buffer, parse it into an AST, diff against the previous AST, and emit
+* the resulting patches via `onPatch`.
+*/
+var Renderer = class {
+	buffer = "";
+	prevAst = [];
+	parse;
+	options;
+	sanitize;
+	constructor(options = {}) {
+		this.options = options;
+		this.sanitize = options.sanitize !== false;
+		if (options.registry) for (const plugin of options.plugins ?? []) for (const card of plugin.cards ?? []) options.registry.register(card);
+		this.parse = createParser({
+			registry: options.registry,
+			plugins: options.plugins
+		});
+	}
+	push(chunk) {
+		this.buffer += chunk;
+		this.render();
+	}
+	async feed(source) {
+		if (Symbol.asyncIterator in source) {
+			for await (const chunk of source) this.push(chunk);
+			return;
+		}
+		const reader = source.getReader();
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (value != null) this.push(value);
+		}
+	}
+	reset() {
+		this.buffer = "";
+		this.prevAst = [];
+	}
+	render() {
+		const repaired = repairMarkdown(this.buffer);
+		const nextAst = this.parse(repaired);
+		if (this.sanitize) sanitizeNodes(nextAst);
+		const patches = diffAst(this.prevAst, nextAst);
+		this.prevAst = nextAst;
+		if (patches.length > 0) this.options.onPatch?.(patches, nextAst);
+	}
+};
+/**
+* Recursively sanitize node markup in place: the content of `html` nodes and
+* the rendered inline `html` field carried by any node.
+*/
+function sanitizeNodes(nodes) {
+	for (const node of nodes) {
+		if (node.type === "html" && typeof node.content === "string") node.content = sanitizeHtml(node.content);
+		if (node.html) node.html = sanitizeHtml(node.html);
+		if (node.children) sanitizeNodes(node.children);
+	}
+}
+
+//#endregion
+//#region src/stream-router.ts
+const DEFAULT_CHANNEL = "content";
+/**
+* Demultiplexes one incoming stream into multiple named channels so different
+* UI regions can update independently (e.g. `progress` + `content` from a single
+* SSE). Framing is auto-detected per line and supports:
+*
+*  1. JSON envelope: `{"ch":"<channel>","delta":"text"}` (a text delta) or
+*     `{"ch":"<channel>","data":<any>}` (a structured value). May appear bare or
+*     after a `data: ` prefix.
+*  2. SSE `event: <name>` sets the channel for the following `data:` line(s).
+*  3. A plain `data: <text>` line with no `ch` and no preceding `event:` is a
+*     text delta on the default `content` channel.
+*/
+var StreamRouter = class {
+	sinks = new Map();
+	handlers = new Map();
+	/** Bind a text-stream sink to a channel: text deltas call `sink.push(delta)`. */
+	channel(name, sink) {
+		this.sinks.set(name, sink);
+		return this;
+	}
+	/** Bind a handler to a channel: data values (and deltas as strings) call it. */
+	on(name, handler) {
+		this.handlers.set(name, handler);
+		return this;
+	}
+	/**
+	* Consume a stream to completion, dispatching each parsed line to its channel.
+	* Accepts an async iterable of strings, or a `ReadableStream` of either strings
+	* or `Uint8Array` bytes (decoded as UTF-8).
+	*/
+	async feed(source) {
+		let buffer = "";
+		let currentEvent;
+		const consume = (chunk) => {
+			buffer += chunk;
+			let index;
+			while ((index = buffer.indexOf("\n")) !== -1) {
+				const line = buffer.slice(0, index);
+				buffer = buffer.slice(index + 1);
+				currentEvent = this.processLine(line, currentEvent);
+			}
+		};
+		if ("getReader" in source && typeof source.getReader === "function") {
+			const reader = source.getReader();
+			const decoder = new TextDecoder();
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (value == null) continue;
+				consume(typeof value === "string" ? value : decoder.decode(value, { stream: true }));
+			}
+			const tail = decoder.decode();
+			if (tail) consume(tail);
+		} else for await (const chunk of source) consume(chunk);
+		if (buffer.length > 0) this.processLine(buffer, currentEvent);
+	}
+	/** Process a single raw line; returns the (possibly updated) current event. */
+	processLine(rawLine, currentEvent) {
+		const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+		if (line.trim() === "") return void 0;
+		if (line.startsWith("event:")) return line.slice(6).trim();
+		let payload = line;
+		if (payload.startsWith("data:")) {
+			payload = payload.slice(5);
+			if (payload.startsWith(" ")) payload = payload.slice(1);
+		}
+		if (payload.startsWith("{")) {
+			const parsed = tryParseJson(payload);
+			if (parsed !== void 0 && isRecord(parsed) && typeof parsed.ch === "string") {
+				if ("delta" in parsed) this.routeDelta(parsed.ch, String(parsed.delta));
+				else this.routeData(parsed.ch, parsed.data);
+				return currentEvent;
+			}
+			if (parsed !== void 0) {
+				this.routeData(currentEvent ?? DEFAULT_CHANNEL, parsed);
+				return currentEvent;
+			}
+		}
+		if (currentEvent !== void 0) {
+			const parsed = tryParseJson(payload);
+			this.routeData(currentEvent, parsed !== void 0 ? parsed : payload);
+			return currentEvent;
+		}
+		this.routeDelta(DEFAULT_CHANNEL, payload);
+		return currentEvent;
+	}
+	/** Route a text delta: to a bound sink and/or an on() handler (either/both). */
+	routeDelta(channel, text) {
+		const sink = this.sinks.get(channel);
+		const handler = this.handlers.get(channel);
+		if (sink) sink.push(text);
+		if (handler) handler(text);
+	}
+	/** Route a structured value: to the handler, or a string value to a lone sink. */
+	routeData(channel, value) {
+		const handler = this.handlers.get(channel);
+		if (handler) {
+			handler(value);
+			return;
+		}
+		const sink = this.sinks.get(channel);
+		if (sink && typeof value === "string") sink.push(value);
+	}
+};
+function tryParseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return void 0;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+
+//#endregion
+//#region src/build-system-prompt.ts
+/**
+* Assembles the LLM system-prompt guidance: an optional base, the registered
+* cards' spec, and every plugin's promptSpec. Consumers prepend this to their
+* own system prompt so the model knows which fenced blocks it may emit.
+*/
+function buildSystemPrompt(options = {}) {
+	const parts = [];
+	if (options.base) parts.push(options.base);
+	const cardSpec = options.registry?.toPromptSpec();
+	if (options.registry && hasCards(options.registry) && cardSpec) parts.push(cardSpec);
+	for (const p of options.plugins ?? []) if (p.promptSpec) parts.push(p.promptSpec);
+	return parts.join("\n\n");
+}
+function hasCards(registry) {
+	return registry.toPromptSpec().includes("card:");
+}
+
+//#endregion
+export { CardRegistry, Renderer, StreamRouter, buildSystemPrompt, collectNodeRenderers, createParser, diffAst, parsePartialJSON, pluginNodeTypes, repairMarkdown, sanitizeHtml };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ai-gui/core",
+  "version": "0.1.0",
+  "description": "Headless streaming renderer core for LLM-generated UI — markdown/JSON repair, card registry, AST diff, plugin engine, sanitizer.",
+  "keywords": [
+    "llm",
+    "ai",
+    "streaming",
+    "markdown",
+    "renderer",
+    "headless",
+    "sanitizer",
+    "ast-diff",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/liliang-cn/aigui#readme",
+  "bugs": "https://github.com/liliang-cn/aigui/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "dompurify": "^3.4.12",
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "jsdom": "^29.1.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}