@runtypelabs/persona 4.23.2 → 4.25.0

package/src/utils/code-generators.ts

@@ -588,6 +588,13 @@ function appendSerializableObjectBlock(
   lines.push(`${indent}},`);
 }
 
+/** Preserve an explicitly authored defaults-version opt-in in every snippet. */
+function appendFutureDefaultsConfig(lines: string[], config: any, indent: string): void {
+  if (config.future?.v5Defaults !== undefined) {
+    lines.push(`${indent}future: { v5Defaults: ${config.future.v5Defaults === true} },`);
+  }
+}
+
 /**
  * Resolve the mount-target selector for a single-quoted JS string context.
  * Defaults to `body` and escapes backslashes / single quotes so an arbitrary
@@ -647,6 +654,7 @@ function generateESMCode(config: any, options?: CodeGeneratorOptions): string {
   if (config.target) lines.push(`    target: "${config.target}",`);
   if (config.flowId) lines.push(`    flowId: "${config.flowId}",`);
   if (shouldEmitParserType) lines.push(`    parserType: "${parserType}",`);
+  appendFutureDefaultsConfig(lines, config, "    ");
 
   if (config.theme && typeof config.theme === "object" && Object.keys(config.theme).length > 0) {
     appendSerializableObjectBlock(lines, "theme", config.theme as Record<string, unknown>, "    ");
@@ -797,6 +805,7 @@ function generateReactComponentCode(config: any, options?: CodeGeneratorOptions)
   if (config.target) lines.push(`        target: "${config.target}",`);
   if (config.flowId) lines.push(`        flowId: "${config.flowId}",`);
   if (shouldEmitParserType) lines.push(`        parserType: "${parserType}",`);
+  appendFutureDefaultsConfig(lines, config, "        ");
 
   if (config.theme && typeof config.theme === "object" && Object.keys(config.theme).length > 0) {
     appendSerializableObjectBlock(lines, "theme", config.theme as Record<string, unknown>, "        ");
@@ -1064,6 +1073,7 @@ function generateReactAdvancedCode(config: any, options?: CodeGeneratorOptions):
   if (config.agentId) lines.push(`        agentId: "${config.agentId}",`);
   if (config.target) lines.push(`        target: "${config.target}",`);
   if (config.flowId) lines.push(`        flowId: "${config.flowId}",`);
+  appendFutureDefaultsConfig(lines, config, "        ");
 
   if (config.theme && typeof config.theme === "object" && Object.keys(config.theme).length > 0) {
     appendSerializableObjectBlock(lines, "theme", config.theme as Record<string, unknown>, "        ");
@@ -1324,6 +1334,9 @@ function buildSerializableConfig(config: any): Record<string, any> {
   if (config.target) serializableConfig.target = config.target;
   if (config.flowId) serializableConfig.flowId = config.flowId;
   if (shouldEmitParserType) serializableConfig.parserType = parserType;
+  if (config.future?.v5Defaults !== undefined) {
+    serializableConfig.future = { v5Defaults: config.future.v5Defaults === true };
+  }
   if (config.theme) serializableConfig.theme = config.theme;
   if (config.launcher) serializableConfig.launcher = config.launcher;
   if (config.copy) serializableConfig.copy = config.copy;
@@ -1477,6 +1490,7 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
   if (config.target) lines.push(`      target: "${config.target}",`);
   if (config.flowId) lines.push(`      flowId: "${config.flowId}",`);
   if (shouldEmitParserType) lines.push(`      parserType: "${parserType}",`);
+  appendFutureDefaultsConfig(lines, config, "      ");
 
   if (config.theme && typeof config.theme === "object" && Object.keys(config.theme).length > 0) {
     appendSerializableObjectBlock(lines, "theme", config.theme as Record<string, unknown>, "      ");

package/src/utils/composer-compact.test.ts

@@ -13,7 +13,6 @@ const base: ComposerCompactInput = {
   hasChips: false,
   hasQuote: false,
   hasPendingSubmission: false,
-  dictationActive: false,
 };
 
 describe("isComposerCompact", () => {
@@ -38,7 +37,6 @@ describe("isComposerCompact", () => {
     ["hasChips"],
     ["hasQuote"],
     ["hasPendingSubmission"],
-    ["dictationActive"],
   ] as const)("%s expands an otherwise empty composer", (key) => {
     expect(isComposerCompact({ ...base, [key]: true })).toBe(false);
   });

package/src/utils/composer-compact.ts

@@ -18,13 +18,12 @@ export type ComposerCompactInput = {
   hasChips: boolean;
   hasQuote: boolean;
   hasPendingSubmission: boolean;
-  dictationActive: boolean;
 };
 
 /**
  * Compact when the draft is empty or a single line and nothing else occupies
  * the composer. Text alone is not enough: any chip, attachment, quote, pending
- * submission, or live dictation expands it.
+ * submission expands it. Recording state alone does not affect layout.
  */
 export function isComposerCompact(input: ComposerCompactInput): boolean {
   if (input.wrapped) return false;
@@ -33,8 +32,7 @@ export function isComposerCompact(input: ComposerCompactInput): boolean {
     input.hasAttachments ||
     input.hasChips ||
     input.hasQuote ||
-    input.hasPendingSubmission ||
-    input.dictationActive
+    input.hasPendingSubmission
   );
 }
 

