@runtypelabs/persona 4.17.1 → 4.18.0

package/src/history-render.ts

@@ -0,0 +1,325 @@
+/**
+ * History render-hook arbitration (plan D7, "Public rendering customization
+ * contract").
+ *
+ * Lives in CORE, not in the lazy view chunk: plugins must arbitrate before any
+ * chunk-owned DOM exists, and the hook contexts are part of the public package
+ * surface. Only type imports reach into `history-view-entry`, so nothing here
+ * pulls the chunk into the main bundles.
+ *
+ * Arbitration:
+ *   - plugins run in priority order; the first non-null `renderHistoryView` wins
+ *   - null falls back to the default full view, which then applies the first
+ *     non-null header/row/state hook at each slot
+ *   - the full hook's `defaultRenderer()` bypasses only that hook: the default
+ *     view is built and its lower slots still arbitrate, including the same
+ *     plugin's. Hook-kind separation is what prevents recursion.
+ *   - a thrown hook is reported and skipped; the default renderer stands in and
+ *     no history state is lost.
+ *
+ * Contexts are frozen, field-by-field snapshots. The provider, credentials,
+ * proofs, visitor ids, raw responses, and prepared commit/discard never appear:
+ * every action routes back through the view's own operations, which are the
+ * same ones the default DOM invokes.
+ */
+
+import type { AgentWidgetPlugin } from "./plugins/types";
+import type {
+  AgentWidgetConfig,
+  AgentWidgetHistoryRenderActions,
+  AgentWidgetRenderHistoryConversationContext,
+  AgentWidgetRenderHistoryHeaderContext,
+  AgentWidgetRenderHistoryStateContext,
+  AgentWidgetRenderHistoryViewContext,
+  HistoryConversationSummary,
+  HistoryPendingAction,
+  HistoryReturnSurface,
+  ResolvedHistoryPresentation,
+} from "./types";
+import type {
+  HistoryRailSection,
+  HistoryViewHandle,
+  HistoryViewModel,
+  HistoryViewSlotRenderers,
+} from "./history-view-entry";
+
+export interface HistoryRenderSurfaceOptions {
+  plugins: AgentWidgetPlugin[];
+  config: AgentWidgetConfig;
+  getPresentation: () => ResolvedHistoryPresentation;
+  getReturnSurface: () => HistoryReturnSurface;
+  /** Shell close: records the return surface and restores focus. */
+  close: () => void;
+  /**
+   * Builds the default view with the core-owned slots wired in. Invoked once;
+   * `renderDom` starts false so no slot runs before the full hook arbitrates.
+   */
+  createView: (options: {
+    slots: HistoryViewSlotRenderers;
+    renderDom: boolean;
+    onModelChange: () => void;
+    /** Plugin rail sections, for the core to merge behind the config ones. */
+    railSections: HistoryRailSection[];
+  }) => HistoryViewHandle;
+  /** Mount (previous === null) or swap the arbitrated element. */
+  onElementChanged: (next: HTMLElement, previous: HTMLElement | null) => void;
+}
+
+export interface HistoryRenderSurface {
+  readonly view: HistoryViewHandle;
+  /** Currently arbitrated element: the default view, or a plugin's. */
+  readonly element: HTMLElement;
+  /** Re-run arbitration with the current snapshot. Inert after dispose. */
+  requestRender(): void;
+  /** Runs pending cleanups and makes `requestRender()` inert. */
+  dispose(): void;
+}
+
+const warn = (hook: string, error: unknown): void => {
+  // eslint-disable-next-line no-console
+  console.warn(`[persona] ${hook} threw`, error);
+};
+
+/** Frozen shallow copy: a plugin can neither mutate nor retain view state. */
+const frozen = <T extends object>(value: T): T => Object.freeze({ ...value });
+
+/** Field-by-field copy: an unknown provider field can never reach a plugin. */
+const snapshotConversation = (
+  conversation: HistoryConversationSummary
+): HistoryConversationSummary =>
+  Object.freeze({
+    id: conversation.id,
+    title: conversation.title,
+    targetId: conversation.targetId,
+    preview: conversation.preview,
+    messageCount: conversation.messageCount,
+    createdAt: conversation.createdAt,
+    updatedAt: conversation.updatedAt,
+  });
+
+const snapshotPending = (pending: HistoryPendingAction): HistoryPendingAction =>
+  pending ? frozen(pending) : null;
+
+export function createHistoryRenderSurface(
+  options: HistoryRenderSurfaceOptions
+): HistoryRenderSurface {
+  const { plugins, config } = options;
+  let disposed = false;
+  let arbitrating = false;
+  /** The view constructor emits a model signal; nothing may arbitrate yet. */
+  let ready = false;
+  /** Lower-level slots run only when the default view owns the surface. */
+  let slotsActive = false;
+  let element: HTMLElement | null = null;
+  const cleanups: Array<() => void> = [];
+
+  const runCleanups = (): void => {
+    for (const callback of cleanups.splice(0)) {
+      try {
+        callback();
+      } catch (error) {
+        warn("renderHistoryView cleanup", error);
+      }
+    }
+  };
+
+  type SlotHook =
+    | "renderHistoryHeader"
+    | "renderHistoryConversation"
+    | "renderHistoryState";
+
+  /** One first-non-null pass per slot; a throw is reported and skipped. */
+  const arbitrateSlot = <C>(hook: SlotHook, context: C): HTMLElement | null => {
+    for (const plugin of plugins) {
+      const render = plugin[hook] as
+        | ((context: C) => HTMLElement | null)
+        | undefined;
+      if (!render) continue;
+      try {
+        const custom = render(context);
+        if (custom) return custom;
+      } catch (error) {
+        warn(hook, error);
+      }
+    }
+    return null;
+  };
+
+  /** Fields every slot context carries. */
+  const slotBase = (): {
+    presentation: ResolvedHistoryPresentation;
+    config: AgentWidgetConfig;
+  } => ({ presentation: options.getPresentation(), config });
+
+  const slots: HistoryViewSlotRenderers = {
+    header: (slot) =>
+      slotsActive
+        ? arbitrateSlot<AgentWidgetRenderHistoryHeaderContext>(
+            "renderHistoryHeader",
+            Object.freeze({
+              ...slotBase(),
+              returnSurface: options.getReturnSurface(),
+              identityStatus: frozen(slot.identityStatus),
+              pendingAction: snapshotPending(slot.pendingAction),
+              copy: frozen(slot.copy),
+              actions: Object.freeze({
+                close: actions.close,
+                startNewConversation: actions.startNewConversation,
+              }),
+              defaultRenderer: slot.defaultRenderer,
+            })
+          )
+        : null,
+    conversation: (slot) =>
+      slotsActive
+        ? arbitrateSlot<AgentWidgetRenderHistoryConversationContext>(
+            "renderHistoryConversation",
+            Object.freeze({
+              ...slotBase(),
+              conversation: snapshotConversation(slot.conversation),
+              active: slot.active,
+              pending: slot.pending,
+              open: slot.open,
+              requestDelete: slot.requestDelete,
+              defaultRenderer: slot.defaultRenderer,
+            })
+          )
+        : null,
+    state: (slot) =>
+      slotsActive
+        ? arbitrateSlot<AgentWidgetRenderHistoryStateContext>(
+            "renderHistoryState",
+            Object.freeze({
+              ...slotBase(),
+              state: frozen(slot.state),
+              identityStatus: frozen(slot.identityStatus),
+              copy: frozen(slot.copy),
+              ...(slot.retry ? { retry: slot.retry } : {}),
+              ...(slot.startNewConversation
+                ? { startNewConversation: slot.startNewConversation }
+                : {}),
+              defaultRenderer: slot.defaultRenderer,
+            })
+          )
+        : null,
+  };
+
+  /**
+   * Plugin rail sections, in plugin order. Only the context is assembled here;
+   * a throwing `render` is the view's to warn about once and drop. `actions`
+   * resolves at invocation, which never happens before the view owns the DOM.
+   */
+  const railSections: HistoryRailSection[] = plugins.flatMap((plugin) =>
+    (plugin.railSections ?? []).map((section) => ({
+      ...section,
+      placement: section.placement ?? "above-conversations",
+      items: [],
+      render: (collapsed: boolean) =>
+        section.render(
+          Object.freeze({
+            collapsed,
+            presentation: options.getPresentation(),
+            actions,
+          })
+        ),
+    }))
+  );
+
+  const view = options.createView({
+    slots,
+    renderDom: false,
+    onModelChange: () => requestRender(),
+    railSections,
+  });
+
+  /** Every action IS the operation the default DOM invokes; close is the shell's. */
+  const actions: AgentWidgetHistoryRenderActions = Object.freeze({
+    ...view.operations,
+    close: options.close,
+  });
+
+  /** Builds (and renders) the default view; lower slots arbitrate from here on. */
+  const buildDefault = (): HTMLElement => {
+    slotsActive = true;
+    view.setDomRenderEnabled(true);
+    return view.element;
+  };
+
+  const buildViewContext = (
+    model: HistoryViewModel
+  ): AgentWidgetRenderHistoryViewContext =>
+    Object.freeze({
+      conversations: Object.freeze(
+        model.conversations.map(snapshotConversation)
+      ),
+      activeConversationId: model.activeConversationId,
+      state: frozen(model.state),
+      pendingAction: snapshotPending(model.pendingAction),
+      identityStatus: frozen(model.identityStatus),
+      nextCursor: model.nextCursor,
+      presentation: options.getPresentation(),
+      returnSurface: options.getReturnSurface(),
+      config,
+      copy: frozen(view.copy),
+      actions,
+      defaultRenderer: buildDefault,
+      requestRender: () => requestRender(),
+      onCleanup: (callback: () => void) => {
+        cleanups.push(callback);
+      },
+    });
+
+  const arbitrate = (): HTMLElement => {
+    slotsActive = false;
+    let custom: HTMLElement | null = null;
+    for (const plugin of plugins) {
+      if (!plugin.renderHistoryView) continue;
+      try {
+        custom = plugin.renderHistoryView(buildViewContext(view.getModel()));
+      } catch (error) {
+        warn("renderHistoryView", error);
+        custom = null;
+      }
+      if (custom) break;
+    }
+    // Returning the default view (or a wrapper around it) is composition, not
+    // a takeover: it keeps rendering and its slots keep arbitrating.
+    // `contains` is true for the node itself, so this covers a plain return.
+    const usesDefault = !custom || custom.contains(view.element);
+    slotsActive = usesDefault;
+    view.setDomRenderEnabled(usesDefault);
+    return custom ?? view.element;
+  };
+
+  function requestRender(): void {
+    // A hook calling requestRender() from inside its own render would recurse.
+    if (!ready || disposed || arbitrating) return;
+    arbitrating = true;
+    try {
+      // Cleanups belong to the render being replaced, so they run first.
+      runCleanups();
+      const next = arbitrate();
+      if (next === element) return;
+      const previous = element;
+      element = next;
+      options.onElementChanged(next, previous);
+    } finally {
+      arbitrating = false;
+    }
+  }
+
+  ready = true;
+  requestRender();
+
+  return {
+    view,
+    get element() {
+      return element ?? view.element;
+    },
+    requestRender,
+    dispose: () => {
+      disposed = true;
+      runCleanups();
+    },
+  };
+}

