@assistant-ui/core 0.2.3 → 0.2.5

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

@@ -0,0 +1,182 @@
+"use client";
+
+import {
+  type ComponentType,
+  type FC,
+  type ReactNode,
+  createElement,
+  useMemo,
+} from "react";
+import { useAuiState } from "@assistant-ui/store";
+import type {
+  GenerativeUINode,
+  GenerativeUISpec,
+} from "../../../types/message";
+import type {
+  GenerativeUIComponentRegistry,
+  GenerativeUIRenderProps,
+} from "../../types/MessagePartComponentTypes";
+
+/**
+ * Thrown when a generative-ui spec references a component name that is not
+ * present in the consumer-provided allowlist. The allowlist is the security
+ * boundary in the same-realm rendering path — there is no fallback by
+ * default. Pass `Fallback` to opt into a soft-fail UX.
+ */
+export class GenerativeUIRenderError extends Error {
+  public readonly componentName: string;
+
+  constructor(
+    componentName: string,
+    message = `Component "${componentName}" is not in the generative-ui allowlist.`,
+  ) {
+    super(message);
+    this.name = "GenerativeUIRenderError";
+    this.componentName = componentName;
+  }
+}
+
+const isObjectNode = (
+  node: GenerativeUINode,
+): node is Exclude<GenerativeUINode, string> =>
+  typeof node === "object" && node !== null;
+
+const renderNode = (
+  node: GenerativeUINode | undefined,
+  components: GenerativeUIComponentRegistry,
+  Fallback: GenerativeUIRenderProps["Fallback"],
+  path: string,
+): ReactNode => {
+  if (node === undefined || node === null) return null;
+
+  if (typeof node === "string") return node;
+
+  if (!isObjectNode(node) || !("component" in node)) {
+    if (
+      typeof process !== "undefined" &&
+      process.env?.NODE_ENV !== "production"
+    ) {
+      console.warn(`[generative-ui] Skipping malformed node at ${path}:`, node);
+    }
+    return null;
+  }
+
+  const { component, props, children, key } = node;
+
+  const Resolved = components[component];
+  if (!Resolved) {
+    if (Fallback) {
+      return <Fallback key={key ?? path} component={component} props={props} />;
+    }
+    throw new GenerativeUIRenderError(component);
+  }
+
+  const renderedChildren = children?.length
+    ? children.map((child, i) =>
+        renderNode(child, components, Fallback, `${path}/${i}`),
+      )
+    : undefined;
+
+  return createElement(
+    Resolved,
+    { ...(props ?? {}), key: key ?? path },
+    ...(renderedChildren ?? []),
+  );
+};
+
+const normalizeRoot = (
+  spec: GenerativeUISpec | undefined,
+): readonly GenerativeUINode[] => {
+  if (!spec || spec.root === undefined || spec.root === null) return [];
+  const root = spec.root;
+  return Array.isArray(root)
+    ? (root as readonly GenerativeUINode[])
+    : [root as GenerativeUINode];
+};
+
+/**
+ * Internal renderer. Resolves a {@link GenerativeUISpec} against the consumer
+ * allowlist. Used by `MessagePrimitive.GenerativeUI` and by
+ * `MessagePrimitive.Parts` when handling a `generative-ui` part.
+ */
+export const GenerativeUIRender: FC<GenerativeUIRenderProps> = ({
+  spec,
+  components,
+  Fallback,
+}) => {
+  const nodes = useMemo(() => normalizeRoot(spec), [spec]);
+
+  return (
+    <>
+      {nodes.map((node, i) => renderNode(node, components, Fallback, `${i}`))}
+    </>
+  );
+};
+
+GenerativeUIRender.displayName = "GenerativeUIRender";
+
+export namespace MessagePrimitiveGenerativeUI {
+  export type Props = {
+    /**
+     * The component allowlist. Keys are the names referenced in the spec
+     * (e.g. `"Card"`, `"Button"`), values are the React components.
+     *
+     * This is the security boundary — any name not in the allowlist is
+     * rejected with {@link GenerativeUIRenderError}.
+     */
+    components: GenerativeUIComponentRegistry;
+    /**
+     * Optional override spec. If omitted, the primitive reads the
+     * `generative-ui` part from the surrounding `MessagePartProvider` /
+     * `PartByIndexProvider` context.
+     */
+    spec?: GenerativeUISpec | undefined;
+    /** Optional fallback for unknown component names. */
+    Fallback?:
+      | ComponentType<{ component: string; props?: unknown }>
+      | undefined;
+  };
+}
+
+/**
+ * Renders a generative-ui message part using a consumer-provided allowlist.
+ *
+ * The agent emits a `generative-ui` message part containing a JSON spec
+ * (see {@link GenerativeUISpec}). This primitive walks the spec and resolves
+ * each `component` name against the allowlist. Names not in the allowlist
+ * throw {@link GenerativeUIRenderError} unless a `Fallback` is provided.
+ *
+ * Stream-friendly: a partial spec renders progressively as it is filled in.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.GenerativeUI
+ *   components={{ Card: MyCard, Button: MyButton }}
+ * />
+ * ```
+ */
+export const MessagePrimitiveGenerativeUI: FC<
+  MessagePrimitiveGenerativeUI.Props
+> = ({ components, spec, Fallback }) => {
+  // Selector reads store state only — combining with the `spec` prop inside
+  // the selector closes over a value that may change identity per render and
+  // would trigger spurious tearing-detection re-renders in
+  // `useSyncExternalStore`.
+  const storeSpec = useAuiState((s) => {
+    const part = s.part as { type?: string; spec?: GenerativeUISpec };
+    return part?.type === "generative-ui" ? part.spec : undefined;
+  });
+  const partSpec = spec ?? storeSpec;
+
+  if (!partSpec) return null;
+
+  return (
+    <GenerativeUIRender
+      spec={partSpec}
+      components={components}
+      Fallback={Fallback}
+    />
+  );
+};
+
+MessagePrimitiveGenerativeUI.displayName = "MessagePrimitive.GenerativeUI";

