@assistant-ui/react 0.14.20 → 0.14.22

package/src/index.ts

@@ -124,6 +124,7 @@ export type {
 
 // --- external-store ---
 export type { ThreadMessageLike } from "@assistant-ui/core";
+export { fromThreadMessageLike, generateId } from "@assistant-ui/core";
 export {
   getExternalStoreMessages,
   bindExternalStoreMessage,
@@ -414,6 +415,12 @@ export {
   type Unstable_UseSlashCommandAdapterOptions,
 } from "./unstable/useSlashCommandAdapter";
 
+// Unstable - live (async) completion adapter helper
+export {
+  unstable_useLiveCompletionAdapter,
+  type Unstable_UseLiveCompletionAdapterOptions,
+} from "./unstable/useLiveCompletionAdapter";
+
 export type { ToolExecutionStatus } from "./internal";
 
 // Unstable - trigger popover (unified root for @ mentions, / slash commands, etc.)

package/src/internal.ts

@@ -10,10 +10,8 @@ export {
   CompositeContextProvider,
   MessageRepository,
   BaseAssistantRuntimeCore,
-  generateId,
   AssistantRuntimeImpl,
   ThreadRuntimeImpl,
-  fromThreadMessageLike,
   getAutoStatus,
 } from "@assistant-ui/core/internal";
 export type {

package/src/primitives/composer/trigger/TriggerPopover.tsx

@@ -72,6 +72,8 @@ export namespace ComposerPrimitiveTriggerPopover {
     readonly char: string;
     /** Adapter providing categories and items. */
     readonly adapter?: Unstable_TriggerAdapter | undefined;
+    /** Whether the adapter is resolving items, surfaced to the popover scope for async sources. @default false */
+    readonly isLoading?: boolean | undefined;
   };
 }
 
@@ -107,7 +109,14 @@ export const ComposerPrimitiveTriggerPopover = forwardRef<
   ComposerPrimitiveTriggerPopover.Props
 >(
   (
-    { char, adapter, "aria-label": ariaLabel, children, ...props },
+    {
+      char,
+      adapter,
+      isLoading = false,
+      "aria-label": ariaLabel,
+      children,
+      ...props
+    },
     forwardedRef,
   ) => {
     const aui = useAui();
@@ -159,6 +168,7 @@ export const ComposerPrimitiveTriggerPopover = forwardRef<
         behavior: behavior ?? undefined,
         aui,
         popoverId,
+        isLoading,
       }),
     );
 

package/src/primitives/composer/trigger/TriggerPopoverResource.ts

@@ -29,6 +29,8 @@ export type TriggerPopoverResourceOutput = {
   readonly items: readonly Unstable_TriggerItem[];
   readonly highlightedIndex: number;
   readonly isSearchMode: boolean;
+  /** Whether the adapter is currently resolving items (async sources). */
+  readonly isLoading: boolean;
   /** Stable ID prefix for generating accessible element IDs. */
   readonly popoverId: string;
   /** ID of the currently highlighted item (for aria-activedescendant). */
@@ -58,6 +60,7 @@ const useTriggerPopoverResource = ({
   behavior,
   aui,
   popoverId,
+  isLoading,
 }: {
   adapter: Unstable_TriggerAdapter | undefined;
   text: string;
@@ -66,6 +69,7 @@ const useTriggerPopoverResource = ({
   aui: AssistantClient;
   /** Stable ID for accessible element IDs (pass React's useId() from component layer). */
   popoverId: string;
+  isLoading: boolean;
 }): TriggerPopoverResourceOutput => {
   const detection = useResource(
     TriggerDetectionResource({ text, triggerChar }),
@@ -122,6 +126,7 @@ const useTriggerPopoverResource = ({
     items: navigation.items,
     highlightedIndex: keyboard.highlightedIndex,
     isSearchMode: navigation.isSearchMode,
+    isLoading,
     popoverId,
     highlightedItemId: keyboard.highlightedItemId,
     selectCategory: navigation.selectCategory,

package/src/tests/ExternalStoreThreadRuntimeCore.test.ts

@@ -569,4 +569,117 @@ describe("ExternalStoreThreadRuntimeCore", () => {
       );
     });
   });
+
+  describe("messageRepository incremental sync", () => {
+    const u1 = createUserMessage("u1");
+    const a1 = createAssistantMessage("a1");
+
+    const repoAdapter = (
+      messages: { message: ThreadMessage; parentId: string | null }[],
+      headId: string | null,
+      overrides: Partial<ExternalStoreAdapter<ThreadMessage>> = {},
+    ): ExternalStoreAdapter<ThreadMessage> => ({
+      messageRepository: { headId, messages },
+      onNew: vi.fn(async () => {}),
+      ...overrides,
+    });
+
+    it("imports the initial repository", () => {
+      const core = new ExternalStoreThreadRuntimeCore(
+        contextProvider,
+        repoAdapter([{ message: u1, parentId: null }], "u1"),
+      );
+      expect(core.messages.map((m) => m.id)).toEqual(["u1"]);
+    });
+
+    it("adds a message when the repository is replaced", () => {
+      const core = new ExternalStoreThreadRuntimeCore(
+        contextProvider,
+        repoAdapter([{ message: u1, parentId: null }], "u1"),
+      );
+      core.__internal_setAdapter(
+        repoAdapter(
+          [
+            { message: u1, parentId: null },
+            { message: a1, parentId: "u1" },
+          ],
+          "a1",
+        ),
+      );
+      expect(core.messages.map((m) => m.id)).toEqual(["u1", "a1"]);
+    });
+
+    it("deletes a message no longer present in the new repository", () => {
+      const core = new ExternalStoreThreadRuntimeCore(
+        contextProvider,
+        repoAdapter(
+          [
+            { message: u1, parentId: null },
+            { message: a1, parentId: "u1" },
+          ],
+          "a1",
+        ),
+      );
+      expect(core.messages.map((m) => m.id)).toEqual(["u1", "a1"]);
+
+      core.__internal_setAdapter(
+        repoAdapter([{ message: u1, parentId: null }], "u1"),
+      );
+      expect(core.messages.map((m) => m.id)).toEqual(["u1"]);
+    });
+
+    it("matches a fresh import when built incrementally", () => {
+      const incremental = new ExternalStoreThreadRuntimeCore(
+        contextProvider,
+        repoAdapter([{ message: u1, parentId: null }], "u1"),
+      );
+      incremental.__internal_setAdapter(
+        repoAdapter(
+          [
+            { message: u1, parentId: null },
+            { message: a1, parentId: "u1" },
+          ],
+          "a1",
+        ),
+      );
+      const fresh = new ExternalStoreThreadRuntimeCore(
+        contextProvider,
+        repoAdapter(
+          [
+            { message: u1, parentId: null },
+            { message: a1, parentId: "u1" },
+          ],
+          "a1",
+        ),
+      );
+      expect(incremental.messages.map((m) => m.id)).toEqual(
+        fresh.messages.map((m) => m.id),
+      );
+    });
+
+    it("coalesces an isRunning flip on an unchanged repository reference", () => {
+      const messageRepository = {
+        headId: "u1",
+        messages: [{ message: u1, parentId: null }],
+      };
+      const onNew = vi.fn(async () => {});
+      const core = new ExternalStoreThreadRuntimeCore(contextProvider, {
+        messageRepository,
+        onNew,
+        isRunning: false,
+      });
+      expect(core.messages.map((m) => m.id)).toEqual(["u1"]);
+
+      core.__internal_setAdapter({ messageRepository, onNew, isRunning: true });
+      expect(core.messages.length).toBe(2);
+      expect(core.messages[1]!.role).toBe("assistant");
+
+      core.__internal_setAdapter({
+        messageRepository,
+        onNew,
+        isRunning: false,
+      });
+      expect(core.messages.map((m) => m.id)).toEqual(["u1"]);
+    });
+  });
 });

package/src/unstable/useLiveCompletionAdapter.test.tsx

@@ -0,0 +1,176 @@
+/** @vitest-environment jsdom */
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Unstable_TriggerItem } from "@assistant-ui/core";
+import { unstable_useLiveCompletionAdapter } from "./useLiveCompletionAdapter";
+
+const item = (id: string): Unstable_TriggerItem => ({
+  id,
+  type: "x",
+  label: id,
+});
+
+describe("unstable_useLiveCompletionAdapter", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("returns cached items synchronously and schedules a debounced fetch", async () => {
+    let resolve!: (value: readonly Unstable_TriggerItem[]) => void;
+    const fetcher = vi.fn(
+      () =>
+        new Promise<readonly Unstable_TriggerItem[]>((r) => {
+          resolve = r;
+        }),
+    );
+    const { result } = renderHook(() =>
+      unstable_useLiveCompletionAdapter({ fetcher, debounceMs: 50 }),
+    );
+
+    let returned: readonly Unstable_TriggerItem[] = [];
+    await act(async () => {
+      returned = result.current.adapter.search!("ab");
+    });
+    expect(returned).toEqual([]);
+    expect(result.current.isLoading).toBe(true);
+    expect(fetcher).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50);
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+    expect(fetcher).toHaveBeenCalledWith("ab");
+
+    await act(async () => {
+      resolve([item("ab")]);
+    });
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.adapter.search!("ab")).toEqual([item("ab")]);
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("defers its state update out of search() so it is safe to call during render", () => {
+    const fetcher = vi.fn(async () => []);
+    const { result } = renderHook(() =>
+      unstable_useLiveCompletionAdapter({ fetcher, debounceMs: 0 }),
+    );
+
+    const returned = result.current.adapter.search!("ab");
+    expect(returned).toEqual([]);
+    // the fetch (and its setIsLoading) is queued, not run synchronously
+    expect(result.current.isLoading).toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it("does not fetch when disabled and clears cached items", async () => {
+    const fetcher = vi.fn(async () => [item("a")]);
+    const { result, rerender } = renderHook(
+      ({ enabled }) =>
+        unstable_useLiveCompletionAdapter({ fetcher, enabled, debounceMs: 0 }),
+      { initialProps: { enabled: true } },
+    );
+
+    await act(async () => {
+      result.current.adapter.search!("ab");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(result.current.adapter.search!("ab")).toEqual([item("a")]);
+
+    fetcher.mockClear();
+    await act(async () => {
+      rerender({ enabled: false });
+    });
+    expect(result.current.adapter.search!("ab")).toEqual([]);
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10);
+    });
+    expect(fetcher).not.toHaveBeenCalled();
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("drops a stale in-flight result when the query changes", async () => {
+    const resolvers: Record<
+      string,
+      (value: readonly Unstable_TriggerItem[]) => void
+    > = {};
+    const fetcher = vi.fn(
+      (q: string) =>
+        new Promise<readonly Unstable_TriggerItem[]>((r) => {
+          resolvers[q] = r;
+        }),
+    );
+    const { result } = renderHook(() =>
+      unstable_useLiveCompletionAdapter({ fetcher, debounceMs: 0 }),
+    );
+
+    await act(async () => {
+      result.current.adapter.search!("a");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    await act(async () => {
+      result.current.adapter.search!("ab");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(fetcher).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      resolvers["a"]!([item("a")]);
+    });
+    expect(result.current.adapter.search!("ab")).toEqual([]);
+
+    await act(async () => {
+      resolvers["ab"]!([item("ab")]);
+    });
+    expect(result.current.adapter.search!("ab")).toEqual([item("ab")]);
+  });
+
+  it("drops an in-flight fetch when the query returns to a cached value", async () => {
+    const resolvers: Record<
+      string,
+      (value: readonly Unstable_TriggerItem[]) => void
+    > = {};
+    const fetcher = vi.fn(
+      (q: string) =>
+        new Promise<readonly Unstable_TriggerItem[]>((r) => {
+          resolvers[q] = r;
+        }),
+    );
+    const { result } = renderHook(() =>
+      unstable_useLiveCompletionAdapter({ fetcher, debounceMs: 0 }),
+    );
+
+    await act(async () => {
+      result.current.adapter.search!("ab");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    await act(async () => {
+      resolvers["ab"]!([item("ab")]);
+    });
+    expect(result.current.adapter.search!("ab")).toEqual([item("ab")]);
+
+    // type "abc": a fetch goes in flight
+    await act(async () => {
+      result.current.adapter.search!("abc");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(resolvers["abc"]).toBeTypeOf("function");
+
+    // delete back to the cached "ab": the in-flight "abc" must be invalidated
+    await act(async () => {
+      result.current.adapter.search!("ab");
+    });
+    await act(async () => {
+      resolvers["abc"]!([item("abc")]);
+    });
+    expect(result.current.adapter.search!("ab")).toEqual([item("ab")]);
+  });
+});

package/src/unstable/useLiveCompletionAdapter.ts

@@ -0,0 +1,145 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type {
+  Unstable_TriggerAdapter,
+  Unstable_TriggerItem,
+} from "@assistant-ui/core";
+
+export type Unstable_UseLiveCompletionAdapterOptions = {
+  /**
+   * Fetches the items for a query from an async source. Called debounced; the
+   * resolved items are cached and returned synchronously to the popover on the
+   * next render.
+   */
+  readonly fetcher: (query: string) => Promise<readonly Unstable_TriggerItem[]>;
+  /** Debounce applied before a fetch fires, in milliseconds. @default 60 */
+  readonly debounceMs?: number | undefined;
+  /** When `false`, no fetch is scheduled and the adapter stays empty. @default true */
+  readonly enabled?: boolean | undefined;
+};
+
+/** Sentinel that no real query (including the empty string) equals, so the first query always fetches. */
+const NO_QUERY = "\u0000";
+
+/**
+ * @deprecated Under active development and may change without notice.
+ *
+ * Bridges an async completion source (a server search, a gateway RPC) into the
+ * synchronous `Unstable_TriggerAdapter` that `ComposerTriggerPopover` consumes.
+ * `search(query)` returns the last fetched items synchronously and schedules a
+ * debounced fetch when the query changes; when results arrive the returned
+ * `adapter` identity changes, which re-runs the popover's lookup so the fresh
+ * items render. This is a search-only adapter (`categories` are empty).
+ *
+ * `isLoading` is `true` while a fetch is in flight. Pass it to the popover's
+ * `isLoading` prop to render a loading state.
+ *
+ * @example
+ * ```tsx
+ * const mentions = unstable_useLiveCompletionAdapter({
+ *   fetcher: (query) => searchUsers(query),
+ * });
+ *
+ * <ComposerTriggerPopover
+ *   char="@"
+ *   adapter={mentions.adapter}
+ *   isLoading={mentions.isLoading}
+ *   directive={{ onInserted }}
+ * />
+ * ```
+ */
+export function unstable_useLiveCompletionAdapter(
+  options: Unstable_UseLiveCompletionAdapterOptions,
+): { adapter: Unstable_TriggerAdapter; isLoading: boolean } {
+  const { fetcher, debounceMs = 60, enabled = true } = options;
+
+  const [state, setState] = useState<{
+    query: string;
+    items: readonly Unstable_TriggerItem[];
+  }>({ query: NO_QUERY, items: [] });
+  const [isLoading, setIsLoading] = useState(false);
+
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const tokenRef = useRef(0);
+  const pendingQueryRef = useRef<string | null>(null);
+
+  const cancelTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const scheduleFetch = useCallback(
+    (query: string) => {
+      if (!enabled) return;
+      if (pendingQueryRef.current === query) return;
+      pendingQueryRef.current = query;
+      cancelTimer();
+      const token = ++tokenRef.current;
+      setIsLoading(true);
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        fetcherRef.current(query).then(
+          (items) => {
+            if (token !== tokenRef.current) return;
+            setState({ query, items });
+            setIsLoading(false);
+          },
+          () => {
+            if (token !== tokenRef.current) return;
+            setState({ query, items: [] });
+            setIsLoading(false);
+          },
+        );
+      }, debounceMs);
+    },
+    [enabled, debounceMs, cancelTimer],
+  );
+
+  const invalidatePending = useCallback(() => {
+    cancelTimer();
+    pendingQueryRef.current = null;
+    tokenRef.current += 1;
+    setIsLoading(false);
+  }, [cancelTimer]);
+
+  useEffect(() => {
+    if (enabled) return;
+    invalidatePending();
+    setState((s) =>
+      s.query === NO_QUERY ? s : { query: NO_QUERY, items: [] },
+    );
+  }, [enabled, invalidatePending]);
+
+  useEffect(() => cancelTimer, [cancelTimer]);
+
+  const adapter = useMemo<Unstable_TriggerAdapter>(
+    () => ({
+      categories: () => [],
+      categoryItems: () => [],
+      search: (query: string) => {
+        // search() runs inside the popover's render; defer state updates with
+        // queueMicrotask so they are not dispatched while another component renders.
+        if (query !== state.query) {
+          queueMicrotask(() => scheduleFetch(query));
+        } else if (
+          pendingQueryRef.current !== null &&
+          pendingQueryRef.current !== query
+        ) {
+          // the query returned to a cached value while a fetch for a different
+          // query is in flight; drop it so its result cannot overwrite the cache
+          queueMicrotask(invalidatePending);
+        }
+        return state.items;
+      },
+    }),
+    [state, scheduleFetch, invalidatePending],
+  );
+
+  return { adapter, isLoading };
+}

package/src/utils/smooth/useSmooth.test.tsx

@@ -1,6 +1,6 @@
 /** @vitest-environment jsdom */
-import { renderHook } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type {
   MessagePartState,
   ReasoningMessagePart,
@@ -32,7 +32,61 @@ const reasoningState = (text: string) =>
     status: { type: "complete", reason: "stop" },
   }) as MessagePartState & ReasoningMessagePart;
 
+const runningState = (text: string) =>
+  ({
+    type: "text",
+    text,
+    status: { type: "running" },
+  }) as MessagePartState & TextMessagePart;
+
+const driveAndCount = (minCommitMs: number) => {
+  const raf: FrameRequestCallback[] = [];
+  const rafSpy = vi
+    .spyOn(globalThis, "requestAnimationFrame")
+    .mockImplementation((cb) => {
+      raf.push(cb);
+      return raf.length;
+    });
+  const cafSpy = vi
+    .spyOn(globalThis, "cancelAnimationFrame")
+    .mockImplementation(() => {});
+  let now = 1000;
+  const nowSpy = vi.spyOn(Date, "now").mockImplementation(() => now);
+
+  const state = runningState("0123456789");
+  const { result, unmount } = renderHook(() =>
+    useSmooth(state, {
+      minCommitMs,
+      maxCharsPerFrame: 1,
+      maxCharIntervalMs: 1,
+    }),
+  );
+
+  const seen = new Set<string>();
+  let guard = 0;
+  while (raf.length > 0 && guard < 100) {
+    guard++;
+    const cb = raf.shift()!;
+    now += 16;
+    act(() => {
+      cb(now);
+    });
+    seen.add(result.current.text);
+  }
+
+  const final = result.current.text;
+  unmount();
+  rafSpy.mockRestore();
+  cafSpy.mockRestore();
+  nowSpy.mockRestore();
+  return { final, commits: seen.size };
+};
+
 describe("useSmooth", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it("returns the input state unchanged when disabled", () => {
     const state = textState("hello");
     const { result } = renderHook(() => useSmooth(state, false));
@@ -92,4 +146,54 @@ describe("useSmooth", () => {
     expect(result.current.text).toBe("hello");
     expect(result.current.status).toBe(state.status);
   });
+
+  it("commits fewer times under minCommitMs without losing characters", () => {
+    const everyFrame = driveAndCount(0);
+    const floored = driveAndCount(50);
+
+    expect(everyFrame.final).toBe("0123456789");
+    expect(floored.final).toBe("0123456789");
+    expect(floored.commits).toBeLessThan(everyFrame.commits);
+  });
+
+  it("commits the first frame after a discontinuity without waiting out minCommitMs", () => {
+    const raf: FrameRequestCallback[] = [];
+    vi.spyOn(globalThis, "requestAnimationFrame").mockImplementation((cb) => {
+      raf.push(cb);
+      return raf.length;
+    });
+    vi.spyOn(globalThis, "cancelAnimationFrame").mockImplementation(() => {});
+    let now = 1_000_000;
+    vi.spyOn(Date, "now").mockImplementation(() => now);
+
+    const frame = () => {
+      if (raf.length === 0) return;
+      const cb = raf.shift()!;
+      now += 16;
+      act(() => {
+        cb(now);
+      });
+    };
+
+    const options: SmoothOptions = {
+      minCommitMs: 10000,
+      maxCharsPerFrame: 1,
+      maxCharIntervalMs: 1,
+    };
+    const { result, rerender } = renderHook(
+      (part) => useSmooth(part, options),
+      {
+        initialProps: runningState("aaaaaaaaaa"),
+      },
+    );
+
+    frame();
+    expect(result.current.text).toBe("a");
+    frame();
+    expect(result.current.text).toBe("a");
+
+    rerender(runningState("zzzzzzzzzz"));
+    frame();
+    expect(result.current.text).toBe("z");
+  });
 });