@runtypelabs/persona 3.6.0 → 3.8.0

package/src/ui.ts

@@ -33,7 +33,16 @@ import { renderLucideIcon } from "./utils/icons";
 import { createElement, createElementInDocument } from "./utils/dom";
 import { morphMessages } from "./utils/morph";
 import { computeMessageFingerprint, createMessageCache, getCachedWrapper, setCachedWrapper, pruneCache } from "./utils/message-fingerprint";
-import { statusCopy } from "./utils/constants";
+import {
+  createFollowStateController,
+  getScrollBottomOffset,
+  isElementNearBottom,
+  resolveFollowStateFromScroll,
+  resolveFollowStateFromWheel
+} from "./utils/auto-follow";
+import { statusCopy, DEFAULT_OVERLAY_Z_INDEX, PORTALED_OVERLAY_Z_INDEX } from "./utils/constants";
+import { syncOverlayHostStacking } from "./utils/overlay-host-stacking";
+import { acquireScrollLock } from "./utils/scroll-lock";
 import { isDockedMountMode, resolveDockConfig } from "./utils/dock";
 import { createLauncherButton } from "./components/launcher";
 import { createWrapper, buildPanel, buildHeader, buildComposer, attachHeaderToContainer } from "./components/panel";
@@ -545,6 +554,7 @@ export const createAgentExperience = (
   let showReasoning = config.features?.showReasoning ?? true;
   let showToolCalls = config.features?.showToolCalls ?? true;
   let showEventStreamToggle = config.features?.showEventStreamToggle ?? false;
+  let scrollToBottomFeature = config.features?.scrollToBottom ?? {};
   const persistKeyPrefix = (typeof config.persistState === 'object' ? config.persistState?.keyPrefix : undefined) ?? "persona-";
   const eventStreamDbName = `${persistKeyPrefix}event-stream`;
   let eventStreamStore = showEventStreamToggle ? new EventStreamStore(eventStreamDbName) : null;
@@ -655,6 +665,49 @@ export const createAgentExperience = (
   let attachmentButtonWrapper: HTMLElement | null = panelElements.attachmentButtonWrapper;
   let attachmentInput: HTMLInputElement | null = panelElements.attachmentInput;
   let attachmentPreviewsContainer: HTMLElement | null = panelElements.attachmentPreviewsContainer;
+  container.classList.add("persona-relative");
+  body.classList.add("persona-relative");
+  const SCROLL_TO_BOTTOM_EDGE_OFFSET = 12;
+
+  const getScrollToBottomLabel = () => scrollToBottomFeature.label ?? "";
+  const getScrollToBottomIconName = () => scrollToBottomFeature.iconName ?? "arrow-down";
+  const isScrollToBottomEnabled = () => scrollToBottomFeature.enabled !== false;
+  const scrollToBottomButton = createElement(
+    "button",
+    "persona-scroll-to-bottom-indicator persona-absolute persona-bottom-3 persona-left-1/2 persona-z-10 persona-flex persona-items-center persona-gap-1 persona-text-xs persona-transform persona--translate-x-1/2 persona-cursor-pointer"
+  ) as HTMLButtonElement;
+  scrollToBottomButton.type = "button";
+  scrollToBottomButton.style.display = "none";
+  scrollToBottomButton.setAttribute("data-persona-scroll-to-bottom", "true");
+  const scrollToBottomIcon = createElement("span", "persona-flex persona-items-center");
+  const scrollToBottomLabel = createElement("span", "");
+  scrollToBottomButton.append(scrollToBottomIcon, scrollToBottomLabel);
+  container.appendChild(scrollToBottomButton);
+
+  const updateScrollToBottomButtonOffset = () => {
+    const footerHidden = footer.style.display === "none";
+    const footerHeight = footerHidden ? 0 : footer.offsetHeight;
+    scrollToBottomButton.style.bottom = `${footerHeight + SCROLL_TO_BOTTOM_EDGE_OFFSET}px`;
+  };
+  updateScrollToBottomButtonOffset();
+
+  const renderScrollToBottomButton = () => {
+    const hasLabel = Boolean(getScrollToBottomLabel());
+    scrollToBottomButton.setAttribute("aria-label", getScrollToBottomLabel() || "Jump to latest");
+    scrollToBottomButton.title = getScrollToBottomLabel();
+    scrollToBottomButton.setAttribute("data-persona-scroll-to-bottom-has-label", hasLabel ? "true" : "false");
+    scrollToBottomIcon.innerHTML = "";
+    const icon = renderLucideIcon(getScrollToBottomIconName(), "14px", "currentColor", 2);
+    if (icon) {
+      scrollToBottomIcon.appendChild(icon);
+      scrollToBottomIcon.style.display = "";
+    } else {
+      scrollToBottomIcon.style.display = "none";
+    }
+    scrollToBottomLabel.textContent = getScrollToBottomLabel();
+    scrollToBottomLabel.style.display = hasLabel ? "" : "none";
+  };
+  renderScrollToBottomButton();
 
   // Initialized after composer plugins rebind footer DOM (see `bindComposerRefsFromFooter`)
   let attachmentManager: AttachmentManager | null = null;
@@ -719,6 +772,7 @@ export const createAgentExperience = (
     };
     eventStreamLastUpdate = 0;
     eventStreamRAF = requestAnimationFrame(rafLoop);
+    syncScrollToBottomButton();
     eventBus.emit("eventStream:opened", { timestamp: Date.now() });
   };
 
@@ -739,6 +793,7 @@ export const createAgentExperience = (
       cancelAnimationFrame(eventStreamRAF);
       eventStreamRAF = null;
     }
+    syncScrollToBottomButton();
     eventBus.emit("eventStream:closed", { timestamp: Date.now() });
   };
 
