@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/src/primitives/thread/ThreadRoot.test.tsx

@@ -0,0 +1,419 @@
+// @vitest-environment jsdom
+
+import { screen } from "@testing-library/dom";
+import { defineComponent, h } from "vue";
+import { act, cleanup, render } from "../../tests/vue";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AssistantRuntimeProvider } from "@ulearning/ai-core/vue";
+import { useLocalRuntime } from "@ulearning/ai-core/vue";
+import type {
+  ChatModelAdapter,
+  SpeechSynthesisAdapter,
+  ThreadMessageLike,
+} from "../../index";
+import { ComposerPrimitiveInput } from "../composer/ComposerInput";
+import { ThreadPrimitiveRoot } from "./ThreadRoot";
+
+const noOpAdapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const waitForAbortAdapter: ChatModelAdapter = {
+  async *run({ abortSignal }) {
+    await new Promise<void>((resolve) => {
+      if (abortSignal.aborted) {
+        resolve();
+        return;
+      }
+      abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+  },
+};
+
+const initialMessages: ThreadMessageLike[] = [
+  {
+    role: "assistant",
+    content: [{ type: "text", text: "Hello" }],
+    status: { type: "complete", reason: "stop" },
+  },
+];
+
+const createSpeechAdapter = () => {
+  const cancel = vi.fn();
+  const subscribers = new Set<() => void>();
+  const utterance: SpeechSynthesisAdapter.Utterance = {
+    status: { type: "running" },
+    cancel,
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+  };
+  const adapter: SpeechSynthesisAdapter = {
+    speak: vi.fn(() => utterance),
+  };
+  const finish = () => {
+    utterance.status = { type: "ended", reason: "finished" };
+    for (const subscriber of subscribers) subscriber();
+  };
+
+  return { adapter, cancel, finish };
+};
+
+type RuntimeRef = {
+  current: ReturnType<typeof useLocalRuntime> | null;
+};
+
+afterEach(cleanup);
+const waitFor = vi.waitFor;
+const RuntimeProvider = defineComponent<{
+  runtimeRef: RuntimeRef;
+  speech: SpeechSynthesisAdapter;
+  chatModel?: ChatModelAdapter;
+}>(
+  (props, { slots }) => {
+    const runtime = useLocalRuntime(props.chatModel ?? noOpAdapter, {
+      initialMessages,
+      adapters: { speech: props.speech },
+    });
+    props.runtimeRef.current = runtime;
+    return () =>
+      h(
+        AssistantRuntimeProvider,
+        { runtime },
+        { default: () => h(ThreadPrimitiveViewportProvider, null, slots) },
+      );
+  },
+  { props: ["runtimeRef", "speech", "chatModel"] },
+);
+
+const startSpeaking = (runtimeRef: RuntimeRef) => {
+  act(() => {
+    runtimeRef.current!.thread.getMessageByIndex(0).speak();
+  });
+};
+
+const dispatchEscape = (target: EventTarget) => {
+  const event = new KeyboardEvent("keydown", {
+    key: "Escape",
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+  });
+  act(() => target.dispatchEvent(event));
+  return event;
+};
+
+describe("ThreadPrimitiveRoot", () => {
+  it("stops active speech after the initiating control unmounts", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    const App = ({ showControl }: { showControl: boolean }) => (
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot>
+          {showControl && <button data-testid="speak-control" />}
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>
+    );
+    const view = render(<App showControl />);
+
+    const control = screen.getByTestId("speak-control");
+    control.focus();
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    await view.rerender(<App showControl={false} />);
+    const event = dispatchEscape(document.body);
+
+    expect(speech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("does not consume Escape when no speech is active", () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot>
+          <button data-testid="thread-control" />
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>,
+    );
+
+    const event = dispatchEscape(screen.getByTestId("thread-control"));
+
+    expect(speech.cancel).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("does not stop speech in another mounted thread", async () => {
+    const firstSpeech = createSpeechAdapter();
+    const secondSpeech = createSpeechAdapter();
+    const firstRuntimeRef: RuntimeRef = { current: null };
+    const secondRuntimeRef: RuntimeRef = { current: null };
+    render(
+      <>
+        <RuntimeProvider
+          runtimeRef={firstRuntimeRef}
+          speech={firstSpeech.adapter}
+        >
+          <ThreadPrimitiveRoot>
+            <button data-testid="first-thread-control" />
+          </ThreadPrimitiveRoot>
+        </RuntimeProvider>
+        <RuntimeProvider
+          runtimeRef={secondRuntimeRef}
+          speech={secondSpeech.adapter}
+        >
+          <ThreadPrimitiveRoot>
+            <button data-testid="second-thread-control" />
+          </ThreadPrimitiveRoot>
+        </RuntimeProvider>
+      </>,
+    );
+    startSpeaking(firstRuntimeRef);
+    await waitFor(() => {
+      expect(firstRuntimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    const event = dispatchEscape(screen.getByTestId("second-thread-control"));
+
+    expect(firstSpeech.cancel).not.toHaveBeenCalled();
+    expect(secondSpeech.cancel).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("stops speech in the thread containing the Escape target", async () => {
+    const firstSpeech = createSpeechAdapter();
+    const secondSpeech = createSpeechAdapter();
+    const firstRuntimeRef: RuntimeRef = { current: null };
+    const secondRuntimeRef: RuntimeRef = { current: null };
+    render(
+      <>
+        <RuntimeProvider
+          runtimeRef={firstRuntimeRef}
+          speech={firstSpeech.adapter}
+        >
+          <ThreadPrimitiveRoot>
+            <button data-testid="first-thread-control" />
+          </ThreadPrimitiveRoot>
+        </RuntimeProvider>
+        <RuntimeProvider
+          runtimeRef={secondRuntimeRef}
+          speech={secondSpeech.adapter}
+        >
+          <ThreadPrimitiveRoot>
+            <button data-testid="second-thread-control" />
+          </ThreadPrimitiveRoot>
+        </RuntimeProvider>
+      </>,
+    );
+    startSpeaking(firstRuntimeRef);
+    startSpeaking(secondRuntimeRef);
+    await waitFor(() => {
+      expect(firstRuntimeRef.current!.thread.getState().speech).toBeDefined();
+      expect(secondRuntimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    const event = dispatchEscape(screen.getByTestId("second-thread-control"));
+
+    expect(firstSpeech.cancel).not.toHaveBeenCalled();
+    expect(secondSpeech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("stops speech in a thread mounted inside a closed shadow root", async () => {
+    const firstSpeech = createSpeechAdapter();
+    const secondSpeech = createSpeechAdapter();
+    const firstRuntimeRef: RuntimeRef = { current: null };
+    const secondRuntimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider
+        runtimeRef={firstRuntimeRef}
+        speech={firstSpeech.adapter}
+      >
+        <ThreadPrimitiveRoot />
+      </RuntimeProvider>,
+    );
+    const shadowHost = document.createElement("div");
+    const shadowRoot = shadowHost.attachShadow({ mode: "closed" });
+    const shadowContainer = document.createElement("div");
+    shadowRoot.append(shadowContainer);
+    document.body.append(shadowHost);
+    const shadowView = render(
+      <RuntimeProvider
+        runtimeRef={secondRuntimeRef}
+        speech={secondSpeech.adapter}
+      >
+        <ThreadPrimitiveRoot>
+          <button data-testid="shadow-thread-control" />
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>,
+      { container: shadowContainer },
+    );
+
+    try {
+      startSpeaking(firstRuntimeRef);
+      startSpeaking(secondRuntimeRef);
+      await waitFor(() => {
+        expect(firstRuntimeRef.current!.thread.getState().speech).toBeDefined();
+        expect(
+          secondRuntimeRef.current!.thread.getState().speech,
+        ).toBeDefined();
+      });
+
+      const event = dispatchEscape(
+        shadowContainer.querySelector("[data-testid=shadow-thread-control]")!,
+      );
+
+      expect(firstSpeech.cancel).not.toHaveBeenCalled();
+      expect(secondSpeech.cancel).toHaveBeenCalledOnce();
+      expect(event.defaultPrevented).toBe(true);
+    } finally {
+      shadowView.unmount();
+      shadowHost.remove();
+    }
+  });
+
+  it("stops speech from outside the only mounted thread", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <>
+        <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+          <ThreadPrimitiveRoot />
+        </RuntimeProvider>
+        <button data-testid="outside-control" />
+      </>,
+    );
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    const event = dispatchEscape(screen.getByTestId("outside-control"));
+
+    expect(speech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("ignores speech ending between the rendered state and Escape", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot />
+      </RuntimeProvider>,
+    );
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    expect(() => {
+      act(() => {
+        speech.finish();
+        document.body.dispatchEvent(
+          new KeyboardEvent("keydown", {
+            key: "Escape",
+            bubbles: true,
+            cancelable: true,
+          }),
+        );
+      });
+    }).not.toThrow();
+    expect(speech.cancel).not.toHaveBeenCalled();
+  });
+
+  it("lets a composer mounted after the root consume Escape first", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    const App = ({ showComposer }: { showComposer: boolean }) => (
+      <RuntimeProvider
+        runtimeRef={runtimeRef}
+        speech={speech.adapter}
+        chatModel={waitForAbortAdapter}
+      >
+        <ThreadPrimitiveRoot>
+          {showComposer && <ComposerPrimitiveInput data-testid="composer" />}
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>
+    );
+    const view = render(<App showComposer={false} />);
+    startSpeaking(runtimeRef);
+    act(() => {
+      runtimeRef.current!.thread.append("Run");
+    });
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+      expect(runtimeRef.current!.thread.getState().isRunning).toBe(true);
+    });
+
+    await view.rerender(<App showComposer />);
+    const event = dispatchEscape(screen.getByTestId("composer"));
+
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().isRunning).toBe(false);
+    });
+    expect(speech.cancel).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it.each([
+    ["during the composition", { isComposing: true }],
+    ["after compositionend (Safari)", { keyCode: 229 }],
+  ])(
+    "keeps speech playing when Escape ends an IME composition %s",
+    async (_, init) => {
+      const speech = createSpeechAdapter();
+      const runtimeRef: RuntimeRef = { current: null };
+      render(
+        <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+          <ThreadPrimitiveRoot>
+            <ComposerPrimitiveInput data-testid="composer" />
+          </ThreadPrimitiveRoot>
+        </RuntimeProvider>,
+      );
+      startSpeaking(runtimeRef);
+      await waitFor(() => {
+        expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+      });
+
+      const event = new KeyboardEvent("keydown", {
+        key: "Escape",
+        bubbles: true,
+        cancelable: true,
+        ...init,
+      });
+      act(() => screen.getByTestId("composer").dispatchEvent(event));
+
+      expect(speech.cancel).not.toHaveBeenCalled();
+      expect(event.defaultPrevented).toBe(false);
+    },
+  );
+
+  it("lets an idle composer fall through so Escape still stops speech", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot>
+          <ComposerPrimitiveInput data-testid="composer" />
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>,
+    );
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    const event = dispatchEscape(screen.getByTestId("composer"));
+
+    expect(speech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+    expect(runtimeRef.current!.thread.getState().isRunning).toBe(false);
+  });
+});

package/src/primitives/thread/ThreadRoot.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+import { Primitive, type PrimitiveProps } from "../../utils/Primitive";
+import { isCompositionKey } from "../../utils/isCompositionKey";
+import {
+  defineComponent,
+  h,
+  mergeProps,
+  provide,
+  shallowRef,
+  type ComponentPublicInstance,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useAui } from "@ulearning/ai-store";
+import { ThreadRootElementContext } from "./ThreadRootElementContext";
+
+const escapeEventThreadRoots = new WeakMap<KeyboardEvent, Element>();
+
+export namespace ThreadPrimitiveRoot {
+  export type Element = ComponentPublicInstance;
+  /**
+   * Props for the ThreadPrimitive.Root component.
+   * Accepts all standard div element props.
+   */
+  export type Props = PrimitiveProps<"div">;
+}
+
+/**
+ * The root container component for a thread.
+ *
+ * This component serves as the foundational wrapper for all thread-related components.
+ * It provides the basic structure and context needed for thread functionality.
+ *
+ * While this component is mounted, an unhandled Escape keydown inside this thread stops its
+ * active speech, even if the action bar that started it is no longer mounted. Escape outside
+ * every thread retains the document-level fallback.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.Root>
+ *   <ThreadPrimitive.Viewport>
+ *     <ThreadPrimitive.Messages>
+ *       {() => <MyMessage />}
+ *     </ThreadPrimitive.Messages>
+ *   </ThreadPrimitive.Viewport>
+ * </ThreadPrimitive.Root>
+ * ```
+ */
+export const ThreadPrimitiveRoot = defineComponent<ThreadPrimitiveRoot.Props>(
+  (props, { attrs, slots }) => {
+    const { forwardRef } = useForwardExpose();
+    const aui = useAui();
+    const root = shallowRef<HTMLElement | null>(null);
+    provide(ThreadRootElementContext, root);
+    const setElement = (instance: Element | ComponentPublicInstance | null) => {
+      forwardRef(instance);
+      const element = instance instanceof Element ? instance : instance?.$el;
+      root.value = element instanceof HTMLElement ? element : null;
+    };
+    const markRoot = (event: KeyboardEvent) => {
+      if (event.key === "Escape" && root.value)
+        escapeEventThreadRoots.set(event, root.value);
+    };
+    useIsomorphicLayoutEffect(() => {
+      const doc = root.value?.ownerDocument;
+      if (!doc) return undefined;
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key !== "Escape" || isCompositionKey(event)) return;
+        if (event.defaultPrevented || aui.thread.source === null) return;
+        const eventThreadRoot =
+          escapeEventThreadRoots.get(event) ??
+          event
+            .composedPath()
+            .find(
+              (target) =>
+                target instanceof Element &&
+                target.hasAttribute("data-aui-thread-root"),
+            );
+        if (eventThreadRoot && eventThreadRoot !== root.value) return;
+        if (aui.thread.getState().speech == null) return;
+        event.preventDefault();
+        try {
+          aui.thread.stopSpeaking();
+        } catch (error) {
+          if (
+            !(error instanceof Error) ||
+            error.message !== "No message is being spoken"
+          )
+            throw error;
+        }
+      };
+      doc.addEventListener("keydown", handleKeyDown);
+      return () => doc.removeEventListener("keydown", handleKeyDown);
+    });
+    return () =>
+      h(
+        Primitive.div,
+        {
+          ...attrs,
+          render: props.render,
+          asChild: props.asChild,
+          children: props.children,
+          "data-aui-thread-root": "",
+          ref: setElement,
+          ...mergeProps(
+            { onKeydown: markRoot },
+            { onKeydown: attrs.onKeydown },
+          ),
+        },
+        slots,
+      );
+  },
+  {
+    name: "ThreadPrimitive.Root",
+    inheritAttrs: false,
+    props: ["render", "asChild", "children"],
+  },
+);

package/src/primitives/thread/ThreadRootElementContext.ts

@@ -0,0 +1,9 @@
+"use client";
+
+import { inject, type InjectionKey, type ShallowRef } from "vue";
+
+export const ThreadRootElementContext: InjectionKey<
+  ShallowRef<HTMLElement | null>
+> = Symbol("aui.ThreadRootElement");
+export const useThreadRootElementRef = () =>
+  inject(ThreadRootElementContext, undefined);

package/src/primitives/thread/ThreadScrollToBottom.ts

@@ -0,0 +1,45 @@
+"use client";
+
+import {
+  type ActionButtonElement,
+  type ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+import { computed } from "vue";
+import {
+  useThreadViewport,
+  useThreadViewportStore,
+} from "../../context/vue/ThreadViewportContext";
+
+export namespace useThreadScrollToBottom {
+  export type Options = {
+    behavior?: ScrollBehavior | undefined;
+  };
+}
+
+const useThreadScrollToBottom = (
+  options: useThreadScrollToBottom.Options = {},
+) => {
+  const isAtBottom = useThreadViewport((s) => s.isAtBottom);
+
+  const threadViewportStore = useThreadViewportStore();
+
+  const handleScrollToBottom = () => {
+    threadViewportStore
+      .getState()
+      .scrollToBottom({ behavior: options.behavior });
+  };
+
+  return computed(() => (isAtBottom.value ? null : handleScrollToBottom));
+};
+
+export namespace ThreadPrimitiveScrollToBottom {
+  export type Element = ActionButtonElement;
+  export type Props = ActionButtonProps<typeof useThreadScrollToBottom>;
+}
+
+export const ThreadPrimitiveScrollToBottom = createActionButton(
+  "ThreadPrimitive.ScrollToBottom",
+  useThreadScrollToBottom,
+  ["behavior"],
+);

package/src/primitives/thread/ThreadSuggestion.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { computed } from "vue";
+
+import {
+  type ActionButtonElement,
+  type ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+import { useSuggestionTrigger as useSuggestionTriggerBehavior } from "@ulearning/ai-core/vue";
+
+const useThreadSuggestion = (options: {
+  /** The suggestion prompt. */
+  prompt: string;
+
+  /**
+   * When true, automatically sends the message.
+   * When false, replaces or appends the composer text with the suggestion - depending on the value of `clearComposer`.
+   */
+  send?: boolean | undefined;
+
+  /**
+   * Whether to clear the composer after sending. A send queued while a run is
+   * in progress never clears the composer.
+   * When send is set to false, determines if composer text is replaced with suggestion (true, default),
+   * or if it's appended to the composer text (false).
+   *
+   * @default true
+   */
+  clearComposer?: boolean | undefined;
+
+  /** @deprecated Use `send` instead. */
+  autoSend?: boolean | undefined;
+
+  /** @deprecated Use `clearComposer` instead. */
+  method?: "replace";
+}) => {
+  const { disabled, trigger } = useSuggestionTriggerBehavior(() => ({
+    prompt: options.prompt,
+    send: options.send ?? options.autoSend ?? false,
+    clearComposer: options.clearComposer,
+  }));
+  return computed(() => (disabled.value ? null : trigger));
+};
+
+export namespace ThreadPrimitiveSuggestion {
+  export type Element = ActionButtonElement;
+  export type Props = ActionButtonProps<typeof useThreadSuggestion>;
+}
+
+export const ThreadPrimitiveSuggestion = createActionButton(
+  "ThreadPrimitive.Suggestion",
+  useThreadSuggestion,
+  ["prompt", "send", "clearComposer", "autoSend", "method"],
+);

package/src/primitives/thread/ThreadSuggestions.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+export {
+  ThreadPrimitiveSuggestions,
+  ThreadPrimitiveSuggestionsImpl,
+  ThreadPrimitiveSuggestionByIndex,
+} from "@ulearning/ai-core/vue";