@runtypelabs/persona 4.23.1 → 4.24.0

package/src/theme-editor/state.ts

@@ -1,9 +1,10 @@
 /** Headless state management for the theme editor (no DOM, no localStorage, no side effects) */
 
 import type { AgentWidgetConfig } from '../types';
-import type { PersonaTheme } from '../types/theme';
+import type { DeepPartial, PersonaTheme } from '../types/theme';
 import { createTheme } from '../utils/theme';
-import { DEFAULT_WIDGET_CONFIG } from '../defaults';
+import { resolveDefaults, resolveDefaultsVersion } from '../defaults';
+import { deepMerge } from '../utils/deep-merge';
 import type { ConfiguratorSnapshot, ConfigChangeListener } from './types';
 
 // ─── Dot-path utilities ─────────────────────────────────────────
@@ -65,18 +66,29 @@ export class ThemeEditorState {
   private history: ConfiguratorSnapshot[] = [];
   private historyIndex = -1;
   private suppressHistory = false;
+  private authoredConfig: Partial<AgentWidgetConfig> = {};
+  private authoredTheme: DeepPartial<PersonaTheme> = {};
+  private mergeDefaults = true;
+  private snapshotIntent = new WeakMap<ConfiguratorSnapshot, { config: Partial<AgentWidgetConfig>; theme: DeepPartial<PersonaTheme> }>();
 
   constructor(
-    initialTheme?: Partial<PersonaTheme>,
+    initialTheme?: DeepPartial<PersonaTheme>,
     initialConfig?: Partial<AgentWidgetConfig>,
     options?: { mergeDefaults?: boolean }
   ) {
     const mergeDefaults = options?.mergeDefaults ?? true;
+    this.mergeDefaults = mergeDefaults;
+    this.authoredConfig = { ...initialConfig };
+    this.authoredTheme = initialTheme ?? {};
+    const defaults = resolveDefaults(initialConfig);
     this.config = (mergeDefaults
-      ? { ...DEFAULT_WIDGET_CONFIG, ...initialConfig }
-      : (initialConfig ?? DEFAULT_WIDGET_CONFIG)
+      ? { ...defaults, ...initialConfig }
+      : (initialConfig ?? defaults)
     ) as AgentWidgetConfig;
-    this.theme = createTheme(initialTheme, { validate: false });
+    this.theme = createTheme(initialTheme, {
+      validate: false,
+      future: this.config.future,
+    });
     this.syncThemeIntoConfig();
     this.pushHistorySnapshot(this.exportSnapshot(), true);
   }
@@ -116,13 +128,15 @@ export class ThemeEditorState {
    * - everything else → writes into AgentWidgetConfig
    */
   set(path: string, value: unknown): void {
+    const previousVersion = resolveDefaultsVersion(this.config);
+    this.recordIntent(path, value);
     if (path.startsWith('theme.')) {
       const themePath = path.replace('theme.', '');
       this.theme = setByPath(this.theme, themePath, value) as PersonaTheme;
       this.syncThemeIntoConfig();
     } else if (path.startsWith('darkTheme.')) {
       const themePath = path.replace('darkTheme.', '');
-      const dark = this.config.darkTheme ?? createTheme();
+      const dark = this.config.darkTheme ?? createTheme(undefined, { future: this.config.future });
       this.config = {
         ...this.config,
         darkTheme: setByPath(dark, themePath, value) as AgentWidgetConfig['darkTheme'],
@@ -131,12 +145,15 @@ export class ThemeEditorState {
       this.config = setByPath(this.config, path, value) as AgentWidgetConfig;
     }
 
+    this.rebaseDefaults(previousVersion);
     this.recordHistory();
     this.notifyListeners();
   }
 
   /** Delete a dot-path and prune empty parents so sparse preferences inherit. */
   unset(path: string): void {
+    const previousVersion = resolveDefaultsVersion(this.config);
+    this.recordIntent(path, undefined, true);
     if (path.startsWith('theme.')) {
       const themePath = path.replace('theme.', '');
       this.theme = unsetByPath(this.theme, themePath) as PersonaTheme;
@@ -153,24 +170,27 @@ export class ThemeEditorState {
     } else {
       this.config = unsetByPath(this.config, path) as AgentWidgetConfig;
     }
+    this.rebaseDefaults(previousVersion);
     this.recordHistory();
     this.notifyListeners();
   }
 
   /** Batch-set multiple paths at once */
   setBatch(updates: Record<string, unknown>): void {
+    const previousVersion = resolveDefaultsVersion(this.config);
     let themeChanged = false;
     let darkThemeChanged = false;
     let configChanged = false;
 
     for (const [path, value] of Object.entries(updates)) {
+      this.recordIntent(path, value);
       if (path.startsWith('theme.')) {
         const themePath = path.replace('theme.', '');
         this.theme = setByPath(this.theme, themePath, value) as PersonaTheme;
         themeChanged = true;
       } else if (path.startsWith('darkTheme.')) {
         const themePath = path.replace('darkTheme.', '');
-        const dark = this.config.darkTheme ?? createTheme();
+        const dark = this.config.darkTheme ?? createTheme(undefined, { future: this.config.future });
         this.config = {
           ...this.config,
           darkTheme: setByPath(dark, themePath, value) as AgentWidgetConfig['darkTheme'],
@@ -185,6 +205,7 @@ export class ThemeEditorState {
     if (themeChanged) {
       this.syncThemeIntoConfig();
     }
+    this.rebaseDefaults(previousVersion);
     if (themeChanged || darkThemeChanged || configChanged) {
       this.recordHistory();
       this.notifyListeners();
@@ -193,6 +214,7 @@ export class ThemeEditorState {
 
   /** Replace the entire theme */
   setTheme(theme: PersonaTheme): void {
+    this.authoredTheme = theme;
     this.theme = theme;
     this.syncThemeIntoConfig();
     this.recordHistory();
@@ -201,6 +223,8 @@ export class ThemeEditorState {
 
   /** Replace the entire config (for preset loading) */
   setFullConfig(config: AgentWidgetConfig, theme?: PersonaTheme): void {
+    this.authoredConfig = { ...config };
+    if (theme) this.authoredTheme = theme;
     this.config = { ...config };
     if (theme) {
       this.theme = theme;
@@ -221,21 +245,27 @@ export class ThemeEditorState {
     if ('config' in parsed || 'theme' in parsed || parsed.version === 2) {
       const config = (parsed.config ?? this.config) as AgentWidgetConfig;
       const theme = createTheme(
-        (parsed.theme ?? this.theme) as Partial<PersonaTheme>,
-        { validate: false }
+        (parsed.theme ?? this.theme) as DeepPartial<PersonaTheme>,
+        { validate: false, future: config.future }
       );
       this.setFullConfig(config, theme);
       return;
     }
 
-    const theme = createTheme(parsed as Partial<PersonaTheme>, { validate: false });
+    const theme = createTheme(parsed as DeepPartial<PersonaTheme>, { validate: false, future: this.config.future });
     this.setTheme(theme);
   }
 
   /** Reset to defaults */
   resetToDefaults(): void {
-    this.config = { ...DEFAULT_WIDGET_CONFIG } as AgentWidgetConfig;
-    this.theme = createTheme();
+    const future = this.config.future;
+    this.authoredConfig = future ? { future } : {};
+    this.authoredTheme = {};
+    this.config = {
+      ...resolveDefaults({ future }),
+      ...(future ? { future } : {}),
+    } as AgentWidgetConfig;
+    this.theme = createTheme(undefined, { future: this.config.future });
     this.syncThemeIntoConfig();
     this.history = [];
     this.historyIndex = -1;
@@ -295,6 +325,27 @@ export class ThemeEditorState {
 
   // ─── Private ────────────────────────────────────────────────
 
+  private recordIntent(path: string, value: unknown, remove = false): void {
+    const write = (target: object, key: string) => remove || value === undefined
+      ? unsetByPath(target, key) : setByPath(target, key, value);
+    if (path.startsWith('theme.')) {
+      this.authoredTheme = write(this.authoredTheme, path.slice(6)) as DeepPartial<PersonaTheme>;
+    } else if (path === 'theme') {
+      this.authoredTheme = (value ?? {}) as DeepPartial<PersonaTheme>;
+    } else {
+      this.authoredConfig = write(this.authoredConfig, path) as Partial<AgentWidgetConfig>;
+    }
+  }
+
+  private rebaseDefaults(previousVersion: string): void {
+    if (previousVersion === resolveDefaultsVersion(this.config)) return;
+    this.config = (this.mergeDefaults
+      ? deepMerge(resolveDefaults(this.authoredConfig), this.authoredConfig)
+      : { ...this.authoredConfig }) as AgentWidgetConfig;
+    this.theme = createTheme(this.authoredTheme, { validate: false, future: this.config.future });
+    this.syncThemeIntoConfig();
+  }
+
   private syncThemeIntoConfig(): void {
     this.config = {
       ...this.config,
@@ -314,6 +365,7 @@ export class ThemeEditorState {
 
   private pushHistorySnapshot(snapshot: ConfiguratorSnapshot, replaceCurrent = false): void {
     if (this.suppressHistory) return;
+    this.snapshotIntent.set(snapshot, { config: this.authoredConfig, theme: this.authoredTheme });
 
     const serialized = JSON.stringify(snapshot);
     const currentSerialized =
@@ -326,7 +378,10 @@ export class ThemeEditorState {
       return;
     }
 
-    if (serialized === currentSerialized) return;
+    const currentIntent = this.historyIndex >= 0
+      ? this.snapshotIntent.get(this.history[this.historyIndex]) : undefined;
+    if (serialized === currentSerialized &&
+      JSON.stringify(this.snapshotIntent.get(snapshot)) === JSON.stringify(currentIntent)) return;
 
     this.history = this.history.slice(0, this.historyIndex + 1);
     this.history.push(snapshot);
@@ -335,8 +390,11 @@ export class ThemeEditorState {
 
   private restoreSnapshot(snapshot: ConfiguratorSnapshot): void {
     this.suppressHistory = true;
+    const intent = this.snapshotIntent.get(snapshot);
+    this.authoredConfig = intent?.config ?? snapshot.config as Partial<AgentWidgetConfig>;
+    this.authoredTheme = intent?.theme ?? snapshot.theme;
     this.config = snapshot.config as unknown as AgentWidgetConfig;
-    this.theme = createTheme(snapshot.theme, { validate: false });
+    this.theme = createTheme(snapshot.theme, { validate: false, future: this.config.future });
     this.syncThemeIntoConfig();
     this.suppressHistory = false;
     this.notifyListeners();

package/src/theme-reference.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { getThemeReference } from "./theme-reference";
+import { resolveDefaults } from "./defaults";
+import { resolveThemeDefaults } from "./utils/tokens";
+
+describe.each([false, true])("theme reference defaults versioning (v5=%s)", (v5Defaults) => {
+  it("reads its documented defaults from the shared future-aware resolvers", () => {
+    const reference = getThemeReference({ v5Defaults });
+    const future = { v5Defaults };
+
+    expect(reference.defaultsVersion).toBe(v5Defaults ? "v5" : "v4");
+    expect(reference.themeDefaultsVersion).toBe(v5Defaults ? "v5" : "v4");
+    expect(reference.defaultColorPalette).toBe(
+      resolveThemeDefaults(future).palette.colors
+    );
+    expect(reference.defaultRadius).toBe(resolveThemeDefaults(future).palette.radius);
+    expect(reference.defaultLauncher).toEqual(resolveDefaults({ future }).launcher);
+  });
+});

package/src/theme-reference.ts

@@ -5,7 +5,8 @@
  * out of the IIFE widget bundle. Intended for AI/MCP tool consumption.
  */
 
-import { DEFAULT_PALETTE } from './utils/tokens'
+import { resolveThemeDefaults, resolveThemeDefaultsVersion } from './utils/tokens'
+import { resolveDefaults, resolveDefaultsVersion } from './defaults'
 import type { DeepPartial, PersonaTheme } from './types/theme'
 
 // ---------------------------------------------------------------------------
@@ -173,7 +174,7 @@ export const THEME_TOKEN_DOCS = {
         'Shared scrollbar appearance for every scroller: thumb (default semantic.colors.border), track (default transparent).',
       reasoningBubble: 'shadow: reasoning/thinking row box-shadow.',
       composer:
-        'Message input form: shadow (box-shadow), borderColor, padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type), controlSize (edge of every icon control in the action row: attachment, mention, mic, action buttons, overflow trigger, icon-mode send; default 40px) and controlIconSize (glyph inside them, default 24px). Per-control config keys (sendButton.size, voiceRecognition.iconSize) override controlSize; coarse-pointer devices floor the hit area at 40px. overlayBand paints the band behind an overlaid footer (composer.placement: "overlay"). segmented styles a segmented mode-group track (trackBackground, trackBorderRadius, padding, activeBackground, activeForeground, activeShadow, inactiveForeground, itemPadding); every key is optional and the stylesheet owns the defaults. modelPicker styles the model picker (background, hoverBackground, borderColor, borderRadius and labelColor on the closed control, which the native select and the popover trigger share; menuBackground, menuBorderRadius, rowHoverBackground, descriptionColor and suffixColor on the popover only), also all optional. overflowMenu styles the composer overflow "+" menu panel (background, borderColor, borderRadius, foreground, shadow), also all optional.',
+        'Message input form: sendIconSize (send/stop glyph; explicit sendButton.iconSize wins), sendButtonRadius (icon-mode submit radius), footerBorder (footer top border shorthand; none hides it), shadow (box-shadow), borderColor, focusBorderColor (focused form border; V4 keeps the resting border, V5 uses a stronger neutral mix), focusRing (CSS outline shorthand, 1px offset; V4 none, V5 a thin neutral ring; preserves shadow and causes no layout shift), padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type), controlSize (edge of every icon control in the action row: attachment, mention, mic, action buttons, overflow trigger, icon-mode send; default 40px) and controlIconSize (glyph inside them, default 24px). Per-control config keys (sendButton.size, voiceRecognition.iconSize) override controlSize; coarse-pointer devices floor the hit area at 40px. overlayBand paints the band behind an overlaid footer (composer.placement: "overlay"). segmented styles a segmented mode-group track (trackBackground, trackBorderRadius, padding, activeBackground, activeForeground, activeShadow, inactiveForeground, itemPadding); every key is optional and the stylesheet owns the defaults. modelPicker styles the model picker (background, hoverBackground, borderColor, borderRadius and labelColor on the closed control, which the native select and the popover trigger share; menuBackground, menuBorderRadius, rowHoverBackground, descriptionColor and suffixColor on the popover only), also all optional. overflowMenu styles the composer overflow "+" menu panel (background, borderColor, borderRadius, foreground, shadow), also all optional.',
       artifact:
         'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
     },
@@ -466,11 +467,16 @@ export const THEME_EXAMPLES: Record<string, ThemeExample> = {
  * Returns token system docs, the default color palette and radius scale,
  * example themes, and a list of SDK-bundled presets.
  */
-export function getThemeReference() {
+export function getThemeReference(future?: { v5Defaults?: boolean }) {
+  const themeDefaults = resolveThemeDefaults(future)
+  const defaults = resolveDefaults({ future })
   return {
     tokenDocs: THEME_TOKEN_DOCS,
-    defaultColorPalette: DEFAULT_PALETTE.colors,
-    defaultRadius: DEFAULT_PALETTE.radius,
+    defaultsVersion: resolveDefaultsVersion({ future }),
+    themeDefaultsVersion: resolveThemeDefaultsVersion(future),
+    defaultColorPalette: themeDefaults.palette.colors,
+    defaultRadius: themeDefaults.palette.radius,
+    defaultLauncher: defaults.launcher,
     examples: THEME_EXAMPLES,
     sdkPresets: ['shop', 'minimal', 'fullscreen'],
   }

package/src/tool-call-display-defaults.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { DEFAULT_WIDGET_CONFIG } from "./defaults";
+import { DEFAULT_WIDGET_CONFIG, mergeWithDefaults } from "./defaults";
 
 describe("tool call display defaults", () => {
   it("keeps advanced tool call transcript modes disabled by default", () => {
@@ -23,4 +23,36 @@ describe("tool call display defaults", () => {
       loadingAnimation: "none",
     });
   });
+
+  it("fills omitted tool display options when one option is overridden", () => {
+    const override = { collapsedMode: "tool-name" as const, expandable: false };
+    expect(mergeWithDefaults({ features: { toolCallDisplay: override } }).features?.toolCallDisplay)
+      .toEqual({ ...DEFAULT_WIDGET_CONFIG.features?.toolCallDisplay, ...override });
+    expect(DEFAULT_WIDGET_CONFIG.features?.toolCallDisplay?.collapsedMode).toBe("tool-call");
+  });
+
+  it("fills omitted reasoning display options without losing explicit false or zero", () => {
+    const override = { activePreview: false, previewMaxLines: 0, expandable: false };
+    expect(mergeWithDefaults({ features: { reasoningDisplay: override } }).features?.reasoningDisplay)
+      .toEqual({ ...DEFAULT_WIDGET_CONFIG.features?.reasoningDisplay, ...override });
+    expect(DEFAULT_WIDGET_CONFIG.features?.reasoningDisplay?.previewMaxLines).toBe(3);
+  });
+
+  it("retains optional display settings and leaves unrelated features intact", () => {
+    const result = mergeWithDefaults({
+      features: {
+        showToolCalls: false,
+        toolCallDisplay: { grouped: true, activeMinHeight: "100px", completedVisibility: "removed" },
+        reasoningDisplay: { loadingAnimation: "shimmer" },
+      },
+    });
+    expect(result.features?.showToolCalls).toBe(false);
+    expect(result.features?.toolCallDisplay?.activeMinHeight).toBe("100px");
+    expect(result.features?.toolCallDisplay?.completedVisibility).toBe("removed");
+    expect(result.features?.toolCallDisplay?.grouped).toBe(true);
+    expect(result.features?.reasoningDisplay).toEqual({
+      ...DEFAULT_WIDGET_CONFIG.features?.reasoningDisplay,
+      loadingAnimation: "shimmer",
+    });
+  });
 });

package/src/types/theme.ts

@@ -212,6 +212,8 @@ export interface InputTokens extends ComponentTokenSet {
 }
 
 export interface LauncherTokens extends ComponentTokenSet {
+  /** Distance from the viewport edges. Circle default: 20px; pill: 24px. */
+  offset?: string;
   size: string;
   iconSize: string;
   shadow: TokenReference<'shadow'>;
@@ -235,6 +237,15 @@ export interface PanelTokens extends ComponentTokenSet {
   inset?: string;
   /** Background of the region revealed behind a detached panel. */
   canvasBackground?: string;
+  /** Chrome defaults by rendered panel mode. */
+  modes?: Partial<Record<'floating' | 'inline' | 'sidebar' | 'docked' | 'mobile', {
+    /** Full border shorthand (for example, `"1px solid var(--persona-border)"`). */
+    border?: string;
+    /** Box-shadow token reference or raw CSS shadow. */
+    shadow?: string;
+    /** Corner radius token reference or raw CSS radius. */
+    borderRadius?: TokenReference<'radius'>;
+  }>>;
 }
 
 /** Per-element text styling shared by themable text surfaces. */
@@ -263,10 +274,16 @@ export interface HeaderTokens extends ComponentTokenSet {
    */
   border?: TokenReference<'color'>;
   borderRadius: TokenReference<'radius'>;
+  /** Standard-header padding. @default "20px 24px" */
+  padding?: string;
+  /** Minimal-header padding. Explicitly wins over `padding`. @default "16px 24px" */
+  minimalPadding?: string;
   /** 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'>;
+  /** Header identity glyph size as a fraction of its icon box. @default "0.6" */
+  iconScale?: string;
   /**
    * Legacy alias of `title.color`; `title.color` wins when both are set.
    * Unset, the title takes `foreground`, then the primary color.
@@ -305,6 +322,14 @@ export interface HeaderTokens extends ComponentTokenSet {
    * sibling. @default "1.5"
    */
   controlStrokeWidth?: string;
+  /** Header control corner radius. Per-control radius overrides win. */
+  controlBorderRadius?: string;
+  /** Default control hover/focus fill. Explicit button backgrounds win. */
+  controlHoverBackground?: TokenReference<'color'>;
+  /** Default control hover/focus icon color. Explicit button colors win. */
+  controlHoverForeground?: TokenReference<'color'>;
+  /** Keyboard focus outline; unset preserves the browser default. */
+  controlFocusOutline?: 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`). */
@@ -484,6 +509,12 @@ export interface MessageGeometryTokens {
 }
 
 export interface MessageTokens {
+  /** Height of the optional transcript top fade. Default 18px. */
+  topFadeHeight?: string;
+  /** Vertical gap between transcript turns. @default "12px" */
+  gap?: string;
+  /** Gap between turns in fullscreen mode; falls back to `gap`. */
+  fullscreenGap?: string;
   user: MessageGeometryTokens & {
     background: TokenReference<'color'>;
     text: TokenReference<'color'>;
@@ -497,6 +528,8 @@ export interface MessageTokens {
     borderRadius: TokenReference<'radius'>;
     /** Assistant bubble border color (CSS color). */
     border?: TokenReference<'color'>;
+    /** Border width; set to 0px for a flat assistant response. @default "1px" */
+    borderWidth?: string;
     /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
   };
@@ -622,13 +655,42 @@ export interface AttachmentTokens {
 }
 
 /** Tool-call row chrome (collapsible tool bubbles). */
-export interface ToolBubbleTokens {
+export interface ActivityTokens {
+  /** Minimum activity row height. */
+  rowHeight?: string;
+  /** Group child indentation; falls back to indent when unset. V5: 0px. */
+  groupIndent?: string;
+  /** Extra vertical gap between grouped rows. V5: 0px. */
+  groupGap?: string;
+  /** Padding around expanded group children. V5: 0px. */
+  groupPadding?: string;
+  /** Gap between consecutive activity entries. V5: 0px. */
+  transcriptGap?: string;
+  /** Gap from activity to an assistant response. V5: 12px. */
+  responseGap?: string;
+  /** Expanded body padding. V5: 4px 0. */
+  bodyPadding?: string;
+  /** Expanded reasoning text size. V5: 13px. */
+  bodySize?: string;
+  /** Expanded reasoning line height. V5: 1.5. */
+  bodyLineHeight?: string;
+  /** Expanded reasoning font weight. V5: 400. */
+  bodyFontWeight?: string;
+  /** Gap between expanded detail sections. V5: 8px. */
+  sectionGap?: string;
+  labelSize?: string;
+  iconSize?: string;
+  indent?: string;
+  bodySurface?: TokenReference<'color'>;
+}
+
+export interface ToolBubbleTokens extends ActivityTokens {
   /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
   shadow: string;
 }
 
 /** Reasoning / “thinking” row chrome. */
-export interface ReasoningBubbleTokens {
+export interface ReasoningBubbleTokens extends ActivityTokens {
   shadow: string;
 }
 
@@ -769,6 +831,10 @@ export interface ComposerChromeTokens {
   shadow: string;
   /** Border color of the composer form. @default semantic.colors.border */
   borderColor?: TokenReference<'color'>;
+  /** Focused form border color; falls back to borderColor. V5: a stronger neutral border. */
+  focusBorderColor?: TokenReference<'color'>;
+  /** Outer focus ring (CSS outline shorthand). V4: none; V5: a thin neutral ring. */
+  focusRing?: 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" */
@@ -787,12 +853,18 @@ export interface ComposerChromeTokens {
   controlSize?: string;
   /** Glyph box inside those controls. @default "24px" */
   controlIconSize?: string;
+  /** Send/stop glyph size. Explicit sendButton.iconSize wins. V5: 18px. */
+  sendIconSize?: string;
+  /** Icon-mode submit button radius. V4 inherits the primary button; V5: 9999px. */
+  sendButtonRadius?: string;
+  /** Footer top border (CSS shorthand). V4: 1px solid divider; V5: none. */
+  footerBorder?: string;
   /**
    * Background painted behind an overlaid composer footer
    * (`composer.placement: "overlay"`). Any CSS `background` value, gradients
    * included — same convention as the shadow tokens. Inert under
    * `placement: "block"`.
-   * @default "transparent"
+   * @default "transparent" (V4); a theme-aware 24px fade (V5)
    */
   overlayBand?: string;
   /** Segmented mode-group track. */
@@ -979,6 +1051,8 @@ export interface ScrollToBottomTokens extends ComponentTokenSet {
 
 /** Visual tokens shared by one suggestion presentation variant. */
 export interface SuggestionVariantTokens extends ComponentTokenSet {
+  /** Label weight. V4: 500; V5: 400. */
+  fontWeight?: string;
   /** Space inside one item, between its icon and its copy. */
   gap?: string;
   /** Space between suggestion items in the container. */
@@ -1030,6 +1104,7 @@ export interface ComponentTokens {
   voice: VoiceTokens;
   approval: ApprovalTokens;
   attachment: AttachmentTokens;
+  activity?: ActivityTokens;
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
   /** Event-stream inspector badge chips. */
@@ -1124,4 +1199,6 @@ export interface CreateThemeOptions {
   plugins?: PersonaThemePlugin[];
   validate?: boolean;
   extend?: PersonaTheme;
+  /** Selects the defaults overlay; explicit theme tokens always take precedence. */
+  future?: { v5Defaults?: boolean };
 }