@runtypelabs/persona 4.15.0 → 4.16.0

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

package/src/welcome.ts

@@ -0,0 +1,130 @@
+import type {
+  AgentWidgetConfig,
+  AgentWidgetMessage,
+  AgentWidgetWelcomeDismiss,
+  AgentWidgetWelcomeIcon,
+  AgentWidgetWelcomeVariant,
+} from "./types";
+
+/**
+ * Single source of truth for the welcome surface. Renderers consume the
+ * resolved shape only and never read `copy.welcome*` directly.
+ *
+ * The defaults live here, not in `defaults.ts`: `mergeConfigUpdate`
+ * re-applies `mergeWithDefaults` after every patch, so anything defaulted
+ * there would be materialized into the stored config and presence-based
+ * precedence could no longer tell a host-set value from a default.
+ */
+
+/** Default welcome title, applied when neither `welcome` nor `copy` sets one. */
+export const DEFAULT_WELCOME_TITLE = "Hello 👋";
+
+/**
+ * Scope statement in the assistant's voice, deliberately generic so the
+ * placeholder shape reads as something to replace with domain copy.
+ */
+export const DEFAULT_WELCOME_SUBTITLE =
+  "I can answer questions and help you get things done here.";
+
+export interface ResolvedWelcomeConfig {
+  title: string;
+  subtitle: string;
+  icon?: AgentWidgetWelcomeIcon;
+  variant: AgentWidgetWelcomeVariant;
+  dismiss: AgentWidgetWelcomeDismiss;
+  /** Undefined under `variant: "hero"`, which suppresses the greeting. */
+  message?: string;
+}
+
+// Keyed on the config object: the resolver runs on every render, so warnings
+// fire once per config identity instead of once per frame.
+const warnedConfigs = new WeakSet<AgentWidgetConfig>();
+
+const isSet = <T, K extends keyof T>(source: T | undefined, key: K): boolean =>
+  !!source && source[key] !== undefined;
+
+const warnOnce = (config: AgentWidgetConfig | undefined, messages: string[]) => {
+  if (!config || config.debug !== true || !messages.length) return;
+  if (warnedConfigs.has(config)) return;
+  warnedConfigs.add(config);
+  messages.forEach((message) => console.warn(`[persona] ${message}`));
+};
+
+/**
+ * Per-field, presence-based precedence: `welcome.*` wins, else the legacy
+ * `copy` alias, else the default above.
+ */
+export const resolveWelcomeConfig = (
+  config?: AgentWidgetConfig
+): ResolvedWelcomeConfig => {
+  const welcome = config?.welcome;
+  const copy = config?.copy;
+
+  const variant: AgentWidgetWelcomeVariant = isSet(welcome, "variant")
+    ? welcome!.variant!
+    : copy?.showWelcomeCard === false
+      ? "none"
+      : "card";
+
+  // Hero IS the greeting: `dismiss` is forced and `message` is suppressed.
+  const dismiss: AgentWidgetWelcomeDismiss =
+    variant === "hero"
+      ? "on-first-message"
+      : isSet(welcome, "dismiss")
+        ? welcome!.dismiss!
+        : "never";
+
+  const conflicts: string[] = [];
+  if (isSet(welcome, "title") && isSet(copy, "welcomeTitle")) {
+    conflicts.push(
+      "welcome.title and copy.welcomeTitle are both set; welcome.title wins. copy.welcomeTitle is deprecated."
+    );
+  }
+  if (isSet(welcome, "subtitle") && isSet(copy, "welcomeSubtitle")) {
+    conflicts.push(
+      "welcome.subtitle and copy.welcomeSubtitle are both set; welcome.subtitle wins. copy.welcomeSubtitle is deprecated."
+    );
+  }
+  if (isSet(welcome, "variant") && isSet(copy, "showWelcomeCard")) {
+    conflicts.push(
+      "welcome.variant and copy.showWelcomeCard are both set; welcome.variant wins. copy.showWelcomeCard is deprecated."
+    );
+  }
+  if (variant === "hero" && isSet(welcome, "message")) {
+    conflicts.push(
+      'welcome.message is ignored when welcome.variant is "hero": the hero is the greeting.'
+    );
+  }
+  if (variant === "hero" && isSet(welcome, "dismiss") && welcome!.dismiss !== "on-first-message") {
+    conflicts.push(
+      'welcome.dismiss is pinned to "on-first-message" when welcome.variant is "hero".'
+    );
+  }
+  warnOnce(config, conflicts);
+
+  return {
+    title: isSet(welcome, "title")
+      ? welcome!.title!
+      : copy?.welcomeTitle ?? DEFAULT_WELCOME_TITLE,
+    subtitle: isSet(welcome, "subtitle")
+      ? welcome!.subtitle!
+      : copy?.welcomeSubtitle ?? DEFAULT_WELCOME_SUBTITLE,
+    icon: welcome?.icon,
+    variant,
+    dismiss,
+    message: variant === "hero" ? undefined : welcome?.message,
+  };
+};
+
+/**
+ * Derived visibility, never stored. "User activity" is the same predicate the
+ * starters use: the session contains at least one `role: "user"` message.
+ */
+export const isWelcomeVisible = (
+  resolved: ResolvedWelcomeConfig,
+  messages: readonly AgentWidgetMessage[] | undefined
+): boolean => {
+  if (resolved.variant === "none") return false;
+  if (resolved.dismiss === "never") return true;
+  return !(messages ?? []).some((message) => message.role === "user");
+};