@runtypelabs/persona 4.23.2 → 4.25.0

package/src/launcher-variants.test.ts

@@ -0,0 +1,52 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAgentExperience } from "./ui";
+import { mount as mountCritical } from "./launcher-global";
+import { getActiveTheme, themeToCssVariables } from "./utils/theme";
+import type { AgentWidgetConfig } from "./types";
+
+afterEach(() => { document.body.replaceChildren(); vi.restoreAllMocks(); });
+
+describe.each([false, true])("launcher variants (v5=%s)", (v5Defaults) => {
+  it.each([undefined, "pill", "circle"] as const)("matches deferred and full rendering for %s", (variant) => {
+    window.scrollTo = vi.fn();
+    const config: AgentWidgetConfig = {
+      apiUrl: "/dispatch", persistState: false, future: { v5Defaults },
+      launcher: { ...(variant ? { variant } : {}), title: "Open support", teaser: { text: "Need help?" } },
+    };
+    const host = document.body.appendChild(document.createElement("div"));
+    const target = document.body.appendChild(document.createElement("div"));
+    const full = createAgentExperience(host, config);
+    const critical = mountCritical({ target, config, onOpen: vi.fn() });
+    const button = host.querySelector<HTMLButtonElement>(".persona-launcher-surface > button")!;
+    try {
+      const circle = variant ? variant === "circle" : v5Defaults;
+      expect(button.dataset.personaLauncherVariant).toBe(circle ? "circle" : undefined);
+      expect(button.innerHTML).toBe(critical.element.innerHTML);
+      expect(button.getAttribute("style")).toBe(critical.element.getAttribute("style"));
+      expect(host.style.getPropertyValue("--persona-launcher-bg"))
+        .toBe(critical.root.style.getPropertyValue("--persona-launcher-bg"));
+      if (circle) expect(button.getAttribute("aria-label")).toBe("Open support");
+      full.update({ launcher: { variant: circle ? "pill" : "circle" } });
+      critical.update({ ...config, launcher: { ...config.launcher, variant: circle ? "pill" : "circle" } });
+      expect(button.dataset.personaLauncherVariant).toBe(circle ? undefined : "circle");
+      expect(button.innerHTML).toBe(critical.element.innerHTML);
+    } finally { full.destroy(); critical.destroy(); }
+  });
+
+  it.each(["light", "dark"] as const)("resolves circle geometry and explicit tokens in %s", colorScheme => {
+    const config: AgentWidgetConfig = { future: { v5Defaults }, colorScheme, launcher: { variant: "circle" } };
+    const css = themeToCssVariables(getActiveTheme(config));
+    expect(css["--persona-components-launcher-size"]).toBe("48px");
+    expect(css["--persona-components-launcher-offset"]).toBe("20px");
+    expect(css["--persona-launcher-shadow"]).toBe("0 8px 24px rgba(0,0,0,.16)");
+    expect(css["--persona-launcher-bg"]).not.toBe(css["--persona-launcher-fg"]);
+    const custom = themeToCssVariables(getActiveTheme({ ...config, theme: { components: { launcher: {
+      size: "56px", iconSize: "20px", offset: "32px", background: "#123456", foreground: "#ffffff", shadow: "none",
+    } } } }));
+    expect(custom["--persona-components-launcher-size"]).toBe("56px");
+    expect(custom["--persona-components-launcher-offset"]).toBe("32px");
+    expect(custom["--persona-launcher-bg"]).toBe("#123456");
+    expect(custom["--persona-launcher-shadow"]).toBe("none");
+  });
+});

package/src/runtime/init-update-reset.test.ts

@@ -78,4 +78,25 @@ describe("handle.update explicit-undefined reset reaches the controller", () =>
 
     handle.destroy();
   });
+
+  it("updates the root defaults-version attribute", () => {
+    window.scrollTo = vi.fn();
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false },
+        future: { v5Defaults: false },
+      },
+    });
+    const root = () => document.querySelector<HTMLElement>("[data-persona-root]")!;
+
+    expect(root().getAttribute("data-persona-defaults")).toBe("v4");
+    handle.update({ future: { v5Defaults: true } });
+    expect(root().getAttribute("data-persona-defaults")).toBe("v5");
+
+    handle.destroy();
+  });
 });

package/src/session.ts

