@runtypelabs/persona 3.30.0 → 3.31.1

package/src/session.test.ts

@@ -894,6 +894,68 @@ describe('AgentWidgetSession.resolveApproval', () => {
   });
 });
 
+describe('AgentWidgetSession - approval context across agent_approval_complete', () => {
+  const sseStream = (events: Array<Record<string, unknown>>): ReadableStream<Uint8Array> => {
+    const encoder = new TextEncoder();
+    const body = events
+      .map((e) => `event: ${e.type}\ndata: ${JSON.stringify(e)}\n\n`)
+      .join('');
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(body));
+        controller.close();
+      },
+    });
+  };
+
+  it('keeps toolName/description/toolType/reason/parameters when the sparse complete event resolves the bubble', async () => {
+    let messages: AgentWidgetMessage[] = [];
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://localhost:8000' },
+      {
+        onMessagesChanged: (m) => { messages = m; },
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onError: () => {},
+      }
+    );
+
+    // `agent_approval_complete` carries only the resolution — none of the
+    // context fields from `agent_approval_start`. The session merge must keep
+    // them so a full re-render of the resolved bubble (morph, virtual-scroll
+    // re-mount, storage restore) still shows the tool, description, and the
+    // agent's stated reason.
+    await session.connectStream(sseStream([
+      {
+        type: 'agent_approval_start',
+        executionId: 'exec_abc',
+        approvalId: 'appr_1',
+        toolName: 'send_email',
+        toolType: 'external',
+        description: 'Send an email to the customer',
+        reason: 'The user asked me to notify the customer.',
+        parameters: { to: 'customer@example.com' },
+      },
+      {
+        type: 'agent_approval_complete',
+        executionId: 'exec_abc',
+        approvalId: 'appr_1',
+        decision: 'approved',
+        resolvedBy: 'user',
+      },
+    ]));
+
+    const bubble = messages.find((m) => m.id === 'approval-appr_1');
+    expect(bubble?.approval?.status).toBe('approved');
+    expect(bubble?.approval?.resolvedAt).toBeDefined();
+    expect(bubble?.approval?.toolName).toBe('send_email');
+    expect(bubble?.approval?.toolType).toBe('external');
+    expect(bubble?.approval?.description).toBe('Send an email to the customer');
+    expect(bubble?.approval?.reason).toBe('The user asked me to notify the customer.');
+    expect(bubble?.approval?.parameters).toEqual({ to: 'customer@example.com' });
+  });
+});
+
 describe('AgentWidgetSession - dispatch error fallback', () => {
   const originalFetch = global.fetch;
 

package/src/session.ts

@@ -2659,6 +2659,33 @@ export class AgentWidgetSession {
           awaitingLocalTool: false,
         };
       }
+      // Approval equivalent: `agent_approval_complete` carries only the
+      // resolution (approvalId, decision, resolvedBy) — the runtime does not
+      // re-send toolName/description/toolType/reason/parameters, so client.ts
+      // rebuilds the approval with empty required fields and the optional
+      // ones absent. A wholesale `approval` replacement would wipe that
+      // context from the resolved bubble on the next full re-render (morph,
+      // virtual-scroll re-mount, storage restore). Merge field-wise instead:
+      // take the resolution from the incoming event, keep existing context
+      // wherever the event is silent or empty.
+      if (
+        existing.approval &&
+        withSequence.approval &&
+        existing.approval.id === withSequence.approval.id
+      ) {
+        const prior = existing.approval;
+        const incoming = withSequence.approval;
+        merged.approval = {
+          ...prior,
+          ...incoming,
+          executionId: incoming.executionId || prior.executionId,
+          toolName: incoming.toolName || prior.toolName,
+          description: incoming.description || prior.description,
+          toolType: incoming.toolType ?? prior.toolType,
+          reason: incoming.reason ?? prior.reason,
+          parameters: incoming.parameters ?? prior.parameters,
+        };
+      }
       // WebMCP equivalent: once a `webmcp:*` tool has started resolving
       // (inflight) or resolved, a duplicate `step_await` re-emit must not
       // flip `awaitingLocalTool` back to true and resurrect the "waiting on

package/src/styles/widget.css

@@ -2616,6 +2616,25 @@
   height: var(--persona-scroll-to-bottom-icon-size, 14px);
 }
 
