@runtypelabs/persona 4.12.0 → 4.14.0

package/dist/theme-editor.d.cts

@@ -1968,6 +1968,14 @@ type AgentToolsConfig = {
 };
 /** Artifact kinds for the Persona sidebar and dispatch payload */
 type PersonaArtifactKind = "markdown" | "component";
+type PersonaArtifactPresentation = {
+    /**
+     * Producer hint for where this artifact renders (content-disposition
+     * model). Beats configured defaults; loses to explicit `files`/`byKind`
+     * rules. Persona never infers it; the producer or host supplies it.
+     */
+    preferredMode?: PersonaArtifactDisplayModeInput;
+};
 /**
  * Agent configuration for agent execution mode.
  * When provided in the widget config, enables agent loop execution instead of flow dispatch.
@@ -2496,7 +2504,48 @@ type AgentWidgetArtifactsLayoutConfig = {
         jsonPayload: string;
     }) => void | Promise<void>;
 };
-type PersonaArtifactDisplayMode = "card" | "panel" | "inline";
+/**
+ * Where the artifact body renders by default. Every mode shows the compact
+ * reference in the transcript; the mode names where the body goes:
+ * nowhere yet (`collapsed`), the side panel (`panel`), or the conversation
+ * itself (`inline`).
+ */
+type PersonaArtifactDisplayMode = "collapsed" | "panel" | "inline";
+/**
+ * Accepted wherever a display mode is written. `"card"` is a deprecated
+ * alias of `"collapsed"` (the old name described the reference card, which
+ * every mode shows, instead of where the body renders). Resolution and
+ * parsing always canonicalize to `"collapsed"`.
+ */
+type PersonaArtifactDisplayModeInput = PersonaArtifactDisplayMode | "card";
+/**
+ * Display rules for file-backed artifacts. `byMediaType` keys are exact MIME
+ * types (`"text/html"`) or major-type wildcards (`"image/*"`), matched
+ * case-insensitively without parameters; exact beats wildcard.
+ */
+type PersonaArtifactFilesDisplayRules = {
+    default?: PersonaArtifactDisplayModeInput;
+    byMediaType?: Record<string, PersonaArtifactDisplayModeInput>;
+};
+/**
+ * Scoped artifact display rules. Matching resolves from the most specific
+ * selector to `default`; see `resolveArtifactDisplay`.
+ *
+ * Across preference layers, one merge rule applies everywhere: a string value
+ * replaces the whole subtree it names; an object refines it per key. So
+ * `files: "inline"` overrides every lower-layer file rule, while
+ * `files: { default: "inline" }` keeps lower-layer MIME exceptions.
+ */
+type PersonaArtifactDisplayRules = {
+    default?: PersonaArtifactDisplayModeInput;
+    byKind?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>>;
+    /**
+     * @deprecated Use `byKind`. When both are present, `byKind` wins.
+     */
+    byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>>;
+    /** Rules for any artifact carrying file metadata. */
+    files?: PersonaArtifactDisplayModeInput | PersonaArtifactFilesDisplayRules;
+};
 /** Context handed to custom artifact actions. Content fields are best-effort: resolved from live session state or, after a refresh, from the persisted reference-card payload. */
 type PersonaArtifactActionContext = {
     artifactId: string | null;
@@ -2553,13 +2602,10 @@ type AgentWidgetArtifactsFeature = {
     allowedTypes?: PersonaArtifactKind[];
     /**
      * Where artifact bodies render. A single mode applies to all artifacts;
-     * the object form sets a default plus per-type overrides.
+     * the object form sets a default plus scoped overrides.
      * Defaults to "panel" (current behavior).
      */
-    display?: PersonaArtifactDisplayMode | {
-        default?: PersonaArtifactDisplayMode;
-        byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayMode>>;
-    };
+    display?: PersonaArtifactDisplayModeInput | PersonaArtifactDisplayRules;
     /** Split / drawer dimensions and launcher widen behavior */
     layout?: AgentWidgetArtifactsLayoutConfig;
     /**
@@ -3288,6 +3334,46 @@ type AgentWidgetFeatureFlags = {
      */
     suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
+type WidgetPreferenceCapabilities = {
+    artifacts?: boolean;
+    tools?: boolean;
+    reasoning?: boolean;
+};
+/**
+ * Persistable artifact-layout choices. The full layout config deliberately is
+ * not exposed because it also contains callbacks and embedder-owned chrome.
+ */
+type WidgetArtifactLayoutPreference = Pick<AgentWidgetArtifactsLayoutConfig, "paneWidth" | "paneMaxWidth" | "paneMinWidth" | "expandLauncherPanelWhenOpen" | "expandedPanelWidth" | "resizable" | "resizableMinWidth" | "resizableMaxWidth">;
+/**
+ * Curated, JSON-serializable display preferences in native `features` shape.
+ *
+ * Absence means inherit the next preference layer and ultimately Persona's
+ * current default. Persist only explicit choices; resetting a choice deletes
+ * its key.
+ *
+ * Capability facts (`artifacts.enabled`, `allowedTypes`), trusted iframe
+ * security, callbacks, actions, renderers, labels, and theme styling are
+ * intentionally excluded because they remain embedder/code-owned.
+ */
+type WidgetPreferenceSlice = {
+    showToolCalls?: boolean;
+    showReasoning?: boolean;
+    toolCallDisplay?: Pick<AgentWidgetToolCallDisplayFeature, "collapsedMode" | "expandable" | "grouped" | "groupedMode" | "loadingAnimation">;
+    reasoningDisplay?: Pick<AgentWidgetReasoningDisplayFeature, "expandable" | "activePreview">;
+    artifacts?: {
+        /**
+         * String and object forms are both persistable and mean different things
+         * when layers merge: a string replaces every lower-layer display rule; an
+         * object refines lower layers per selector key (same rule applies to
+         * `display.files`).
+         */
+        display?: PersonaArtifactDisplayModeInput | PersonaArtifactDisplayRules;
+        filePreview?: {
+            enabled?: boolean;
+        };
+        layout?: WidgetArtifactLayoutPreference;
+    };
+};
 /**
  * Feature config for the built-in `suggest_replies` quick-reply chips.
  * Chips render in the existing suggestions slot above the composer and are
@@ -5729,6 +5815,15 @@ type AgentWidgetConfig = {
      */
     colorScheme?: 'auto' | 'light' | 'dark';
     features?: AgentWidgetFeatureFlags;
+    /**
+     * Per-instance display overrides, applied over `features` through the
+     * preference allowlist (security/capability keys cannot pass). String
+     * `display` values replace the base rule subtree; objects refine it per
+     * key. Each `controller.update({ preferences })` replaces the previous
+     * slice wholesale (dropped keys revert to the base `features`); an
+     * explicit-undefined patch clears it entirely.
+     */
+    preferences?: WidgetPreferenceSlice;
     /**
      * When true, focus the chat input after the panel opens and the open animation completes.
      * Applies to launcher mode (user click, controller.open(), autoExpand) and inline mode (on init).
@@ -6489,6 +6584,8 @@ type PersonaArtifactRecord = {
     props?: Record<string, unknown>;
     /** Present when this markdown artifact is a previewable file (see PersonaArtifactFileMeta). */
     file?: PersonaArtifactFileMeta;
+    /** Optional presentation metadata such as the producer's display-mode hint. */
+    presentation?: PersonaArtifactPresentation;
 };
 
 /** Field definition types for the declarative configurator system (headless: no DOM) */
@@ -6569,6 +6666,12 @@ interface FieldDef {
     formatValue?: (value: unknown) => unknown;
     /** Convert control input back into the stored value shape */
     parseValue?: (value: unknown) => unknown;
+    /** Capability required for hosts to render this field. */
+    requiresCapability?: keyof WidgetPreferenceCapabilities;
+    /** The host may offer an inherit/reset action which deletes this path. */
+    unsettable?: boolean;
+    /** Label for the inherit/reset action. Default: "Use default". */
+    unsetLabel?: string;
 }
 interface SectionDef {
     id: string;
@@ -6579,6 +6682,8 @@ interface SectionDef {
     collapsed?: boolean;
     /** Preset buttons for this section */
     presets?: SectionPreset[];
+    /** Capability required for hosts to render this section. */
+    requiresCapability?: keyof WidgetPreferenceCapabilities;
 }
 interface SectionPreset {
     id: string;
@@ -6609,6 +6714,8 @@ interface ThemeEditorPreset {
     toolCall?: AgentWidgetToolCallConfig;
     /** Tool call styling for dark mode (falls back to toolCall if not set) */
     darkToolCall?: AgentWidgetToolCallConfig;
+    /** Sparse, persistable widget behavior layered separately from theme tokens. */
+    behavior?: WidgetPreferenceSlice;
     preview: {
         primary: string;
         surface: string;
@@ -6659,6 +6766,8 @@ declare class ThemeEditorState {
      * - everything else → writes into AgentWidgetConfig
      */
     set(path: string, value: unknown): void;
+    /** Delete a dot-path and prune empty parents so sparse preferences inherit. */
+    unset(path: string): void;
     /** Batch-set multiple paths at once */
     setBatch(updates: Record<string, unknown>): void;
     /** Replace the entire theme */
@@ -6695,6 +6804,8 @@ declare const COMPONENT_SHAPE_SECTIONS: SectionDef[];
 /** Component color sections (can be scoped for light/dark) */
 declare const COMPONENT_COLOR_SECTIONS: SectionDef[];
 declare const COMPONENTS_SECTIONS: SectionDef[];
+declare const ARTIFACT_DISPLAY_PREFERENCE_SECTION: SectionDef;
+declare const STREAM_AND_ARTIFACTS_SUB_GROUP: SubGroupDef;
 declare const CONFIGURE_SUB_GROUPS: SubGroupDef[];
 declare const CONFIGURE_SECTIONS: SectionDef[];
 /** Section 1: Theme: color mode selection */
@@ -6812,6 +6923,22 @@ interface PreviewConfigOptions {
 declare function buildPreviewConfig(options: PreviewConfigOptions, shellModeOverride?: 'light' | 'dark'): AgentWidgetConfig;
 declare function buildPreviewConfigWithMessages(options: PreviewConfigOptions, messages: AgentWidgetMessage[], shellModeOverride?: 'light' | 'dark'): AgentWidgetConfig;
 
+/**
+ * Imperative preview renderer for the theme editor.
+ * Import from `@runtypelabs/persona/theme-editor/preview` (not the headless
+ * `@runtypelabs/persona/theme-editor` subpath, which omits the widget runtime).
+ *
+ * Manages iframe-based widget previews with device frames, zoom, scenes, and compare mode.
+ * No external DOM dependencies: only needs a container element to mount into.
+ *
+ * For advanced preview needs (background URLs, inline editing, contrast checking),
+ * use the lifecycle hooks in `ThemePreviewOptions` and import shared building blocks
+ * from `./preview-utils` directly.
+ */
+
+type PreviewShellMode = 'light' | 'dark';
+type CompareMode = 'off' | 'baseline' | 'themes';
+
 /**
  * Interface Role → Token mapping layer.
  *
@@ -7104,4 +7231,4 @@ declare function runContrastChecks(state: ThemeEditorLike, level?: ContrastLevel
 /** Compact contrast warnings for the regions a mutation touched. */
 declare function quickContrastWarnings(state: ThemeEditorLike, pairKeys: string[], variant?: 'light' | 'dark' | 'both', level?: ContrastLevel): ContrastWarning[];
 
-export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewScene, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolContent, type ToolExecute, type ToolImageContent, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };
+export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, ARTIFACT_DISPLAY_PREFERENCE_SECTION, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STREAM_AND_ARTIFACTS_SUB_GROUP, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolContent, type ToolExecute, type ToolImageContent, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };

package/dist/theme-editor.d.ts

@@ -1968,6 +1968,14 @@ type AgentToolsConfig = {
 };
 /** Artifact kinds for the Persona sidebar and dispatch payload */
 type PersonaArtifactKind = "markdown" | "component";
+type PersonaArtifactPresentation = {
+    /**
+     * Producer hint for where this artifact renders (content-disposition
+     * model). Beats configured defaults; loses to explicit `files`/`byKind`
+     * rules. Persona never infers it; the producer or host supplies it.
+     */
+    preferredMode?: PersonaArtifactDisplayModeInput;
+};
 /**
  * Agent configuration for agent execution mode.
  * When provided in the widget config, enables agent loop execution instead of flow dispatch.
@@ -2496,7 +2504,48 @@ type AgentWidgetArtifactsLayoutConfig = {
         jsonPayload: string;
     }) => void | Promise<void>;
 };
-type PersonaArtifactDisplayMode = "card" | "panel" | "inline";
+/**
+ * Where the artifact body renders by default. Every mode shows the compact
+ * reference in the transcript; the mode names where the body goes:
+ * nowhere yet (`collapsed`), the side panel (`panel`), or the conversation
+ * itself (`inline`).
+ */
+type PersonaArtifactDisplayMode = "collapsed" | "panel" | "inline";
+/**
+ * Accepted wherever a display mode is written. `"card"` is a deprecated
+ * alias of `"collapsed"` (the old name described the reference card, which
+ * every mode shows, instead of where the body renders). Resolution and
+ * parsing always canonicalize to `"collapsed"`.
+ */
+type PersonaArtifactDisplayModeInput = PersonaArtifactDisplayMode | "card";
+/**
+ * Display rules for file-backed artifacts. `byMediaType` keys are exact MIME
+ * types (`"text/html"`) or major-type wildcards (`"image/*"`), matched
+ * case-insensitively without parameters; exact beats wildcard.
+ */
+type PersonaArtifactFilesDisplayRules = {
+    default?: PersonaArtifactDisplayModeInput;
+    byMediaType?: Record<string, PersonaArtifactDisplayModeInput>;
+};
+/**
+ * Scoped artifact display rules. Matching resolves from the most specific
+ * selector to `default`; see `resolveArtifactDisplay`.
+ *
+ * Across preference layers, one merge rule applies everywhere: a string value
+ * replaces the whole subtree it names; an object refines it per key. So
+ * `files: "inline"` overrides every lower-layer file rule, while
+ * `files: { default: "inline" }` keeps lower-layer MIME exceptions.
+ */
+type PersonaArtifactDisplayRules = {
+    default?: PersonaArtifactDisplayModeInput;
+    byKind?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>>;
+    /**
+     * @deprecated Use `byKind`. When both are present, `byKind` wins.
+     */
+    byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>>;
+    /** Rules for any artifact carrying file metadata. */
+    files?: PersonaArtifactDisplayModeInput | PersonaArtifactFilesDisplayRules;
+};
 /** Context handed to custom artifact actions. Content fields are best-effort: resolved from live session state or, after a refresh, from the persisted reference-card payload. */
 type PersonaArtifactActionContext = {
     artifactId: string | null;
@@ -2553,13 +2602,10 @@ type AgentWidgetArtifactsFeature = {
     allowedTypes?: PersonaArtifactKind[];
     /**
      * Where artifact bodies render. A single mode applies to all artifacts;
-     * the object form sets a default plus per-type overrides.
+     * the object form sets a default plus scoped overrides.
      * Defaults to "panel" (current behavior).
      */
-    display?: PersonaArtifactDisplayMode | {
-        default?: PersonaArtifactDisplayMode;
-        byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayMode>>;
-    };
+    display?: PersonaArtifactDisplayModeInput | PersonaArtifactDisplayRules;
     /** Split / drawer dimensions and launcher widen behavior */
     layout?: AgentWidgetArtifactsLayoutConfig;
     /**
@@ -3288,6 +3334,46 @@ type AgentWidgetFeatureFlags = {
      */
     suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
+type WidgetPreferenceCapabilities = {
+    artifacts?: boolean;
+    tools?: boolean;
+    reasoning?: boolean;
+};
+/**
+ * Persistable artifact-layout choices. The full layout config deliberately is
+ * not exposed because it also contains callbacks and embedder-owned chrome.
+ */
+type WidgetArtifactLayoutPreference = Pick<AgentWidgetArtifactsLayoutConfig, "paneWidth" | "paneMaxWidth" | "paneMinWidth" | "expandLauncherPanelWhenOpen" | "expandedPanelWidth" | "resizable" | "resizableMinWidth" | "resizableMaxWidth">;
+/**
+ * Curated, JSON-serializable display preferences in native `features` shape.
+ *
+ * Absence means inherit the next preference layer and ultimately Persona's
+ * current default. Persist only explicit choices; resetting a choice deletes
+ * its key.
+ *
+ * Capability facts (`artifacts.enabled`, `allowedTypes`), trusted iframe
+ * security, callbacks, actions, renderers, labels, and theme styling are
+ * intentionally excluded because they remain embedder/code-owned.
+ */
+type WidgetPreferenceSlice = {
+    showToolCalls?: boolean;
+    showReasoning?: boolean;
+    toolCallDisplay?: Pick<AgentWidgetToolCallDisplayFeature, "collapsedMode" | "expandable" | "grouped" | "groupedMode" | "loadingAnimation">;
+    reasoningDisplay?: Pick<AgentWidgetReasoningDisplayFeature, "expandable" | "activePreview">;
+    artifacts?: {
+        /**
+         * String and object forms are both persistable and mean different things
+         * when layers merge: a string replaces every lower-layer display rule; an
+         * object refines lower layers per selector key (same rule applies to
+         * `display.files`).
+         */
+        display?: PersonaArtifactDisplayModeInput | PersonaArtifactDisplayRules;
+        filePreview?: {
+            enabled?: boolean;
+        };
+        layout?: WidgetArtifactLayoutPreference;
+    };
+};
 /**
  * Feature config for the built-in `suggest_replies` quick-reply chips.
  * Chips render in the existing suggestions slot above the composer and are
@@ -5729,6 +5815,15 @@ type AgentWidgetConfig = {
      */
     colorScheme?: 'auto' | 'light' | 'dark';
     features?: AgentWidgetFeatureFlags;
+    /**
+     * Per-instance display overrides, applied over `features` through the
+     * preference allowlist (security/capability keys cannot pass). String
+     * `display` values replace the base rule subtree; objects refine it per
+     * key. Each `controller.update({ preferences })` replaces the previous
+     * slice wholesale (dropped keys revert to the base `features`); an
+     * explicit-undefined patch clears it entirely.
+     */
+    preferences?: WidgetPreferenceSlice;
     /**
      * When true, focus the chat input after the panel opens and the open animation completes.
      * Applies to launcher mode (user click, controller.open(), autoExpand) and inline mode (on init).
@@ -6489,6 +6584,8 @@ type PersonaArtifactRecord = {
     props?: Record<string, unknown>;
     /** Present when this markdown artifact is a previewable file (see PersonaArtifactFileMeta). */
     file?: PersonaArtifactFileMeta;
+    /** Optional presentation metadata such as the producer's display-mode hint. */
+    presentation?: PersonaArtifactPresentation;
 };
 
 /** Field definition types for the declarative configurator system (headless: no DOM) */
@@ -6569,6 +6666,12 @@ interface FieldDef {
     formatValue?: (value: unknown) => unknown;
     /** Convert control input back into the stored value shape */
     parseValue?: (value: unknown) => unknown;
+    /** Capability required for hosts to render this field. */
+    requiresCapability?: keyof WidgetPreferenceCapabilities;
+    /** The host may offer an inherit/reset action which deletes this path. */
+    unsettable?: boolean;
+    /** Label for the inherit/reset action. Default: "Use default". */
+    unsetLabel?: string;
 }
 interface SectionDef {
     id: string;
@@ -6579,6 +6682,8 @@ interface SectionDef {
     collapsed?: boolean;
     /** Preset buttons for this section */
     presets?: SectionPreset[];
+    /** Capability required for hosts to render this section. */
+    requiresCapability?: keyof WidgetPreferenceCapabilities;
 }
 interface SectionPreset {
     id: string;
@@ -6609,6 +6714,8 @@ interface ThemeEditorPreset {
     toolCall?: AgentWidgetToolCallConfig;
     /** Tool call styling for dark mode (falls back to toolCall if not set) */
     darkToolCall?: AgentWidgetToolCallConfig;
+    /** Sparse, persistable widget behavior layered separately from theme tokens. */
+    behavior?: WidgetPreferenceSlice;
     preview: {
         primary: string;
         surface: string;
@@ -6659,6 +6766,8 @@ declare class ThemeEditorState {
      * - everything else → writes into AgentWidgetConfig
      */
     set(path: string, value: unknown): void;
+    /** Delete a dot-path and prune empty parents so sparse preferences inherit. */
+    unset(path: string): void;
     /** Batch-set multiple paths at once */
     setBatch(updates: Record<string, unknown>): void;
     /** Replace the entire theme */
@@ -6695,6 +6804,8 @@ declare const COMPONENT_SHAPE_SECTIONS: SectionDef[];
 /** Component color sections (can be scoped for light/dark) */
 declare const COMPONENT_COLOR_SECTIONS: SectionDef[];
 declare const COMPONENTS_SECTIONS: SectionDef[];
+declare const ARTIFACT_DISPLAY_PREFERENCE_SECTION: SectionDef;
+declare const STREAM_AND_ARTIFACTS_SUB_GROUP: SubGroupDef;
 declare const CONFIGURE_SUB_GROUPS: SubGroupDef[];
 declare const CONFIGURE_SECTIONS: SectionDef[];
 /** Section 1: Theme: color mode selection */
@@ -6812,6 +6923,22 @@ interface PreviewConfigOptions {
 declare function buildPreviewConfig(options: PreviewConfigOptions, shellModeOverride?: 'light' | 'dark'): AgentWidgetConfig;
 declare function buildPreviewConfigWithMessages(options: PreviewConfigOptions, messages: AgentWidgetMessage[], shellModeOverride?: 'light' | 'dark'): AgentWidgetConfig;
 
+/**
+ * Imperative preview renderer for the theme editor.
+ * Import from `@runtypelabs/persona/theme-editor/preview` (not the headless
+ * `@runtypelabs/persona/theme-editor` subpath, which omits the widget runtime).
+ *
+ * Manages iframe-based widget previews with device frames, zoom, scenes, and compare mode.
+ * No external DOM dependencies: only needs a container element to mount into.
+ *
+ * For advanced preview needs (background URLs, inline editing, contrast checking),
+ * use the lifecycle hooks in `ThemePreviewOptions` and import shared building blocks
+ * from `./preview-utils` directly.
+ */
+
+type PreviewShellMode = 'light' | 'dark';
+type CompareMode = 'off' | 'baseline' | 'themes';
+
 /**
  * Interface Role → Token mapping layer.
  *
@@ -7104,4 +7231,4 @@ declare function runContrastChecks(state: ThemeEditorLike, level?: ContrastLevel
 /** Compact contrast warnings for the regions a mutation touched. */
 declare function quickContrastWarnings(state: ThemeEditorLike, pairKeys: string[], variant?: 'light' | 'dark' | 'both', level?: ContrastLevel): ContrastWarning[];
 
-export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewScene, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolContent, type ToolExecute, type ToolImageContent, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };
+export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, ARTIFACT_DISPLAY_PREFERENCE_SECTION, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STREAM_AND_ARTIFACTS_SUB_GROUP, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolContent, type ToolExecute, type ToolImageContent, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };