@runtypelabs/persona 2.1.0 → 2.2.0

package/dist/widget.css

@@ -2064,9 +2064,9 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  padding: 0.25rem;
-  border-radius: var(--persona-radius-md, 0.375rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
+  padding: var(--persona-artifact-toolbar-icon-padding, 0.25rem);
+  border-radius: var(--persona-artifact-toolbar-icon-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-artifact-toolbar-icon-border, 1px solid var(--persona-border, #e5e7eb));
   background: var(--persona-surface, #ffffff);
   color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
   cursor: pointer;
@@ -2074,7 +2074,8 @@
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn:hover {
-  background: var(--persona-container, #f3f4f6);
+  color: var(--persona-artifact-toolbar-icon-hover-color, inherit);
+  background: var(--persona-artifact-toolbar-icon-hover-bg, var(--persona-container, #f3f4f6));
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn[aria-pressed="true"] {
@@ -2086,24 +2087,53 @@
   display: inline-flex;
   align-items: center;
   gap: 0.35rem;
-  padding: 0.25rem 0.5rem;
-  border-radius: var(--persona-radius-md, 0.375rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
-  background: var(--persona-surface, #ffffff);
-  color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
+  padding: var(--persona-artifact-toolbar-copy-padding, 0.25rem 0.5rem);
+  border-radius: var(--persona-artifact-toolbar-copy-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-artifact-toolbar-copy-border, 1px solid var(--persona-border, #e5e7eb));
+  background: var(--persona-artifact-toolbar-copy-bg, var(--persona-surface, #ffffff));
+  color: var(--persona-artifact-toolbar-copy-color, var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827)));
   cursor: pointer;
   font-size: 0.75rem;
   line-height: 1.25;
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-copy-btn:hover {
-  background: var(--persona-container, #f3f4f6);
+  background: var(--persona-artifact-toolbar-icon-hover-bg, var(--persona-container, #f3f4f6));
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-copy-label {
   font-weight: 500;
 }
 
+/* Copy menu dropdown theming */
+#persona-root .persona-artifact-doc-copy-menu {
+  background: var(--persona-artifact-toolbar-copy-menu-bg, var(--persona-surface, #fff));
+  border: var(--persona-artifact-toolbar-copy-menu-border, 1px solid var(--persona-border, #e5e7eb));
+  box-shadow: var(--persona-artifact-toolbar-copy-menu-shadow, 0 4px 6px -1px rgba(0,0,0,.1));
+  border-radius: var(--persona-artifact-toolbar-copy-menu-radius, 0.375rem);
+}
+
+#persona-root .persona-artifact-doc-copy-menu button:hover {
+  background: var(--persona-artifact-toolbar-copy-menu-item-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+/* Artifact tab theming */
+#persona-root .persona-artifact-tab {
+  background: var(--persona-artifact-tab-bg, transparent);
+  border-radius: var(--persona-artifact-tab-radius, 0.5rem);
+  color: var(--persona-artifact-tab-color, inherit);
+}
+
+#persona-root .persona-artifact-tab.persona-bg-persona-container {
+  background: var(--persona-artifact-tab-active-bg, var(--persona-container, #f3f4f6));
+  border-color: var(--persona-artifact-tab-active-border, var(--persona-border, #e5e7eb));
+}
+
+/* Artifact toolbar background theming */
+#persona-root .persona-artifact-toolbar {
+  background: var(--persona-artifact-toolbar-bg, var(--persona-surface, #fff));
+}
+
 /* Draggable split handle (desktop split only; hidden in drawer / narrow host / small viewport) */
 #persona-root .persona-artifact-split-handle {
   width: 6px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -47,6 +47,7 @@
   "engines": {
     "node": ">=18.17.0"
   },
+  "author": "Runtype",
   "license": "MIT",
   "keywords": [
     "ai",

package/src/client.ts

@@ -45,7 +45,6 @@ const DEFAULT_CLIENT_API_BASE = "https://api.runtype.com";
  * Check if a message has valid (non-empty) content for sending to the API.
  * Filters out messages with empty content that would cause validation errors.
  *
- * @see https://github.com/anthropics/claude-code/issues/XXX - Empty assistant messages from failed requests
  */
 const hasValidContent = (message: AgentWidgetMessage): boolean => {
   // Check contentParts (multi-modal content)

package/src/components/artifact-pane.ts

@@ -127,6 +127,7 @@ export function createArtifactPane(
     "aside",
     "persona-artifact-pane persona-flex persona-flex-col persona-min-h-0 persona-min-w-0 persona-bg-persona-surface persona-text-persona-primary persona-border-l persona-border-persona-border"
   );
+  shell.setAttribute("data-persona-theme-zone", "artifact-pane");
   if (documentChrome) {
     shell.classList.add("persona-artifact-pane-document");
   }
@@ -135,6 +136,7 @@ export function createArtifactPane(
     "div",
     "persona-artifact-toolbar persona-flex persona-items-center persona-justify-between persona-gap-2 persona-px-2 persona-py-2 persona-border-b persona-border-persona-border persona-shrink-0"
   );
+  toolbar.setAttribute("data-persona-theme-zone", "artifact-toolbar");
   if (documentChrome) {
     toolbar.classList.add("persona-artifact-toolbar-document");
   }

package/src/components/composer-builder.ts

@@ -68,6 +68,7 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     "div",
     "persona-widget-footer persona-border-t-persona-divider persona-bg-persona-surface persona-px-6 persona-py-4"
   );
+  footer.setAttribute("data-persona-theme-zone", "composer");
 
   const suggestions = createElement(
     "div",

package/src/components/header-builder.ts

@@ -31,6 +31,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
     "div",
     "persona-widget-header persona-flex persona-items-center persona-gap-3 persona-px-6 persona-py-5"
   );
+  header.setAttribute("data-persona-theme-zone", "header");
   header.style.backgroundColor = 'var(--persona-header-bg, var(--persona-surface, #ffffff))';
   header.style.borderBottomWidth = '1px';
   header.style.borderBottomStyle = 'solid';

package/src/components/header-layouts.ts

@@ -24,12 +24,32 @@ export type HeaderLayoutRenderer = (context: HeaderLayoutContext) => HeaderEleme
  * Full header with icon, title, subtitle, clear chat, and close button
  */
 export const buildDefaultHeader: HeaderLayoutRenderer = (context) => {
-  return buildHeader({
+  const elements = buildHeader({
     config: context.config,
     showClose: context.showClose,
     onClose: context.onClose,
     onClearChat: context.onClearChat
   });
+
+  // Make the title/subtitle area clickable when onTitleClick is provided
+  const onTitleClick = context.layoutHeaderConfig?.onTitleClick;
+  if (onTitleClick) {
+    const headerCopy = elements.headerTitle.parentElement;
+    if (headerCopy) {
+      headerCopy.style.cursor = "pointer";
+      headerCopy.setAttribute("role", "button");
+      headerCopy.setAttribute("tabindex", "0");
+      headerCopy.addEventListener("click", () => onTitleClick());
+      headerCopy.addEventListener("keydown", (e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onTitleClick();
+        }
+      });
+    }
+  }
+
+  return elements;
 };
 
 /**
@@ -68,6 +88,7 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
     "div",
     "persona-flex persona-items-center persona-justify-between persona-bg-persona-surface persona-px-6 persona-py-4 persona-border-b-persona-divider"
   );
+  header.setAttribute("data-persona-theme-zone", "header");
 
   const titleRow = createElement(
     "div",
@@ -85,6 +106,25 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
     layoutHeaderConfig?.onAction ?? onHeaderAction
   );
 
+  // Make title row clickable when onTitleClick is provided
+  if (layoutHeaderConfig?.onTitleClick) {
+    titleRow.style.cursor = "pointer";
+    titleRow.setAttribute("role", "button");
+    titleRow.setAttribute("tabindex", "0");
+    const handleTitleClick = layoutHeaderConfig.onTitleClick;
+    titleRow.addEventListener("click", (e) => {
+      // Skip if the click was on a trailing action button
+      if ((e.target as HTMLElement).closest("button")) return;
+      handleTitleClick();
+    });
+    titleRow.addEventListener("keydown", (e) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        handleTitleClick();
+      }
+    });
+  }
+
   header.appendChild(titleRow);
 
   // Close button

package/src/components/message-bubble.ts

@@ -470,6 +470,8 @@ export const createStandardBubble = (
   bubble.id = `bubble-${message.id}`;
   bubble.setAttribute("data-message-id", message.id);
 
+  bubble.setAttribute("data-persona-theme-zone", message.role === "user" ? "user-message" : "assistant-message");
+
   // Apply component-level color overrides via CSS variables
   if (message.role === "user") {
     bubble.style.backgroundColor = 'var(--persona-message-user-bg, var(--persona-accent))';

package/src/components/panel.ts

@@ -116,6 +116,7 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     "div",
     "persona-widget-container persona-flex persona-h-full persona-w-full persona-flex-1 persona-min-h-0 persona-flex-col persona-bg-persona-surface persona-text-persona-primary persona-rounded-2xl persona-overflow-hidden persona-border persona-border-persona-border"
   );
+  container.setAttribute("data-persona-theme-zone", "container");
 
   // Build header using layout config if available, otherwise use standard builder
   const headerLayoutConfig = config?.layout?.header;
@@ -130,6 +131,7 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     "persona-widget-body persona-flex persona-flex-1 persona-min-h-0 persona-flex-col persona-gap-6 persona-overflow-y-auto persona-bg-persona-container persona-px-6 persona-py-6"
   );
   body.id = "persona-scroll-container";
+  body.setAttribute("data-persona-theme-zone", "messages");
   
   const introCard = createElement(
     "div",

package/src/index.ts

@@ -189,8 +189,10 @@ export {
   DEFAULT_PALETTE,
   DEFAULT_SEMANTIC,
   DEFAULT_COMPONENTS,
-  validateTheme
+  validateTheme,
+  THEME_ZONES
 } from "./utils/tokens";
+export type { ThemeZone } from "./utils/tokens";
 export {
   accessibilityPlugin,
   animationsPlugin,
@@ -219,6 +221,9 @@ export type {
   SemanticSpacing,
   SemanticTypography,
   ComponentTokens,
+  ArtifactToolbarTokens,
+  ArtifactTabTokens,
+  ArtifactPaneTokens,
   ThemeValidationResult,
   ThemeValidationError
 } from "./types/theme";
@@ -245,6 +250,14 @@ export {
   DEFAULT_DARK_THEME,
   mergeWithDefaults
 } from "./defaults";
+export {
+  PRESETS,
+  getPreset,
+  PRESET_SHOP,
+  PRESET_MINIMAL,
+  PRESET_FULLSCREEN
+} from "./presets";
+export type { WidgetPreset } from "./presets";
 
 // Layout system exports
 export {

package/src/presets.ts

@@ -0,0 +1,127 @@
+import type { AgentWidgetConfig } from './types';
+
+/**
+ * A named preset containing partial widget configuration.
+ * Apply with: `createAgentExperience(el, { ...PRESET_SHOP.config, apiUrl: '...' })`
+ * or via IIFE: `{ ...AgentWidget.PRESETS.shop.config, apiUrl: '...' }`
+ */
+export interface WidgetPreset {
+  id: string;
+  label: string;
+  config: Partial<AgentWidgetConfig>;
+}
+
+/**
+ * Shopping / e-commerce preset.
+ * Dark header, rounded launchers, shopping-oriented copy.
+ */
+export const PRESET_SHOP: WidgetPreset = {
+  id: 'shop',
+  label: 'Shopping Assistant',
+  config: {
+    theme: {
+      primary: '#111827',
+      accent: '#1d4ed8',
+      surface: '#ffffff',
+      muted: '#6b7280',
+      container: '#f8fafc',
+      border: '#f1f5f9',
+      divider: '#f1f5f9',
+      messageBorder: '#f1f5f9',
+      inputBackground: '#ffffff',
+      callToAction: '#000000',
+      callToActionBackground: '#ffffff',
+      sendButtonBackgroundColor: '#111827',
+      sendButtonTextColor: '#ffffff',
+      radiusSm: '0.75rem',
+      radiusMd: '1rem',
+      radiusLg: '1.5rem',
+      launcherRadius: '9999px',
+      buttonRadius: '9999px',
+    },
+    launcher: {
+      title: 'Shopping Assistant',
+      subtitle: 'Here to help you find what you need',
+      agentIconText: '🛍️',
+      position: 'bottom-right',
+      width: 'min(400px, calc(100vw - 24px))',
+    },
+    copy: {
+      welcomeTitle: 'Welcome to our shop!',
+      welcomeSubtitle: 'I can help you find products and answer questions',
+      inputPlaceholder: 'Ask me anything...',
+      sendButtonLabel: 'Send',
+    },
+    suggestionChips: [
+      'What can you help me with?',
+      'Tell me about your features',
+      'How does this work?',
+    ],
+  },
+};
+
+/**
+ * Minimal preset.
+ * Stripped-down header, no launcher button, suitable for inline embeds.
+ */
+export const PRESET_MINIMAL: WidgetPreset = {
+  id: 'minimal',
+  label: 'Minimal',
+  config: {
+    launcher: {
+      enabled: false,
+      fullHeight: true,
+    },
+    layout: {
+      header: {
+        layout: 'minimal',
+        showCloseButton: false,
+      },
+      messages: {
+        layout: 'minimal',
+      },
+    },
+    theme: {
+      panelBorderRadius: '0',
+      panelShadow: 'none',
+    },
+  },
+};
+
+/**
+ * Fullscreen assistant preset.
+ * No launcher, content-max-width constrained, minimal header.
+ */
+export const PRESET_FULLSCREEN: WidgetPreset = {
+  id: 'fullscreen',
+  label: 'Fullscreen Assistant',
+  config: {
+    launcher: {
+      enabled: false,
+      fullHeight: true,
+    },
+    layout: {
+      header: {
+        layout: 'minimal',
+        showCloseButton: false,
+      },
+      contentMaxWidth: '72ch',
+    },
+    theme: {
+      panelBorderRadius: '0',
+      panelShadow: 'none',
+    },
+  },
+};
+
+/** All named presets keyed by ID. */
+export const PRESETS: Record<string, WidgetPreset> = {
+  shop: PRESET_SHOP,
+  minimal: PRESET_MINIMAL,
+  fullscreen: PRESET_FULLSCREEN,
+};
+
+/** Look up a preset by ID. */
+export function getPreset(id: string): WidgetPreset | undefined {
+  return PRESETS[id];
+}

package/src/styles/widget.css

@@ -2064,9 +2064,9 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  padding: 0.25rem;
-  border-radius: var(--persona-radius-md, 0.375rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
+  padding: var(--persona-artifact-toolbar-icon-padding, 0.25rem);
+  border-radius: var(--persona-artifact-toolbar-icon-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-artifact-toolbar-icon-border, 1px solid var(--persona-border, #e5e7eb));
   background: var(--persona-surface, #ffffff);
   color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
   cursor: pointer;
@@ -2074,7 +2074,8 @@
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn:hover {
-  background: var(--persona-container, #f3f4f6);
+  color: var(--persona-artifact-toolbar-icon-hover-color, inherit);
+  background: var(--persona-artifact-toolbar-icon-hover-bg, var(--persona-container, #f3f4f6));
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn[aria-pressed="true"] {
@@ -2086,24 +2087,53 @@
   display: inline-flex;
   align-items: center;
   gap: 0.35rem;
-  padding: 0.25rem 0.5rem;
-  border-radius: var(--persona-radius-md, 0.375rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
-  background: var(--persona-surface, #ffffff);
-  color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
+  padding: var(--persona-artifact-toolbar-copy-padding, 0.25rem 0.5rem);
+  border-radius: var(--persona-artifact-toolbar-copy-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-artifact-toolbar-copy-border, 1px solid var(--persona-border, #e5e7eb));
+  background: var(--persona-artifact-toolbar-copy-bg, var(--persona-surface, #ffffff));
+  color: var(--persona-artifact-toolbar-copy-color, var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827)));
   cursor: pointer;
   font-size: 0.75rem;
   line-height: 1.25;
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-copy-btn:hover {
-  background: var(--persona-container, #f3f4f6);
+  background: var(--persona-artifact-toolbar-icon-hover-bg, var(--persona-container, #f3f4f6));
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-copy-label {
   font-weight: 500;
 }
 
+/* Copy menu dropdown theming */
+#persona-root .persona-artifact-doc-copy-menu {
+  background: var(--persona-artifact-toolbar-copy-menu-bg, var(--persona-surface, #fff));
+  border: var(--persona-artifact-toolbar-copy-menu-border, 1px solid var(--persona-border, #e5e7eb));
+  box-shadow: var(--persona-artifact-toolbar-copy-menu-shadow, 0 4px 6px -1px rgba(0,0,0,.1));
+  border-radius: var(--persona-artifact-toolbar-copy-menu-radius, 0.375rem);
+}
+
+#persona-root .persona-artifact-doc-copy-menu button:hover {
+  background: var(--persona-artifact-toolbar-copy-menu-item-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+/* Artifact tab theming */
+#persona-root .persona-artifact-tab {
+  background: var(--persona-artifact-tab-bg, transparent);
+  border-radius: var(--persona-artifact-tab-radius, 0.5rem);
+  color: var(--persona-artifact-tab-color, inherit);
+}
+
+#persona-root .persona-artifact-tab.persona-bg-persona-container {
+  background: var(--persona-artifact-tab-active-bg, var(--persona-container, #f3f4f6));
+  border-color: var(--persona-artifact-tab-active-border, var(--persona-border, #e5e7eb));
+}
+
+/* Artifact toolbar background theming */
+#persona-root .persona-artifact-toolbar {
+  background: var(--persona-artifact-toolbar-bg, var(--persona-surface, #fff));
+}
+
 /* Draggable split handle (desktop split only; hidden in drawer / narrow host / small viewport) */
 #persona-root .persona-artifact-split-handle {
   width: 6px;

package/src/types/theme.ts

@@ -298,6 +298,41 @@ export interface ComposerChromeTokens {
   shadow: string;
 }
 
+/** Artifact toolbar chrome. */
+export interface ArtifactToolbarTokens {
+  iconHoverColor?: string;
+  iconHoverBackground?: string;
+  iconPadding?: string;
+  iconBorderRadius?: string;
+  iconBorder?: string;
+  toggleGroupGap?: string;
+  toggleBorderRadius?: string;
+  copyBackground?: string;
+  copyBorder?: string;
+  copyColor?: string;
+  copyBorderRadius?: string;
+  copyPadding?: string;
+  copyMenuBackground?: string;
+  copyMenuBorder?: string;
+  copyMenuShadow?: string;
+  copyMenuBorderRadius?: string;
+  copyMenuItemHoverBackground?: string;
+}
+
+/** Artifact tab strip chrome. */
+export interface ArtifactTabTokens {
+  background?: string;
+  activeBackground?: string;
+  activeBorder?: string;
+  borderRadius?: string;
+  textColor?: string;
+}
+
+/** Artifact pane chrome. */
+export interface ArtifactPaneTokens {
+  toolbarBackground?: string;
+}
+
 export interface ComponentTokens {
   button: ButtonTokens;
   input: InputTokens;
@@ -313,6 +348,12 @@ export interface ComponentTokens {
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
   composer: ComposerChromeTokens;
+  /** Artifact toolbar, tab strip, and pane chrome. */
+  artifact?: {
+    toolbar?: ArtifactToolbarTokens;
+    tab?: ArtifactTabTokens;
+    pane?: ArtifactPaneTokens;
+  };
 }
 
 export interface PaletteExtras {

package/src/types.ts

@@ -525,6 +525,14 @@ export type AgentWidgetArtifactsFeature = {
   allowedTypes?: PersonaArtifactKind[];
   /** Split / drawer dimensions and launcher widen behavior */
   layout?: AgentWidgetArtifactsLayoutConfig;
+  /**
+   * Called when an artifact card action is triggered (open, download).
+   * Return `true` to prevent the default behavior.
+   */
+  onArtifactAction?: (action: {
+    type: 'open' | 'download';
+    artifactId: string;
+  }) => boolean | void;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -1452,6 +1460,12 @@ export type AgentWidgetHeaderLayoutConfig = {
   trailingActions?: AgentWidgetHeaderTrailingAction[];
   /** Called when a `trailingActions` button is clicked. */
   onAction?: (actionId: string) => void;
+  /**
+   * Called when the header title row is clicked.
+   * Useful for dropdown menus or navigation triggered from the header.
+   * When set, the title row becomes visually interactive (cursor: pointer).
+   */
+  onTitleClick?: () => void;
 };
 
 /**

package/src/ui.ts

@@ -1142,6 +1142,9 @@ export const createAgentExperience = (
     event.stopPropagation();
     const artifactId = dlBtn.getAttribute('data-download-artifact');
     if (!artifactId) return;
+    // Let integrator intercept
+    const dlPrevented = config.features?.artifacts?.onArtifactAction?.({ type: 'download', artifactId });
+    if (dlPrevented === true) return;
     // Try session state first, fall back to content stored in the card's rawContent props
     const artifact = session.getArtifactById(artifactId);
     let markdown = artifact?.markdown;
@@ -1180,6 +1183,9 @@ export const createAgentExperience = (
     if (!card) return;
     const artifactId = card.getAttribute('data-open-artifact');
     if (!artifactId) return;
+    // Let integrator intercept
+    const openPrevented = config.features?.artifacts?.onArtifactAction?.({ type: 'open', artifactId });
+    if (openPrevented === true) return;
     event.preventDefault();
     event.stopPropagation();
     session.selectArtifact(artifactId);
@@ -3560,6 +3566,8 @@ export const createAgentExperience = (
       const previousMessageActions = config.messageActions;
       const previousLayoutMessages = config.layout?.messages;
       const previousColorScheme = config.colorScheme;
+      const previousLoadingIndicator = config.loadingIndicator;
+      const previousIterationDisplay = config.iterationDisplay;
       config = { ...config, ...nextConfig };
       // applyFullHeightStyles resets mount.style.cssText, so call it before applyThemeVariables
       applyFullHeightStyles();
@@ -3790,7 +3798,12 @@ export const createAgentExperience = (
       const toolCallConfigChanged = JSON.stringify(nextConfig.toolCall) !== JSON.stringify(previousToolCallConfig);
       const messageActionsChanged = JSON.stringify(config.messageActions) !== JSON.stringify(previousMessageActions);
       const layoutMessagesChanged = JSON.stringify(config.layout?.messages) !== JSON.stringify(previousLayoutMessages);
-      const messagesConfigChanged = toolCallConfigChanged || messageActionsChanged || layoutMessagesChanged;
+      const loadingIndicatorChanged = config.loadingIndicator?.render !== previousLoadingIndicator?.render
+        || config.loadingIndicator?.renderIdle !== previousLoadingIndicator?.renderIdle
+        || config.loadingIndicator?.showBubble !== previousLoadingIndicator?.showBubble;
+      const iterationDisplayChanged = config.iterationDisplay !== previousIterationDisplay;
+      const messagesConfigChanged = toolCallConfigChanged || messageActionsChanged || layoutMessagesChanged
+        || loadingIndicatorChanged || iterationDisplayChanged;
       if (messagesConfigChanged && session) {
         configVersion++;
         renderMessagesWithPlugins(messagesWrapper, session.getMessages(), postprocess);

package/src/utils/tokens.ts

@@ -689,6 +689,42 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-md-prose-font-family'] = mdProseFont;
   }
 
+  // Artifact tokens
+  const components = theme.components;
+  const artifact = components?.artifact;
+  if (artifact?.toolbar) {
+    const t = artifact.toolbar;
+    if (t.iconHoverColor) cssVars['--persona-artifact-toolbar-icon-hover-color'] = t.iconHoverColor;
+    if (t.iconHoverBackground) cssVars['--persona-artifact-toolbar-icon-hover-bg'] = t.iconHoverBackground;
+    if (t.iconPadding) cssVars['--persona-artifact-toolbar-icon-padding'] = t.iconPadding;
+    if (t.iconBorderRadius) cssVars['--persona-artifact-toolbar-icon-radius'] = t.iconBorderRadius;
+    if (t.iconBorder) cssVars['--persona-artifact-toolbar-icon-border'] = t.iconBorder;
+    if (t.toggleGroupGap) cssVars['--persona-artifact-toolbar-toggle-group-gap'] = t.toggleGroupGap;
+    if (t.toggleBorderRadius) cssVars['--persona-artifact-toolbar-toggle-radius'] = t.toggleBorderRadius;
+    if (t.copyBackground) cssVars['--persona-artifact-toolbar-copy-bg'] = t.copyBackground;
+    if (t.copyBorder) cssVars['--persona-artifact-toolbar-copy-border'] = t.copyBorder;
+    if (t.copyColor) cssVars['--persona-artifact-toolbar-copy-color'] = t.copyColor;
+    if (t.copyBorderRadius) cssVars['--persona-artifact-toolbar-copy-radius'] = t.copyBorderRadius;
+    if (t.copyPadding) cssVars['--persona-artifact-toolbar-copy-padding'] = t.copyPadding;
+    if (t.copyMenuBackground) cssVars['--persona-artifact-toolbar-copy-menu-bg'] = t.copyMenuBackground;
+    if (t.copyMenuBorder) cssVars['--persona-artifact-toolbar-copy-menu-border'] = t.copyMenuBorder;
+    if (t.copyMenuShadow) cssVars['--persona-artifact-toolbar-copy-menu-shadow'] = t.copyMenuShadow;
+    if (t.copyMenuBorderRadius) cssVars['--persona-artifact-toolbar-copy-menu-radius'] = t.copyMenuBorderRadius;
+    if (t.copyMenuItemHoverBackground) cssVars['--persona-artifact-toolbar-copy-menu-item-hover-bg'] = t.copyMenuItemHoverBackground;
+  }
+  if (artifact?.tab) {
+    const t = artifact.tab;
+    if (t.background) cssVars['--persona-artifact-tab-bg'] = t.background;
+    if (t.activeBackground) cssVars['--persona-artifact-tab-active-bg'] = t.activeBackground;
+    if (t.activeBorder) cssVars['--persona-artifact-tab-active-border'] = t.activeBorder;
+    if (t.borderRadius) cssVars['--persona-artifact-tab-radius'] = t.borderRadius;
+    if (t.textColor) cssVars['--persona-artifact-tab-color'] = t.textColor;
+  }
+  if (artifact?.pane) {
+    const t = artifact.pane;
+    if (t.toolbarBackground) cssVars['--persona-artifact-toolbar-bg'] = t.toolbarBackground;
+  }
+
   return cssVars;
 }
 
@@ -699,3 +735,21 @@ export function applyThemeVariables(element: HTMLElement, theme: PersonaTheme):
     element.style.setProperty(name, value);
   }
 }
+
+/**
+ * Stable `data-persona-theme-zone` values applied to key widget regions.
+ * Visual editors should use `[data-persona-theme-zone="header"]` selectors
+ * rather than internal class names.
+ */
+export const THEME_ZONES = {
+  header: 'Widget header bar',
+  messages: 'Message list area',
+  'user-message': 'User message bubble',
+  'assistant-message': 'Assistant message bubble',
+  composer: 'Footer / composer area',
+  container: 'Main widget container',
+  'artifact-pane': 'Artifact sidebar',
+  'artifact-toolbar': 'Artifact toolbar',
+} as const;
+
+export type ThemeZone = keyof typeof THEME_ZONES;