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

package/src/primitives/messagePart/useMessagePartData.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { defineComponent, h, nextTick, shallowRef } from "vue";
+import { afterEach, expect, it } from "vitest";
+import { resource } from "@ulearning/ai-tap";
+import { AuiConfig, AuiProvider, type ClientOutput } from "@ulearning/ai-store";
+import type { MessagePartState } from "@ulearning/ai-core";
+import { cleanup, render } from "../../tests/vue";
+import { useMessagePartData } from "./useMessagePartData";
+
+afterEach(cleanup);
+
+const Part = resource(function Part({
+  state,
+}: {
+  state: MessagePartState;
+}): ClientOutput<"part"> {
+  return {
+    getState: () => state,
+    addToolResult: () => {},
+    resumeToolCall: () => {},
+    respondToToolApproval: async () => {},
+  };
+});
+
+it("follows real scoped part changes and keeps non-data and name mismatches nullable", async () => {
+  const state = shallowRef<MessagePartState>({
+    type: "text",
+    text: "text",
+    status: { type: "complete" },
+  });
+  const Probe = defineComponent({
+    setup() {
+      const selected = useMessagePartData<{ count: number }>("counter");
+      return () =>
+        h(
+          "output",
+          selected.value === null ? "none" : String(selected.value.data.count),
+        );
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup: () => () =>
+          h(
+            AuiProvider,
+            { config: AuiConfig({ part: Part({ state: state.value }) }) },
+            {
+              default: () => h(Probe),
+            },
+          ),
+      }),
+    ),
+  );
+  const element = view.container.querySelector("output");
+  expect(element?.textContent).toBe("none");
+  state.value = {
+    type: "data",
+    name: "counter",
+    data: { count: 2 },
+    status: { type: "complete" },
+  };
+  await nextTick();
+  expect(element?.textContent).toBe("2");
+  state.value = {
+    type: "data",
+    name: "different",
+    data: { count: 3 },
+    status: { type: "complete" },
+  };
+  await nextTick();
+  expect(element?.textContent).toBe("none");
+  state.value = {
+    type: "reasoning",
+    text: "reasoning",
+    status: { type: "complete" },
+  };
+  await nextTick();
+  expect(element?.textContent).toBe("none");
+  state.value = {
+    type: "data",
+    name: "counter",
+    data: { count: 4 },
+    status: { type: "complete" },
+  };
+  await nextTick();
+  expect(element?.textContent).toBe("4");
+  expect(view.container.querySelector("output")).toBe(element);
+});
+
+it("allows every named data part when the optional name filter is absent", () => {
+  const state: MessagePartState = {
+    type: "data",
+    name: "any-name",
+    data: { count: 7 },
+    status: { type: "complete" },
+  };
+  const Probe = defineComponent({
+    setup() {
+      const selected = useMessagePartData<{ count: number }>();
+      return () =>
+        h(
+          "output",
+          selected.value === null
+            ? "none"
+            : `${selected.value.name}:${selected.value.data.count}`,
+        );
+    },
+  });
+  const view = render(
+    h(
+      AuiProvider,
+      { config: AuiConfig({ part: Part({ state }) }) },
+      { default: () => h(Probe) },
+    ),
+  );
+  expect(view.container.textContent).toBe("any-name:7");
+});

package/src/primitives/messagePart/useMessagePartData.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import { computed } from "vue";
+import type { DataMessagePart } from "@ulearning/ai-core";
+import { useAuiState } from "@ulearning/ai-store";
+
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
+ *
+ * @example
+ * ```tsx
+ * const part = useAuiState((s) =>
+ *   s.part.type === "data" && (!name || s.part.name === name)
+ *     ? s.part
+ *     : null,
+ * );
+ * ```
+ */
+export const useMessagePartData = <T = any>(name?: string) => {
+  const part = useAuiState((s) => {
+    if (s.part.type !== "data") {
+      return null;
+    }
+    return s.part as DataMessagePart<T>;
+  });
+
+  return computed(() => {
+    const value = part.value;
+    return value !== null && (!name || value.name === name) ? value : null;
+  });
+};

