@ai-gui/vanilla 0.1.0 → 0.3.0

package/README.md

@@ -11,24 +11,37 @@ pnpm add @ai-gui/core @ai-gui/vanilla
 ## Usage
 
 ```ts
-import { CardRegistry } from "@ai-gui/core"
+import { ActionRegistry, CardRegistry, CardStore, createActionRuntime } 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) => {
+  // HTMLElement remains supported. Return a VanillaCardInstance for stateful cards.
+  render: (data: any, { state, onAction }: any) => {
     const el = document.createElement("div")
     el.textContent = `${data.city} — ${data.tempC}°C`
-    return el
+    return {
+      element: el,
+      update(next: any, context: any) {
+        el.textContent = `${next.city} — ${next.tempC}°C (${context.state.status})`
+      },
+      destroy() {},
+    }
   },
 })
 
+const actions = new ActionRegistry()
+actions.register({ type: "refresh", run: async (params, { signal }) => fetch("/api/weather", { signal }) })
+const cardStore = new CardStore({ registry })
+const actionRuntime = createActionRuntime({ registry: actions, cardStore })
+
 const r = createRenderer(document.getElementById("out")!, {
   registry,
-  onCardAction: ({ type, params, cardType }) => {/* app makes the real request */},
+  cardStore,
+  actionRuntime,
+  onCardAction: (action) => console.log("observed", action),
 })
 
 await r.feed(response.body!) // r.push(chunk) / r.reset() / r.destroy()
@@ -36,6 +49,9 @@ await r.feed(response.body!) // r.push(chunk) / r.reset() / r.destroy()
 
 ## Exports
 
-- `createRenderer(el, { registry?, plugins?, sanitize?, onCardAction? })` → `{ push, feed, reset, destroy }`.
+- `createRenderer(el, { registry?, cardStore?, plugins?, sanitize?, actionRuntime?, onCardAction? })` → `{ push, feed, reset, destroy }`.
+- `VanillaCardInstance` is `{ element, update(data, { state, onAction }), destroy? }`. Its host and `element` stay mounted while AST data, store data, or action state changes.
+- Legacy factories returning an `HTMLElement` remain supported. For cards with an `id` and a `cardStore`, the adapter may rebuild that child element after store updates so it displays current data.
+- Cards with a valid top-level `id` register their initial data in the supplied external `CardStore`. The adapter subscribes but never clears that store; a shared store updates every renderer displaying the same card id.
 
 `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

@@ -26,18 +26,18 @@ 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) {
+function renderOutputToElement(out, sanitize) {
 	switch (out.kind) {
 		case "html": {
 			const el = document.createElement("div");
-			el.innerHTML = (0, __ai_gui_core.sanitizeHtml)(out.html);
+			el.innerHTML = sanitizeOutput(out.html, sanitize);
 			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));
+			for (const child of out.children ?? []) el.appendChild(renderOutputToElement(child, sanitize));
 			return el;
 		}
 		case "card": {
@@ -52,37 +52,61 @@ function renderOutputToElement(out) {
 			const el = document.createElement("div");
 			el.setAttribute("data-aigui-mount", "");
 			queueMicrotask(() => {
+				if (el.__aiguiDisposed) return;
 				const c = out.mount(el);
-				if (typeof c === "function") el.__aiguiCleanup = c;
+				if (typeof c === "function") if (el.__aiguiDisposed) c();
+				else el.__aiguiCleanup = c;
 			});
 			return el;
 		}
 	}
 }
