@runtypelabs/persona 3.34.1 → 3.35.0

package/src/components/widget-view.test.ts

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import { createWidgetView, resolveLauncher } from "./widget-view";
+import type { HeaderElements } from "./header-builder";
+import type { AgentWidgetConfig } from "../types";
+import type { AgentWidgetPlugin } from "../plugins/types";
+
+describe("createWidgetView: default assembly", () => {
+  const config: AgentWidgetConfig = {
+    apiUrl: "/api",
+    voiceRecognition: { enabled: true, provider: { type: "runtype" } },
+    attachments: { enabled: true },
+  };
+
+  it("groups shell, transcript, header, and composer refs over the real nodes", () => {
+    const view = createWidgetView({ config, showClose: true });
+
+    // Shell. The empty `panel` is wired to the `container` later by ui.ts
+    // (panel.appendChild(container)); createWidgetView preserves that split.
+    expect(view.shell.wrapper.contains(view.shell.panel)).toBe(true);
+    expect(view.shell.pillRoot).toBeUndefined();
+
+    // Transcript subtree is wired by buildPanel
+    expect(view.transcript.container.contains(view.transcript.body)).toBe(true);
+    expect(view.transcript.body.contains(view.transcript.messagesWrapper)).toBe(true);
+
+    // Header + composer are mounted in the container
+    expect(view.transcript.container.contains(view.header.element)).toBe(true);
+    expect(view.transcript.container.contains(view.composer.footer)).toBe(true);
+
+    // Grouped refs are the same nodes as the raw flat panelElements
+    expect(view.composer.textarea).toBe(view.panelElements.textarea);
+    expect(view.composer.footer).toBe(view.panelElements.footer);
+    expect(view.header.element).toBe(view.panelElements.header);
+  });
+
+  it("exposes the stable composer ref attributes", () => {
+    const view = createWidgetView({ config, showClose: true });
+
+    expect(view.composer.textarea.getAttribute("data-persona-composer-input")).toBe("");
+    expect(view.composer.sendButton.getAttribute("data-persona-composer-submit")).toBe("");
+    expect(view.composer.statusText.getAttribute("data-persona-composer-status")).toBe("");
+    expect(view.composer.suggestions.getAttribute("data-persona-composer-suggestions")).toBe("");
+    expect(view.composer.actionsRow.getAttribute("data-persona-composer-actions")).toBe("");
+    expect(view.composer.micButton).not.toBeNull();
+    expect(
+      view.composer.attachmentButton?.getAttribute("data-persona-composer-attachment-button")
+    ).toBe("");
+    expect(
+      view.composer.attachmentInput?.getAttribute("data-persona-composer-attachment-input")
+    ).toBe("");
+    expect(
+      view.composer.attachmentPreviewsContainer?.getAttribute(
+        "data-persona-composer-attachment-previews"
+      )
+    ).toBe("");
+  });
+
+  it("hides header and footer when layout disables them", () => {
+    const view = createWidgetView({
+      config: { apiUrl: "/api", layout: { showHeader: false, showFooter: false } },
+      showClose: true,
+    });
+
+    expect(view.header.element.style.display).toBe("none");
+    expect(view.composer.footer.style.display).toBe("none");
+  });
+});
+
+describe("createWidgetView: composer-bar assembly", () => {
+  const config: AgentWidgetConfig = {
+    apiUrl: "/api",
+    launcher: { mountMode: "composer-bar" },
+  };
+
+  it("exposes the pill root and peek banner", () => {
+    const view = createWidgetView({ config, showClose: true });
+
+    expect(view.shell.pillRoot).toBeInstanceOf(HTMLElement);
+    expect(view.composer.peekBanner).toBeInstanceOf(HTMLElement);
+    expect(view.composer.peekTextNode).toBeInstanceOf(HTMLElement);
+    // Composer-bar uses a hidden placeholder header (close button is the chrome).
+    expect(view.header.element.style.display).toBe("none");
+  });
+});
+
+describe("createWidgetView: replacement helpers", () => {
+  it("replaceHeader swaps the mounted element and mirrors sub-refs", () => {
+    const view = createWidgetView({ config: { apiUrl: "/api" }, showClose: true });
+    const original = view.header.element;
+    const parent = original.parentElement;
+
+    const next: HeaderElements = {
+      header: document.createElement("header"),
+      iconHolder: document.createElement("span"),
+      headerTitle: document.createElement("span"),
+      headerSubtitle: document.createElement("span"),
+      closeButton: document.createElement("button"),
+      closeButtonWrapper: document.createElement("div"),
+      clearChatButton: null,
+      clearChatButtonWrapper: null,
+    };
+
+    const returned = view.replaceHeader(next);
+
+    expect(returned).toBe(next);
+    expect(view.header.element).toBe(next.header);
+    expect(view.header.iconHolder).toBe(next.iconHolder);
+    expect(view.header.closeButton).toBe(next.closeButton);
+    expect(parent?.contains(next.header)).toBe(true);
+    expect(parent?.contains(original)).toBe(false);
+  });
+
+  it("replaceComposer swaps the mounted footer and updates the ref", () => {
+    const view = createWidgetView({ config: { apiUrl: "/api" }, showClose: true });
+    const original = view.composer.footer;
+    const parent = original.parentElement;
+    const nextFooter = document.createElement("div");
+
+    view.replaceComposer(nextFooter);
+
+    expect(view.composer.footer).toBe(nextFooter);
+    expect(parent?.contains(nextFooter)).toBe(true);
+    expect(parent?.contains(original)).toBe(false);
+  });
+});
+
+describe("resolveLauncher", () => {
+  const config: AgentWidgetConfig = { apiUrl: "/api" };
+
+  it("builds the default launcher controller and wires onToggle", () => {
+    const onToggle = vi.fn();
+    const { instance, element } = resolveLauncher({ config, plugins: [], onToggle });
+
+    expect(instance).not.toBeNull();
+    expect(element).toBe(instance?.element);
+    expect(element.tagName).toBe("BUTTON");
+
+    element.dispatchEvent(new Event("click"));
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses a plugin-provided launcher element and returns no controller", () => {
+    const custom = document.createElement("div");
+    custom.id = "custom-launcher";
+    const plugin: AgentWidgetPlugin = {
+      id: "custom",
+      renderLauncher: ({ defaultRenderer }) => {
+        // The default renderer is still callable; the plugin opts to ignore it.
+        expect(defaultRenderer().tagName).toBe("BUTTON");
+        return custom;
+      },
+    };
+
+    const { instance, element } = resolveLauncher({
+      config,
+      plugins: [plugin],
+      onToggle: () => {},
+    });
+
+    expect(instance).toBeNull();
+    expect(element).toBe(custom);
+  });
+
+  it("falls back to the default launcher when the plugin returns null", () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "passthrough",
+      renderLauncher: () => null,
+    };
+
+    const { instance, element } = resolveLauncher({
+      config,
+      plugins: [plugin],
+      onToggle: () => {},
+    });
+
+    expect(instance).not.toBeNull();
+    expect(element).toBe(instance?.element);
+  });
+});