package/src/primitives/messagePart/useMessagePartFile.ts

@@ -0,0 +1,42 @@
+"use client";
+
+import type {
+  FileMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@ulearning/ai-core";
+import { useAuiState } from "@ulearning/ai-store";
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_FILE_PART: MessagePartState & FileMessagePart = Object.freeze({
+  type: "file",
+  data: "",
+  mimeType: "",
+  status: COMPLETE_STATUS,
+});
+
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
+ *
+ * @example
+ * ```tsx
+ * const file = useAuiState((s) => {
+ *   if (s.part.type !== "file") return null;
+ *   return s.part;
+ * });
+ * ```
+ */
+export const useMessagePartFile = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
+  const file = useAuiState((s) => {
+    if (s.part.type !== "file") return EMPTY_FILE_PART;
+
+    return s.part as MessagePartState & FileMessagePart;
+  });
+
+  return file;
+};

package/src/primitives/messagePart/useMessagePartImage.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import type {
+  ImageMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@ulearning/ai-core";
+import { useAuiState } from "@ulearning/ai-store";
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_IMAGE_PART: MessagePartState & ImageMessagePart = Object.freeze({
+  type: "image",
+  image: "",
+  status: COMPLETE_STATUS,
+});
+
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
+ *
+ * @example
+ * ```tsx
+ * const image = useAuiState((s) => {
+ *   if (s.part.type !== "image") return null;
+ *   return s.part;
+ * });
+ * ```
+ */
+export const useMessagePartImage = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
+  const image = useAuiState((s) => {
+    if (s.part.type !== "image") return EMPTY_IMAGE_PART;
+
+    return s.part as MessagePartState & ImageMessagePart;
+  });
+
+  return image;
+};

package/src/primitives/messagePart/useMessagePartReasoning.ts

@@ -0,0 +1,42 @@
+"use client";
+
+import type {
+  ReasoningMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@ulearning/ai-core";
+import { useAuiState } from "@ulearning/ai-store";
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_REASONING_PART: MessagePartState & ReasoningMessagePart =
+  Object.freeze({
+    type: "reasoning",
+    text: "",
+    status: COMPLETE_STATUS,
+  });
+
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
+ *
+ * @example
+ * ```tsx
+ * const reasoning = useAuiState((s) => {
+ *   if (s.part.type !== "reasoning") return null;
+ *   return s.part;
+ * });
+ * ```
+ */
+export const useMessagePartReasoning = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
+  const text = useAuiState((s) => {
+    if (s.part.type !== "reasoning") return EMPTY_REASONING_PART;
+
+    return s.part as MessagePartState & ReasoningMessagePart;
+  });
+
+  return text;
+};

package/src/primitives/messagePart/useMessagePartSource.ts

@@ -0,0 +1,43 @@
+"use client";
+
+import type {
+  SourceMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@ulearning/ai-core";
+import { useAuiState } from "@ulearning/ai-store";
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_SOURCE_PART: MessagePartState & SourceMessagePart = Object.freeze({
+  type: "source",
+  sourceType: "url",
+  id: "",
+  url: "",
+  status: COMPLETE_STATUS,
+});
+
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
+ *
+ * @example
+ * ```tsx
+ * const source = useAuiState((s) => {
+ *   if (s.part.type !== "source") return null;
+ *   return s.part;
+ * });
+ * ```
+ */
+export const useMessagePartSource = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
+  const source = useAuiState((s) => {
+    if (s.part.type !== "source") return EMPTY_SOURCE_PART;
+
+    return s.part as MessagePartState & SourceMessagePart;
+  });
+
+  return source;
+};

package/src/primitives/messagePart/useMessagePartText.ts

