@runtypelabs/persona 4.23.2 → 4.25.0

package/src/ui.v5-defaults.test.ts

@@ -0,0 +1,144 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAgentExperience } from "./ui";
+
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+afterEach(() => {
+  controllers.splice(0).forEach((controller) => controller.destroy());
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+});
+
+describe.each([false, true])("core defaults lifecycle (v5=%s)", (v5Defaults) => {
+  it("applies a live defaults switch to existing messages and header", () => {
+    window.scrollTo = vi.fn();
+    const mount = document.createElement("div");
+    document.body.append(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: "/dispatch", persistState: false,
+      future: { v5Defaults }, launcher: { autoExpand: true },
+    });
+    controllers.push(controller);
+    controller.injectUserMessage({ content: "Hello" });
+    controller.injectAssistantMessage({ content: "Welcome" });
+    const assertState = (v5: boolean) => {
+      expect(mount.dataset.personaDefaults).toBe(v5 ? "v5" : "v4");
+      const header = mount.querySelector<HTMLElement>(".persona-widget-header")!;
+      expect((header.firstElementChild as HTMLElement).style.width).toBe(v5 ? "20px" : "40px");
+      expect(mount.style.getPropertyValue("--persona-components-header-padding"))
+        .toBe(v5 ? "8px 8px 8px 16px" : "20px 24px");
+      const bubble = mount.querySelector<HTMLElement>(".persona-message-row-assistant .persona-message-bubble")!;
+      expect(bubble.style.lineHeight).toBe(v5 ? "var(--persona-message-assistant-line-height, 1.75)" : "");
+      const status = mount.querySelector<HTMLElement>("[data-persona-composer-status]")!;
+      expect(status.style.display).toBe(v5 ? "none" : "");
+    };
+    assertState(v5Defaults);
+    controller.update({ future: { v5Defaults: !v5Defaults } });
+    assertState(!v5Defaults);
+    controller.update({ future: { v5Defaults } });
+    assertState(v5Defaults);
+  });
+
+  it("exposes composer chrome and honors explicit glyph overrides", () => {
+    window.scrollTo = vi.fn();
+    const mount = document.createElement("div");
+    document.body.append(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: "/dispatch", persistState: false, future: { v5Defaults },
+      launcher: { autoExpand: true },
+    });
+    controllers.push(controller);
+    expect(mount.style.getPropertyValue("--persona-components-composer-sendIconSize"))
+      .toBe(v5Defaults ? "18px" : "");
+    expect(mount.style.getPropertyValue("--persona-components-composer-sendButtonRadius"))
+      .toBe(v5Defaults ? "9999px" : "");
+    expect(mount.style.getPropertyValue("--persona-components-composer-footerBorder"))
+      .toBe(v5Defaults ? "none" : "");
+    controller.update({
+      sendButton: { iconName: "send", iconSize: "15px" },
+      theme: { components: { composer: {
+        sendIconSize: "22px", sendButtonRadius: "8px", footerBorder: "2px solid red",
+      } } },
+    });
+    const svg = mount.querySelector<SVGElement>("[data-persona-composer-submit] svg")!;
+    expect(svg.getAttribute("width")).toBe("15");
+    expect(svg.style.width).toBe("");
+    expect(mount.style.getPropertyValue("--persona-components-composer-sendButtonRadius")).toBe("8px");
+    expect(mount.style.getPropertyValue("--persona-components-composer-footerBorder")).toBe("2px solid red");
+  });
+
+  it("switches composer focus defaults live and retains explicit focus and resting chrome", () => {
+    window.scrollTo = vi.fn();
+    const mount = document.createElement("div");
+    document.body.append(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: "/dispatch", persistState: false, future: { v5Defaults },
+      launcher: { autoExpand: true },
+      theme: { components: { composer: { borderColor: "#123456", shadow: "0 3px 8px #123456" } } },
+    });
+    controllers.push(controller);
+    const assertDefaults = (v5: boolean) => {
+      expect(mount.style.getPropertyValue("--persona-components-composer-focusBorderColor"))
+        .toBe(v5 ? "color-mix(in srgb, var(--persona-text) 28%, var(--persona-border))" : "");
+      expect(mount.style.getPropertyValue("--persona-components-composer-focusRing"))
+        .toBe(v5 ? "1px solid color-mix(in srgb, var(--persona-text) 12%, transparent)" : "");
+      expect(mount.style.getPropertyValue("--persona-composer-border-color")).toBe("#123456");
+      expect(mount.style.getPropertyValue("--persona-composer-shadow")).toBe("0 3px 8px #123456");
+      // No inline outline may suppress the stylesheet's ring.
+      expect(mount.querySelector<HTMLElement>("[data-persona-composer-form]")!.style.outline).toBe("");
+    };
+    assertDefaults(v5Defaults);
+    controller.update({ future: { v5Defaults: !v5Defaults } });
+    assertDefaults(!v5Defaults);
+    controller.update({ theme: { components: { composer: {
+      focusBorderColor: "#abcdef", focusRing: "2px solid #fedcba",
+    } } } });
+    for (const state of [v5Defaults, !v5Defaults]) {
+      controller.update({ future: { v5Defaults: state } });
+      expect(mount.style.getPropertyValue("--persona-components-composer-focusBorderColor")).toBe("#abcdef");
+      expect(mount.style.getPropertyValue("--persona-components-composer-focusRing")).toBe("2px solid #fedcba");
+    }
+    controller.update({ theme: { components: { composer: { focusRing: "none" } } } });
+    expect(mount.style.getPropertyValue("--persona-components-composer-focusRing")).toBe("none");
+  });
+
+  it("switches default placement and fade while retaining explicit choices", () => {
+    window.scrollTo = vi.fn();
+    const mount = document.createElement("div");
+    document.body.append(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: "/dispatch", persistState: false, future: { v5Defaults },
+      launcher: { autoExpand: true },
+    });
+    controllers.push(controller);
+    for (const state of [v5Defaults, !v5Defaults]) {
+      controller.update({ future: { v5Defaults: state } });
+      expect(mount.dataset.personaComposerPlacement).toBe(state ? "overlay" : "block");
+      expect(mount.style.getPropertyValue("--persona-composer-overlay-band"))
+        .toBe(state ? "linear-gradient(to bottom, transparent, var(--persona-container) 24px)" : "transparent");
+    }
+    controller.update({ composer: { placement: "block" }, theme: { components: { composer: { overlayBand: "transparent" } } } });
+    controller.update({ future: { v5Defaults: !v5Defaults } });
+    expect(mount.dataset.personaComposerPlacement).toBe("block");
+    expect(mount.style.getPropertyValue("--persona-composer-overlay-band")).toBe("transparent");
+  });
+
+  it("uses fullscreen turn spacing in full-height embeds and honors explicit spacing", () => {
+    window.scrollTo = vi.fn();
+    const mount = document.createElement("div");
+    document.body.append(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: "/dispatch", persistState: false, future: { v5Defaults },
+      launcher: { enabled: false, fullHeight: true },
+    });
+    controllers.push(controller);
+    const messages = mount.querySelector<HTMLElement>(".persona-widget-messages")!;
+    expect(messages.style.gap).toContain("--persona-components-message-fullscreenGap");
+    expect(mount.style.getPropertyValue("--persona-components-message-fullscreenGap"))
+      .toBe(v5Defaults ? "28px" : "");
+    controller.update({ theme: { components: { message: { gap: "33px" } } } });
+    expect(mount.style.getPropertyValue("--persona-components-message-fullscreenGap")).toBe("33px");
+    controller.update({ theme: { components: { message: { fullscreenGap: "42px" } } } });
+    expect(mount.style.getPropertyValue("--persona-components-message-fullscreenGap")).toBe("42px");
+  });
+});

