@runtypelabs/persona 4.14.0 → 4.16.0

package/src/utils/theme.test.ts

@@ -137,6 +137,36 @@ describe('theme utils', () => {
     expect(cssVars['--persona-button-radius']).toBe('6px');
   });
 
+  it('zeroes horizontal intro-card padding when the card resolves flat', () => {
+    const cssVars = themeToCssVariables(createTheme({} as any));
+    expect(cssVars['--persona-intro-card-padding']).toBe('1.5rem 0');
+  });
+
+  it('keeps full intro-card padding when a background or shadow makes it a card', () => {
+    const withBackground = themeToCssVariables(
+      createTheme({
+        components: { introCard: { background: '#ffffff' } },
+      } as any)
+    );
+    expect(withBackground['--persona-intro-card-padding']).toBe('1.5rem');
+
+    const withShadow = themeToCssVariables(
+      createTheme({
+        components: { introCard: { shadow: '0 1px 2px rgba(0,0,0,0.1)' } },
+      } as any)
+    );
+    expect(withShadow['--persona-intro-card-padding']).toBe('1.5rem');
+  });
+
+  it('lets an explicit intro-card padding token win over the flat default', () => {
+    const cssVars = themeToCssVariables(
+      createTheme({
+        components: { introCard: { padding: '2rem' } },
+      } as any)
+    );
+    expect(cssVars['--persona-intro-card-padding']).toBe('2rem');
+  });
+
   it.each([
     {
       role: 'surface',
@@ -287,6 +317,61 @@ describe('theme utils', () => {
     expect(customVars['--persona-header-action-icon-fg']).toBe('#9ca3af');
   });
 
+  it('emits full-path CSS variables for header and welcome text style tokens', () => {
+    const theme = createTheme({
+      components: {
+        introCard: {
+          title: { fontFamily: 'Georgia, serif', fontSize: '1.5rem' },
+        },
+        header: {
+          title: {
+            fontFamily: 'Inter, sans-serif',
+            color: 'palette.colors.secondary.500',
+          },
+        },
+      },
+    } as any);
+    const cssVars = themeToCssVariables(theme);
+
+    expect(cssVars['--persona-components-introCard-title-fontFamily']).toBe(
+      'Georgia, serif'
+    );
+    expect(cssVars['--persona-components-introCard-title-fontSize']).toBe('1.5rem');
+    expect(cssVars['--persona-components-header-title-fontFamily']).toBe(
+      'Inter, sans-serif'
+    );
+    // title.color supersedes the legacy titleForeground alias.
+    expect(cssVars['--persona-header-title-fg']).toBe('#8b5cf6');
+  });
+
+  it('keeps titleForeground working when no header.title.color is set', () => {
+    const cssVars = themeToCssVariables(
+      createTheme({
+        components: {
+          header: { titleForeground: 'palette.colors.gray.500' },
+        },
+      } as any)
+    );
+
+    expect(cssVars['--persona-header-title-fg']).toBe('#6b7280');
+  });
+
+  it('emits suggestion itemGap for every variant, defaulting to 8px', () => {
+    const defaults = themeToCssVariables(createTheme());
+    expect(defaults['--persona-components-suggestion-chip-itemGap']).toBe('8px');
+    expect(defaults['--persona-components-suggestion-card-itemGap']).toBe('8px');
+    expect(defaults['--persona-components-suggestion-list-itemGap']).toBe('8px');
+
+    const custom = themeToCssVariables(
+      createTheme({
+        components: { suggestion: { list: { itemGap: '20px' } } },
+      } as any)
+    );
+    expect(custom['--persona-components-suggestion-list-itemGap']).toBe('20px');
+    // Sibling variants keep the default.
+    expect(custom['--persona-components-suggestion-chip-itemGap']).toBe('8px');
+  });
+
   it('maps button.ghost tokens to the composer ghost icon-button CSS variables', () => {
     const cssVars = themeToCssVariables(createTheme());
 
@@ -393,6 +478,40 @@ describe('theme utils', () => {
     expect(cssVars['--persona-composer-shadow']).toBe('none');
   });
 
+  it('falls back composer spacing/type vars to the utility-class defaults', () => {
+    const cssVars = themeToCssVariables(createTheme());
+
+    expect(cssVars['--persona-composer-padding']).toBe('0.75rem 1rem');
+    expect(cssVars['--persona-composer-gap']).toBe('0.5rem');
+    expect(cssVars['--persona-composer-font-size']).toBe('0.875rem');
+    expect(cssVars['--persona-composer-line-height']).toBe('1.25rem');
+  });
+
+  it('maps composer spacing/type tokens to dedicated CSS variables', () => {
+    const theme = createTheme({
+      components: {
+        composer: {
+          padding: '1rem 1.25rem',
+          gap: '0.75rem',
+          fontSize: '1rem',
+          lineHeight: '1.5rem',
+        },
+      },
+    } as any);
+
+    const cssVars = themeToCssVariables(theme);
+
+    expect(cssVars['--persona-components-composer-padding']).toBe('1rem 1.25rem');
+    expect(cssVars['--persona-components-composer-gap']).toBe('0.75rem');
+    expect(cssVars['--persona-components-composer-fontSize']).toBe('1rem');
+    expect(cssVars['--persona-components-composer-lineHeight']).toBe('1.5rem');
+
+    expect(cssVars['--persona-composer-padding']).toBe('1rem 1.25rem');
+    expect(cssVars['--persona-composer-gap']).toBe('0.75rem');
+    expect(cssVars['--persona-composer-font-size']).toBe('1rem');
+    expect(cssVars['--persona-composer-line-height']).toBe('1.5rem');
+  });
+
   it('maps scroll-to-bottom component tokens to dedicated CSS variables', () => {
     const theme = createTheme({
       components: {
@@ -462,6 +581,51 @@ describe('theme utils', () => {
     expect(cssVars['--persona-intro-card-bg']).toBe('transparent');
   });
 
+  it('resolves semantic suggestion tokens for every variant and state', () => {
+    const theme = createTheme({
+      components: {
+        suggestion: {
+          chip: {
+            background: 'palette.colors.accent.50',
+            hoverBackground: 'palette.colors.accent.100',
+            focusRing: 'semantic.colors.interactive.focus',
+          },
+          card: {
+            borderRadius: 'palette.radius.lg',
+            shadow: 'palette.shadows.md',
+          },
+          list: {
+            minHeight: '48px',
+            disabledOpacity: '0.4',
+          },
+        },
+      },
+    });
+    const cssVars = themeToCssVariables(theme);
+
+    expect(cssVars['--persona-components-suggestion-chip-background']).toBe(
+      '#ecfeff'
+    );
+    expect(
+      cssVars['--persona-components-suggestion-chip-hoverBackground']
+    ).toBe('#cffafe');
+    expect(cssVars['--persona-components-suggestion-chip-focusRing']).toBe(
+      '#0f0f0f'
+    );
+    expect(
+      cssVars['--persona-components-suggestion-card-borderRadius']
+    ).toBe('0.5rem');
+    expect(cssVars['--persona-components-suggestion-card-shadow']).toContain(
+      '0 4px 6px'
+    );
+    expect(cssVars['--persona-components-suggestion-list-minHeight']).toBe(
+      '48px'
+    );
+    expect(
+      cssVars['--persona-components-suggestion-list-disabledOpacity']
+    ).toBe('0.4');
+  });
+
   it('drives --persona-tool-bubble-shadow from the theme token (config.toolCall.shadow is applied inline on the bubble, not the root var)', () => {
     const el = document.createElement('div');
     applyThemeVariables(el, {
@@ -495,4 +659,56 @@ describe('theme utils', () => {
     const cssVars = themeToCssVariables(theme);
     expect(cssVars['--persona-code-bg']).toBe('#fafafa');
   });
+
+  it('derives the shared scrollbar variables from components.scrollbar with border fallback', () => {
+    const defaults = themeToCssVariables(createTheme({} as any));
+    expect(defaults['--persona-scrollbar-thumb']).toBe(defaults['--persona-border']);
+    expect(defaults['--persona-scrollbar-track']).toBe('transparent');
+
+    const themed = themeToCssVariables(
+      createTheme({
+        components: { scrollbar: { thumb: '#00dfc1', track: '#111111' } },
+      } as any)
+    );
+    expect(themed['--persona-scrollbar-thumb']).toBe('#00dfc1');
+    expect(themed['--persona-scrollbar-track']).toBe('#111111');
+  });
+
+  it('exposes intro card border and composer border color tokens', () => {
+    const defaults = themeToCssVariables(createTheme({} as any));
+    expect(defaults['--persona-intro-card-border']).toBe('none');
+    expect(defaults['--persona-composer-border-color']).toBe(defaults['--persona-border']);
+
+    const themed = themeToCssVariables(
+      createTheme({
+        components: {
+          introCard: { border: '1px solid rgba(0, 0, 0, 0.1)' },
+          composer: { borderColor: 'rgba(29, 28, 23, 0.25)' },
+        },
+      } as any)
+    );
+    expect(themed['--persona-intro-card-border']).toBe('1px solid rgba(0, 0, 0, 0.1)');
+    expect(themed['--persona-composer-border-color']).toBe('rgba(29, 28, 23, 0.25)');
+  });
+
+  it('follows the palette radius for markdown code blocks so square themes get square code', () => {
+    const defaults = themeToCssVariables(createTheme({} as any));
+    expect(defaults['--persona-md-code-block-border-radius']).toBe('0.375rem');
+
+    const square = themeToCssVariables(
+      createTheme({
+        palette: {
+          radius: { sm: '0px', md: '0px', lg: '0px', xl: '0px', '2xl': '0px' },
+        },
+      } as any)
+    );
+    expect(square['--persona-md-code-block-border-radius']).toBe('0px');
+
+    const explicit = themeToCssVariables(
+      createTheme({
+        components: { markdown: { codeBlock: { borderRadius: '2px' } } },
+      } as any)
+    );
+    expect(explicit['--persona-md-code-block-border-radius']).toBe('2px');
+  });
 });

package/src/utils/tokens.ts

@@ -336,6 +336,63 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     padding: 'semantic.spacing.lg',
     shadow: 'palette.shadows.none',
   },
+  suggestion: {
+    chip: {
+      background: 'semantic.colors.surface',
+      foreground: 'semantic.colors.text',
+      border: 'semantic.colors.border',
+      borderRadius: 'palette.radius.full',
+      padding: '0.5rem 0.875rem',
+      gap: '0.5rem',
+      itemGap: '8px',
+      minHeight: '36px',
+      fontSize: '0.8125rem',
+      lineHeight: '1.25',
+      iconSize: '16px',
+      hoverBackground: 'palette.colors.gray.100',
+      hoverBorder: 'palette.colors.gray.300',
+      pressedBackground: 'palette.colors.gray.200',
+      focusRing: 'semantic.colors.interactive.focus',
+      disabledOpacity: '0.5',
+    },
+    card: {
+      background: 'semantic.colors.surface',
+      foreground: 'semantic.colors.text',
+      border: 'semantic.colors.border',
+      borderRadius: 'palette.radius.xl',
+      padding: '1rem',
+      shadow: 'palette.shadows.sm',
+      gap: '0.625rem',
+      itemGap: '8px',
+      minHeight: '72px',
+      fontSize: '0.875rem',
+      lineHeight: '1.35',
+      iconSize: '18px',
+      hoverBackground: 'palette.colors.gray.100',
+      hoverBorder: 'palette.colors.gray.300',
+      pressedBackground: 'palette.colors.gray.200',
+      focusRing: 'semantic.colors.interactive.focus',
+      disabledOpacity: '0.5',
+    },
+    list: {
+      background: 'transparent',
+      foreground: 'semantic.colors.text',
+      border: 'semantic.colors.border',
+      borderRadius: 'palette.radius.md',
+      padding: '0.75rem',
+      gap: '0.625rem',
+      itemGap: '8px',
+      minHeight: '44px',
+      fontSize: '0.875rem',
+      lineHeight: '1.35',
+      iconSize: '17px',
+      hoverBackground: 'palette.colors.gray.100',
+      hoverBorder: 'palette.colors.gray.300',
+      pressedBackground: 'palette.colors.gray.200',
+      focusRing: 'semantic.colors.interactive.focus',
+      disabledOpacity: '0.5',
+    },
+  },
   toolBubble: {
     shadow: 'palette.shadows.sm',
   },
@@ -345,6 +402,10 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
   composer: {
     shadow: 'palette.shadows.none',
   },
+  scrollbar: {
+    thumb: 'semantic.colors.border',
+    track: 'transparent',
+  },
   markdown: {
     inlineCode: {
       background: 'palette.colors.gray.50',
@@ -361,6 +422,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       background: 'semantic.colors.container',
       borderColor: 'semantic.colors.border',
       textColor: 'inherit',
+      borderRadius: 'palette.radius.md',
     },
     table: {
       headerBackground: 'semantic.colors.container',
@@ -797,10 +859,15 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-header-iconBackground'] ?? cssVars['--persona-primary'];
   cssVars['--persona-header-icon-fg'] =
     cssVars['--persona-components-header-iconForeground'] ?? cssVars['--persona-text-inverse'];
+  // `title.color` / `subtitle.color` supersede the legacy *Foreground tokens.
   cssVars['--persona-header-title-fg'] =
-    cssVars['--persona-components-header-titleForeground'] ?? cssVars['--persona-primary'];
+    cssVars['--persona-components-header-title-color'] ??
+    cssVars['--persona-components-header-titleForeground'] ??
+    cssVars['--persona-primary'];
   cssVars['--persona-header-subtitle-fg'] =
-    cssVars['--persona-components-header-subtitleForeground'] ?? cssVars['--persona-text-muted'];
+    cssVars['--persona-components-header-subtitle-color'] ??
+    cssVars['--persona-components-header-subtitleForeground'] ??
+    cssVars['--persona-text-muted'];
   cssVars['--persona-header-action-icon-fg'] =
     cssVars['--persona-components-header-actionIconForeground'] ?? cssVars['--persona-muted'];
 
@@ -816,10 +883,25 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-introCard-background'] ?? 'transparent';
   cssVars['--persona-intro-card-radius'] =
     cssVars['--persona-components-introCard-borderRadius'] ?? '1rem';
-  cssVars['--persona-intro-card-padding'] =
+  // Flat cards (transparent background, no shadow) drop the horizontal
+  // component of the stock padding so the welcome text shares the content
+  // column's left edge instead of carrying an invisible card inset. Compared
+  // by resolved value, not key presence: DEFAULT_COMPONENTS materializes the
+  // introCard tokens into every theme. A non-stock padding is emitted as-is;
+  // '1.5rem 1.5rem' forces the symmetric inset on a flat card.
+  const introBg = cssVars['--persona-components-introCard-background'];
+  const introShadow = cssVars['--persona-components-introCard-shadow'];
+  const introCardFlat =
+    (!introBg || introBg === 'transparent' || introBg === 'none') &&
+    (!introShadow || introShadow === 'none');
+  const introPadding =
     cssVars['--persona-components-introCard-padding'] ?? '1.5rem';
+  cssVars['--persona-intro-card-padding'] =
+    introCardFlat && introPadding === '1.5rem' ? '1.5rem 0' : introPadding;
   cssVars['--persona-intro-card-shadow'] =
     cssVars['--persona-components-introCard-shadow'] ?? 'none';
+  cssVars['--persona-intro-card-border'] =
+    cssVars['--persona-components-introCard-border'] ?? 'none';
 
   cssVars['--persona-input-background'] =
     cssVars['--persona-components-input-background'] ?? cssVars['--persona-surface'];
@@ -883,6 +965,28 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-reasoningBubble-shadow'] ?? '0 5px 15px rgba(15, 23, 42, 0.08)';
   cssVars['--persona-composer-shadow'] =
     cssVars['--persona-components-composer-shadow'] ?? 'none';
+  // Composer spacing/type. Fallbacks reproduce the utility classes the form
+  // used to carry (`px-4 py-3`, `gap-2`, `text-sm`) exactly.
+  cssVars['--persona-composer-padding'] =
+    cssVars['--persona-components-composer-padding'] ?? '0.75rem 1rem';
+  cssVars['--persona-composer-gap'] =
+    cssVars['--persona-components-composer-gap'] ?? '0.5rem';
+  cssVars['--persona-composer-font-size'] =
+    cssVars['--persona-components-composer-fontSize'] ?? '0.875rem';
+  cssVars['--persona-composer-line-height'] =
+    cssVars['--persona-components-composer-lineHeight'] ?? '1.25rem';
+  cssVars['--persona-composer-border-color'] =
+    cssVars['--persona-components-composer-borderColor'] ??
+    cssVars['--persona-border'] ??
+    '#e5e7eb';
+
+  // Scrollbars (every scroller in the widget consumes these two)
+  cssVars['--persona-scrollbar-thumb'] =
+    cssVars['--persona-components-scrollbar-thumb'] ??
+    cssVars['--persona-border'] ??
+    '#e5e7eb';
+  cssVars['--persona-scrollbar-track'] =
+    cssVars['--persona-components-scrollbar-track'] ?? 'transparent';
 
   cssVars['--persona-md-inline-code-bg'] =
     cssVars['--persona-components-markdown-inlineCode-background'] ?? cssVars['--persona-container'];
@@ -915,6 +1019,12 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-markdown-codeBlock-borderColor'] ?? cssVars['--persona-border'];
   cssVars['--persona-md-code-block-text-color'] =
     cssVars['--persona-components-markdown-codeBlock-textColor'] ?? 'inherit';
+  // Follows the palette radius so square-corner themes get square code blocks;
+  // the 0.375rem fallback matches palette.radius.md's default.
+  cssVars['--persona-md-code-block-border-radius'] =
+    cssVars['--persona-components-markdown-codeBlock-borderRadius'] ??
+    cssVars['--persona-radius-md'] ??
+    '0.375rem';
 
   // Markdown table
   cssVars['--persona-md-table-header-bg'] =

package/src/welcome.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_WIDGET_CONFIG, mergeWithDefaults } from "./defaults";
+import { mergeConfigUpdate } from "./utils/config-merge";
+import {
+  DEFAULT_WELCOME_SUBTITLE,
+  DEFAULT_WELCOME_TITLE,
+  isWelcomeVisible,
+  resolveWelcomeConfig,
+} from "./welcome";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "./types";
+
+const config = (partial: Partial<AgentWidgetConfig>): AgentWidgetConfig =>
+  partial as AgentWidgetConfig;
+
+const userMessage: AgentWidgetMessage = {
+  id: "u1",
+  role: "user",
+  content: "hi",
+  createdAt: "2026-08-01T00:00:00.000Z",
+  streaming: false,
+};
+
+const assistantMessage: AgentWidgetMessage = {
+  ...userMessage,
+  id: "a1",
+  role: "assistant",
+};
+
+describe("resolveWelcomeConfig", () => {
+  it("falls back to resolver-owned defaults", () => {
+    const resolved = resolveWelcomeConfig(config({}));
+    expect(resolved.title).toBe(DEFAULT_WELCOME_TITLE);
+    expect(resolved.subtitle).toBe(DEFAULT_WELCOME_SUBTITLE);
+    expect(resolved.variant).toBe("card");
+    expect(resolved.dismiss).toBe("never");
+    expect(resolved.message).toBeUndefined();
+    expect(resolved.icon).toBeUndefined();
+  });
+
+  it("prefers welcome.* over the legacy copy aliases, per field", () => {
+    const resolved = resolveWelcomeConfig(
+      config({
+        welcome: { title: "New title" },
+        copy: { welcomeTitle: "Legacy title", welcomeSubtitle: "Legacy subtitle" },
+      })
+    );
+    expect(resolved.title).toBe("New title");
+    expect(resolved.subtitle).toBe("Legacy subtitle");
+  });
+
+  it("uses the legacy aliases when welcome does not set the field", () => {
+    const resolved = resolveWelcomeConfig(
+      config({ copy: { welcomeTitle: "Legacy", welcomeSubtitle: "Scope" } })
+    );
+    expect(resolved.title).toBe("Legacy");
+    expect(resolved.subtitle).toBe("Scope");
+  });
+
+  it("honors an explicitly empty title or subtitle", () => {
+    const resolved = resolveWelcomeConfig(
+      config({ welcome: { title: "", subtitle: "" } })
+    );
+    expect(resolved.title).toBe("");
+    expect(resolved.subtitle).toBe("");
+  });
+
+  it("maps showWelcomeCard: false onto variant none", () => {
+    expect(
+      resolveWelcomeConfig(config({ copy: { showWelcomeCard: false } })).variant
+    ).toBe("none");
+    expect(
+      resolveWelcomeConfig(config({ copy: { showWelcomeCard: true } })).variant
+    ).toBe("card");
+  });
+
+  it("lets welcome.variant win over showWelcomeCard", () => {
+    expect(
+      resolveWelcomeConfig(
+        config({ welcome: { variant: "hero" }, copy: { showWelcomeCard: false } })
+      ).variant
+    ).toBe("hero");
+  });
+
+  it("forces on-first-message dismissal for hero and suppresses the greeting", () => {
+    const resolved = resolveWelcomeConfig(
+      config({
+        welcome: { variant: "hero", dismiss: "never", message: "Hi there" },
+      })
+    );
+    expect(resolved.dismiss).toBe("on-first-message");
+    expect(resolved.message).toBeUndefined();
+  });
+
+  it("keeps the greeting for card and none variants", () => {
+    expect(
+      resolveWelcomeConfig(config({ welcome: { message: "Hi there" } })).message
+    ).toBe("Hi there");
+    expect(
+      resolveWelcomeConfig(
+        config({ welcome: { variant: "none", message: "Hi there" } })
+      ).message
+    ).toBe("Hi there");
+  });
+
+  it("warns once in debug mode when a field is set through both namespaces", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const withBoth = config({
+      debug: true,
+      welcome: { title: "New" },
+      copy: { welcomeTitle: "Legacy" },
+    });
+    resolveWelcomeConfig(withBoth);
+    resolveWelcomeConfig(withBoth);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain("copy.welcomeTitle");
+    warn.mockRestore();
+  });
+
+  it("warns in debug mode when message is set with variant hero", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    resolveWelcomeConfig(
+      config({ debug: true, welcome: { variant: "hero", message: "Hi" } })
+    );
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain("welcome.message is ignored");
+    warn.mockRestore();
+  });
+
+  it("stays silent outside debug mode", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    resolveWelcomeConfig(
+      config({ welcome: { title: "New" }, copy: { welcomeTitle: "Legacy" } })
+    );
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe("welcome defaults are never materialized into config", () => {
+  it("keeps welcome copy out of DEFAULT_WIDGET_CONFIG", () => {
+    expect(DEFAULT_WIDGET_CONFIG.copy).not.toHaveProperty("welcomeTitle");
+    expect(DEFAULT_WIDGET_CONFIG.copy).not.toHaveProperty("welcomeSubtitle");
+    expect(DEFAULT_WIDGET_CONFIG).not.toHaveProperty("welcome");
+  });
+
+  it("keeps welcome copy out of a defaults-merged config", () => {
+    const merged = mergeWithDefaults({ apiUrl: "https://example.com" });
+    expect(merged.copy).not.toHaveProperty("welcomeTitle");
+    expect(merged.copy).not.toHaveProperty("welcomeSubtitle");
+    expect(merged.welcome).toBeUndefined();
+  });
+
+  it("resets to the resolver default on an explicit-undefined patch", () => {
+    const initial = mergeWithDefaults({
+      apiUrl: "https://example.com",
+      welcome: { title: "Set by host" },
+    }) as AgentWidgetConfig;
+    expect(resolveWelcomeConfig(initial).title).toBe("Set by host");
+
+    const cleared = mergeConfigUpdate(initial, {
+      welcome: { title: undefined },
+    });
+    expect(cleared.welcome).not.toHaveProperty("title");
+    expect(resolveWelcomeConfig(cleared).title).toBe(DEFAULT_WELCOME_TITLE);
+  });
+
+  it("falls back to the legacy alias after clearing the welcome field", () => {
+    const initial = mergeWithDefaults({
+      apiUrl: "https://example.com",
+      welcome: { title: "New" },
+      copy: { welcomeTitle: "Legacy" },
+    }) as AgentWidgetConfig;
+    const cleared = mergeConfigUpdate(initial, { welcome: { title: undefined } });
+    expect(resolveWelcomeConfig(cleared).title).toBe("Legacy");
+  });
+
+  it("replaces the icon wholesale instead of splicing union variants", () => {
+    const initial = mergeWithDefaults({
+      apiUrl: "https://example.com",
+      welcome: { icon: { type: "image", url: "/logo.png", alt: "Logo" } },
+    }) as AgentWidgetConfig;
+    const updated = mergeConfigUpdate(initial, {
+      welcome: { icon: { type: "lucide", name: "sparkles" } },
+    });
+    expect(updated.welcome?.icon).toEqual({ type: "lucide", name: "sparkles" });
+  });
+});
+
+describe("isWelcomeVisible", () => {
+  const card = resolveWelcomeConfig(config({}));
+  const hero = resolveWelcomeConfig(config({ welcome: { variant: "hero" } }));
+  const none = resolveWelcomeConfig(config({ welcome: { variant: "none" } }));
+
+  it("shows a never-dismissing card regardless of transcript content", () => {
+    expect(isWelcomeVisible(card, [])).toBe(true);
+    expect(isWelcomeVisible(card, [userMessage])).toBe(true);
+  });
+
+  it("hides an on-first-message surface once a user message exists", () => {
+    expect(isWelcomeVisible(hero, [])).toBe(true);
+    expect(isWelcomeVisible(hero, [assistantMessage])).toBe(true);
+    expect(isWelcomeVisible(hero, [userMessage, assistantMessage])).toBe(false);
+  });
+
+  it("never shows variant none", () => {
+    expect(isWelcomeVisible(none, [])).toBe(false);
+  });
+
+  it("treats a missing message list as empty", () => {
+    expect(isWelcomeVisible(hero, undefined)).toBe(true);
+  });
+});