@runtypelabs/persona 2.3.0 → 3.0.0

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 `#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,

package/src/components/launcher.ts

@@ -1,7 +1,7 @@
 import { createElement } from "../utils/dom";
 import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
-import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
+import { isDockedMountMode } from "../utils/dock";
 import { renderLucideIcon } from "../utils/icons";
 
 export interface LauncherButton {
@@ -175,18 +175,21 @@ export const createLauncherButton = (
     button.style.boxShadow = launcher.shadow ?? defaultShadow;
 
     if (dockedMode) {
-      const dock = resolveDockConfig(newConfig);
-      button.style.width = `calc(${dock.collapsedWidth} - 16px)`;
-      button.style.minWidth = "40px";
-      button.style.maxWidth = `calc(${dock.collapsedWidth} - 16px)`;
-      button.style.justifyContent = "center";
-      button.style.padding = "12px 0";
+      // Docked mode uses a 0px column when closed and hides this button; keep no hit target.
+      button.style.width = "0";
+      button.style.minWidth = "0";
+      button.style.maxWidth = "0";
+      button.style.padding = "0";
+      button.style.overflow = "hidden";
+      button.style.border = "none";
+      button.style.boxShadow = "none";
     } else {
       button.style.width = "";
       button.style.minWidth = "";
       button.style.maxWidth = "";
       button.style.justifyContent = "";
       button.style.padding = "";
+      button.style.overflow = "";
     }
   };
 

package/src/components/message-bubble.ts

@@ -9,7 +9,7 @@ import {
   LoadingIndicatorRenderContext,
   ImageContentPart
 } from "../types";
-import { renderLucideIcon } from "../utils/icons";
+import { createIconButton } from "../utils/buttons";
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "../utils/content";
 
 /** Validate that an image src URL uses a safe scheme (blocks javascript: and SVG data URIs). */
@@ -414,17 +414,13 @@ export const createMessageActions = (
     label: string,
     dataAction: string
   ): HTMLButtonElement => {
-    const button = document.createElement("button");
-    button.className = "persona-message-action-btn";
-    button.setAttribute("aria-label", label);
-    button.setAttribute("title", label);
+    const button = createIconButton({
+      icon: iconName,
+      label,
+      size: 14,
+      className: "persona-message-action-btn",
+    });
     button.setAttribute("data-action", dataAction);
-
-    const icon = renderLucideIcon(iconName, 14, "currentColor", 2);
-    if (icon) {
-      button.appendChild(icon);
-    }
-
     return button;
   };
 

package/src/components/panel.ts

@@ -133,10 +133,10 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   body.id = "persona-scroll-container";
   body.setAttribute("data-persona-theme-zone", "messages");
   
-  const introCard = createElement(
-    "div",
-    "persona-rounded-2xl persona-bg-persona-surface persona-p-6 persona-shadow-sm"
-  );
+  const introCardClasses = isDockedMountMode(config)
+    ? "persona-rounded-2xl persona-bg-persona-surface persona-p-6"
+    : "persona-rounded-2xl persona-bg-persona-surface persona-p-6 persona-shadow-sm";
+  const introCard = createElement("div", introCardClasses);
   const introTitle = createElement(
     "h2",
     "persona-text-lg persona-font-semibold persona-text-persona-primary"

package/src/defaults.ts

@@ -1,82 +1,6 @@
-import type { AgentWidgetConfig, AgentWidgetTheme } from "./types";
-
-/**
- * Default light theme colors
- */
-export const DEFAULT_LIGHT_THEME: AgentWidgetTheme = {
-  primary: "#111827",
-  accent: "#1d4ed8",
-  surface: "#ffffff",
-  muted: "#6b7280",
-  container: "#f8fafc",
-  border: "#f1f5f9",
-  divider: "#f1f5f9",
-  messageBorder: "#f1f5f9",
-  inputBackground: "#ffffff",
-  callToAction: "#000000",
-  callToActionBackground: "#ffffff",
-  sendButtonBackgroundColor: "#111827",
-  sendButtonTextColor: "#ffffff",
-  sendButtonBorderColor: "#60a5fa",
-  closeButtonColor: "#6b7280",
-  closeButtonBackgroundColor: "transparent",
-  closeButtonBorderColor: "",
-  clearChatIconColor: "#6b7280",
-  clearChatBackgroundColor: "transparent",
-  clearChatBorderColor: "transparent",
-  micIconColor: "#111827",
-  micBackgroundColor: "transparent",
-  micBorderColor: "transparent",
-  recordingIconColor: "#ffffff",
-  recordingBackgroundColor: "#ef4444",
-  recordingBorderColor: "transparent",
-  inputFontFamily: "sans-serif",
-  inputFontWeight: "400",
-  radiusSm: "0.75rem",
-  radiusMd: "1rem",
-  radiusLg: "1.5rem",
-  launcherRadius: "9999px",
-  buttonRadius: "9999px",
-};
-
-/**
- * Default dark theme colors
- */
-export const DEFAULT_DARK_THEME: AgentWidgetTheme = {
-  primary: "#f9fafb",
-  accent: "#3b82f6",
-  surface: "#1f2937",
-  muted: "#9ca3af",
-  container: "#111827",
-  border: "#374151",
-  divider: "#374151",
-  messageBorder: "#374151",
-  inputBackground: "#111827",
-  callToAction: "#ffffff",
-  callToActionBackground: "#374151",
-  sendButtonBackgroundColor: "#3b82f6",
-  sendButtonTextColor: "#ffffff",
-  sendButtonBorderColor: "#60a5fa",
-  closeButtonColor: "#9ca3af",
-  closeButtonBackgroundColor: "transparent",
-  closeButtonBorderColor: "",
-  clearChatIconColor: "#9ca3af",
-  clearChatBackgroundColor: "transparent",
-  clearChatBorderColor: "transparent",
-  micIconColor: "#f9fafb",
-  micBackgroundColor: "transparent",
-  micBorderColor: "transparent",
-  recordingIconColor: "#ffffff",
-  recordingBackgroundColor: "#ef4444",
-  recordingBorderColor: "transparent",
-  inputFontFamily: "sans-serif",
-  inputFontWeight: "400",
-  radiusSm: "0.75rem",
-  radiusMd: "1rem",
-  radiusLg: "1.5rem",
-  launcherRadius: "9999px",
-  buttonRadius: "9999px",
-};
+import type { AgentWidgetConfig } from "./types";
+import type { DeepPartial, PersonaTheme } from "./types/theme";
+import { deepMerge } from "./utils/deep-merge";
 
 /**
  * Default widget configuration
@@ -86,8 +10,8 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   apiUrl: "http://localhost:43111/api/chat/dispatch",
   // Client token mode defaults (optional, only used when clientToken is set)
   clientToken: undefined,
-  theme: DEFAULT_LIGHT_THEME,
-  darkTheme: DEFAULT_DARK_THEME,
+  theme: undefined,
+  darkTheme: undefined,
   colorScheme: "light",
   launcher: {
     enabled: true,
@@ -95,7 +19,6 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
     dock: {
       side: "right",
       width: "420px",
-      collapsedWidth: "72px",
     },
     title: "Chat Assistant",
     subtitle: "Here to help you get answers fast",
@@ -114,10 +37,9 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
     callToActionIconPadding: "5px",
     callToActionIconColor: "#000000",
     callToActionIconBackgroundColor: "#ffffff",
-    closeButtonColor: "#6b7280",
+    // closeButtonColor / clearChat.iconColor omitted so theme.components.header.actionIconForeground applies.
     closeButtonBackgroundColor: "transparent",
     clearChat: {
-      iconColor: "#6b7280",
       backgroundColor: "transparent",
       borderColor: "transparent",
       enabled: true,
@@ -225,7 +147,7 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   messageActions: {
     enabled: true,
     showCopy: true,
-    showUpvote: false,  // Requires backend - disabled by default
+    showUpvote: false, // Requires backend - disabled by default
     showDownvote: false, // Requires backend - disabled by default
     visibility: "hover",
     align: "right",
@@ -234,6 +156,19 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   debug: false,
 };
 
+function mergeThemePartials(
+  base: DeepPartial<PersonaTheme> | undefined,
+  override: DeepPartial<PersonaTheme> | undefined
+): DeepPartial<PersonaTheme> | undefined {
+  if (!base && !override) return undefined;
+  if (!base) return override;
+  if (!override) return base;
+  return deepMerge(
+    base as Record<string, unknown>,
+    override as Record<string, unknown>
+  ) as DeepPartial<PersonaTheme>;
+}
+
 /**
  * Helper to deep merge user config with defaults
  * This ensures all default values are present while allowing selective overrides
@@ -246,14 +181,8 @@ export function mergeWithDefaults(
   return {
     ...DEFAULT_WIDGET_CONFIG,
     ...config,
-    theme: {
-      ...DEFAULT_WIDGET_CONFIG.theme,
-      ...config.theme,
-    },
-    darkTheme: {
-      ...DEFAULT_WIDGET_CONFIG.darkTheme,
-      ...config.darkTheme,
-    },
+    theme: mergeThemePartials(DEFAULT_WIDGET_CONFIG.theme, config.theme),
+    darkTheme: mergeThemePartials(DEFAULT_WIDGET_CONFIG.darkTheme, config.darkTheme),
     launcher: {
       ...DEFAULT_WIDGET_CONFIG.launcher,
       ...config.launcher,

package/src/index.ts

@@ -5,7 +5,6 @@ import {
 
 export type {
   AgentWidgetConfig,
-  AgentWidgetTheme,
   AgentWidgetFeatureFlags,
   AgentWidgetArtifactsFeature,
   AgentWidgetArtifactsLayoutConfig,
@@ -179,6 +178,22 @@ export type { AgentWidgetInitHandle };
 export type { AgentWidgetPlugin } from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
+// Dropdown utility exports
+export { createDropdownMenu } from "./utils/dropdown";
+export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";
+
+// Button utility exports
+export { createIconButton, createLabelButton, createToggleGroup, createComboButton } from "./utils/buttons";
+export type {
+  CreateIconButtonOptions,
+  CreateLabelButtonOptions,
+  CreateToggleGroupOptions,
+  ToggleGroupItem,
+  ToggleGroupHandle,
+  CreateComboButtonOptions,
+  ComboButtonHandle
+} from "./utils/buttons";
+
 // Theme system exports
 export {
   createTheme,
@@ -206,11 +221,8 @@ export {
   highContrastPlugin,
   createPlugin
 } from "./utils/plugins";
-export {
-  migrateV1Theme,
-  validateV1Theme
-} from "./utils/migration";
 export type {
+  DeepPartial,
   PersonaTheme,
   PersonaThemePlugin,
   CreateThemeOptions,
@@ -229,6 +241,9 @@ export type {
   ArtifactToolbarTokens,
   ArtifactTabTokens,
   ArtifactPaneTokens,
+  IconButtonTokens,
+  LabelButtonTokens,
+  ToggleGroupTokens,
   ThemeValidationResult,
   ThemeValidationError
 } from "./types/theme";
@@ -251,8 +266,6 @@ export {
 // Default configuration exports
 export {
   DEFAULT_WIDGET_CONFIG,
-  DEFAULT_LIGHT_THEME,
-  DEFAULT_DARK_THEME,
   mergeWithDefaults
 } from "./defaults";
 export {