@runtypelabs/persona 3.37.0 → 4.0.0

package/src/index-core.ts

@@ -108,11 +108,10 @@ export type {
 } from "./types";
 
 export type {
-  RuntypeAgentSSEEvent,
+  RuntypeExecutionStreamEvent,
   RuntypeFlowSSEEvent,
-  RuntypeDispatchSSEEvent,
   RuntypeStreamEventOf,
-  RuntypeAgentTurnCompleteEvent,
+  RuntypeTurnCompleteEvent,
   RuntypeStepCompleteEvent,
   RuntypeStopReasonKind,
   RuntypeClientInitRequest,

package/src/install.test.ts

@@ -15,7 +15,6 @@ const PERSONA_EVENTS = [
   "persona:script-load",
   "persona:launcher-shown",
   "persona:chat-ready",
-  "persona:ready",
   "persona:error",
 ] as const;
 
@@ -28,7 +27,6 @@ let launcherDestroy: ReturnType<typeof vi.fn>;
 let launcherElement: HTMLButtonElement;
 let initAgentWidget: ReturnType<typeof vi.fn>;
 let fakeHandle: FakeHandle;
-let warnSpy: ReturnType<typeof vi.spyOn>;
 let errorSpy: ReturnType<typeof vi.spyOn>;
 
 /** Subscribe to every persona:* event and record dispatch order + detail. */
@@ -128,7 +126,7 @@ beforeEach(() => {
   fakeHandle = { open: vi.fn(), close: vi.fn(), on: vi.fn() };
   initAgentWidget = vi.fn(() => fakeHandle);
 
-  warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  vi.spyOn(console, "warn").mockImplementation(() => {});
   errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
 });
 
@@ -345,37 +343,6 @@ describe("install.ts: deferral gate", () => {
   });
 });
 
