@runtypelabs/persona 3.29.1 → 3.31.0

package/src/theme-editor/preview-utils.ts

@@ -206,7 +206,8 @@ export type PreviewTranscriptEntryPreset =
   | 'reasoning-streaming'
   | 'reasoning-complete'
   | 'tool-running'
-  | 'tool-complete';
+  | 'tool-complete'
+  | 'approval-request';
 
 const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, string> = {
   'user-message': 'User message',
@@ -218,6 +219,7 @@ const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, str
   'reasoning-complete': 'Reasoning (complete)',
   'tool-running': 'Tool call (running)',
   'tool-complete': 'Tool call (complete)',
+  'approval-request': 'Approval request',
 };
 
 export function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string {
@@ -325,6 +327,32 @@ export function createPreviewTranscriptEntry(
           durationMs: 1200,
         },
       };
+    case 'approval-request': {
+      // Use the `approval-<approvalId>` id convention so the optimistic status
+      // flip in `session.resolveApproval` updates this bubble in place when the
+      // Approve/Deny buttons are clicked.
+      const approvalId = `preview-approval-${suffix}`;
+      return {
+        id: `approval-${approvalId}`,
+        role: 'assistant',
+        content: '',
+        createdAt,
+        streaming: false,
+        variant: 'approval',
+        approval: {
+          id: approvalId,
+          status: 'pending',
+          agentId: 'preview-agent',
+          executionId: `preview-exec-${suffix}`,
+          toolName: 'add_to_cart',
+          description:
+            'Add the selected item to the shopping cart. Approve to let the assistant continue.',
+          parameters: {
+            items: [{ productEntityId: 129, quantity: 1 }],
+          },
+        },
+      };
+    }
     case 'tool-complete':
       return {
         id: `preview-seq-tool-complete-${suffix}`,

package/src/theme-editor/sections.test.ts

@@ -27,6 +27,23 @@ describe("theme editor scroll-to-bottom controls", () => {
     expect(fieldPaths).toContain("theme.components.scrollToBottom.iconSize");
   });
 
+  it("exposes a shadow control for every themeable component", () => {
+    const fieldPaths = COMPONENTS_SECTIONS.flatMap((section) => section.fields.map((field) => field.path));
+
+    // Pre-existing shadow controls.
+    expect(fieldPaths).toContain("theme.components.launcher.shadow");
+    expect(fieldPaths).toContain("theme.components.panel.shadow");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.shadow");
+    // Newly added component shadow controls.
+    expect(fieldPaths).toContain("theme.components.message.user.shadow");
+    expect(fieldPaths).toContain("theme.components.message.assistant.shadow");
+    expect(fieldPaths).toContain("theme.components.toolBubble.shadow");
+    expect(fieldPaths).toContain("theme.components.reasoningBubble.shadow");
+    expect(fieldPaths).toContain("theme.components.approval.requested.shadow");
+    expect(fieldPaths).toContain("theme.components.introCard.shadow");
+    expect(fieldPaths).toContain("theme.components.composer.shadow");
+  });
+
   it("adds a scroll-to-bottom interface role mapping", () => {
     const role = ALL_ROLES.find((entry) => entry.roleId === "role-scroll-to-bottom");
 

package/src/theme-editor/sections.ts

@@ -455,6 +455,36 @@ const scrollToBottomSectionDef: SectionDef = {
   ],
 };
 
+// Reusable shadow-scale options matching the launcher / panel / scroll-to-bottom selects.
+const SHADOW_SCALE_OPTIONS: { value: string; label: string }[] = [
+  { value: 'palette.shadows.none', label: 'None' },
+  { value: 'palette.shadows.sm', label: 'Small' },
+  { value: 'palette.shadows.md', label: 'Medium' },
+  { value: 'palette.shadows.lg', label: 'Large' },
+  { value: 'palette.shadows.xl', label: 'Extra Large' },
+];
+
+// The approval and intro-card defaults are a bespoke "card" shadow rather than a
+// palette step, so expose it as a leading "Default" option users can keep.
+const CARD_SHADOW = '0 5px 15px rgba(15, 23, 42, 0.08)';
+const CARD_SHADOW_OPTIONS = [{ value: CARD_SHADOW, label: 'Default' }, ...SHADOW_SCALE_OPTIONS];
+
+const componentShadowsSectionDef: SectionDef = {
+  id: 'comp-shadows',
+  title: 'Component Shadows',
+  description: 'Box-shadow for chat bubbles and surfaces.',
+  collapsed: true,
+  fields: [
+    { id: 'shadow-msg-user', label: 'User Message', type: 'select', path: 'theme.components.message.user.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-msg-assistant', label: 'Assistant Message', type: 'select', path: 'theme.components.message.assistant.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-tool-bubble', label: 'Tool Call Bubble', type: 'select', path: 'theme.components.toolBubble.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-reasoning-bubble', label: 'Reasoning Bubble', type: 'select', path: 'theme.components.reasoningBubble.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-approval', label: 'Approval Bubble', type: 'select', path: 'theme.components.approval.requested.shadow', defaultValue: CARD_SHADOW, options: CARD_SHADOW_OPTIONS },
+    { id: 'shadow-intro-card', label: 'Intro Card', type: 'select', path: 'theme.components.introCard.shadow', defaultValue: CARD_SHADOW, options: CARD_SHADOW_OPTIONS },
+    { id: 'shadow-composer', label: 'Composer', type: 'select', path: 'theme.components.composer.shadow', defaultValue: 'palette.shadows.none', options: SHADOW_SCALE_OPTIONS },
+  ],
+};
+
 /** Shared shape sections (not scoped to light/dark) */
 export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   panelLayoutSectionDef,
@@ -462,6 +492,7 @@ export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   messageShapeSectionDef,
   inputShapeSectionDef,
   buttonShapeSectionDef,
+  componentShadowsSectionDef,
 ];
 
 /** Component color sections (can be scoped for light/dark) */

package/src/theme-reference.ts

@@ -136,7 +136,7 @@ export const THEME_TOKEN_DOCS = {
       voice:
         'recording (indicator, background, border), processing (icon, background), speaking (icon).',
       approval:
-        'requested (background, border, text), approve (background, foreground), deny (background, foreground).',
+        'requested (background, border, text, shadow), approve (background, foreground), deny (background, foreground).',
       attachment: 'image (background, border).',
       scrollToBottom:
         'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
@@ -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/theme.ts

@@ -330,6 +330,8 @@ export interface ApprovalTokens {
     background: TokenReference<'color'>;
     border: TokenReference<'color'>;
     text: TokenReference<'color'>;
+    /** Box-shadow for the approval bubble (token ref or raw CSS, e.g. `none`). */
+    shadow: string;
   };
   approve: ComponentTokenSet;
   deny: ComponentTokenSet;

package/src/types.ts

@@ -255,6 +255,12 @@ export type WebMcpConfirmInfo = {
   toolName: string;
   args: unknown;
   description?: string;
+  /**
+   * Display title the tool declared via the WebMCP spec's
+   * `ToolDescriptor.title` (e.g. `"Add to Cart"`). Absent when the tool
+   * didn't declare one.
+   */
+  title?: string;
   annotations?: {
     readOnlyHint?: boolean;
     untrustedContentHint?: boolean;
@@ -751,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
@@ -1043,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. */
@@ -1816,6 +1849,23 @@ export interface VoiceProvider {
   stopPlayback?(): void;
 }
 
+/**
+ * Extra context for an approval decision, surfaced to `onDecision` and to the
+ * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.
+ */
+export type AgentWidgetApprovalDecisionOptions = {
+  /**
+   * The user chose a "remember this" affordance (e.g. an "Always allow"
+   * button) rather than a one-time decision. The widget resolves the *current*
+   * approval identically whether or not this is set — an approval bubble is a
+   * single binary gate (`approved`/`denied`). Persisting a don't-ask-again
+   * policy for *future* approvals (auto-resolving them, or not surfacing them)
+   * is the integrator's responsibility, typically inside `onDecision`.
+   * Defaults to absent/`false`.
+   */
+  remember?: boolean;
+};
+
 /**
  * Configuration for tool approval bubbles.
  * Controls styling, labels, and behavior of the approval UI.
@@ -1825,6 +1875,8 @@ export type AgentWidgetApprovalConfig = {
   backgroundColor?: string;
   /** Border color of the approval bubble */
   borderColor?: string;
+  /** Box-shadow for the approval bubble; pass `"none"` to remove it. Overrides the default `persona-shadow-sm`. */
+  shadow?: string;
   /** Color for the title text */
   titleColor?: string;
   /** Color for the description text */
@@ -1847,19 +1899,67 @@ 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:
+   * - `"collapsed"` (default) — hidden behind a "Show details" toggle
+   * - `"expanded"` — visible, with the toggle available to hide them
+   * - `"hidden"` — never rendered
+   */
+  detailsDisplay?: "collapsed" | "expanded" | "hidden";
+  /** Label for the toggle that reveals the technical details */
+  showDetailsLabel?: string;
+  /** Label for the toggle that hides the technical details */
+  hideDetailsLabel?: string;
+  /**
+   * Build the user-facing summary line for an approval request. Overrides the
+   * default "The assistant wants to use “Tool name”." copy. Return a falsy
+   * value to fall back to the default for that approval. `displayTitle` is
+   * the display name the tool declared via the WebMCP spec's
+   * `ToolDescriptor.title`, when one exists.
+   */
+  formatDescription?: (approval: {
+    toolName: string;
+    toolType?: string;
+    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.
    * Return void to let the SDK auto-resolve via the API,
    * or return a Response/ReadableStream for custom handling.
+   *
+   * `options.remember` is `true` when the decision came from a "remember this"
+   * affordance (e.g. an "Always allow" button in a custom `renderApproval`
+   * plugin). Use it to persist a don't-ask-again policy for future approvals;
+   * the current approval resolves the same way regardless.
    */
   onDecision?: (
     data: { approvalId: string; executionId: string; agentId: string; toolName: string },
-    decision: 'approved' | 'denied'
+    decision: 'approved' | 'denied',
+    options?: AgentWidgetApprovalDecisionOptions
   ) => Promise<Response | ReadableStream<Uint8Array> | void>;
 };
 
 export type AgentWidgetToolCallConfig = {
-  /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
+  /** Box-shadow for tool-call bubbles; pass `"none"` to remove it. Overrides the `components.toolBubble.shadow` token / `--persona-tool-bubble-shadow`. */
   shadow?: string;
   /** Background color of the tool call bubble container. */
   backgroundColor?: string;
@@ -3799,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.approval-plugin.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import type { AgentWidgetPlugin } from "./plugins/types";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const injectApproval = (
+  controller: ReturnType<typeof createAgentExperience>,
+  {
+    id = "appr-1",
+    status = "pending" as "pending" | "approved" | "denied",
+  } = {}
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id: `approval-${id}`,
+      role: "assistant",
+      content: "",
+      createdAt: "2026-04-24T00:00:00.000Z",
+      streaming: false,
+      variant: "approval",
+      approval: {
+        id,
+        status,
+        agentId: "agent_1",
+        executionId: "exec_1",
+        toolName: "Search documentation",
+        description: "Search the docs",
+        parameters: { query: "approval theming" },
+      },
+    },
+  });
+};
+
+const injectNoise = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id = "noise"
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "user",
+      content: "noise",
+      createdAt: "2026-04-26T00:00:00.000Z",
+      streaming: false,
+    },
+  });
+};
+
+describe("renderApproval plugin hook", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("renders a plugin-returned element in place of the built-in bubble", () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "custom-approval",
+      renderApproval: ({ message }) => {
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "custom-approval");
+        root.textContent = message.approval?.toolName ?? "";
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    injectApproval(controller);
+
+    const custom = mount.querySelector('[data-test-id="custom-approval"]');
+    expect(custom).not.toBeNull();
+    expect(custom?.textContent).toBe("Search documentation");
+    // The built-in bubble must NOT also render.
+    expect(mount.querySelector(".persona-approval-bubble")).toBeNull();
+  });
+
+  it("preserves plugin click listeners (e.g. an accordion) across morph re-renders", () => {
+    const toggleSpy = vi.fn();
+    const plugin: AgentWidgetPlugin = {
+      id: "accordion-approval",
+      renderApproval: ({ message }) => {
+        if (message.approval?.status !== "pending") return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "appr-root");
+        const head = document.createElement("button");
+        head.type = "button";
+        head.setAttribute("data-test-id", "appr-head");
+        head.setAttribute("data-action", "toggle");
+        const params = document.createElement("pre");
+        params.setAttribute("data-test-id", "appr-params");
+        // Single delegated listener at the root — the recommended pattern.
+        root.addEventListener("click", (e) => {
+          const target = (e.target as HTMLElement).closest("[data-action]");
+          if (target?.getAttribute("data-action") === "toggle") {
+            params.hidden = !params.hidden;
+            toggleSpy();
+          }
+        });
+        root.append(head, params);
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    injectApproval(controller);
+    // Force a re-render — the scenario where innerHTML morph drops listeners
+    // on a freshly-built plugin element unless it's hydrated post-morph.
+    injectNoise(controller);
+
+    const head = mount.querySelector<HTMLButtonElement>('[data-test-id="appr-head"]');
+    const params = mount.querySelector<HTMLPreElement>('[data-test-id="appr-params"]');
+    expect(head).not.toBeNull();
+    expect(params).not.toBeNull();
+
+    head!.click();
+    expect(toggleSpy).toHaveBeenCalledTimes(1);
+    expect(params!.hidden).toBe(true);
+  });
+
+  it("resolves via the approve callback (with the remember option)", async () => {
+    const onDecision = vi.fn(async () => {});
+    const plugin: AgentWidgetPlugin = {
+      id: "approve-callback",
+      renderApproval: ({ message, approve }) => {
+        if (message.approval?.status !== "pending") return null;
+        const root = document.createElement("div");
+        const btn = document.createElement("button");
+        btn.setAttribute("data-test-id", "always-allow");
+        btn.addEventListener("click", () => approve({ remember: true }));
+        root.appendChild(btn);
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      approval: { onDecision },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    injectApproval(controller);
+    injectNoise(controller);
+
+    const btn = mount.querySelector<HTMLButtonElement>('[data-test-id="always-allow"]');
+    expect(btn).not.toBeNull();
+    btn!.click();
+
+    await Promise.resolve();
+    expect(onDecision).toHaveBeenCalledWith(
+      expect.objectContaining({ toolName: "Search documentation" }),
+      "approved",
+      { remember: true }
+    );
+  });
+
+  it("falls through to the built-in bubble when the plugin returns null (resolved state)", () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "pending-only-approval",
+      renderApproval: ({ message }) => {
+        if (message.approval?.status !== "pending") return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "custom-pending");
+        return root;
+      },
+    };
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      plugins: [plugin],
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    // Inject directly in the resolved state — plugin opts out, built-in renders.
+    injectApproval(controller, { status: "approved" });
+
+    expect(mount.querySelector('[data-test-id="custom-pending"]')).toBeNull();
+    expect(mount.querySelector(".persona-approval-bubble")).not.toBeNull();
+  });
+});