@runtypelabs/persona 4.7.0 → 4.8.0

package/dist/theme-editor-preview.d.cts

@@ -1,3 +1,5 @@
+import { IconNode } from 'lucide';
+
 /**
  * Plugin interface for customizing widget components
  */
@@ -445,6 +447,10 @@ interface PanelTokens extends ComponentTokenSet {
     maxWidth: string;
     height: string;
     maxHeight: string;
+    /** Gap between the detached panel and its region edges. Only used when detached. */
+    inset?: string;
+    /** Background of the region revealed behind a detached panel. */
+    canvasBackground?: string;
 }
 interface HeaderTokens extends ComponentTokenSet {
     background: TokenReference<'color'>;
@@ -609,6 +615,14 @@ interface ArtifactToolbarTokens {
     iconBorder?: string;
     toggleGroupGap?: string;
     toggleBorderRadius?: string;
+    /** Inner padding of the segmented view/source toggle pill. */
+    toggleGroupPadding?: string;
+    /** Border of the segmented view/source toggle pill (e.g., `none`). */
+    toggleGroupBorder?: string;
+    /** Corner radius of the segmented view/source toggle pill. */
+    toggleGroupBorderRadius?: string;
+    /** Background of the segmented view/source toggle pill. */
+    toggleGroupBackground?: string;
     copyBackground?: string;
     copyBorder?: string;
     copyColor?: string;
@@ -640,6 +654,16 @@ interface ArtifactTabTokens {
     /** Tab list container padding (CSS shorthand). */
     listPadding?: string;
 }
+/** Artifact reference card (chat thread) chrome. */
+interface ArtifactCardTokens {
+    background?: string;
+    /** Full border shorthand (e.g. `1px solid #e5e7eb`). */
+    border?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    /** Border color on hover. */
+    hoverBorderColor?: string;
+}
 /** Artifact pane chrome. */
 interface ArtifactPaneTokens {
     /**
@@ -650,6 +674,54 @@ interface ArtifactPaneTokens {
     background?: string;
     toolbarBackground?: string;
 }
+/** Inline artifact block chrome (`display: "inline"` file preview). */
+interface ArtifactInlineTokens {
+    /** Background of the inline preview frame. */
+    background?: string;
+    /** Full border shorthand for the frame (e.g. `1px solid #e5e7eb`). */
+    border?: string;
+    /** Border radius of the inline preview frame. */
+    borderRadius?: string;
+    /** Background of the title/toolbar chrome bar. */
+    chromeBackground?: string;
+    /** Bottom border of the title bar. */
+    chromeBorder?: string;
+    /** Title text color in the chrome bar (artifact basename). */
+    titleColor?: string;
+    /** Muted text color for the type label / streaming status. */
+    mutedColor?: string;
+    /** Preview iframe height inside the inline body. */
+    frameHeight?: string;
+}
+/**
+ * Syntax-highlighted artifact source view (pane + inline), rendered by
+ * `utils/code-highlight.ts`. One Light defaults ship in `widget.css`, with a
+ * One Dark override keyed off the widget's resolved color scheme (the
+ * `data-persona-color-scheme` root attribute, not the OS preference); set any
+ * of these to retheme the tokenizer palette and the line-number gutter.
+ */
+interface CodeTokens {
+    /** Keywords, booleans, null (e.g. `const`, `true`). */
+    keywordColor?: string;
+    /** String and template literals; HTML attribute values. */
+    stringColor?: string;
+    /** Line and block comments. */
+    commentColor?: string;
+    /** Numeric literals; CSS hex colors / units. */
+    numberColor?: string;
+    /** HTML tag brackets + names; doctype. */
+    tagColor?: string;
+    /** HTML attribute names. */
+    attrColor?: string;
+    /** CSS property names; JSON object keys. */
+    propertyColor?: string;
+    /** Line-number gutter digits. */
+    lineNumberColor?: string;
+    /** Right border of the line-number gutter. */
+    gutterBorderColor?: string;
+    /** Background of the source-view code sheet (defaults to One Light/Dark editor background). */
+    background?: string;
+}
 /** Icon button chrome (used by createIconButton). */
 interface IconButtonTokens {
     background?: string;
@@ -719,9 +791,13 @@ interface ComponentTokens {
         toolbar?: ArtifactToolbarTokens;
         tab?: ArtifactTabTokens;
         pane?: ArtifactPaneTokens;
+        card?: ArtifactCardTokens;
+        inline?: ArtifactInlineTokens;
     };
     /** Collapsible widget chrome (tool/reasoning/approval bubbles). */
     collapsibleWidget?: CollapsibleWidgetTokens;
+    /** Syntax-highlighted artifact source view (tokenizer palette + gutter). */
+    code?: CodeTokens;
 }
 interface PaletteExtras {
     transitions?: Record<string, string>;
@@ -764,6 +840,7 @@ type RuntypeExecutionStreamEvent = ({
     totalSteps?: number;
     type: "execution_start";
 }) | ({
+    claudeManagedAgentId?: string;
     completedAt?: string;
     durationMs?: number;
     executionId: string;
@@ -808,6 +885,15 @@ type RuntypeExecutionStreamEvent = ({
     completedAt?: string;
     content?: string;
     cost?: number;
+    estimatedContextBreakdown?: {
+        categories: Record<string, {
+            chars: number;
+            estimatedTokens: number;
+        }>;
+        contextWindowSize?: number;
+        estimatedTotalTokens: number;
+        estimatedUtilizationPercent?: number;
+    };
     executionId: string;
     fallback?: {
         attempts: Array<{
@@ -845,6 +931,7 @@ type RuntypeExecutionStreamEvent = ({
     type: "step_start";
 } | ({
     completedAt?: string;
+    cost?: number;
     durationMs?: number;
     error?: string;
     executionId: string;
@@ -950,6 +1037,11 @@ type RuntypeExecutionStreamEvent = ({
     artifactType: "markdown" | "component";
     component?: string;
     executionId?: string;
+    file?: {
+        language?: string;
+        mimeType: string;
+        path: string;
+    };
     id: string;
     seq?: number;
     title?: string;
@@ -1058,6 +1150,14 @@ type RuntypeExecutionStreamEvent = ({
     awaitReason?: string;
     awaitedAt?: string;
     crawlId?: string;
+    elicitation?: {
+        message: string;
+        mode: "form" | "url";
+        pauseCount?: number;
+        requestedSchema?: Record<string, unknown>;
+        serverName?: string;
+        url?: string;
+    };
     executionId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
@@ -1157,6 +1257,14 @@ type RuntypeFlowSSEEvent = {
     awaitReason?: string;
     awaitedAt: string;
     crawlId?: string;
+    elicitation?: {
+        message: string;
+        mode: "form" | "url";
+        pauseCount?: number;
+        requestedSchema?: Record<string, unknown>;
+        serverName?: string;
+        url?: string;
+    };
     executionId?: string;
     flowId: string;
     origin?: "webmcp" | "sdk";
@@ -1207,7 +1315,7 @@ type RuntypeFlowSSEEvent = {
     completedAt?: string;
     duration?: number;
     durationMs?: number;
-    error?: string;
+    error?: string | null;
     executionId?: string;
     executionTime?: number;
     id?: string;
@@ -1251,13 +1359,21 @@ type RuntypeFlowSSEEvent = {
     totalSteps: number;
     type: "step_skip";
     when: string;
-} | {
+} | ({
+    elicitation?: {
+        message: string;
+        mode: "form" | "url";
+        pauseCount?: number;
+        requestedSchema?: Record<string, unknown>;
+        serverName?: string;
+        url?: string;
+    };
     executionId?: string;
     reason?: string;
     seq?: number;
     type: "step_await";
     [key: string]: unknown;
-} | ({
+}) | ({
     agentContext?: {
         executionId: string;
         iteration: number;
@@ -1422,6 +1538,149 @@ type TargetResolver = (id: string) => {
     payload: Record<string, unknown>;
 };
 
+/**
+ * Curated registry of lucide icons available to `renderLucideIcon`.
+ *
+ * The widget used to do `import * as icons from "lucide"` and look up
+ * icons dynamically by string. That defeated tree-shaking, so the IIFE
+ * (CDN/script-tag) bundle shipped all 1640 lucide icons (~400KB of icon
+ * data) regardless of which we actually used. This explicit registry
+ * lets the bundler drop any icon not listed here.
+ *
+ * Trade-off: `renderLucideIcon(name)` is now a *closed set*. Names not
+ * in this map return `null` and log a warning, exactly as a typo did
+ * before. The registry is intentionally generous (~110 icons) so that
+ * custom `ComponentRenderer` authors rarely hit a missing-icon dead end.
+ *
+ * To add icons: add a named import above and a row in `LUCIDE_ICONS`,
+ * keyed by the lucide kebab-case name (matches their filename and
+ * https://lucide.dev/icons).
+ *
+ * See `packages/widget/docs/icon-registry-shortlist.md` for the full
+ * curation rationale and which icons were considered but excluded.
+ */
+declare const LUCIDE_ICONS: {
+    readonly activity: IconNode;
+    readonly "arrow-down": IconNode;
+    readonly "arrow-up": IconNode;
+    readonly "arrow-up-right": IconNode;
+    readonly bot: IconNode;
+    readonly "chevron-down": IconNode;
+    readonly "chevron-up": IconNode;
+    readonly "chevron-right": IconNode;
+    readonly "chevron-left": IconNode;
+    readonly check: IconNode;
+    readonly clipboard: IconNode;
+    readonly "clipboard-copy": IconNode;
+    readonly "code-xml": IconNode;
+    readonly copy: IconNode;
+    readonly file: IconNode;
+    readonly "file-code": IconNode;
+    readonly "file-spreadsheet": IconNode;
+    readonly "file-text": IconNode;
+    readonly "image-plus": IconNode;
+    readonly loader: IconNode;
+    readonly "loader-circle": IconNode;
+    readonly mic: IconNode;
+    readonly paperclip: IconNode;
+    readonly "refresh-cw": IconNode;
+    readonly search: IconNode;
+    readonly send: IconNode;
+    readonly "shield-alert": IconNode;
+    readonly "shield-check": IconNode;
+    readonly "shield-x": IconNode;
+    readonly square: IconNode;
+    readonly "thumbs-down": IconNode;
+    readonly "thumbs-up": IconNode;
+    readonly upload: IconNode;
+    readonly "volume-2": IconNode;
+    readonly x: IconNode;
+    readonly user: IconNode;
+    readonly mail: IconNode;
+    readonly phone: IconNode;
+    readonly calendar: IconNode;
+    readonly clock: IconNode;
+    readonly building: IconNode;
+    readonly "map-pin": IconNode;
+    readonly lock: IconNode;
+    readonly key: IconNode;
+    readonly "credit-card": IconNode;
+    readonly "at-sign": IconNode;
+    readonly hash: IconNode;
+    readonly globe: IconNode;
+    readonly link: IconNode;
+    readonly "circle-check": IconNode;
+    readonly "circle-x": IconNode;
+    readonly "triangle-alert": IconNode;
+    readonly info: IconNode;
+    readonly ban: IconNode;
+    readonly shield: IconNode;
+    readonly "arrow-left": IconNode;
+    readonly "arrow-right": IconNode;
+    readonly "external-link": IconNode;
+    readonly ellipsis: IconNode;
+    readonly "ellipsis-vertical": IconNode;
+    readonly menu: IconNode;
+    readonly house: IconNode;
+    readonly plus: IconNode;
+    readonly minus: IconNode;
+    readonly pencil: IconNode;
+    readonly trash: IconNode;
+    readonly "trash-2": IconNode;
+    readonly save: IconNode;
+    readonly download: IconNode;
+    readonly share: IconNode;
+    readonly funnel: IconNode;
+    readonly settings: IconNode;
+    readonly "rotate-cw": IconNode;
+    readonly maximize: IconNode;
+    readonly minimize: IconNode;
+    readonly "shopping-cart": IconNode;
+    readonly "shopping-bag": IconNode;
+    readonly package: IconNode;
+    readonly truck: IconNode;
+    readonly tag: IconNode;
+    readonly gift: IconNode;
+    readonly receipt: IconNode;
+    readonly wallet: IconNode;
+    readonly store: IconNode;
+    readonly "dollar-sign": IconNode;
+    readonly percent: IconNode;
+    readonly play: IconNode;
+    readonly pause: IconNode;
+    readonly "volume-x": IconNode;
+    readonly camera: IconNode;
+    readonly image: IconNode;
+    readonly film: IconNode;
+    readonly headphones: IconNode;
+    readonly "message-circle": IconNode;
+    readonly "message-square": IconNode;
+    readonly bell: IconNode;
+    readonly heart: IconNode;
+    readonly star: IconNode;
+    readonly eye: IconNode;
+    readonly "eye-off": IconNode;
+    readonly bookmark: IconNode;
+    readonly "calendar-days": IconNode;
+    readonly history: IconNode;
+    readonly timer: IconNode;
+    readonly folder: IconNode;
+    readonly "folder-open": IconNode;
+    readonly files: IconNode;
+    readonly sparkles: IconNode;
+    readonly zap: IconNode;
+    readonly sun: IconNode;
+    readonly moon: IconNode;
+    readonly flag: IconNode;
+    readonly monitor: IconNode;
+    readonly smartphone: IconNode;
+};
+/**
+ * Names of lucide icons that ship with the widget. Names not in this
+ * union return `null` from `renderLucideIcon` (with a console warning).
+ */
+type IconName = keyof typeof LUCIDE_ICONS;
+
 /**
  * Text content part for multi-modal messages
  */
@@ -2032,7 +2291,13 @@ type AgentWidgetControllerEventMap = {
  * new artifact content arrives or the host calls `showArtifacts()` on the widget handle.
  */
 type AgentWidgetArtifactsLayoutConfig = {
-    /** Flex gap between chat column and artifact pane. @default 0.5rem */
+    /**
+     * Flex gap between chat column and artifact pane.
+     * @default 0 (welded); detached uses the panel inset
+     * @remarks In welded appearances (`panel` / `seamless`) a nonzero gap opens a
+     * visible seam in the single card. It is honored geometrically (resize clamps
+     * and the seam handle account for it) but is usually undesired.
+     */
     splitGap?: string;
     /** Artifact column width in split mode. @default 40% */
     paneWidth?: string;
@@ -2063,16 +2328,39 @@ type AgentWidgetArtifactsLayoutConfig = {
     /** Optional max artifact width cap while resizing (`px` only). Layout still bounds by chat min width. */
     resizableMaxWidth?: string;
     /**
-     * Visual treatment for the artifact column in split mode.
-     * - `'panel'`: bordered sidebar with left border, gap, and shadow (default).
-     * - `'seamless'`: flush with chat: no border or shadow, container background, zero gap.
+     * Visual treatment for the artifact column in a desktop split.
+     * - `'panel'`: one welded card (border + radius wrap chat + pane) with a hairline
+     *   divider on the pane's chat-facing edge, zero gap (default).
+     * - `'seamless'`: the same welded card with no internal divider or chrome, zero gap.
+     * - `'detached'`: two separate elevated cards: gap from `--persona-panel-inset`,
+     *   all-side border and radius on each, and canvas background behind the split.
+     *   In an inline embed this also insets the split from the container edges on all
+     *   sides (the page canvas shows through), so the all-side margin no longer requires
+     *   `launcher.detachedPanel`.
+     *
+     * Default is `'panel'` unless `launcher.detachedPanel` is true, in which case an unset
+     * `paneAppearance` resolves to `'detached'`. An explicit value always wins.
      * @default 'panel'
      */
-    paneAppearance?: "panel" | "seamless";
+    paneAppearance?: "panel" | "seamless" | "detached";
     /** Border radius on the artifact pane (CSS length). Works with any `paneAppearance`. */
     paneBorderRadius?: string;
     /** CSS `box-shadow` on the artifact pane. Set `"none"` to suppress the default shadow. */
     paneShadow?: string;
+    /**
+     * CSS `box-shadow` for the chat column card in a detached split. Defaults to the same
+     * elevation as the artifact pane; set to `"none"` to keep the chat flat while the pane stays raised.
+     */
+    chatShadow?: string;
+    /**
+     * Chat column surface in a detached split. `"card"` (default) renders the chat as an inset card
+     * matching the artifact pane; `"flush"` renders the chat flush with the container (no border, radius,
+     * or shadow) and insets only the artifact pane, so the chat is flat background and the pane floats.
+     * Only affects an inline-embedded detached split (the container-filling case); in floating, docked,
+     * or sidebar modes it falls back to the card look.
+     * @default 'card'
+     */
+    chatSurface?: "card" | "flush";
     /**
      * Full `border` shorthand for the artifact `<aside>` (all sides). Overrides default pane borders.
      * Example: `"1px solid #cccccc"`.
@@ -2084,14 +2372,12 @@ type AgentWidgetArtifactsLayoutConfig = {
      */
     paneBorderLeft?: string;
     /**
-     * Desktop split only (not narrow-host drawer / not ≤640px): square the **main chat card’s**
-     * top-right and bottom-right radii, and round the **artifact pane’s** top-right and bottom-right
-     * to match `persona-rounded-2xl` (`--persona-radius-lg`) so the two columns read as one shell.
+     * @deprecated No-op. Panel and seamless splits now weld into one card by default.
      */
     unifiedSplitChrome?: boolean;
     /**
-     * When `unifiedSplitChrome` is true, outer-right corner radius on the artifact column (CSS length).
-     * @default matches theme large radius (`--persona-radius-lg`)
+     * Desktop welded split only: override the artifact pane's outer-right corner radius (CSS length).
+     * @default matches the panel radius (`--persona-panel-radius`)
      */
     unifiedSplitOuterRadius?: string;
     /**
@@ -2111,6 +2397,10 @@ type AgentWidgetArtifactsLayoutConfig = {
      * @default 'default'
      */
     toolbarPreset?: "default" | "document";
+    /** Visible title in the artifact toolbar. @default "Artifacts" */
+    toolbarTitle?: string;
+    /** Label for the artifact dismiss control. @default "Close" */
+    closeButtonLabel?: string;
     /**
      * When `toolbarPreset` is `document`, show a visible "Copy" label next to the copy icon.
      */
@@ -2125,6 +2415,17 @@ type AgentWidgetArtifactsLayoutConfig = {
     documentToolbarToggleActiveBackground?: string;
     /** Active view/source toggle border color. Sets `--persona-artifact-doc-toggle-active-border`. */
     documentToolbarToggleActiveBorderColor?: string;
+    /** Show an expand/collapse toggle in the artifact toolbar (both presets). Expanded fills the widget with the pane and hides the chat column. Default: false. */
+    showExpandToggle?: boolean;
+    /** Show the copy control in the `default` toolbar preset (the `document` preset always shows it). Default: false. */
+    showCopyButton?: boolean;
+    /** Edge fade on the scrollable tab strip. true = both ends (dynamic). @default true */
+    tabFade?: boolean | {
+        start?: boolean;
+        end?: boolean;
+    };
+    /** Tab fade width (CSS length). @default 24px */
+    tabFadeSize?: string;
     /**
      * Invoked when the document toolbar Refresh control is used (before the pane re-renders).
      * Use to replay `connectStream`, refetch, etc.
@@ -2148,20 +2449,349 @@ type AgentWidgetArtifactsLayoutConfig = {
         jsonPayload: string;
     }) => void | Promise<void>;
 };
+type PersonaArtifactDisplayMode = "card" | "panel" | "inline";
+/** 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;
+    title: string;
+    artifactType: string;
+    markdown?: string;
+    file?: PersonaArtifactFileMeta;
+    /** Component artifacts: pretty-printed { component, props } JSON. */
+    jsonPayload?: string;
+};
+/**
+ * Context passed to a `features.artifacts.statusLabel` function on every
+ * artifact streaming update, once per visible surface. Treat it as read-only:
+ * the function should be pure and fast (it runs per streaming delta, per
+ * surface).
+ */
+type PersonaArtifactStatusLabelContext = {
+    artifactId: string;
+    artifactType: "markdown" | "component";
+    title?: string;
+    /** The default subject, e.g. "document", "component", or a file type label like "HTML file". */
+    typeLabel: string;
+    file?: PersonaArtifactFileMeta;
+    /** Accumulated streamed content length so far (0 for component artifacts). */
+    chars: number;
+    /** Accumulated line count so far (0 for component artifacts). */
+    lines: number;
+    /** Milliseconds since this artifact's first streaming update was seen. */
+    elapsedMs: number;
+    /** Lazy accessor for the accumulated markdown source (empty string for component artifacts). Call only if needed; parsing cost is opt-in. */
+    content: () => string;
+    /** Which surface is asking, so hosts can shorten for cramped spots. */
+    surface: "card" | "inline-chrome" | "status-body";
+};
+/** A custom action button rendered in an artifact toolbar/card slot. */
+type PersonaArtifactCustomAction = {
+    /** Stable id, used for DOM wiring and keyed re-renders. */
+    id: string;
+    /** Accessible label; also the visible text when showLabel is true. */
+    label: string;
+    /** Registry icon name, or a factory returning your own element (e.g. a brand SVG). The factory result is author-owned code, not sanitized wire data. */
+    icon?: IconName | (() => HTMLElement | SVGElement);
+    /** Render icon + text instead of icon-only. Default: false. */
+    showLabel?: boolean;
+    /** Per-artifact gate, evaluated on each render. Omitted = always visible. */
+    visible?: (ctx: PersonaArtifactActionContext) => boolean;
+    /** May be async; rejections are swallowed like built-in action errors. */
+    onClick: (ctx: PersonaArtifactActionContext) => void | Promise<void>;
+};
 type AgentWidgetArtifactsFeature = {
     /** When true, Persona shows the artifact pane and handles artifact_* SSE events */
     enabled?: boolean;
     /** If set, artifact events for other types are ignored */
     allowedTypes?: PersonaArtifactKind[];
+    /**
+     * Where artifact bodies render. A single mode applies to all artifacts;
+     * the object form sets a default plus per-type overrides.
+     * Defaults to "panel" (current behavior).
+     */
+    display?: PersonaArtifactDisplayMode | {
+        default?: PersonaArtifactDisplayMode;
+        byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayMode>>;
+    };
     /** Split / drawer dimensions and launcher widen behavior */
     layout?: AgentWidgetArtifactsLayoutConfig;
     /**
-     * Called when an artifact card action is triggered (open, download).
-     * Return `true` to prevent the default behavior.
+     * Controls inline preview of previewable file artifacts (HTML/SVG written by
+     * a Claude Managed agent). When a markdown artifact carries `file` metadata,
+     * the pane can render an isolated `<iframe srcdoc>` sandbox instead of a code
+     * block.
+     */
+    filePreview?: {
+        /** Enable rendered preview for html/svg files. Defaults to enabled. Set false to force source view. */
+        enabled?: boolean;
+        /**
+         * `sandbox` attribute for the preview iframe. Defaults to `"allow-scripts"`.
+         * `allow-same-origin` is stripped (with a console warning) unless
+         * `dangerouslyAllowSameOrigin` is set: the opaque origin is what isolates
+         * the preview from the host page. Embedder-trusted config.
+         */
+        iframeSandbox?: string;
+        /**
+         * Allows `allow-same-origin` to pass through `iframeSandbox`. Off by
+         * default because it lets agent-written file content run with the host
+         * page's origin (DOM, storage, credentialed requests). Only set this when
+         * every previewed file source is fully trusted.
+         */
+        dangerouslyAllowSameOrigin?: boolean;
+        /**
+         * Loading treatment for the preview iframe. Default on.
+         *
+         * A sandboxed `iframe srcdoc` (opaque origin, `allow-scripts` only) paints
+         * blank until its content renders — seconds for artifacts that pull CDN
+         * scripts (React/Babel). The default shows a themed "Loading preview…"
+         * overlay over the iframe, dismissed the instant the content signals it has
+         * painted (an injected `postMessage` reporter) or a hard timeout elapses.
+         *
+         * `false` disables the overlay and the injected ready signal entirely (the
+         * srcdoc becomes the raw file source, the prior behavior). An object tunes
+         * the timing; omitted / `true` uses all defaults.
+         */
+        loading?: boolean | {
+            /** Show the overlay only if the preview is not ready after this many ms. Default 200. */
+            delayMs?: number;
+            /** Once shown, keep the overlay visible at least this long (anti-flicker). Default 300. */
+            minVisibleMs?: number;
+            /** Give up waiting and reveal the iframe regardless after this many ms. Default 8000. */
+            timeoutMs?: number;
+            /**
+             * Append the `postMessage` ready reporter to the srcdoc so the overlay
+             * dismisses on first paint rather than the iframe `load` event (which
+             * fires before post-DOMContentLoaded rendering like Babel compilation).
+             * Default true. When false, the overlay dismisses on `load` + a double
+             * `requestAnimationFrame`, or the timeout.
+             */
+            injectReadySignal?: boolean;
+            /**
+             * Escalation text shown beside the spinner after `labelDelayMs`.
+             * Default `"Starting preview..."`. `false` renders an icon-only
+             * indicator forever (no text ever). A short work-naming label is
+             * added only after a delay by design — icon-first, with text reserved
+             * for genuinely slow loads (per Geist/Sandpack guidance; HIG warns
+             * against the vague word "loading").
+             */
+            label?: string | false;
+            /**
+             * Delay before the escalation label fades in, measured from when the
+             * overlay actually becomes visible (i.e. after `delayMs`), not from
+             * iframe creation. Default 2000.
+             */
+            labelDelayMs?: number;
+            /**
+             * Full replacement for the default indicator (spinner + escalation
+             * label). Called once when the overlay is built; return any element
+             * (a brand mark, skeleton, custom animation) to own the indicator
+             * content entirely (the escalation-label logic is then skipped), or
+             * return `null` to fall back to the default. A thrown error also falls
+             * back. Mirrors `renderInline` / `renderCard`'s null-falls-back
+             * contract. The overlay backdrop, timing, and dismissal stay
+             * widget-owned either way.
+             */
+            renderIndicator?: (ctx: {
+                artifactId: string;
+                config: AgentWidgetConfig;
+            }) => HTMLElement | null;
+        };
+    };
+    /**
+     * Custom action buttons for the artifact pane toolbar, rendered between the
+     * refresh and expand/close controls in both toolbar presets. Re-read on live
+     * config updates.
+     */
+    toolbarActions?: PersonaArtifactCustomAction[];
+    /**
+     * Custom action buttons for the artifact reference card, rendered before the
+     * Download button on complete artifacts. Clicks are delegated, so they
+     * survive re-renders and page refresh.
+     */
+    cardActions?: PersonaArtifactCustomAction[];
+    /**
+     * File chrome (title bar + toolbar) around inline preview blocks
+     * (`display: "inline"`). Default when undefined: chrome on, with the built-in
+     * Copy and Expand controls. Pass `false` to render the bare preview body
+     * (frame → padded body, no chrome bar), or an object to toggle the built-in
+     * controls individually.
+     *
+     * Note: default-on chrome adds a title bar and buttons to every existing
+     * inline host on upgrade; set `inlineChrome: false` to opt out.
+     */
+    inlineChrome?: boolean | {
+        /** Show the built-in Copy button (complete artifacts only). Default true. */
+        showCopy?: boolean;
+        /** Show the built-in Expand button (opens the pane for this artifact). Default true. */
+        showExpand?: boolean;
+        /**
+         * Show the built-in rendered/source view toggle (complete artifacts
+         * only). Default true. The toggle is availability-gated: it appears only
+         * for file-backed markdown artifacts that have a rendered alternative to
+         * their source (previewable HTML/SVG, or markdown-kind files), and never
+         * when `inlineBody.viewMode: "source"` forces a source-only body. Plain
+         * markdown and component artifacts don't get it (the pane toggle covers
+         * those).
+         */
+        showViewToggle?: boolean;
+    };
+    /**
+     * Custom action buttons for the inline chrome toolbar, rendered before the
+     * built-in Copy/Expand controls on complete artifacts. Same shape as
+     * `cardActions`; each action's `visible` gate is respected and clicks are
+     * delegated, so they survive re-renders and page refresh.
+     */
+    inlineActions?: PersonaArtifactCustomAction[];
+    /**
+     * Replace the artifact tab strip entirely (Seam A). Return an element mounted in
+     * place of the built-in `.persona-artifact-list`; the pane still owns the toolbar,
+     * preview body, iframe reuse, and lazy-render gate. Re-invoked when the records or
+     * selection change. Custom bars own their own accessibility; use `createRovingTablist`
+     * to keep keyboard/tablist behavior. When set, the built-in strip (scroll, fade,
+     * tablist) is not rendered.
+     *
+     * Return either a fresh element per call, or the SAME element updated in place.
+     * Returning a stable element preserves internal state across selection changes:
+     * the pane skips remounting an unchanged node, so a roving tablist keeps keyboard
+     * focus on the selected tab (a fresh element per call drops focus and breaks
+     * Arrow-key nav). See the reference bars in `apps/web/src/artifact-demo.ts`.
+     */
+    renderTabBar?: (ctx: {
+        records: PersonaArtifactRecord[];
+        selectedId: string | null;
+        onSelect: (id: string) => void;
+    }) => HTMLElement;
+    /**
+     * Body layout for inline artifact blocks (`display: "inline"`). Controls how
+     * the block reserves height and behaves while a file/document artifact
+     * streams, so the streaming source no longer grows an unbounded `<pre>` and
+     * then snaps to the completed preview. Affects only the inline block; the
+     * artifact pane is unchanged.
+     *
+     * Defaults (a behavior change from prior versions, which grew with content
+     * during streaming): a fixed 320px streaming source window with tail-follow,
+     * a top edge fade, and an animated streaming→complete swap. Pass
+     * `height: "auto"` to restore the old grow-with-content streaming behavior.
+     */
+    inlineBody?: {
+        /** What the body shows while streaming. Default `"source"`. */
+        streamingView?: "source" | "status";
+        /**
+         * How the completed body renders. `"rendered"` (default) keeps the current
+         * behavior: file previews in a sandboxed iframe, markdown through the
+         * markdown pipeline. `"source"` always shows the raw syntax-highlighted
+         * source instead — for hosts where the artifact is input to the host system
+         * (a code editor, a query runner) rather than something to preview. Unlike
+         * `filePreview.enabled: false`, this also covers markdown-kind files and
+         * plain markdown artifacts. Component artifacts always render through the
+         * registry.
+         */
+        viewMode?: "rendered" | "source";
+        /**
+         * Body height per state. A number reserves that many px for the whole body
+         * region (border-box, padding included) with internal scroll — the
+         * zero-layout-shift path; `"auto"` means content-sized. A
+         * scalar applies to both the streaming and complete states; the object form
+         * sets them independently. Default `320` for both states.
+         *
+         * Note: with `"auto"` on the complete state, non-iframe bodies (rendered
+         * markdown, source view, component) are content-sized, but a file-preview
+         * iframe cannot be content-sized without postMessage plumbing, so it falls
+         * back to the CSS-var default (`--persona-artifact-inline-frame-height`,
+         * 320px).
+         *
+         * Numeric heights are applied via the CSS var
+         * `--persona-artifact-inline-body-height` on the block root. The older
+         * `--persona-artifact-inline-frame-height` var still overrides the iframe
+         * height when this one is unset, so themes pinned to it keep working.
+         */
+        height?: number | "auto" | {
+            streaming?: number | "auto";
+            complete?: number | "auto";
+        };
+        /**
+         * Tail-follow the newest streamed lines in a fixed-height source window: if
+         * the viewport is already at the bottom, keep it pinned as content arrives;
+         * if the reader scrolled up, don't fight them. Only meaningful for a numeric
+         * streaming height. Default `true`.
+         *
+         * Precedence: ignored when `overflow: "clip"` (a clipped window shows the
+         * top of the document and never scrolls, so there is no tail to follow).
+         */
+        followOutput?: boolean;
+        /**
+         * How a fixed-height source window handles content taller than the window.
+         *
+         * - `"scroll"` (default) — the current behavior: an internally scrollable
+         *   window that tail-follows the newest streamed lines (see `followOutput`),
+         *   so the reader sees the growing tail of the document.
+         * - `"clip"` — a fixed-height window that shows the TOP of the document,
+         *   `overflow: hidden` with no internal scroll and no tail-follow
+         *   (`followOutput` is ignored in this mode). When content overflows the
+         *   window a bottom edge fade signals there is more below (the top is always
+         *   visible, so a top fade never applies); an explicit `fadeMask` still wins
+         *   over this clip-mode default. When the inline chrome's Expand control is
+         *   enabled the whole body doubles as an expand hitbox (click / Enter / Space
+         *   opens the artifact in the pane), matching the industry inline-card
+         *   pattern; otherwise the clip is purely visual.
+         *
+         * Only meaningful for a numeric streaming/complete height. Default
+         * `"scroll"`.
+         */
+        overflow?: "scroll" | "clip";
+        /**
+         * Edge fade masks on the fixed-height streaming window (a top fade signals
+         * clipped content above, a bottom fade signals clipped content below). Each
+         * fade renders only when content is actually clipped on that edge, so with
+         * tail-follow pinned at the bottom the bottom fade stays inert until the
+         * reader scrolls up mid-stream. `true` = `{ top: true, bottom: true }`,
+         * `false` = none. Default `{ top: true, bottom: true }`.
+         */
+        fadeMask?: boolean | {
+            top?: boolean;
+            bottom?: boolean;
+        };
+        /**
+         * Animate the streaming→complete body swap. `"auto"` uses the View
+         * Transitions API when supported and `prefers-reduced-motion` is off;
+         * `"none"` swaps instantly. Default `"auto"`.
+         */
+        transition?: "auto" | "none";
+        /**
+         * What the block becomes once the artifact completes.
+         *
+         * - `"inline"` (default) — the streamed body stays inline forever, as
+         *   configured by the other `inlineBody` options.
+         * - `"card"` — the block streams inline as configured, then collapses to the
+         *   compact artifact reference card once the artifact completes (the Copilot
+         *   "chiclet" / Claude side-panel handoff pattern), keeping the thread
+         *   scannable. The collapse plays as a short CSS height transition (skipped
+         *   under `prefers-reduced-motion`); it does not use the View Transitions
+         *   API, so `transition` does not affect it. After the collapse the card's
+         *   normal actions apply (click opens the artifact pane). `viewMode`, the
+         *   inline rendered/source view toggle, `inlineActions`, and inline copy are
+         *   streaming-phase-only in this mode and inert once the block is a card
+         *   (there is nothing to toggle or copy on a collapsed card). Blocks that are
+         *   already complete when they first render (page-refresh hydration) render
+         *   the card directly, with no flash of the inline body and no animation.
+         *
+         * Default `"inline"`.
+         */
+        completeDisplay?: "inline" | "card";
+    };
+    /**
+     * Called when an artifact action is triggered (open, download, expand).
+     * Return `true` to intercept: the widget then does not change state.
+     * For `expand`, `expanded` is the state the toggle is about to enter and
+     * `artifactId` is the currently selected artifact (or `null` when none).
      */
     onArtifactAction?: (action: {
         type: 'open' | 'download';
         artifactId: string;
+    } | {
+        type: 'expand';
+        artifactId: string | null;
+        expanded: boolean;
     }) => boolean | void;
     /**
      * Custom renderer for artifact reference cards shown in the message thread.
@@ -2177,6 +2807,72 @@ type AgentWidgetArtifactsFeature = {
         config: AgentWidgetConfig;
         defaultRenderer: () => HTMLElement;
     }) => HTMLElement | null;
+    /**
+     * Custom renderer for inline artifact blocks (display: "inline"), mirroring
+     * `renderCard`. Return an element to replace the default inline preview,
+     * or null to use the default.
+     */
+    renderInline?: (context: {
+        artifact: {
+            artifactId: string;
+            title: string;
+            artifactType: string;
+            status: string;
+        };
+        config: AgentWidgetConfig;
+        defaultRenderer: () => HTMLElement;
+    }) => HTMLElement | null;
+    /**
+     * Text shown while an artifact streams, in place of the default
+     * `Generating <type>...` status. Applies to every streaming surface: the
+     * reference card status line, the inline chrome meta label, and the inline
+     * streaming status body (`inlineBody.streamingView: "status"`).
+     *
+     * - A plain string replaces the default label everywhere (localization or
+     *   brand voice).
+     * - A function is called on every artifact update for each visible surface;
+     *   it must be pure and fast. Returning a string sets the animated label
+     *   only. Returning `{ label, detail }` splits the status into an animated
+     *   label (re-applied only when its text changes, so the loading animation
+     *   stays stable) and a plain un-animated detail span that may update freely
+     *   per delta (live counters).
+     *
+     * Default when unset: the current behavior, `Generating <type>...` with no
+     * detail. If the function throws, the default label is used for that update
+     * (a bad host callback must never break rendering). There is deliberately no
+     * percent progress: streams do not announce total length, so counts and
+     * elapsed time are the only truthful signals.
+     */
+    statusLabel?: string | ((ctx: PersonaArtifactStatusLabelContext) => string | {
+        label: string;
+        detail?: string;
+    });
+    /**
+     * Animation applied to the artifact card's "Generating …" status text while
+     * the artifact streams. Character-by-character modes (`shimmer`,
+     * `shimmer-color`, `rainbow`) wrap each character in a span with a staggered
+     * `animation-delay`; `pulse` fades the whole status text; `none` disables the
+     * animation. Honors `prefers-reduced-motion`.
+     * @default "shimmer"
+     */
+    loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
+    /**
+     * Duration of one full animation cycle in milliseconds.
+     * Applies to pulse, shimmer, shimmer-color, and rainbow modes.
+     * @default 2000
+     */
+    loadingAnimationDuration?: number;
+    /**
+     * Primary color for shimmer-color animation mode.
+     * Defaults to the current text color.
+     */
+    loadingAnimationColor?: string;
+    /**
+     * Secondary/end color for shimmer-color animation mode.
+     * Creates a gradient sweep between `loadingAnimationColor` and this color.
+     * @default "#3b82f6"
+     */
+    loadingAnimationSecondaryColor?: string;
 };
 /**
  * How the transcript scrolls while an assistant response streams in.
@@ -2304,6 +3000,13 @@ type AgentWidgetToolCallDisplayFeature = {
      * @default false
      */
     grouped?: boolean;
+    /**
+     * Controls how a grouped tool sequence is rendered.
+     * - `"stack"`: show the group summary and each child tool row.
+     * - `"summary"`: show one consolidated summary row only.
+     * @default "stack"
+     */
+    groupedMode?: "stack" | "summary";
     /**
      * When false, tool call bubbles show only the collapsed summary with no
      * expand/collapse toggle. Users see tool awareness without full details.
@@ -2993,6 +3696,24 @@ type AgentWidgetLauncherConfig = {
      * @default false
      */
     sidebarMode?: boolean;
+    /**
+     * When true, the widget panel renders as a detached card inset within its region,
+     * with rounded corners on all sides and elevation (shadow plus hairline border),
+     * instead of sitting flush against the region edges.
+     *
+     * The gap around the card is themed via `theme.components.panel.inset`. The
+     * background revealed behind it is themed via `theme.components.panel.canvasBackground`
+     * in docked and inline embed modes. In sidebar mode the gap stays click-through, so the
+     * host page shows through it the same way it does in floating mode, and canvasBackground
+     * is a no-op there.
+     *
+     * Applies to sidebar, docked, and inline embed modes. Ignored in mobile fullscreen,
+     * where chrome is already suppressed. Floating mode is unchanged, since it already
+     * renders as a detached card.
+     *
+     * @default false
+     */
+    detachedPanel?: boolean;
     /**
      * Width of the sidebar panel when sidebarMode is true.
      * @default "420px"
@@ -5798,6 +6519,21 @@ type InjectComponentDirectiveOptions = {
      */
     sequence?: number;
 };
+/**
+ * Optional file metadata attached to a markdown artifact that represents a
+ * concrete file written by a Claude Managed agent (e.g. `/mnt/session/outputs/cat.html`).
+ * Additive: the artifact content stays a fenced code block on the wire for
+ * backward compatibility; new widgets use this to recover the raw source and
+ * offer a preview. Mirrors the `file` field on the core `artifact_start` event.
+ */
+type PersonaArtifactFileMeta = {
+    /** Full path of the written file (also used as the artifact title). */
+    path: string;
+    /** MIME type of the file (used for download and preview decisions). */
+    mimeType: string;
+    /** Fence language the content was encoded with (html/xml/md/text). */
+    language?: string;
+};
 type PersonaArtifactRecord = {
     id: string;
     artifactType: PersonaArtifactKind;
@@ -5806,6 +6542,8 @@ type PersonaArtifactRecord = {
     markdown?: string;
     component?: string;
     props?: Record<string, unknown>;
+    /** Present when this markdown artifact is a previewable file (see PersonaArtifactFileMeta). */
+    file?: PersonaArtifactFileMeta;
 };
 /** Programmatic artifact upsert (controller / window API) */
 type PersonaArtifactManualUpsert = {
@@ -5813,12 +6551,18 @@ type PersonaArtifactManualUpsert = {
     artifactType: "markdown";
     title?: string;
     content: string;
+    /** Optional file metadata for previewable file artifacts. */
+    file?: PersonaArtifactFileMeta;
+    /** Set false to update the registry/pane without a transcript block (pre-4.x behavior). */
+    transcript?: boolean;
 } | {
     id?: string;
     artifactType: "component";
     title?: string;
     component: string;
     props?: Record<string, unknown>;
+    /** Set false to update the registry/pane without a transcript block (pre-4.x behavior). */
+    transcript?: boolean;
 };
 type AgentWidgetEvent = {
     type: "message";
@@ -5853,6 +6597,8 @@ type AgentWidgetEvent = {
     artifactType: PersonaArtifactKind;
     title?: string;
     component?: string;
+    /** Present when this markdown artifact is a previewable file. */
+    file?: PersonaArtifactFileMeta;
 } | {
     type: "artifact_delta";
     id: string;