@runtypelabs/persona 4.7.0 → 4.9.0

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

@@ -1,3 +1,5 @@
+import { IconNode } from 'lucide';
+
 /**
  * Plugin interface for customizing widget components
  */
@@ -421,6 +423,8 @@ interface ComponentTokenSet {
     margin?: TokenReference<'spacing'>;
     shadow?: TokenReference<'shadow'>;
     opacity?: number;
+    /** Hover background — used by transparent variants like `button.ghost`. */
+    hoverBackground?: TokenReference<'color'>;
 }
 interface ButtonTokens extends ComponentTokenSet {
     primary: ComponentTokenSet;
@@ -445,6 +449,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 +617,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 +656,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 +676,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 +793,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 +842,7 @@ type RuntypeExecutionStreamEvent = ({
     totalSteps?: number;
     type: "execution_start";
 }) | ({
+    claudeManagedAgentId?: string;
     completedAt?: string;
     durationMs?: number;
     executionId: string;
@@ -808,6 +887,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 +933,7 @@ type RuntypeExecutionStreamEvent = ({
     type: "step_start";
 } | ({
     completedAt?: string;
+    cost?: number;
     durationMs?: number;
     error?: string;
     executionId: string;
@@ -950,6 +1039,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 +1152,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 +1259,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 +1317,7 @@ type RuntypeFlowSSEEvent = {
     completedAt?: string;
     duration?: number;
     durationMs?: number;
-    error?: string;
+    error?: string | null;
     executionId?: string;
     executionTime?: number;
     id?: string;
@@ -1251,13 +1361,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 +1540,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
  */
@@ -1480,6 +1741,446 @@ type AgentWidgetContextProviderContext = {
     config: AgentWidgetConfig;
 };
 type AgentWidgetContextProvider = (context: AgentWidgetContextProviderContext) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+/** A single selectable item in the mention menu (host-provided). */
+type AgentWidgetContextMentionItem = {
+    /** Stable key within its source. */
+    id: string;
+    /** Shown in the menu and on the chip (e.g. "App.tsx"). */
+    label: string;
+    /** Subtitle line in the menu. */
+    description?: string;
+    /** Lucide icon name. */
+    iconName?: string;
+    /**
+     * Accent color for this item's inline token (`display: "inline"`), any CSS
+     * color. Sets `--persona-mention-token-accent` on the token, tinting its pill
+     * background + icon/label — the per-item/per-type color knob (Slack/Linear
+     * style). Prefer setting the same color across a source's items for a "color
+     * per type" look, or theme by `[data-mention-source]` in CSS instead. Ignored
+     * in chip mode.
+     */
+    color?: string;
+    /** Group header override; defaults to the source's `label`. */
+    group?: string;
+    /** Optional recency/popularity hint the default matcher boosts on. */
+    recencyScore?: number;
+    /**
+     * SKILLS / SLASH-COMMANDS. When set, this item is a COMMAND (a verb) rather
+     * than a context mention (a noun), so selecting it dispatches a behavior
+     * instead of adding a context chip. Absent for ordinary mentions.
+     *
+     *  - `"prompt"`: a prompt macro. `resolve()` returns `insertText` (or
+     *    `llmAppend`) which is written into the composer (see `insertMode`);
+     *    `submitOnSelect` optionally sends it immediately. No chip.
+     *  - `"action"`: a client action. `action()` runs in the browser; no resolve,
+     *    no chip, no message sent (e.g. `/clear`, `/theme dark`).
+     *  - `"server"`: a server-invoked skill. Routed like a `resolveOn:"submit"`
+     *    mention whose `resolve().context` reaches the backend via request
+     *    `context.mentions.<sourceId>.<itemId>` (a flow/agent reads it).
+     */
+    command?: "prompt" | "action" | "server";
+    /**
+     * `command:"action"` handler. Receives the parsed `args` (text after the
+     * command name), plus a small `composer` capability + `config`/`messages`.
+     * Short-circuits the mention flow (no chip, no send). Ignored otherwise.
+     */
+    action?: (ctx: AgentWidgetContextMentionCommandContext) => void | Promise<void>;
+    /**
+     * `command:"prompt"` insertion mode. `"replace"` (default) swaps the whole
+     * composer value for the resolved text; `"insert-at-caret"` replaces only the
+     * `/token` span, keeping surrounding prose. Ignored otherwise.
+     */
+    insertMode?: "replace" | "insert-at-caret";
+    /**
+     * When true, a `command:"prompt"` submits the composer immediately after
+     * inserting its text (a one-shot macro). Ignored for other kinds.
+     */
+    submitOnSelect?: boolean;
+    /**
+     * COMMANDS only. Ghost hint for a free-text argument (e.g. "order id" →
+     * `/lookup ‹order id›` in the menu). Its presence switches the command to
+     * INLINE COMPLETION (Slack-style): selecting it fills `/name ` into the
+     * composer for inline arg entry instead of dispatching on select, and the
+     * command is executed at SUBMIT with the typed args. `command:"server"` items
+     * always use inline completion (their chip had no way to add an argument);
+     * for `"prompt"`/`"action"` items this is opt-in. Ignored for non-commands.
+     */
+    commandArgsPlaceholder?: string;
+};
+/**
+ * Capability object handed to a `command:"action"` handler. The widget exposes
+ * only composer-local operations; broader actions (clear the transcript, change
+ * theme) are wired by the host via closures over its own controller.
+ */
+type AgentWidgetContextMentionComposerCapability = {
+    /** Current composer text. */
+    getValue: () => string;
+    /** Replace composer text (fires `input`, moves caret to end, refocuses). */
+    setValue: (value: string) => void;
+    /** Submit the composer (same path as pressing send). */
+    submit: () => void;
+};
+/** Context passed to a `command:"action"` handler. */
+type AgentWidgetContextMentionCommandContext = {
+    /** Text typed after the command name (e.g. `staging` for `/deploy staging`). */
+    args: string;
+    config: AgentWidgetConfig;
+    messages: AgentWidgetMessage[];
+    composer: AgentWidgetContextMentionComposerCapability;
+};
+/** Reference stored on a sent message for transcript fidelity + chip rendering. */
+type AgentWidgetContextMentionRef = {
+    sourceId: string;
+    itemId: string;
+    label: string;
+    iconName?: string;
+    /** Accent color for the inline token (see `AgentWidgetContextMentionItem.color`). */
+    color?: string;
+};
+/**
+ * One ordered segment of a sent message's prose, for inline mention rendering
+ * (`contextMentions.display: "inline"`). Text runs and atomic mention tokens
+ * interleave in document order so the sent bubble re-renders `@tokens` in place
+ * and composer history can round-trip them. Display/transcript concern only —
+ * the model still sees resolved bodies via `llmContent`/`contentParts`.
+ */
+type AgentWidgetContentSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "mention";
+    ref: AgentWidgetContextMentionRef;
+};
+/**
+ * The payload a source returns from `resolve()` for one selected item.
+ * Lead with `llmAppend` — it is the only channel guaranteed to reach the model
+ * with no backend changes.
+ */
+type AgentWidgetContextMentionPayload = {
+    /**
+     * PRIMARY, model-visible channel. Appended to this user message's LLM content
+     * so the model actually sees the context with no backend changes.
+     */
+    llmAppend?: string;
+    /**
+     * `command:"prompt"` macros only. Text written into the COMPOSER on select
+     * (see `AgentWidgetContextMentionItem.insertMode`) — distinct from the hidden
+     * `llmAppend` context channel. Falls back to `llmAppend` when omitted.
+     */
+    insertText?: string;
+    /** Extra content parts (e.g. file text / image) via the multi-modal path. */
+    contentParts?: ContentPart[];
+    /**
+     * OPT-IN structured channel. Merged into request `context` under
+     * `mentions.<sourceId>.<itemId>` for flows/agents that read it. NOTE: ambient
+     * `context` is NOT guaranteed to reach the model — use `llmAppend` if you need
+     * the model to see it.
+     */
+    context?: Record<string, unknown>;
+};
+/**
+ * One resolved mention, handed to `contextMentions.llmFormat` to build the
+ * model-visible block. `text` is the source's `llmAppend`; `ref`/`item` carry
+ * the selection identity/metadata for a custom formatter (e.g. a source-specific
+ * wrapper or a path from `item`).
+ */
+type AgentWidgetMentionLlmEntry = {
+    /** The mention's display label (from `ref.label`). */
+    label: string;
+    /** The resolved model-visible body (the source's `llmAppend`). */
+    text: string;
+    ref: AgentWidgetContextMentionRef;
+    item: AgentWidgetContextMentionItem;
+};
+type AgentWidgetContextMentionSearchContext = {
+    messages: AgentWidgetMessage[];
+    config: AgentWidgetConfig;
+    /** Aborts when the next keystroke supersedes this in-flight search. */
+    signal: AbortSignal;
+};
+type AgentWidgetContextMentionResolveContext = AgentWidgetContextMentionSearchContext & {
+    /** Plain-text composer value at resolve time. */
+    composerText: string;
+    /**
+     * For `command` items: the text typed after the command name (e.g.
+     * `"123"` for `/lookup 123`). Empty string for ordinary mentions.
+     */
+    args: string;
+};
+type AgentWidgetContextMentionSource = {
+    id: string;
+    /** Group header shown in the menu. */
+    label: string;
+    /**
+     * Filter items for the current `@query` (empty query → recent/popular).
+     * Implement server-side search for large/remote sets, or return all items and
+     * let the widget rank them with `defaultMentionFilter`
+     * (see `createStaticMentionSource` for the common case).
+     */
+    search: (query: string, ctx: AgentWidgetContextMentionSearchContext) => AgentWidgetContextMentionItem[] | Promise<AgentWidgetContextMentionItem[]>;
+    /**
+     * Fetch the payload for dispatch. Called once when the user SELECTS the item
+     * (eagerly, cached on the chip, abortable on removal) unless `resolveOn` is
+     * `"submit"`. A throw/abort drops the mention via `onMentionResolveError`.
+     */
+    resolve: (item: AgentWidgetContextMentionItem, ctx: AgentWidgetContextMentionResolveContext) => AgentWidgetContextMentionPayload | Promise<AgentWidgetContextMentionPayload>;
+    /**
+     * When to call `resolve()`:
+     *  - `"select"` (default): eager on pick; parallelizes the fetch with the user
+     *    finishing their sentence so submit stays instant.
+     *  - `"submit"`: defer to send time, for time-sensitive sources (e.g. current
+     *    page state that may change between select and send).
+     * @default "select"
+     */
+    resolveOn?: "select" | "submit";
+    /**
+     * COMMAND sources only. Resolve a `/name` (the first token of a command line)
+     * to its menu item, for submit-time inline-command dispatch and the menu's
+     * "typing args now" suppression. `createSlashCommandsSource` sets this; plain
+     * `@`-mention sources leave it undefined.
+     */
+    matchCommand?: (name: string) => AgentWidgetContextMentionItem | undefined;
+};
+/** Context passed to the optional `renderMentionMenu` override. */
+type AgentWidgetContextMentionMenuRenderContext = {
+    /** Current trigger query ("" when freshly opened). */
+    query: string;
+    /** Grouped, ranked, capped results ready to paint. */
+    groups: {
+        source: AgentWidgetContextMentionSource;
+        items: AgentWidgetContextMentionItem[];
+    }[];
+    /** Per-source async state for loading/empty/error rendering, keyed by source id. */
+    status: Record<string, "loading" | "ready" | "empty" | "error">;
+    /** Index into the flat keyboard-traversal order. */
+    activeIndex: number;
+    /** Commit a selection (strips `@query`, adds chip, resolves on select). */
+    select: (item: AgentWidgetContextMentionItem) => void;
+    /** Close the menu, keeping a literal `@`. */
+    close: () => void;
+};
+/** Context passed to the optional `renderMentionItem` per-row override. */
+type AgentWidgetContextMentionItemRenderContext = {
+    /** The item to render. */
+    item: AgentWidgetContextMentionItem;
+    /** The source this item came from (its group). */
+    source: AgentWidgetContextMentionSource;
+    /** Current trigger query, for highlighting matches. */
+    query: string;
+    /** True when this row is the keyboard-highlighted one at render time. */
+    active: boolean;
+    /** Position in the flat keyboard-traversal order. */
+    index: number;
+};
+/** Context passed to the optional `renderMentionChip` override. */
+type AgentWidgetContextMentionChipRenderContext = {
+    ref: AgentWidgetContextMentionRef;
+    /** Resolve-on-select lifecycle for spinner→ready→error UI. */
+    status: "resolving" | "ready" | "error";
+    /**
+     * The resolved payload, once available (select-resolved sources only). Use it
+     * to preview already-fetched content on hover. Undefined while `status` is
+     * `"resolving"`, on `"error"`, and for `resolveOn:"submit"` sources (which
+     * resolve at send time, not while the chip sits in the composer — for those,
+     * `ref.itemId` carries the source key you can re-read on demand, e.g. a CSS
+     * selector for the smart-dom source).
+     */
+    payload?: AgentWidgetContextMentionPayload;
+    /** Remove the chip; aborts any in-flight resolve. */
+    remove: () => void;
+};
+/**
+ * Where a trigger char is allowed to open the menu:
+ *  - `"anywhere"` (default): after any whitespace or start (the `@` rule).
+ *  - `"line-start"`: only when the char before the trigger is a newline or the
+ *    start of input — the natural rule for `/` slash-commands.
+ *  - `"input-start"`: only at index 0 of the composer.
+ */
+type AgentWidgetMentionTriggerPosition = "anywhere" | "line-start" | "input-start";
+/**
+ * A SECOND (or Nth) trigger channel sharing the same menu engine — e.g. `/` for
+ * slash-commands alongside `@` for context. The legacy `trigger`/`sources`
+ * fields form the implicit first channel; `triggers[]` adds more. At any caret
+ * at most one channel is active, so all channels drive one menu/controller.
+ */
+type AgentWidgetMentionTriggerChannel = {
+    /** Trigger character (e.g. "/"). */
+    trigger: string;
+    /** Sources for this channel (searched only when this trigger is active). */
+    sources: AgentWidgetContextMentionSource[];
+    /** Where the trigger may open. @default "anywhere" */
+    triggerPosition?: AgentWidgetMentionTriggerPosition;
+    /**
+     * Let the query span spaces so a command can take ARGS (`/deploy staging`).
+     * A newline still ends it. Pair with `triggerPosition: "line-start"` for
+     * slash-commands. @default false
+     */
+    allowSpaces?: boolean;
+    /** Show a composer affordance button for this channel. @default false */
+    showButton?: boolean;
+    /** Icon for this channel's affordance button. */
+    buttonIconName?: string;
+    /** Tooltip / aria-label for this channel's affordance button. */
+    buttonTooltipText?: string;
+    /** Placeholder for this channel's picker search field. */
+    searchPlaceholder?: string;
+};
+type AgentWidgetContextMentionConfig = {
+    /** @default false */
+    enabled?: boolean;
+    /**
+     * Show the visible composer affordance button (the discoverable entry point).
+     * Strongly recommended; the bare `@` trigger alone is hard to discover for
+     * non-technical users. @default true
+     */
+    showButton?: boolean;
+    /**
+     * Icon for the affordance button (any registered Lucide name). Defaults to a
+     * "+" signifier — the consumer-recognized "add context" affordance — rather
+     * than an "@" glyph, which reads as power-user. Use `"at-sign"` on a
+     * developer/power-user surface. @default "plus"
+     */
+    buttonIconName?: string;
+    /** Tooltip / aria-label for the affordance button. @default "Add context" */
+    buttonTooltipText?: string;
+    /**
+     * Placeholder for the picker's search field, shown when the menu is opened
+     * from the affordance button (a Cursor/Copilot-style picker that inserts no
+     * trigger character). The typed-trigger path keeps its query in the textarea
+     * and never shows this field. @default "Search context…"
+     */
+    searchPlaceholder?: string;
+    /** Trigger character. @default "@" */
+    trigger?: string;
+    /**
+     * Where the primary `trigger` may open the menu. @default "anywhere"
+     */
+    triggerPosition?: AgentWidgetMentionTriggerPosition;
+    /**
+     * ADDITIONAL trigger channels sharing this engine — e.g. a `/` slash-command
+     * channel next to `@` context. Each channel has its own trigger char,
+     * sources, and position rule. See `AgentWidgetMentionTriggerChannel`.
+     */
+    triggers?: AgentWidgetMentionTriggerChannel[];
+    /** Max mentions per message. @default 8 */
+    maxMentions?: number;
+    /** Max items shown per source group before "keep typing to narrow". @default 6 */
+    maxItemsPerGroup?: number;
+    /**
+     * Debounce for ASYNC source search only (ms). Synchronous sources and the
+     * menu's first paint are never debounced. @default 150
+     */
+    searchDebounceMs?: number;
+    /** Registered mention sources (search + resolve). */
+    sources: AgentWidgetContextMentionSource[];
+    /** Chip icon fallback when a source/item omits one. @default "at-sign" */
+    chipIconName?: string;
+    /**
+     * How each resolved mention's `llmAppend` text is wrapped into a delimited
+     * block before it is prepended to the model-visible message content. Blocks
+     * are joined with a blank line and the typed prose follows last.
+     *
+     * - `"fenced"` (default): a fenced code block with the label in the info
+     *   string, e.g. selecting `App.tsx` emits:
+     *   ```text
+     *   ```App.tsx
+     *   <file body>
+     *   ```
+     *   ```
+     *   The fence auto-escalates (four+ backticks) when the body itself contains a
+     *   fence, so a body can never terminate its own wrapper.
+     * - `"document"`: Anthropic's long-context document shape, e.g.:
+     *   ```text
+     *   <document index="1">
+     *   <source>App.tsx</source>
+     *   <document_content>
+     *   <file body>
+     *   </document_content>
+     *   </document>
+     *   ```
+     *   Prefer this for prose/document-shaped sources per Anthropic's long-context
+     *   guidance (indexed `<document>` blocks improve grounding and citation). A
+     *   body containing the literal `</document_content>` closing tag falls back to
+     *   the fenced block for that entry to avoid a broken XML boundary.
+     * - function form: fully owns the block for one mention — its return string is
+     *   used verbatim (no extra wrapping), joined with the other blocks. `index` is
+     *   the 0-based position among the message's mention blocks.
+     *
+     * @default "fenced"
+     */
+    llmFormat?: "fenced" | "document" | ((entry: AgentWidgetMentionLlmEntry, index: number) => string);
+    /**
+     * How `@` selections appear in the composer and sent user bubble.
+     *
+     * - `"chip"` (default): strip `@query` on select; show a compact pill in the
+     *   composer context row; `content` is prose-only.
+     * - `"inline"`: insert an atomic styled token in the sentence (Slack/Linear/
+     *   Cursor style), backed by a contenteditable composer. Slash-command channels
+     *   (`triggers[]` with `/`) stay inline-text regardless — they already use the
+     *   `/name args` model, not chips. `renderMentionChip` is ignored for `@`
+     *   mentions in this mode.
+     *
+     * The resolved-context channel (`llmContent`/`contentParts`) is unchanged
+     * across both modes — inline tokens are a display concern.
+     *
+     * @default "chip"
+     */
+    display?: "chip" | "inline";
+    /**
+     * Fired when a pick is rejected: it duplicates an existing chip in chip display
+     * (`"duplicate"` — inline display allows the same item as multiple tokens, so it
+     * never rejects for this reason), hits `maxMentions` (`"limit"`), or (inline
+     * display) the composer text changed between parse and commit so the token could
+     * not be inserted (`"stale"`).
+     */
+    onMentionRejected?: (item: AgentWidgetContextMentionItem, reason: "duplicate" | "limit" | "stale") => void;
+    /**
+     * A `resolve()` that throws/aborts: the mention is dropped and the message
+     * still sends. Surface a non-blocking notice here if desired.
+     */
+    onMentionResolveError?: (item: AgentWidgetContextMentionItem, error: unknown) => void;
+    /**
+     * MID-LEVEL render override for the autocomplete menu. The widget still owns
+     * trigger detection, search, debounce/abort, keyboard nav, and positioning;
+     * you only supply the menu markup and drive selection through `ctx`. Omit to
+     * use the built-in grouped menu. @default built-in
+     */
+    renderMentionMenu?: (ctx: AgentWidgetContextMentionMenuRenderContext) => HTMLElement;
+    /**
+     * NARROW render override for a single result row's INNER content, keeping the
+     * built-in menu chrome (group headers, loading/empty/error, keyboard nav, the
+     * "keep typing" hint). The widget keeps the `role="option"` wrapper and its
+     * click/hover wiring; you return only the row's contents. For full menu
+     * control use `renderMentionMenu` instead. Highlight is CSS-driven via the
+     * wrapper's `[data-active]` attribute, so this is called once per render, not
+     * on every arrow key. Ignored when `renderMentionMenu` is set. @default built-in
+     */
+    renderMentionItem?: (ctx: AgentWidgetContextMentionItemRenderContext) => HTMLElement;
+    /**
+     * MID-LEVEL render override for a single context chip. Return your own pill
+     * (must include an accessible remove control wired to `ctx.remove`); reflect
+     * `ctx.status` for resolve-on-select. Omit to use the built-in compact pill.
+     * @default built-in
+     */
+    renderMentionChip?: (ctx: AgentWidgetContextMentionChipRenderContext) => HTMLElement;
+    /**
+     * INLINE display only (`display: "inline"`). Render override for a single inline
+     * mention TOKEN — the atomic styled node that sits in the sentence, in both the
+     * contenteditable composer and the read-only sent bubble. Return your own
+     * element (e.g. a fully custom colored pill); the composer marks it
+     * `contenteditable="false"` and stamps `data-mention-id` so it stays atomic.
+     * Omit to use the built-in pill (icon + `@label`, tinted by
+     * `--persona-mention-token-accent` / `ref.color`, themeable per source via the
+     * `[data-mention-source]` attribute). Ignored in chip mode.
+     * @default built-in
+     */
+    renderMentionToken?: (ctx: AgentWidgetContextMentionTokenRenderContext) => HTMLElement;
+};
+/** Render context for `renderMentionToken`. `readonly` is true in the sent bubble. */
+type AgentWidgetContextMentionTokenRenderContext = {
+    ref: AgentWidgetContextMentionRef;
+    readonly: boolean;
+};
 type AgentWidgetRequestPayloadMessage = {
     role: AgentWidgetMessageRole;
     content: MessageContent;
@@ -2032,7 +2733,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 +2770,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 +2814,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 +2839,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 +2857,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 +2891,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 +3249,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 +3442,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 +4138,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"
@@ -5036,6 +6199,18 @@ type AgentWidgetConfig = {
     }) => string;
     plugins?: AgentWidgetPlugin[];
     contextProviders?: AgentWidgetContextProvider[];
+    /**
+     * Context mentions: let users explicitly pull external context into a turn by
+     * typing `@` or clicking a visible composer button, both opening one shared
+     * searchable menu of host-provided sources. Selecting a mention adds a
+     * removable pill chip; resolved content reaches the model via `llmAppend`
+     * (default) or the opt-in structured `context` channel.
+     *
+     * Disabled by default. When enabled, the mention runtime is lazy-loaded from a
+     * sibling chunk on first use, so sites that leave it off pay no bundle cost.
+     * See `docs/context-mentions-plan.md`.
+     */
+    contextMentions?: AgentWidgetContextMentionConfig;
     requestMiddleware?: AgentWidgetRequestMiddleware;
     actionParsers?: AgentWidgetActionParser[];
     actionHandlers?: AgentWidgetActionHandler[];
@@ -5578,6 +6753,25 @@ type AgentWidgetMessage = {
      * The `content` field contains the text-only representation for display.
      */
     contentParts?: ContentPart[];
+    /**
+     * Context mentions attached to this (user) message, for transcript fidelity +
+     * chip rendering in the sent bubble. Refs only — the resolved payloads are
+     * merged into `llmContent`/`contentParts` (model-visible) at send time.
+     */
+    contextMentions?: AgentWidgetContextMentionRef[];
+    /**
+     * Ordered prose + mention blocks for inline-mode rendering and composer history
+     * recall (`contextMentions.display: "inline"`). Present only on inline-mode user
+     * messages; when omitted the sent bubble falls back to the chip row derived from
+     * `contextMentions`. Display/transcript concern only — not the model channel.
+     */
+    contentSegments?: AgentWidgetContentSegment[];
+    /**
+     * Resolved opt-in structured mention context for this (user) message, merged
+     * into the request `context` under `mentions.<sourceId>.<itemId>` by the
+     * client. Internal: set at send time from each source's `resolve().context`.
+     */
+    mentionContext?: Record<string, unknown>;
     streaming?: boolean;
     variant?: AgentWidgetMessageVariant;
     sequence?: number;
@@ -5798,6 +6992,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 +7015,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 +7024,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 +7070,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;