+/* New-messages count badge pinned to the affordance's top-right corner. */
+[data-persona-root] .persona-scroll-to-bottom-indicator [data-persona-scroll-to-bottom-count] {
+  position: absolute;
+  top: -6px;
+  right: -6px;
+  box-sizing: border-box;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  border-radius: var(--persona-radius-full, 9999px);
+  border: 1px solid var(--persona-scroll-to-bottom-border, var(--persona-primary, #111827));
+  background: var(--persona-scroll-to-bottom-count-bg, var(--persona-surface, #ffffff));
+  color: var(--persona-scroll-to-bottom-count-fg, var(--persona-primary, #111827));
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 16px;
+  text-align: center;
+}
+
 [data-persona-root] .persona-scroll-to-bottom-indicator:hover {
   opacity: 0.92;
 }

package/src/theme-reference.ts

@@ -229,7 +229,7 @@ export const THEME_TOKEN_DOCS = {
       description:
         'Tool approval bubble styling and behavior. Set to false to disable.',
       properties:
-        'backgroundColor, borderColor, titleColor, descriptionColor, approveButtonColor, approveButtonTextColor, denyButtonColor, denyButtonTextColor, parameterBackgroundColor, parameterTextColor, title, approveLabel, denyLabel.',
+        'backgroundColor, borderColor, titleColor, descriptionColor, reasonColor, reasonLabel, approveButtonColor, approveButtonTextColor, denyButtonColor, denyButtonTextColor, parameterBackgroundColor, parameterTextColor, title, approveLabel, denyLabel.',
     },
     copy: {
       description: 'Widget text content.',

package/src/types.ts

@@ -757,6 +757,31 @@ export type AgentWidgetArtifactsFeature = {
   }) => HTMLElement | null;
 };
 
+/**
+ * How the transcript scrolls while an assistant response streams in.
+ *
+ * - `"follow"` (default): keep the newest content pinned to the bottom of the
+ *   viewport, pausing when the user scrolls up and resuming when they return
+ *   to the bottom.
+ * - `"anchor-top"`: on send, scroll the user's message near the top of the
+ *   viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
+ *   way back to the latest content.
+ */
+export type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
+
+export type AgentWidgetScrollBehaviorFeature = {
+  /** Scroll behavior during streamed responses. @default "follow" */
+  mode?: AgentWidgetScrollMode;
+  /**
+   * Gap (px) kept between the anchored user message and the top of the
+   * viewport in `"anchor-top"` mode.
+   * @default 16
+   */
+  anchorTopOffset?: number;
+};
+
 export type AgentWidgetScrollToBottomFeature = {
   /**
    * When true, Persona shows a scroll-to-bottom affordance when the user breaks
@@ -1049,6 +1074,8 @@ export type AgentWidgetFeatureFlags = {
   composerHistory?: boolean;
   /** Shared transcript + event stream scroll-to-bottom affordance. */
   scrollToBottom?: AgentWidgetScrollToBottomFeature;
+  /** Transcript scroll behavior during streamed responses. */
+  scrollBehavior?: AgentWidgetScrollBehaviorFeature;
   /** Collapsed transcript behavior for tool call rows. */
   toolCallDisplay?: AgentWidgetToolCallDisplayFeature;
   /** Collapsed transcript behavior for reasoning rows. */
@@ -1872,6 +1899,16 @@ export type AgentWidgetApprovalConfig = {
   approveLabel?: string;
   /** Label for the deny button */
   denyLabel?: string;
+  /**
+   * Color for the agent-authored reason line (the agent's per-call
+   * justification, shown attributed below the summary when present).
+   */
+  reasonColor?: string;
+  /**
+   * Label prefix for the agent-authored reason line.
+   * Defaults to "Agent's stated reason:".
+   */
+  reasonLabel?: string;
   /**
    * How the technical details (the tool's agent-facing description and the
    * raw parameters JSON) are presented:
@@ -1897,6 +1934,12 @@ export type AgentWidgetApprovalConfig = {
     description: string;
     parameters?: unknown;
     displayTitle?: string;
+    /**
+     * Agent-authored justification for this specific call, when the agent
+     * provided one. It is the agent's own claim — if you fold it into the
+     * summary, keep it attributed to the agent.
+     */
+    reason?: string;
   }) => string | undefined;
   /**
    * Custom handler for approval decisions.
@@ -3856,6 +3899,13 @@ export type AgentWidgetApproval = {
   toolName: string;
   toolType?: string;
   description: string;
+  /**
+   * Agent-authored justification for this specific call (the agent's own
+   * claim about its intent, extracted server-side from the reserved
+   * `_approvalReason` parameter). Render it attributed to the agent and as
+   * plain text — it is approver context, not a system statement.
+   */
+  reason?: string;
   parameters?: unknown;
   resolvedAt?: number;
 };

package/src/ui.scroll.test.ts

@@ -61,6 +61,27 @@ const installRafMock = () => {
   };
 };
 
+const installResizeObserverMock = () => {
+  const triggers: Array<() => void> = [];
+
+  class ResizeObserverMock {
+    constructor(callback: (entries: unknown[], observer: unknown) => void) {
+      triggers.push(() => callback([], this));
+    }
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+
+  vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+
+  return {
+    trigger() {
+      triggers.forEach((fire) => fire());
+    }
+  };
+};
+
 const installScrollMetrics = (
   element: HTMLElement,
   initial: { scrollHeight: number; clientHeight: number }
@@ -123,6 +144,22 @@ const emitStreamingMessage = (
   });
 };
 
+const emitUserMessage = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id: string,
+  content = "Hello"
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "user",
+      content,
+      createdAt: STREAM_CREATED_AT
+    }
+  });
+};
+
 const emitReasoningMessage = (
   controller: ReturnType<typeof createAgentExperience>,
   chunks: string[]
@@ -200,7 +237,12 @@ describe("createAgentExperience streaming scroll", () => {
 
   afterEach(() => {
     document.body.innerHTML = "";
+    // Widgets persist chat history to localStorage by default; without
+    // clearing it, a later widget restores an earlier test's messages at
+    // construction and "new message" assertions see stale ids.
+    localStorage.clear();
     vi.restoreAllMocks();
+    vi.unstubAllGlobals();
   });
 
   it("stops auto-follow after a small upward scroll during streaming", () => {
@@ -744,4 +786,345 @@ describe("createAgentExperience streaming scroll", () => {
     controller.destroy();
   });
 
+  it("re-pins to the bottom when content grows without a render event", () => {
+    const raf = installRafMock();
+    const resize = installResizeObserverMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    // Content grows with no render event (e.g. an image finishing loading
+    // mid-stream) — only the ResizeObserver sees it.
+    metrics.setScrollHeight(1200);
+    resize.trigger();
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("does not yank a paused reader when content grows without a render event", () => {
+    const raf = installRafMock();
+    const resize = installResizeObserverMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -24 }));
+    metrics.setScrollTop(420);
+
+    metrics.setScrollHeight(1200);
+    resize.trigger();
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(420);
+
+    controller.destroy();
+  });
+
+  it("pauses auto-follow while the user selects transcript text during streaming", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    // A selection forms inside the transcript (mouse drag or keyboard —
+    // both surface as selectionchange).
+    let currentSelection: Partial<Selection> | null = {
+      isCollapsed: false,
+      anchorNode: scrollContainer,
+      focusNode: scrollContainer
+    };
+    vi.spyOn(document, "getSelection").mockImplementation(
+      () => currentSelection as Selection | null
+    );
+    document.dispatchEvent(new Event("selectionchange"));
+
+    metrics.setScrollHeight(1100);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    // Auto-follow paused: the selection isn't dragged out from under the user.
+    expect(metrics.getScrollTop()).toBe(600);
+
+    // Drag-selecting toward the bottom edge auto-scrolls down — that must
+    // not read as a resume gesture while the selection is still active.
+    metrics.setScrollTop(metrics.getBottomScrollTop());
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+    const heldPosition = metrics.getScrollTop();
+    metrics.setScrollHeight(1200);
+    emitStreamingMessage(controller, "Third chunk");
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(heldPosition);
+
+    // Once the selection clears, scrolling down near the bottom resumes.
+    currentSelection = null;
+    metrics.setScrollTop(metrics.getBottomScrollTop());
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+    metrics.setScrollHeight(1300);
+    emitStreamingMessage(controller, "Fourth chunk");
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("re-sticks to the bottom when the user sends a message after scrolling up", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -24 }));
+    metrics.setScrollTop(300);
+
+    emitUserMessage(controller, "user-resend", "Follow-up question");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("shows a count badge for messages that arrive while paused", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false }
+    });
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    raf.flush();
+
+    scrollContainer!.dispatchEvent(new WheelEvent("wheel", { deltaY: -24 }));
+    metrics.setScrollTop(300);
+
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "ast-while-paused",
+        role: "assistant",
+        content: "Another answer",
+        createdAt: STREAM_CREATED_AT
+      }
+    });
+    raf.flush();
+
+    const badge = mount.querySelector<HTMLElement>(
+      "[data-persona-scroll-to-bottom-count]"
+    );
+    expect(badge?.textContent).toBe("1");
+    expect(badge?.style.display).not.toBe("none");
+
+    // Jumping back to the latest clears the count.
+    getScrollToBottomButton(mount)!.click();
+    raf.flush();
+    expect(badge?.textContent).toBe("");
+    expect(badge?.style.display).toBe("none");
+
+    controller.destroy();
+  });
+
+  it("anchor-top mode pins the sent user message near the viewport top and never follows the stream", () => {
+    const raf = installRafMock();
+    const resize = 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-anchor", "Long question");
+
+    // Give the rendered bubble layout geometry before the anchor rAF runs.
+    const bubble = scrollContainer!.querySelector<HTMLElement>(
+      '[data-message-id="user-anchor"]'
+    );
+    expect(bubble).not.toBeNull();
+    Object.defineProperty(bubble!, "offsetTop", { value: 700 });
+
+    // 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.
+    const spacer = scrollContainer!.querySelector<HTMLElement>(
+      "[data-persona-anchor-spacer]"
+    );
+    expect(spacer?.style.height).toBe("84px");
+
+    // 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);
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(684);
+
+    // Streaming below the anchor never moves the viewport.
+    metrics.setScrollHeight(1150);
+    emitStreamingMessage(controller, "Streaming response");
+    raf.flush();
+    expect(metrics.getScrollTop()).toBe(684);
+
+    // As real content grows, the spacer gives room back (shrink-only):
+    // content grew from 1000 to 1150 - 84 = 1066, so spacer 84 - 66 = 18.
+    resize.trigger();
+    expect(spacer?.style.height).toBe("18px");
+
+    // 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(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("jump-to-latest cancels an in-flight anchor scroll animation", () => {
+    const raf = installRafMock();
+    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-anchor-cancel", "Question");
+
+    // Anchor target (484) is reachable without a spacer, and differs from
+    // the bottom (600) so a stale animation is distinguishable.
+    const bubble = scrollContainer!.querySelector<HTMLElement>(
+      '[data-message-id="user-anchor-cancel"]'
+    );
+    Object.defineProperty(bubble!, "offsetTop", { value: 500 });
+
+    raf.step(1); // anchor frame: starts the scroll animation
+    raf.step(1); // first animation frame — animation now in flight
+
+    // Jump to the latest mid-animation: the stale anchor animation must not
+    // keep easing scrollTop back toward the old target.
+    getScrollToBottomButton(mount)!.click();
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
+
+    controller.destroy();
+  });
+
+  it("scroll mode none never auto-scrolls during streaming", () => {
+    const raf = installRafMock();
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        scrollBehavior: { mode: "none" }
+      }
+    } as any);
+
+    const scrollContainer = mount.querySelector<HTMLElement>("#persona-scroll-container");
+    const metrics = installScrollMetrics(scrollContainer!, {
+      scrollHeight: 1000,
+      clientHeight: 400
+    });
+
+    emitStreamingStatus(controller);
+    emitStreamingMessage(controller, "First chunk");
+    metrics.setScrollHeight(1200);
+    emitStreamingMessage(controller, "Second chunk");
+    raf.flush();
+
+    expect(metrics.getScrollTop()).toBe(0);
+
+    // The affordance is still available to get back to the latest content,
+    // and messages that arrived while away from the bottom are counted.
+    scrollContainer!.dispatchEvent(new Event("scroll"));
+    expect(getScrollToBottomButton(mount)?.style.display).not.toBe("none");
+    const badge = mount.querySelector<HTMLElement>(
+      "[data-persona-scroll-to-bottom-count]"
+    );
+    expect(badge?.textContent).toBe("1");
+
+    controller.destroy();
+  });
+
 });