@runtypelabs/persona 3.29.1 → 3.30.0

package/src/plugin-kit.ts

@@ -0,0 +1,294 @@
+// Plugin Kit — small, dependency-free utilities for authoring Persona plugins.
+//
+// Plugin render hooks (`renderApproval`, `renderAskUserQuestion`, `renderMessage`,
+// …) return a detached `HTMLElement` that the widget morphs into the transcript.
+// Two needs come up again and again when that element is more than static markup:
+//
+//   1. Injecting the plugin's own CSS so it survives the widget's Shadow-DOM mode
+//      (a plain `document.head` <style> does NOT pierce a shadow root).
+//   2. Floating UI — dropdowns, menus, tooltips — that must overlay the rest of
+//      the widget and not be clipped by the transcript's scroll container.
+//
+// Both are easy to get subtly wrong, so they live here as a supported, optional
+// subpath: `@runtypelabs/persona/plugin-kit`. Importing it costs nothing unless
+// you use it, and nothing here touches the widget's core bundle.
+//
+// ```ts
+// import { injectStyles, createPopover, isEditableEventTarget } from
+//   "@runtypelabs/persona/plugin-kit";
+// ```
+
+/* ============================================================
+   Shadow-safe style injection
+   ============================================================ */
+
+/**
+ * Resolve the root a node's styles should live in.
+ *
+ * Returns the node's `ShadowRoot` when it (or an ancestor) is shadowed, the
+ * owning `Document` otherwise. A `<style>` placed in this root reaches the node
+ * regardless of whether the widget runs in light or shadow DOM. For a detached
+ * node (one not yet mounted) this falls back to the owning document.
+ */
+export function getStyleRoot(node: Node): Document | ShadowRoot {
+  const root = node.getRootNode?.();
+  if (root instanceof ShadowRoot) return root;
+  if (root instanceof Document) return root;
+  return node.ownerDocument ?? document;
+}
+
+function injectInto(root: Document | ShadowRoot, id: string, css: string): void {
+  const container: Document | ShadowRoot | HTMLHeadElement =
+    root instanceof Document ? root.head : root;
+  const escaped = id.replace(/["\\]/g, "\\$&");
+  if (container.querySelector(`style[data-persona-plugin-style="${escaped}"]`)) {
+    return; // Already present in this root — idempotent.
+  }
+  const doc = root instanceof Document ? root : root.ownerDocument ?? document;
+  const style = doc.createElement("style");
+  style.setAttribute("data-persona-plugin-style", id);
+  style.textContent = css;
+  container.appendChild(style);
+}
+
+/**
+ * Inject a plugin's CSS once into the correct root — the widget's shadow root
+ * when shadowed, the document head otherwise. Idempotent: keyed by `id`, so it
+ * is safe to call on every render.
+ *
+ * Pass the element you're about to return from a render hook. While building, an
+ * element is detached and its eventual root is unknown, so this injects into the
+ * owning document immediately (covering the default light-DOM case with no
+ * flash) and then, on the next microtask — after the widget has mounted the
+ * element — re-resolves and also injects into its shadow root if it landed in
+ * one. You may also pass an explicit `Document` or `ShadowRoot`.
+ *
+ * @example
+ * ```ts
+ * renderApproval: ({ message, approve, deny }) => {
+ *   const card = buildCard(message.approval, approve, deny);
+ *   injectStyles(card, "my-approval-plugin", CSS);
+ *   return card;
+ * }
+ * ```
+ */
+export function injectStyles(
+  target: Node | Document | ShadowRoot,
+  id: string,
+  css: string
+): void {
+  if (target instanceof Document || target instanceof ShadowRoot) {
+    injectInto(target, id, css);
+    return;
+  }
+  const node = target;
+  if (node.isConnected) {
+    injectInto(getStyleRoot(node), id, css);
+    return;
+  }
+  // Detached (built but not yet mounted): inject into the owning document now,
+  // then re-resolve after mount so shadow-DOM widgets also get the <style>.
+  const doc = node.ownerDocument ?? document;
+  injectInto(doc, id, css);
+  queueMicrotask(() => {
+    const root = getStyleRoot(node);
+    if (root !== doc) injectInto(root, id, css);
+  });
+}
+
+/* ============================================================
+   Floating popover
+   ============================================================ */
+
+export type PopoverPlacement =
+  | "bottom-start"
+  | "bottom-end"
+  | "top-start"
+  | "top-end";
+
+export interface PopoverOptions {
+  /** Element the popover is positioned against. */
+  anchor: HTMLElement;
+  /** The floating element (menu, tooltip, panel). Built detached; mounted on `open`. */
+  content: HTMLElement;
+  /** Where to place `content` relative to `anchor`. Default `"bottom-start"`. */
+  placement?: PopoverPlacement;
+  /** Gap in px between anchor and content. Default `6`. */
+  offset?: number;
+  /** Set `content`'s `min-width` to the anchor's width. Default `false`. */
+  matchAnchorWidth?: boolean;
+  /**
+   * Inline `z-index` for `content`. Default `2147483000` so it overlays the rest
+   * of the widget. Pass `null` to leave z-index to your own CSS.
+   */
+  zIndex?: number | null;
+  /**
+   * Where to mount `content`. Defaults to the anchor's shadow root (when
+   * shadowed) or `document.body` — keeping it inside the same style + stacking
+   * scope as the anchor while escaping the transcript's scroll clipping.
+   */
+  container?: HTMLElement | ShadowRoot;
+  onOpen?: () => void;
+  /** Fired when the popover closes by itself (outside click or the anchor leaving the DOM). */
+  onDismiss?: (reason: "outside" | "anchor-removed") => void;
+}
+
+export interface PopoverHandle {
+  readonly isOpen: boolean;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  /** Recompute position from the current anchor rect (called automatically on scroll/resize). */
+  reposition(): void;
+  /** Close and release all listeners; the handle is inert afterward. */
+  destroy(): void;
+}
+
+function defaultContainer(anchor: HTMLElement): HTMLElement | ShadowRoot {
+  const root = anchor.getRootNode?.();
+  if (root instanceof ShadowRoot) return root;
+  return (anchor.ownerDocument ?? document).body;
+}
+
+/**
+ * A floating popover anchored to an element: `fixed`-positioned (so it overlays
+ * the rest of the widget and isn't clipped by scroll containers), dismissed on
+ * outside pointerdown, repositioned on scroll/resize, and auto-closed if the
+ * anchor leaves the DOM. Mount your styles with {@link injectStyles}.
+ *
+ * @example
+ * ```ts
+ * const popover = createPopover({
+ *   anchor: splitButton,
+ *   content: menu,
+ *   placement: "bottom-start",
+ *   matchAnchorWidth: true,
+ * });
+ * caret.addEventListener("click", () => popover.toggle());
+ * // on teardown: popover.destroy();
+ * ```
+ */
+export function createPopover(options: PopoverOptions): PopoverHandle {
+  const {
+    anchor,
+    content,
+    placement = "bottom-start",
+    offset = 6,
+    matchAnchorWidth = false,
+    zIndex = 2147483000,
+    onOpen,
+    onDismiss,
+  } = options;
+
+  const container = options.container ?? defaultContainer(anchor);
+  let open = false;
+  let detach: (() => void) | null = null;
+
+  const reposition = (): void => {
+    if (!open) return;
+    const rect = anchor.getBoundingClientRect();
+    content.style.position = "fixed";
+    if (matchAnchorWidth) content.style.minWidth = `${rect.width}px`;
+
+    const top =
+      placement === "top-start" || placement === "top-end"
+        ? rect.top - offset - content.getBoundingClientRect().height
+        : rect.bottom + offset;
+
+    const left =
+      placement === "bottom-end" || placement === "top-end"
+        ? rect.right - content.getBoundingClientRect().width
+        : rect.left;
+
+    content.style.top = `${top}px`;
+    content.style.left = `${left}px`;
+  };
+
+  const close = (): void => {
+    if (!open) return;
+    open = false;
+    if (detach) {
+      detach();
+      detach = null;
+    }
+    content.remove();
+  };
+
+  const doOpen = (): void => {
+    if (open) return;
+    open = true;
+    if (zIndex != null) content.style.zIndex = String(zIndex);
+    container.appendChild(content);
+    reposition();
+
+    const ownerWindow = (anchor.ownerDocument ?? document).defaultView ?? window;
+    const ownerDocument = anchor.ownerDocument ?? document;
+
+    const onReposition = (): void => {
+      if (!anchor.isConnected) {
+        close();
+        onDismiss?.("anchor-removed");
+        return;
+      }
+      reposition();
+    };
+    const onOutside = (event: Event): void => {
+      const path =
+        typeof event.composedPath === "function" ? event.composedPath() : [];
+      if (path.includes(content) || path.includes(anchor)) return;
+      close();
+      onDismiss?.("outside");
+    };
+
+    // Defer arming so the click that opened the popover doesn't dismiss it.
+    const armId = ownerWindow.setTimeout(() => {
+      ownerDocument.addEventListener("pointerdown", onOutside, true);
+    }, 0);
+    ownerWindow.addEventListener("scroll", onReposition, true);
+    ownerWindow.addEventListener("resize", onReposition);
+
+    detach = () => {
+      ownerWindow.clearTimeout(armId);
+      ownerDocument.removeEventListener("pointerdown", onOutside, true);
+      ownerWindow.removeEventListener("scroll", onReposition, true);
+      ownerWindow.removeEventListener("resize", onReposition);
+    };
+
+    onOpen?.();
+  };
+
+  return {
+    get isOpen() {
+      return open;
+    },
+    open: doOpen,
+    close,
+    toggle: () => (open ? close() : doOpen()),
+    reposition,
+    destroy: close,
+  };
+}
+
+/* ============================================================
+   Keyboard helpers
+   ============================================================ */
+
+/**
+ * Whether an event originated from an editable element (`<input>`, `<textarea>`,
+ * or `contenteditable`). Use it to avoid hijacking keys like Enter/Escape while
+ * the user is typing in the composer.
+ *
+ * Inspects the composed path, so it works for events that cross the widget's
+ * Shadow-DOM boundary (where `event.target` is retargeted to the host).
+ */
+export function isEditableEventTarget(event: Event): boolean {
+  const path =
+    typeof event.composedPath === "function" ? event.composedPath() : [];
+  return path.some(
+    (el) =>
+      el instanceof HTMLElement &&
+      (el.tagName === "INPUT" ||
+        el.tagName === "TEXTAREA" ||
+        el.isContentEditable)
+  );
+}

package/src/plugins/types.ts

@@ -1,6 +1,7 @@
 import {
   AgentWidgetMessage,
   AgentWidgetConfig,
+  AgentWidgetApprovalDecisionOptions,
   AskUserQuestionPayload,
   LoadingIndicatorRenderContext,
   IdleIndicatorRenderContext,
@@ -165,13 +166,59 @@ export interface AgentWidgetPlugin {
   }) => HTMLElement | null;
 
   /**
-   * Custom renderer for approval bubbles
-   * Return null to use default renderer
+   * Custom renderer for approval bubbles.
+   *
+   * Return an `HTMLElement` to fully own the approval UI, `defaultRenderer()`
+   * to render (or wrap) the built-in bubble, or `null` to fall through to the
+   * default. Unlike the built-in bubble — whose Approve/Deny buttons are wired
+   * via delegation — a fully custom element resolves the approval by calling
+   * the `approve`/`deny` callbacks. Both route through the same path the
+   * built-in buttons use (optimistic update, `onDecision`, in-place anchoring).
+   *
+   * An approval is a single binary gate, so there are exactly two outcomes.
+   * Pass `{ remember: true }` to flag a "remember this" affordance (e.g. an
+   * "Always allow" button); the current approval resolves identically, but the
+   * flag is forwarded to `config.approval.onDecision` so you can persist a
+   * don't-ask-again policy for future approvals.
+   *
+   * `renderApproval` is called again whenever the approval's status changes, so
+   * branch on `message.approval?.status` to render the resolved state (and tear
+   * down any global listeners you added while pending).
+   *
+   * @example
+   * ```typescript
+   * // An alternative prompt: "Always allow" / "Allow once" / "Deny".
+   * renderApproval: ({ message, approve, deny }) => {
+   *   const approval = message.approval;
+   *   if (!approval || approval.status !== "pending") return null; // default renders resolved state
+   *   const root = document.createElement("div");
+   *   root.textContent = `${approval.toolName} requires approval`;
+   *
+   *   const always = document.createElement("button");
+   *   always.textContent = "Always allow";
+   *   always.addEventListener("click", () => approve({ remember: true }));
+   *
+   *   const once = document.createElement("button");
+   *   once.textContent = "Allow once";
+   *   once.addEventListener("click", () => approve());
+   *
+   *   const no = document.createElement("button");
+   *   no.textContent = "Deny";
+   *   no.addEventListener("click", () => deny());
+   *
+   *   root.append(always, once, no);
+   *   return root;
+   * }
+   * ```
    */
   renderApproval?: (context: {
     message: AgentWidgetMessage;
     defaultRenderer: () => HTMLElement;
     config: AgentWidgetConfig;
+    /** Resolve this approval as approved. Pass `{ remember: true }` for an "Always allow" affordance. */
+    approve: (options?: AgentWidgetApprovalDecisionOptions) => void;
+    /** Resolve this approval as denied. Pass `{ remember: true }` for an "Always deny" affordance. */
+    deny: (options?: AgentWidgetApprovalDecisionOptions) => void;
   }) => HTMLElement | null;
 
   /**

package/src/session.test.ts

@@ -793,6 +793,105 @@ describe('AgentWidgetSession.resolveApproval', () => {
     expect(session.isStreaming()).toBe(false);
     expect(errors.length).toBe(1);
   });
+
+  it('keeps a resolved approval anchored in its original transcript position', async () => {
+    const earlier = new Date('2020-01-01T00:00:00.000Z').toISOString();
+    const later = new Date('2020-01-01T00:05:00.000Z').toISOString();
+    const approval = makeApproval();
+    // The bubble id follows the `approval-<approval.id>` convention used by
+    // resolveApproval's optimistic upsert.
+    const messageId = `approval-${approval.id}`;
+
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:43111/api/chat/dispatch',
+        // Resolve locally (return void) so no network round-trip is needed.
+        approval: { onDecision: async () => {} },
+        initialMessages: [
+          {
+            id: messageId,
+            role: 'assistant',
+            content: '',
+            createdAt: earlier,
+            variant: 'approval',
+            approval,
+          },
+          {
+            id: 'after-1',
+            role: 'assistant',
+            content: 'A message created after the approval was requested.',
+            createdAt: later,
+          },
+        ],
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    await session.resolveApproval(approval, 'approved');
+
+    const messages = session.getMessages();
+    const approvalMsg = messages.find((m) => m.id === messageId);
+    const approvalIdx = messages.findIndex((m) => m.id === messageId);
+    const afterIdx = messages.findIndex((m) => m.id === 'after-1');
+
+    expect(approvalMsg?.approval?.status).toBe('approved');
+    // createdAt is preserved (not re-stamped to "now"), so the resolved bubble
+    // stays before the message that was created after it.
+    expect(approvalMsg?.createdAt).toBe(earlier);
+    expect(approvalIdx).toBeGreaterThanOrEqual(0);
+    expect(approvalIdx).toBeLessThan(afterIdx);
+  });
+
+  it('forwards the decision options (e.g. remember) to onDecision', async () => {
+    const onDecision = vi.fn(async () => {});
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:43111/api/chat/dispatch',
+        approval: { onDecision },
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    await session.resolveApproval(makeApproval(), 'approved', { remember: true });
+
+    expect(onDecision).toHaveBeenCalledTimes(1);
+    expect(onDecision).toHaveBeenCalledWith(
+      expect.objectContaining({ toolName: 'send_email', approvalId: 'approval-1' }),
+      'approved',
+      { remember: true }
+    );
+  });
+
+  it('passes undefined options to onDecision when none are given', async () => {
+    const onDecision = vi.fn(async () => {});
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:43111/api/chat/dispatch',
+        approval: { onDecision },
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    await session.resolveApproval(makeApproval(), 'denied');
+
+    expect(onDecision).toHaveBeenCalledWith(
+      expect.objectContaining({ toolName: 'send_email' }),
+      'denied',
+      undefined
+    );
+  });
 });
 
 describe('AgentWidgetSession - dispatch error fallback', () => {

package/src/session.ts

@@ -5,6 +5,7 @@ import {
   AgentWidgetEvent,
   AgentWidgetMessage,
   AgentWidgetApproval,
+  AgentWidgetApprovalDecisionOptions,
   WebMcpConfirmInfo,
   AgentExecutionState,
   ClientSession,
@@ -1196,7 +1197,8 @@ export class AgentWidgetSession {
    */
   public async resolveApproval(
     approval: AgentWidgetApproval,
-    decision: 'approved' | 'denied'
+    decision: 'approved' | 'denied',
+    options?: AgentWidgetApprovalDecisionOptions
   ): Promise<void> {
     // 1. Update approval message status immediately for responsive UI
     const approvalMessageId = `approval-${approval.id}`;
@@ -1205,11 +1207,19 @@ export class AgentWidgetSession {
       status: decision,
       resolvedAt: Date.now(),
     };
+    // Anchor the bubble where the agent paused for permission. An approval is a
+    // timeline checkpoint, not a "now" event, so resolving it must preserve the
+    // original message's createdAt/sequence — otherwise sortMessages (which
+    // orders by createdAt first) would re-stamp it to now and float it past any
+    // message created later (e.g. a long-pending approval resolved after more
+    // conversation, or restored/replayed transcripts).
+    const existing = this.messages.find((m) => m.id === approvalMessageId);
     const updatedMessage: AgentWidgetMessage = {
       id: approvalMessageId,
       role: "assistant",
       content: "",
-      createdAt: new Date().toISOString(),
+      createdAt: existing?.createdAt ?? new Date().toISOString(),
+      ...(existing?.sequence !== undefined ? { sequence: existing.sequence } : {}),
       streaming: false,
       variant: "approval",
       approval: updatedApproval,
@@ -1238,7 +1248,8 @@ export class AgentWidgetSession {
             agentId: approval.agentId,
             toolName: approval.toolName,
           },
-          decision
+          decision,
+          options
         );
       } else {
         response = await this.client.resolveApproval(

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

@@ -49,6 +49,16 @@ describe("theme editor preview demo data", () => {
     expect(reasoningMessage.reasoning?.status).toBe("streaming");
   });
 
+  it("creates a pending approval preview entry for theming the approval bubble", () => {
+    const message = createPreviewTranscriptEntry("approval-request", 3);
+
+    expect(message.variant).toBe("approval");
+    expect(message.approval?.status).toBe("pending");
+    expect(message.approval?.toolName).toBe("add_to_cart");
+    // Includes parameters so the params block is exercised when theming.
+    expect(message.approval?.parameters).toBeTruthy();
+  });
+
   it("appends public preview transcript entries to an existing conversation", () => {
     const messages = appendPreviewTranscriptEntry([], "tool-running");
     const updated = appendPreviewTranscriptEntry(messages, "reasoning-complete");

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.',

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;