package/src/history-view-bundle.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Bundle guard for the lazy history-view chunk (see
+ * `docs/visitor-history-implementation-plan.md` D7, Bundle size).
+ *
+ * The Messages view must NOT land in ANY core bundle shipped to consumers —
+ * neither the CDN IIFE (`dist/index.global.js`) nor the ESM/CJS bundles
+ * (`dist/index.js` / `dist/index.cjs`). It ships as the sibling chunk
+ * `dist/history-view.{js,cjs}`, loaded on demand: the IIFE via a sibling URL,
+ * ESM/CJS via the external `@runtypelabs/persona/history-view` subpath. A stray
+ * static import would pull the view back in; this fails then.
+ *
+ * Rejected-load retry (the other half of the transport contract) is covered by
+ * `history-view-loader.test.ts`.
+ *
+ * Skips when `dist/` hasn't been built (e.g. a test-only CI step).
+ */
+const dist = (f: string) => resolve(__dirname, "..", "dist", f);
+
+// Chunk-only literals. `persona-history-view` is the view's root class and is
+// never emitted by core code; the sibling-URL stub in the core bundles is the
+// bare filename `history-view.js`, which does not contain these.
+const RUNTIME_MARKERS = ["persona-history-view", "persona-history-view-loading"];
+
+const SUBPATH = "@runtypelabs/persona/history-view";
+
+describe("history-view bundle split", () => {
+  const iifeBuilt =
+    existsSync(dist("index.global.js")) && existsSync(dist("history-view.js"));
+  const esmBuilt = existsSync(dist("index.js")) && existsSync(dist("index.cjs"));
+
+  it.runIf(iifeBuilt)("keeps the history view OUT of the core IIFE bundle", () => {
+    const core = readFileSync(dist("index.global.js"), "utf8");
+    for (const marker of RUNTIME_MARKERS) {
+      expect(core.includes(marker), `IIFE bundle unexpectedly contains "${marker}"`).toBe(
+        false
+      );
+    }
+    // The loader stub (sibling-URL reference) must remain so the chunk can load.
+    expect(core).toContain("history-view.js");
+  });
+
+  it.runIf(esmBuilt)("keeps the history view OUT of the ESM/CJS bundles", () => {
+    for (const file of ["index.js", "index.cjs"]) {
+      const core = readFileSync(dist(file), "utf8");
+      for (const marker of RUNTIME_MARKERS) {
+        expect(core.includes(marker), `${file} unexpectedly contains "${marker}"`).toBe(
+          false
+        );
+      }
+      // TODO(history-ui): the ESM/CJS core only reaches the loader once `ui.ts`
+      // mounts the view, so today these bundles carry no history reference at
+      // all. The invariant asserted meanwhile — and automatically once the UI
+      // lands — is that any reference goes through the external subpath rather
+      // than an inlined relative import.
+      if (core.includes("history-view")) {
+        expect(
+          core.includes(SUBPATH),
+          `${file} must reach the view via the external subpath`
+        ).toBe(true);
+      }
+    }
+  });
+
+  it.runIf(iifeBuilt)("ships the history view in the sibling chunk", () => {
+    const chunk = readFileSync(dist("history-view.js"), "utf8");
+    for (const marker of RUNTIME_MARKERS) {
+      expect(chunk.includes(marker), `chunk is missing "${marker}"`).toBe(true);
+    }
+    // A CJS twin exists for require()-based consumers.
+    expect(existsSync(dist("history-view.cjs"))).toBe(true);
+    // Declarations ship with the chunk so the subpath is typed.
+    expect(existsSync(dist("history-view.d.ts"))).toBe(true);
+  });
+});

