@runtypelabs/persona 4.13.0 → 4.15.0

package/dist/theme-editor.d.cts

@@ -339,6 +339,14 @@ interface ReasoningBubbleTokens {
 interface ComposerChromeTokens {
     /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
     shadow: string;
+    /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
+    padding?: string;
+    /** Gap between the textarea row and the actions row. @default "0.5rem" */
+    gap?: string;
+    /** Composer textarea font-size. @default "0.875rem" */
+    fontSize?: string;
+    /** Composer textarea line-height. @default "1.25rem" */
+    lineHeight?: string;
 }
 /** Artifact toolbar chrome. */
 interface ArtifactToolbarTokens {
@@ -488,6 +496,26 @@ interface ScrollToBottomTokens extends ComponentTokenSet {
     fontSize?: string;
     iconSize?: string;
 }
+/** Visual tokens shared by one suggestion presentation variant. */
+interface SuggestionVariantTokens extends ComponentTokenSet {
+    gap?: string;
+    minHeight?: string;
+    fontSize?: string;
+    lineHeight?: string;
+    iconSize?: string;
+    hoverBackground?: TokenReference<'color'>;
+    hoverForeground?: TokenReference<'color'>;
+    hoverBorder?: TokenReference<'color'>;
+    pressedBackground?: TokenReference<'color'>;
+    focusRing?: TokenReference<'color'>;
+    disabledOpacity?: string;
+}
+/** Starter and follow-up suggestion chrome. */
+interface SuggestionTokens {
+    chip: SuggestionVariantTokens;
+    card: SuggestionVariantTokens;
+    list: SuggestionVariantTokens;
+}
 /** Toggle group chrome (used by createToggleGroup). */
 interface ToggleGroupTokens {
     /** Gap between toggle buttons. Default: 0 (connected). */
@@ -518,6 +546,8 @@ interface ComponentTokens {
     labelButton?: LabelButtonTokens;
     /** Scroll-to-bottom indicator styling tokens. */
     scrollToBottom?: ScrollToBottomTokens;
+    /** Starter prompt and follow-up suggestion styling tokens. */
+    suggestion?: SuggestionTokens;
     /** Toggle group styling tokens. */
     toggleGroup?: ToggleGroupTokens;
     /** Artifact toolbar, tab strip, and pane chrome. */
@@ -559,6 +589,40 @@ type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
+type AgentWidgetTransformSuggestionsContext = {
+    /**
+     * Fresh copy of the suggestions entering this plugin, already normalized:
+     * shorthand strings expanded and the effective send/fill behavior resolved.
+     */
+    suggestions: AgentWidgetResolvedSuggestion[];
+    surface: AgentWidgetSuggestionSurface;
+    source: AgentWidgetSuggestionSource;
+    config: AgentWidgetConfig;
+};
+type AgentWidgetRenderSuggestionContext = {
+    /** Fully normalized suggestion, including the effective send/fill behavior. */
+    suggestion: AgentWidgetResolvedSuggestion;
+    index: number;
+    surface: AgentWidgetSuggestionSurface;
+    source: AgentWidgetSuggestionSource;
+    variant: AgentWidgetSuggestionVariant;
+    streaming: boolean;
+    config: AgentWidgetConfig;
+    /** Build Persona's standard chip, card, or list item. */
+    defaultRenderer: () => HTMLElement;
+    /**
+     * Run the normal selection pipeline: DOM event, plugin selection hooks, then
+     * send or fill. Custom renderers should call this instead of sending directly.
+     */
+    select: () => void;
+};
+type AgentWidgetSuggestionSelectContext = {
+    suggestion: AgentWidgetResolvedSuggestion;
+    surface: AgentWidgetSuggestionSurface;
+    source: AgentWidgetSuggestionSource;
+    variant: AgentWidgetSuggestionVariant;
+    config: AgentWidgetConfig;
+};
 /**
  * Plugin interface for customizing widget components
  */
@@ -571,6 +635,25 @@ interface AgentWidgetPlugin {
      * Optional priority (higher = runs first). Default: 0
      */
     priority?: number;
+    /**
+     * Transform, filter, enrich, or reorder suggestions. Hooks receive normalized
+     * items and compose in plugin priority order; the return value may use the
+     * loose shape (string shorthand included) and is re-normalized before the next
+     * hook. A per-item `behavior` set here survives. `maxItems` caps the list
+     * after the full chain. Return an empty array to hide the surface.
+     */
+    transformSuggestions?: (context: AgentWidgetTransformSuggestionsContext) => AgentWidgetSuggestion[];
+    /**
+     * Render one starter or follow-up suggestion. Return null to use Persona's
+     * default chip/card/list renderer. Call `select()` from custom interaction
+     * controls to preserve events, selection hooks, and send/fill behavior.
+     */
+    renderSuggestion?: (context: AgentWidgetRenderSuggestionContext) => HTMLElement | null;
+    /**
+     * Observe or intercept a suggestion selection. Return false to cancel the
+     * built-in send/fill action. Hooks run in plugin priority order.
+     */
+    onSuggestionSelect?: (context: AgentWidgetSuggestionSelectContext) => void | boolean;
     /**
      * Custom renderer for message bubbles
      * Return null to use default renderer
@@ -1080,7 +1163,24 @@ type RuntypeExecutionStreamEvent = ({
     type: "source";
     url?: string;
     [key: string]: unknown;
+} | {
+    executionId: string;
+    iteration?: number;
+    seq: number;
+    state: Record<string, unknown>;
+    type: "state_snapshot";
 } | ({
+    executionId: string;
+    iteration?: number;
+    patch: Array<{
+        from?: string;
+        op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+        path: string;
+        value?: unknown;
+    }>;
+    seq: number;
+    type: "state_delta";
+}) | ({
     executionId: string;
     hiddenParameterNames?: Array<string>;
     iteration?: number;
@@ -1322,6 +1422,7 @@ declare const LUCIDE_ICONS: {
     readonly plus: IconNode;
     readonly minus: IconNode;
     readonly pencil: IconNode;
+    readonly "pen-line": IconNode;
     readonly trash: IconNode;
     readonly "trash-2": IconNode;
     readonly save: IconNode;
@@ -1364,11 +1465,13 @@ declare const LUCIDE_ICONS: {
     readonly folder: IconNode;
     readonly "folder-open": IconNode;
     readonly files: IconNode;
+    readonly "chart-column": IconNode;
     readonly sparkles: IconNode;
     readonly zap: IconNode;
     readonly sun: IconNode;
     readonly moon: IconNode;
     readonly flag: IconNode;
+    readonly lightbulb: IconNode;
     readonly monitor: IconNode;
     readonly smartphone: IconNode;
 };
@@ -1968,6 +2071,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 +2607,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 +2705,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;
     /**
@@ -3281,19 +3430,63 @@ type AgentWidgetFeatureFlags = {
      */
     askUserQuestion?: AgentWidgetAskUserQuestionFeature;
     /**
-     * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
-     * the tool, the widget shows the suggestions as tappable chips above the
-     * composer (reusing the suggestion-chips surface) and immediately resumes
-     * the execution: fire-and-forget, no user input awaited.
+     * Built-in `suggest_replies` follow-ups. When the assistant invokes the
+     * tool, the widget shows the suggestions using `suggestions.followUps` and
+     * immediately resumes the execution: fire-and-forget, no user input awaited.
+     *
+     * @deprecated Both keys moved to `suggestions.followUps`: use
+     * `suggestions.followUps.enabled` and `suggestions.followUps.expose`. This
+     * alias keeps working per key, with `suggestions.followUps` winning.
      */
     suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
+type WidgetPreferenceCapabilities = {
+    artifacts?: boolean;
+    tools?: boolean;
+    reasoning?: boolean;
+};
 /**
- * Feature config for the built-in `suggest_replies` quick-reply chips.
- * Chips render in the existing suggestions slot above the composer and are
- * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
- * verbatim as the user's next message; chips clear once any user message
- * follows them.
+ * 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` follow-ups.
+ *
+ * @deprecated Both keys moved to `suggestions.followUps`
+ * (`suggestions.followUps.enabled` / `suggestions.followUps.expose`), which
+ * also owns presentation, placement, and send/fill behavior. Resolution is
+ * per key with `suggestions.followUps` winning; removal waits for 5.0.
  */
 type AgentWidgetSuggestRepliesFeature = {
     /**
@@ -3301,14 +3494,18 @@ type AgentWidgetSuggestRepliesFeature = {
      * renders as a regular tool bubble and is NOT auto-resumed: only set this
      * with no server-side `suggest_replies` declaration, or the execution
      * parks awaiting a resume that never comes.
+     * @deprecated Use `suggestions.followUps.enabled`.
      */
     enabled?: boolean;
     /**
      * Advertise the built-in `suggest_replies` tool to the agent on every
      * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
-     * needed. Defaults to `false`: flows that already declare the tool via
-     * `runtimeTools` would otherwise present it to the model twice. Ignored
-     * when `enabled` is `false`.
+     * needed. Defaults to `false`. Declare the tool in one place: the API
+     * dedupes a double declaration by name with `clientTools[]` winning, so the
+     * model still sees exactly one tool, but the widget's description and schema
+     * win and the effective tool type becomes `local` (the execution pauses and
+     * the widget auto-resumes it). Ignored when `enabled` is `false`.
+     * @deprecated Use `suggestions.followUps.expose`.
      */
     expose?: boolean;
 };
@@ -3378,10 +3575,13 @@ type AgentWidgetAskUserQuestionFeature = {
      * matching {@link AskUserQuestionPayload}; when the model calls it, the
      * existing answer-pill sheet renders and the answer resumes the execution.
      *
-     * Defaults to `false`: flows that already declare `ask_user_question` via
-     * `runtimeTools` would otherwise present the tool to the model twice.
-     * Ignored when `enabled` is `false`: never offer the agent a question
-     * tool the widget can't render an answer UI for.
+     * Defaults to `false`. Declare the tool in one place: the API dedupes a
+     * double declaration by name with `clientTools[]` winning, so the model
+     * still sees exactly one tool, but the widget's description and schema win
+     * and the effective tool type becomes `local` (the execution pauses and the
+     * widget resumes it with the user's answer). Ignored when `enabled` is
+     * `false`: never offer the agent a question tool the widget can't render an
+     * answer UI for.
      */
     expose?: boolean;
     /** Slide-in animation duration in ms. Defaults to 180. */
@@ -3854,6 +4054,10 @@ type AgentWidgetSendButtonConfig = {
     paddingY?: string;
     iconText?: string;
     iconName?: string;
+    /** Icon glyph box in icon mode, e.g. "20px". Defaults to half of `size`. */
+    iconSize?: string;
+    /** Stroke width for the icon glyph, in viewBox units. Default 2. */
+    iconStrokeWidth?: number;
     useIcon?: boolean;
     tooltipText?: string;
     showTooltip?: boolean;
@@ -4577,6 +4781,109 @@ type AgentWidgetSuggestionChipsConfig = {
     paddingX?: string;
     paddingY?: string;
 };
+/** A suggested next action shown to the user. Strings remain supported as shorthand. */
+type AgentWidgetSuggestion = string | {
+    /** Stable analytics / DOM identity. Falls back to the prompt or label. */
+    id?: string;
+    /** Concise visible action label. */
+    label: string;
+    /** Text placed in the composer or sent. Defaults to `label`. */
+    prompt?: string;
+    /** Optional supporting copy, most useful with the `card` variant. */
+    description?: string;
+    /** Optional icon from Persona's bundled Lucide registry. */
+    icon?: IconName;
+    /**
+     * CSS color for this item's glyph. Tints the icon only: label, border,
+     * and background stay neutral. Ignored without an `icon`.
+     */
+    iconColor?: string;
+    /** Override the surface's click behavior for this item. */
+    behavior?: AgentWidgetSuggestionBehavior;
+    /** Visually promote one high-confidence action. */
+    emphasis?: "default" | "primary";
+};
+type AgentWidgetSuggestionBehavior = "send" | "fill";
+type AgentWidgetSuggestionVariant = "chip" | "card" | "list";
+type AgentWidgetSuggestionSurface = "starter" | "followUp";
+/**
+ * Who produced the rendered suggestions: static config, the agent's
+ * `suggest_replies` tool, or `controller.setFollowUpSuggestions`.
+ */
+type AgentWidgetSuggestionSource = "config" | "agent" | "host";
+/**
+ * A suggestion after Persona has normalized shorthand strings and resolved the
+ * effective click behavior. Plugin hooks receive this stable shape.
+ */
+type AgentWidgetResolvedSuggestion = {
+    id: string;
+    label: string;
+    prompt: string;
+    description?: string;
+    icon?: IconName;
+    /** CSS color for the glyph only; never the label, border, or background. */
+    iconColor?: string;
+    behavior: AgentWidgetSuggestionBehavior;
+    emphasis: "default" | "primary";
+};
+/** Presentation keys shared by every suggestion surface. */
+type AgentWidgetSuggestionSurfaceConfig = {
+    /** Item density. Defaults to `card` for starters and `chip` for follow-ups. */
+    variant?: AgentWidgetSuggestionVariant;
+    /** Default click behavior, overridable per item. Defaults to `send`. */
+    behavior?: AgentWidgetSuggestionBehavior;
+    /**
+     * Layout for items past the surface width. Defaults to `wrap` for starters
+     * and `scroll` for follow-ups. Applies to the `chip` variant only; the
+     * `card` and `list` layouts manage their own stacking.
+     */
+    overflow?: "scroll" | "wrap";
+    /** Maximum visible items. Defaults to 4. */
+    maxItems?: number;
+};
+type AgentWidgetStarterSuggestionsConfig = AgentWidgetSuggestionSurfaceConfig & {
+    /** Suggestions shown before the first user message. */
+    items?: AgentWidgetSuggestion[];
+    /**
+     * `auto` uses the welcome surface when the welcome card renders and the
+     * composer otherwise. Explicit values are literal: `welcome` renders
+     * nothing when the welcome card is hidden. Defaults to `auto`.
+     */
+    placement?: "auto" | "welcome" | "composer";
+};
+type AgentWidgetFollowUpSuggestionsConfig = AgentWidgetSuggestionSurfaceConfig & {
+    /**
+     * Enable the built-in `suggest_replies` follow-ups. Defaults to true. When
+     * false, `suggest_replies` renders as a regular tool bubble and is NOT
+     * auto-resumed: only set this with no server-side `suggest_replies`
+     * declaration, or the execution parks awaiting a resume that never comes.
+     */
+    enabled?: boolean;
+    /**
+     * Advertise the built-in `suggest_replies` tool to the agent on every
+     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
+     * needed. Defaults to `false`. Declare the tool in one place: the API
+     * dedupes a double declaration by name with `clientTools[]` winning, so
+     * the model still sees exactly one tool, but the widget's description and
+     * schema win and the effective tool type becomes `local` (the execution
+     * pauses and the widget auto-resumes it). Ignored when `enabled` is
+     * `false`.
+     */
+    expose?: boolean;
+    /**
+     * `auto` places follow-ups after the transcript in regular panels and above
+     * the composer in composer-bar mode. Defaults to `auto`.
+     */
+    placement?: "auto" | "after-message" | "composer";
+};
+/**
+ * Structured suggestions configuration. The legacy `suggestionChips` and
+ * `suggestionChipsConfig` fields remain supported for backwards compatibility.
+ */
+type AgentWidgetSuggestionsConfig = {
+    starters?: AgentWidgetStarterSuggestionsConfig;
+    followUps?: AgentWidgetFollowUpSuggestionsConfig;
+};
 /**
  * Interface for pluggable stream parsers that extract text from streaming responses.
  * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
@@ -5729,6 +6036,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).
@@ -5749,7 +6065,11 @@ type AgentWidgetConfig = {
      * with `initialArtifacts`.
      */
     initialSelectedArtifactId?: string | null;
+    /** Rich starter and follow-up suggestion surfaces. */
+    suggestions?: AgentWidgetSuggestionsConfig;
+    /** @deprecated Prefer `suggestions.starters.items`. */
     suggestionChips?: string[];
+    /** @deprecated Prefer semantic tokens under `theme.components.suggestion`. */
     suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
     debug?: boolean;
     formEndpoint?: string;
@@ -6489,6 +6809,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 +6891,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 +6907,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 +6939,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 +6991,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 +7029,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 */
@@ -6769,7 +7105,7 @@ declare const MOCK_WORKSPACE_CONTENT = "\n    <div class=\"preview-workspace-con
  * using the exported templates and shell CSS utilities.
  */
 declare function buildSrcdoc(mountId: string, shellMode: 'light' | 'dark', docked: boolean, widgetCssPath: string): string;
-type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
+type PreviewScene = 'home' | 'conversation' | 'follow-ups' | 'minimized' | 'artifact';
 type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete' | 'approval-request';
 declare function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string;
 declare function createPreviewTranscriptEntry(preset: PreviewTranscriptEntryPreset, index?: number): AgentWidgetMessage;
@@ -6812,6 +7148,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 +7456,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 };