@runtypelabs/persona 2.3.0 → 3.0.0

package/src/styles/widget.css

@@ -2067,7 +2067,7 @@
   padding: var(--persona-artifact-toolbar-icon-padding, 0.25rem);
   border-radius: var(--persona-artifact-toolbar-icon-radius, var(--persona-radius-md, 0.375rem));
   border: var(--persona-artifact-toolbar-icon-border, 1px solid var(--persona-border, #e5e7eb));
-  background: var(--persona-surface, #ffffff);
+  background: var(--persona-artifact-toolbar-icon-bg, var(--persona-surface, #ffffff));
   color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
   cursor: pointer;
   line-height: 1;
@@ -2105,18 +2105,6 @@
   font-weight: 500;
 }
 
-/* Copy menu dropdown theming */
-#persona-root .persona-artifact-doc-copy-menu {
-  background: var(--persona-artifact-toolbar-copy-menu-bg, var(--persona-surface, #fff));
-  border: var(--persona-artifact-toolbar-copy-menu-border, 1px solid var(--persona-border, #e5e7eb));
-  box-shadow: var(--persona-artifact-toolbar-copy-menu-shadow, 0 4px 6px -1px rgba(0,0,0,.1));
-  border-radius: var(--persona-artifact-toolbar-copy-menu-radius, 0.375rem);
-}
-
-#persona-root .persona-artifact-doc-copy-menu button:hover {
-  background: var(--persona-artifact-toolbar-copy-menu-item-hover-bg, var(--persona-container, #f3f4f6));
-}
-
 /* Artifact tab theming */
 #persona-root .persona-artifact-tab {
   background: var(--persona-artifact-tab-bg, transparent);
@@ -2134,6 +2122,200 @@
   background: var(--persona-artifact-toolbar-bg, var(--persona-surface, #fff));
 }
 
+/* Toggle group gap */
+#persona-root .persona-artifact-toggle-group {
+  gap: var(--persona-artifact-toolbar-toggle-group-gap, 0.25rem);
+}
+
+/* Toggle button border-radius (view/code buttons) */
+#persona-root .persona-artifact-toolbar-document .persona-artifact-view-btn,
+#persona-root .persona-artifact-toolbar-document .persona-artifact-code-btn {
+  border-radius: var(--persona-artifact-toolbar-toggle-radius, var(--persona-artifact-toolbar-icon-radius, var(--persona-radius-md, 0.375rem)));
+}
+
+/* Tab hover */
+#persona-root .persona-artifact-tab:hover {
+  background: var(--persona-artifact-tab-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+/* Tab list container */
+#persona-root .persona-artifact-list {
+  background: var(--persona-artifact-tab-list-bg, transparent);
+  border-bottom-color: var(--persona-artifact-tab-list-border-color, var(--persona-border, #e5e7eb));
+  padding: var(--persona-artifact-tab-list-padding, 0.5rem);
+}
+
+/* Toolbar border override */
+#persona-root .persona-artifact-toolbar-document {
+  border-bottom: var(--persona-artifact-toolbar-border, 1px solid var(--persona-border, #e5e7eb));
+}
+
+/* ── Composable button utilities ── */
+
+/* Icon button — base for all icon-only buttons created by createIconButton() */
+#persona-root .persona-icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--persona-icon-btn-padding, 0.25rem);
+  border-radius: var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-icon-btn-border, 1px solid var(--persona-border, #e5e7eb));
+  background: var(--persona-icon-btn-bg, var(--persona-surface, #ffffff));
+  color: var(--persona-icon-btn-color, var(--persona-text, #111827));
+  cursor: pointer;
+  line-height: 1;
+  transition: background-color 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+}
+
+#persona-root .persona-icon-btn:hover {
+  background: var(--persona-icon-btn-hover-bg, var(--persona-container, #f3f4f6));
+  color: var(--persona-icon-btn-hover-color, inherit);
+}
+
+#persona-root .persona-icon-btn:focus-visible {
+  outline: 2px solid var(--persona-accent, #3b82f6);
+  outline-offset: 2px;
+}
+
+#persona-root .persona-icon-btn[aria-pressed="true"] {
+  background: var(--persona-icon-btn-active-bg, var(--persona-container, #f3f4f6));
+  border-color: var(--persona-icon-btn-active-border, var(--persona-border, #e5e7eb));
+}
+
+/* Label button — icon + text button created by createLabelButton() */
+#persona-root .persona-label-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--persona-label-btn-gap, 0.35rem);
+  padding: var(--persona-label-btn-padding, 0.25rem 0.5rem);
+  border-radius: var(--persona-label-btn-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-label-btn-border, 1px solid var(--persona-border, #e5e7eb));
+  background: var(--persona-label-btn-bg, var(--persona-surface, #ffffff));
+  color: var(--persona-label-btn-color, var(--persona-text, #111827));
+  cursor: pointer;
+  font-size: var(--persona-label-btn-font-size, 0.75rem);
+  font-weight: 500;
+  line-height: 1.25;
+  white-space: nowrap;
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+
+#persona-root .persona-label-btn:hover {
+  background: var(--persona-label-btn-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+#persona-root .persona-label-btn:focus-visible {
+  outline: 2px solid var(--persona-accent, #3b82f6);
+  outline-offset: 2px;
+}
+
+#persona-root .persona-label-btn--sm {
+  padding: var(--persona-label-btn-padding, 0.25rem 0.5rem);
+  font-size: var(--persona-label-btn-font-size, 0.75rem);
+}
+
+#persona-root .persona-label-btn--md {
+  padding: 0.375rem 0.75rem;
+  font-size: 0.8125rem;
+}
+
+#persona-root .persona-label-btn--primary {
+  background: var(--persona-primary, #3b82f6);
+  color: var(--persona-text-inverse, #ffffff);
+  border-color: transparent;
+}
+
+#persona-root .persona-label-btn--primary:hover {
+  opacity: 0.9;
+}
+
+#persona-root .persona-label-btn--destructive {
+  color: var(--persona-label-btn-destructive-color, #ef4444);
+}
+
+#persona-root .persona-label-btn--ghost {
+  border: none;
+  background: transparent;
+}
+
+#persona-root .persona-label-btn--ghost:hover {
+  background: var(--persona-label-btn-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+/* Toggle group — mutually exclusive button set created by createToggleGroup() */
+#persona-root .persona-toggle-group {
+  display: inline-flex;
+  gap: var(--persona-toggle-group-gap, 0);
+}
+
+#persona-root .persona-toggle-group > .persona-icon-btn {
+  border-radius: 0;
+}
+
+#persona-root .persona-toggle-group > .persona-icon-btn:first-child {
+  border-top-left-radius: var(--persona-toggle-group-radius, var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem)));
+  border-bottom-left-radius: var(--persona-toggle-group-radius, var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem)));
+}
+
+#persona-root .persona-toggle-group > .persona-icon-btn:last-child {
+  border-top-right-radius: var(--persona-toggle-group-radius, var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem)));
+  border-bottom-right-radius: var(--persona-toggle-group-radius, var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem)));
+}
+
+/* Combo button — label + chevron with dropdown */
+#persona-root .persona-combo-btn {
+  font-size: var(--persona-combo-btn-font-size, 0.8125rem);
+  font-weight: var(--persona-combo-btn-font-weight, 600);
+  color: var(--persona-combo-btn-color, var(--persona-text, #111827));
+  user-select: none;
+}
+
+#persona-root .persona-combo-btn-label {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Dropdown menu utility */
+#persona-root .persona-dropdown-menu {
+  z-index: 100;
+  min-width: 160px;
+  background: var(--persona-dropdown-bg, var(--persona-surface, #fff));
+  border: var(--persona-dropdown-border, 1px solid var(--persona-border, #e5e7eb));
+  border-radius: var(--persona-dropdown-radius, 0.625rem);
+  padding: 0.25rem 0;
+  box-shadow: var(--persona-dropdown-shadow, 0 4px 16px rgba(0,0,0,0.12));
+}
+
+#persona-root .persona-dropdown-menu button {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  width: 100%;
+  padding: 0.5rem 0.875rem;
+  border: none;
+  background: transparent;
+  color: var(--persona-dropdown-item-color, var(--persona-text, #1f2937));
+  font-size: 0.8125rem;
+  cursor: pointer;
+  text-align: left;
+  white-space: nowrap;
+}
+
+#persona-root .persona-dropdown-menu button:hover {
+  background: var(--persona-dropdown-item-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+#persona-root .persona-dropdown-menu button[data-destructive] {
+  color: var(--persona-dropdown-destructive-color, #ef4444);
+}
+
+#persona-root .persona-dropdown-menu hr {
+  border: none;
+  border-top: 1px solid var(--persona-dropdown-hr, var(--persona-border, #e5e7eb));
+  margin: 0.25rem 0;
+}
+
 /* Draggable split handle (desktop split only; hidden in drawer / narrow host / small viewport) */
 #persona-root .persona-artifact-split-handle {
   width: 6px;
@@ -2178,7 +2360,11 @@
 #persona-root .persona-artifact-pane {
   border-radius: var(--persona-artifact-pane-radius, 0);
   overflow: hidden;
-  background-color: var(--persona-artifact-pane-bg, var(--persona-surface, #ffffff));
+  /* Layout paneBackground → theme components.artifact.pane.background → semantic surface */
+  background-color: var(
+    --persona-artifact-pane-bg,
+    var(--persona-components-artifact-pane-background, var(--persona-surface, #ffffff))
+  );
 }
 
 /* paneAppearance: 'seamless' — flush with chat, no border/shadow/gap */
@@ -2192,7 +2378,11 @@
   border-left-width: 0 !important;
   border-left-color: transparent !important;
   box-shadow: none !important;
-  background-color: var(--persona-artifact-pane-bg, var(--persona-container, #f8fafc));
+  /* Same token chain; final fallback stays container for flush split chrome */
+  background-color: var(
+    --persona-artifact-pane-bg,
+    var(--persona-components-artifact-pane-background, var(--persona-container, #f8fafc))
+  );
 }
 
 /* layout.paneBorder / paneBorderLeft — theme overrides (after appearance defaults) */

package/src/types/theme.ts

@@ -199,6 +199,20 @@ export interface HeaderTokens extends ComponentTokenSet {
   background: TokenReference<'color'>;
   border: TokenReference<'color'>;
   borderRadius: TokenReference<'radius'>;
+  /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
+  iconBackground: TokenReference<'color'>;
+  /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
+  iconForeground: TokenReference<'color'>;
+  /** Header title line (next to the icon, or minimal layout title). */
+  titleForeground: TokenReference<'color'>;
+  /** Header subtitle line under the title. */
+  subtitleForeground: TokenReference<'color'>;
+  /** Default color for clear / close icon buttons when launcher overrides are unset. */
+  actionIconForeground: TokenReference<'color'>;
+  /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
+  shadow?: string;
+  /** Override the header bottom border (e.g., `none`). */
+  borderBottom?: string;
 }
 
 export interface MessageTokens {
@@ -317,6 +331,10 @@ export interface ArtifactToolbarTokens {
   copyMenuShadow?: string;
   copyMenuBorderRadius?: string;
   copyMenuItemHoverBackground?: string;
+  /** Base background of icon buttons (defaults to --persona-surface). */
+  iconBackground?: string;
+  /** Border on the toolbar (e.g., `none` to remove the bottom border). */
+  toolbarBorder?: string;
 }
 
 /** Artifact tab strip chrome. */
@@ -326,13 +344,62 @@ export interface ArtifactTabTokens {
   activeBorder?: string;
   borderRadius?: string;
   textColor?: string;
+  /** Hover background for inactive tabs. */
+  hoverBackground?: string;
+  /** Tab list container background. */
+  listBackground?: string;
+  /** Tab list container border color. */
+  listBorderColor?: string;
+  /** Tab list container padding (CSS shorthand). */
+  listPadding?: string;
 }
 
 /** Artifact pane chrome. */
 export interface ArtifactPaneTokens {
+  /**
+   * Background for the artifact column (toolbar + content), resolved from the theme.
+   * Defaults to `semantic.colors.container` so the pane matches assistant message surfaces.
+   * `features.artifacts.layout.paneBackground` still wins when set (layout escape hatch).
+   */
+  background?: string;
   toolbarBackground?: string;
 }
 
+/** Icon button chrome (used by createIconButton). */
+export interface IconButtonTokens {
+  background?: string;
+  border?: string;
+  color?: string;
+  padding?: string;
+  borderRadius?: string;
+  hoverBackground?: string;
+  hoverColor?: string;
+  /** Background when aria-pressed="true". */
+  activeBackground?: string;
+  /** Border color when aria-pressed="true". */
+  activeBorder?: string;
+}
+
+/** Label button chrome (used by createLabelButton). */
+export interface LabelButtonTokens {
+  background?: string;
+  border?: string;
+  color?: string;
+  padding?: string;
+  borderRadius?: string;
+  hoverBackground?: string;
+  fontSize?: string;
+  gap?: string;
+}
+
+/** Toggle group chrome (used by createToggleGroup). */
+export interface ToggleGroupTokens {
+  /** Gap between toggle buttons. Default: 0 (connected). */
+  gap?: string;
+  /** Border radius for first/last buttons. */
+  borderRadius?: string;
+}
+
 export interface ComponentTokens {
   button: ButtonTokens;
   input: InputTokens;
@@ -348,6 +415,12 @@ export interface ComponentTokens {
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
   composer: ComposerChromeTokens;
+  /** Icon button styling tokens. */
+  iconButton?: IconButtonTokens;
+  /** Label button styling tokens. */
+  labelButton?: LabelButtonTokens;
+  /** Toggle group styling tokens. */
+  toggleGroup?: ToggleGroupTokens;
   /** Artifact toolbar, tab strip, and pane chrome. */
   artifact?: {
     toolbar?: ArtifactToolbarTokens;
@@ -384,6 +457,9 @@ export type PersonaTheme = PersonaThemeBase &
   PersonaThemeSemantic & 
   PersonaThemeComponents;
 
+/** Recursive partial for `config.theme` / `config.darkTheme` overrides. */
+export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+
 export interface ResolvedToken {
   path: string;
   value: string;

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { AgentWidgetPlugin } from "./plugins/types";
+import type { DeepPartial, PersonaTheme } from "./types/theme";
 
 // ============================================================================
 // Multi-Modal Content Types
@@ -469,7 +470,9 @@ export type AgentWidgetArtifactsLayoutConfig = {
    */
   unifiedSplitOuterRadius?: string;
   /**
-   * Background color for the artifact column (CSS color). Sets `--persona-artifact-pane-bg` on the widget root.
+   * Strongest override: solid background for the artifact column (CSS color). Sets `--persona-artifact-pane-bg`
+   * on the widget root. Leave unset to use theme `components.artifact.pane.background` (defaults to semantic
+   * container) so light/dark stays consistent.
    */
   paneBackground?: string;
   /**
@@ -533,6 +536,20 @@ export type AgentWidgetArtifactsFeature = {
     type: 'open' | 'download';
     artifactId: string;
   }) => boolean | void;
+  /**
+   * Custom renderer for artifact reference cards shown in the message thread.
+   * Return an HTMLElement to replace the default card, or `null` to use the default.
+   */
+  renderCard?: (context: {
+    artifact: {
+      artifactId: string;
+      title: string;
+      artifactType: string;
+      status: string;
+    };
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+  }) => HTMLElement | null;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -667,85 +684,6 @@ export type EventStreamPayloadRenderContext = {
   parsedPayload: unknown;
 };
 
-export type AgentWidgetTheme = {
-  primary?: string;
-  secondary?: string;
-  surface?: string;
-  muted?: string;
-  accent?: string;
-  container?: string;
-  border?: string;
-  divider?: string;
-  messageBorder?: string;
-  inputBackground?: string;
-  callToAction?: string;
-  callToActionBackground?: string;
-  sendButtonBackgroundColor?: string;
-  sendButtonTextColor?: string;
-  sendButtonBorderColor?: string;
-  closeButtonColor?: string;
-  closeButtonBackgroundColor?: string;
-  closeButtonBorderColor?: string;
-  clearChatIconColor?: string;
-  clearChatBackgroundColor?: string;
-  clearChatBorderColor?: string;
-  tooltipBackground?: string;
-  tooltipForeground?: string;
-  micIconColor?: string;
-  micBackgroundColor?: string;
-  micBorderColor?: string;
-  recordingIconColor?: string;
-  recordingBackgroundColor?: string;
-  recordingBorderColor?: string;
-  inputFontFamily?: "sans-serif" | "serif" | "mono";
-  inputFontWeight?: string;
-  radiusSm?: string;
-  radiusMd?: string;
-  radiusLg?: string;
-  launcherRadius?: string;
-  buttonRadius?: string;
-  /**
-   * Border style for the chat panel container.
-   * @example "1px solid #e5e7eb" | "none"
-   * @default "1px solid var(--persona-border)"
-   */
-  panelBorder?: string;
-  /**
-   * Box shadow for the chat panel container.
-   * @example "0 25px 50px -12px rgba(0,0,0,0.25)" | "none"
-   * @default "0 25px 50px -12px rgba(0,0,0,0.25)"
-   */
-  panelShadow?: string;
-  /**
-   * Border radius for the chat panel container.
-   * @example "16px" | "0"
-   * @default "16px"
-   */
-  panelBorderRadius?: string;
-  /**
-   * Box-shadow for user message bubbles (bubble message layout).
-   * @example "none" | "0 1px 2px rgba(0,0,0,0.05)"
-   */
-  messageUserShadow?: string;
-  /**
-   * Box-shadow for assistant message bubbles (bubble message layout).
-   * Overrides the default subtle assistant shadow when set.
-   */
-  messageAssistantShadow?: string;
-  /**
-   * Box-shadow for tool-call / function-call rows.
-   */
-  toolBubbleShadow?: string;
-  /**
-   * Box-shadow for reasoning (“thinking”) rows.
-   */
-  reasoningBubbleShadow?: string;
-  /**
-   * Box-shadow on the composer (input) container.
-   */
-  composerShadow?: string;
-};
-
 export type AgentWidgetDockConfig = {
   /**
    * Side of the wrapped container where the docked panel should render.
@@ -758,10 +696,22 @@ export type AgentWidgetDockConfig = {
    */
   width?: string;
   /**
-   * Width of the collapsed launcher rail when the docked panel is closed.
-   * @default "72px"
+   * When false, the dock column snaps between `0` and `width` with no CSS transition so main
+   * content does not reflow during the open/close animation.
+   * @default true
+   */
+  animate?: boolean;
+  /**
+   * How the dock panel is shown.
+   * - `"resize"` (default): a flex column grows/shrinks between `0` and `width` (main content reflows).
+   * - `"overlay"`: panel is absolutely positioned and translates in/out **over** full-width content.
+   * - `"push"`: a wide inner track `[content at shell width][panel]` translates horizontally so the panel
+   *   appears to push the workspace aside **without** animating the content column width (Shopify-style).
+   * - `"emerge"`: like `"resize"`, the flex column animates so **page content reflows**; the chat
+   *   panel keeps a **fixed** `dock.width` (not squeezed while the column grows), clipped by the slot so
+   *   it appears to emerge at full width like a floating widget.
    */
-  collapsedWidth?: string;
+  reveal?: "resize" | "overlay" | "push" | "emerge";
 };
 
 export type AgentWidgetLauncherConfig = {
@@ -1396,6 +1346,17 @@ export type AgentWidgetHeaderTrailingAction = {
   icon?: string;
   label?: string;
   ariaLabel?: string;
+  /**
+   * When set, clicking this action opens a dropdown menu.
+   * Menu item selections fire `onAction(menuItemId)`.
+   */
+  menuItems?: Array<{
+    id: string;
+    label: string;
+    icon?: string;
+    destructive?: boolean;
+    dividerBefore?: boolean;
+  }>;
 };
 
 /**
@@ -1466,6 +1427,41 @@ export type AgentWidgetHeaderLayoutConfig = {
    * When set, the title row becomes visually interactive (cursor: pointer).
    */
   onTitleClick?: () => void;
+  /** Style config for the title row hover effect (minimal layout). */
+  titleRowHover?: {
+    /** Hover background color. */
+    background?: string;
+    /** Hover border color. */
+    border?: string;
+    /** Border radius for the pill shape. */
+    borderRadius?: string;
+    /** Padding inside the pill. */
+    padding?: string;
+  };
+  /**
+   * Replaces the title with a combo button (label + chevron + dropdown menu).
+   * When set, `trailingActions`, `onTitleClick`, and `titleRowHover` are ignored
+   * since the combo button handles all of these internally.
+   */
+  titleMenu?: {
+    /** Dropdown menu items. */
+    menuItems: Array<{
+      id: string;
+      label: string;
+      icon?: string;
+      destructive?: boolean;
+      dividerBefore?: boolean;
+    }>;
+    /** Called when a menu item is selected. */
+    onSelect: (id: string) => void;
+    /** Hover pill style. */
+    hover?: {
+      background?: string;
+      border?: string;
+      borderRadius?: string;
+      padding?: string;
+    };
+  };
 };
 
 /**
@@ -2256,22 +2252,15 @@ export type AgentWidgetConfig = {
      */
     showWelcomeCard?: boolean;
   };
-  theme?: AgentWidgetTheme;
   /**
-   * Theme colors for dark mode. Applied when dark mode is detected
-   * (when colorScheme is 'dark' or 'auto' with dark mode active).
-   * If not provided, falls back to `theme` colors.
-   * 
-   * @example
-   * ```typescript
-   * config: {
-   *   theme: { primary: '#111827', surface: '#ffffff' },
-   *   darkTheme: { primary: '#f9fafb', surface: '#1f2937' },
-   *   colorScheme: 'auto'
-   * }
-   * ```
+   * Semantic design tokens (`palette`, `semantic`, `components`).
+   * Omit for library defaults.
+   */
+  theme?: DeepPartial<PersonaTheme>;
+  /**
+   * Dark-mode token overrides. Merged over `theme` when the active scheme is dark.
    */
-  darkTheme?: AgentWidgetTheme;
+  darkTheme?: DeepPartial<PersonaTheme>;
   /**
    * Color scheme mode for the widget.
    * - 'light': Always use light theme (default)