@@ -144,6 +144,7 @@ const CONNECTION_CONFIG_KEYS = [
   "getStoredSessionId",
   "setStoredSessionId",
   "getIdentityProof",
+  "identityProvider",
   "getStoredConversationId",
   "setStoredConversationId",
   "clearStoredConversationId",
@@ -909,6 +910,33 @@ export class AgentWidgetSession {
     }
   }
 
+  /**
+   * Warm the voice path ahead of the mic click (`voiceRecognition.prewarm`).
+   * Session-owned providers (`runtype`, `custom`) get `provider.prewarm()` once
+   * the lazy voice runtime has installed them; the browser (Web Speech) path
+   * warms the client-token session instead. Fire-and-forget and silent.
+   */
+  public prewarmVoice(): void {
+    if (!usesSessionVoice(this.config.voiceRecognition?.provider)) {
+      this.warmClientSession();
+      return;
+    }
+    const generation = this.voiceSetupGeneration;
+    const run = () => {
+      const provider = this.voiceProvider;
+      if (!provider?.prewarm || generation !== this.voiceSetupGeneration) return;
+      if (this.voiceActive || this.isBargeInActive()) return;
+      void Promise.resolve()
+        .then(() => provider.prewarm?.())
+        .catch(() => {});
+    };
+    if (!this.voiceProvider && this.voiceSetupPromise) {
+      void this.voiceSetupPromise.then(run, () => {});
+      return;
+    }
+    run();
+  }
+
   /**
    * Cleanup voice resources
    */
@@ -974,7 +1002,9 @@ export class AgentWidgetSession {
             clientToken: providerConfig.runtype?.clientToken ?? this.config.clientToken,
             host: providerConfig.runtype?.host ?? this.config.apiUrl,
             voiceId: providerConfig.runtype?.voiceId,
-            createPlaybackEngine: providerConfig.runtype?.createPlaybackEngine
+            createPlaybackEngine: providerConfig.runtype?.createPlaybackEngine,
+            prewarmMode: providerConfig.runtype?.prewarmMode,
+            attachIdleMs: providerConfig.runtype?.attachIdleMs
           }
         };
       
@@ -1033,12 +1063,29 @@ export class AgentWidgetSession {
     }
   }
 
+  /**
+   * Early, fire-and-forget client-token init (`sessionInit` trigger or
+   * `controller.initSession()`). Failures stay silent here: no `onError`, no
+   * UI. The send re-runs `initSession()` and reports them as it always has.
+   */
+  public warmClientSession(): void {
+    // The visitor may send before this resolves; the server welcome still
+    // belongs ahead of that first turn when the transcript started empty.
+    const pristine = !this.messages.length;
+    void this.client.warmSession().then((session) => {
+      // A start-new or credential re-init may have replaced it meanwhile.
+      if (session && this.client.getClientSession() === session) {
+        this.setClientSession(session, pristine);
+      }
+    });
+  }
+
   /**
    * Set the client session after initialization
    */
