@runtypelabs/persona 4.17.0 → 4.18.0

package/src/theme-editor/sections.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from "vitest";
 
-import { COMPONENTS_SECTIONS, CONFIGURE_SECTIONS, INTERFACE_ROLES_SECTION, STYLE_SECTIONS } from "./sections";
+import {
+  COMPONENT_COLOR_SECTIONS,
+  COMPONENT_SHAPE_SECTIONS,
+  COMPONENTS_SECTIONS,
+  CONFIGURE_SECTIONS,
+  INTERFACE_ROLES_SECTION,
+  STYLE_SECTIONS,
+} from "./sections";
 import { ALL_ROLES } from "./role-mappings";
 
 describe("theme editor scroll-to-bottom controls", () => {
@@ -93,6 +100,166 @@ describe("theme editor scroll-to-bottom controls", () => {
     );
   });
 
+  it("exposes the launcher icon stroke as a unitless slider", () => {
+    const section = COMPONENT_SHAPE_SECTIONS.find(
+      (entry) => entry.id === "comp-launcher"
+    );
+    const stroke = section?.fields.find(
+      (field) => field.path === "theme.components.launcher.iconStrokeWidth"
+    );
+
+    expect(stroke?.defaultValue).toBe("1.5");
+    // Unitless slider: the stroke must never pick up a px suffix, and the
+    // WebMCP escape hatch coerces sliders to raw numbers while token
+    // resolution only walks string values.
+    expect(stroke?.slider?.unit).toBe("none");
+    expect(stroke?.parseValue?.(1.5)).toBe("1.5");
+    expect(stroke?.parseValue?.("1.75")).toBe("1.75");
+  });
+
+  it("exposes the three shared header control knobs as live shape fields", () => {
+    const section = COMPONENT_SHAPE_SECTIONS.find(
+      (entry) => entry.id === "comp-header-controls"
+    );
+    const fieldsByPath = new Map(
+      section?.fields.map((field) => [field.path, field]) ?? []
+    );
+
+    const size = fieldsByPath.get("theme.components.header.controlSize");
+    const iconSize = fieldsByPath.get("theme.components.header.controlIconSize");
+    const stroke = fieldsByPath.get("theme.components.header.controlStrokeWidth");
+
+    expect(size?.defaultValue).toBe("32px");
+    expect(iconSize?.defaultValue).toBe("20px");
+    expect(stroke?.defaultValue).toBe("1.5");
+
+    // Unitless slider: the stroke must never pick up a px suffix.
+    expect(stroke?.slider?.unit).toBe("none");
+    expect(size?.slider?.unit).toBeUndefined();
+
+    // The WebMCP escape hatch coerces sliders to raw numbers, and token
+    // resolution only walks string values.
+    expect(size?.parseValue?.(44)).toBe("44px");
+    expect(size?.parseValue?.("2.5rem")).toBe("2.5rem");
+    expect(stroke?.parseValue?.(2)).toBe("2");
+    expect(stroke?.parseValue?.("1.75")).toBe("1.75");
+
+    // Sizes are not colors: light/dark scoping must never fork them.
+    expect(
+      COMPONENT_COLOR_SECTIONS.some((entry) => entry.id === "comp-header-controls")
+    ).toBe(false);
+  });
+
+  it("exposes the header and rail header band controls", () => {
+    const headerControls = COMPONENT_SHAPE_SECTIONS.find(
+      (entry) => entry.id === "comp-header-controls"
+    );
+    const minHeight = headerControls?.fields.find(
+      (field) => field.path === "theme.components.header.minHeight"
+    );
+    expect(minHeight?.type).toBe("text");
+    // Blank keeps the built-in auto height instead of writing an empty token.
+    expect(minHeight?.parseValue?.(" 65px ")).toBe("65px");
+    expect(minHeight?.parseValue?.("")).toBeUndefined();
+
+    const railShape = COMPONENT_SHAPE_SECTIONS.find(
+      (entry) => entry.id === "comp-history-rail-header"
+    );
+    const railPaths = railShape?.fields.map((field) => field.path) ?? [];
+    expect(railPaths).toEqual([
+      "theme.components.history.railHeader.minHeight",
+      "theme.components.history.railHeader.border",
+    ]);
+
+    const railColors = COMPONENT_COLOR_SECTIONS.find(
+      (entry) => entry.id === "comp-history-rail-header-colors"
+    );
+    const background = railColors?.fields.find(
+      (field) => field.path === "theme.components.history.railHeader.background"
+    );
+    expect(background?.type).toBe("token-ref");
+    expect(background?.tokenRef?.tokenType).toBe("color");
+
+    // Sizes are not colors: light/dark scoping must never fork them.
+    expect(
+      COMPONENT_COLOR_SECTIONS.some(
+        (entry) => entry.id === "comp-history-rail-header"
+      )
+    ).toBe(false);
+  });
+
+  it("exposes the floating rail surface controls", () => {
+    const shape = COMPONENT_SHAPE_SECTIONS.find(
+      (entry) => entry.id === "comp-history-overlay"
+    );
+    expect(shape?.fields.map((field) => field.path)).toEqual([
+      "theme.components.history.overlay.margin",
+      "theme.components.history.overlay.borderRadius",
+      "theme.components.history.overlay.shadow",
+    ]);
+    // Blank keeps the built-in default instead of writing an empty token.
+    const margin = shape?.fields[0];
+    expect(margin?.type).toBe("text");
+    expect(margin?.parseValue?.(" 12px ")).toBe("12px");
+    expect(margin?.parseValue?.("")).toBeUndefined();
+
+    const colors = COMPONENT_COLOR_SECTIONS.find(
+      (entry) => entry.id === "comp-history-overlay-colors"
+    );
+    const background = colors?.fields.find(
+      (field) => field.path === "theme.components.history.overlay.background"
+    );
+    expect(background?.type).toBe("token-ref");
+    expect(background?.tokenRef?.tokenType).toBe("color");
+
+    // Geometry is not color: the shape section never forks per light/dark.
+    expect(
+      COMPONENT_COLOR_SECTIONS.some((entry) => entry.id === "comp-history-overlay")
+    ).toBe(false);
+  });
+
+  it("exposes the tooltip shape and color controls", () => {
+    const shape = COMPONENT_SHAPE_SECTIONS.find(
+      (entry) => entry.id === "comp-tooltip"
+    );
+    const shapePaths = shape?.fields.map((field) => field.path) ?? [];
+    expect(shapePaths).toEqual([
+      "theme.components.tooltip.borderRadius",
+      "theme.components.tooltip.fontSize",
+      "theme.components.tooltip.arrow",
+    ]);
+
+    const fontSize = shape?.fields.find(
+      (field) => field.path === "theme.components.tooltip.fontSize"
+    );
+    // Blank keeps the built-in 12px instead of writing an empty token.
+    expect(fontSize?.parseValue?.(" 13px ")).toBe("13px");
+    expect(fontSize?.parseValue?.("")).toBeUndefined();
+
+    const arrow = shape?.fields.find(
+      (field) => field.path === "theme.components.tooltip.arrow"
+    );
+    expect(arrow?.type).toBe("toggle");
+    expect(arrow?.defaultValue).toBe(true);
+
+    const colors = COMPONENT_COLOR_SECTIONS.find(
+      (entry) => entry.id === "comp-tooltip-colors"
+    );
+    expect(colors?.fields.map((field) => field.path)).toEqual([
+      "theme.components.tooltip.background",
+      "theme.components.tooltip.foreground",
+      "theme.components.tooltip.hintForeground",
+    ]);
+    expect(
+      colors?.fields.every((field) => field.tokenRef?.tokenType === "color")
+    ).toBe(true);
+
+    // Sizes are not colors: light/dark scoping must never fork them.
+    expect(
+      COMPONENT_COLOR_SECTIONS.some((entry) => entry.id === "comp-tooltip")
+    ).toBe(false);
+  });
+
   it("exposes a shadow control for every themeable component", () => {
     const fieldPaths = COMPONENTS_SECTIONS.flatMap((section) => section.fields.map((field) => field.path));
 

package/src/theme-editor/sections.ts

@@ -27,6 +27,13 @@ const parseOptionalCssValue = (value: unknown): string | undefined => {
   return normalized || undefined;
 };
 
+// Slider controls emit CSS strings, but the WebMCP escape hatch coerces a
+// slider to a raw number and token resolution only walks string values.
+const parseSliderPxLength = (value: unknown): string =>
+  typeof value === 'number' ? `${value}px` : String(value ?? '').trim();
+
+const parseSliderUnitless = (value: unknown): string => String(value ?? '').trim();
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // STYLE TAB: brand colors, chat colors, typography, shape, etc.
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -72,11 +79,12 @@ const chatColorsSectionDef: SectionDef = {
   collapsed: true,
   fields: [
     { id: 'chat-header-bg', label: 'Header Background', type: 'token-ref', path: 'theme.components.header.background', defaultValue: 'semantic.colors.surface', tokenRef: { tokenType: 'color' } },
+    { id: 'chat-header-fg', label: 'Header Foreground', description: 'Anchors the header text. The title takes it, the subtitle and button icons take a 72% mix of it over the background', type: 'token-ref', path: 'theme.components.header.foreground', defaultValue: '', tokenRef: { tokenType: 'color' } },
     { id: 'chat-header-icon-bg', label: 'Header Icon Background', type: 'token-ref', path: 'theme.components.header.iconBackground', defaultValue: 'semantic.colors.primary', tokenRef: { tokenType: 'color' } },
     { id: 'chat-header-icon-fg', label: 'Header Icon Color', type: 'token-ref', path: 'theme.components.header.iconForeground', defaultValue: 'semantic.colors.textInverse', tokenRef: { tokenType: 'color' } },
-    { id: 'chat-header-title-fg', label: 'Header Title Color', type: 'token-ref', path: 'theme.components.header.titleForeground', defaultValue: 'semantic.colors.primary', tokenRef: { tokenType: 'color' } },
-    { id: 'chat-header-subtitle-fg', label: 'Header Subtitle Color', type: 'token-ref', path: 'theme.components.header.subtitleForeground', defaultValue: 'semantic.colors.textMuted', tokenRef: { tokenType: 'color' } },
-    { id: 'chat-header-action-icons-fg', label: 'Header Button Icons', type: 'token-ref', path: 'theme.components.header.actionIconForeground', defaultValue: 'semantic.colors.textMuted', tokenRef: { tokenType: 'color' } },
+    { id: 'chat-header-title-fg', label: 'Header Title Color', description: 'Blank follows the header foreground', type: 'token-ref', path: 'theme.components.header.titleForeground', defaultValue: '', tokenRef: { tokenType: 'color' } },
+    { id: 'chat-header-subtitle-fg', label: 'Header Subtitle Color', description: 'Blank follows the 72% foreground mix', type: 'token-ref', path: 'theme.components.header.subtitleForeground', defaultValue: '', tokenRef: { tokenType: 'color' } },
+    { id: 'chat-header-action-icons-fg', label: 'Header Button Icons', description: 'Blank follows the 72% foreground mix', type: 'token-ref', path: 'theme.components.header.actionIconForeground', defaultValue: '', tokenRef: { tokenType: 'color' } },
     { id: 'chat-msg-user-bg', label: 'User Message Background', type: 'token-ref', path: 'theme.components.message.user.background', defaultValue: 'semantic.colors.primary', tokenRef: { tokenType: 'color' } },
     { id: 'chat-msg-user-text', label: 'User Message Text', type: 'token-ref', path: 'theme.components.message.user.text', defaultValue: 'semantic.colors.textInverse', tokenRef: { tokenType: 'color' } },
     { id: 'chat-msg-assistant-bg', label: 'Assistant Message Background', type: 'token-ref', path: 'theme.components.message.assistant.background', defaultValue: 'semantic.colors.container', tokenRef: { tokenType: 'color' } },
@@ -316,6 +324,7 @@ const launcherLayoutSectionDef: SectionDef = {
   fields: [
     { id: 'launcher-size', label: 'Size', type: 'slider', path: 'theme.components.launcher.size', defaultValue: '60px', slider: { min: 32, max: 80, step: 2 } },
     { id: 'launcher-icon-size', label: 'Icon Size', type: 'slider', path: 'theme.components.launcher.iconSize', defaultValue: '28px', slider: { min: 16, max: 48, step: 2 } },
+    { id: 'launcher-icon-stroke-width', label: 'Icon Stroke Width', description: 'Unitless line weight for the agent glyph and the call-to-action arrow', type: 'slider', path: 'theme.components.launcher.iconStrokeWidth', defaultValue: '1.5', slider: { min: 1, max: 2.5, step: 0.25, unit: 'none' }, parseValue: parseSliderUnitless },
     { id: 'launcher-border-radius', label: 'Border Radius', type: 'select', path: 'theme.components.launcher.borderRadius', defaultValue: 'palette.radius.full', options: [
       { value: 'palette.radius.md', label: 'Medium' },
       { value: 'palette.radius.lg', label: 'Large' },
@@ -332,6 +341,115 @@ const launcherLayoutSectionDef: SectionDef = {
   ],
 };
 
+const headerControlsSectionDef: SectionDef = {
+  id: 'comp-header-controls',
+  title: 'Header Controls',
+  description:
+    'One box, glyph, and stroke shared by every header icon button: close, clear chat, trailing actions, and Messages, plus the strip height.',
+  collapsed: true,
+  fields: [
+    { id: 'header-min-height', label: 'Header Min Height', description: 'CSS length, e.g. 65px. Blank stays at the natural height', type: 'text', path: 'theme.components.header.minHeight', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'header-control-size', label: 'Control Size', description: 'The button box. Coarse pointers still floor the hit area at 40px', type: 'slider', path: 'theme.components.header.controlSize', defaultValue: '32px', slider: { min: 24, max: 64, step: 2 }, parseValue: parseSliderPxLength },
+    { id: 'header-control-icon-size', label: 'Icon Size', description: 'The glyph inside the button', type: 'slider', path: 'theme.components.header.controlIconSize', defaultValue: '20px', slider: { min: 12, max: 40, step: 1 }, parseValue: parseSliderPxLength },
+    { id: 'header-control-stroke-width', label: 'Icon Stroke Width', description: 'Unitless line weight. The close X renders at 0.7 of it so its sparser glyph matches', type: 'slider', path: 'theme.components.header.controlStrokeWidth', defaultValue: '1.5', slider: { min: 1, max: 2.5, step: 0.25, unit: 'none' }, parseValue: parseSliderUnitless },
+  ],
+};
+
+// The Messages rail's own top strip, beside the widget header in rail
+// presentation. Its color lives in COMPONENT_COLOR_SECTIONS.
+const historyRailHeaderShapeSectionDef: SectionDef = {
+  id: 'comp-history-rail-header',
+  title: 'Messages Rail Header',
+  description:
+    'The Messages rail top strip. Match its height to the header so both read as one band.',
+  collapsed: true,
+  fields: [
+    { id: 'rail-header-min-height', label: 'Min Height', description: 'CSS length. Blank follows the header min height', type: 'text', path: 'theme.components.history.railHeader.minHeight', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'rail-header-border', label: 'Bottom Border', description: 'Full border-bottom shorthand, e.g. 1px solid #333', type: 'text', path: 'theme.components.history.railHeader.border', defaultValue: '', parseValue: parseOptionalCssValue },
+  ],
+};
+
+const historyRailHeaderColorsSectionDef: SectionDef = {
+  id: 'comp-history-rail-header-colors',
+  title: 'Messages Rail Header Colors',
+  collapsed: true,
+  fields: [
+    { id: 'rail-header-bg', label: 'Background', type: 'token-ref', path: 'theme.components.history.railHeader.background', defaultValue: 'semantic.colors.container', tokenRef: { tokenType: 'color' } },
+  ],
+};
+
+// The floating rail a collapsed overlay rail opens on hover. Its width and
+// edge stay features.history.rail config; only the surface is themeable.
+const historyOverlayShapeSectionDef: SectionDef = {
+  id: 'comp-history-overlay',
+  title: 'Messages Floating Rail',
+  description:
+    'The Messages rail floating over the conversation, when a collapsed rail opens on hover.',
+  collapsed: true,
+  fields: [
+    { id: 'history-overlay-margin', label: 'Margin', description: 'Gap from the trigger, the docked edge and the bottom', type: 'text', path: 'theme.components.history.overlay.margin', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'history-overlay-radius', label: 'Corner Radius', description: 'CSS length on all four corners. Blank keeps 16px', type: 'text', path: 'theme.components.history.overlay.borderRadius', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'history-overlay-shadow', label: 'Shadow', description: 'Full box-shadow shorthand. Blank keeps the built-in elevation', type: 'text', path: 'theme.components.history.overlay.shadow', defaultValue: '', parseValue: parseOptionalCssValue },
+  ],
+};
+
+const historyOverlayColorsSectionDef: SectionDef = {
+  id: 'comp-history-overlay-colors',
+  title: 'Messages Floating Rail Colors',
+  collapsed: true,
+  fields: [
+    { id: 'history-overlay-bg', label: 'Background', type: 'token-ref', path: 'theme.components.history.overlay.background', defaultValue: 'semantic.colors.container', tokenRef: { tokenType: 'color' } },
+  ],
+};
+
+// Enter/exit motion of the Messages surface. Durations, not colors, so it
+// stays a shape section and never forks per scheme.
+const historyMotionSectionDef: SectionDef = {
+  id: 'comp-history-motion',
+  title: 'Messages Motion',
+  description:
+    'Enter and exit animation of the Messages body. The bar is persistent chrome and never animates; reduced-motion preferences always win.',
+  collapsed: true,
+  fields: [
+    { id: 'history-motion-enter-ms', label: 'Enter Duration', description: 'Milliseconds, e.g. 180. 0 disables the entrance. Blank keeps 180', type: 'text', path: 'theme.components.history.motion.enterDurationMs', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'history-motion-enter-easing', label: 'Enter Easing', description: 'CSS easing, e.g. ease-out or cubic-bezier(0, 0, 0.2, 1)', type: 'text', path: 'theme.components.history.motion.enterEasing', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'history-motion-exit-ms', label: 'Exit Duration', description: 'Milliseconds, e.g. 160. 0 disables the exit. Blank keeps 160', type: 'text', path: 'theme.components.history.motion.exitDurationMs', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'history-motion-exit-easing', label: 'Exit Easing', description: 'CSS easing, e.g. ease-in or cubic-bezier(0.4, 0, 1, 1)', type: 'text', path: 'theme.components.history.motion.exitEasing', defaultValue: '', parseValue: parseOptionalCssValue },
+  ],
+};
+
+// The portaled tooltip on icon controls. Its colors live in
+// COMPONENT_COLOR_SECTIONS.
+const tooltipShapeSectionDef: SectionDef = {
+  id: 'comp-tooltip',
+  title: 'Tooltip',
+  description:
+    'The hover and focus tooltip on icon controls, including its shortcut hint chip.',
+  collapsed: true,
+  fields: [
+    { id: 'tooltip-radius', label: 'Corner Radius', type: 'select', path: 'theme.components.tooltip.borderRadius', defaultValue: 'palette.radius.sm', options: [
+      { value: 'palette.radius.none', label: 'None' },
+      { value: 'palette.radius.sm', label: 'Small' },
+      { value: 'palette.radius.md', label: 'Medium' },
+      { value: 'palette.radius.lg', label: 'Large' },
+      { value: 'palette.radius.xl', label: 'Extra Large' },
+    ] },
+    { id: 'tooltip-font-size', label: 'Font Size', description: 'CSS length. Blank stays at 12px', type: 'text', path: 'theme.components.tooltip.fontSize', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'tooltip-arrow', label: 'Show Arrow', description: 'The caret pointing at the control', type: 'toggle', path: 'theme.components.tooltip.arrow', defaultValue: true },
+  ],
+};
+
+const tooltipColorsSectionDef: SectionDef = {
+  id: 'comp-tooltip-colors',
+  title: 'Tooltip Colors',
+  collapsed: true,
+  fields: [
+    { id: 'tooltip-bg', label: 'Background', type: 'token-ref', path: 'theme.components.tooltip.background', defaultValue: 'palette.colors.gray.900', tokenRef: { tokenType: 'color' } },
+    { id: 'tooltip-fg', label: 'Label', type: 'token-ref', path: 'theme.components.tooltip.foreground', defaultValue: 'palette.colors.primary.50', tokenRef: { tokenType: 'color' } },
+    { id: 'tooltip-hint-fg', label: 'Shortcut Hint', type: 'token-ref', path: 'theme.components.tooltip.hintForeground', defaultValue: 'palette.colors.gray.400', tokenRef: { tokenType: 'color' } },
+  ],
+};
+
 const messageShapeSectionDef: SectionDef = {
   id: 'comp-message-shape',
   title: 'Message Shape',
@@ -401,12 +519,13 @@ const headerColorsSectionDef: SectionDef = {
   collapsed: true,
   fields: [
     { id: 'header-bg', label: 'Background', type: 'token-ref', path: 'theme.components.header.background', defaultValue: 'semantic.colors.surface', tokenRef: { tokenType: 'color' } },
+    { id: 'header-fg', label: 'Foreground', description: 'Anchors the header text. Background and foreground together derive every color left blank below', type: 'token-ref', path: 'theme.components.header.foreground', defaultValue: '', tokenRef: { tokenType: 'color' } },
     { id: 'header-icon-bg', label: 'Icon background', type: 'token-ref', path: 'theme.components.header.iconBackground', defaultValue: 'semantic.colors.primary', tokenRef: { tokenType: 'color' } },
     { id: 'header-icon-fg', label: 'Icon color', type: 'token-ref', path: 'theme.components.header.iconForeground', defaultValue: 'semantic.colors.textInverse', tokenRef: { tokenType: 'color' } },
-    { id: 'header-title-fg', label: 'Title color', type: 'token-ref', path: 'theme.components.header.titleForeground', defaultValue: 'semantic.colors.primary', tokenRef: { tokenType: 'color' } },
-    { id: 'header-subtitle-fg', label: 'Subtitle color', type: 'token-ref', path: 'theme.components.header.subtitleForeground', defaultValue: 'semantic.colors.textMuted', tokenRef: { tokenType: 'color' } },
-    { id: 'header-action-icons-fg', label: 'Clear / close icons', type: 'token-ref', path: 'theme.components.header.actionIconForeground', defaultValue: 'semantic.colors.textMuted', tokenRef: { tokenType: 'color' } },
-    { id: 'header-border', label: 'Border', type: 'token-ref', path: 'theme.components.header.border', defaultValue: 'semantic.colors.border', tokenRef: { tokenType: 'color' } },
+    { id: 'header-title-fg', label: 'Title color', description: 'Blank follows the header foreground', type: 'token-ref', path: 'theme.components.header.titleForeground', defaultValue: '', tokenRef: { tokenType: 'color' } },
+    { id: 'header-subtitle-fg', label: 'Subtitle color', description: 'Blank follows a 72% mix of the foreground over the background', type: 'token-ref', path: 'theme.components.header.subtitleForeground', defaultValue: '', tokenRef: { tokenType: 'color' } },
+    { id: 'header-action-icons-fg', label: 'Clear / close icons', description: 'Blank follows the same 72% foreground mix as the subtitle', type: 'token-ref', path: 'theme.components.header.actionIconForeground', defaultValue: '', tokenRef: { tokenType: 'color' } },
+    { id: 'header-border', label: 'Border', description: 'Blank follows a 14% mix of the foreground over the background', type: 'token-ref', path: 'theme.components.header.border', defaultValue: '', tokenRef: { tokenType: 'color' } },
   ],
 };
 
@@ -566,6 +685,13 @@ const textStylesSectionDef: SectionDef = {
 export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   panelLayoutSectionDef,
   launcherLayoutSectionDef,
+  // Sizes, not colors: kept out of COMPONENT_COLOR_SECTIONS so scopeSection
+  // never forks them per light/dark.
+  headerControlsSectionDef,
+  historyRailHeaderShapeSectionDef,
+  historyOverlayShapeSectionDef,
+  historyMotionSectionDef,
+  tooltipShapeSectionDef,
   messageShapeSectionDef,
   inputShapeSectionDef,
   composerSpacingSectionDef,
@@ -577,6 +703,9 @@ export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
 /** Component color sections (can be scoped for light/dark) */
 export const COMPONENT_COLOR_SECTIONS: SectionDef[] = [
   headerColorsSectionDef,
+  historyRailHeaderColorsSectionDef,
+  historyOverlayColorsSectionDef,
+  tooltipColorsSectionDef,
   messageColorsSectionDef,
   inputColorsSectionDef,
   buttonColorsSectionDef,

package/src/theme-editor/webmcp/summary.ts

@@ -163,13 +163,15 @@ export interface ContrastPair {
   key: string;
   label: string;
   fg: string;
+  /** Tried in order when `fg` is unset; suggestions still write to `fg`. */
+  fgFallbacks?: string[];
   bg: string;
 }
 
 export const CONTRAST_PAIRS: ContrastPair[] = [
   { key: 'user-message', label: 'User message text', fg: 'components.message.user.text', bg: 'components.message.user.background' },
   { key: 'assistant-message', label: 'Assistant message text', fg: 'components.message.assistant.text', bg: 'components.message.assistant.background' },
-  { key: 'header', label: 'Header title', fg: 'components.header.titleForeground', bg: 'components.header.background' },
+  { key: 'header', label: 'Header title', fg: 'components.header.titleForeground', fgFallbacks: ['components.header.foreground'], bg: 'components.header.background' },
   { key: 'primary-button', label: 'Primary button label', fg: 'components.button.primary.foreground', bg: 'components.button.primary.background' },
   { key: 'input', label: 'Input placeholder', fg: 'components.input.placeholder', bg: 'components.input.background' },
   { key: 'link', label: 'Link text', fg: 'components.markdown.link.foreground', bg: 'semantic.colors.background' },
@@ -178,6 +180,18 @@ export const CONTRAST_PAIRS: ContrastPair[] = [
   { key: 'surface', label: 'Body text on surface', fg: 'semantic.colors.text', bg: 'semantic.colors.surface' },
 ];
 
+function resolveContrastForeground(
+  state: ThemeEditorLike,
+  pair: ContrastPair,
+  prefix: 'theme' | 'darkTheme'
+): string | null {
+  for (const path of [pair.fg, ...(pair.fgFallbacks ?? [])]) {
+    const color = resolveColor(state, path, prefix);
+    if (color) return color;
+  }
+  return null;
+}
+
 /**
  * The contrast-pair keys relevant to a role, derived by intersecting the role's
  * target token paths with the contrast pairs. This replaces a hand-maintained
@@ -275,7 +289,7 @@ export function runContrastChecks(
   for (const v of variants) {
     const prefix = v === 'light' ? 'theme' : 'darkTheme';
     for (const pair of pairs) {
-      const fg = resolveColor(state, pair.fg, prefix);
+      const fg = resolveContrastForeground(state, pair, prefix);
       const bg = resolveColor(state, pair.bg, prefix);
       if (!fg || !bg) continue;
       const ratio = round2(wcagContrastRatio(fg, bg));

package/src/theme-reference.ts

@@ -110,7 +110,8 @@ export const THEME_TOKEN_DOCS = {
       },
       launcher: {
         description: 'Floating launcher button.',
-        properties: 'size (60px), iconSize (28px), borderRadius, shadow.',
+        properties:
+          'size (60px), iconSize (28px), iconStrokeWidth (2, unitless glyph stroke weight; applies to registry-icon launchers, inert for emoji and image icons), borderRadius, shadow.',
       },
       panel: {
         description: 'Chat panel container.',
@@ -118,11 +119,24 @@ export const THEME_TOKEN_DOCS = {
           'width, maxWidth (440px), height (600px), maxHeight, borderRadius, shadow, inset (16px, gap around a detached panel), canvasBackground (transparent, fills the region behind a detached panel in docked and inline embed modes; a no-op in sidebar mode, where the gap stays click-through and the host page shows through like floating). inset and canvasBackground apply only when launcher.detachedPanel is true or artifacts.layout.paneAppearance is "detached".',
       },
       header: {
-        description: 'Chat panel header.',
+        description:
+          'Chat panel header. background and foreground are the pair that colors the band: set those two and the rest of the header text follows.',
         properties:
-          'background, border, borderRadius, padding, iconBackground, iconForeground, actionIconForeground, shadow, borderBottom, title and subtitle (each fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, color).',
+          'background, foreground (anchors the header text; the title takes it directly, the subtitle and action icons take color-mix(in srgb, foreground 72%, background), and the border takes color-mix(in srgb, foreground 14%, background)), border, borderRadius, padding, iconBackground, iconForeground (the avatar tile, which keeps its own defaults and never derives), actionIconForeground, controlSize (32px, the box of every header icon button), controlIconSize (20px, the glyph inside it), controlStrokeWidth (1.5, unitless glyph stroke weight; sparse-viewBox glyphs such as the close X scale it by 0.7), shadow, borderBottom, minHeight (height floor for the header strip), title and subtitle (each fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, color). Derivation only fills keys the theme leaves unset, so any explicit border, titleForeground, subtitleForeground, actionIconForeground, title.color, or subtitle.color wins. With no foreground either, each key falls back as before: the primary color for the title, the muted text color for the subtitle and action icons, the divider color for the border.',
         legacy:
-          'titleForeground and subtitleForeground are legacy aliases of header.title.color and header.subtitle.color. Both still work; the title/subtitle color wins when both are set.',
+          'titleForeground and subtitleForeground are legacy aliases of header.title.color and header.subtitle.color. Both still work; the title/subtitle color wins when both are set, and either alias still outranks the foreground derivation.',
+      },
+      history: {
+        description:
+          'Messages (conversation history) chrome and motion. railHeader styles the rail sidebar top strip, which runs beside the widget header in rail presentation; overlay styles the floating rail a collapsed overlay rail opens on hover; motion times the surface entering and leaving.',
+        properties:
+          'railHeader.background (defaults to the rail surface), railHeader.border (full border-bottom shorthand, default 0), railHeader.minHeight (defaults to components.header.minHeight, then 56px). Pin railHeader.minHeight and header.minHeight to the same value so both top strips read as one band. railHeader.title takes TextStyleTokens for the strip view title ("Messages"): color (defaults to the text color; the sidebar identity reads at full strength), fontFamily, fontSize (14px), fontWeight (600), lineHeight, letterSpacing. listHeading takes the same TextStyleTokens for the rail-only "Conversations" heading over the list block (14px/600 in the text color); groupHeading styles the muted sub-headers, both the date groups ("Today", "Yesterday") and rail nav section titles (rail 13px/500, muted text color). Every key of all three is pinned in the widget CSS, so host-page h2/h3 rules cannot restyle them. overlay.margin (8px, the gap from the trigger, the docked edge and the bottom), overlay.borderRadius (16px), overlay.shadow (0 12px 40px rgba(0, 0, 0, 0.25)), overlay.background (defaults to the rail surface). The floating rail keeps features.history.rail width and side, which are config, not tokens. motion.enterDurationMs (180) and motion.exitDurationMs (160) are bare millisecond numbers, 0 disables that leg; motion.enterEasing (cubic-bezier(0, 0, 0.2, 1)) and motion.exitEasing (cubic-bezier(0.4, 0, 1, 1)) take any CSS easing. Only the body animates, and prefers-reduced-motion always wins.',
+      },
+      tooltip: {
+        description:
+          'The portaled tooltip on icon controls, plus the muted shortcut hint chip after its label.',
+        properties:
+          'background (#111827), foreground (#ffffff), hintForeground (rgba(255, 255, 255, 0.55)), borderRadius (palette.radius.sm), fontSize (12px), padding (6px 12px), shadow, maxWidth (min(320px, calc(100vw - 16px))), arrow (boolean, default true; false drops the caret). Unset keys keep the built-in dark look.',
       },
       message: {
         description: 'Chat message bubbles.',
@@ -211,12 +225,12 @@ export const THEME_TOKEN_DOCS = {
         'backgroundColor, textColor, borderWidth, borderColor, paddingX, paddingY, iconText, iconName, size.',
     },
     closeButton: {
-      description: 'Close button (on launcher config).',
+      description: 'Close button (on launcher config). Unset closeButtonSize means theme.components.header.controlSize owns the box.',
       properties:
         'closeButtonSize, closeButtonColor, closeButtonBackgroundColor, closeButtonBorderWidth, closeButtonBorderColor, closeButtonBorderRadius.',
     },
     clearChat: {
-      description: 'Clear chat button (on launcher.clearChat config).',
+      description: 'Clear chat button (on launcher.clearChat config). Unset size means theme.components.header.controlSize owns the box.',
       properties:
         'enabled, iconColor, backgroundColor, borderWidth, borderColor, borderRadius, size.',
     },