@runtypelabs/persona 4.17.1 → 4.18.0

package/dist/context-mentions.d.cts

@@ -21,6 +21,8 @@ interface AgentWidgetPluginStorage {
     remove: (key: string) => void;
 }
 
+type ShortcutScope = "widget" | "page";
+
 type AgentWidgetTransformSuggestionsContext = {
     /**
      * Fresh copy of the suggestions entering this plugin, already normalized:
@@ -69,6 +71,37 @@ type AgentWidgetRenderWelcomeContext = {
     /** Teardown for this render; runs before the next one and on destroy. */
     onCleanup: (fn: () => void) => void;
 };
+/** Context for one `railSections` entry. Frozen per invocation. */
+type AgentWidgetRailSectionContext = {
+    /** Current rail width state. The section re-renders whenever this flips. */
+    collapsed: boolean;
+    presentation: ResolvedHistoryPresentation;
+    /** The same frozen action path the default rows and `renderHistoryView` use. */
+    actions: AgentWidgetHistoryRenderActions;
+};
+/** A plugin-contributed navigation section in the history rail. */
+type AgentWidgetRailSection = {
+    /** Stable identity, stamped as `data-persona-rail-section`. */
+    id: string;
+    /** Default `"above-conversations"`. */
+    placement?: AgentWidgetHistoryRailSection["placement"];
+    /** Optional heading, styled like a conversation date-group heading. */
+    title?: string;
+    /** Section body. Null renders nothing for the current state. */
+    render: (context: AgentWidgetRailSectionContext) => Element | null;
+};
+/** A plugin-contributed keyboard shortcut, bound per widget instance. */
+type AgentWidgetPluginShortcut = {
+    /** Stable identity, used in duplicate/throw warnings. */
+    id: string;
+    /** e.g. `"mod+b"`. "mod" is Command on Apple platforms, Control elsewhere. */
+    combo: string;
+    /** Default `"widget"`: fires only from inside the widget mount. */
+    scope?: ShortcutScope;
+    /** Returning false skips the binding for this keypress. */
+    when?: () => boolean;
+    run: () => void;
+};
 type AgentWidgetSuggestionSelectContext = {
     suggestion: AgentWidgetResolvedSuggestion;
     surface: AgentWidgetSuggestionSurface;
@@ -339,6 +372,10 @@ interface AgentWidgetPlugin {
      * Custom renderer for loading indicator
      * Return null to use default renderer (or config-based renderer)
      *
+     * Covers the streaming indicator ('inline', 'standalone') and the transcript
+     * skeleton shown while a conversation opened from the Messages list loads
+     * ('conversation-open').
+     *
      * @example
      * ```typescript
      * renderLoadingIndicator: ({ location, defaultRenderer }) => {
@@ -390,6 +427,118 @@ interface AgentWidgetPlugin {
      * Return null to use default renderer.
      */
     renderEventStreamPayload?: (context: EventStreamPayloadRenderContext) => HTMLElement | null;
+    /**
+     * Replace the complete history ("Messages") navigation contents in either
+     * host. Plugins run by priority and the first non-null element wins; null
+     * falls through to the default full view, which then applies the first
+     * non-null header/row/state hook at each slot.
+     *
+     * Calling `defaultRenderer()` bypasses this hook only: the default view is
+     * built and its lower-level slots still arbitrate, including this plugin's.
+     * Return it (or an element containing it) to compose rather than replace.
+     *
+     * The hook replaces contents, not orchestration. Persona keeps placement,
+     * open/close, responsive rail <-> panel movement, inertness, Escape, the
+     * confirmation dialogs, live announcements, and focus fallback. Fetch nothing
+     * directly: `actions.refresh()` is the only way to reload the list.
+     *
+     * @example
+     * ```typescript
+     * renderHistoryView: ({ conversations, actions, presentation, onCleanup }) => {
+     *   const rail = document.createElement("nav");
+     *   rail.dataset.presentation = presentation;
+     *   for (const conversation of conversations) {
+     *     const row = document.createElement("button");
+     *     row.textContent = conversation.title;
+     *     row.addEventListener("click", () => void actions.openConversation(conversation.id));
+     *     rail.appendChild(row);
+     *   }
+     *   const timer = setInterval(() => void actions.refresh(), 60_000);
+     *   onCleanup(() => clearInterval(timer));
+     *   return rail;
+     * }
+     * ```
+     */
+    renderHistoryView?: (context: AgentWidgetRenderHistoryViewContext) => HTMLElement | null;
+    /**
+     * Replace the standard Messages header while retaining its list/state UI.
+     * Return null to use the default top bar. A custom header may not remove the
+     * keyboard close path or falsify the resolved open state.
+     */
+    renderHistoryHeader?: (context: AgentWidgetRenderHistoryHeaderContext) => HTMLElement | null;
+    /**
+     * Replace one conversation row while retaining standard paging/grouping.
+     * Return null to use the default row.
+     */
+    renderHistoryConversation?: (context: AgentWidgetRenderHistoryConversationContext) => HTMLElement | null;
+    /**
+     * Replace loading, empty, error, authentication, rate-limit, or recovery
+     * content in the list region. Return null to use the default block.
+     */
+    renderHistoryState?: (context: AgentWidgetRenderHistoryStateContext) => HTMLElement | null;
+    /**
+     * Replace the transcript-level error surface shown when opening a
+     * conversation from the Messages list fails. Plugins run by priority and
+     * the first non-null element wins; null falls through to the default block.
+     *
+     * Persona keeps the centered transcript column, the alert role, and the
+     * composer gate around the returned element. `retry`/`back` are the only
+     * exits: both route through the token-guarded open flow, so do not fetch
+     * directly. `back` is absent when there is no Messages surface to return
+     * to; do not render a back affordance without it.
+     */
+    renderHistoryOpenError?: (context: AgentWidgetRenderHistoryOpenErrorContext) => HTMLElement | null;
+    /**
+     * Contribute navigation sections to the history rail, stacked around the
+     * conversation list in `placement` order. Rail only: the panel presentation
+     * renders none of them, and `features.history.rail.sections` (config) comes
+     * first inside each bucket, then plugins in plugin order.
+     *
+     * `render` is re-invoked with the new `collapsed` value whenever the rail
+     * collapses or expands, and its return replaces the previous content;
+     * returning null renders nothing for that state. A throwing `render` warns
+     * once and drops that section only, leaving the rest of the rail alone. An id
+     * a config section already owns is dropped with a warning.
+     *
+     * Keep heavy UI in the host bundle: `render` may return a skeleton and
+     * hydrate it after the host's own dynamic import resolves.
+     *
+     * @example
+     * ```typescript
+     * railSections: [
+     *   {
+     *     id: "pinned",
+     *     title: "Pinned",
+     *     render: ({ collapsed, actions }) => {
+     *       if (collapsed) return null;
+     *       const list = document.createElement("div");
+     *       const row = document.createElement("button");
+     *       row.textContent = "Weekly report";
+     *       row.addEventListener("click", () => void actions.openConversation("c1"));
+     *       list.appendChild(row);
+     *       return list;
+     *     }
+     *   }
+     * ]
+     * ```
+     */
+    railSections?: AgentWidgetRailSection[];
+    /**
+     * Keyboard shortcuts registered for the lifetime of each widget instance the
+     * plugin is active in, and unregistered on its teardown. `combo` is written
+     * as `"mod+b"` / `"mod+shift+k"`, where "mod" is Command on Apple platforms
+     * and Control elsewhere. `scope` defaults to `"widget"` (only while focus is
+     * inside the mount); `when` returning false skips the keypress. A combo
+     * another binding already owns warns and is ignored, first registration wins.
+     *
+     * @example
+     * ```typescript
+     * shortcuts: [
+     *   { id: "open-inbox", combo: "mod+shift+i", run: () => openInbox() }
+     * ]
+     * ```
+     */
+    shortcuts?: AgentWidgetPluginShortcut[];
     /**
      * Called when plugin is registered
      */
@@ -548,6 +697,10 @@ interface SemanticTokens {
 }
 interface ComponentTokenSet {
     background?: TokenReference<'color'>;
+    /**
+     * Text and glyph color on `background`. `HeaderTokens` also derives its
+     * unset text, icon, and border colors from this pair.
+     */
     foreground?: TokenReference<'color'>;
     border?: TokenReference<'color'>;
     borderRadius?: TokenReference<'radius'>;
@@ -575,6 +728,15 @@ interface LauncherTokens extends ComponentTokenSet {
     size: string;
     iconSize: string;
     shadow: TokenReference<'shadow'>;
+    /**
+     * Stroke weight of the launcher glyphs, the agent icon and the
+     * call-to-action arrow alike. Unitless, and must be a STRING (`"1.75"`,
+     * never `1.75`: the token resolver silently skips numbers). Applied as CSS,
+     * so it beats the attribute the icons render with. Inert for emoji / image
+     * launchers, which have no svg.
+     * @default "1.5", matching the header's controlStrokeWidth
+     */
+    iconStrokeWidth?: string;
 }
 interface PanelTokens extends ComponentTokenSet {
     width: string;
@@ -595,28 +757,212 @@ interface TextStyleTokens {
     letterSpacing?: string;
     color?: TokenReference<'color'>;
 }
+/**
+ * Header band tokens. `background` plus `foreground` (inherited from
+ * `ComponentTokenSet`) is the pair that colors the band: `foreground` anchors
+ * the header text, and every text, action-icon, and border color the theme
+ * leaves unset derives from the pair. Derivation only fills unset keys, so an
+ * explicit key always wins, and `iconBackground` / `iconForeground` (the avatar
+ * tile) keep their own defaults rather than deriving.
+ */
 interface HeaderTokens extends ComponentTokenSet {
     background: TokenReference<'color'>;
-    border: TokenReference<'color'>;
+    /**
+     * Hairline under the header. Unset, it derives as
+     * `color-mix(in srgb, foreground 14%, background)`, then the divider color.
+     */
+    border?: TokenReference<'color'>;
     borderRadius: TokenReference<'radius'>;
     /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
     iconBackground: TokenReference<'color'>;
     /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
     iconForeground: TokenReference<'color'>;
-    /** Legacy alias of `title.color`; `title.color` wins when both are set. */
-    titleForeground: TokenReference<'color'>;
-    /** Legacy alias of `subtitle.color`; `subtitle.color` wins when both are set. */
-    subtitleForeground: TokenReference<'color'>;
+    /**
+     * Legacy alias of `title.color`; `title.color` wins when both are set.
+     * Unset, the title takes `foreground`, then the primary color.
+     */
+    titleForeground?: TokenReference<'color'>;
+    /**
+     * Legacy alias of `subtitle.color`; `subtitle.color` wins when both are set.
+     * Unset, the subtitle takes `color-mix(in srgb, foreground 72%, background)`,
+     * then the muted text color.
+     */
+    subtitleForeground?: TokenReference<'color'>;
     /** Header title typography (next to the icon, or minimal layout title). */
     title?: TextStyleTokens;
     /** Header subtitle typography, for the line under the title. */
     subtitle?: TextStyleTokens;
-    /** Default color for clear / close icon buttons when launcher overrides are unset. */
-    actionIconForeground: TokenReference<'color'>;
+    /**
+     * Default color for clear / close icon buttons when launcher overrides are
+     * unset. Itself unset, it takes the same
+     * `color-mix(in srgb, foreground 72%, background)` as the subtitle, then the
+     * muted text color.
+     */
+    actionIconForeground?: TokenReference<'color'>;
+    /**
+     * Edge of every header icon button: close, clear chat, `trailingActions`, and
+     * the Messages toggle. Per-control config keys (`launcher.closeButtonSize`,
+     * `launcher.clearChat.size`) still win. Coarse pointers floor the hit area at
+     * 40px regardless. @default "32px"
+     */
+    controlSize?: string;
+    /** Glyph box inside a header control. @default "20px" */
+    controlIconSize?: string;
+    /**
+     * Stroke weight of the glyph inside a header control. Unitless, as an SVG
+     * stroke-width (e.g. `"1.75"`). Sparse-viewBox glyphs (the close X) render
+     * at 0.7 of it so their heavier visible weight still matches a dense
+     * sibling. @default "1.5"
+     */
+    controlStrokeWidth?: string;
     /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
     shadow?: string;
     /** Override the header bottom border (e.g., `none`). */
     borderBottom?: string;
+    /**
+     * Floor for the header strip's height (e.g. `"56px"`). Pin it together with
+     * `components.history.railHeader.minHeight` so the Messages rail header and
+     * the conversation header read as one continuous band.
+     */
+    minHeight?: string;
+}
+/** Messages (conversation history) surfaces. */
+interface HistoryTokens {
+    /**
+     * The Messages rail's own top strip, which runs beside the widget header
+     * when `features.history.presentation` resolves to `rail`.
+     */
+    railHeader?: {
+        /** Strip background. Defaults to the rail's surface color. */
+        background?: TokenReference<'color'>;
+        /** Full border-bottom shorthand (raw CSS, e.g. `"1px solid #e5e7eb"`). @default "0" */
+        border?: string;
+        /** Strip height floor. Defaults to `components.header.minHeight`, then 56px. */
+        minHeight?: string;
+        /**
+         * The strip's view title ("Messages"). 14px/600 in the text color by
+         * default; set the type keys to restyle it.
+         */
+        title?: TextStyleTokens;
+    };
+    /**
+     * The "Conversations" heading over the list block. Visible in rail
+     * presentation only (the panel keeps it screen-reader-only). 14px/600 in
+     * the text color by default. Every key is pinned in the widget CSS, so
+     * host-page heading rules never restyle it.
+     */
+    listHeading?: TextStyleTokens;
+    /**
+     * The muted sub-headers inside the Messages surface: date groups ("Today",
+     * "Yesterday") and rail nav section titles (`features.history.rail.sections`
+     * `title`, e.g. "Workspace"). 13px/500 in the muted text color in the rail
+     * (the panel keeps date groups screen-reader-only). Every key is pinned in
+     * the widget CSS, so host-page heading rules never restyle them.
+     */
+    groupHeading?: TextStyleTokens;
+    /**
+     * The floating rail that a collapsed
+     * `features.history.rail.collapsedBehavior: "overlay"` opens on hover. It
+     * hangs below the trigger in the conversation header; its width and edge
+     * stay `features.history.rail` geometry, not tokens.
+     */
+    overlay?: {
+        /** Gap from the trigger, the docked edge, and the bottom. @default "8px" */
+        margin?: string;
+        /** Corner radius, on all four corners. @default "16px" */
+        borderRadius?: string;
+        /** Elevation over the conversation. @default "0 12px 40px rgba(0, 0, 0, 0.25)" */
+        shadow?: string;
+        /** Surface behind the rail. Defaults to the rail's own surface color. */
+        background?: TokenReference<'color'>;
+    };
+    /**
+     * Destructive action text (row Delete, "Delete all conversations").
+     * Defaults to `palette.colors.error.600` in light schemes and a lighter
+     * red in the built-in dark theme so the 14px labels keep AA contrast.
+     */
+    dangerForeground?: TokenReference<'color'>;
+    /**
+     * The delete/forget confirmation dialog the shell shows for destructive
+     * history actions. The danger pair is always emitted (`--persona-danger`
+     * / `--persona-danger-fg`); scrim and shadow keep the built-in look when
+     * unset.
+     */
+    confirm?: {
+        /**
+         * Destructive button fill. Defaults to `palette.colors.error.700` in
+         * light schemes and `error.600` in the built-in dark theme.
+         */
+        dangerBackground?: TokenReference<'color'>;
+        /** Destructive button label. @default "#ffffff" */
+        dangerForeground?: TokenReference<'color'>;
+        /** Overlay behind the dialog. @default "rgba(15, 23, 42, 0.45)" */
+        scrim?: TokenReference<'color'>;
+        /** Card elevation (raw CSS shadow). */
+        shadow?: string;
+    };
+    /** The per-row overflow menu in the Messages list (rail and panel). */
+    menu?: {
+        /**
+         * Menu surface. Defaults to the list surface lifted 8% toward white so
+         * the menu reads as elevated in dark schemes.
+         */
+        background?: TokenReference<'color'>;
+        /** Corner radius. @default "12px" */
+        borderRadius?: string;
+    };
+    /**
+     * Enter/exit motion of the Messages surface. Only the body slides; the bar
+     * is persistent chrome and never animates. Durations are milliseconds and 0
+     * disables that leg; `prefers-reduced-motion` always wins over these.
+     */
+    motion?: {
+        /** Entrance slide-and-fade duration: bare ms number, or a CSS time string. @default 180 */
+        enterDurationMs?: number | string;
+        /** Entrance easing. @default "cubic-bezier(0, 0, 0.2, 1)" */
+        enterEasing?: string;
+        /** Exit slide-and-fade duration: bare ms number, or a CSS time string. @default 160 */
+        exitDurationMs?: number | string;
+        /** Exit easing. @default "cubic-bezier(0.4, 0, 1, 1)" */
+        exitEasing?: string;
+    };
+}
+/**
+ * The portaled icon-control tooltip (header controls, composer buttons) and
+ * its trailing shortcut hint chip. Unset keys keep the built-in dark look.
+ */
+interface TooltipTokens {
+    /** Bubble and arrow fill. @default "#111827" */
+    background?: TokenReference<'color'>;
+    /** Label color. @default "#ffffff" */
+    foreground?: TokenReference<'color'>;
+    /** Trailing shortcut hint color. @default "rgba(255, 255, 255, 0.55)" */
+    hintForeground?: TokenReference<'color'>;
+    /** Bubble corner radius. Defaults to `palette.radius.sm`. */
+    borderRadius?: TokenReference<'radius'>;
+    /** Label type size. @default "12px" */
+    fontSize?: string;
+    /** Bubble inset, full CSS shorthand. @default "6px 12px" */
+    padding?: TokenReference<'spacing'>;
+    /** Bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+    shadow?: string;
+    /** Render the caret pointing at the control. @default true */
+    arrow?: boolean;
+    /** Wrap width. @default "min(320px, calc(100vw - 16px))" */
+    maxWidth?: string;
+}
+/**
+ * The hover-revealed action row under a message (copy, vote, read aloud).
+ * Unset keys inherit the shared ghost icon-button wash, which is already
+ * scheme-aware, so most themes never need this group.
+ */
+interface MessageActionsTokens {
+    /** Hover fill. Defaults to `components.button.ghost.hoverBackground`. */
+    hoverBackground?: TokenReference<'color'>;
+    /** Hover icon color. Defaults to `semantic.colors.text`. */
+    hoverForeground?: TokenReference<'color'>;
+    /** Button corner radius. Defaults to `palette.radius.md`. */
+    borderRadius?: TokenReference<'radius'>;
 }
 interface MessageTokens {
     user: {
@@ -962,7 +1308,13 @@ interface ComponentTokens {
     launcher: LauncherTokens;
     panel: PanelTokens;
     header: HeaderTokens;
+    /** Messages rail chrome. */
+    history?: HistoryTokens;
+    /** Portaled icon-control tooltip and its shortcut hint chip. */
+    tooltip?: TooltipTokens;
     message: MessageTokens;
+    /** Hover-revealed per-message action row (copy, vote, read aloud). */
+    messageActions?: MessageActionsTokens;
     /** Welcome / intro card shown above the message list. */
     introCard?: IntroCardTokens;
     /** Markdown surfaces (chat + artifact pane). */
@@ -1461,6 +1813,101 @@ type TargetResolver = (id: string) => {
     payload: Record<string, unknown>;
 };
 
+/**
+ * History provider seam (`docs/visitor-history-implementation-plan.md` D9).
+ * Session/UI history code depends on this interface, never on
+ * `AgentWidgetClient`.
+ *
+ * The module stays under `internal/` but its contract is public: `index-core.ts`
+ * re-exports these declarations so integrators can implement
+ * `features.history.provider`. The provider REGISTRY beside it stays private.
+ */
+
+/** Fixed for the lifetime of one opened history view/action chain. */
+interface HistoryOperationContext {
+    scope: HistoryScope;
+}
+/**
+ * An authorized-but-not-yet-applied conversation activation. The provider must
+ * not mutate the active chat until `commit()`.
+ */
+interface PreparedHistoryActivation {
+    conversationId: string;
+    conversationRevision: string;
+    /** Apply the already-authorized provider-specific transport/session binding. */
+    commit(): void | Promise<void>;
+    /** Idempotently abandon a stale/superseded activation without changing chat. */
+    discard(): void;
+}
+interface HistoryListOptions {
+    cursor?: string;
+    limit?: number;
+    targetId?: string;
+    context: HistoryOperationContext;
+}
+interface HistoryListResult {
+    items: HistoryConversationSummary[];
+    nextCursor: string | null;
+}
+interface HistoryPageOptions {
+    cursor?: string;
+    /** Lets the provider synthesize stable timestamps across page boundaries. */
+    beforeCreatedAt?: string;
+    context: HistoryOperationContext;
+}
+interface HistoryPageResult {
+    summary: HistoryConversationSummary;
+    /** Already mapped; the visitor-visible projection lives in `content`. */
+    messages: AgentWidgetMessage[];
+    conversationRevision: string;
+    /** Follow for the next older page. `null` at the start of the transcript. */
+    nextCursor: string | null;
+}
+interface HistoryDeleteAllOptions {
+    /** Absent means the whole authorized scope, never the UI default. */
+    targetId?: string;
+    context: HistoryOperationContext;
+}
+/** The contract a `features.history.provider` implementation satisfies. */
+interface HistoryProvider {
+    readonly capabilities: {
+        scopes: readonly HistoryScope[];
+    };
+    getIdentityStatus(): HistoryIdentityStatus;
+    subscribeIdentityStatus(callback: (status: HistoryIdentityStatus) => void): () => void;
+    list(opts: HistoryListOptions): Promise<HistoryListResult>;
+    getPage(id: string, opts: HistoryPageOptions): Promise<HistoryPageResult>;
+    prepareOpen(id: string, opts: {
+        context: HistoryOperationContext;
+    }): Promise<PreparedHistoryActivation>;
+    prepareStartNew(opts: {
+        context: HistoryOperationContext;
+    }): Promise<PreparedHistoryActivation>;
+    delete(id: string, opts: {
+        context: HistoryOperationContext;
+    }): Promise<void>;
+    deleteAll(opts: HistoryDeleteAllOptions): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Optional capability: visitor-scoped rename/star. Absence hides every
+     * update affordance (star glyphs, built-in title-menu actions). A user-set
+     * title pins: the provider must never let a later auto-generated title
+     * overwrite one set through this call.
+     */
+    update?(id: string, patch: HistoryConversationPatch, opts: {
+        context: HistoryOperationContext;
+    }): Promise<HistoryConversationSummary>;
+    /**
+     * Optional capability. Absence hides "forget this device". Resolves (never
+     * rejects) on remote failure; credentials are cleared in `finally` either way.
+     */
+    resetDevice?(): Promise<{
+        remoteRevocationConfirmed: boolean;
+    }>;
+    subscribeAvailability?(callback: (available: boolean) => void): () => void;
+}
+
 /**
  * Curated registry of lucide icons available to `renderLucideIcon`.
  *
@@ -1545,6 +1992,7 @@ declare const LUCIDE_ICONS: {
     readonly "ellipsis-vertical": IconNode;
     readonly menu: IconNode;
     readonly house: IconNode;
+    readonly "panel-left": IconNode;
     readonly plus: IconNode;
     readonly minus: IconNode;
     readonly pencil: IconNode;
@@ -2706,6 +3154,8 @@ type AgentWidgetArtifactsLayoutConfig = {
     documentToolbarToggleActiveBackground?: string;
     /** Active view/source toggle border color. Sets `--persona-artifact-doc-toggle-active-border`. */
     documentToolbarToggleActiveBorderColor?: string;
+    /** Active view/source toggle icon color (defaults to `documentToolbarIconColor`). Sets `--persona-artifact-doc-toggle-active-color`. */
+    documentToolbarToggleActiveColor?: 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. */
@@ -2718,13 +3168,20 @@ type AgentWidgetArtifactsLayoutConfig = {
     /** 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.
+     * Invoked when the document toolbar Refresh control is used (before the pane
+     * re-renders). The button renders only while this handler is set: the refresh
+     * glyph universally reads "reload this preview" (Claude artifacts, v0), so
+     * keep the handler scoped to refreshing the rendered artifact — regenerating
+     * content or resetting the conversation belongs to message-level or
+     * conversation-level controls, not artifact chrome.
      */
     onDocumentToolbarRefresh?: () => void | Promise<void>;
     /**
      * Optional copy dropdown entries (shown when `documentToolbarShowCopyChevron` is true and this array is non-empty).
      * The main Copy control still performs default copy unless `onDocumentToolbarCopyMenuSelect` handles everything.
+     * Without a handler, built-in ids work out of the box: `download` saves the
+     * artifact (real filename/MIME for file artifacts, `<title>.md` otherwise);
+     * `markdown`/`md` and `json`/`source` copy that form to the clipboard.
      */
     documentToolbarCopyMenuItems?: Array<{
         id: string;
@@ -2732,13 +3189,24 @@ type AgentWidgetArtifactsLayoutConfig = {
     }>;
     /**
      * When set, invoked for the chevron menu (and can override default copy per `actionId`).
+     * Return `false` to fall through to the widget's built-in behavior for that
+     * action id (`download` saves the artifact; copy ids copy); any other return
+     * value keeps the handler's outcome as final.
      */
     onDocumentToolbarCopyMenuSelect?: (payload: {
         actionId: string;
         artifactId: string | null;
         markdown: string;
         jsonPayload: string;
-    }) => void | Promise<void>;
+        /** File metadata when the selected artifact is a previewable file. */
+        file?: PersonaArtifactFileMeta;
+        /** Filename the built-in download would use (file basename, or `<title>.md`). */
+        suggestedFilename: string;
+        /** MIME type paired with `suggestedFilename`. */
+        mime: string;
+        /** Raw content the built-in download would write (unfenced source for file artifacts). */
+        content: string;
+    }) => void | boolean | Promise<void | boolean>;
 };
 /**
  * Where the artifact body renders by default. Every mode shows the compact
@@ -3581,6 +4049,11 @@ type AgentWidgetFeatureFlags = {
      * pills + optional free-text input.
      */
     askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+    /**
+     * Per-visitor conversation history. Client token mode only; disabled by
+     * default so no capability flag is sent on init and no UI mounts.
+     */
+    history?: AgentWidgetHistoryFeature;
     /**
      * Built-in `suggest_replies` follow-ups. When the assistant invokes the
      * tool, the widget shows the suggestions using `suggestions.followUps` and
@@ -3773,6 +4246,604 @@ type AgentWidgetAskUserQuestionFeature = {
     /** Style overrides for the sheet and pills. */
     styles?: AgentWidgetAskUserQuestionStyles;
 };
+/**
+ * Copy overrides for the visitor-facing conversation history surface. These are
+ * the widget's only localization mechanism for history, so every user-visible
+ * history string is listed here.
+ */
+interface AgentWidgetHistoryCopy {
+    /** Title of the history view. Defaults to "Messages". */
+    viewTitle?: string;
+    /** Heading shown when the visitor has no stored conversations. */
+    emptyTitle?: string;
+    /** Body text shown when the visitor has no stored conversations. */
+    emptyDescription?: string;
+    /** Heading shown when a history request fails. */
+    errorTitle?: string;
+    /** Body text shown when a history request fails. */
+    errorDescription?: string;
+    /** Label for the retry action on the error state. */
+    retryLabel?: string;
+    /** Heading shown after a 429 rate-limited history response. */
+    rateLimitedTitle?: string;
+    /** Body text shown after a 429 rate-limited history response. */
+    rateLimitedDescription?: string;
+    /** Confirmation prompt before deleting a single conversation. */
+    deleteConversationConfirm?: string;
+    /** Confirmation prompt before deleting every conversation in the active scope. */
+    clearHistoryConfirm?: string;
+    /** Confirmation prompt before detaching this browser from its history identity. */
+    resetIdentityConfirm?: string;
+    /** Label for the action that starts a new server conversation. */
+    newConversationLabel?: string;
+    /** Label for the action that prepends the previous transcript page. */
+    showEarlierMessagesLabel?: string;
+    /** Accessible label for the transcript skeleton while a conversation loads. */
+    openConversationLoadingLabel?: string;
+    /** Body text when a selected conversation failed to load. */
+    openConversationErrorTitle?: string;
+    /** Label for the retry action after a conversation failed to load. */
+    openConversationRetryLabel?: string;
+    /** Label for the return-to-messages action after a conversation failed to load. */
+    openConversationBackLabel?: string;
+    /** Status notice after a deleted conversation was recovered into a fresh one. */
+    conversationDeletedNotice?: string;
+    /** Status notice after this browser was detached from its history identity. */
+    identityResetNotice?: string;
+    /** Status notice when a local reset succeeded but server revocation was unconfirmed. */
+    identityResetUnconfirmedNotice?: string;
+    /** Pinned group heading for starred conversations. */
+    groupStarred?: string;
+    /** Time-group heading for conversations updated today. */
+    groupToday?: string;
+    /** Time-group heading for conversations updated yesterday. */
+    groupYesterday?: string;
+    /** Time-group heading for the trailing 7-day window. */
+    groupPrevious7Days?: string;
+    /** Time-group heading for the trailing 30-day window. */
+    groupPrevious30Days?: string;
+    /** Time-group heading for older conversations, grouped by month and year. */
+    groupMonthYear?: string;
+    /** Scope title when history is limited to this browser. */
+    browserOnlyTitle?: string;
+    /** Scope description when history is limited to this browser. */
+    browserOnlyDescription?: string;
+    /** Scope title while an identity proof is being resolved. */
+    verifyingTitle?: string;
+    /** Scope description while an identity proof is being resolved. */
+    verifyingDescription?: string;
+    /** Scope title when history is available across signed-in devices. */
+    verifiedTitle?: string;
+    /** Scope description when history is available across signed-in devices. */
+    verifiedDescription?: string;
+    /** Scope title when the visitor must sign in again to view account history. */
+    authenticationRequiredTitle?: string;
+    /** Scope description when the visitor must sign in again to view account history. */
+    authenticationRequiredDescription?: string;
+    /** Scope title when the host identity provider threw or rejected. */
+    identityProviderFailedTitle?: string;
+    /** Scope description when the host identity provider threw or rejected. */
+    identityProviderFailedDescription?: string;
+    /** Scope title when the server did not admit a supplied identity proof. */
+    proofNotAdmittedTitle?: string;
+    /** Scope description when the server did not admit a supplied identity proof. */
+    proofNotAdmittedDescription?: string;
+    /** Label for the action that retries identity resolution. */
+    retryIdentityLabel?: string;
+    /** Accessible name of the header control that opens history. */
+    openHistoryLabel?: string;
+    /** Accessible name of that control while a turn is streaming or resuming. */
+    openHistoryBusyLabel?: string;
+    /** Least-destructive action in every history confirmation dialog. */
+    confirmCancelLabel?: string;
+    /** Heading of the delete-one confirmation. */
+    deleteConversationConfirmTitle?: string;
+    /** Confirming action of the delete-one confirmation. */
+    deleteConversationConfirmLabel?: string;
+    /** Heading of the delete-all confirmation. */
+    clearHistoryConfirmTitle?: string;
+    /** Confirming action of the delete-all confirmation. */
+    clearHistoryConfirmLabel?: string;
+    /** Delete-all body used when the resolved scope is the signed-in user. */
+    clearHistoryVerifiedConfirm?: string;
+    /** Heading of the forget-this-device confirmation. */
+    resetIdentityConfirmTitle?: string;
+    /** Confirming action of the forget-this-device confirmation. */
+    resetIdentityConfirmLabel?: string;
+    /** Panel back control; returns to the surface that opened Messages. */
+    backLabel?: string;
+    /** Rail close control, shown only when the rail is not collapsible. */
+    closeLabel?: string;
+    /** Rail collapse toggle while the rail is expanded. */
+    collapseLabel?: string;
+    /** Rail collapse toggle while the rail is collapsed to icons. */
+    expandLabel?: string;
+    /** Accessible name of the docked rail's drag-resize handle. */
+    resizeLabel?: string;
+    /** Accessible status while the first page loads. */
+    loadingLabel?: string;
+    /** Label of the paging action below the last group. */
+    loadMoreLabel?: string;
+    /** Label of that action while its page is in flight. */
+    loadingMoreLabel?: string;
+    /**
+     * Heading over the conversation list. Visible in rail presentation, where it
+     * carries the list overflow trigger; sr-only in panel presentation.
+     */
+    conversationsTitle?: string;
+    /** Accessible name of the per-row overflow trigger and its menu. */
+    rowActionsLabel?: string;
+    /** Accessible name of the list-level overflow trigger and its menu. */
+    listOptionsLabel?: string;
+    /** Delete item inside the per-row overflow menu. */
+    deleteConversationLabel?: string;
+    /** Delete-all item inside the list overflow menu. */
+    clearHistoryLabel?: string;
+    /** Forget-this-device item inside the list overflow menu. */
+    resetIdentityLabel?: string;
+    /** Row message count. `{count}` placeholder. */
+    messageCountLabel?: string;
+    /** Row message count for exactly one message. */
+    messageCountLabelOne?: string;
+    /** Announced after a single conversation was deleted. */
+    conversationRemovedNotice?: string;
+    /** Announced after every conversation in scope was deleted. */
+    historyClearedNotice?: string;
+    /** Heading shown when history is unavailable for this surface. */
+    unavailableTitle?: string;
+    /** Body text shown when history is unavailable for this surface. */
+    unavailableDescription?: string;
+    /** Heading of the post-deletion replacement-init recovery state. */
+    newConversationRequiredTitle?: string;
+    /** Body text of the post-deletion replacement-init recovery state. */
+    newConversationRequiredDescription?: string;
+    /** Rate-limited wait guidance. `{seconds}` placeholder. */
+    rateLimitedWaitDescription?: string;
+    /** Row-adjacent error after a failed open. */
+    openFailedLabel?: string;
+    /** Row-adjacent error after a failed delete. */
+    deleteFailedLabel?: string;
+    /** Relative time for the most recent bucket. */
+    relativeNow?: string;
+    /** Relative time in minutes. `{value}` placeholder. */
+    relativeMinutes?: string;
+    /** Relative time in hours. `{value}` placeholder. */
+    relativeHours?: string;
+    /** Relative time in days. `{value}` placeholder. */
+    relativeDays?: string;
+    /** Relative time in weeks. `{value}` placeholder. */
+    relativeWeeks?: string;
+    /** Relative time in years. `{value}` placeholder. */
+    relativeYears?: string;
+}
+/**
+ * One row in a `features.history.rail.sections` navigation section. Icon
+ * precedence, highest first: `renderIcon`, then `iconUrl`, then `icon`.
+ * Whichever resolves first is built once and reused for the item's lifetime.
+ */
+interface AgentWidgetHistoryRailSectionItem {
+    /** Stable identity, stamped as `data-persona-rail-item`. */
+    id: string;
+    /** Visible text, and the default `aria-label` of the button. */
+    label: string;
+    /**
+     * Lucide name from the widget's built-in icon registry (see `IconName`). A
+     * name outside the registry warns once and the row renders label-only.
+     */
+    icon?: IconName | (string & {});
+    /** Image URL or data URI, rendered as a decorative `img` in the icon slot. */
+    iconUrl?: string;
+    /** Full custom icon node. Returning null renders the row label-only. */
+    renderIcon?: () => Element | null;
+    /** Small trailing text chip, for a count or a short status word. */
+    badge?: string;
+    /** Invoked on click. A throw is caught and warned once per section. */
+    onSelect: () => void;
+}
+/** One navigation section in the history rail, above or below the list. */
+interface AgentWidgetHistoryRailSection {
+    /** Stable identity, stamped as `data-persona-rail-section`. */
+    id: string;
+    /** Optional heading, styled like a conversation date-group heading. */
+    title?: string;
+    /** Default `"above-conversations"`. */
+    placement?: "above-conversations" | "below-conversations" | "footer";
+    items: AgentWidgetHistoryRailSectionItem[];
+}
+/**
+ * Host-defined item in the list overflow menu (the `…` beside the
+ * conversation-list heading). Rendered above the built-in destructive items.
+ */
+interface AgentWidgetHistoryListAction {
+    /** Stable identity; keeps menu focus keys stable across re-renders. */
+    id: string;
+    label: string;
+    /** Destructive (red) styling like the built-in delete-all. Default false. */
+    danger?: boolean;
+    /** Receives the conversation summaries loaded at selection time. */
+    onSelect: (context: {
+        conversations: HistoryConversationSummary[];
+    }) => void | Promise<void>;
+}
+/**
+ * Feature config for per-visitor conversation history. Without a `provider`,
+ * client token mode only: the built-in Runtype backend needs one, so the UI
+ * never renders for proxy/agent sessions. A `provider` lifts that restriction.
+ */
+interface AgentWidgetHistoryFeature {
+    /** Master switch. Default false: no capability flag on init, no UI. */
+    enabled?: boolean;
+    /**
+     * Custom conversation-history backend. Supply one to run the history UX
+     * (list, open, delete, delete-all, header title binding) against your own
+     * storage in ANY session mode, including a custom `apiUrl` backend with no
+     * client token. Omitted, history falls back to the built-in Runtype backend,
+     * which requires client token mode.
+     *
+     * Pass either an instance or a factory. The factory form is called once per
+     * widget instance, so a single script-tag config object (assembled before
+     * install) can back several widgets without sharing provider state. Passing a
+     * new factory identity through `update()` rebuilds the provider.
+     *
+     * Failures are signalled by throwing `HistoryProviderError` with a `code` from
+     * `HistoryProviderErrorCode`. The view branches on that code alone: it never
+     * reads message text, and an untyped throw degrades to a generic error state.
+     *
+     * `prepareOpen`/`prepareStartNew` resolve BEFORE anything visible changes:
+     * they return a `PreparedHistoryActivation` whose `commit()` applies the
+     * already-authorized binding and whose `discard()` idempotently abandons a
+     * superseded activation, leaving the active chat untouched. The widget calls
+     * exactly one of the two per prepared activation.
+     *
+     * Optional capabilities hide their affordances when absent: no `update`
+     * removes the rename/star actions (including the built-in title-menu `star`),
+     * and no `resetDevice` removes "forget this device".
+     *
+     * The provider's `capabilities.scopes` is authoritative: the widget derives a
+     * default scope (`"verified-user"` when `getIdentityProof` is configured,
+     * otherwise `"browser"`) and narrows it to what the provider advertises, so a
+     * browser-only provider is never asked for a scope it cannot serve. An
+     * explicit `features.history.scope` is a hard request and still fails closed
+     * with `unsupported_scope`. `getIdentityProof` is never called for a supplied
+     * provider, and `HistoryOperationContext` carries only the resolved scope;
+     * report your own identity through `getIdentityStatus()` /
+     * `subscribeIdentityStatus()`, which is what the scope banner and its retry
+     * affordance read.
+     *
+     * Reopening the last conversation after a page reload is the host's job: the
+     * widget's boot resume runs only on the built-in Runtype path, so with a
+     * supplied provider the transcript is restored by the storage adapter while
+     * `getActiveConversationId()` starts null (no active row, no
+     * conversation-bound header title) until something opens a conversation.
+     * Persist the id yourself and call `controller.openConversation(id)` on ready
+     * if you want the last conversation to come back automatically.
+     *
+     * @example
+     * ```js
+     * features: { history: { enabled: true, provider: () => myProvider } }
+     * ```
+     */
+    provider?: HistoryProvider | (() => HistoryProvider);
+    /** Page size for the conversation list (default 25, server max 100). */
+    pageSize?: number;
+    /**
+     * Default history placement. "panel" replaces the conversation surface;
+     * "rail" requests a side navigation host whenever it is at least 720px wide
+     * and collapses to panel below that; "auto" uses rail only for a wide inline
+     * or docked shell and keeps floating launchers panel-based at every width.
+     * Default "panel".
+     */
+    presentation?: "panel" | "rail" | "auto";
+    /**
+     * Geometry of the rail navigation column. `side` picks the edge it docks to
+     * (default "left", beside the conversation); `width` is its fixed width in
+     * px, clamped to 200-400 (default 260). `collapsible` (default true) puts a
+     * collapse toggle in the rail header that shrinks it to a 52px icon rail, and
+     * `defaultCollapsed` (default false) picks the state a visitor who has never
+     * toggled it starts in. The chosen state is remembered per visitor alongside
+     * the other `persistState` keys. Ignored in panel presentation.
+     */
+    rail?: {
+        side?: "left" | "right";
+        width?: number;
+        collapsible?: boolean;
+        defaultCollapsed?: boolean;
+        /**
+         * Drag handle on the docked rail's divider edge, resizing it live within
+         * the same 200 to 400 clamp `width` takes. Default false. The chosen width
+         * is remembered per visitor alongside the other `persistState` keys and
+         * outranks a later `width` update, the way the collapsed state does; the
+         * floating overlay rail inherits it but is never itself resizable, and a
+         * collapsed icon column ignores it until it expands again.
+         */
+        resizable?: boolean;
+        /**
+         * Shape of the COLLAPSED rail. `"icon-rail"` (default) keeps the 52px icon
+         * column beside the conversation. `"overlay"` removes the column entirely:
+         * a trigger takes the leading edge of the conversation header, hovering or
+         * tapping it floats the expanded rail over the conversation, and clicking
+         * it pins the rail back open. The floating rail is transient, so leaving
+         * it, Escape, a click outside, or selecting a conversation all dismiss it;
+         * its own header toggle docks it instead, being the control the pointer
+         * finds there. Geometry follows `width` and `side`; the collapsed rail's
+         * chunk is not loaded until the first hover. Ignored when `collapsible` is
+         * false or in panel presentation.
+         */
+        collapsedBehavior?: "icon-rail" | "overlay";
+        /**
+         * One brand declaration, placed in both of the rail's identity spots: the
+         * header's heading area when expanded (the mark leading, `copy.viewTitle`
+         * beside it as the wordmark), and the collapse toggle's rest face when the
+         * rail is collapsed, where hover and keyboard focus reveal the panel glyph
+         * under it. A coarse pointer keeps the glyph, having no hover to reveal it
+         * with. Icon precedence, highest first: `render`, then `iconUrl`, then
+         * `icon`. `render` receives the placement through `ctx.collapsed` (`true`
+         * is the collapsed toggle face) and may return null to skip that spot.
+         * `renderHeader` outranks this for the heading area; the collapsed face is
+         * this slot's alone. Decorative either way: the view's accessible name
+         * still comes from `copy.viewTitle`, and the toggle keeps its own label.
+         * Ignored in panel presentation.
+         */
+        brand?: {
+            /** Lucide name from the built-in registry; an unknown one warns once. */
+            icon?: IconName | (string & {});
+            /** Image URL or data URI, rendered as a decorative `img`. */
+            iconUrl?: string;
+            /** Full custom node. A throw warns once and drops the brand. */
+            render?: (context: {
+                collapsed: boolean;
+            }) => Element | null;
+        };
+        /**
+         * Full override of the rail header's identity area, outranking `brand`
+         * there, re-invoked whenever the collapsed state changes. Return null to
+         * leave the area empty, which leaves the collapse toggle standing alone.
+         * The accessible name of the
+         * view comes from `copy.viewTitle` either way: the heading stays in the
+         * DOM, visually hidden, whenever this renders. Ignored in panel
+         * presentation.
+         */
+        renderHeader?: (context: {
+            collapsed: boolean;
+            defaultTitle: string;
+        }) => Element | null;
+        /**
+         * Extra navigation sections stacked around the conversation list, in array
+         * order within each `placement` bucket. Rail-only in this release: a move
+         * into panel presentation removes them and a move back re-renders them.
+         */
+        sections?: AgentWidgetHistoryRailSection[];
+        /**
+         * Keyboard shortcut for the collapse toggle, e.g. `"mod+b"` ("mod" is
+         * Command on Apple platforms, Control elsewhere). Undefined by default, so
+         * an embedded widget never claims a host page's keys. The same declaration
+         * drives the binding, the toggle's tooltip hint chip, and its
+         * `aria-keyshortcuts`.
+         */
+        collapseShortcut?: string | false;
+        /**
+         * Where `collapseShortcut` listens. Default `"widget"`: only while focus is
+         * inside the widget. `"page"` claims the combo document-wide, which suits a
+         * fullscreen widget that IS the app.
+         */
+        collapseShortcutScope?: "widget" | "page";
+    };
+    /**
+     * History scope. Defaults to "verified-user" when getIdentityProof exists,
+     * otherwise "browser". Before this browser has been identity-bound, a null
+     * proof falls back to browser scope for that operation. Once visitor.endUserId
+     * is non-null, a null proof fails closed until the host resets history identity.
+     *
+     * With a `provider`, this is a hard request: the provider must advertise it
+     * in `capabilities.scopes` or every history operation fails with
+     * `unsupported_scope`. Leave it unset to let the provider's advertised scope
+     * win.
+     */
+    scope?: HistoryScope;
+    /** Copy overrides. Every user-visible history string must be here. */
+    copy?: AgentWidgetHistoryCopy;
+    /**
+     * Date bucketing of the conversation list. `"time"` (default) groups rows
+     * under Today, Yesterday, Previous 7 days, Previous 30 days, and month
+     * headings. `"none"` renders one flat list in server order instead, the
+     * recents-style sidebar. Starred conversations keep their pinned group
+     * either way.
+     */
+    grouping?: "time" | "none";
+    /**
+     * Leading avatar on each conversation row. Unset, rows show the launcher's
+     * image mark (`launcher.iconUrl`) when one exists and are text-only
+     * otherwise, the assistant-list default. Pass an image URL or a glyph to
+     * always show a mark, or false to force text-only rows.
+     */
+    rowAvatar?: boolean | string;
+    /** Show the evidence-based history scope/status beneath the Messages heading. Default true. */
+    showScopeStatus?: boolean;
+    /**
+     * Visitor-facing delete of a single conversation via each row's overflow
+     * menu. Default true. False hides the control only: it changes nothing about
+     * what is stored or for how long, and custom row slots still receive
+     * `requestDelete`. Turn off for deployments that treat conversations as
+     * business records.
+     */
+    showDelete?: boolean;
+    /**
+     * The "Delete all conversations" item in the Messages overflow menu. Default
+     * true. False hides the control only; storage and retention are unchanged.
+     * The identity reset item is separate and unaffected.
+     */
+    showDeleteAll?: boolean;
+    /**
+     * Host items appended to the list overflow menu, above the built-in
+     * destructive actions. The trigger renders whenever any item exists, so
+     * these keep the menu alive even with `showDeleteAll: false`.
+     */
+    listActions?: AgentWidgetHistoryListAction[];
+}
+/** Resolved scope for a logical history operation. */
+type HistoryScope = "browser" | "verified-user";
+/** `presentation` after it has been resolved against the host container width. */
+type ResolvedHistoryPresentation = "panel" | "rail";
+/**
+ * The surface Messages returns to on back/Escape. `"home"` only when a Home
+ * Screen composition opened it; the core header button always records
+ * `"conversation"`.
+ */
+type HistoryReturnSurface = "home" | "conversation";
+/**
+ * Evidence-based history identity state. Never inferred from the mere presence
+ * of `getIdentityProof`, and never carries token, visitor, or end-user values.
+ */
+type HistoryIdentityStatus = {
+    state: "browser_only";
+    reason: "configured_browser_scope" | "no_identity_provider" | "proof_unavailable_before_binding";
+} | {
+    state: "verifying";
+} | {
+    state: "verified";
+} | {
+    state: "authentication_required";
+    reason: "proof_unavailable_after_binding" | "invalid_identity_proof";
+} | {
+    state: "identity_provider_failed";
+} | {
+    state: "configuration_error";
+    reason: "proof_not_admitted";
+} | {
+    state: "resetting";
+} | {
+    state: "unavailable";
+    reason: "history_disabled" | "ineligible_mode";
+};
+/** Fully defaulted history copy. Every user-visible history string. */
+type ResolvedHistoryCopy = Required<AgentWidgetHistoryCopy>;
+/** List-region state handed to render hooks. */
+type HistoryViewState = {
+    kind: "loading";
+    phase: "initial" | "refresh" | "load-more";
+} | {
+    kind: "ready";
+} | {
+    kind: "empty";
+} | {
+    kind: "error";
+    reason: "unavailable" | "authentication_failed" | "authentication_required" | "identity_provider_failed" | "proof_not_admitted" | "unsupported_scope" | "unknown";
+    retryable: boolean;
+} | {
+    kind: "rate_limited";
+    retryAfterSeconds: number;
+} | {
+    kind: "new_conversation_required";
+};
+/** The single in-flight history operation, or `null` when idle. */
+type HistoryPendingAction = {
+    kind: "refresh" | "load-more" | "start-new" | "clear" | "reset";
+} | {
+    kind: "open" | "delete";
+    conversationId: string;
+} | null;
+/**
+ * Every history operation a render hook may invoke. Each routes through the
+ * same controller/session path as the default renderer, so busy gating,
+ * selection epochs, and confirmations behave identically.
+ */
+type AgentWidgetHistoryRenderActions = {
+    refresh(): Promise<void>;
+    loadMore(): Promise<void>;
+    openConversation(conversationId: string): Promise<void>;
+    startNewConversation(): Promise<void>;
+    /** Each request method opens Persona's accessible confirmation first. */
+    requestDeleteConversation(conversationId: string): Promise<"deleted" | "cancelled">;
+    requestClearConversationHistory(): Promise<"cleared" | "cancelled">;
+    requestResetHistoryIdentity(): Promise<{
+        outcome: "cancelled";
+    } | {
+        outcome: "reset";
+        remoteRevocationConfirmed: boolean;
+    }>;
+    close(): void;
+};
+/** Context for `renderHistoryView`. Frozen snapshot; no provider or credentials. */
+type AgentWidgetRenderHistoryViewContext = {
+    conversations: readonly HistoryConversationSummary[];
+    activeConversationId: string | null;
+    state: HistoryViewState;
+    pendingAction: HistoryPendingAction;
+    identityStatus: HistoryIdentityStatus;
+    nextCursor: string | null;
+    presentation: ResolvedHistoryPresentation;
+    returnSurface: HistoryReturnSurface;
+    config: AgentWidgetConfig;
+    copy: ResolvedHistoryCopy;
+    actions: AgentWidgetHistoryRenderActions;
+    /** The default full view. Bypasses this hook only; lower slots still apply. */
+    defaultRenderer(): HTMLElement;
+    /** Re-run arbitration with the current snapshot. Inert after close/destroy. */
+    requestRender(): void;
+    /** Teardown for this render; runs before the next one and on close. */
+    onCleanup(callback: () => void): void;
+};
+/** Context for `renderHistoryConversation` (one list row). */
+type AgentWidgetRenderHistoryConversationContext = {
+    conversation: HistoryConversationSummary;
+    active: boolean;
+    pending: "opening" | "deleting" | null;
+    presentation: ResolvedHistoryPresentation;
+    config: AgentWidgetConfig;
+    open(): Promise<void>;
+    requestDelete(): Promise<"deleted" | "cancelled">;
+    defaultRenderer(): HTMLElement;
+};
+/** Context for `renderHistoryHeader` (the Messages top bar). */
+type AgentWidgetRenderHistoryHeaderContext = {
+    presentation: ResolvedHistoryPresentation;
+    returnSurface: HistoryReturnSurface;
+    identityStatus: HistoryIdentityStatus;
+    pendingAction: HistoryPendingAction;
+    config: AgentWidgetConfig;
+    copy: ResolvedHistoryCopy;
+    actions: Pick<AgentWidgetHistoryRenderActions, "close" | "startNewConversation">;
+    defaultRenderer(): HTMLElement;
+};
+/**
+ * Context for `renderHistoryState`. Invoked only for non-ready list states;
+ * `retry`/`startNewConversation` are present only where they are safe, so
+ * custom DOM never infers recovery behavior.
+ */
+type AgentWidgetRenderHistoryStateContext = {
+    state: Exclude<HistoryViewState, {
+        kind: "ready";
+    }>;
+    identityStatus: HistoryIdentityStatus;
+    presentation: ResolvedHistoryPresentation;
+    config: AgentWidgetConfig;
+    copy: ResolvedHistoryCopy;
+    retry?: () => Promise<void>;
+    startNewConversation?: () => Promise<void>;
+    defaultRenderer(): HTMLElement;
+};
+/**
+ * Context for `renderHistoryOpenError` (the transcript-level surface shown
+ * when opening a conversation from the Messages list fails). `retry` and
+ * `back` are the only exits: both route through the token-guarded open flow,
+ * so custom DOM must not fetch on its own. `back` is present only when the
+ * Messages surface is available to return to.
+ */
+type AgentWidgetRenderHistoryOpenErrorContext = {
+    conversationId: string;
+    config: AgentWidgetConfig;
+    /** Resolved shell copy the default surface renders. */
+    copy: {
+        title: string;
+        retryLabel: string;
+        backLabel: string;
+    };
+    /** Re-runs the open through Persona's token-guarded flow. */
+    retry: () => void;
+    /** Returns to the Messages list. Absent when history is unavailable. */
+    back?: () => void;
+    defaultRenderer(): HTMLElement;
+};
 type SSEEventRecord = {
     id: string;
     type: string;
@@ -4245,6 +5316,24 @@ type AgentWidgetLauncherTeaserConfig = {
      */
     dismissLabel?: string;
 };
+/**
+ * Timing for the portaled icon-control tooltip (header, composer, rail).
+ * Keyboard focus always opens immediately. Hover waits `delayMs` unless
+ * another tooltip closed within `skipDelayMs` (toolbar scan).
+ */
+type AgentWidgetTooltipConfig = {
+    /**
+     * Milliseconds to wait on hover before the first tooltip appears.
+     * `0` restores the previous instant-open behavior.
+     * @default 200
+     */
+    delayMs?: number;
+    /**
+     * After a tooltip closes, later hovers in this window skip `delayMs`.
+     * @default 300
+     */
+    skipDelayMs?: number;
+};
 type AgentWidgetSendButtonConfig = {
     borderWidth?: string;
     borderColor?: string;
@@ -5251,6 +6340,21 @@ type ClientSession = {
         name: string;
         description: string | null;
     };
+    /**
+     * Active conversation record for this session. Optional only for rolling-deploy
+     * compatibility with servers that predate the visitor history contract.
+     */
+    conversationId?: string;
+    /**
+     * Canonical resolved chat target (flow or agent). Normalized from the response
+     * `targetId`, falling back to `flow.id` during rolling deployment. History code
+     * reads this, never widget config.
+     */
+    targetId?: string;
+    /** Opaque change token; differs whenever the conversation transcript mutated. */
+    conversationRevision?: string;
+    /** Visitor grant backing history. `token` appears only at mint. */
+    visitor?: ClientVisitorGrant;
     /** Configuration from the server */
     config: {
         welcomeMessage: string | null;
@@ -5258,6 +6362,43 @@ type ClientSession = {
         theme: Record<string, unknown> | null;
     };
 };
+/**
+ * Visitor credential and identity acknowledgement returned by /v1/client/init.
+ * `expiresAt` stays the wire string: it is a server-slid idle window the widget
+ * never evaluates locally.
+ */
+type ClientVisitorGrant = {
+    id: string;
+    /** Replacement secret. Present only at mint; persist it before anything else. */
+    token?: string;
+    expiresAt: string;
+    endUserId: string | null;
+    /** Server acknowledgement of the supplied identity proof. Status metadata only. */
+    identityStatus?: "not_provided" | "admitted" | "ignored";
+};
+/**
+ * One conversation row, normalized at the Runtype boundary. The deprecated wire
+ * `flowId` alias never escapes that boundary: history code reads `targetId`.
+ */
+type HistoryConversationSummary = {
+    id: string;
+    /** Server-generated; rendered verbatim, never derived locally. */
+    title: string;
+    /** Resolved chat target (flow or agent); `null` when the server omits it. */
+    targetId: string | null;
+    /** Server-produced plain-text preview; `null` when unavailable. */
+    preview: string | null;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+    /** Visitor-pinned flag. Absent when the provider has no update capability. */
+    starred?: boolean;
+};
+/** Visitor-editable conversation metadata. Absent fields are left unchanged. */
+type HistoryConversationPatch = {
+    title?: string;
+    starred?: boolean;
+};
 /** Icon button in the header title row (minimal layout). */
 type AgentWidgetHeaderTrailingAction = {
     id: string;
@@ -5276,6 +6417,13 @@ type AgentWidgetHeaderTrailingAction = {
         destructive?: boolean;
         dividerBefore?: boolean;
     }>;
+    /**
+     * Keyboard shortcut that activates this action, e.g. `"mod+shift+h"` ("mod"
+     * is Command on Apple platforms, Control elsewhere). Fires only while focus
+     * is inside the widget, and also drives the button's tooltip hint chip and
+     * its `aria-keyshortcuts`.
+     */
+    shortcut?: string;
 };
 /**
  * Context provided to header render functions
@@ -5319,6 +6467,15 @@ type AgentWidgetHeaderLayoutConfig = {
     showIcon?: boolean;
     /** Show/hide the title */
     showTitle?: boolean;
+    /**
+     * What the header title (or `titleMenu` label) displays. `"static"`
+     * (default) always shows `launcher.title`. `"conversation"` shows the active
+     * conversation's title — the Claude-style pairing for a `titleMenu` holding
+     * conversation actions — falling back to `launcher.title` while no titled
+     * conversation is open (fresh chat, cleared history, or before the history
+     * view has loaded titles). Requires `features.history` for titles to exist.
+     */
+    titleSource?: "static" | "conversation";
     /** Show/hide the subtitle */
     showSubtitle?: boolean;
     /** Show/hide the close button */
@@ -5369,8 +6526,16 @@ type AgentWidgetHeaderLayoutConfig = {
             destructive?: boolean;
             dividerBefore?: boolean;
         }>;
-        /** Called when a menu item is selected. */
-        onSelect: (id: string) => void;
+        /**
+         * Called when a menu item is selected. Returning `false` (sync or via
+         * promise) falls through to the widget built-ins, mirroring the artifact
+         * copy-menu contract: id `star` toggles the active conversation's star and
+         * id `delete` runs the shell's confirm-then-delete on it (both require
+         * `features.history` and, for star, a provider with the update
+         * capability). `rename` has no built-in: hosts own the rename UI and call
+         * `renameConversation()`.
+         */
+        onSelect: (id: string) => void | boolean | Promise<void | boolean>;
         /** Hover pill style. */
         hover?: {
             background?: string;
@@ -5941,15 +7106,20 @@ type LoadingIndicatorRenderContext = {
      */
     config: AgentWidgetConfig;
     /**
-     * Current streaming state (always true when indicator is shown)
+     * Current streaming state. Always true for 'inline' and 'standalone';
+     * false for 'conversation-open' (a history fetch, not a stream).
      */
     streaming: boolean;
     /**
      * Location where the indicator is rendered:
      * - 'inline': Inside a streaming assistant message bubble (when content is empty)
      * - 'standalone': Separate bubble while waiting for stream to start
+     * - 'conversation-open': Transcript stand-in while a conversation opened
+     *   from the Messages list is being fetched. The returned element is mounted
+     *   inside Persona's centered transcript column, which keeps the status
+     *   role, announcement label, and composer gating.
      */
-    location: 'inline' | 'standalone';
+    location: 'inline' | 'standalone' | 'conversation-open';
     /**
      * Function to render the default 3-dot bouncing indicator.
      * Call this if you want to use the default for certain cases.
@@ -6248,6 +7418,28 @@ type AgentWidgetConfig = {
      * ```
      */
     setStoredSessionId?: (sessionId: string) => void;
+    /**
+     * Called immediately before any cross-device history request and before a
+     * conversationId resume of a conversation discovered on another device.
+     * Return a fresh end-user access token (rt_eu_… / JWT). Null uses exact-browser
+     * scope only for a never-bound visitor; a previously bound visitor fails closed
+     * until resetHistoryIdentity() runs. Never cached by the widget.
+     */
+    getIdentityProof?: () => string | null | Promise<string | null>;
+    /**
+     * Read the persisted active conversation id (client token mode only).
+     * Called only after the internal stored-state bootstrap gate resolves.
+     */
+    getStoredConversationId?: () => string | null;
+    /** Persist the active conversation id so a later boot reopens the same record. */
+    setStoredConversationId?: (conversationId: string) => void;
+    /** Drop the persisted active conversation id (new conversation, deletion, reset). */
+    clearStoredConversationId?: () => void;
+    /**
+     * Drop the persisted session id. Dedicated clear seam: it avoids widening
+     * `setStoredSessionId` and its existing host call sites.
+     */
+    clearStoredSessionId?: () => void;
     /**
      * Static headers to include with each request.
      * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
@@ -6327,6 +7519,12 @@ type AgentWidgetConfig = {
      * @default false
      */
     autoFocusInput?: boolean;
+    /**
+     * Hover timing for the portaled control tooltip. Keyboard focus is
+     * always immediate. Unset keys keep the ChatGPT/Claude defaults
+     * (`delayMs: 200`, `skipDelayMs: 300`).
+     */
+    tooltip?: AgentWidgetTooltipConfig;
     launcher?: AgentWidgetLauncherConfig;
     initialMessages?: AgentWidgetMessage[];
     /**