@ai-gui/react 0.4.2 → 0.5.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,12 +67,13 @@ function useAIRenderer(options = {}) {
 	}, [
 		options.registry,
 		options.sanitize,
-		options.plugins,
+		pluginList,
 		options.scheduler,
 		options.debug,
 		options.onDebugEvent
 	]);
 	(0, react.useEffect)(() => {
+		active.current = session.token;
 		setNodes([]);
 		return () => {
 			session.renderer.reset();
@@ -94,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
@@ -255,11 +265,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, {
@@ -373,7 +385,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,
@@ -383,6 +395,7 @@ 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)("");
 	(0, react.useEffect)(() => () => {
 		actionScope.current.controller.abort();
 		actionScope.current = createActionScope();
@@ -395,8 +408,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;
@@ -432,7 +467,8 @@ 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,

package/dist/index.d.cts

@@ -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 {
@@ -54,12 +56,36 @@ interface AIRendererHandle {
   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

@@ -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 {
@@ -54,12 +56,36 @@ interface AIRendererHandle {
   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

@@ -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,12 +43,13 @@ function useAIRenderer(options = {}) {
 	}, [
 		options.registry,
 		options.sanitize,
-		options.plugins,
+		pluginList,
 		options.scheduler,
 		options.debug,
 		options.onDebugEvent
 	]);
 	useEffect(() => {
+		active.current = session.token;
 		setNodes([]);
 		return () => {
 			session.renderer.reset();
@@ -70,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
@@ -231,11 +241,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, {
@@ -349,7 +361,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,
@@ -359,6 +371,7 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 	};
 	const { renderer, nodes, push, feed, reset: resetRenderer } = useAIRenderer(opts);
 	const actionScope = useRef(createActionScope());
+	const rendered = useRef("");
 	useEffect(() => () => {
 		actionScope.current.controller.abort();
 		actionScope.current = createActionScope();
@@ -371,8 +384,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;
@@ -408,7 +443,8 @@ const AIRenderer = forwardRef(function AIRenderer$1(props, ref) {
 		nodeRenderers,
 		onCardAction: handleCardAction,
 		sanitize,
-		sanitized: true
+		sanitized: true,
+		theme
 	};
 	return /* @__PURE__ */ jsx("div", {
 		className,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/react",
-  "version": "0.4.2",
+  "version": "0.5.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.2"
+    "@ai-gui/core": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=18",