@runtypelabs/persona 4.32.1 → 4.33.0

package/src/types/theme.ts

@@ -580,6 +580,27 @@ export interface MessageTokens {
     /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
   };
+  /**
+   * Operator bubble: a human speaking on the agent's side (`role: "operator"`).
+   * Renders on the assistant's side. Defaults tint the container with the
+   * theme primary (`--persona-primary`), so `brand` themes follow without
+   * extra config. Geometry keys fall back to the layout preset, not to the
+   * assistant's geometry.
+   */
+  operator?: MessageGeometryTokens & {
+    /** @default "color-mix(in srgb, var(--persona-primary) 6%, var(--persona-container))" */
+    background?: TokenReference<'color'>;
+    /** @default semantic.colors.text */
+    text?: TokenReference<'color'>;
+    /** @default palette.radius.lg */
+    borderRadius?: TokenReference<'radius'>;
+    /** @default "color-mix(in srgb, var(--persona-primary) 20%, var(--persona-container))" */
+    border?: TokenReference<'color'>;
+    /** Border width; set to 0px to drop it. @default "1px" */
+    borderWidth?: string;
+    /** Operator bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+    shadow?: string;
+  };
   /** Border color between messages in the thread. */
   border?: TokenReference<'color'>;
 }

package/src/types.ts