package/src/utils/composer-placement.ts

@@ -4,9 +4,8 @@ export const DEFAULT_ANCHOR_COMPOSER_TOP = "44%";
 export const DEFAULT_COMPOSER_GAP = "24px";
 
 /**
- * Resolver-owned default, not `defaults.ts`: `mergeWithDefaults` materializes
- * anything declared there (see `welcome.ts` header). Composer-bar mode owns
- * its own geometry and always resolves `"block"`.
+ * V4 falls back to block; mergeWithDefaults supplies V5 overlay placement.
+ * Composer-bar mode owns its own geometry and always resolves `"block"`.
  */
 export const resolveComposerPlacement = (
   config: AgentWidgetConfig | undefined,

package/src/utils/config-merge.test.ts

@@ -1,14 +1,49 @@
 import { describe, expect, it, vi } from "vitest";
 
 import { mergeConfigUpdate } from "./config-merge";
-import { mergeWithDefaults } from "../defaults";
+import { DEFAULT_FLOATING_LAUNCHER_WIDTH, mergeWithDefaults } from "../defaults";
+import { getPanelAliasProvenance } from "./panel-config";
 import type { AgentWidgetConfig, StreamAnimationPlugin } from "../types";
 
-// Stored controller config is post-mergeWithDefaults; simulate that here.
-const base = (overrides: Partial<AgentWidgetConfig> = {}): AgentWidgetConfig =>
-  mergeWithDefaults({ apiUrl: "https://api.example.com/chat", ...overrides }) as AgentWidgetConfig;
+describe.each([false, true])("mergeConfigUpdate (v5=%s)", (v5Defaults) => {
+  // Stored controller config is post-mergeWithDefaults.
+  const base = (overrides: Partial<AgentWidgetConfig> = {}): AgentWidgetConfig =>
+    mergeWithDefaults({ apiUrl: "https://api.example.com/chat", future: { v5Defaults }, ...overrides }) as AgentWidgetConfig;
+
+  it("retains and clears legacy panel-alias provenance across live patches", () => {
+    const initial = base({ launcher: { width: "600px", dock: { width: "520px" } } });
+    expect(getPanelAliasProvenance(initial)).toMatchObject({ launcherWidth: true, dockWidth: true });
+
+    const retained = mergeConfigUpdate(initial, { launcher: { title: "Updated" } });
+    expect(getPanelAliasProvenance(retained)).toMatchObject({ launcherWidth: true, dockWidth: true });
+
+    const cleared = mergeConfigUpdate(retained, { launcher: { width: undefined, dock: { width: undefined } } });
+    expect(getPanelAliasProvenance(cleared)).toMatchObject({ launcherWidth: false, dockWidth: false });
+
+    const parentCleared = mergeConfigUpdate(initial, { launcher: undefined });
+    expect(getPanelAliasProvenance(parentCleared)).toMatchObject({ launcherWidth: false, dockWidth: false });
+
+    const dockParentCleared = mergeConfigUpdate(initial, { launcher: { dock: undefined } });
+    expect(getPanelAliasProvenance(dockParentCleared)).toMatchObject({ launcherWidth: true, dockWidth: false });
+  });
+
+  it("does not treat an explicit undefined width as a legacy alias", () => {
+    const config = mergeWithDefaults({
+      future: { v5Defaults },
+      launcherWidth: "600px",
+      launcher: { width: undefined },
+    }) as AgentWidgetConfig;
+    expect(getPanelAliasProvenance(config)).toMatchObject({
+      launcherWidth: false,
+      legacyLauncherWidth: true,
+    });
+  });
+
+  it("keeps an explicit legacy width even when it equals the materialized default", () => {
+    const config = base({ launcher: { width: DEFAULT_FLOATING_LAUNCHER_WIDTH } });
+    expect(getPanelAliasProvenance(config).launcherWidth).toBe(true);
+  });
 
-describe("mergeConfigUpdate", () => {
   it("recursively merges nested plain objects, preserving sibling overrides", () => {
     const prev = base({ launcher: { enabled: false, clearChat: { backgroundColor: "#123456" } } });
     const next = mergeConfigUpdate(prev, { launcher: { title: "After" } });
@@ -304,3 +339,44 @@ describe("mergeConfigUpdate", () => {
     expect(again).toEqual(merged);
   });
 });
+
+
+describe("live defaults version changes", () => {
+  const base = (config: Partial<AgentWidgetConfig> = {}) =>
+    mergeWithDefaults({ apiUrl: "/api", ...config }) as AgentWidgetConfig;
+
+  it("moves inherited defaults in both directions and resets a cleared future flag", () => {
+    const v5 = mergeConfigUpdate(base(), { future: { v5Defaults: true } });
+    expect(v5.launcher?.headerIconSize).toBe("20px");
+    expect(v5.layout?.header?.showSubtitle).toBe(false);
+    expect(v5.composer?.layout).toBe("single-row");
+    expect(v5.statusIndicator?.mode).toBe("transient");
+    const v4 = mergeConfigUpdate(v5, { future: undefined });
+    expect(v4.launcher?.headerIconSize).toBe("40px");
+    expect(v4.layout?.header?.showSubtitle).toBe(true);
+    expect(v4.composer?.layout).toBeUndefined();
+    expect(v4.statusIndicator?.mode).toBeUndefined();
+    const v5Again = mergeConfigUpdate(v4, { future: { v5Defaults: true } });
+    expect(v5Again.layout?.messages?.assistant?.width).toBe("full");
+    expect(v5Again.composer?.layout).toBe("single-row");
+  });
+
+  it("retains host choices even when they equal a previous version default", () => {
+    const initial = base({ launcher: { headerIconSize: "40px" }, layout: { header: { showSubtitle: true } } });
+    const v5 = mergeConfigUpdate(initial, { future: { v5Defaults: true } });
+    expect(v5.launcher?.headerIconSize).toBe("40px");
+    expect(v5.layout?.header?.showSubtitle).toBe(true);
+    const reset = mergeConfigUpdate(v5, { launcher: { headerIconSize: undefined }, layout: { header: undefined } });
+    expect(reset.launcher?.headerIconSize).toBe("20px");
+    expect(reset.layout?.header?.showSubtitle).toBe(false);
+    expect(initial.launcher?.headerIconSize).toBe("40px");
+  });
+
+  it("preserves live overrides and normal config spreads across version changes", () => {
+    const edited = mergeConfigUpdate(base(), { composer: { layout: "stacked" }, statusIndicator: { mode: "always" } });
+    const v5 = mergeConfigUpdate({ ...edited }, { future: { v5Defaults: true } });
+    expect(v5.composer?.layout).toBe("stacked");
+    expect(v5.statusIndicator?.mode).toBe("always");
+    expect(v5.launcher?.headerIconSize).toBe("20px");
+  });
+});

package/src/utils/config-merge.ts

@@ -1,5 +1,8 @@
-import { mergeWithDefaults } from "../defaults";
+import { DEFAULTS_V5, mergeWithDefaults } from "../defaults";
 import type { AgentWidgetConfig, AgentWidgetConfigPatch } from "../types";
+import { setPanelAliasProvenance, updatePanelAliasProvenance } from "./panel-config";
+
+import { omitInheritedDefaults, setDefaultProvenance, updateDefaultProvenance, versionedDefaultPaths } from "./defaults-provenance";
 
 // Same predicate as utils/deep-merge.ts: plain object, non-null, non-array.
 // Class instances and DOM nodes also pass here, so replace-leaf paths guard the
@@ -63,6 +66,13 @@ export function mergeConfigUpdate(
   previousConfig: AgentWidgetConfig,
   patch: AgentWidgetConfigPatch
 ): AgentWidgetConfig {
-  const merged = mergePatch(previousConfig, patch, "") as Partial<AgentWidgetConfig>;
-  return mergeWithDefaults(merged) as AgentWidgetConfig;
+  const paths = versionedDefaultPaths(DEFAULTS_V5);
+  const explicit = updateDefaultProvenance(previousConfig, patch, paths);
+  const merged = setDefaultProvenance(omitInheritedDefaults(
+    mergePatch(previousConfig, patch, "") as Partial<AgentWidgetConfig>, paths, explicit
+  ), explicit);
+  return setPanelAliasProvenance(
+    mergeWithDefaults(merged) as AgentWidgetConfig,
+    updatePanelAliasProvenance(previousConfig, patch)
+  );
 }

package/src/utils/defaults-provenance.ts

@@ -0,0 +1,67 @@
+/** Tracks host intent for versioned defaults without comparing values to defaults. */
+const DEFAULTS_PROVENANCE = Symbol("persona.defaultsProvenance");
+type Provenance = { [DEFAULTS_PROVENANCE]?: readonly string[] };
+const record = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export function versionedDefaultPaths(overlay: object, prefix = ""): string[] {
+  return Object.entries(overlay).flatMap(([key, value]) => {
+    const path = prefix ? `${prefix}.${key}` : key;
+    return record(value) ? versionedDefaultPaths(value, path) : [path];
+  });
+}
+
+function suppliedPath(value: unknown, path: string): "absent" | "clear" | "explicit" {
+  for (const key of path.split(".")) {
+    if (!record(value) || !Object.prototype.hasOwnProperty.call(value, key)) return "absent";
+    value = value[key];
+    if (value === undefined) return "clear";
+  }
+  return "explicit";
+}
+
+export function defaultProvenance(config: object | undefined, paths: readonly string[]): readonly string[] {
+  return (config as Provenance | undefined)?.[DEFAULTS_PROVENANCE]
+    ?? paths.filter((path) => suppliedPath(config, path) === "explicit");
+}
+
+export function setDefaultProvenance<T extends object>(config: T, explicit: readonly string[]): T {
+  Object.defineProperty(config, DEFAULTS_PROVENANCE, {
+    value: explicit, enumerable: true, configurable: true,
+  });
+  return config;
+}
+
+export function inheritDefaultProvenance<T extends object>(result: T, raw: object | undefined, overlay: object): T {
+  return setDefaultProvenance(result, defaultProvenance(raw, versionedDefaultPaths(overlay)));
+}
+
+export function updateDefaultProvenance(previous: object, patch: object, paths: readonly string[]): readonly string[] {
+  const marked = (patch as Provenance)[DEFAULTS_PROVENANCE];
+  if (marked) return marked;
+  const explicit = new Set(defaultProvenance(previous, paths));
+  for (const path of paths) {
+    const supplied = suppliedPath(patch, path);
+    if (supplied === "clear") explicit.delete(path);
+    if (supplied === "explicit") explicit.add(path);
+  }
+  return [...explicit];
+}
+
+/** Copy only traversed objects so deleting inherited defaults never mutates callers. */
+export function omitInheritedDefaults<T extends object>(config: T, paths: readonly string[], explicit: readonly string[]): T {
+  const result = { ...config } as Record<string, unknown>;
+  for (const path of paths) {
+    if (explicit.includes(path)) continue;
+    const keys = path.split(".");
+    let target: Record<string, unknown> | undefined = result;
+    for (const key of keys.slice(0, -1)) {
+      const child: unknown = target[key];
+      if (!record(child)) { target = undefined; break; }
+      target[key] = { ...child };
+      target = target[key] as Record<string, unknown>;
+    }
+    if (target) delete target[keys[keys.length - 1]];
+  }
+  return result as T;
+}

package/src/utils/dock.ts

@@ -1,4 +1,7 @@
 import type { AgentWidgetConfig, AgentWidgetDockConfig } from "../types";
+import { getPanelAliasProvenance } from "./panel-config";
+import { getActiveTheme } from "./theme";
+import { resolveTokenValue } from "./tokens";
 
 const DEFAULT_DOCK_CONFIG: Required<AgentWidgetDockConfig> = {
   side: "right",
@@ -25,9 +28,12 @@ export const resolveDockConfig = (
   config?: AgentWidgetConfig
 ): Required<AgentWidgetDockConfig> => {
   const dock = config?.launcher?.dock;
+  const width = getPanelAliasProvenance(config).dockWidth
+    ? dock?.width
+    : resolveTokenValue(getActiveTheme(config), "components.panel.width");
   return {
     side: dock?.side ?? DEFAULT_DOCK_CONFIG.side,
-    width: dock?.width ?? DEFAULT_DOCK_CONFIG.width,
+    width: width ?? DEFAULT_DOCK_CONFIG.width,
     animate: dock?.animate ?? DEFAULT_DOCK_CONFIG.animate,
     reveal: dock?.reveal ?? DEFAULT_DOCK_CONFIG.reveal,
     maxHeight: dock?.maxHeight ?? DEFAULT_DOCK_CONFIG.maxHeight,

package/src/utils/launcher-variant.ts

@@ -0,0 +1,16 @@
+import type { AgentWidgetConfig } from "../types";
+import type { LauncherTokens } from "../types/theme";
+
+export const resolveLauncherVariant = (config?: Pick<AgentWidgetConfig, "launcher" | "future">): "pill" | "circle" =>
+  config?.launcher?.variant ?? (config?.future?.v5Defaults === true ? "circle" : "pill");
+
+export const CIRCLE_LAUNCHER_TOKENS: LauncherTokens = {
+  background: "semantic.colors.primary",
+  foreground: "semantic.colors.textInverse",
+  border: "transparent",
+  size: "48px",
+  iconSize: "24px",
+  borderRadius: "palette.radius.full",
+  shadow: "0 8px 24px rgba(0,0,0,.16)",
+  offset: "20px",
+};

package/src/utils/panel-config.ts

@@ -0,0 +1,97 @@
+import type { AgentWidgetConfig, AgentWidgetConfigPatch } from "../types";
+
+export const PANEL_WIDTH_VAR = "var(--persona-components-panel-width)";
+
+/**
+ * Provenance for legacy panel geometry aliases. Config merging materializes
+ * launcher defaults, so values alone cannot distinguish a caller's alias from
+ * an inherited v4 default. The enumerable symbol survives object spreads while
+ * remaining absent from JSON, generated snippets, and the public config shape.
+ */
+export const PANEL_ALIAS_PROVENANCE = Symbol("persona.panelAliasProvenance");
+
+export type PanelAliasProvenance = {
+  launcherWidth: boolean;
+  legacyLauncherWidth: boolean;
+  sidebarWidth: boolean;
+  dockWidth: boolean;
+};
+
+type WithPanelAliasProvenance = {
+  [PANEL_ALIAS_PROVENANCE]?: PanelAliasProvenance;
+};
+
+const hasOwn = (value: object | undefined, key: string): boolean =>
+  value != null && Object.prototype.hasOwnProperty.call(value, key);
+
+const hasOwnDefined = (value: object | undefined, key: string): boolean =>
+  hasOwn(value, key) && (value as Record<string, unknown>)[key] !== undefined;
+
+const fromRawConfig = (
+  config?: Partial<AgentWidgetConfig>
+): PanelAliasProvenance => ({
+  launcherWidth: hasOwnDefined(config?.launcher, "width"),
+  legacyLauncherWidth: hasOwnDefined(config, "launcherWidth"),
+  sidebarWidth: hasOwnDefined(config?.launcher, "sidebarWidth"),
+  dockWidth: hasOwnDefined(config?.launcher?.dock, "width"),
+});
+
+export const getPanelAliasProvenance = (
+  config?: Partial<AgentWidgetConfig>
+): PanelAliasProvenance => {
+  const stored = (config as WithPanelAliasProvenance | undefined)?.[PANEL_ALIAS_PROVENANCE];
+  return stored ? { ...stored } : fromRawConfig(config);
+};
+
+export const setPanelAliasProvenance = <T extends object>(
+  config: T,
+  provenance: PanelAliasProvenance
+): T => {
+  Object.defineProperty(config, PANEL_ALIAS_PROVENANCE, {
+    value: provenance,
+    enumerable: true,
+    configurable: true,
+  });
+  return config;
+};
+
+/** Stamp a defaulted config with aliases supplied by the raw input. */
+export const inheritPanelAliasProvenance = <T extends object>(
+  result: T,
+  rawConfig?: Partial<AgentWidgetConfig>
+): T => setPanelAliasProvenance(result, getPanelAliasProvenance(rawConfig));
+
+/** Apply own alias keys in a live patch, including explicit-undefined resets. */
+export const updatePanelAliasProvenance = (
+  previous: Partial<AgentWidgetConfig>,
+  patch: AgentWidgetConfigPatch
+): PanelAliasProvenance => {
+  // A config spread remains marked. Treat it as an already-normalized full
+  // config rather than mistaking its materialized launcher defaults for a
+  // patch that explicitly supplied every alias.
+  const patchProvenance = (patch as WithPanelAliasProvenance)[PANEL_ALIAS_PROVENANCE];
+  if (patchProvenance) return { ...patchProvenance };
+
+  const next = getPanelAliasProvenance(previous);
+  if (hasOwn(patch, "launcherWidth")) {
+    next.legacyLauncherWidth = patch.launcherWidth !== undefined;
+  }
+  if (hasOwn(patch, "launcher") && patch.launcher === undefined) {
+    next.launcherWidth = false;
+    next.sidebarWidth = false;
+    next.dockWidth = false;
+    return next;
+  }
+  if (hasOwn(patch.launcher, "width")) {
+    next.launcherWidth = patch.launcher?.width !== undefined;
+  }
+  if (hasOwn(patch.launcher, "sidebarWidth")) {
+    next.sidebarWidth = patch.launcher?.sidebarWidth !== undefined;
+  }
+  if (hasOwn(patch.launcher, "dock") && patch.launcher?.dock === undefined) {
+    next.dockWidth = false;
+  } else if (hasOwn(patch.launcher?.dock, "width")) {
+    next.dockWidth = patch.launcher?.dock?.width !== undefined;
+  }
+  return next;
+};

package/src/utils/status-indicator.ts

@@ -0,0 +1,39 @@
+import type { AgentWidgetStatusIndicatorConfig } from "../types";
+
+/** Transient connection chrome excludes normal idle and streaming states. */
+export const isStatusIndicatorVisible = (
+  config: AgentWidgetStatusIndicatorConfig,
+  status: string,
+): boolean => config.visible !== false && (
+  config.mode !== "transient" ||
+  status === "connecting" || status === "paused" ||
+  status === "resuming" || status === "error"
+);
+
+export const applyStatusIndicatorState = (
+  element: HTMLElement,
+  config: AgentWidgetStatusIndicatorConfig,
+  status: string,
+): void => {
+  const transient = config.mode === "transient";
+  const hasNotice = element.hasAttribute("data-persona-composer-reason") ||
+    element.hasAttribute("data-persona-composer-notice");
+  element.style.display = isStatusIndicatorVisible(config, status) ||
+    (transient && hasNotice && config.visible !== false) ? "" : "none";
+  element.classList.toggle("persona-mt-2", !transient);
+  element.classList.toggle("persona-mb-2", transient);
+};
+
+/** Move only sibling regions, leaving a plugin's internal structure intact. */
+export const placeStatusIndicator = (
+  element: HTMLElement,
+  form: HTMLElement,
+  config: AgentWidgetStatusIndicatorConfig,
+): void => {
+  if (!form.parentElement || element.parentElement !== form.parentElement) return;
+  if (config.mode === "transient") {
+    if (element.nextElementSibling !== form) form.before(element);
+  } else if (form.nextElementSibling !== element) {
+    form.after(element);
+  }
+};