+function sanitizeOutput(html, sanitize) {
+	if (sanitize === false) return html;
+	return (0, __ai_gui_core.sanitizeHtml)(html, typeof sanitize === "object" ? sanitize : void 0);
+}
 
 //#endregion
 //#region src/render-node-dom.ts
 function renderNodeToElement(node, ctx) {
-	const r = (0, __ai_gui_core.collectNodeRenderers)(ctx.plugins)[node.type];
+	const r = (ctx.nodeRenderers ?? (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;
+		if (node.complete === false) {
+			const loading = document.createElement("div");
+			loading.setAttribute("data-aigui-block-loading", "");
+			loading.setAttribute("data-block-type", node.type);
+			return loading;
+		}
+		try {
+			const out = r(node);
+			if (typeof out?.then === "function") {
+				const host = document.createElement("div");
+				host.setAttribute("data-aigui-async-pending", "");
+				out.then((res) => {
+					if (host.__aiguiDisposed) return;
+					host.removeAttribute("data-aigui-async-pending");
+					host.replaceChildren(renderOutputToElement(res, ctx.sanitize));
+				}, () => {
+					if (host.__aiguiDisposed) return;
+					host.removeAttribute("data-aigui-async-pending");
+					host.setAttribute("data-aigui-async-error", "");
+				});
+				return host;
+			}
+			return renderOutputToElement(out, ctx.sanitize);
+		} catch {
+			return renderFallback(node, ctx);
 		}
-		return renderOutputToElement(out);
 	}
 	switch (node.type) {
 		case "heading": {
 			const el = document.createElement(node.tag ?? "h1");
-			el.innerHTML = node.html ?? "";
+			el.innerHTML = renderHtml(node.html ?? "", ctx);
 			return el;
 		}
 		case "paragraph": {
 			const el = document.createElement("p");
-			el.innerHTML = node.html ?? "";
+			el.innerHTML = renderHtml(node.html ?? "", ctx);
 			return el;
 		}
 		case "code": {
@@ -96,17 +120,22 @@ function renderNodeToElement(node, ctx) {
 		case "hr": return document.createElement("hr");
 		case "html": {
 			const el = document.createElement("div");
-			el.innerHTML = node.content ?? "";
+			el.innerHTML = renderHtml(node.content ?? "", ctx);
 			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;
-		}
+		default: return renderFallback(node, ctx);
 	}
 }
+function renderFallback(node, ctx) {
+	const el = document.createElement("div");
+	el.innerHTML = renderHtml(node.html ?? node.content ?? "", ctx);
+	return el;
+}
+function renderHtml(html, ctx) {
+	if (ctx.sanitized || ctx.sanitize === false) return html;
+	return (0, __ai_gui_core.sanitizeHtml)(html, typeof ctx.sanitize === "object" ? ctx.sanitize : void 0);
+}
 function renderCardElement(node, ctx) {
 	const card = node.card;
 	if (!card) return document.createElement("div");
@@ -125,22 +154,153 @@ function renderCardElement(node, ctx) {
 		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;
-	}
+	if (!factory) return createCardFallback(card, ctx);
 	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
-	}) }));
+	const controller = createCardController(host, card, factory, ctx);
+	host.__aiguiCardController = controller;
+	host.__aiguiCleanup = () => controller.destroy();
 	return host;
 }