@@ -616,7 +616,7 @@ export type AgentWidgetReplayedToolResult = {
  * from its own stored transcript there.
  */
 export type AgentWidgetRequestPayloadMessage = {
-  role: AgentWidgetMessageRole | "tool";
+  role: AgentWidgetModelMessageRole | "tool";
   content: MessageContent;
   createdAt: string;
   /** Optional assistant phase for backend adapters that replay provider history. */
@@ -1123,6 +1123,21 @@ export type AgentMessageMetadata = {
   };
 };
 
+/** Ordinary model context only; the serializer owns tool-call/result pairing. */
+export type AgentWidgetModelMessageProjection = Pick<AgentWidgetRequestPayloadMessage, "content" | "createdAt" | "phase"> & {
+  role: AgentWidgetModelMessageRole;
+};
+
+/** Synchronous, per-message conversion before any dispatch transport serializes history. */
+export type AgentWidgetModelMessageTransform = (context: {
+  /** Full UI transcript entry, including identity and human provenance. */
+  message: Readonly<AgentWidgetMessage>;
+  /** Resolved model content: contentParts > llmContent > rawContent > content. */
+  content: MessageContent;
+  /** Normal model projection; null for operator messages. Return null to omit. */
+  modelMessage: AgentWidgetModelMessageProjection | null;
+}) => AgentWidgetModelMessageProjection | null;
+
 export type AgentWidgetRequestMiddlewareContext = {
   payload: AgentWidgetRequestPayload;
   config: AgentWidgetConfig;
@@ -1391,7 +1406,7 @@ export type AgentWidgetMessageActionsConfig = {
 };
 
 /** Which roles a custom message action appears on. */
-export type AgentWidgetCustomMessageActionRole = "user" | "assistant";
+export type AgentWidgetCustomMessageActionRole = "user" | "assistant" | "operator";
 
 /** One host-contributed message action. */
 export type AgentWidgetCustomMessageAction = {
@@ -7191,6 +7206,11 @@ export type AgentWidgetAvatarConfig = {
   userAvatar?: string;
   /** URL or emoji for assistant avatar */
   assistantAvatar?: string;
+  /**
+   * URL or emoji for operator (human takeover) avatar. Defaults to the letter
+   * "O" on a neutral fill.
+   */
+  operatorAvatar?: string;
 };
 
 /**
@@ -7246,7 +7266,10 @@ export type AgentWidgetMessageLayoutConfig = {
   groupConsecutive?: boolean;
   /** Width behavior for user-authored message rows */
   user?: AgentWidgetMessageRoleLayout;
-  /** Width behavior for assistant-authored message rows and assistant UI variants */
+  /**
+   * Width behavior for assistant-authored message rows and assistant UI
+   * variants. Operator rows sit on the same side and use it too.
+   */
   assistant?: AgentWidgetMessageRoleLayout;
   /**
    * Custom renderer for user messages
@@ -8398,6 +8421,8 @@ export type AgentWidgetConfig = {
    */
   getHeaders?: AgentWidgetHeadersFunction;
   copy?: {
+    /** Visible and accessible label for human operator replies. @default "Human operator" */
+    operatorLabel?: string;
     /** @deprecated Use `welcome.title`. */
     welcomeTitle?: string;
     /** @deprecated Use `welcome.subtitle`. */
@@ -8590,6 +8615,16 @@ export type AgentWidgetConfig = {
    * See `docs/context-mentions-plan.md`.
    */
   contextMentions?: AgentWidgetContextMentionConfig;
+  /**
+   * Synchronous model-context conversion for each nonempty conversation entry.
+   * Runs on proxy, agent and client-token dispatch, after local-only notices and
+   * voice captions are excluded. By default operator messages are omitted;
+   * stateless adapters can explicitly map their historical human contributions
+   * into supported model roles. Do not replay contributions already owned by
+   * server history. This does not authorize steering, takeover or tool approval.
+   * Invalid return values fail dispatch. See docs/MESSAGE-INJECTION.md.
+   */
+  modelMessageTransform?: AgentWidgetModelMessageTransform;
   requestMiddleware?: AgentWidgetRequestMiddleware;
   actionParsers?: AgentWidgetActionParser[];
   actionHandlers?: AgentWidgetActionHandler[];
@@ -9093,7 +9128,25 @@ type ConfigPatch<T> = T extends (...args: never[]) => unknown
       ? { [K in keyof T]?: ConfigPatch<T[K]> }
       : T;
 
-export type AgentWidgetMessageRole = "user" | "assistant" | "system";
+/**
+ * Who authored a message.
+ *
+ * - `user`: the end user.
+ * - `assistant`: the agent (model output).
+ * - `system`: context for the model, rendered like an assistant row.
+ * - `operator`: a human speaking on the agent's side of the conversation, such
+ *   as a support agent who has taken over the thread. It renders on the
+ *   assistant's side with its own bubble style (`theme.components.message.operator`).
+ *   Operator messages are omitted from model requests by default. A stateless
+ *   adapter can explicitly convert them with `modelMessageTransform`.
+ */
+export type AgentWidgetMessageRole = "user" | "assistant" | "system" | "operator";
+
+/**
+ * Roles that reach a model request. Human operator UI entries must be explicitly
+ * converted to a supported model role by an adapter.
+ */
+export type AgentWidgetModelMessageRole = Exclude<AgentWidgetMessageRole, "operator">;
 
 export type AgentWidgetReasoning = {
   id: string;
@@ -9216,11 +9269,18 @@ export type AgentWidgetTurnActivityConfig = {
   }) => HTMLElement | string | null | undefined;
 };
 
+/** Display provenance, supplied by the host; never an authorization credential. */
+export type AgentWidgetMessageAuthor = {
+  id?: string;
+  displayName?: string;
+  kind?: "human" | "ai" | "system";
+};
+
 /**
  * Represents a message in the chat conversation.
  *
  * @property id - Unique message identifier
- * @property role - Message role: "user", "assistant", or "system"
+ * @property role - Message role: "user", "assistant", "system", or "operator"
  * @property content - Message text content (for display)
  * @property contentParts - Original multi-modal content parts (for API requests)
  * @property createdAt - ISO timestamp when message was created
@@ -9234,6 +9294,8 @@ export type AgentWidgetTurnActivityConfig = {
  *                      Useful for implementing voice-specific behaviors like auto-reactivation.
  */
 export type AgentWidgetMessage = {
+  /** Preserved by injection, history and persistence; not sent to models automatically. */
+  author?: AgentWidgetMessageAuthor;
   /** Opt-in whole-turn presentation metadata. Does not change model-visible content. */
   turnActivity?: AgentWidgetTurnActivity;
   id: string;
@@ -9388,10 +9450,13 @@ export type AgentWidgetMessage = {
  * }
  */
 export type InjectMessageOptions = {
+  /** Host-supplied display provenance. Does not grant model or backend authority. */
+  author?: AgentWidgetMessageAuthor;
   /** Mark assistant content as dispatch failure detail for `errorDisplay`. */
   dispatchError?: boolean;
   /**
-   * Message role: "assistant", "user", or "system"
+   * Message role: "assistant", "user", "system", or "operator". Operator
+   * messages are omitted from requests unless modelMessageTransform converts them.
    */
   role: AgentWidgetMessageRole;
 

package/src/ui.ask-user-question-plugin.test.ts

@@ -689,3 +689,157 @@ describe("renderAskUserQuestion plugin hook", () => {
     controller.destroy();
   });
 });
+
+describe("typing indicator while ask_user_question arguments stream", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  // Streaming transcript updates render once per animation frame; queue the
+  // frames so each injection can be rendered synchronously.
+  let frames = new Map<number, (time: number) => void>();
+  let nextFrameId = 1;
+  const renderFrame = () => {
+    const pending = [...frames.values()];
+    frames.clear();
+    pending.forEach((callback) => callback(0));
+  };
+
+  const mountStreaming = async (config: Record<string, unknown> = {}) => {
+    frames = new Map();
+    vi.stubGlobal("requestAnimationFrame", (callback: (time: number) => void) => {
+      const id = nextFrameId++;
+      frames.set(id, callback);
+      return id;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+    global.fetch = vi.fn().mockImplementation(
+      () => new Promise(() => {})
+    ) as unknown as typeof fetch;
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      ...config,
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    controller.submitMessage("hello");
+    await Promise.resolve();
+    await Promise.resolve();
+    return { mount, controller };
+  };
+
+  // Stamped in the future so the rows sort after the submitted user message.
+  const sequence = Date.now() + 60_000;
+  const createdAt = new Date(sequence).toISOString();
+  const fullArgs = {
+    questions: [
+      { question: "Which audience?", options: [{ label: "Hobbyists" }, { label: "Pros" }] },
+    ],
+  };
+
+  const injectStreamingAsk = (
+    controller: ReturnType<typeof createAgentExperience>,
+    { chunks = [], args }: { chunks?: string[]; args?: unknown } = {}
+  ) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "ask-1",
+        role: "assistant",
+        content: "",
+        createdAt,
+        sequence,
+        streaming: true,
+        variant: "tool",
+        toolCall: { id: "ask-1", name: "ask_user_question", status: "running", chunks, args },
+      },
+    });
+    renderFrame();
+  };
+
+  const injectAwaitingAsk = (controller: ReturnType<typeof createAgentExperience>) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "ask-1",
+        role: "assistant",
+        content: "",
+        createdAt,
+        sequence,
+        streaming: false,
+        variant: "tool",
+        toolCall: { id: "ask-1", name: "ask_user_question", status: "complete", chunks: [], args: fullArgs },
+        agentMetadata: { executionId: "exec_123", awaitingLocalTool: true },
+      },
+    });
+    renderFrame();
+  };
+
+  const typingIndicator = (mount: HTMLElement) =>
+    mount.querySelector('[data-typing-indicator="true"]');
+  const askSheet = (mount: HTMLElement) => mount.querySelector("[data-persona-ask-sheet-for]");
+
+  it("keeps the dots until the built-in sheet mounts when no plugin renders the question", async () => {
+    const { mount, controller } = await mountStreaming();
+
+    injectStreamingAsk(controller);
+    expect(askSheet(mount)).toBeNull();
+    expect(typingIndicator(mount)).not.toBeNull();
+
+    injectAwaitingAsk(controller);
+    expect(askSheet(mount)).not.toBeNull();
+    expect(typingIndicator(mount)).toBeNull();
+
+    controller.destroy();
+  });
+
+  it("keeps the dots while the plugin returns null for a partial payload", async () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "partial-asker",
+      renderAskUserQuestion: ({ payload }) => {
+        if (!payload?.questions?.[0]?.options?.length) return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "partial-ask");
+        return root;
+      },
+    };
+    const { mount, controller } = await mountStreaming({ plugins: [plugin] });
+
+    injectStreamingAsk(controller, { chunks: ['{"questions":[{"question":"Which'] });
+    expect(mount.querySelector('[data-test-id="partial-ask"]')).toBeNull();
+    expect(askSheet(mount)).toBeNull();
+    expect(typingIndicator(mount)).not.toBeNull();
+
+    injectStreamingAsk(controller, { args: fullArgs });
+    expect(mount.querySelector('[data-test-id="partial-ask"]')).not.toBeNull();
+    expect(typingIndicator(mount)).toBeNull();
+
+    controller.destroy();
+  });
+
+  it.each([true, false])("hides the dots as soon as the plugin renders a bubble (showToolCalls=%s)", async (showToolCalls) => {
+    const plugin: AgentWidgetPlugin = {
+      id: "eager-asker",
+      renderAskUserQuestion: () => {
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "eager-ask");
+        return root;
+      },
+    };
+    const { mount, controller } = await mountStreaming({
+      plugins: [plugin],
+      features: { showToolCalls },
+    });
+
+    injectStreamingAsk(controller);
+    expect(mount.querySelector('[data-test-id="eager-ask"]')).not.toBeNull();
+    expect(typingIndicator(mount)).toBeNull();
+
+    controller.destroy();
+  });
+});

