@runtypelabs/persona 3.34.1 → 3.35.0

package/src/index-global.ts

@@ -1,18 +1,18 @@
 /**
- * IIFE entry point — bundled for `<script>` tag consumers.
+ * IIFE entry point: bundled for `<script>` tag consumers.
  *
  * This file re-exports everything from the main entry AND side-imports all
  * built-in subpath animations so they register automatically. Script-tag
  * users who include the global build don't need extra script tags or
- * registration calls — setting `features.streamAnimation.type` to any
+ * registration calls: setting `features.streamAnimation.type` to any
  * built-in name just works.
  *
  * npm consumers continue to import from the main entry (`import ... from
- * "@runtypelabs/persona"`) — those animations stay in their subpath
+ * "@runtypelabs/persona"`): those animations stay in their subpath
  * modules so bundlers can tree-shake them.
  */
 
-// Re-export the full public API — from `index-core` (NOT `index`) so the
+// Re-export the full public API: from `index-core` (NOT `index`) so the
 // dev-only helpers (`generateCodeSnippet`, `createDemoCarousel`) stay out of the
 // CDN/IIFE bundle. npm consumers still get them via the `index.ts` barrel.
 export * from "./index-core";
@@ -35,7 +35,7 @@ export type { StreamAnimationPlugin, StreamAnimationContext } from "./types";
 // ---------------------------------------------------------------------------
 // Deferred WebMCP polyfill loading.
 //
-// This bundle is built with `@mcp-b/webmcp-polyfill` external — the bridge's
+// This bundle is built with `@mcp-b/webmcp-polyfill` external: the bridge's
 // default `import("@mcp-b/webmcp-polyfill")` is a bare specifier no browser
 // can resolve, so register a loader that imports the self-contained
 // `webmcp-polyfill.js` chunk from a sibling URL instead. Mirrors how
@@ -44,7 +44,7 @@ export type { StreamAnimationPlugin, StreamAnimationContext } from "./types";
 
 import { setWebMcpPolyfillLoader } from "./webmcp-bridge";
 
-// Capture at module-evaluation time — `document.currentScript` is null once
+// Capture at module-evaluation time: `document.currentScript` is null once
 // execution leaves the script's initial synchronous run.
 const widgetScriptSrc: string | null =
   typeof document !== "undefined"
@@ -70,3 +70,70 @@ setWebMcpPolyfillLoader(() => {
   // leaves it untouched (and must not try to bundle it).
   return import(/* @vite-ignore */ chunkUrl);
 });
+
+// ---------------------------------------------------------------------------
+// Deferred Markdown Parsers (marked + dompurify) loading.
+//
+// This bundle is built with `./markdown-parsers-entry` external: the Markdown
+// and HTML sanitization libraries are kept out of the CDN payload. Register a
+// loader that imports the self-contained `markdown-parsers.js` chunk from a sibling
+// URL. The session prefetches it at init so it's warm before the first message.
+// ---------------------------------------------------------------------------
+
+import { setMarkdownParsersLoader, loadMarkdownParsers } from "./markdown-parsers-loader";
+
+setMarkdownParsersLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "markdown-parsers.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the markdown-parsers.js URL from the widget script URL " +
+          `(${widgetScriptSrc ?? "unavailable"}). Self-hosted deployments that ` +
+          "rename index.global.js should host markdown-parsers.js alongside it.",
+      ),
+    );
+  }
+  return import(/* @vite-ignore */ chunkUrl);
+});
+
+// Kick off the load immediately since it will likely be needed.
+loadMarkdownParsers().catch(err => {
+  // It's okay if this fails (e.g. ad blocker), it'll just fall back to plain text.
+  if (typeof console !== "undefined") {
+    console.warn("[Persona] Failed to pre-load markdown parsers", err);
+  }
+});
+// ---------------------------------------------------------------------------
+// Deferred Runtype TTS engine loading.
+//
+// This bundle is built with `./runtype-speech-engine` external (see
+// `tsup.global.config.ts`): the hosted read-aloud engine + the
+// AudioPlaybackManager it bundles are kept out of the CDN payload. Register a
+// loader that imports the self-contained `runtype-tts.js` chunk from a sibling
+// URL; the session prefetches it at init when `textToSpeech.provider:'runtype'`
+// is set, so it's warm before the first click. Same pattern as the WebMCP
+// polyfill above.
+// ---------------------------------------------------------------------------
+
+import { setRuntypeTtsLoader } from "./voice/runtype-tts-loader";
+
+setRuntypeTtsLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "runtype-tts.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the runtype-tts.js URL from the widget script URL " +
+          `(${widgetScriptSrc ?? "unavailable"}). Self-hosted deployments that ` +
+          "rename index.global.js should host runtype-tts.js alongside it, or set " +
+          "textToSpeech.createEngine to supply a speech engine directly.",
+      ),
+    );
+  }
+  return import(/* @vite-ignore */ chunkUrl);
+});

