@runtypelabs/persona 4.17.1 → 4.18.0

package/src/components/artifact-preview.ts

@@ -206,6 +206,12 @@ export type ArtifactPreviewBodyHandle = {
   el: HTMLElement;
   /** Apply streaming deltas / status changes (may be a different record). */
   update(record: PersonaArtifactRecord): void;
+  /**
+   * Release the file-preview loading state machine: pending overlay/settle
+   * timers and the window `message` listener, which otherwise outlive a
+   * discarded preview. Idempotent; call whenever the handle is dropped.
+   */
+  destroy(): void;
 };
 
 const PRE_CLASS =
@@ -990,5 +996,8 @@ export function renderArtifactPreviewBody(
     update(rec: PersonaArtifactRecord) {
       render(rec);
     },
+    destroy() {
+      resetFilePreview();
+    },
   };
 }

package/src/components/header-builder.ts

@@ -11,6 +11,8 @@ export const HEADER_THEME_CSS = {
     "var(--persona-header-subtitle-fg, var(--persona-text-muted, var(--persona-muted, #9ca3af)))",
   actionIconColor:
     "var(--persona-header-action-icon-fg, var(--persona-muted, #9ca3af))",
+  /** One knob for both header builders; the Messages rail header shares it. */
+  minHeight: "var(--persona-header-min-height, auto)",
 } as const;
 
 /**
@@ -65,6 +67,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
       "persona-widget-header persona-flex persona-items-center persona-gap-3 persona-px-6 persona-py-5",
     attrs: { "data-persona-theme-zone": "header" },
     style: {
+      minHeight: HEADER_THEME_CSS.minHeight,
       backgroundColor: "var(--persona-header-bg, var(--persona-surface, #ffffff))",
       borderBottomColor: "var(--persona-header-border, var(--persona-divider, #f1f5f9))",
       boxShadow: "var(--persona-header-shadow, none)",

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

@@ -2,8 +2,10 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { buildMinimalHeader } from "./header-layouts";
+import { buildHeaderWithLayout, buildMinimalHeader } from "./header-layouts";
 import { HEADER_THEME_CSS } from "./header-builder";
+import type { AgentWidgetConfig } from "../types";
+import { setMacPlatformOverride } from "../utils/shortcuts";
 
 const build = (layoutHeaderConfig: Parameters<typeof buildMinimalHeader>[0]["layoutHeaderConfig"]) =>
   buildMinimalHeader({
@@ -27,21 +29,105 @@ describe("minimal header trailing actions", () => {
     );
     expect(button).not.toBeNull();
 
-    // Trailing cluster, not the title row: the button shares a parent with
-    // the close button wrapper and does not precede the title.
-    expect(button!.parentElement).toBe(elements.closeButtonWrapper.parentElement);
+    // Trailing cluster, not the title row: the action's wrapper shares a
+    // parent with the close button wrapper and does not precede the title.
+    expect(button!.parentElement!.parentElement).toBe(
+      elements.closeButtonWrapper.parentElement
+    );
     expect(elements.headerTitle.parentElement!.contains(button!)).toBe(false);
 
-    // Close-button chrome: 32px round hit area, header action-icon color.
-    expect(button!.style.height).toBe("32px");
-    expect(button!.style.width).toBe("32px");
+    // Shared header control chrome: token-sized box, no inline size, header
+    // action-icon color.
+    expect(button!.classList.contains("persona-header-control")).toBe(true);
+    expect(button!.classList.contains("persona-header-control--glyph")).toBe(true);
+    expect(button!.style.width).toBe("");
+    expect(button!.style.height).toBe("");
     expect(button!.style.color).toBe(HEADER_THEME_CSS.actionIconColor);
     expect(button!.className).toContain("persona-rounded-full");
+    // Flex wrapper: an inline-flex button in a block wrapper reserves baseline
+    // slack and rides high.
+    expect(button!.parentElement!.className).toContain("persona-inline-flex");
 
     button!.click();
     expect(onAction).toHaveBeenCalledWith("home");
   });
 
+  it("stamps a declared shortcut on the button and hints it in the tooltip", () => {
+    setMacPlatformOverride(false);
+    const elements = build({
+      layout: "minimal",
+      trailingActions: [
+        {
+          id: "home",
+          icon: "house",
+          ariaLabel: "Back to home",
+          shortcut: "mod+shift+h",
+        },
+      ],
+    });
+    const button = elements.header.querySelector<HTMLButtonElement>(
+      'button[aria-label="Back to home"]'
+    )!;
+    // The shell finds the button by this id to run the binding.
+    expect(button.getAttribute("data-persona-header-action")).toBe("home");
+    expect(button.getAttribute("aria-keyshortcuts")).toBe("Control+Shift+H");
+
+    document.body.appendChild(elements.header);
+    button.parentElement!.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(
+      document.querySelector(".persona-control-tooltip__hint")!.textContent
+    ).toBe("Ctrl+Shift+H");
+    document.body.innerHTML = "";
+    setMacPlatformOverride(null);
+  });
+
+  it("leaves aria-keyshortcuts off an action with no shortcut", () => {
+    const elements = build({
+      layout: "minimal",
+      trailingActions: [{ id: "home", icon: "house", ariaLabel: "Back to home" }],
+    });
+    const button = elements.header.querySelector<HTMLButtonElement>(
+      'button[aria-label="Back to home"]'
+    )!;
+    expect(button.hasAttribute("aria-keyshortcuts")).toBe(false);
+  });
+
+  it("keeps the close button transparent so the UA button fill never shows", () => {
+    const elements = build({ layout: "minimal" });
+    expect(elements.closeButton.className).toContain("persona-bg-transparent");
+    expect(elements.closeButton.className).toContain("hover:persona-bg-gray-100");
+    expect(elements.closeButton.style.backgroundColor).toBe("");
+  });
+
+  it("shares the header control chrome and a flex wrapper with the default layout", () => {
+    const elements = build({ layout: "minimal" });
+    expect(elements.closeButton.classList.contains("persona-header-control")).toBe(true);
+    // Sparse X glyph: the stylesheet scales it up from the icon-size token.
+    expect(
+      elements.closeButton.classList.contains("persona-header-control--sparse")
+    ).toBe(true);
+    expect(elements.closeButton.style.width).toBe("");
+    // The centering bug: a block wrapper reserves inline baseline slack, so
+    // the button rides high inside it.
+    expect(elements.closeButtonWrapper.className).toContain("persona-inline-flex");
+    expect(elements.closeButtonWrapper.className).toContain("persona-items-center");
+  });
+
+  it("applies closeButtonBackgroundColor instead of the transparent default", () => {
+    const elements = buildMinimalHeader({
+      config: {
+        apiUrl: "https://example.com/api",
+        launcher: { closeButtonBackgroundColor: "red" },
+      },
+      showClose: true,
+      onClose: () => {},
+      layoutHeaderConfig: { layout: "minimal" },
+    });
+    expect(elements.closeButton.style.backgroundColor).toBe("red");
+    expect(elements.closeButton.className).not.toContain("persona-bg-transparent");
+    expect(elements.closeButton.className).not.toContain("hover:persona-bg-gray-100");
+  });
+
   it("still ignores trailingActions when titleMenu is configured", () => {
     const elements = build({
       layout: "minimal",
@@ -54,3 +140,81 @@ describe("minimal header trailing actions", () => {
     ).toBeNull();
   });
 });
+
+describe("minimal header clear chat", () => {
+  it("renders clear chat in the cluster between trailing actions and close", () => {
+    const elements = build({
+      layout: "minimal",
+      trailingActions: [{ id: "home", icon: "house", ariaLabel: "Back to home" }],
+    });
+
+    const clear = elements.clearChatButton;
+    expect(clear).not.toBeNull();
+    expect(clear!.classList.contains("persona-header-control")).toBe(true);
+    expect(elements.clearChatButtonWrapper!.parentElement).toBe(
+      elements.closeButtonWrapper.parentElement
+    );
+    const action = elements.header.querySelector('button[aria-label="Back to home"]')!;
+    expect(
+      action.compareDocumentPosition(clear!) & Node.DOCUMENT_POSITION_FOLLOWING
+    ).toBeTruthy();
+    expect(
+      clear!.compareDocumentPosition(elements.closeButton) &
+        Node.DOCUMENT_POSITION_FOLLOWING
+    ).toBeTruthy();
+  });
+
+  it("renders nothing when launcher.clearChat.enabled is false", () => {
+    const elements = buildMinimalHeader({
+      config: {
+        apiUrl: "https://example.com/api",
+        launcher: { clearChat: { enabled: false } },
+      },
+      showClose: true,
+      onClose: () => {},
+      layoutHeaderConfig: { layout: "minimal" },
+    });
+    expect(elements.clearChatButton).toBeNull();
+    expect(elements.clearChatButtonWrapper).toBeNull();
+  });
+
+  it("hides the wrapper under layout.header.showClearChat false", () => {
+    const config = {
+      apiUrl: "https://example.com/api",
+      layout: { header: { layout: "minimal", showClearChat: false } },
+    } as unknown as AgentWidgetConfig;
+    const elements = buildHeaderWithLayout(config, config.layout!.header!, {
+      config,
+      showClose: true,
+      onClose: () => {},
+    });
+    expect(elements.clearChatButtonWrapper).not.toBeNull();
+    expect(elements.clearChatButtonWrapper!.style.display).toBe("none");
+  });
+
+  it("keeps a top-right placement out of the header for the container mount", () => {
+    const elements = buildMinimalHeader({
+      config: {
+        apiUrl: "https://example.com/api",
+        launcher: { clearChat: { placement: "top-right" } },
+      },
+      showClose: true,
+      onClose: () => {},
+      layoutHeaderConfig: { layout: "minimal" },
+    });
+    expect(elements.clearChatButtonWrapper).not.toBeNull();
+    expect(elements.header.contains(elements.clearChatButtonWrapper!)).toBe(false);
+    expect(elements.clearChatButtonWrapper!.style.right).toBe("48px");
+  });
+
+  it("still renders clear chat and close when titleMenu is configured", () => {
+    const elements = build({
+      layout: "minimal",
+      titleMenu: { menuItems: [{ id: "a", label: "A" }], onSelect: () => {} },
+    });
+    expect(elements.clearChatButton).not.toBeNull();
+    expect(elements.clearChatButtonWrapper!.parentElement).toBe(
+      elements.closeButtonWrapper.parentElement
+    );
+  });
+});

package/src/components/header-layouts.ts

@@ -1,7 +1,7 @@
 import { createElement } from "../utils/dom";
-import { renderLucideIcon } from "../utils/icons";
 import { createDropdownMenu } from "../utils/dropdown";
 import { createComboButton } from "../utils/buttons";
+import { ariaCombo, formatCombo } from "../utils/shortcuts";
 import {
   AgentWidgetConfig,
   AgentWidgetHeaderLayoutConfig,
@@ -14,6 +14,11 @@ import {
   HeaderElements,
   attachHeaderToContainer as _attachHeaderToContainer,
 } from "./header-builder";
+import {
+  createClearChatButton,
+  createCloseButton,
+  createHeaderIconButton,
+} from "./header-parts";
 
 export interface HeaderLayoutContext {
   config: AgentWidgetConfig;
@@ -71,29 +76,25 @@ function appendTrailingHeaderActions(
 ): void {
   if (!actions?.length) return;
   for (const a of actions) {
-    // Same chrome as the close button beside them: 32px round hit area,
-    // hover fill, and the header zone's action-icon color (the muted body
-    // token disappears on themed headers).
-    const btn = 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 persona-bg-transparent persona-p-0"
-    ) as HTMLButtonElement;
-    btn.type = "button";
-    btn.style.height = "32px";
-    btn.style.width = "32px";
-    btn.style.color = HEADER_THEME_CSS.actionIconColor;
-    btn.setAttribute("aria-label", a.ariaLabel ?? a.label ?? a.id);
-    if (a.icon) {
-      const ic = renderLucideIcon(a.icon, 16, "currentColor", 2);
-      if (ic) btn.appendChild(ic);
-    } else if (a.label) {
-      btn.textContent = a.label;
+    // Same shared chrome as the close button beside them. The wrapper stays
+    // relative so a dropdown can anchor to it.
+    const { button: btn, wrapper } = createHeaderIconButton({
+      ariaLabel: a.ariaLabel ?? a.label ?? a.id,
+      iconName: a.icon,
+      iconText: a.icon ? undefined : a.label,
+      tooltipHint: a.shortcut ? formatCombo(a.shortcut) : undefined,
+      wrapperClassName:
+        "persona-relative persona-inline-flex persona-items-center persona-justify-center",
+    });
+    // The keydown binding is registered by the shell, which finds the button
+    // by this id; the shortcut's other two artifacts are stamped here.
+    btn.setAttribute("data-persona-header-action", a.id);
+    if (a.shortcut) {
+      const aria = ariaCombo(a.shortcut);
+      if (aria) btn.setAttribute("aria-keyshortcuts", aria);
     }
 
     if (a.menuItems?.length) {
-      // Wrap in a relative container for dropdown positioning
-      const wrapper = createElement("div", "persona-relative");
-      wrapper.appendChild(btn);
       const dropdown = createDropdownMenu({
         items: a.menuItems,
         onSelect: (itemId) => onAction?.(itemId),
@@ -107,11 +108,10 @@ function appendTrailingHeaderActions(
         e.stopPropagation();
         dropdown.toggle();
       });
-      container.appendChild(wrapper);
     } else {
       btn.addEventListener("click", () => onAction?.(a.id));
-      container.appendChild(btn);
     }
+    container.appendChild(wrapper);
   }
 }
 
@@ -119,11 +119,13 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
   const { config, showClose = true, onClose, layoutHeaderConfig, onHeaderAction } = context;
   const launcher = config?.launcher ?? {};
 
+  // max(title 24px, cluster 32px) + py-4 + border = the strip's 65px.
   const header = createElement(
     "div",
     "persona-flex persona-items-center persona-justify-between persona-px-6 persona-py-4"
   );
   header.setAttribute("data-persona-theme-zone", "header");
+  header.style.minHeight = HEADER_THEME_CSS.minHeight;
   header.style.backgroundColor = 'var(--persona-header-bg, var(--persona-surface, #ffffff))';
   header.style.borderBottomColor = 'var(--persona-header-border, var(--persona-divider, #f1f5f9))';
   header.style.boxShadow = 'var(--persona-header-shadow, none)';
@@ -140,7 +142,28 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
     const combo = createComboButton({
       label: launcher.title ?? "Chat Assistant",
       menuItems: titleMenuConfig.menuItems,
-      onSelect: titleMenuConfig.onSelect,
+      // `false` = not handled: bubble the id to the shell's built-ins (star,
+      // delete on the active conversation). A DOM event, not a context
+      // callback, because the initial header is built by the pure panel
+      // builder with no shell in reach.
+      onSelect: (itemId) => {
+        const finish = (handled: unknown): void => {
+          if (handled !== false) return;
+          combo.element.dispatchEvent(
+            new CustomEvent("persona:title-menu-builtin", {
+              bubbles: true,
+              composed: true,
+              detail: { actionId: itemId },
+            })
+          );
+        };
+        const result = titleMenuConfig.onSelect(itemId);
+        if (result instanceof Promise) {
+          void result.then(finish, () => {});
+        } else {
+          finish(result);
+        }
+      },
       hover: titleMenuConfig.hover,
       className: "",
     });
@@ -203,38 +226,20 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
 
   header.appendChild(titleRow);
 
-  // Close button
-  const closeButtonSize = launcher.closeButtonSize ?? "32px";
-  const closeButtonWrapper = createElement("div", "");
-
-  const closeButton = 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;
-  closeButton.style.height = closeButtonSize;
-  closeButton.style.width = closeButtonSize;
-  closeButton.type = "button";
-  closeButton.setAttribute("aria-label", "Close chat");
-  closeButton.style.display = showClose ? "" : "none";
-  closeButton.style.color =
-    launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
-
-  const closeButtonIconName = launcher.closeButtonIconName ?? "x";
-  // Larger intrinsic size compensates for the X glyph's sparse viewBox
-  // (paths only occupy the middle 50%). Matches header-builder.ts.
-  const closeIconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
-  if (closeIconSvg) {
-    closeButton.appendChild(closeIconSvg);
-  } else {
-    closeButton.textContent = "×";
-  }
+  // Close button: same shared factory the default layout uses. The wrapper is
+  // flex so an inline-flex button can never reserve baseline slack and ride
+  // high inside it.
+  const trailingWrapperClass =
+    "persona-relative persona-inline-flex persona-items-center persona-justify-center";
+  const { button: closeButton, wrapper: closeButtonWrapper } = createCloseButton(
+    config,
+    { showClose, wrapperClassName: trailingWrapperClass }
+  );
 
   if (onClose) {
     closeButton.addEventListener("click", onClose);
   }
 
-  closeButtonWrapper.appendChild(closeButton);
-
   // Trailing edge: action buttons cluster with the close button, matching
   // its chrome. `titleMenu` still ignores `trailingActions` (documented).
   const trailingCluster = createElement(
@@ -248,6 +253,31 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
       layoutHeaderConfig?.onAction ?? onHeaderAction
     );
   }
+
+  // Clear chat honors the same config surface as the default layout. Click
+  // wiring is owned by setupClearChatButton() in ui.ts via the returned ref;
+  // top-right placement is mounted by attachHeaderToContainer, also via ref.
+  const clearChatConfig = launcher.clearChat ?? {};
+  let clearChatButton: HTMLButtonElement | null = null;
+  let clearChatButtonWrapper: HTMLElement | null = null;
+  if (clearChatConfig.enabled ?? true) {
+    const clearChatPlacement = clearChatConfig.placement ?? "inline";
+    const parts = createClearChatButton(config, {
+      wrapperClassName:
+        clearChatPlacement === "top-right"
+          ? "persona-absolute persona-top-4 persona-z-50"
+          : trailingWrapperClass,
+    });
+    clearChatButton = parts.button;
+    clearChatButtonWrapper = parts.wrapper;
+    if (clearChatPlacement === "top-right") {
+      clearChatButtonWrapper.style.right = "48px";
+    } else {
+      // Close stays outermost.
+      trailingCluster.appendChild(clearChatButtonWrapper);
+    }
+  }
+
   trailingCluster.appendChild(closeButtonWrapper);
   header.appendChild(trailingCluster);
 
@@ -266,8 +296,8 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
     headerSubtitle,
     closeButton,
     closeButtonWrapper,
-    clearChatButton: null,
-    clearChatButtonWrapper: null
+    clearChatButton,
+    clearChatButtonWrapper
   };
 };
 

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

@@ -1,11 +1,152 @@
 // @vitest-environment jsdom
 
 import { describe, expect, it } from "vitest";
-import { createCloseButton, createClearChatButton } from "./header-parts";
+import {
+  createCloseButton,
+  createClearChatButton,
+  createHeaderIconButton,
+  HEADER_CONTROL_CLASS,
+  HEADER_CONTROL_GLYPH_CLASS,
+  HEADER_CONTROL_SPARSE_CLASS,
+} from "./header-parts";
+import { HEADER_THEME_CSS } from "./header-builder";
 import type { AgentWidgetConfig } from "../types";
 
 const baseConfig: AgentWidgetConfig = { apiUrl: "/api" };
 
+describe("createHeaderIconButton", () => {
+  it("leaves the box and glyph to the tokens when nothing is configured", () => {
+    const { button } = createHeaderIconButton({
+      ariaLabel: "Do it",
+      iconName: "refresh-cw",
+    });
+    expect(button.classList.contains(HEADER_CONTROL_CLASS)).toBe(true);
+    expect(button.classList.contains(HEADER_CONTROL_GLYPH_CLASS)).toBe(true);
+    expect(button.classList.contains(HEADER_CONTROL_SPARSE_CLASS)).toBe(false);
+    expect(button.style.width).toBe("");
+    expect(button.style.height).toBe("");
+    expect(button.style.minWidth).toBe("");
+    expect(button.type).toBe("button");
+    expect(button.getAttribute("aria-label")).toBe("Do it");
+    expect(button.style.color).toBe(HEADER_THEME_CSS.actionIconColor);
+  });
+
+  it("writes an inline box and drops the glyph class for explicit sizes", () => {
+    const { button } = createHeaderIconButton({
+      ariaLabel: "Do it",
+      iconName: "refresh-cw",
+      size: "16px",
+      iconSize: "14px",
+    });
+    expect(button.classList.contains(HEADER_CONTROL_CLASS)).toBe(true);
+    expect(button.classList.contains(HEADER_CONTROL_GLYPH_CLASS)).toBe(false);
+    expect(button.style.width).toBe("16px");
+    expect(button.style.minHeight).toBe("16px");
+    const svg = button.querySelector("svg")!;
+    expect(svg.getAttribute("width")).toBe("14px");
+    expect(svg.getAttribute("stroke-width")).toBe("1.5");
+    expect(svg.style.strokeWidth).toBe(
+      "calc(var(--persona-components-header-controlStrokeWidth, 1.5) * 1)"
+    );
+  });
+
+  it("routes the stroke token inline for explicitly sized glyphs", () => {
+    const { button } = createHeaderIconButton({
+      ariaLabel: "Close",
+      iconName: "x",
+      iconSize: "12px",
+    });
+    // No class hooks, so the stylesheet rules can't reach this control: the
+    // inline style carries the stroke token, with the attribute as the
+    // no-token fallback and the sparse 0.7 factor preserved.
+    expect(button.classList.contains(HEADER_CONTROL_GLYPH_CLASS)).toBe(false);
+    expect(button.classList.contains(HEADER_CONTROL_SPARSE_CLASS)).toBe(false);
+    const svg = button.querySelector("svg")!;
+    expect(svg.getAttribute("stroke-width")).toBe("1.05");
+    expect(svg.style.strokeWidth).toBe(
+      "calc(var(--persona-components-header-controlStrokeWidth, 1.5) * 0.7)"
+    );
+  });
+
+  it("compensates the sparse X glyph in both the class hook and the attributes", () => {
+    const token = createHeaderIconButton({ ariaLabel: "Close", iconName: "x" });
+    expect(token.button.classList.contains(HEADER_CONTROL_SPARSE_CLASS)).toBe(true);
+
+    const explicit = createHeaderIconButton({
+      ariaLabel: "Close",
+      iconName: "x",
+      iconSize: "10px",
+    });
+    // Nominal 10px scaled by 1.4, stroke thinned by the same factor so the
+    // rendered weight still matches a dense sibling glyph.
+    const svg = explicit.button.querySelector("svg")!;
+    expect(svg.getAttribute("width")).toBe("14px");
+    expect(svg.getAttribute("stroke-width")).toBe("1.05");
+    expect(explicit.button.classList.contains(HEADER_CONTROL_SPARSE_CLASS)).toBe(false);
+  });
+
+  it("swaps the transparent default classes for an explicit background", () => {
+    const { button } = createHeaderIconButton({
+      ariaLabel: "Do it",
+      iconName: "refresh-cw",
+      backgroundColor: "rgb(1, 2, 3)",
+      color: "rgb(9, 9, 9)",
+    });
+    expect(button.className).not.toContain("persona-bg-transparent");
+    expect(button.className).not.toContain("hover:persona-bg-gray-100");
+    expect(button.style.backgroundColor).toBe("rgb(1, 2, 3)");
+    expect(button.style.color).toBe("rgb(9, 9, 9)");
+  });
+
+  it("falls back to the text glyph when the icon is not in the registry", () => {
+    const { button } = createHeaderIconButton({
+      ariaLabel: "Close",
+      iconName: "not-a-real-icon",
+      iconText: "×",
+    });
+    expect(button.querySelector("svg")).toBeNull();
+    expect(button.textContent).toBe("×");
+  });
+
+  it("wraps the button in a flex box so it can never ride off-center", () => {
+    const { button, wrapper } = createHeaderIconButton({
+      ariaLabel: "Do it",
+      iconName: "refresh-cw",
+    });
+    expect(button.parentElement).toBe(wrapper);
+    expect(wrapper.className).toContain("persona-inline-flex");
+    expect(wrapper.className).toContain("persona-items-center");
+    expect(wrapper.className).toContain("persona-justify-center");
+  });
+
+  it("attaches the styled tooltip by default, reading the live aria-label", () => {
+    const { button, wrapper } = createHeaderIconButton({
+      ariaLabel: "Messages",
+      iconName: "history",
+    });
+    document.body.appendChild(wrapper);
+    button.setAttribute("aria-label", "Opening conversation");
+    wrapper.dispatchEvent(new MouseEvent("mouseenter"));
+    const tooltip = document.body.querySelector(".persona-control-tooltip");
+    expect(tooltip).not.toBeNull();
+    expect(tooltip!.textContent).toContain("Opening conversation");
+    wrapper.remove();
+    tooltip!.remove();
+  });
+
+  it("attaches no tooltip when tooltip is false", () => {
+    const { wrapper } = createHeaderIconButton({
+      ariaLabel: "Silent",
+      iconName: "x",
+      tooltip: false,
+    });
+    document.body.appendChild(wrapper);
+    wrapper.dispatchEvent(new MouseEvent("mouseenter"));
+    expect(document.body.querySelector(".persona-control-tooltip")).toBeNull();
+    wrapper.remove();
+  });
+});
+
 describe("createCloseButton", () => {
   it("keeps the default utility classes when no style overrides are set", () => {
     const { button } = createCloseButton(baseConfig, {});
@@ -15,6 +156,18 @@ describe("createCloseButton", () => {
     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);
+    // Unset `launcher.closeButtonSize` leaves the control-size token in charge.
+    expect(button.classList.contains(HEADER_CONTROL_CLASS)).toBe(true);
+    expect(button.style.width).toBe("");
+  });
+
+  it("still lets launcher.closeButtonSize pin the box past the token", () => {
+    const { button } = createCloseButton(
+      { ...baseConfig, launcher: { closeButtonSize: "28px" } },
+      {}
+    );
+    expect(button.style.width).toBe("28px");
+    expect(button.style.minWidth).toBe("28px");
   });
 
   it("hides the button when showClose is false", () => {