package/src/ui.voice-prewarm.test.ts

@@ -0,0 +1,222 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createAgentExperience } from "./ui";
+import type {
+  AgentWidgetConfig,
+  AgentWidgetVoicePrewarmHook,
+  AgentWidgetVoiceRecognitionConfig,
+} from "./types";
+
+let controller: ReturnType<typeof createAgentExperience> | undefined;
+
+beforeEach(() => {
+  window.scrollTo = vi.fn();
+});
+
+afterEach(() => {
+  controller?.destroy();
+  controller = undefined;
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+const initResponse = () =>
+  Response.json({
+    sessionId: "session-1",
+    expiresAt: new Date(Date.now() + 600_000).toISOString(),
+    flow: { id: "agent-1", name: "Agent", description: null },
+    config: { welcomeMessage: null, placeholder: "Ask...", theme: null },
+  });
+
+const runtypeVoice = (
+  extra: Partial<AgentWidgetVoiceRecognitionConfig> = {}
+): AgentWidgetVoiceRecognitionConfig => ({
+  enabled: true,
+  provider: { type: "runtype", runtype: { agentId: "agent-1" } },
+  ...extra,
+});
+
+function mountWidget(config: Partial<AgentWidgetConfig>) {
+  const prewarms: Array<{ url: string; init?: RequestInit }> = [];
+  const inits: string[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init?: RequestInit) => {
+      if (url.endsWith("/voice/prewarm")) {
+        prewarms.push({ url, init });
+        return new Response(null, { status: 204 });
+      }
+      if (url.endsWith("/v1/client/init")) {
+        inits.push(url);
+        return initResponse();
+      }
+      return new Response('data: {"type":"done"}\n\n', {
+        headers: { "Content-Type": "text/event-stream" },
+      });
+    })
+  );
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com",
+    agentId: "agent-1",
+    launcher: { enabled: false },
+    persistState: false,
+    ...config,
+  } as AgentWidgetConfig);
+  const mic = () => mount.querySelector<HTMLButtonElement>("[data-persona-composer-mic]")!;
+  const hover = () => mic().dispatchEvent(new Event("pointerover", { bubbles: true }));
+  return { mount, mic, hover, prewarms, inits };
+}
+
+// Lets the lazy voice runtime install and any fire-and-forget fetch run.
+const settle = async () => {
+  for (let i = 0; i < 5; i += 1) await new Promise((r) => setTimeout(r, 0));
+};
+
+describe("voiceRecognition.prewarm: default", () => {
+  it("prewarms once on mic hover in client token mode (latched)", async () => {
+    const w = mountWidget({ clientToken: "ct_test", voiceRecognition: runtypeVoice() });
+    await settle();
+    expect(w.prewarms).toHaveLength(0);
+
+    w.hover();
+    await vi.waitFor(() => expect(w.prewarms).toHaveLength(1));
+    expect(w.prewarms[0].url).toBe(
+      "https://api.example.com/v1/client/agents/agent-1/voice/prewarm"
+    );
+    expect(w.prewarms[0].init?.headers).toEqual({ Authorization: "Bearer ct_test" });
+
+    w.hover();
+    w.mic().dispatchEvent(new Event("pointerdown", { bubbles: true }));
+    w.mic().dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    await settle();
+    expect(w.prewarms).toHaveLength(1);
+  });
+
+  it("also prewarms on keyboard focus", async () => {
+    const w = mountWidget({ clientToken: "ct_test", voiceRecognition: runtypeVoice() });
+    await settle();
+    w.mic().dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    await vi.waitFor(() => expect(w.prewarms).toHaveLength(1));
+  });
+
+  it("ignores hover elsewhere in the widget", async () => {
+    const w = mountWidget({ clientToken: "ct_test", voiceRecognition: runtypeVoice() });
+    await settle();
+    w.mount
+      .querySelector("[data-persona-composer-input]")!
+      .dispatchEvent(new Event("pointerover", { bubbles: true }));
+    await settle();
+    expect(w.prewarms).toHaveLength(0);
+  });
+
+  it("does not auto-prewarm outside client token mode", async () => {
+    const w = mountWidget({
+      voiceRecognition: {
+        enabled: true,
+        provider: { type: "runtype", runtype: { agentId: "agent-1", clientToken: "ct_voice" } },
+      },
+    });
+    await settle();
+    w.hover();
+    await settle();
+    expect(w.prewarms).toHaveLength(0);
+  });
+
+  it("warms the client session on the browser (Web Speech) path", async () => {
+    vi.stubGlobal("SpeechRecognition", vi.fn());
+    const w = mountWidget({ clientToken: "ct_test", voiceRecognition: { enabled: true } });
+    await settle();
+    expect(w.inits).toHaveLength(0);
+    w.hover();
+    await vi.waitFor(() => expect(w.inits).toHaveLength(1));
+    expect(w.prewarms).toHaveLength(0);
+  });
+});
+
+describe("voiceRecognition.prewarm: explicit settings", () => {
+  it("false opts out", async () => {
+    const w = mountWidget({
+      clientToken: "ct_test",
+      voiceRecognition: runtypeVoice({ prewarm: false }),
+    });
+    await settle();
+    w.hover();
+    await settle();
+    expect(w.prewarms).toHaveLength(0);
+  });
+
+  it("'hover' enables it outside client token mode", async () => {
+    const w = mountWidget({
+      voiceRecognition: {
+        enabled: true,
+        prewarm: "hover",
+        provider: { type: "runtype", runtype: { agentId: "agent-1", clientToken: "ct_voice" } },
+      },
+    });
+    await settle();
+    w.hover();
+    await vi.waitFor(() => expect(w.prewarms).toHaveLength(1));
+    expect(w.prewarms[0].init?.headers).toEqual({ Authorization: "Bearer ct_voice" });
+  });
+
+  it("a custom hook receives warm and the mic button, replaces hover, and is cleaned up", async () => {
+    const cleanup = vi.fn();
+    let context: Parameters<AgentWidgetVoicePrewarmHook>[0] | undefined;
+    const hook = vi.fn((ctx: Parameters<AgentWidgetVoicePrewarmHook>[0]) => {
+      context = ctx;
+      return cleanup;
+    });
+    const w = mountWidget({
+      clientToken: "ct_test",
+      voiceRecognition: runtypeVoice({ prewarm: hook }),
+    });
+    await settle();
+    expect(hook).toHaveBeenCalledOnce();
+    expect(context?.micButton).toBe(w.mic());
+    expect(context?.mount).toBe(w.mount);
+
+    w.hover();
+    await settle();
+    expect(w.prewarms).toHaveLength(0);
+
+    context!.warm();
+    await vi.waitFor(() => expect(w.prewarms).toHaveLength(1));
+
+    controller!.destroy();
+    controller = undefined;
+    expect(cleanup).toHaveBeenCalledOnce();
+  });
+
+  it("update() swaps the hook and turning prewarm off releases it", async () => {
+    const cleanupA = vi.fn();
+    const hookA = vi.fn(() => cleanupA);
+    const hookB = vi.fn();
+    mountWidget({ clientToken: "ct_test", voiceRecognition: runtypeVoice({ prewarm: hookA }) });
+    await settle();
+
+    controller!.update({ voiceRecognition: runtypeVoice({ prewarm: hookB }) });
+    expect(cleanupA).toHaveBeenCalledOnce();
+    expect(hookB).toHaveBeenCalledOnce();
+
+    controller!.update({ voiceRecognition: runtypeVoice({ prewarm: false }) });
+    expect(hookB).toHaveBeenCalledOnce();
+    expect(hookA).toHaveBeenCalledOnce();
+  });
+
+  it("a throwing hook does not break mount", async () => {
+    const w = mountWidget({
+      clientToken: "ct_test",
+      voiceRecognition: runtypeVoice({
+        prewarm: () => {
+          throw new Error("host bug");
+        },
+      }),
+    });
+    await settle();
+    expect(w.mic()).toBeTruthy();
+  });
+});

