@ai-gui/react 0.2.0 → 0.4.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

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const react = __toESM(require("react"));
 const __ai_gui_core = __toESM(require("@ai-gui/core"));
+const react_dom = __toESM(require("react-dom"));
 const react_jsx_runtime = __toESM(require("react/jsx-runtime"));
 
 //#region src/apply-patches.ts
@@ -66,7 +67,9 @@ function useAIRenderer(options = {}) {
 		options.registry,
 		options.sanitize,
 		options.plugins,
-		options.scheduler
+		options.scheduler,
+		options.debug,
+		options.onDebugEvent
 	]);
 	(0, react.useEffect)(() => {
 		setNodes([]);
@@ -84,6 +87,7 @@ function useAIRenderer(options = {}) {
 		setNodes([]);
 	}, [session]);
 	return {
+		renderer: session.renderer,
 		nodes,
 		push,
 		feed,
@@ -91,40 +95,104 @@ 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, sanitize) {
+function renderOutput(out, key, sanitize, context) {
 	switch (out.kind) {
 		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), sanitize)));
+		}, (out.children ?? []).map((c, i) => renderOutput(c, String(i), sanitize, context)));
 		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) })
 		}, key);
-		case "mount": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MountHost, { mount: out.mount }, key);
+		case "mount": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MountHost, {
+			mount: out.mount,
+			context
+		}, key);
 	}
 }
 /** Host a framework-neutral imperative mount into a managed DOM element. */
-function MountHost({ mount }) {
+function MountHost({ mount, context }) {
 	const ref = (0, react.useRef)(null);
+	const [slots, setSlots] = (0, react.useState)([]);
 	(0, react.useEffect)(() => {
 		if (!ref.current) return;
-		const cleanup = mount(ref.current);
+		const mountContext = createMountContext(context, setSlots);
+		const cleanup = mount(ref.current, mountContext);
 		return () => {
 			if (typeof cleanup === "function") cleanup();
 		};
-	}, [mount]);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+	}, [
+		mount,
+		context?.registry,
+		context?.onCardAction
+	]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		ref,
 		"data-aigui-mount": true
-	});
+	}), slots.map((slot) => (0, react_dom.createPortal)((0, react.createElement)(slot.Comp, {
+		data: slot.data,
+		onAction: (action) => context?.onCardAction?.({
+			...action,
+			cardType: slot.type
+		})
+	}), slot.host, slot.id))] });
+}
+let nextCardSlotId = 0;
+function createMountContext(context, setSlots) {
+	return { mountCard(host, request) {
+		return mountCard(host, request, context, setSlots);
+	} };
+}
+function mountCard(host, request, context, setSlots) {
+	const Comp = context?.registry?.getRender(request.type);
+	if (!Comp) return void 0;
+	const id = String(nextCardSlotId++);
+	let destroyed = false;
+	setSlots((slots) => [...slots, {
+		id,
+		host,
+		type: request.type,
+		data: request.data,
+		Comp
+	}]);
+	return {
+		update(data) {
+			if (destroyed) return;
+			setSlots((slots) => slots.map((slot) => slot.id === id ? {
+				...slot,
+				data
+			} : slot));
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			setSlots((slots) => slots.filter((slot) => slot.id !== id));
+		}
+	};
 }
 /** Await an async RenderOutput, rendering a placeholder until it resolves. */
