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

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.ts

@@ -0,0 +1,221 @@
+"use client";
+
+import {
+  computeTopAnchorReserve,
+  computeTopAnchorTargetScrollTop,
+} from "./computeTopAnchorSlack";
+import { createReserveObservers } from "./createReserveObservers";
+import {
+  createReserveElement,
+  getAnchorId,
+  setReserveHeight,
+  snapScrollTop,
+} from "./topAnchorUtils";
+
+/**
+ * Minimal slice of `ThreadViewportStore` that the top-anchor reserve needs.
+ * Decoupling from the full store keeps `mountTopAnchorReserve` testable in
+ * isolation and re-usable from any consumer that can adapt to this shape.
+ */
+export type TopAnchorStore = {
+  getState(): {
+    turnAnchor: "top" | "bottom";
+    element: {
+      viewport: HTMLElement | null;
+      anchor: HTMLElement | null;
+      target: HTMLElement | null;
+    };
+    targetConfig: {
+      tallerThan: number;
+      visibleHeight: number;
+    } | null;
+    topAnchorTurn: {
+      readonly anchorId: string;
+      readonly targetId: string;
+    } | null;
+  };
+  subscribe(fn: () => void): () => void;
+};
+
+const createFrameScheduler = (fn: () => void) => {
+  let frame: number | null = null;
+
+  return {
+    schedule: () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        fn();
+      });
+    },
+    cancel: () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+        frame = null;
+      }
+    },
+  };
+};
+
+export const mountTopAnchorReserve = (store: TopAnchorStore) => {
+  let reserve: HTMLElement | null = null;
+  let lastScrolledAnchorId: string | undefined;
+
+  let listenedViewport: HTMLElement | null = null;
+  let lastScrollTop = 0;
+  let restoreScrollTop: number | null = null;
+  let restoredThisTurn = false;
+  let lastAppliedTarget: number | null = null;
+
+  const clearRestore = () => {
+    restoreScrollTop = null;
+    lastAppliedTarget = null;
+  };
+
+  const wasPinnedAtLastScroll = () =>
+    lastAppliedTarget !== null &&
+    Math.abs(lastScrollTop - lastAppliedTarget) <= 1;
+
+  const handleScroll = () => {
+    const viewport = listenedViewport;
+    if (!viewport) return;
+    const scrollTop = viewport.scrollTop;
+    const maxScrollTop = Math.max(
+      0,
+      viewport.scrollHeight - viewport.clientHeight,
+    );
+    // A range clamp starts beyond the new maximum and lands on it.
+    const isRangeClamp =
+      scrollTop < lastScrollTop &&
+      lastScrollTop > maxScrollTop + 1 &&
+      Math.abs(scrollTop - maxScrollTop) <= 1;
+
+    if (isRangeClamp && wasPinnedAtLastScroll() && !restoredThisTurn) {
+      restoreScrollTop ??= lastScrollTop;
+      scheduler.schedule();
+    }
+
+    lastScrollTop = scrollTop;
+  };
+
+  const listenViewport = (viewport: HTMLElement | null) => {
+    if (listenedViewport === viewport) return;
+    if (listenedViewport) {
+      listenedViewport.removeEventListener("scroll", handleScroll);
+    }
+    listenedViewport = viewport;
+    restoredThisTurn = false;
+    clearRestore();
+    if (viewport) {
+      viewport.addEventListener("scroll", handleScroll, { passive: true });
+      lastScrollTop = viewport.scrollTop;
+    }
+  };
+
+  function apply() {
+    const state = store.getState();
+    const { viewport, anchor, target } = state.element;
+    const clamp = state.targetConfig;
+
+    listenViewport(state.turnAnchor === "top" ? viewport : null);
+
+    if (state.turnAnchor !== "top" || !viewport) {
+      observers.disconnect();
+      clearRestore();
+      if (reserve) {
+        setReserveHeight(reserve, 0);
+        reserve.remove();
+      }
+      return;
+    }
+
+    if (!anchor && !target && !clamp && state.topAnchorTurn) {
+      // ThreadViewport clears this state once the stored pair stops being the
+      // trailing turn (followed at most by pending user messages), so reaching
+      // here means the anchor gap is transient and the next run is imminent.
+      observers.disconnect();
+      clearRestore();
+      if (
+        reserve?.parentElement &&
+        reserve.parentElement.lastElementChild !== reserve
+      ) {
+        reserve.parentElement.append(reserve);
+      }
+      return;
+    }
+
+    if (!anchor || !target || !clamp) {
+      observers.disconnect();
+      clearRestore();
+      if (reserve) {
+        setReserveHeight(reserve, 0);
+        reserve.remove();
+      }
+      return;
+    }
+
+    reserve ??= createReserveElement();
+
+    if (
+      reserve.parentElement !== target.parentElement ||
+      reserve.previousElementSibling !== target
+    ) {
+      target.after(reserve);
+    }
+
+    observers.target(viewport, anchor, target);
+
+    const reserveChanged = setReserveHeight(
+      reserve,
+      computeTopAnchorReserve({ viewport, anchor, reserve, ...clamp }),
+    );
+
+    if (reserveChanged) {
+      scheduler.schedule();
+      return;
+    }
+
+    const anchorId = getAnchorId(anchor);
+    const targetScrollTop = snapScrollTop(
+      computeTopAnchorTargetScrollTop({ viewport, anchor, ...clamp }),
+    );
+
+    if (anchorId === undefined || anchorId !== lastScrolledAnchorId) {
+      restoreScrollTop = null;
+      restoredThisTurn = false;
+      if (Math.abs(viewport.scrollTop - targetScrollTop) > 1) {
+        viewport.scrollTo({ top: targetScrollTop, behavior: "smooth" });
+      }
+      if (anchorId !== undefined) lastScrolledAnchorId = anchorId;
+    } else if (restoreScrollTop !== null && lastAppliedTarget !== null) {
+      // Restore the anchor-relative position: if content above the anchor
+      // changed height and the browser already adjusted scrollTop to match
+      // (scroll anchoring), the desired offset equals the current one and
+      // this is a no-op.
+      const desired = snapScrollTop(
+        restoreScrollTop + (targetScrollTop - lastAppliedTarget),
+      );
+      restoreScrollTop = null;
+      restoredThisTurn = true;
+      if (Math.abs(viewport.scrollTop - desired) > 1) {
+        viewport.scrollTo({ top: desired, behavior: "instant" });
+      }
+    }
+
+    lastAppliedTarget = targetScrollTop;
+  }
+
+  const scheduler = createFrameScheduler(apply);
+  const observers = createReserveObservers(scheduler.schedule);
+
+  scheduler.schedule();
+  const unsubscribe = store.subscribe(scheduler.schedule);
+
+  return () => {
+    scheduler.cancel();
+    unsubscribe();
+    observers.disconnect();
+    listenViewport(null);
+    reserve?.remove();
+  };
+};