package/src/history-view-entry.ts

@@ -0,0 +1,41 @@
+/**
+ * History-view runtime entry — the module that assembles the lazily loaded
+ * Messages surface. It is NEVER statically imported on the core path: the
+ * IIFE/CDN build marks `@runtypelabs/persona/history-view` external
+ * (`tsup.global.config.ts`) and loads the standalone `history-view.js` chunk
+ * from a sibling URL on first open of the history UI. The core reaches it
+ * through `history-view-loader.ts`.
+ *
+ * Mirrors `context-mentions-entry.ts`; see
+ * `docs/visitor-history-implementation-plan.md` D7 (Bundle size).
+ */
+
+export { createHistoryView } from "./components/history-view";
+export type {
+  HistoryViewOptions,
+  HistoryViewHandle,
+  HistoryViewPresentation,
+  HistoryHeaderPlacement,
+  HistoryViewPendingAction,
+  HistoryViewModel,
+  HistoryViewOperations,
+  HistoryRailSection,
+  HistoryRailSectionItem,
+  HistoryRailSectionPlacement,
+  HistoryViewSlotRenderers,
+  HistoryHeaderSlotContext,
+  HistoryConversationSlotContext,
+  HistoryStateSlotContext,
+} from "./components/history-view";
+export {
+  HISTORY_VIEW_COPY_DEFAULTS,
+  resolveHistoryViewCopy,
+} from "./components/history-view/copy";
+export type {
+  HistoryViewCopyInput,
+  ResolvedHistoryViewCopy,
+} from "./components/history-view/copy";
+export type {
+  HistoryListState,
+  HistoryListErrorReason,
+} from "./components/history-view/state";

