@runtypelabs/persona 4.1.0 → 4.2.1

package/src/theme-reference.ts

@@ -227,9 +227,9 @@ export const THEME_TOKEN_DOCS = {
     },
     approval: {
       description:
-        'Tool approval bubble styling and behavior. Set to false to disable.',
+        'Tool approval card styling and behavior. Neutral surface card; the primary action anchors to the brand --persona-primary token. Set to false to disable. Set enableAlwaysAllow: true to add the split "Always allow / Allow once" control (needs a backend to persist the policy via onDecision\'s remember).',
       properties:
-        'backgroundColor, borderColor, titleColor, descriptionColor, reasonColor, reasonLabel, approveButtonColor, approveButtonTextColor, denyButtonColor, denyButtonTextColor, parameterBackgroundColor, parameterTextColor, title, approveLabel, denyLabel.',
+        'enableAlwaysAllow, detailsDisplay ("collapsed" | "expanded" | "hidden"), showDetailsLabel, hideDetailsLabel, backgroundColor, borderColor, titleColor, descriptionColor, reasonColor, reasonLabel, approveButtonColor, approveButtonTextColor, denyButtonColor, denyButtonTextColor, parameterBackgroundColor, parameterTextColor, approveLabel, denyLabel, formatDescription. (title no longer renders in the default card; use formatDescription to customize the summary.)',
     },
     copy: {
       description: 'Widget text content.',

package/src/types.ts

@@ -2296,6 +2296,21 @@ export type AgentWidgetApprovalConfig = {
   showDetailsLabel?: string;
   /** Label for the toggle that hides the technical details */
   hideDetailsLabel?: string;
+  /**
+   * Offer an "Always allow" affordance in the default approval bubble.
+   *
+   * Default `false`. When `false`, the bubble shows a single "Allow" (allow
+   * once) plus "Deny". When `true`, the primary action becomes a split control:
+   * "Always allow" (resolves with `{ remember: true }`) with a dropdown for
+   * "Allow once", plus "Deny", and keyboard shortcuts (Enter = Always allow,
+   * Cmd/Ctrl+Enter = Allow once, Esc = Deny).
+   *
+   * Keep this off unless your backend actually persists the don't-ask-again
+   * policy: "Always allow" only resolves the *current* approval — honoring it
+   * for *future* calls is up to your `onDecision` handler (which receives
+   * `options.remember`). Showing it without that wiring would mislead users.
+   */
+  enableAlwaysAllow?: boolean;
   /**
    * Build the user-facing summary line for an approval request. Overrides the
    * default "The assistant wants to use “Tool name”." copy. Return a falsy

package/src/ui.ts

@@ -99,6 +99,7 @@ import {
 } from "./suggest-replies-tool";
 import { formatElapsedMs } from "./utils/formatting";
 import { approvalDetailsExpansionState, createApprovalBubble, updateApprovalDetailsUI } from "./components/approval-bubble";
+import { createBuiltInApprovalPlugin } from "./components/approval-actions";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
 import { EventStreamStore } from "./utils/event-stream-store";
@@ -542,7 +543,13 @@ export const createAgentExperience = (
 
   // Get plugins for this instance
   const plugins = pluginRegistry.getForInstance(config.plugins);
-  
+
+  // The built-in approval renderer, shaped as a plugin. Resolved as a FALLBACK
+  // (not pushed into `plugins`) so a user `renderApproval` plugin always wins
+  // and a later config-update plugin push can't reorder ahead of it.
+  const { plugin: builtInApprovalPlugin, teardown: teardownBuiltInApprovals } =
+    createBuiltInApprovalPlugin();
+
   // Register components from config
   if (config.components) {
     componentRegistry.registerAll(config.components);
@@ -2743,6 +2750,11 @@ export const createAgentExperience = (
     }
   });
 
+  // Release this widget's pending built-in approval listeners + "Allow once"
+  // popovers if it's destroyed while an approval is still open. Scoped to this
+  // instance's state, so other widgets on the page are unaffected.
+  destroyCallbacks.push(teardownBuiltInApprovals);
+
   // Activate the stream-animation plugin for this widget instance. Plugins
   // with `styles` inject their CSS into the widget root once; plugins with
   // `onAttach` (e.g., glyph-cycle's MutationObserver for real glyph tick
@@ -3418,7 +3430,10 @@ export const createAgentExperience = (
     // interactivity), and idiomorph imports nodes via `document.importNode`,
     // which strips them. So we build the live element, append a stub during
     // morph, and inject the live element afterward.
-    const hasApprovalPlugin = plugins.some((p) => p.renderApproval) && config.approval !== false;
+    // The built-in approval renderer is always available (as a fallback plugin),
+    // so every approval flows through the stub-and-hydrate path whenever
+    // approvals are enabled — a user `renderApproval` plugin just overrides it.
+    const hasApprovalPlugin = config.approval !== false;
     type ApprovalPluginHydrate = {
       messageId: string;
       fingerprint: string;
@@ -3638,7 +3653,8 @@ export const createAgentExperience = (
         // any accordion listeners survive idiomorph's `importNode`. Gate the
         // rebuild on fingerprint so interactive state (e.g. a collapsed
         // accordion) is preserved while the approval stays pending.
-        const approvalPlugin = plugins.find((p) => typeof p.renderApproval === "function");
+        const approvalPlugin =
+          plugins.find((p) => typeof p.renderApproval === "function") ?? builtInApprovalPlugin;
         const lastFp = lastApprovalBubbleFingerprint.get(message.id);
         const needsRebuild = lastFp !== fingerprint;
         let liveBubble: HTMLElement | null = null;

package/src/utils/tokens.ts

@@ -384,22 +384,25 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       icon: 'palette.colors.success.500',
     },
   },
+  // Neutral surface card (components/approval-actions.ts). The primary action
+  // anchors to the brand primary; deny is a neutral tinted button. Consumers who
+  // themed these (or set config.approval.* color overrides) still win.
   approval: {
     requested: {
-      background: 'palette.colors.warning.50',
-      border: 'palette.colors.warning.200',
+      background: 'semantic.colors.surface',
+      border: 'semantic.colors.border',
       text: 'palette.colors.gray.900',
-      shadow: '0 5px 15px rgba(15, 23, 42, 0.08)',
+      shadow: '0 1px 2px 0 rgba(11, 11, 11, 0.06), 0 2px 8px 0 rgba(11, 11, 11, 0.04)',
     },
     approve: {
-      background: 'palette.colors.success.500',
-      foreground: 'palette.colors.gray.50',
+      background: 'semantic.colors.primary',
+      foreground: 'semantic.colors.textInverse',
       borderRadius: 'palette.radius.md',
       padding: 'semantic.spacing.sm',
     },
     deny: {
-      background: 'palette.colors.error.500',
-      foreground: 'palette.colors.gray.50',
+      background: 'semantic.colors.container',
+      foreground: 'semantic.colors.text',
       borderRadius: 'palette.radius.md',
       padding: 'semantic.spacing.sm',
     },
@@ -681,12 +684,12 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   cssVars['--persona-voice-processing-icon'] = cssVars['--persona-components-voice-processing-icon'] ?? cssVars['--persona-palette-colors-primary-500'];
   cssVars['--persona-voice-speaking-icon'] = cssVars['--persona-components-voice-speaking-icon'] ?? cssVars['--persona-palette-colors-success-500'];
 
-  cssVars['--persona-approval-bg'] = cssVars['--persona-components-approval-requested-background'] ?? cssVars['--persona-palette-colors-warning-50'];
-  cssVars['--persona-approval-border'] = cssVars['--persona-components-approval-requested-border'] ?? cssVars['--persona-palette-colors-warning-200'];
+  cssVars['--persona-approval-bg'] = cssVars['--persona-components-approval-requested-background'] ?? cssVars['--persona-surface'];
+  cssVars['--persona-approval-border'] = cssVars['--persona-components-approval-requested-border'] ?? cssVars['--persona-border'];
   cssVars['--persona-approval-text'] = cssVars['--persona-components-approval-requested-text'] ?? cssVars['--persona-palette-colors-gray-900'];
-  cssVars['--persona-approval-shadow'] = cssVars['--persona-components-approval-requested-shadow'] ?? '0 5px 15px rgba(15, 23, 42, 0.08)';
-  cssVars['--persona-approval-approve-bg'] = cssVars['--persona-components-approval-approve-background'] ?? cssVars['--persona-palette-colors-success-500'];
-  cssVars['--persona-approval-deny-bg'] = cssVars['--persona-components-approval-deny-background'] ?? cssVars['--persona-palette-colors-error-500'];
+  cssVars['--persona-approval-shadow'] = cssVars['--persona-components-approval-requested-shadow'] ?? '0 1px 2px 0 rgba(11, 11, 11, 0.06), 0 2px 8px 0 rgba(11, 11, 11, 0.04)';
+  cssVars['--persona-approval-approve-bg'] = cssVars['--persona-components-approval-approve-background'] ?? cssVars['--persona-button-primary-bg'];
+  cssVars['--persona-approval-deny-bg'] = cssVars['--persona-components-approval-deny-background'] ?? cssVars['--persona-container'];
 
   cssVars['--persona-attachment-image-bg'] = cssVars['--persona-components-attachment-image-background'] ?? cssVars['--persona-palette-colors-gray-100'];
   cssVars['--persona-attachment-image-border'] = cssVars['--persona-components-attachment-image-border'] ?? cssVars['--persona-palette-colors-gray-200'];