package/src/ui.operator-role.test.ts

@@ -0,0 +1,336 @@
+// @vitest-environment jsdom
+
+import { readFileSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import type { AgentWidgetMessage, AgentWidgetStoredState } from "./types";
+import type { AgentWidgetPlugin } from "./plugins/types";
+
+const mounts: HTMLElement[] = [];
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+
+const makeController = (config: Record<string, unknown> = {}) => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  mounts.push(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    persistState: false,
+    suggestionChips: [],
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+  controllers.push(controller);
+  return { mount, controller };
+};
+
+/** Let microtasks and the coalesced render frame run. */
+const settle = async () => {
+  for (let i = 0; i < 8; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+  await new Promise((resolve) => setTimeout(resolve, 32));
+};
+
+const row = (mount: HTMLElement, id: string) =>
+  mount.querySelector<HTMLElement>(`[data-wrapper-id="${id}"]`);
+
+describe("operator role in the transcript", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => {
+      try {
+        controller.destroy();
+      } catch {
+        /* already destroyed */
+      }
+    });
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("renders an operator row on the assistant side with its own bubble", async () => {
+    const { mount, controller } = makeController();
+    controller.injectUserMessage({ id: "u1", content: "Where is my order?" });
+    controller.injectAssistantMessage({ id: "a1", content: "Let me check." });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here, I refunded it." });
+    await settle();
+
+    const operatorRow = row(mount, "op1")!;
+    expect(operatorRow.getAttribute("data-message-role")).toBe("operator");
+    expect(operatorRow.classList.contains("persona-message-row-operator")).toBe(true);
+    expect(operatorRow.classList.contains("persona-justify-end")).toBe(false);
+    expect(operatorRow.querySelector(".persona-message-operator-bubble")).not.toBeNull();
+    expect(operatorRow.querySelector(".persona-message-assistant-bubble")).toBeNull();
+
+    // Existing roles are untouched.
+    expect(row(mount, "u1")!.classList.contains("persona-justify-end")).toBe(true);
+    expect(row(mount, "a1")!.querySelector(".persona-message-assistant-bubble")).not.toBeNull();
+  });
+
+  it("names human replies with avatars off and updates provenance on reinjection", async () => {
+    const { mount, controller } = makeController();
+    controller.injectMessage({ id: "human", role: "operator", content: "Refunded" });
+    await settle();
+    expect(row(mount, "human")!.querySelector('[role="group"]')?.getAttribute("aria-label")).toBe("Human operator");
+    controller.injectMessage({ id: "human", role: "operator", content: "Refunded", author: { id: "sam", displayName: "Sam", kind: "human" } });
+    await settle();
+    expect(row(mount, "human")!.querySelector(".persona-message-author")?.textContent).toBe("Sam · Human operator");
+    expect(row(mount, "human")!.querySelector('[role="group"]')?.getAttribute("aria-label")).toBe("Sam · Human operator");
+    expect(controller.getMessages().find(message => message.id === "human")?.author).toEqual({ id: "sam", displayName: "Sam", kind: "human" });
+  });
+
+  it("persists and restores structured author provenance", async () => {
+    let state: AgentWidgetStoredState | null = null;
+    const adapter = {
+      load: () => state,
+      save: (value: AgentWidgetStoredState) => { state = JSON.parse(JSON.stringify(value)); },
+      clear: () => { state = null; },
+    };
+    const { controller } = makeController({ persistState: true, storageAdapter: adapter });
+    controller.injectMessage({ id: "saved", role: "operator", content: "Refunded", author: { id: "sam", displayName: "Sam", kind: "human" } });
+    await vi.waitFor(() => expect(state?.messages?.some(message => message.id === "saved")).toBe(true));
+    const { mount, controller: restored } = makeController({ persistState: true, storageAdapter: adapter });
+    await settle();
+    expect(restored.getMessages().find(message => message.id === "saved")?.author).toEqual({ id: "sam", displayName: "Sam", kind: "human" });
+    expect(row(mount, "saved")!.querySelector(".persona-message-author")?.textContent).toBe("Sam · Human operator");
+  });
+
+  it("hides destructive retry and edit before human replies while allowing a subsequent turn", async () => {
+    const { mount, controller } = makeController({ messageActions: { enabled: true, showEdit: true, showRegenerate: true } });
+    controller.injectUserMessage({ id: "before", content: "Question" });
+    controller.injectAssistantMessage({ id: "answer", content: "Answer" });
+    await settle();
+    expect(row(mount, "answer")!.querySelector('[data-action="regenerate"]')).not.toBeNull();
+    controller.injectMessage({ id: "human", role: "operator", content: "Refunded" });
+    await settle();
+    expect(row(mount, "before")!.querySelector('[data-action="edit"]')).toBeNull();
+    expect(row(mount, "answer")!.querySelector('[data-action="regenerate"]')).toBeNull();
+    controller.injectUserMessage({ id: "after", content: "Follow up" });
+    controller.injectAssistantMessage({ id: "next", content: "Next answer" });
+    await settle();
+    expect(row(mount, "after")!.querySelector('[data-action="edit"]')).not.toBeNull();
+    expect(row(mount, "next")!.querySelector('[data-action="regenerate"]')).not.toBeNull();
+  });
+
+  it("does not report operator messages as assistant messages", async () => {
+    const { controller } = makeController();
+    const assistantMessages: AgentWidgetMessage[] = [];
+    controller.on("assistant:message", (message) => assistantMessages.push(message));
+    controller.injectMessage({ id: "op1", role: "operator", content: "Hello from support" });
+    controller.injectAssistantMessage({ id: "a1", content: "Agent reply" });
+    await settle();
+    expect(assistantMessages.map((message) => message.id)).toEqual(["a1"]);
+  });
+
+  it("renders operator messages from initialMessages", async () => {
+    const { mount } = makeController({
+      initialMessages: [
+        { id: "in1", role: "user", content: "Hi", createdAt: "2026-01-01T00:00:00.000Z" },
+        { id: "op1", role: "operator", content: "Hello, Sam here.", createdAt: "2026-01-01T00:00:01.000Z" },
+      ] satisfies AgentWidgetMessage[],
+    });
+    await settle();
+    expect(row(mount, "in1")!.getAttribute("data-message-role")).toBe("user");
+    expect(row(mount, "op1")!.getAttribute("data-message-role")).toBe("operator");
+    expect(row(mount, "op1")!.querySelector(".persona-message-operator-bubble")).not.toBeNull();
+  });
+
+  it("shrink-wraps operator rows even when the assistant is full width", async () => {
+    const { mount, controller } = makeController({
+      layout: { messages: { assistant: { width: "full" } } },
+    });
+    controller.injectAssistantMessage({ id: "a1", content: "Let me check." });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+    await settle();
+    expect(row(mount, "a1")!.getAttribute("data-message-width")).toBe("full");
+    const operatorRow = row(mount, "op1")!;
+    expect(operatorRow.getAttribute("data-message-width")).toBe("content");
+    // It keeps the assistant's full-width cap, so a long message can still fill the column.
+    expect(operatorRow.style.getPropertyValue("--persona-message-row-max-width")).toBe(
+      "var(--persona-message-operator-max-width, var(--persona-message-assistant-max-width, 100%))"
+    );
+  });
+});
+
+describe("operator bubble styles", () => {
+  let stylesheet: HTMLStyleElement;
+
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+    stylesheet = document.createElement("style");
+    stylesheet.textContent = readFileSync("src/styles/widget.css", "utf8");
+    document.head.append(stylesheet);
+  });
+
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => controller.destroy());
+    mounts.splice(0).forEach((mount) => mount.remove());
+    stylesheet.remove();
+    document.body.innerHTML = "";
+  });
+
+  it.each(["bubble", "flat", "minimal"] as const)(
+    "outlines the V5 operator bubble in the %s layout",
+    async (layout) => {
+      const { mount, controller } = makeController({
+        future: { v5Defaults: true },
+        layout: { messages: { layout } },
+      });
+      controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+      await settle();
+      const bubble = row(mount, "op1")!.querySelector<HTMLElement>("#bubble-op1")!;
+      const style = getComputedStyle(bubble);
+      expect(style.borderTopStyle).toBe("solid");
+      // Width and fill come from the V5 operator tokens on the themed ancestor.
+      const token = (name: string) => {
+        for (let node: HTMLElement | null = bubble; node; node = node.parentElement) {
+          const value = node.style.getPropertyValue(name).trim();
+          if (value) return value;
+        }
+        return "";
+      };
+      expect(token("--persona-components-message-operator-borderWidth")).toBe("1px");
+      expect(token("--persona-components-message-operator-background")).toBe("transparent");
+    }
+  );
+
+  it.each(["flat", "minimal"] as const)("keeps the V4 %s operator borderless", async (layout) => {
+    const { mount, controller } = makeController({ layout: { messages: { layout } } });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+    await settle();
+    const bubble = row(mount, "op1")!.querySelector<HTMLElement>("#bubble-op1")!;
+    expect(getComputedStyle(bubble).borderTopStyle).not.toBe("solid");
+  });
+});
+
+/**
+ * Hosts draw per-message badges (delivery status, author label, errors) with a
+ * `renderMessage` plugin: it wraps the default bubble, appends a
+ * `data-preserve-runtime` slot, and the host fills that slot itself. These
+ * tests pin the route for operator rows.
+ */
+describe("operator messages through a renderMessage plugin slot", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => controller.destroy());
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  const slotPlugin = (seen: AgentWidgetMessage["role"][]): AgentWidgetPlugin => ({
+    id: "delivery-status",
+    renderMessage: ({ message, defaultRenderer }) => {
+      seen.push(message.role);
+      if (message.role !== "operator" && message.role !== "assistant") return null;
+      const element = defaultRenderer();
+      const slot = document.createElement("div");
+      slot.setAttribute("data-preserve-runtime", "true");
+      slot.setAttribute("data-status-slot", message.id);
+      element.insertBefore(slot, element.querySelector(":scope > .persona-message-actions"));
+      return element;
+    },
+  });
+
+  const slot = (mount: HTMLElement, id: string) =>
+    row(mount, id)?.querySelector<HTMLElement>(`[data-status-slot="${id}"]`) ?? null;
+
+  /** What a host does once the row is on screen: fill the slot with its own UI. */
+  const fillSlot = (target: HTMLElement, text: string) => {
+    const badge = document.createElement("span");
+    badge.className = "host-status";
+    badge.textContent = text;
+    target.replaceChildren(badge);
+  };
+
+  it("runs the hook for operator rows and uses the element it returns", async () => {
+    const seen: AgentWidgetMessage["role"][] = [];
+    const { mount, controller } = makeController({ plugins: [slotPlugin(seen)] });
+    controller.injectUserMessage({ id: "u1", content: "Where is my order?" });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here, I refunded it." });
+    await settle();
+
+    expect(seen).toContain("operator");
+    expect(seen).toContain("user");
+    const operatorRow = row(mount, "op1")!;
+    expect(operatorRow.getAttribute("data-message-role")).toBe("operator");
+    expect(slot(mount, "op1")).not.toBeNull();
+    // The plugin returned null for the user row, so it keeps the default bubble.
+    expect(row(mount, "u1")!.querySelector("[data-status-slot]")).toBeNull();
+    expect(row(mount, "u1")!.querySelector(".persona-message-user-bubble")).not.toBeNull();
+  });
+
+  it("keeps the operator bubble class when a plugin wraps the default renderer", async () => {
+    const { mount, controller } = makeController({ plugins: [slotPlugin([])] });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+    await settle();
+
+    const bubble = row(mount, "op1")!.querySelector<HTMLElement>("#bubble-op1")!;
+    expect(bubble.classList.contains("persona-message-operator-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(false);
+    expect(bubble.getAttribute("data-persona-theme-zone")).toBe("operator-message");
+    expect(bubble.contains(slot(mount, "op1"))).toBe(true);
+  });
+
+  it("keeps the host-filled slot node across controller.update()", async () => {
+    const seen: AgentWidgetMessage["role"][] = [];
+    const { mount, controller } = makeController({ plugins: [slotPlugin(seen)] });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+    await settle();
+    const first = slot(mount, "op1")!;
+    fillSlot(first, "Delivered");
+    const rendersBefore = seen.length;
+
+    controller.update({ copy: { welcomeTitle: "Support" } });
+    await settle();
+    controller.update({ theme: { components: { message: { operator: { borderRadius: "4px" } } } } });
+    await settle();
+
+    // The plugin rendered the row again, and the morph kept the live slot.
+    expect(seen.length).toBeGreaterThan(rendersBefore);
+    expect(slot(mount, "op1")).toBe(first);
+    expect(first.isConnected).toBe(true);
+    expect(first.querySelector(".host-status")?.textContent).toBe("Delivered");
+    expect(row(mount, "op1")!.querySelector(".persona-message-operator-bubble")).not.toBeNull();
+  });
+
+  it("keeps the host-filled slot node when injectMessage upserts the same id", async () => {
+    const seen: AgentWidgetMessage["role"][] = [];
+    const { mount, controller } = makeController({ plugins: [slotPlugin(seen)] });
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+    await settle();
+    const first = slot(mount, "op1")!;
+    fillSlot(first, "Sending");
+
+    // Same id, same text: a status-only change on the host side.
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here." });
+    await settle();
+    expect(slot(mount, "op1")).toBe(first);
+
+    // Same id, new text: the plugin renders the row again and the slot survives.
+    const rendersBefore = seen.length;
+    controller.injectMessage({ id: "op1", role: "operator", content: "Sam here, refund sent." });
+    await settle();
+    expect(seen.length).toBeGreaterThan(rendersBefore);
+
+    expect(mount.querySelectorAll('[data-wrapper-id="op1"]')).toHaveLength(1);
+    expect(slot(mount, "op1")).toBe(first);
+    // The host's content is still there; the host then updates it in place.
+    expect(first.querySelector(".host-status")?.textContent).toBe("Sending");
+    fillSlot(first, "Delivered");
+    expect(slot(mount, "op1")?.querySelector(".host-status")?.textContent).toBe("Delivered");
+    expect(row(mount, "op1")!.querySelector("#bubble-op1")?.textContent).toContain("refund sent");
+    expect(row(mount, "op1")!.querySelector(".persona-message-operator-bubble")).not.toBeNull();
+  });
+});