package/src/react/primitives/message/MessageGroupedParts.tsx

@@ -107,8 +107,9 @@ const renderNode = <TKey extends `group-${string}`>(
   render: (info: MessagePrimitiveGroupedParts.RenderInfo<TKey>) => ReactNode,
 ): ReactNode => {
   if (node.type === "part") {
+    // Key by absolute part index, not structural nodeKey — prevents zombie fiber subscriptions when parts reshape (#4051).
     return (
-      <MessagePartChildren key={node.nodeKey} index={node.index}>
+      <MessagePartChildren key={`part-${node.index}`} index={node.index}>
         {({ part }) => render({ part, children: <PartChildrenSentinel /> })}
       </MessagePartChildren>
     );

package/src/react/primitives/message/MessageParts.tsx

@@ -30,8 +30,14 @@ import type {
   ReasoningMessagePartComponent,
   ReasoningGroupComponent,
   QuoteMessagePartComponent,
+  GenerativeUIComponentRegistry,
 } from "../../types/MessagePartComponentTypes";
-import { isMcpAppUri, type MessagePartStatus } from "../../../types/message";
+import { GenerativeUIRender } from "../generativeUI/GenerativeUI";
+import {
+  isMcpAppUri,
+  type MessagePartStatus,
+  type GenerativeUIMessagePart,
+} from "../../../types/message";
 import type { DataRenderersState } from "../../types/scopes/dataRenderers";
 import type { ToolsState } from "../../types/scopes/tools";
 import { useShallow } from "zustand/shallow";
@@ -174,6 +180,24 @@ export namespace MessagePrimitiveParts {
     data?: DataConfig | undefined;
     /** Component for rendering a quoted message reference (from metadata, not parts) */
     Quote?: QuoteMessagePartComponent | undefined;
+    /**
+     * Configuration for generative-ui part rendering.
+     *
+     * `components` is the consumer-provided allowlist of React components
+     * the agent's JSON spec is permitted to render. Any name not present in
+     * the registry is rejected with a typed `GenerativeUIRenderError` —
+     * this is the security boundary in the same-realm rendering path.
+     */
+    generativeUI?:
+      | {
+          /** The component allowlist (the security boundary). */
+          components: GenerativeUIComponentRegistry;
+          /** Optional fallback for unknown component names. */
+          Fallback?:
+            | ComponentType<{ component: string; props?: unknown }>
+            | undefined;
+        }
+      | undefined;
   };
 
   type ToolsConfig =
@@ -345,6 +369,7 @@ export const MessagePartComponent: FC<MessagePartComponentProps> = ({
     Unstable_Audio: Audio = defaultComponents.Unstable_Audio,
     tools = {},
     data,
+    generativeUI,
   } = {},
 }) => {
   const aui = useAui();
@@ -394,6 +419,29 @@ export const MessagePartComponent: FC<MessagePartComponentProps> = ({
       return <DataUIDisplay {...part} Fallback={Data} />;
     }
 
+    case "generative-ui": {
+      if (!generativeUI?.components) {
+        if (
+          typeof process !== "undefined" &&
+          process.env?.NODE_ENV !== "production"
+        ) {
+          console.warn(
+            "MessagePrimitive.Parts received a generative-ui part but no " +
+              "`components.generativeUI.components` allowlist was provided. " +
+              "Pass an allowlist or render with <MessagePrimitive.GenerativeUI />.",
+          );
+        }
+        return null;
+      }
+      return (
+        <GenerativeUIRender
+          spec={(part as GenerativeUIMessagePart).spec}
+          components={generativeUI.components}
+          Fallback={generativeUI.Fallback}
+        />
+      );
+    }
+
     default:
       console.warn(`Unknown message part type: ${type}`);
       return null;
@@ -429,6 +477,7 @@ export const MessagePrimitivePartByIndex: FC<MessagePrimitivePartByIndex.Props>
       prev.components?.Unstable_Audio === next.components?.Unstable_Audio &&
       prev.components?.tools === next.components?.tools &&
       prev.components?.data === next.components?.data &&
+      prev.components?.generativeUI === next.components?.generativeUI &&
       prev.components?.ToolGroup === next.components?.ToolGroup &&
       prev.components?.ReasoningGroup === next.components?.ReasoningGroup,
   );
@@ -775,13 +824,16 @@ const MessagePrimitivePartsCompat: FC<{
           >
             {Array.from(
               { length: range.endIndex - range.startIndex + 1 },
-              (_, i) => (
-                <MessagePrimitivePartByIndex
-                  key={i}
-                  index={range.startIndex + i}
-                  components={components}
-                />
-              ),
+              (_, i) => {
+                const partIndex = range.startIndex + i;
+                return (
+                  <MessagePrimitivePartByIndex
+                    key={`part-${partIndex}`}
+                    index={partIndex}
+                    components={components}
+                  />
+                );
+              },
             )}
           </ToolGroupComponent>
         );
@@ -797,13 +849,16 @@ const MessagePrimitivePartsCompat: FC<{
           >
             {Array.from(
               { length: range.endIndex - range.startIndex + 1 },
-              (_, i) => (
-                <MessagePrimitivePartByIndex
-                  key={i}
-                  index={range.startIndex + i}
-                  components={components}
-                />
-              ),
+              (_, i) => {
+                const partIndex = range.startIndex + i;
+                return (
+                  <MessagePrimitivePartByIndex
+                    key={`part-${partIndex}`}
+                    index={partIndex}
+                    components={components}
+                  />
+                );
+              },
             )}
           </ReasoningGroupComponent>
         );

package/src/react/runtimes/RemoteThreadListHookInstanceManager.tsx

@@ -128,6 +128,7 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
 
     const aui = useAui();
     const initPromiseRef = useRef<Promise<unknown> | undefined>(undefined);
+    const hasInitializedRef = useRef(false);
 
     useEffect(() => {
       const runtimeCore = threadBinding.getState();
@@ -139,17 +140,20 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
     }, [threadBinding]);
 
     useEffect(() => {
+      hasInitializedRef.current = false;
       return runtime.threads.main.unstable_on("initialize", () => {
+        if (hasInitializedRef.current) return;
+
         const state = aui.threadListItem().getState();
-        if (state.status === "new") {
-          initPromiseRef.current = aui.threadListItem().initialize();
+        if (state.status !== "new") return;
+        hasInitializedRef.current = true;
 
-          const dispose = runtime.thread.unstable_on("runEnd", () => {
-            dispose();
+        initPromiseRef.current = aui.threadListItem().initialize();
 
-            aui.threadListItem().generateTitle();
-          });
-        }
+        const dispose = runtime.thread.unstable_on("runEnd", () => {
+          dispose();
+          aui.threadListItem().generateTitle();
+        });
       });
     }, [runtime, aui]);
 

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.tsx

@@ -274,7 +274,10 @@ export class RemoteThreadListThreadListRuntimeCore
     return getThreadData(this._state.value, threadIdOrRemoteId);
   }
 
-  public async switchToThread(threadIdOrRemoteId: string): Promise<void> {
+  public async switchToThread(
+    threadIdOrRemoteId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void> {
     let data = this.getItemById(threadIdOrRemoteId);
 
     if (!data) {
@@ -343,7 +346,9 @@ export class RemoteThreadListThreadListRuntimeCore
       task.then(() => this._notifySubscribers());
     }
 
-    if (data.status === "archived") await this.unarchive(data.id);
+    if (data.status === "archived" && options?.unarchive !== false) {
+      await this.unarchive(data.id);
+    }
     this._mainThreadId = data.id;
 
     this._notifySubscribers();

package/src/react/runtimes/cloud/auiV0.ts

@@ -163,7 +163,7 @@ export function auiV0Encode(message: ThreadMessage): AuiV0Message {
           };
 
         default: {
-          const unhandledType: "audio" | "data" = type;
+          const unhandledType: "audio" | "data" | "generative-ui" = type;
           throw new Error(
             `Message part type not supported by aui/v0: ${unhandledType}`,
           );

package/src/react/types/MessagePartComponentTypes.ts

@@ -3,6 +3,8 @@ import type {
   MessagePartStatus,
   DataMessagePart,
   FileMessagePart,
+  GenerativeUIMessagePart,
+  GenerativeUISpec,
   ImageMessagePart,
   ReasoningMessagePart,
   SourceMessagePart,
@@ -79,3 +81,27 @@ export type ToolCallMessagePartComponent<
 
 export type QuoteMessagePartProps = QuoteInfo;
 export type QuoteMessagePartComponent = ComponentType<QuoteMessagePartProps>;
+
+/**
+ * The consumer-provided allowlist of components a generative-ui spec is
+ * permitted to render. Keys are the component names referenced in the spec
+ * (e.g. `"Card"`, `"Button"`); values are the React components.
+ *
+ * This registry is the security boundary in the same-realm rendering path —
+ * any name not present in the registry is rejected with a typed error.
+ */
+export type GenerativeUIComponentRegistry = Record<string, ComponentType<any>>;
+
+export type GenerativeUIMessagePartProps = MessagePartState &
+  GenerativeUIMessagePart;
+export type GenerativeUIMessagePartComponent =
+  ComponentType<GenerativeUIMessagePartProps>;
+
+export type GenerativeUIRenderProps = {
+  /** The JSON spec to render. */
+  spec: GenerativeUISpec;
+  /** The component allowlist. */
+  components: GenerativeUIComponentRegistry;
+  /** Optional fallback for unknown component names. */
+  Fallback?: ComponentType<{ component: string; props?: unknown }> | undefined;
+};

package/src/runtime/api/thread-list-item-runtime.ts

@@ -36,7 +36,7 @@ export type ThreadListItemRuntime = {
   initialize(): Promise<{ remoteId: string; externalId: string | undefined }>;
   generateTitle(): Promise<void>;
 
-  switchTo(): Promise<void>;
+  switchTo(options?: { unarchive?: boolean }): Promise<void>;
   rename(newTitle: string): Promise<void>;
   archive(): Promise<void>;
   unarchive(): Promise<void>;
@@ -89,9 +89,9 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     return this._core.getState();
   }
 
-  public switchTo(): Promise<void> {
+  public switchTo(options?: { unarchive?: boolean }): Promise<void> {
     const state = this._core.getState();
-    return this._threadListBinding.switchToThread(state.id);
+    return this._threadListBinding.switchToThread(state.id, options);
   }
 
   public rename(newTitle: string): Promise<void> {

package/src/runtime/api/thread-list-runtime.ts

@@ -48,7 +48,10 @@ export type ThreadListRuntime = {
   getItemByIndex(idx: number): ThreadListItemRuntime;
   getArchivedItemByIndex(idx: number): ThreadListItemRuntime;
 
-  switchToThread(threadId: string): Promise<void>;
+  switchToThread(
+    threadId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
   getLoadThreadsPromise(): Promise<void>;
@@ -152,8 +155,11 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     this.getArchivedItemByIndex = this.getArchivedItemByIndex.bind(this);
   }
 
-  public switchToThread(threadId: string): Promise<void> {
-    return this._core.switchToThread(threadId);
+  public switchToThread(
+    threadId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void> {
+    return this._core.switchToThread(threadId, options);
   }
 
   public switchToNewThread(): Promise<void> {

package/src/runtime/base/base-thread-runtime-core.ts

@@ -478,6 +478,14 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     }
     subscribers.add(wrapped);
 
+    // `initialize` latches: replay it (deferred) to subscribers that attach
+    // after the thread already initialized, mirroring a BehaviorSubject.
+    if (event === "initialize" && this._isInitialized) {
+      queueMicrotask(() => {
+        if (subscribers.has(wrapped)) wrapped({});
+      });
+    }
+
     return () => {
       this._eventSubscribers.get(event)?.delete(wrapped);
     };

package/src/runtime/interfaces/thread-list-runtime-core.ts

@@ -32,7 +32,10 @@ export type ThreadListRuntimeCore = {
 
   getItemById(threadId: string): ThreadListItemCoreState | undefined;
 
-  switchToThread(threadId: string): Promise<void>;
+  switchToThread(
+    threadId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
   getLoadThreadsPromise(): Promise<void>;

package/src/runtime/interfaces/thread-runtime-core.ts

@@ -85,11 +85,12 @@ export type ThreadRuntimeEventPayload = {
    */
   runEnd: Record<string, never>;
   /**
-   * @deprecated State-derivable. This event fires at the initialization
-   * transition immediately BEFORE the first message is added, so reading state
-   * inside the handler still sees an empty thread; observe `state.messages`
-   * becoming non-empty via a regular `subscribe` callback instead. Kept for
-   * backward compatibility.
+   * @deprecated State-derivable. Observe `state.messages` becoming non-empty
+   * via a regular `subscribe` callback instead. This event fires once at the
+   * initialization transition; subscribers that attach afterwards receive a
+   * one-off replay (on a microtask), by which point the thread already has
+   * messages, so handler-visible state differs between live and replayed
+   * delivery. Kept for backward compatibility.
    */
   initialize: Record<string, never>;
   /**

package/src/runtime/utils/thread-message-like.ts

@@ -14,6 +14,7 @@ import type {
   ThreadSystemMessage,
   FileMessagePart,
   DataMessagePart,
+  GenerativeUIMessagePart,
   Unstable_AudioMessagePart,
 } from "../../types/message";
 import type { CompleteAttachment } from "../../types/attachment";
@@ -39,6 +40,7 @@ export type ThreadMessageLike = {
         | ImageMessagePart
         | FileMessagePart
         | DataMessagePart
+        | GenerativeUIMessagePart
         | Unstable_AudioMessagePart
         | DataPrefixedPart
         | {
@@ -105,10 +107,13 @@ export const fromThreadMessageLike = (
     image,
     ...rest
   }: ImageMessagePart): ImageMessagePart | null => {
-    const match = image.match(
-      /^data:image\/(png|jpeg|jpg|gif|webp);base64,(.*)$/,
+    const dataUri = image.match(
+      /^data:image\/(png|jpeg|jpg|gif|webp|svg\+xml);base64,(.*)$/,
     );
-    if (match) {
+    if (dataUri) {
+      return { ...rest, image };
+    }
+    if (/^(https:\/\/|blob:)/.test(image)) {
       return { ...rest, image };
     }
     console.warn(`Invalid image data format detected`);
@@ -148,6 +153,9 @@ export const fromThreadMessageLike = (
               case "data":
                 return part;
 
+              case "generative-ui":
+                return part;
+
               case "tool-call": {
                 const { parentId, messages, ...basePart } = part;
                 const commonProps = {

package/src/runtimes/external-store/external-store-thread-list-runtime-core.ts

@@ -168,7 +168,10 @@ export class ExternalStoreThreadListRuntimeCore
     this._notifySubscribers();
   }
 
-  public async switchToThread(threadId: string): Promise<void> {
+  public async switchToThread(
+    threadId: string,
+    _options?: { unarchive?: boolean },
+  ): Promise<void> {
     if (this._mainThreadId === threadId) return;
     const onSwitchToThread = this.adapter.onSwitchToThread;
     if (!onSwitchToThread)

package/src/store/runtime-clients/thread-list-runtime-client.ts

@@ -81,8 +81,8 @@ export const ThreadListClient = resource(
           : state.threadIds[index]!;
         return threadItems.get({ key: id });
       },
-      switchToThread: async (threadId) => {
-        await runtime.switchToThread(threadId);
+      switchToThread: async (threadId, options) => {
+        await runtime.switchToThread(threadId, options);
       },
       switchToNewThread: async () => {
         await runtime.switchToNewThread();

package/src/store/scopes/thread-list-item.ts

@@ -12,7 +12,7 @@ export type ThreadListItemState = {
 
 export type ThreadListItemMethods = {
   getState(): ThreadListItemState;
-  switchTo(): void;
+  switchTo(options?: { unarchive?: boolean }): void;
   rename(newTitle: string): void;
   archive(): void;
   unarchive(): void;

package/src/store/scopes/threads.ts

@@ -19,7 +19,7 @@ export type ThreadsState = {
 
 export type ThreadsMethods = {
   getState(): ThreadsState;
-  switchToThread(threadId: string): void;
+  switchToThread(threadId: string, options?: { unarchive?: boolean }): void;
   switchToNewThread(): void;
   item(
     threadIdOrOptions: