@runtypelabs/persona 4.30.0 → 4.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.30.0",
+  "version": "4.32.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -236,7 +236,7 @@
     "check:dist-vite8": "node scripts/check-dist-no-in-for-init.mjs",
     "build:styles": "node scripts/build-styles.mjs",
     "lint": "oxlint",
-    "typecheck": "pnpm run check:runtype-types && tsgo --noEmit",
+    "typecheck": "pnpm run check:runtype-types && node ../../scripts/typecheck.mjs --noEmit",
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",

package/src/activity-ui.ts

@@ -8,6 +8,29 @@ import { updateToolBubbleUI } from "./components/tool-bubble";
 import { updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import type { AgentWidgetConfig, AgentWidgetMessage } from "./types";
 import { createActivityOverflow } from "./utils/activity-overflow";
+import { afterDisclosureAnimation } from "./components/disclosure-animation";
+
+type DisclosureAnchor = { spacerHeight: number; initialSpacerHeight: number; contentHeightAtAnchor: number; pending: number };
+
+/** Keep scroll reserve throughout manual disclosure animations and reversals. */
+export function holdScroll(
+  bubble: HTMLElement, body: HTMLElement, anchor: DisclosureAnchor,
+  measure: (spacer: number) => number, setSpacer: (height: number) => void,
+  slack: number, isCurrent: () => boolean
+): () => void {
+  // Reserve the whole possible collapse before changing display or starting an
+  // animation. ResizeObserver must not drain it during intermediate frames.
+  setSpacer(anchor.spacerHeight + bubble.offsetHeight);
+  anchor.pending++;
+  return () => afterDisclosureAnimation(bubble, () => {
+    if (--anchor.pending || !isCurrent()) return;
+    // Respect scrolling that the reader did while the animation was running.
+    setSpacer(body.scrollTop + body.clientHeight + slack - measure(anchor.spacerHeight));
+    anchor.initialSpacerHeight = anchor.spacerHeight;
+    // Match the resize drain, including the flex gap before the spacer.
+    anchor.contentHeightAtAnchor = body.scrollHeight - anchor.spacerHeight;
+  });
+}
 
 /** Keep automatic disclosure updates in the optional activity chunk. */
 export function createActivityLifecycle(

package/src/components/disclosure-animation.ts

@@ -7,6 +7,11 @@ type Settings = { animation: "instant" | "height"; duration: number; easing: str
 type Running = { effect: Animation; expanded: boolean; settings: string; finish: () => void };
 const running = new WeakMap<HTMLElement, Running>();
 
+/** Observe this disclosure's height effect without waiting for looping children. */
+export function afterDisclosureAnimation(bubble: HTMLElement, finish: () => void): void {
+  running.get(bubble)?.effect.finished?.then(finish, finish) ?? finish();
+}
+
 export function disclosureSettings(config?: AgentWidgetConfig): Settings {
   const options = config?.expansion;
   return {

package/src/components/tool-bubble.ts

@@ -131,6 +131,7 @@ export const createToolBubble = (
   if (!tool) {
     return applyActivityRow(bubble, message, config, "tool");
   }
+  if (tool.id) bubble.dataset.toolCallId = tool.id;
 
   const toolDisplayConfig = config.features!.toolCallDisplay!;
   const expandable = toolDisplayConfig.expandable ?? DEFAULT_TOOL_CALL_DISPLAY.expandable;

package/src/index-core.ts

@@ -226,6 +226,7 @@ export type {
   // Visitor conversation history (client-token mode) types
   AgentWidgetHistoryFeature,
   AgentWidgetOpenConversationOptions,
+  AgentWidgetRevealToolCallOptions,
   BackgroundConversationAdapter,
   ConversationExecutionState,
   AgentWidgetHistoryListAction,
@@ -395,6 +396,7 @@ export {
 } from "./utils/actions";
 export {
   markdownPostprocessor,
+  preprocessStreamingMarkdown,
   escapeHtml,
   directivePostprocessor,
   createMarkdownProcessor,

package/src/markdown-parsers-eager.ts

@@ -16,5 +16,6 @@
 import { Marked } from "marked";
 import DOMPurify from "dompurify";
 import { provideMarkdownParsers } from "./markdown-parsers-loader";
+import { stabilizeStreamingMarkdown } from "./utils/streaming-markdown";
 
-provideMarkdownParsers({ Marked, DOMPurify });
+provideMarkdownParsers({ Marked, DOMPurify, stabilizeStreamingMarkdown });

package/src/markdown-parsers-entry.ts

@@ -2,3 +2,4 @@ import { Marked } from "marked";
 import DOMPurify from "dompurify";
 
 export { Marked, DOMPurify };
+export { stabilizeStreamingMarkdown } from "./utils/streaming-markdown";

package/src/markdown-parsers-loader.ts

@@ -5,6 +5,8 @@ import type DOMPurify from "dompurify";
 export type MarkdownParsersModule = {
   Marked: typeof Marked;
   DOMPurify: typeof DOMPurify;
+  /** Optional for compatibility with custom parser loaders. Display-only repairs. */
+  stabilizeStreamingMarkdown?: (source: string) => string;
 };
 
 // Memoization + rejection-retry semantics live in `createChunkLoader`. The

package/src/postprocessors.ts

@@ -1,6 +1,20 @@
 import type { RendererObject } from "marked";
 import type { AgentWidgetMarkdownConfig, AgentWidgetMarkdownRendererOverrides, AgentWidgetMarkdownOptions } from "./types";
 import { getMarkdownParsersSync } from "./markdown-parsers-loader";
+import { stabilizeStreamingTables } from "./utils/streaming-table";
+
+/**
+ * Repair incomplete Markdown for a streaming display before parsing it as HTML.
+ * Apply custom text transforms first, then pass the result and the callback's
+ * `streaming` flag here. Completed text is returned unchanged. This never
+ * mutates message content or raw payloads and does not load the parser chunk;
+ * until that chunk is ready, only the lightweight table repairs are available.
+ */
+export const preprocessStreamingMarkdown = (text: string, streaming: boolean): string =>
+  streaming
+    ? (getMarkdownParsersSync()?.stabilizeStreamingMarkdown ?? stabilizeStreamingTables)(text)
+    : text;
+
 
 /**
  * Options for creating a markdown processor

package/src/session.ts

@@ -875,11 +875,14 @@ export class AgentWidgetSession {
    * Toggle voice recognition on/off
    */
   public async toggleVoice() {
+    const generation = this.#voiceSetupGeneration;
     // A click can race the setup chunk load; wait for it rather than
     // erroring (prefetch at construction makes this window ~one microtask).
     if (!this.#voiceProvider && this.#voiceSetupPromise) {
       await this.#voiceSetupPromise;
     }
+    // A navigation or config replacement supersedes a click waiting on setup.
+    if (generation !== this.#voiceSetupGeneration) return;
     if (!this.#voiceProvider) {
       console.error('Voice not configured');
       return;

package/src/styles/widget.css

@@ -6773,6 +6773,12 @@
   outline-offset: 2px;
 }
 
+/* revealToolCall() marks the revealed tool briefly. */
+.persona-tool-bubble[data-persona-revealed] {
+  outline: 2px solid var(--persona-focus-ring, var(--persona-primary, #171717));
+  outline-offset: 2px;
+}
+
 /* Compact approval disclosures share the tool detail surfaces. */
 .persona-approval-row .persona-approval-details {
   display: grid;

package/src/types.ts

@@ -3568,6 +3568,14 @@ export type AgentWidgetOpenConversationOptions = {
   busy?: "reject" | "stop" | "background";
 };
 
+/** Options for `controller.revealToolCall()`. */
+export type AgentWidgetRevealToolCallOptions = {
+  /** Expand the tool's details. Default true. */
+  expand?: boolean;
+  /** How long the bubble keeps `data-persona-revealed`, in ms; 0 skips the mark. Default 2000. */
+  highlightMs?: number;
+};
+
 /** The single in-flight history operation, or `null` when idle. */
 export type HistoryPendingAction =
   | { kind: "refresh" | "load-more" | "start-new" | "clear" | "reset" }
@@ -8557,6 +8565,11 @@ export type AgentWidgetConfig = {
    * ```
    */
   webmcp?: AgentWidgetWebMcpConfig;
+  /**
+   * Custom HTML renderer; receives unmodified streaming text. To opt into the
+   * default Markdown display repairs after your text transforms, call
+   * `preprocessStreamingMarkdown(text, streaming)` before your Markdown parser.
+   */
   postprocessMessage?: (context: {
     text: string;
     message: AgentWidgetMessage;

package/src/ui.background-conversations.test.ts

@@ -43,6 +43,12 @@ it.each([false, true])("restores the draft and emits conversation-scoped backgro
   expect(widget.getComposerState().text).toBe("");
   expect(states).toHaveBeenCalledWith(expect.objectContaining({ conversationId: "a", status: "running", detached: true }), expect.objectContaining({ instanceId: expect.any(String) }));
   widget.setMessage("Draft B");
+  window.dispatchEvent(new PageTransitionEvent("pagehide", { persisted: true }));
+  window.dispatchEvent(new PageTransitionEvent("pageshow", { persisted: true }));
+  // Cached restoration must not discard A's detached replay checkpoint or
+  // attach a foreground reader until the visitor opens that conversation.
+  expect(widget.getComposerState().text).toBe("Draft B");
+  expect(reconnect).not.toHaveBeenCalled();
   await widget.openConversation("a");
   await vi.waitFor(() => expect(widget.getMessages().filter(message => message.content === "Partial reply")).toHaveLength(1));
   expect(widget.getComposerState().text).toBe("Follow-up draft A");

package/src/ui.footer-visibility.test.ts

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { initAgentWidget } from "./runtime/init";
+import { createAgentExperience, type AgentWidgetController } from "./ui";
+
+let mount: HTMLElement;
+let controller: { destroy: () => void } | undefined;
+
+const footer = () => mount.querySelector<HTMLElement>(".persona-widget-footer");
+const settle = async () => {
+  await vi.dynamicImportSettled();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+beforeEach(() => {
+  window.localStorage.clear();
+  window.scrollTo = vi.fn();
+  mount = document.createElement("div");
+  mount.id = "chat";
+  document.body.appendChild(mount);
+});
+
+afterEach(() => {
+  controller?.destroy();
+  controller = undefined;
+  document.body.replaceChildren();
+});
+
+describe.each([false, true])("layout.showFooter: false (V5 defaults: %s)", (v5Defaults) => {
+  const config = {
+    apiUrl: "/test",
+    persistState: false,
+    future: { v5Defaults },
+    launcher: { enabled: false },
+    layout: { embedded: true, showFooter: false },
+    initialMessages: [{ id: "m1", role: "user" as const, content: "Hi", createdAt: "2026-01-01T00:00:00Z" }],
+  };
+
+  it("keeps the footer hidden after the widget is ready", async () => {
+    controller = initAgentWidget({ target: "#chat", useShadowDom: false, config });
+    await settle();
+    expect(footer()?.style.display).toBe("none");
+  });
+
+  it("keeps the footer hidden when an update rebuilds the composer", async () => {
+    const experience: AgentWidgetController = createAgentExperience(mount, config);
+    controller = experience;
+    await settle();
+    experience.update({ contextMentions: { enabled: false } });
+    await settle();
+    expect(footer()?.style.display).toBe("none");
+  });
+});

package/src/ui.page-cache.test.ts

@@ -0,0 +1,268 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { createAgentExperience } from "./ui";
+import type { AgentWidgetConfig, SpeechEngine, VoiceProvider, VoiceResult, VoiceStatus } from "./types";
+
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+beforeEach(() => { window.scrollTo = vi.fn(); });
+afterEach(() => {
+  controllers.splice(0).forEach(controller => controller.destroy());
+  document.body.replaceChildren();
+  localStorage.clear();
+  sessionStorage.clear();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+function mount(config: AgentWidgetConfig = {}) {
+  const element = document.createElement("div");
+  document.body.append(element);
+  const controller = createAgentExperience(element, {
+    apiUrl: "/local-chat", launcher: { enabled: false }, persistState: false,
+    suggestionChips: [], ...config,
+  });
+  controllers.push(controller);
+  return { controller, element };
+}
+const transition = (name: "pagehide" | "pageshow", persisted = true) =>
+  window.dispatchEvent(new PageTransitionEvent(name, { persisted }));
+
+function voice() {
+  let active = false;
+  let status: (status: VoiceStatus) => void = () => {};
+  let result: (result: VoiceResult) => void = () => {};
+  const provider: VoiceProvider = {
+    type: "custom", connect: vi.fn(async () => {}),
+    disconnect: vi.fn(async () => { active = false; }),
+    startListening: vi.fn(async () => { active = true; status("listening"); }),
+    stopListening: vi.fn(async () => { active = false; status("idle"); }),
+    onStatusChange: callback => { status = callback; },
+    onResult: callback => { result = callback; }, onError: () => {},
+    isBargeInActive: () => active,
+  };
+  return { provider, result: (text: string) => result({ text, isFinal: true, provider: "custom" }) };
+}
+
+it("aborts an active reply while retaining the same transcript and draft through repeated Back restores", async () => {
+  const signals: AbortSignal[] = [];
+  const customFetch = vi.fn((_url, init) => {
+    const signal = init!.signal!;
+    signals.push(signal);
+    return new Promise<Response>((_resolve, reject) => {
+      signal.addEventListener("abort", () => reject(new DOMException("Stopped", "AbortError")), { once: true });
+    });
+  });
+  const { controller, element } = mount({ customFetch });
+  for (let cycle = 0; cycle < 3; cycle++) {
+    expect(controller.submitMessage(`Question ${cycle}`)).toBe(true);
+    await vi.waitFor(() => expect(signals).toHaveLength(cycle + 1));
+    const input = element.querySelector<HTMLTextAreaElement>("[data-persona-composer-input]")!;
+    input.value = "Keep this draft";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    transition("pagehide");
+    expect(signals[cycle].aborted).toBe(true);
+    expect(controller.getState().streaming).toBe(false);
+    transition("pageshow");
+    expect(element.querySelector("[data-persona-composer-input]")).toBe(input);
+    expect(controller.getComposerState().text).toBe("Keep this draft");
+    expect(controller.getMessages().some(message => message.content === `Question ${cycle}`)).toBe(true);
+    await Promise.resolve();
+    expect(customFetch).toHaveBeenCalledTimes(cycle + 1);
+  }
+});
+
+it("disconnects session voice on cached hide and keeps the controls usable without restarting the call", async () => {
+  const { provider } = voice();
+  const { controller } = mount({ voiceRecognition: { enabled: true, provider: { type: "custom", custom: () => provider } } });
+  for (let cycle = 0; cycle < 2; cycle++) {
+    controller.startVoiceRecognition();
+    await vi.waitFor(() => expect(provider.startListening).toHaveBeenCalledTimes(cycle + 1));
+    transition("pagehide");
+    expect(provider.disconnect).toHaveBeenCalledTimes(cycle + 1);
+    expect(controller.isVoiceActive()).toBe(false);
+    transition("pageshow");
+    await Promise.resolve();
+    expect(provider.startListening).toHaveBeenCalledTimes(cycle + 1);
+  }
+});
+
+it("does not let a pending microphone start cross a cached navigation", async () => {
+  const { provider } = voice();
+  const { controller } = mount({ voiceRecognition: { enabled: true, provider: { type: "custom", custom: () => provider } } });
+  controller.startVoiceRecognition();
+  transition("pagehide");
+  transition("pageshow");
+  await new Promise(resolve => setTimeout(resolve, 50));
+  expect(provider.startListening).not.toHaveBeenCalled();
+  controller.startVoiceRecognition();
+  await vi.waitFor(() => expect(provider.startListening).toHaveBeenCalledOnce());
+});
+
+it("cancels dictation without submitting its final result or losing the previous draft", async () => {
+  const { provider, result } = voice();
+  const { controller } = mount({ voiceRecognition: { enabled: true, completionBehavior: "review",
+    dictation: { provider: { type: "custom", custom: () => provider } } } });
+  controller.setMessage("Original draft");
+  controller.startDictation();
+  await vi.waitFor(() => expect(controller.getDictationState().phase).toBe("recording"));
+  transition("pagehide");
+  result("Late transcript");
+  transition("pageshow");
+  await vi.waitFor(() => expect(provider.disconnect).toHaveBeenCalled());
+  expect(controller.getDictationState().phase).toBe("idle");
+  expect(controller.getComposerState().text).toBe("Original draft");
+  expect(controller.getMessages()).toHaveLength(0);
+});
+
+it("stops browser recognition without accepting a trailing result and can record again on Back", () => {
+  const recordings: Recognition[] = [];
+  class Recognition {
+    onresult: ((event: unknown) => void) | null = null;
+    onend: (() => void) | null = null;
+    onerror: ((event: unknown) => void) | null = null;
+    start = vi.fn();
+    stop = vi.fn();
+    constructor() { recordings.push(this); }
+  }
+  vi.stubGlobal("SpeechRecognition", Recognition);
+  const { controller } = mount({ voiceRecognition: { enabled: true } });
+  controller.setMessage("Keep my draft");
+  expect(controller.startVoiceRecognition()).toBe(true);
+  expect(recordings[0].start).toHaveBeenCalledOnce();
+  transition("pagehide");
+  expect(recordings[0].stop).toHaveBeenCalledOnce();
+  recordings[0].onresult?.({ results: [Object.assign([{ transcript: "Late result" }], { isFinal: true })] });
+  transition("pageshow");
+  expect(controller.getComposerState().text).toBe("Keep my draft");
+  expect(controller.startVoiceRecognition()).toBe(true);
+  expect(recordings[1].start).toHaveBeenCalledOnce();
+  expect(controller.getMessages()).toHaveLength(0);
+});
+
+it("stops read-aloud playback on cached hide and does not resume it on Back", async () => {
+  const engine: SpeechEngine = { id: "cache-test", supportsPause: false,
+    speak: vi.fn((_request, callbacks) => { callbacks.onStart?.(); }),
+    stop: vi.fn(), pause: vi.fn(), resume: vi.fn(),
+  };
+  const { controller } = mount({ textToSpeech: { enabled: true, createEngine: () => engine } });
+  const message = controller.injectAssistantMessage({ content: "Read this reply aloud." });
+  controller.toggleReadAloud(message.id);
+  await vi.waitFor(() => expect(controller.getReadAloudState(message.id)).toBe("playing"));
+  transition("pagehide");
+  expect(engine.stop).toHaveBeenCalled();
+  expect(controller.getReadAloudState(message.id)).toBe("idle");
+  transition("pageshow");
+  await Promise.resolve();
+  expect(engine.speak).toHaveBeenCalledOnce();
+});
+
+it("abandons an asynchronous before-send hook and leaves its draft sendable after Back", async () => {
+  let finishHook: () => void = () => {};
+  let signal: AbortSignal | undefined;
+  const hook = vi.fn((_snapshot, context) => {
+    signal = context.signal;
+    return new Promise<void>(resolve => { finishHook = resolve; });
+  });
+  const customFetch = vi.fn(async () => new Response("", { headers: { "content-type": "text/event-stream" } }));
+  const { controller, element } = mount({ composer: { onBeforeSend: hook }, customFetch });
+  controller.setMessage("Unsent draft");
+  element.querySelector<HTMLButtonElement>("[data-persona-composer-submit]")!.click();
+  await vi.waitFor(() => expect(hook).toHaveBeenCalledOnce());
+  transition("pagehide");
+  expect(signal?.aborted).toBe(true);
+  transition("pageshow");
+  expect(customFetch).not.toHaveBeenCalled();
+  expect(controller.getComposerState().text).toBe("Unsent draft");
+  let finishNext: () => void = () => {};
+  const nextHook = vi.fn(() => new Promise<void>(resolve => { finishNext = resolve; }));
+  controller.update({ composer: { onBeforeSend: nextHook } });
+  element.querySelector<HTMLButtonElement>("[data-persona-composer-submit]")!.click();
+  await vi.waitFor(() => expect(nextHook).toHaveBeenCalledOnce());
+  finishHook();
+  await Promise.resolve();
+  element.querySelector<HTMLButtonElement>("[data-persona-composer-submit]")!.click();
+  expect(nextHook).toHaveBeenCalledOnce();
+  expect(customFetch).not.toHaveBeenCalled();
+  finishNext();
+  await vi.waitFor(() => expect(customFetch).toHaveBeenCalledOnce());
+});
+
+it("retains the live-call metadata used to redial on a genuine document navigation", async () => {
+  const { provider } = voice();
+  const { controller } = mount({ voiceRecognition: { enabled: true, provider: { type: "custom", custom: () => provider } } });
+  controller.startVoiceRecognition();
+  await vi.waitFor(() => expect(provider.startListening).toHaveBeenCalledOnce());
+  transition("pagehide", false);
+  expect(provider.disconnect).not.toHaveBeenCalled();
+  controller.destroy();
+  controllers.splice(controllers.indexOf(controller), 1);
+  expect(provider.disconnect).toHaveBeenCalledOnce();
+  expect(controller.getPersistentMetadata().voiceState).toMatchObject({ active: true });
+});
+
+it.each(["queued", "late", "injected"])("discards %s action resubmits across Back and accepts fresh actions", async mode => {
+  vi.useFakeTimers();
+  try {
+    let trigger = () => {};
+    const customFetch = vi.fn(async () => new Response("", { headers: { "content-type": "text/event-stream" } }));
+    const { controller } = mount({ customFetch, actionHandlers: [(_action, context) => {
+      trigger = context.triggerResubmit;
+      return { handled: true, displayText: "Action handled", resubmit: mode === "injected" };
+    }] });
+    controller.injectAssistantMessage({ content: '{"action":"search"}' });
+    await vi.advanceTimersByTimeAsync(0);
+    if (mode === "queued") trigger();
+    transition("pagehide");
+    transition("pageshow");
+    if (mode === "late") trigger();
+    if (mode === "injected") controller.injectAssistantMessage({ content: "Late result" });
+    await vi.advanceTimersByTimeAsync(200);
+    expect(customFetch).not.toHaveBeenCalled();
+    controller.injectAssistantMessage({ content: '{"action":"search"}' });
+    await vi.advanceTimersByTimeAsync(0);
+    if (mode !== "injected") trigger();
+    await vi.advanceTimersByTimeAsync(200);
+    expect(customFetch).toHaveBeenCalledOnce();
+  } finally { vi.useRealTimers(); }
+});
+
+it.each(["back", "destroy", "navigation"])("guards queued metadata voice restoration on %s", async lifecycle => {
+  vi.useFakeTimers();
+  try {
+    const { provider } = voice();
+    const { controller } = mount({
+      persistState: true, storageAdapter: { load: () => ({ messages: [], metadata: { voiceState: { active: true, timestamp: Date.now() } } }), save: () => {} },
+      voiceRecognition: { enabled: true, provider: { type: "custom", custom: () => provider } },
+    });
+    if (lifecycle === "back") { transition("pagehide"); transition("pageshow"); }
+    if (lifecycle === "destroy") controller.destroy();
+    await vi.advanceTimersByTimeAsync(1100);
+    expect(provider.startListening).toHaveBeenCalledTimes(lifecycle === "navigation" ? 1 : 0);
+    if (lifecycle === "back") {
+      controller.startVoiceRecognition();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(provider.startListening).toHaveBeenCalledOnce();
+    }
+  } finally { vi.useRealTimers(); }
+});
+
+it("discards the delayed browser voice restore before Back while allowing a fresh mic tap", async () => {
+  vi.useFakeTimers();
+  try {
+    const start = vi.fn();
+    class Recognition { start = start; stop = vi.fn(); }
+    vi.stubGlobal("SpeechRecognition", Recognition);
+    const { controller } = mount({
+      persistState: true,
+      storageAdapter: { load: () => ({ messages: [], metadata: { voiceState: { active: true, timestamp: Date.now() } } }), save: () => {} },
+      voiceRecognition: { enabled: true },
+    });
+    await vi.advanceTimersByTimeAsync(100);
+    expect(start).not.toHaveBeenCalled();
+    transition("pagehide");
+    transition("pageshow");
+    await vi.advanceTimersByTimeAsync(1100);
+    expect(start).not.toHaveBeenCalled();
+    expect(controller.startVoiceRecognition()).toBe(true);
+    expect(start).toHaveBeenCalledOnce();
+  } finally { vi.useRealTimers(); }
+});

package/src/ui.postprocess.test.ts

@@ -3,7 +3,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { buildPostprocessor } from "./ui";
-import { escapeHtml } from "./postprocessors";
+import { escapeHtml, markdownPostprocessor, preprocessStreamingMarkdown } from "./postprocessors";
 import * as parsersLoader from "./markdown-parsers-loader";
 import type { AgentWidgetConfig, AgentWidgetMessage } from "./types";
 
@@ -93,6 +93,62 @@ describe("buildPostprocessor degraded path (parsers not loaded)", () => {
 });
 
 describe("buildPostprocessor loaded path (parsers available)", () => {
+  it("lets custom callbacks transform text before opting into the shared streaming repairs", () => {
+    const text = "<answer>Read **unfinished";
+    const raw = JSON.stringify({ answer: text });
+    const message: AgentWidgetMessage = {
+      id: "custom-stream", role: "assistant", content: text, rawContent: raw, createdAt: "2026-10-20T00:00:00.000Z",
+    };
+    const custom = vi.fn(({ text, streaming }: { text: string; streaming: boolean }) =>
+      markdownPostprocessor(preprocessStreamingMarkdown(text.replace("<answer>", ""), streaming)));
+    const transform = buildPostprocessor({ postprocessMessage: custom, sanitize: true }, undefined, undefined);
+    const displayText = text.replace("<answer>", "");
+    const builtIn = buildPostprocessor({ markdown: {} }, undefined, undefined);
+    expect(transform({ text, raw, message, streaming: true })).toBe(
+      builtIn({ text: displayText, message, streaming: true }));
+    expect(transform({ text, raw, message, streaming: false })).toBe("<p>Read **unfinished</p>\n");
+    expect(message.content).toBe(text);
+    expect(message.rawContent).toBe(raw);
+    expect(custom.mock.calls[0][0]).toMatchObject({ text, raw, streaming: true });
+  });
+
+  it("repairs streaming display without mutating the stored or final Markdown", () => {
+    const text = "Read **unfinished";
+    const message: AgentWidgetMessage = {
+      id: "stream", role: "assistant", content: text, createdAt: "2026-10-20T00:00:00.000Z",
+    };
+    const transform = buildPostprocessor({ markdown: {} }, undefined, undefined);
+    expect(transform({ text, message, streaming: true })).toContain("<strong>unfinished</strong>");
+    expect(message.content).toBe(text);
+    expect(transform({ text, message, streaming: false })).toBe("<p>Read **unfinished</p>\n");
+  });
+
+  it("leaves custom postprocessors and plain-text rendering untouched during streaming", () => {
+    const text = "**unfinished";
+    const message: AgentWidgetMessage = {
+      id: "stream", role: "assistant", content: text, createdAt: "2026-10-20T00:00:00.000Z",
+    };
+    const custom = vi.fn(({ text }: { text: string }) => escapeHtml(text));
+    const transform = buildPostprocessor({ markdown: {}, postprocessMessage: custom }, undefined, undefined);
+    expect(transform({ text, message, streaming: true })).toBe(text);
+    expect(custom.mock.calls[0][0].text).toBe(text);
+    expect(buildPostprocessor(undefined, undefined, undefined)({ text, message, streaming: true })).toBe(text);
+  });
+
+  it("sanitizes completed links after streaming repair and retains legacy custom parser compatibility", () => {
+    const text = "[bad](javascript:alert(1)) **hello";
+    const message: AgentWidgetMessage = {
+      id: "stream", role: "assistant", content: text, createdAt: "2026-10-20T00:00:00.000Z",
+    };
+    const transform = buildPostprocessor({ markdown: {} }, undefined, undefined);
+    const out = transform({ text, message, streaming: true });
+    expect(out).toContain("<strong>hello</strong>");
+    expect(out).not.toContain("javascript:");
+    const parsers = parsersLoader.getMarkdownParsersSync()!;
+    vi.spyOn(parsersLoader, "getMarkdownParsersSync").mockReturnValue({ Marked: parsers.Marked, DOMPurify: parsers.DOMPurify });
+    expect(transform({ text, message, streaming: true })).toContain("**hello");
+  });
+
   it("renders markdown to real HTML, normalizes apostrophes, strips scripts", () => {
     // No spy: vitest.setup.ts eager-provides parsers, so this is the loaded path.
     const text = "**bold** I'll go\n\n<script>alert(1)</script>";
@@ -152,3 +208,26 @@ describe("buildPostprocessor failure containment", () => {
     expect(out).toBe(escapeHtml(SAMPLE));
   });
 });
+
+describe("preprocessStreamingMarkdown parser readiness", () => {
+  it("leaves final text unchanged even when a parser repair would modify it", () => {
+    const repair = vi.fn(() => "repaired");
+    const parsers = parsersLoader.getMarkdownParsersSync()!;
+    vi.spyOn(parsersLoader, "getMarkdownParsersSync").mockReturnValue({ ...parsers, stabilizeStreamingMarkdown: repair });
+    expect(preprocessStreamingMarkdown("**unfinished", false)).toBe("**unfinished");
+    expect(repair).not.toHaveBeenCalled();
+    expect(preprocessStreamingMarkdown("**unfinished", true)).toBe("repaired");
+  });
+
+  it("uses the same lightweight table fallback before parsers load and with legacy loaders", () => {
+    const parsers = parsersLoader.getMarkdownParsersSync()!;
+    const text = "| A | B |\n| ---";
+    vi.spyOn(parsersLoader, "getMarkdownParsersSync").mockReturnValue(null);
+    const beforeLoad = preprocessStreamingMarkdown(text, true);
+    expect(beforeLoad).not.toBe(text);
+    expect(preprocessStreamingMarkdown("**unfinished", true)).toBe("**unfinished");
+    vi.mocked(parsersLoader.getMarkdownParsersSync).mockReturnValue({ Marked: parsers.Marked, DOMPurify: parsers.DOMPurify });
+    expect(preprocessStreamingMarkdown(text, true)).toBe(beforeLoad);
+    expect(preprocessStreamingMarkdown(text, false)).toBe(text);
+  });
+});