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

package/src/context/providers/vue-providers.test.tsx

@@ -0,0 +1,326 @@
+// @vitest-environment jsdom
+import {
+  KeepAlive,
+  Suspense,
+  createApp,
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  provide,
+  shallowRef,
+  version,
+  type App,
+} from "vue";
+import { renderToString } from "@vue/server-renderer";
+import { afterEach, beforeAll, expect, it, vi } from "vitest";
+import { AuiConfig, AuiProvider, useAuiState } from "@ulearning/ai-store";
+import { flushTapSync } from "@ulearning/ai-tap";
+import {
+  ThreadViewportContext,
+  useThreadViewport,
+  useThreadViewportStore,
+} from "../vue/ThreadViewportContext";
+import { makeThreadViewportStore } from "../stores/ThreadViewport";
+import { writableStore } from "../ReadonlyStore";
+import { ThreadPrimitiveViewportProvider } from "./ThreadViewportProvider";
+import { MessageProvider } from "./MessageProvider";
+import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
+import {
+  AssistantRuntimeImpl,
+  ExternalStoreRuntimeCore,
+} from "@ulearning/ai-core/internal";
+import {
+  AssistantRuntimeProvider,
+  AssistantRuntimeProviderImpl,
+} from "../../legacy-runtime/AssistantRuntimeProvider";
+
+const apps: App[] = [];
+const mount = (component: ReturnType<typeof defineComponent>) => {
+  const app = createApp(component);
+  apps.push(app);
+  const element = document.createElement("div");
+  document.body.append(element);
+  const errors: unknown[] = [];
+  app.config.errorHandler = (error) => errors.push(error);
+  app.mount(element);
+  delete app.config.errorHandler;
+  if (errors.length) throw errors[0];
+  return element;
+};
+const capture = (setup: () => () => ReturnType<typeof h> | null) =>
+  defineComponent({ setup });
+beforeAll(() => {
+  const expected = process.env.AUI_VUE_RUNTIME_ROOT?.replaceAll("\\", "/")
+    .split("/")
+    .at(-1);
+  if (expected) expect(version).toBe(expected);
+});
+afterEach(() => {
+  apps.splice(0).forEach((app) => app.unmount());
+  document.body.innerHTML = "";
+  vi.restoreAllMocks();
+});
+
+it("requires a viewport unless optional, whose missing value is an explicit Ref", () => {
+  const value = capture(() => {
+    expect(useThreadViewportStore({ optional: true })).toBeNull();
+    expect(useThreadViewport({ optional: true }).value).toBeNull();
+    expect(() => useThreadViewport()).toThrow("ThreadPrimitive.Viewport");
+    return () => null;
+  });
+  mount(value);
+});
+
+it("keeps selected snapshots shallow and avoids renders for unrelated changes", async () => {
+  const store = makeThreadViewportStore();
+  let renders = 0;
+  const Consumer = capture(() => {
+    const height = useThreadViewport((state) => state.height);
+    expect(height.value).toBe(store.getState().height);
+    return () => {
+      renders++;
+      return h("p", String(height.value.viewport));
+    };
+  });
+  const element = mount(
+    capture(() => {
+      provide(ThreadViewportContext, { useThreadViewport: store });
+      return () => h(Consumer);
+    }),
+  );
+  expect(renders).toBe(1);
+  store.setState({ isAtBottom: false });
+  await nextTick();
+  expect(renders).toBe(1);
+  const size = store.getState().registerViewport();
+  size.setHeight(42);
+  await nextTick();
+  expect(renders).toBe(2);
+  expect(element.textContent).toBe("42");
+});
+
+it("SSR reads selectors without connecting external subscriptions", async () => {
+  const store = makeThreadViewportStore();
+  const subscribe = vi.spyOn(store, "subscribe");
+  const Consumer = capture(() => {
+    const atBottom = useThreadViewport((state) => state.isAtBottom);
+    return () => h("p", String(atBottom.value));
+  });
+  const Host = capture(() => {
+    provide(ThreadViewportContext, { useThreadViewport: store });
+    return () => h(Consumer);
+  });
+  expect(await renderToString(createSSRApp(Host))).toBe("<p>true</p>");
+  expect(subscribe).not.toHaveBeenCalled();
+});
+
+it("KeepAlive disconnects, ignores late callbacks, and catches up on activation", async () => {
+  const store = makeThreadViewportStore();
+  const rawSubscribe = store.subscribe;
+  const releases = vi.fn();
+  let late!: () => void;
+  vi.spyOn(store, "subscribe").mockImplementation((callback) => {
+    late = () => callback(store.getState(), store.getState());
+    const release = rawSubscribe(callback);
+    return () => {
+      releases();
+      release();
+    };
+  });
+  const active = shallowRef(true);
+  const observed: boolean[] = [];
+  let setups = 0;
+  const Consumer = capture(() => {
+    setups++;
+    const atBottom = useThreadViewport((state) => state.isAtBottom);
+    return () => {
+      observed.push(atBottom.value);
+      return h("p", String(atBottom.value));
+    };
+  });
+  const element = mount(
+    capture(() => {
+      provide(ThreadViewportContext, { useThreadViewport: store });
+      return () =>
+        h(KeepAlive, null, {
+          default: () => (active.value ? h(Consumer) : null),
+        });
+    }),
+  );
+  const stale = late;
+  active.value = false;
+  await nextTick();
+  expect(releases).toHaveBeenCalledOnce();
+  store.setState({ isAtBottom: false });
+  stale();
+  await nextTick();
+  expect(observed).toEqual([true]);
+  active.value = true;
+  await nextTick();
+  expect(setups).toBe(1);
+  expect(element.textContent).toBe("false");
+  const current = late;
+  apps[0]!.unmount();
+  expect(releases).toHaveBeenCalledTimes(2);
+  store.setState({ isAtBottom: true });
+  current();
+  await nextTick();
+  expect(observed).toEqual([true, false]);
+});
+
+it("does not connect an abandoned Suspense branch even after its gate resolves", async () => {
+  const store = makeThreadViewportStore();
+  const subscribe = vi.spyOn(store, "subscribe");
+  let finish!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  const show = shallowRef(true);
+  const Pending = defineComponent({
+    async setup() {
+      useThreadViewport();
+      await gate;
+      return () => h("p", "pending");
+    },
+  });
+  mount(
+    capture(() => {
+      provide(ThreadViewportContext, { useThreadViewport: store });
+      return () =>
+        show.value
+          ? h(Suspense, null, {
+              default: () => h(Pending),
+              fallback: () => h("p", "loading"),
+            })
+          : h("p", "removed");
+    }),
+  );
+  expect(subscribe).not.toHaveBeenCalled();
+  show.value = false;
+  await nextTick();
+  finish();
+  await gate;
+  await nextTick();
+  expect(subscribe).not.toHaveBeenCalled();
+});
+
+it("forwards nested scrolling and bottom state while retaining initial options", async () => {
+  let outer!: NonNullable<ReturnType<typeof useThreadViewportStore>>;
+  let inner!: NonNullable<ReturnType<typeof useThreadViewportStore>>;
+  const options = shallowRef({ turnAnchor: "top" as "top" | "bottom" });
+  const callback = shallowRef(vi.fn());
+  const firstCallback = callback.value;
+  const Inner = capture(() => {
+    inner = useThreadViewportStore();
+    useOnScrollToBottom(callback);
+    return () => null;
+  });
+  const Outer = capture(() => {
+    outer = useThreadViewportStore();
+    return () =>
+      h(
+        ThreadPrimitiveViewportProvider,
+        { options: options.value },
+        { default: () => h(Inner) },
+      );
+  });
+  mount(
+    capture(
+      () => () =>
+        h(ThreadPrimitiveViewportProvider, null, { default: () => h(Outer) }),
+    ),
+  );
+  outer.getState().scrollToBottom({ behavior: "smooth" });
+  expect(firstCallback).toHaveBeenCalledExactlyOnceWith({ behavior: "smooth" });
+  callback.value = vi.fn();
+  outer.getState().scrollToBottom();
+  expect(firstCallback).toHaveBeenCalledOnce();
+  expect(callback.value).toHaveBeenCalledExactlyOnceWith({ behavior: "auto" });
+  writableStore(inner).setState({ isAtBottom: false });
+  expect(outer.getState().isAtBottom).toBe(false);
+  options.value = { turnAnchor: "bottom" };
+  await nextTick();
+  expect(inner.getState().turnAnchor).toBe("top");
+  apps[0]!.unmount();
+  outer.getState().scrollToBottom();
+  expect(callback.value).toHaveBeenCalledOnce();
+});
+
+it("MessageProvider updates the real message scope with reactive props", async () => {
+  const message = shallowRef({
+    id: "first",
+    role: "user" as const,
+    content: [{ type: "text" as const, text: "one" }],
+    createdAt: new Date(0),
+    metadata: { custom: {} },
+    attachments: [],
+  });
+  const index = shallowRef(0);
+  const Consumer = capture(() => {
+    const state = useAuiState((s) => s.message);
+    return () => h("p", `${state.value.id}:${state.value.index}`);
+  });
+  const element = mount(
+    capture(
+      () => () =>
+        h(
+          AuiProvider,
+          { config: AuiConfig({}) },
+          {
+            default: () =>
+              h(
+                MessageProvider,
+                { message: message.value, index: index.value },
+                { default: () => h(Consumer) },
+              ),
+          },
+        ),
+    ),
+  );
+  expect(element.textContent).toBe("first:0");
+  flushTapSync(() => {
+    message.value = { ...message.value, id: "second" };
+    index.value = 2;
+  });
+  await nextTick();
+  expect(element.textContent).toBe("second:2");
+});
+
+it("Web runtime Provider replaces the actual Core runtime and owns its viewport scope", async () => {
+  expect(AssistantRuntimeProvider).toBe(AssistantRuntimeProviderImpl);
+  const first = new ExternalStoreRuntimeCore({
+    messages: [],
+    onNew: async () => {},
+  });
+  const second = new ExternalStoreRuntimeCore({
+    messages: [],
+    onNew: async () => {},
+    isRunning: true,
+  });
+  const runtime = shallowRef(new AssistantRuntimeImpl(first));
+  const Consumer = capture(() => {
+    const running = useAuiState((s) => s.thread.isRunning);
+    expect(useThreadViewportStore().getState().isAtBottom).toBe(true);
+    return () => h("p", String(running.value));
+  });
+  const element = mount(
+    capture(
+      () => () =>
+        h(
+          AssistantRuntimeProvider,
+          { runtime: runtime.value },
+          { default: () => h(Consumer) },
+        ),
+    ),
+  );
+  expect(element.textContent).toBe("false");
+  runtime.value = new AssistantRuntimeImpl(second);
+  await nextTick();
+  expect(element.textContent).toBe("true");
+  flushTapSync(() =>
+    first.setAdapter({ messages: [], onNew: async () => {}, isRunning: false }),
+  );
+  await nextTick();
+  expect(element.textContent).toBe("true");
+});