-function AsyncOutput({ promise, sanitize }) {
+function AsyncOutput({ promise, sanitize, context }) {
 	const [resolved, setResolved] = (0, react.useState)(null);
 	const [failed, setFailed] = (0, react.useState)(false);
 	(0, react.useEffect)(() => {
@@ -143,7 +211,7 @@ function AsyncOutput({ promise, sanitize }) {
 	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 });
 	try {
-		return renderOutput(resolved, void 0, sanitize);
+		return renderOutput(resolved, void 0, sanitize, context);
 	} catch {
 		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { "data-aigui-async-error": true });
 	}
@@ -157,15 +225,22 @@ function sanitizeOutput(html, sanitize) {
 //#region src/render-node.tsx
 function renderNode(node, ctx) {
 	const r = (ctx.nodeRenderers ?? (0, __ai_gui_core.collectNodeRenderers)(ctx.plugins))[node.type];
-	if (r) try {
-		const out = r(node);
-		if (out && typeof out.then === "function") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AsyncOutput, {
-			promise: out,
-			sanitize: ctx.sanitize
+	if (r) {
+		if (node.complete === false) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			"data-aigui-block-loading": "",
+			"data-block-type": node.type
 		}, node.key);
-		return renderOutput(out, node.key, ctx.sanitize);
-	} catch {
-		return renderFallback(node, ctx);
+		try {
+			const out = r(node);
+			if (out && typeof out.then === "function") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AsyncOutput, {
+				promise: out,
+				sanitize: ctx.sanitize,
+				context: ctx
+			}, node.key);
+			return renderOutput(out, node.key, ctx.sanitize, ctx);
+		} catch {
+			return renderFallback(node, ctx);
+		}
 	}
 	switch (node.type) {
 		case "heading": return (0, react.createElement)(node.tag ?? "h1", {
@@ -203,10 +278,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?.({
@@ -215,6 +295,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);
@@ -222,29 +345,71 @@ 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), [plugins]);
+	const nodeRenderers = (0, react.useMemo)(() => (0, __ai_gui_core.collectNodeRenderers)(plugins, { debugTarget: renderer }), [plugins, renderer]);
 	const ctx = {
 		registry,
+		cardStore,
 		plugins,
 		nodeRenderers,
-		onCardAction,
+		onCardAction: handleCardAction,
 		sanitize,
 		sanitized: true
 	};
@@ -260,4 +425,5 @@ 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,10 +1,11 @@
-import { AIGuiPlugin, ASTNode, CardRegistry, FeedOptions, FeedSource, NodeRenderer, 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: FeedSource, options?: FeedOptions) => Promise<void>;
@@ -12,46 +13,67 @@ interface UseAIRendererResult {
 }
 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[];
   nodeRenderers?: Record<string, NodeRenderer>;
-  onCardAction?: (action: {
-    type: string;
-    params?: unknown;
-    cardType: string;
-  }) => void;
+  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;
+  }) => void;
+}
 
 //#endregion
 //#region src/ai-renderer.d.ts
 interface AIRendererHandle {
+  readonly debugSource: "renderer";
+  subscribeDebug: (listener: DebugEventListener) => () => void;
   push: (chunk: string) => void;
   feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
 }
 interface AIRendererProps {
   registry?: CardRegistry;
+  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, sanitize?: RendererOptions["sanitize"]): ReactNode;
+declare function renderOutput(out: RenderOutput, key?: string, sanitize?: RendererOptions["sanitize"], context?: RenderContext): 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,10 +1,11 @@
 import * as react0 from "react";
 import * as react1 from "react";
 import { ReactNode } from "react";
-import { AIGuiPlugin, ASTNode, CardRegistry, FeedOptions, FeedSource, NodeRenderer, 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: FeedSource, options?: FeedOptions) => Promise<void>;
@@ -12,46 +13,67 @@ interface UseAIRendererResult {
 }
 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[];
   nodeRenderers?: Record<string, NodeRenderer>;
-  onCardAction?: (action: {
-    type: string;
-    params?: unknown;
-    cardType: string;
-  }) => void;
+  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;
+  }) => void;
+}
 
 //#endregion
 //#region src/ai-renderer.d.ts
 interface AIRendererHandle {
+  readonly debugSource: "renderer";
+  subscribeDebug: (listener: DebugEventListener) => () => void;
   push: (chunk: string) => void;
   feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
   reset: () => void;
 }
 interface AIRendererProps {
   registry?: CardRegistry;
+  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, sanitize?: RendererOptions["sanitize"]): ReactNode;
+declare function renderOutput(out: RenderOutput, key?: string, sanitize?: RendererOptions["sanitize"], context?: RenderContext): 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,6 +1,7 @@
-import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
-import { Renderer, collectNodeRenderers, sanitizeHtml } from "@ai-gui/core";
-import { jsx } from "react/jsx-runtime";
+import { Fragment, createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Renderer, collectNodeRenderers, getIdleActionState, sanitizeHtml } from "@ai-gui/core";
+import { createPortal } from "react-dom";
+import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/apply-patches.ts
 function applyPatches(nodes, patches) {
@@ -42,7 +43,9 @@ function useAIRenderer(options = {}) {
 		options.registry,
 		options.sanitize,
 		options.plugins,
-		options.scheduler
+		options.scheduler,
+		options.debug,
+		options.onDebugEvent
 	]);
 	useEffect(() => {
 		setNodes([]);
@@ -60,6 +63,7 @@ function useAIRenderer(options = {}) {
 		setNodes([]);
 	}, [session]);
 	return {
+		renderer: session.renderer,
 		nodes,
 		push,
 		feed,
@@ -67,40 +71,104 @@ 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, sanitize) {
+function renderOutput(out, key, sanitize, context) {
 	switch (out.kind) {
 		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), sanitize)));
+		}, (out.children ?? []).map((c, i) => renderOutput(c, String(i), sanitize, context)));
 		case "card": return /* @__PURE__ */ jsx("pre", {
 			"data-aigui-card-fallback": true,
 			children: /* @__PURE__ */ jsx("code", { children: JSON.stringify(out.data, null, 2) })
 		}, key);
-		case "mount": return /* @__PURE__ */ jsx(MountHost, { mount: out.mount }, key);
+		case "mount": return /* @__PURE__ */ jsx(MountHost, {
+			mount: out.mount,
+			context
+		}, key);
 	}
 }
 /** Host a framework-neutral imperative mount into a managed DOM element. */
