@ai-gui/vanilla 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @ai-gui/vanilla
+
+Vanilla-DOM adapter for [AIGUI](../../README.md) — renders a streaming LLM response into a plain DOM element, no framework required.
+
+## Install
+
+```sh
+pnpm add @ai-gui/core @ai-gui/vanilla
+```
+
+## Usage
+
+```ts
+import { CardRegistry } from "@ai-gui/core"
+import { createRenderer } from "@ai-gui/vanilla"
+
+const registry = new CardRegistry()
+registry.register({
+  type: "weather",
+  description: "Weather summary",
+  // card render = (data, { onAction }) => HTMLElement
+  render: (data: any, { onAction }: any) => {
+    const el = document.createElement("div")
+    el.textContent = `${data.city} — ${data.tempC}°C`
+    return el
+  },
+})
+
+const r = createRenderer(document.getElementById("out")!, {
+  registry,
+  onCardAction: ({ type, params, cardType }) => {/* app makes the real request */},
+})
+
+await r.feed(response.body!) // r.push(chunk) / r.reset() / r.destroy()
+```
+
+## Exports
+
+- `createRenderer(el, { registry?, plugins?, sanitize?, onCardAction? })` → `{ push, feed, reset, destroy }`.
+
+`destroy()` tears down the host and cleans up any mounted interactive widgets. See the [root README](../../README.md) for cards, plugins, and `buildSystemPrompt`.

package/dist/index.cjs

