@assistant-ui/core 0.3.20 → 0.3.21

package/src/react/interactables-legacy/interactable-model-context.ts

@@ -1,26 +1,21 @@
-import type { Tool } from "assistant-stream";
-import type { InteractableDefinition, InteractableStateSchema } from "./scopes";
+import type { Tool, toJSONSchema } from "assistant-stream";
+import { getPartialJsonObjectMeta } from "assistant-stream/utils";
+import { overlayPartialPath } from "../../model-context/interactable-composer-metadata";
+import type { InteractableDefinition } from "./scopes";
 
-export function shallowMerge(prev: unknown, partial: unknown): unknown {
-  if (
-    typeof prev !== "object" ||
-    prev === null ||
-    typeof partial !== "object" ||
-    partial === null ||
-    Array.isArray(prev) ||
-    Array.isArray(partial)
-  ) {
-    return partial;
-  }
-  return {
-    ...(prev as Record<string, unknown>),
-    ...(partial as Record<string, unknown>),
-  };
-}
+export type StateJSONSchema = ReturnType<typeof toJSONSchema>;
+
+// The spread also drops the non-enumerable `~standard` zod attaches to its
+// JSON Schema output; carried over, the tool runtime would validate every
+// partial update against the full state schema.
+const withoutRootRequired = ({
+  required: _required,
+  ...schema
+}: StateJSONSchema) => schema;
 
 export function buildInteractableModelContext(
   definitions: Record<string, InteractableDefinition>,
-  partialSchemaCache: Map<string, InteractableStateSchema>,
+  schemaCache: Map<string, StateJSONSchema>,
   setDefState: (id: string, updater: (prev: unknown) => unknown) => void,
 ): { system: string; tools: Record<string, Tool<any, any>> } | undefined {
   const entries = Object.values(definitions);
@@ -53,23 +48,30 @@ export function buildInteractableModelContext(
         ? `update_${safeName}_${safeId}`
         : `update_${safeName}`;
 
-      const partialSchema = partialSchemaCache.get(def.id) ?? def.stateSchema;
+      const jsonSchema = schemaCache.get(def.id);
 
       tools[toolName] = {
         type: "frontend" as const,
-        description: `Update the state of interactable component "${name}"${isMulti ? ` (id: ${def.id})` : ""}. Only include the fields you want to change; omitted fields keep their current values. ${def.description}`,
-        parameters: partialSchema,
+        description: `Update the state of interactable component "${name}"${isMulti ? ` (id: ${def.id})` : ""}. Only include the fields you want to change; omitted fields keep their current values. A nested object replaces the existing one, so send it complete. ${def.description}`,
+        parameters: jsonSchema
+          ? withoutRootRequired(jsonSchema)
+          : def.stateSchema,
         streamCall: async (reader) => {
           try {
             for await (const partialArgs of reader.args.streamValues()) {
-              setDefState(def.id, (prev) => shallowMerge(prev, partialArgs));
+              const partialPath = getPartialJsonObjectMeta(
+                partialArgs as Record<symbol, unknown>,
+              )?.partialPath;
+              setDefState(def.id, (prev) =>
+                overlayPartialPath(prev, partialArgs, partialPath),
+              );
             }
           } catch {
             // Non-fatal: execute handles the final state
           }
         },
         execute: async (partialState: unknown) => {
-          setDefState(def.id, (prev) => shallowMerge(prev, partialState));
+          setDefState(def.id, (prev) => overlayPartialPath(prev, partialState));
           return { success: true };
         },
       };

package/src/react/interactables-shared/useInteractablePersistenceQueue.test.tsx

@@ -23,10 +23,15 @@ const createDeferred = () => {
   return { promise, resolve, reject };
 };
 
-const renderQueue = (save: (state: TestState) => void | Promise<void>) => {
+const renderQueue = (
+  save: ((state: TestState) => void | Promise<void>) | undefined,
+) => {
   let snapshot: TestState = {};
   let persistence: PersistenceStatusMap = {};
-  const adapterRef = { current: { save } };
+  const adapterRef: {
+    current: { save: (state: TestState) => void | Promise<void> } | undefined;
+  } = { current: save ? { save } : undefined };
+  const adapterGenerationRef = { current: 0 };
   const updatePersistenceStatus = (
     updater: (prev: PersistenceStatusMap) => PersistenceStatusMap,
   ) => {
@@ -35,6 +40,7 @@ const renderQueue = (save: (state: TestState) => void | Promise<void>) => {
   const hook = renderHook(() =>
     useInteractablePersistenceQueue({
       adapterRef,
+      adapterGenerationRef,
       snapshot: () => snapshot,
       updatePersistenceStatus,
     }),
@@ -68,6 +74,20 @@ afterEach(() => {
 });
 
 describe("useInteractablePersistenceQueue", () => {
+  it("resolves flush while edits wait for an adapter", async () => {
+    const queue = renderQueue(undefined);
+
+    queue.setState("a", 1);
+    act(() => queue.result.current.schedulePersistence("a"));
+
+    let flushPromise!: Promise<void>;
+    act(() => {
+      flushPromise = queue.result.current.flush();
+    });
+
+    await expect(flushPromise).resolves.toBeUndefined();
+  });
+
   it("coalesces dirty marks inside the debounce window into one save", async () => {
     const save = vi.fn<(state: TestState) => void>();
     const queue = renderQueue(save);

package/src/react/interactables-shared/useInteractablePersistenceQueue.ts

@@ -1,7 +1,14 @@
 import { useCallback, useRef, type RefObject } from "react";
 import { nullProtoRecord } from "../../utils/record";
 
-const PERSISTENCE_DEBOUNCE_MS = 500;
+export const PERSISTENCE_DEBOUNCE_MS = 500;
+
+/**
+ * `load` is caller code with no settling contract, so an awaited `flush` bounds
+ * the wait rather than inheriting it. Past this the edit stays queued for the
+ * next successful snapshot, which is the same shape a failed load already has.
+ */
+export const FLUSH_LOAD_TIMEOUT_MS = 5_000;
 
 type PersistenceAdapter<State> = {
   save(state: State): void | Promise<void>;
@@ -20,14 +27,18 @@ type PersistenceStatusUpdater = (
 
 type UseInteractablePersistenceQueueOptions<State> = {
   adapterRef: RefObject<PersistenceAdapter<State> | undefined>;
+  adapterGenerationRef: RefObject<number>;
   snapshot: () => State;
   updatePersistenceStatus: PersistenceStatusUpdater;
+  retainDirtyWithoutAdapter?: boolean;
 };
 
 export const useInteractablePersistenceQueue = <State>({
   adapterRef,
+  adapterGenerationRef,
   snapshot,
   updatePersistenceStatus,
+  retainDirtyWithoutAdapter = false,
 }: UseInteractablePersistenceQueueOptions<State>) => {
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
     undefined,
@@ -43,6 +54,7 @@ export const useInteractablePersistenceQueue = <State>({
     payload: State;
     dirtyIds: Set<string>;
     seq: number;
+    adapterGeneration: number;
   };
 
   const outgoingQueueRef = useRef<PersistenceBatch[]>([]);
@@ -57,9 +69,15 @@ export const useInteractablePersistenceQueue = <State>({
       dirtyIdsRef.current.clear();
       const seq = ++syncSeqRef.current;
       for (const id of dirtyIds) latestSyncSeqByIdRef.current.set(id, seq);
-      return { adapter, payload: snapshot(), dirtyIds, seq };
+      return {
+        adapter,
+        adapterGeneration: adapterGenerationRef.current,
+        payload: snapshot(),
+        dirtyIds,
+        seq,
+      };
     },
-    [snapshot],
+    [adapterGenerationRef, snapshot],
   );
 
   const enqueuePersistence = useCallback(
@@ -88,7 +106,7 @@ export const useInteractablePersistenceQueue = <State>({
         return;
       }
 
-      const { adapter, payload, dirtyIds, seq } = resolved;
+      const { adapter, adapterGeneration, payload, dirtyIds, seq } = resolved;
       inFlightPersistenceRef.current += 1;
 
       updatePersistenceStatus((prev) => {
@@ -128,7 +146,17 @@ export const useInteractablePersistenceQueue = <State>({
         await adapter.save(payload);
         settleBatch(undefined);
       } catch (e) {
-        settleBatch({ isPending: false, error: e });
+        const isCurrentScope =
+          adapterGenerationRef.current === adapterGeneration;
+        if (!isCurrentScope) {
+          console.warn(
+            "[Interactables] Persistence save failed after the adapter changed.",
+            e,
+          );
+        }
+        settleBatch(
+          isCurrentScope ? { isPending: false, error: e } : undefined,
+        );
       } finally {
         inFlightPersistenceRef.current -= 1;
         const next =
@@ -148,7 +176,7 @@ export const useInteractablePersistenceQueue = <State>({
         }
       }
     },
-    [adapterRef, takeDirtyBatch, updatePersistenceStatus],
+    [adapterGenerationRef, adapterRef, takeDirtyBatch, updatePersistenceStatus],
   );
   runPersistenceRef.current = (nextBatch) => {
     void runPersistence(nextBatch);
@@ -164,8 +192,9 @@ export const useInteractablePersistenceQueue = <State>({
 
   const schedulePersistence = useCallback(
     (id: string) => {
-      if (!adapterRef.current) return;
+      if (!adapterRef.current && !retainDirtyWithoutAdapter) return;
       dirtyIdsRef.current.add(id);
+      if (!adapterRef.current) return;
       if (debounceTimerRef.current !== undefined) {
         clearTimeout(debounceTimerRef.current);
       }
@@ -181,9 +210,26 @@ export const useInteractablePersistenceQueue = <State>({
         }
       }, PERSISTENCE_DEBOUNCE_MS);
     },
-    [adapterRef, enqueuePersistence],
+    [adapterRef, enqueuePersistence, retainDirtyWithoutAdapter],
   );
 
+  const discardPending = useCallback(() => {
+    if (debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+    dirtyIdsRef.current.clear();
+    if (
+      inFlightPersistenceRef.current === 0 &&
+      outgoingQueueRef.current.length === 0
+    ) {
+      for (const resolve of flushResolversRef.current) resolve();
+      flushResolversRef.current = [];
+    }
+  }, []);
+
+  const getDirtyIds = useCallback(() => new Set(dirtyIdsRef.current), []);
+
   const flush = useCallback(async () => {
     if (debounceTimerRef.current !== undefined) {
       clearTimeout(debounceTimerRef.current);
@@ -191,8 +237,8 @@ export const useInteractablePersistenceQueue = <State>({
     }
     const hasWork =
       inFlightPersistenceRef.current > 0 ||
-      dirtyIdsRef.current.size > 0 ||
-      outgoingQueueRef.current.length > 0;
+      outgoingQueueRef.current.length > 0 ||
+      (adapterRef.current !== undefined && dirtyIdsRef.current.size > 0);
     if (!hasWork) return;
     const p = new Promise<void>((resolve) => {
       flushResolversRef.current.push(resolve);
@@ -201,5 +247,11 @@ export const useInteractablePersistenceQueue = <State>({
     return p;
   }, [adapterRef, enqueuePersistence]);
 
-  return { flushIfPending, schedulePersistence, flush };
+  return {
+    discardPending,
+    flushIfPending,
+    getDirtyIds,
+    schedulePersistence,
+    flush,
+  };
 };

package/src/react/primitive-hooks/useSuggestionTrigger.test.ts

@@ -11,6 +11,7 @@ const mocks = vi.hoisted(() => {
       isDisabled: false,
       isRunning: false,
       capabilities: { queue: false },
+      voice: undefined as { canSendText: boolean } | undefined,
     },
   };
   const composerState = {
@@ -50,6 +51,7 @@ afterEach(() => {
   mocks.state.thread.isDisabled = false;
   mocks.state.thread.isRunning = false;
   mocks.state.thread.capabilities = { queue: false };
+  mocks.state.thread.voice = undefined;
   mocks.composerState.text = "";
 });
 
@@ -101,6 +103,37 @@ describe("useSuggestionTrigger", () => {
     expect(mocks.setText).not.toHaveBeenCalled();
   });
 
+  it("sends into a voice session that takes typed text while a spoken reply is running", () => {
+    mocks.state.thread.isRunning = true;
+    mocks.state.thread.voice = { canSendText: true };
+    mocks.composerState.text = "my draft";
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", send: true }),
+    );
+
+    result.current.trigger();
+
+    expect(result.current.disabled).toBe(false);
+    expect(mocks.append).toHaveBeenCalledWith({
+      content: [{ type: "text", text: "Hello" }],
+      runConfig: { custom: { model: "gpt-test" } },
+    });
+    expect(mocks.setText).toHaveBeenCalledWith("");
+  });
+
+  it("disables and no-ops while a voice session cannot take typed text", () => {
+    mocks.state.thread.voice = { canSendText: false };
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", send: true }),
+    );
+
+    result.current.trigger();
+
+    expect(result.current.disabled).toBe(true);
+    expect(mocks.append).not.toHaveBeenCalled();
+    expect(mocks.setText).not.toHaveBeenCalled();
+  });
+
   it("replaces the composer text when send is false, even while running", () => {
     mocks.state.thread.isRunning = true;
     mocks.composerState.text = "my draft";

package/src/react/primitive-hooks/useSuggestionTrigger.ts

@@ -1,6 +1,9 @@
 import { useCallback } from "react";
 import { useAui, useAuiState } from "@assistant-ui/store";
-import { suggestionTriggerDisabled } from "../../store/primitive-predicates";
+import {
+  suggestionSendMode,
+  suggestionTriggerDisabled,
+} from "../../store/primitive-predicates";
 
 export type UseSuggestionTriggerOptions = {
   prompt: string;
@@ -21,15 +24,15 @@ export const useSuggestionTrigger = ({
 
   const trigger = useCallback(() => {
     if (resolvedSend) {
-      const { isRunning, capabilities } = aui.thread.getState();
-      if (isRunning && !capabilities.queue) return;
+      const mode = suggestionSendMode(aui.thread.getState());
+      if (mode === "blocked") return;
 
       aui.thread.append({
         content: [{ type: "text", text: prompt }],
         runConfig: aui.composer.getState().runConfig,
       });
       // A queued send must not clear the draft the user is still composing.
-      if (clearComposer && !isRunning) {
+      if (clearComposer && mode === "now") {
         aui.composer.setText("");
       }
     } else {

package/src/react/primitives/generativeUI/GenerativeUI.test.tsx

@@ -1,22 +1,51 @@
 /** @vitest-environment jsdom */
 import { render } from "@testing-library/react";
-import type { ReactNode } from "react";
+import { type ReactNode, useState } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import type { GenerativeUISpec } from "../../../types/message";
-import { GenerativeUIRender } from "./GenerativeUI";
+import type {
+  GenerativeUINode,
+  GenerativeUISpec,
+} from "../../../types/message";
+import type { GenerativeUIRenderProps } from "../../types/MessagePartComponentTypes";
+import { GenerativeUIRender, GenerativeUIRenderError } from "./GenerativeUI";
 
 const Card = ({ children }: { children?: ReactNode }) => (
   <section>{children}</section>
 );
 
-const renderRoot = (root: unknown) =>
+const Fallback = ({ component }: { component: string }) => <i>{component}</i>;
+
+const inheritedNames = [
+  "constructor",
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "toLocaleString",
+  "toString",
+  "valueOf",
+  "__proto__",
+];
+
+const renderRoot = (
+  root: unknown,
+  props: Partial<Pick<GenerativeUIRenderProps, "components" | "Fallback">> = {},
+) =>
   render(
     <GenerativeUIRender
       spec={{ root } as GenerativeUISpec}
       components={{ Card }}
+      {...props}
     />,
   ).container.innerHTML;
 
+const thrownBy = (fn: () => unknown): unknown => {
+  try {
+    fn();
+  } catch (error) {
+    return error;
+  }
+  return undefined;
+};
+
 describe("GenerativeUIRender", () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -37,10 +66,67 @@ describe("GenerativeUIRender", () => {
     ).toBe("<section><section>Sunny</section></section>");
   });
 
-  it.each([
-    ["a number", 42],
-    ["an array-like object", { length: 1 }],
-  ])("skips %s children value as a malformed node", (_label, children) => {
+  it("renders number leaves and nested arrays recursively", () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    expect(
+      renderRoot({
+        component: "Card",
+        children: ["Count: ", [42, { component: "Card", children: [7] }]],
+      }),
+    ).toBe("<section>Count: 42<section>7</section></section>");
+    expect(error).not.toHaveBeenCalled();
+  });
+
+  it("preserves keyed component identity when nested arrays reorder", () => {
+    let nextInstance = 0;
+    const StatefulCard = ({ label }: { label?: string }) => {
+      const [instance] = useState(() => ++nextInstance);
+      return <span>{`${label}:${instance}`}</span>;
+    };
+    const nodes = [
+      { component: "StatefulCard", key: "a", props: { label: "A" } },
+      { component: "StatefulCard", key: "b", props: { label: "B" } },
+    ] satisfies readonly GenerativeUINode[];
+    const view = render(
+      <GenerativeUIRender
+        spec={{
+          root: { component: "Card", children: [nodes] },
+        }}
+        components={{ Card, StatefulCard }}
+      />,
+    );
+
+    expect(view.container.textContent).toBe("A:1B:2");
+    view.rerender(
+      <GenerativeUIRender
+        spec={{
+          root: {
+            component: "Card",
+            children: [[nodes[1]!, nodes[0]!]],
+          },
+        }}
+        components={{ Card, StatefulCard }}
+      />,
+    );
+    expect(view.container.textContent).toBe("B:2A:1");
+  });
+
+  it("stops rendering arrays beyond the recursion limit", () => {
+    let root: GenerativeUINode = "too deep";
+    for (let depth = 0; depth < 66; depth += 1) root = [root];
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    expect(renderRoot(root)).toBe("");
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "[generative-ui] Skipping node nested past 64 levels at 0/",
+      ),
+    );
+  });
+
+  it("skips an array-like object children value as a malformed node", () => {
+    const children = { length: 1 };
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 
     expect(renderRoot({ component: "Card", children })).toBe(
@@ -51,4 +137,34 @@ describe("GenerativeUIRender", () => {
       children,
     );
   });
+
+  it.each(inheritedNames)(
+    "renders Fallback for the inherited name %s",
+    (component) => {
+      expect(renderRoot({ component }, { Fallback })).toBe(
+        `<i>${component}</i>`,
+      );
+    },
+  );
+
+  it.each(inheritedNames)(
+    "throws GenerativeUIRenderError for the inherited name %s",
+    (component) => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+
+      const error = thrownBy(() => renderRoot({ component }));
+
+      expect(error).toBeInstanceOf(GenerativeUIRenderError);
+      expect((error as GenerativeUIRenderError).componentName).toBe(component);
+    },
+  );
+
+  it("renders a component registered under an inherited name", () => {
+    expect(
+      renderRoot(
+        { component: "toString", children: "Sunny" },
+        { components: { toString: Card } },
+      ),
+    ).toBe("<section>Sunny</section>");
+  });
 });

package/src/react/primitives/generativeUI/GenerativeUI.tsx

@@ -38,45 +38,65 @@ export class GenerativeUIRenderError extends Error {
 
 const isObjectNode = (
   node: GenerativeUINode,
-): node is Exclude<GenerativeUINode, string> =>
-  typeof node === "object" && node !== null;
+): node is Extract<GenerativeUINode, { component: string }> =>
+  typeof node === "object" && node !== null && !Array.isArray(node);
 
 const toNodeList = (
-  value: GenerativeUINode | readonly GenerativeUINode[] | null | undefined,
+  value: GenerativeUINode | null | undefined,
 ): readonly GenerativeUINode[] => {
   if (value === undefined || value === null) return [];
-  return Array.isArray(value)
-    ? (value as readonly GenerativeUINode[])
-    : [value as GenerativeUINode];
+  return Array.isArray(value) ? value : [value];
 };
 
+const warn = (message: string, ...args: unknown[]) => {
+  if (
+    typeof process !== "undefined" &&
+    process.env?.NODE_ENV !== "production"
+  ) {
+    console.warn(message, ...args);
+  }
+};
+
+/** Bounds recursion so a runaway or adversarial model response cannot overflow the stack. */
+const MAX_DEPTH = 64;
+
 const renderNode = (
   node: GenerativeUINode | undefined,
   components: GenerativeUIComponentRegistry,
   Fallback: GenerativeUIRenderProps["Fallback"],
   path: string,
+  depth = 0,
 ): ReactNode => {
+  if (depth > MAX_DEPTH) {
+    warn(
+      `[generative-ui] Skipping node nested past ${MAX_DEPTH} levels at ${path}.`,
+    );
+    return null;
+  }
   if (node === undefined || node === null) return null;
 
-  if (typeof node === "string") return node;
+  if (typeof node === "string" || typeof node === "number") return node;
+
+  if (Array.isArray(node)) {
+    return node.map((child, i) =>
+      renderNode(child, components, Fallback, `${path}/${i}`, depth + 1),
+    );
+  }
 
   if (
     !isObjectNode(node) ||
     !("component" in node) ||
     typeof node.component !== "string"
   ) {
-    if (
-      typeof process !== "undefined" &&
-      process.env?.NODE_ENV !== "production"
-    ) {
-      console.warn(`[generative-ui] Skipping malformed node at ${path}:`, node);
-    }
+    warn(`[generative-ui] Skipping malformed node at ${path}:`, node);
     return null;
   }
 
   const { component, props, children, key } = node;
 
-  const Resolved = components[component];
+  const Resolved = Object.hasOwn(components, component)
+    ? components[component]
+    : undefined;
   if (!Resolved) {
     if (Fallback) {
       return <Fallback key={key ?? path} component={component} props={props} />;
@@ -88,7 +108,7 @@ const renderNode = (
     Resolved,
     { ...(props ?? {}), key: key ?? path },
     ...toNodeList(children).map((child, i) =>
-      renderNode(child, components, Fallback, `${path}/${i}`),
+      renderNode(child, components, Fallback, `${path}/${i}`, depth + 1),
     ),
   );
 };

package/src/react/primitives/message/MessageAttachments.test.tsx

@@ -2,7 +2,7 @@
 import { render, screen } from "@testing-library/react";
 import { useState, type ReactNode } from "react";
 import { describe, expect, it, vi } from "vitest";
-import type { CompleteAttachment } from "../../../types/attachment";
+import type { Attachment, CompleteAttachment } from "../../../types/attachment";
 
 const mocks = vi.hoisted(() => ({
   role: "user" as "user" | "assistant",
@@ -56,11 +56,7 @@ const attachment = (id: string): CompleteAttachment => ({
   content: [],
 });
 
-const StatefulAttachment = ({
-  attachment,
-}: {
-  attachment: CompleteAttachment;
-}) => {
+const StatefulAttachment = ({ attachment }: { attachment: Attachment }) => {
   const [initialId] = useState(attachment.id);
   return <span>{initialId}</span>;
 };