@runtypelabs/persona 2.1.0 → 2.3.0

package/dist/index.d.cts

@@ -638,6 +638,14 @@ 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;
 };
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
@@ -1480,6 +1488,12 @@ 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;
 };
 /**
  * Avatar configuration for message bubbles
@@ -2557,6 +2571,19 @@ type AgentWidgetConfig = {
      * ```
      */
     markdown?: AgentWidgetMarkdownConfig;
+    /**
+     * HTML sanitization for rendered message content.
+     *
+     * The widget renders AI-generated markdown as HTML. By default, all HTML
+     * output is sanitized using DOMPurify to prevent XSS attacks.
+     *
+     * - `true` (default): sanitize using built-in DOMPurify
+     * - `false`: disable sanitization (only use with fully trusted content sources)
+     * - `(html: string) => string`: custom sanitizer function
+     *
+     * @default true
+     */
+    sanitize?: boolean | ((html: string) => string);
     /**
      * Configuration for message action buttons (copy, upvote, downvote).
      * Shows action buttons on assistant messages for user feedback.
@@ -3632,6 +3659,24 @@ declare const createDirectivePostprocessor: (markdownConfig?: AgentWidgetMarkdow
  */
 declare const directivePostprocessor: (text: string) => string;
 
+/**
+ * A function that sanitizes an HTML string, returning safe HTML.
+ */
+type SanitizeFunction = (html: string) => string;
+/**
+ * Creates the default DOMPurify-based sanitizer.
+ * Uses the global window when available (browser).
+ */
+declare const createDefaultSanitizer: () => SanitizeFunction;
+/**
+ * Resolves a `sanitize` config value into a concrete function or null.
+ *
+ * - `undefined` / `true` → built-in DOMPurify sanitizer
+ * - `false` → `null` (no sanitization)
+ * - custom function → returned as-is
+ */
+declare const resolveSanitizer: (option: boolean | SanitizeFunction | undefined) => SanitizeFunction | null;
+
 /**
  * Plain text parser - passes through text as-is without any parsing.
  * This is the default parser.
@@ -4411,6 +4456,38 @@ interface ComposerChromeTokens {
     /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
     shadow: string;
 }
+/** Artifact toolbar chrome. */
+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. */
+interface ArtifactTabTokens {
+    background?: string;
+    activeBackground?: string;
+    activeBorder?: string;
+    borderRadius?: string;
+    textColor?: string;
+}
+/** Artifact pane chrome. */
+interface ArtifactPaneTokens {
+    toolbarBackground?: string;
+}
 interface ComponentTokens {
     button: ButtonTokens;
     input: InputTokens;
@@ -4426,6 +4503,12 @@ interface ComponentTokens {
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
     composer: ComposerChromeTokens;
+    /** Artifact toolbar, tab strip, and pane chrome. */
+    artifact?: {
+        toolbar?: ArtifactToolbarTokens;
+        tab?: ArtifactTabTokens;
+        pane?: ArtifactPaneTokens;
+    };
 }
 interface PaletteExtras {
     transitions?: Record<string, string>;
@@ -4645,6 +4728,22 @@ declare function resolveTokens(theme: PersonaTheme): Record<string, ResolvedToke
 declare function validateTheme(theme: Partial<PersonaTheme>): ThemeValidationResult;
 declare function createTheme(userConfig?: Partial<PersonaTheme>, options?: CreateThemeOptions): PersonaTheme;
 declare function themeToCssVariables(theme: PersonaTheme): Record<string, string>;
+/**
+ * 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.
+ */
+declare const THEME_ZONES: {
+    readonly header: "Widget header bar";
+    readonly messages: "Message list area";
+    readonly 'user-message': "User message bubble";
+    readonly 'assistant-message': "Assistant message bubble";
+    readonly composer: "Footer / composer area";
+    readonly container: "Main widget container";
+    readonly 'artifact-pane': "Artifact sidebar";
+    readonly 'artifact-toolbar': "Artifact toolbar";
+};
+type ThemeZone = keyof typeof THEME_ZONES;
 
 type ColorScheme = 'light' | 'dark' | 'auto';
 interface PersonaWidgetConfig {
@@ -4885,6 +4984,36 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
+/**
+ * A named preset containing partial widget configuration.
+ * Apply with: `createAgentExperience(el, { ...PRESET_SHOP.config, apiUrl: '...' })`
+ * or via IIFE: `{ ...AgentWidget.PRESETS.shop.config, apiUrl: '...' }`
+ */
+interface WidgetPreset {
+    id: string;
+    label: string;
+    config: Partial<AgentWidgetConfig>;
+}
+/**
+ * Shopping / e-commerce preset.
+ * Dark header, rounded launchers, shopping-oriented copy.
+ */
+declare const PRESET_SHOP: WidgetPreset;
+/**
+ * Minimal preset.
+ * Stripped-down header, no launcher button, suitable for inline embeds.
+ */
+declare const PRESET_MINIMAL: WidgetPreset;
+/**
+ * Fullscreen assistant preset.
+ * No launcher, content-max-width constrained, minimal header.
+ */
+declare const PRESET_FULLSCREEN: WidgetPreset;
+/** All named presets keyed by ID. */
+declare const PRESETS: Record<string, WidgetPreset>;
+/** Look up a preset by ID. */
+declare function getPreset(id: string): WidgetPreset | undefined;
+
 interface HeaderElements {
     header: HTMLElement;
     iconHolder: HTMLElement;
@@ -4975,4 +5104,4 @@ declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
 declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
 declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
 
-export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, type CreateThemeOptions, DEFAULT_COMPONENTS, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DomContextMode, type DomContextOptions, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, migrateV1Theme, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveTokens, themeToCssVariables, validateImageFile, validateTheme, validateV1Theme };
+export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, type CreateThemeOptions, DEFAULT_COMPONENTS, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DomContextMode, type DomContextOptions, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, migrateV1Theme, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, validateImageFile, validateTheme, validateV1Theme };

package/dist/index.d.ts

@@ -638,6 +638,14 @@ 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;
 };
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
@@ -1480,6 +1488,12 @@ 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;
 };
 /**
  * Avatar configuration for message bubbles
@@ -2557,6 +2571,19 @@ type AgentWidgetConfig = {
      * ```
      */
     markdown?: AgentWidgetMarkdownConfig;