@@ -0,0 +1,257 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __ai_gui_core = __toESM(require("@ai-gui/core"));
+
+//#region src/render-output.ts
+/** Translate a framework-neutral RenderOutput (from a plugin node renderer) into a DOM element. */
+function renderOutputToElement(out) {
+	switch (out.kind) {
+		case "html": {
+			const el = document.createElement("div");
+			el.innerHTML = (0, __ai_gui_core.sanitizeHtml)(out.html);
+			return el;
+		}
+		case "element": {
+			const el = document.createElement(out.tag);
+			for (const [key, value] of Object.entries(out.props ?? {})) if (key === "class" || key === "className") el.className = String(value);
+			else el.setAttribute(key, String(value));
+			for (const child of out.children ?? []) el.appendChild(renderOutputToElement(child));
+			return el;
+		}
+		case "card": {
+			const pre = document.createElement("pre");
+			pre.setAttribute("data-aigui-card-fallback", "");
+			const code = document.createElement("code");
+			code.textContent = JSON.stringify(out.data, null, 2);
+			pre.appendChild(code);
+			return pre;
+		}
+		case "mount": {
+			const el = document.createElement("div");
+			el.setAttribute("data-aigui-mount", "");
+			queueMicrotask(() => {
+				const c = out.mount(el);
+				if (typeof c === "function") el.__aiguiCleanup = c;
+			});
+			return el;
+		}
+	}
+}
+
+//#endregion
+//#region src/render-node-dom.ts
+function renderNodeToElement(node, ctx) {
+	const r = (0, __ai_gui_core.collectNodeRenderers)(ctx.plugins)[node.type];
+	if (r) {
+		const out = r(node);
+		if (typeof out?.then === "function") {
+			const ph = document.createElement("div");
+			ph.setAttribute("data-aigui-async-pending", "");
+			out.then((res) => ph.replaceWith(renderOutputToElement(res)));
+			return ph;
+		}
+		return renderOutputToElement(out);
+	}
+	switch (node.type) {
+		case "heading": {
+			const el = document.createElement(node.tag ?? "h1");
+			el.innerHTML = node.html ?? "";
+			return el;
+		}
+		case "paragraph": {
+			const el = document.createElement("p");
+			el.innerHTML = node.html ?? "";
+			return el;
+		}
+		case "code": {
+			const pre = document.createElement("pre");
+			if (node.attrs?.lang) pre.setAttribute("data-lang", node.attrs.lang);
+			const code = document.createElement("code");
+			code.textContent = node.content ?? "";
+			pre.appendChild(code);
+			return pre;
+		}
+		case "hr": return document.createElement("hr");
+		case "html": {
+			const el = document.createElement("div");
+			el.innerHTML = node.content ?? "";
+			return el;
+		}
+		case "card": return renderCardElement(node, ctx);
+		default: {
+			const el = document.createElement("div");
+			el.innerHTML = node.html ?? (0, __ai_gui_core.sanitizeHtml)(node.content ?? "");
+			return el;
+		}
+	}
+}
+function renderCardElement(node, ctx) {
+	const card = node.card;
+	if (!card) return document.createElement("div");
+	if (!card.complete) {
+		const el = document.createElement("div");
+		el.setAttribute("data-aigui-card-loading", "");
+		el.setAttribute("data-card-type", card.type);
+		return el;
+	}
+	if (!card.valid) {
+		const pre = document.createElement("pre");
+		pre.setAttribute("data-aigui-card-invalid", "");
+		const c = document.createElement("code");
+		c.textContent = JSON.stringify(card.data, null, 2);
+		pre.appendChild(c);
+		return pre;
+	}
+	const factory = ctx.registry?.getRender(card.type);
+	if (!factory) {
+		const pre = document.createElement("pre");
+		pre.setAttribute("data-aigui-card-fallback", "");
+		const c = document.createElement("code");
+		c.textContent = JSON.stringify(card.data, null, 2);
+		pre.appendChild(c);
+		return pre;
+	}
+	const host = document.createElement("div");
+	host.setAttribute("data-aigui-card", card.type);
+	host.appendChild(factory(card.data, { onAction: (a) => ctx.onCardAction?.({
+		...a,
+		cardType: card.type
+	}) }));
+	return host;
+}
+
+//#endregion
+//#region src/reconcile.ts
+function createReconcileState() {
+	return { els: new Map() };
+}
+/** Run a mounted widget's cleanup (if any) before the element leaves the DOM. */
+function disposeEl(el) {
+	el.__aiguiCleanup?.();
+}
+function reconcile(container, nodes, ctx, state) {
+	const nextKeys = new Set(nodes.map((n) => n.key));
+	for (const [key, entry] of state.els) if (!nextKeys.has(key)) {
+		disposeEl(entry.el);
+		entry.el.remove();
+		state.els.delete(key);
+	}
+	let prev = null;
+	for (const node of nodes) {
+		const hash = JSON.stringify(node);
+		let entry = state.els.get(node.key);
+		if (!entry) {
+			const el = renderNodeToElement(node, ctx);
+			entry = {
+				el,
+				hash
+			};
+			state.els.set(node.key, entry);
+		} else if (entry.hash !== hash) if (updateElementInPlace(entry.el, node, ctx)) entry.hash = hash;
+		else {
+			disposeEl(entry.el);
+			const el = renderNodeToElement(node, ctx);
+			entry.el.replaceWith(el);
+			entry.el = el;
+			entry.hash = hash;
+		}
+		const ref = prev ? prev.nextSibling : container.firstChild;
+		if (entry.el !== ref) container.insertBefore(entry.el, ref);
+		prev = entry.el;
+	}
+}
+/** Mutate an existing element to reflect the node without replacing it. Returns false when a fresh element is required. */
+function updateElementInPlace(el, node, ctx) {
+	switch (node.type) {
+		case "heading":
+			if (el.tagName !== (node.tag ?? "h1").toUpperCase()) return false;
+			el.innerHTML = node.html ?? "";
+			return true;
+		case "paragraph":
+			if (el.tagName !== "P") return false;
+			el.innerHTML = node.html ?? "";
+			return true;
+		case "code": {
+			if (el.tagName !== "PRE") return false;
+			if (node.attrs?.lang) el.setAttribute("data-lang", node.attrs.lang);
+			let code = el.querySelector("code");
+			if (!code) {
+				code = document.createElement("code");
+				el.appendChild(code);
+			}
+			code.textContent = node.content ?? "";
+			return true;
+		}
+		case "hr": return el.tagName === "HR";
+		case "html":
+			if (el.tagName !== "DIV") return false;
+			el.innerHTML = node.content ?? "";
+			return true;
+		case "card": return false;
+		default:
+			if (el.tagName !== "DIV") return false;
+			el.innerHTML = node.html ?? (0, __ai_gui_core.sanitizeHtml)(node.content ?? "");
+			return true;
+	}
+}
+
+//#endregion
+//#region src/create-renderer.ts
+function createRenderer(el, options = {}) {
+	const { onCardAction,...rendererOpts } = options;
+	const ctx = {
+		registry: options.registry,
+		onCardAction,
+		plugins: options.plugins
+	};
+	const state = createReconcileState();
+	const renderer = new __ai_gui_core.Renderer({
+		...rendererOpts,
+		onPatch: (_patches, nodes) => reconcile(el, nodes, ctx, state)
+	});
+	const disposeAll = () => {
+		for (const entry of state.els.values()) disposeEl(entry.el);
+	};
+	return {
+		push: (c) => renderer.push(c),
+		feed: (s) => renderer.feed(s),
+		reset: () => {
+			disposeAll();
+			renderer.reset();
+			state.els.clear();
+			el.replaceChildren();
+		},
+		destroy: () => {
+			disposeAll();
+			state.els.clear();
+			el.replaceChildren();
+		}
+	};
+}
+
+//#endregion
+exports.createRenderer = createRenderer
+exports.renderNodeToElement = renderNodeToElement
+exports.renderOutputToElement = renderOutputToElement

