@assistant-ui/react 0.15.8 → 0.15.10

package/src/tests/external-thread-speech.test.tsx

@@ -0,0 +1,328 @@
+// @vitest-environment jsdom
+
+import { act, render, waitFor } from "@testing-library/react";
+import type { FC } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AuiProvider, useAui } from "@assistant-ui/store";
+import type { SpeechSynthesisAdapter } from "@assistant-ui/core";
+import type {
+  ExternalThreadMessage,
+  ExternalThreadProps,
+} from "../client/ExternalThread";
+import { ExternalThread } from "../client/ExternalThread";
+
+const MESSAGES = [
+  {
+    id: "u1",
+    role: "user",
+    content: [{ type: "text", text: "hi" }],
+    createdAt: new Date(0),
+    attachments: [],
+    metadata: { custom: {} },
+  },
+  {
+    id: "a1",
+    role: "assistant",
+    content: [{ type: "text", text: "hello there" }],
+    createdAt: new Date(0),
+    metadata: { custom: {} },
+  },
+] as unknown as readonly ExternalThreadMessage[];
+
+type FakeUtterance = {
+  text: string;
+  cancel: ReturnType<typeof vi.fn>;
+  emit: (status: SpeechSynthesisAdapter.Status) => void;
+};
+
+const createFakeAdapter = () => {
+  const utterances: FakeUtterance[] = [];
+  const adapter: SpeechSynthesisAdapter = {
+    speak: (text) => {
+      const subscribers = new Set<() => void>();
+      // mirror WebSpeechSynthesisAdapter: cancel transitions to ended and notifies synchronously
+      const cancel = vi.fn(() => {
+        if (utterance.status.type === "ended") return;
+        utterance.status = { type: "ended", reason: "cancelled" };
+        for (const subscriber of subscribers) subscriber();
+      });
+      const utterance: SpeechSynthesisAdapter.Utterance = {
+        status: { type: "starting" },
+        cancel,
+        subscribe: (callback) => {
+          subscribers.add(callback);
+          return () => subscribers.delete(callback);
+        },
+      };
+      utterances.push({
+        text,
+        cancel,
+        emit: (status) => {
+          utterance.status = status;
+          for (const subscriber of subscribers) subscriber();
+        },
+      });
+      return utterance;
+    },
+  };
+  return { adapter, utterances };
+};
+
+const renderThreadWithProps = (props: Partial<ExternalThreadProps>) => {
+  const captured: { aui?: ReturnType<typeof useAui> } = {};
+  const Capture: FC = () => {
+    captured.aui = useAui();
+    return null;
+  };
+  const App: FC<{ props: Partial<ExternalThreadProps> }> = ({ props }) => {
+    const aui = useAui({
+      thread: ExternalThread({
+        messages: MESSAGES,
+        isRunning: false,
+        ...props,
+      }),
+    });
+    return (
+      <AuiProvider value={aui}>
+        <Capture />
+      </AuiProvider>
+    );
+  };
+
+  const view = render(<App props={props} />);
+  const aui = () => captured.aui!;
+  aui.rerender = (nextProps: Partial<ExternalThreadProps>) =>
+    view.rerender(<App props={nextProps} />);
+  aui.unmount = () => view.unmount();
+  return aui;
+};
+
+describe("ExternalThread speech", () => {
+  it("reports the speech capability based on adapter presence", () => {
+    const withoutAdapter = renderThreadWithProps({});
+    expect(withoutAdapter().thread.getState().capabilities.speech).toBe(false);
+
+    const { adapter } = createFakeAdapter();
+    const withAdapter = renderThreadWithProps({ speechAdapter: adapter });
+    expect(withAdapter().thread.getState().capabilities.speech).toBe(true);
+  });
+
+  it("throws on speak when no adapter is configured", () => {
+    const aui = renderThreadWithProps({});
+    expect(() => aui().thread.message({ id: "a1" }).speak()).toThrow(
+      "Speech adapter not configured",
+    );
+  });
+
+  it("tracks utterance status in thread and message state", async () => {
+    const { adapter, utterances } = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+
+    expect(utterances[0]!.text).toBe("hello there");
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toEqual({
+        messageId: "a1",
+        status: { type: "starting" },
+      });
+      expect(aui().thread.message({ id: "a1" }).getState().speech).toEqual({
+        messageId: "a1",
+        status: { type: "starting" },
+      });
+      expect(
+        aui().thread.message({ id: "u1" }).getState().speech,
+      ).toBeUndefined();
+    });
+
+    await act(async () => {
+      utterances[0]!.emit({ type: "running" });
+    });
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toEqual({
+        messageId: "a1",
+        status: { type: "running" },
+      });
+    });
+
+    await act(async () => {
+      utterances[0]!.emit({ type: "ended", reason: "finished" });
+    });
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toBeUndefined();
+      expect(
+        aui().thread.message({ id: "a1" }).getState().speech,
+      ).toBeUndefined();
+    });
+  });
+
+  it("cancels the previous utterance when a new speak starts", async () => {
+    const { adapter, utterances } = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+    await act(async () => {
+      aui().thread.message({ id: "u1" }).speak();
+    });
+
+    expect(utterances).toHaveLength(2);
+    expect(utterances[0]!.cancel).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toEqual({
+        messageId: "u1",
+        status: { type: "starting" },
+      });
+    });
+
+    await act(async () => {
+      utterances[0]!.emit({ type: "ended", reason: "cancelled" });
+    });
+    expect(aui().thread.getState().speech).toEqual({
+      messageId: "u1",
+      status: { type: "starting" },
+    });
+  });
+
+  it("stopSpeaking cancels the utterance and clears state", async () => {
+    const { adapter, utterances } = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+    await act(async () => {
+      aui().thread.stopSpeaking();
+    });
+
+    expect(utterances[0]!.cancel).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toBeUndefined();
+    });
+    expect(() => aui().thread.stopSpeaking()).toThrow(
+      "No message is being spoken",
+    );
+  });
+
+  it("message stopSpeaking throws unless that message is being spoken", async () => {
+    const { adapter, utterances } = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    expect(() => aui().thread.message({ id: "a1" }).stopSpeaking()).toThrow(
+      "Message is not being spoken",
+    );
+
+    // speak and stopSpeaking in the same tick, before any re-render
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+      expect(() => aui().thread.message({ id: "u1" }).stopSpeaking()).toThrow(
+        "Message is not being spoken",
+      );
+      aui().thread.message({ id: "a1" }).stopSpeaking();
+    });
+
+    expect(utterances[0]!.cancel).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toBeUndefined();
+    });
+  });
+
+  it("cancels the utterance when the adapter is removed", async () => {
+    const { adapter, utterances } = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+    await act(async () => {
+      aui.rerender({});
+    });
+
+    expect(utterances[0]!.cancel).toHaveBeenCalledTimes(1);
+    expect(aui().thread.getState().capabilities.speech).toBe(false);
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toBeUndefined();
+    });
+
+    await act(async () => {
+      utterances[0]!.emit({ type: "running" });
+    });
+    expect(aui().thread.getState().speech).toBeUndefined();
+  });
+
+  it("keeps the utterance alive when the adapter identity changes", async () => {
+    const first = createFakeAdapter();
+    const second = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: first.adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+    await act(async () => {
+      aui.rerender({ speechAdapter: second.adapter });
+    });
+
+    expect(first.utterances[0]!.cancel).not.toHaveBeenCalled();
+    expect(aui().thread.getState().speech).toEqual({
+      messageId: "a1",
+      status: { type: "starting" },
+    });
+
+    await act(async () => {
+      aui().thread.message({ id: "u1" }).speak();
+    });
+    expect(first.utterances[0]!.cancel).toHaveBeenCalledTimes(1);
+    expect(second.utterances[0]!.text).toBe("hi");
+    await waitFor(() => {
+      expect(aui().thread.getState().speech).toEqual({
+        messageId: "u1",
+        status: { type: "starting" },
+      });
+    });
+  });
+
+  it("handles utterances that end synchronously on subscribe", async () => {
+    const cancel = vi.fn();
+    const adapter: SpeechSynthesisAdapter = {
+      speak: () => ({
+        status: { type: "ended", reason: "finished" },
+        cancel,
+        subscribe: (callback) => {
+          callback();
+          return () => {};
+        },
+      }),
+    };
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+
+    expect(aui().thread.getState().speech).toBeUndefined();
+    expect(() => aui().thread.stopSpeaking()).toThrow(
+      "No message is being spoken",
+    );
+  });
+
+  it("cancels the utterance on unmount", async () => {
+    const { adapter, utterances } = createFakeAdapter();
+    const aui = renderThreadWithProps({ speechAdapter: adapter });
+
+    await act(async () => {
+      aui().thread.message({ id: "a1" }).speak();
+    });
+    await act(async () => {
+      aui.unmount();
+    });
+
+    expect(utterances[0]!.cancel).toHaveBeenCalledTimes(1);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+});