@@ -0,0 +1,45 @@
+"use client";
+
+import type {
+  TextMessagePart,
+  ReasoningMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@ulearning/ai-core";
+import { useAuiState } from "@ulearning/ai-store";
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_TEXT_PART: MessagePartState & TextMessagePart = Object.freeze({
+  type: "text",
+  text: "",
+  status: COMPLETE_STATUS,
+});
+
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
+ *
+ * @example
+ * ```tsx
+ * const text = useAuiState((s) => {
+ *   if (s.part.type !== "text" && s.part.type !== "reasoning") return null;
+ *   return s.part;
+ * });
+ * ```
+ */
+export const useMessagePartText = () => {
+  // Runs inside useSyncExternalStore's getSnapshot, where a throw tears down
+  // the React root; the module-level frozen sentinel keeps snapshots stable.
+  const text = useAuiState((s) => {
+    if (s.part.type !== "text" && s.part.type !== "reasoning")
+      return EMPTY_TEXT_PART;
+
+    return s.part as MessagePartState &
+      (TextMessagePart | ReasoningMessagePart);
+  });
+
+  return text;
+};

package/src/primitives/messagePart.ts

@@ -0,0 +1,4 @@
+export { MessagePartPrimitiveText as Text } from "./messagePart/MessagePartText";
+export { MessagePartPrimitiveImage as Image } from "./messagePart/MessagePartImage";
+export { MessagePartPrimitiveInProgress as InProgress } from "./messagePart/MessagePartInProgress";
+export { PartPrimitiveMessages as Messages } from "@ulearning/ai-core/vue";

package/src/primitives/native-action-bindings.test.ts

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+import { defineComponent, h, nextTick, shallowRef, type VNode } from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { useAui } from "@ulearning/ai-store";
+import {
+  AssistantRuntimeProvider,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type {
+  AppendMessage,
+  ExternalStoreAdapter,
+  ThreadMessageLike,
+} from "@ulearning/ai-core";
+import { cleanup, render } from "../tests/vue";
+import { ComposerPrimitiveSend } from "./composer/ComposerSend";
+import { ComposerPrimitiveResume } from "./composer/ComposerResume";
+import { ThreadPrimitiveSuggestion } from "./thread/ThreadSuggestion";
+import { ThreadPrimitiveLoadEarlier } from "./thread/ThreadLoadEarlier";
+
+afterEach(cleanup);
+
+function mountActions(
+  buttons: () => VNode[],
+  initial: Partial<ExternalStoreAdapter<ThreadMessageLike>> = {},
+) {
+  const adapter = shallowRef<ExternalStoreAdapter<ThreadMessageLike>>({
+    messages: [],
+    convertMessage: (message: ThreadMessageLike) => message,
+    onNew: async () => {},
+    ...initial,
+  });
+  let aui!: ReturnType<typeof useAui>;
+  const Actions = defineComponent({
+    setup() {
+      aui = useAui();
+      return () => h("div", buttons());
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup() {
+          const runtime = useExternalStoreRuntime(adapter);
+          return () =>
+            h(
+              AssistantRuntimeProvider,
+              { runtime },
+              { default: () => h(Actions) },
+            );
+        },
+      }),
+    ),
+  );
+  return {
+    ...view,
+    adapter,
+    get aui() {
+      return aui;
+    },
+    async update(value: Partial<ExternalStoreAdapter<ThreadMessageLike>>) {
+      flushTapSync(() => {
+        adapter.value = { ...adapter.value, ...value };
+      });
+      await nextTick();
+    },
+  };
+}
+
+it("updates send availability from real draft and disabled state without replacing the button", async () => {
+  const onNew = vi.fn(async (_message: AppendMessage) => {});
+  const view = mountActions(
+    () => [h(ComposerPrimitiveSend, { "aria-label": "Send" })],
+    { onNew },
+  );
+  const button = view.container.querySelector("button")!;
+  expect(button.disabled).toBe(true);
+  flushTapSync(() => view.aui.composer.setText("draft"));
+  await nextTick();
+  expect(button.disabled).toBe(false);
+  await view.update({ isSendDisabled: true });
+  expect(button.disabled).toBe(true);
+  button.click();
+  expect(onNew).not.toHaveBeenCalled();
+  await view.update({ isSendDisabled: false });
+  button.click();
+  await vi.waitFor(() => expect(onNew).toHaveBeenCalledOnce());
+  expect(onNew.mock.calls[0]?.[0]).toMatchObject({
+    role: "user",
+    content: [{ type: "text", text: "draft" }],
+  });
+  expect(view.container.querySelector("button")).toBe(button);
+});
+
+it("uses changed suggestion props and retains the draft when sending is blocked", async () => {
+  const prompt = shallowRef("first");
+  const send = shallowRef(false);
+  const clearComposer = shallowRef(true);
+  const onNew = vi.fn(async (_message: AppendMessage) => {});
+  const view = mountActions(
+    () => [
+      h(ThreadPrimitiveSuggestion, {
+        prompt: prompt.value,
+        send: send.value,
+        clearComposer: clearComposer.value,
+      }),
+    ],
+    { onNew },
+  );
+  const button = view.container.querySelector("button")!;
+  flushTapSync(() => button.click());
+  await nextTick();
+  expect(view.aui.composer.getState().text).toBe("first");
+  prompt.value = "second";
+  clearComposer.value = false;
+  await nextTick();
+  flushTapSync(() => button.click());
+  await nextTick();
+  expect(view.aui.composer.getState().text).toBe("first second");
+  send.value = true;
+  await nextTick();
+  await view.update({ isSendDisabled: true });
+  expect(button.disabled).toBe(true);
+  button.click();
+  expect(onNew).not.toHaveBeenCalled();
+  expect(view.aui.composer.getState().text).toBe("first second");
+  await view.update({ isSendDisabled: false });
+  button.click();
+  await vi.waitFor(() => expect(onNew).toHaveBeenCalledOnce());
+  expect(onNew.mock.calls[0]?.[0]).toMatchObject({
+    content: [{ type: "text", text: "second" }],
+  });
+});
+
+it("keeps paging enabled and focused while a repeated press joins the pending page", async () => {
+  const page = Promise.withResolvers<void>();
+  const onLoadEarlier = vi.fn(() => page.promise);
+  const view = mountActions(() => [h(ThreadPrimitiveLoadEarlier)], {
+    hasEarlier: true,
+    onLoadEarlier,
+  });
+  const button = view.container.querySelector("button")!;
+  button.focus();
+  button.click();
+  button.click();
+  await vi.waitFor(() => expect(onLoadEarlier).toHaveBeenCalledOnce());
+  expect(button.disabled).toBe(false);
+  expect(document.activeElement).toBe(button);
+  page.resolve();
+  await page.promise;
+  await view.update({ hasEarlier: false });
+  expect(button.disabled).toBe(true);
+  button.click();
+  expect(onLoadEarlier).toHaveBeenCalledOnce();
+});
+
+it("enables resume only for a checkpoint and preserves its parent message", async () => {
+  const onResume = vi.fn(async (_config: { parentId: string | null }) => {});
+  const view = mountActions(() => [h(ComposerPrimitiveResume)], {
+    messages: [
+      {
+        id: "checkpoint",
+        role: "assistant",
+        content: [],
+        status: { type: "incomplete", reason: "cancelled" },
+      },
+    ],
+    onResume,
+    canResume: false,
+  });
+  const button = view.container.querySelector("button")!;
+  expect(button.disabled).toBe(true);
+  await view.update({ canResume: true });
+  expect(button.disabled).toBe(false);
+  button.click();
+  await vi.waitFor(() => expect(onResume).toHaveBeenCalledOnce());
+  expect(onResume.mock.calls[0]?.[0]).toMatchObject({ parentId: "checkpoint" });
+  expect(
+    view.aui.thread.getState().messages.map((message) => message.id),
+  ).toEqual(["checkpoint"]);
+});