@runtypelabs/persona 3.34.0 → 3.35.0

package/src/components/header-parts.test.ts

@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { createCloseButton, createClearChatButton } from "./header-parts";
+import type { AgentWidgetConfig } from "../types";
+
+const baseConfig: AgentWidgetConfig = { apiUrl: "/api" };
+
+describe("createCloseButton", () => {
+  it("keeps the default utility classes when no style overrides are set", () => {
+    const { button } = createCloseButton(baseConfig, {});
+    expect(button.tagName).toBe("BUTTON");
+    expect(button.type).toBe("button");
+    expect(button.getAttribute("aria-label")).toBe("Close chat");
+    expect(button.classList.contains("persona-rounded-full")).toBe(true);
+    expect(button.classList.contains("persona-border-none")).toBe(true);
+    expect(button.classList.contains("hover:persona-bg-gray-100")).toBe(true);
+  });
+
+  it("hides the button when showClose is false", () => {
+    const { button } = createCloseButton(baseConfig, { showClose: false });
+    expect(button.style.display).toBe("none");
+  });
+
+  it("drops each default class and sets the inline style for the matching override", () => {
+    const { button } = createCloseButton(
+      {
+        ...baseConfig,
+        launcher: {
+          closeButtonBackgroundColor: "rgb(1, 2, 3)",
+          closeButtonBorderRadius: "4px",
+          closeButtonBorderWidth: "2px",
+          closeButtonBorderColor: "rgb(4, 5, 6)",
+        },
+      },
+      {}
+    );
+    expect(button.classList.contains("hover:persona-bg-gray-100")).toBe(false);
+    expect(button.style.backgroundColor).toBe("rgb(1, 2, 3)");
+    expect(button.classList.contains("persona-rounded-full")).toBe(false);
+    expect(button.style.borderRadius).toBe("4px");
+    expect(button.classList.contains("persona-border-none")).toBe(false);
+    expect(button.style.borderWidth).toBe("2px");
+    expect(button.style.borderStyle).toBe("solid");
+  });
+
+  it("defaults border width to 0px when only border color is provided", () => {
+    const { button } = createCloseButton(
+      { ...baseConfig, launcher: { closeButtonBorderColor: "rgb(7, 8, 9)" } },
+      {}
+    );
+    expect(button.classList.contains("persona-border-none")).toBe(false);
+    expect(button.style.borderWidth).toBe("0px");
+    expect(button.style.borderStyle).toBe("solid");
+  });
+});
+
+describe("createClearChatButton", () => {
+  it("keeps the default utility classes when no style overrides are set", () => {
+    const { button } = createClearChatButton(baseConfig, {});
+    expect(button.type).toBe("button");
+    expect(button.classList.contains("persona-rounded-full")).toBe(true);
+    expect(button.classList.contains("persona-border-none")).toBe(true);
+    expect(button.classList.contains("hover:persona-bg-gray-100")).toBe(true);
+  });
+
+  it("drops each default class and sets the inline style for the matching override", () => {
+    const { button } = createClearChatButton(
+      {
+        ...baseConfig,
+        launcher: {
+          clearChat: {
+            backgroundColor: "rgb(1, 2, 3)",
+            borderRadius: "4px",
+            borderWidth: "2px",
+            borderColor: "rgb(4, 5, 6)",
+          },
+        },
+      },
+      {}
+    );
+    expect(button.classList.contains("hover:persona-bg-gray-100")).toBe(false);
+    expect(button.style.backgroundColor).toBe("rgb(1, 2, 3)");
+    expect(button.classList.contains("persona-rounded-full")).toBe(false);
+    expect(button.style.borderRadius).toBe("4px");
+    expect(button.classList.contains("persona-border-none")).toBe(false);
+    expect(button.style.borderWidth).toBe("2px");
+    expect(button.style.borderStyle).toBe("solid");
+  });
+});

package/src/components/header-parts.ts