package/src/ui.welcome.test.ts

@@ -328,8 +328,8 @@ describe("welcome visibility state machine", () => {
 });
 
 describe("welcome greeting bubble", () => {
-  it("renders an assistant-styled bubble above the transcript", () => {
-    const { mount } = makeController({ welcome: { message: "Hi, I'm Ada." } });
+  it.each([false, true])("renders an assistant-styled bubble above the transcript (v5=%s)", (v5Defaults) => {
+    const { mount } = makeController({ future: { v5Defaults }, welcome: { message: "Hi, I'm Ada." } });
     const greeting = greetingHost(mount);
     expect(isVisible(greeting)).toBe(true);
     expect(greeting.textContent).toBe("Hi, I'm Ada.");
@@ -342,7 +342,7 @@ describe("welcome greeting bubble", () => {
     const body = mount.querySelector<HTMLElement>("#persona-scroll-container")!;
     const children = Array.from(body.children);
     const transcript = body.querySelector<HTMLElement>(
-      ":scope > .persona-gap-3"
+      ":scope > .persona-widget-messages"
     )!;
     expect(children.indexOf(greeting)).toBeLessThan(
       children.indexOf(transcript)
@@ -508,3 +508,92 @@ describe("welcome live updates", () => {
     expect(isVisible(welcomeHost(mount))).toBe(true);
   });
 });
+
+describe("centered welcome", () => {
+  it("groups legacy starters in the V5 welcome and restores them after clear", () => {
+    const { mount, controller } = makeController({ future: { v5Defaults: true }, suggestionChips: ["One", "Two", "Three", "Four", "Five"] });
+    const host = welcomeHost(mount);
+    expect(host.getAttribute("data-persona-welcome-layout")).toBe("centered");
+    expect(host.querySelector("h2")?.textContent).toBe("What can I help with?");
+    expect(host.querySelectorAll(".persona-suggestion")).toHaveLength(3);
+    expect(host.querySelector(".persona-suggestions")?.getAttribute("data-variant")).toBe("chip");
+    controller.injectTestMessage({ type: "message", message: assistantMessage() });
+    expect(isVisible(host)).toBe(true);
+    sendUserMessage(controller);
+    expect(isVisible(host)).toBe(false);
+    controller.clearChat();
+    expect(isVisible(host)).toBe(true);
+    expect(host.querySelectorAll(".persona-suggestion")).toHaveLength(3);
+  });
+
+  it("raises fullscreen empty composers and defaults starters to four cards", () => {
+    const { mount } = makeController({ future: { v5Defaults: true }, launcher: { enabled: false, fullHeight: true }, suggestionChips: ["One", "Two", "Three", "Four", "Five"] });
+    expect(mount.getAttribute("data-persona-welcome-anchor")).toBe("center");
+    expect(welcomeHost(mount).querySelectorAll(".persona-suggestion")).toHaveLength(4);
+    expect(welcomeHost(mount).querySelector(".persona-suggestions")?.getAttribute("data-variant")).toBe("card");
+  });
+});
+
+it("updates starter density when the floating panel becomes mobile fullscreen", () => {
+  const originalWidth = window.innerWidth;
+  try {
+    Object.defineProperty(window, "innerWidth", { configurable: true, value: 1000 });
+    const { mount } = makeController({ future: { v5Defaults: true }, launcher: { enabled: true }, suggestionChips: ["One", "Two", "Three", "Four", "Five"] });
+    expect(welcomeHost(mount).querySelectorAll(".persona-suggestion")).toHaveLength(3);
+    Object.defineProperty(window, "innerWidth", { configurable: true, value: 500 });
+    window.dispatchEvent(new Event("resize"));
+    expect(mount.getAttribute("data-persona-welcome-anchor")).toBe("center");
+    expect(welcomeHost(mount).querySelectorAll(".persona-suggestion")).toHaveLength(4);
+    Object.defineProperty(window, "innerWidth", { configurable: true, value: 1000 });
+    window.dispatchEvent(new Event("resize"));
+    expect(mount.getAttribute("data-persona-welcome-anchor")).toBe("bottom");
+    expect(welcomeHost(mount).querySelectorAll(".persona-suggestion")).toHaveLength(3);
+  } finally {
+    Object.defineProperty(window, "innerWidth", { configurable: true, value: originalWidth });
+  }
+});
+
+describe.each([false, true])("explicit welcome layout (V5 defaults: %s)", (v5Defaults) => {
+  it("makes top override hero centering in empty and active states", () => {
+    const { mount, controller } = makeController({ future: { v5Defaults }, welcome: { layout: "top", variant: "hero", dismiss: "never" } });
+    expect(mount.getAttribute("data-persona-welcome-layout-explicit")).toBe("top");
+    expect(isVisible(welcomeHost(mount))).toBe(true);
+    sendUserMessage(controller);
+    expect(mount.getAttribute("data-persona-welcome-layout-explicit")).toBe("top");
+    expect(isVisible(welcomeHost(mount))).toBe(true);
+  });
+
+  it("centers and resets explicit greeting/starters while honoring overrides", () => {
+    const { mount, controller } = makeController({
+      future: { v5Defaults },
+      welcome: { layout: "centered", title: "Custom", subtitle: "Scope", dismiss: "on-first-message", align: "start", anchor: "bottom" },
+      suggestions: { starters: { items: ["One", "Two", "Three", "Four", "Five"], maxItems: 2, variant: "list", behavior: "fill" } },
+    });
+    expect(welcomeHost(mount).getAttribute("data-persona-welcome-layout")).toBe("centered");
+    expect(welcomeHost(mount).getAttribute("data-persona-welcome-align")).toBe("start");
+    expect(mount.getAttribute("data-persona-welcome-anchor")).toBe("bottom");
+    expect(welcomeHost(mount).querySelector("h2")?.textContent).toBe("Custom");
+    expect(welcomeHost(mount).querySelectorAll(".persona-suggestion")).toHaveLength(2);
+    controller.injectTestMessage({ type: "message", message: assistantMessage() });
+    expect(isVisible(welcomeHost(mount))).toBe(true);
+    sendUserMessage(controller);
+    expect(isVisible(welcomeHost(mount))).toBe(false);
+    controller.clearChat();
+    expect(isVisible(welcomeHost(mount))).toBe(true);
+  });
+
+  it("centers the measured fullscreen group and preserves an explicit percentage", () => {
+    const { mount, controller } = makeController({ future: { v5Defaults }, launcher: { enabled: false, fullHeight: true }, composer: { placement: "overlay" }, welcome: { layout: "centered" } });
+    const footer = mount.querySelector<HTMLElement>(".persona-widget-footer")!;
+    const container = footer.parentElement!;
+    Object.defineProperty(container, "clientHeight", { configurable: true, value: 800 });
+    Object.defineProperty(footer, "offsetHeight", { configurable: true, value: 100 });
+    Object.defineProperty(welcomeHost(mount), "offsetHeight", { configurable: true, value: 200 });
+    window.dispatchEvent(new Event("resize"));
+    // jsdom has no stylesheet geometry: the zero gap/body origin gives
+    // (800 - 200 - 100) / 2 rather than the old 44%-top anchoring.
+    expect(mount.style.getPropertyValue("--persona-composer-lift")).toBe("250px");
+    controller.update({ welcome: { layout: "centered", anchorComposerTop: "40%" } });
+    expect(mount.style.getPropertyValue("--persona-composer-lift")).toBe("380px");
+  });
+});