+function createCardFallback(card, ctx) {
+	const pre = document.createElement("pre");
+	pre.setAttribute("data-aigui-card-fallback", "");
+	const code = document.createElement("code");
+	pre.appendChild(code);
+	const render = (data) => {
+		pre.removeAttribute("data-aigui-card-missing");
+		code.textContent = JSON.stringify(data, null, 2);
+	};
+	const missing = () => {
+		pre.setAttribute("data-aigui-card-missing", "");
+		code.textContent = "Card data is unavailable";
+	};
+	let unsubscribe = () => {};
+	if (card.id !== void 0 && ctx.cardStore) {
+		try {
+			const record = ctx.cardStore.register({
+				id: card.id,
+				type: card.type,
+				data: card.data
+			});
+			render(record.data);
+		} catch (error) {
+			pre.setAttribute("data-aigui-card-store-error", "");
+			code.textContent = error instanceof Error ? error.message : "Card registration failed";
+		}
+		unsubscribe = ctx.cardStore.subscribe(card.id, (next) => {
+			if (!next || next.type !== card.type) missing();
+			else {
+				pre.removeAttribute("data-aigui-card-store-error");
+				render(next.data);
+			}
+		});
+		pre.__aiguiCleanup = unsubscribe;
+	} else render(card.data);
+	return pre;
+}
+function updateCardElement(el, node) {
+	return el.__aiguiCardController?.updateNode(node) ?? false;
+}
+function createCardController(host, initialCard, factory, ctx) {
+	let card = initialCard;
+	let destroyed = false;
+	let unsubscribe = () => {};
+	let instance;
+	let element;
+	let missing = false;
+	const id = card.id;
+	const onAction = (action) => ctx.onCardAction?.({
+		...action,
+		cardType: card.type,
+		...id === void 0 ? {} : { cardId: id }
+	});
+	let data = card.data;
+	let state = { status: "idle" };
+	let registrationError;
+	if (id !== void 0 && ctx.cardStore) try {
+		const record = ctx.cardStore.register({
+			id,
+			type: card.type,
+			data
+		});
+		data = record.data;
+		state = record.action;
+	} catch (error) {
+		registrationError = error;
+	}
+	const context = () => ({
+		state,
+		onAction
+	});
+	const mount = (nextData) => {
+		const rendered = factory(nextData, context());
+		if (isVanillaCardInstance(rendered)) {
+			instance = rendered;
+			element = rendered.element;
+		} else {
+			instance = void 0;
+			element = rendered;
+		}
+		host.replaceChildren(element);
+	};
+	const update = (nextData, nextState) => {
+		if (destroyed) return;
+		data = nextData;
+		state = nextState;
+		host.removeAttribute("data-aigui-card-store-error");
+		if (missing) {
+			missing = false;
+			host.removeAttribute("data-aigui-card-missing");
+			if (element) host.replaceChildren(element);
+		}
+		if (instance) instance.update(data, context());
+		else mount(data);
+	};
+	const showMissing = () => {
+		if (destroyed || missing) return;
+		missing = true;
+		host.removeAttribute("data-aigui-card-store-error");
+		host.setAttribute("data-aigui-card-missing", "");
+		const fallback = document.createElement("code");
+		fallback.textContent = "Card data is unavailable";
+		host.replaceChildren(fallback);
+	};
+	if (registrationError === void 0) mount(data);
+	else {
+		host.setAttribute("data-aigui-card-store-error", "");
+		const code = document.createElement("code");
+		code.textContent = registrationError instanceof Error ? registrationError.message : "Card registration failed";
+		host.replaceChildren(code);
+	}
+	if (id !== void 0 && ctx.cardStore) unsubscribe = ctx.cardStore.subscribe(id, (record) => {
+		if (!record || record.type !== card.type) {
+			showMissing();
+			return;
+		}
+		update(record.data, record.action);
+	});
+	return {
+		updateNode(node) {
+			const next = node.card;
+			if (!next?.complete || !next.valid || next.type !== card.type || next.id !== id) return false;
+			card = next;
+			if (id === void 0 || !ctx.cardStore) update(next.data, state);
+			return true;
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			unsubscribe();
+			unsubscribe = () => {};
+			instance?.destroy?.();
+			instance = void 0;
+		}
+	};
+}
+function isVanillaCardInstance(value) {
+	return !(value instanceof HTMLElement) && value !== null && typeof value === "object" && value.element instanceof HTMLElement && typeof value.update === "function";
+}
 
 //#endregion
 //#region src/reconcile.ts