package/dist/index.d.cts

@@ -0,0 +1,34 @@
+import { AIGuiPlugin, ASTNode, CardRegistry, RenderOutput, RendererOptions } from "@ai-gui/core";
+
+//#region src/render-node-dom.d.ts
+interface DomRenderContext {
+  registry?: CardRegistry;
+  onCardAction?: (action: {
+    type: string;
+    params?: unknown;
+    cardType: string;
+  }) => void;
+  plugins?: AIGuiPlugin[];
+}
+declare function renderNodeToElement(node: ASTNode, ctx: DomRenderContext): HTMLElement;
+
+//#endregion
+//#region src/create-renderer.d.ts
+interface CreateRendererOptions extends Omit<RendererOptions, "onPatch"> {
+  onCardAction?: DomRenderContext["onCardAction"];
+}
+interface VanillaRenderer {
+  push: (chunk: string) => void;
+  feed: (source: AsyncIterable<string> | ReadableStream) => Promise<void>;
+  reset: () => void;
+  destroy: () => void;
+}
+declare function createRenderer(el: HTMLElement, options?: CreateRendererOptions): VanillaRenderer;
+
+//#endregion
+//#region src/render-output.d.ts
+/** Translate a framework-neutral RenderOutput (from a plugin node renderer) into a DOM element. */
+declare function renderOutputToElement(out: RenderOutput): HTMLElement;
+
+//#endregion
+export { CreateRendererOptions, DomRenderContext, VanillaRenderer, createRenderer, renderNodeToElement, renderOutputToElement };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { AIGuiPlugin, ASTNode, CardRegistry, RenderOutput, RendererOptions } from "@ai-gui/core";
+
+//#region src/render-node-dom.d.ts
+interface DomRenderContext {
+  registry?: CardRegistry;
+  onCardAction?: (action: {
+    type: string;
+    params?: unknown;
+    cardType: string;
+  }) => void;
+  plugins?: AIGuiPlugin[];
+}
+declare function renderNodeToElement(node: ASTNode, ctx: DomRenderContext): HTMLElement;
+
+//#endregion
+//#region src/create-renderer.d.ts
+interface CreateRendererOptions extends Omit<RendererOptions, "onPatch"> {
+  onCardAction?: DomRenderContext["onCardAction"];
+}
+interface VanillaRenderer {
+  push: (chunk: string) => void;
+  feed: (source: AsyncIterable<string> | ReadableStream) => Promise<void>;
+  reset: () => void;
+  destroy: () => void;
+}
+declare function createRenderer(el: HTMLElement, options?: CreateRendererOptions): VanillaRenderer;
+
+//#endregion
+//#region src/render-output.d.ts
+/** Translate a framework-neutral RenderOutput (from a plugin node renderer) into a DOM element. */
+declare function renderOutputToElement(out: RenderOutput): HTMLElement;
+
+//#endregion
+export { CreateRendererOptions, DomRenderContext, VanillaRenderer, createRenderer, renderNodeToElement, renderOutputToElement };

