@runtypelabs/persona 4.12.0 → 4.14.0

package/src/ui.ts

@@ -64,6 +64,7 @@ import {
   createFollowStateController,
   getScrollBottomOffset,
   hasSelectionWithin,
+  isAttentionWorthyMessage,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
@@ -90,7 +91,7 @@ import { buildHeaderWithLayout } from "./components/header-layouts";
 import { positionMap } from "./utils/positioning";
 import type { HeaderElements as _HeaderElements, ComposerElements as _ComposerElements } from "./components/panel";
 import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } from "./components/message-bubble";
-import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
+import { createStandardBubble, createTypingIndicator, getBubbleClasses } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
 import {
@@ -132,6 +133,7 @@ import {
   shouldExpandLauncherForArtifacts
 } from "./utils/artifact-gate";
 import { resolveArtifactDisplayMode } from "./utils/artifact-display";
+import { resolveConfigPreferences } from "./utils/feature-preferences";
 import { readFlexGapPx, resolveArtifactPaneWidthPx } from "./utils/artifact-resize";
 import { enhanceWithForms } from "./components/forms";
 import { pluginRegistry } from "./plugins/registry";
@@ -595,6 +597,11 @@ export const createAgentExperience = (
   }
 
   let config = mergeWithDefaults(initialConfig) as AgentWidgetConfig;
+  // `config.features` holds the preference-resolved view every read site uses;
+  // `baseFeatures` keeps the pre-preference base so update() re-resolves from
+  // it instead of stacking new preferences onto already-overlaid values.
+  let baseFeatures = config.features;
+  config = resolveConfigPreferences(config);
   // Note: applyThemeVariables is called after applyFullHeightStyles() below
   // because applyFullHeightStyles resets mount.style.cssText
 
@@ -1799,7 +1806,7 @@ export const createAgentExperience = (
   let artifactPaneExpandedPinned = false;
   // Whether the user explicitly opened the pane (card click, inline Expand,
   // showArtifacts(), programmatic upsert). Auto-open is otherwise reserved for
-  // artifacts whose resolved display mode is "panel": "card" keeps the card as
+  // artifacts whose resolved display mode is "panel": "collapsed" keeps the card as
   // the only affordance and "inline" renders in the transcript. "inline" no
   // longer *auto*-opens the pane, but its Expand control is a deliberate,
   // user-driven open (setting artifactsPaneUserOpened, same as a card click);
@@ -1810,7 +1817,7 @@ export const createAgentExperience = (
     artifactsPaneUserOpened ||
     lastArtifactsState.artifacts.some(
       (a) =>
-        resolveArtifactDisplayMode(config.features?.artifacts, a.artifactType) === "panel"
+        resolveArtifactDisplayMode(config.features?.artifacts, a) === "panel"
     );
   const artifactPaneVisible = () =>
     lastArtifactsState.artifacts.length > 0 &&
@@ -2009,7 +2016,7 @@ export const createAgentExperience = (
     event.preventDefault();
     event.stopPropagation();
     artifactsPaneUserHidden = false;
-    // Card click is an explicit open: it overrides the "card"/"inline"
+    // Card click is an explicit open: it overrides the "collapsed"/"inline"
     // auto-open suppression for as long as artifacts exist.
     artifactsPaneUserOpened = true;
     session.selectArtifact(artifactId);
@@ -2517,7 +2524,7 @@ export const createAgentExperience = (
     } else if (lastArtifactsState.artifacts.length > 0 && artifactPaneCanShow()) {
       // User chose “show” again (e.g. programmatic showArtifacts): clear dismiss chrome
       // and force drawer open so narrow-host / mobile slide-out is not stuck off-screen.
-      // Artifacts whose display mode is "card" or "inline" don't auto-open the
+      // Artifacts whose display mode is "collapsed" or "inline" don't auto-open the
       // pane (artifactPaneCanShow); it stays hidden until an explicit open or
       // until a "panel"-mode artifact arrives.
       artifactPaneApi.element.classList.remove("persona-hidden");
@@ -3537,6 +3544,24 @@ export const createAgentExperience = (
   // pinned and never re-arms the fallback, so a late-loading embed can't yank
   // the viewport down to the bottom.
   let currentTurnAnchored = false;
+  // Which message the anchor is currently parked on. Starts as the sent user
+  // message and moves once to the turn's first attention-worthy block (see
+  // `maybeAnchorToFirstUnread`).
+  let anchoredMessageId: string | null = null;
+  // Has the reader taken over positioning this turn? First-unread anchoring is
+  // a guess about where someone who ISN'T watching wants to land; the moment
+  // they demonstrably are watching, the guess stands down and never moves the
+  // viewport under them. Reset on each user send (an explicit "take me along").
+  //
+  // Driven by real INPUT (wheel, touch drag, pointer press, transcript
+  // keyboard nav, focus, selection) rather than by scroll deltas: streaming
+  // content under a pinned anchor makes the browser clamp and then restore
+  // scrollTop, which is indistinguishable from a deliberate scroll if you only
+  // look at the scroll event.
+  let readerEngagedThisTurn = false;
+  const markReaderEngaged = () => {
+    readerEngagedThisTurn = true;
+  };
   // Dedupes assistant-turn detection across token-by-token re-renders.
   let lastHandledAssistantId: string | null = null;
 
@@ -3940,6 +3965,24 @@ export const createAgentExperience = (
     return top;
   };
 
+  // Defined here (rather than beside the scroll listeners) because
+  // `maybeAnchorToFirstUnread` runs on every render and would otherwise hit
+  // these consts in their temporal dead zone on a synchronous first paint.
+  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);
+
   // Principle 11: reopen where the reader left off. When `restorePosition` is
   // "last-user-turn" and there is pre-existing history, land with the last user
   // message pinned near the top of the viewport instead of jumping to the
@@ -4002,11 +4045,10 @@ export const createAgentExperience = (
     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) => {
+  // Anchor-top mode: scroll `messageId` 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 scheduleAnchorToMessage = (messageId: string) => {
     if (anchorRAF !== null) {
       cancelAnimationFrame(anchorRAF);
     }
@@ -4087,7 +4129,11 @@ export const createAgentExperience = (
       // next user send.
       followFallbackActive = false;
       currentTurnAnchored = true;
-      scheduleAnchorToUserMessage(messageId);
+      // A send is an explicit "take me along": it re-arms first-unread
+      // positioning even if the reader had scrolled away during the last turn.
+      readerEngagedThisTurn = false;
+      anchoredMessageId = messageId;
+      scheduleAnchorToMessage(messageId);
     }
   };
 
@@ -4110,6 +4156,44 @@ export const createAgentExperience = (
     scheduleAutoScroll(true);
   };
 
+  // Anchor-top positioning: park on the turn's FIRST UNREAD attention-worthy
+  // block.
+  //
+  // The read boundary is the last user send — the reader wrote it, so it (and
+  // everything above) is read; every attention-worthy block after it is not.
+  // Tool calls and reasoning are chrome and never targeted, so they scroll
+  // past underneath rather than parking the reader on progress output.
+  //
+  // The policy assumes the reader is NOT watching the stream, and picks the
+  // best place for them to land when they look back: the start of what they
+  // haven't seen. `readerEngagedThisTurn` is the escape hatch — once someone
+  // is demonstrably driving, their position wins and this stands down until
+  // the next send.
+  //
+  // Anchoring to the first unread (not the newest) block means this fires at
+  // most once per turn in practice, and later blocks stream in below the
+  // anchor exactly as they do today.
+  const maybeAnchorToFirstUnread = (messages: AgentWidgetMessage[]) => {
+    if (getScrollMode() !== "anchor-top") return;
+    if (!currentTurnAnchored) return;
+    if (readerEngagedThisTurn) return;
+    if (hasActiveTranscriptSelection()) return;
+
+    let pastReadBoundary = lastSentUserMessageId === null;
+    for (const message of messages) {
+      if (!pastReadBoundary) {
+        if (message.id === lastSentUserMessageId) pastReadBoundary = true;
+        continue;
+      }
+      if (!isAttentionWorthyMessage(message)) continue;
+      // Already parked on it: hold still while it streams.
+      if (message.id === anchoredMessageId) return;
+      anchoredMessageId = message.id;
+      scheduleAnchorToMessage(message.id);
+      return;
+    }
+  };
+
   const trackMessages = (messages: AgentWidgetMessage[]) => {
     const nextState = new Map<
       string,
@@ -4967,28 +5051,30 @@ export const createAgentExperience = (
 
       // Only render if we have an indicator (allows hiding via returning null)
       if (typingIndicator) {
-        // Create a bubble wrapper for the typing indicator (similar to assistant messages)
+        // Bubble wrapper for the typing indicator. It borrows the assistant
+        // bubble's classes and background so the "thinking" bubble matches the
+        // message bubbles that replace it under every layout preset.
         const typingBubble = document.createElement("div");
         const showBubble = config.loadingIndicator?.showBubble !== false; // default true
+        const messageLayout = config.layout?.messages?.layout ?? "bubble";
         typingBubble.className = showBubble
-          ? [
-              "persona-rounded-2xl",
-              "persona-text-sm",
-              "persona-leading-relaxed",
-              "persona-shadow-sm",
-              "persona-bg-persona-surface",
-              "persona-border",
-              "persona-text-persona-primary",
-              "persona-px-5",
-              "persona-py-3"
-            ].join(" ")
+          ? getBubbleClasses("assistant", messageLayout).join(" ")
           : [
               "persona-text-sm",
               "persona-leading-relaxed",
-              "persona-text-persona-primary"
+              "persona-text-persona-text"
             ].join(" ");
         typingBubble.setAttribute("data-typing-indicator", "true");
-        typingBubble.style.borderColor = "var(--persona-message-assistant-border, var(--persona-border, #e5e7eb))";
+        if (showBubble) {
+          typingBubble.style.color =
+            "var(--persona-message-assistant-text, var(--persona-text))";
+          if (messageLayout !== "flat") {
+            typingBubble.style.backgroundColor =
+              "var(--persona-message-assistant-bg, var(--persona-container))";
+            typingBubble.style.borderColor =
+              "var(--persona-message-assistant-border, var(--persona-border, #e5e7eb))";
+          }
+        }
 
         typingBubble.appendChild(typingIndicator);
 
@@ -5998,6 +6084,8 @@ export const createAgentExperience = (
       resetAnchorState();
       followFallbackActive = true;
       currentTurnAnchored = false;
+      anchoredMessageId = null;
+      readerEngagedThisTurn = false;
     }
     if (!scrollSendSeeded || suppressScrollSend) {
       scrollSendSeeded = true;
@@ -6013,6 +6101,7 @@ export const createAgentExperience = (
       handleAssistantTurnStarted();
     }
     if (lastAssistantMessage) lastHandledAssistantId = lastAssistantMessage.id;
+    maybeAnchorToFirstUnread(messages);
 
     const prevLastUserMessageId = voiceState.lastUserMessageId;
     if (lastUserMessage && lastUserMessage.id !== prevLastUserMessageId) {
@@ -7341,21 +7430,6 @@ export const createAgentExperience = (
   lastScrollTop = body.scrollTop;
   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)
@@ -7373,6 +7447,14 @@ export const createAgentExperience = (
     if (!isFollowEffective()) {
       // No follow state to manage (anchored anchor-top / none): just keep the
       // scroll-to-bottom affordance in sync with the user's position.
+      //
+      // Reader intent is deliberately NOT inferred from scroll deltas here.
+      // Growing the transcript under a pinned anchor makes the browser clamp
+      // scrollTop and then restore it, which lands as a matched pair of real
+      // scroll events (e.g. -12 then +12) with no user involved. The restore
+      // arrives while the bottom offset is GROWING, so the shrink mask above
+      // doesn't cover it, and it reads as a deliberate scroll. Engagement is
+      // tracked from actual input instead (see `markReaderEngaged` callers).
       lastScrollTop = scrollTop;
       syncScrollToBottomButton();
       return;
@@ -7459,21 +7541,23 @@ export const createAgentExperience = (
     "ArrowDown",
   ]);
   const handleTranscriptKeydown = (event: KeyboardEvent) => {
+    if (!NAV_KEYS.has(event.key)) return;
+    // Reader intent for first-unread anchoring is tracked unconditionally;
+    // only the follow-mode *pause* below stays behind the opt-in flag.
+    markReaderEngaged();
     if (!isPauseOnInteractionEnabled()) return;
     if (!isFollowEffective()) return;
     if (!autoFollow.isFollowing()) return;
-    if (NAV_KEYS.has(event.key)) {
-      pauseAutoScroll();
-    }
+    pauseAutoScroll();
   };
   const handleTranscriptFocusIn = (event: FocusEvent) => {
+    const target = event.target as Element | null;
+    if (!target?.closest("a, button, [tabindex], input, textarea, select")) return;
+    markReaderEngaged();
     if (!isPauseOnInteractionEnabled()) return;
     if (!isFollowEffective()) return;
     if (!autoFollow.isFollowing()) return;
-    const target = event.target as Element | null;
-    if (target && target.closest("a, button, [tabindex], input, textarea, select")) {
-      pauseAutoScroll();
-    }
+    pauseAutoScroll();
   };
   body.addEventListener("keydown", handleTranscriptKeydown);
   body.addEventListener("focusin", handleTranscriptFocusIn);
@@ -7483,6 +7567,9 @@ export const createAgentExperience = (
   });
 
   const handleWheel = (event: WheelEvent) => {
+    // A wheel tick is unambiguous reader intent in every mode — including
+    // anchored anchor-top, where there is no follow state to pause.
+    if (event.deltaY !== 0) markReaderEngaged();
     if (!isFollowEffective()) return;
     const action = resolveFollowStateFromWheel({
       following: autoFollow.isFollowing(),
@@ -7498,6 +7585,14 @@ export const createAgentExperience = (
     }
   };
   body.addEventListener("wheel", handleWheel, { passive: true });
+  // Touch drag and pointer press (scrollbar drags, tapping a tool bubble open)
+  // are the remaining ways a reader takes over without a wheel or key event.
+  body.addEventListener("touchmove", markReaderEngaged, { passive: true });
+  body.addEventListener("pointerdown", markReaderEngaged, { passive: true });
+  destroyCallbacks.push(() => {
+    body.removeEventListener("touchmove", markReaderEngaged);
+    body.removeEventListener("pointerdown", markReaderEngaged);
+  });
   destroyCallbacks.push(() => body.removeEventListener("wheel", handleWheel));
   scrollToBottomButton.addEventListener("click", () => {
     // Jumping to the latest abandons the current anchor: drop the spacer
@@ -7759,8 +7854,11 @@ export const createAgentExperience = (
       const previousStreamAnimationType = config.features?.streamAnimation?.type;
       // One consistent recursive patch policy across the live controller and the
       // init handle. See utils/config-merge.ts for the replace-leaf list and
-      // explicit-undefined reset semantics.
-      config = mergeConfigUpdate(config, nextConfig);
+      // explicit-undefined reset semantics. The patch merges over the
+      // pre-preference base features, then preferences re-resolve on top.
+      config = mergeConfigUpdate({ ...config, features: baseFeatures }, nextConfig);
+      baseFeatures = config.features;
+      config = resolveConfigPreferences(config);
       // applyFullHeightStyles resets mount.style.cssText, so call it before applyThemeVariables
       applyFullHeightStyles();
       applyThemeVariables(mount, config);
@@ -9195,13 +9293,20 @@ export const createAgentExperience = (
       if (!artifactsSidebarEnabled(config)) return null;
       // Programmatic upserts match the streamed UX: only "panel"-mode
       // artifacts auto-open the pane (overriding a previous Close), while
-      // "card"/"inline" stay calm — the injected transcript block is the
+      // "collapsed"/"inline" stay calm — the injected transcript block is the
       // affordance. Independent of `transcript: false`: pane-only callers
-      // (e.g. the theme editor preview) rely on the panel-default surfacing;
-      // callers that want the pane in a non-panel mode call showArtifacts().
+      // (e.g. the theme editor preview) rely on the auto-open default
+      // surfacing; callers that want the pane in another mode call
+      // showArtifacts().
       const mode = resolveArtifactDisplayMode(
         config.features?.artifacts,
-        manual.artifactType
+        {
+          artifactType: manual.artifactType,
+          ...(manual.artifactType === "markdown" && manual.file
+            ? { file: manual.file }
+            : {}),
+          ...(manual.presentation ? { presentation: manual.presentation } : {}),
+        }
       );
       if (mode === "panel") {
         artifactsPaneUserHidden = false;

package/src/ui.typing-indicator.test.ts

@@ -0,0 +1,135 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+/**
+ * Mount a widget with a never-resolving fetch, send a message, and return the
+ * standalone typing indicator bubble rendered during the silent gap.
+ */
+const renderTypingBubble = async (
+  config: Record<string, unknown>
+): Promise<{ bubble: HTMLElement; destroy: () => void }> => {
+  global.fetch = vi.fn().mockImplementation(
+    () => new Promise(() => {})
+  ) as unknown as typeof fetch;
+
+  const mount = createMount();
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+  controller.submitMessage("hello");
+  await Promise.resolve();
+  await Promise.resolve();
+
+  const bubble = mount.querySelector<HTMLElement>('[data-typing-indicator="true"]')!;
+  return { bubble, destroy: () => controller.destroy() };
+};
+
+describe("standalone typing indicator bubble", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("uses the assistant bubble classes under the default bubble layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({});
+
+    expect(bubble).not.toBeNull();
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(true);
+    expect(bubble.classList.contains("persona-border")).toBe(true);
+    expect(bubble.classList.contains("persona-px-5")).toBe(true);
+
+    destroy();
+  });
+
+  it("drops the shadow and border under the minimal layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "minimal" } },
+    });
+
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.classList.contains("persona-px-3")).toBe(true);
+    // Minimal keeps the surface background, matching its message bubbles.
+    expect(bubble.style.backgroundColor).toContain("--persona-message-assistant-bg");
+
+    destroy();
+  });
+
+  it("drops the background entirely under the flat layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "flat" } },
+    });
+
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.style.backgroundColor).toBe("");
+    expect(bubble.style.color).toBe(
+      "var(--persona-message-assistant-text, var(--persona-text))"
+    );
+
+    destroy();
+  });
+
+  it("renders bare text classes when loadingIndicator.showBubble is false", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      loadingIndicator: { showBubble: false },
+    });
+
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(false);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.classList.contains("persona-text-persona-text")).toBe(true);
+    expect(bubble.classList.contains("persona-text-persona-primary")).toBe(false);
+    expect(bubble.style.backgroundColor).toBe("");
+
+    destroy();
+  });
+
+  it("honors the assistant bubble theme background token", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "minimal" } },
+      theme: {
+        semantic: {
+          colors: {
+            container: "#112233",
+            text: "#ddeeff",
+            border: "#445566",
+          },
+        },
+      },
+    });
+
+    // The bubble reads the same variable the assistant message bubbles read,
+    // so `theme.components.message.assistant.background` covers both.
+    expect(bubble.style.backgroundColor).toBe(
+      "var(--persona-message-assistant-bg, var(--persona-container))"
+    );
+    const root = bubble.closest<HTMLElement>("[data-persona-root]");
+    expect(root?.style.getPropertyValue("--persona-message-assistant-bg")).toBe(
+      "#112233"
+    );
+    expect(root?.style.getPropertyValue("--persona-message-assistant-text")).toBe(
+      "#ddeeff"
+    );
+    expect(root?.style.getPropertyValue("--persona-message-assistant-border")).toBe(
+      "#445566"
+    );
+
+    destroy();
+  });
+});