package/src/unstable/useLiveCompletionAdapter.test.tsx

@@ -129,6 +129,96 @@ describe("unstable_useLiveCompletionAdapter", () => {
     expect(result.current.adapter.search!("ab")).toEqual([item("ab")]);
   });
 
+  it("allows a failed query to be retried", async () => {
+    const fetcher = vi
+      .fn<(query: string) => Promise<readonly Unstable_TriggerItem[]>>()
+      .mockRejectedValueOnce(new Error("temporarily unavailable"))
+      .mockRejectedValueOnce(new Error("still unavailable"))
+      .mockResolvedValueOnce([item("alice")]);
+    const { result } = renderHook(() =>
+      unstable_useLiveCompletionAdapter({ fetcher, debounceMs: 0 }),
+    );
+
+    for (const attempt of [1, 2]) {
+      await act(async () => {
+        result.current.adapter.search!("alice");
+        await vi.advanceTimersByTimeAsync(0);
+      });
+      expect(fetcher).toHaveBeenCalledTimes(attempt);
+      expect(result.current.isLoading).toBe(false);
+    }
+
+    await act(async () => {
+      result.current.adapter.search!("alice");
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(fetcher).toHaveBeenCalledTimes(3);
+    expect(result.current.adapter.search!("alice")).toEqual([item("alice")]);
+  });
+
+  it("does not automatically retry when search runs during every render", async () => {
+    const fetcher = vi
+      .fn<(query: string) => Promise<readonly Unstable_TriggerItem[]>>()
+      .mockRejectedValueOnce(new Error("temporarily unavailable"))
+      .mockImplementation(
+        () => new Promise<readonly Unstable_TriggerItem[]>(() => {}),
+      );
+    const { result } = renderHook(() => {
+      const completion = unstable_useLiveCompletionAdapter({
+        fetcher,
+        debounceMs: 0,
+      });
+      completion.adapter.search!("alice");
+      return completion;
+    });
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(result.current.isLoading).toBe(false);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-arms a failed query when its pending retry is interrupted", async () => {
+    const fetcher = vi
+      .fn<(query: string) => Promise<readonly Unstable_TriggerItem[]>>()
+      .mockRejectedValueOnce(new Error("temporarily unavailable"))
+      .mockImplementationOnce(
+        () => new Promise<readonly Unstable_TriggerItem[]>(() => {}),
+      )
+      .mockResolvedValueOnce([item("alice")]);
+    const { result } = renderHook(() =>
+      unstable_useLiveCompletionAdapter({ fetcher, debounceMs: 0 }),
+    );
+
+    await act(async () => {
+      result.current.adapter.search!("alice");
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    await act(async () => {
+      result.current.adapter.search!("alice");
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(fetcher).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      result.current.adapter.search!("alicex");
+    });
+    await act(async () => {
+      result.current.adapter.search!("alice");
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    expect(fetcher).toHaveBeenCalledTimes(3);
+    expect(fetcher).toHaveBeenLastCalledWith("alice");
+    expect(result.current.adapter.search!("alice")).toEqual([item("alice")]);
+  });
+
   it("drops an in-flight fetch when the query returns to a cached value", async () => {
     const resolvers: Record<
       string,

package/src/unstable/useLiveCompletionAdapter.ts

@@ -57,7 +57,8 @@ export function unstable_useLiveCompletionAdapter(
   const [state, setState] = useState<{
     query: string;
     items: readonly Unstable_TriggerItem[];
-  }>({ query: NO_QUERY, items: [] });
+    failed: boolean;
+  }>({ query: NO_QUERY, items: [], failed: false });
   const [isLoading, setIsLoading] = useState(false);
 
   const fetcherRef = useRef(fetcher);
@@ -66,6 +67,8 @@ export function unstable_useLiveCompletionAdapter(
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const tokenRef = useRef(0);
   const pendingQueryRef = useRef<string | null>(null);
+  const retryableQueryRef = useRef<string | null>(null);
+  const pendingRetryQueryRef = useRef<string | null>(null);
 
   const cancelTimer = useCallback(() => {
     if (timerRef.current !== null) {
@@ -74,10 +77,22 @@ export function unstable_useLiveCompletionAdapter(
     }
   }, []);
 
+  const rearmPendingRetry = useCallback(() => {
+    const query = pendingRetryQueryRef.current;
+    if (query === null) return;
+    retryableQueryRef.current = query;
+    pendingRetryQueryRef.current = null;
+  }, []);
+
   const scheduleFetch = useCallback(
     (query: string) => {
       if (!enabled) return;
       if (pendingQueryRef.current === query) return;
+      rearmPendingRetry();
+      if (retryableQueryRef.current === query) {
+        retryableQueryRef.current = null;
+        pendingRetryQueryRef.current = query;
+      }
       pendingQueryRef.current = query;
       cancelTimer();
       const token = ++tokenRef.current;
@@ -87,37 +102,47 @@ export function unstable_useLiveCompletionAdapter(
         fetcherRef.current(query).then(
           (items) => {
             if (token !== tokenRef.current) return;
-            setState({ query, items });
+            pendingRetryQueryRef.current = null;
+            setState({ query, items, failed: false });
             setIsLoading(false);
           },
           () => {
             if (token !== tokenRef.current) return;
-            setState({ query, items: [] });
+            pendingQueryRef.current = null;
+            pendingRetryQueryRef.current = null;
+            setState({ query, items: [], failed: true });
             setIsLoading(false);
           },
         );
       }, debounceMs);
     },
-    [enabled, debounceMs, cancelTimer],
+    [enabled, debounceMs, cancelTimer, rearmPendingRetry],
   );
 
   const invalidatePending = useCallback(() => {
+    rearmPendingRetry();
     cancelTimer();
     pendingQueryRef.current = null;
     tokenRef.current += 1;
     setIsLoading(false);
-  }, [cancelTimer]);
+  }, [cancelTimer, rearmPendingRetry]);
 
   useEffect(() => {
     if (enabled) return;
     invalidatePending();
     setState((s) =>
-      s.query === NO_QUERY ? s : { query: NO_QUERY, items: [] },
+      s.query === NO_QUERY ? s : { query: NO_QUERY, items: [], failed: false },
     );
   }, [enabled, invalidatePending]);
 
   useEffect(() => cancelTimer, [cancelTimer]);
 
+  // Arm retries only after the failed state commits. Arming during rejection
+  // would let the failure render immediately schedule another request.
+  useEffect(() => {
+    retryableQueryRef.current = state.failed ? state.query : null;
+  }, [state]);
+
   const adapter = useMemo<Unstable_TriggerAdapter>(
     () => ({
       categories: () => [],
@@ -125,7 +150,7 @@ export function unstable_useLiveCompletionAdapter(
       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) {
+        if (query !== state.query || retryableQueryRef.current === query) {
           queueMicrotask(() => scheduleFetch(query));
         } else if (
           pendingQueryRef.current !== null &&