@runtypelabs/persona 4.13.0 → 4.15.0

package/src/theme-editor/state-preferences.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { ThemeEditorState } from "./state";
+
+describe("ThemeEditorState preference reset", () => {
+  it("unsets a path and prunes empty parent objects", () => {
+    const state = new ThemeEditorState(undefined, {}, { mergeDefaults: false });
+    state.set("features.artifacts.display.files", "inline");
+    expect(state.get("features.artifacts.display.files")).toBe("inline");
+
+    state.unset("features.artifacts.display.files");
+
+    expect(state.get("features.artifacts.display.files")).toBeUndefined();
+    expect(state.getConfig()).not.toHaveProperty("features");
+  });
+});

package/src/theme-editor/state.ts

@@ -32,6 +32,30 @@ function setByPath(obj: unknown, path: string, value: unknown): unknown {
   };
 }
 
+function unsetByPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  if (parts.length === 1) {
+    const result = { ...(obj as Record<string, unknown>) };
+    delete result[parts[0]];
+    return result;
+  }
+  const [first, ...rest] = parts;
+  const current = obj as Record<string, unknown>;
+  const child = unsetByPath(current?.[first] ?? {}, rest.join('.'));
+  const result = { ...current };
+  if (
+    typeof child === 'object' &&
+    child !== null &&
+    !Array.isArray(child) &&
+    Object.keys(child as Record<string, unknown>).length === 0
+  ) {
+    delete result[first];
+  } else {
+    result[first] = child;
+  }
+  return result;
+}
+
 // ─── ThemeEditorState ───────────────────────────────────────────
 
 export class ThemeEditorState {
@@ -111,6 +135,28 @@ export class ThemeEditorState {
     this.notifyListeners();
   }
 
+  /** Delete a dot-path and prune empty parents so sparse preferences inherit. */
+  unset(path: string): void {
+    if (path.startsWith('theme.')) {
+      const themePath = path.replace('theme.', '');
+      this.theme = unsetByPath(this.theme, themePath) as PersonaTheme;
+      this.syncThemeIntoConfig();
+    } else if (path.startsWith('darkTheme.')) {
+      const themePath = path.replace('darkTheme.', '');
+      this.config = {
+        ...this.config,
+        darkTheme: unsetByPath(
+          this.config.darkTheme ?? {},
+          themePath
+        ) as AgentWidgetConfig['darkTheme'],
+      };
+    } else {
+      this.config = unsetByPath(this.config, path) as AgentWidgetConfig;
+    }
+    this.recordHistory();
+    this.notifyListeners();
+  }
+
   /** Batch-set multiple paths at once */
   setBatch(updates: Record<string, unknown>): void {
     let themeChanged = false;

package/src/theme-editor/types.ts

@@ -1,7 +1,11 @@
 /** Field definition types for the declarative configurator system (headless: no DOM) */
 
 import type { DeepPartial, PersonaTheme } from '../types/theme';
-import type { AgentWidgetConfig } from '../types';
+import type {
+  AgentWidgetConfig,
+  WidgetPreferenceCapabilities,
+  WidgetPreferenceSlice,
+} from '../types';
 
 // ─── Field System ────────────────────────────────────────────────
 
@@ -101,6 +105,12 @@ export interface FieldDef {
   formatValue?: (value: unknown) => unknown;
   /** Convert control input back into the stored value shape */
   parseValue?: (value: unknown) => unknown;
+  /** Capability required for hosts to render this field. */
+  requiresCapability?: keyof WidgetPreferenceCapabilities;
+  /** The host may offer an inherit/reset action which deletes this path. */
+  unsettable?: boolean;
+  /** Label for the inherit/reset action. Default: "Use default". */
+  unsetLabel?: string;
 }
 
 export interface SectionDef {
@@ -112,6 +122,8 @@ export interface SectionDef {
   collapsed?: boolean;
   /** Preset buttons for this section */
   presets?: SectionPreset[];
+  /** Capability required for hosts to render this section. */
+  requiresCapability?: keyof WidgetPreferenceCapabilities;
 }
 
 export interface SectionPreset {
@@ -149,6 +161,8 @@ export interface ThemeEditorPreset {
   toolCall?: AgentWidgetToolCallConfig;
   /** Tool call styling for dark mode (falls back to toolCall if not set) */
   darkToolCall?: AgentWidgetToolCallConfig;
+  /** Sparse, persistable widget behavior layered separately from theme tokens. */
+  behavior?: WidgetPreferenceSlice;
   preview: {
     primary: string;
     surface: string;

package/src/theme-editor/webmcp/tools.test.ts

@@ -123,6 +123,19 @@ describe('createThemeEditorTools', () => {
     );
   });
 
+  it('apply_preset installs both Persona default slots with automatic scheme selection', async () => {
+    const out = await call(tools.get('apply_preset')!, { presetId: 'persona-default' });
+
+    expect(out.applied.appliedPreset.id).toBe('persona-default');
+    expect(state.get('colorScheme')).toBe('auto');
+    expect(state.get('theme.components.artifact.pane.background')).toBe(
+      'semantic.colors.container'
+    );
+    expect(state.get('darkTheme.semantic.colors.surface')).toBe(
+      'palette.colors.gray.800'
+    );
+  });
+
   it('configure_widget writes config paths', async () => {
     await call(tools.get('configure_widget')!, {
       launcherPosition: 'bottom-left',

package/src/theme-editor/webmcp/tools.ts

@@ -10,6 +10,7 @@
  */
 
 import { createTheme } from '../../utils/theme';
+import { applyFeaturePreferences } from '../../utils/feature-preferences';
 import type { AgentWidgetConfig } from '../../types';
 import type { PersonaTheme } from '../../types/theme';
 import { generateColorScale, SHADE_KEYS } from '../color-utils';
@@ -469,8 +470,12 @@ export function createThemeEditorTools(
       const config: AgentWidgetConfig = { ...state.getConfig() };
       if (preset.darkTheme) {
         config.darkTheme = createTheme(preset.darkTheme, { validate: false }) as PersonaTheme;
+        config.colorScheme = 'auto';
       }
       if (preset.toolCall) config.toolCall = preset.toolCall;
+      if (preset.behavior) {
+        config.features = applyFeaturePreferences(config.features, [preset.behavior]);
+      }
       state.setFullConfig(config, theme);
       const warnings = quickContrastWarnings(state, ['body', 'assistant-message'], 'light');
       return result({ appliedPreset: { id: preset.id, name: preset.name } }, warnings);

package/src/theme-reference.ts

@@ -142,7 +142,8 @@ export const THEME_TOKEN_DOCS = {
         'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
       toolBubble: 'shadow: tool call row box-shadow.',
       reasoningBubble: 'shadow: reasoning/thinking row box-shadow.',
-      composer: 'shadow: message input form box-shadow.',
+      composer:
+        'Message input form: shadow (box-shadow), padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type).',
       artifact:
         'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
     },
@@ -245,8 +246,14 @@ export const THEME_TOKEN_DOCS = {
       properties:
         'enabled, provider ("browser" | "runtype"), browserFallback, voice, rate, pitch.',
     },
+    suggestions: {
+      description:
+        'Rich starter and follow-up suggestion surfaces. Strings remain valid item shorthand.',
+      properties:
+        'starters.items, starters.variant ("card" | "chip" | "list"), starters.placement ("auto" | "welcome" | "composer"), starters.behavior ("send" | "fill"), starters.overflow ("scroll" | "wrap"), starters.maxItems, followUps.enabled, followUps.expose, followUps.variant, followUps.placement ("auto" | "after-message" | "composer"), followUps.behavior, followUps.overflow ("scroll" | "wrap"), followUps.maxItems.',
+    },
     suggestionChips:
-      'string[]: Suggested prompts shown to the user.',
+      'Deprecated string[] shorthand for starter prompts. Prefer suggestions.starters.items.',
     messageActions: {
       description: 'Message action buttons (copy, upvote, downvote).',
       properties:

package/src/types/theme.ts

@@ -365,6 +365,14 @@ export interface ReasoningBubbleTokens {
 export interface ComposerChromeTokens {
   /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
   shadow: string;
+  /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
+  padding?: string;
+  /** Gap between the textarea row and the actions row. @default "0.5rem" */
+  gap?: string;
+  /** Composer textarea font-size. @default "0.875rem" */
+  fontSize?: string;
+  /** Composer textarea line-height. @default "1.25rem" */
+  lineHeight?: string;
 }
 
 /** Artifact toolbar chrome. */
@@ -524,6 +532,28 @@ export interface ScrollToBottomTokens extends ComponentTokenSet {
   iconSize?: string;
 }
 
+/** Visual tokens shared by one suggestion presentation variant. */
+export interface SuggestionVariantTokens extends ComponentTokenSet {
+  gap?: string;
+  minHeight?: string;
+  fontSize?: string;
+  lineHeight?: string;
+  iconSize?: string;
+  hoverBackground?: TokenReference<'color'>;
+  hoverForeground?: TokenReference<'color'>;
+  hoverBorder?: TokenReference<'color'>;
+  pressedBackground?: TokenReference<'color'>;
+  focusRing?: TokenReference<'color'>;
+  disabledOpacity?: string;
+}
+
+/** Starter and follow-up suggestion chrome. */
+export interface SuggestionTokens {
+  chip: SuggestionVariantTokens;
+  card: SuggestionVariantTokens;
+  list: SuggestionVariantTokens;
+}
+
 /** Toggle group chrome (used by createToggleGroup). */
 export interface ToggleGroupTokens {
   /** Gap between toggle buttons. Default: 0 (connected). */
@@ -555,6 +585,8 @@ export interface ComponentTokens {
   labelButton?: LabelButtonTokens;
   /** Scroll-to-bottom indicator styling tokens. */
   scrollToBottom?: ScrollToBottomTokens;
+  /** Starter prompt and follow-up suggestion styling tokens. */
+  suggestion?: SuggestionTokens;
   /** Toggle group styling tokens. */
   toggleGroup?: ToggleGroupTokens;
   /** Artifact toolbar, tab strip, and pane chrome. */

package/src/types.ts

@@ -685,6 +685,15 @@ export type AgentToolsConfig = {
 /** Artifact kinds for the Persona sidebar and dispatch payload */
 export type PersonaArtifactKind = "markdown" | "component";
 
+export type PersonaArtifactPresentation = {
+  /**
+   * Producer hint for where this artifact renders (content-disposition
+   * model). Beats configured defaults; loses to explicit `files`/`byKind`
+   * rules. Persona never infers it; the producer or host supplies it.
+   */
+  preferredMode?: PersonaArtifactDisplayModeInput;
+};
+
 /**
  * Agent configuration for agent execution mode.
  * When provided in the widget config, enables agent loop execution instead of flow dispatch.
@@ -1375,10 +1384,60 @@ export type AgentWidgetArtifactsLayoutConfig = {
   }) => void | Promise<void>;
 };
 
+/**
+ * Where the artifact body renders by default. Every mode shows the compact
+ * reference in the transcript; the mode names where the body goes:
+ * nowhere yet (`collapsed`), the side panel (`panel`), or the conversation
+ * itself (`inline`).
+ */
 export type PersonaArtifactDisplayMode =
-  | "card"    // reference card in transcript; pane opens on click
-  | "panel"   // reference card in transcript; pane also auto-opens on artifact_start (current default behavior)
-  | "inline"; // artifact preview renders directly in the transcript; no pane involvement
+  | "collapsed" // body renders nowhere until the user selects the reference; pane opens on click
+  | "panel" // body renders in the side panel, which auto-opens on artifact_start (default behavior)
+  | "inline"; // body renders directly in the transcript; no pane involvement
+
+/**
+ * Accepted wherever a display mode is written. `"card"` is a deprecated
+ * alias of `"collapsed"` (the old name described the reference card, which
+ * every mode shows, instead of where the body renders). Resolution and
+ * parsing always canonicalize to `"collapsed"`.
+ */
+export type PersonaArtifactDisplayModeInput =
+  | PersonaArtifactDisplayMode
+  | "card";
+
+/**
+ * Display rules for file-backed artifacts. `byMediaType` keys are exact MIME
+ * types (`"text/html"`) or major-type wildcards (`"image/*"`), matched
+ * case-insensitively without parameters; exact beats wildcard.
+ */
+export type PersonaArtifactFilesDisplayRules = {
+  default?: PersonaArtifactDisplayModeInput;
+  byMediaType?: Record<string, PersonaArtifactDisplayModeInput>;
+};
+
+/**
+ * Scoped artifact display rules. Matching resolves from the most specific
+ * selector to `default`; see `resolveArtifactDisplay`.
+ *
+ * Across preference layers, one merge rule applies everywhere: a string value
+ * replaces the whole subtree it names; an object refines it per key. So
+ * `files: "inline"` overrides every lower-layer file rule, while
+ * `files: { default: "inline" }` keeps lower-layer MIME exceptions.
+ */
+export type PersonaArtifactDisplayRules = {
+  default?: PersonaArtifactDisplayModeInput;
+  byKind?: Partial<
+    Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>
+  >;
+  /**
+   * @deprecated Use `byKind`. When both are present, `byKind` wins.
+   */
+  byType?: Partial<
+    Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>
+  >;
+  /** Rules for any artifact carrying file metadata. */
+  files?: PersonaArtifactDisplayModeInput | PersonaArtifactFilesDisplayRules;
+};
 
 /** Context handed to custom artifact actions. Content fields are best-effort: resolved from live session state or, after a refresh, from the persisted reference-card payload. */
 export type PersonaArtifactActionContext = {
@@ -1439,15 +1498,12 @@ export type AgentWidgetArtifactsFeature = {
   allowedTypes?: PersonaArtifactKind[];
   /**
    * Where artifact bodies render. A single mode applies to all artifacts;
-   * the object form sets a default plus per-type overrides.
+   * the object form sets a default plus scoped overrides.
    * Defaults to "panel" (current behavior).
    */
   display?:
-    | PersonaArtifactDisplayMode
-    | {
-        default?: PersonaArtifactDisplayMode;
-        byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayMode>>;
-      };
+    | PersonaArtifactDisplayModeInput
+    | PersonaArtifactDisplayRules;
   /** Split / drawer dimensions and launcher widen behavior */
   layout?: AgentWidgetArtifactsLayoutConfig;
   /**
@@ -2201,20 +2257,85 @@ export type AgentWidgetFeatureFlags = {
    */
   askUserQuestion?: AgentWidgetAskUserQuestionFeature;
   /**
-   * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
-   * the tool, the widget shows the suggestions as tappable chips above the
-   * composer (reusing the suggestion-chips surface) and immediately resumes
-   * the execution: fire-and-forget, no user input awaited.
+   * Built-in `suggest_replies` follow-ups. When the assistant invokes the
+   * tool, the widget shows the suggestions using `suggestions.followUps` and
+   * immediately resumes the execution: fire-and-forget, no user input awaited.
+   *
+   * @deprecated Both keys moved to `suggestions.followUps`: use
+   * `suggestions.followUps.enabled` and `suggestions.followUps.expose`. This
+   * alias keeps working per key, with `suggestions.followUps` winning.
    */
   suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
 
+export type WidgetPreferenceCapabilities = {
+  artifacts?: boolean;
+  tools?: boolean;
+  reasoning?: boolean;
+};
+
+/**
+ * Persistable artifact-layout choices. The full layout config deliberately is
+ * not exposed because it also contains callbacks and embedder-owned chrome.
+ */
+export type WidgetArtifactLayoutPreference = Pick<
+  AgentWidgetArtifactsLayoutConfig,
+  | "paneWidth"
+  | "paneMaxWidth"
+  | "paneMinWidth"
+  | "expandLauncherPanelWhenOpen"
+  | "expandedPanelWidth"
+  | "resizable"
+  | "resizableMinWidth"
+  | "resizableMaxWidth"
+>;
+
+/**
+ * Curated, JSON-serializable display preferences in native `features` shape.
+ *
+ * Absence means inherit the next preference layer and ultimately Persona's
+ * current default. Persist only explicit choices; resetting a choice deletes
+ * its key.
+ *
+ * Capability facts (`artifacts.enabled`, `allowedTypes`), trusted iframe
+ * security, callbacks, actions, renderers, labels, and theme styling are
+ * intentionally excluded because they remain embedder/code-owned.
+ */
+export type WidgetPreferenceSlice = {
+  showToolCalls?: boolean;
+  showReasoning?: boolean;
+  toolCallDisplay?: Pick<
+    AgentWidgetToolCallDisplayFeature,
+    | "collapsedMode"
+    | "expandable"
+    | "grouped"
+    | "groupedMode"
+    | "loadingAnimation"
+  >;
+  reasoningDisplay?: Pick<
+    AgentWidgetReasoningDisplayFeature,
+    "expandable" | "activePreview"
+  >;
+  artifacts?: {
+    /**
+     * String and object forms are both persistable and mean different things
+     * when layers merge: a string replaces every lower-layer display rule; an
+     * object refines lower layers per selector key (same rule applies to
+     * `display.files`).
+     */
+    display?: PersonaArtifactDisplayModeInput | PersonaArtifactDisplayRules;
+    filePreview?: { enabled?: boolean };
+    layout?: WidgetArtifactLayoutPreference;
+  };
+};
+
 /**
- * Feature config for the built-in `suggest_replies` quick-reply chips.
- * Chips render in the existing suggestions slot above the composer and are
- * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
- * verbatim as the user's next message; chips clear once any user message
- * follows them.
+ * Feature config for the built-in `suggest_replies` follow-ups.
+ *
+ * @deprecated Both keys moved to `suggestions.followUps`
+ * (`suggestions.followUps.enabled` / `suggestions.followUps.expose`), which
+ * also owns presentation, placement, and send/fill behavior. Resolution is
+ * per key with `suggestions.followUps` winning; removal waits for 5.0.
  */
 export type AgentWidgetSuggestRepliesFeature = {
   /**
@@ -2222,14 +2343,18 @@ export type AgentWidgetSuggestRepliesFeature = {
    * renders as a regular tool bubble and is NOT auto-resumed: only set this
    * with no server-side `suggest_replies` declaration, or the execution
    * parks awaiting a resume that never comes.
+   * @deprecated Use `suggestions.followUps.enabled`.
    */
   enabled?: boolean;
   /**
    * Advertise the built-in `suggest_replies` tool to the agent on every
    * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
-   * needed. Defaults to `false`: flows that already declare the tool via
-   * `runtimeTools` would otherwise present it to the model twice. Ignored
-   * when `enabled` is `false`.
+   * needed. Defaults to `false`. Declare the tool in one place: the API
+   * dedupes a double declaration by name with `clientTools[]` winning, so the
+   * model still sees exactly one tool, but the widget's description and schema
+   * win and the effective tool type becomes `local` (the execution pauses and
+   * the widget auto-resumes it). Ignored when `enabled` is `false`.
+   * @deprecated Use `suggestions.followUps.expose`.
    */
   expose?: boolean;
 };
@@ -2304,10 +2429,13 @@ export type AgentWidgetAskUserQuestionFeature = {
    * matching {@link AskUserQuestionPayload}; when the model calls it, the
    * existing answer-pill sheet renders and the answer resumes the execution.
    *
-   * Defaults to `false`: flows that already declare `ask_user_question` via
-   * `runtimeTools` would otherwise present the tool to the model twice.
-   * Ignored when `enabled` is `false`: never offer the agent a question
-   * tool the widget can't render an answer UI for.
+   * Defaults to `false`. Declare the tool in one place: the API dedupes a
+   * double declaration by name with `clientTools[]` winning, so the model
+   * still sees exactly one tool, but the widget's description and schema win
+   * and the effective tool type becomes `local` (the execution pauses and the
+   * widget resumes it with the user's answer). Ignored when `enabled` is
+   * `false`: never offer the agent a question tool the widget can't render an
+   * answer UI for.
    */
   expose?: boolean;
   /** Slide-in animation duration in ms. Defaults to 180. */
@@ -2796,6 +2924,10 @@ export type AgentWidgetSendButtonConfig = {
   paddingY?: string;
   iconText?: string;
   iconName?: string;
+  /** Icon glyph box in icon mode, e.g. "20px". Defaults to half of `size`. */
+  iconSize?: string;
+  /** Stroke width for the icon glyph, in viewBox units. Default 2. */
+  iconStrokeWidth?: number;
   useIcon?: boolean;
   tooltipText?: string;
   showTooltip?: boolean;
@@ -3611,6 +3743,123 @@ export type AgentWidgetSuggestionChipsConfig = {
   paddingY?: string;
 };
 
+/** A suggested next action shown to the user. Strings remain supported as shorthand. */
+export type AgentWidgetSuggestion =
+  | string
+  | {
+      /** Stable analytics / DOM identity. Falls back to the prompt or label. */
+      id?: string;
+      /** Concise visible action label. */
+      label: string;
+      /** Text placed in the composer or sent. Defaults to `label`. */
+      prompt?: string;
+      /** Optional supporting copy, most useful with the `card` variant. */
+      description?: string;
+      /** Optional icon from Persona's bundled Lucide registry. */
+      icon?: IconName;
+      /**
+       * CSS color for this item's glyph. Tints the icon only: label, border,
+       * and background stay neutral. Ignored without an `icon`.
+       */
+      iconColor?: string;
+      /** Override the surface's click behavior for this item. */
+      behavior?: AgentWidgetSuggestionBehavior;
+      /** Visually promote one high-confidence action. */
+      emphasis?: "default" | "primary";
+    };
+
+export type AgentWidgetSuggestionBehavior = "send" | "fill";
+export type AgentWidgetSuggestionVariant = "chip" | "card" | "list";
+export type AgentWidgetSuggestionSurface = "starter" | "followUp";
+/**
+ * Who produced the rendered suggestions: static config, the agent's
+ * `suggest_replies` tool, or `controller.setFollowUpSuggestions`.
+ */
+export type AgentWidgetSuggestionSource = "config" | "agent" | "host";
+
+/**
+ * A suggestion after Persona has normalized shorthand strings and resolved the
+ * effective click behavior. Plugin hooks receive this stable shape.
+ */
+export type AgentWidgetResolvedSuggestion = {
+  id: string;
+  label: string;
+  prompt: string;
+  description?: string;
+  icon?: IconName;
+  /** CSS color for the glyph only; never the label, border, or background. */
+  iconColor?: string;
+  behavior: AgentWidgetSuggestionBehavior;
+  emphasis: "default" | "primary";
+};
+
+/** Presentation keys shared by every suggestion surface. */
+export type AgentWidgetSuggestionSurfaceConfig = {
+  /** Item density. Defaults to `card` for starters and `chip` for follow-ups. */
+  variant?: AgentWidgetSuggestionVariant;
+  /** Default click behavior, overridable per item. Defaults to `send`. */
+  behavior?: AgentWidgetSuggestionBehavior;
+  /**
+   * Layout for items past the surface width. Defaults to `wrap` for starters
+   * and `scroll` for follow-ups. Applies to the `chip` variant only; the
+   * `card` and `list` layouts manage their own stacking.
+   */
+  overflow?: "scroll" | "wrap";
+  /** Maximum visible items. Defaults to 4. */
+  maxItems?: number;
+};
+
+export type AgentWidgetStarterSuggestionsConfig =
+  AgentWidgetSuggestionSurfaceConfig & {
+    /** Suggestions shown before the first user message. */
+    items?: AgentWidgetSuggestion[];
+    /**
+     * `auto` uses the welcome surface when the welcome card renders and the
+     * composer otherwise. Explicit values are literal: `welcome` renders
+     * nothing when the welcome card is hidden. Defaults to `auto`.
+     */
+    placement?: "auto" | "welcome" | "composer";
+  };
+
+export type AgentWidgetFollowUpSuggestionsConfig =
+  AgentWidgetSuggestionSurfaceConfig & {
+    /**
+     * Enable the built-in `suggest_replies` follow-ups. Defaults to true. When
+     * false, `suggest_replies` renders as a regular tool bubble and is NOT
+     * auto-resumed: only set this with no server-side `suggest_replies`
+     * declaration, or the execution parks awaiting a resume that never comes.
+     */
+    enabled?: boolean;
+    /**
+     * Advertise the built-in `suggest_replies` tool to the agent on every
+     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
+     * needed. Defaults to `false`. Declare the tool in one place: the API
+     * dedupes a double declaration by name with `clientTools[]` winning, so
+     * the model still sees exactly one tool, but the widget's description and
+     * schema win and the effective tool type becomes `local` (the execution
+     * pauses and the widget auto-resumes it). Ignored when `enabled` is
+     * `false`.
+     */
+    expose?: boolean;
+    /**
+     * `auto` places follow-ups after the transcript in regular panels and above
+     * the composer in composer-bar mode. Defaults to `auto`.
+     */
+    placement?: "auto" | "after-message" | "composer";
+    // No `items`: follow-up items are contextual and come from the agent's
+    // `suggest_replies` tool or `controller.setFollowUpSuggestions`, not static
+    // config. Static lists are `starters`.
+  };
+
+/**
+ * Structured suggestions configuration. The legacy `suggestionChips` and
+ * `suggestionChipsConfig` fields remain supported for backwards compatibility.
+ */
+export type AgentWidgetSuggestionsConfig = {
+  starters?: AgentWidgetStarterSuggestionsConfig;
+  followUps?: AgentWidgetFollowUpSuggestionsConfig;
+};
+
 /**
  * Interface for pluggable stream parsers that extract text from streaming responses.
  * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
@@ -4902,6 +5151,15 @@ export type AgentWidgetConfig = {
    */
   colorScheme?: 'auto' | 'light' | 'dark';
   features?: AgentWidgetFeatureFlags;
+  /**
+   * Per-instance display overrides, applied over `features` through the
+   * preference allowlist (security/capability keys cannot pass). String
+   * `display` values replace the base rule subtree; objects refine it per
+   * key. Each `controller.update({ preferences })` replaces the previous
+   * slice wholesale (dropped keys revert to the base `features`); an
+   * explicit-undefined patch clears it entirely.
+   */
+  preferences?: WidgetPreferenceSlice;
   /**
    * When true, focus the chat input after the panel opens and the open animation completes.
    * Applies to launcher mode (user click, controller.open(), autoExpand) and inline mode (on init).
@@ -4922,7 +5180,11 @@ export type AgentWidgetConfig = {
    * with `initialArtifacts`.
    */
   initialSelectedArtifactId?: string | null;
+  /** Rich starter and follow-up suggestion surfaces. */
+  suggestions?: AgentWidgetSuggestionsConfig;
+  /** @deprecated Prefer `suggestions.starters.items`. */
   suggestionChips?: string[];
+  /** @deprecated Prefer semantic tokens under `theme.components.suggestion`. */
   suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
   debug?: boolean;
   formEndpoint?: string;
@@ -5864,6 +6126,8 @@ export type PersonaArtifactRecord = {
   props?: Record<string, unknown>;
   /** Present when this markdown artifact is a previewable file (see PersonaArtifactFileMeta). */
   file?: PersonaArtifactFileMeta;
+  /** Optional presentation metadata such as the producer's display-mode hint. */
+  presentation?: PersonaArtifactPresentation;
 };
 
 /** Programmatic artifact upsert (controller / window API) */
@@ -5875,6 +6139,7 @@ export type PersonaArtifactManualUpsert =
       content: string;
       /** Optional file metadata for previewable file artifacts. */
       file?: PersonaArtifactFileMeta;
+      presentation?: PersonaArtifactPresentation;
       /** Set false to update the registry/pane without a transcript block (pre-4.x behavior). */
       transcript?: boolean;
     }
@@ -5884,6 +6149,7 @@ export type PersonaArtifactManualUpsert =
       title?: string;
       component: string;
       props?: Record<string, unknown>;
+      presentation?: PersonaArtifactPresentation;
       /** Set false to update the registry/pane without a transcript block (pre-4.x behavior). */
       transcript?: boolean;
     };