@runtypelabs/persona 3.15.1 → 3.17.0

package/dist/theme-editor.d.cts

@@ -767,6 +767,17 @@ type AgentMessageMetadata = {
     iteration?: number;
     turnId?: string;
     agentName?: string;
+    /**
+     * When this message was produced by a step inside a nested flow executed
+     * as a tool, identifies the parent tool call id. Enables renderers to
+     * visually group or indent nested-flow output under its parent tool.
+     */
+    parentToolId?: string;
+    /**
+     * Nested flow step id that produced this message (e.g. a `send-stream`
+     * or `prompt` step inside the nested flow). Stable key for that step.
+     */
+    parentStepId?: string;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -1210,6 +1221,151 @@ type AgentWidgetReasoningDisplayFeature = {
      */
     loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
+/**
+ * Reveal animation applied to assistant message text while it is streaming.
+ *
+ * Built-in types always available:
+ * - `none` — text appears as tokens arrive (default).
+ * - `typewriter` — characters fade in with a blinking caret.
+ * - `pop-bubble` — the bubble scales in; text streams normally afterward.
+ * - `letter-rise` — per-char translateY + fade reveal.
+ * - `word-fade` — per-word blur + translateY fade-in.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * Custom types are allowed — register a plugin with any string name and
+ * reference it by that name in `type`.
+ */
+type AgentWidgetStreamAnimationBuiltinType = "none" | "typewriter" | "word-fade" | "letter-rise" | "glyph-cycle" | "wipe" | "pop-bubble";
+type AgentWidgetStreamAnimationType = AgentWidgetStreamAnimationBuiltinType | (string & {});
+/**
+ * Placeholder shown inside a streaming assistant bubble before the first token arrives.
+ * - `none` — use the default typing-dots indicator (existing behavior).
+ * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ */
+type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
+/**
+ * How much of the accumulated streaming content to display while tokens are
+ * still arriving. Trimming to a boundary means in-progress words or lines
+ * stay hidden until they complete — useful for animations that benefit from
+ * unit-complete reveals (e.g. wipe, glyph-cycle).
+ * - `none` — show every character as it arrives (default).
+ * - `word` — trim to the last whitespace boundary.
+ * - `line` — trim to the last newline boundary.
+ */
+type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+type StreamAnimationContext = {
+    /** The `.persona-message-content` element owning the streamed text. */
+    container: HTMLElement;
+    /** The outer message bubble element. */
+    bubble: HTMLElement;
+    /** ID of the streaming message. */
+    messageId: string;
+    /** Read-only reference to the message being streamed. */
+    message: AgentWidgetMessage;
+    /** Effective `speed` from `streamAnimation.speed`. */
+    speed: number;
+    /** Effective `duration` from `streamAnimation.duration`. */
+    duration: number;
+};
+/**
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
+ *
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   widget's style host.
+ * - For each streaming assistant message whose `type` matches `name`, the
+ *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
+ *   and — if `useCaret` is true — appends a blinking caret.
+ * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
+ *   and `data-preserve-animation` to safely mutate per-char or per-word spans
+ *   without idiomorph clobbering in-flight work.
+ */
+type StreamAnimationPlugin = {
+    /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+    name: string;
+    /** Class added to `.persona-message-content` while streaming. */
+    containerClass?: string;
+    /** Class added to the bubble element (e.g. a one-shot scale animation). */
+    bubbleClass?: string;
+    /** Wrap mode applied to text nodes during streaming. @default "none" */
+    wrap?: "none" | "char" | "word";
+    /**
+     * HTML tags whose descendant text is skipped during wrapping. Defaults to
+     * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+     * blocks legible and link click-targets intact. Plugins that want to
+     * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
+     * the list.
+     */
+    skipTags?: string[];
+    /** Append a blinking caret after the last rendered char/word. */
+    useCaret?: boolean;
+    /** CSS string injected into the widget style host on first activation. */
+    styles?: string;
+    /**
+     * Optional custom buffering strategy. Returns the portion of `content`
+     * that should be rendered during streaming. Use this for buffering
+     * schemes beyond the built-in `word` / `line` strategies.
+     */
+    bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+    /**
+     * Fires once when the plugin is first activated inside a widget instance.
+     * Use this to set up MutationObservers or other long-lived listeners.
+     * Return an optional cleanup function that runs on widget destroy.
+     */
+    onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+    /** Fires after each render that reaches the live DOM. */
+    onAfterRender?: (ctx: StreamAnimationContext) => void;
+    /** Fires when a streamed message's `streaming` flag flips to false. */
+    onStreamComplete?: (ctx: StreamAnimationContext) => void;
+    /**
+     * Report whether the plugin still has in-flight animation work for a
+     * message. When `true`, the widget keeps rendering the message in its
+     * "streaming-animated" mode even after `message.streaming` flips false —
+     * preventing the final non-animated render from yanking the rug out from
+     * under unfinished per-char cycles or reveals.
+     */
+    isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+type AgentWidgetStreamAnimationFeature = {
+    /** Reveal animation to apply while streaming. @default "none" */
+    type?: AgentWidgetStreamAnimationType;
+    /** Pre-first-token placeholder. @default "none" */
+    placeholder?: AgentWidgetStreamAnimationPlaceholder;
+    /**
+     * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
+     * and per-unit plugin animations. Each arriving character/word animates from
+     * invisible to visible over this duration, independent of its position — the
+     * streaming cadence itself provides the visible stagger.
+     * @default 120
+     */
+    speed?: number;
+    /**
+     * Total duration of container-level animations (`pop-bubble` and custom
+     * plugin animations), in milliseconds.
+     * @default 1800
+     */
+    duration?: number;
+    /**
+     * Trim the accumulated streaming content to a word or line boundary before
+     * rendering. Hides in-progress units until they complete.
+     * @default "none"
+     */
+    buffer?: AgentWidgetStreamAnimationBuffer;
+    /**
+     * Extra animation plugins available to this widget instance. Keys are
+     * plugin names; the matching plugin activates when `type` is set to that
+     * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+     */
+    plugins?: Record<string, StreamAnimationPlugin>;
+};
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
     showToolCalls?: boolean;
@@ -1224,6 +1380,8 @@ type AgentWidgetFeatureFlags = {
     eventStream?: EventStreamConfig;
     /** Optional artifact sidebar (split pane / mobile drawer) */
     artifacts?: AgentWidgetArtifactsFeature;
+    /** Reveal animation for streaming assistant text. */
+    streamAnimation?: AgentWidgetStreamAnimationFeature;
 };
 type SSEEventRecord = {
     id: string;
@@ -1512,6 +1670,10 @@ type AgentWidgetSendButtonConfig = {
     backgroundColor?: string;
     textColor?: string;
     size?: string;
+    /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
+    stopIconName?: string;
+    /** Tooltip text shown while streaming. Default: "Stop generating". */
+    stopTooltipText?: string;
 };
 /** Optional composer UI state for custom `renderComposer` implementations. */
 type AgentWidgetComposerConfig = {
@@ -2911,11 +3073,21 @@ type AgentWidgetConfig = {
         welcomeSubtitle?: string;
         inputPlaceholder?: string;
         sendButtonLabel?: string;
+        /** Button label shown in text mode while a response is streaming. Default: "Stop". */
+        stopButtonLabel?: string;
         /**
          * When false, the welcome / intro card is not shown above the message list.
          * @default true
          */
         showWelcomeCard?: boolean;
+        /**
+         * Per-stop-reason copy for the inline notice rendered on assistant
+         * bubbles when the runtime reports a non-natural stop (e.g. the agent
+         * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
+         * optional — keys you omit fall back to the built-in defaults. Set a
+         * key to an empty string to suppress the notice for that reason.
+         */
+        stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
     };
     /**
      * Semantic design tokens (`palette`, `semantic`, `components`).
@@ -3413,6 +3585,21 @@ type AgentWidgetApproval = {
     resolvedAt?: number;
 };
 type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * owned by the upstream Runtype API — do not extend without coordination.
+ *
+ * - `end_turn` — natural completion (no affordance needed)
+ * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
+ * - `length` — provider hit max output tokens
+ * - `content_filter` — provider content filter intervened
+ * - `error` — provider/runtime error (prefer existing error rendering)
+ * - `unknown` — explicitly reported but uninformative
+ *
+ * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ */
+type StopReasonKind = 'end_turn' | 'max_tool_calls' | 'length' | 'content_filter' | 'error' | 'unknown';
 /**
  * Represents a message in the chat conversation.
  *
@@ -3499,6 +3686,17 @@ type AgentWidgetMessage = {
      * Contains execution context like iteration number and turn ID.
      */
     agentMetadata?: AgentMessageMetadata;
+    /**
+     * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+     * (agent-loop path) or the last `step_complete` for a prompt step
+     * (dispatch / flow path). Absent when the API did not report a value.
+     *
+     * When set to a non-natural value (`max_tool_calls`, `length`,
+     * `content_filter`, `error`), the widget renders an inline notice on
+     * the assistant bubble. See `config.copy.stopReasonNotice` to override
+     * the default copy.
+     */
+    stopReason?: StopReasonKind;
 };
 /**
  * Options for injecting a message into the conversation.
@@ -4050,10 +4248,35 @@ declare const MOCK_WORKSPACE_CONTENT = "\n    <div class=\"preview-workspace-con
  */
 declare function buildSrcdoc(mountId: string, shellMode: 'light' | 'dark', docked: boolean, widgetCssPath: string): string;
 type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
-type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete';
+type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete';
 declare function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string;
 declare function createPreviewTranscriptEntry(preset: PreviewTranscriptEntryPreset, index?: number): AgentWidgetMessage;
 declare function appendPreviewTranscriptEntry(messages: AgentWidgetMessage[], preset: PreviewTranscriptEntryPreset): AgentWidgetMessage[];
+/** Presets whose assistant content should stream in so Stream Animation settings engage. */
+declare function presetStreamsText(preset: PreviewTranscriptEntryPreset): boolean;
+interface TranscriptStreamFrame {
+    /** Message to upsert into the session. */
+    message: AgentWidgetMessage;
+    /** Delay from the previous frame in ms. The first frame uses 0. */
+    delayMs: number;
+    /** True when this is the final frame (message is no longer streaming). */
+    done: boolean;
+}
+interface BuildTranscriptStreamFramesOptions {
+    /** Characters per progressive chunk. Default: 24. */
+    chunkSize?: number;
+    /** Delay between chunks in ms. Default: 42. */
+    delayMs?: number;
+}
+/**
+ * Builds progressive snapshots for a transcript preset suitable for feeding into
+ * `injectTestMessage({ type: 'message', message })` on a timer. Each frame upserts
+ * the same message id with more content, ending with `streaming: false`.
+ *
+ * - Streaming-capable presets (assistant text) yield many frames.
+ * - All other presets yield a single `done` frame matching `createPreviewTranscriptEntry`.
+ */
+declare function buildTranscriptStreamFrames(preset: PreviewTranscriptEntryPreset, suffix: number, options?: BuildTranscriptStreamFramesOptions): TranscriptStreamFrame[];
 declare function createPreviewMessages(scene: PreviewScene, config?: Partial<AgentWidgetConfig>, appendedMessages?: AgentWidgetMessage[]): AgentWidgetMessage[];
 declare function applySceneConfig(base: AgentWidgetConfig, scene: PreviewScene, appendedMessages?: AgentWidgetMessage[]): AgentWidgetConfig;
 
@@ -4230,4 +4453,4 @@ declare function paletteColorPath(family: string, shade: string): string;
 declare function resolveThemeColorPath(get: (path: string) => unknown, path: string, depth?: number): string;
 declare function tokenRefDisplayName(path: string): string;
 
-export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, DEVICE_DIMENSIONS, type DetectedRoleAssignment, 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 PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, 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 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 ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type TokenRefOptions, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, resolveRoleAssignment, resolveThemeColorPath, scopeSection, tokenRefDisplayName, wcagContrastRatio };
+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, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, DEVICE_DIMENSIONS, type DetectedRoleAssignment, 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 PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, 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 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 ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type TokenRefOptions, type TranscriptStreamFrame, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildTranscriptStreamFrames, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, resolveRoleAssignment, resolveThemeColorPath, scopeSection, tokenRefDisplayName, wcagContrastRatio };

package/dist/theme-editor.d.ts

@@ -767,6 +767,17 @@ type AgentMessageMetadata = {
     iteration?: number;
     turnId?: string;
     agentName?: string;
+    /**
+     * When this message was produced by a step inside a nested flow executed
+     * as a tool, identifies the parent tool call id. Enables renderers to
+     * visually group or indent nested-flow output under its parent tool.
+     */
+    parentToolId?: string;
+    /**
+     * Nested flow step id that produced this message (e.g. a `send-stream`
+     * or `prompt` step inside the nested flow). Stable key for that step.
+     */
+    parentStepId?: string;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -1210,6 +1221,151 @@ type AgentWidgetReasoningDisplayFeature = {
      */
     loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
+/**
+ * Reveal animation applied to assistant message text while it is streaming.
+ *
+ * Built-in types always available:
+ * - `none` — text appears as tokens arrive (default).
+ * - `typewriter` — characters fade in with a blinking caret.
+ * - `pop-bubble` — the bubble scales in; text streams normally afterward.
+ * - `letter-rise` — per-char translateY + fade reveal.
+ * - `word-fade` — per-word blur + translateY fade-in.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * Custom types are allowed — register a plugin with any string name and
+ * reference it by that name in `type`.
+ */
+type AgentWidgetStreamAnimationBuiltinType = "none" | "typewriter" | "word-fade" | "letter-rise" | "glyph-cycle" | "wipe" | "pop-bubble";
+type AgentWidgetStreamAnimationType = AgentWidgetStreamAnimationBuiltinType | (string & {});
+/**
+ * Placeholder shown inside a streaming assistant bubble before the first token arrives.
+ * - `none` — use the default typing-dots indicator (existing behavior).
+ * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ */
+type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
+/**
+ * How much of the accumulated streaming content to display while tokens are
+ * still arriving. Trimming to a boundary means in-progress words or lines
+ * stay hidden until they complete — useful for animations that benefit from
+ * unit-complete reveals (e.g. wipe, glyph-cycle).
+ * - `none` — show every character as it arrives (default).
+ * - `word` — trim to the last whitespace boundary.
+ * - `line` — trim to the last newline boundary.
+ */
+type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+type StreamAnimationContext = {
+    /** The `.persona-message-content` element owning the streamed text. */
+    container: HTMLElement;
+    /** The outer message bubble element. */
+    bubble: HTMLElement;
+    /** ID of the streaming message. */
+    messageId: string;
+    /** Read-only reference to the message being streamed. */
+    message: AgentWidgetMessage;
+    /** Effective `speed` from `streamAnimation.speed`. */
+    speed: number;
+    /** Effective `duration` from `streamAnimation.duration`. */
+    duration: number;
+};
+/**
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
+ *
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   widget's style host.
+ * - For each streaming assistant message whose `type` matches `name`, the
+ *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
+ *   and — if `useCaret` is true — appends a blinking caret.
+ * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
+ *   and `data-preserve-animation` to safely mutate per-char or per-word spans
+ *   without idiomorph clobbering in-flight work.
+ */
+type StreamAnimationPlugin = {
+    /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+    name: string;
+    /** Class added to `.persona-message-content` while streaming. */
+    containerClass?: string;
+    /** Class added to the bubble element (e.g. a one-shot scale animation). */
+    bubbleClass?: string;
+    /** Wrap mode applied to text nodes during streaming. @default "none" */
+    wrap?: "none" | "char" | "word";
+    /**
+     * HTML tags whose descendant text is skipped during wrapping. Defaults to
+     * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+     * blocks legible and link click-targets intact. Plugins that want to
+     * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
+     * the list.
+     */
+    skipTags?: string[];
+    /** Append a blinking caret after the last rendered char/word. */
+    useCaret?: boolean;
+    /** CSS string injected into the widget style host on first activation. */
+    styles?: string;
+    /**
+     * Optional custom buffering strategy. Returns the portion of `content`
+     * that should be rendered during streaming. Use this for buffering
+     * schemes beyond the built-in `word` / `line` strategies.
+     */
+    bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+    /**
+     * Fires once when the plugin is first activated inside a widget instance.
+     * Use this to set up MutationObservers or other long-lived listeners.
+     * Return an optional cleanup function that runs on widget destroy.
+     */
+    onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+    /** Fires after each render that reaches the live DOM. */
+    onAfterRender?: (ctx: StreamAnimationContext) => void;
+    /** Fires when a streamed message's `streaming` flag flips to false. */
+    onStreamComplete?: (ctx: StreamAnimationContext) => void;
+    /**
+     * Report whether the plugin still has in-flight animation work for a
+     * message. When `true`, the widget keeps rendering the message in its
+     * "streaming-animated" mode even after `message.streaming` flips false —
+     * preventing the final non-animated render from yanking the rug out from
+     * under unfinished per-char cycles or reveals.
+     */
+    isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+type AgentWidgetStreamAnimationFeature = {
+    /** Reveal animation to apply while streaming. @default "none" */
+    type?: AgentWidgetStreamAnimationType;
+    /** Pre-first-token placeholder. @default "none" */
+    placeholder?: AgentWidgetStreamAnimationPlaceholder;
+    /**
+     * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
+     * and per-unit plugin animations. Each arriving character/word animates from
+     * invisible to visible over this duration, independent of its position — the
+     * streaming cadence itself provides the visible stagger.
+     * @default 120
+     */
+    speed?: number;
+    /**
+     * Total duration of container-level animations (`pop-bubble` and custom
+     * plugin animations), in milliseconds.
+     * @default 1800
+     */
+    duration?: number;
+    /**
+     * Trim the accumulated streaming content to a word or line boundary before
+     * rendering. Hides in-progress units until they complete.
+     * @default "none"
+     */
+    buffer?: AgentWidgetStreamAnimationBuffer;
+    /**
+     * Extra animation plugins available to this widget instance. Keys are
+     * plugin names; the matching plugin activates when `type` is set to that
+     * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+     */
+    plugins?: Record<string, StreamAnimationPlugin>;
+};
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
     showToolCalls?: boolean;
@@ -1224,6 +1380,8 @@ type AgentWidgetFeatureFlags = {
     eventStream?: EventStreamConfig;
     /** Optional artifact sidebar (split pane / mobile drawer) */
     artifacts?: AgentWidgetArtifactsFeature;
+    /** Reveal animation for streaming assistant text. */
+    streamAnimation?: AgentWidgetStreamAnimationFeature;
 };
 type SSEEventRecord = {
     id: string;
@@ -1512,6 +1670,10 @@ type AgentWidgetSendButtonConfig = {
     backgroundColor?: string;
     textColor?: string;
     size?: string;
+    /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
+    stopIconName?: string;
+    /** Tooltip text shown while streaming. Default: "Stop generating". */
+    stopTooltipText?: string;
 };
 /** Optional composer UI state for custom `renderComposer` implementations. */
 type AgentWidgetComposerConfig = {
@@ -2911,11 +3073,21 @@ type AgentWidgetConfig = {
         welcomeSubtitle?: string;
         inputPlaceholder?: string;
         sendButtonLabel?: string;
+        /** Button label shown in text mode while a response is streaming. Default: "Stop". */
+        stopButtonLabel?: string;
         /**
          * When false, the welcome / intro card is not shown above the message list.
          * @default true
          */
         showWelcomeCard?: boolean;
+        /**
+         * Per-stop-reason copy for the inline notice rendered on assistant
+         * bubbles when the runtime reports a non-natural stop (e.g. the agent
+         * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
+         * optional — keys you omit fall back to the built-in defaults. Set a
+         * key to an empty string to suppress the notice for that reason.
+         */
+        stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
     };
     /**
      * Semantic design tokens (`palette`, `semantic`, `components`).
@@ -3413,6 +3585,21 @@ type AgentWidgetApproval = {
     resolvedAt?: number;
 };
 type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * owned by the upstream Runtype API — do not extend without coordination.
+ *
+ * - `end_turn` — natural completion (no affordance needed)
+ * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
+ * - `length` — provider hit max output tokens
+ * - `content_filter` — provider content filter intervened
+ * - `error` — provider/runtime error (prefer existing error rendering)
+ * - `unknown` — explicitly reported but uninformative
+ *
+ * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ */
+type StopReasonKind = 'end_turn' | 'max_tool_calls' | 'length' | 'content_filter' | 'error' | 'unknown';
 /**
  * Represents a message in the chat conversation.
  *
@@ -3499,6 +3686,17 @@ type AgentWidgetMessage = {
      * Contains execution context like iteration number and turn ID.
      */
     agentMetadata?: AgentMessageMetadata;
+    /**
+     * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+     * (agent-loop path) or the last `step_complete` for a prompt step
+     * (dispatch / flow path). Absent when the API did not report a value.
+     *
+     * When set to a non-natural value (`max_tool_calls`, `length`,
+     * `content_filter`, `error`), the widget renders an inline notice on
+     * the assistant bubble. See `config.copy.stopReasonNotice` to override
+     * the default copy.
+     */
+    stopReason?: StopReasonKind;
 };
 /**
  * Options for injecting a message into the conversation.
@@ -4050,10 +4248,35 @@ declare const MOCK_WORKSPACE_CONTENT = "\n    <div class=\"preview-workspace-con
  */
 declare function buildSrcdoc(mountId: string, shellMode: 'light' | 'dark', docked: boolean, widgetCssPath: string): string;
 type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
-type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete';
+type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete';
 declare function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string;
 declare function createPreviewTranscriptEntry(preset: PreviewTranscriptEntryPreset, index?: number): AgentWidgetMessage;
 declare function appendPreviewTranscriptEntry(messages: AgentWidgetMessage[], preset: PreviewTranscriptEntryPreset): AgentWidgetMessage[];
+/** Presets whose assistant content should stream in so Stream Animation settings engage. */
+declare function presetStreamsText(preset: PreviewTranscriptEntryPreset): boolean;
+interface TranscriptStreamFrame {
+    /** Message to upsert into the session. */
+    message: AgentWidgetMessage;
+    /** Delay from the previous frame in ms. The first frame uses 0. */
+    delayMs: number;
+    /** True when this is the final frame (message is no longer streaming). */
+    done: boolean;
+}
+interface BuildTranscriptStreamFramesOptions {
+    /** Characters per progressive chunk. Default: 24. */
+    chunkSize?: number;
+    /** Delay between chunks in ms. Default: 42. */
+    delayMs?: number;
+}
+/**
+ * Builds progressive snapshots for a transcript preset suitable for feeding into
+ * `injectTestMessage({ type: 'message', message })` on a timer. Each frame upserts
+ * the same message id with more content, ending with `streaming: false`.
+ *
+ * - Streaming-capable presets (assistant text) yield many frames.
+ * - All other presets yield a single `done` frame matching `createPreviewTranscriptEntry`.
+ */
+declare function buildTranscriptStreamFrames(preset: PreviewTranscriptEntryPreset, suffix: number, options?: BuildTranscriptStreamFramesOptions): TranscriptStreamFrame[];
 declare function createPreviewMessages(scene: PreviewScene, config?: Partial<AgentWidgetConfig>, appendedMessages?: AgentWidgetMessage[]): AgentWidgetMessage[];
 declare function applySceneConfig(base: AgentWidgetConfig, scene: PreviewScene, appendedMessages?: AgentWidgetMessage[]): AgentWidgetConfig;
 
@@ -4230,4 +4453,4 @@ declare function paletteColorPath(family: string, shade: string): string;
 declare function resolveThemeColorPath(get: (path: string) => unknown, path: string, depth?: number): string;
 declare function tokenRefDisplayName(path: string): string;
 
-export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, DEVICE_DIMENSIONS, type DetectedRoleAssignment, 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 PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, 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 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 ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type TokenRefOptions, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, resolveRoleAssignment, resolveThemeColorPath, scopeSection, tokenRefDisplayName, wcagContrastRatio };
+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, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, DEVICE_DIMENSIONS, type DetectedRoleAssignment, 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 PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, 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 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 ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type TokenRefOptions, type TranscriptStreamFrame, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildTranscriptStreamFrames, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, resolveRoleAssignment, resolveThemeColorPath, scopeSection, tokenRefDisplayName, wcagContrastRatio };