package/src/history-view-loader.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  loadHistoryView,
+  setHistoryViewLoader,
+  type HistoryViewModule,
+} from "./history-view-loader";
+
+const fakeModule = {
+  createHistoryView: vi.fn(),
+} as unknown as HistoryViewModule;
+
+describe("loadHistoryView", () => {
+  it("retries after a rejected load instead of caching the failure forever", async () => {
+    const loader = vi
+      .fn<() => Promise<HistoryViewModule>>()
+      .mockRejectedValueOnce(new Error("network"))
+      .mockResolvedValueOnce(fakeModule);
+    setHistoryViewLoader(loader);
+
+    // First call surfaces the rejection to the caller.
+    await expect(loadHistoryView()).rejects.toThrow("network");
+    // A later call retries (the failed promise was not cached) and resolves.
+    await expect(loadHistoryView()).resolves.toBe(fakeModule);
+    expect(loader).toHaveBeenCalledTimes(2);
+
+    // Once resolved, the module is cached (no third loader call).
+    await expect(loadHistoryView()).resolves.toBe(fakeModule);
+    expect(loader).toHaveBeenCalledTimes(2);
+  });
+});

package/src/history-view-loader.ts

@@ -0,0 +1,32 @@
+/**
+ * Loader indirection for the lazy history-view chunk (core bundle, tiny).
+ *
+ * Mirrors `context-mentions-loader.ts`: the IIFE/CDN entry (`index-global.ts`)
+ * registers a loader that imports the standalone `history-view.js` chunk from a
+ * sibling URL. ESM/CJS consumers fall back to importing the package's
+ * `./history-view` subpath — which `build:client` marks external, so the view is
+ * NOT inlined into `dist/index.{js,cjs}` and stays out of the core bundle until
+ * the history UI is first opened. (A relative `./history-view-entry` import
+ * would be inlined by the `--splitting false` build, defeating the split.)
+ */
+
+import { createChunkLoader } from "./utils/chunk-loader";
+import type {
+  HistoryViewOptions,
+  HistoryViewHandle,
+} from "./history-view-entry";
+
+export type HistoryViewModule = {
+  createHistoryView: (options: HistoryViewOptions) => HistoryViewHandle;
+};
+
+// IIFE/CDN: sibling-URL chunk via the registered loader.
+// ESM/CJS fallback: the package's own `./history-view` subpath (external, so the
+// runtime chunk is code-split out of dist/index.{js,cjs} rather than inlined).
+// Memoization + rejection-retry semantics live in `createChunkLoader`.
+const { setLoader, load } = createChunkLoader<HistoryViewModule>({
+  fallbackImport: () => import("@runtypelabs/persona/history-view"),
+});
+
+export const setHistoryViewLoader = setLoader;
+export const loadHistoryView = load;

