@runtypelabs/persona 4.14.0 → 4.16.0

package/src/ui.scroll-additive.test.ts

@@ -262,6 +262,53 @@ describe("scrollBehavior.showActivityWhilePinned (Principle 8)", () => {
   });
 });
 
+describe("anchor-top scroll-to-bottom affordance ignores spacer air", () => {
+  let raf: ReturnType<typeof installRafMock>;
+  beforeEach(() => {
+    raf = installRafMock();
+  });
+
+  it("stays hidden while the whole transcript is in view above the spacer, then shows once content grows past the viewport", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(
+      mount,
+      baseConfig({ features: { scrollBehavior: { mode: "anchor-top" } } })
+    );
+    const sc = getScrollContainer(mount);
+    // Short transcript (300px of content) in a 400px viewport.
+    const metrics = installScrollMetrics(sc, { scrollHeight: 300, clientHeight: 400 });
+
+    anchorUserTurn(controller);
+    // Give the anchored user bubble a real offset so the anchor computation
+    // produces a spacer (jsdom offsets are otherwise all 0).
+    const bubble = sc.querySelector<HTMLElement>('[data-message-id="u1"]')!;
+    Object.defineProperty(bubble, "offsetTop", { configurable: true, get: () => 200 });
+    raf.flush();
+
+    // Reflect the spacer in the mocked scroll metrics, as a browser would.
+    const spacer = sc.querySelector<HTMLElement>("[data-persona-anchor-spacer]")!;
+    const spacerHeight = parseFloat(spacer.style.height);
+    expect(spacerHeight).toBeGreaterThan(0);
+    metrics.setScrollHeight(300 + spacerHeight);
+
+    emitStreamingAssistant(controller, "a1", "Streaming reply");
+
+    // All 300px of real content fit in the [60, 460] viewport; the only
+    // scrollable space below is spacer air, so no jump affordance.
+    metrics.setScrollTop(60);
+    sc.dispatchEvent(new Event("scroll"));
+    expect(getScrollToBottomButton(mount).style.display).toBe("none");
+
+    // Content streams past the viewport bottom (300px -> 900px): now there is
+    // real content below the fold and the affordance appears.
+    metrics.setScrollHeight(900 + spacerHeight);
+    sc.dispatchEvent(new Event("scroll"));
+    expect(getScrollToBottomButton(mount).style.display).toBe("");
+
+    controller.destroy();
+  });
+});
+
 describe("scrollBehavior anchor-top no-anchor fallback", () => {
   let raf: ReturnType<typeof installRafMock>;
   beforeEach(() => {
@@ -451,10 +498,11 @@ describe("scrollBehavior.announce (Principle 15)", () => {
 });
 
 
-// Anchor-top parks on the first UNREAD attention-worthy block of a turn:
-// tool calls and reasoning are chrome and never targeted, so a response that
-// opens with them scrolls them past rather than stranding the answer below
-// the fold.
+// Anchor-top pins the sent user message (market pattern) and hands off to
+// the turn's first UNREAD attention-worthy block only when that block starts
+// below the fold: tool calls and reasoning are chrome and never targeted, so
+// a response that opens with them scrolls them past rather than stranding
+// the answer. A block starting within view keeps the user message anchored.
 describe("anchor-top first-unread positioning", () => {
   beforeEach(() => {
     installRafMock();
@@ -541,8 +589,13 @@ describe("anchor-top first-unread positioning", () => {
     // Tool calls are chrome: they never move the anchor.
     expect(metrics.getScrollTop()).toBe(284);
 
+    // The answer starts 400px below the pinned question — past the fold at a
+    // 400px viewport — so the anchor hands off to it. (The strandedness probe
+    // reads layout at render time, so the mocked offset needs one more
+    // render to be seen.)
     emitStreamingAssistant(controller, "a1", "Good news — your order is on track.");
     setBubbleOffsetTop(mount, "a1", 700);
+    emitStreamingAssistant(controller, "a1", "Good news — your order is on track!");
     raf.flush();
     expect(metrics.getScrollTop()).toBe(684);
 
@@ -564,7 +617,11 @@ describe("anchor-top first-unread positioning", () => {
     raf.flush();
 
     emitArtifactMessage(controller, "art-msg");
+    // 320px below the question: stranded past the 400 - 96 visibility floor,
+    // so the anchor hands off. The trailing tool render lets the probe see
+    // the mocked offset.
     setBubbleOffsetTop(mount, "art-msg", 620);
+    emitToolMessage(controller, "t-after");
     raf.flush();
 
     expect(metrics.getScrollTop()).toBe(604);
@@ -581,21 +638,24 @@ describe("anchor-top first-unread positioning", () => {
     });
 
     startTurn(controller, mount, raf);
+    // First segment starts past the fold (delta 400 at a 400px viewport):
+    // the anchor hands off to it.
     emitStreamingAssistant(controller, "a1", "First segment.");
-    setBubbleOffsetTop(mount, "a1", 500);
+    setBubbleOffsetTop(mount, "a1", 700);
     metrics.setScrollHeight(1400);
+    emitStreamingAssistant(controller, "a1", "First segment!");
     raf.flush();
-    expect(metrics.getScrollTop()).toBe(484);
+    expect(metrics.getScrollTop()).toBe(684);
 
     // Interleaved: tool, then a second text segment. The anchor stays on the
     // first unread block — later blocks stream in below it.
     emitToolMessage(controller, "t0");
     emitStreamingAssistant(controller, "a2", "Second segment.");
-    setBubbleOffsetTop(mount, "a2", 900);
+    setBubbleOffsetTop(mount, "a2", 1100);
     metrics.setScrollHeight(1800);
     raf.flush();
 
-    expect(metrics.getScrollTop()).toBe(484);
+    expect(metrics.getScrollTop()).toBe(684);
     controller.destroy();
   });
 
@@ -640,7 +700,9 @@ describe("anchor-top first-unread positioning", () => {
     sc.dispatchEvent(new WheelEvent("wheel", { deltaY: -120, bubbles: true }));
     sc.dispatchEvent(new Event("scroll"));
 
-    // A new send is an explicit "take me along".
+    // A new send is an explicit "take me along": the new user message
+    // anchors (600 - 16 = 584) and, with the reply starting only 200px below
+    // it — within view — stays anchored while the reply streams beneath.
     emitUserMessage(controller, "u2", "And the second order?");
     setBubbleOffsetTop(mount, "u2", 600);
     metrics.setScrollHeight(1400);
@@ -649,9 +711,10 @@ describe("anchor-top first-unread positioning", () => {
     emitStreamingAssistant(controller, "a2", "That one shipped Tuesday.");
     setBubbleOffsetTop(mount, "a2", 800);
     metrics.setScrollHeight(1600);
+    emitStreamingAssistant(controller, "a2", "That one shipped Tuesday!");
     raf.flush();
 
-    expect(metrics.getScrollTop()).toBe(784);
+    expect(metrics.getScrollTop()).toBe(584);
     controller.destroy();
   });
 });
@@ -694,16 +757,18 @@ describe("anchor-top first-unread — edge shapes", () => {
   };
 
   // KNOWN TRADEOFF: a chatty preamble ("Let me look that up…") is itself the
-  // first unread block, so the anchor lands there and the tool run still
-  // pushes the real answer toward the fold. That is the policy behaving as
-  // specified — chronological, honest about what arrived first — but it is
-  // the case most likely to want revisiting.
-  it("anchors a preamble, not the answer that follows the tool run", () => {
+  // first unread block, so when a long question strands it the anchor lands
+  // there — and the tool run still pushes the real answer toward the fold.
+  // That is the policy behaving as specified — chronological, honest about
+  // what arrived first — but it is the case most likely to want revisiting.
+  // (A preamble starting within view never moves the anchor at all: the user
+  // message keeps it.)
+  it("anchors a stranded preamble, not the answer that follows the tool run", () => {
     const raf = installRafMock();
     const mount = createMount();
     const controller = createAgentExperience(mount, anchorTopConfig());
     const metrics = installScrollMetrics(getScrollContainer(mount), {
-      scrollHeight: 1000,
+      scrollHeight: 1200,
       clientHeight: 400,
     });
 
@@ -712,20 +777,21 @@ describe("anchor-top first-unread — edge shapes", () => {
     setTop(mount, "u1", 300);
     raf.flush();
 
+    // A tall question strands the preamble (delta 400 > 400 - 96): handoff.
     emitStreamingAssistant(controller, "pre", "Sure — let me pull that up.");
-    setTop(mount, "pre", 420);
-    metrics.setScrollHeight(1200);
+    setTop(mount, "pre", 700);
+    emitStreamingAssistant(controller, "pre", "Sure — let me pull that up!");
     raf.flush();
-    expect(metrics.getScrollTop()).toBe(404);
+    expect(metrics.getScrollTop()).toBe(684);
 
     for (let i = 0; i < 6; i += 1) emitTool(controller, `t${i}`);
     emitStreamingAssistant(controller, "answer", "Good news — it is on track.");
-    setTop(mount, "answer", 900);
+    setTop(mount, "answer", 1300);
     metrics.setScrollHeight(1800);
     raf.flush();
 
     // Still parked on the preamble: the answer is NOT re-targeted.
-    expect(metrics.getScrollTop()).toBe(404);
+    expect(metrics.getScrollTop()).toBe(684);
     controller.destroy();
   });
 
@@ -805,9 +871,13 @@ describe("anchor-top first-unread — layout scroll is not reader intent", () =>
     sc.dispatchEvent(new Event("scroll"));
     raf.flush();
 
+    // Stranded answer (delta 400): the clamp/restore pair must not have been
+    // read as reader intent, so the handoff still fires. One more render so
+    // the strandedness probe sees the mocked offset.
     emitStreamingAssistant(controller, "a1", "Good news — your order is on track.");
     const answer = sc.querySelector<HTMLElement>('[data-message-id="a1"]');
     Object.defineProperty(answer!, "offsetTop", { configurable: true, value: 700 });
+    emitStreamingAssistant(controller, "a1", "Good news — your order is on track!");
     raf.flush();
 
     expect(metrics.getScrollTop()).toBe(684);

package/src/ui.scroll.test.ts

@@ -991,7 +991,7 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
-  it("anchor-top mode pins the turn's first unread block near the viewport top and never follows the stream", () => {
+  it("anchor-top keeps the sent user message pinned while the reply starts in view", () => {
     const raf = installRafMock();
     const resize = installResizeObserverMock();
     const mount = createMount();
@@ -1022,21 +1022,27 @@ describe("createAgentExperience streaming scroll", () => {
     // Run just the anchor frame: it sizes the spacer and starts the scroll.
     raf.step(1);
 
-    // target = 700 - 16 = 684; spacer = 684 + 400 - 1000 = 84.
+    // target = 700 - 16 = 684; spacer = 684 + 400 - 1000 + 24 slack = 108.
+    // The 24px slack keeps the held position off the clamp boundary so
+    // transient content dips during streaming can't bounce the viewport.
     const spacer = scrollContainer!.querySelector<HTMLElement>(
       "[data-persona-anchor-spacer]"
     );
-    expect(spacer?.style.height).toBe("84px");
+    expect(spacer?.style.height).toBe("108px");
+    // Sized means visible: unsized it stays display:none so the body's flex
+    // gap doesn't add phantom scrollable space below the transcript.
+    expect(spacer?.style.display).toBe("");
 
     // The spacer's height is invisible to the mocked scroll metrics: apply
     // it manually so the anchor target is reachable, as in a real browser.
-    metrics.setScrollHeight(1084);
+    metrics.setScrollHeight(1108);
     raf.flush();
     expect(metrics.getScrollTop()).toBe(684);
 
-    // The response's first block is the turn's first unread output, so the
-    // anchor hands off to it: target = 900 - 16 = 884, and with content at
-    // 1284 - 84 = 1200 the spacer re-sizes to 884 + 400 - 1200 = 84.
+    // The reply's first block starts 200px below the pinned user message —
+    // well within the 400px viewport — so the anchor STAYS on the user
+    // message (market pattern: the sent message remains visible as the
+    // header of the streaming reply). No handoff.
     metrics.setScrollHeight(1284);
     emitStreamingMessage(controller, "Streaming response");
     const streamBubble = scrollContainer!.querySelector<HTMLElement>(
@@ -1044,30 +1050,204 @@ describe("createAgentExperience streaming scroll", () => {
     );
     expect(streamBubble).not.toBeNull();
     Object.defineProperty(streamBubble!, "offsetTop", { value: 900 });
-    raf.flush();
-    expect(metrics.getScrollTop()).toBe(884);
-
-    // Continuing to stream below that anchor never moves the viewport again.
     metrics.setScrollHeight(1324);
     emitStreamingMessage(controller, "Streaming response, now longer");
     raf.flush();
-    expect(metrics.getScrollTop()).toBe(884);
+    expect(metrics.getScrollTop()).toBe(684);
 
     // As real content grows, the spacer gives room back (shrink-only):
-    // content grew from 1200 to 1324 - 84 = 1240, so spacer 84 - 40 = 44.
+    // content grew from 1000 to 1324 - 108 = 1216, past the 108px reserve.
     resize.trigger();
-    expect(spacer?.style.height).toBe("44px");
+    expect(spacer?.style.height).toBe("0px");
 
     // Jumping to the latest abandons the anchor: the spacer is dropped so
     // "bottom" is the real end of content.
     getScrollToBottomButton(mount)!.click();
     raf.flush();
     expect(spacer?.style.height).toBe("0px");
+    expect(spacer?.style.display).toBe("none");
     expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
 
     controller.destroy();
   });
 
+  it("trims leftover anchor spacer air when the stream ends", () => {
+    const raf = installRafMock();
+    installResizeObserverMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        scrollBehavior: { mode: "anchor-top", anchorTopOffset: 16 }
+      }
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitUserMessage(controller, "user-trim", "Long question");
+    const bubble = scrollContainer!.querySelector<HTMLElement>(
+      '[data-message-id="user-trim"]'
+    );
+    Object.defineProperty(bubble!, "offsetTop", { value: 700 });
+    raf.step(1);
+    const spacer = scrollContainer!.querySelector<HTMLElement>(
+      "[data-persona-anchor-spacer]"
+    );
+    expect(spacer?.style.height).toBe("108px");
+    metrics.setScrollHeight(1108);
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(684);
+
+    // Reply streams in-view (anchor stays on the user message); content grows
+    // but the ResizeObserver drain never fires — the real-browser failure
+    // shape where the growth-driven shrink stops before converging.
+    emitStreamingMessage(controller, "Streaming response");
+    metrics.setScrollHeight(1174);
+
+    // Stream end: the spacer trims to what the held position needs plus the
+    // 24px anti-bounce slack (684 + 400 - 1066 + 24 = 42). The remaining
+    // below-fold air equals the near-bottom threshold, so the
+    // scroll-to-bottom arrow stays hidden.
+    controller.injectTestMessage({ type: "status", status: "idle" });
+    expect(spacer?.style.height).toBe("42px");
+
+    controller.destroy();
+  });
+
+  it("re-pins the anchored message when the hero welcome collapses mid-stream", async () => {
+    // Hero dismissal fades via WAAPI while still occupying layout, then drops
+    // display (and the roomier empty-state body gap) in one frame — after the
+    // anchor ease already scrolled against the old layout. Without a re-pin
+    // the browser clamps scrollTop by the removed height and visibly yanks
+    // the pinned user message.
+    const raf = installRafMock();
+    installResizeObserverMock();
+    let resolveFinished: () => void = () => {};
+    const finished = new Promise<void>((resolve) => {
+      resolveFinished = resolve;
+    });
+    const animate = vi.fn(
+      () => ({ finished, cancel: vi.fn() }) as unknown as Animation
+    );
+    const originalAnimate = (Element.prototype as { animate?: unknown })
+      .animate;
+    (Element.prototype as { animate?: unknown }).animate = animate;
+
+    try {
+      const mount = createMount();
+      const controller = createAgentExperience(mount, {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false },
+        welcome: { variant: "hero" },
+        features: {
+          scrollBehavior: { mode: "anchor-top", anchorTopOffset: 16 }
+        }
+      } as any);
+
+      const scrollContainer = mount.querySelector<HTMLElement>(
+        "#persona-scroll-container"
+      );
+      const metrics = installScrollMetrics(scrollContainer!, {
+        scrollHeight: 1000,
+        clientHeight: 400
+      });
+
+      emitStreamingStatus(controller);
+      emitUserMessage(controller, "user-hero", "Long question");
+
+      const bubble = scrollContainer!.querySelector<HTMLElement>(
+        '[data-message-id="user-hero"]'
+      );
+      expect(bubble).not.toBeNull();
+      Object.defineProperty(bubble!, "offsetTop", {
+        value: 700,
+        configurable: true
+      });
+      raf.step(1);
+      const spacer = scrollContainer!.querySelector<HTMLElement>(
+        "[data-persona-anchor-spacer]"
+      );
+      expect(spacer?.style.height).toBe("108px");
+      metrics.setScrollHeight(1108);
+      raf.flush();
+      expect(metrics.getScrollTop()).toBe(684);
+
+      // The dismiss animation completes: 300px of hero layout leaves in one
+      // frame, shifting the bubble up and shrinking scroll content. The
+      // clamp alone would drop scrollTop to 808 - 400 = 408.
+      Object.defineProperty(bubble!, "offsetTop", {
+        value: 400,
+        configurable: true
+      });
+      metrics.setScrollHeight(808);
+      resolveFinished();
+      await finished;
+      await Promise.resolve();
+
+      // Re-pinned: the bubble rests at the anchor offset again (400 - 16)
+      // with the spacer recomputed for the collapsed layout, not left stale.
+      expect(metrics.getScrollTop()).toBe(384);
+      expect(spacer?.style.height).toBe("108px");
+
+      controller.destroy();
+    } finally {
+      if (originalAnimate === undefined) {
+        delete (Element.prototype as { animate?: unknown }).animate;
+      } else {
+        (Element.prototype as { animate?: unknown }).animate = originalAnimate;
+      }
+    }
+  });
+
+  it("anchor-top hands off to the first unread block only when it starts below the fold", () => {
+    const raf = installRafMock();
+    installResizeObserverMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        scrollBehavior: { mode: "anchor-top", anchorTopOffset: 16 }
+      }
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1600,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitUserMessage(controller, "user-strand", "Very long question");
+    const bubble = scrollContainer!.querySelector<HTMLElement>(
+      '[data-message-id="user-strand"]'
+    );
+    Object.defineProperty(bubble!, "offsetTop", { value: 100 });
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(84);
+
+    // The reply's first block starts 500px below the user message: with the
+    // user message pinned it would sit past the fold (16 + 500 > 400 - 96),
+    // so the anchor hands off to the block: target = 600 - 16 = 584. This is
+    // the stranded case the handoff exists for (tall send / tool prelude).
+    emitStreamingMessage(controller, "Streaming response");
+    const streamBubble = scrollContainer!.querySelector<HTMLElement>(
+      `[data-message-id="${STREAM_MESSAGE_ID}"]`
+    );
+    Object.defineProperty(streamBubble!, "offsetTop", { value: 600 });
+    emitStreamingMessage(controller, "Streaming response, longer");
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(584);
+
+    controller.destroy();
+  });
+
   it("jump-to-latest cancels an in-flight anchor scroll animation", () => {
     const raf = installRafMock();
     const mount = createMount();
@@ -1145,4 +1325,112 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
+  it("keeps a welcome-only transcript at the top on open with no jump affordance", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      persistState: false,
+      launcher: { enabled: true },
+      welcome: { title: "How can we help?" }
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>(
+      "#persona-scroll-container"
+    );
+    // Welcome content slightly taller than the viewport: pre-fix, opening
+    // scrolled to the bottom (clipping the greeting) and the >24px overflow
+    // surfaced the scroll-to-bottom arrow with no messages to jump to.
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 430,
+      clientHeight: 400
+    });
+
+    controller.open();
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(0);
+    const button = getScrollToBottomButton(mount);
+    expect(!button || button.style.display === "none").toBe(true);
+
+    // A real message restores the historical open behavior: land on latest.
+    // Flush first so the inject-time anchor animation settles before reopen.
+    controller.injectUserMessage({ content: "hi" });
+    raf.flush();
+    metrics.setScrollHeight(800);
+    controller.close();
+    controller.open();
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("stamps the on-scroll scrollbar policy and reveals only on reader input", () => {
+    vi.useFakeTimers();
+    installResizeObserverMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    } as any);
+
+    expect(mount.getAttribute("data-persona-scrollbar")).toBe("on-scroll");
+    const scrollContainer = mount.querySelector<HTMLElement>(
+      "#persona-scroll-container"
+    )!;
+    // At rest, and during widget-driven scrolling (which never routes through
+    // markReaderEngaged), the bar stays hidden.
+    expect(scrollContainer.hasAttribute("data-persona-scrollbar-visible")).toBe(
+      false
+    );
+
+    // A wheel tick is reader input: reveal, then hide after the idle delay
+    // because the reader sits at the resting position (jsdom measures the
+    // body as scrolled to the bottom).
+    scrollContainer.dispatchEvent(
+      new WheelEvent("wheel", { deltaY: 5, bubbles: true })
+    );
+    expect(scrollContainer.hasAttribute("data-persona-scrollbar-visible")).toBe(
+      true
+    );
+    vi.advanceTimersByTime(1000);
+    expect(scrollContainer.hasAttribute("data-persona-scrollbar-visible")).toBe(
+      false
+    );
+
+    // Away from the resting position the bar survives the idle delay: it is
+    // the positional affordance while the reader is scrolled up.
+    const metrics = installScrollMetrics(scrollContainer, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+    metrics.setScrollTop(100);
+    scrollContainer.dispatchEvent(
+      new WheelEvent("wheel", { deltaY: -5, bubbles: true })
+    );
+    vi.advanceTimersByTime(1000);
+    expect(scrollContainer.hasAttribute("data-persona-scrollbar-visible")).toBe(
+      true
+    );
+
+    // Switching policy clears the reveal state and restamps the root.
+    controller.update({
+      features: { scrollBehavior: { scrollbar: "hidden" } }
+    });
+    expect(mount.getAttribute("data-persona-scrollbar")).toBe("hidden");
+    expect(scrollContainer.hasAttribute("data-persona-scrollbar-visible")).toBe(
+      false
+    );
+    scrollContainer.dispatchEvent(
+      new WheelEvent("wheel", { deltaY: 5, bubbles: true })
+    );
+    expect(scrollContainer.hasAttribute("data-persona-scrollbar-visible")).toBe(
+      false
+    );
+
+    controller.destroy();
+    vi.useRealTimers();
+  });
+
 });