package/dist/index.js

@@ -0,0 +1,231 @@
+import { Renderer, collectNodeRenderers, sanitizeHtml } from "@ai-gui/core";
+
+//#region src/render-output.ts
+/** Translate a framework-neutral RenderOutput (from a plugin node renderer) into a DOM element. */
+function renderOutputToElement(out) {
+	switch (out.kind) {
+		case "html": {
+			const el = document.createElement("div");
+			el.innerHTML = sanitizeHtml(out.html);
+			return el;
+		}
+		case "element": {
+			const el = document.createElement(out.tag);
+			for (const [key, value] of Object.entries(out.props ?? {})) if (key === "class" || key === "className") el.className = String(value);
+			else el.setAttribute(key, String(value));
+			for (const child of out.children ?? []) el.appendChild(renderOutputToElement(child));
+			return el;
+		}
+		case "card": {
+			const pre = document.createElement("pre");
+			pre.setAttribute("data-aigui-card-fallback", "");
+			const code = document.createElement("code");
+			code.textContent = JSON.stringify(out.data, null, 2);
+			pre.appendChild(code);
+			return pre;
+		}
+		case "mount": {
+			const el = document.createElement("div");
+			el.setAttribute("data-aigui-mount", "");
+			queueMicrotask(() => {
+				const c = out.mount(el);
+				if (typeof c === "function") el.__aiguiCleanup = c;
+			});
+			return el;
+		}
+	}
+}
+
+//#endregion
+//#region src/render-node-dom.ts
+function renderNodeToElement(node, ctx) {
+	const r = collectNodeRenderers(ctx.plugins)[node.type];
+	if (r) {
+		const out = r(node);
+		if (typeof out?.then === "function") {
+			const ph = document.createElement("div");
+			ph.setAttribute("data-aigui-async-pending", "");
+			out.then((res) => ph.replaceWith(renderOutputToElement(res)));
+			return ph;
+		}
+		return renderOutputToElement(out);
+	}
+	switch (node.type) {
+		case "heading": {
+			const el = document.createElement(node.tag ?? "h1");
+			el.innerHTML = node.html ?? "";
+			return el;
+		}
+		case "paragraph": {
+			const el = document.createElement("p");
+			el.innerHTML = node.html ?? "";
+			return el;
+		}
+		case "code": {
+			const pre = document.createElement("pre");
+			if (node.attrs?.lang) pre.setAttribute("data-lang", node.attrs.lang);
+			const code = document.createElement("code");
+			code.textContent = node.content ?? "";
+			pre.appendChild(code);
+			return pre;
+		}
+		case "hr": return document.createElement("hr");
+		case "html": {
+			const el = document.createElement("div");
+			el.innerHTML = node.content ?? "";
+			return el;
+		}
+		case "card": return renderCardElement(node, ctx);
+		default: {
+			const el = document.createElement("div");
+			el.innerHTML = node.html ?? sanitizeHtml(node.content ?? "");
+			return el;
+		}
+	}
+}
+function renderCardElement(node, ctx) {
+	const card = node.card;
+	if (!card) return document.createElement("div");
+	if (!card.complete) {
+		const el = document.createElement("div");
+		el.setAttribute("data-aigui-card-loading", "");
+		el.setAttribute("data-card-type", card.type);
+		return el;
+	}
+	if (!card.valid) {
+		const pre = document.createElement("pre");
+		pre.setAttribute("data-aigui-card-invalid", "");
+		const c = document.createElement("code");
+		c.textContent = JSON.stringify(card.data, null, 2);
+		pre.appendChild(c);
+		return pre;
+	}
+	const factory = ctx.registry?.getRender(card.type);
+	if (!factory) {
+		const pre = document.createElement("pre");
+		pre.setAttribute("data-aigui-card-fallback", "");
+		const c = document.createElement("code");
+		c.textContent = JSON.stringify(card.data, null, 2);
+		pre.appendChild(c);
+		return pre;
+	}
+	const host = document.createElement("div");
+	host.setAttribute("data-aigui-card", card.type);
+	host.appendChild(factory(card.data, { onAction: (a) => ctx.onCardAction?.({
+		...a,
+		cardType: card.type
+	}) }));
+	return host;
+}
+
+//#endregion
+//#region src/reconcile.ts
+function createReconcileState() {
+	return { els: new Map() };
+}
+/** Run a mounted widget's cleanup (if any) before the element leaves the DOM. */
+function disposeEl(el) {
+	el.__aiguiCleanup?.();
+}
+function reconcile(container, nodes, ctx, state) {
+	const nextKeys = new Set(nodes.map((n) => n.key));
+	for (const [key, entry] of state.els) if (!nextKeys.has(key)) {
+		disposeEl(entry.el);
+		entry.el.remove();
+		state.els.delete(key);
+	}
+	let prev = null;
+	for (const node of nodes) {
+		const hash = JSON.stringify(node);
+		let entry = state.els.get(node.key);
+		if (!entry) {
+			const el = renderNodeToElement(node, ctx);
+			entry = {
+				el,
+				hash
+			};
+			state.els.set(node.key, entry);
+		} else if (entry.hash !== hash) if (updateElementInPlace(entry.el, node, ctx)) entry.hash = hash;
+		else {
+			disposeEl(entry.el);
+			const el = renderNodeToElement(node, ctx);
+			entry.el.replaceWith(el);
+			entry.el = el;
+			entry.hash = hash;
+		}
+		const ref = prev ? prev.nextSibling : container.firstChild;
+		if (entry.el !== ref) container.insertBefore(entry.el, ref);
+		prev = entry.el;
+	}
+}
+/** Mutate an existing element to reflect the node without replacing it. Returns false when a fresh element is required. */
+function updateElementInPlace(el, node, ctx) {
+	switch (node.type) {
+		case "heading":
+			if (el.tagName !== (node.tag ?? "h1").toUpperCase()) return false;
+			el.innerHTML = node.html ?? "";
+			return true;
+		case "paragraph":
+			if (el.tagName !== "P") return false;
+			el.innerHTML = node.html ?? "";
+			return true;
+		case "code": {
+			if (el.tagName !== "PRE") return false;
+			if (node.attrs?.lang) el.setAttribute("data-lang", node.attrs.lang);
+			let code = el.querySelector("code");
+			if (!code) {
+				code = document.createElement("code");
+				el.appendChild(code);
+			}
+			code.textContent = node.content ?? "";
+			return true;
+		}
+		case "hr": return el.tagName === "HR";
+		case "html":
+			if (el.tagName !== "DIV") return false;
+			el.innerHTML = node.content ?? "";
+			return true;
+		case "card": return false;
+		default:
+			if (el.tagName !== "DIV") return false;
+			el.innerHTML = node.html ?? sanitizeHtml(node.content ?? "");
+			return true;
+	}
+}
+
+//#endregion
+//#region src/create-renderer.ts
+function createRenderer(el, options = {}) {
+	const { onCardAction,...rendererOpts } = options;
+	const ctx = {
+		registry: options.registry,
+		onCardAction,
+		plugins: options.plugins
+	};
+	const state = createReconcileState();
+	const renderer = new Renderer({
+		...rendererOpts,
+		onPatch: (_patches, nodes) => reconcile(el, nodes, ctx, state)
+	});
+	const disposeAll = () => {
+		for (const entry of state.els.values()) disposeEl(entry.el);
+	};
+	return {
+		push: (c) => renderer.push(c),
+		feed: (s) => renderer.feed(s),
+		reset: () => {
+			disposeAll();
+			renderer.reset();
+			state.els.clear();
+			el.replaceChildren();
+		},
+		destroy: () => {
+			disposeAll();
+			state.els.clear();
+			el.replaceChildren();
+		}
+	};
+}
+
+//#endregion
+export { createRenderer, renderNodeToElement, renderOutputToElement };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ai-gui/vanilla",
+  "version": "0.1.0",
+  "description": "Framework-free DOM adapter for AIGUI — stream LLM output straight into the DOM.",
+  "keywords": [
+    "llm",
+    "ai",
+    "streaming",
+    "markdown",
+    "vanilla",
+    "dom",
+    "framework-free",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/vanilla"
+  },
+  "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": {
+    "@ai-gui/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}