-function MountHost({ mount }) {
+function MountHost({ mount, context }) {
 	const ref = useRef(null);
+	const [slots, setSlots] = useState([]);
 	useEffect(() => {
 		if (!ref.current) return;
-		const cleanup = mount(ref.current);
+		const mountContext = createMountContext(context, setSlots);
+		const cleanup = mount(ref.current, mountContext);
 		return () => {
 			if (typeof cleanup === "function") cleanup();
 		};
-	}, [mount]);
-	return /* @__PURE__ */ jsx("div", {
+	}, [
+		mount,
+		context?.registry,
+		context?.onCardAction
+	]);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
 		ref,
 		"data-aigui-mount": true
-	});
+	}), slots.map((slot) => createPortal(createElement(slot.Comp, {
+		data: slot.data,
+		onAction: (action) => context?.onCardAction?.({
+			...action,
+			cardType: slot.type
+		})
+	}), slot.host, slot.id))] });
+}
+let nextCardSlotId = 0;
+function createMountContext(context, setSlots) {
+	return { mountCard(host, request) {
+		return mountCard(host, request, context, setSlots);
+	} };
+}
+function mountCard(host, request, context, setSlots) {
+	const Comp = context?.registry?.getRender(request.type);
+	if (!Comp) return void 0;
+	const id = String(nextCardSlotId++);
+	let destroyed = false;
+	setSlots((slots) => [...slots, {
+		id,
+		host,
+		type: request.type,
+		data: request.data,
+		Comp
+	}]);
+	return {
+		update(data) {
+			if (destroyed) return;
+			setSlots((slots) => slots.map((slot) => slot.id === id ? {
+				...slot,
+				data
+			} : slot));
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			setSlots((slots) => slots.filter((slot) => slot.id !== id));
+		}
+	};
 }
 /** Await an async RenderOutput, rendering a placeholder until it resolves. */
-function AsyncOutput({ promise, sanitize }) {
+function AsyncOutput({ promise, sanitize, context }) {
 	const [resolved, setResolved] = useState(null);
 	const [failed, setFailed] = useState(false);
 	useEffect(() => {
@@ -119,7 +187,7 @@ function AsyncOutput({ promise, sanitize }) {
 	if (failed) return /* @__PURE__ */ jsx("span", { "data-aigui-async-error": true });
 	if (resolved === null) return /* @__PURE__ */ jsx("span", { "data-aigui-async-pending": true });
 	try {
-		return renderOutput(resolved, void 0, sanitize);
+		return renderOutput(resolved, void 0, sanitize, context);
 	} catch {
 		return /* @__PURE__ */ jsx("span", { "data-aigui-async-error": true });
 	}
@@ -133,15 +201,22 @@ function sanitizeOutput(html, sanitize) {
 //#region src/render-node.tsx
 function renderNode(node, ctx) {
 	const r = (ctx.nodeRenderers ?? collectNodeRenderers(ctx.plugins))[node.type];
-	if (r) try {
-		const out = r(node);
-		if (out && typeof out.then === "function") return /* @__PURE__ */ jsx(AsyncOutput, {
-			promise: out,
-			sanitize: ctx.sanitize
+	if (r) {
+		if (node.complete === false) return /* @__PURE__ */ jsx("div", {
+			"data-aigui-block-loading": "",
+			"data-block-type": node.type
 		}, node.key);
-		return renderOutput(out, node.key, ctx.sanitize);
-	} catch {
-		return renderFallback(node, ctx);
+		try {
+			const out = r(node);
+			if (out && typeof out.then === "function") return /* @__PURE__ */ jsx(AsyncOutput, {
+				promise: out,
+				sanitize: ctx.sanitize,
+				context: ctx
+			}, node.key);
+			return renderOutput(out, node.key, ctx.sanitize, ctx);
+		} catch {
+			return renderFallback(node, ctx);
+		}
 	}
 	switch (node.type) {
 		case "heading": return createElement(node.tag ?? "h1", {
@@ -179,10 +254,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?.({
@@ -191,6 +271,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);
@@ -198,29 +321,71 @@ 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), [plugins]);
+	const nodeRenderers = useMemo(() => collectNodeRenderers(plugins, { debugTarget: renderer }), [plugins, renderer]);
 	const ctx = {
 		registry,
+		cardStore,
 		plugins,
 		nodeRenderers,
-		onCardAction,
+		onCardAction: handleCardAction,
 		sanitize,
 		sanitized: true
 	};
@@ -232,4 +397,4 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 });
 
 //#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.2.0",
+  "version": "0.4.0",
   "description": "React adapter for AIGUI — stream LLM output into live React components with cards, plugins, and interactive widgets.",
   "keywords": [
     "llm",
@@ -50,10 +50,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-gui/core": "0.2.0"
+    "@ai-gui/core": "0.4.0"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "devDependencies": {
     "react": "^18.3.1",