@ai-gui/react 0.1.0 → 0.3.0

package/README.md

@@ -11,8 +11,8 @@ pnpm add @ai-gui/core @ai-gui/react
 ## Usage
 
 ```tsx
-import { CardRegistry } from "@ai-gui/core"
-import { AIRenderer } from "@ai-gui/react"
+import { ActionRegistry, CardRegistry, CardStore, createActionRuntime } from "@ai-gui/core"
+import { AIRenderer, useActionState } from "@ai-gui/react"
 import { useRef } from "react"
 
 const registry = new CardRegistry()
@@ -28,6 +28,14 @@ registry.register({
   ),
 })
 
+const actions = new ActionRegistry()
+actions.register({
+  type: "refresh",
+  run: async (params, { signal }) => fetch("/api/weather", { signal }).then((r) => r.json()),
+})
+const cardStore = new CardStore({ registry })
+const actionRuntime = createActionRuntime({ registry: actions, cardStore })
+
 function Chat() {
   const ref = useRef<React.ComponentRef<typeof AIRenderer>>(null)
   // ref.current?.push(chunk) / feed(source) / reset()
@@ -35,7 +43,9 @@ function Chat() {
     <AIRenderer
       ref={ref}
       registry={registry}
-      onCardAction={({ type, params, cardType }) => {/* app makes the real request */}}
+      cardStore={cardStore}
+      actionRuntime={actionRuntime}
+      onCardAction={(action) => console.log("observed", action)}
     />
   )
 }
@@ -43,7 +53,10 @@ function Chat() {
 
 ## Exports
 
-- `<AIRenderer ref registry plugins sanitize onCardAction />` — imperative `ref.current.push/feed/reset`.
+- `<AIRenderer ref registry cardStore plugins sanitize actionRuntime onCardAction />` — imperative `ref.current.push/feed/reset`.
 - `useAIRenderer(options)` → `{ nodes, push, feed, reset }` — the hook form when you want to render `nodes` yourself.
+- `useActionState(runtime, key)` — subscribe to one action's `idle | pending | success | error | cancelled` state.
+
+Cards with a top-level `id` use the supplied `CardStore`. Their React component receives `{ data, state, onAction }`; patches update props while preserving component and DOM state.
 
 See the [root README](../../README.md) for cards, plugins, and `buildSystemPrompt`.

package/dist/index.cjs

@@ -26,26 +26,67 @@ const react = __toESM(require("react"));
 const __ai_gui_core = __toESM(require("@ai-gui/core"));
 const react_jsx_runtime = __toESM(require("react/jsx-runtime"));
 
+//#region src/apply-patches.ts
+function applyPatches(nodes, patches) {
+	let out = nodes.slice();
+	for (const p of patches) if (p.op === "insert") out.splice(p.index, 0, p.node);
+	else if (p.op === "update") {
+		const i = out.findIndex((n) => n.key === p.key);
+		if (i >= 0) out[i] = p.node;
+	} else if (p.op === "remove") out = out.filter((n) => n.key !== p.key);
+	else if (p.op === "move") {
+		const i = out.findIndex((n) => n.key === p.key);
+		if (i >= 0) {
+			const [node] = out.splice(i, 1);
+			out.splice(p.index, 0, node);
+		}
+	}
+	return out;
+}
+
+//#endregion
 //#region src/use-ai-renderer.ts
 function useAIRenderer(options = {}) {
 	const [nodes, setNodes] = (0, react.useState)([]);
-	const renderer = (0, react.useMemo)(() => {
-		return new __ai_gui_core.Renderer({
+	const active = (0, react.useRef)(null);
+	const session = (0, react.useMemo)(() => {
+		const token = {};
+		const renderer = new __ai_gui_core.Renderer({
 			...options,
-			onPatch: (_patches, nextNodes) => setNodes(nextNodes)
+			onPatch: (patches) => {
+				if (active.current === token) setNodes((current) => applyPatches(current, patches));
+			}
 		});
+		active.current = token;
+		return {
+			renderer,
+			token
+		};
 	}, [
 		options.registry,
 		options.sanitize,
-		options.plugins
+		options.plugins,
+		options.scheduler,
+		options.debug,
+		options.onDebugEvent
 	]);
-	const push = (0, react.useCallback)((chunk) => renderer.push(chunk), [renderer]);
-	const feed = (0, react.useCallback)((source) => renderer.feed(source), [renderer]);
+	(0, react.useEffect)(() => {
+		setNodes([]);
+		return () => {
+			session.renderer.reset();
+			if (active.current === session.token) active.current = null;
+		};
+	}, [session]);
+	const push = (0, react.useCallback)((chunk) => {
+		if (active.current === session.token) session.renderer.push(chunk);
+	}, [session]);
+	const feed = (0, react.useCallback)((source, feedOptions) => active.current === session.token ? session.renderer.feed(source, feedOptions) : Promise.resolve(), [session]);
 	const reset = (0, react.useCallback)(() => {
-		renderer.reset();
+		session.renderer.reset();
 		setNodes([]);
-	}, [renderer]);
+	}, [session]);
 	return {
+		renderer: session.renderer,
 		nodes,
 		push,
 		feed,
@@ -53,16 +94,32 @@ function useAIRenderer(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/use-action-state.ts
+function useActionState(runtime, key) {
+	const idle = (0, react.useMemo)(() => (0, __ai_gui_core.getIdleActionState)(key), [key]);
+	const subscribe = (0, react.useCallback)((notify) => runtime?.subscribe(() => notify()) ?? (() => {}), [runtime]);
+	const getSnapshot = (0, react.useCallback)(() => {
+		const state = runtime?.getState(key) ?? idle;
+		return state.status === "idle" ? idle : state;
+	}, [
+		idle,
+		key,
+		runtime
+	]);
+	return (0, react.useSyncExternalStore)(subscribe, getSnapshot, () => idle);
+}
+
 //#endregion
 //#region src/render-output.tsx
 /** Translate a framework-neutral RenderOutput into React nodes. */
-function renderOutput(out, key) {
+function renderOutput(out, key, sanitize) {
 	switch (out.kind) {
-		case "html": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: (0, __ai_gui_core.sanitizeHtml)(out.html) } }, key);
+		case "html": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: sanitizeOutput(out.html, sanitize) } }, key);
 		case "element": return (0, react.createElement)(out.tag, {
 			key,
 			...out.props
-		}, (out.children ?? []).map((c, i) => renderOutput(c, String(i))));
+		}, (out.children ?? []).map((c, i) => renderOutput(c, String(i), sanitize)));
 		case "card": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
 			"data-aigui-card-fallback": true,
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: JSON.stringify(out.data, null, 2) })
@@ -79,53 +136,85 @@ function MountHost({ mount }) {
 		return () => {
 			if (typeof cleanup === "function") cleanup();
 		};
-	}, []);
+	}, [mount]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		ref,
 		"data-aigui-mount": true
 	});
 }
 /** Await an async RenderOutput, rendering a placeholder until it resolves. */
-function AsyncOutput({ promise }) {
+function AsyncOutput({ promise, sanitize }) {
 	const [resolved, setResolved] = (0, react.useState)(null);
+	const [failed, setFailed] = (0, react.useState)(false);
 	(0, react.useEffect)(() => {
 		let cancelled = false;
+		setResolved(null);
+		setFailed(false);
 		promise.then((out) => {
 			if (!cancelled) setResolved(out);
+		}, () => {
+			if (!cancelled) setFailed(true);
 		});
 		return () => {
 			cancelled = true;
 		};
 	}, [promise]);
+	if (failed) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { "data-aigui-async-error": true });
 	if (resolved === null) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { "data-aigui-async-pending": true });
-	return renderOutput(resolved);
+	try {
+		return renderOutput(resolved, void 0, sanitize);
+	} catch {
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { "data-aigui-async-error": true });
+	}
+}
+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.tsx
 function renderNode(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 (out && typeof out.then === "function") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AsyncOutput, { promise: out }, node.key);
-		return renderOutput(out, node.key);
+		if (node.complete === false) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			"data-aigui-block-loading": "",
+			"data-block-type": node.type
+		}, node.key);
+		try {
+			const out = r(node);
+			if (out && typeof out.then === "function") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AsyncOutput, {
+				promise: out,
+				sanitize: ctx.sanitize
+			}, node.key);
+			return renderOutput(out, node.key, ctx.sanitize);
+		} catch {
+			return renderFallback(node, ctx);
+		}
 	}
 	switch (node.type) {
 		case "heading": return (0, react.createElement)(node.tag ?? "h1", {
 			key: node.key,
-			dangerouslySetInnerHTML: { __html: node.html ?? "" }
+			dangerouslySetInnerHTML: { __html: renderHtml(node.html ?? "", ctx) }
 		});
-		case "paragraph": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { dangerouslySetInnerHTML: { __html: node.html ?? "" } }, node.key);
+		case "paragraph": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { dangerouslySetInnerHTML: { __html: renderHtml(node.html ?? "", ctx) } }, node.key);
 		case "code": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
 			"data-lang": node.attrs?.lang,
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: node.content })
 		}, node.key);
 		case "hr": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("hr", {}, node.key);
-		case "html": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: node.content ?? "" } }, node.key);
+		case "html": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: renderHtml(node.content ?? "", ctx) } }, node.key);
 		case "card": return renderCard(node, ctx);
-		default: return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: node.html ?? (0, __ai_gui_core.sanitizeHtml)(node.content ?? "") } }, node.key);
+		default: return renderFallback(node, ctx);
 	}
 }
+function renderFallback(node, ctx) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: renderHtml(node.html ?? node.content ?? "", ctx) } }, node.key);
+}
+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 renderCard(node, ctx) {
 	const card = node.card;
 	if (!card) return null;
@@ -139,10 +228,15 @@ function renderCard(node, ctx) {
 		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: JSON.stringify(card.data, null, 2) })
 	}, node.key);
 	const Comp = getCardComponent(ctx.registry, card.type);
-	if (!Comp) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
-		"data-aigui-card-fallback": true,
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: JSON.stringify(card.data, null, 2) })
+	if (card.id && ctx.cardStore) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(StatefulCardHost, {
+		cardStore: ctx.cardStore,
+		cardId: card.id,
+		cardType: card.type,
+		initialData: card.data,
+		Comp,
+		onCardAction: ctx.onCardAction
 	}, node.key);
+	if (!Comp) return renderCardFallback(node.key, card.data);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Comp, {
 		data: card.data,
 		onAction: (a) => ctx.onCardAction?.({
@@ -151,6 +245,49 @@ function renderCard(node, ctx) {
 		})
 	}, node.key);
 }
+const getServerCardSnapshot = () => void 0;
+function StatefulCardHost({ cardStore, cardId, cardType, initialData, Comp, onCardAction }) {
+	const subscribe = (0, react.useCallback)((notify) => cardStore.subscribe(cardId, notify), [cardStore, cardId]);
+	const getSnapshot = (0, react.useCallback)(() => cardStore.get(cardId), [cardStore, cardId]);
+	const record = (0, react.useSyncExternalStore)(subscribe, getSnapshot, getServerCardSnapshot);
+	(0, react.useEffect)(() => {
+		if (cardStore.get(cardId)) return;
+		try {
+			cardStore.register({
+				id: cardId,
+				type: cardType,
+				data: initialData
+			});
+		} catch {}
+	}, [
+		cardStore,
+		cardId,
+		cardType,
+		initialData
+	]);
+	if (!record) return renderCardFallback(void 0, initialData);
+	if (record.type !== cardType) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+		"data-aigui-card-invalid": true,
+		"data-card-type": cardType,
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: JSON.stringify(initialData, null, 2) })
+	});
+	if (!Comp) return renderCardFallback(void 0, record.data);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Comp, {
+		data: record.data,
+		state: record.action,
+		onAction: (action) => onCardAction?.({
+			...action,
+			cardType,
+			cardId
+		})
+	});
+}
+function renderCardFallback(key, data) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+		"data-aigui-card-fallback": true,
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: JSON.stringify(data, null, 2) })
+	}, key);
+}
 function getCardComponent(registry, type) {
 	if (!registry) return void 0;
 	return registry.getRender(type);
@@ -158,27 +295,73 @@ function getCardComponent(registry, type) {
 
 //#endregion
 //#region src/ai-renderer.tsx
+function createActionScope() {
+	return {
+		controller: new AbortController(),
+		owner: {}
+	};
+}
 const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
-	const { registry, sanitize, plugins, onCardAction, className } = props;
+	const { registry, cardStore, sanitize, plugins, actionRuntime, onCardAction, className, debug, onDebugEvent } = props;
 	const opts = {
 		registry,
 		sanitize,
-		plugins
+		plugins,
+		debug,
+		onDebugEvent
 	};
-	const { nodes, push, feed, reset } = useAIRenderer(opts);
+	const { renderer, nodes, push, feed, reset: resetRenderer } = useAIRenderer(opts);
+	const actionScope = (0, react.useRef)(createActionScope());
+	(0, react.useEffect)(() => () => {
+		actionScope.current.controller.abort();
+		actionScope.current = createActionScope();
+	}, [
+		actionRuntime,
+		registry,
+		sanitize,
+		plugins
+	]);
+	const reset = (0, react.useCallback)(() => {
+		actionScope.current.controller.abort();
+		actionScope.current = createActionScope();
+		resetRenderer();
+	}, [resetRenderer]);
+	const handleCardAction = (0, react.useCallback)((action) => {
+		if (actionRuntime) {
+			const scope = actionScope.current;
+			actionRuntime.dispatch({
+				type: action.type,
+				params: action.params,
+				cardType: action.cardType,
+				cardId: action.cardId
+			}, {
+				signal: scope.controller.signal,
+				owner: scope.owner
+			}).catch(() => {});
+		}
+		onCardAction?.(action);
+	}, [actionRuntime, onCardAction]);
 	(0, react.useImperativeHandle)(ref, () => ({
+		debugSource: "renderer",
+		subscribeDebug: (listener) => renderer.subscribeDebug(listener),
 		push,
 		feed,
 		reset
 	}), [
+		renderer,
 		push,
 		feed,
 		reset
 	]);
+	const nodeRenderers = (0, react.useMemo)(() => (0, __ai_gui_core.collectNodeRenderers)(plugins, { debugTarget: renderer }), [plugins, renderer]);
 	const ctx = {
 		registry,
+		cardStore,
 		plugins,
-		onCardAction
+		nodeRenderers,
+		onCardAction: handleCardAction,
+		sanitize,
+		sanitized: true
 	};
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		className,
@@ -187,21 +370,10 @@ const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
 	});
 });
 
-//#endregion
-//#region src/apply-patches.ts
-function applyPatches(nodes, patches) {
-	let out = nodes.slice();
-	for (const p of patches) if (p.op === "insert") out.splice(p.index, 0, p.node);
-	else if (p.op === "update") {
-		const i = out.findIndex((n) => n.key === p.key);
-		if (i >= 0) out[i] = p.node;
-	} else if (p.op === "remove") out = out.filter((n) => n.key !== p.key);
-	return out;
-}
-
 //#endregion
 exports.AIRenderer = AIRenderer
 exports.applyPatches = applyPatches
 exports.renderNode = renderNode
 exports.renderOutput = renderOutput
-exports.useAIRenderer = useAIRenderer
+exports.useAIRenderer = useAIRenderer
+exports.useActionState = useActionState

package/dist/index.d.cts

@@ -1,54 +1,79 @@
-import { AIGuiPlugin, ASTNode, CardRegistry, Patch, RenderOutput, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, ActionState, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, Patch, RenderOutput, Renderer, RendererOptions } from "@ai-gui/core";
 import * as react0 from "react";
 import * as react1 from "react";
 import { ReactNode } from "react";
 
 //#region src/use-ai-renderer.d.ts
 interface UseAIRendererResult {
+  renderer: Renderer;
   nodes: ASTNode[];
   push: (chunk: string) => void;
-  feed: (source: AsyncIterable<string> | ReadableStream) => Promise<void>;
+  feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
 }
 declare function useAIRenderer(options?: Omit<RendererOptions, "onPatch">): UseAIRendererResult;
 
+//#endregion
+//#region src/use-action-state.d.ts
+declare function useActionState(runtime: ActionRuntime | undefined, key: string): ActionState;
+
 //#endregion
 //#region src/render-node.d.ts
+interface CardActionPayload {
+  type: string;
+  params?: unknown;
+  cardType: string;
+  cardId?: string;
+}
 interface RenderContext {
   registry?: CardRegistry;
+  cardStore?: CardStore;
   plugins?: AIGuiPlugin[];
-  onCardAction?: (action: {
+  nodeRenderers?: Record<string, NodeRenderer>;
+  onCardAction?: (action: CardActionPayload) => void;
+  sanitize?: RendererOptions["sanitize"];
+  sanitized?: boolean;
+}
+declare function renderNode(node: ASTNode, ctx: RenderContext): ReactNode;
+interface CardComponentProps {
+  data: unknown;
+  state?: CardAction;
+  onAction: (a: {
     type: string;
     params?: unknown;
-    cardType: string;
   }) => void;
 }
-declare function renderNode(node: ASTNode, ctx: RenderContext): ReactNode;
 
 //#endregion
 //#region src/ai-renderer.d.ts
 interface AIRendererHandle {
+  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;
 }
 interface AIRendererProps {
   registry?: CardRegistry;
-  sanitize?: boolean;
+  cardStore?: CardStore;
+  sanitize?: RendererOptions["sanitize"];
   plugins?: AIGuiPlugin[];
+  actionRuntime?: ActionRuntime;
   onCardAction?: RenderContext["onCardAction"];
   className?: string;
+  debug?: RendererOptions["debug"];
+  onDebugEvent?: RendererOptions["onDebugEvent"];
 }
 declare const AIRenderer: react1.ForwardRefExoticComponent<AIRendererProps & react0.RefAttributes<AIRendererHandle>>;
 
 //#endregion
 //#region src/render-output.d.ts
 /** Translate a framework-neutral RenderOutput into React nodes. */
-declare function renderOutput(out: RenderOutput, key?: string): ReactNode;
+declare function renderOutput(out: RenderOutput, key?: string, sanitize?: RendererOptions["sanitize"]): ReactNode;
 
 //#endregion
 //#region src/apply-patches.d.ts
 declare function applyPatches(nodes: ASTNode[], patches: Patch[]): ASTNode[];
 
 //#endregion
-export { AIRenderer, AIRendererHandle, AIRendererProps, RenderContext, UseAIRendererResult, applyPatches, renderNode, renderOutput, useAIRenderer };
+export { AIRenderer, AIRendererHandle, AIRendererProps, CardActionPayload, CardComponentProps, RenderContext, UseAIRendererResult, applyPatches, renderNode, renderOutput, useAIRenderer, useActionState };

package/dist/index.d.ts

@@ -1,54 +1,79 @@
 import * as react0 from "react";
 import * as react1 from "react";
 import { ReactNode } from "react";
-import { AIGuiPlugin, ASTNode, CardRegistry, Patch, RenderOutput, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, ActionState, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, Patch, RenderOutput, Renderer, RendererOptions } from "@ai-gui/core";
 
 //#region src/use-ai-renderer.d.ts
 interface UseAIRendererResult {
+  renderer: Renderer;
   nodes: ASTNode[];
   push: (chunk: string) => void;
-  feed: (source: AsyncIterable<string> | ReadableStream) => Promise<void>;
+  feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
 }
 declare function useAIRenderer(options?: Omit<RendererOptions, "onPatch">): UseAIRendererResult;
 
+//#endregion
+//#region src/use-action-state.d.ts
+declare function useActionState(runtime: ActionRuntime | undefined, key: string): ActionState;
+
 //#endregion
 //#region src/render-node.d.ts
+interface CardActionPayload {
+  type: string;
+  params?: unknown;
+  cardType: string;
+  cardId?: string;
+}
 interface RenderContext {
   registry?: CardRegistry;
+  cardStore?: CardStore;
   plugins?: AIGuiPlugin[];
-  onCardAction?: (action: {
+  nodeRenderers?: Record<string, NodeRenderer>;
+  onCardAction?: (action: CardActionPayload) => void;
+  sanitize?: RendererOptions["sanitize"];
+  sanitized?: boolean;
+}
+declare function renderNode(node: ASTNode, ctx: RenderContext): ReactNode;
+interface CardComponentProps {
+  data: unknown;
+  state?: CardAction;
+  onAction: (a: {
     type: string;
     params?: unknown;
-    cardType: string;
   }) => void;
 }
-declare function renderNode(node: ASTNode, ctx: RenderContext): ReactNode;
 
 //#endregion
 //#region src/ai-renderer.d.ts
 interface AIRendererHandle {
+  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;
 }
 interface AIRendererProps {
   registry?: CardRegistry;
-  sanitize?: boolean;
+  cardStore?: CardStore;
+  sanitize?: RendererOptions["sanitize"];
   plugins?: AIGuiPlugin[];
+  actionRuntime?: ActionRuntime;
   onCardAction?: RenderContext["onCardAction"];
   className?: string;
+  debug?: RendererOptions["debug"];
+  onDebugEvent?: RendererOptions["onDebugEvent"];
 }
 declare const AIRenderer: react1.ForwardRefExoticComponent<AIRendererProps & react0.RefAttributes<AIRendererHandle>>;
 
 //#endregion
 //#region src/render-output.d.ts
 /** Translate a framework-neutral RenderOutput into React nodes. */
-declare function renderOutput(out: RenderOutput, key?: string): ReactNode;
+declare function renderOutput(out: RenderOutput, key?: string, sanitize?: RendererOptions["sanitize"]): ReactNode;
 
 //#endregion
 //#region src/apply-patches.d.ts
 declare function applyPatches(nodes: ASTNode[], patches: Patch[]): ASTNode[];
 
 //#endregion
-export { AIRenderer, AIRendererHandle, AIRendererProps, RenderContext, UseAIRendererResult, applyPatches, renderNode, renderOutput, useAIRenderer };
+export { AIRenderer, AIRendererHandle, AIRendererProps, CardActionPayload, CardComponentProps, RenderContext, UseAIRendererResult, applyPatches, renderNode, renderOutput, useAIRenderer, useActionState };

package/dist/index.js

@@ -1,27 +1,68 @@
-import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
-import { Renderer, collectNodeRenderers, sanitizeHtml } from "@ai-gui/core";
+import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Renderer, collectNodeRenderers, getIdleActionState, sanitizeHtml } from "@ai-gui/core";
 import { jsx } from "react/jsx-runtime";
 
+//#region src/apply-patches.ts
+function applyPatches(nodes, patches) {
+	let out = nodes.slice();
+	for (const p of patches) if (p.op === "insert") out.splice(p.index, 0, p.node);
+	else if (p.op === "update") {
+		const i = out.findIndex((n) => n.key === p.key);
+		if (i >= 0) out[i] = p.node;
+	} else if (p.op === "remove") out = out.filter((n) => n.key !== p.key);
+	else if (p.op === "move") {
+		const i = out.findIndex((n) => n.key === p.key);
+		if (i >= 0) {
+			const [node] = out.splice(i, 1);
+			out.splice(p.index, 0, node);
+		}
+	}
+	return out;
+}
+
+//#endregion
 //#region src/use-ai-renderer.ts
 function useAIRenderer(options = {}) {
 	const [nodes, setNodes] = useState([]);
-	const renderer = useMemo(() => {
-		return new Renderer({
+	const active = useRef(null);
+	const session = useMemo(() => {
+		const token = {};
+		const renderer = new Renderer({
 			...options,
-			onPatch: (_patches, nextNodes) => setNodes(nextNodes)
+			onPatch: (patches) => {
+				if (active.current === token) setNodes((current) => applyPatches(current, patches));
+			}
 		});
+		active.current = token;
+		return {
+			renderer,
+			token
+		};
 	}, [
 		options.registry,
 		options.sanitize,
-		options.plugins
+		options.plugins,
+		options.scheduler,
+		options.debug,
+		options.onDebugEvent
 	]);
-	const push = useCallback((chunk) => renderer.push(chunk), [renderer]);
-	const feed = useCallback((source) => renderer.feed(source), [renderer]);
+	useEffect(() => {
+		setNodes([]);
+		return () => {
+			session.renderer.reset();
+			if (active.current === session.token) active.current = null;
+		};
+	}, [session]);
+	const push = useCallback((chunk) => {
+		if (active.current === session.token) session.renderer.push(chunk);
+	}, [session]);
+	const feed = useCallback((source, feedOptions) => active.current === session.token ? session.renderer.feed(source, feedOptions) : Promise.resolve(), [session]);
 	const reset = useCallback(() => {
-		renderer.reset();
+		session.renderer.reset();
 		setNodes([]);
-	}, [renderer]);
+	}, [session]);
 	return {
+		renderer: session.renderer,
 		nodes,
 		push,
 		feed,
@@ -29,16 +70,32 @@ function useAIRenderer(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/use-action-state.ts
+function useActionState(runtime, key) {
+	const idle = useMemo(() => getIdleActionState(key), [key]);
+	const subscribe = useCallback((notify) => runtime?.subscribe(() => notify()) ?? (() => {}), [runtime]);
+	const getSnapshot = useCallback(() => {
+		const state = runtime?.getState(key) ?? idle;
+		return state.status === "idle" ? idle : state;
+	}, [
+		idle,
+		key,
+		runtime
+	]);
+	return useSyncExternalStore(subscribe, getSnapshot, () => idle);
+}
+
 //#endregion
 //#region src/render-output.tsx
 /** Translate a framework-neutral RenderOutput into React nodes. */
-function renderOutput(out, key) {
+function renderOutput(out, key, sanitize) {
 	switch (out.kind) {
-		case "html": return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: sanitizeHtml(out.html) } }, key);
+		case "html": return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: sanitizeOutput(out.html, sanitize) } }, key);
 		case "element": return createElement(out.tag, {
 			key,
 			...out.props
-		}, (out.children ?? []).map((c, i) => renderOutput(c, String(i))));
+		}, (out.children ?? []).map((c, i) => renderOutput(c, String(i), sanitize)));
 		case "card": return /* @__PURE__ */ jsx("pre", {
 			"data-aigui-card-fallback": true,
 			children: /* @__PURE__ */ jsx("code", { children: JSON.stringify(out.data, null, 2) })
@@ -55,53 +112,85 @@ function MountHost({ mount }) {
 		return () => {
 			if (typeof cleanup === "function") cleanup();
 		};
-	}, []);
+	}, [mount]);
 	return /* @__PURE__ */ jsx("div", {
 		ref,
 		"data-aigui-mount": true
 	});
 }
 /** Await an async RenderOutput, rendering a placeholder until it resolves. */
-function AsyncOutput({ promise }) {
+function AsyncOutput({ promise, sanitize }) {
 	const [resolved, setResolved] = useState(null);
+	const [failed, setFailed] = useState(false);
 	useEffect(() => {
 		let cancelled = false;
+		setResolved(null);
+		setFailed(false);
 		promise.then((out) => {
 			if (!cancelled) setResolved(out);
+		}, () => {
+			if (!cancelled) setFailed(true);
 		});
 		return () => {
 			cancelled = true;
 		};
 	}, [promise]);
+	if (failed) return /* @__PURE__ */ jsx("span", { "data-aigui-async-error": true });
 	if (resolved === null) return /* @__PURE__ */ jsx("span", { "data-aigui-async-pending": true });
-	return renderOutput(resolved);
+	try {
+		return renderOutput(resolved, void 0, sanitize);
+	} catch {
+		return /* @__PURE__ */ jsx("span", { "data-aigui-async-error": true });
+	}
+}
+function sanitizeOutput(html, sanitize) {
+	if (sanitize === false) return html;
+	return sanitizeHtml(html, typeof sanitize === "object" ? sanitize : void 0);
 }
 
 //#endregion
 //#region src/render-node.tsx
 function renderNode(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 (out && typeof out.then === "function") return /* @__PURE__ */ jsx(AsyncOutput, { promise: out }, node.key);
-		return renderOutput(out, node.key);
+		if (node.complete === false) return /* @__PURE__ */ jsx("div", {
+			"data-aigui-block-loading": "",
+			"data-block-type": node.type
+		}, node.key);
+		try {
+			const out = r(node);
+			if (out && typeof out.then === "function") return /* @__PURE__ */ jsx(AsyncOutput, {
+				promise: out,
+				sanitize: ctx.sanitize
+			}, node.key);
+			return renderOutput(out, node.key, ctx.sanitize);
+		} catch {
+			return renderFallback(node, ctx);
+		}
 	}
 	switch (node.type) {
 		case "heading": return createElement(node.tag ?? "h1", {
 			key: node.key,
-			dangerouslySetInnerHTML: { __html: node.html ?? "" }
+			dangerouslySetInnerHTML: { __html: renderHtml(node.html ?? "", ctx) }
 		});
-		case "paragraph": return /* @__PURE__ */ jsx("p", { dangerouslySetInnerHTML: { __html: node.html ?? "" } }, node.key);
+		case "paragraph": return /* @__PURE__ */ jsx("p", { dangerouslySetInnerHTML: { __html: renderHtml(node.html ?? "", ctx) } }, node.key);
 		case "code": return /* @__PURE__ */ jsx("pre", {
 			"data-lang": node.attrs?.lang,
 			children: /* @__PURE__ */ jsx("code", { children: node.content })
 		}, node.key);
 		case "hr": return /* @__PURE__ */ jsx("hr", {}, node.key);
-		case "html": return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: node.content ?? "" } }, node.key);
+		case "html": return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: renderHtml(node.content ?? "", ctx) } }, node.key);
 		case "card": return renderCard(node, ctx);
-		default: return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: node.html ?? sanitizeHtml(node.content ?? "") } }, node.key);
+		default: return renderFallback(node, ctx);
 	}
 }
+function renderFallback(node, ctx) {
+	return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: renderHtml(node.html ?? node.content ?? "", ctx) } }, node.key);
+}
+function renderHtml(html, ctx) {
+	if (ctx.sanitized || ctx.sanitize === false) return html;
+	return sanitizeHtml(html, typeof ctx.sanitize === "object" ? ctx.sanitize : void 0);
+}
 function renderCard(node, ctx) {
 	const card = node.card;
 	if (!card) return null;
@@ -115,10 +204,15 @@ function renderCard(node, ctx) {
 		children: /* @__PURE__ */ jsx("code", { children: JSON.stringify(card.data, null, 2) })
 	}, node.key);
 	const Comp = getCardComponent(ctx.registry, card.type);
-	if (!Comp) return /* @__PURE__ */ jsx("pre", {
-		"data-aigui-card-fallback": true,
-		children: /* @__PURE__ */ jsx("code", { children: JSON.stringify(card.data, null, 2) })
+	if (card.id && ctx.cardStore) return /* @__PURE__ */ jsx(StatefulCardHost, {
+		cardStore: ctx.cardStore,
+		cardId: card.id,
+		cardType: card.type,
+		initialData: card.data,
+		Comp,
+		onCardAction: ctx.onCardAction
 	}, node.key);
+	if (!Comp) return renderCardFallback(node.key, card.data);
 	return /* @__PURE__ */ jsx(Comp, {
 		data: card.data,
 		onAction: (a) => ctx.onCardAction?.({
@@ -127,6 +221,49 @@ function renderCard(node, ctx) {
 		})
 	}, node.key);
 }
+const getServerCardSnapshot = () => void 0;
+function StatefulCardHost({ cardStore, cardId, cardType, initialData, Comp, onCardAction }) {
+	const subscribe = useCallback((notify) => cardStore.subscribe(cardId, notify), [cardStore, cardId]);
+	const getSnapshot = useCallback(() => cardStore.get(cardId), [cardStore, cardId]);
+	const record = useSyncExternalStore(subscribe, getSnapshot, getServerCardSnapshot);
+	useEffect(() => {
+		if (cardStore.get(cardId)) return;
+		try {
+			cardStore.register({
+				id: cardId,
+				type: cardType,
+				data: initialData
+			});
+		} catch {}
+	}, [
+		cardStore,
+		cardId,
+		cardType,
+		initialData
+	]);
+	if (!record) return renderCardFallback(void 0, initialData);
+	if (record.type !== cardType) return /* @__PURE__ */ jsx("pre", {
+		"data-aigui-card-invalid": true,
+		"data-card-type": cardType,
+		children: /* @__PURE__ */ jsx("code", { children: JSON.stringify(initialData, null, 2) })
+	});
+	if (!Comp) return renderCardFallback(void 0, record.data);
+	return /* @__PURE__ */ jsx(Comp, {
+		data: record.data,
+		state: record.action,
+		onAction: (action) => onCardAction?.({
+			...action,
+			cardType,
+			cardId
+		})
+	});
+}
+function renderCardFallback(key, data) {
+	return /* @__PURE__ */ jsx("pre", {
+		"data-aigui-card-fallback": true,
+		children: /* @__PURE__ */ jsx("code", { children: JSON.stringify(data, null, 2) })
+	}, key);
+}
 function getCardComponent(registry, type) {
 	if (!registry) return void 0;
 	return registry.getRender(type);
@@ -134,27 +271,73 @@ function getCardComponent(registry, type) {
 
 //#endregion
 //#region src/ai-renderer.tsx
+function createActionScope() {
+	return {
+		controller: new AbortController(),
+		owner: {}
+	};
+}
 const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
-	const { registry, sanitize, plugins, onCardAction, className } = props;
+	const { registry, cardStore, sanitize, plugins, actionRuntime, onCardAction, className, debug, onDebugEvent } = props;
 	const opts = {
 		registry,
 		sanitize,
-		plugins
+		plugins,
+		debug,
+		onDebugEvent
 	};
-	const { nodes, push, feed, reset } = useAIRenderer(opts);
+	const { renderer, nodes, push, feed, reset: resetRenderer } = useAIRenderer(opts);
+	const actionScope = useRef(createActionScope());
+	useEffect(() => () => {
+		actionScope.current.controller.abort();
+		actionScope.current = createActionScope();
+	}, [
+		actionRuntime,
+		registry,
+		sanitize,
+		plugins
+	]);
+	const reset = useCallback(() => {
+		actionScope.current.controller.abort();
+		actionScope.current = createActionScope();
+		resetRenderer();
+	}, [resetRenderer]);
+	const handleCardAction = useCallback((action) => {
+		if (actionRuntime) {
+			const scope = actionScope.current;
+			actionRuntime.dispatch({
+				type: action.type,
+				params: action.params,
+				cardType: action.cardType,
+				cardId: action.cardId
+			}, {
+				signal: scope.controller.signal,
+				owner: scope.owner
+			}).catch(() => {});
+		}
+		onCardAction?.(action);
+	}, [actionRuntime, onCardAction]);
 	useImperativeHandle(ref, () => ({
+		debugSource: "renderer",
+		subscribeDebug: (listener) => renderer.subscribeDebug(listener),
 		push,
 		feed,
 		reset
 	}), [
+		renderer,
 		push,
 		feed,
 		reset
 	]);
+	const nodeRenderers = useMemo(() => collectNodeRenderers(plugins, { debugTarget: renderer }), [plugins, renderer]);
 	const ctx = {
 		registry,
+		cardStore,
 		plugins,
-		onCardAction
+		nodeRenderers,
+		onCardAction: handleCardAction,
+		sanitize,
+		sanitized: true
 	};
 	return /* @__PURE__ */ jsx("div", {
 		className,
@@ -164,16 +347,4 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 });
 
 //#endregion
-//#region src/apply-patches.ts
-function applyPatches(nodes, patches) {
-	let out = nodes.slice();
-	for (const p of patches) if (p.op === "insert") out.splice(p.index, 0, p.node);
-	else if (p.op === "update") {
-		const i = out.findIndex((n) => n.key === p.key);
-		if (i >= 0) out[i] = p.node;
-	} else if (p.op === "remove") out = out.filter((n) => n.key !== p.key);
-	return out;
-}
-
-//#endregion
-export { AIRenderer, applyPatches, renderNode, renderOutput, useAIRenderer };
+export { AIRenderer, applyPatches, renderNode, renderOutput, useAIRenderer, useActionState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/react",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "React adapter for AIGUI — stream LLM output into live React components with cards, plugins, and interactive widgets.",
   "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,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-gui/core": "0.1.0"
+    "@ai-gui/core": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -56,6 +65,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project react",
     "typecheck": "tsc --noEmit"
   }
 }