+    /**
+     * HTML sanitization for rendered message content.
+     *
+     * The widget renders AI-generated markdown as HTML. By default, all HTML
+     * output is sanitized using DOMPurify to prevent XSS attacks.
+     *
+     * - `true` (default): sanitize using built-in DOMPurify
+     * - `false`: disable sanitization (only use with fully trusted content sources)
+     * - `(html: string) => string`: custom sanitizer function
+     *
+     * @default true
+     */
+    sanitize?: boolean | ((html: string) => string);
     /**
      * Configuration for message action buttons (copy, upvote, downvote).
      * Shows action buttons on assistant messages for user feedback.
@@ -3632,6 +3659,24 @@ declare const createDirectivePostprocessor: (markdownConfig?: AgentWidgetMarkdow
  */
 declare const directivePostprocessor: (text: string) => string;
 
+/**
+ * A function that sanitizes an HTML string, returning safe HTML.
+ */
+type SanitizeFunction = (html: string) => string;
+/**
+ * Creates the default DOMPurify-based sanitizer.
+ * Uses the global window when available (browser).
+ */
+declare const createDefaultSanitizer: () => SanitizeFunction;
+/**
+ * Resolves a `sanitize` config value into a concrete function or null.
+ *
+ * - `undefined` / `true` → built-in DOMPurify sanitizer
+ * - `false` → `null` (no sanitization)
+ * - custom function → returned as-is
+ */
+declare const resolveSanitizer: (option: boolean | SanitizeFunction | undefined) => SanitizeFunction | null;
+
 /**
  * Plain text parser - passes through text as-is without any parsing.
  * This is the default parser.
@@ -4411,6 +4456,38 @@ interface ComposerChromeTokens {
     /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
     shadow: string;
 }
+/** Artifact toolbar chrome. */
+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. */
+interface ArtifactTabTokens {
+    background?: string;
+    activeBackground?: string;
+    activeBorder?: string;
+    borderRadius?: string;
+    textColor?: string;
+}
+/** Artifact pane chrome. */
+interface ArtifactPaneTokens {
+    toolbarBackground?: string;
+}
 interface ComponentTokens {
     button: ButtonTokens;
     input: InputTokens;
@@ -4426,6 +4503,12 @@ interface ComponentTokens {
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
     composer: ComposerChromeTokens;
+    /** Artifact toolbar, tab strip, and pane chrome. */
+    artifact?: {
+        toolbar?: ArtifactToolbarTokens;
+        tab?: ArtifactTabTokens;
+        pane?: ArtifactPaneTokens;
+    };
 }
 interface PaletteExtras {
     transitions?: Record<string, string>;
@@ -4645,6 +4728,22 @@ declare function resolveTokens(theme: PersonaTheme): Record<string, ResolvedToke
 declare function validateTheme(theme: Partial<PersonaTheme>): ThemeValidationResult;
 declare function createTheme(userConfig?: Partial<PersonaTheme>, options?: CreateThemeOptions): PersonaTheme;
 declare function themeToCssVariables(theme: PersonaTheme): Record<string, string>;
+/**
+ * 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.
+ */
+declare const THEME_ZONES: {
+    readonly header: "Widget header bar";
+    readonly messages: "Message list area";
+    readonly 'user-message': "User message bubble";
+    readonly 'assistant-message': "Assistant message bubble";
+    readonly composer: "Footer / composer area";
+    readonly container: "Main widget container";
+    readonly 'artifact-pane': "Artifact sidebar";
+    readonly 'artifact-toolbar': "Artifact toolbar";
+};
+type ThemeZone = keyof typeof THEME_ZONES;
 
 type ColorScheme = 'light' | 'dark' | 'auto';
 interface PersonaWidgetConfig {
@@ -4885,6 +4984,36 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
+/**
+ * A named preset containing partial widget configuration.
+ * Apply with: `createAgentExperience(el, { ...PRESET_SHOP.config, apiUrl: '...' })`
+ * or via IIFE: `{ ...AgentWidget.PRESETS.shop.config, apiUrl: '...' }`
+ */
+interface WidgetPreset {
+    id: string;
+    label: string;
+    config: Partial<AgentWidgetConfig>;
+}
+/**
+ * Shopping / e-commerce preset.
+ * Dark header, rounded launchers, shopping-oriented copy.
+ */
+declare const PRESET_SHOP: WidgetPreset;
+/**
+ * Minimal preset.
+ * Stripped-down header, no launcher button, suitable for inline embeds.
+ */
+declare const PRESET_MINIMAL: WidgetPreset;
+/**
+ * Fullscreen assistant preset.
+ * No launcher, content-max-width constrained, minimal header.
+ */
+declare const PRESET_FULLSCREEN: WidgetPreset;
+/** All named presets keyed by ID. */
+declare const PRESETS: Record<string, WidgetPreset>;
+/** Look up a preset by ID. */
+declare function getPreset(id: string): WidgetPreset | undefined;
+
 interface HeaderElements {
     header: HTMLElement;
     iconHolder: HTMLElement;
@@ -4975,4 +5104,4 @@ declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
 declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
 declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
 
-export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, type CreateThemeOptions, DEFAULT_COMPONENTS, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DomContextMode, type DomContextOptions, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, migrateV1Theme, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveTokens, themeToCssVariables, validateImageFile, validateTheme, validateV1Theme };
+export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, type CreateThemeOptions, DEFAULT_COMPONENTS, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DomContextMode, type DomContextOptions, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, migrateV1Theme, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, validateImageFile, validateTheme, validateV1Theme };