@runtypelabs/persona 2.3.1 → 3.1.0

package/src/components/artifact-pane.ts

@@ -4,6 +4,8 @@ import { escapeHtml, createMarkdownProcessorFromConfig } from "../postprocessors
 import { resolveSanitizer } from "../utils/sanitize";
 import { componentRegistry, type ComponentContext } from "./registry";
 import { renderLucideIcon } from "../utils/icons";
+import { createDropdownMenu, type DropdownMenuHandle } from "../utils/dropdown";
+import { createIconButton, createLabelButton } from "../utils/buttons";
 
 export type ArtifactPaneApi = {
   element: HTMLElement;
@@ -27,65 +29,6 @@ function fallbackComponentCard(sel: PersonaArtifactRecord): HTMLElement {
   return card;
 }
 
-function iconButton(iconName: string, label: string, extraClass = ""): HTMLButtonElement {
-  const btn = createElement(
-    "button",
-    `persona-inline-flex persona-items-center persona-justify-center persona-rounded-md persona-border persona-border-persona-border persona-bg-persona-surface persona-p-1 persona-text-persona-primary hover:persona-bg-persona-container ${extraClass}`
-  ) as HTMLButtonElement;
-  btn.type = "button";
-  btn.setAttribute("aria-label", label);
-  btn.title = label;
-  const icon = renderLucideIcon(iconName, 16, "currentColor", 2);
-  if (icon) btn.appendChild(icon);
-  return btn;
-}
-
-function documentToolbarIconButton(
-  iconName: string,
-  label: string,
-  extraClass: string
-): HTMLButtonElement {
-  const btn = createElement(
-    "button",
-    `persona-artifact-doc-icon-btn ${extraClass}`.trim()
-  ) as HTMLButtonElement;
-  btn.type = "button";
-  btn.setAttribute("aria-label", label);
-  btn.title = label;
-  const icon = renderLucideIcon(iconName, 16, "currentColor", 2);
-  if (icon) btn.appendChild(icon);
-  return btn;
-}
-
-function documentToolbarCopyMainButton(showLabel: boolean): HTMLButtonElement {
-  const btn = createElement("button", "persona-artifact-doc-copy-btn") as HTMLButtonElement;
-  btn.type = "button";
-  btn.setAttribute("aria-label", "Copy");
-  btn.title = "Copy";
-  const icon = renderLucideIcon("copy", showLabel ? 14 : 16, "currentColor", 2);
-  if (icon) btn.appendChild(icon);
-  if (showLabel) {
-    const span = createElement("span", "persona-artifact-doc-copy-label");
-    span.textContent = "Copy";
-    btn.appendChild(span);
-  }
-  return btn;
-}
-
-function documentToolbarChevronMenuButton(): HTMLButtonElement {
-  const btn = createElement(
-    "button",
-    "persona-artifact-doc-copy-menu-chevron persona-artifact-doc-icon-btn"
-  ) as HTMLButtonElement;
-  btn.type = "button";
-  btn.setAttribute("aria-label", "More copy options");
-  btn.setAttribute("aria-haspopup", "true");
-  btn.setAttribute("aria-expanded", "false");
-  const chev = renderLucideIcon("chevron-down", 14, "currentColor", 2);
-  if (chev) btn.appendChild(chev);
-  return btn;
-}
-
 /**
  * Right-hand artifact sidebar / mobile drawer content.
  */
@@ -119,6 +62,8 @@ export function createArtifactPane(
   const dismissLocalUi = () => {
     backdrop?.classList.add("persona-hidden");
     shell.classList.remove("persona-artifact-drawer-open");
+    // Hide portaled copy menu
+    copyMenuDropdown?.hide();
   };
 
   if (backdrop) {
@@ -162,13 +107,13 @@ export function createArtifactPane(
 
   /** Document preset: view vs raw source */
   let viewMode: "rendered" | "source" = "rendered";
-  const leftTools = createElement("div", "persona-flex persona-items-center persona-gap-1 persona-shrink-0");
+  const leftTools = createElement("div", "persona-flex persona-items-center persona-gap-1 persona-shrink-0 persona-artifact-toggle-group");
   const viewBtn = documentChrome
-    ? documentToolbarIconButton("eye", "Rendered view", "persona-artifact-view-btn")
-    : iconButton("eye", "Rendered view", "");
+    ? createIconButton({ icon: "eye", label: "Rendered view", className: "persona-artifact-doc-icon-btn persona-artifact-view-btn" })
+    : createIconButton({ icon: "eye", label: "Rendered view" });
   const codeBtn = documentChrome
-    ? documentToolbarIconButton("code-2", "Source", "persona-artifact-code-btn")
-    : iconButton("code-2", "Source", "");
+    ? createIconButton({ icon: "code-2", label: "Source", className: "persona-artifact-doc-icon-btn persona-artifact-code-btn" })
+    : createIconButton({ icon: "code-2", label: "Source" });
   const actionsRight = createElement("div", "persona-flex persona-items-center persona-gap-1 persona-shrink-0");
   const showCopyLabel = layout?.documentToolbarShowCopyLabel === true;
   const showCopyChevron = layout?.documentToolbarShowCopyChevron === true;
@@ -178,10 +123,12 @@ export function createArtifactPane(
   let copyWrap: HTMLElement | null = null;
   let copyBtn: HTMLButtonElement;
   let copyMenuChevronBtn: HTMLButtonElement | null = null;
-  let copyMenuEl: HTMLElement | null = null;
+  let copyMenuDropdown: DropdownMenuHandle | null = null;
 
   if (documentChrome && (showCopyLabel || showCopyChevron) && !showCopyMenu) {
-    copyBtn = documentToolbarCopyMainButton(showCopyLabel);
+    copyBtn = showCopyLabel
+      ? createLabelButton({ icon: "copy", label: "Copy", iconSize: 14, className: "persona-artifact-doc-copy-btn" })
+      : createIconButton({ icon: "copy", label: "Copy", className: "persona-artifact-doc-copy-btn" });
     if (showCopyChevron) {
       const chev = renderLucideIcon("chevron-down", 14, "currentColor", 2);
       if (chev) copyBtn.appendChild(chev);
@@ -191,36 +138,29 @@ export function createArtifactPane(
       "div",
       "persona-relative persona-inline-flex persona-items-center persona-gap-0 persona-rounded-md"
     );
-    copyBtn = documentToolbarCopyMainButton(showCopyLabel);
-    copyMenuChevronBtn = documentToolbarChevronMenuButton();
+    copyBtn = showCopyLabel
+      ? createLabelButton({ icon: "copy", label: "Copy", iconSize: 14, className: "persona-artifact-doc-copy-btn" })
+      : createIconButton({ icon: "copy", label: "Copy", className: "persona-artifact-doc-copy-btn" });
+    copyMenuChevronBtn = createIconButton({
+      icon: "chevron-down",
+      label: "More copy options",
+      size: 14,
+      className: "persona-artifact-doc-copy-menu-chevron persona-artifact-doc-icon-btn",
+      aria: { "aria-haspopup": "true", "aria-expanded": "false" }
+    });
     copyWrap.append(copyBtn, copyMenuChevronBtn);
-    copyMenuEl = createElement(
-      "div",
-      "persona-artifact-doc-copy-menu persona-absolute persona-right-0 persona-top-full persona-z-20 persona-mt-1 persona-min-w-[10rem] persona-rounded-md persona-border persona-border-persona-border persona-bg-persona-surface persona-py-1 persona-shadow-md persona-hidden"
-    );
-    copyWrap.appendChild(copyMenuEl);
-    for (const item of copyMenuItems!) {
-      const opt = createElement(
-        "button",
-        "persona-block persona-w-full persona-text-left persona-px-3 persona-py-2 persona-text-xs persona-text-persona-primary hover:persona-bg-persona-container"
-      ) as HTMLButtonElement;
-      opt.type = "button";
-      opt.textContent = item.label;
-      opt.dataset.copyMenuId = item.id;
-      copyMenuEl.appendChild(opt);
-    }
   } else if (documentChrome) {
-    copyBtn = documentToolbarIconButton("copy", "Copy", "");
+    copyBtn = createIconButton({ icon: "copy", label: "Copy", className: "persona-artifact-doc-icon-btn" });
   } else {
-    copyBtn = iconButton("copy", "Copy", "");
+    copyBtn = createIconButton({ icon: "copy", label: "Copy" });
   }
 
   const refreshBtn = documentChrome
-    ? documentToolbarIconButton("refresh-cw", "Refresh", "")
-    : iconButton("refresh-cw", "Refresh", "");
+    ? createIconButton({ icon: "refresh-cw", label: "Refresh", className: "persona-artifact-doc-icon-btn" })
+    : createIconButton({ icon: "refresh-cw", label: "Refresh" });
   const closeIconBtn = documentChrome
-    ? documentToolbarIconButton("x", "Close", "")
-    : iconButton("x", "Close", "");
+    ? createIconButton({ icon: "x", label: "Close", className: "persona-artifact-doc-icon-btn" })
+    : createIconButton({ icon: "x", label: "Close" });
 
   const getSelectedArtifactText = (): { markdown: string; jsonPayload: string; id: string | null } => {
     const sel = records.find((r) => r.id === selectedId) ?? records[records.length - 1];
@@ -262,45 +202,46 @@ export function createArtifactPane(
     await defaultCopy();
   });
 
-  if (copyMenuChevronBtn && copyMenuEl) {
-    const closeMenu = () => {
-      copyMenuEl!.classList.add("persona-hidden");
-      copyMenuChevronBtn!.setAttribute("aria-expanded", "false");
+  if (copyMenuChevronBtn && copyMenuItems?.length) {
+    // Resolve the portal target — widget root for CSS var inheritance, escaping overflow: hidden
+    const resolvePortal = (): HTMLElement => shell.closest("[data-persona-root]") as HTMLElement ?? document.body;
+
+    const initDropdown = () => {
+      copyMenuDropdown = createDropdownMenu({
+        items: copyMenuItems.map((item) => ({ id: item.id, label: item.label })),
+        onSelect: async (actionId) => {
+          const { markdown, jsonPayload, id } = getSelectedArtifactText();
+          const handler = layout?.onDocumentToolbarCopyMenuSelect;
+          try {
+            if (handler) {
+              await handler({ actionId, artifactId: id, markdown, jsonPayload });
+            } else if (actionId === "markdown" || actionId === "md") {
+              await navigator.clipboard.writeText(markdown);
+            } else if (actionId === "json" || actionId === "source") {
+              await navigator.clipboard.writeText(jsonPayload);
+            } else {
+              await navigator.clipboard.writeText(markdown || jsonPayload);
+            }
+          } catch {
+            /* ignore */
+          }
+        },
+        anchor: copyWrap ?? copyMenuChevronBtn!,
+        position: 'bottom-right',
+        portal: resolvePortal(),
+      });
     };
-    copyMenuChevronBtn.addEventListener("click", (e) => {
-      e.stopPropagation();
-      const open = copyMenuEl!.classList.contains("persona-hidden");
-      if (open) {
-        copyMenuEl!.classList.remove("persona-hidden");
-        copyMenuChevronBtn!.setAttribute("aria-expanded", "true");
-      } else {
-        closeMenu();
-      }
-    });
-    if (typeof document !== "undefined") {
-      document.addEventListener("click", closeMenu);
+
+    // Defer init until shell is in the DOM (may not be attached yet)
+    if (shell.isConnected) {
+      initDropdown();
+    } else {
+      requestAnimationFrame(initDropdown);
     }
-    copyMenuEl.addEventListener("click", async (e) => {
-      const t = (e.target as HTMLElement).closest("button[data-copy-menu-id]") as HTMLButtonElement | null;
-      if (!t?.dataset.copyMenuId) return;
+
+    copyMenuChevronBtn.addEventListener("click", (e) => {
       e.stopPropagation();
-      const actionId = t.dataset.copyMenuId;
-      const { markdown, jsonPayload, id } = getSelectedArtifactText();
-      const handler = layout?.onDocumentToolbarCopyMenuSelect;
-      try {
-        if (handler) {
-          await handler({ actionId, artifactId: id, markdown, jsonPayload });
-        } else if (actionId === "markdown" || actionId === "md") {
-          await navigator.clipboard.writeText(markdown);
-        } else if (actionId === "json" || actionId === "source") {
-          await navigator.clipboard.writeText(jsonPayload);
-        } else {
-          await navigator.clipboard.writeText(markdown || jsonPayload);
-        }
-      } catch {
-        /* ignore */
-      }
-      closeMenu();
+      copyMenuDropdown?.toggle();
     });
   }
 
@@ -388,7 +329,7 @@ export function createArtifactPane(
     for (const r of records) {
       const tab = createElement(
         "button",
-        "persona-artifact-tab persona-shrink-0 persona-rounded-lg persona-px-2 persona-py-1 persona-text-xs persona-border persona-border-transparent persona-text-persona-primary hover:persona-bg-persona-container"
+        "persona-artifact-tab persona-shrink-0 persona-rounded-lg persona-px-2 persona-py-1 persona-text-xs persona-border persona-border-transparent persona-text-persona-primary"
       );
       tab.type = "button";
       tab.textContent = r.title || r.id.slice(0, 8);
@@ -461,7 +402,7 @@ export function createArtifactPane(
     shell.classList.toggle("persona-hidden", !has);
     if (backdrop) {
       const root =
-        typeof shell.closest === "function" ? shell.closest("#persona-root") : null;
+        typeof shell.closest === "function" ? shell.closest("[data-persona-root]") : null;
       const narrowHost = root?.classList.contains("persona-artifact-narrow-host") ?? false;
       const isMobile =
         narrowHost ||

package/src/components/composer-builder.ts

@@ -40,23 +40,6 @@ export interface ComposerBuildContext {
   disabled?: boolean;
 }
 
-/**
- * Helper to get font family CSS value from config preset
- */
-const getFontFamilyValue = (
-  family: "sans-serif" | "serif" | "mono"
-): string => {
-  switch (family) {
-    case "serif":
-      return 'Georgia, "Times New Roman", Times, serif';
-    case "mono":
-      return '"Courier New", Courier, "Lucida Console", Monaco, monospace';
-    case "sans-serif":
-    default:
-      return '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif';
-  }
-};
-
 /**
  * Build the composer/footer section of the panel.
  * Extracted for reuse and plugin override support.
@@ -91,12 +74,9 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     "persona-w-full persona-min-h-[24px] persona-resize-none persona-border-none persona-bg-transparent persona-text-sm persona-text-persona-primary focus:persona-outline-none focus:persona-border-none persona-composer-textarea";
   textarea.rows = 1;
 
-  // Apply font family and weight from config
-  const fontFamily = config?.theme?.inputFontFamily ?? "sans-serif";
-  const fontWeight = config?.theme?.inputFontWeight ?? "400";
-
-  textarea.style.fontFamily = getFontFamilyValue(fontFamily);
-  textarea.style.fontWeight = fontWeight;
+  textarea.style.fontFamily =
+    'var(--persona-input-font-family, var(--persona-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif))';
+  textarea.style.fontWeight = "var(--persona-input-font-weight, var(--persona-font-weight, 400))";
 
   // Set up auto-resize: expand up to 3 lines, then scroll
   // Line height is ~20px for text-sm (14px * 1.25 line-height), so 3 lines ≈ 60px

package/src/components/header-builder.ts

@@ -2,6 +2,16 @@ import { createElement, createElementInDocument } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
 import { AgentWidgetConfig } from "../types";
 
+/** CSS `color` values; variables are set on `[data-persona-root]` from `theme.components.header`. */
+export const HEADER_THEME_CSS = {
+  titleColor:
+    "var(--persona-header-title-fg, var(--persona-primary, #2563eb))",
+  subtitleColor:
+    "var(--persona-header-subtitle-fg, var(--persona-text-muted, var(--persona-muted, #9ca3af)))",
+  actionIconColor:
+    "var(--persona-header-action-icon-fg, var(--persona-muted, #9ca3af))",
+} as const;
+
 export interface HeaderElements {
   header: HTMLElement;
   iconHolder: HTMLElement;
@@ -33,9 +43,9 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
   );
   header.setAttribute("data-persona-theme-zone", "header");
   header.style.backgroundColor = 'var(--persona-header-bg, var(--persona-surface, #ffffff))';
-  header.style.borderBottomWidth = '1px';
-  header.style.borderBottomStyle = 'solid';
   header.style.borderBottomColor = 'var(--persona-header-border, var(--persona-divider, #f1f5f9))';
+  header.style.boxShadow = 'var(--persona-header-shadow, none)';
+  header.style.borderBottom = 'var(--persona-header-border-bottom, 1px solid var(--persona-header-border, var(--persona-divider, #f1f5f9)))';
 
   const launcher = config?.launcher ?? {};
   const headerIconSize = launcher.headerIconSize ?? "48px";
@@ -46,17 +56,21 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
   const iconHolder = createElement(
     "div",
-    "persona-flex persona-items-center persona-justify-center persona-rounded-xl persona-bg-persona-primary persona-text-white persona-text-xl"
+    "persona-flex persona-items-center persona-justify-center persona-rounded-xl persona-text-xl"
   );
   iconHolder.style.height = headerIconSize;
   iconHolder.style.width = headerIconSize;
+  iconHolder.style.backgroundColor =
+    "var(--persona-header-icon-bg, var(--persona-primary, #2563eb))";
+  iconHolder.style.color =
+    "var(--persona-header-icon-fg, var(--persona-text-inverse, #ffffff))";
 
   // Render icon based on priority: Lucide icon > iconUrl > agentIconText
   if (!headerIconHidden) {
     if (headerIconName) {
       // Use Lucide icon
       const iconSize = parseFloat(headerIconSize) || 24;
-      const iconSvg = renderLucideIcon(headerIconName, iconSize * 0.6, "var(--persona-text-inverse, #ffffff)", 1);
+      const iconSvg = renderLucideIcon(headerIconName, iconSize * 0.6, "currentColor", 1);
       if (iconSvg) {
         iconHolder.replaceChildren(iconSvg);
       } else {
@@ -80,8 +94,10 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
   const headerCopy = createElement("div", "persona-flex persona-flex-col");
   const title = createElement("span", "persona-text-base persona-font-semibold");
+  title.style.color = HEADER_THEME_CSS.titleColor;
   title.textContent = config?.launcher?.title ?? "Chat Assistant";
-  const subtitle = createElement("span", "persona-text-xs persona-text-persona-muted");
+  const subtitle = createElement("span", "persona-text-xs");
+  subtitle.style.color = HEADER_THEME_CSS.subtitleColor;
   subtitle.textContent =
     config?.launcher?.subtitle ?? "Here to help you get answers fast";
 
@@ -132,31 +148,22 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
     clearChatButton = createElement(
       "button",
-      "persona-inline-flex persona-items-center persona-justify-center persona-rounded-full persona-text-persona-muted hover:persona-bg-gray-100 persona-cursor-pointer persona-border-none"
+      "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;
 
     clearChatButton.style.height = clearChatSize;
     clearChatButton.style.width = clearChatSize;
     clearChatButton.type = "button";
     clearChatButton.setAttribute("aria-label", clearChatTooltipText);
+    clearChatButton.style.color =
+      clearChatIconColor || HEADER_THEME_CSS.actionIconColor;
 
     // Add icon
-    const iconSvg = renderLucideIcon(
-      clearChatIconName,
-      "20px",
-      clearChatIconColor || "",
-      1
-    );
+    const iconSvg = renderLucideIcon(clearChatIconName, "20px", "currentColor", 1);
     if (iconSvg) {
       clearChatButton.appendChild(iconSvg);
     }
 
-    // Apply styling from config
-    if (clearChatIconColor) {
-      clearChatButton.style.color = clearChatIconColor;
-      clearChatButton.classList.remove("persona-text-persona-muted");
-    }
-
     if (clearChatBgColor) {
       clearChatButton.style.backgroundColor = clearChatBgColor;
       clearChatButton.classList.remove("hover:persona-bg-gray-100");
@@ -281,7 +288,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
   // Create close button with base classes
   const closeButton = createElement(
     "button",
-    "persona-inline-flex persona-items-center persona-justify-center persona-rounded-full persona-text-persona-muted hover:persona-bg-gray-100 persona-cursor-pointer persona-border-none"
+    "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;
@@ -297,29 +304,17 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
   // Add icon or fallback text
   const closeButtonIconName = launcher.closeButtonIconName ?? "x";
   const closeButtonIconText = launcher.closeButtonIconText ?? "×";
+  closeButton.style.color =
+    launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
 
   // Try to render Lucide icon, fallback to text if not provided or fails
-  const closeIconSvg = renderLucideIcon(
-    closeButtonIconName,
-    "20px",
-    launcher.closeButtonColor || "",
-    1
-  );
+  const closeIconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 1);
   if (closeIconSvg) {
     closeButton.appendChild(closeIconSvg);
   } else {
     closeButton.textContent = closeButtonIconText;
   }
 
-  // Apply close button styling from config
-  if (launcher.closeButtonColor) {
-    closeButton.style.color = launcher.closeButtonColor;
-    closeButton.classList.remove("persona-text-persona-muted");
-  } else {
-    closeButton.style.color = "";
-    closeButton.classList.add("persona-text-persona-muted");
-  }
-
   if (launcher.closeButtonBackgroundColor) {
     closeButton.style.backgroundColor = launcher.closeButtonBackgroundColor;
     closeButton.classList.remove("hover:persona-bg-gray-100");

package/src/components/header-layouts.ts

@@ -1,11 +1,18 @@
 import { createElement } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
+import { createDropdownMenu } from "../utils/dropdown";
+import { createComboButton } from "../utils/buttons";
 import {
   AgentWidgetConfig,
   AgentWidgetHeaderLayoutConfig,
   AgentWidgetHeaderTrailingAction
 } from "../types";
-import { buildHeader, HeaderElements, attachHeaderToContainer as _attachHeaderToContainer } from "./header-builder";
+import {
+  buildHeader,
+  HEADER_THEME_CSS,
+  HeaderElements,
+  attachHeaderToContainer as _attachHeaderToContainer,
+} from "./header-builder";
 
 export interface HeaderLayoutContext {
   config: AgentWidgetConfig;
@@ -75,8 +82,27 @@ function appendTrailingHeaderActions(
     } else if (a.label) {
       btn.textContent = a.label;
     }
-    btn.addEventListener("click", () => onAction?.(a.id));
-    container.appendChild(btn);
+
+    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),
+        anchor: wrapper,
+        position: 'bottom-left',
+      });
+      wrapper.appendChild(dropdown.element);
+      btn.addEventListener("click", (e) => {
+        e.stopPropagation();
+        dropdown.toggle();
+      });
+      container.appendChild(wrapper);
+    } else {
+      btn.addEventListener("click", () => onAction?.(a.id));
+      container.appendChild(btn);
+    }
   }
 }
 
@@ -86,43 +112,88 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
 
   const header = createElement(
     "div",
-    "persona-flex persona-items-center persona-justify-between persona-bg-persona-surface persona-px-6 persona-py-4 persona-border-b-persona-divider"
+    "persona-flex persona-items-center persona-justify-between persona-px-6 persona-py-4"
   );
   header.setAttribute("data-persona-theme-zone", "header");
+  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)';
+  header.style.borderBottom =
+    'var(--persona-header-border-bottom, 1px solid var(--persona-header-border, var(--persona-divider, #f1f5f9)))';
 
-  const titleRow = createElement(
-    "div",
-    "persona-flex persona-min-w-0 persona-flex-1 persona-items-center persona-gap-1"
-  );
+  // Build the title area — either a combo button (titleMenu) or standard title row
+  const titleMenuConfig = layoutHeaderConfig?.titleMenu;
+  let titleRow: HTMLElement;
+  let headerTitle: HTMLElement;
+
+  if (titleMenuConfig) {
+    // Combo button replaces title + trailing actions + hover
+    const combo = createComboButton({
+      label: launcher.title ?? "Chat Assistant",
+      menuItems: titleMenuConfig.menuItems,
+      onSelect: titleMenuConfig.onSelect,
+      hover: titleMenuConfig.hover,
+      className: "",
+    });
+    titleRow = combo.element;
+    titleRow.style.color = HEADER_THEME_CSS.titleColor;
+    // The combo button's label span acts as headerTitle for update()
+    headerTitle = titleRow.querySelector(".persona-combo-btn-label") ?? titleRow;
+  } else {
+    titleRow = createElement(
+      "div",
+      "persona-flex persona-min-w-0 persona-flex-1 persona-items-center persona-gap-1"
+    );
 
-  // Title only (no icon, no subtitle)
-  const title = createElement("span", "persona-text-base persona-font-semibold persona-truncate");
-  title.textContent = launcher.title ?? "Chat Assistant";
+    // Title only (no icon, no subtitle)
+    headerTitle = createElement("span", "persona-text-base persona-font-semibold persona-truncate");
+    headerTitle.style.color = HEADER_THEME_CSS.titleColor;
+    headerTitle.textContent = launcher.title ?? "Chat Assistant";
 
-  titleRow.appendChild(title);
-  appendTrailingHeaderActions(
-    titleRow,
-    layoutHeaderConfig?.trailingActions,
-    layoutHeaderConfig?.onAction ?? onHeaderAction
-  );
+    titleRow.appendChild(headerTitle);
+    appendTrailingHeaderActions(
+      titleRow,
+      layoutHeaderConfig?.trailingActions,
+      layoutHeaderConfig?.onAction ?? onHeaderAction
+    );
 
-  // Make title row clickable when onTitleClick is provided
-  if (layoutHeaderConfig?.onTitleClick) {
-    titleRow.style.cursor = "pointer";
-    titleRow.setAttribute("role", "button");
-    titleRow.setAttribute("tabindex", "0");
-    const handleTitleClick = layoutHeaderConfig.onTitleClick;
-    titleRow.addEventListener("click", (e) => {
-      // Skip if the click was on a trailing action button
-      if ((e.target as HTMLElement).closest("button")) return;
-      handleTitleClick();
-    });
-    titleRow.addEventListener("keydown", (e) => {
-      if (e.key === "Enter" || e.key === " ") {
-        e.preventDefault();
+    // Make title row clickable when onTitleClick is provided
+    if (layoutHeaderConfig?.onTitleClick) {
+      titleRow.style.cursor = "pointer";
+      titleRow.setAttribute("role", "button");
+      titleRow.setAttribute("tabindex", "0");
+      const handleTitleClick = layoutHeaderConfig.onTitleClick;
+      titleRow.addEventListener("click", (e) => {
+        if ((e.target as HTMLElement).closest("button")) return;
         handleTitleClick();
-      }
-    });
+      });
+      titleRow.addEventListener("keydown", (e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          handleTitleClick();
+        }
+      });
+    }
+
+    // Title row hover pill effect
+    const hoverCfg = layoutHeaderConfig?.titleRowHover;
+    if (hoverCfg) {
+      titleRow.style.borderRadius = hoverCfg.borderRadius ?? '10px';
+      titleRow.style.padding = hoverCfg.padding ?? '6px 4px 6px 12px';
+      titleRow.style.margin = '-6px 0 -6px -12px';
+      titleRow.style.border = '1px solid transparent';
+      titleRow.style.transition = 'background-color 0.15s ease, border-color 0.15s ease';
+      titleRow.style.width = 'fit-content';
+      titleRow.style.flex = 'none';
+      titleRow.addEventListener('mouseenter', () => {
+        titleRow.style.backgroundColor = hoverCfg.background ?? '';
+        titleRow.style.borderColor = hoverCfg.border ?? '';
+      });
+      titleRow.addEventListener('mouseleave', () => {
+        titleRow.style.backgroundColor = '';
+        titleRow.style.borderColor = 'transparent';
+      });
+    }
   }
 
   header.appendChild(titleRow);
@@ -133,21 +204,18 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
 
   const closeButton = createElement(
     "button",
-    "persona-inline-flex persona-items-center persona-justify-center persona-rounded-full persona-text-persona-muted hover:persona-bg-gray-100 persona-cursor-pointer persona-border-none"
+    "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";
-  const closeIconSvg = renderLucideIcon(
-    closeButtonIconName,
-    "20px",
-    launcher.closeButtonColor || "",
-    2
-  );
+  const closeIconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 2);
   if (closeIconSvg) {
     closeButton.appendChild(closeIconSvg);
   } else {
@@ -172,7 +240,7 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
   return {
     header,
     iconHolder,
-    headerTitle: title,
+    headerTitle,
     headerSubtitle,
     closeButton,
     closeButtonWrapper,