@runtypelabs/persona 4.23.1 → 4.24.0

package/src/utils/theme.test.ts

@@ -1249,6 +1249,24 @@ describe('theme utils', () => {
     expect(el.getAttribute('data-persona-color-scheme')).toBe('dark');
   });
 
+  it.each([{ v5Defaults: false }, { v5Defaults: true }])(
+    'threads future.v5Defaults=%s through active theme resolution and root state',
+    (future) => {
+      const config = {
+        colorScheme: 'dark' as const,
+        future,
+        theme: { palette: { colors: { gray: { 500: '#123456' } } } },
+      };
+      expect(getActiveTheme(config).palette.colors.gray[500]).toBe('#123456');
+
+      const el = document.createElement('div');
+      applyThemeVariables(el, config);
+      expect(el.getAttribute('data-persona-defaults')).toBe(
+        future.v5Defaults ? 'v5' : 'v4'
+      );
+    }
+  );
+
   it('maps components.code.background to --persona-code-bg', () => {
     const theme = createTheme({
       components: { code: { background: '#fafafa' } },
@@ -1309,3 +1327,167 @@ describe('theme utils', () => {
     expect(explicit['--persona-md-code-block-border-radius']).toBe('2px');
   });
 });
+
+
+describe.each([false, true])('versioned panel mode widths (v5=%s)', (v5Defaults) => {
+  it.each(['docked', 'sidebar'] as const)('uses version defaults and explicit widths in %s', (mode) => {
+    const config = { apiUrl: '/api', future: { v5Defaults }, launcher: mode === 'docked' ? { mountMode: 'docked' as const } : { sidebarMode: true } };
+    expect(getActiveTheme(config).components.panel.width).toBe(v5Defaults ? '400px' : '420px');
+    expect(getActiveTheme({ ...config, theme: { components: { panel: { width: '510px' } } } }).components.panel.width).toBe('510px');
+    expect(getActiveTheme({ ...config, colorScheme: 'dark', darkTheme: { components: { panel: { width: '530px' } } } }).components.panel.width).toBe('530px');
+  });
+});
+
+describe.each([false, true])('versioned dark palette (v5=%s)', (v5Defaults) => {
+  const future = { v5Defaults };
+  const variables = (colorScheme: 'light' | 'dark' | 'auto') =>
+    themeToCssVariables(getActiveTheme({ future, colorScheme }));
+
+  afterEach(() => document.documentElement.classList.remove('dark'));
+
+  it('changes neutral and markdown defaults only in V5', () => {
+    const light = variables('light');
+    const dark = variables('dark');
+    for (const token of [
+      'surface', 'background', 'text', 'border', 'md-inline-code-bg', 'md-inline-code-color',
+      'md-code-block-bg', 'md-table-header-bg', 'md-blockquote-bg', 'md-blockquote-text-color',
+    ]) {
+      expect(dark[`--persona-${token}`], token).toBeDefined();
+      if (v5Defaults) expect(dark[`--persona-${token}`], token).not.toBe(light[`--persona-${token}`]);
+      else expect(dark[`--persona-${token}`], token).toBe(light[`--persona-${token}`]);
+    }
+    if (v5Defaults) {
+      expect(dark['--persona-surface']).toBe('#1a1a1b');
+      expect(dark['--persona-background']).toBe('#0f0f10');
+      expect(dark['--persona-text']).toBe('#f4f4f5');
+      expect(dark['--persona-border']).toBe('#2a2a2d');
+      expect(dark['--persona-message-user-bg']).toBe('#27272a');
+    }
+  });
+
+  it('resolves auto mode through the same versioned dark defaults', () => {
+    expect(variables('auto')).toEqual(variables('light'));
+    document.documentElement.classList.add('dark');
+    expect(variables('auto')).toEqual(variables('dark'));
+  });
+
+  it.each(['light', 'dark', 'auto'] as const)('honors explicit palette, semantic and component tokens in %s', (colorScheme) => {
+    document.documentElement.classList.add('dark');
+    const css = themeToCssVariables(getActiveTheme({
+      future, colorScheme,
+      theme: {
+        palette: { colors: { primary: { 500: '#123456' }, gray: { 500: '#abcdef' } } },
+        semantic: { colors: { surface: '#223344' } },
+        components: { markdown: { inlineCode: { background: '#334455' } } },
+      },
+      darkTheme: { components: { markdown: { table: { headerBackground: '#445566' } } } },
+    }));
+    expect(css['--persona-button-primary-bg']).toBe('#123456');
+    expect(css['--persona-text-muted']).toBe('#abcdef');
+    expect(css['--persona-surface']).toBe('#223344');
+    expect(css['--persona-md-inline-code-bg']).toBe('#334455');
+    if (colorScheme !== 'light') {
+      expect(css['--persona-md-table-header-bg']).toBe('#445566');
+      // A single custom gray stop must not reset the rest of V5's dark ramp.
+      if (v5Defaults) expect(css['--persona-text']).toBe('#f4f4f5');
+    }
+  });
+});
+
+it('keeps V5 dark body and markdown text above AA contrast', () => {
+  const css = themeToCssVariables(getActiveTheme({ colorScheme: 'dark', future: { v5Defaults: true } }));
+  const luminance = (hex: string) => {
+    const channels = hex.slice(1).match(/.{2}/g)!.map((channel) => {
+      const value = parseInt(channel, 16) / 255;
+      return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+    });
+    return channels[0] * 0.2126 + channels[1] * 0.7152 + channels[2] * 0.0722;
+  };
+  for (const [foreground, background] of [
+    ['text', 'surface'], ['text', 'background'], ['text', 'container'],
+    ['text-muted', 'surface'], ['text-muted', 'container'],
+    ['text', 'message-user-bg'], ['md-inline-code-color', 'md-inline-code-bg'],
+    ['md-code-block-text-color', 'md-code-block-bg'], ['text', 'md-table-header-bg'],
+    ['md-blockquote-text-color', 'md-blockquote-bg'], ['md-link-color', 'surface'],
+    ['button-primary-fg', 'button-primary-bg'],
+  ]) {
+    const values = [foreground, background].map((token) => luminance(css[`--persona-${token}`]));
+    expect((Math.max(...values) + 0.05) / (Math.min(...values) + 0.05), `${foreground} on ${background}`).toBeGreaterThanOrEqual(4.5);
+  }
+});
+
+describe.each([false, true])('welcome typography defaults (V5: %s)', (v5Defaults) => {
+  it('resolves lighter V5 typography and preserves V4 fallbacks', () => {
+    const css = themeToCssVariables(getActiveTheme({ future: { v5Defaults } }));
+    expect(css['--persona-components-introCard-title-fontSize']).toBe(v5Defaults ? '22px' : undefined);
+    expect(css['--persona-components-introCard-title-fontWeight']).toBe(v5Defaults ? '500' : undefined);
+    expect(css['--persona-components-header-title-fontWeight']).toBe(v5Defaults ? '500' : undefined);
+    for (const variant of ['chip', 'card', 'list']) {
+      expect(css[`--persona-components-suggestion-${variant}-fontWeight`]).toBe(v5Defaults ? '400' : undefined);
+    }
+    if (v5Defaults) expect(css['--persona-input-radius']).toBe('9999px');
+  });
+
+  it('honors explicit typography and composer corners', () => {
+    const css = themeToCssVariables(getActiveTheme({ future: { v5Defaults }, theme: { components: {
+      introCard: { title: { fontWeight: '400', fontSize: '30px' } },
+      header: { title: { fontWeight: '600' } },
+      suggestion: { card: { fontWeight: '600' } },
+      input: { borderRadius: '20px' },
+    } } }));
+    expect(css['--persona-components-introCard-title-fontWeight']).toBe('400');
+    expect(css['--persona-components-introCard-title-fontSize']).toBe('30px');
+    expect(css['--persona-components-header-title-fontWeight']).toBe('600');
+    expect(css['--persona-components-suggestion-card-fontWeight']).toBe('600');
+    expect(css['--persona-input-radius']).toBe('20px');
+  });
+});
+
+describe.each([false, true])('activity aliases (V5 %s)', v5Defaults => {
+  it('emits versioned spacing and preserves independent spacing overrides', () => {
+    const defaults = themeToCssVariables(getActiveTheme({ future: { v5Defaults } }));
+    const expected = { indent: '0px', groupIndent: '0px', groupGap: '0px', groupPadding: '0px', transcriptGap: '0px', responseGap: '12px', bodyPadding: '4px 0', bodySize: '13px', bodyLineHeight: '1.5', bodyFontWeight: '400', sectionGap: '8px' };
+    for (const [key, value] of Object.entries(expected)) {
+      expect(defaults[`--persona-components-activity-${key}`]).toBe(v5Defaults ? value : undefined);
+    }
+    const activity = { indent: '12px', groupIndent: '6px', groupGap: '3px', groupPadding: '2px 0', transcriptGap: '6px', responseGap: '16px', bodyPadding: '10px 0', bodySize: '15px', bodyLineHeight: '1.7', bodyFontWeight: '500', sectionGap: '14px' };
+    const overridden = themeToCssVariables(getActiveTheme({ future: { v5Defaults }, theme: { components: { activity } } }));
+    for (const [key, value] of Object.entries(activity)) {
+      expect(overridden[`--persona-components-activity-${key}`]).toBe(value);
+    }
+  });
+  it('keeps legacy values usable while preferring explicit activity tokens', () => {
+    const vars = (activity?: { labelSize?: string; bodySurface?: string }) => themeToCssVariables(getActiveTheme({ future: { v5Defaults }, theme: { components: {
+      toolBubble: { labelSize: '17px', shadow: 'none' }, collapsibleWidget: { surface: '#123456' }, activity,
+    } } }));
+    expect(vars()['--persona-components-toolBubble-labelSize']).toBe('17px');
+    expect(vars()['--persona-components-activity-bodySurface']).toBe('#123456');
+    expect(vars({ labelSize: '15px', bodySurface: '#abcdef' })['--persona-components-toolBubble-labelSize']).toBe('15px');
+    expect(vars({ bodySurface: '#abcdef' })['--persona-components-activity-bodySurface']).toBe('#abcdef');
+  });
+});
+
+describe.each(['light', 'dark'] as const)('V5 header surface (%s)', colorScheme => {
+  it('matches the transcript container while preserving explicit header colors', () => {
+    const config = { colorScheme, future: { v5Defaults: true } };
+    const css = themeToCssVariables(getActiveTheme(config));
+    expect(css['--persona-header-bg']).toBe(css['--persona-container']);
+    const custom = themeToCssVariables(getActiveTheme({ ...config, theme: { components: { header: { background: '#123456' } } } }));
+    expect(custom['--persona-header-bg']).toBe('#123456');
+  });
+});
+
+describe('V5 header control surfaces', () => {
+  it('keeps V4 tokens unset and preserves explicit V5 overrides', () => {
+    const legacy = themeToCssVariables(createTheme());
+    const v5 = themeToCssVariables(createTheme(undefined, { future: { v5Defaults: true } }));
+    expect(legacy['--persona-components-header-controlBorderRadius']).toBeUndefined();
+    expect(v5['--persona-components-header-controlBorderRadius']).toBe('8px');
+    expect(v5['--persona-components-header-controlHoverBackground']).toContain('8%');
+    const custom = themeToCssVariables(createTheme({
+      components: { header: { controlBorderRadius: '4px', controlHoverBackground: 'red' } },
+    }, { future: { v5Defaults: true } }));
+    expect(custom['--persona-components-header-controlBorderRadius']).toBe('4px');
+    expect(custom['--persona-components-header-controlHoverBackground']).toBe('red');
+  });
+});

package/src/utils/theme.ts

@@ -1,6 +1,8 @@
-import type { DeepPartial, PersonaTheme } from '../types/theme';
+import { CIRCLE_LAUNCHER_TOKENS, resolveLauncherVariant } from "./launcher-variant";
+import type { CreateThemeOptions, DeepPartial, PersonaTheme } from '../types/theme';
 import type { AgentWidgetConfig } from '../types';
-import { createTheme, resolveTokens, themeToCssVariables } from './tokens';
+import { resolveDefaultsVersion } from '../defaults';
+import { createTheme, resolveTokens, themeToCssVariables, DEFAULT_COMPONENTS_V4 } from './tokens';
 import { deepMerge } from './deep-merge';
 
 export type ColorScheme = 'light' | 'dark' | 'auto';
@@ -9,11 +11,32 @@ export interface PersonaWidgetConfig {
   theme?: DeepPartial<PersonaTheme>;
   darkTheme?: DeepPartial<PersonaTheme>;
   colorScheme?: ColorScheme;
+  future?: { v5Defaults?: boolean };
 }
 
 type WidgetConfig = PersonaWidgetConfig | AgentWidgetConfig;
 
-const DARK_PALETTE = {
+const isPanelWidthMode = (config?: WidgetConfig): boolean =>
+  !!config &&
+  "launcher" in config &&
+  (config.launcher?.sidebarMode === true || config.launcher?.mountMode === "docked");
+
+const applyPanelModeWidth = (theme: PersonaTheme, config?: WidgetConfig): PersonaTheme => {
+  if (!config || !isPanelWidthMode(config)) return theme;
+  const lightWidth = config.theme?.components?.panel?.width;
+  const darkWidth = config.darkTheme?.components?.panel?.width;
+  const configuredWidth = getColorScheme(config) === "dark" ? darkWidth ?? lightWidth : lightWidth;
+  if (configuredWidth != null) return theme;
+  return {
+    ...theme,
+    components: {
+      ...theme.components,
+      panel: { ...theme.components.panel, width: resolveDefaultsVersion(config) === "v5" ? "400px" : "420px" },
+    },
+  };
+};
+
+const DARK_PALETTE_BASE = {
   colors: {
     primary: {
       50: '#ffffff',
@@ -113,7 +136,7 @@ const DARK_PALETTE = {
  * The ghost hover wash must invert with the scheme: 5% black is invisible on a
  * near-black surface, so every dark scheme gets a light alpha instead.
  */
-const DARK_COMPONENTS: DeepPartial<PersonaTheme> = {
+const DARK_COMPONENTS_BASE: DeepPartial<PersonaTheme> = {
   components: {
     button: {
       ghost: {
@@ -160,6 +183,79 @@ const DARK_COMPONENTS: DeepPartial<PersonaTheme> = {
   },
 };
 
+// V4 stays frozen; V5 provides the dark neutral ramp and semantic roles.
+export const DARK_PALETTE_V4 = DARK_PALETTE_BASE;
+export const DARK_PALETTE_V5 = {
+  ...DARK_PALETTE_V4,
+  colors: {
+    ...DARK_PALETTE_V4.colors,
+    primary: {
+      50: '#0f0f10', 100: '#27272a', 200: '#3f3f46', 300: '#52525b',
+      400: '#71717a', 500: '#f4f4f5', 600: '#e4e4e7', 700: '#d4d4d8',
+      800: '#a1a1aa', 900: '#fafafa', 950: '#ffffff',
+    },
+    gray: {
+      50: '#1a1a1b', 100: '#27272a', 200: '#2a2a2d', 300: '#52525b',
+      400: '#71717a', 500: '#a1a1aa', 600: '#b4b4bd', 700: '#d4d4d8',
+      800: '#e4e4e7', 900: '#f4f4f5', 950: '#fafafa',
+    },
+  },
+};
+export const DARK_COMPONENTS_V4 = DARK_COMPONENTS_BASE;
+export const DARK_COMPONENTS_V5: DeepPartial<PersonaTheme> = {
+  semantic: {
+    colors: {
+      primary: 'palette.colors.primary.500',
+      accent: 'palette.colors.primary.600',
+      background: '#0f0f10',
+      surface: 'palette.colors.gray.50',
+      container: '#1c1c20',
+      text: 'palette.colors.gray.900',
+      textMuted: 'palette.colors.gray.500',
+      textInverse: '#0f0f10',
+      border: 'palette.colors.gray.200',
+      divider: 'palette.colors.gray.200',
+      interactive: {
+        default: 'palette.colors.primary.600', hover: 'palette.colors.primary.700',
+        focus: 'palette.colors.primary.600', active: 'palette.colors.primary.600',
+      },
+    },
+  },
+  components: {
+    ...DARK_COMPONENTS_BASE.components,
+    button: {
+      ...DARK_COMPONENTS_BASE.components?.button,
+      primary: { background: 'semantic.colors.primary', foreground: 'palette.colors.primary.50' },
+    },
+    markdown: {
+      inlineCode: { background: 'palette.colors.gray.100', foreground: 'semantic.colors.text' },
+      link: { foreground: 'semantic.colors.accent' },
+      codeBlock: {
+        background: 'semantic.colors.container', borderColor: 'semantic.colors.border',
+        textColor: 'semantic.colors.text',
+      },
+      table: { headerBackground: 'palette.colors.gray.100', borderColor: 'semantic.colors.border' },
+      blockquote: {
+        background: 'semantic.colors.container', borderColor: 'palette.colors.gray.300',
+        textColor: 'semantic.colors.textMuted',
+      },
+    },
+    eventStream: {
+      ...DARK_COMPONENTS_BASE.components?.eventStream,
+      badge: {
+        ...DARK_COMPONENTS_BASE.components?.eventStream?.badge,
+        step: { background: 'palette.colors.gray.100', foreground: 'palette.colors.gray.700' },
+        default: { background: 'palette.colors.gray.100', foreground: 'palette.colors.gray.700' },
+      },
+    },
+  },
+};
+
+const resolveDarkDefaults = (future?: { v5Defaults?: boolean }) =>
+  resolveDefaultsVersion({ future }) === 'v5'
+    ? { palette: DARK_PALETTE_V5, components: DARK_COMPONENTS_V5 }
+    : { palette: DARK_PALETTE_V4, components: DARK_COMPONENTS_V4 };
+
 /**
  * Normalize theme config for merging; rejects non-objects.
  */
@@ -195,11 +291,17 @@ export const getColorScheme = (config?: WidgetConfig): 'light' | 'dark' => {
   return getColorSchemeFromConfig(config);
 };
 
-export const createLightTheme = (userConfig?: DeepPartial<PersonaTheme>): PersonaTheme => {
-  return createTheme(userConfig);
+export const createLightTheme = (
+  userConfig?: DeepPartial<PersonaTheme>,
+  options: Pick<CreateThemeOptions, 'future'> = {}
+): PersonaTheme => {
+  return createTheme(userConfig, options);
 };
 
-export const createDarkTheme = (userConfig?: DeepPartial<PersonaTheme>): PersonaTheme => {
+export const createDarkTheme = (
+  userConfig?: DeepPartial<PersonaTheme>,
+  options: Pick<CreateThemeOptions, 'future'> = {}
+): PersonaTheme => {
   // createTheme() already merges every palette sub-object (radius, typography,
   // shadows, …) over the defaults, so only the dark color scales need to be
   // layered UNDER the user's colors here. Spreading a pre-built default
@@ -209,8 +311,9 @@ export const createDarkTheme = (userConfig?: DeepPartial<PersonaTheme>): Persona
   // DARK_COMPONENTS goes underneath by deep merge, not spread: a shallow
   // spread of `components` would drop the dark ghost hover the moment a host
   // set any unrelated component token.
+  const darkDefaults = resolveDarkDefaults(options.future);
   const config = (deepMerge(
-    DARK_COMPONENTS as Record<string, unknown>,
+    darkDefaults.components as Record<string, unknown>,
     (userConfig ?? {}) as Record<string, unknown>
   ) ?? {}) as DeepPartial<PersonaTheme>;
 
@@ -219,31 +322,40 @@ export const createDarkTheme = (userConfig?: DeepPartial<PersonaTheme>): Persona
       ...config,
       palette: {
         ...config.palette,
-        colors: {
-          ...DARK_PALETTE.colors,
-          ...config.palette?.colors,
-        },
+        // Preserve every dark stop when a host overrides just one shade.
+        // Keep V4's historical scale replacement behavior unchanged.
+        colors: resolveDefaultsVersion(options) === 'v5'
+          ? deepMerge(darkDefaults.palette.colors, config.palette?.colors) as PersonaTheme['palette']['colors']
+          : { ...darkDefaults.palette.colors, ...config.palette?.colors },
       },
     },
-    { validate: false }
+    { validate: false, future: options.future }
   );
 };
 
 export const getActiveTheme = (config?: WidgetConfig): PersonaTheme => {
   const scheme = getColorScheme(config);
-  const lightThemeConfig = normalizeThemeConfig(config?.theme);
+  const explicitTheme = normalizeThemeConfig(config?.theme);
+  // Variant defaults sit under explicit theme tokens in either defaults state.
+  const launcherDefaults = resolveLauncherVariant(config) === 'circle'
+    ? CIRCLE_LAUNCHER_TOKENS
+    : { ...DEFAULT_COMPONENTS_V4.launcher, ...(config?.future?.v5Defaults ? { offset: '1.5rem' } : {}) };
+  const lightThemeConfig = deepMerge(
+    { components: { launcher: launcherDefaults } }, explicitTheme
+  ) as DeepPartial<PersonaTheme>;
   const darkThemeConfig = normalizeThemeConfig(config?.darkTheme);
 
   if (scheme === 'dark') {
-    return createDarkTheme(
+    return applyPanelModeWidth(createDarkTheme(
       deepMerge(
         (lightThemeConfig ?? {}) as Record<string, unknown>,
         (darkThemeConfig ?? {}) as Record<string, unknown>
-      ) as DeepPartial<PersonaTheme>
-    );
+      ) as DeepPartial<PersonaTheme>,
+      { future: config?.future }
+    ), config);
   }
 
-  return createLightTheme(lightThemeConfig);
+  return applyPanelModeWidth(createLightTheme(lightThemeConfig, { future: config?.future }), config);
 };
 
 export const getCssVariables = (theme: PersonaTheme): Record<string, string> => {
@@ -267,6 +379,7 @@ export const applyThemeVariables = (
   // host pins colorScheme. Re-applied on every theme application, so live
   // config updates and theme-observer callbacks keep it current.
   element.setAttribute("data-persona-color-scheme", getColorScheme(config));
+  element.setAttribute("data-persona-defaults", resolveDefaultsVersion(config));
 };
 
 export const createThemeObserver = (

package/src/utils/tokens.test.ts

@@ -1,10 +1,131 @@
 import { describe, expect, it } from 'vitest';
-import { createTheme, themeToCssVariables } from './tokens';
+import {
+  createTheme,
+  resolveThemeDefaults,
+  resolveThemeDefaultsVersion,
+  themeToCssVariables,
+} from './tokens';
 import type { DeepPartial, PersonaTheme } from '../types/theme';
 
 const vars = (override: DeepPartial<PersonaTheme>): Record<string, string> =>
   themeToCssVariables(createTheme(override, { validate: false }));
 
+describe.each([{ v5Defaults: false }, { v5Defaults: true }])(
+  'theme defaults ($v5Defaults)',
+  ({ v5Defaults }) => {
+    it('resolves an explicit overlay version while preserving explicit token precedence', () => {
+      const future = { v5Defaults };
+      expect(resolveThemeDefaultsVersion(future)).toBe(v5Defaults ? 'v5' : 'v4');
+      expect(resolveThemeDefaults(future).palette.colors.gray[500]).toBe(
+        v5Defaults ? '#737373' : '#6b7280'
+      );
+
+      const theme = createTheme(
+        { palette: { colors: { gray: { 500: '#123456' } } } },
+        { future, validate: false }
+      );
+      expect(theme.palette.colors.gray[500]).toBe('#123456');
+    });
+
+    it('materializes the selected version geometry defaults', () => {
+      const css = themeToCssVariables(createTheme(undefined, { future: { v5Defaults }, validate: false }));
+      expect(css['--persona-components-header-padding']).toBe(v5Defaults ? '8px 8px 8px 16px' : '20px 24px');
+      expect(css['--persona-components-header-minimalPadding']).toBe(v5Defaults ? '8px 8px 8px 16px' : '16px 24px');
+      expect(css['--persona-components-message-gap']).toBe(v5Defaults ? '20px' : '12px');
+      expect(css['--persona-components-panel-width']).toBe(v5Defaults ? 'min(400px, calc(100vw - 24px))' : 'min(440px, calc(100vw - 24px))');
+      expect(css['--persona-components-panel-height']).toBe(
+        v5Defaults ? 'min(704px, calc(100dvh - 104px))' : 'min(640px, max(200px, calc(100vh - 64px)))'
+      );
+      expect(css['--persona-components-panel-modes-mobile-borderRadius']).toBe('0');
+    });
+
+    it('keeps explicit geometry and typography above the version overlay', () => {
+      const css = themeToCssVariables(createTheme({ components: {
+        message: { user: { padding: '4px', borderRadius: '7px' }, assistant: { borderWidth: '2px', lineHeight: '1.8' } },
+        composer: { fontSize: '17px', controlSize: '36px' },
+        input: { borderRadius: '9px' },
+        header: { controlSize: '34px', iconScale: '0.75' },
+      } }, { future: { v5Defaults }, validate: false }));
+      expect(css['--persona-message-user-padding']).toBe('4px');
+      expect(css['--persona-message-user-radius']).toBe('7px');
+      expect(css['--persona-message-assistant-border-width']).toBe('2px');
+      expect(css['--persona-message-assistant-line-height']).toBe('1.8');
+      expect(css['--persona-composer-font-size']).toBe('17px');
+      expect(css['--persona-composer-control-size']).toBe('36px');
+      expect(css['--persona-input-radius']).toBe('9px');
+    });
+
+    it('uses an explicit shared turn gap in fullscreen unless separately overridden', () => {
+      const shared = createTheme({ components: { message: { gap: '13px' } } }, { future: { v5Defaults }, validate: false });
+      expect(shared.components.message.fullscreenGap).toBe('13px');
+      const specific = createTheme({ components: { message: { gap: '13px', fullscreenGap: '31px' } } }, { future: { v5Defaults }, validate: false });
+      expect(specific.components.message.fullscreenGap).toBe('31px');
+    });
+
+    it('keeps the transcript surface separate from the tinted user bubble', () => {
+      const css = themeToCssVariables(createTheme(undefined, { future: { v5Defaults }, validate: false }));
+      expect(css['--persona-container']).toBe(v5Defaults ? '#ffffff' : '#f9fafb');
+      expect(css['--persona-message-user-bg']).toBe(v5Defaults ? '#f5f5f5' : '#171717');
+    });
+
+    it('keeps palette radius overrides connected to panel, user bubble, and composer', () => {
+      const css = themeToCssVariables(createTheme({ palette: { radius: { lg: '3px', xl: '7px', '2xl': '11px', full: '99px' } } }, { future: { v5Defaults }, validate: false }));
+      expect(css['--persona-panel-radius']).toBe('7px');
+      expect(css['--persona-message-user-radius']).toBe(v5Defaults ? '7px' : '3px');
+      expect(css['--persona-input-radius']).toBe(v5Defaults ? '99px' : '3px');
+    });
+
+    it('derives minimal header padding from an explicit shared padding unless overridden', () => {
+      const shared = createTheme(
+        { components: { header: { padding: '10px 12px' } } },
+        { future: { v5Defaults }, validate: false }
+      );
+      expect(shared.components.header.minimalPadding).toBe('10px 12px');
+
+      const specific = createTheme(
+        { components: { header: { padding: '10px 12px', minimalPadding: '8px 10px' } } },
+        { future: { v5Defaults }, validate: false }
+      );
+      expect(specific.components.header.minimalPadding).toBe('8px 10px');
+    });
+
+    it('emits prefixed collapsible-widget chrome aliases and legacy aliases', () => {
+      const css = themeToCssVariables(createTheme(undefined, { future: { v5Defaults }, validate: false }));
+
+      expect(css['--persona-cw-container']).toBe(v5Defaults ? '#fafafa' : '#f9fafb');
+      expect(css['--persona-cw-surface']).toBe(v5Defaults ? '#ffffff' : '#f9fafb');
+      expect(css['--persona-cw-border']).toBe(v5Defaults ? '#e5e5e5' : '#e5e7eb');
+      expect(css['--cw-container']).toBe(css['--persona-cw-container']);
+      expect(css['--cw-surface']).toBe(css['--persona-cw-surface']);
+      expect(css['--cw-border']).toBe(css['--persona-cw-border']);
+    });
+
+    it('applies explicit collapsible-widget tokens to both alias families', () => {
+      const css = themeToCssVariables(
+        createTheme(
+          {
+            components: {
+              collapsibleWidget: {
+                container: '#123456',
+                surface: '#234567',
+                border: '#345678',
+              },
+            },
+          },
+          { future: { v5Defaults }, validate: false }
+        )
+      );
+
+      expect(css['--persona-cw-container']).toBe('#123456');
+      expect(css['--persona-cw-surface']).toBe('#234567');
+      expect(css['--persona-cw-border']).toBe('#345678');
+      expect(css['--cw-container']).toBe('#123456');
+      expect(css['--cw-surface']).toBe('#234567');
+      expect(css['--cw-border']).toBe('#345678');
+    });
+  }
+);
+
 const flatSurface = (surface: string): DeepPartial<PersonaTheme> => ({
   semantic: { colors: { surface, background: surface, container: surface } },
 });