package/src/components/widget-view.ts

@@ -0,0 +1,234 @@
+import { AgentWidgetConfig } from "../types";
+import { AgentWidgetPlugin } from "../plugins/types";
+import { createWrapper, buildPanel, PanelElements } from "./panel";
+import { HeaderElements } from "./header-builder";
+import { createLauncherButton, LauncherButton } from "./launcher";
+
+/**
+ * Widget view assembly layer.
+ *
+ * `ui.ts` owns behavior (session dispatch, streaming, scroll, voice, events);
+ * this module owns the one-time structural assembly of the widget's DOM and
+ * groups the resulting element references into named regions so callers read
+ * `view.composer.textarea` instead of destructuring a ~30-field flat object.
+ *
+ * The grouped refs are a view over the same nodes returned by `buildPanel`;
+ * the raw flat `PanelElements` is still exposed as `view.panelElements` for
+ * incremental migration. No framework, no virtual DOM: these are the real
+ * elements built by the existing `panel.ts` / `composer-*` / `header-*`
+ * builders.
+ */
+
+export interface WidgetShellRefs {
+  wrapper: HTMLElement;
+  panel: HTMLElement;
+  /** Composer-bar mode only: viewport-fixed sibling that owns the pill. */
+  pillRoot?: HTMLElement;
+}
+
+export interface WidgetTranscriptRefs {
+  container: HTMLElement;
+  body: HTMLElement;
+  messagesWrapper: HTMLElement;
+  /** Absolute slot above the composer where interactive sheets mount. */
+  composerOverlay: HTMLElement;
+  introTitle: HTMLElement;
+  introSubtitle: HTMLElement;
+}
+
+export interface WidgetHeaderRefs {
+  /** The header root element currently mounted in the container. */
+  element: HTMLElement;
+  iconHolder: HTMLElement;
+  headerTitle: HTMLElement;
+  headerSubtitle: HTMLElement;
+  closeButton: HTMLButtonElement;
+  closeButtonWrapper: HTMLElement | null;
+  clearChatButton: HTMLButtonElement | null;
+  clearChatButtonWrapper: HTMLElement | null;
+}
+
+export interface WidgetComposerRefs {
+  /** The footer root element currently mounted in the panel. */
+  footer: HTMLElement;
+  form: HTMLFormElement;
+  textarea: HTMLTextAreaElement;
+  sendButton: HTMLButtonElement;
+  sendButtonWrapper: HTMLElement;
+  micButton: HTMLButtonElement | null;
+  micButtonWrapper: HTMLElement | null;
+  statusText: HTMLElement;
+  suggestions: HTMLElement;
+  attachmentButton: HTMLButtonElement | null;
+  attachmentButtonWrapper: HTMLElement | null;
+  attachmentInput: HTMLInputElement | null;
+  attachmentPreviewsContainer: HTMLElement | null;
+  actionsRow: HTMLElement;
+  leftActions: HTMLElement;
+  rightActions: HTMLElement;
+  setSendButtonMode: (mode: "send" | "stop") => void;
+  /** Composer-bar peek banner (undefined for non-composer-bar modes). */
+  peekBanner?: HTMLButtonElement;
+  peekTextNode?: HTMLElement;
+}
+
+export interface WidgetView {
+  shell: WidgetShellRefs;
+  /** Raw flat refs from `buildPanel`, retained for incremental migration. */
+  panelElements: PanelElements;
+  transcript: WidgetTranscriptRefs;
+  header: WidgetHeaderRefs;
+  composer: WidgetComposerRefs;
+  /**
+   * Swap the mounted header element for `next.header` and mirror the header
+   * sub-refs (icon/title/subtitle/close) onto `view.header`. Used by the
+   * header-layout rebuild path. Returns the new `HeaderElements` for the
+   * caller to mirror into its own locals during incremental migration.
+   */
+  replaceHeader: (next: HeaderElements) => HeaderElements;
+  /**
+   * Swap the mounted footer element for `nextFooter` and update
+   * `view.composer.footer`. The remaining composer sub-refs become stale
+   * after a plugin-provided composer replaces the footer; callers re-derive
+   * them from the new footer (see `bindComposerRefsFromFooter` in ui.ts).
+   */
+  replaceComposer: (nextFooter: HTMLElement) => void;
+}
+
+export interface CreateWidgetViewOptions {
+  config: AgentWidgetConfig;
+  /** Whether the panel renders a close affordance (panel is toggleable). */
+  showClose: boolean;
+}
+
+/**
+ * Build the widget shell + panel once and group the element references into
+ * named regions. Equivalent to the previous `createWrapper(config)` +
+ * `buildPanel(config, showClose)` pair, plus the grouping/replacement helpers.
+ */
+export const createWidgetView = ({
+  config,
+  showClose,
+}: CreateWidgetViewOptions): WidgetView => {
+  const { wrapper, panel, pillRoot } = createWrapper(config);
+  const panelElements = buildPanel(config, showClose);
+
+  const shell: WidgetShellRefs = { wrapper, panel, pillRoot };
+
+  const transcript: WidgetTranscriptRefs = {
+    container: panelElements.container,
+    body: panelElements.body,
+    messagesWrapper: panelElements.messagesWrapper,
+    composerOverlay: panelElements.composerOverlay,
+    introTitle: panelElements.introTitle,
+    introSubtitle: panelElements.introSubtitle,
+  };
+
+  const header: WidgetHeaderRefs = {
+    element: panelElements.header,
+    iconHolder: panelElements.iconHolder,
+    headerTitle: panelElements.headerTitle,
+    headerSubtitle: panelElements.headerSubtitle,
+    closeButton: panelElements.closeButton,
+    closeButtonWrapper: panelElements.closeButtonWrapper,
+    clearChatButton: panelElements.clearChatButton,
+    clearChatButtonWrapper: panelElements.clearChatButtonWrapper,
+  };
+
+  const composer: WidgetComposerRefs = {
+    footer: panelElements.footer,
+    form: panelElements.composerForm,
+    textarea: panelElements.textarea,
+    sendButton: panelElements.sendButton,
+    sendButtonWrapper: panelElements.sendButtonWrapper,
+    micButton: panelElements.micButton,
+    micButtonWrapper: panelElements.micButtonWrapper,
+    statusText: panelElements.statusText,
+    suggestions: panelElements.suggestions,
+    attachmentButton: panelElements.attachmentButton,
+    attachmentButtonWrapper: panelElements.attachmentButtonWrapper,
+    attachmentInput: panelElements.attachmentInput,
+    attachmentPreviewsContainer: panelElements.attachmentPreviewsContainer,
+    actionsRow: panelElements.actionsRow,
+    leftActions: panelElements.leftActions,
+    rightActions: panelElements.rightActions,
+    setSendButtonMode: panelElements.setSendButtonMode,
+    peekBanner: panelElements.peekBanner,
+    peekTextNode: panelElements.peekTextNode,
+  };
+
+  const replaceHeader = (next: HeaderElements): HeaderElements => {
+    header.element.replaceWith(next.header);
+    header.element = next.header;
+    header.iconHolder = next.iconHolder;
+    header.headerTitle = next.headerTitle;
+    header.headerSubtitle = next.headerSubtitle;
+    header.closeButton = next.closeButton;
+    header.closeButtonWrapper = next.closeButtonWrapper;
+    header.clearChatButton = next.clearChatButton;
+    header.clearChatButtonWrapper = next.clearChatButtonWrapper;
+    return next;
+  };
+
+  const replaceComposer = (nextFooter: HTMLElement): void => {
+    composer.footer.replaceWith(nextFooter);
+    composer.footer = nextFooter;
+  };
+
+  return {
+    shell,
+    panelElements,
+    transcript,
+    header,
+    composer,
+    replaceHeader,
+    replaceComposer,
+  };
+};
+
+export interface ResolveLauncherOptions {
+  config: AgentWidgetConfig;
+  plugins: AgentWidgetPlugin[];
+  /** Toggles the panel open/closed; wired to the launcher's click. */
+  onToggle: () => void;
+}
+
+export interface ResolvedLauncher {
+  /**
+   * The default launcher controller (with `update`/`destroy`), or null when a
+   * plugin supplied a custom launcher element.
+   */
+  instance: LauncherButton | null;
+  /** The element to mount: either the default button or the plugin's element. */
+  element: HTMLElement;
+}
+
+/**
+ * Resolve the launcher element, honoring a `renderLauncher` plugin if present.
+ * De-duplicates the identical default-or-plugin logic that previously lived at
+ * both the initial-build and re-enable call sites in ui.ts.
+ *
+ * When a plugin returns a custom element, `instance` is null (the plugin owns
+ * its own updates); otherwise the default `LauncherButton` controller is
+ * returned so the caller can drive `update()`/`destroy()`.
+ */
+export const resolveLauncher = ({
+  config,
+  plugins,
+  onToggle,
+}: ResolveLauncherOptions): ResolvedLauncher => {
+  const launcherPlugin = plugins.find((p) => p.renderLauncher);
+  if (launcherPlugin?.renderLauncher) {
+    const customLauncher = launcherPlugin.renderLauncher({
+      config,
+      defaultRenderer: () => createLauncherButton(config, onToggle).element,
+      onToggle,
+    });
+    if (customLauncher) {
+      return { instance: null, element: customLauncher };
+    }
+  }
+
+  const instance = createLauncherButton(config, onToggle);
+  return { instance, element: instance.element };
+};