@@ -149,7 +309,15 @@ function createReconcileState() {
 }
 /** Run a mounted widget's cleanup (if any) before the element leaves the DOM. */
 function disposeEl(el) {
-	el.__aiguiCleanup?.();
+	for (const child of el.querySelectorAll("*")) disposeManagedEl(child);
+	disposeManagedEl(el);
+}
+function disposeManagedEl(el) {
+	const managed = el;
+	if (managed.__aiguiDisposed) return;
+	managed.__aiguiDisposed = true;
+	managed.__aiguiCleanup?.();
+	managed.__aiguiCleanup = void 0;
 }
 function reconcile(container, nodes, ctx, state) {
 	const nextKeys = new Set(nodes.map((n) => n.key));
@@ -184,6 +352,7 @@ function reconcile(container, nodes, ctx, state) {
 }
 /** Mutate an existing element to reflect the node without replacing it. Returns false when a fresh element is required. */
 function updateElementInPlace(el, node, ctx) {
+	if (ctx.nodeRenderers?.[node.type]) return false;
 	switch (node.type) {
 		case "heading":
 			if (el.tagName !== (node.tag ?? "h1").toUpperCase()) return false;
@@ -209,10 +378,10 @@ function updateElementInPlace(el, node, ctx) {
 			if (el.tagName !== "DIV") return false;
 			el.innerHTML = node.content ?? "";
 			return true;
-		case "card": return false;
+		case "card": return updateCardElement(el, node);
 		default:
 			if (el.tagName !== "DIV") return false;
-			el.innerHTML = node.html ?? (0, __ai_gui_core.sanitizeHtml)(node.content ?? "");
+			el.innerHTML = node.html ?? node.content ?? "";
 			return true;
 	}
 }
@@ -220,33 +389,73 @@ function updateElementInPlace(el, node, ctx) {
 //#endregion
 //#region src/create-renderer.ts
 function createRenderer(el, options = {}) {
-	const { onCardAction,...rendererOpts } = options;
-	const ctx = {
-		registry: options.registry,
-		onCardAction,
-		plugins: options.plugins
+	const { actionRuntime, cardStore, onCardAction,...rendererOpts } = options;
+	let actionScope = {
+		owner: {},
+		controller: new AbortController()
+	};
+	const handleCardAction = (action) => {
+		if (actionRuntime) actionRuntime.dispatch({
+			...action,
+			params: action.params
+		}, {
+			owner: actionScope.owner,
+			signal: actionScope.controller.signal
+		}).catch(() => {});
+		onCardAction?.(action);
 	};
 	const state = createReconcileState();
+	let destroyed = false;
 	const renderer = new __ai_gui_core.Renderer({
 		...rendererOpts,
-		onPatch: (_patches, nodes) => reconcile(el, nodes, ctx, state)
+		onPatch: (_patches, nodes) => {
+			if (!destroyed) reconcile(el, nodes, ctx, state);
+		}
 	});
+	const ctx = {
+		registry: options.registry,
+		cardStore,
+		onCardAction: handleCardAction,
+		plugins: options.plugins,
+		nodeRenderers: (0, __ai_gui_core.collectNodeRenderers)(options.plugins, { debugTarget: renderer }),
+		sanitize: options.sanitize,
+		sanitized: true
+	};
 	const disposeAll = () => {
 		for (const entry of state.els.values()) disposeEl(entry.el);
 	};
+	const resetActionScope = () => {
+		actionScope.controller.abort();
+		actionScope = {
+			owner: {},
+			controller: new AbortController()
+		};
+	};
 	return {
-		push: (c) => renderer.push(c),
-		feed: (s) => renderer.feed(s),
+		debugSource: "renderer",
+		subscribeDebug: (listener) => renderer.subscribeDebug(listener),
+		push: (c) => {
+			if (!destroyed) renderer.push(c);
+		},
+		feed: (source, feedOptions) => destroyed ? Promise.resolve() : renderer.feed(source, feedOptions),
 		reset: () => {
-			disposeAll();
-			renderer.reset();
-			state.els.clear();
-			el.replaceChildren();
+			if (!destroyed) {
+				resetActionScope();
+				disposeAll();
+				renderer.reset();
+				state.els.clear();
+				el.replaceChildren();
+			}
 		},
 		destroy: () => {
-			disposeAll();
-			state.els.clear();
-			el.replaceChildren();
+			if (!destroyed) {
+				destroyed = true;
+				actionScope.controller.abort();
+				renderer.reset();
+				disposeAll();
+				state.els.clear();
+				el.replaceChildren();
+			}
 		}
 	};
 }

package/dist/index.d.cts

@@ -1,25 +1,48 @@
-import { AIGuiPlugin, ASTNode, CardRegistry, RenderOutput, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, RenderOutput, RendererOptions } from "@ai-gui/core";
 
 //#region src/render-node-dom.d.ts
+interface VanillaCardAction {
+  type: string;
+  params?: unknown;
+}
+interface VanillaCardUpdateContext {
+  state: CardAction;
+  onAction: (action: VanillaCardAction) => void;
+}
+interface VanillaCardInstance {
+  element: HTMLElement;
+  update: (data: unknown, context: VanillaCardUpdateContext) => void;
+  destroy?: () => void;
+}
+type VanillaCardFactory = (data: unknown, context: VanillaCardUpdateContext) => HTMLElement | VanillaCardInstance;
 interface DomRenderContext {
   registry?: CardRegistry;
+  cardStore?: CardStore;
   onCardAction?: (action: {
     type: string;
     params?: unknown;
     cardType: string;
+    cardId?: string;
   }) => void;
   plugins?: AIGuiPlugin[];
+  nodeRenderers?: Record<string, NodeRenderer>;
+  sanitize?: RendererOptions["sanitize"];
+  sanitized?: boolean;
 }
 declare function renderNodeToElement(node: ASTNode, ctx: DomRenderContext): HTMLElement;
 
 //#endregion
 //#region src/create-renderer.d.ts
 interface CreateRendererOptions extends Omit<RendererOptions, "onPatch"> {
+  actionRuntime?: ActionRuntime;
+  cardStore?: CardStore;
   onCardAction?: DomRenderContext["onCardAction"];
 }
 interface VanillaRenderer {
+  readonly debugSource: "renderer";
+  subscribeDebug: (listener: DebugEventListener) => () => void;
   push: (chunk: string) => void;
-  feed: (source: AsyncIterable<string> | ReadableStream) => Promise<void>;
+  feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
   destroy: () => void;
 }
@@ -28,7 +51,7 @@ declare function createRenderer(el: HTMLElement, options?: CreateRendererOptions
 //#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;
+declare function renderOutputToElement(out: RenderOutput, sanitize?: RendererOptions["sanitize"]): HTMLElement;
 
 //#endregion
-export { CreateRendererOptions, DomRenderContext, VanillaRenderer, createRenderer, renderNodeToElement, renderOutputToElement };
+export { CreateRendererOptions, DomRenderContext, VanillaCardAction, VanillaCardFactory, VanillaCardInstance, VanillaCardUpdateContext, VanillaRenderer, createRenderer, renderNodeToElement, renderOutputToElement };

package/dist/index.d.ts

@@ -1,25 +1,48 @@
-import { AIGuiPlugin, ASTNode, CardRegistry, RenderOutput, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, RenderOutput, RendererOptions } from "@ai-gui/core";
 
 //#region src/render-node-dom.d.ts
+interface VanillaCardAction {
+  type: string;
+  params?: unknown;
+}
+interface VanillaCardUpdateContext {
+  state: CardAction;
+  onAction: (action: VanillaCardAction) => void;
+}
+interface VanillaCardInstance {
+  element: HTMLElement;
+  update: (data: unknown, context: VanillaCardUpdateContext) => void;
+  destroy?: () => void;
+}
+type VanillaCardFactory = (data: unknown, context: VanillaCardUpdateContext) => HTMLElement | VanillaCardInstance;
 interface DomRenderContext {
   registry?: CardRegistry;
+  cardStore?: CardStore;
   onCardAction?: (action: {
     type: string;
     params?: unknown;
     cardType: string;
+    cardId?: string;
   }) => void;
   plugins?: AIGuiPlugin[];
+  nodeRenderers?: Record<string, NodeRenderer>;
+  sanitize?: RendererOptions["sanitize"];
+  sanitized?: boolean;
 }
 declare function renderNodeToElement(node: ASTNode, ctx: DomRenderContext): HTMLElement;
 
 //#endregion
 //#region src/create-renderer.d.ts
 interface CreateRendererOptions extends Omit<RendererOptions, "onPatch"> {
+  actionRuntime?: ActionRuntime;
+  cardStore?: CardStore;
   onCardAction?: DomRenderContext["onCardAction"];
 }
 interface VanillaRenderer {
+  readonly debugSource: "renderer";
+  subscribeDebug: (listener: DebugEventListener) => () => void;
   push: (chunk: string) => void;
-  feed: (source: AsyncIterable<string> | ReadableStream) => Promise<void>;
+  feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
   destroy: () => void;
 }
@@ -28,7 +51,7 @@ declare function createRenderer(el: HTMLElement, options?: CreateRendererOptions
 //#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;
+declare function renderOutputToElement(out: RenderOutput, sanitize?: RendererOptions["sanitize"]): HTMLElement;
 
 //#endregion
-export { CreateRendererOptions, DomRenderContext, VanillaRenderer, createRenderer, renderNodeToElement, renderOutputToElement };
+export { CreateRendererOptions, DomRenderContext, VanillaCardAction, VanillaCardFactory, VanillaCardInstance, VanillaCardUpdateContext, VanillaRenderer, createRenderer, renderNodeToElement, renderOutputToElement };

package/dist/index.js

@@ -2,18 +2,18 @@ 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) {
+function renderOutputToElement(out, sanitize) {
 	switch (out.kind) {
 		case "html": {
 			const el = document.createElement("div");
-			el.innerHTML = sanitizeHtml(out.html);
+			el.innerHTML = sanitizeOutput(out.html, sanitize);
 			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));
+			for (const child of out.children ?? []) el.appendChild(renderOutputToElement(child, sanitize));
 			return el;
 		}
 		case "card": {
@@ -28,37 +28,61 @@ function renderOutputToElement(out) {
 			const el = document.createElement("div");
 			el.setAttribute("data-aigui-mount", "");
 			queueMicrotask(() => {
+				if (el.__aiguiDisposed) return;
 				const c = out.mount(el);
-				if (typeof c === "function") el.__aiguiCleanup = c;
+				if (typeof c === "function") if (el.__aiguiDisposed) c();
+				else el.__aiguiCleanup = c;
 			});
 			return el;
 		}
 	}
 }
+function sanitizeOutput(html, sanitize) {
+	if (sanitize === false) return html;
+	return sanitizeHtml(html, typeof sanitize === "object" ? sanitize : void 0);
+}
 
 //#endregion
 //#region src/render-node-dom.ts
 function renderNodeToElement(node, ctx) {
-	const r = collectNodeRenderers(ctx.plugins)[node.type];
+	const r = (ctx.nodeRenderers ?? 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);
+		if (node.complete === false) {
+			const loading = document.createElement("div");
+			loading.setAttribute("data-aigui-block-loading", "");
+			loading.setAttribute("data-block-type", node.type);
+			return loading;
+		}
+		try {
+			const out = r(node);
+			if (typeof out?.then === "function") {
+				const host = document.createElement("div");
+				host.setAttribute("data-aigui-async-pending", "");
+				out.then((res) => {
+					if (host.__aiguiDisposed) return;
+					host.removeAttribute("data-aigui-async-pending");
+					host.replaceChildren(renderOutputToElement(res, ctx.sanitize));
+				}, () => {
+					if (host.__aiguiDisposed) return;
+					host.removeAttribute("data-aigui-async-pending");
+					host.setAttribute("data-aigui-async-error", "");
+				});
+				return host;
+			}
+			return renderOutputToElement(out, ctx.sanitize);
+		} catch {
+			return renderFallback(node, ctx);
+		}
 	}
 	switch (node.type) {
 		case "heading": {
 			const el = document.createElement(node.tag ?? "h1");
-			el.innerHTML = node.html ?? "";
+			el.innerHTML = renderHtml(node.html ?? "", ctx);
 			return el;
 		}
 		case "paragraph": {
 			const el = document.createElement("p");
-			el.innerHTML = node.html ?? "";
+			el.innerHTML = renderHtml(node.html ?? "", ctx);
 			return el;
 		}
 		case "code": {
@@ -72,17 +96,22 @@ function renderNodeToElement(node, ctx) {
 		case "hr": return document.createElement("hr");
 		case "html": {
 			const el = document.createElement("div");
-			el.innerHTML = node.content ?? "";
+			el.innerHTML = renderHtml(node.content ?? "", ctx);
 			return el;
 		}
 		case "card": return renderCardElement(node, ctx);
-		default: {
-			const el = document.createElement("div");
-			el.innerHTML = node.html ?? sanitizeHtml(node.content ?? "");
-			return el;
-		}
+		default: return renderFallback(node, ctx);
 	}
 }
+function renderFallback(node, ctx) {
+	const el = document.createElement("div");
+	el.innerHTML = renderHtml(node.html ?? node.content ?? "", ctx);
+	return el;
+}
+function renderHtml(html, ctx) {
+	if (ctx.sanitized || ctx.sanitize === false) return html;
+	return sanitizeHtml(html, typeof ctx.sanitize === "object" ? ctx.sanitize : void 0);
+}
 function renderCardElement(node, ctx) {
 	const card = node.card;
 	if (!card) return document.createElement("div");
@@ -101,22 +130,153 @@ function renderCardElement(node, ctx) {
 		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;
-	}
+	if (!factory) return createCardFallback(card, ctx);
 	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
-	}) }));
+	const controller = createCardController(host, card, factory, ctx);
+	host.__aiguiCardController = controller;
+	host.__aiguiCleanup = () => controller.destroy();
 	return host;
 }
+function createCardFallback(card, ctx) {
+	const pre = document.createElement("pre");
+	pre.setAttribute("data-aigui-card-fallback", "");
+	const code = document.createElement("code");
+	pre.appendChild(code);
+	const render = (data) => {
+		pre.removeAttribute("data-aigui-card-missing");
+		code.textContent = JSON.stringify(data, null, 2);
+	};
+	const missing = () => {
+		pre.setAttribute("data-aigui-card-missing", "");
+		code.textContent = "Card data is unavailable";
+	};
+	let unsubscribe = () => {};
+	if (card.id !== void 0 && ctx.cardStore) {
+		try {
+			const record = ctx.cardStore.register({
+				id: card.id,
+				type: card.type,
+				data: card.data
+			});
+			render(record.data);
+		} catch (error) {
+			pre.setAttribute("data-aigui-card-store-error", "");
+			code.textContent = error instanceof Error ? error.message : "Card registration failed";
+		}
+		unsubscribe = ctx.cardStore.subscribe(card.id, (next) => {
+			if (!next || next.type !== card.type) missing();
+			else {
+				pre.removeAttribute("data-aigui-card-store-error");
+				render(next.data);
+			}
+		});
+		pre.__aiguiCleanup = unsubscribe;
+	} else render(card.data);
+	return pre;
+}
+function updateCardElement(el, node) {
+	return el.__aiguiCardController?.updateNode(node) ?? false;
+}
+function createCardController(host, initialCard, factory, ctx) {
+	let card = initialCard;
+	let destroyed = false;
+	let unsubscribe = () => {};
+	let instance;
+	let element;
+	let missing = false;
+	const id = card.id;
+	const onAction = (action) => ctx.onCardAction?.({
+		...action,
+		cardType: card.type,
+		...id === void 0 ? {} : { cardId: id }
+	});
+	let data = card.data;
+	let state = { status: "idle" };
+	let registrationError;
+	if (id !== void 0 && ctx.cardStore) try {
+		const record = ctx.cardStore.register({
+			id,
+			type: card.type,
+			data
+		});
+		data = record.data;
+		state = record.action;
+	} catch (error) {
+		registrationError = error;
+	}
+	const context = () => ({
+		state,
+		onAction
+	});
+	const mount = (nextData) => {
+		const rendered = factory(nextData, context());
+		if (isVanillaCardInstance(rendered)) {
+			instance = rendered;
+			element = rendered.element;
+		} else {
+			instance = void 0;
+			element = rendered;
+		}
+		host.replaceChildren(element);
+	};
+	const update = (nextData, nextState) => {
+		if (destroyed) return;
+		data = nextData;
+		state = nextState;
+		host.removeAttribute("data-aigui-card-store-error");
+		if (missing) {
+			missing = false;
+			host.removeAttribute("data-aigui-card-missing");
+			if (element) host.replaceChildren(element);
+		}
+		if (instance) instance.update(data, context());
+		else mount(data);
+	};
+	const showMissing = () => {
+		if (destroyed || missing) return;
+		missing = true;
+		host.removeAttribute("data-aigui-card-store-error");
+		host.setAttribute("data-aigui-card-missing", "");
+		const fallback = document.createElement("code");
+		fallback.textContent = "Card data is unavailable";
+		host.replaceChildren(fallback);
+	};
+	if (registrationError === void 0) mount(data);
+	else {
+		host.setAttribute("data-aigui-card-store-error", "");
+		const code = document.createElement("code");
+		code.textContent = registrationError instanceof Error ? registrationError.message : "Card registration failed";
+		host.replaceChildren(code);
+	}
+	if (id !== void 0 && ctx.cardStore) unsubscribe = ctx.cardStore.subscribe(id, (record) => {
+		if (!record || record.type !== card.type) {
+			showMissing();
+			return;
+		}
+		update(record.data, record.action);
+	});
+	return {
+		updateNode(node) {
+			const next = node.card;
+			if (!next?.complete || !next.valid || next.type !== card.type || next.id !== id) return false;
+			card = next;
+			if (id === void 0 || !ctx.cardStore) update(next.data, state);
+			return true;
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			unsubscribe();
+			unsubscribe = () => {};
+			instance?.destroy?.();
+			instance = void 0;
+		}
+	};
+}
+function isVanillaCardInstance(value) {
+	return !(value instanceof HTMLElement) && value !== null && typeof value === "object" && value.element instanceof HTMLElement && typeof value.update === "function";
+}
 
 //#endregion
 //#region src/reconcile.ts
@@ -125,7 +285,15 @@ function createReconcileState() {
 }
 /** Run a mounted widget's cleanup (if any) before the element leaves the DOM. */
 function disposeEl(el) {
-	el.__aiguiCleanup?.();
+	for (const child of el.querySelectorAll("*")) disposeManagedEl(child);
+	disposeManagedEl(el);
+}
+function disposeManagedEl(el) {
+	const managed = el;
+	if (managed.__aiguiDisposed) return;
+	managed.__aiguiDisposed = true;
+	managed.__aiguiCleanup?.();
+	managed.__aiguiCleanup = void 0;
 }
 function reconcile(container, nodes, ctx, state) {
 	const nextKeys = new Set(nodes.map((n) => n.key));
@@ -160,6 +328,7 @@ function reconcile(container, nodes, ctx, state) {
 }
 /** Mutate an existing element to reflect the node without replacing it. Returns false when a fresh element is required. */
 function updateElementInPlace(el, node, ctx) {
+	if (ctx.nodeRenderers?.[node.type]) return false;
 	switch (node.type) {
 		case "heading":
 			if (el.tagName !== (node.tag ?? "h1").toUpperCase()) return false;
@@ -185,10 +354,10 @@ function updateElementInPlace(el, node, ctx) {
 			if (el.tagName !== "DIV") return false;
 			el.innerHTML = node.content ?? "";
 			return true;
-		case "card": return false;
+		case "card": return updateCardElement(el, node);
 		default:
 			if (el.tagName !== "DIV") return false;
-			el.innerHTML = node.html ?? sanitizeHtml(node.content ?? "");
+			el.innerHTML = node.html ?? node.content ?? "";
 			return true;
 	}
 }
@@ -196,33 +365,73 @@ function updateElementInPlace(el, node, ctx) {
 //#endregion
 //#region src/create-renderer.ts
 function createRenderer(el, options = {}) {
-	const { onCardAction,...rendererOpts } = options;
-	const ctx = {
-		registry: options.registry,
-		onCardAction,
-		plugins: options.plugins
+	const { actionRuntime, cardStore, onCardAction,...rendererOpts } = options;
+	let actionScope = {
+		owner: {},
+		controller: new AbortController()
+	};
+	const handleCardAction = (action) => {
+		if (actionRuntime) actionRuntime.dispatch({
+			...action,
+			params: action.params
+		}, {
+			owner: actionScope.owner,
+			signal: actionScope.controller.signal
+		}).catch(() => {});
+		onCardAction?.(action);
 	};
 	const state = createReconcileState();
+	let destroyed = false;
 	const renderer = new Renderer({
 		...rendererOpts,
-		onPatch: (_patches, nodes) => reconcile(el, nodes, ctx, state)
+		onPatch: (_patches, nodes) => {
+			if (!destroyed) reconcile(el, nodes, ctx, state);
+		}
 	});
+	const ctx = {
+		registry: options.registry,
+		cardStore,
+		onCardAction: handleCardAction,
+		plugins: options.plugins,
+		nodeRenderers: collectNodeRenderers(options.plugins, { debugTarget: renderer }),
+		sanitize: options.sanitize,
+		sanitized: true
+	};
 	const disposeAll = () => {
 		for (const entry of state.els.values()) disposeEl(entry.el);
 	};
+	const resetActionScope = () => {
+		actionScope.controller.abort();
+		actionScope = {
+			owner: {},
+			controller: new AbortController()
+		};
+	};
 	return {
-		push: (c) => renderer.push(c),
-		feed: (s) => renderer.feed(s),
+		debugSource: "renderer",
+		subscribeDebug: (listener) => renderer.subscribeDebug(listener),
+		push: (c) => {
+			if (!destroyed) renderer.push(c);
+		},
+		feed: (source, feedOptions) => destroyed ? Promise.resolve() : renderer.feed(source, feedOptions),
 		reset: () => {
-			disposeAll();
-			renderer.reset();
-			state.els.clear();
-			el.replaceChildren();
+			if (!destroyed) {
+				resetActionScope();
+				disposeAll();
+				renderer.reset();
+				state.els.clear();
+				el.replaceChildren();
+			}
 		},
 		destroy: () => {
-			disposeAll();
-			state.els.clear();
-			el.replaceChildren();
+			if (!destroyed) {
+				destroyed = true;
+				actionScope.controller.abort();
+				renderer.reset();
+				disposeAll();
+				state.els.clear();
+				el.replaceChildren();
+			}
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/vanilla",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Framework-free DOM adapter for AIGUI — stream LLM output straight into the DOM.",
   "keywords": [
     "llm",
@@ -22,14 +22,23 @@
   "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": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -41,10 +50,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-gui/core": "0.1.0"
+    "@ai-gui/core": "0.3.0"
   },
   "scripts": {
     "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project vanilla",
     "typecheck": "tsc --noEmit"
   }
 }