@@ -1,4 +1,4 @@
-import { createElement, createElementInDocument } from "../utils/dom";
+import { createElement, createElementInDocument, createNode, cx } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
 import { AgentWidgetConfig } from "../types";
 import { PORTALED_OVERLAY_Z_INDEX } from "../utils/constants";
@@ -25,14 +25,14 @@ export interface CreateCloseButtonOptions {
   /**
    * Explicit button-size override that wins over `launcher.closeButtonSize`.
    * Use when the call site has its own opinion about the size that should
-   * take precedence over the global launcher config — e.g. composer-bar's
+   * take precedence over the global launcher config: e.g. composer-bar's
    * minimal close icon, where size is part of the mode's UX, not something
    * that should inherit from the floating launcher's button size.
    */
   buttonSize?: string;
   /**
    * Override the rendered icon size (default: "28px"). Pair with
-   * `buttonSize` when scaling the whole control down — otherwise the
+   * `buttonSize` when scaling the whole control down: otherwise the
    * 28px icon will overflow a smaller button.
    */
   iconSize?: string;
@@ -85,24 +85,41 @@ export const createCloseButton = (
 
   const wrapper = createElement("div", wrapperClassName);
 
-  const button = createElement(
-    "button",
-    "persona-inline-flex persona-items-center persona-justify-center persona-rounded-full hover:persona-bg-gray-100 persona-cursor-pointer persona-border-none"
-  ) as HTMLButtonElement;
-  button.style.height = closeButtonSize;
-  button.style.width = closeButtonSize;
-  button.type = "button";
-
   const closeButtonTooltipText = launcher.closeButtonTooltipText ?? "Close chat";
   const closeButtonShowTooltip = launcher.closeButtonShowTooltip ?? true;
-
-  button.setAttribute("aria-label", closeButtonTooltipText);
-  button.style.display = showClose ? "" : "none";
-
   const closeButtonIconName = launcher.closeButtonIconName ?? "x";
   const closeButtonIconText = launcher.closeButtonIconText ?? "×";
-  button.style.color =
-    launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
+  // hover-bg / border-none / rounded-full are default utility classes that
+  // apply only when the matching style override is absent; an override sets
+  // the inline style instead (cx omits the class).
+  const hasCloseBorder = Boolean(
+    launcher.closeButtonBorderWidth || launcher.closeButtonBorderColor
+  );
+
+  const button = createNode("button", {
+    className: cx(
+      "persona-inline-flex persona-items-center persona-justify-center persona-cursor-pointer",
+      !launcher.closeButtonBackgroundColor && "hover:persona-bg-gray-100",
+      !hasCloseBorder && "persona-border-none",
+      !launcher.closeButtonBorderRadius && "persona-rounded-full"
+    ),
+    attrs: { type: "button", "aria-label": closeButtonTooltipText },
+    style: {
+      height: closeButtonSize,
+      width: closeButtonSize,
+      display: showClose ? undefined : "none",
+      color: launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor,
+      backgroundColor: launcher.closeButtonBackgroundColor || undefined,
+      border: hasCloseBorder
+        ? `${launcher.closeButtonBorderWidth || "0px"} solid ${launcher.closeButtonBorderColor || "transparent"}`
+        : undefined,
+      borderRadius: launcher.closeButtonBorderRadius || undefined,
+      paddingLeft: launcher.closeButtonPaddingX || undefined,
+      paddingRight: launcher.closeButtonPaddingX || undefined,
+      paddingTop: launcher.closeButtonPaddingY || undefined,
+      paddingBottom: launcher.closeButtonPaddingY || undefined,
+    },
+  });
 
   // The X glyph's paths occupy only the middle 50% of its 24x24 viewBox
   // (from 6,6 to 18,18), while other header icons (e.g. refresh-cw) span
@@ -118,47 +135,6 @@ export const createCloseButton = (
     button.textContent = closeButtonIconText;
   }
 
-  if (launcher.closeButtonBackgroundColor) {
-    button.style.backgroundColor = launcher.closeButtonBackgroundColor;
-    button.classList.remove("hover:persona-bg-gray-100");
-  } else {
-    button.style.backgroundColor = "";
-    button.classList.add("hover:persona-bg-gray-100");
-  }
-
-  if (launcher.closeButtonBorderWidth || launcher.closeButtonBorderColor) {
-    const borderWidth = launcher.closeButtonBorderWidth || "0px";
-    const borderColor = launcher.closeButtonBorderColor || "transparent";
-    button.style.border = `${borderWidth} solid ${borderColor}`;
-    button.classList.remove("persona-border-none");
-  } else {
-    button.style.border = "";
-    button.classList.add("persona-border-none");
-  }
-
-  if (launcher.closeButtonBorderRadius) {
-    button.style.borderRadius = launcher.closeButtonBorderRadius;
-    button.classList.remove("persona-rounded-full");
-  } else {
-    button.style.borderRadius = "";
-    button.classList.add("persona-rounded-full");
-  }
-
-  if (launcher.closeButtonPaddingX) {
-    button.style.paddingLeft = launcher.closeButtonPaddingX;
-    button.style.paddingRight = launcher.closeButtonPaddingX;
-  } else {
-    button.style.paddingLeft = "";
-    button.style.paddingRight = "";
-  }
-  if (launcher.closeButtonPaddingY) {
-    button.style.paddingTop = launcher.closeButtonPaddingY;
-    button.style.paddingBottom = launcher.closeButtonPaddingY;
-  } else {
-    button.style.paddingTop = "";
-    button.style.paddingBottom = "";
-  }
-
   wrapper.appendChild(button);
 
   if (closeButtonShowTooltip && closeButtonTooltipText) {
@@ -259,15 +235,34 @@ export const createClearChatButton = (
 
   const wrapper = createElement("div", wrapperClassName);
 
-  const button = createElement(
-    "button",
-    "persona-inline-flex persona-items-center persona-justify-center persona-rounded-full hover:persona-bg-gray-100 persona-cursor-pointer persona-border-none"
-  ) as HTMLButtonElement;
-  button.style.height = clearChatSize;
-  button.style.width = clearChatSize;
-  button.type = "button";
-  button.setAttribute("aria-label", clearChatTooltipText);
-  button.style.color = clearChatIconColor || HEADER_THEME_CSS.actionIconColor;
+  // hover-bg / border-none / rounded-full are default utility classes that
+  // apply only when the matching style override is absent; an override sets
+  // the inline style instead (cx omits the class).
+  const hasClearChatBorder = Boolean(clearChatBorderWidth || clearChatBorderColor);
+
+  const button = createNode("button", {
+    className: cx(
+      "persona-inline-flex persona-items-center persona-justify-center persona-cursor-pointer",
+      !clearChatBgColor && "hover:persona-bg-gray-100",
+      !hasClearChatBorder && "persona-border-none",
+      !clearChatBorderRadius && "persona-rounded-full"
+    ),
+    attrs: { type: "button", "aria-label": clearChatTooltipText },
+    style: {
+      height: clearChatSize,
+      width: clearChatSize,
+      color: clearChatIconColor || HEADER_THEME_CSS.actionIconColor,
+      backgroundColor: clearChatBgColor || undefined,
+      border: hasClearChatBorder
+        ? `${clearChatBorderWidth || "0px"} solid ${clearChatBorderColor || "transparent"}`
+        : undefined,
+      borderRadius: clearChatBorderRadius || undefined,
+      paddingLeft: clearChatPaddingX || undefined,
+      paddingRight: clearChatPaddingX || undefined,
+      paddingTop: clearChatPaddingY || undefined,
+      paddingBottom: clearChatPaddingY || undefined,
+    },
+  });
 
   const iconSvg = renderLucideIcon(clearChatIconName, iconSize, "currentColor", 1);
   if (iconSvg) {
@@ -275,32 +270,6 @@ export const createClearChatButton = (
     button.appendChild(iconSvg);
   }
 
-  if (clearChatBgColor) {
-    button.style.backgroundColor = clearChatBgColor;
-    button.classList.remove("hover:persona-bg-gray-100");
-  }
-
-  if (clearChatBorderWidth || clearChatBorderColor) {
-    const borderWidth = clearChatBorderWidth || "0px";
-    const borderColor = clearChatBorderColor || "transparent";
-    button.style.border = `${borderWidth} solid ${borderColor}`;
-    button.classList.remove("persona-border-none");
-  }
-
-  if (clearChatBorderRadius) {
-    button.style.borderRadius = clearChatBorderRadius;
-    button.classList.remove("persona-rounded-full");
-  }
-
-  if (clearChatPaddingX) {
-    button.style.paddingLeft = clearChatPaddingX;
-    button.style.paddingRight = clearChatPaddingX;
-  }
-  if (clearChatPaddingY) {
-    button.style.paddingTop = clearChatPaddingY;
-    button.style.paddingBottom = clearChatPaddingY;
-  }
-
   wrapper.appendChild(button);
 
   if (clearChatShowTooltip && clearChatTooltipText) {

package/src/components/launcher.test.ts

@@ -5,6 +5,17 @@ import { createLauncherButton } from "./launcher";
 import { DEFAULT_WIDGET_CONFIG } from "../defaults";
 
 describe("createLauncherButton", () => {
+  it("uses the package default subtitle when no subtitle is configured", () => {
+    const { element, update } = createLauncherButton(undefined, () => {});
+    update({});
+    const subtitleEl = element.querySelector("[data-role='launcher-subtitle']");
+    expect(subtitleEl?.textContent).toBe("Here to help you get answers fast");
+    expect(subtitleEl?.getAttribute("title")).toBe(
+      "Here to help you get answers fast"
+    );
+    element.remove();
+  });
+
   it("applies collapsedMaxWidth when set", () => {
     const { element, update } = createLauncherButton(undefined, () => {});
     update({

package/src/components/launcher.ts

@@ -41,7 +41,7 @@ export const createLauncherButton = (
 
     const subtitleEl = button.querySelector("[data-role='launcher-subtitle']");
     if (subtitleEl) {
-      const s = launcher.subtitle ?? "Get answers fast";
+      const s = launcher.subtitle ?? "Here to help you get answers fast";
       subtitleEl.textContent = s;
       subtitleEl.setAttribute("title", s);
     }

package/src/components/message-bubble.test.ts

@@ -155,7 +155,7 @@ describe("resolveStopReasonNoticeText", () => {
   });
 });
 
-describe("createStandardBubble — stopReason notice", () => {
+describe("createStandardBubble: stopReason notice", () => {
   const renderWithStopReason = (
     overrides: Partial<AgentWidgetMessage>,
     widgetConfig?: Partial<AgentWidgetConfig>
@@ -333,7 +333,7 @@ describe("isSafeMediaSrc", () => {
   });
 });
 
-describe("createStandardBubble — audio/video/file content parts", () => {
+describe("createStandardBubble: audio/video/file content parts", () => {
   it("renders an <audio> element with controls for an audio content part", () => {
     const bubble = createStandardBubble(
       makeMessage({
@@ -466,3 +466,75 @@ describe("createStandardBubble — audio/video/file content parts", () => {
     expect(link?.getAttribute("href")).toBe("https://example.com/report.pdf");
   });
 });
+
+describe("createStandardBubble: timestamp position", () => {
+  it("tucks an inline timestamp inside the last content block so it trails the text", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ content: "Hello there" }),
+      ({ text }) => `<p>${text}</p>`,
+      { timestamp: { show: true, position: "inline" } }
+    );
+
+    // Markdown content is block-wrapped; the inline timestamp must live inside
+    // that block (trailing the text), not as a block sibling under the bubble.
+    const inline = bubble.querySelector("p .persona-timestamp-inline");
+    expect(inline).not.toBeNull();
+    expect(inline?.textContent).toMatch(/\d/);
+    expect(Array.from(bubble.children)).not.toContain(inline);
+    // Must be an inline-level <span>; a <div> here is invalid inside a <p>.
+    expect(inline?.tagName).toBe("SPAN");
+  });
+
+  it("uses an inline element that survives an innerHTML re-parse (idiomorph round-trip)", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ content: "Hello there" }),
+      ({ text }) => `<p>${text}</p>`,
+      { timestamp: { show: true, position: "inline" } }
+    );
+    const content = bubble.querySelector(".persona-message-content") as HTMLElement;
+
+    // Re-serializing + re-parsing is what the re-render path does. A <div>
+    // inside a <p> would be auto-closed out to a sibling (leaving an empty
+    // <p>), dropping the timestamp onto its own line; a <span> stays put.
+    const serialized = content.innerHTML;
+    content.innerHTML = serialized;
+
+    expect(content.querySelector("p .persona-timestamp-inline")).not.toBeNull();
+    const emptyParagraphs = Array.from(content.querySelectorAll("p")).filter(
+      (p) => p.textContent === ""
+    );
+    expect(emptyParagraphs.length).toBe(0);
+  });
+
+  it("falls back to the content container for plain-text (non-block) content", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ content: "Hello there" }),
+      ({ text }) => text,
+      { timestamp: { show: true, position: "inline" } }
+    );
+
+    const content = bubble.querySelector(".persona-message-content")!;
+    const inline = content.querySelector(".persona-timestamp-inline");
+    expect(inline).not.toBeNull();
+    expect(content.contains(inline)).toBe(true);
+  });
+
+  it("renders a below timestamp as a block under the content (direct bubble child)", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ content: "Hello there" }),
+      ({ text }) => `<p>${text}</p>`,
+      { timestamp: { show: true, position: "below" } }
+    );
+
+    // "below" must not produce an inline timestamp, and the timestamp block is
+    // appended to the bubble (under the content), not nested in the content.
+    expect(bubble.querySelector(".persona-timestamp-inline")).toBeNull();
+    const below = Array.from(bubble.children).find(
+      (el) =>
+        el.classList.contains("persona-mt-1") &&
+        el.classList.contains("persona-text-xs")
+    );
+    expect(below).toBeDefined();
+    expect(below?.textContent).toMatch(/\d/);
+  });
+});

package/src/components/message-bubble.ts

@@ -28,7 +28,7 @@ import {
  * Default copy for the inline notice rendered when a turn ends with a
  * non-natural stop reason. Deployers override per-reason via
  * `config.copy.stopReasonNotice`. Returns `null` for natural completions
- * (`end_turn`) and uninformative reasons (`unknown`) — those never render
+ * (`end_turn`) and uninformative reasons (`unknown`): those never render
  * an affordance.
  */
 export const getDefaultStopReasonNoticeCopy = (
@@ -62,7 +62,7 @@ export const resolveStopReasonNoticeText = (
 ): string | null => {
   if (!stopReason) return null;
   const fallback = getDefaultStopReasonNoticeCopy(stopReason);
-  // Reasons without a default (end_turn, unknown) never render — overrides
+  // Reasons without a default (end_turn, unknown) never render: overrides
   // for those keys are intentionally ignored.
   if (fallback === null) return null;
   const override = overrides?.[stopReason];
@@ -498,10 +498,11 @@ const createAvatar = (
  */
 const createTimestamp = (
   message: AgentWidgetMessage,
-  timestampConfig: AgentWidgetTimestampConfig
+  timestampConfig: AgentWidgetTimestampConfig,
+  tagName: "div" | "span" = "div"
 ): HTMLElement => {
   const timestamp = createElement(
-    "div",
+    tagName,
     "persona-text-xs persona-text-persona-muted"
   );
 
@@ -629,9 +630,10 @@ export const createMessageActions = (
   const showCopy = actionsConfig.showCopy ?? true;
   const showUpvote = actionsConfig.showUpvote ?? true;
   const showDownvote = actionsConfig.showDownvote ?? true;
+  const showReadAloud = actionsConfig.showReadAloud ?? false;
 
   // Don't render the container at all when no actions are visible
-  if (!showCopy && !showUpvote && !showDownvote) {
+  if (!showCopy && !showUpvote && !showDownvote && !showReadAloud) {
     const empty = createElement("div");
     empty.style.display = "none";
     empty.id = `actions-${message.id}`;
@@ -686,6 +688,12 @@ export const createMessageActions = (
     container.appendChild(createActionButton("copy", "Copy message", "copy"));
   }
 
+  // Read-aloud button. Click handling and play/pause/resume state are managed
+  // in ui.ts (event delegation + ReadAloudController) so they survive morphs.
+  if (showReadAloud) {
+    container.appendChild(createActionButton("volume-2", "Read aloud", "read-aloud"));
+  }
+
   // Upvote button
   if (showUpvote) {
     container.appendChild(createActionButton("thumbs-up", "Upvote", "upvote"));
@@ -768,7 +776,7 @@ export const createStandardBubble = (
       ? resolveStreamAnimationPlugin(streamAnimation.type, streamPluginOverrides)
       : null;
   // Stay in "streaming-animated" mode while the plugin reports in-flight
-  // work for this message — e.g. glyph-cycle's tick loops still walking
+  // work for this message: e.g. glyph-cycle's tick loops still walking
   // through the tail after the last token arrived. Without this, the final
   // non-animated render rips out the cycling spans mid-animation.
   const pluginStillAnimating =
@@ -861,11 +869,17 @@ export const createStandardBubble = (
     }
   }
 
-  // Add inline timestamp if configured
+  // Usung <span>, not <div> for timestamp 
+  // because a block child of a <p> gets re-parented outside of it on re-render (idiomorph).
   if (showTimestamp && timestampPosition === "inline" && message.createdAt) {
-    const timestamp = createTimestamp(message, timestampConfig!);
-    timestamp.classList.add("persona-ml-2", "persona-inline");
-    contentDiv.appendChild(timestamp);
+    const timestamp = createTimestamp(message, timestampConfig!, "span");
+    timestamp.classList.add("persona-timestamp-inline");
+    const lastBlock = contentDiv.lastElementChild;
+    if (lastBlock) {
+      lastBlock.appendChild(timestamp);
+    } else {
+      contentDiv.appendChild(timestamp);
+    }
   }
 
   if (imageParts.length > 0) {
@@ -930,7 +944,7 @@ export const createStandardBubble = (
       : null;
 
   // Add typing indicator (or skeleton placeholder) for streaming assistant
-  // messages. Check the buffered content — a plugin's `bufferContent` may
+  // messages. Check the buffered content: a plugin's `bufferContent` may
   // hold back the first N chars (e.g. glyph-cycle waits for 50 chars), during
   // which the bubble would otherwise appear empty.
   //

package/src/components/messages.ts

@@ -34,7 +34,7 @@ export const renderMessages = (
       if (!showReasoning) return;
       bubble = createReasoningBubble(message, config);
     } else if (isAskUserQuestionMessage(message)) {
-      // No transcript bubble — the overlay sheet is the only question UI.
+      // No transcript bubble: the overlay sheet is the only question UI.
       if (config?.features?.askUserQuestion?.enabled === false) return;
       if (!message.agentMetadata?.askUserQuestionAnswered) {
         if (message.toolCall?.id) liveAskToolIds.add(message.toolCall.id);
@@ -45,7 +45,7 @@ export const renderMessages = (
       isSuggestRepliesMessage(message) &&
       config?.features?.suggestReplies?.enabled !== false
     ) {
-      // No transcript bubble — the chips above the composer are the only UI.
+      // No transcript bubble: the chips above the composer are the only UI.
       // When the feature is disabled the message falls through to the generic
       // tool bubble below (and is never auto-resumed), making the parked
       // execution visible instead of silently swallowed.

package/src/components/panel.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from "vitest";
 import { createWrapper } from "./panel";
 import type { AgentWidgetConfig } from "../types";
 
-describe("createWrapper — composer-bar mode", () => {
+describe("createWrapper: composer-bar mode", () => {
   it("marks the wrapper with composer-bar data-attrs and leaves geometry to updateOpenState", () => {
     const config: AgentWidgetConfig = {
       apiUrl: "/api",