@ai-gui/vanilla 0.2.0 → 0.4.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,7 +26,7 @@ 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, sanitize) {
+function renderOutputToElement(out, sanitize, mountContext = {}) {
 	switch (out.kind) {
 		case "html": {
 			const el = document.createElement("div");
@@ -37,7 +37,7 @@ function renderOutputToElement(out, sanitize) {
 			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, sanitize));
+			for (const child of out.children ?? []) el.appendChild(renderOutputToElement(child, sanitize, mountContext));
 			return el;
 		}
 		case "card": {
@@ -53,7 +53,7 @@ function renderOutputToElement(out, sanitize) {
 			el.setAttribute("data-aigui-mount", "");
 			queueMicrotask(() => {
 				if (el.__aiguiDisposed) return;
-				const c = out.mount(el);
+				const c = out.mount(el, mountContext);
 				if (typeof c === "function") if (el.__aiguiDisposed) c();
 				else el.__aiguiCleanup = c;
 			});
@@ -70,25 +70,33 @@ function sanitizeOutput(html, sanitize) {
 //#region src/render-node-dom.ts
 function renderNodeToElement(node, ctx) {
 	const r = (ctx.nodeRenderers ?? (0, __ai_gui_core.collectNodeRenderers)(ctx.plugins))[node.type];
-	if (r) 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;
+	if (r) {
+		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, createRenderMountContext(ctx)));
+				}, () => {
+					if (host.__aiguiDisposed) return;
+					host.removeAttribute("data-aigui-async-pending");
+					host.setAttribute("data-aigui-async-error", "");
+				});
+				return host;
+			}
+			return renderOutputToElement(out, ctx.sanitize, createRenderMountContext(ctx));
+		} catch {
+			return renderFallback(node, ctx);
 		}
-		return renderOutputToElement(out, ctx.sanitize);
-	} catch {
-		return renderFallback(node, ctx);
 	}
 	switch (node.type) {
 		case "heading": {
@@ -146,22 +154,191 @@ 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 createRenderMountContext(ctx) {
+	return { mountCard(host, request) {
+		return mountCardSlot(host, request, ctx);
+	} };
+}
+function mountCardSlot(host, request, ctx) {
+	const factory = ctx.registry?.getRender(request.type);
+	if (!factory) return void 0;
+	return createVanillaCardSlot(host, request.data, factory, () => ({
+		state: { status: "idle" },
+		onAction: (action) => ctx.onCardAction?.({
+			...action,
+			cardType: request.type
+		})
+	}));
+}
+function createVanillaCardSlot(host, initialData, factory, context) {
+	let destroyed = false;
+	let instance;
+	let element;
+	const mount = (data) => {
+		const rendered = factory(data, context());
+		if (isVanillaCardInstance(rendered)) {
+			instance = rendered;
+			element = rendered.element;
+		} else {
+			instance = void 0;
+			element = rendered;
+		}
+		host.replaceChildren(element);
+	};
+	mount(initialData);
+	return {
+		element: () => element,
+		update(data) {
+			if (destroyed) return;
+			if (instance) instance.update(data, context());
+			else mount(data);
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			instance?.destroy?.();
+			instance = void 0;
+		}
+	};
+}
+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 slot;
+	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 mount = (nextData) => {
+		slot = createVanillaCardSlot(host, nextData, factory, () => ({
+			state,
+			onAction
+		}));
+	};
+	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");
+			const element = slot?.element();
+			if (element) host.replaceChildren(element);
+		}
+		if (slot) slot.update(data);
+		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 = () => {};
+			slot?.destroy();
+			slot = 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
@@ -239,7 +416,7 @@ 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 ?? node.content ?? "";
@@ -250,14 +427,20 @@ 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,
-		nodeRenderers: (0, __ai_gui_core.collectNodeRenderers)(options.plugins),
-		sanitize: options.sanitize,
-		sanitized: true
+	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;
@@ -267,16 +450,35 @@ function createRenderer(el, options = {}) {
 			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 {
+		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: () => {
 			if (!destroyed) {
+				resetActionScope();
 				disposeAll();
 				renderer.reset();
 				state.els.clear();
@@ -286,6 +488,7 @@ function createRenderer(el, options = {}) {
 		destroy: () => {
 			if (!destroyed) {
 				destroyed = true;
+				actionScope.controller.abort();
 				renderer.reset();
 				disposeAll();
 				state.els.clear();

package/dist/index.d.cts

@@ -1,12 +1,28 @@
-import { AIGuiPlugin, ASTNode, CardRegistry, FeedOptions, FeedSource, NodeRenderer, RenderOutput, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, RenderMountContext, 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>;
@@ -18,9 +34,13 @@ declare function renderNodeToElement(node: ASTNode, ctx: DomRenderContext): HTML
 //#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: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
@@ -31,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, sanitize?: RendererOptions["sanitize"]): HTMLElement;
+declare function renderOutputToElement(out: RenderOutput, sanitize?: RendererOptions["sanitize"], mountContext?: RenderMountContext): 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,12 +1,28 @@
-import { AIGuiPlugin, ASTNode, CardRegistry, FeedOptions, FeedSource, NodeRenderer, RenderOutput, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, RenderMountContext, 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>;
@@ -18,9 +34,13 @@ declare function renderNodeToElement(node: ASTNode, ctx: DomRenderContext): HTML
 //#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: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
@@ -31,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, sanitize?: RendererOptions["sanitize"]): HTMLElement;
+declare function renderOutputToElement(out: RenderOutput, sanitize?: RendererOptions["sanitize"], mountContext?: RenderMountContext): 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,7 +2,7 @@ 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, sanitize) {
+function renderOutputToElement(out, sanitize, mountContext = {}) {
 	switch (out.kind) {
 		case "html": {
 			const el = document.createElement("div");
@@ -13,7 +13,7 @@ function renderOutputToElement(out, sanitize) {
 			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, sanitize));
+			for (const child of out.children ?? []) el.appendChild(renderOutputToElement(child, sanitize, mountContext));
 			return el;
 		}
 		case "card": {
@@ -29,7 +29,7 @@ function renderOutputToElement(out, sanitize) {
 			el.setAttribute("data-aigui-mount", "");
 			queueMicrotask(() => {
 				if (el.__aiguiDisposed) return;
-				const c = out.mount(el);
+				const c = out.mount(el, mountContext);
 				if (typeof c === "function") if (el.__aiguiDisposed) c();
 				else el.__aiguiCleanup = c;
 			});
@@ -46,25 +46,33 @@ function sanitizeOutput(html, sanitize) {
 //#region src/render-node-dom.ts
 function renderNodeToElement(node, ctx) {
 	const r = (ctx.nodeRenderers ?? collectNodeRenderers(ctx.plugins))[node.type];
-	if (r) 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;
+	if (r) {
+		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, createRenderMountContext(ctx)));
+				}, () => {
+					if (host.__aiguiDisposed) return;
+					host.removeAttribute("data-aigui-async-pending");
+					host.setAttribute("data-aigui-async-error", "");
+				});
+				return host;
+			}
+			return renderOutputToElement(out, ctx.sanitize, createRenderMountContext(ctx));
+		} catch {
+			return renderFallback(node, ctx);
 		}
-		return renderOutputToElement(out, ctx.sanitize);
-	} catch {
-		return renderFallback(node, ctx);
 	}
 	switch (node.type) {
 		case "heading": {
@@ -122,22 +130,191 @@ 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 createRenderMountContext(ctx) {
+	return { mountCard(host, request) {
+		return mountCardSlot(host, request, ctx);
+	} };
+}
+function mountCardSlot(host, request, ctx) {
+	const factory = ctx.registry?.getRender(request.type);
+	if (!factory) return void 0;
+	return createVanillaCardSlot(host, request.data, factory, () => ({
+		state: { status: "idle" },
+		onAction: (action) => ctx.onCardAction?.({
+			...action,
+			cardType: request.type
+		})
+	}));
+}
+function createVanillaCardSlot(host, initialData, factory, context) {
+	let destroyed = false;
+	let instance;
+	let element;
+	const mount = (data) => {
+		const rendered = factory(data, context());
+		if (isVanillaCardInstance(rendered)) {
+			instance = rendered;
+			element = rendered.element;
+		} else {
+			instance = void 0;
+			element = rendered;
+		}
+		host.replaceChildren(element);
+	};
+	mount(initialData);
+	return {
+		element: () => element,
+		update(data) {
+			if (destroyed) return;
+			if (instance) instance.update(data, context());
+			else mount(data);
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			instance?.destroy?.();
+			instance = void 0;
+		}
+	};
+}
+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 slot;
+	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 mount = (nextData) => {
+		slot = createVanillaCardSlot(host, nextData, factory, () => ({
+			state,
+			onAction
+		}));
+	};
+	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");
+			const element = slot?.element();
+			if (element) host.replaceChildren(element);
+		}
+		if (slot) slot.update(data);
+		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 = () => {};
+			slot?.destroy();
+			slot = 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
@@ -215,7 +392,7 @@ 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 ?? node.content ?? "";
@@ -226,14 +403,20 @@ 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,
-		nodeRenderers: collectNodeRenderers(options.plugins),
-		sanitize: options.sanitize,
-		sanitized: true
+	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;
@@ -243,16 +426,35 @@ function createRenderer(el, options = {}) {
 			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 {
+		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: () => {
 			if (!destroyed) {
+				resetActionScope();
 				disposeAll();
 				renderer.reset();
 				state.els.clear();
@@ -262,6 +464,7 @@ function createRenderer(el, options = {}) {
 		destroy: () => {
 			if (!destroyed) {
 				destroyed = true;
+				actionScope.controller.abort();
 				renderer.reset();
 				disposeAll();
 				state.els.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/vanilla",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Framework-free DOM adapter for AIGUI — stream LLM output straight into the DOM.",
   "keywords": [
     "llm",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-gui/core": "0.2.0"
+    "@ai-gui/core": "0.4.0"
   },
   "scripts": {
     "build": "tsdown",