@runtypelabs/persona 4.23.2 → 4.25.0

package/src/defaults-parity.test.ts

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+
+/**
+ * Locked 4.22.0 defaults contract. The fixture was captured before the v5
+ * defaults work began and must not be regenerated as part of later changes.
+ *
+ * JSDOM does not perform browser layout or resolve inherited custom
+ * properties. This test therefore records the DOM-facing computed declarations
+ * it can reliably expose, alongside the resolved config and emitted token map.
+ * The Playwright visual harness covers physical layout separately.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { mergeWithDefaults } from "./defaults";
+import { createAgentExperience } from "./ui";
+import { createTheme, themeToCssVariables } from "./utils/tokens";
+
+const fixturePath = resolve(process.cwd(), "src/__fixtures__/defaults-parity.v4.json");
+const stylesheetPath = resolve(process.cwd(), "src/styles/widget.css");
+
+const styles = (element: Element | null) => {
+  if (!element) throw new Error("Expected baseline element to be rendered");
+  const computed = getComputedStyle(element);
+  return Object.fromEntries(
+    ["display", "position", "background-color", "color", "border-radius", "padding", "margin", "font-size", "line-height", "box-shadow", "width", "height"].map(
+      (property) => [property, computed.getPropertyValue(property)]
+    )
+  );
+};
+
+const snapshot = (v5Defaults = false) => {
+  const stylesheet = document.createElement("style");
+  stylesheet.textContent = readFileSync(stylesheetPath, "utf8");
+  document.head.appendChild(stylesheet);
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { autoExpand: true },
+    persistState: false,
+    future: { v5Defaults },
+  });
+  controller.injectUserMessage({ content: "Baseline user message" });
+  controller.injectAssistantMessage({ content: "Baseline assistant message" });
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id: "baseline-tool",
+      role: "assistant",
+      content: "",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      sequence: 3,
+      streaming: false,
+      variant: "tool",
+      toolCall: { id: "baseline-tool", name: "baseline_tool", status: "complete", chunks: ["done"] },
+    },
+  });
+
+  const result = {
+    themeCssVariables: themeToCssVariables(createTheme(undefined, { future: { v5Defaults } })),
+    mergedDefaultConfig: mergeWithDefaults(),
+    computedStyles: {
+      header: styles(mount.querySelector(".persona-widget-header")),
+      userBubble: styles(mount.querySelector(".persona-message-row-user .persona-message-bubble")),
+      assistantBubble: styles(mount.querySelector(".persona-message-row-assistant .persona-message-bubble")),
+      composer: styles(mount.querySelector("[data-persona-composer-form]")),
+      launcher: styles(mount.querySelector(".persona-launcher-surface button")),
+      toolBubble: styles(mount.querySelector(".persona-tool-bubble")),
+    },
+  };
+  controller.destroy();
+  mount.remove();
+  stylesheet.remove();
+  return result;
+};
+
+afterEach(() => document.body.replaceChildren());
+
+type DefaultsSnapshot = ReturnType<typeof snapshot>;
+
+// JSDOM leaves some computed declarations as var(...) strings. Resolve a
+// whole-value reference against that snapshot's own emitted tokens before
+// comparing, so deleting an unreachable fallback is not a visual regression.
+// Unknown references stay verbatim; changes to actual tokens still fail the
+// independent, complete themeCssVariables comparison. The fixture stays intact.
+const resolveComputedTokens = (value: DefaultsSnapshot): DefaultsSnapshot => ({
+  ...value,
+  computedStyles: Object.fromEntries(
+    Object.entries(value.computedStyles).map(([name, declarations]) => [name,
+      Object.fromEntries(Object.entries(declarations).map(([property, declaration]) => {
+        const seen = new Set<string>();
+        let resolved = declaration;
+        while (!seen.has(resolved)) {
+          seen.add(resolved);
+          const reference = /^var\((--[\w-]+)(?:,[\s\S]*)?\)$/.exec(resolved);
+          const token = reference && value.themeCssVariables[reference[1]];
+          if (typeof token !== "string") break;
+          resolved = token;
+        }
+        return [property, resolved.replace(/([\d.]+)rem\b/g, (_, amount) => `${Number(amount) * 16}px`)];
+      })),
+    ])
+  ) as DefaultsSnapshot["computedStyles"],
+});
+
+describe("4.22.0 defaults parity (flag off)", () => {
+  it("matches the committed baseline", () => {
+    // JSON is deliberately the fixture format: it makes omitted/undefined
+    // config and token values deterministic across Node versions.
+    const actual = JSON.parse(JSON.stringify(snapshot(false)));
+    const baseline = JSON.parse(readFileSync(fixturePath, "utf8"));
+    // Phase 3 activates formerly unused tokens. Lock their old and new values
+    // explicitly instead of rewriting the historical fixture or ignoring keys.
+    const activatedTokens: Record<string, [string, string]> = {
+      "--persona-components-header-padding": ["1rem", "20px 24px"],
+      "--persona-components-panel-height": ["600px", "min(640px, max(200px, calc(100vh - 64px)))"],
+      "--persona-components-panel-maxHeight": ["calc(100vh - 80px)", "none"],
+      "--persona-components-panel-maxWidth": ["440px", "none"],
+    };
+    const addedTokens: Record<string, string> = {
+      "--persona-components-header-minimalPadding": "16px 24px",
+      "--persona-components-message-gap": "12px",
+      "--persona-cw-container": "#f9fafb",
+      "--persona-cw-surface": "#f9fafb",
+      "--persona-cw-border": "#e5e7eb",
+    };
+    for (const [mode, border, shadow, radius] of [
+      ["floating", "1px solid var(--persona-border)", baseline.themeCssVariables["--persona-components-panel-shadow"], "0.75rem"],
+      ["inline", "1px solid var(--persona-border)", "none", "0.75rem"],
+      ["docked", "none", "none", "0.75rem"],
+      ["sidebar", "none", undefined, "0"],
+      ["mobile", "none", "none", "0"],
+    ]) {
+      addedTokens[`--persona-components-panel-modes-${mode}-border`] = border!;
+      addedTokens[`--persona-components-panel-modes-${mode}-borderRadius`] = radius!;
+      if (shadow !== undefined) addedTokens[`--persona-components-panel-modes-${mode}-shadow`] = shadow;
+    }
+    // Resolve computed declarations before adapting the token map for comparison.
+    // The baseline stylesheet uses rem; this JSDOM harness assumes a 16px root.
+    const resolvedActual = resolveComputedTokens(actual);
+    const resolvedBaseline = resolveComputedTokens(baseline);
+    resolvedActual.themeCssVariables = { ...actual.themeCssVariables };
+    for (const [key, [oldValue, newValue]] of Object.entries(activatedTokens)) {
+      expect(baseline.themeCssVariables[key], key).toBe(oldValue);
+      expect(actual.themeCssVariables[key], key).toBe(newValue);
+      resolvedActual.themeCssVariables[key] = oldValue;
+    }
+    for (const [key, value] of Object.entries(addedTokens)) {
+      expect(baseline.themeCssVariables).not.toHaveProperty(key);
+      expect(actual.themeCssVariables[key], key).toBe(value);
+      delete resolvedActual.themeCssVariables[key];
+    }
+    expect(resolvedActual).toEqual(resolvedBaseline);
+  });
+});

package/src/defaults.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_WIDGET_CONFIG,
+  mergeWithDefaults,
+  resolveDefaults,
+  resolveDefaultsVersion,
+} from "./defaults";
+
+describe.each([false, true])("defaults resolver (v5Defaults: %s)", (v5Defaults) => {
+  const future = { v5Defaults };
+
+  it("selects the requested version and its documented defaults", () => {
+    expect(resolveDefaultsVersion({ future })).toBe(v5Defaults ? "v5" : "v4");
+    const defaults = resolveDefaults({ future });
+    if (!v5Defaults) expect(defaults).toEqual(DEFAULT_WIDGET_CONFIG);
+    expect(defaults.layout?.header?.showSubtitle).toBe(!v5Defaults);
+    expect(defaults.composer?.layout).toBe(v5Defaults ? "single-row" : undefined);
+    expect(defaults.launcher?.variant).toBe(v5Defaults ? "circle" : undefined);
+    expect(defaults.composer?.placement).toBe(v5Defaults ? "overlay" : undefined);
+    expect(defaults.launcher?.width).toBe(v5Defaults
+      ? "min(400px, calc(100vw - 24px))"
+      : "min(440px, calc(100vw - 24px))");
+  });
+
+  it("preserves explicit composer and header options above the version defaults", () => {
+    const result = mergeWithDefaults({
+      future, composer: { layout: "stacked", placement: "block" },
+      layout: { header: { showSubtitle: true } },
+    });
+    expect(result.composer?.layout).toBe("stacked");
+    expect(result.composer?.placement).toBe("block");
+    expect(result.layout?.header?.showSubtitle).toBe(true);
+    const partial = mergeWithDefaults({ future, composer: { placement: "overlay" } });
+    expect(partial.composer?.layout).toBe(v5Defaults ? "single-row" : undefined);
+  });
+
+  it("merges partial role sizing above the selected default width", () => {
+    const result = mergeWithDefaults({ future, layout: { messages: { assistant: { maxWidth: "65ch" } } } });
+    expect(result.layout?.messages?.assistant?.maxWidth).toBe("65ch");
+    expect(result.layout?.messages?.assistant?.width).toBe(v5Defaults ? "full" : undefined);
+    expect(result.layout?.messages?.user).toBeUndefined();
+  });
+
+  it("merges explicit options and nested theme overrides above the selected defaults", () => {
+    const config = {
+      future,
+      launcher: { headerIconSize: "31px", title: "Custom title" },
+      features: { reasoningDisplay: { expandable: false } },
+      theme: { components: { header: { padding: "7px", title: { fontSize: "19px" } } } },
+    };
+    const result = mergeWithDefaults(config);
+    expect(result.future).toEqual(future);
+    expect(result.launcher?.headerIconSize).toBe("31px");
+    expect(result.launcher?.title).toBe("Custom title");
+    expect(result.features?.reasoningDisplay).toEqual({
+      ...DEFAULT_WIDGET_CONFIG.features?.reasoningDisplay,
+      ...(v5Defaults ? { variant: "row", iconVisibility: "active", autoExpand: false, loadingAnimation: "shimmer" } : {}),
+      expandable: false,
+    });
+    expect(result.theme?.components?.header).toEqual(config.theme.components.header);
+    expect(resolveDefaults({ future }).launcher?.headerIconSize).toBe(v5Defaults ? "20px" : "40px");
+  });
+});
+
+it("keeps the legacy defaults when the opt-in is missing", () => {
+  expect(resolveDefaultsVersion()).toBe("v4");
+  expect(resolveDefaultsVersion({ future: {} })).toBe("v4");
+  expect(JSON.stringify(mergeWithDefaults())).toBe(JSON.stringify(DEFAULT_WIDGET_CONFIG));
+});

package/src/defaults.ts

@@ -1,6 +1,8 @@
 import type { AgentWidgetConfig, AgentWidgetLauncherConfig } from "./types";
 import type { DeepPartial, PersonaTheme } from "./types/theme";
 import { deepMerge } from "./utils/deep-merge";
+import { inheritDefaultProvenance } from "./utils/defaults-provenance";
+import { inheritPanelAliasProvenance } from "./utils/panel-config";
 import {
   DEFAULT_TOOLTIP_DELAY_MS,
   DEFAULT_TOOLTIP_SKIP_DELAY_MS,
@@ -16,12 +18,33 @@ export const DEFAULT_FLOATING_LAUNCHER_WIDTH = "min(440px, calc(100vw - 24px))";
 /** Max width cap paired with {@link DEFAULT_FLOATING_LAUNCHER_WIDTH} for theme defaults. */
 export const DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH = "440px";
 
