@runtypelabs/persona 3.2.2 → 3.4.0

package/src/index.ts

@@ -194,6 +194,14 @@ export type {
   ComboButtonHandle
 } from "./utils/buttons";
 
+// Demo carousel exports
+export { createDemoCarousel } from "./components/demo-carousel";
+export type {
+  DemoCarouselItem,
+  DemoCarouselOptions,
+  DemoCarouselHandle
+} from "./components/demo-carousel";
+
 // Theme system exports
 export {
   createTheme,

package/src/styles/widget.css

@@ -1222,6 +1222,68 @@
   font-size: 0.8125rem;
 }
 
+/* Code block copy button */
+.persona-code-block-wrapper {
+  position: relative;
+  margin: 0.5rem 0;
+}
+
+.persona-code-block-wrapper pre {
+  margin: 0 !important;
+  border-top-left-radius: 0 !important;
+  border-top-right-radius: 0 !important;
+}
+
+.persona-code-block-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  background-color: var(--persona-md-code-block-bg, #f3f4f6);
+  border: 1px solid var(--persona-md-code-block-border-color, #e5e7eb);
+  border-bottom: none;
+  border-top-left-radius: var(--persona-md-code-block-border-radius, 0.375rem);
+  border-top-right-radius: var(--persona-md-code-block-border-radius, 0.375rem);
+  padding: 0.25rem 0.5rem 0.25rem 0.75rem;
+  font-size: 0.75rem;
+  color: var(--persona-text-muted, #6b7280);
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Consolas, "Liberation Mono", Menlo, monospace;
+}
+
+.persona-code-copy-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  background: none;
+  border: 1px solid transparent;
+  border-radius: 0.25rem;
+  padding: 0.25rem 0.5rem;
+  cursor: pointer;
+  color: var(--persona-text-muted, #6b7280);
+  font-size: 0.75rem;
+  font-family: inherit;
+  line-height: 1;
+  transition: color 0.15s ease, border-color 0.15s ease;
+}
+
+.persona-code-copy-btn:hover {
+  color: var(--persona-text, #111827);
+  border-color: var(--persona-md-code-block-border-color, #e5e7eb);
+}
+
+.persona-code-copy-btn.persona-code-copied {
+  color: #16a34a;
+}
+
+.persona-code-copy-btn.persona-code-copy-generating {
+  cursor: default;
+  opacity: 0.5;
+}
+
+.persona-code-copy-btn.persona-code-copy-generating:hover {
+  color: var(--persona-text-muted, #6b7280);
+  border-color: transparent;
+}
+
 /* Ensure all links in chat bubbles have underlines */
 .vanilla-message-bubble a {
   text-decoration: underline;

package/src/theme-reference.ts

@@ -0,0 +1,371 @@
+/**
+ * Theme Reference — Structured documentation and examples for the Persona v2 theme system.
+ *
+ * Exported via the `@runtypelabs/persona/theme-reference` entry point so it stays
+ * out of the IIFE widget bundle. Intended for AI/MCP tool consumption.
+ */
+
+import { DEFAULT_PALETTE } from './utils/tokens'
+import type { DeepPartial, PersonaTheme } from './types/theme'
+
+// ---------------------------------------------------------------------------
+// Token System Documentation
+// ---------------------------------------------------------------------------
+
+export const THEME_TOKEN_DOCS = {
+  overview:
+    'Persona uses a three-layer design token system: palette → semantic → components. Most themes only need palette.colors overrides — semantic and component layers auto-derive from palette values. Config also accepts non-theme appearance options (launcher, sendButton, toolCall, etc.).',
+
+  layers: {
+    palette: {
+      description:
+        'Primitive design tokens. Override specific shades to change the entire widget feel.',
+      colors: {
+        description:
+          '7 color scales, each with shades 50 (lightest) to 950 (darkest). Override only the shades you need.',
+        scales: {
+          gray: 'Neutrals — backgrounds, text, borders. Key shades: 50 (lightest bg), 100 (secondary bg), 200 (borders), 500 (muted text), 900 (primary text).',
+          primary:
+            'Brand color — buttons, links, interactive elements. Key shades: 500 (default), 600 (hover).',
+          accent: 'Secondary highlight. Key shades: 500 (default), 600 (hover).',
+          secondary: 'Tertiary color scale.',
+          success: 'Positive feedback (default: green).',
+          warning: 'Caution feedback (default: yellow).',
+          error: 'Error/danger feedback (default: red).',
+        },
+      },
+      radius: {
+        description: 'Border radius scale. Add custom keys like launcher, button.',
+        defaults: {
+          none: '0px',
+          sm: '0.125rem',
+          md: '0.375rem',
+          lg: '0.5rem',
+          xl: '0.75rem',
+          '2xl': '1rem',
+          full: '9999px',
+        },
+      },
+      typography: {
+        fontFamily:
+          'Three stacks: sans (system-ui), serif (Georgia), mono (ui-monospace). Override individual stack values.',
+        fontSize:
+          'Scale: xs (0.75rem), sm (0.875rem), base (1rem), lg (1.125rem), xl (1.25rem), 2xl (1.5rem), 3xl (1.875rem), 4xl (2.25rem).',
+        fontWeight: 'normal (400), medium (500), semibold (600), bold (700).',
+        lineHeight: 'tight (1.25), normal (1.5), relaxed (1.625).',
+      },
+      shadows:
+        'Scale: none, sm, md, lg, xl, 2xl. Values are CSS box-shadow strings.',
+      borders: 'Scale: none, sm (1px solid), md (2px solid), lg (4px solid).',
+      spacing:
+        'Scale: 0 (0px), 1 (0.25rem), 2 (0.5rem), 3 (0.75rem), 4 (1rem), 5 (1.25rem), 6 (1.5rem), 8 (2rem), 10 (2.5rem), 12 (3rem), 16-64.',
+    },
+
+    semantic: {
+      description:
+        'Design intent tokens. Auto-derived from palette by default. Override to redirect token resolution. Values are token reference strings like "palette.colors.primary.500".',
+      colors: {
+        primary: 'palette.colors.primary.500 — Primary brand color.',
+        secondary: 'palette.colors.gray.500 — Secondary color.',
+        accent: 'palette.colors.primary.600 — Accent/interactive color.',
+        surface: 'palette.colors.gray.50 — Panel/card backgrounds.',
+        background: 'palette.colors.gray.50 — Page background.',
+        container: 'palette.colors.gray.100 — Container backgrounds.',
+        text: 'palette.colors.gray.900 — Primary text.',
+        textMuted: 'palette.colors.gray.500 — Muted/secondary text.',
+        textInverse: 'palette.colors.gray.50 — Text on dark backgrounds.',
+        border: 'palette.colors.gray.200 — Default border color.',
+        divider: 'palette.colors.gray.200 — Divider lines.',
+        interactive: {
+          default: 'palette.colors.primary.500',
+          hover: 'palette.colors.primary.600',
+          focus: 'palette.colors.primary.700',
+          active: 'palette.colors.primary.800',
+          disabled: 'palette.colors.gray.300',
+        },
+        feedback: {
+          success: 'palette.colors.success.500',
+          warning: 'palette.colors.warning.500',
+          error: 'palette.colors.error.500',
+          info: 'palette.colors.primary.500',
+        },
+      },
+      spacing:
+        'xs (0.25rem), sm (0.5rem), md (1rem), lg (1.5rem), xl (2rem), 2xl (2.5rem).',
+      typography:
+        'fontFamily, fontSize, fontWeight, lineHeight — reference palette typography tokens.',
+    },
+
+    components: {
+      description:
+        'UI element tokens. Rarely needed for basic theming. Override for fine-grained control. All values are token references or raw CSS strings.',
+      button: {
+        description: 'Three variants: primary, secondary, ghost.',
+        properties: 'background, foreground, borderRadius, padding.',
+      },
+      input: {
+        description: 'Message input field.',
+        properties:
+          'background, placeholder, borderRadius, padding, focus.border, focus.ring.',
+      },
+      launcher: {
+        description: 'Floating launcher button.',
+        properties: 'size (60px), iconSize (28px), borderRadius, shadow.',
+      },
+      panel: {
+        description: 'Chat panel container.',
+        properties:
+          'width, maxWidth (400px), height (600px), maxHeight, borderRadius, shadow.',
+      },
+      header: {
+        description: 'Chat panel header.',
+        properties:
+          'background, border, borderRadius, padding, iconBackground, iconForeground, titleForeground, subtitleForeground, actionIconForeground, shadow, borderBottom.',
+      },
+      message: {
+        description: 'Chat message bubbles.',
+        user: 'background, text, borderRadius, shadow.',
+        assistant:
+          'background, text, borderRadius, border (optional), shadow (optional).',
+      },
+      markdown: {
+        description: 'Markdown rendering in messages and artifact pane.',
+        properties:
+          'inlineCode (background, foreground), link.foreground, prose.fontFamily, heading.h1/h2 (fontSize, fontWeight).',
+      },
+      voice:
+        'recording (indicator, background, border), processing (icon, background), speaking (icon).',
+      approval:
+        'requested (background, border, text), approve (background, foreground), deny (background, foreground).',
+      attachment: 'image (background, border).',
+      toolBubble: 'shadow — tool call row box-shadow.',
+      reasoningBubble: 'shadow — reasoning/thinking row box-shadow.',
+      composer: 'shadow — message input form box-shadow.',
+      artifact:
+        'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
+    },
+  },
+
+  colorScheme:
+    '"dark" merges darkTheme overrides on top of theme. "auto" detects system preference or <html class="dark">. "light" is default. colorScheme does NOT auto-invert colors — provide dark palette and semantic overrides yourself.',
+
+  plugins: {
+    description:
+      'Plugins transform theme tokens before resolution. Use with createTheme().',
+    available: {
+      brandPlugin:
+        'Auto-generates full color scales from a single brand hex: brandPlugin({ colors: { primary: "#7c3aed" } }).',
+      accessibilityPlugin:
+        'Enhanced focus indicators and disabled states.',
+      highContrastPlugin: 'Increased contrast for visual accessibility.',
+      reducedMotionPlugin:
+        'Disables all animations (sets transitions to 0ms).',
+      animationsPlugin: 'Adds transition and easing tokens.',
+    },
+    usage:
+      'createTheme(themeOverrides, { plugins: [brandPlugin({ colors: { primary: "#7c3aed" } })] })',
+  },
+
+  widgetConfig: {
+    description:
+      'Non-theme config options on the widget config object that affect appearance. These are siblings of "theme" in the config, not nested inside it.',
+    launcher: {
+      description: 'Floating launcher button and panel positioning.',
+      properties: {
+        enabled: 'Show/hide the launcher button.',
+        title: 'Header title text.',
+        subtitle: 'Header subtitle text.',
+        position:
+          '"bottom-right" | "bottom-left" | "top-right" | "top-left".',
+        width: 'Chat panel width (CSS value).',
+        fullHeight: 'Fill full height of container.',
+        mountMode: '"floating" | "docked".',
+        agentIconText: 'Emoji/text for agent icon.',
+        border: 'Border style for launcher button.',
+        shadow: 'Box shadow for launcher button.',
+        collapsedMaxWidth: 'Max-width for launcher pill when panel closed.',
+      },
+    },
+    sendButton: {
+      description: 'Send button appearance.',
+      properties:
+        'backgroundColor, textColor, borderWidth, borderColor, paddingX, paddingY, iconText, iconName, size.',
+    },
+    closeButton: {
+      description: 'Close button (on launcher config).',
+      properties:
+        'closeButtonSize, closeButtonColor, closeButtonBackgroundColor, closeButtonBorderWidth, closeButtonBorderColor, closeButtonBorderRadius.',
+    },
+    clearChat: {
+      description: 'Clear chat button (on launcher.clearChat config).',
+      properties:
+        'enabled, iconColor, backgroundColor, borderWidth, borderColor, borderRadius, size.',
+    },
+    toolCall: {
+      description: 'Tool call display styling.',
+      properties:
+        'backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, contentBackgroundColor, contentTextColor, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor.',
+    },
+    copy: {
+      description: 'Widget text content.',
+      properties:
+        'welcomeTitle, welcomeSubtitle, inputPlaceholder, sendButtonLabel.',
+    },
+    voiceRecognition: {
+      description: 'Voice input configuration.',
+      properties: 'enabled, pauseDuration, iconColor, backgroundColor.',
+    },
+    suggestionChips:
+      'string[] — Suggested prompts shown to the user.',
+    layout: {
+      description: 'Layout configuration.',
+      header: '"default" | "minimal". Options: showIcon, showTitle, showSubtitle, showCloseButton.',
+      messages:
+        '"bubble" | "flat" | "minimal". Avatar and timestamp options available.',
+    },
+    features: {
+      description: 'Feature flags.',
+      properties:
+        'showReasoning (AI thinking steps), showToolCalls (tool invocations), artifacts (sidebar config).',
+    },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Example Themes
+// ---------------------------------------------------------------------------
+
+export interface ThemeExample {
+  description: string
+  colorScheme?: 'light' | 'dark' | 'auto'
+  theme: DeepPartial<PersonaTheme>
+}
+
+export const THEME_EXAMPLES: Record<string, ThemeExample> = {
+  darkIndigo: {
+    description:
+      'Dark mode with indigo accent — override grays for dark backgrounds and semantic tokens for inverted text/surface',
+    theme: {
+      palette: {
+        colors: {
+          primary: { 500: '#6366f1', 600: '#4f46e5' },
+          gray: {
+            50: '#f1f5f9',
+            100: '#1e293b',
+            200: '#334155',
+            500: '#94a3b8',
+            900: '#0f172a',
+            950: '#020617',
+          },
+        },
+      },
+      semantic: {
+        colors: {
+          surface: 'palette.colors.gray.900',
+          background: 'palette.colors.gray.900',
+          container: 'palette.colors.gray.100',
+          text: 'palette.colors.gray.50',
+          textMuted: 'palette.colors.gray.500',
+          textInverse: 'palette.colors.gray.900',
+          border: 'palette.colors.gray.200',
+        },
+      },
+    },
+  },
+  warmVintage: {
+    description: 'Warm sepia tones with serif font and subtle radius',
+    theme: {
+      palette: {
+        colors: {
+          primary: { 500: '#b45309', 600: '#92400e' },
+          gray: {
+            50: '#fef3c7',
+            100: '#fef9c3',
+            200: '#d6d3d1',
+            500: '#78716c',
+            900: '#44403c',
+          },
+        },
+        radius: { sm: '0.125rem', md: '0.25rem', lg: '0.375rem' },
+        typography: {
+          fontFamily: {
+            sans: 'Georgia, Cambria, "Times New Roman", Times, serif',
+          },
+        },
+      },
+    },
+  },
+  neonCyberpunk: {
+    description:
+      'Neon on dark with monospace font — full semantic override for dark background',
+    theme: {
+      palette: {
+        colors: {
+          primary: { 500: '#f0abfc', 600: '#e879f9' },
+          accent: { 500: '#22d3ee', 600: '#06b6d4' },
+          gray: {
+            50: '#f0abfc',
+            100: '#1e0a3c',
+            200: '#3b0764',
+            500: '#c084fc',
+            900: '#0c0a1a',
+            950: '#050412',
+          },
+        },
+        radius: { sm: '0', md: '0.25rem', lg: '0.375rem' },
+        typography: {
+          fontFamily: {
+            sans: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+          },
+        },
+      },
+      semantic: {
+        colors: {
+          surface: 'palette.colors.gray.900',
+          background: 'palette.colors.gray.950',
+          container: 'palette.colors.gray.100',
+          text: 'palette.colors.gray.50',
+          textMuted: 'palette.colors.gray.500',
+          border: 'palette.colors.gray.200',
+        },
+      },
+    },
+  },
+  cleanRounded: {
+    description: 'Clean light theme with large radius and panel styling',
+    theme: {
+      palette: {
+        radius: {
+          sm: '6px',
+          md: '8px',
+          lg: '12px',
+          launcher: '50px',
+          button: '8px',
+        },
+      },
+      components: {
+        panel: { borderRadius: '16px', shadow: 'palette.shadows.2xl' },
+      },
+    },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Reference Payload
+// ---------------------------------------------------------------------------
+
+/**
+ * Complete theme reference payload for AI / MCP tool consumption.
+ *
+ * Returns token system docs, the default color palette and radius scale,
+ * example themes, and a list of SDK-bundled presets.
+ */
+export function getThemeReference() {
+  return {
+    tokenDocs: THEME_TOKEN_DOCS,
+    defaultColorPalette: DEFAULT_PALETTE.colors,
+    defaultRadius: DEFAULT_PALETTE.radius,
+    examples: THEME_EXAMPLES,
+    sdkPresets: ['shop', 'minimal', 'fullscreen'],
+  }
+}

package/src/types.ts

@@ -884,7 +884,11 @@ export type AgentWidgetClearChatConfig = {
 
 export type AgentWidgetStatusIndicatorConfig = {
   visible?: boolean;
+  /** Text alignment. Default: 'right'. */
+  align?: 'left' | 'center' | 'right';
   idleText?: string;
+  /** URL to open in a new tab when the idle text is clicked. */
+  idleLink?: string;
   connectingText?: string;
   connectedText?: string;
   errorText?: string;

package/src/ui.ts

@@ -604,6 +604,23 @@ export const createAgentExperience = (
     return statusCopy[status];
   };
 
+  /** Update statusText element, rendering a link for idle status when idleLink is configured. */
+  function applyStatusToElement(el: HTMLElement, text: string, statusCfg: typeof statusConfig, status: string): void {
+    if (status === "idle" && statusCfg.idleLink) {
+      el.textContent = "";
+      const link = document.createElement("a");
+      link.href = statusCfg.idleLink;
+      link.target = "_blank";
+      link.rel = "noopener noreferrer";
+      link.textContent = text;
+      link.style.color = "inherit";
+      link.style.textDecoration = "none";
+      el.appendChild(link);
+    } else {
+      el.textContent = text;
+    }
+  }
+
   const { wrapper, panel } = createWrapper(config);
   const panelElements = buildPanel(config, launcherEnabled);
   let {
@@ -2670,14 +2687,14 @@ export const createAgentExperience = (
     },
     onStatusChanged(status) {
       const currentStatusConfig = config.statusIndicator ?? {};
-      const getCurrentStatusText = (status: AgentWidgetSessionStatus): string => {
-        if (status === "idle") return currentStatusConfig.idleText ?? statusCopy.idle;
-        if (status === "connecting") return currentStatusConfig.connectingText ?? statusCopy.connecting;
-        if (status === "connected") return currentStatusConfig.connectedText ?? statusCopy.connected;
-        if (status === "error") return currentStatusConfig.errorText ?? statusCopy.error;
-        return statusCopy[status];
+      const getCurrentStatusText = (s: AgentWidgetSessionStatus): string => {
+        if (s === "idle") return currentStatusConfig.idleText ?? statusCopy.idle;
+        if (s === "connecting") return currentStatusConfig.connectingText ?? statusCopy.connecting;
+        if (s === "connected") return currentStatusConfig.connectedText ?? statusCopy.connected;
+        if (s === "error") return currentStatusConfig.errorText ?? statusCopy.error;
+        return statusCopy[s];
       };
-      statusText.textContent = getCurrentStatusText(status);
+      applyStatusToElement(statusText, getCurrentStatusText(status), currentStatusConfig, status);
     },
     onStreamingChanged(streaming) {
       isStreaming = streaming;
@@ -4815,14 +4832,14 @@ export const createAgentExperience = (
       // Update status text if status is currently set
       if (session) {
         const currentStatus = session.getStatus();
-        const getCurrentStatusText = (status: AgentWidgetSessionStatus): string => {
-          if (status === "idle") return statusIndicatorConfig.idleText ?? statusCopy.idle;
-          if (status === "connecting") return statusIndicatorConfig.connectingText ?? statusCopy.connecting;
-          if (status === "connected") return statusIndicatorConfig.connectedText ?? statusCopy.connected;
-          if (status === "error") return statusIndicatorConfig.errorText ?? statusCopy.error;
-          return statusCopy[status];
+        const getCurrentStatusText = (s: AgentWidgetSessionStatus): string => {
+          if (s === "idle") return statusIndicatorConfig.idleText ?? statusCopy.idle;
+          if (s === "connecting") return statusIndicatorConfig.connectingText ?? statusCopy.connecting;
+          if (s === "connected") return statusIndicatorConfig.connectedText ?? statusCopy.connected;
+          if (s === "error") return statusIndicatorConfig.errorText ?? statusCopy.error;
+          return statusCopy[s];
         };
-        statusText.textContent = getCurrentStatusText(currentStatus);
+        applyStatusToElement(statusText, getCurrentStatusText(currentStatus), statusIndicatorConfig, currentStatus);
       }
     },
     open() {