package/src/context/stores/ThreadViewport.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it, onTestFinished, vi } from "vitest";
+import { makeThreadViewportStore } from "./ThreadViewport";
+
+describe("makeThreadViewportStore", () => {
+  it("notifies every scroll listener when one throws", () => {
+    const store = makeThreadViewportStore();
+    const listenerError = new Error("scroll listener failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    onTestFinished(() => consoleError.mockRestore());
+    const laterListener = vi.fn();
+
+    store.getState().onScrollToBottom(() => {
+      throw listenerError;
+    });
+    store.getState().onScrollToBottom((config) => {
+      config.behavior = "smooth";
+    });
+    store.getState().onScrollToBottom(laterListener);
+
+    expect(() => store.getState().scrollToBottom()).not.toThrow();
+    expect(laterListener).toHaveBeenCalledWith({ behavior: "auto" });
+    expect(consoleError).toHaveBeenCalledWith(
+      expect.stringContaining("Thread viewport"),
+      listenerError,
+    );
+  });
+});

package/src/context/stores/ThreadViewport.ts

@@ -0,0 +1,278 @@
+"use client";
+
+import { createStore } from "zustand/vanilla";
+import type { Unsubscribe } from "@ulearning/ai-core";
+import { notifyEventListeners } from "@ulearning/ai-core/internal";
+import {
+  createThreadViewportAutoScroll,
+  type ThreadViewportAutoScroll,
+  type ThreadViewportAutoScrollOptions,
+} from "@ulearning/ai-store/client";
+import type { ReadonlyStore } from "../ReadonlyStore";
+
+export type SizeHandle = {
+  /** Update the height */
+  setHeight: (height: number) => void;
+  /** Unregister this handle */
+  unregister: Unsubscribe;
+};
+
+type SizeRegistry = {
+  register: () => SizeHandle;
+};
+
+const createSizeRegistry = (
+  onChange: (total: number) => void,
+): SizeRegistry => {
+  const entries = new Map<symbol, number>();
+
+  const recalculate = () => {
+    let total = 0;
+    for (const height of entries.values()) {
+      total += height;
+    }
+    onChange(total);
+  };
+
+  return {
+    register: () => {
+      const id = Symbol();
+      entries.set(id, 0);
+
+      return {
+        setHeight: (height: number) => {
+          if (entries.get(id) !== height) {
+            entries.set(id, height);
+            recalculate();
+          }
+        },
+        unregister: () => {
+          entries.delete(id);
+          recalculate();
+        },
+      };
+    },
+  };
+};
+
+export type ThreadViewportState = {
+  readonly isAtBottom: boolean;
+  readonly scrollToBottom: (config?: {
+    behavior?: ScrollBehavior | undefined;
+  }) => void;
+  readonly onScrollToBottom: (
+    callback: ({ behavior }: { behavior: ScrollBehavior }) => void,
+  ) => Unsubscribe;
+
+  /** Controls scroll anchoring: "top" anchors user messages at top, "bottom" is classic behavior */
+  readonly turnAnchor: "top" | "bottom";
+
+  /** Clamps tall user messages so the assistant response stays in view. */
+  readonly topAnchorMessageClamp: {
+    readonly tallerThan: string;
+    readonly visibleHeight: string;
+  };
+
+  /** Raw height values from registered elements */
+  readonly height: {
+    /** Total viewport height */
+    readonly viewport: number;
+    /** Total content inset height (footer, anchor message, etc.) */
+    readonly inset: number;
+  };
+
+  /** Current DOM elements used for geometry-based top anchoring */
+  readonly element: {
+    readonly viewport: HTMLElement | null;
+    readonly anchor: HTMLElement | null;
+    readonly target: HTMLElement | null;
+  };
+
+  /** Numeric clamp configuration for the active top-anchor target message */
+  readonly targetConfig: {
+    readonly tallerThan: number;
+    readonly visibleHeight: number;
+  } | null;
+
+  /**
+   * The current top-anchor turn activated in this viewport session.
+   * History-loaded messages do not populate this; it is set when a run creates
+   * a live user/assistant pair and remains after the run completes.
+   */
+  readonly topAnchorTurn: {
+    readonly anchorId: string;
+    readonly targetId: string;
+  } | null;
+
+  /** Register a viewport and get a handle to update its height */
+  readonly registerViewport: () => SizeHandle;
+
+  /** Register a content inset (footer, anchor message, etc.) and get a handle to update its height */
+  readonly registerContentInset: () => SizeHandle;
+
+  /** Register the scroll viewport element */
+  readonly registerViewportElement: (
+    element: HTMLElement | null,
+  ) => Unsubscribe;
+
+  /** Register the current anchor user message element */
+  readonly registerAnchorElement: (element: HTMLElement | null) => Unsubscribe;
+
+  /**
+   * Register the current top-anchor target (last assistant response) element
+   * along with its numeric clamp configuration. When unregistered, both
+   * `element.target` and `targetConfig` clear together.
+   */
+  readonly registerAnchorTargetElement: (
+    element: HTMLElement | null,
+    config?: { readonly tallerThan: number; readonly visibleHeight: number },
+  ) => Unsubscribe;
+
+  readonly setTopAnchorTurn: (
+    turn: { readonly anchorId: string; readonly targetId: string } | null,
+  ) => void;
+};
+
+export type ThreadViewportStoreOptions = {
+  turnAnchor?: "top" | "bottom" | undefined;
+  topAnchorMessageClamp?:
+    | {
+        tallerThan?: string | undefined;
+        visibleHeight?: string | undefined;
+      }
+    | undefined;
+};
+
+type ViewportAutoScroll = {
+  controller: ThreadViewportAutoScroll;
+  getOptions: () => ThreadViewportAutoScrollOptions;
+};
+
+const viewportAutoScroll = new WeakMap<
+  ReadonlyStore<ThreadViewportState>,
+  ViewportAutoScroll
+>();
+
+export const getThreadViewportAutoScroll = (
+  store: ReadonlyStore<ThreadViewportState>,
+) => viewportAutoScroll.get(store)!;
+
+export const makeThreadViewportStore = (
+  options: ThreadViewportStoreOptions = {},
+) => {
+  const scrollToBottomListeners = new Set<
+    (config: { behavior: ScrollBehavior }) => void
+  >();
+
+  const viewportRegistry = createSizeRegistry((total) => {
+    store.setState({
+      height: {
+        ...store.getState().height,
+        viewport: total,
+      },
+    });
+  });
+  const autoScroll: ViewportAutoScroll = {
+    getOptions: () => ({
+      autoScroll: options.turnAnchor !== "top",
+      scrollToBottomOnInitialize: true,
+      scrollToBottomOnRunStart: options.turnAnchor !== "top",
+      scrollToBottomOnThreadSwitch: true,
+    }),
+    controller: createThreadViewportAutoScroll({
+      getOptions: () => autoScroll.getOptions(),
+      onAtBottomChange: (isAtBottom) => store.setState({ isAtBottom }),
+      onContentInsetChange: (inset) => {
+        store.setState({ height: { ...store.getState().height, inset } });
+      },
+    }),
+  };
+  const registerElementSlot = (
+    key: "viewport" | "anchor",
+    element: HTMLElement | null,
+  ) => {
+    store.setState({
+      element: {
+        ...store.getState().element,
+        [key]: element,
+      },
+    });
+
+    return () => {
+      if (store.getState().element[key] !== element) return;
+      store.setState({
+        element: {
+          ...store.getState().element,
+          [key]: null,
+        },
+      });
+    };
+  };
+
+  const store = createStore<ThreadViewportState>(() => ({
+    isAtBottom: true,
+    scrollToBottom: ({ behavior = "auto" } = {}) => {
+      notifyEventListeners(
+        scrollToBottomListeners,
+        () => ({ behavior }),
+        "Thread viewport",
+      );
+    },
+    onScrollToBottom: (callback) => {
+      scrollToBottomListeners.add(callback);
+      return () => {
+        scrollToBottomListeners.delete(callback);
+      };
+    },
+
+    turnAnchor: options.turnAnchor ?? "bottom",
+    topAnchorMessageClamp: {
+      tallerThan: options.topAnchorMessageClamp?.tallerThan ?? "10em",
+      visibleHeight: options.topAnchorMessageClamp?.visibleHeight ?? "6em",
+    },
+
+    height: {
+      viewport: 0,
+      inset: 0,
+    },
+    element: {
+      viewport: null,
+      anchor: null,
+      target: null,
+    },
+    targetConfig: null,
+    topAnchorTurn: null,
+
+    registerViewport: viewportRegistry.register,
+    registerContentInset: autoScroll.controller.registerContentInset,
+    registerViewportElement: (element) =>
+      registerElementSlot("viewport", element),
+    registerAnchorElement: (element) => registerElementSlot("anchor", element),
+    registerAnchorTargetElement: (element, config) => {
+      store.setState({
+        element: {
+          ...store.getState().element,
+          target: element,
+        },
+        targetConfig: element && config ? config : null,
+      });
+
+      return () => {
+        if (store.getState().element.target !== element) return;
+        store.setState({
+          element: {
+            ...store.getState().element,
+            target: null,
+          },
+          targetConfig: null,
+        });
+      };
+    },
+    setTopAnchorTurn: (topAnchorTurn) => {
+      store.setState({ topAnchorTurn });
+    },
+  }));
+
+  viewportAutoScroll.set(store, autoScroll);
+  return store;
+};

package/src/context/vue/ThreadViewportContext.ts

@@ -0,0 +1,22 @@
+"use client";
+
+import type { InjectionKey } from "vue";
+import type { ReadonlyStore } from "../ReadonlyStore";
+import { createContextHook } from "./utils/createContextHook";
+import { createContextStoreHook } from "./utils/createContextStoreHook";
+import type { ThreadViewportState } from "../stores/ThreadViewport";
+
+export type ThreadViewportContextValue = {
+  useThreadViewport: ReadonlyStore<ThreadViewportState>;
+};
+
+export const ThreadViewportContext: InjectionKey<ThreadViewportContextValue | null> =
+  Symbol("aui.ThreadViewport");
+
+const useThreadViewportContext = createContextHook(
+  ThreadViewportContext,
+  "ThreadPrimitive.Viewport",
+);
+
+export const { useThreadViewport, useThreadViewportStore } =
+  createContextStoreHook(useThreadViewportContext, "useThreadViewport");

package/src/context/vue/utils/createContextHook.ts

@@ -0,0 +1,26 @@
+"use client";
+
+import { hasInjectionContext, inject, type InjectionKey } from "vue";
+
+/**
+ * Creates a context hook with optional support.
+ * @param context - The Vue injection key to consume.
+ * @param providerName - The name of the provider for error messages.
+ * @returns A hook function that provides the context value.
+ */
+export function createContextHook<T>(
+  context: InjectionKey<T | null>,
+  providerName: string,
+) {
+  function useContextHook(options?: {
+    optional?: boolean | undefined;
+  }): T | null {
+    const contextValue = hasInjectionContext() ? inject(context, null) : null;
+    if (!options?.optional && !contextValue) {
+      throw new Error(`This component must be used within ${providerName}.`);
+    }
+    return contextValue;
+  }
+
+  return useContextHook;
+}