@assistant-ui/core 0.3.13 → 0.3.14

package/src/react/client/InMemoryThreadList.ts

@@ -0,0 +1,290 @@
+import { useState, useMemo } from "react";
+import { resource, withKey, type ResourceElement } from "@assistant-ui/tap";
+import type {
+  AssistantClient,
+  ClientOutput,
+  ScopesConfig,
+} from "@assistant-ui/store";
+import {
+  useClientLookup,
+  Derived,
+  attachTransformScopes,
+  useClientResource,
+} from "@assistant-ui/store/client";
+import { useThreadSelectionEvents } from "../../store/internal";
+import { generateId } from "../../utils/id";
+import { ModelContext } from "../../store/clients/model-context-client";
+import { Tools } from "./Tools";
+import { DataRenderers } from "./DataRenderers";
+
+const RESOLVED_PROMISE = Promise.resolve();
+
+export type InMemoryThreadListProps = {
+  thread: (threadId: string) => ResourceElement<ClientOutput<"thread">>;
+  onSwitchToThread?: (threadId: string) => void;
+  onSwitchToNewThread?: () => void;
+  onDelete?: (threadId: string) => void;
+};
+
+type ThreadData = {
+  id: string;
+  title?: string;
+  status: "regular" | "archived";
+  custom?: Record<string, unknown> | undefined;
+};
+
+// ThreadListItem Client
+const useThreadListItemClient = (props: {
+  data: ThreadData;
+  isRunning: boolean;
+  onSwitchTo: () => void;
+  onRename: (title: string) => void;
+  onUpdateCustom: (custom: Record<string, unknown> | undefined) => void;
+  onArchive: () => void;
+  onUnarchive: () => void;
+  onDelete: () => void;
+}): ClientOutput<"threadListItem"> => {
+  const {
+    data,
+    isRunning,
+    onSwitchTo,
+    onRename,
+    onUpdateCustom,
+    onArchive,
+    onUnarchive,
+    onDelete,
+  } = props;
+  const state = useMemo(
+    () => ({
+      id: data.id,
+      remoteId: undefined,
+      externalId: undefined,
+      title: data.title,
+      status: data.status,
+      custom: data.custom,
+      isRunning,
+    }),
+    [data.id, data.title, data.status, data.custom, isRunning],
+  );
+
+  return {
+    getState: () => state,
+    switchTo: onSwitchTo,
+    rename: onRename,
+    updateCustom: onUpdateCustom,
+    archive: onArchive,
+    unarchive: onUnarchive,
+    delete: onDelete,
+    generateTitle: () => {},
+    initialize: async () => ({ remoteId: data.id, externalId: undefined }),
+    detach: () => {},
+  };
+};
+
+const ThreadListItemClient = resource(useThreadListItemClient);
+
+// InMemoryThreadList Client
+const useInMemoryThreadList = (
+  props: InMemoryThreadListProps,
+): ClientOutput<"threads"> => {
+  const {
+    thread: threadFactory,
+    onSwitchToThread,
+    onSwitchToNewThread,
+    onDelete,
+  } = props;
+
+  const [{ threads, mainThreadId }, setListState] = useState<{
+    threads: readonly ThreadData[];
+    mainThreadId: string;
+  }>(() => ({
+    threads: [{ id: "main", title: "Main Thread", status: "regular" }],
+    mainThreadId: "main",
+  }));
+  const setThreads = (
+    update: (prev: readonly ThreadData[]) => readonly ThreadData[],
+  ) => setListState((prev) => ({ ...prev, threads: update(prev.threads) }));
+
+  useThreadSelectionEvents(mainThreadId);
+
+  const handleSwitchToThread = (threadId: string) => {
+    setListState((prev) => ({ ...prev, mainThreadId: threadId }));
+    onSwitchToThread?.(threadId);
+  };
+
+  const handleRename = (threadId: string, title: string) => {
+    setThreads((prev) =>
+      prev.map((t) => (t.id === threadId ? { ...t, title } : t)),
+    );
+  };
+
+  const handleArchive = (threadId: string) => {
+    setThreads((prev) =>
+      prev.map((t) =>
+        t.id === threadId ? { ...t, status: "archived" as const } : t,
+      ),
+    );
+  };
+
+  const handleUnarchive = (threadId: string) => {
+    setThreads((prev) =>
+      prev.map((t) =>
+        t.id === threadId ? { ...t, status: "regular" as const } : t,
+      ),
+    );
+  };
+
+  const handleUpdateCustom = (
+    threadId: string,
+    custom: Record<string, unknown> | undefined,
+  ) => {
+    setThreads((prev) =>
+      prev.map((t) => (t.id === threadId ? { ...t, custom } : t)),
+    );
+  };
+
+  const handleDelete = (threadId: string) => {
+    // Deleting the last thread starts a fresh one; the removed id must not
+    // stay selected. The fallback id is minted eagerly so the updater stays
+    // pure under batched deletes.
+    const fallbackId = `thread-${generateId()}`;
+    setListState((prev) => {
+      const remaining = prev.threads.filter((t) => t.id !== threadId);
+      if (remaining.length === 0) {
+        return {
+          threads: [{ id: fallbackId, title: "New Thread", status: "regular" }],
+          mainThreadId: fallbackId,
+        };
+      }
+      return {
+        threads: remaining,
+        mainThreadId:
+          prev.mainThreadId === threadId
+            ? (remaining.find((t) => t.status === "regular") ?? remaining[0]!)
+                .id
+            : prev.mainThreadId,
+      };
+    });
+    onDelete?.(threadId);
+  };
+
+  const handleSwitchToNewThread = () => {
+    const newId = `thread-${generateId()}`;
+    setListState((prev) => ({
+      threads: [
+        ...prev.threads,
+        { id: newId, title: "New Thread", status: "regular" },
+      ],
+      mainThreadId: newId,
+    }));
+    onSwitchToNewThread?.();
+  };
+
+  // Only the main thread is mounted, so it is the only thread that can run.
+  const mainThreadClient = useClientResource(threadFactory(mainThreadId));
+
+  const threadListItems = useClientLookup(
+    threads.map((t) =>
+      withKey(
+        t.id,
+        ThreadListItemClient({
+          data: t,
+          isRunning: t.id === mainThreadId && mainThreadClient.state.isRunning,
+          onSwitchTo: () => handleSwitchToThread(t.id),
+          onRename: (title) => handleRename(t.id, title),
+          onUpdateCustom: (custom) => handleUpdateCustom(t.id, custom),
+          onArchive: () => handleArchive(t.id),
+          onUnarchive: () => handleUnarchive(t.id),
+          onDelete: () => handleDelete(t.id),
+        }),
+      ),
+    ),
+  );
+
+  const state = useMemo(() => {
+    const regularThreads = threads.filter((t) => t.status === "regular");
+    const archivedThreads = threads.filter((t) => t.status === "archived");
+
+    return {
+      mainThreadId,
+      newThreadId: null,
+      isLoading: false,
+      isLoadingMore: false,
+      hasMore: false,
+      threadIds: regularThreads.map((t) => t.id),
+      archivedThreadIds: archivedThreads.map((t) => t.id),
+      threadItems: threadListItems.state,
+      main: mainThreadClient.state,
+    };
+  }, [mainThreadId, threads, threadListItems.state, mainThreadClient.state]);
+
+  return {
+    getState: () => state,
+    switchToThread: handleSwitchToThread,
+    switchToNewThread: handleSwitchToNewThread,
+    getLoadThreadsPromise: () => RESOLVED_PROMISE,
+    reload: () => RESOLVED_PROMISE,
+    reloadMainThread: () =>
+      mainThreadClient.methods.unstable_refetchThread?.() ?? RESOLVED_PROMISE,
+    loadMore: () => RESOLVED_PROMISE,
+    item: (selector) => {
+      if (selector === "main") {
+        const index = threads.findIndex((t) => t.id === mainThreadId);
+        return threadListItems.get({ index: index === -1 ? 0 : index });
+      }
+      if ("id" in selector) {
+        const index = threads.findIndex((t) => t.id === selector.id);
+        return threadListItems.get({ index });
+      }
+      return threadListItems.get(selector);
+    },
+    thread: () => mainThreadClient.methods,
+  };
+};
+
+export const InMemoryThreadList = resource(useInMemoryThreadList);
+
+/**
+ * The scope defaults `InMemoryThreadList` installs when it is used as the
+ * `threads` config entry. Adapter packages that wrap it in their own config
+ * entry attach this to the wrapping resource for scope parity.
+ */
+export const inMemoryThreadListTransformScopes = (
+  scopes: ScopesConfig,
+  parent: AssistantClient,
+): void => {
+  scopes.thread ??= Derived({
+    source: "threads",
+    query: { type: "main" },
+    get: (aui) => aui.threads.thread("main"),
+  });
+  scopes.threadListItem ??= Derived({
+    source: "threads",
+    query: { type: "main" },
+    get: (aui) => aui.threads.item("main"),
+  });
+  scopes.composer ??= Derived({
+    source: "thread",
+    query: {},
+    get: (aui) => aui.threads.thread("main").composer(),
+  });
+
+  if (!scopes.modelContext && parent.modelContext.source === null) {
+    scopes.modelContext = ModelContext();
+  }
+  if (!scopes.tools && parent.tools.source === null) {
+    scopes.tools = Tools({});
+  }
+  if (!scopes.dataRenderers && parent.dataRenderers.source === null) {
+    scopes.dataRenderers = DataRenderers();
+  }
+  if (!scopes.suggestions && parent.suggestions.source === null) {
+    scopes.suggestions = Derived({
+      source: "thread",
+      query: {},
+      get: (aui) => aui.thread.suggestions(),
+    });
+  }
+};
+
+attachTransformScopes(useInMemoryThreadList, inMemoryThreadListTransformScopes);

