@ai-gui/react 0.4.4 → 0.6.0

package/dist/index.cjs

@@ -50,6 +50,7 @@ function applyPatches(nodes, patches) {
 function useAIRenderer(options = {}) {
 	const [nodes, setNodes] = (0, react.useState)([]);
 	const active = (0, react.useRef)(null);
+	const pluginList = useStableList(options.plugins);
 	const session = (0, react.useMemo)(() => {
 		const token = {};
 		const renderer = new __ai_gui_core.Renderer({
@@ -66,7 +67,7 @@ function useAIRenderer(options = {}) {
 	}, [
 		options.registry,
 		options.sanitize,
-		options.plugins,
+		pluginList,
 		options.scheduler,
 		options.debug,
 		options.onDebugEvent
@@ -95,6 +96,14 @@ function useAIRenderer(options = {}) {
 		reset
 	};
 }
+/** Keep the same array reference for as long as it holds the same members in the same order. */
+function useStableList(list) {
+	const held = (0, react.useRef)(list);
+	const current = held.current;
+	const same = list === current || !!list && !!current && list.length === current.length && list.every((item, index) => item === current[index]);
+	if (!same) held.current = list;
+	return held.current;
+}
 
 //#endregion
 //#region src/use-action-state.ts
@@ -117,7 +126,7 @@ function useActionState(runtime, key) {
 /** Translate a framework-neutral RenderOutput into React nodes. */
 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 "html": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { dangerouslySetInnerHTML: { __html: (0, __ai_gui_core.sanitizeRenderedHtml)(out.html, sanitize, out.trusted) } }, key);
 		case "element": return (0, react.createElement)(out.tag, {
 			key,
 			...out.props
@@ -217,10 +226,6 @@ function AsyncOutput({ promise, sanitize, context }) {
 		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
@@ -256,11 +261,13 @@ function renderNode(node, ctx) {
 function PluginOutputHost({ node, renderer, context }) {
 	const cache = (0, react.useRef)();
 	const signature = nodeSignature(node);
+	const theme = context.theme;
 	try {
-		if (!cache.current || cache.current.renderer !== renderer || cache.current.signature !== signature) cache.current = {
+		if (!cache.current || cache.current.renderer !== renderer || cache.current.signature !== signature || cache.current.theme !== theme) cache.current = {
 			renderer,
 			signature,
-			output: renderer(node)
+			theme,
+			output: renderer(node, { theme })
 		};
 		const output = cache.current.output;
 		if (output && typeof output.then === "function") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AsyncOutput, {
@@ -374,7 +381,7 @@ function createActionScope() {
 	};
 }
 const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
-	const { registry, cardStore, sanitize, plugins, actionRuntime, onCardAction, className, debug, onDebugEvent } = props;
+	const { text, registry, cardStore, sanitize, plugins, actionRuntime, onCardAction, onRender, theme, className, debug, onDebugEvent } = props;
 	const opts = {
 		registry,
 		sanitize,
@@ -384,6 +391,8 @@ const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
 	};
 	const { renderer, nodes, push, feed, reset: resetRenderer } = useAIRenderer(opts);
 	const actionScope = (0, react.useRef)(createActionScope());
+	const rendered = (0, react.useRef)("");
+	const root = (0, react.useRef)(null);
 	(0, react.useEffect)(() => () => {
 		actionScope.current.controller.abort();
 		actionScope.current = createActionScope();
@@ -396,8 +405,30 @@ const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
 	const reset = (0, react.useCallback)(() => {
 		actionScope.current.controller.abort();
 		actionScope.current = createActionScope();
+		rendered.current = "";
 		resetRenderer();
 	}, [resetRenderer]);
+	(0, react.useEffect)(() => {
+		if (text === void 0 || text === rendered.current) return;
+		if (text.startsWith(rendered.current)) push(text.slice(rendered.current.length));
+		else {
+			reset();
+			push(text);
+		}
+		rendered.current = text;
+	}, [
+		text,
+		push,
+		reset
+	]);
+	const onRenderRef = (0, react.useRef)(onRender);
+	onRenderRef.current = onRender;
+	(0, react.useEffect)(() => {
+		onRenderRef.current?.(nodes);
+	}, [nodes]);
+	(0, react.useEffect)(() => () => {
+		rendered.current = "";
+	}, [renderer]);
 	const handleCardAction = (0, react.useCallback)((action) => {
 		if (actionRuntime) {
 			const scope = actionScope.current;
@@ -413,16 +444,19 @@ const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
 		}
 		onCardAction?.(action);
 	}, [actionRuntime, onCardAction]);
+	const exportImages = (0, react.useCallback)((options) => root.current ? (0, __ai_gui_core.exportRenderedImages)(root.current, options) : Promise.resolve([]), []);
 	(0, react.useImperativeHandle)(ref, () => ({
 		debugSource: "renderer",
 		subscribeDebug: (listener) => renderer.subscribeDebug(listener),
 		push,
 		feed,
+		exportImages,
 		reset
 	}), [
 		renderer,
 		push,
 		feed,
+		exportImages,
 		reset
 	]);
 	const nodeRenderers = (0, react.useMemo)(() => (0, __ai_gui_core.collectNodeRenderers)(plugins, { debugTarget: renderer }), [plugins, renderer]);
@@ -433,11 +467,13 @@ const AIRenderer = (0, react.forwardRef)(function AIRenderer$1(props, ref) {
 		nodeRenderers,
 		onCardAction: handleCardAction,
 		sanitize,
-		sanitized: true
+		sanitized: true,
+		theme
 	};
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		className,
 		"data-aigui-renderer": true,
+		ref: root,
 		children: nodes.map((n) => renderNode(n, ctx))
 	});
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AIGuiPlugin, ASTNode, ActionRuntime, ActionState, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, Patch, RenderOutput, Renderer, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, ActionState, CardAction, CardRegistry, CardStore, DebugEventListener, ExportImageOptions, ExportedImage, 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";
@@ -33,6 +33,8 @@ interface RenderContext {
   onCardAction?: (action: CardActionPayload) => void;
   sanitize?: RendererOptions["sanitize"];
   sanitized?: boolean;
+  /** The host's colour scheme, handed to every plugin that renders a node. */
+  theme?: string;
 }
 declare function renderNode(node: ASTNode, ctx: RenderContext): ReactNode;
 interface CardComponentProps {
@@ -51,15 +53,46 @@ interface AIRendererHandle {
   subscribeDebug: (listener: DebugEventListener) => () => void;
   push: (chunk: string) => void;
   feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
+  /**
+   * Export every drawing currently rendered, as PNG data URLs.
+   *
+   * The element the drawings live in belongs to the renderer, so a host offering "save this chart"
+   * would otherwise have to wrap it in one of its own just to find them.
+   */
+  exportImages: (options?: ExportImageOptions) => Promise<ExportedImage[]>;
   reset: () => void;
 }
 interface AIRendererProps {
+  /**
+   * The whole text to render, as a controlled component.
+   *
+   * Streaming a model's answer means re-rendering with a longer string, and only the added part
+   * is new. Working that out is the renderer's job: pass the full text on every update and it
+   * pushes the delta, or starts over when the new text is not a continuation of what it holds.
+   * Leave it undefined to drive the renderer through the imperative handle instead.
+   */
+  text?: string;
   registry?: CardRegistry;
   cardStore?: CardStore;
   sanitize?: RendererOptions["sanitize"];
   plugins?: AIGuiPlugin[];
   actionRuntime?: ActionRuntime;
   onCardAction?: RenderContext["onCardAction"];
+  /**
+   * Called with the nodes currently on screen, whenever they change.
+   *
+   * What a model produced is only knowable from the parsed nodes: a host that wants to offer
+   * "export this chart" or count the diagrams in an answer would otherwise have to watch the DOM
+   * for the elements a plugin happened to create.
+   */
+  onRender?: (nodes: ASTNode[]) => void;
+  /**
+   * The host's colour scheme, "light" or "dark" by convention, handed to every plugin.
+   *
+   * Charts and diagrams choose their own colours and cannot see the page they sit on, so an
+   * answer rendered on a dark page comes back with white plot areas until the host says so.
+   */
+  theme?: string;
   className?: string;
   debug?: RendererOptions["debug"];
   onDebugEvent?: RendererOptions["onDebugEvent"];

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react0 from "react";
 import * as react1 from "react";
 import { ReactNode } from "react";
-import { AIGuiPlugin, ASTNode, ActionRuntime, ActionState, CardAction, CardRegistry, CardStore, DebugEventListener, FeedOptions, FeedSource, NodeRenderer, Patch, RenderOutput, Renderer, RendererOptions } from "@ai-gui/core";
+import { AIGuiPlugin, ASTNode, ActionRuntime, ActionState, CardAction, CardRegistry, CardStore, DebugEventListener, ExportImageOptions, ExportedImage, FeedOptions, FeedSource, NodeRenderer, Patch, RenderOutput, Renderer, RendererOptions } from "@ai-gui/core";
 
 //#region src/use-ai-renderer.d.ts
 interface UseAIRendererResult {
@@ -33,6 +33,8 @@ interface RenderContext {
   onCardAction?: (action: CardActionPayload) => void;
   sanitize?: RendererOptions["sanitize"];
   sanitized?: boolean;
+  /** The host's colour scheme, handed to every plugin that renders a node. */
+  theme?: string;
 }
 declare function renderNode(node: ASTNode, ctx: RenderContext): ReactNode;
 interface CardComponentProps {
@@ -51,15 +53,46 @@ interface AIRendererHandle {
   subscribeDebug: (listener: DebugEventListener) => () => void;
   push: (chunk: string) => void;
   feed: (source: FeedSource, options?: FeedOptions) => Promise<void>;
+  /**
+   * Export every drawing currently rendered, as PNG data URLs.
+   *
+   * The element the drawings live in belongs to the renderer, so a host offering "save this chart"
+   * would otherwise have to wrap it in one of its own just to find them.
+   */
+  exportImages: (options?: ExportImageOptions) => Promise<ExportedImage[]>;
   reset: () => void;
 }
 interface AIRendererProps {
+  /**
+   * The whole text to render, as a controlled component.
+   *
+   * Streaming a model's answer means re-rendering with a longer string, and only the added part
+   * is new. Working that out is the renderer's job: pass the full text on every update and it
+   * pushes the delta, or starts over when the new text is not a continuation of what it holds.
+   * Leave it undefined to drive the renderer through the imperative handle instead.
+   */
+  text?: string;
   registry?: CardRegistry;
   cardStore?: CardStore;
   sanitize?: RendererOptions["sanitize"];
   plugins?: AIGuiPlugin[];
   actionRuntime?: ActionRuntime;
   onCardAction?: RenderContext["onCardAction"];
+  /**
+   * Called with the nodes currently on screen, whenever they change.
+   *
+   * What a model produced is only knowable from the parsed nodes: a host that wants to offer
+   * "export this chart" or count the diagrams in an answer would otherwise have to watch the DOM
+   * for the elements a plugin happened to create.
+   */
+  onRender?: (nodes: ASTNode[]) => void;
+  /**
+   * The host's colour scheme, "light" or "dark" by convention, handed to every plugin.
+   *
+   * Charts and diagrams choose their own colours and cannot see the page they sit on, so an
+   * answer rendered on a dark page comes back with white plot areas until the host says so.
+   */
+  theme?: string;
   className?: string;
   debug?: RendererOptions["debug"];
   onDebugEvent?: RendererOptions["onDebugEvent"];

package/dist/index.js

@@ -1,5 +1,5 @@
 import { Fragment, createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { Renderer, collectNodeRenderers, getIdleActionState, sanitizeHtml } from "@ai-gui/core";
+import { Renderer, collectNodeRenderers, exportRenderedImages, getIdleActionState, sanitizeHtml, sanitizeRenderedHtml } from "@ai-gui/core";
 import { createPortal } from "react-dom";
 import { jsx, jsxs } from "react/jsx-runtime";
 
@@ -26,6 +26,7 @@ function applyPatches(nodes, patches) {
 function useAIRenderer(options = {}) {
 	const [nodes, setNodes] = useState([]);
 	const active = useRef(null);
+	const pluginList = useStableList(options.plugins);
 	const session = useMemo(() => {
 		const token = {};
 		const renderer = new Renderer({
@@ -42,7 +43,7 @@ function useAIRenderer(options = {}) {
 	}, [
 		options.registry,
 		options.sanitize,
-		options.plugins,
+		pluginList,
 		options.scheduler,
 		options.debug,
 		options.onDebugEvent
@@ -71,6 +72,14 @@ function useAIRenderer(options = {}) {
 		reset
 	};
 }
+/** Keep the same array reference for as long as it holds the same members in the same order. */
+function useStableList(list) {
+	const held = useRef(list);
+	const current = held.current;
+	const same = list === current || !!list && !!current && list.length === current.length && list.every((item, index) => item === current[index]);
+	if (!same) held.current = list;
+	return held.current;
+}
 
 //#endregion
 //#region src/use-action-state.ts
@@ -93,7 +102,7 @@ function useActionState(runtime, key) {
 /** Translate a framework-neutral RenderOutput into React nodes. */
 function renderOutput(out, key, sanitize, context) {
 	switch (out.kind) {
-		case "html": return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: sanitizeOutput(out.html, sanitize) } }, key);
+		case "html": return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: sanitizeRenderedHtml(out.html, sanitize, out.trusted) } }, key);
 		case "element": return createElement(out.tag, {
 			key,
 			...out.props
@@ -193,10 +202,6 @@ function AsyncOutput({ promise, sanitize, context }) {
 		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
@@ -232,11 +237,13 @@ function renderNode(node, ctx) {
 function PluginOutputHost({ node, renderer, context }) {
 	const cache = useRef();
 	const signature = nodeSignature(node);
+	const theme = context.theme;
 	try {
-		if (!cache.current || cache.current.renderer !== renderer || cache.current.signature !== signature) cache.current = {
+		if (!cache.current || cache.current.renderer !== renderer || cache.current.signature !== signature || cache.current.theme !== theme) cache.current = {
 			renderer,
 			signature,
-			output: renderer(node)
+			theme,
+			output: renderer(node, { theme })
 		};
 		const output = cache.current.output;
 		if (output && typeof output.then === "function") return /* @__PURE__ */ jsx(AsyncOutput, {
@@ -350,7 +357,7 @@ function createActionScope() {
 	};
 }
 const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
-	const { registry, cardStore, sanitize, plugins, actionRuntime, onCardAction, className, debug, onDebugEvent } = props;
+	const { text, registry, cardStore, sanitize, plugins, actionRuntime, onCardAction, onRender, theme, className, debug, onDebugEvent } = props;
 	const opts = {
 		registry,
 		sanitize,
@@ -360,6 +367,8 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 	};
 	const { renderer, nodes, push, feed, reset: resetRenderer } = useAIRenderer(opts);
 	const actionScope = useRef(createActionScope());
+	const rendered = useRef("");
+	const root = useRef(null);
 	useEffect(() => () => {
 		actionScope.current.controller.abort();
 		actionScope.current = createActionScope();
@@ -372,8 +381,30 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 	const reset = useCallback(() => {
 		actionScope.current.controller.abort();
 		actionScope.current = createActionScope();
+		rendered.current = "";
 		resetRenderer();
 	}, [resetRenderer]);
+	useEffect(() => {
+		if (text === void 0 || text === rendered.current) return;
+		if (text.startsWith(rendered.current)) push(text.slice(rendered.current.length));
+		else {
+			reset();
+			push(text);
+		}
+		rendered.current = text;
+	}, [
+		text,
+		push,
+		reset
+	]);
+	const onRenderRef = useRef(onRender);
+	onRenderRef.current = onRender;
+	useEffect(() => {
+		onRenderRef.current?.(nodes);
+	}, [nodes]);
+	useEffect(() => () => {
+		rendered.current = "";
+	}, [renderer]);
 	const handleCardAction = useCallback((action) => {
 		if (actionRuntime) {
 			const scope = actionScope.current;
@@ -389,16 +420,19 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 		}
 		onCardAction?.(action);
 	}, [actionRuntime, onCardAction]);
+	const exportImages = useCallback((options) => root.current ? exportRenderedImages(root.current, options) : Promise.resolve([]), []);
 	useImperativeHandle(ref, () => ({
 		debugSource: "renderer",
 		subscribeDebug: (listener) => renderer.subscribeDebug(listener),
 		push,
 		feed,
+		exportImages,
 		reset
 	}), [
 		renderer,
 		push,
 		feed,
+		exportImages,
 		reset
 	]);
 	const nodeRenderers = useMemo(() => collectNodeRenderers(plugins, { debugTarget: renderer }), [plugins, renderer]);
@@ -409,11 +443,13 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 		nodeRenderers,
 		onCardAction: handleCardAction,
 		sanitize,
-		sanitized: true
+		sanitized: true,
+		theme
 	};
 	return /* @__PURE__ */ jsx("div", {
 		className,
 		"data-aigui-renderer": true,
+		ref: root,
 		children: nodes.map((n) => renderNode(n, ctx))
 	});
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/react",
-  "version": "0.4.4",
+  "version": "0.6.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.4.4"
+    "@ai-gui/core": "0.6.0"
   },
   "peerDependencies": {
     "react": ">=18",