@runtypelabs/persona 4.17.0 → 4.18.0

package/src/components/launcher-surface.test.ts

@@ -1,7 +1,12 @@
 // @vitest-environment jsdom
 
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createLauncherSurface } from "./launcher";
+import { mount as mountCriticalLauncher } from "../launcher-global";
+import { createAgentExperience } from "../ui";
 import type {
   AgentWidgetConfig,
   AgentWidgetLauncherTeaserConfig,
@@ -401,3 +406,131 @@ describe("createLauncherSurface", () => {
     expect(document.body.children.length).toBe(0);
   });
 });
+
+/**
+ * The deferred install paints the launcher from the critical bundle and swaps
+ * to the full widget on first click, so any glyph styling must reach both
+ * surfaces from the one stylesheet or the swap flickers.
+ */
+describe("launcher icon stroke parity", () => {
+  // jsdom leaves `import.meta.url` an http URL, so resolve from the package root.
+  const widgetCss = readFileSync(
+    resolve(process.cwd(), "src/styles/widget.css"),
+    "utf8"
+  );
+  // The SHIPPED selector, read back out of widget.css by its declaration, so
+  // a rescope of the real rule fails here instead of slipping past a
+  // hardcoded copy of the selector.
+  const strokeDeclarationAt = widgetCss.indexOf(
+    "stroke-width: var(--persona-components-launcher-iconStrokeWidth, 1.5)"
+  );
+  const strokeSelectorStart = widgetCss.lastIndexOf("}", strokeDeclarationAt) + 1;
+  const STROKE_RULE = widgetCss
+    .slice(strokeSelectorStart, widgetCss.indexOf("{", strokeSelectorStart))
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .trim();
+
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("renders one glyph the shared stroke rule reaches from both surfaces", () => {
+    const config = {
+      apiUrl: "https://api.example.com/chat",
+      persistState: { keyPrefix: nextPrefix() },
+      launcher: {
+        agentIconName: "message-circle",
+        callToActionIconName: "arrow-up-right",
+      },
+    };
+
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const controller = createAgentExperience(host, config);
+
+    const criticalTarget = document.createElement("div");
+    document.body.appendChild(criticalTarget);
+    const critical = mountCriticalLauncher({
+      target: criticalTarget,
+      config,
+      onOpen: () => {},
+    });
+
+    const iconSvg = "[data-role='launcher-icon'] > svg";
+    const eager = host.querySelector<SVGElement>(iconSvg);
+    const deferred = criticalTarget.querySelector<SVGElement>(iconSvg);
+
+    expect(eager).not.toBeNull();
+    expect(deferred).not.toBeNull();
+    expect(deferred!.outerHTML).toBe(eager!.outerHTML);
+    // matches() resolves the descendant combinator against each surface's own
+    // ancestors, and STROKE_RULE is the selector parsed from widget.css, so
+    // this proves the shipped rule selects the glyph in both surfaces.
+    expect(eager!.matches(STROKE_RULE)).toBe(true);
+    expect(deferred!.matches(STROKE_RULE)).toBe(true);
+
+    // One pill, one line weight: the call-to-action arrow follows the same
+    // rule as the agent glyph on both surfaces.
+    const ctaSvg = "[data-role='launcher-call-to-action-icon'] > svg";
+    const eagerCta = host.querySelector<SVGElement>(ctaSvg);
+    const deferredCta = criticalTarget.querySelector<SVGElement>(ctaSvg);
+    expect(eagerCta).not.toBeNull();
+    expect(deferredCta).not.toBeNull();
+    expect(eagerCta!.matches(STROKE_RULE)).toBe(true);
+    expect(deferredCta!.matches(STROKE_RULE)).toBe(true);
+
+    critical.destroy();
+    controller.destroy();
+  });
+
+  it("emits the stroke token onto both surfaces' roots", () => {
+    const config = {
+      apiUrl: "https://api.example.com/chat",
+      persistState: { keyPrefix: nextPrefix() },
+      launcher: { agentIconName: "message-circle" },
+      theme: { components: { launcher: { iconStrokeWidth: "1.25" } } },
+    };
+
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const controller = createAgentExperience(host, config);
+
+    const criticalTarget = document.createElement("div");
+    document.body.appendChild(criticalTarget);
+    const critical = mountCriticalLauncher({
+      target: criticalTarget,
+      config,
+      onOpen: () => {},
+    });
+
+    // The theme plumbing is duplicated across the two bundles; this is the
+    // claim that breaks if they diverge.
+    const fullRoot = host.hasAttribute("data-persona-root")
+      ? host
+      : host.querySelector<HTMLElement>("[data-persona-root]");
+    const criticalRoot = criticalTarget.querySelector<HTMLElement>(
+      "[data-persona-root]"
+    );
+    expect(fullRoot).not.toBeNull();
+    expect(criticalRoot).not.toBeNull();
+    expect(
+      fullRoot!.style.getPropertyValue(
+        "--persona-components-launcher-iconStrokeWidth"
+      )
+    ).toBe("1.25");
+    expect(
+      criticalRoot!.style.getPropertyValue(
+        "--persona-components-launcher-iconStrokeWidth"
+      )
+    ).toBe("1.25");
+
+    critical.destroy();
+    controller.destroy();
+  });
+});

