@runtypelabs/persona 3.29.0 → 3.30.0

package/src/components/approval-bubble.ts

@@ -2,6 +2,86 @@ import { createElement } from "../utils/dom";
 import { AgentWidgetMessage, AgentWidgetConfig } from "../types";
 import { formatUnknownValue } from "../utils/formatting";
 import { renderLucideIcon } from "../utils/icons";
+import { WEBMCP_TOOL_PREFIX, getWebMcpToolDisplayTitle } from "../webmcp-bridge";
+
+/**
+ * Per-message expanded/collapsed state for the technical-details section.
+ * Absent means "use the config default" (`approval.detailsDisplay`). Lives at
+ * module scope so the choice survives idiomorph re-renders, mirroring
+ * `toolExpansionState` in tool-bubble.ts.
+ */
+export const approvalDetailsExpansionState = new Map<string, boolean>();
+
+/**
+ * Turn a wire tool name into a user-facing label: strips the `webmcp:`
+ * prefix and splits snake_case / kebab-case / camelCase into a sentence
+ * (`add_to_cart` → "Add to cart"). Falls back to the input when nothing
+ * word-like remains.
+ */
+export const humanizeToolName = (toolName: string): string => {
+  const bare = toolName.startsWith(WEBMCP_TOOL_PREFIX)
+    ? toolName.slice(WEBMCP_TOOL_PREFIX.length)
+    : toolName;
+  const words = bare
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[_\-\s.]+/)
+    .filter(Boolean);
+  if (words.length === 0) return toolName;
+  const sentence = words.join(" ").toLowerCase();
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+};
+
+const resolveApprovalConfig = (config?: AgentWidgetConfig) =>
+  config?.approval !== false ? config?.approval : undefined;
+
+const isDetailsExpanded = (
+  messageId: string,
+  config?: AgentWidgetConfig
+): boolean => {
+  const detailsMode = resolveApprovalConfig(config)?.detailsDisplay ?? "collapsed";
+  return approvalDetailsExpansionState.get(messageId) ?? detailsMode === "expanded";
+};
+
+const applyDetailsToggleState = (
+  toggle: HTMLElement,
+  expanded: boolean,
+  config?: AgentWidgetConfig
+): void => {
+  const approvalConfig = resolveApprovalConfig(config);
+  toggle.setAttribute("aria-expanded", expanded ? "true" : "false");
+  const label = toggle.querySelector("[data-approval-details-label]") as HTMLElement | null;
+  if (label) {
+    label.textContent = expanded
+      ? (approvalConfig?.hideDetailsLabel ?? "Hide details")
+      : (approvalConfig?.showDetailsLabel ?? "Show details");
+  }
+  const chevronHolder = toggle.querySelector("[data-approval-details-chevron]") as HTMLElement | null;
+  if (chevronHolder) {
+    chevronHolder.innerHTML = "";
+    const chevron = renderLucideIcon(expanded ? "chevron-up" : "chevron-down", 14, "currentColor", 2);
+    if (chevron) {
+      chevronHolder.appendChild(chevron);
+    }
+  }
+};
+
+/**
+ * Sync the technical-details section (toggle label/chevron + visibility) with
+ * `approvalDetailsExpansionState`. Called from the ui.ts expansion event
+ * delegation after a toggle click.
+ */
+export const updateApprovalDetailsUI = (
+  messageId: string,
+  bubble: HTMLElement,
+  config?: AgentWidgetConfig
+): void => {
+  const toggle = bubble.querySelector('button[data-bubble-type="approval"]') as HTMLElement | null;
+  const details = bubble.querySelector("[data-approval-details]") as HTMLElement | null;
+  if (!toggle || !details) return;
+  const expanded = isDetailsExpanded(messageId, config);
+  applyDetailsToggleState(toggle, expanded, config);
+  details.style.display = expanded ? "" : "none";
+};
 
 /**
  * Update an existing approval bubble's UI after status changes.
@@ -96,6 +176,10 @@ export const createApprovalBubble = (
   // Apply styling — use semantic tokens with config overrides
   bubble.style.backgroundColor = approvalConfig?.backgroundColor ?? "var(--persona-approval-bg, #fefce8)";
   bubble.style.borderColor = approvalConfig?.borderColor ?? "var(--persona-approval-border, #fef08a)";
+  bubble.style.boxShadow =
+    approvalConfig?.shadow !== undefined
+      ? (approvalConfig.shadow.trim() === "" ? "none" : approvalConfig.shadow)
+      : "var(--persona-approval-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))";
 
   if (!approval) {
     return bubble;
@@ -156,30 +240,96 @@ export const createApprovalBubble = (
 
   content.appendChild(titleRow);
 
-  // Description
-  const description = createElement("p", "persona-text-sm persona-mt-0.5 persona-text-persona-muted");
+  // User-facing summary line. The wire `description` is the tool's
+  // agent-facing description (prompt prose, usage rules), so it is not shown
+  // here — it lives in the collapsible details section below. Label priority:
+  // formatDescription → declared WebMCP `title` → humanized tool name →
+  // raw description (no tool name at all).
+  const isWebMcpTool =
+    approval.toolType === "webmcp" ||
+    approval.toolName.startsWith(WEBMCP_TOOL_PREFIX);
+  const declaredTitle = isWebMcpTool
+    ? getWebMcpToolDisplayTitle(approval.toolName)
+    : undefined;
+  const summaryFromConfig = approvalConfig?.formatDescription?.({
+    toolName: approval.toolName,
+    toolType: approval.toolType,
+    description: approval.description,
+    parameters: approval.parameters,
+    ...(declaredTitle ? { displayTitle: declaredTitle } : {}),
+  });
+  const summaryFallsBackToDescription = !approval.toolName;
+  const summaryText =
+    summaryFromConfig ||
+    (summaryFallsBackToDescription
+      ? approval.description
+      : `The assistant wants to use “${declaredTitle ?? humanizeToolName(approval.toolName)}”.`);
+
+  const summary = createElement("p", "persona-text-sm persona-mt-0.5 persona-text-persona-muted");
+  summary.setAttribute("data-approval-summary", "true");
   if (approvalConfig?.descriptionColor) {
-    description.style.color = approvalConfig.descriptionColor;
+    summary.style.color = approvalConfig.descriptionColor;
   }
-  description.textContent = approval.description;
-  content.appendChild(description);
-
-  // Parameters block
-  if (approval.parameters) {
-    const paramsPre = createElement(
-      "pre",
-      "persona-mt-2 persona-text-xs persona-p-2 persona-rounded persona-overflow-x-auto persona-max-h-32 persona-bg-persona-container persona-text-persona-primary"
-    );
-    if (approvalConfig?.parameterBackgroundColor) {
-      paramsPre.style.backgroundColor = approvalConfig.parameterBackgroundColor;
+  summary.textContent = summaryText;
+  content.appendChild(summary);
+
+  // Technical details: agent-facing description + raw parameters JSON,
+  // collapsed behind a toggle by default (`approval.detailsDisplay`).
+  const detailsMode = approvalConfig?.detailsDisplay ?? "collapsed";
+  const showDescriptionInDetails = Boolean(approval.description) && !summaryFallsBackToDescription;
+  const hasDetails = showDescriptionInDetails || Boolean(approval.parameters);
+  if (detailsMode !== "hidden" && hasDetails) {
+    const expanded = isDetailsExpanded(message.id, config);
+
+    const toggle = createElement(
+      "button",
+      "persona-inline-flex persona-items-center persona-gap-1 persona-mt-1 persona-p-0 persona-border-none persona-bg-transparent persona-text-xs persona-font-medium persona-cursor-pointer persona-text-persona-muted"
+    ) as HTMLButtonElement;
+    toggle.type = "button";
+    toggle.setAttribute("data-expand-header", "true");
+    toggle.setAttribute("data-bubble-type", "approval");
+    if (approvalConfig?.descriptionColor) {
+      toggle.style.color = approvalConfig.descriptionColor;
+    }
+    const toggleLabel = createElement("span");
+    toggleLabel.setAttribute("data-approval-details-label", "true");
+    const chevronHolder = createElement("span", "persona-inline-flex persona-items-center");
+    chevronHolder.setAttribute("data-approval-details-chevron", "true");
+    toggle.append(toggleLabel, chevronHolder);
+    applyDetailsToggleState(toggle, expanded, config);
+    content.appendChild(toggle);
+
+    const details = createElement("div");
+    details.setAttribute("data-approval-details", "true");
+    details.style.display = expanded ? "" : "none";
+
+    if (showDescriptionInDetails) {
+      const description = createElement("p", "persona-text-sm persona-mt-1 persona-text-persona-muted");
+      if (approvalConfig?.descriptionColor) {
+        description.style.color = approvalConfig.descriptionColor;
+      }
+      description.textContent = approval.description;
+      details.appendChild(description);
     }
-    if (approvalConfig?.parameterTextColor) {
-      paramsPre.style.color = approvalConfig.parameterTextColor;
+
+    if (approval.parameters) {
+      const paramsPre = createElement(
+        "pre",
+        "persona-mt-2 persona-text-xs persona-p-2 persona-rounded persona-overflow-x-auto persona-max-h-32 persona-bg-persona-container persona-text-persona-primary"
+      );
+      if (approvalConfig?.parameterBackgroundColor) {
+        paramsPre.style.backgroundColor = approvalConfig.parameterBackgroundColor;
+      }
+      if (approvalConfig?.parameterTextColor) {
+        paramsPre.style.color = approvalConfig.parameterTextColor;
+      }
+      paramsPre.style.fontSize = "0.75rem";
+      paramsPre.style.lineHeight = "1rem";
+      paramsPre.textContent = formatUnknownValue(approval.parameters);
+      details.appendChild(paramsPre);
     }
-    paramsPre.style.fontSize = "0.75rem";
-    paramsPre.style.lineHeight = "1rem";
-    paramsPre.textContent = formatUnknownValue(approval.parameters);
-    content.appendChild(paramsPre);
+
+    content.appendChild(details);
   }
 
   // Action buttons (only shown when pending)

package/src/components/launcher.ts

@@ -187,10 +187,13 @@ export const createLauncherButton = (
 
     // Apply launcher border and shadow from config (with defaults matching previous Tailwind classes)
     const defaultBorder = "1px solid var(--persona-border, #e5e7eb)";
-    const defaultShadow = "var(--persona-shadow, 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1))";
-    
+    const defaultShadow = "var(--persona-launcher-shadow, 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1))";
+
     button.style.border = launcher.border ?? defaultBorder;
-    button.style.boxShadow = launcher.shadow ?? defaultShadow;
+    button.style.boxShadow =
+      launcher.shadow !== undefined
+        ? (launcher.shadow.trim() === "" ? "none" : launcher.shadow)
+        : defaultShadow;
 
     if (dockedMode) {
       // Docked mode uses a 0px column when closed and hides this button; keep no hit target.

package/src/components/tool-bubble.test.ts

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { createToolBubble } from "./tool-bubble";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "../types";
+
+const makeMessage = (): AgentWidgetMessage => ({
+  id: "msg-1",
+  role: "assistant",
+  content: "",
+  createdAt: new Date().toISOString(),
+  variant: "tool",
+  streaming: false,
+  toolCall: {
+    id: "tool-1",
+    name: "get_weather",
+    status: "complete",
+    args: { city: "SF" },
+  },
+});
+
+describe("createToolBubble shadow", () => {
+  it("falls back to the themeable --persona-tool-bubble-shadow variable when no config.shadow is set", () => {
+    const bubble = createToolBubble(makeMessage());
+    expect(bubble.style.boxShadow).toContain("--persona-tool-bubble-shadow");
+  });
+
+  it("applies a custom shadow inline from config.toolCall.shadow", () => {
+    const config = { toolCall: { shadow: "0 8px 24px rgba(0,0,0,0.15)" } } as AgentWidgetConfig;
+    const bubble = createToolBubble(makeMessage(), config);
+    expect(bubble.style.boxShadow).toBe("0 8px 24px rgba(0,0,0,0.15)");
+  });
+
+  it('maps an empty shadow string to "none"', () => {
+    const config = { toolCall: { shadow: "  " } } as AgentWidgetConfig;
+    const bubble = createToolBubble(makeMessage(), config);
+    expect(bubble.style.boxShadow).toBe("none");
+  });
+});

package/src/components/tool-bubble.ts

@@ -151,6 +151,10 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   if (toolCallConfig.borderRadius) {
     bubble.style.borderRadius = toolCallConfig.borderRadius;
   }
+  bubble.style.boxShadow =
+    toolCallConfig.shadow !== undefined
+      ? (toolCallConfig.shadow.trim() === "" ? "none" : toolCallConfig.shadow)
+      : "var(--persona-tool-bubble-shadow, 0 5px 15px rgba(15, 23, 42, 0.08))";
 
   if (!tool) {
     return bubble;

package/src/generated/runtype-openapi-contract.ts

@@ -206,6 +206,7 @@ export type RuntypeAgentSSEEvent = {
   iteration: number;
   reflection?: string;
   seq: number;
+  timestamp?: string;
   type: "agent_reflection";
 } | {
   activatedCapabilities: Array<string>;
@@ -213,6 +214,7 @@ export type RuntypeAgentSSEEvent = {
   iteration: number;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_loaded";
 } | ({
@@ -222,6 +224,7 @@ export type RuntypeAgentSSEEvent = {
   proposalId?: string;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_proposed";
 }) | ({
@@ -255,6 +258,7 @@ export type RuntypeAgentSSEEvent = {
   iteration?: number;
   recoverable: boolean;
   seq: number;
+  timestamp?: string;
   type: "agent_error";
 } | {
   executionId: string;
@@ -289,6 +293,7 @@ export type RuntypeFlowSSEEvent = {
   failedSteps?: number;
   finalOutput?: string;
   flowId?: string;
+  flowName?: string;
   output?: unknown;
   seq?: number;
   source?: string;
@@ -340,6 +345,7 @@ export type RuntypeFlowSSEEvent = {
   id?: string;
   index?: number;
   name?: string;
+  outputVariable?: string;
   seq?: number;
   startedAt: string;
   stepId?: string;
@@ -751,6 +757,7 @@ export type RuntypeDispatchSSEEvent = {
   iteration: number;
   reflection?: string;
   seq: number;
+  timestamp?: string;
   type: "agent_reflection";
 } | {
   activatedCapabilities: Array<string>;
@@ -758,6 +765,7 @@ export type RuntypeDispatchSSEEvent = {
   iteration: number;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_loaded";
 } | ({
@@ -767,6 +775,7 @@ export type RuntypeDispatchSSEEvent = {
   proposalId?: string;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_proposed";
 }) | ({
@@ -800,6 +809,7 @@ export type RuntypeDispatchSSEEvent = {
   iteration?: number;
   recoverable: boolean;
   seq: number;
+  timestamp?: string;
   type: "agent_error";
 } | {
   executionId: string;
@@ -832,6 +842,7 @@ export type RuntypeDispatchSSEEvent = {
   failedSteps?: number;
   finalOutput?: string;
   flowId?: string;
+  flowName?: string;
   output?: unknown;
   seq?: number;
   source?: string;
@@ -883,6 +894,7 @@ export type RuntypeDispatchSSEEvent = {
   id?: string;
   index?: number;
   name?: string;
+  outputVariable?: string;
   seq?: number;
   startedAt: string;
   stepId?: string;

package/src/index-core.ts

@@ -81,6 +81,7 @@ export type {
   // Approval types
   AgentWidgetApproval,
   AgentWidgetApprovalConfig,
+  AgentWidgetApprovalDecisionOptions,
   // WebMCP — page-discovered tool consumption
   AgentWidgetWebMcpConfig,
   ClientToolDefinition,

package/src/plugin-kit.test.ts

@@ -0,0 +1,230 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createPopover,
+  getStyleRoot,
+  injectStyles,
+  isEditableEventTarget,
+} from "./plugin-kit";
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  document.head.querySelectorAll("[data-persona-plugin-style]").forEach((n) => n.remove());
+  vi.restoreAllMocks();
+});
+
+const flushMicrotasks = () => Promise.resolve();
+
+describe("injectStyles / getStyleRoot", () => {
+  it("injects a <style> into the document head for a connected light-DOM node", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+
+    injectStyles(el, "kit-light", ".x { color: red; }");
+
+    const style = document.head.querySelector(
+      'style[data-persona-plugin-style="kit-light"]'
+    );
+    expect(style).not.toBeNull();
+    expect(style?.textContent).toContain("color: red");
+  });
+
+  it("is idempotent — repeated calls add only one <style>", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+
+    injectStyles(el, "kit-once", ".a {}");
+    injectStyles(el, "kit-once", ".a {}");
+    injectStyles(el, "kit-once", ".a {}");
+
+    expect(
+      document.head.querySelectorAll('style[data-persona-plugin-style="kit-once"]').length
+    ).toBe(1);
+  });
+
+  it("injects into the shadow root for a node inside shadow DOM", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: "open" });
+    const el = document.createElement("div");
+    shadow.appendChild(el);
+
+    expect(getStyleRoot(el)).toBe(shadow);
+
+    injectStyles(el, "kit-shadow", ".s {}");
+
+    expect(shadow.querySelector('style[data-persona-plugin-style="kit-shadow"]')).not.toBeNull();
+    // Must NOT leak into the document head.
+    expect(
+      document.head.querySelector('style[data-persona-plugin-style="kit-shadow"]')
+    ).toBeNull();
+  });
+
+  it("defers shadow injection for a node that mounts after the call", async () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: "open" });
+
+    // Build detached, inject, then mount into the shadow root (mirrors a plugin
+    // returning an element the widget mounts afterward).
+    const el = document.createElement("div");
+    injectStyles(el, "kit-deferred", ".d {}");
+    shadow.appendChild(el);
+
+    await flushMicrotasks();
+
+    expect(shadow.querySelector('style[data-persona-plugin-style="kit-deferred"]')).not.toBeNull();
+  });
+
+  it("accepts an explicit Document or ShadowRoot target", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: "open" });
+
+    injectStyles(shadow, "kit-explicit", ".e {}");
+
+    expect(shadow.querySelector('style[data-persona-plugin-style="kit-explicit"]')).not.toBeNull();
+  });
+});
+
+describe("createPopover", () => {
+  const setup = () => {
+    const anchor = document.createElement("button");
+    anchor.textContent = "anchor";
+    document.body.appendChild(anchor);
+    const content = document.createElement("div");
+    content.textContent = "menu";
+    return { anchor, content };
+  };
+
+  it("mounts and positions the content on open, removes it on close", () => {
+    const { anchor, content } = setup();
+    const popover = createPopover({ anchor, content });
+
+    expect(popover.isOpen).toBe(false);
+    expect(content.isConnected).toBe(false);
+
+    popover.open();
+    expect(popover.isOpen).toBe(true);
+    expect(content.isConnected).toBe(true);
+    expect(content.style.position).toBe("fixed");
+    expect(content.style.top).not.toBe("");
+    expect(content.style.left).not.toBe("");
+
+    popover.close();
+    expect(popover.isOpen).toBe(false);
+    expect(content.isConnected).toBe(false);
+  });
+
+  it("toggle flips open/closed", () => {
+    const { anchor, content } = setup();
+    const popover = createPopover({ anchor, content });
+
+    popover.toggle();
+    expect(popover.isOpen).toBe(true);
+    popover.toggle();
+    expect(popover.isOpen).toBe(false);
+  });
+
+  it("closes on outside pointerdown and fires onDismiss", () => {
+    vi.useFakeTimers();
+    const onDismiss = vi.fn();
+    const { anchor, content } = setup();
+    const popover = createPopover({ anchor, content, onDismiss });
+
+    popover.open();
+    // Arming is deferred via setTimeout so the opening click can't dismiss it.
+    vi.runAllTimers();
+
+    document.body.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+
+    expect(popover.isOpen).toBe(false);
+    expect(onDismiss).toHaveBeenCalledWith("outside");
+    vi.useRealTimers();
+  });
+
+  it("does not dismiss when the pointerdown is inside the content", () => {
+    vi.useFakeTimers();
+    const onDismiss = vi.fn();
+    const { anchor, content } = setup();
+    const popover = createPopover({ anchor, content, onDismiss });
+
+    popover.open();
+    vi.runAllTimers();
+
+    content.dispatchEvent(new Event("pointerdown", { bubbles: true, composed: true }));
+
+    expect(popover.isOpen).toBe(true);
+    expect(onDismiss).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+
+  it("auto-closes when the anchor leaves the DOM on reposition", () => {
+    const onDismiss = vi.fn();
+    const { anchor, content } = setup();
+    const popover = createPopover({ anchor, content, onDismiss });
+
+    popover.open();
+    anchor.remove();
+    window.dispatchEvent(new Event("resize"));
+
+    expect(popover.isOpen).toBe(false);
+    expect(onDismiss).toHaveBeenCalledWith("anchor-removed");
+  });
+
+  it("mounts into the anchor's shadow root when shadowed", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: "open" });
+    const anchor = document.createElement("button");
+    shadow.appendChild(anchor);
+    const content = document.createElement("div");
+
+    const popover = createPopover({ anchor, content });
+    popover.open();
+
+    expect(content.getRootNode()).toBe(shadow);
+  });
+
+  it("destroy removes content and detaches listeners", () => {
+    vi.useFakeTimers();
+    const onDismiss = vi.fn();
+    const { anchor, content } = setup();
+    const popover = createPopover({ anchor, content, onDismiss });
+
+    popover.open();
+    vi.runAllTimers();
+    popover.destroy();
+
+    expect(content.isConnected).toBe(false);
+    // Listeners are gone, so a later outside pointerdown is a no-op.
+    document.body.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+    expect(onDismiss).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+});
+
+describe("isEditableEventTarget", () => {
+  it("is true for input / textarea / contenteditable targets", () => {
+    const input = document.createElement("input");
+    document.body.appendChild(input);
+    const event = new Event("keydown", { bubbles: true, composed: true });
+    input.dispatchEvent(event);
+    // jsdom keeps composedPath populated only during dispatch; assert via a
+    // synthetic event whose composedPath we can rely on.
+    const synthetic = {
+      composedPath: () => [input, document.body],
+    } as unknown as Event;
+    expect(isEditableEventTarget(synthetic)).toBe(true);
+  });
+
+  it("is false for a plain button target", () => {
+    const button = document.createElement("button");
+    const synthetic = {
+      composedPath: () => [button, document.body],
+    } as unknown as Event;
+    expect(isEditableEventTarget(synthetic)).toBe(false);
+  });
+});