@assistant-ui/core 0.3.14 → 0.3.16

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

@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useInteractablePersistenceQueue } from "./useInteractablePersistenceQueue";
+
+type TestState = Record<string, number>;
+
+type PersistenceStatus = {
+  isPending: boolean;
+  error: unknown;
+};
+
+type PersistenceStatusMap = Record<string, PersistenceStatus>;
+
+const createDeferred = () => {
+  let resolve!: () => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<void>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+
+const renderQueue = (save: (state: TestState) => void | Promise<void>) => {
+  let snapshot: TestState = {};
+  let persistence: PersistenceStatusMap = {};
+  const adapterRef = { current: { save } };
+  const updatePersistenceStatus = (
+    updater: (prev: PersistenceStatusMap) => PersistenceStatusMap,
+  ) => {
+    persistence = updater(persistence);
+  };
+  const hook = renderHook(() =>
+    useInteractablePersistenceQueue({
+      adapterRef,
+      snapshot: () => snapshot,
+      updatePersistenceStatus,
+    }),
+  );
+
+  return {
+    ...hook,
+    setState(id: string, value: number) {
+      snapshot = { ...snapshot, [id]: value };
+    },
+    removeStatus(id: string) {
+      const { [id]: _, ...rest } = persistence;
+      persistence = rest;
+    },
+    getStatus() {
+      return persistence;
+    },
+  };
+};
+
+const flushMicrotasks = () => vi.advanceTimersByTimeAsync(0);
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("useInteractablePersistenceQueue", () => {
+  it("coalesces dirty marks inside the debounce window into one save", async () => {
+    const save = vi.fn<(state: TestState) => void>();
+    const queue = renderQueue(save);
+
+    queue.setState("a", 1);
+    act(() => queue.result.current.schedulePersistence("a"));
+    await act(() => vi.advanceTimersByTimeAsync(200));
+
+    queue.setState("b", 2);
+    act(() => queue.result.current.schedulePersistence("b"));
+    await act(() => vi.advanceTimersByTimeAsync(200));
+
+    queue.setState("a", 3);
+    act(() => queue.result.current.schedulePersistence("a"));
+    await act(() => vi.advanceTimersByTimeAsync(499));
+
+    expect(save).not.toHaveBeenCalled();
+
+    await act(() => vi.advanceTimersByTimeAsync(1));
+
+    expect(save).toHaveBeenCalledOnce();
+    expect(save).toHaveBeenCalledWith({ a: 3, b: 2 });
+  });
+
+  it("attributes errors by batch sequence and lets a newer save supersede an older error", async () => {
+    const first = createDeferred();
+    const second = createDeferred();
+    const firstError = new Error("first save failed");
+    const secondError = new Error("second save failed");
+    const save = vi
+      .fn<(state: TestState) => Promise<void>>()
+      .mockImplementationOnce(() => first.promise)
+      .mockImplementationOnce(() => second.promise);
+    const queue = renderQueue(save);
+
+    queue.setState("a", 1);
+    queue.setState("b", 1);
+    act(() => {
+      queue.result.current.schedulePersistence("a");
+      queue.result.current.schedulePersistence("b");
+    });
+    await act(() => vi.advanceTimersByTimeAsync(500));
+
+    queue.setState("a", 2);
+    act(() => queue.result.current.schedulePersistence("a"));
+    let flushPromise!: Promise<void>;
+    act(() => {
+      flushPromise = queue.result.current.flush();
+    });
+
+    first.reject(firstError);
+    await act(flushMicrotasks);
+
+    expect(save).toHaveBeenCalledTimes(2);
+    expect(queue.getStatus()).toEqual({
+      a: { isPending: true, error: undefined },
+      b: { isPending: false, error: firstError },
+    });
+
+    second.reject(secondError);
+    await act(flushMicrotasks);
+    await flushPromise;
+
+    expect(queue.getStatus()).toEqual({
+      a: { isPending: false, error: secondError },
+      b: { isPending: false, error: firstError },
+    });
+  });
+
+  it("does not recreate a removed status when an in-flight save rejects", async () => {
+    const pending = createDeferred();
+    const save = vi
+      .fn<(state: TestState) => Promise<void>>()
+      .mockImplementationOnce(() => pending.promise);
+    const queue = renderQueue(save);
+
+    queue.setState("removed", 1);
+    act(() => queue.result.current.schedulePersistence("removed"));
+    await act(() => vi.advanceTimersByTimeAsync(500));
+
+    expect(queue.getStatus()).toEqual({
+      removed: { isPending: true, error: undefined },
+    });
+
+    queue.removeStatus("removed");
+    pending.reject(new Error("save failed"));
+    await act(flushMicrotasks);
+
+    expect(queue.getStatus()).toEqual({});
+  });
+});

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

@@ -0,0 +1,206 @@
+import { useCallback, useRef, type RefObject } from "react";
+
+const PERSISTENCE_DEBOUNCE_MS = 500;
+
+type PersistenceAdapter<State> = {
+  save(state: State): void | Promise<void>;
+};
+
+type PersistenceStatus = {
+  isPending: boolean;
+  error: unknown;
+};
+
+type PersistenceStatusMap = Record<string, PersistenceStatus>;
+
+type PersistenceStatusUpdater = (
+  updater: (prev: PersistenceStatusMap) => PersistenceStatusMap,
+) => void;
+
+type UseInteractablePersistenceQueueOptions<State> = {
+  adapterRef: RefObject<PersistenceAdapter<State> | undefined>;
+  snapshot: () => State;
+  updatePersistenceStatus: PersistenceStatusUpdater;
+};
+
+export const useInteractablePersistenceQueue = <State>({
+  adapterRef,
+  snapshot,
+  updatePersistenceStatus,
+}: UseInteractablePersistenceQueueOptions<State>) => {
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  const syncSeqRef = useRef(0);
+  const latestSyncSeqByIdRef = useRef(new Map<string, number>());
+  const inFlightPersistenceRef = useRef(0);
+  const flushResolversRef = useRef<Array<() => void>>([]);
+  const dirtyIdsRef = useRef(new Set<string>());
+
+  type PersistenceBatch = {
+    adapter: PersistenceAdapter<State>;
+    payload: State;
+    dirtyIds: Set<string>;
+    seq: number;
+  };
+
+  const outgoingQueueRef = useRef<PersistenceBatch[]>([]);
+  const runPersistenceRef = useRef<(batch?: PersistenceBatch) => void>(
+    () => {},
+  );
+
+  const takeDirtyBatch = useCallback(
+    (adapter: PersistenceAdapter<State>): PersistenceBatch | undefined => {
+      if (dirtyIdsRef.current.size === 0) return;
+      const dirtyIds = new Set(dirtyIdsRef.current);
+      dirtyIdsRef.current.clear();
+      const seq = ++syncSeqRef.current;
+      for (const id of dirtyIds) latestSyncSeqByIdRef.current.set(id, seq);
+      return { adapter, payload: snapshot(), dirtyIds, seq };
+    },
+    [snapshot],
+  );
+
+  const enqueuePersistence = useCallback(
+    (adapter: PersistenceAdapter<State>) => {
+      const batch = takeDirtyBatch(adapter);
+      if (!batch) return;
+      if (inFlightPersistenceRef.current === 0) {
+        runPersistenceRef.current(batch);
+      } else {
+        outgoingQueueRef.current.push(batch);
+      }
+    },
+    [takeDirtyBatch],
+  );
+
+  const runPersistence = useCallback(
+    async (batch?: PersistenceBatch) => {
+      const resolved =
+        batch ??
+        (adapterRef.current ? takeDirtyBatch(adapterRef.current) : undefined);
+      if (!resolved) {
+        if (inFlightPersistenceRef.current === 0) {
+          for (const resolve of flushResolversRef.current) resolve();
+          flushResolversRef.current = [];
+        }
+        return;
+      }
+
+      const { adapter, payload, dirtyIds, seq } = resolved;
+      inFlightPersistenceRef.current += 1;
+
+      updatePersistenceStatus((prev) => ({
+        ...prev,
+        ...Object.fromEntries(
+          [...dirtyIds].map((id) => [
+            id,
+            { isPending: true, error: undefined },
+          ]),
+        ),
+      }));
+
+      const settleBatch = (status: PersistenceStatus | undefined) => {
+        const settledIds: string[] = [];
+        for (const id of dirtyIds) {
+          if (
+            latestSyncSeqByIdRef.current.get(id) !== seq ||
+            dirtyIdsRef.current.has(id)
+          )
+            continue;
+          latestSyncSeqByIdRef.current.delete(id);
+          settledIds.push(id);
+        }
+        if (settledIds.length === 0) return;
+        updatePersistenceStatus((prev) => {
+          let changed = false;
+          const persistence = { ...prev };
+          for (const id of settledIds) {
+            if (prev[id] === undefined) continue;
+            if (status === undefined) delete persistence[id];
+            else persistence[id] = status;
+            changed = true;
+          }
+          return changed ? persistence : prev;
+        });
+      };
+
+      try {
+        await adapter.save(payload);
+        settleBatch(undefined);
+      } catch (e) {
+        settleBatch({ isPending: false, error: e });
+      } finally {
+        inFlightPersistenceRef.current -= 1;
+        const next =
+          outgoingQueueRef.current.shift() ??
+          (adapterRef.current && dirtyIdsRef.current.size > 0
+            ? takeDirtyBatch(adapterRef.current)
+            : undefined);
+        if (next) {
+          if (debounceTimerRef.current !== undefined) {
+            clearTimeout(debounceTimerRef.current);
+            debounceTimerRef.current = undefined;
+          }
+          runPersistenceRef.current(next);
+        } else if (inFlightPersistenceRef.current === 0) {
+          for (const resolve of flushResolversRef.current) resolve();
+          flushResolversRef.current = [];
+        }
+      }
+    },
+    [adapterRef, takeDirtyBatch, updatePersistenceStatus],
+  );
+  runPersistenceRef.current = (nextBatch) => {
+    void runPersistence(nextBatch);
+  };
+
+  const flushIfPending = useCallback(() => {
+    if (debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+    if (adapterRef.current) enqueuePersistence(adapterRef.current);
+  }, [adapterRef, enqueuePersistence]);
+
+  const schedulePersistence = useCallback(
+    (id: string) => {
+      if (!adapterRef.current) return;
+      dirtyIdsRef.current.add(id);
+      if (debounceTimerRef.current !== undefined) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        debounceTimerRef.current = undefined;
+        if (inFlightPersistenceRef.current === 0 && adapterRef.current) {
+          enqueuePersistence(adapterRef.current);
+        } else {
+          debounceTimerRef.current = setTimeout(() => {
+            debounceTimerRef.current = undefined;
+            if (adapterRef.current) enqueuePersistence(adapterRef.current);
+          }, PERSISTENCE_DEBOUNCE_MS);
+        }
+      }, PERSISTENCE_DEBOUNCE_MS);
+    },
+    [adapterRef, enqueuePersistence],
+  );
+
+  const flush = useCallback(async () => {
+    if (debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+    const hasWork =
+      inFlightPersistenceRef.current > 0 ||
+      dirtyIdsRef.current.size > 0 ||
+      outgoingQueueRef.current.length > 0;
+    if (!hasWork) return;
+    const p = new Promise<void>((resolve) => {
+      flushResolversRef.current.push(resolve);
+    });
+    if (adapterRef.current) enqueuePersistence(adapterRef.current);
+    return p;
+  }, [adapterRef, enqueuePersistence]);
+
+  return { flushIfPending, schedulePersistence, flush };
+};

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

@@ -82,6 +82,21 @@ describe("useActionBarCopy", () => {
     expect(mocks.setIsCopied).not.toHaveBeenCalled();
   });
 
+  it("does not report copy success when the clipboard handler throws synchronously", async () => {
+    const copyToClipboard = vi.fn(() => {
+      throw new TypeError(
+        "Cannot read properties of undefined (reading 'writeText')",
+      );
+    });
+    const { result } = renderHook(() => useActionBarCopy({ copyToClipboard }));
+
+    expect(() => result.current.copy()).not.toThrow();
+    await Promise.resolve();
+
+    expect(copyToClipboard).toHaveBeenCalledWith("Hello");
+    expect(mocks.setIsCopied).not.toHaveBeenCalled();
+  });
+
   it("keeps copy success visible for the full duration after copying again", async () => {
     vi.useFakeTimers();
     const copyToClipboard = vi.fn();

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

@@ -40,9 +40,19 @@ export const useActionBarCopy = ({
     if (!valueToCopy) return;
     const scopeGeneration = scopeGenerationRef.current;
 
-    // The rejection handler swallows clipboard write failures (permission denied,
-    // API unavailable) so they don't surface as unhandled promise rejections.
-    Promise.resolve(copyToClipboard(valueToCopy)).then(
+    // The writer runs synchronously inside the press so the user-gesture gating
+    // of navigator.clipboard survives (WebKit scopes it to the stack); the try
+    // contains a synchronously throwing caller-supplied writer, and the rejection
+    // handler swallows clipboard failures (permission denied, API unavailable) so
+    // they don't surface as unhandled rejections.
+    let write: void | Promise<void>;
+    try {
+      write = copyToClipboard(valueToCopy);
+    } catch {
+      return;
+    }
+
+    Promise.resolve(write).then(
       () => {
         if (scopeGeneration !== scopeGenerationRef.current) return;
 

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

@@ -1,5 +1,8 @@
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use `useAuiState((s) => s.thread.isEmpty)` instead.
+ */
 export const useThreadIsEmpty = (): boolean => {
   return useAuiState((s) => s.thread.isEmpty);
 };

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

@@ -1,5 +1,8 @@
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use `useAuiState((s) => s.thread.isRunning)` instead.
+ */
 export const useThreadIsRunning = (): boolean => {
   return useAuiState((s) => s.thread.isRunning);
 };

package/src/react/runtimes/RemoteThreadListHookInstanceManager.tsx

@@ -173,6 +173,18 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
       this._trackRunning(instance);
     }
     this._notifySubscribers();
+    if (previousRuntime !== undefined && previousRuntime !== runtime) {
+      for (const callback of this.replacedSubscribers) callback();
+    }
+  }
+
+  private replacedSubscribers = new Set<() => void>();
+
+  public __internal_subscribeRuntimeReplaced(
+    callback: () => void,
+  ): Unsubscribe {
+    this.replacedSubscribers.add(callback);
+    return () => this.replacedSubscribers.delete(callback);
   }
 
   private _trackRunning(instance: RemoteThreadListHookInstance) {

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.republish.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { RemoteThreadListThreadListRuntimeCore } from "./RemoteThreadListThreadListRuntimeCore";
+import { ThreadListRuntimeImpl } from "../../runtime/api/thread-list-runtime";
+import { ReadonlyThreadRuntimeCore } from "../../runtimes/readonly/ReadonlyThreadRuntimeCore";
+import {
+  contextProvider,
+  makeAdapter,
+} from "../../tests/remote-thread-list-test-helpers";
+import type { ThreadMessage } from "../../types/message";
+
+const message = (id: string): ThreadMessage =>
+  ({
+    id,
+    role: "user",
+    content: [{ type: "text", text: id }],
+    createdAt: new Date(0),
+    attachments: [],
+    metadata: { custom: {} },
+  }) as unknown as ThreadMessage;
+
+const setup = () => {
+  const core = new RemoteThreadListThreadListRuntimeCore(
+    { adapter: makeAdapter(), runtimeHook: () => ({}) as never },
+    contextProvider,
+  );
+  const hookManager = (
+    core as unknown as {
+      _hookManager: {
+        _publishThreadRuntime: (
+          id: string,
+          runtime: ReadonlyThreadRuntimeCore,
+          generation: number,
+        ) => void;
+        instances: Map<string, { generation: number }>;
+      };
+    }
+  )._hookManager;
+  const threadId = core.mainThreadId!;
+  const publish = (runtime: ReadonlyThreadRuntimeCore) =>
+    hookManager._publishThreadRuntime(
+      threadId,
+      runtime,
+      hookManager.instances.get(threadId)!.generation,
+    );
+  return { core, publish };
+};
+
+describe("RemoteThreadListThreadListRuntimeCore republish", () => {
+  it("keeps the subscribed main thread state on the republished core", async () => {
+    const { core, publish } = setup();
+    const first = new ReadonlyThreadRuntimeCore();
+    first.setMessages([message("m1")]);
+    publish(first);
+
+    const thread = new ThreadListRuntimeImpl(core).main;
+    thread.subscribe(() => {});
+    expect(thread.getState().messages.map((m) => m.id)).toEqual(["m1"]);
+
+    const second = new ReadonlyThreadRuntimeCore();
+    second.setMessages([message("m2")]);
+    publish(second);
+    await Promise.resolve();
+
+    const ids = thread.getState().messages.map((m) => m.id);
+    expect(ids).toEqual(["m2"]);
+    for (const id of ids) {
+      expect(() => thread.getMessageById(id).getState()).not.toThrow();
+    }
+  });
+
+  it("notifies thread subscribers when the core is republished", async () => {
+    const { core, publish } = setup();
+    publish(new ReadonlyThreadRuntimeCore());
+
+    const thread = new ThreadListRuntimeImpl(core).main;
+    let notified = 0;
+    thread.subscribe(() => notified++);
+
+    const next = new ReadonlyThreadRuntimeCore();
+    next.setMessages([message("m1")]);
+    publish(next);
+    await Promise.resolve();
+
+    expect(notified).toBeGreaterThan(0);
+    expect(thread.getState().messages.map((m) => m.id)).toEqual(["m1"]);
+  });
+});