package/src/react/client/Interactables.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createTapRoot, useResource } from "@assistant-ui/tap";
+import { createTapRoot, flushTapSync, useResource } from "@assistant-ui/tap";
 import type {
   Unstable_InteractablePersistedState,
   Unstable_InteractablePersistenceAdapter,
@@ -8,10 +8,49 @@ import type {
 import type { ThreadMessage } from "../../types/message";
 
 const clientHolder: { client: unknown } = { client: null };
+const clientListeners = new Set<() => void>();
+let registeredModelContextProvider:
+  | { subscribe?: (callback: () => void) => () => void }
+  | undefined;
+
+const replaceClient = (client: unknown) => {
+  clientHolder.client = client;
+  for (const listener of clientListeners) listener();
+};
 
 vi.mock("@assistant-ui/store/client", async (importOriginal) => {
   const actual =
     await importOriginal<typeof import("@assistant-ui/store/client")>();
+  const { useEffect } = await import("react");
+  // Mirrors the real hook's guarantees: the effect only runs while the scope
+  // is available, and a client replacement migrates the registration.
+  const useScopeEffectShim = (
+    scope: string,
+    effect: () => (() => void) | void,
+    deps: readonly unknown[],
+  ) => {
+    useEffect(() => {
+      let cleanup: (() => void) | undefined;
+      const apply = () => {
+        cleanup?.();
+        cleanup = undefined;
+        const accessor = (
+          clientHolder.client as Record<string, { source?: unknown }> | null
+        )?.[scope];
+        if (accessor?.source == null) return;
+        const result = effect();
+        cleanup = typeof result === "function" ? result : undefined;
+      };
+
+      apply();
+      clientListeners.add(apply);
+      return () => {
+        clientListeners.delete(apply);
+        cleanup?.();
+      };
+      // oxlint-disable-next-line react-hooks/exhaustive-deps -- caller-provided deps, mirrors the real hook
+    }, deps);
+  };
   return {
     ...actual,
     useAssistantClientRef: () => ({
@@ -19,6 +58,7 @@ vi.mock("@assistant-ui/store/client", async (importOriginal) => {
         return clientHolder.client;
       },
     }),
+    useAssistantScopeEffect: useScopeEffectShim,
   };
 });
 
@@ -38,7 +78,19 @@ const makeClient = (
   setToolUI?: (...args: unknown[]) => () => void,
   threadId?: string,
 ) => ({
-  modelContext: () => ({ register: () => () => {} }),
+  modelContext: Object.assign(
+    () => ({
+      register: (
+        provider: NonNullable<typeof registeredModelContextProvider>,
+      ) => {
+        registeredModelContextProvider = provider;
+        return () => {
+          registeredModelContextProvider = undefined;
+        };
+      },
+    }),
+    { source: "root" },
+  ),
   thread: threadMessages
     ? Object.assign(
         () => ({ getState: () => ({ messages: threadMessages }) }),
@@ -122,6 +174,7 @@ let root: ReturnType<typeof mount> | undefined;
 
 beforeEach(() => {
   vi.useFakeTimers();
+  registeredModelContextProvider = undefined;
 });
 
 afterEach(() => {
@@ -132,6 +185,25 @@ afterEach(() => {
 });
 
 describe("Interactables registration", () => {
+  it("notifies every model-context subscriber when one throws", async () => {
+    root = mount();
+    await flushMicrotasks();
+    const listenerError = new Error("listener failed");
+    const laterListener = vi.fn();
+
+    const provider = registeredModelContextProvider;
+    expect(provider).toBeDefined();
+    provider?.subscribe?.(() => {
+      throw listenerError;
+    });
+    provider?.subscribe?.(laterListener);
+
+    expect(() =>
+      flushTapSync(() => root?.getValue().register(reg("n1"))),
+    ).toThrow(listenerError);
+    expect(laterListener).toHaveBeenCalledOnce();
+  });
+
   it("seeds a new registration with initialState", () => {
     root = mount();
     root.getValue().register(reg("n1", { initialState: { v: 7 } }));
@@ -242,6 +314,57 @@ describe("Interactables registration", () => {
     second();
     expect(removeToolUI).toHaveBeenCalledTimes(1);
   });
+
+  it("migrates update tool UIs when the tools scope is replaced", () => {
+    const removeFirst = vi.fn();
+    const setFirst = vi.fn(() => removeFirst);
+    const removeSecond = vi.fn();
+    const setSecond = vi.fn(() => removeSecond);
+    root = mount({ setToolUI: setFirst });
+
+    const render = () => null;
+    const unregister = root
+      .getValue()
+      .register(reg("n1", { updateRender: render }));
+
+    replaceClient(makeClient(undefined, setSecond));
+
+    expect(removeFirst).toHaveBeenCalledTimes(1);
+    expect(setSecond).toHaveBeenCalledWith("update_note", render, {
+      standalone: true,
+    });
+
+    unregister();
+    expect(removeSecond).toHaveBeenCalledTimes(1);
+  });
+
+  it("installs a pending update tool UI when the tools scope becomes available", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const removeToolUI = vi.fn();
+    const setToolUI = vi.fn(() => removeToolUI);
+    root = mount();
+
+    const unregister = root
+      .getValue()
+      .register(reg("n1", { updateRender: () => null }));
+    expect(warn).toHaveBeenCalledWith(
+      '[Interactables] "note" supplied an updateRender, but no ' +
+        "tools scope is available yet; it will be installed once one appears.",
+    );
+    warn.mockRestore();
+
+    replaceClient(makeClient(undefined, setToolUI));
+
+    expect(setToolUI).toHaveBeenCalledWith(
+      "update_note",
+      expect.any(Function),
+      {
+        standalone: true,
+      },
+    );
+    unregister();
+    expect(removeToolUI).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe("Interactables persistence save", () => {
@@ -302,6 +425,207 @@ describe("Interactables persistence save", () => {
     await p;
     expect(resolved).toBe(true);
   });
+
+  it("saves queued changes with the adapter that observed them", async () => {
+    const firstSave = vi.fn();
+    const secondSave = vi.fn();
+    root = mount({ persistence: { save: firstSave } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+
+    root.getValue().setState("n1", () => ({ v: 1 }));
+    root.getValue().setPersistenceAdapter({ save: secondSave });
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(firstSave).toHaveBeenCalledWith({
+      n1: { name: "note", state: { v: 1 } },
+    });
+    expect(secondSave).not.toHaveBeenCalled();
+  });
+
+  it("keeps edits queued during an in-flight flush with the outgoing adapter", async () => {
+    const saveResolvers: Array<() => void> = [];
+    const firstSave = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          saveResolvers.push(resolve);
+        }),
+    );
+    const secondSave = vi.fn();
+    root = mount({ persistence: { save: firstSave } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+
+    root.getValue().setState("n1", () => ({ v: 1 }));
+    await vi.advanceTimersByTimeAsync(500);
+    root.getValue().setState("n1", () => ({ v: 2 }));
+
+    let flushed = false;
+    const flush = root
+      .getValue()
+      .flush()
+      .then(() => {
+        flushed = true;
+      });
+    root.getValue().setPersistenceAdapter({ save: secondSave });
+
+    expect(firstSave).toHaveBeenCalledTimes(1);
+    expect(secondSave).not.toHaveBeenCalled();
+
+    saveResolvers[0]!();
+    await flushMicrotasks();
+    expect(flushed).toBe(false);
+    expect(firstSave).toHaveBeenCalledTimes(2);
+    expect(firstSave.mock.calls[1]![0]).toEqual({
+      n1: { name: "note", state: { v: 2 } },
+    });
+    expect(secondSave).not.toHaveBeenCalled();
+
+    saveResolvers[1]!();
+    await flush;
+    expect(flushed).toBe(true);
+    expect(firstSave.mock.calls.at(-1)?.[0]).toEqual({
+      n1: { name: "note", state: { v: 2 } },
+    });
+    expect(secondSave).not.toHaveBeenCalled();
+  });
+
+  it("cancels an empty retry timer when replacing the adapter", async () => {
+    let resolveFirstSave!: () => void;
+    const firstSave = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveFirstSave = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined);
+    const secondSave = vi.fn();
+    root = mount({ persistence: { save: firstSave } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+
+    root.getValue().setState("n1", () => ({ v: 1 }));
+    await vi.advanceTimersByTimeAsync(500);
+    root.getValue().setState("n1", () => ({ v: 2 }));
+    await vi.advanceTimersByTimeAsync(500);
+
+    resolveFirstSave();
+    await flushMicrotasks();
+    expect(firstSave).toHaveBeenCalledTimes(2);
+
+    root.getValue().setPersistenceAdapter({ save: secondSave });
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(firstSave).toHaveBeenCalledTimes(2);
+    expect(secondSave).not.toHaveBeenCalled();
+  });
+
+  it("cancels the retry timer after starting the queued batch", async () => {
+    let resolveFirstSave!: () => void;
+    const save = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveFirstSave = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined);
+    root = mount({ persistence: { save } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+
+    root.getValue().setState("n1", () => ({ v: 1 }));
+    await vi.advanceTimersByTimeAsync(500);
+    root.getValue().setState("n1", () => ({ v: 2 }));
+    await vi.advanceTimersByTimeAsync(500);
+
+    resolveFirstSave();
+    await flushMicrotasks();
+    expect(save).toHaveBeenCalledTimes(2);
+
+    await vi.advanceTimersByTimeAsync(500);
+    expect(save).toHaveBeenCalledTimes(2);
+  });
+
+  it("settles overlapping persistence batches per interactable", async () => {
+    let resolveFirstSave!: () => void;
+    const firstSave = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveFirstSave = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined);
+    root = mount({ persistence: { save: firstSave } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+    root.getValue().register(reg("n2"));
+
+    root.getValue().setState("n1", () => ({ v: 1 }));
+    await vi.advanceTimersByTimeAsync(500);
+    root.getValue().setState("n2", () => ({ v: 2 }));
+    root.getValue().setPersistenceAdapter({ save: vi.fn() });
+    await flushMicrotasks();
+
+    expect(root.getValue().getState().persistence["n1"]?.isPending).toBe(true);
+    expect(root.getValue().getState().persistence["n2"]).toBeUndefined();
+
+    resolveFirstSave();
+    await flushMicrotasks();
+    expect(root.getValue().getState().persistence["n1"]).toBeUndefined();
+  });
+
+  it("keeps an interactable pending while its newer edit is queued", async () => {
+    const saveResolvers: Array<() => void> = [];
+    const firstSave = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          saveResolvers.push(resolve);
+        }),
+    );
+    const secondSave = vi.fn();
+    root = mount({ persistence: { save: firstSave } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+    root.getValue().register(reg("n2"));
+
+    root.getValue().setState("n1", () => ({ v: 1 }));
+    await vi.advanceTimersByTimeAsync(500);
+    root.getValue().setState("n2", () => ({ v: 2 }));
+    root.getValue().setPersistenceAdapter({ save: secondSave });
+    root.getValue().setState("n1", () => ({ v: 3 }));
+
+    saveResolvers[0]!();
+    await flushMicrotasks();
+    expect(root.getValue().getState().persistence["n1"]?.isPending).toBe(true);
+    expect(secondSave).not.toHaveBeenCalled();
+
+    saveResolvers[1]!();
+    await flushMicrotasks();
+    expect(secondSave).toHaveBeenCalledTimes(1);
+    expect(root.getValue().getState().persistence["n1"]).toBeUndefined();
+  });
+
+  it("flushes queued changes through the declarative adapter on unmount", async () => {
+    const save = vi.fn();
+    root = mount({ persistence: { save } });
+    await flushMicrotasks();
+    root.getValue().register(reg("n1"));
+    root.getValue().setState("n1", () => ({ v: 1 }));
+
+    root.unmount();
+    root = undefined;
+    await flushMicrotasks();
+
+    expect(save).toHaveBeenCalledWith({
+      n1: { name: "note", state: { v: 1 } },
+    });
+  });
 });
 
 describe("Interactables persistence load", () => {