package/src/primitives/thread/topAnchor/topAnchorTurn.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import {
+  getActiveTopAnchorAnchorId,
+  getActiveTopAnchorTargetId,
+  getActiveTopAnchorTurn,
+  isTopAnchorTurnValid,
+} from "./topAnchorTurn";
+
+describe("topAnchorTurn", () => {
+  it("does not activate history-loaded messages", () => {
+    const messages = [
+      { id: "user-1", role: "user" },
+      { id: "assistant-1", role: "assistant" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: false, messages })).toBe(null);
+  });
+
+  it("activates the live user/assistant pair while running", () => {
+    const messages = [
+      { id: "assistant-1", role: "assistant" },
+      { id: "user-2", role: "user" },
+      { id: "assistant-2", role: "assistant" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toEqual({
+      anchorId: "user-2",
+      targetId: "assistant-2",
+    });
+    expect(getActiveTopAnchorAnchorId({ isRunning: true, messages })).toBe(
+      "user-2",
+    );
+    expect(getActiveTopAnchorTargetId({ isRunning: true, messages })).toBe(
+      "assistant-2",
+    );
+  });
+
+  it("ignores running states without a trailing user/assistant pair", () => {
+    const messages = [
+      { id: "user-1", role: "user" },
+      { id: "assistant-1", role: "assistant" },
+      { id: "user-2", role: "user" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toBe(null);
+  });
+
+  it("keeps a completed turn valid while it remains the trailing turn", () => {
+    const turn = { anchorId: "user-2", targetId: "assistant-2" };
+
+    expect(
+      isTopAnchorTurnValid(turn, [
+        { id: "assistant-1", role: "assistant" },
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+      ]),
+    ).toBe(true);
+  });
+
+  it("keeps a turn valid across the between-turns gap with pending user messages", () => {
+    const turn = { anchorId: "user-2", targetId: "assistant-2" };
+
+    expect(
+      isTopAnchorTurnValid(turn, [
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+        { id: "user-3", role: "user" },
+        { id: "user-4", role: "user" },
+      ]),
+    ).toBe(true);
+  });
+
+  it.each([
+    [
+      "thread switch",
+      [
+        { id: "other-user", role: "user" },
+        { id: "other-assistant", role: "assistant" },
+      ],
+    ],
+    ["new chat", []],
+    ["last-turn deletion", [{ id: "older-assistant", role: "assistant" }]],
+    [
+      "branch swap",
+      [
+        { id: "branch-user", role: "user" },
+        { id: "branch-assistant", role: "assistant" },
+      ],
+    ],
+    [
+      "an externally synced completed turn",
+      [
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+        { id: "user-3", role: "user" },
+        { id: "assistant-3", role: "assistant" },
+      ],
+    ],
+    [
+      "a resync separating the pair",
+      [
+        { id: "user-2", role: "user" },
+        { id: "inserted-assistant", role: "assistant" },
+        { id: "assistant-2", role: "assistant" },
+      ],
+    ],
+  ])("invalidates a stored turn after %s", (_transition, messages) => {
+    expect(
+      isTopAnchorTurnValid(
+        { anchorId: "user-2", targetId: "assistant-2" },
+        messages,
+      ),
+    ).toBe(false);
+  });
+});

package/src/primitives/thread/topAnchor/topAnchorTurn.ts

@@ -0,0 +1,59 @@
+"use client";
+
+type TopAnchorTurnMessage = {
+  readonly id: string;
+  readonly role: string;
+};
+
+export type TopAnchorTurn = {
+  readonly anchorId: string;
+  readonly targetId: string;
+};
+
+/**
+ * A stored turn stays valid only while it is still the trailing turn: the
+ * anchor immediately precedes the target, and anything after the target is a
+ * pending user message awaiting the next run. An assistant message after the
+ * target means the turn was superseded (e.g. an external store synced in a
+ * turn completed elsewhere), so the reserve must be torn down, not preserved.
+ */
+export const isTopAnchorTurnValid = (
+  turn: TopAnchorTurn | null,
+  messages: readonly TopAnchorTurnMessage[],
+) => {
+  if (!turn) return false;
+
+  const targetIndex = messages.findIndex(
+    (message) => message.id === turn.targetId,
+  );
+  if (targetIndex < 1) return false;
+
+  return (
+    messages[targetIndex - 1]?.id === turn.anchorId &&
+    messages.slice(targetIndex + 1).every((message) => message.role === "user")
+  );
+};
+
+export const getActiveTopAnchorTurn = ({
+  isRunning,
+  messages,
+}: {
+  readonly isRunning: boolean;
+  readonly messages: readonly TopAnchorTurnMessage[];
+}) => {
+  if (!isRunning) return null;
+
+  const target = messages.at(-1);
+  const anchor = messages.at(-2);
+  if (anchor?.role !== "user" || target?.role !== "assistant") return null;
+
+  return { anchorId: anchor.id, targetId: target.id };
+};
+
+export const getActiveTopAnchorAnchorId = (
+  options: Parameters<typeof getActiveTopAnchorTurn>[0],
+) => getActiveTopAnchorTurn(options)?.anchorId;
+
+export const getActiveTopAnchorTargetId = (
+  options: Parameters<typeof getActiveTopAnchorTurn>[0],
+) => getActiveTopAnchorTurn(options)?.targetId;

package/src/primitives/thread/topAnchor/topAnchorUtils.ts

@@ -0,0 +1,58 @@
+"use client";
+
+/**
+ * Convert a supported CSS length string (`px`, `em`, `rem`) into pixels,
+ * resolving font-relative units against the supplied element's computed style.
+ * Unsupported or malformed values disable the tall-message clamp.
+ *
+ * Part of the top-anchor package's public input contract: consumers may pass
+ * clamp configuration as supported CSS-length strings, and this function is the
+ * single place that converts them into the pixel values the package operates on.
+ */
+export const parseCssLength = (value: string, element: HTMLElement): number => {
+  const match = value.trim().match(/^(\d+(?:\.\d+)?|\.\d+)(em|px|rem)$/);
+  if (!match) return Number.POSITIVE_INFINITY;
+
+  const num = Number(match[1]);
+  const unit = match[2];
+
+  if (unit === "px") return num;
+  if (unit === "em") {
+    const fontSize = parseFloat(getComputedStyle(element).fontSize) || 16;
+    return num * fontSize;
+  }
+  if (unit === "rem") {
+    const rootFontSize =
+      parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    return num * rootFontSize;
+  }
+  return Number.POSITIVE_INFINITY;
+};
+
+export const getAnchorId = (anchor: HTMLElement) => anchor.dataset.messageId;
+
+export const createReserveElement = () => {
+  const reserve = document.createElement("div");
+  reserve.dataset.auiTopAnchorReserve = "";
+  reserve.style.height = "0px";
+  reserve.style.flexShrink = "0";
+  reserve.style.pointerEvents = "none";
+  reserve.setAttribute("aria-hidden", "true");
+
+  return reserve;
+};
+
+export const setReserveHeight = (reserve: HTMLElement, height: number) => {
+  const nextHeight = `${height}px`;
+  if (reserve.style.height !== nextHeight) {
+    reserve.style.height = nextHeight;
+    return true;
+  }
+
+  return false;
+};
+
+export const snapScrollTop = (top: number) => {
+  const pixelRatio = window.devicePixelRatio || 1;
+  return Math.round(top * pixelRatio) / pixelRatio;
+};

package/src/primitives/thread/topAnchor/useTopAnchorReserve.ts

@@ -0,0 +1,23 @@
+"use client";
+
+import { toValue, type MaybeRefOrGetter } from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useThreadViewportStore } from "../../../context/vue/ThreadViewportContext";
+import { mountTopAnchorReserve } from "./mountTopAnchorReserve";
+
+/**
+ * Mounts the top-turn-anchor reserve element against the active
+ * `ThreadViewport` store. Call this from inside the scrollable viewport so
+ * the reserve `<div>` is appended next to the streaming assistant message.
+ */
+export const useTopAnchorReserve = (enabled: MaybeRefOrGetter<boolean>) => {
+  const threadViewportStore = useThreadViewportStore();
+
+  useIsomorphicLayoutEffect(
+    () => {
+      if (!toValue(enabled)) return;
+      return mountTopAnchorReserve(threadViewportStore);
+    },
+    () => [toValue(enabled), threadViewportStore],
+  );
+};