@runtypelabs/persona 4.23.2 → 4.24.0

package/src/theme-editor/sections.test.ts

@@ -5,12 +5,43 @@ import {
   COMPONENT_SHAPE_SECTIONS,
   COMPONENTS_SECTIONS,
   CONFIGURE_SECTIONS,
+  getThemeEditorTabs,
   INTERFACE_ROLES_SECTION,
+  resolveEditorFieldDefault,
   STYLE_SECTIONS,
 } from "./sections";
+import { resolveDefaults } from "../defaults";
+import { resolveThemeDefaults } from "../utils/tokens";
 import { ALL_ROLES } from "./role-mappings";
 
 describe("theme editor scroll-to-bottom controls", () => {
+  it("resolves field hints from the selected shared defaults tree", () => {
+    const v4Tabs = getThemeEditorTabs();
+    const v5Tabs = getThemeEditorTabs({ v5Defaults: true });
+    const headerIcon = v4Tabs
+      .flatMap((tab) => tab.sections)
+      .flatMap((section) => section.fields)
+      .find((field) => field.path === "launcher.headerIconSize");
+
+    expect(headerIcon?.defaultValue).toBe(
+      resolveDefaults().launcher?.headerIconSize
+    );
+    expect(resolveEditorFieldDefault({
+      id: "theme-surface",
+      label: "Surface",
+      type: "token-ref",
+      path: "theme.semantic.colors.surface",
+    }, { v5Defaults: true })).toBe(
+      resolveThemeDefaults({ v5Defaults: true }).semantic.colors.surface
+    );
+    const v5HeaderIcon = v5Tabs.flatMap((tab) => tab.sections)
+      .flatMap((section) => section.fields)
+      .find((field) => field.path === "launcher.headerIconSize");
+    expect(v5HeaderIcon?.defaultValue).toBe("20px");
+    expect(headerIcon?.defaultValue).toBe("40px");
+    expect(v5Tabs.map((tab) => tab.id)).toEqual(v4Tabs.map((tab) => tab.id));
+  });
+
   it("exposes clear style semantics and independent role width controls", () => {
     const section = CONFIGURE_SECTIONS.find((entry) => entry.id === "messages-layout");
     const fieldsByPath = new Map(

package/src/theme-editor/sections.ts

@@ -5,11 +5,14 @@ import {
   DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH,
   DEFAULT_FLOATING_LAUNCHER_WIDTH,
   DEFAULT_INPUT_PLACEHOLDER,
+  resolveDefaults,
 } from '../defaults';
 import {
   DEFAULT_PANEL_CANVAS_BACKGROUND,
   DEFAULT_PANEL_INSET,
+  resolveThemeDefaults,
 } from '../utils/tokens';
+import type { AgentWidgetConfig } from '../types';
 import { COLOR_FAMILIES } from './color-utils';
 import {
   ROLE_SURFACES,
@@ -1336,12 +1339,63 @@ export const STYLE_SECTIONS_V2: SectionDef[] = [
 // ALL TABS
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-export const ALL_TABS: TabDef[] = [
+const ALL_TABS_BASE: TabDef[] = [
   { id: 'style', label: 'Style', sections: STYLE_SECTIONS },
   { id: 'design-system', label: 'Design System', sections: COMPONENTS_SECTIONS },
   { id: 'configure', label: 'Configure', sections: CONFIGURE_SECTIONS },
 ];
 
+const getByPath = (value: unknown, path: string): unknown =>
+  path.split('.').reduce<unknown>((current, key) =>
+    current && typeof current === 'object'
+      ? (current as Record<string, unknown>)[key]
+      : undefined, value);
+
+/**
+ * Resolves editor field metadata from the same versioned config and token
+ * defaults as the widget. The static field value remains the fallback for
+ * presentation-only values (such as intentionally blank optional tokens).
+ */
+export function resolveEditorFieldDefault(
+  field: FieldDef,
+  future?: AgentWidgetConfig['future']
+): unknown {
+  const configDefaults = resolveDefaults({ future });
+  const themeDefaults = resolveThemeDefaults(future);
+  const path = field.path;
+  const themePath = path.startsWith('theme.')
+    ? path.slice('theme.'.length)
+    : path.startsWith('darkTheme.')
+      ? path.slice('darkTheme.'.length)
+      : undefined;
+  const resolved = themePath
+    ? getByPath(themeDefaults, themePath)
+    : getByPath(configDefaults, path);
+  return resolved === undefined ? field.defaultValue : resolved;
+}
+
+/**
+ * Returns editor tabs with default metadata resolved for the selected defaults
+ * version. Callers keep authored values separate; this only drives UI hints.
+ */
+export function getThemeEditorTabs(
+  future?: AgentWidgetConfig['future']
+): TabDef[] {
+  return ALL_TABS_BASE.map((tab) => ({
+    ...tab,
+    sections: tab.sections.map((section) => ({
+      ...section,
+      fields: section.fields.map((field) => ({
+        ...field,
+        defaultValue: resolveEditorFieldDefault(field, future),
+      })),
+    })),
+  }));
+}
+
+/** Legacy editor metadata, resolved through the v4 defaults tree. */
+export const ALL_TABS: TabDef[] = getThemeEditorTabs();
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // HELPERS: light/dark scoping for dual-mode editing
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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

@@ -12,4 +12,53 @@ describe("ThemeEditorState preference reset", () => {
     expect(state.get("features.artifacts.display.files")).toBeUndefined();
     expect(state.getConfig()).not.toHaveProperty("features");
   });
+
+  it("preserves an authored v5 defaults opt-in across state reset", () => {
+    const state = new ThemeEditorState(
+      undefined,
+      { future: { v5Defaults: true } },
+    );
+
+    expect(state.getConfig().future?.v5Defaults).toBe(true);
+    expect(state.exportSnapshot().config.future).toEqual({ v5Defaults: true });
+
+    state.resetToDefaults();
+
+    expect(state.getConfig().future?.v5Defaults).toBe(true);
+  });
+});
+
+describe('version switching preserves authored values', () => {
+  it('rebases config and theme in both directions, including undo/redo', () => {
+    const state = new ThemeEditorState();
+    state.set('theme.components.header.controlSize', '32px');
+    state.set('features.toolCallDisplay.autoExpand', true);
+    state.set('future.v5Defaults', true);
+    expect(state.get('features.toolCallDisplay.variant')).toBe('row');
+    expect(state.get('features.toolCallDisplay.autoExpand')).toBe(true);
+    expect(state.get('theme.components.header.controlSize')).toBe('32px');
+    expect(state.get('theme.components.header.controlIconSize')).toBe('18px');
+    state.undo();
+    state.redo();
+    state.unset('future.v5Defaults');
+    expect(state.get('features.toolCallDisplay.variant')).toBeUndefined();
+    expect(state.get('theme.components.header.controlIconSize')).toBeUndefined();
+    state.set('future.v5Defaults', true);
+    expect(state.get('theme.components.header.controlSize')).toBe('32px');
+  });
+  it('preserves constructor overrides and same-batch edits regardless of order', () => {
+    const state = new ThemeEditorState({ components: { header: { controlSize: '40px' } } }, { features: { toolCallDisplay: { autoExpand: true } } });
+    state.setBatch({ 'theme.components.header.controlIconSize': '22px', 'future.v5Defaults': true });
+    expect(state.get('features.toolCallDisplay.variant')).toBe('row');
+    expect(state.get('theme.components.header.controlSize')).toBe('40px');
+    expect(state.get('theme.components.header.controlIconSize')).toBe('22px');
+    state.setBatch({ 'future.v5Defaults': false, 'theme.components.header.controlSize': '44px' });
+    expect(state.get('theme.components.header.controlSize')).toBe('44px');
+  });
+  it('keeps sparse configs sparse when defaults merging is disabled', () => {
+    const state = new ThemeEditorState(undefined, {}, { mergeDefaults: false });
+    state.set('future.v5Defaults', true);
+    expect(state.get('features')).toBeUndefined();
+    expect(state.get('theme.components.header.controlSize')).toBe('28px');
+  });
 });

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",
+    });
+  });
 });