@runtypelabs/persona 3.29.1 → 3.31.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,167 @@ 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 - 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', () => {

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(
@@ -2648,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-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");