@@ -1493,7 +1548,7 @@ export const createAgentExperience = (
     // Determine panel styling based on mode, with theme overrides
     const position = config.launcher?.position ?? 'bottom-left';
     const isLeftSidebar = position === 'bottom-left' || position === 'top-left';
-    const overlayZIndex = config.launcher?.zIndex ?? 9999;
+    const overlayZIndex = config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX;
 
     // Default values based on mode
     let defaultPanelBorder = (sidebarMode || shouldGoFullscreen) ? 'none' : '1px solid var(--persona-border)';
@@ -1766,9 +1821,8 @@ export const createAgentExperience = (
     if (!isInlineEmbed && !dockedMode) {
       const maxHeightStyles = 'max-height: -moz-available !important; max-height: stretch !important;';
       const paddingStyles = sidebarMode ? '' : 'padding-top: 1.25em !important;';
-      // Override z-index only when explicitly configured; otherwise the persona-z-50 class applies
-      const zIndexStyles = !sidebarMode && config.launcher?.zIndex != null
-        ? `z-index: ${config.launcher.zIndex} !important;`
+      const zIndexStyles = !sidebarMode
+        ? `z-index: ${config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX} !important;`
         : '';
       wrapper.style.cssText += maxHeightStyles + paddingStyles + zIndexStyles;
     }
@@ -1781,6 +1835,16 @@ export const createAgentExperience = (
 
   const destroyCallbacks: Array<() => void> = [];
 
+  let teardownHostStacking: (() => void) | null = null;
+  let releaseScrollLock: (() => void) | null = null;
+
+  destroyCallbacks.push(() => {
+    teardownHostStacking?.();
+    teardownHostStacking = null;
+    releaseScrollLock?.();
+    releaseScrollLock = null;
+  });
+
   if (artifactPanelResizeObs) {
     destroyCallbacks.push(() => {
       artifactPanelResizeObs?.disconnect();
@@ -1845,18 +1909,13 @@ export const createAgentExperience = (
   let isStreaming = false;
   const messageCache = createMessageCache();
   let configVersion = 0;
-  let shouldAutoScroll = true;
+  const autoFollow = createFollowStateController();
   let lastScrollTop = 0;
-  let lastAutoScrollTime = 0;
   let scrollRAF: number | null = null;
-  let isAutoScrollBlocked = false;
-  let blockUntilTime = 0;
   let isAutoScrolling = false;
 
-  const AUTO_SCROLL_THROTTLE = 125;
-  const AUTO_SCROLL_BLOCK_TIME = 2000;
-  const USER_SCROLL_THRESHOLD = 5;
-  const BOTTOM_THRESHOLD = 50;
+  const USER_SCROLL_THRESHOLD = 1;
+  const BOTTOM_THRESHOLD = 8;
   const messageState = new Map<
     string,
     { streaming?: boolean; role: AgentWidgetMessage["role"] }
@@ -1946,75 +2005,92 @@ export const createAgentExperience = (
     }
   }
 
-  const scheduleAutoScroll = (force = false) => {
-    if (!shouldAutoScroll) return;
+  // Track ongoing smooth scroll animation
+  let smoothScrollRAF: number | null = null;
 
-    const now = Date.now();
+  // Get the scrollable container using its unique ID
+  const getScrollableContainer = (): HTMLElement => {
+    // Use the unique ID for reliable selection
+    const scrollable = wrapper.querySelector('#persona-scroll-container') as HTMLElement;
+    // Fallback to body if ID not found (shouldn't happen, but safe fallback)
+    return scrollable || body;
+  };
 
-    if (isAutoScrollBlocked && now < blockUntilTime) {
-      if (!force) return;
+  const cancelSmoothScroll = () => {
+    if (smoothScrollRAF !== null) {
+      cancelAnimationFrame(smoothScrollRAF);
+      smoothScrollRAF = null;
     }
+    isAutoScrolling = false;
+  };
 
-    if (isAutoScrollBlocked && now >= blockUntilTime) {
-      isAutoScrollBlocked = false;
+  const cancelAutoScroll = () => {
+    if (scrollRAF !== null) {
+      cancelAnimationFrame(scrollRAF);
+      scrollRAF = null;
     }
+    cancelSmoothScroll();
+  };
 
-    if (!force && !isStreaming) return;
+  const syncScrollToBottomButton = () => {
+    if (!isScrollToBottomEnabled() || eventStreamVisible) {
+      if (scrollToBottomButton.parentNode) {
+        scrollToBottomButton.remove();
+      }
+      scrollToBottomButton.style.display = "none";
+      return;
+    }
+    if (scrollToBottomButton.parentNode !== container) {
+      container.appendChild(scrollToBottomButton);
+    }
+    updateScrollToBottomButtonOffset();
+    const hasOverflow = getScrollBottomOffset(body) > 0;
+    scrollToBottomButton.style.display = (autoFollow.isFollowing() || !hasOverflow) ? "none" : "";
+  };
 
-    if (now - lastAutoScrollTime < AUTO_SCROLL_THROTTLE) return;
-    lastAutoScrollTime = now;
+  const pauseAutoScroll = () => {
+    if (!autoFollow.pause()) return;
+    cancelAutoScroll();
+    syncScrollToBottomButton();
+  };
 
-    if (scrollRAF) {
-      cancelAnimationFrame(scrollRAF);
-    }
+  const resumeAutoScroll = () => {
+    autoFollow.resume();
+    syncScrollToBottomButton();
+  };
+
+  const scheduleAutoScroll = (force = false) => {
+    if (!autoFollow.isFollowing()) return;
+
+    if (!force && !isStreaming) return;
+
+    cancelAutoScroll();
 
     scrollRAF = requestAnimationFrame(() => {
-      if (isAutoScrollBlocked || !shouldAutoScroll) return;
-      isAutoScrolling = true;
-      body.scrollTop = body.scrollHeight;
-      lastScrollTop = body.scrollTop;
-      requestAnimationFrame(() => {
-        isAutoScrolling = false;
-      });
       scrollRAF = null;
+      if (!autoFollow.isFollowing()) return;
+      smoothScrollToBottom(getScrollableContainer(), force ? 220 : 140);
     });
   };
 
-  // Track ongoing smooth scroll animation
-  let smoothScrollRAF: number | null = null;
-
-  // Get the scrollable container using its unique ID
-  const getScrollableContainer = (): HTMLElement => {
-    // Use the unique ID for reliable selection
-    const scrollable = wrapper.querySelector('#persona-scroll-container') as HTMLElement;
-    // Fallback to body if ID not found (shouldn't happen, but safe fallback)
-    return scrollable || body;
-  };
-
   // Custom smooth scroll animation with easing
   const smoothScrollToBottom = (element: HTMLElement, duration = 500) => {
     const start = element.scrollTop;
-    const clientHeight = element.clientHeight;
     // Recalculate target dynamically to handle layout changes
-    let target = element.scrollHeight;
+    let target = getScrollBottomOffset(element);
     let distance = target - start;
 
-    // Check if already at bottom: scrollTop + clientHeight should be >= scrollHeight
-    // Add a small threshold (2px) to account for rounding/subpixel differences
-    const isAtBottom = start + clientHeight >= target - 2;
-    
     // If already at bottom or very close, skip animation to prevent glitch
-    if (isAtBottom || Math.abs(distance) < 5) {
+    if (Math.abs(distance) < 1) {
+      lastScrollTop = element.scrollTop;
       return;
     }
 
     // Cancel any ongoing smooth scroll animation
-    if (smoothScrollRAF !== null) {
-      cancelAnimationFrame(smoothScrollRAF);
-      smoothScrollRAF = null;
-    }
+    cancelSmoothScroll();
 
     const startTime = performance.now();
+    isAutoScrolling = true;
 
     // Easing function: ease-out cubic for smooth deceleration
     const easeOutCubic = (t: number): number => {
@@ -2022,8 +2098,13 @@ export const createAgentExperience = (
     };
 
     const animate = (currentTime: number) => {
+      if (!autoFollow.isFollowing()) {
+        cancelSmoothScroll();
+        return;
+      }
+
       // Recalculate target each frame in case scrollHeight changed
-      const currentTarget = element.scrollHeight;
+      const currentTarget = getScrollBottomOffset(element);
       if (currentTarget !== target) {
         target = currentTarget;
         distance = target - start;
@@ -2035,13 +2116,16 @@ export const createAgentExperience = (
       
       const currentScroll = start + distance * eased;
       element.scrollTop = currentScroll;
+      lastScrollTop = element.scrollTop;
 
       if (progress < 1) {
         smoothScrollRAF = requestAnimationFrame(animate);
       } else {
         // Ensure we end exactly at the target
-        element.scrollTop = element.scrollHeight;
+        element.scrollTop = target;
+        lastScrollTop = element.scrollTop;
         smoothScrollRAF = null;
+        isAutoScrolling = false;
       }
     };
 
@@ -2481,20 +2565,6 @@ export const createAgentExperience = (
 
     // Use idiomorph to morph the container contents
     morphMessages(container, tempContainer);
-    // Defer scroll to next frame for smoother animation and to prevent jolt
-    // This allows the browser to update layout (e.g., typing indicator removal) before scrolling
-    // Use double RAF to ensure layout has fully settled before starting scroll animation
-    // Get the scrollable container using its unique ID (#persona-scroll-container)
-    // Only smooth-scroll if auto-scroll hasn't been blocked by the user scrolling up
-    if (shouldAutoScroll && !isAutoScrollBlocked) {
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          if (!shouldAutoScroll || isAutoScrollBlocked) return;
-          const scrollableContainer = getScrollableContainer();
-          smoothScrollToBottom(scrollableContainer);
-        });
-      });
-    }
   };
 
   // Alias for clarity - the implementation handles flicker prevention via typing indicator logic
@@ -2562,12 +2632,46 @@ export const createAgentExperience = (
     const prevOpen = open;
     open = nextOpen;
     updateOpenState();
-    
+
+    // Sync host stacking and scroll lock for viewport-covering modes
+    const isViewportCovering = (() => {
+      const sm = config.launcher?.sidebarMode ?? false;
+      const ow = mount.ownerDocument.defaultView ?? window;
+      const mf = config.launcher?.mobileFullscreen ?? true;
+      const mb = config.launcher?.mobileBreakpoint ?? 640;
+      const isMobile = ow.innerWidth <= mb;
+      const dockedMF = isDockedMountMode(config) && mf && isMobile;
+      return sm || (mf && isMobile && launcherEnabled) || dockedMF;
+    })();
+
+    if (open && isViewportCovering) {
+      if (!teardownHostStacking) {
+        const root = mount.getRootNode();
+        const hostEl = root instanceof ShadowRoot
+          ? (root.host as HTMLElement)
+          : mount.closest<HTMLElement>(".persona-host");
+        if (hostEl) {
+          teardownHostStacking = syncOverlayHostStacking(
+            hostEl,
+            config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+          );
+        }
+      }
+      if (!releaseScrollLock) {
+        releaseScrollLock = acquireScrollLock(mount.ownerDocument);
+      }
+    } else if (!open) {
+      teardownHostStacking?.();
+      teardownHostStacking = null;
+      releaseScrollLock?.();
+      releaseScrollLock = null;
+    }
+
     if (open) {
       recalcPanelHeight();
       scheduleAutoScroll(true);
     }
-    
+
     // Emit widget state events
     const stateEvent: AgentWidgetStateEvent = {
       open,
@@ -3512,7 +3616,37 @@ export const createAgentExperience = (
     } finally {
       // applyFullHeightStyles() assigns wrapper.style.cssText (e.g. display:flex !important), which
       // overwrites updateOpenState()'s display:none when docked+closed. Re-sync after every recalc.
+      updateScrollToBottomButtonOffset();
       updateOpenState();
+
+      // Sync scroll lock and host stacking when viewport mode changes (e.g. orientation change)
+      if (open && launcherEnabled) {
+        const ow = mount.ownerDocument.defaultView ?? window;
+        const isMobile = ow.innerWidth <= (config.launcher?.mobileBreakpoint ?? 640);
+        const sm = config.launcher?.sidebarMode ?? false;
+        const mf = config.launcher?.mobileFullscreen ?? true;
+        const dockedMF = isDockedMountMode(config) && mf && isMobile;
+        const isVC = sm || (mf && isMobile && launcherEnabled) || dockedMF;
+
+        if (isVC && !releaseScrollLock) {
+          const root = mount.getRootNode();
+          const hostEl = root instanceof ShadowRoot
+            ? (root.host as HTMLElement)
+            : mount.closest<HTMLElement>(".persona-host");
+          if (hostEl && !teardownHostStacking) {
+            teardownHostStacking = syncOverlayHostStacking(
+              hostEl,
+              config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+            );
+          }
+          releaseScrollLock = acquireScrollLock(mount.ownerDocument);
+        } else if (!isVC) {
+          teardownHostStacking?.();
+          teardownHostStacking = null;
+          releaseScrollLock?.();
+          releaseScrollLock = null;
+        }
+      }
     }
   };
 
@@ -3520,37 +3654,68 @@ export const createAgentExperience = (
   const ownerWindow = mount.ownerDocument.defaultView ?? window;
   ownerWindow.addEventListener("resize", recalcPanelHeight);
   destroyCallbacks.push(() => ownerWindow.removeEventListener("resize", recalcPanelHeight));
+  if (typeof ResizeObserver !== "undefined") {
+    const footerResizeObserver = new ResizeObserver(() => {
+      updateScrollToBottomButtonOffset();
+    });
+    footerResizeObserver.observe(footer);
+    destroyCallbacks.push(() => footerResizeObserver.disconnect());
+  }
 
   lastScrollTop = body.scrollTop;
 
   const handleScroll = () => {
     const scrollTop = body.scrollTop;
-    const scrollHeight = body.scrollHeight;
-    const clientHeight = body.clientHeight;
-    const distanceFromBottom = scrollHeight - scrollTop - clientHeight;
-    const delta = Math.abs(scrollTop - lastScrollTop);
-    lastScrollTop = scrollTop;
-
-    if (isAutoScrolling) return;
-    if (delta <= USER_SCROLL_THRESHOLD) return;
-
-    if (!shouldAutoScroll && distanceFromBottom < BOTTOM_THRESHOLD) {
-      isAutoScrollBlocked = false;
-      shouldAutoScroll = true;
+    const { action, nextLastScrollTop } = resolveFollowStateFromScroll({
+      following: autoFollow.isFollowing(),
+      currentScrollTop: scrollTop,
+      lastScrollTop,
+      nearBottom: isElementNearBottom(body, BOTTOM_THRESHOLD),
+      userScrollThreshold: USER_SCROLL_THRESHOLD,
+      isAutoScrolling,
+      pauseOnUpwardScroll: true,
+      pauseWhenAwayFromBottom: false,
+      resumeRequiresDownwardScroll: true
+    });
+    lastScrollTop = nextLastScrollTop;
+
+    if (action === "resume") {
+      resumeAutoScroll();
       return;
     }
 
-    if (shouldAutoScroll && distanceFromBottom > BOTTOM_THRESHOLD) {
-      isAutoScrollBlocked = true;
-      blockUntilTime = Date.now() + AUTO_SCROLL_BLOCK_TIME;
-      shouldAutoScroll = false;
+    if (action === "pause") {
+      pauseAutoScroll();
     }
   };
 
   body.addEventListener("scroll", handleScroll, { passive: true });
   destroyCallbacks.push(() => body.removeEventListener("scroll", handleScroll));
+  const handleWheel = (event: WheelEvent) => {
+    const action = resolveFollowStateFromWheel({
+      following: autoFollow.isFollowing(),
+      deltaY: event.deltaY,
+      nearBottom: isElementNearBottom(body, BOTTOM_THRESHOLD),
+      resumeWhenNearBottom: true
+    });
+
+    if (action === "pause") {
+      pauseAutoScroll();
+    } else if (action === "resume") {
+      resumeAutoScroll();
+    }
+  };
+  body.addEventListener("wheel", handleWheel, { passive: true });
+  destroyCallbacks.push(() => body.removeEventListener("wheel", handleWheel));
+  scrollToBottomButton.addEventListener("click", () => {
+    body.scrollTop = body.scrollHeight;
+    lastScrollTop = body.scrollTop;
+    resumeAutoScroll();
+    scheduleAutoScroll(true);
+  });
+  destroyCallbacks.push(() => scrollToBottomButton.remove());
   destroyCallbacks.push(() => {
-    if (scrollRAF) cancelAnimationFrame(scrollRAF);
+    cancelAutoScroll();
   });
 
   const refreshCloseButton = () => {
@@ -3581,6 +3746,7 @@ export const createAgentExperience = (
       // Clear messages in session (this will trigger onMessagesChanged which re-renders)
       session.clearMessages();
       messageCache.clear();
+      resumeAutoScroll();
 
       // Always clear the default localStorage key
       try {
@@ -3697,6 +3863,9 @@ export const createAgentExperience = (
       autoExpand = config.launcher?.autoExpand ?? false;
       showReasoning = config.features?.showReasoning ?? true;
       showToolCalls = config.features?.showToolCalls ?? true;
+      scrollToBottomFeature = config.features?.scrollToBottom ?? {};
+      renderScrollToBottomButton();
+      syncScrollToBottomButton();
       const prevShowEventStreamToggle = showEventStreamToggle;
       showEventStreamToggle = config.features?.showEventStreamToggle ?? false;
 
@@ -3875,6 +4044,8 @@ export const createAgentExperience = (
       if (footer) {
         footer.style.display = showFooter ? "" : "none";
       }
+      updateScrollToBottomButtonOffset();
+      syncScrollToBottomButton();
 
       // Only update open state if launcher enabled state changed or autoExpand value changed
       const launcherEnabledChanged = launcherEnabled !== prevLauncherEnabled;
@@ -4155,6 +4326,7 @@ export const createAgentExperience = (
 
               // Position tooltip above button
               portaledTooltip.style.position = "fixed";
+              portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
               portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
               portaledTooltip.style.top = `${buttonRect.top - 8}px`;
               portaledTooltip.style.transform = "translate(-50%, -100%)";
@@ -4369,6 +4541,7 @@ export const createAgentExperience = (
 
                 // Position tooltip above button
                 portaledTooltip.style.position = "fixed";
+                portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
                 portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
                 portaledTooltip.style.top = `${buttonRect.top - 8}px`;
                 portaledTooltip.style.transform = "translate(-50%, -100%)";
@@ -4899,6 +5072,7 @@ export const createAgentExperience = (
       artifactsPaneUserHidden = false;
       session.clearMessages();
       messageCache.clear();
+      resumeAutoScroll();
 
       // Always clear the default localStorage key
       try {

package/src/utils/auto-follow.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createFollowStateController,
+  getScrollBottomOffset,
+  isElementNearBottom,
+  resolveFollowStateFromScroll,
+  resolveFollowStateFromWheel
+} from "./auto-follow";
+
+describe("auto-follow utilities", () => {
+  it("tracks pause and resume state", () => {
+    const state = createFollowStateController();
+
+    expect(state.isFollowing()).toBe(true);
+    expect(state.pause()).toBe(true);
+    expect(state.isFollowing()).toBe(false);
+    expect(state.pause()).toBe(false);
+    expect(state.resume()).toBe(true);
+    expect(state.isFollowing()).toBe(true);
+  });
+
+  it("computes bottom offset and near-bottom status", () => {
+    const element = {
+      scrollTop: 590,
+      scrollHeight: 1000,
+      clientHeight: 400
+    };
+
+    expect(getScrollBottomOffset(element)).toBe(600);
+    expect(isElementNearBottom(element, 10)).toBe(true);
+    expect(isElementNearBottom({ ...element, scrollTop: 560 }, 10)).toBe(false);
+  });
+
+  it("pauses transcript-style auto-follow on upward scroll immediately", () => {
+    const result = resolveFollowStateFromScroll({
+      following: true,
+      currentScrollTop: 597,
+      lastScrollTop: 600,
+      nearBottom: true,
+      userScrollThreshold: 1,
+      pauseOnUpwardScroll: true,
+      pauseWhenAwayFromBottom: false
+    });
+
+    expect(result.action).toBe("pause");
+  });
+
+  it("resumes event-log-style auto-follow only when scrolling down near bottom", () => {
+    const stayPaused = resolveFollowStateFromScroll({
+      following: false,
+      currentScrollTop: 550,
+      lastScrollTop: 560,
+      nearBottom: true,
+      userScrollThreshold: 1,
+      resumeRequiresDownwardScroll: true
+    });
+    const resume = resolveFollowStateFromScroll({
+      following: false,
+      currentScrollTop: 590,
+      lastScrollTop: 550,
+      nearBottom: true,
+      userScrollThreshold: 1,
+      resumeRequiresDownwardScroll: true
+    });
+
+    expect(stayPaused.action).toBe("none");
+    expect(resume.action).toBe("resume");
+  });
+
+  it("keeps transcript-style auto-follow paused near the bottom until scrolling down", () => {
+    const stayPaused = resolveFollowStateFromScroll({
+      following: false,
+      currentScrollTop: 597,
+      lastScrollTop: 600,
+      nearBottom: true,
+      userScrollThreshold: 1,
+      resumeRequiresDownwardScroll: true
+    });
+    const resume = resolveFollowStateFromScroll({
+      following: false,
+      currentScrollTop: 599,
+      lastScrollTop: 597,
+      nearBottom: true,
+      userScrollThreshold: 1,
+      resumeRequiresDownwardScroll: true
+    });
+
+    expect(stayPaused.action).toBe("none");
+    expect(resume.action).toBe("resume");
+  });
+
+  it("resolves wheel intent for pause and resume", () => {
+    expect(
+      resolveFollowStateFromWheel({
+        following: true,
+        deltaY: -12
+      })
+    ).toBe("pause");
+
+    expect(
+      resolveFollowStateFromWheel({
+        following: false,
+        deltaY: 12,
+        nearBottom: true,
+        resumeWhenNearBottom: true
+      })
+    ).toBe("resume");
+  });
+});