@ai-gui/react 0.2.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

@@ -66,7 +66,9 @@ function useAIRenderer(options = {}) {
 		options.registry,
 		options.sanitize,
 		options.plugins,
-		options.scheduler
+		options.scheduler,
+		options.debug,
+		options.onDebugEvent
 	]);
 	(0, react.useEffect)(() => {
 		setNodes([]);
@@ -84,6 +86,7 @@ function useAIRenderer(options = {}) {
 		setNodes([]);
 	}, [session]);
 	return {
+		renderer: session.renderer,
 		nodes,
 		push,
 		feed,
@@ -91,6 +94,22 @@ 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. */
@@ -157,15 +176,21 @@ 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
+			}, 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", {
@@ -203,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?.({
@@ -215,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);
@@ -222,29 +295,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 +375,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,35 +13,56 @@ 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>>;
 
@@ -54,4 +76,4 @@ declare function renderOutput(out: RenderOutput, key?: string, sanitize?: Render
 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,35 +13,56 @@ 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>>;
 
@@ -54,4 +76,4 @@ declare function renderOutput(out: RenderOutput, key?: string, sanitize?: Render
 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,5 +1,5 @@
-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
@@ -42,7 +42,9 @@ function useAIRenderer(options = {}) {
 		options.registry,
 		options.sanitize,
 		options.plugins,
-		options.scheduler
+		options.scheduler,
+		options.debug,
+		options.onDebugEvent
 	]);
 	useEffect(() => {
 		setNodes([]);
@@ -60,6 +62,7 @@ function useAIRenderer(options = {}) {
 		setNodes([]);
 	}, [session]);
 	return {
+		renderer: session.renderer,
 		nodes,
 		push,
 		feed,
@@ -67,6 +70,22 @@ 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. */
@@ -133,15 +152,21 @@ 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
+			}, node.key);
+			return renderOutput(out, node.key, ctx.sanitize);
+		} catch {
+			return renderFallback(node, ctx);
+		}
 	}
 	switch (node.type) {
 		case "heading": return createElement(node.tag ?? "h1", {
@@ -179,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?.({
@@ -191,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);
@@ -198,29 +271,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 +347,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.3.0",
   "description": "React adapter for AIGUI — stream LLM output into live React components with cards, plugins, and interactive widgets.",
   "keywords": [
     "llm",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-gui/core": "0.2.0"
+    "@ai-gui/core": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18"