-describe("install.ts: onReady deprecation alias", () => {
-  it("still calls the deprecated onReady and warns once", async () => {
-    markCssLoaded();
-    provideFullBundle();
-    const onReady = vi.fn();
-
-    await install({ config: { apiUrl: "/api", launcher: { enabled: false } }, onReady });
-    await flush();
-
-    expect(onReady).toHaveBeenCalledTimes(1);
-    expect(onReady).toHaveBeenCalledWith(fakeHandle);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(String(warnSpy.mock.calls[0]?.[0])).toContain("`onReady` is deprecated");
-  });
-
-  it("prefers onChatReady over onReady and does not warn", async () => {
-    markCssLoaded();
-    provideFullBundle();
-    const onReady = vi.fn();
-    const onChatReady = vi.fn();
-
-    await install({ config: { apiUrl: "/api", launcher: { enabled: false } }, onReady, onChatReady });
-    await flush();
-
-    expect(onChatReady).toHaveBeenCalledTimes(1);
-    expect(onChatReady).toHaveBeenCalledWith(fakeHandle);
-    expect(onReady).not.toHaveBeenCalled();
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-});
-
 describe("install.ts: onError", () => {
   it("fires onError with phase 'init' and dispatches persona:error when initialization throws", async () => {
     markCssLoaded();

package/src/install.ts

@@ -18,9 +18,6 @@ interface SiteAgentInstallConfig {
   clientToken?: string;
   flowId?: string;
   apiUrl?: string;
-  /** Wire vocabulary requested from the dispatch endpoint; 'unified' opts into the
-   *  API's neutral event schema (transparently bridged back to the same rendering). */
-  events?: "legacy" | "unified";
   // Optional query param key that gates widget installation in preview mode
   previewQueryParam?: string;
   // Shadow DOM option (defaults to false for better CSS compatibility)
@@ -46,11 +43,6 @@ interface SiteAgentInstallConfig {
    * installs: on page load.
    */
   onChatReady?: (handle: any) => void;
-  /**
-   * @deprecated Use `onChatReady`. Retained as a working alias; it will be
-   * removed in the next major version.
-   */
-  onReady?: (handle: any) => void;
   /**
    * Fired when a load step fails (stylesheet, full bundle, or init), so you can
    * detect ad-blocked / timed-out installs instead of failing silently.
@@ -163,21 +155,6 @@ declare global {
     safeCall(config.onError, { phase, error });
     dispatchLifecycle("persona:error", { phase, error });
   };
-  // `onReady` is the deprecated alias of `onChatReady`; warn once if it's used.
-  let warnedOnReadyDeprecated = false;
-  const resolveChatReady = (): ((handle: any) => void) | undefined => {
-    if (config.onChatReady) return config.onChatReady;
-    if (config.onReady) {
-      if (!warnedOnReadyDeprecated) {
-        warnedOnReadyDeprecated = true;
-        console.warn(
-          "[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
   // case that paints a clickable launcher at load. Shared by the deferral gate
   // and the eager-path `onLauncherShown` so the event name stays honest.
@@ -380,7 +357,6 @@ declare global {
     if (config.apiUrl && !widgetConfig.apiUrl) widgetConfig.apiUrl = config.apiUrl;
     if (config.clientToken && !widgetConfig.clientToken) widgetConfig.clientToken = config.clientToken;
     if (config.flowId && !widgetConfig.flowId) widgetConfig.flowId = config.flowId;
-    if (config.events && !widgetConfig.events) widgetConfig.events = config.events;
 
     const hasApiConfig = !!(widgetConfig.apiUrl || widgetConfig.clientToken);
     return { target, widgetConfig, hasApiConfig };
@@ -433,9 +409,8 @@ declare global {
       }
 
       // The full widget is initialized and its controller API is callable.
-      safeCall(resolveChatReady(), handle);
+      safeCall(config.onChatReady, handle);
       dispatchLifecycle("persona:chat-ready", handle);
-      dispatchLifecycle("persona:ready", handle); // deprecated alias: removed next major
       return handle;
     } catch (error) {
       fail("init", error);

package/src/runtime/init.test.ts

@@ -122,21 +122,6 @@ describe("initAgentWidget windowKey and ready notifications", () => {
     handle.destroy();
   });
 
-  it("calls onReady after initialization", async () => {
-    const { initAgentWidget } = await import("./init");
-    document.body.innerHTML = `<div id="target"></div>`;
-
-    const onReady = vi.fn();
-    const handle = initAgentWidget({
-      target: "#target",
-      onReady,
-      config: { launcher: { enabled: false } },
-    });
-
-    expect(onReady).toHaveBeenCalledOnce();
-    handle.destroy();
-  });
-
   it("the window key handle proxies controller methods", async () => {
     const { initAgentWidget } = await import("./init");
     document.body.innerHTML = `<div id="target"></div>`;
@@ -159,7 +144,7 @@ describe("initAgentWidget windowKey and ready notifications", () => {
   });
 });
 
-describe("initAgentWidget onChatReady / onReady deprecation", () => {
+describe("initAgentWidget onChatReady", () => {
   beforeEach(() => {
     document.body.innerHTML = "";
     createAgentExperienceMock.mockReset();
@@ -184,65 +169,21 @@ describe("initAgentWidget onChatReady / onReady deprecation", () => {
     handle.destroy();
     warn.mockRestore();
   });
-
-  it("prefers onChatReady over the deprecated onReady (onReady never fires, no warning)", async () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const { initAgentWidget } = await import("./init");
-    document.body.innerHTML = `<div id="target"></div>`;
-
-    const onChatReady = vi.fn();
-    const onReady = vi.fn();
-    const handle = initAgentWidget({
-      target: "#target",
-      onChatReady,
-      onReady,
-      config: { launcher: { enabled: false } },
-    });
-
-    expect(onChatReady).toHaveBeenCalledOnce();
-    expect(onReady).not.toHaveBeenCalled();
-    expect(warn).not.toHaveBeenCalled();
-
-    handle.destroy();
-    warn.mockRestore();
-  });
-
-  it("still calls the deprecated onReady but warns at most once across multiple widgets", async () => {
-    // Fresh module so the once-per-page warn flag starts unset.
-    vi.resetModules();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const { initAgentWidget } = await import("./init");
-    document.body.innerHTML = `<div id="a"></div><div id="b"></div>`;
-
-    const onReadyA = vi.fn();
-    const onReadyB = vi.fn();
-    const a = initAgentWidget({ target: "#a", onReady: onReadyA, config: { launcher: { enabled: false } } });
-    const b = initAgentWidget({ target: "#b", onReady: onReadyB, config: { launcher: { enabled: false } } });
-
-    expect(onReadyA).toHaveBeenCalledOnce();
-    expect(onReadyB).toHaveBeenCalledOnce();
-    expect(warn).toHaveBeenCalledTimes(1);
-    expect(String(warn.mock.calls[0]?.[0])).toContain("`onReady` is deprecated");
-
-    a.destroy();
-    b.destroy();
-    warn.mockRestore();
-  });
 });
 
-describe("install script onReady and persona:ready event", () => {
+describe("install script persona:chat-ready event", () => {
   beforeEach(() => {
     document.body.innerHTML = "";
     createAgentExperienceMock.mockReset();
     createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
   });
 
-  it("persona:ready event fires with the handle as detail", async () => {
+  it("persona:chat-ready event fires with the handle as detail", async () => {
     const { initAgentWidget } = await import("./init");
     document.body.innerHTML = `<div id="target"></div>`;
 
     const eventPromise = new Promise<any>((resolve) => {
-      window.addEventListener("persona:ready", (e) => {
+      window.addEventListener("persona:chat-ready", (e) => {
         resolve((e as CustomEvent).detail);
       }, { once: true });
     });
@@ -254,7 +195,7 @@ describe("install script onReady and persona:ready event", () => {
     });
 
     // Simulate what install.ts does after initAgentWidget returns
-    window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+    window.dispatchEvent(new CustomEvent("persona:chat-ready", { detail: handle }));
 
     const detail = await eventPromise;
     expect(detail).toBe(handle);
@@ -264,12 +205,12 @@ describe("install script onReady and persona:ready event", () => {
     handle.destroy();
   });
 
-  it("persona:ready event listener set up before init receives the handle", async () => {
+  it("persona:chat-ready event listener set up before init receives the handle", async () => {
     const { initAgentWidget } = await import("./init");
     document.body.innerHTML = `<div id="target"></div>`;
 
     const received: any[] = [];
-    window.addEventListener("persona:ready", (e) => {
+    window.addEventListener("persona:chat-ready", (e) => {
       received.push((e as CustomEvent).detail);
     }, { once: true });
 
@@ -279,7 +220,7 @@ describe("install script onReady and persona:ready event", () => {
     });
 
     // Simulate install.ts dispatching the event
-    window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+    window.dispatchEvent(new CustomEvent("persona:chat-ready", { detail: handle }));
 
     expect(received).toHaveLength(1);
     expect(received[0]).toBe(handle);

package/src/runtime/init.ts

@@ -3,9 +3,6 @@ import { AgentWidgetConfig as _AgentWidgetConfig, AgentWidgetInitOptions, AgentW
 import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
 import { createWidgetHostLayout } from "./host-layout";
 
-// Warn at most once per page when the deprecated `onReady` alias is used.
-let warnedOnReadyDeprecated = false;
-
 const ensureTarget = (target: string | HTMLElement): HTMLElement => {
   if (typeof window === "undefined" || typeof document === "undefined") {
     throw new Error("Chat widget can only be mounted in a browser environment");
@@ -160,20 +157,8 @@ export const initAgentWidget = (
   };
 
   mountController();
-  // Fired when the controller is mounted and its API is callable. `onReady` is
-  // the deprecated alias of `onChatReady` (removed next major): warn once.
-  if (options.onChatReady) {
-    options.onChatReady();
-  } else if (options.onReady) {
-    if (!warnedOnReadyDeprecated) {
-      warnedOnReadyDeprecated = true;
-      // eslint-disable-next-line no-console
-      console.warn(
-        "[Persona] `onReady` is deprecated: use `onChatReady`. `onReady` still works but is removed in the next major."
-      );
-    }
-    options.onReady();
-  }
+  // Fired when the controller is mounted and its API is callable.
+  options.onChatReady?.();
 
   const rebuildLayout = (nextConfig?: _AgentWidgetConfig) => {
     destroyCurrentController();

package/src/session.test.ts

@@ -893,7 +893,7 @@ describe('AgentWidgetSession.resolveApproval', () => {
   });
 });
 
-describe('AgentWidgetSession - approval context across agent_approval_complete', () => {
+describe('AgentWidgetSession - approval context across approval_complete', () => {
   const sseStream = (events: Array<Record<string, unknown>>): ReadableStream<Uint8Array> => {
     const encoder = new TextEncoder();
     const body = events
@@ -919,14 +919,14 @@ describe('AgentWidgetSession - approval context across agent_approval_complete',
       }
     );
 
-    // `agent_approval_complete` carries only the resolution: none of the
-    // context fields from `agent_approval_start`. The session merge must keep
-    // them so a full re-render of the resolved bubble (morph, virtual-scroll
-    // re-mount, storage restore) still shows the tool, description, and the
-    // agent's stated reason.
+    // Unified `approval_complete` carries only the resolution: none of the
+    // context fields from `approval_start`. The session merge must keep them so
+    // a full re-render of the resolved bubble (morph, virtual-scroll re-mount,
+    // storage restore) still shows the tool, description, and the agent's stated
+    // reason.
     await session.connectStream(sseStream([
       {
-        type: 'agent_approval_start',
+        type: 'approval_start',
         executionId: 'exec_abc',
         approvalId: 'appr_1',
         toolName: 'send_email',
@@ -936,7 +936,7 @@ describe('AgentWidgetSession - approval context across agent_approval_complete',
         parameters: { to: 'customer@example.com' },
       },
       {
-        type: 'agent_approval_complete',
+        type: 'approval_complete',
         executionId: 'exec_abc',
         approvalId: 'appr_1',
         decision: 'approved',

package/src/session.ts

@@ -2920,7 +2920,7 @@ export class AgentWidgetSession {
           awaitingLocalTool: false,
         };
       }
-      // Approval equivalent: `agent_approval_complete` carries only the
+      // Approval equivalent: `approval_complete` carries only the
       // resolution (approvalId, decision, resolvedBy): the runtime does not
       // re-send toolName/description/toolType/reason/parameters, so client.ts
       // rebuilds the approval with empty required fields and the optional

package/src/types.ts

@@ -3588,6 +3588,11 @@ export type AgentWidgetConfig = {
    * When provided, the widget uses agent loop execution instead of flow dispatch.
    * Mutually exclusive with `flowId`.
    *
+   * Note: `@runtypelabs/persona-proxy` rejects a client-supplied `agent` (it was
+   * an open relay). This option is only for endpoints authorized to accept a
+   * client agent — your own backend, or token-scoped direct-to-Runtype dispatch.
+   * For the proxy, pin the agent server-side with `agentConfig`/`agentId`.
+   *
    * @example
    * ```typescript
    * config: {
@@ -4056,16 +4061,6 @@ export type AgentWidgetConfig = {
    * ```
    */
   parseSSEEvent?: AgentWidgetSSEEventParser;
-  /**
-   * Wire vocabulary requested from the dispatch endpoint.
-   * - `'legacy'` (default): the current `agent_*` / `flow_*` SSE events.
-   * - `'unified'`: opt into the API's neutral unified event vocabulary by sending
-   *   `?events=unified`; incoming frames are transparently bridged back to the same
-   *   handlers, so rendering is unchanged. Requires an upstream that honors the
-   *   param — the widget detects the actual wire mode from the first stream frame
-   *   and falls back to legacy automatically if the param was ignored.
-   */
-  events?: "legacy" | "unified";
   /**
    * Called for every parsed SSE frame (after JSON parse), before native handling.
    * Use for lightweight side effects (e.g. telemetry). Does not replace native
@@ -4254,6 +4249,12 @@ export type AgentWidgetReasoning = {
   id: string;
   status: "pending" | "streaming" | "complete";
   chunks: string[];
+  /**
+   * Reasoning channel scope (unified spec). `"turn"` is ordinary per-turn
+   * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
+   * replaced the legacy `agent_reflection` event). Absent for legacy streams.
+   */
+  scope?: "turn" | "loop";
   startedAt?: number;
   completedAt?: number;
   durationMs?: number;
@@ -4633,8 +4634,6 @@ export type AgentWidgetInitOptions = {
   useShadowDom?: boolean;
   /** Fired when the widget controller is mounted and its API is callable. */
   onChatReady?: () => void;
-  /** @deprecated Use `onChatReady`. Retained as an alias; removed in the next major. */
-  onReady?: () => void;
   windowKey?: string; // If provided, stores the controller on window[windowKey] for global access
   debugTools?: boolean;
 };

package/src/ui.postprocess.test.ts

@@ -0,0 +1,107 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { buildPostprocessor } from "./ui";
+import { escapeHtml } from "./postprocessors";
+import * as parsersLoader from "./markdown-parsers-loader";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "./types";
+
+/**
+ * Regression tests for the degraded (parsers-not-loaded) render path.
+ *
+ * In the IIFE/CDN build, `marked` + `DOMPurify` load lazily. Until they resolve
+ * (or permanently, if the chunk 404s), both the markdown processor and the
+ * sanitizer fall back to `escapeHtml`. The old blanket `sanitize(html)` composed
+ * the two fallbacks and escaped twice ("I'll" -> "I'"). The bug lives in
+ * the COMPOSITION inside `buildPostprocessor`, so these tests drive the transform
+ * end-to-end rather than testing the primitives in isolation.
+ *
+ * `vitest.setup.ts` eager-provides parsers, so `getMarkdownParsersSync()` is
+ * non-null by default -> that's the "loaded" path. The degraded path is simulated
+ * by spying on the loader and returning null. Each consuming module
+ * (`ui.ts`, `sanitize.ts`, `postprocessors.ts`) calls the imported binding
+ * directly per invocation, so the spy propagates.
+ */
+
+const SAMPLE = "a & b < c, I'll go";
+
+const callTransform = (
+  cfg: AgentWidgetConfig | undefined,
+  text: string
+): string => {
+  const transform = buildPostprocessor(cfg, undefined, undefined);
+  const message: AgentWidgetMessage = {
+    id: "1",
+    role: "assistant",
+    content: text,
+    createdAt: "2026-06-17T00:00:00.000Z",
+  };
+  return transform({ text, message, streaming: false });
+};
+
+const simulateParsersNotLoaded = () => {
+  vi.spyOn(parsersLoader, "getMarkdownParsersSync").mockReturnValue(null);
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("buildPostprocessor degraded path (parsers not loaded)", () => {
+  it("escapes plain text exactly once (no markdown config, default sanitize)", () => {
+    simulateParsersNotLoaded();
+    const out = callTransform(undefined, SAMPLE);
+
+    expect(out).toContain("I&#39;ll");
+    expect(out).toContain("a &amp; b");
+    expect(out).not.toContain("&amp;#39;");
+    expect(out).not.toContain("&amp;amp;");
+  });
+
+  it("escapes exactly once when a markdown config is set", () => {
+    simulateParsersNotLoaded();
+    const out = callTransform({ markdown: {} }, SAMPLE);
+
+    // Markdown processor falls back to escapeHtml while parsers are not loaded,
+    // and the sanitizer is skipped (parsersReady === false) so it stays single.
+    expect(out).toBe(escapeHtml(SAMPLE));
+    expect(out).not.toContain("&amp;#39;");
+    expect(out).not.toContain("&amp;amp;");
+  });
+
+  it("escapes custom postprocessMessage HTML exactly once (default sanitize)", () => {
+    simulateParsersNotLoaded();
+    const cfg: AgentWidgetConfig = {
+      postprocessMessage: () => "<b>I'll</b>",
+    };
+    const out = callTransform(cfg, SAMPLE);
+
+    // The sanitizer's degraded fallback escapes the raw custom HTML — but only
+    // once, because custom HTML is NOT pre-escaped.
+    expect(out).toBe("&lt;b&gt;I&#39;ll&lt;/b&gt;");
+    expect(out).not.toContain("&amp;#39;");
+  });
+
+  it("regression: degraded plain text is single-escaped, never double-applied", () => {
+    simulateParsersNotLoaded();
+    const out = callTransform(undefined, SAMPLE);
+
+    expect(out).toBe(escapeHtml(SAMPLE));
+    expect(out).not.toBe(escapeHtml(escapeHtml(SAMPLE)));
+  });
+});
+
+describe("buildPostprocessor loaded path (parsers available)", () => {
+  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>";
+    const out = callTransform({ markdown: {} }, text);
+
+    expect(out).toContain("<strong>bold</strong>");
+    expect(out).toContain("<p>");
+    expect(out).toContain("I'll");
+    expect(out).not.toContain("<script");
+    expect(out).not.toContain("&amp;#39;");
+  });
+});

package/src/ui.ts

@@ -36,6 +36,7 @@ import { resolveTokenValue } from "./utils/tokens";
 import { renderLucideIcon } from "./utils/icons";
 import { createElement, createElementInDocument } from "./utils/dom";
 import { morphMessages } from "./utils/morph";
+import { normalizeCopiedSelectionText } from "./utils/copy-selection";
 import {
   navigateComposerHistory,
   INITIAL_HISTORY_STATE,
@@ -403,7 +404,7 @@ type Controller = {
   ) => Promise<void>;
 };
 
-const buildPostprocessor = (
+export const buildPostprocessor = (
   cfg: AgentWidgetConfig | undefined,
   actionManager?: ReturnType<typeof createActionManager>,
   onResubmitRequested?: () => void
@@ -452,21 +453,35 @@ const buildPostprocessor = (
       }
     }
 
-    // Priority: postprocessMessage > markdown config > escapeHtml
+    // Priority: postprocessMessage > markdown config > escapeHtml.
+    //
+    // Degraded path (IIFE/CDN build before `markdown-parsers.js` resolves, or if
+    // it never loads): the markdown processor and the sanitizer BOTH fall back to
+    // escapeHtml, so the old `sanitize(markdownProcessor(text))` escaped twice and
+    // displayed entities literally (I'll -> &amp;#39;). Only run the sanitizer when
+    // it can actually parse HTML; escapeHtml output is already inert. Checked per
+    // render (not once at setup): the chunk lands later and the self-heal re-renders.
+    const parsersReady = getMarkdownParsersSync() !== null;
     let html: string;
     if (cfg?.postprocessMessage) {
-      html = cfg.postprocessMessage({
+      const out = cfg.postprocessMessage({
         ...context,
         text: nextText,
         raw: rawPayload ?? context.text ?? ""
       });
+      // Custom HTML is NOT pre-escaped, so this stays a single pass even via the
+      // sanitizer's degraded fallback. Honors `sanitize: false` (pass-through) as before.
+      html = sanitize ? sanitize(out) : out;
     } else if (markdownProcessor) {
-      html = markdownProcessor(nextText);
+      // Already escapeHtml(text) (single, safe) while parsers are not loaded.
+      const out = markdownProcessor(nextText);
+      html = sanitize && parsersReady ? sanitize(out) : out;
     } else {
+      // Plain text: escapeHtml output is inert — never re-sanitize (the second escape).
       html = escapeHtml(nextText);
     }
 
-    return sanitize ? sanitize(html) : html;
+    return html;
   };
 };
 
@@ -1355,6 +1370,26 @@ export const createAgentExperience = (
     }
   });
 
+  // Normalize manual (triple-click + Ctrl/Cmd-C) copies of message text. The
+  // browser serializes the DOM selection, and block-level markdown elements
+  // (<p>, <li>, <pre>, …) emit surrounding newlines — so a single-message copy
+  // arrives with stray trailing/leading blank lines. Rewrite the clipboard's
+  // plain text to the trimmed selection so the buffer matches what was visibly
+  // highlighted. (The Copy action button is unaffected; it uses message.content.)
+  messagesWrapper.addEventListener('copy', (event) => {
+    const { clipboardData } = event;
+    if (!clipboardData) return;
+    const root = messagesWrapper.getRootNode() as { getSelection?: () => Selection | null };
+    const selection =
+      typeof root.getSelection === 'function' ? root.getSelection() : window.getSelection();
+    if (!selection || selection.isCollapsed) return;
+    const raw = selection.toString();
+    const normalized = normalizeCopiedSelectionText(raw);
+    if (!normalized || normalized === raw) return;
+    clipboardData.setData('text/plain', normalized);
+    event.preventDefault();
+  });
+
   // Add event delegation for message action buttons (upvote, downvote, copy)
   // This handles clicks even after idiomorph morphs the DOM and strips inline listeners
   const messageVoteState = new Map<string, "upvote" | "downvote">();