@assistant-ui/core 0.3.1 → 0.3.2

package/dist/utils/data-url.js

@@ -1,10 +1,10 @@
 //#region src/utils/data-url.ts
 const httpUrlPattern = /^https?:\/\//i;
 function parseDataUrl(value) {
-	const match = value.match(/^data:([^;,]+)(?:;[^;,]+)*;base64,(.+)$/);
+	const match = value.match(/^data:([^;,]+)(?:;[^;,]+)*;base64,(.*)$/i);
 	if (!match) return null;
 	return {
-		mimeType: match[1],
+		mimeType: match[1].toLowerCase(),
 		data: match[2]
 	};
 }

package/dist/utils/data-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-url.js","names":["httpUrlPattern","parseDataUrl","value","mimeType","data","match"],"sources":["../../src/utils/data-url.ts"],"sourcesContent":["export const httpUrlPattern = /^https?:\\/\\//i;\n\nexport function parseDataUrl(\n  value: string,\n): { mimeType: string; data: string } | null {\n  const match = value.match(/^data:([^;,]+)(?:;[^;,]+)*;base64,(.+)$/);\n  if (!match) return null;\n  return { mimeType: match[1]!, data: match[2]! };\n}\n"],"mappings":";AAAA,MAAaA,iBAAiB;AAE9B,SAAgBC,aACdC,OAC2C;CAC3C,MAAMG,QAAQH,MAAMG,MAAM,yCAAyC;CACnE,IAAI,CAACA,OAAO,OAAO;CACnB,OAAO;EAAEF,UAAUE,MAAM;EAAKD,MAAMC,MAAM;CAAI;AAChD"}
+{"version":3,"file":"data-url.js","names":["httpUrlPattern","parseDataUrl","value","mimeType","data","match","toLowerCase"],"sources":["../../src/utils/data-url.ts"],"sourcesContent":["export const httpUrlPattern = /^https?:\\/\\//i;\n\nexport function parseDataUrl(\n  value: string,\n): { mimeType: string; data: string } | null {\n  const match = value.match(/^data:([^;,]+)(?:;[^;,]+)*;base64,(.*)$/i);\n  if (!match) return null;\n  return { mimeType: match[1]!.toLowerCase(), data: match[2]! };\n}\n"],"mappings":";AAAA,MAAaA,iBAAiB;AAE9B,SAAgBC,aACdC,OAC2C;CAC3C,MAAMG,QAAQH,MAAMG,MAAM,0CAA0C;CACpE,IAAI,CAACA,OAAO,OAAO;CACnB,OAAO;EAAEF,UAAUE,MAAM,EAAE,CAAEC,YAAY;EAAGF,MAAMC,MAAM;CAAI;AAC9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,7 +59,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.30",
+    "assistant-stream": "^0.3.31",
     "nanoid": "^6.0.0"
   },
   "optionalDevDependencies": {
@@ -95,8 +95,8 @@
     "react-dom": "^19.2.8",
     "vitest": "^4.1.10",
     "zustand": "^5.0.14",
-    "@assistant-ui/store": "0.3.1",
-    "@assistant-ui/tap": "0.9.7",
+    "@assistant-ui/store": "0.3.2",
+    "@assistant-ui/tap": "0.9.8",
     "@assistant-ui/vite": "0.0.11",
     "@assistant-ui/x-buildutils": "0.0.20",
     "assistant-cloud": "0.1.37"

package/src/internal.ts

@@ -58,12 +58,5 @@ export { isJSONValue, isRecord } from "./utils/json/is-json";
 // outbound part conversion lives in one place.
 export { httpUrlPattern, parseDataUrl } from "./utils/data-url";
 
-// Runtime extras helper for external-store adapters. Internal because the
-// tap-native runtime path replaces the `thread.extras` side-channel it wraps.
-export {
-  createRuntimeExtras,
-  type RuntimeExtras,
-} from "./react/runtimes/createRuntimeExtras";
-
 export * from "./runtime/internal";
 export * from "./runtimes/internal";

package/src/react/AssistantProvider.tsx

@@ -19,24 +19,37 @@ export type AssistantProviderBaseProps = PropsWithChildren<{
   aui?: AssistantClient | null;
 }>;
 
+const AssistantProviderInner: FC<
+  PropsWithChildren<{ runtime: AssistantRuntime }>
+> = ({ runtime, children }) => {
+  // The runtime has a stable identity but mutates in place: its options are
+  // pushed in by an unconditional effect inside <RenderComponent />, so that
+  // element must be re-created every commit for React to re-render it and
+  // re-run the effect. React Compiler caches <RenderComponent /> on the
+  // stable RenderComponent type, which silences the effect and stops option
+  // changes (e.g. unstable_enableMessageQueue) from reaching the runtime.
+  "use no memo";
+  const aui = useAui({ threads: RuntimeAdapter(runtime) });
+  const RenderComponent = getRenderComponent(runtime);
+  return (
+    <AuiProvider value={aui}>
+      {RenderComponent && <RenderComponent />}
+      {children}
+    </AuiProvider>
+  );
+};
+
 export const AssistantProviderBase: FC<AssistantProviderBaseProps> = memo(
-  ({ runtime, aui: parent = null, children }) => {
-    // The runtime has a stable identity but mutates in place: its options are
-    // pushed in by an unconditional effect inside <RenderComponent />, so that
-    // element must be re-created every commit for React to re-render it and
-    // re-run the effect. React Compiler caches <RenderComponent /> on the
-    // stable RenderComponent type, which silences the effect and stops option
-    // changes (e.g. unstable_enableMessageQueue) from reaching the runtime.
-    "use no memo";
-    const aui = useAui({ threads: RuntimeAdapter(runtime) }, { parent });
-    const RenderComponent = getRenderComponent(runtime);
+  ({ runtime, aui = null, children }) => {
     const inner = (
-      <AuiProvider value={aui}>
-        {RenderComponent && <RenderComponent />}
+      <AssistantProviderInner runtime={runtime}>
         {children}
-      </AuiProvider>
+      </AssistantProviderInner>
+    );
+    return aui ? (
+      <AuiProvider value={aui}>{inner}</AuiProvider>
+    ) : (
+      <AuiProvider value={null}>{inner}</AuiProvider>
     );
-    if (!parent) return inner;
-    return <AuiProvider value={parent}>{inner}</AuiProvider>;
   },
 );

package/src/react/AssistantRuntimeProvider.test.tsx

@@ -0,0 +1,101 @@
+// @vitest-environment jsdom
+
+import type { ReactNode } from "react";
+import { useEffect } from "react";
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { resource } from "@assistant-ui/tap";
+import { AuiProvider, useAui, type AssistantClient } from "@assistant-ui/store";
+import type { ChatModelAdapter } from "../runtime/utils/chat-model-adapter";
+import { AssistantRuntimeProvider } from "./AssistantRuntimeProvider";
+import { useLocalRuntime } from "./runtimes/useLocalRuntime";
+
+type AnyClient = Record<string, any>;
+
+const chatModel: ChatModelAdapter = {
+  run: async () => ({ content: [] }),
+};
+
+const makeCounterClient = (log?: string[]) => {
+  const useCounterClient = () => {
+    useEffect(() => {
+      log?.push("parent tap effect");
+    }, []);
+    return { getState: () => ({ count: 0 }) };
+  };
+  return resource(useCounterClient);
+};
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("AssistantRuntimeProvider aui composition", () => {
+  it("isolates from ambient context by default", () => {
+    let aui!: AnyClient;
+    const Consumer = () => {
+      aui = useAui();
+      return null;
+    };
+
+    const Ambient = ({ children }: { children: ReactNode }) => {
+      const ambient = useAui({
+        parentScope: makeCounterClient()(),
+      } as unknown as useAui.Props);
+      return <AuiProvider value={ambient}>{children}</AuiProvider>;
+    };
+
+    const App = () => {
+      const runtime = useLocalRuntime(chatModel);
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <Consumer />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(
+      <Ambient>
+        <App />
+      </Ambient>,
+    );
+
+    expect(aui.threads).toBeDefined();
+    expect(() => aui.parentScope.getState()).toThrow(
+      /The current scope does not have a "parentScope" property/,
+    );
+  });
+
+  it("inherits a prop-passed parent and mounts its effects", () => {
+    const log: string[] = [];
+    let aui!: AnyClient;
+    const Consumer = () => {
+      aui = useAui();
+      useEffect(() => {
+        log.push("consumer effect");
+      }, []);
+      return null;
+    };
+
+    const App = ({ parent }: { parent: AssistantClient }) => {
+      const runtime = useLocalRuntime(chatModel);
+      return (
+        <AssistantRuntimeProvider runtime={runtime} aui={parent}>
+          <Consumer />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    const Root = () => {
+      const parent = useAui({
+        parentScope: makeCounterClient(log)(),
+      } as unknown as useAui.Props);
+      return <App parent={parent} />;
+    };
+
+    render(<Root />);
+
+    expect(aui.parentScope.getState()).toEqual({ count: 0 });
+    expect(log).toEqual(["parent tap effect", "consumer effect"]);
+  });
+});

package/src/react/adapters/LocalStorageThreadListAdapter.tsx

@@ -1,5 +1,12 @@
 import { type AssistantStream, createAssistantStream } from "assistant-stream";
-import { type FC, type PropsWithChildren, useMemo } from "react";
+import {
+  type FC,
+  type PropsWithChildren,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { useAui } from "@assistant-ui/store";
 import type {
   RemoteThreadInitializeResponse,
@@ -276,22 +283,26 @@ export const parseStoredMessageRepository = (
 
 class AsyncStorageHistoryAdapter implements ThreadHistoryAdapter {
   private storage: AsyncStorageLike;
-  private aui: ReturnType<typeof useAui>;
+  private getAui: () => ReturnType<typeof useAui>;
   private prefix: string;
   private mutationQueue: KeyedMutationQueue;
 
   constructor(
     storage: AsyncStorageLike,
-    aui: ReturnType<typeof useAui>,
+    getAui: () => ReturnType<typeof useAui>,
     prefix: string,
     mutationQueue: KeyedMutationQueue,
   ) {
     this.storage = storage;
-    this.aui = aui;
+    this.getAui = getAui;
     this.prefix = prefix;
     this.mutationQueue = mutationQueue;
   }
 
+  private get aui(): ReturnType<typeof useAui> {
+    return this.getAui();
+  }
+
   private _messagesKey(remoteId: string) {
     return `${this.prefix}messages:${remoteId}`;
   }
@@ -334,9 +345,19 @@ const createHistoryProvider = (
 ): FC<PropsWithChildren> => {
   const Provider: FC<PropsWithChildren> = ({ children }) => {
     const aui = useAui();
-    const history = useMemo(
-      () => new AsyncStorageHistoryAdapter(storage, aui, prefix, mutationQueue),
-      [aui],
+    // Not useEffectEvent: history adapter methods run during render (SSR load).
+    const auiRef = useRef(aui);
+    useEffect(() => {
+      auiRef.current = aui;
+    });
+    const [history] = useState(
+      () =>
+        new AsyncStorageHistoryAdapter(
+          storage,
+          () => auiRef.current,
+          prefix,
+          mutationQueue,
+        ),
     );
     const adapters = useMemo(() => ({ history }), [history]);
 

package/src/react/index.ts

@@ -226,6 +226,10 @@ export {
   type StreamingTimingOptions,
   type StreamingTimingState,
 } from "./runtimes/useStreamingTiming";
+export {
+  createRuntimeExtras,
+  type RuntimeExtras,
+} from "./runtimes/createRuntimeExtras";
 export { RemoteThreadListHookInstanceManager } from "./runtimes/RemoteThreadListHookInstanceManager";
 export { RemoteThreadListThreadListRuntimeCore } from "./runtimes/RemoteThreadListThreadListRuntimeCore";
 export { useRemoteThreadListRuntime } from "./runtimes/useRemoteThreadListRuntime";

package/src/react/runtimes/RemoteThreadListHookInstanceManager.tsx

@@ -4,6 +4,7 @@ import {
   useCallback,
   useRef,
   useEffect,
+  useEffectEvent,
   useLayoutEffect,
   memo,
   type PropsWithChildren,
@@ -142,23 +143,25 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
       }
     }, [threadBinding]);
 
-    useEffect(() => {
-      hasInitializedRef.current = false;
-      return runtime.threads.main.unstable_on("initialize", () => {
-        if (hasInitializedRef.current) return;
+    const handleInitialize = useEffectEvent(() => {
+      if (hasInitializedRef.current) return;
 
-        const state = aui.threadListItem.getState();
-        if (state.status !== "new") return;
-        hasInitializedRef.current = true;
+      const state = aui.threadListItem.getState();
+      if (state.status !== "new") return;
+      hasInitializedRef.current = true;
 
-        initPromiseRef.current = aui.threadListItem.initialize();
+      initPromiseRef.current = aui.threadListItem.initialize();
 
-        const dispose = runtime.thread.unstable_on("runEnd", () => {
-          dispose();
-          aui.threadListItem.generateTitle();
-        });
+      const dispose = runtime.thread.unstable_on("runEnd", () => {
+        dispose();
+        aui.threadListItem.generateTitle();
       });
-    }, [runtime, aui]);
+    });
+
+    useEffect(() => {
+      hasInitializedRef.current = false;
+      return runtime.threads.main.unstable_on("initialize", handleInitialize);
+    }, [runtime]);
 
     return <>{children}</>;
   };

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.tsx

@@ -200,6 +200,10 @@ export class RemoteThreadListThreadListRuntimeCore
 
     const adapterChanged =
       this._options !== undefined && this._options.adapter !== options.adapter;
+    const controlledThreadIdChanged =
+      this._initialThreadLoaded &&
+      this._options !== undefined &&
+      this._options.threadId !== options.threadId;
 
     this._options = options;
 
@@ -219,15 +223,25 @@ export class RemoteThreadListThreadListRuntimeCore
         cursor: undefined,
       });
     }
+
+    if (controlledThreadIdChanged) {
+      this._switchToThreadFromProp(options.threadId).catch(() => {});
+    }
   }
 
   public __internal_load() {
     this.getLoadThreadsPromise(); // begin loading on initial bind
+    if (this._initialThreadLoaded) return;
+    this._initialThreadLoaded = true;
+
     const startThreadId =
       this._options.threadId ?? this._options.initialThreadId;
-    if (!this._initialThreadLoaded && startThreadId) {
-      this._initialThreadLoaded = true;
-      this.switchToThread(startThreadId).catch(() => {});
+    if (startThreadId !== undefined) {
+      const switchTask =
+        this._options.threadId !== undefined
+          ? this._switchToThreadFromProp(startThreadId)
+          : this.switchToThread(startThreadId);
+      switchTask.catch(() => {});
     }
   }
 
@@ -279,11 +293,13 @@ export class RemoteThreadListThreadListRuntimeCore
 
   private _lastNotifiedThreadId: string | undefined = undefined;
 
-  private _notifyThreadIdChange() {
+  private _notifyThreadIdChange(emit = true) {
     const threadId = this._mainThreadRemoteId;
     if (this._lastNotifiedThreadId === threadId) return;
     this._lastNotifiedThreadId = threadId;
-    this._options.onThreadIdChange?.(threadId);
+    if (emit) {
+      this._options.onThreadIdChange?.(threadId);
+    }
   }
 
   public getMainThreadRuntimeCore() {
@@ -312,9 +328,22 @@ export class RemoteThreadListThreadListRuntimeCore
   public switchToThread(
     threadIdOrRemoteId: string,
     options?: { unarchive?: boolean },
+  ): Promise<void> {
+    return this._startSwitchToThread(threadIdOrRemoteId, options, true);
+  }
+
+  private _startSwitchToThread(
+    threadIdOrRemoteId: string,
+    options: { unarchive?: boolean } | undefined,
+    emitThreadIdChange: boolean,
   ): Promise<void> {
     const generation = ++this._switchGeneration;
-    const task = this._switchToThread(threadIdOrRemoteId, options, generation);
+    const task = this._switchToThread(
+      threadIdOrRemoteId,
+      options,
+      generation,
+      emitThreadIdChange,
+    );
     this._switchTask = task;
     return task;
   }
@@ -323,6 +352,7 @@ export class RemoteThreadListThreadListRuntimeCore
     threadIdOrRemoteId: string,
     options: { unarchive?: boolean } | undefined,
     generation: number,
+    emitThreadIdChange: boolean,
   ): Promise<void> {
     let data = this.getItemById(threadIdOrRemoteId);
 
@@ -418,17 +448,30 @@ export class RemoteThreadListThreadListRuntimeCore
     this._mainThreadId = data.id;
 
     this._notifySubscribers();
-    this._notifyThreadIdChange();
+    this._notifyThreadIdChange(emitThreadIdChange);
   }
 
   public switchToNewThread(): Promise<void> {
+    return this._startSwitchToNewThread(true);
+  }
+
+  private _switchToThreadFromProp(threadId: string | undefined): Promise<void> {
+    return threadId !== undefined
+      ? this._startSwitchToThread(threadId, undefined, false)
+      : this._startSwitchToNewThread(false);
+  }
+
+  private _startSwitchToNewThread(emitThreadIdChange: boolean): Promise<void> {
     const generation = ++this._switchGeneration;
-    const task = this._switchToNewThread(generation);
+    const task = this._switchToNewThread(generation, emitThreadIdChange);
     this._switchTask = task;
     return task;
   }
 
-  private async _switchToNewThread(generation: number): Promise<void> {
+  private async _switchToNewThread(
+    generation: number,
+    emitThreadIdChange: boolean,
+  ): Promise<void> {
     // an initialization transaction is in progress, wait for it to settle
     while (
       this._state.baseValue.newThreadId !== undefined &&
@@ -467,7 +510,7 @@ export class RemoteThreadListThreadListRuntimeCore
       });
     }
 
-    return this._switchToThread(id, undefined, generation);
+    return this._switchToThread(id, undefined, generation, emitThreadIdChange);
   }
 
   public initialize = async (threadId: string) => {

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

@@ -22,18 +22,18 @@ const globalPersistence = new WeakMap<
 
 class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
   private cloudRef: RefObject<AssistantCloud>;
-  private auiRef: RefObject<AssistantClient>;
+  private getAui: () => AssistantClient;
 
   constructor(
     cloudRef: RefObject<AssistantCloud>,
-    auiRef: RefObject<AssistantClient>,
+    getAui: () => AssistantClient,
   ) {
     this.cloudRef = cloudRef;
-    this.auiRef = auiRef;
+    this.getAui = getAui;
   }
 
   private get aui(): AssistantClient {
-    return this.auiRef.current;
+    return this.getAui();
   }
 
   private get _persistence(): CloudMessagePersistence {
@@ -816,12 +816,14 @@ export function useAssistantCloudThreadHistoryAdapter(
   cloudRef: RefObject<AssistantCloud>,
 ): ThreadHistoryAdapter {
   const aui = useAui();
+  // Not useEffectEvent: history adapter methods run during render (SSR load).
   const auiRef = useRef(aui);
   useEffect(() => {
     auiRef.current = aui;
   });
   const [adapter] = useState(
-    () => new AssistantCloudThreadHistoryAdapter(cloudRef, auiRef),
+    () =>
+      new AssistantCloudThreadHistoryAdapter(cloudRef, () => auiRef.current),
   );
   return adapter;
 }

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -51,8 +51,7 @@ export const useRemoteThreadListRuntime = (
   const runtimeHookRef = useRef(options.runtimeHook);
   runtimeHookRef.current = options.runtimeHook;
 
-  // threadId/initialThreadId only affect the constructor; capture once via ref
-  const startThreadIdRef = useRef(options.threadId ?? options.initialThreadId);
+  const initialThreadIdRef = useRef(options.initialThreadId);
 
   const stableRuntimeHook = useCallback(() => {
     return runtimeHookRef.current();
@@ -66,11 +65,17 @@ export const useRemoteThreadListRuntime = (
     () => ({
       adapter: options.adapter,
       allowNesting: options.allowNesting,
-      initialThreadId: startThreadIdRef.current,
+      threadId: options.threadId,
+      initialThreadId: initialThreadIdRef.current,
       runtimeHook: stableRuntimeHook,
       onThreadIdChange,
     }),
-    [options.adapter, options.allowNesting, stableRuntimeHook],
+    [
+      options.adapter,
+      options.allowNesting,
+      options.threadId,
+      stableRuntimeHook,
+    ],
   );
 
   const aui = useAui();
@@ -91,16 +96,5 @@ export const useRemoteThreadListRuntime = (
 
   const runtime = useRemoteThreadListRuntimeImpl(stableOptions);
 
-  const prevThreadIdRef = useRef(options.threadId);
-  useEffect(() => {
-    if (options.threadId === prevThreadIdRef.current) return;
-    prevThreadIdRef.current = options.threadId;
-    if (options.threadId) {
-      runtime.threads.switchToThread(options.threadId).catch(() => {});
-    } else {
-      runtime.threads.switchToNewThread().catch(() => {});
-    }
-  }, [runtime, options.threadId]);
-
   return runtime;
 };

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

@@ -131,12 +131,12 @@ export const fromThreadMessageLike = (
   }: ImageMessagePart): ImageMessagePart | null => {
     if (typeof image !== "string") return null;
     const dataUri = image.match(
-      /^data:image\/(png|jpeg|jpg|gif|webp|svg\+xml);base64,(.*)$/,
+      /^data:image\/(png|jpeg|jpg|gif|webp|svg\+xml);base64,(.*)$/i,
     );
     if (dataUri) {
       return { ...rest, image };
     }
-    if (/^(https:\/\/|blob:)/.test(image)) {
+    if (/^(https:\/\/|blob:)/i.test(image)) {
       return { ...rest, image };
     }
     console.warn(`Invalid image data format detected`);

package/src/runtimes/remote-thread-list/types.ts

@@ -78,10 +78,11 @@ export type RemoteThreadListOptions = {
   threadId?: string | undefined;
 
   /**
-   * Called whenever the active thread's canonical (remote) ID changes, so the
-   * value can be treated as a managed/controlled variable (e.g. synced to a
-   * URL query param). Together with `threadId` this forms the controlled
-   * pattern: `threadId` in, `onThreadIdChange` out.
+   * Called whenever the runtime changes the active thread's canonical (remote)
+   * ID, so the value can be treated as a managed/controlled variable (e.g.
+   * synced to a URL query param). Changes initiated by the controlled
+   * `threadId` option are not echoed back. Together these options form the
+   * controlled pattern: `threadId` in, `onThreadIdChange` out.
    *
    * Only the settled remote ID is emitted: while a freshly created thread is
    * still optimistic (no remote ID yet) the value is `undefined`, and the real

package/src/store/scopes/thread.ts

@@ -108,7 +108,7 @@ export type ThreadMethods = {
    * @param initialMessages - Optional array of initial messages to populate the thread
    */
   reset(initialMessages?: readonly ThreadMessageLike[]): void;
-  importExternalState?(state: unknown): void;
+  importExternalState(state: unknown): void;
   message(selector: { id: string } | { index: number }): MessageMethods;
   /** @deprecated This API is still under active development and might change without notice. */
   stopSpeaking(): void;