+/** Canonical header avatar box size, shared by the initial render and updates. */
+export const DEFAULT_HEADER_ICON_SIZE = "40px";
+
 /**
  * Canonical composer placeholder. The low-level builders fall back to this so
  * they cannot drift from `DEFAULT_WIDGET_CONFIG.copy.inputPlaceholder`.
  */
 export const DEFAULT_INPUT_PLACEHOLDER = "How can I help...";
 
+/** Shared by config resolution and standalone transcript component builders. */
+export const DEFAULT_TOOL_CALL_DISPLAY = {
+  collapsedMode: "tool-call",
+  activePreview: false,
+  grouped: false,
+  groupedMode: "stack",
+  previewMaxLines: 3,
+  expandable: true,
+  loadingAnimation: "none",
+} satisfies NonNullable<NonNullable<AgentWidgetConfig["features"]>["toolCallDisplay"]>;
+
+export const DEFAULT_REASONING_DISPLAY = {
+  activePreview: false,
+  previewMaxLines: 3,
+  expandable: true,
+  loadingAnimation: "none",
+} satisfies NonNullable<NonNullable<AgentWidgetConfig["features"]>["reasoningDisplay"]>;
+
 export const DEFAULT_LAUNCHER_CONFIG: AgentWidgetLauncherConfig = {
   enabled: true,
   mountMode: "floating",
@@ -40,7 +63,7 @@ export const DEFAULT_LAUNCHER_CONFIG: AgentWidgetLauncherConfig = {
   autoExpand: false,
   callToActionIconHidden: false,
   agentIconSize: "40px",
-  headerIconSize: "40px",
+  headerIconSize: DEFAULT_HEADER_ICON_SIZE,
   // closeButtonSize / clearChat.size omitted so theme.components.header.controlSize
   // sizes the header controls; setting either here would pin them past the token.
   // Zero out browser-default <button> padding so the icon gets the full
@@ -78,7 +101,7 @@ export const DEFAULT_LAUNCHER_CONFIG: AgentWidgetLauncherConfig = {
  * Default widget configuration
  * Single source of truth for all default values
  */
-export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
+export const DEFAULTS_BASE: Partial<AgentWidgetConfig> = {
   apiUrl: "https://api.runtype.com/api/chat/dispatch",
   // Client token mode defaults (optional, only used when clientToken is set)
   clientToken: undefined,
@@ -155,21 +178,8 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       // default so the default UX keeps the affordance.)
       showActivityWhilePinned: true,
     },
-    toolCallDisplay: {
-      collapsedMode: "tool-call",
-      activePreview: false,
-      grouped: false,
-      groupedMode: "stack",
-      previewMaxLines: 3,
-      expandable: true,
-      loadingAnimation: "none",
-    },
-    reasoningDisplay: {
-      activePreview: false,
-      previewMaxLines: 3,
-      expandable: true,
-      loadingAnimation: "none",
-    },
+    toolCallDisplay: DEFAULT_TOOL_CALL_DISPLAY,
+    reasoningDisplay: DEFAULT_REASONING_DISPLAY,
     streamAnimation: {
       type: "none",
       placeholder: "none",
@@ -246,6 +256,49 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   debug: false,
 };
 
+/** Version-specific defaults, selected by the staged V5 opt-in. */
+export const DEFAULTS_V4: Partial<AgentWidgetConfig> = {};
+export const DEFAULT_LAUNCHER_V5: Partial<AgentWidgetLauncherConfig> = {
+  variant: "circle",
+  width: "min(400px, calc(100vw - 24px))",
+  headerIconSize: "20px",
+};
+export const DEFAULTS_V5: Partial<AgentWidgetConfig> = {
+  launcher: DEFAULT_LAUNCHER_V5,
+  features: {
+    toolCallDisplay: { variant: "row", iconVisibility: "active", autoExpand: false, grouped: true, groupedMode: "collapsible", loadingAnimation: "shimmer" },
+    reasoningDisplay: { variant: "row", iconVisibility: "active", autoExpand: false, loadingAnimation: "shimmer" },
+  },
+  composer: { layout: "single-row", placement: "overlay" },
+  sendButton: { iconName: "arrow-up" },
+  statusIndicator: { mode: "transient" },
+  layout: {
+    contentMaxWidth: "768px",
+    topFade: true,
+    header: { showSubtitle: false },
+    messages: { assistant: { width: "full" } },
+  },
+};
+
+export type DefaultsVersion = "v4" | "v5";
+
+/** Shared by config, token, theme, and editor resolution. Only true opts in. */
+export function resolveDefaultsVersion(
+  config?: Pick<AgentWidgetConfig, "future">
+): DefaultsVersion {
+  return config?.future?.v5Defaults === true ? "v5" : "v4";
+}
+
+export function resolveDefaults(
+  config?: Pick<AgentWidgetConfig, "future">
+): Partial<AgentWidgetConfig> {
+  const overlay = resolveDefaultsVersion(config) === "v5" ? DEFAULTS_V5 : DEFAULTS_V4;
+  return deepMerge(DEFAULTS_BASE, overlay) as Partial<AgentWidgetConfig>;
+}
+
+/** Backward-compatible export of the legacy widget defaults. */
+export const DEFAULT_WIDGET_CONFIG = resolveDefaults();
+
 function mergeThemePartials(
   base: DeepPartial<PersonaTheme> | undefined,
   override: DeepPartial<PersonaTheme> | undefined
@@ -266,57 +319,62 @@ function mergeThemePartials(
 export function mergeWithDefaults(
   config?: Partial<AgentWidgetConfig>
 ): Partial<AgentWidgetConfig> {
-  if (!config) return DEFAULT_WIDGET_CONFIG;
+  const defaults = resolveDefaults(config);
+  if (!config) return inheritDefaultProvenance(inheritPanelAliasProvenance(defaults), undefined, DEFAULTS_V5);
 
-  return {
-    ...DEFAULT_WIDGET_CONFIG,
+  return inheritDefaultProvenance(inheritPanelAliasProvenance({
+    ...defaults,
     ...config,
-    theme: mergeThemePartials(DEFAULT_WIDGET_CONFIG.theme, config.theme),
-    darkTheme: mergeThemePartials(DEFAULT_WIDGET_CONFIG.darkTheme, config.darkTheme),
+    theme: mergeThemePartials(defaults.theme, config.theme),
+    darkTheme: mergeThemePartials(defaults.darkTheme, config.darkTheme),
     launcher: {
-      ...DEFAULT_WIDGET_CONFIG.launcher,
+      ...defaults.launcher,
       ...config.launcher,
       dock: {
-        ...DEFAULT_WIDGET_CONFIG.launcher?.dock,
+        ...defaults.launcher?.dock,
         ...config.launcher?.dock,
       },
       clearChat: {
-        ...DEFAULT_WIDGET_CONFIG.launcher?.clearChat,
+        ...defaults.launcher?.clearChat,
         ...config.launcher?.clearChat,
       },
     },
+    ...((defaults.composer || config.composer) ? { composer: {
+      ...defaults.composer,
+      ...config.composer,
+    } } : {}),
     tooltip: {
-      ...DEFAULT_WIDGET_CONFIG.tooltip,
+      ...defaults.tooltip,
       ...config.tooltip,
     },
     copy: {
-      ...DEFAULT_WIDGET_CONFIG.copy,
+      ...defaults.copy,
       ...config.copy,
     },
     sendButton: {
-      ...DEFAULT_WIDGET_CONFIG.sendButton,
+      ...defaults.sendButton,
       ...config.sendButton,
     },
     statusIndicator: {
-      ...DEFAULT_WIDGET_CONFIG.statusIndicator,
+      ...defaults.statusIndicator,
       ...config.statusIndicator,
     },
     voiceRecognition: {
-      ...DEFAULT_WIDGET_CONFIG.voiceRecognition,
+      ...defaults.voiceRecognition,
       ...config.voiceRecognition,
     },
     features: (() => {
-      const da = DEFAULT_WIDGET_CONFIG.features?.artifacts;
+      const da = defaults.features?.artifacts;
       const ca = config.features?.artifacts;
-      const dsb = DEFAULT_WIDGET_CONFIG.features?.scrollToBottom;
+      const dsb = defaults.features?.scrollToBottom;
       const csb = config.features?.scrollToBottom;
-      const dsc = DEFAULT_WIDGET_CONFIG.features?.scrollBehavior;
+      const dsc = defaults.features?.scrollBehavior;
       const csc = config.features?.scrollBehavior;
-      const dsa = DEFAULT_WIDGET_CONFIG.features?.streamAnimation;
+      const dsa = defaults.features?.streamAnimation;
       const csa = config.features?.streamAnimation;
-      const dau = DEFAULT_WIDGET_CONFIG.features?.askUserQuestion;
+      const dau = defaults.features?.askUserQuestion;
       const cau = config.features?.askUserQuestion;
-      const dh = DEFAULT_WIDGET_CONFIG.features?.history;
+      const dh = defaults.features?.history;
       const ch = config.features?.history;
       const mergedArtifacts =
         da === undefined && ca === undefined
@@ -373,8 +431,16 @@ export function mergeWithDefaults(
               },
             };
       return {
-        ...DEFAULT_WIDGET_CONFIG.features,
+        ...defaults.features,
         ...config.features,
+        toolCallDisplay: {
+          ...defaults.features?.toolCallDisplay,
+          ...config.features?.toolCallDisplay,
+        },
+        reasoningDisplay: {
+          ...defaults.features?.reasoningDisplay,
+          ...config.features?.reasoningDisplay,
+        },
         ...(mergedScrollToBottom !== undefined ? { scrollToBottom: mergedScrollToBottom } : {}),
         ...(mergedScrollBehavior !== undefined ? { scrollBehavior: mergedScrollBehavior } : {}),
         ...(mergedArtifacts !== undefined ? { artifacts: mergedArtifacts } : {}),
@@ -383,46 +449,59 @@ export function mergeWithDefaults(
         ...(mergedHistory !== undefined ? { history: mergedHistory } : {}),
       };
     })(),
-    suggestionChips: config.suggestionChips ?? DEFAULT_WIDGET_CONFIG.suggestionChips,
+    suggestionChips: config.suggestionChips ?? defaults.suggestionChips,
     suggestionChipsConfig: {
-      ...DEFAULT_WIDGET_CONFIG.suggestionChipsConfig,
+      ...defaults.suggestionChipsConfig,
       ...config.suggestionChipsConfig,
     },
     layout: {
-      ...DEFAULT_WIDGET_CONFIG.layout,
+      ...defaults.layout,
       ...config.layout,
       header: {
-        ...DEFAULT_WIDGET_CONFIG.layout?.header,
+        ...defaults.layout?.header,
         ...config.layout?.header,
       },
       messages: {
-        ...DEFAULT_WIDGET_CONFIG.layout?.messages,
+        ...defaults.layout?.messages,
         ...config.layout?.messages,
+        ...((defaults.layout?.messages?.user || config.layout?.messages?.user) ? {
+          user: {
+            ...defaults.layout?.messages?.user,
+            ...config.layout?.messages?.user,
+          },
+        } : {}),
+        ...((defaults.layout?.messages?.assistant || config.layout?.messages?.assistant) ? {
+          assistant: {
+            ...defaults.layout?.messages?.assistant,
+            ...config.layout?.messages?.assistant,
+          },
+        } : {}),
         avatar: {
-          ...DEFAULT_WIDGET_CONFIG.layout?.messages?.avatar,
+          ...defaults.layout?.messages?.avatar,
           ...config.layout?.messages?.avatar,
         },
         timestamp: {
-          ...DEFAULT_WIDGET_CONFIG.layout?.messages?.timestamp,
+          ...defaults.layout?.messages?.timestamp,
           ...config.layout?.messages?.timestamp,
         },
       },
       slots: {
-        ...DEFAULT_WIDGET_CONFIG.layout?.slots,
+        ...defaults.layout?.slots,
         ...config.layout?.slots,
       },
     },
     markdown: {
-      ...DEFAULT_WIDGET_CONFIG.markdown,
+      ...defaults.markdown,
       ...config.markdown,
       options: {
-        ...DEFAULT_WIDGET_CONFIG.markdown?.options,
+        ...defaults.markdown?.options,
         ...config.markdown?.options,
       },
     },
     messageActions: {
-      ...DEFAULT_WIDGET_CONFIG.messageActions,
+      ...defaults.messageActions,
       ...config.messageActions,
     },
-  };
+  }, config), config, DEFAULTS_V5);
+
 }

package/src/generated/runtype-openapi-contract.ts

@@ -619,7 +619,7 @@ export type RuntypeClientInitResponse = {
   conversationRevision: string;
   durableRecovery?: {
   enabled: boolean;
-  join?: boolean;
+  steer?: boolean;
 };
   expiresAt: string;
   flow?: {
@@ -681,7 +681,7 @@ export type RuntypeClientChatRequest = {
 }>;
   metadata?: Record<string, unknown>;
   sessionId: string;
-  submitMode?: "normal" | "interrupt" | "join";
+  submitMode?: "normal" | "interrupt" | "steer";
   turnId?: string;
 };
 

package/src/index-core.ts

@@ -9,6 +9,10 @@ export type {
   AgentWidgetStorageAdapter,
   AgentWidgetStoredState,
   AgentWidgetConfigPatch,
+  AgentWidgetSessionInitTrigger,
+  AgentWidgetSessionInitHook,
+  AgentWidgetVoicePrewarmTrigger,
+  AgentWidgetVoicePrewarmHook,
   TargetResolver,
   ResolvedTarget,
   AgentWidgetFeatureFlags,

package/src/install.test.ts

@@ -226,6 +226,30 @@ describe("install.ts: deferred launcher path", () => {
 
     expect(initAgentWidget).toHaveBeenCalledTimes(1);
   });
+
+  it.each([false, true])("passes future.v5Defaults=%s through the deferred launcher handoff", async (v5Defaults) => {
+    markCssLoaded();
+    provideFullBundle();
+    provideLauncherBundle();
+
+    const variant = v5Defaults ? "pill" : "circle";
+    await install({
+      config: { apiUrl: "/api", launcher: { variant } },
+      future: { v5Defaults },
+    });
+    await flush();
+
+    expect(launcherMount).toHaveBeenCalledWith(expect.objectContaining({
+      config: expect.objectContaining({ future: { v5Defaults }, launcher: expect.objectContaining({ variant }) }),
+    }));
+
+    capturedOnOpen!();
+    await flush();
+
+    expect(initAgentWidget).toHaveBeenCalledWith(expect.objectContaining({
+      config: expect.objectContaining({ future: { v5Defaults }, launcher: expect.objectContaining({ variant }) }),
+    }));
+  });
 });
 
 describe("install.ts: eager path", () => {

package/src/install.ts

@@ -19,6 +19,8 @@ interface SiteAgentInstallConfig {
   jsUrl?: string;
   target?: string | HTMLElement;
   config?: any;
+  /** Opt in to the staged v5 defaults when using top-level installer options. */
+  future?: { v5Defaults?: boolean };
   autoInit?: boolean;
   // Client token mode options (can also be set via data attributes)
   clientToken?: string;
@@ -447,6 +449,7 @@ declare global {
     if (config.clientToken && !widgetConfig.clientToken) widgetConfig.clientToken = config.clientToken;
     if (config.flowId && !widgetConfig.flowId) widgetConfig.flowId = config.flowId;
     if (config.agentId && !widgetConfig.agentId) widgetConfig.agentId = config.agentId;
+    if (config.future && !widgetConfig.future) widgetConfig.future = config.future;
 
     const hasApiConfig = !!(widgetConfig.apiUrl || widgetConfig.clientToken);
     return { target, widgetConfig, hasApiConfig };
@@ -631,4 +634,3 @@ declare global {
   // This prevents Next.js/Nuxt/etc. from removing dynamically added CSS
   waitForHydration(install);
 })();
-

package/src/launcher-global.ts

@@ -22,7 +22,7 @@
  */
 import { createLauncherSurface } from "./components/launcher";
 import { applyThemeVariables } from "./utils/theme";
-import { DEFAULT_LAUNCHER_CONFIG } from "./defaults";
+import { DEFAULT_LAUNCHER_CONFIG, DEFAULT_LAUNCHER_V5 } from "./defaults";
 import { setIconsExtraLoader } from "./icons-extra-loader";
 import type { AgentWidgetConfig } from "./types";
 
@@ -94,6 +94,7 @@ const mergeCriticalLauncherConfig = (
   ...config,
   launcher: {
     ...DEFAULT_LAUNCHER_CONFIG,
+    ...(config?.future?.v5Defaults === true ? DEFAULT_LAUNCHER_V5 : {}),
     ...config?.launcher,
     dock: {
       ...DEFAULT_LAUNCHER_CONFIG.dock,