@assistant-ui/core 0.3.0 → 0.3.2

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/model-context/useInteractable.ts

@@ -90,14 +90,10 @@ const useInteractable = <TSchema extends Unstable_InteractableStateSchema>(
 
   const autoId = useId().replace(/[^a-zA-Z0-9]/g, "");
 
-  // Whether this component renders inside a message part is fixed for its
-  // lifetime, so conditioning the selectors on it is safe.
-  const inPart = aui.part.source != null;
   const updateToolName = interactableToolName(name);
   const part = useAuiState((s) => {
-    if (!inPart) return undefined;
-    const p = s.part;
-    return p.type === "tool-call" ? p : undefined;
+    const p = s.optional.part;
+    return p?.type === "tool-call" ? p : undefined;
   });
 
   // Inside an update_{name} part, the instance id comes from the call itself:

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/local/local-thread-runtime-core.test.ts

@@ -497,6 +497,44 @@ describe("LocalThreadRuntimeCore tool approvals", () => {
 });
 
 describe("LocalThreadRuntimeCore cancellation", () => {
+  it("keeps a replacement run cancellable after the previous run settles", async () => {
+    let releaseFirst!: () => void;
+    let releaseSecond!: () => void;
+    const firstGate = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    const secondGate = new Promise<void>((resolve) => {
+      releaseSecond = resolve;
+    });
+    const signals: AbortSignal[] = [];
+    const thread = createThread({
+      async *run({ abortSignal }) {
+        signals.push(abortSignal);
+        await (signals.length === 1 ? firstGate : secondGate);
+      },
+    });
+
+    const firstAppend = thread.append(userMessage("first"));
+    await flush();
+    const secondAppend = thread.append(userMessage("second"));
+    await flush();
+
+    expect(signals).toHaveLength(2);
+    expect(signals[0]?.aborted).toBe(true);
+    expect(signals[1]?.aborted).toBe(false);
+
+    releaseFirst();
+    await firstAppend;
+
+    thread.cancelRun();
+    const replacementWasAborted = signals[1]?.aborted;
+
+    releaseSecond();
+    await secondAppend;
+
+    expect(replacementWasAborted).toBe(true);
+  });
+
   it("marks the message cancelled when a streaming adapter returns after abort", async () => {
     let released!: () => void;
     const streaming = new Promise<void>((resolve) => {

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -459,7 +459,8 @@ export class LocalThreadRuntimeCore
 
     // abort existing run
     this.abortController?.abort();
-    this.abortController = new AbortController();
+    const abortController = new AbortController();
+    this.abortController = abortController;
 
     const initialContent = message.content;
     const initialAnnotations = message.metadata?.unstable_annotations;
@@ -550,7 +551,7 @@ export class LocalThreadRuntimeCore
         runCallback ??
         this.adapters.chatModel.run.bind(this.adapters.chatModel);
 
-      const abortSignal = this.abortController.signal;
+      const abortSignal = abortController.signal;
       const threadId = this._getThreadId?.();
       const promiseOrGenerator = runCallback({
         messages,
@@ -609,7 +610,9 @@ export class LocalThreadRuntimeCore
         throw e;
       }
     } finally {
-      this.abortController = null;
+      if (this.abortController === abortController) {
+        this.abortController = null;
+      }
 
       const history = this._options.adapters.history;
       const item = {

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;

package/src/tests/remote-thread-list-reactive-threadId.test.ts

@@ -2,98 +2,6 @@ import { describe, it, expect, vi } from "vitest";
 import type { RemoteThreadListAdapter } from "../runtimes/remote-thread-list/types";
 import { createCore, makeAdapter } from "./remote-thread-list-test-helpers";
 
-/**
- * Tests for the reactive threadId useEffect logic in useRemoteThreadListRuntime.
- *
- * The useEffect compares options.threadId against a prevThreadIdRef and calls
- * switchToThread or switchToNewThread when it changes. We test this logic
- * by simulating the ref + comparison pattern.
- */
-
-// Mirrors the useEffect in useRemoteThreadListRuntimeImpl.
-// Keep in sync if that implementation changes.
-function simulateThreadIdEffect(
-  prevRef: { current: string | undefined },
-  threadId: string | undefined,
-  switchToThread: (id: string) => void,
-  switchToNewThread: () => void,
-) {
-  if (threadId === prevRef.current) return;
-  prevRef.current = threadId;
-  if (threadId) {
-    switchToThread(threadId);
-  } else {
-    switchToNewThread();
-  }
-}
-
-describe("threadId reactive effect", () => {
-  it("does nothing when threadId stays the same", () => {
-    const ref = { current: "thread-1" };
-    const switchToThread = vi.fn();
-    const switchToNewThread = vi.fn();
-
-    simulateThreadIdEffect(ref, "thread-1", switchToThread, switchToNewThread);
-
-    expect(switchToThread).not.toHaveBeenCalled();
-    expect(switchToNewThread).not.toHaveBeenCalled();
-  });
-
-  it("calls switchToThread when threadId changes", () => {
-    const ref = { current: "thread-1" };
-    const switchToThread = vi.fn();
-    const switchToNewThread = vi.fn();
-
-    simulateThreadIdEffect(ref, "thread-2", switchToThread, switchToNewThread);
-
-    expect(switchToThread).toHaveBeenCalledWith("thread-2");
-    expect(ref.current).toBe("thread-2");
-  });
-
-  it("calls switchToNewThread when threadId becomes undefined", () => {
-    const ref = { current: "thread-1" };
-    const switchToThread = vi.fn();
-    const switchToNewThread = vi.fn();
-
-    simulateThreadIdEffect(ref, undefined, switchToThread, switchToNewThread);
-
-    expect(switchToNewThread).toHaveBeenCalledOnce();
-    expect(ref.current).toBeUndefined();
-  });
-
-  it("skips switchToNewThread on first render when threadId is already undefined", () => {
-    const ref = { current: undefined as string | undefined };
-    const switchToThread = vi.fn();
-    const switchToNewThread = vi.fn();
-
-    // First render: undefined === undefined → skipped
-    simulateThreadIdEffect(ref, undefined, switchToThread, switchToNewThread);
-    expect(switchToNewThread).not.toHaveBeenCalled();
-  });
-
-  it("handles full navigation cycle", () => {
-    const ref = { current: undefined as string | undefined };
-    const switchToThread = vi.fn();
-    const switchToNewThread = vi.fn();
-
-    // Mount with thread-1
-    simulateThreadIdEffect(ref, "thread-1", switchToThread, switchToNewThread);
-    expect(switchToThread).toHaveBeenCalledWith("thread-1");
-
-    // Navigate to thread-2
-    simulateThreadIdEffect(ref, "thread-2", switchToThread, switchToNewThread);
-    expect(switchToThread).toHaveBeenCalledWith("thread-2");
-
-    // Navigate to new thread
-    simulateThreadIdEffect(ref, undefined, switchToThread, switchToNewThread);
-    expect(switchToNewThread).toHaveBeenCalledOnce();
-
-    // Navigate back to thread-1
-    simulateThreadIdEffect(ref, "thread-1", switchToThread, switchToNewThread);
-    expect(switchToThread).toHaveBeenCalledTimes(3);
-  });
-});
-
 /**
  * Tests for onThreadIdChange, driving the real
  * RemoteThreadListThreadListRuntimeCore via a mock adapter (no React). These

package/src/tests/thread-message-like.test.ts

@@ -159,6 +159,21 @@ describe("fromThreadMessageLike", () => {
 
       expect(result.content).toEqual([]);
     });
+
+    it("keeps an image part with an uppercase-scheme data URL", () => {
+      const result = fromThreadMessageLike(
+        {
+          role: "assistant",
+          content: [{ type: "image", image: "DATA:IMAGE/PNG;base64,AAAA" }],
+        },
+        fallbackId,
+        fallbackStatus,
+      );
+
+      expect(result.content).toEqual([
+        { type: "image", image: "DATA:IMAGE/PNG;base64,AAAA" },
+      ]);
+    });
   });
 
   describe("providerMetadata passthrough", () => {