-  public setClientSession(session: ClientSession): void {
+  public setClientSession(session: ClientSession, pristine?: boolean): void {
     this.clientSession = session;
-    this.injectWelcomeMessage(session);
+    this.injectWelcomeMessage(session, pristine);
   }
 
   /**
@@ -1046,15 +1093,20 @@ export class AgentWidgetSession {
    * reopening a stored conversation is not a new thread, and the hydrated
    * transcript would otherwise race a welcome bubble.
    */
-  private injectWelcomeMessage(session: ClientSession): void {
+  private injectWelcomeMessage(
+    session: ClientSession,
+    pristine = !this.messages.length
+  ): void {
     if (this.suppressWelcomeInjection) return;
-    if (!session.config.welcomeMessage || this.messages.length !== 0) return;
+    if (!session.config.welcomeMessage || !pristine) return;
+    // A late welcome (the first send raced the init) sorts ahead of that turn.
+    const first = this.messages[0];
     const welcomeMessage: AgentWidgetMessage = {
       id: `welcome-${Date.now()}`,
       role: "assistant",
       content: session.config.welcomeMessage,
-      createdAt: new Date().toISOString(),
-      sequence: this.nextSequence()
+      createdAt: first?.createdAt ?? new Date().toISOString(),
+      sequence: first ? (first.sequence ?? 0) - 1 : this.nextSequence()
     };
     this.appendMessage(welcomeMessage);
   }

package/src/session.voice.test.ts

@@ -13,7 +13,8 @@ const h = vi.hoisted(() => {
       | ((role: 'user' | 'assistant', text: string, isFinal: boolean) => void)
       | null;
     metricsCb: ((m: VoiceMetrics) => void) | null;
-  } = { transcriptCb: null, metricsCb: null };
+    prewarms: number;
+  } = { transcriptCb: null, metricsCb: null, prewarms: 0 };
 
   const fakeProvider = {
     type: 'runtype' as const,
@@ -30,6 +31,9 @@ const h = vi.hoisted(() => {
     onMetrics: (cb: typeof state.metricsCb) => {
       state.metricsCb = cb;
     },
+    prewarm: () => {
+      state.prewarms += 1;
+    },
   };
 
   return { state, fakeProvider };
@@ -212,3 +216,70 @@ describe('AgentWidgetSession - Runtype TTS config', () => {
     }
   });
 });
+
+describe('AgentWidgetSession - prewarmVoice', () => {
+  const callbacks = {
+    onMessagesChanged: () => {},
+    onStatusChanged: () => {},
+    onStreamingChanged: () => {},
+    onError: () => {},
+  };
+  const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+  const runtypeSession = () =>
+    new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:8000',
+        voiceRecognition: {
+          enabled: true,
+          provider: { type: 'runtype', runtype: { agentId: 'a1' } },
+        },
+      },
+      callbacks,
+    );
+
+  beforeEach(() => {
+    h.state.prewarms = 0;
+  });
+
+  it("calls the provider's prewarm once setup has installed it", async () => {
+    const session = runtypeSession();
+    session.setupVoice();
+    await flush();
+    session.prewarmVoice();
+    await flush();
+    expect(h.state.prewarms).toBe(1);
+  });
+
+  it('waits for a setup still loading the voice runtime', async () => {
+    const session = runtypeSession();
+    session.setupVoice();
+    session.prewarmVoice();
+    expect(h.state.prewarms).toBe(0);
+    await flush();
+    expect(h.state.prewarms).toBe(1);
+  });
+
+  it('drops a prewarm whose setup was torn down meanwhile', async () => {
+    const session = runtypeSession();
+    session.setupVoice();
+    session.prewarmVoice();
+    session.cleanupVoice();
+    await flush();
+    expect(h.state.prewarms).toBe(0);
+  });
+
+  it('warms the client session on the browser (Web Speech) path', () => {
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://localhost:8000',
+        clientToken: 'ct_test',
+        voiceRecognition: { enabled: true, provider: { type: 'browser' } },
+      },
+      callbacks,
+    );
+    const warm = vi.spyOn(session, 'warmClientSession').mockImplementation(() => {});
+    session.prewarmVoice();
+    expect(warm).toHaveBeenCalledOnce();
+    expect(h.state.prewarms).toBe(0);
+  });
+});

package/src/styles/widget-styles.test.ts

@@ -189,6 +189,25 @@ describe("suggestion interaction styles", () => {
   });
 });
 
+describe("collapsible widget chrome styles", () => {
+  it("uses prefixed aliases while retaining each legacy alias and literal fallback", () => {
+    const expectedDeclarations: Array<[string, number]> = [
+      ["var(--persona-cw-border, var(--cw-border, #e5e7eb))", 2],
+      ["var(--persona-cw-container, var(--cw-container, #f9fafb))", 1],
+      ["var(--persona-cw-surface, var(--cw-surface, #ffffff))", 2],
+      ["var(--persona-cw-border, var(--cw-border, #f1f5f9))", 1],
+      ["var(--persona-cw-container, var(--cw-container, #f8fafc))", 1],
+      ["var(--persona-cw-border, var(--cw-border, #d1d5db))", 1],
+      ["var(--persona-cw-surface, var(--cw-surface, #fff))", 2],
+    ];
+
+    for (const [declaration, count] of expectedDeclarations) {
+      expect(widgetCss).toContain(declaration);
+      expect(widgetCss.split(declaration).length - 1).toBe(count);
+    }
+  });
+});
+
 describe("composer spacing styles", () => {
   it("themes the composer form padding and gap with utility-matching fallbacks", () => {
     const selector =