package/src/components/launcher.test.ts

@@ -16,6 +16,24 @@ describe("createLauncherButton", () => {
     element.remove();
   });
 
+  it("renders the pill from launcher-specific theme vars", () => {
+    const { element, update } = createLauncherButton(undefined, () => {});
+    update({});
+    expect(element.classList.contains("persona-bg-persona-launcher")).toBe(true);
+    expect(
+      element
+        .querySelector("[data-role='launcher-title']")
+        ?.classList.contains("persona-text-persona-launcher")
+    ).toBe(true);
+    expect(
+      element
+        .querySelector("[data-role='launcher-subtitle']")
+        ?.classList.contains("persona-text-persona-launcher-muted")
+    ).toBe(true);
+    expect(element.style.border).toContain("--persona-launcher-border");
+    element.remove();
+  });
+
   it("applies collapsedMaxWidth when set", () => {
     const { element, update } = createLauncherButton(undefined, () => {});
     update({

package/src/components/launcher.ts

@@ -21,8 +21,8 @@ export const createLauncherButton = (
     <span class="persona-inline-flex persona-items-center persona-justify-center persona-rounded-full persona-bg-persona-primary persona-text-white" data-role="launcher-icon">💬</span>
     <img data-role="launcher-image" class="persona-rounded-full persona-object-cover" alt="" style="display:none" />
     <span class="persona-flex persona-min-w-0 persona-flex-1 persona-flex-col persona-items-start persona-text-left">
-      <span class="persona-block persona-w-full persona-truncate persona-text-sm persona-font-semibold persona-text-persona-primary" data-role="launcher-title"></span>
-      <span class="persona-block persona-w-full persona-truncate persona-text-xs persona-text-persona-muted" data-role="launcher-subtitle"></span>
+      <span class="persona-block persona-w-full persona-truncate persona-text-sm persona-font-semibold persona-text-persona-launcher" data-role="launcher-title"></span>
+      <span class="persona-block persona-w-full persona-truncate persona-text-xs persona-text-persona-launcher-muted" data-role="launcher-subtitle"></span>
     </span>
     <span class="persona-ml-2 persona-grid persona-place-items-center persona-rounded-full persona-bg-persona-primary persona-text-persona-call-to-action" data-role="launcher-call-to-action-icon">↗</span>
   `;
@@ -82,7 +82,7 @@ export const createLauncherButton = (
         if (launcher.agentIconName) {
           // Use Lucide icon
           const iconSizeNum = parseFloat(iconSize) || 24;
-          const iconSvg = renderLucideIcon(launcher.agentIconName, iconSizeNum * 0.6, "var(--persona-text-inverse, #ffffff)", 2);
+          const iconSvg = renderLucideIcon(launcher.agentIconName, iconSizeNum * 0.6, "var(--persona-text-inverse, #ffffff)", 1.5);
           if (iconSvg) {
             icon.appendChild(iconSvg);
             icon.style.display = "";
@@ -166,7 +166,7 @@ export const createLauncherButton = (
           // Calculate actual icon size by subtracting padding
           const containerSize = parseFloat(callToActionIconSize) || 24;
           const iconSize = Math.max(containerSize - paddingTotal, 8); // Ensure minimum size of 8px
-          const iconSvg = renderLucideIcon(launcher.callToActionIconName, iconSize, "currentColor", 2);
+          const iconSvg = renderLucideIcon(launcher.callToActionIconName, iconSize, "currentColor", 1.5);
           if (iconSvg) {
             callToActionIconEl.appendChild(iconSvg);
           } else {
@@ -185,9 +185,9 @@ export const createLauncherButton = (
         : positionMap["bottom-right"];
 
     const floatingBase =
-      "persona-fixed persona-flex persona-items-center persona-gap-3 persona-rounded-launcher persona-bg-persona-surface persona-py-2.5 persona-pl-3 persona-pr-3 persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
+      "persona-fixed persona-flex persona-items-center persona-gap-3 persona-rounded-launcher persona-bg-persona-launcher persona-py-2.5 persona-pl-3 persona-pr-3 persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
     const dockedBase =
-      "persona-relative persona-mt-4 persona-mb-4 persona-mx-auto persona-flex persona-items-center persona-justify-center persona-rounded-launcher persona-bg-persona-surface persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
+      "persona-relative persona-mt-4 persona-mb-4 persona-mx-auto persona-flex persona-items-center persona-justify-center persona-rounded-launcher persona-bg-persona-launcher persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
 
     button.className = dockedMode ? dockedBase : `${floatingBase} ${positionClass}`;
 
@@ -196,7 +196,7 @@ export const createLauncherButton = (
     }
 
     // Apply launcher border and shadow from config (with defaults matching previous Tailwind classes)
-    const defaultBorder = "1px solid var(--persona-border, #e5e7eb)";
+    const defaultBorder = "1px solid var(--persona-launcher-border, var(--persona-border, #e5e7eb))";
     const defaultShadow = "var(--persona-launcher-shadow, 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1))";
 
     button.style.border = launcher.border ?? defaultBorder;

package/src/components/panel.ts

@@ -21,6 +21,16 @@ import {
 import { isWelcomeVisible, resolveWelcomeConfig } from "../welcome";
 import { resolveContentMaxWidth } from "../utils/content-width";
 
+/**
+ * Composer-bar chrome sizes. Not header controls: these float over the
+ * composer, so they opt out of the header control-size token with explicit
+ * per-control overrides. `CLOSE_ICON_SIZE` is the X's nominal size before the
+ * factory's sparse-viewBox compensation (10 x 1.4 = the rendered 14px).
+ */
+export const COMPOSER_BAR_CONTROL_SIZE = "16px";
+export const COMPOSER_BAR_CLOSE_ICON_SIZE = "10px";
+export const COMPOSER_BAR_CLEAR_CHAT_ICON_SIZE = "14px";
+
 export interface PanelWrapper {
   wrapper: HTMLElement;
   panel: HTMLElement;
@@ -257,16 +267,16 @@ const buildComposerBarPanel = (
   // Minimal header: just an absolutely-positioned close button.
   // The wrapper uses inline styles (top/right/z-index values) because the
   // widget's hand-authored CSS doesn't ship every Tailwind utility.
-  // Composer-bar's defaults are roughly half the floating-launcher's
-  // (button 16px, icon 14px) to match the minimal aesthetic; the user can
-  // still override via `launcher.closeButtonSize`.
+  // Composer-bar's close is a 16px box, far below the header control token,
+  // to match the minimal aesthetic; the user can still override via
+  // `launcher.closeButtonSize`.
   const { button: closeButton, wrapper: closeButtonWrapper } = createCloseButton(
     config,
     {
       showClose,
       wrapperClassName: "persona-composer-bar-close",
-      buttonSize: "16px",
-      iconSize: "14px",
+      buttonSize: COMPOSER_BAR_CONTROL_SIZE,
+      iconSize: COMPOSER_BAR_CLOSE_ICON_SIZE,
     }
   );
   closeButtonWrapper.style.position = "absolute";
@@ -288,8 +298,8 @@ const buildComposerBarPanel = (
   if (clearChatEnabled) {
     const parts = createClearChatButton(config, {
       wrapperClassName: "persona-composer-bar-clear-chat",
-      buttonSize: "16px",
-      iconSize: "14px",
+      buttonSize: COMPOSER_BAR_CONTROL_SIZE,
+      iconSize: COMPOSER_BAR_CLEAR_CHAT_ICON_SIZE,
     });
     clearChatButton = parts.button;
     clearChatButtonWrapper = parts.wrapper;

package/src/components/welcome.ts

@@ -285,12 +285,79 @@ export const animateWelcomeOut = (
     onFinished(null);
     return null;
   }
+  // Collapse layout in the SAME motion as the fade. The default welcome is
+  // in-flow above the transcript (unlike plugin welcomes, which overlay it),
+  // so an opacity-only exit would hold the hero's height for the whole fade
+  // and then release it in one frame at the hidden flip — the first message
+  // renders below the hero, then teleports to the top when the repin lands.
+  //
+  // Height alone is not enough: the hero centers itself with auto margins,
+  // and auto margins absorb whatever the height collapse frees, so the
+  // transcript below would still not move until the flip. The margins'
+  // USED values are measured from geometry (computed style reports the
+  // keyword, not pixels, for flex auto margins) and animated to zero in the
+  // same keyframes, with a negative end margin canceling the host's flex gap
+  // slot — the transcript slides up continuously and the hidden flip at the
+  // end changes nothing the eye can see.
+  const rect = host.getBoundingClientRect();
+  const parent = host.parentElement;
+  let gap = 0;
+  let usedMarginTop = 0;
+  let usedMarginBottom = 0;
+  if (parent) {
+    const parentStyle = getComputedStyle(parent);
+    gap = parseFloat(parentStyle.rowGap) || 0;
+    const prev = host.previousElementSibling;
+    const next = host.nextElementSibling;
+    const parentRect = parent.getBoundingClientRect();
+    const contentTop =
+      parentRect.top +
+      (parseFloat(parentStyle.borderTopWidth) || 0) +
+      (parseFloat(parentStyle.paddingTop) || 0) -
+      parent.scrollTop;
+    usedMarginTop = Math.max(
+      0,
+      prev
+        ? rect.top - prev.getBoundingClientRect().bottom - gap
+        : rect.top - contentTop
+    );
+    usedMarginBottom = Math.max(
+      0,
+      next ? next.getBoundingClientRect().top - rect.bottom - gap : 0
+    );
+  }
+  const previousOverflow = host.style.overflow;
+  host.style.overflow = "hidden";
+  // Padding collapses with the height: under border-box sizing a height of
+  // zero clamps at the vertical padding, which would leave a padding-tall
+  // remnant releasing in one frame at the flip.
+  const hostStyle = getComputedStyle(host);
+  const paddingTop = parseFloat(hostStyle.paddingTop) || 0;
+  const paddingBottom = parseFloat(hostStyle.paddingBottom) || 0;
   // `forwards`, not `backwards`: backwards only fills the delay phase, so the
   // element snaps back to opacity 1 for a frame after the keyframes end.
   const animation = host.animate(
     [
-      { opacity: "1", transform: "none" },
-      { opacity: "0", transform: "translateY(-4px)" },
+      {
+        opacity: "1",
+        transform: "none",
+        height: `${rect.height}px`,
+        minHeight: "0px",
+        paddingTop: `${paddingTop}px`,
+        paddingBottom: `${paddingBottom}px`,
+        marginTop: `${usedMarginTop}px`,
+        marginBottom: `${usedMarginBottom}px`,
+      },
+      {
+        opacity: "0",
+        transform: "translateY(-4px)",
+        height: "0px",
+        minHeight: "0px",
+        paddingTop: "0px",
+        paddingBottom: "0px",
+        marginTop: "0px",
+        marginBottom: `${-gap}px`,
+      },
     ],
     { duration: 180, easing: "ease-out", fill: "forwards" }
   );
@@ -298,6 +365,9 @@ export const animateWelcomeOut = (
   const settle = () => {
     if (settled) return;
     settled = true;
+    // Restored on BOTH settle paths (finish and a re-show's cancel), so a
+    // welcome brought back by clearChat keeps its natural overflow.
+    host.style.overflow = previousOverflow;
     onFinished(animation);
   };
   animation.finished.then(settle).catch(settle);

package/src/defaults.ts

@@ -1,6 +1,10 @@
 import type { AgentWidgetConfig, AgentWidgetLauncherConfig } from "./types";
 import type { DeepPartial, PersonaTheme } from "./types/theme";
 import { deepMerge } from "./utils/deep-merge";
+import {
+  DEFAULT_TOOLTIP_DELAY_MS,
+  DEFAULT_TOOLTIP_SKIP_DELAY_MS,
+} from "./utils/tooltip-timing";
 
 /**
  * Default width for the floating launcher panel (when not overridden).
@@ -31,9 +35,10 @@ export const DEFAULT_LAUNCHER_CONFIG: AgentWidgetLauncherConfig = {
   callToActionIconHidden: false,
   agentIconSize: "40px",
   headerIconSize: "40px",
-  closeButtonSize: "32px",
+  // closeButtonSize / clearChat.size omitted so theme.components.header.controlSize
+  // sizes the header controls; setting either here would pin them past the token.
   // Zero out browser-default <button> padding so the icon gets the full
-  // 32x32 content box, matching clearChat.paddingX/Y below. Without this,
+  // 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",
@@ -52,7 +57,6 @@ export const DEFAULT_LAUNCHER_CONFIG: AgentWidgetLauncherConfig = {
     enabled: true,
     placement: "inline",
     iconName: "refresh-cw",
-    size: "32px",
     showTooltip: true,
     tooltipText: "Clear chat",
     paddingX: "0px",
@@ -77,6 +81,10 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   theme: undefined,
   darkTheme: undefined,
   colorScheme: "light",
+  tooltip: {
+    delayMs: DEFAULT_TOOLTIP_DELAY_MS,
+    skipDelayMs: DEFAULT_TOOLTIP_SKIP_DELAY_MS,
+  },
   launcher: DEFAULT_LAUNCHER_CONFIG,
   copy: {
     // No welcomeTitle / welcomeSubtitle here on purpose: `resolveWelcomeConfig`
@@ -168,6 +176,13 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       freeTextPlaceholder: "Type your answer…",
       submitLabel: "Send",
     },
+    history: {
+      enabled: false,
+      presentation: "panel",
+      showScopeStatus: true,
+      showDelete: true,
+      showDeleteAll: true,
+    },
   },
   // Placeholder copy that models the right shape: verb-first, user-voice,
   // one line. Integrators should swap in domain prompts.
@@ -263,6 +278,10 @@ export function mergeWithDefaults(
         ...config.launcher?.clearChat,
       },
     },
+    tooltip: {
+      ...DEFAULT_WIDGET_CONFIG.tooltip,
+      ...config.tooltip,
+    },
     copy: {
       ...DEFAULT_WIDGET_CONFIG.copy,
       ...config.copy,
@@ -290,6 +309,8 @@ export function mergeWithDefaults(
       const csa = config.features?.streamAnimation;
       const dau = DEFAULT_WIDGET_CONFIG.features?.askUserQuestion;
       const cau = config.features?.askUserQuestion;
+      const dh = DEFAULT_WIDGET_CONFIG.features?.history;
+      const ch = config.features?.history;
       const mergedArtifacts =
         da === undefined && ca === undefined
           ? undefined
@@ -333,6 +354,17 @@ export function mergeWithDefaults(
                 ...cau?.styles,
               },
             };
+      const mergedHistory =
+        dh === undefined && ch === undefined
+          ? undefined
+          : {
+              ...dh,
+              ...ch,
+              copy: {
+                ...dh?.copy,
+                ...ch?.copy,
+              },
+            };
       return {
         ...DEFAULT_WIDGET_CONFIG.features,
         ...config.features,
@@ -341,6 +373,7 @@ export function mergeWithDefaults(
         ...(mergedArtifacts !== undefined ? { artifacts: mergedArtifacts } : {}),
         ...(mergedStreamAnimation !== undefined ? { streamAnimation: mergedStreamAnimation } : {}),
         ...(mergedAskUserQuestion !== undefined ? { askUserQuestion: mergedAskUserQuestion } : {}),
+        ...(mergedHistory !== undefined ? { history: mergedHistory } : {}),
       };
     })(),
     suggestionChips: config.suggestionChips ?? DEFAULT_WIDGET_CONFIG.suggestionChips,

package/src/event-stream-view-bundle.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Bundle guard for the lazy event-stream-view chunk.
+ *
+ * The observability panel 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/event-stream-view.{js,cjs}`, loaded on demand: the IIFE via a sibling
+ * URL, ESM/CJS via the external `@runtypelabs/persona/event-stream-view`
+ * subpath. A stray static import would pull the view back in; this fails then.
+ *
+ * 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: the view's root and list class names are never emitted
+// by core code; the sibling-URL stub in the core bundles is the bare filename
+// `event-stream-view.js`, which does not contain these.
+const RUNTIME_MARKERS = ["persona-event-stream-view", "persona-event-stream-list"];
+
+const SUBPATH = "@runtypelabs/persona/event-stream-view";
+
+describe("event-stream-view bundle split", () => {
+  const iifeBuilt =
+    existsSync(dist("index.global.js")) && existsSync(dist("event-stream-view.js"));
+  const esmBuilt = existsSync(dist("index.js")) && existsSync(dist("index.cjs"));
+
+  it.runIf(iifeBuilt)("keeps the event-stream 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("event-stream-view.js");
+  });
+
+  it.runIf(esmBuilt)("keeps the event-stream 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
+        );
+      }
+      // Any reference must go through the external subpath, not an inlined
+      // relative import.
+      expect(
+        core.includes(SUBPATH),
+        `${file} must reach the view via the external subpath`
+      ).toBe(true);
+    }
+  });
+
+  it.runIf(iifeBuilt)("ships the event-stream view in the sibling chunk", () => {
+    const chunk = readFileSync(dist("event-stream-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("event-stream-view.cjs"))).toBe(true);
+    // Declarations ship with the chunk so the subpath is typed.
+    expect(existsSync(dist("event-stream-view.d.ts"))).toBe(true);
+  });
+});

package/src/event-stream-view-entry.ts

@@ -0,0 +1,19 @@
+/**
+ * Event-stream-view runtime entry — the module that assembles the lazily
+ * loaded event-stream observability panel. It is NEVER statically imported on
+ * the core path: the IIFE/CDN build marks
+ * `@runtypelabs/persona/event-stream-view` external (`tsup.global.config.ts`)
+ * and loads the standalone `event-stream-view.js` chunk from a sibling URL on
+ * first open of the panel. The core reaches it through
+ * `event-stream-view-loader.ts`.
+ *
+ * Mirrors `history-view-entry.ts`.
+ */
+
+export { createEventStreamView } from "./components/event-stream-view";
+export type { EventStreamViewOptions } from "./components/event-stream-view";
+
+import type { createEventStreamView as CreateEventStreamView } from "./components/event-stream-view";
+
+/** Mounted-view handle: what `createEventStreamView` returns. */
+export type EventStreamViewHandle = ReturnType<typeof CreateEventStreamView>;

package/src/event-stream-view-loader.ts

@@ -0,0 +1,31 @@
+/**
+ * Loader indirection for the lazy event-stream-view chunk (core bundle, tiny).
+ *
+ * Mirrors `history-view-loader.ts`: the IIFE/CDN entry (`index-global.ts`)
+ * registers a loader that imports the standalone `event-stream-view.js` chunk
+ * from a sibling URL. ESM/CJS consumers fall back to importing the package's
+ * `./event-stream-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 event-stream panel is first opened.
+ */
+
+import { createChunkLoader } from "./utils/chunk-loader";
+import type {
+  EventStreamViewOptions,
+  EventStreamViewHandle,
+} from "./event-stream-view-entry";
+
+export type EventStreamViewModule = {
+  createEventStreamView: (options: EventStreamViewOptions) => EventStreamViewHandle;
+};
+
+// IIFE/CDN: sibling-URL chunk via the registered loader.
+// ESM/CJS fallback: the package's own `./event-stream-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<EventStreamViewModule>({
+  fallbackImport: () => import("@runtypelabs/persona/event-stream-view"),
+});
+
+export const setEventStreamViewLoader = setLoader;
+export const loadEventStreamView = load;

package/src/event-stream-view.ts

@@ -0,0 +1,19 @@
+/**
+ * Standalone event-stream-view chunk (`dist/event-stream-view.js`).
+ *
+ * The IIFE/CDN widget bundle marks `@runtypelabs/persona/event-stream-view`
+ * external so the observability panel is excluded from the core payload; this
+ * file is built as a self-contained sibling chunk
+ * (`tsup.event-stream-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.
+ */
+
+export { createEventStreamView } from "./event-stream-view-entry";
+export type {
+  EventStreamViewOptions,
+  EventStreamViewHandle,
+} from "./event-stream-view-entry";