package/src/history-view.ts

@@ -0,0 +1,28 @@
+/**
+ * Standalone history-view chunk (`dist/history-view.js`).
+ *
+ * The IIFE/CDN widget bundle marks `@runtypelabs/persona/history-view` external
+ * so the Messages surface is excluded from the core payload; this file is built
+ * as a self-contained sibling chunk (`tsup.history-view.config.ts`) and loaded on
+ * demand by the loader registered in `index-global.ts`. ESM/CJS consumers reach
+ * it via this same (external) subpath.
+ *
+ * Lazy-runtime transport entry only: exports are limited to the mount contract
+ * the loader needs, NOT the public history provider/controller seam.
+ */
+
+export { createHistoryView } from "./history-view-entry";
+export {
+  HISTORY_VIEW_COPY_DEFAULTS,
+  resolveHistoryViewCopy,
+} from "./history-view-entry";
+export type {
+  HistoryViewOptions,
+  HistoryViewHandle,
+  HistoryViewPresentation,
+  HistoryViewPendingAction,
+  HistoryViewCopyInput,
+  ResolvedHistoryViewCopy,
+  HistoryListState,
+  HistoryListErrorReason,
+} from "./history-view-entry";

package/src/index-core.ts

@@ -32,6 +32,7 @@ export type {
   AgentWidgetMessage,
   AgentWidgetLauncherConfig,
   AgentWidgetLauncherTeaserConfig,
+  AgentWidgetTooltipConfig,
   AgentWidgetDockConfig,
   AgentWidgetEvent,
   AgentWidgetStreamParser,
@@ -93,6 +94,7 @@ export type {
   // Client token types
   ClientSession,
   ClientInitResponse,
+  PreparedClientSession,
   ClientChatRequest,
   ClientFeedbackRequest,
   ClientFeedbackType,
@@ -142,6 +144,30 @@ export type {
   AskUserQuestionOption,
   AgentWidgetAskUserQuestionFeature,
   AgentWidgetAskUserQuestionStyles,
+  // Visitor conversation history (client-token mode) types
+  AgentWidgetHistoryFeature,
+  AgentWidgetHistoryListAction,
+  AgentWidgetHistoryCopy,
+  HistoryScope,
+  HistoryIdentityStatus,
+  ResolvedHistoryPresentation,
+  HistoryReturnSurface,
+  HistoryConversationSummary,
+  HistoryConversationPatch,
+  HistoryConversationPage,
+  HistoryConversationDetail,
+  HistoryDisplayProjection,
+  // History rendering customization (plugin render hooks; types only)
+  ResolvedHistoryCopy,
+  HistoryViewState,
+  HistoryPendingAction,
+  AgentWidgetHistoryRenderActions,
+  AgentWidgetRenderHistoryViewContext,
+  AgentWidgetRenderHistoryHeaderContext,
+  AgentWidgetRenderHistoryConversationContext,
+  AgentWidgetRenderHistoryStateContext,
+  AgentWidgetRenderHistoryOpenErrorContext,
+  ClientVisitorGrant,
   AgentWidgetSuggestion,
   AgentWidgetSuggestionChipsConfig,
   AgentWidgetResolvedSuggestion,
@@ -159,6 +185,26 @@ export type {
   AgentWidgetWelcomeDismiss
 } from "./types";
 
+// Custom conversation-history backends (`features.history.provider`). The
+// provider registry beside this module stays private.
+export type {
+  HistoryProvider,
+  HistoryOperationContext,
+  PreparedHistoryActivation,
+  HistoryListOptions,
+  HistoryListResult,
+  HistoryPageOptions,
+  HistoryPageResult,
+  HistoryDeleteAllOptions,
+  HistoryProviderErrorCode,
+} from "./internal/history-provider";
+
+// Value export: custom providers construct and `instanceof` this.
+export {
+  HistoryProviderError,
+  isHistoryProviderError,
+} from "./internal/history-provider";
+
 export {
   applyFeaturePreferences,
   parseWidgetPreferenceSlice,
@@ -347,7 +393,9 @@ export type {
   AgentWidgetTransformSuggestionsContext,
   AgentWidgetRenderSuggestionContext,
   AgentWidgetRenderWelcomeContext,
-  AgentWidgetSuggestionSelectContext
+  AgentWidgetSuggestionSelectContext,
+  AgentWidgetRailSection,
+  AgentWidgetRailSectionContext
 } from "./plugins/types";
 // Welcome resolver: `renderWelcome` receives the resolved shape.
 export { resolveWelcomeConfig, isWelcomeVisible } from "./welcome";
@@ -398,7 +446,7 @@ export { renderLucideIcon } from "./utils/icons";
 export type { IconName } from "./utils/icons";
 
 // Button utility exports
-export { createIconButton, createLabelButton, createToggleGroup, createComboButton } from "./utils/buttons";
+export { createIconButton, createLabelButton, createToggleGroup, createComboButton, createSplitButton } from "./utils/buttons";
 export type {
   CreateIconButtonOptions,
   CreateLabelButtonOptions,

package/src/index-global.ts

@@ -188,3 +188,58 @@ setContextMentionsInlineLoader(() => {
   }
   return import(/* @vite-ignore */ chunkUrl);
 });
+
+// ---------------------------------------------------------------------------
+// Deferred history-view loading.
+//
+// This bundle is built with `@runtypelabs/persona/history-view` external (see
+// `tsup.global.config.ts`): the Messages navigation surface is kept out of the
+// CDN payload and fetched only when the visitor first opens history. Same
+// sibling-URL scheme as the chunks above.
+// ---------------------------------------------------------------------------
+
+import { setHistoryViewLoader } from "./history-view-loader";
+
+setHistoryViewLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "history-view.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the history-view.js URL from the widget script URL " +
+          `(${widgetScriptSrc ?? "unavailable"}). Self-hosted deployments that ` +
+          "rename index.global.js should host history-view.js alongside it.",
+      ),
+    );
+  }
+  return import(/* @vite-ignore */ chunkUrl);
+});
+
+// ---------------------------------------------------------------------------
+// Deferred event-stream-view loading.
+//
+// Same scheme as history-view: `@runtypelabs/persona/event-stream-view` is
+// external here (see `tsup.global.config.ts`), and the observability panel is
+// fetched from a sibling URL only when the visitor first opens it.
+// ---------------------------------------------------------------------------
+
+import { setEventStreamViewLoader } from "./event-stream-view-loader";
+
+setEventStreamViewLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "event-stream-view.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the event-stream-view.js URL from the widget script URL " +
+          `(${widgetScriptSrc ?? "unavailable"}). Self-hosted deployments that ` +
+          "rename index.global.js should host event-stream-view.js alongside it.",
+      ),
+    );
+  }
+  return import(/* @vite-ignore */ chunkUrl);
+});