package/src/defaults.ts

@@ -1,4 +1,4 @@
-import type { AgentWidgetConfig } from "./types";
+import type { AgentWidgetConfig, AgentWidgetLauncherConfig } from "./types";
 import type { DeepPartial, PersonaTheme } from "./types/theme";
 import { deepMerge } from "./utils/deep-merge";
 
@@ -12,6 +12,58 @@ 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";
 
+export const DEFAULT_LAUNCHER_CONFIG: AgentWidgetLauncherConfig = {
+  enabled: true,
+  mountMode: "floating",
+  dock: {
+    side: "right",
+    width: "420px",
+  },
+  title: "Chat Assistant",
+  subtitle: "Here to help you get answers fast",
+  agentIconText: "💬",
+  agentIconName: "bot",
+  headerIconName: "bot",
+  position: "bottom-right",
+  width: DEFAULT_FLOATING_LAUNCHER_WIDTH,
+  heightOffset: 0,
+  autoExpand: false,
+  callToActionIconHidden: false,
+  agentIconSize: "40px",
+  headerIconSize: "40px",
+  closeButtonSize: "32px",
+  // Zero out browser-default <button> padding so the icon gets the full
+  // 32x32 content box, matching clearChat.paddingX/Y below. Without this,
+  // UA stylesheets add ~1-2px vertical and ~6px horizontal padding that
+  // eats into the border-box width and shrinks the rendered icon.
+  closeButtonPaddingX: "0px",
+  closeButtonPaddingY: "0px",
+  callToActionIconName: "arrow-up-right",
+  callToActionIconText: "",
+  callToActionIconSize: "32px",
+  callToActionIconPadding: "5px",
+  callToActionIconColor: undefined,
+  callToActionIconBackgroundColor: undefined,
+  // closeButtonColor / clearChat.iconColor omitted so theme.components.header.actionIconForeground applies.
+  closeButtonBackgroundColor: "transparent",
+  clearChat: {
+    backgroundColor: "transparent",
+    borderColor: "transparent",
+    enabled: true,
+    placement: "inline",
+    iconName: "refresh-cw",
+    size: "32px",
+    showTooltip: true,
+    tooltipText: "Clear chat",
+    paddingX: "0px",
+    paddingY: "0px",
+  },
+  headerIconHidden: false,
+  border: undefined,
+  shadow:
+    "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
+};
+
 /**
  * Default widget configuration
  * Single source of truth for all default values
@@ -23,56 +75,7 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   theme: undefined,
   darkTheme: undefined,
   colorScheme: "light",
-  launcher: {
-    enabled: true,
-    mountMode: "floating",
-    dock: {
-      side: "right",
-      width: "420px",
-    },
-    title: "Chat Assistant",
-    subtitle: "Here to help you get answers fast",
-    agentIconText: "💬",
-    agentIconName: "bot",
-    headerIconName: "bot",
-    position: "bottom-right",
-    width: DEFAULT_FLOATING_LAUNCHER_WIDTH,
-    heightOffset: 0,
-    autoExpand: false,
-    callToActionIconHidden: false,
-    agentIconSize: "40px",
-    headerIconSize: "40px",
-    closeButtonSize: "32px",
-    // Zero out browser-default <button> padding so the icon gets the full
-    // 32x32 content box, matching clearChat.paddingX/Y below. Without this,
-    // UA stylesheets add ~1-2px vertical and ~6px horizontal padding that
-    // eats into the border-box width and shrinks the rendered icon.
-    closeButtonPaddingX: "0px",
-    closeButtonPaddingY: "0px",
-    callToActionIconName: "arrow-up-right",
-    callToActionIconText: "",
-    callToActionIconSize: "32px",
-    callToActionIconPadding: "5px",
-    callToActionIconColor: undefined,
-    callToActionIconBackgroundColor: undefined,
-    // closeButtonColor / clearChat.iconColor omitted so theme.components.header.actionIconForeground applies.
-    closeButtonBackgroundColor: "transparent",
-    clearChat: {
-      backgroundColor: "transparent",
-      borderColor: "transparent",
-      enabled: true,
-      placement: "inline",
-      iconName: "refresh-cw",
-      size: "32px",
-      showTooltip: true,
-      tooltipText: "Clear chat",
-      paddingX: "0px",
-      paddingY: "0px",
-    },
-    headerIconHidden: false,
-    border: undefined,
-    shadow: "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
-  },
+  launcher: DEFAULT_LAUNCHER_CONFIG,
   copy: {
     welcomeTitle: "Hello 👋",
     welcomeSubtitle: "Ask anything about your account or products.",

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

@@ -285,6 +285,7 @@ export type RuntypeFlowSSEEvent = {
   totalSteps?: number;
   type: "flow_start";
 } | {
+  claudeManagedAgentId?: string;
   completedAt?: string;
   completedSteps?: number;
   duration?: number;
@@ -399,6 +400,7 @@ export type RuntypeFlowSSEEvent = {
   toolId: string;
 };
   type: "step_complete";
+  unresolvedVariables?: Array<string>;
 }) | {
   error: string;
   executionId?: string;
@@ -836,6 +838,7 @@ export type RuntypeDispatchSSEEvent = {
   totalSteps?: number;
   type: "flow_start";
 } | {
+  claudeManagedAgentId?: string;
   completedAt?: string;
   completedSteps?: number;
   duration?: number;
@@ -950,6 +953,7 @@ export type RuntypeDispatchSSEEvent = {
   toolId: string;
 };
   type: "step_complete";
+  unresolvedVariables?: Array<string>;
 }) | {
   error: string;
   executionId?: string;
@@ -1253,6 +1257,7 @@ export type RuntypeClientFeedbackRequest = {
   metadata?: Record<string, unknown>;
   rating?: number;
   sessionId: string;
+  token: string;
   type: "upvote" | "downvote" | "copy" | "csat" | "nps";
 };
 

package/src/index-core.ts

@@ -82,7 +82,7 @@ export type {
   AgentWidgetApproval,
   AgentWidgetApprovalConfig,
   AgentWidgetApprovalDecisionOptions,
-  // WebMCP — page-discovered tool consumption
+  // WebMCP: page-discovered tool consumption
   AgentWidgetWebMcpConfig,
   ClientToolDefinition,
   WebMcpConfirmHandler,
@@ -98,6 +98,7 @@ export type {
   EventStreamPayloadRenderContext,
   // Controller event map
   AgentWidgetControllerEventMap,
+  AgentWidgetReadAloudEvent,
   // Ask-user-question (built-in answer-pill sheet) types
   AskUserQuestionPayload,
   AskUserQuestionPrompt,
@@ -245,7 +246,7 @@ export type { AgentWidgetInitHandle };
 export type { AgentWidgetPlugin } from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
-// Stream animation plugin API — lets consumers register custom animations
+// Stream animation plugin API: lets consumers register custom animations
 // that match the built-in surface (typewriter, pop-bubble) and subpath
 // modules (letter-rise, word-fade, wipe, glyph-cycle).
 export {
@@ -263,7 +264,7 @@ export type {
   AgentWidgetStreamAnimationPlaceholder,
 } from "./types";
 
-// Action system types — needed to type the `actionHandlers` / `actionParsers`
+// Action system types: needed to type the `actionHandlers` / `actionParsers`
 // config options and to author custom handlers/parsers.
 export type {
   AgentWidgetActionHandler,
@@ -435,7 +436,32 @@ export type {
   VoiceProvider,
   VoiceResult,
   VoiceStatus,
-  VoiceConfig
+  VoiceConfig,
+  VoiceMetrics,
+  VoicePlaybackEngine,
+  PcmStreamPlayer,
+  AgentWidgetVoiceStatusEvent,
+  ReadAloudState,
+  SpeechEngine,
+  SpeechRequest,
+  SpeechCallbacks
 } from "./types";
 
+export {
+  BrowserSpeechEngine,
+  pickBestVoice,
+  ReadAloudController
+} from "./voice";
+export type {
+  BrowserSpeechEngineOptions,
+  ReadAloudListener,
+  FallbackSpeechEngineOptions
+} from "./voice";
+// RuntypeSpeechEngine + FallbackSpeechEngine ship from the
+// `@runtypelabs/persona/voice-worklet-player` subpath, not here: keeping the
+// hosted read-aloud engine out of the main bundle lets the IIFE/CDN build defer
+// it to the `runtype-tts.js` chunk (loaded only for `provider: 'runtype'`). The
+// blessed way to use it is `textToSpeech: { provider: 'runtype' }` — no import
+// needed.
+
 export default initAgentWidgetFn;