package/src/index.ts

@@ -2,7 +2,7 @@
  * npm package entry (`@runtypelabs/persona`).
  *
  * This is a thin barrel over `index-core.ts` (the shared public API) that adds
- * back the **dev/config-tool-only** helpers — `generateCodeSnippet` and
+ * back the **dev/config-tool-only** helpers: `generateCodeSnippet` and
  * `createDemoCarousel`. Those are kept out of `index-core.ts` so the IIFE/CDN
  * build (`index-global.ts`, which re-exports from `index-core.ts`) doesn't ship
  * them: a running widget never needs them, only build-time/demo tooling does.
@@ -12,6 +12,12 @@
  * `createDemoCarousel`.
  */
 
+// Register `marked` + `dompurify` synchronously for the bundled npm build so
+// the synchronous markdown/sanitize API renders on first paint. The IIFE/CDN
+// entry (`index-global.ts`) does NOT import this; it lazy-loads the parsers
+// from the `markdown-parsers.js` chunk instead. Must run before any render.
+import "./markdown-parsers-eager";
+
 // Full public API (everything except the two dev-only helpers below).
 export * from "./index-core";
 export { default } from "./index-core";

package/src/install.test.ts

@@ -70,7 +70,7 @@ function provideLauncherBundle() {
 /**
  * Force the next dynamically-inserted <script> to error. jsdom never fires
  * load/error on injected scripts, so we trigger `onerror` on a fake timer that
- * `runAllTimersAsync()` flushes — deterministic under fake timers.
+ * `runAllTimersAsync()` flushes: deterministic under fake timers.
  */
 function failNextScriptLoad() {
   const head = document.head;
@@ -137,15 +137,15 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-describe("install.ts — onScriptLoad beacon", () => {
+describe("install.ts: onScriptLoad beacon", () => {
   it("fires synchronously on script execution, before any loading or gating", async () => {
     const events = recordEvents();
     const onScriptLoad = vi.fn();
 
-    // No config at all — the beacon must still fire (diagnostics: "did my embed run").
+    // No config at all: the beacon must still fire (diagnostics: "did my embed run").
     await install({ onScriptLoad });
 
-    // Fired during module evaluation — no timer flush needed.
+    // Fired during module evaluation: no timer flush needed.
     expect(onScriptLoad).toHaveBeenCalledTimes(1);
     expect(onScriptLoad).toHaveBeenCalledWith({ version: "latest" });
     expect(events.types()[0]).toBe("persona:script-load");
@@ -160,7 +160,7 @@ describe("install.ts — onScriptLoad beacon", () => {
   });
 });
 
-describe("install.ts — deferred launcher path", () => {
+describe("install.ts: deferred launcher path", () => {
   it("mounts the critical launcher, fires onLauncherShown, and defers onChatReady until open", async () => {
     markCssLoaded();
     provideFullBundle(); // so loadJS resolves instantly when the user opens
@@ -186,7 +186,7 @@ describe("install.ts — deferred launcher path", () => {
     expect(launcherMount).toHaveBeenCalledTimes(1);
     expect(onLauncherShown).toHaveBeenCalledTimes(1);
     expect(onLauncherShown).toHaveBeenCalledWith({ deferred: true, element: launcherElement });
-    // The full widget has NOT been initialized yet — that waits for first open.
+    // The full widget has NOT been initialized yet: that waits for first open.
     expect(initAgentWidget).not.toHaveBeenCalled();
     expect(onChatReady).not.toHaveBeenCalled();
 
@@ -230,7 +230,7 @@ describe("install.ts — deferred launcher path", () => {
   });
 });
 
-describe("install.ts — eager path", () => {
+describe("install.ts: eager path", () => {
   it("non-floating (launcher disabled) eager-loads, fires onChatReady, and does NOT fire onLauncherShown", async () => {
     markCssLoaded();
     provideFullBundle();
@@ -272,7 +272,7 @@ describe("install.ts — eager path", () => {
   });
 });
 
-describe("install.ts — deferral gate", () => {
+describe("install.ts: deferral gate", () => {
   async function expectDecision(config: any, { defers }: { defers: boolean }) {
     markCssLoaded();
     provideFullBundle();
@@ -345,7 +345,7 @@ describe("install.ts — deferral gate", () => {
   });
 });
 
-describe("install.ts — onReady deprecation alias", () => {
+describe("install.ts: onReady deprecation alias", () => {
   it("still calls the deprecated onReady and warns once", async () => {
     markCssLoaded();
     provideFullBundle();
@@ -376,7 +376,7 @@ describe("install.ts — onReady deprecation alias", () => {
   });
 });
 
-describe("install.ts — onError", () => {
+describe("install.ts: onError", () => {
   it("fires onError with phase 'init' and dispatches persona:error when initialization throws", async () => {
     markCssLoaded();
     provideFullBundle();
@@ -420,7 +420,7 @@ describe("install.ts — onError", () => {
   });
 });
 
-describe("install.ts — lifecycle callback safety", () => {
+describe("install.ts: lifecycle callback safety", () => {
   it("a throwing onScriptLoad callback does not break the rest of installation", async () => {
     markCssLoaded();
     provideFullBundle();

package/src/install.ts

@@ -30,11 +30,11 @@ interface SiteAgentInstallConfig {
    */
   onScriptLoad?: (info: { version: string }) => void;
   /**
-   * Fired when the floating launcher is painted on the page — at page-load time.
+   * Fired when the floating launcher is painted on the page: at page-load time.
    * Deferred installs: the critical launcher mounts. Eager floating installs:
    * the full widget's launcher mounts. Use this for "widget appeared" analytics.
    * Does NOT fire for inline / docked / composer-bar installs (no floating
-   * launcher) — use `onChatReady` there.
+   * launcher): use `onChatReady` there.
    */
   onLauncherShown?: (info: { deferred: boolean; element?: HTMLElement }) => void;
   /**
@@ -88,7 +88,7 @@ declare global {
     if (configJson) {
       try {
         // HTML attributes preserve literal newlines/tabs which are invalid
-        // control characters inside JSON string literals — strip them.
+        // control characters inside JSON string literals: strip them.
         const normalizedJson = configJson.replace(/[\r\n]+\s*/g, '');
         const parsedConfig = JSON.parse(normalizedJson);
         // If it has nested 'config' property, use it; otherwise treat as widget config
@@ -152,7 +152,7 @@ declare global {
     try {
       window.dispatchEvent(new CustomEvent(name, { detail }));
     } catch {
-      /* CustomEvent unsupported — ignore */
+      /* CustomEvent unsupported: ignore */
     }
   };
   const fail = (phase: "css" | "bundle" | "init", error: unknown): void => {
@@ -168,14 +168,14 @@ declare global {
       if (!warnedOnReadyDeprecated) {
         warnedOnReadyDeprecated = true;
         console.warn(
-          "[Persona] `onReady` is deprecated — use `onChatReady`. `onReady` still works but is removed in the next major."
+          "[Persona] `onReady` is deprecated: use `onChatReady`. `onReady` still works but is removed in the next major."
         );
       }
       return config.onReady;
     }
     return undefined;
   };
-  // True when the config renders a standard floating launcher button — the only
+  // True when the config renders a standard floating launcher button: the only
   // case that paints a clickable launcher at load. Shared by the deferral gate
   // and the eager-path `onLauncherShown` so the event name stays honest.
   const hasFloatingLauncher = (widgetConfig: any): boolean => {
@@ -343,12 +343,23 @@ declare global {
   // first open is quick. Runs at idle so it never competes with the launcher.
   const prefetchFullBundle = (): void => {
     const addPrefetch = () => {
-      if (isJsLoaded()) return;
-      const link = document.createElement("link");
-      link.rel = "prefetch";
-      link.as = "script";
-      link.href = jsUrl;
-      document.head.appendChild(link);
+      if (!isJsLoaded()) {
+        const link = document.createElement("link");
+        link.rel = "prefetch";
+        link.as = "script";
+        link.href = jsUrl;
+        document.head.appendChild(link);
+      }
+
+      // Also prefetch the markdown parsers chunk
+      const markdownUrl = jsUrl.replace(/index\.global\.js($|\?)/, "markdown-parsers.js$1");
+      if (markdownUrl !== jsUrl) {
+        const link2 = document.createElement("link");
+        link2.rel = "prefetch";
+        link2.as = "script";
+        link2.href = markdownUrl;
+        document.head.appendChild(link2);
+      }
     };
     if (typeof requestIdleCallback !== "undefined") {
       requestIdleCallback(addPrefetch, { timeout: 4000 });
@@ -408,7 +419,7 @@ declare global {
         handle.open();
       }
 
-      // Eager floating installs paint their launcher at load time too — emit the
+      // Eager floating installs paint their launcher at load time too: emit the
       // same page-load "appeared" signal as the deferred path. The deferred
       // handoff (openAfter) already fired it at launcher mount, and non-floating
       // modes have no launcher, so guard on both.
@@ -420,7 +431,7 @@ declare global {
       // The full widget is initialized and its controller API is callable.
       safeCall(resolveChatReady(), handle);
       dispatchLifecycle("persona:chat-ready", handle);
-      dispatchLifecycle("persona:ready", handle); // deprecated alias — removed next major
+      dispatchLifecycle("persona:ready", handle); // deprecated alias: removed next major
       return handle;
     } catch (error) {
       fail("init", error);
@@ -449,11 +460,10 @@ declare global {
 
   // The deferred-launcher optimization only applies to the common floating case
   // that paints a collapsed launcher and waits for a click. Anything that starts
-  // open or renders differently eager-loads the full bundle exactly as before —
-  // including the two open triggers config alone can't express: a host
+  // open or renders differently eager-loads the full bundle exactly as before:  // including the two open triggers config alone can't express: a host
   // onStateLoaded hook that may request open, and a restored "was open" state.
   const shouldDeferPanel = (widgetConfig: any): boolean => {
-    if (!launcherUrl) return false;                                      // custom bundle URL override — can't derive launcher URL
+    if (!launcherUrl) return false;                                      // custom bundle URL override: can't derive launcher URL
     if (!hasFloatingLauncher(widgetConfig)) return false;                // inline / docked / composer-bar
     const launcher = widgetConfig.launcher ?? {};
     if (launcher.autoExpand === true) return false;                      // starts open
@@ -488,7 +498,7 @@ declare global {
     const mounted = window.AgentWidgetLauncher.mount({ target, config: widgetConfig, onOpen });
     launcherHandle = mounted;
 
-    // The real launcher is now painted at page-load time — emit the page-load
+    // The real launcher is now painted at page-load time: emit the page-load
     // "appeared" signal (distinct from `onChatReady`, which waits for first open).
     safeCall(config.onLauncherShown, { deferred: true, element: mounted.element });
     dispatchLifecycle("persona:launcher-shown", { deferred: true, element: mounted.element });

package/src/launcher-global.ts

@@ -1,10 +1,10 @@
 /**
- * Critical-path launcher entry — built to `launcher.global.js` (IIFE).
+ * Critical-path launcher entry: built to `launcher.global.js` (IIFE).
  *
- * Ships ONLY the real collapsed launcher (`createLauncherButton`) plus the full
- * theme system, so the launcher paints pixel-identically to the full widget from
- * a tiny bundle (~13 KB brotli vs ~134 KB for `index.global.js`). The heavy
- * conversation panel is deferred until first open by the installer (Phase 2).
+ * Ships ONLY the real collapsed launcher (`createLauncherButton`) plus the
+ * theme application path, so the launcher paints pixel-identically to the full
+ * widget from a tiny bundle. The heavy conversation panel is deferred until
+ * first open by the installer (Phase 2).
  *
  * The full Lucide icon registry is kept on purpose: any *supported* icon a site
  * configures (`launcher.agentIconName` / `callToActionIconName`) must render at
@@ -18,13 +18,13 @@
  */
 import { createLauncherButton } from "./components/launcher";
 import { applyThemeVariables } from "./utils/theme";
-import { mergeWithDefaults } from "./defaults";
+import { DEFAULT_LAUNCHER_CONFIG } from "./defaults";
 import type { AgentWidgetConfig } from "./types";
 
 export interface AgentWidgetLauncherMountOptions {
   /** Where to mount. Defaults to `document.body` (the floating launcher is `position: fixed`). */
   target?: string | HTMLElement;
-  /** The same widget config the full widget will receive — drives theme, icons, position, copy. */
+  /** The same widget config the full widget will receive: drives theme, icons, position, copy. */
   config?: AgentWidgetConfig;
   /** Called when the launcher is clicked; the installer loads the full widget and opens the panel. */
   onOpen: () => void;
@@ -56,6 +56,20 @@ const resolveTarget = (target?: string | HTMLElement): HTMLElement => {
   return document.body;
 };
 
+const mergeCriticalLauncherConfig = (
+  config?: AgentWidgetConfig
+): AgentWidgetConfig => ({
+  ...config,
+  launcher: {
+    ...DEFAULT_LAUNCHER_CONFIG,
+    ...config?.launcher,
+    dock: {
+      ...DEFAULT_LAUNCHER_CONFIG.dock,
+      ...config?.launcher?.dock,
+    },
+  },
+});
+
 /**
  * Mount the real collapsed launcher from the critical bundle.
  *
@@ -77,12 +91,9 @@ export const mount = (
   const { onOpen } = options;
   const target = resolveTarget(options.target);
 
-  // Render from the SAME effective config the full widget uses: `ui.ts` runs
-  // `mergeWithDefaults(config)` before building the launcher (ui.ts:495). Without
-  // this, the critical launcher misses launcher defaults like
-  // `callToActionIconPadding` and `agentIconName`, so it looks subtly different
-  // from the full widget that replaces it on open.
-  const config = mergeWithDefaults(options.config) as AgentWidgetConfig;
+  // Render from the same launcher defaults the full widget uses without pulling
+  // the full widget default object into the critical bundle.
+  const config = mergeCriticalLauncherConfig(options.config);
 
   const root = document.createElement("div");
   root.setAttribute("data-persona-root", "true");
@@ -97,7 +108,7 @@ export const mount = (
     root,
     element: launcher.element,
     update: (next: AgentWidgetConfig) => {
-      const merged = mergeWithDefaults(next) as AgentWidgetConfig;
+      const merged = mergeCriticalLauncherConfig(next);
       applyThemeVariables(root, merged);
       launcher.update(merged);
     },

package/src/markdown-parsers-eager.ts

@@ -0,0 +1,20 @@
+/**
+ * Eager markdown-parser registration for the bundled (ESM / CJS) builds.
+ *
+ * npm consumers bundle `marked` and `dompurify` directly anyway, so there is no
+ * benefit to deferring them — and the public `markdownPostprocessor()` /
+ * `createDefaultSanitizer()` API is synchronous. Importing this module for its
+ * side effect registers both parsers up front so `getMarkdownParsersSync()`
+ * resolves them on the first render.
+ *
+ * This module is intentionally NOT reachable from `index-global.ts` (the IIFE
+ * entry): it statically imports `marked` + `dompurify`, so pulling it into the
+ * CDN bundle would defeat the lazy `markdown-parsers.js` chunk. It is imported
+ * only from `index.ts` (the npm barrel) and from unit tests that exercise the
+ * synchronous parsers directly.
+ */
+import { Marked } from "marked";
+import DOMPurify from "dompurify";
+import { provideMarkdownParsers } from "./markdown-parsers-loader";
+
+provideMarkdownParsers({ Marked, DOMPurify });

package/src/markdown-parsers-entry.ts

@@ -0,0 +1,4 @@
+import { Marked } from "marked";
+import DOMPurify from "dompurify";
+
+export { Marked, DOMPurify };

package/src/markdown-parsers-loader.ts

@@ -0,0 +1,49 @@
+import type { Marked } from "marked";
+import type DOMPurify from "dompurify";
+
+export type MarkdownParsersModule = {
+  Marked: typeof Marked;
+  DOMPurify: typeof DOMPurify;
+};
+
+let loader: (() => Promise<MarkdownParsersModule>) | null = null;
+let moduleCache: MarkdownParsersModule | null = null;
+let loadPromise: Promise<MarkdownParsersModule> | null = null;
+
+export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>) => {
+  loader = l;
+};
+
+/**
+ * Register the parsers synchronously. Used by the ESM/CJS build (where `marked`
+ * and `dompurify` are bundled directly via `markdown-parsers-eager.ts`), so
+ * `getMarkdownParsersSync()` returns them on the very first render and the
+ * synchronous `markdownPostprocessor` / `createDefaultSanitizer` API keeps
+ * working without an async round-trip. The IIFE/CDN build never calls this;
+ * it lazy-loads the `markdown-parsers.js` chunk instead.
+ */
+export const provideMarkdownParsers = (mod: MarkdownParsersModule): void => {
+  moduleCache = mod;
+};
+
+export const loadMarkdownParsers = (): Promise<MarkdownParsersModule> => {
+  if (moduleCache) return Promise.resolve(moduleCache);
+  if (loadPromise) return loadPromise;
+  if (!loader) {
+    // Fallback for regular ESM/CJS consumers (they import directly)
+    loadPromise = import("./markdown-parsers-entry").then((mod) => {
+      moduleCache = mod;
+      return mod;
+    });
+    return loadPromise;
+  }
+  loadPromise = loader().then((mod) => {
+    moduleCache = mod;
+    return mod;
+  });
+  return loadPromise;
+};
+
+export const getMarkdownParsersSync = (): MarkdownParsersModule | null => {
+  return moduleCache;
+};

package/src/plugin-kit.test.ts

@@ -31,7 +31,7 @@ describe("injectStyles / getStyleRoot", () => {
     expect(style?.textContent).toContain("color: red");
   });
 
-  it("is idempotent — repeated calls add only one <style>", () => {
+  it("is idempotent: repeated calls add only one <style>", () => {
     const el = document.createElement("div");
     document.body.appendChild(el);
 

package/src/plugin-kit.ts

@@ -1,4 +1,4 @@
-// Plugin Kit — small, dependency-free utilities for authoring Persona plugins.
+// Plugin Kit: small, dependency-free utilities for authoring Persona plugins.
 //
 // Plugin render hooks (`renderApproval`, `renderAskUserQuestion`, `renderMessage`,
 // …) return a detached `HTMLElement` that the widget morphs into the transcript.
@@ -6,7 +6,7 @@
 //
 //   1. Injecting the plugin's own CSS so it survives the widget's Shadow-DOM mode
 //      (a plain `document.head` <style> does NOT pierce a shadow root).
-//   2. Floating UI — dropdowns, menus, tooltips — that must overlay the rest of
+//   2. Floating UI, dropdowns, menus, tooltips, that must overlay the rest of
 //      the widget and not be clipped by the transcript's scroll container.
 //
 // Both are easy to get subtly wrong, so they live here as a supported, optional
@@ -42,7 +42,7 @@ function injectInto(root: Document | ShadowRoot, id: string, css: string): void
     root instanceof Document ? root.head : root;
   const escaped = id.replace(/["\\]/g, "\\$&");
   if (container.querySelector(`style[data-persona-plugin-style="${escaped}"]`)) {
-    return; // Already present in this root — idempotent.
+    return; // Already present in this root: idempotent.
   }
   const doc = root instanceof Document ? root : root.ownerDocument ?? document;
   const style = doc.createElement("style");
@@ -52,15 +52,15 @@ function injectInto(root: Document | ShadowRoot, id: string, css: string): void
 }
 
 /**
- * Inject a plugin's CSS once into the correct root — the widget's shadow root
+ * Inject a plugin's CSS once into the correct root: the widget's shadow root
  * when shadowed, the document head otherwise. Idempotent: keyed by `id`, so it
  * is safe to call on every render.
  *
  * Pass the element you're about to return from a render hook. While building, an
  * element is detached and its eventual root is unknown, so this injects into the
  * owning document immediately (covering the default light-DOM case with no
- * flash) and then, on the next microtask — after the widget has mounted the
- * element — re-resolves and also injects into its shadow root if it landed in
+ * flash) and then, on the next microtask: after the widget has mounted the
+ * element: re-resolves and also injects into its shadow root if it landed in
  * one. You may also pass an explicit `Document` or `ShadowRoot`.
  *
  * @example
@@ -124,7 +124,7 @@ export interface PopoverOptions {
   zIndex?: number | null;
   /**
    * Where to mount `content`. Defaults to the anchor's shadow root (when
-   * shadowed) or `document.body` — keeping it inside the same style + stacking
+   * shadowed) or `document.body`: keeping it inside the same style + stacking
    * scope as the anchor while escaping the transcript's scroll clipping.
    */
   container?: HTMLElement | ShadowRoot;

package/src/plugins/types.ts

@@ -64,7 +64,7 @@ export interface AgentWidgetPlugin {
     defaultRenderer: () => HTMLElement;
     onSubmit: (text: string) => void;
     /**
-     * When true, the assistant stream is active — same moment `session.isStreaming()` becomes true.
+     * When true, the assistant stream is active: same moment `session.isStreaming()` becomes true.
      * Prefer wiring controls to `data-persona-composer-disable-when-streaming` plus `setComposerDisabled`
      * in the host, or react to `footer.dataset.personaComposerStreaming === "true"`.
      */
@@ -113,14 +113,14 @@ export interface AgentWidgetPlugin {
    * Custom renderer for `ask_user_question` tool calls.
    *
    * When a plugin returns an `HTMLElement`, it is inserted into the transcript
-   * in place of the default (which is no transcript bubble — the built-in
+   * in place of the default (which is no transcript bubble: the built-in
    * renders a sheet over the composer). The built-in composer-overlay sheet
    * is suppressed so the plugin's UI fully owns the interaction.
    *
    * Return `null` to fall through to the built-in overlay sheet.
    *
    * The context gives you a pre-parsed `payload` (may be partial while the
-   * tool call is still streaming — check `complete`) and two callbacks:
+   * tool call is still streaming: check `complete`) and two callbacks:
    * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
    * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
    *
@@ -170,8 +170,8 @@ export interface AgentWidgetPlugin {
    *
    * Return an `HTMLElement` to fully own the approval UI, `defaultRenderer()`
    * to render (or wrap) the built-in bubble, or `null` to fall through to the
-   * default. Unlike the built-in bubble — whose Approve/Deny buttons are wired
-   * via delegation — a fully custom element resolves the approval by calling
+   * default. Unlike the built-in bubble: whose Approve/Deny buttons are wired
+   * via delegation: a fully custom element resolves the approval by calling
    * the `approve`/`deny` callbacks. Both route through the same path the
    * built-in buttons use (optimistic update, `onDecision`, in-place anchoring).
    *

package/src/postprocessors.ts

@@ -1,5 +1,6 @@
-import { Marked, type RendererObject } from "marked";
+import type { RendererObject } from "marked";
 import type { AgentWidgetMarkdownConfig, AgentWidgetMarkdownRendererOverrides, AgentWidgetMarkdownOptions } from "./types";
+import { getMarkdownParsersSync } from "./markdown-parsers-loader";
 
 /**
  * Options for creating a markdown processor
@@ -48,20 +49,32 @@ const convertRendererOverrides = (
  * ```
  */
 export const createMarkdownProcessor = (options?: MarkdownProcessorOptions) => {
-  const opts = options?.markedOptions;
-  const markedInstance = new Marked({
-    gfm: opts?.gfm ?? true,
-    breaks: opts?.breaks ?? true,
-    pedantic: opts?.pedantic,
-    silent: opts?.silent,
-  });
-  
-  const rendererOverrides = convertRendererOverrides(options?.renderer);
-  if (rendererOverrides) {
-    markedInstance.use({ renderer: rendererOverrides });
-  }
-  
+  let markedInstance: any = null;
+
   return (text: string): string => {
+    const parsers = getMarkdownParsersSync();
+    if (!parsers) {
+      // If the markdown parser hasn't loaded yet, fall back to plain text with HTML escaped.
+      // The widget will re-render automatically once the parser finishes loading.
+      return escapeHtml(text);
+    }
+    
+    if (!markedInstance) {
+      const { Marked } = parsers;
+      const opts = options?.markedOptions;
+      markedInstance = new Marked({
+        gfm: opts?.gfm ?? true,
+        breaks: opts?.breaks ?? true,
+        pedantic: opts?.pedantic,
+        silent: opts?.silent,
+      });
+      
+      const rendererOverrides = convertRendererOverrides(options?.renderer);
+      if (rendererOverrides) {
+        markedInstance.use({ renderer: rendererOverrides });
+      }
+    }
+    
     return markedInstance.parse(text) as string;
   };
 };

package/src/runtime/host-layout.test.ts

@@ -227,7 +227,7 @@ describe("createWidgetHostLayout docked", () => {
   });
 
   it("clamps push and overlay dock slots without sticky (in-flow/absolute contexts)", () => {
-    // push: the slot is an in-flow `position: relative` column — max-height cap
+    // push: the slot is an in-flow `position: relative` column: max-height cap
     // only, no sticky. overlay: keeps absolute positioning.
     const cases = [
       { reveal: "push" as const, position: "relative" },