@runtypelabs/persona 3.29.1 → 3.31.0

package/src/ui.ts

@@ -3,6 +3,7 @@ import { resolveSanitizer } from "./utils/sanitize";
 import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
 import {
   AgentWidgetConfig,
+  AgentWidgetApprovalDecisionOptions,
   AgentWidgetMessage,
   AgentWidgetEvent,
   AgentWidgetStorageAdapter,
@@ -40,8 +41,11 @@ import {
 } from "./utils/composer-history";
 import { computeMessageFingerprint, createMessageCache, getCachedWrapper, setCachedWrapper, pruneCache } from "./utils/message-fingerprint";
 import {
+  computeAnchorScrollState,
+  computeShrunkSpacerHeight,
   createFollowStateController,
   getScrollBottomOffset,
+  hasSelectionWithin,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
@@ -85,7 +89,7 @@ import {
   setCurrentAnswer,
 } from "./components/ask-user-question-bubble";
 import { formatElapsedMs } from "./utils/formatting";
-import { createApprovalBubble } from "./components/approval-bubble";
+import { approvalDetailsExpansionState, createApprovalBubble, updateApprovalDetailsUI } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
 import { EventStreamStore } from "./utils/event-stream-store";
@@ -375,8 +379,14 @@ type Controller = {
    * Programmatically resolve a pending approval.
    * @param approvalId - The approval ID to resolve
    * @param decision - "approved" or "denied"
+   * @param options - Optional decision context (e.g. `{ remember: true }`),
+   *   forwarded to `config.approval.onDecision`.
    */
-  resolveApproval: (approvalId: string, decision: 'approved' | 'denied') => Promise<void>;
+  resolveApproval: (
+    approvalId: string,
+    decision: 'approved' | 'denied',
+    options?: AgentWidgetApprovalDecisionOptions
+  ) => Promise<void>;
 };
 
 const buildPostprocessor = (
@@ -665,6 +675,7 @@ export const createAgentExperience = (
   let showToolCalls = config.features?.showToolCalls ?? true;
   let showEventStreamToggle = config.features?.showEventStreamToggle ?? false;
   let scrollToBottomFeature = config.features?.scrollToBottom ?? {};
+  let scrollBehaviorFeature = config.features?.scrollBehavior ?? {};
   const persistKeyPrefix = (typeof config.persistState === 'object' ? config.persistState?.keyPrefix : undefined) ?? "persona-";
   const eventStreamDbName = `${persistKeyPrefix}event-stream`;
   let eventStreamStore = showEventStreamToggle ? new EventStreamStore(eventStreamDbName) : null;
@@ -785,6 +796,8 @@ export const createAgentExperience = (
   const getScrollToBottomLabel = () => scrollToBottomFeature.label ?? "";
   const getScrollToBottomIconName = () => scrollToBottomFeature.iconName ?? "arrow-down";
   const isScrollToBottomEnabled = () => scrollToBottomFeature.enabled !== false;
+  const getScrollMode = () => scrollBehaviorFeature.mode ?? "follow";
+  const getAnchorTopOffset = () => scrollBehaviorFeature.anchorTopOffset ?? 16;
   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"
@@ -794,9 +807,28 @@ export const createAgentExperience = (
   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);
+  // Count of messages that arrived while auto-follow was paused (or, in
+  // non-follow scroll modes, while the user was away from the bottom).
+  // Rendered as a small badge on the scroll-to-bottom affordance, mirroring
+  // the event stream view's "Jump to latest (N)" indicator.
+  const scrollToBottomCount = createElement("span", "");
+  scrollToBottomCount.setAttribute("data-persona-scroll-to-bottom-count", "");
+  scrollToBottomCount.style.display = "none";
+  scrollToBottomButton.append(scrollToBottomIcon, scrollToBottomLabel, scrollToBottomCount);
   container.appendChild(scrollToBottomButton);
 
+  // Anchor-top scroll mode: zero-height spacer kept after the messages
+  // wrapper. Sized on send so the just-sent user message can be scrolled to
+  // the top of the viewport before the streamed response is tall enough to
+  // make that position reachable; shrinks as real content fills the space.
+  const anchorSpacer = createElement("div", "persona-stream-anchor-spacer");
+  anchorSpacer.setAttribute("aria-hidden", "true");
+  anchorSpacer.setAttribute("data-persona-anchor-spacer", "");
+  anchorSpacer.style.flexShrink = "0";
+  anchorSpacer.style.pointerEvents = "none";
+  anchorSpacer.style.height = "0px";
+  body.appendChild(anchorSpacer);
+
   const updateScrollToBottomButtonOffset = () => {
     const footerHidden = footer.style.display === "none";
     const footerHeight = footerHidden ? 0 : footer.offsetHeight;
@@ -1218,7 +1250,7 @@ export const createAgentExperience = (
     if (!headerButton) return;
     
     // Find the parent bubble element
-    const bubble = headerButton.closest('.persona-reasoning-bubble, .persona-tool-bubble') as HTMLElement;
+    const bubble = headerButton.closest('.persona-reasoning-bubble, .persona-tool-bubble, .persona-approval-bubble') as HTMLElement;
     if (!bubble) return;
     
     // Get message ID from bubble
@@ -1242,6 +1274,12 @@ export const createAgentExperience = (
         toolExpansionState.add(messageId);
       }
       updateToolBubbleUI(messageId, bubble, config);
+    } else if (bubbleType === 'approval') {
+      const approvalConfig = config.approval !== false ? config.approval : undefined;
+      const defaultExpanded = (approvalConfig?.detailsDisplay ?? 'collapsed') === 'expanded';
+      const expanded = approvalDetailsExpansionState.get(messageId) ?? defaultExpanded;
+      approvalDetailsExpansionState.set(messageId, !expanded);
+      updateApprovalDetailsUI(messageId, bubble, config);
     }
     // Invalidate cached wrapper so next render rebuilds with current expansion state
     messageCache.delete(messageId);
@@ -2599,12 +2637,33 @@ export const createAgentExperience = (
   // expensive rebuild on fingerprint change so user state inside the rendered
   // component (e.g. partially-filled form inputs) is not wiped on every pass.
   const lastComponentDirectiveFingerprint = new Map<string, string>();
+  // Same idea for plugin-rendered approval bubbles (`renderApproval`). The
+  // custom element is injected into the live DOM post-morph so its event
+  // listeners (Approve/Deny, an expandable parameters accordion, etc.) survive;
+  // this map gates the rebuild on fingerprint change so interactive state (e.g.
+  // a collapsed accordion) is not reset on every pass while the approval is
+  // pending.
+  const lastApprovalBubbleFingerprint = new Map<string, string>();
   let configVersion = 0;
   const autoFollow = createFollowStateController();
   let lastScrollTop = 0;
   let scrollRAF: number | null = null;
   let isAutoScrolling = false;
   let hasPendingAutoScroll = false;
+  // Messages that arrived while the user was away from the latest content;
+  // shown as a badge on the scroll-to-bottom affordance.
+  let newMessagesSincePause = 0;
+  // Live anchor-top state for the current turn (null when not anchored).
+  let anchorState: {
+    initialSpacerHeight: number;
+    contentHeightAtAnchor: number;
+    spacerHeight: number;
+  } | null = null;
+  let anchorRAF: number | null = null;
+  // Seeded send-detection so restored history doesn't read as a fresh send.
+  let scrollSendSeeded = false;
+  let suppressScrollSend = false;
+  let lastSentUserMessageId: string | null = null;
 
   // Scroll events caused by layout, scroll anchoring, and smooth-scroll
   // easing can easily move by a couple pixels. Keep manual wheel intent
@@ -2732,6 +2791,39 @@ export const createAgentExperience = (
     cancelSmoothScroll();
   };
 
+  const updateScrollToBottomCountBadge = () => {
+    if (newMessagesSincePause > 0) {
+      scrollToBottomCount.textContent = String(newMessagesSincePause);
+      scrollToBottomCount.style.display = "";
+      scrollToBottomButton.setAttribute(
+        "aria-label",
+        `${getScrollToBottomLabel() || "Jump to latest"} (${newMessagesSincePause} new)`
+      );
+    } else {
+      scrollToBottomCount.textContent = "";
+      scrollToBottomCount.style.display = "none";
+      scrollToBottomButton.setAttribute(
+        "aria-label",
+        getScrollToBottomLabel() || "Jump to latest"
+      );
+    }
+  };
+
+  const resetNewMessagesCount = () => {
+    if (newMessagesSincePause === 0) return;
+    newMessagesSincePause = 0;
+    updateScrollToBottomCountBadge();
+  };
+
+  // Whether the user is currently away from the latest content — drives both
+  // the scroll-to-bottom affordance and the new-messages badge. In follow
+  // mode that's "auto-follow paused"; in anchor-top/none modes (where there
+  // is no follow state) it's simply "not near the bottom".
+  const isAwayFromLatest = () =>
+    getScrollMode() === "follow"
+      ? !autoFollow.isFollowing()
+      : !isElementNearBottom(body, BOTTOM_THRESHOLD);
+
   const syncScrollToBottomButton = () => {
     if (!isScrollToBottomEnabled() || eventStreamVisible) {
       if (scrollToBottomButton.parentNode) {
@@ -2745,7 +2837,11 @@ export const createAgentExperience = (
     }
     updateScrollToBottomButtonOffset();
     const hasOverflow = getScrollBottomOffset(body) > 0;
-    scrollToBottomButton.style.display = (autoFollow.isFollowing() || !hasOverflow) ? "none" : "";
+    const show = hasOverflow && isAwayFromLatest();
+    if (!show) {
+      resetNewMessagesCount();
+    }
+    scrollToBottomButton.style.display = show ? "" : "none";
   };
 
   const pauseAutoScroll = () => {
@@ -2756,10 +2852,15 @@ export const createAgentExperience = (
 
   const resumeAutoScroll = () => {
     autoFollow.resume();
+    resetNewMessagesCount();
     syncScrollToBottomButton();
   };
 
   const scheduleAutoScroll = (force = false) => {
+    // Auto-follow only applies in "follow" mode; anchor-top and none never
+    // chase the bottom during streaming.
+    if (getScrollMode() !== "follow") return;
+
     if (!autoFollow.isFollowing()) return;
 
     if (!force && !isStreaming) return;
@@ -2788,31 +2889,21 @@ export const createAgentExperience = (
     });
   };
 
-  // Custom smooth scroll animation with easing
-  const smoothScrollToBottom = (element: HTMLElement, duration = 500) => {
+  // Generic eased scroll animation. `resolveTarget` is re-read every frame so
+  // a moving target (the bottom of a streaming transcript) stays accurate;
+  // `shouldContinue` lets the caller cancel mid-flight (e.g. when auto-follow
+  // pauses). Scroll events emitted by the animation are masked from the
+  // user-intent detector via `isAutoScrolling`.
+  const animateScrollTo = (
+    element: HTMLElement,
+    resolveTarget: () => number,
+    duration: number,
+    shouldContinue: () => boolean = () => true
+  ) => {
     const start = element.scrollTop;
-    // Recalculate target dynamically to handle layout changes
-    let target = getScrollBottomOffset(element);
+    let target = resolveTarget();
     let distance = target - start;
 
-    // If already at bottom or very close, skip animation to prevent glitch
-    if (Math.abs(distance) < 1) {
-      lastScrollTop = element.scrollTop;
-      return;
-    }
-
-    // If the transcript has fallen noticeably behind, catch up immediately
-    // instead of easing over multiple frames. This keeps fast streaming /
-    // bursty tool and reasoning updates pinned to the bottom.
-    if (Math.abs(distance) >= AUTO_SCROLL_SNAP_THRESHOLD) {
-      cancelSmoothScroll();
-      isAutoScrolling = true;
-      element.scrollTop = target;
-      lastScrollTop = element.scrollTop;
-      isAutoScrolling = false;
-      return;
-    }
-
     // Cancel any ongoing smooth scroll animation
     cancelSmoothScroll();
 
@@ -2825,13 +2916,13 @@ export const createAgentExperience = (
     };
 
     const animate = (currentTime: number) => {
-      if (!autoFollow.isFollowing()) {
+      if (!shouldContinue()) {
         cancelSmoothScroll();
         return;
       }
 
       // Recalculate target each frame in case scrollHeight changed
-      const currentTarget = getScrollBottomOffset(element);
+      const currentTarget = resolveTarget();
       if (currentTarget !== target) {
         target = currentTarget;
         distance = target - start;
@@ -2840,7 +2931,7 @@ export const createAgentExperience = (
       const elapsed = currentTime - startTime;
       const progress = Math.min(elapsed / duration, 1);
       const eased = easeOutCubic(progress);
-      
+
       const currentScroll = start + distance * eased;
       element.scrollTop = currentScroll;
       lastScrollTop = element.scrollTop;
@@ -2859,6 +2950,157 @@ export const createAgentExperience = (
     smoothScrollRAF = requestAnimationFrame(animate);
   };
 
+  // Custom smooth scroll animation with easing
+  const smoothScrollToBottom = (element: HTMLElement, duration = 500) => {
+    const distance = getScrollBottomOffset(element) - element.scrollTop;
+
+    // If already at bottom or very close, skip animation to prevent glitch
+    if (Math.abs(distance) < 1) {
+      lastScrollTop = element.scrollTop;
+      return;
+    }
+
+    // If the transcript has fallen noticeably behind, catch up immediately
+    // instead of easing over multiple frames. This keeps fast streaming /
+    // bursty tool and reasoning updates pinned to the bottom.
+    if (Math.abs(distance) >= AUTO_SCROLL_SNAP_THRESHOLD) {
+      cancelSmoothScroll();
+      isAutoScrolling = true;
+      element.scrollTop = getScrollBottomOffset(element);
+      lastScrollTop = element.scrollTop;
+      isAutoScrolling = false;
+      return;
+    }
+
+    animateScrollTo(
+      element,
+      () => getScrollBottomOffset(element),
+      duration,
+      () => autoFollow.isFollowing()
+    );
+  };
+
+  // Instant jump used for initial mount / panel open in non-follow scroll
+  // modes (where scheduleAutoScroll is inert).
+  const jumpToBottomInstant = () => {
+    const element = getScrollableContainer();
+    isAutoScrolling = true;
+    element.scrollTop = getScrollBottomOffset(element);
+    lastScrollTop = element.scrollTop;
+    isAutoScrolling = false;
+    syncScrollToBottomButton();
+  };
+
+  const setAnchorSpacerHeight = (height: number) => {
+    anchorSpacer.style.height = `${Math.max(0, Math.round(height))}px`;
+    if (anchorState) {
+      anchorState.spacerHeight = Math.max(0, height);
+    }
+  };
+
+  const resetAnchorState = () => {
+    if (anchorRAF !== null) {
+      cancelAnimationFrame(anchorRAF);
+      anchorRAF = null;
+    }
+    // Also stop an in-flight anchor scroll animation — otherwise its
+    // remaining frames keep easing scrollTop toward the stale anchor target
+    // after a jump-to-latest, chat clear, or scroll-mode change.
+    cancelSmoothScroll();
+    anchorState = null;
+    anchorSpacer.style.height = "0px";
+  };
+
+  // Anchor-top mode: scroll the just-sent user message to rest
+  // `anchorTopOffset` px below the viewport top and hold it there while the
+  // response streams in beneath it. Deferred one frame so the message bubble
+  // has been rendered and laid out.
+  const scheduleAnchorToUserMessage = (messageId: string) => {
+    if (anchorRAF !== null) {
+      cancelAnimationFrame(anchorRAF);
+    }
+    anchorRAF = requestAnimationFrame(() => {
+      anchorRAF = null;
+      const escapedId =
+        typeof CSS !== "undefined" && typeof CSS.escape === "function"
+          ? CSS.escape(messageId)
+          : messageId.replace(/"/g, '\\"');
+      const bubble = body.querySelector<HTMLElement>(
+        `[data-message-id="${escapedId}"]`
+      );
+      if (!bubble) return;
+
+      // Bubble top relative to the scroll content. `body` is the positioned
+      // ancestor, so walking offsetParents terminates there. offsetTop is
+      // used instead of getBoundingClientRect so in-flight entrance
+      // animations (transforms) can't skew the target.
+      let anchorOffsetTop = 0;
+      let node: HTMLElement | null = bubble;
+      while (node && node !== body) {
+        anchorOffsetTop += node.offsetTop;
+        node = node.offsetParent as HTMLElement | null;
+      }
+
+      const previousSpacerHeight = anchorState?.spacerHeight ?? 0;
+      const contentHeight = body.scrollHeight - previousSpacerHeight;
+      const { targetScrollTop, spacerHeight } = computeAnchorScrollState({
+        anchorOffsetTop,
+        topOffset: getAnchorTopOffset(),
+        viewportHeight: body.clientHeight,
+        contentHeight
+      });
+
+      anchorState = {
+        initialSpacerHeight: spacerHeight,
+        contentHeightAtAnchor: contentHeight,
+        spacerHeight
+      };
+      setAnchorSpacerHeight(spacerHeight);
+      animateScrollTo(body, () => targetScrollTop, 220);
+    });
+  };
+
+  // Content growth handler (ResizeObserver-driven). In follow mode this is
+  // what keeps the transcript pinned when content grows *without* a render
+  // event — images/embeds finishing loading mid-stream, fonts swapping,
+  // the panel or composer resizing. In anchor-top mode it gives spacer room
+  // back as the streamed response grows (shrink-only, so total scroll height
+  // stays constant and nothing jumps).
+  const handleContentResize = () => {
+    if (getScrollMode() === "follow") {
+      if (!autoFollow.isFollowing()) return;
+      if (isElementNearBottom(body, 1)) return;
+      scheduleAutoScroll(!isStreaming);
+      return;
+    }
+    if (anchorState && anchorState.initialSpacerHeight > 0) {
+      const currentContentHeight = body.scrollHeight - anchorState.spacerHeight;
+      const next = computeShrunkSpacerHeight({
+        initialSpacerHeight: anchorState.initialSpacerHeight,
+        contentHeightAtAnchor: anchorState.contentHeightAtAnchor,
+        currentContentHeight
+      });
+      if (next !== anchorState.spacerHeight) {
+        setAnchorSpacerHeight(next);
+      }
+    }
+    syncScrollToBottomButton();
+  };
+
+  // Reacts to a user message the user just sent (seeded so restored history
+  // never triggers it). Follow mode re-sticks to the bottom even if the user
+  // had scrolled up — sending is an unambiguous "take me to the latest"
+  // signal. Anchor-top mode pins the sent message near the viewport top.
+  const handleUserMessageSent = (messageId: string) => {
+    const mode = getScrollMode();
+    if (mode === "follow") {
+      resumeAutoScroll();
+      scheduleAutoScroll(true);
+    } else if (mode === "anchor-top") {
+      scheduleAnchorToUserMessage(messageId);
+    }
+  };
+
   const trackMessages = (messages: AgentWidgetMessage[]) => {
     const nextState = new Map<
       string,
@@ -2874,6 +3116,19 @@ export const createAgentExperience = (
 
       if (!previous && message.role === "assistant") {
         eventBus.emit("assistant:message", message);
+        // Count messages the user hasn't seen for the scroll-to-bottom badge.
+        // Skipped in anchor-top (the user is already reading the latest turn
+        // from its top, so a "new" count would mislead) and during history
+        // hydration (restored messages aren't "missed").
+        if (
+          !suppressScrollSend &&
+          getScrollMode() !== "anchor-top" &&
+          isAwayFromLatest()
+        ) {
+          newMessagesSincePause += 1;
+          updateScrollToBottomCountBadge();
+          syncScrollToBottomButton();
+        }
       }
 
       if (
@@ -2977,10 +3232,26 @@ export const createAgentExperience = (
     const componentDirectiveHydrate: ComponentDirectiveHydrate[] = [];
     const componentStreamingEnabled = config.enableComponentStreaming !== false;
 
+    // Plugin-rendered approval bubbles use the same stub-and-hydrate pattern:
+    // `renderApproval` may attach listeners (the built-in bubble resolves via
+    // delegation on `messagesWrapper`, but a custom element owns its own
+    // interactivity), and idiomorph imports nodes via `document.importNode`,
+    // which strips them. So we build the live element, append a stub during
+    // morph, and inject the live element afterward.
+    const hasApprovalPlugin = plugins.some((p) => p.renderApproval) && config.approval !== false;
+    type ApprovalPluginHydrate = {
+      messageId: string;
+      fingerprint: string;
+      bubble: HTMLElement | null;
+    };
+    const approvalPluginHydrate: ApprovalPluginHydrate[] = [];
+
     messages.forEach((message) => {
       activeMessageIds.add(message.id);
 
       const askWithPlugin = hasAskPlugin && isAskUserQuestionMessage(message);
+      const approvalWithPlugin =
+        hasApprovalPlugin && message.variant === "approval" && !!message.approval;
       const hasDirectiveBubble =
         !askWithPlugin &&
         message.role === "assistant" &&
@@ -2988,6 +3259,14 @@ export const createAgentExperience = (
         componentStreamingEnabled &&
         hasComponentDirective(message);
 
+      // If a message stops being an approval-plugin bubble, strip
+      // `data-preserve-runtime` so the next morph can replace the live wrapper.
+      if (!approvalWithPlugin && lastApprovalBubbleFingerprint.has(message.id)) {
+        const existing = container.querySelector<HTMLElement>(`#wrapper-${message.id}`);
+        existing?.removeAttribute("data-preserve-runtime");
+        lastApprovalBubbleFingerprint.delete(message.id);
+      }
+
       // If a message previously rendered as a directive bubble but no longer
       // does (e.g. content was rewritten), strip `data-preserve-runtime` from
       // the live wrapper so the next morph can replace it.
@@ -3009,7 +3288,7 @@ export const createAgentExperience = (
           }`
         : "";
       const fingerprint = computeMessageFingerprint(message, configVersion) + askMeta;
-      const cachedWrapper = (askWithPlugin || hasDirectiveBubble)
+      const cachedWrapper = (askWithPlugin || approvalWithPlugin || hasDirectiveBubble)
         ? null
         : getCachedWrapper(messageCache, message.id, fingerprint);
       if (cachedWrapper) {
@@ -3043,9 +3322,9 @@ export const createAgentExperience = (
         if (message.variant === "tool" && p.renderToolCall) {
           return true;
         }
-        if (message.variant === "approval" && p.renderApproval) {
-          return true;
-        }
+        // Approval plugins are handled via the stub-and-hydrate path below
+        // (see `approvalWithPlugin`), not this inline morph path, so their
+        // listeners survive — so they are intentionally excluded here.
         if (!message.variant && p.renderMessage) {
           return true;
         }
@@ -3159,6 +3438,74 @@ export const createAgentExperience = (
           }
           return;
         }
+      } else if (approvalWithPlugin) {
+        // Plugin-rendered approval bubble. Build the live element with its
+        // listeners, append a stub for the morph pass, and hydrate the live
+        // element into the morphed wrapper afterward (same trick as
+        // `renderAskUserQuestion` / component directives) so Approve/Deny and
+        // any accordion listeners survive idiomorph's `importNode`. Gate the
+        // rebuild on fingerprint so interactive state (e.g. a collapsed
+        // accordion) is preserved while the approval stays pending.
+        const approvalPlugin = plugins.find((p) => typeof p.renderApproval === "function");
+        const lastFp = lastApprovalBubbleFingerprint.get(message.id);
+        const needsRebuild = lastFp !== fingerprint;
+        let liveBubble: HTMLElement | null = null;
+
+        if (needsRebuild && approvalPlugin?.renderApproval) {
+          // Re-find the live message at decision time so we resolve against
+          // current state, and route WebMCP gate approvals to the local
+          // resolver — mirroring the built-in delegated handler.
+          const approvalMessageId = message.id;
+          const resolveDecision = (
+            decision: "approved" | "denied",
+            options?: AgentWidgetApprovalDecisionOptions
+          ): void => {
+            const live = sessionRef.current
+              ?.getMessages()
+              .find((m) => m.id === approvalMessageId);
+            if (!live?.approval) return;
+            if (live.approval.toolType === "webmcp") {
+              sessionRef.current?.resolveWebMcpApproval(live.id, decision);
+            } else {
+              sessionRef.current?.resolveApproval(live.approval, decision, options);
+            }
+          };
+          liveBubble = approvalPlugin.renderApproval({
+            message,
+            defaultRenderer: () => createApprovalBubble(message, config),
+            config,
+            approve: (options) => resolveDecision("approved", options),
+            deny: (options) => resolveDecision("denied", options)
+          });
+        }
+
+        if (needsRebuild && liveBubble === null) {
+          // Plugin opted out for this state (e.g. a resolved approval, where the
+          // demo plugin defers to the built-in approved/denied bubble). Render
+          // the built-in bubble — it resolves via the delegated `messagesWrapper`
+          // handler and morphs normally — and drop any preserved live wrapper so
+          // morph can replace the now-stale pending bubble.
+          const existing = container.querySelector<HTMLElement>(`#wrapper-${message.id}`);
+          existing?.removeAttribute("data-preserve-runtime");
+          lastApprovalBubbleFingerprint.delete(message.id);
+          bubble = createApprovalBubble(message, config);
+        } else {
+          // A fresh live bubble to hydrate (needsRebuild), or fingerprint
+          // unchanged so we reuse the preserved live wrapper (`bubble: null`).
+          const stub = document.createElement("div");
+          stub.className = "persona-flex";
+          stub.id = `wrapper-${message.id}`;
+          stub.setAttribute("data-wrapper-id", message.id);
+          stub.setAttribute("data-approval-plugin-stub", "true");
+          stub.setAttribute("data-preserve-runtime", "true");
+          tempContainer.appendChild(stub);
+          approvalPluginHydrate.push({
+            messageId: message.id,
+            fingerprint,
+            bubble: liveBubble
+          });
+          return;
+        }
       } else if (matchingPlugin) {
         if (message.variant === "reasoning" && message.reasoning && matchingPlugin.renderReasoning) {
           if (!showReasoning) return;
@@ -3174,13 +3521,6 @@ export const createAgentExperience = (
             defaultRenderer: () => createToolBubble(message, config),
             config
           });
-        } else if (message.variant === "approval" && message.approval && matchingPlugin.renderApproval) {
-          if (config.approval === false) return;
-          bubble = matchingPlugin.renderApproval({
-            message,
-            defaultRenderer: () => createApprovalBubble(message, config),
-            config
-          });
         } else if (matchingPlugin.renderMessage) {
           bubble = matchingPlugin.renderMessage({
             message,
@@ -3663,6 +4003,30 @@ export const createAgentExperience = (
         if (!activeMessageIds.has(id)) lastComponentDirectiveFingerprint.delete(id);
       }
     }
+
+    // Hydrate plugin-rendered approval bubbles into their stub wrappers,
+    // mirroring the ask-question / component-directive hydration above.
+    if (approvalPluginHydrate.length > 0) {
+      for (const { messageId, fingerprint, bubble } of approvalPluginHydrate) {
+        const wrapper = container.querySelector(`#wrapper-${messageId}`);
+        if (!wrapper) continue;
+        if (bubble === null) {
+          // Fingerprint matched the previous pass (or the plugin opted out
+          // after a prior render) — the live wrapper, kept alive by
+          // `data-preserve-runtime`, still holds the listener-bearing bubble.
+          continue;
+        }
+        wrapper.replaceChildren(bubble);
+        wrapper.setAttribute("data-bubble-fp", fingerprint);
+        lastApprovalBubbleFingerprint.set(messageId, fingerprint);
+      }
+    }
+
+    if (lastApprovalBubbleFingerprint.size > 0) {
+      for (const id of lastApprovalBubbleFingerprint.keys()) {
+        if (!activeMessageIds.has(id)) lastApprovalBubbleFingerprint.delete(id);
+      }
+    }
   };
 
   // Alias for clarity - the implementation handles flicker prevention via typing indicator logic
@@ -4251,7 +4615,13 @@ export const createAgentExperience = (
 
     if (open) {
       recalcPanelHeight();
-      scheduleAutoScroll(true);
+      if (getScrollMode() === "follow") {
+        scheduleAutoScroll(true);
+      } else {
+        // Non-follow modes still start at the latest content when the panel
+        // opens; they just never chase it during streaming.
+        jumpToBottomInstant();
+      }
     }
 
     // Emit widget state events
@@ -4407,6 +4777,20 @@ export const createAgentExperience = (
         .reverse()
         .find((msg) => msg.role === "user");
 
+      // Scroll-on-send / anchor-top. Seeded so restored history (constructor
+      // initialMessages and async storage hydration) never reads as a fresh
+      // send; clearing the chat resets any anchor spacer.
+      if (messages.length === 0) {
+        resetAnchorState();
+      }
+      if (!scrollSendSeeded || suppressScrollSend) {
+        scrollSendSeeded = true;
+        lastSentUserMessageId = lastUserMessage?.id ?? null;
+      } else if (lastUserMessage && lastUserMessage.id !== lastSentUserMessageId) {
+        lastSentUserMessageId = lastUserMessage.id;
+        handleUserMessageSent(lastUserMessage.id);
+      }
+
       // Emit user:message event when a new user message is detected
       const prevLastUserMessageId = voiceState.lastUserMessageId;
       if (lastUserMessage && lastUserMessage.id !== prevLastUserMessageId) {
@@ -4486,6 +4870,11 @@ export const createAgentExperience = (
 
   sessionRef.current = session;
 
+  // The constructor only emits onMessagesChanged when it has initial
+  // messages, so seed send-detection explicitly for the empty-session case —
+  // otherwise the user's very first send would be mistaken for the seed.
+  scrollSendSeeded = true;
+
   // Setup Runtype voice provider when configured (connects WebSocket for server-side STT)
   if (config.voiceRecognition?.provider?.type === 'runtype') {
     try {
@@ -4532,7 +4921,14 @@ export const createAgentExperience = (
           actionManager.syncFromMetadata();
         }
         if (state.messages?.length) {
-          session.hydrateMessages(state.messages);
+          // Restored history must not read as a fresh send (scroll-on-send /
+          // anchor-top would fire for the last restored user message).
+          suppressScrollSend = true;
+          try {
+            session.hydrateMessages(state.messages);
+          } finally {
+            suppressScrollSend = false;
+          }
         }
         if (state.artifacts?.length) {
           session.hydrateArtifacts(
@@ -5305,7 +5701,11 @@ export const createAgentExperience = (
   suggestionsManager.render(config.suggestionChips, session, textarea, undefined, config.suggestionChipsConfig);
   updateCopy();
   setComposerDisabled(session.isStreaming());
-  scheduleAutoScroll(true);
+  if (getScrollMode() === "follow") {
+    scheduleAutoScroll(true);
+  } else {
+    jumpToBottomInstant();
+  }
   maybeRestoreVoiceFromMetadata();
 
   if (autoFocusInput) {
@@ -5429,18 +5829,44 @@ export const createAgentExperience = (
   }
 
   lastScrollTop = body.scrollTop;
-  let lastScrollHeight = body.scrollHeight;
+  let lastBottomOffset = getScrollBottomOffset(body);
+
+  const getTranscriptSelection = (): Selection | null => {
+    // Selections inside a shadow root are not always reflected by
+    // document.getSelection(); prefer the shadow root's view when available
+    // (non-standard but supported where it matters).
+    const root = body.getRootNode();
+    const shadowSelection =
+      typeof (root as ShadowRoot & { getSelection?: () => Selection | null })
+        .getSelection === "function"
+        ? (root as ShadowRoot & { getSelection: () => Selection | null }).getSelection()
+        : null;
+    return shadowSelection ?? body.ownerDocument.getSelection();
+  };
+  const hasActiveTranscriptSelection = () =>
+    hasSelectionWithin(getTranscriptSelection(), body);
 
   const handleScroll = () => {
     const scrollTop = body.scrollTop;
-    // When content mutates (e.g. stream-animation plugins re-rendering text),
-    // scrollHeight can shrink and force the browser to clamp scrollTop downward.
+    // When content mutates (e.g. stream-animation plugins re-rendering text)
+    // or the viewport grows (composer shrinking back), the maximum scroll
+    // position can shrink and force the browser to clamp scrollTop downward.
     // That emits a scroll event with a negative delta that would otherwise be
     // misread as the user scrolling up, pausing auto-follow and flashing the
-    // scroll-to-bottom button. Treat those as non-user events.
-    const currentScrollHeight = body.scrollHeight;
-    const scrollHeightShrank = currentScrollHeight < lastScrollHeight;
-    lastScrollHeight = currentScrollHeight;
+    // scroll-to-bottom button. Treat those as non-user events. Tracking the
+    // bottom offset (scrollHeight - clientHeight) rather than scrollHeight
+    // alone also covers clientHeight-driven clamps.
+    const currentBottomOffset = getScrollBottomOffset(body);
+    const bottomOffsetShrank = currentBottomOffset < lastBottomOffset;
+    lastBottomOffset = currentBottomOffset;
+
+    if (getScrollMode() !== "follow") {
+      // No follow state to manage — just keep the scroll-to-bottom
+      // affordance in sync with the user's position.
+      lastScrollTop = scrollTop;
+      syncScrollToBottomButton();
+      return;
+    }
 
     const { action, nextLastScrollTop } = resolveFollowStateFromScroll({
       following: autoFollow.isFollowing(),
@@ -5448,7 +5874,7 @@ export const createAgentExperience = (
       lastScrollTop,
       nearBottom: isElementNearBottom(body, BOTTOM_THRESHOLD),
       userScrollThreshold: USER_SCROLL_THRESHOLD,
-      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll || scrollHeightShrank,
+      isAutoScrolling: isAutoScrolling || hasPendingAutoScroll || bottomOffsetShrank,
       pauseOnUpwardScroll: true,
       pauseWhenAwayFromBottom: false,
       resumeRequiresDownwardScroll: true
@@ -5456,7 +5882,12 @@ export const createAgentExperience = (
     lastScrollTop = nextLastScrollTop;
 
     if (action === "resume") {
-      resumeAutoScroll();
+      // Drag-selecting downward near the bottom edge auto-scrolls down and
+      // would otherwise read as a resume gesture; keep follow paused while a
+      // transcript selection is active so it isn't yanked mid-drag.
+      if (!hasActiveTranscriptSelection()) {
+        resumeAutoScroll();
+      }
       return;
     }
 
@@ -5467,7 +5898,41 @@ export const createAgentExperience = (
 
   body.addEventListener("scroll", handleScroll, { passive: true });
   destroyCallbacks.push(() => body.removeEventListener("scroll", handleScroll));
+
+  // Content-growth follow. Render events already schedule auto-scroll, but
+  // content can also grow without one: images/embeds finishing loading
+  // mid-stream, web fonts swapping, the panel or composer resizing. Observe
+  // the messages wrapper (content growth) and the scroll container itself
+  // (viewport resize) so the pin survives all of them.
+  if (typeof ResizeObserver !== "undefined") {
+    const contentResizeObserver = new ResizeObserver(() => {
+      handleContentResize();
+    });
+    contentResizeObserver.observe(messagesWrapper);
+    contentResizeObserver.observe(body);
+    destroyCallbacks.push(() => contentResizeObserver.disconnect());
+  }
+
+  // Pause auto-follow while the user selects transcript text so the
+  // streaming scroll doesn't move content out from under the selection.
+  // Driven purely by selectionchange (no pointer gating) so keyboard
+  // selection (Shift+arrows, select-all) pauses too; a stale selection
+  // left in the transcript fires no further events, so it can't re-pause
+  // after the user resumes following.
+  const handleSelectionChange = () => {
+    if (getScrollMode() !== "follow") return;
+    if (!autoFollow.isFollowing()) return;
+    if (hasActiveTranscriptSelection()) {
+      pauseAutoScroll();
+    }
+  };
+  const selectionDocument = body.ownerDocument;
+  selectionDocument.addEventListener("selectionchange", handleSelectionChange);
+  destroyCallbacks.push(() => {
+    selectionDocument.removeEventListener("selectionchange", handleSelectionChange);
+  });
   const handleWheel = (event: WheelEvent) => {
+    if (getScrollMode() !== "follow") return;
     const action = resolveFollowStateFromWheel({
       following: autoFollow.isFollowing(),
       deltaY: event.deltaY,
@@ -5477,21 +5942,27 @@ export const createAgentExperience = (
 
     if (action === "pause") {
       pauseAutoScroll();
-    } else if (action === "resume") {
+    } else if (action === "resume" && !hasActiveTranscriptSelection()) {
       resumeAutoScroll();
     }
   };
   body.addEventListener("wheel", handleWheel, { passive: true });
   destroyCallbacks.push(() => body.removeEventListener("wheel", handleWheel));
   scrollToBottomButton.addEventListener("click", () => {
+    // Jumping to the latest abandons the current anchor: drop the spacer
+    // first so "bottom" means the real end of content, not spacer padding
+    // that would keep shrinking underneath the reader.
+    resetAnchorState();
     body.scrollTop = body.scrollHeight;
     lastScrollTop = body.scrollTop;
     resumeAutoScroll();
     scheduleAutoScroll(true);
+    syncScrollToBottomButton();
   });
   destroyCallbacks.push(() => scrollToBottomButton.remove());
   destroyCallbacks.push(() => {
     cancelAutoScroll();
+    resetAnchorState();
   });
 
   const refreshCloseButton = () => {
@@ -5736,6 +6207,14 @@ export const createAgentExperience = (
       showReasoning = config.features?.showReasoning ?? true;
       showToolCalls = config.features?.showToolCalls ?? true;
       scrollToBottomFeature = config.features?.scrollToBottom ?? {};
+      const prevScrollMode = getScrollMode();
+      scrollBehaviorFeature = config.features?.scrollBehavior ?? {};
+      if (prevScrollMode !== getScrollMode()) {
+        // Leaving anchor-top drops any live spacer; entering a new mode
+        // starts from a clean follow state.
+        resetAnchorState();
+        resumeAutoScroll();
+      }
       renderScrollToBottomButton();
       syncScrollToBottomButton();
       const prevShowEventStreamToggle = showEventStreamToggle;
@@ -7258,7 +7737,11 @@ export const createAgentExperience = (
       textarea.focus();
       return true;
     },
-    async resolveApproval(approvalId: string, decision: 'approved' | 'denied'): Promise<void> {
+    async resolveApproval(
+      approvalId: string,
+      decision: 'approved' | 'denied',
+      options?: AgentWidgetApprovalDecisionOptions
+    ): Promise<void> {
       const messages = session.getMessages();
       const approvalMessage = messages.find(
         m => m.variant === "approval" && m.approval?.id === approvalId
@@ -7274,7 +7757,7 @@ export const createAgentExperience = (
         session.resolveWebMcpApproval(approvalMessage.id, decision);
         return;
       }
-      return session.resolveApproval(approvalMessage.approval, decision);
+      return session.resolveApproval(approvalMessage.approval, decision, options);
     },
     getMessages() {
       return session.getMessages();