@runtypelabs/persona 3.5.2 → 3.7.0

package/src/theme-editor/state.ts

@@ -0,0 +1,298 @@
+/** Headless state management for the theme editor (no DOM, no localStorage, no side effects) */
+
+import type { AgentWidgetConfig } from '../types';
+import type { PersonaTheme } from '../types/theme';
+import { createTheme } from '../utils/theme';
+import { DEFAULT_WIDGET_CONFIG } from '../defaults';
+import type { ConfiguratorSnapshot, ConfigChangeListener } from './types';
+
+// ─── Dot-path utilities ─────────────────────────────────────────
+
+function getByPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === undefined || current === null) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function setByPath(obj: unknown, path: string, value: unknown): unknown {
+  const parts = path.split('.');
+  if (parts.length === 1) {
+    return { ...(obj as Record<string, unknown>), [parts[0]]: value };
+  }
+
+  const [first, ...rest] = parts;
+  const current = obj as Record<string, unknown>;
+  return {
+    ...current,
+    [first]: setByPath(current?.[first] ?? {}, rest.join('.'), value),
+  };
+}
+
+// ─── ThemeEditorState ───────────────────────────────────────────
+
+export class ThemeEditorState {
+  private config: AgentWidgetConfig;
+  private theme: PersonaTheme;
+  private listeners: ConfigChangeListener[] = [];
+  private history: ConfiguratorSnapshot[] = [];
+  private historyIndex = -1;
+  private suppressHistory = false;
+
+  constructor(
+    initialTheme?: Partial<PersonaTheme>,
+    initialConfig?: Partial<AgentWidgetConfig>,
+    options?: { mergeDefaults?: boolean }
+  ) {
+    const mergeDefaults = options?.mergeDefaults ?? true;
+    this.config = (mergeDefaults
+      ? { ...DEFAULT_WIDGET_CONFIG, ...initialConfig }
+      : (initialConfig ?? DEFAULT_WIDGET_CONFIG)
+    ) as AgentWidgetConfig;
+    this.theme = createTheme(initialTheme, { validate: false });
+    this.syncThemeIntoConfig();
+    this.pushHistorySnapshot(this.exportSnapshot(), true);
+  }
+
+  // ─── Read ───────────────────────────────────────────────────
+
+  /**
+   * Get a value using a dot-path.
+   * - `theme.*` → reads from the PersonaTheme
+   * - `darkTheme.*` → reads from config.darkTheme
+   * - everything else → reads from the AgentWidgetConfig
+   */
+  get(path: string): unknown {
+    if (path.startsWith('theme.')) {
+      return getByPath(this.theme, path.replace('theme.', ''));
+    }
+    if (path.startsWith('darkTheme.')) {
+      return getByPath(this.config.darkTheme ?? {}, path.replace('darkTheme.', ''));
+    }
+    return getByPath(this.config, path);
+  }
+
+  getTheme(): PersonaTheme {
+    return this.theme;
+  }
+
+  getConfig(): AgentWidgetConfig {
+    return this.config;
+  }
+
+  // ─── Write ──────────────────────────────────────────────────
+
+  /**
+   * Set a value using a dot-path.
+   * - `theme.*` → writes into the PersonaTheme
+   * - `darkTheme.*` → writes into config.darkTheme
+   * - everything else → writes into AgentWidgetConfig
+   */
+  set(path: string, value: unknown): void {
+    if (path.startsWith('theme.')) {
+      const themePath = path.replace('theme.', '');
+      this.theme = setByPath(this.theme, themePath, value) as PersonaTheme;
+      this.syncThemeIntoConfig();
+    } else if (path.startsWith('darkTheme.')) {
+      const themePath = path.replace('darkTheme.', '');
+      const dark = this.config.darkTheme ?? createTheme();
+      this.config = {
+        ...this.config,
+        darkTheme: setByPath(dark, themePath, value) as AgentWidgetConfig['darkTheme'],
+      };
+    } else {
+      this.config = setByPath(this.config, path, value) as AgentWidgetConfig;
+    }
+
+    this.recordHistory();
+    this.notifyListeners();
+  }
+
+  /** Batch-set multiple paths at once */
+  setBatch(updates: Record<string, unknown>): void {
+    let themeChanged = false;
+    let darkThemeChanged = false;
+    let configChanged = false;
+
+    for (const [path, value] of Object.entries(updates)) {
+      if (path.startsWith('theme.')) {
+        const themePath = path.replace('theme.', '');
+        this.theme = setByPath(this.theme, themePath, value) as PersonaTheme;
+        themeChanged = true;
+      } else if (path.startsWith('darkTheme.')) {
+        const themePath = path.replace('darkTheme.', '');
+        const dark = this.config.darkTheme ?? createTheme();
+        this.config = {
+          ...this.config,
+          darkTheme: setByPath(dark, themePath, value) as AgentWidgetConfig['darkTheme'],
+        };
+        darkThemeChanged = true;
+      } else {
+        this.config = setByPath(this.config, path, value) as AgentWidgetConfig;
+        configChanged = true;
+      }
+    }
+
+    if (themeChanged) {
+      this.syncThemeIntoConfig();
+    }
+    if (themeChanged || darkThemeChanged || configChanged) {
+      this.recordHistory();
+      this.notifyListeners();
+    }
+  }
+
+  /** Replace the entire theme */
+  setTheme(theme: PersonaTheme): void {
+    this.theme = theme;
+    this.syncThemeIntoConfig();
+    this.recordHistory();
+    this.notifyListeners();
+  }
+
+  /** Replace the entire config (for preset loading) */
+  setFullConfig(config: AgentWidgetConfig, theme?: PersonaTheme): void {
+    this.config = { ...config };
+    if (theme) {
+      this.theme = theme;
+    }
+    this.syncThemeIntoConfig();
+    this.recordHistory();
+    this.notifyListeners();
+  }
+
+  /** Import a snapshot (v2 or raw theme) */
+  importSnapshot(snapshot: unknown): void {
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+      throw new Error('Snapshot must be a JSON object');
+    }
+
+    const parsed = snapshot as Partial<ConfiguratorSnapshot> & { config?: unknown; theme?: unknown };
+
+    if ('config' in parsed || 'theme' in parsed || parsed.version === 2) {
+      const config = (parsed.config ?? this.config) as AgentWidgetConfig;
+      const theme = createTheme(
+        (parsed.theme ?? this.theme) as Partial<PersonaTheme>,
+        { validate: false }
+      );
+      this.setFullConfig(config, theme);
+      return;
+    }
+
+    const theme = createTheme(parsed as Partial<PersonaTheme>, { validate: false });
+    this.setTheme(theme);
+  }
+
+  /** Reset to defaults */
+  resetToDefaults(): void {
+    this.config = { ...DEFAULT_WIDGET_CONFIG } as AgentWidgetConfig;
+    this.theme = createTheme();
+    this.syncThemeIntoConfig();
+    this.history = [];
+    this.historyIndex = -1;
+    this.pushHistorySnapshot(this.exportSnapshot());
+    this.notifyListeners();
+  }
+
+  // ─── History ────────────────────────────────────────────────
+
+  canUndo(): boolean {
+    return this.historyIndex > 0;
+  }
+
+  canRedo(): boolean {
+    return this.historyIndex >= 0 && this.historyIndex < this.history.length - 1;
+  }
+
+  getHistoryLength(): number {
+    return this.history.length;
+  }
+
+  getHistoryIndex(): number {
+    return this.historyIndex;
+  }
+
+  undo(): void {
+    if (!this.canUndo()) return;
+    this.historyIndex -= 1;
+    this.restoreSnapshot(this.history[this.historyIndex]);
+  }
+
+  redo(): void {
+    if (!this.canRedo()) return;
+    this.historyIndex += 1;
+    this.restoreSnapshot(this.history[this.historyIndex]);
+  }
+
+  // ─── Snapshots ──────────────────────────────────────────────
+
+  exportSnapshot(): ConfiguratorSnapshot {
+    return {
+      version: 2,
+      config: { ...this.config, theme: undefined } as unknown as Record<string, unknown>,
+      theme: this.theme,
+    };
+  }
+
+  // ─── Listeners ──────────────────────────────────────────────
+
+  onChange(listener: ConfigChangeListener): () => void {
+    this.listeners.push(listener);
+    return () => {
+      const idx = this.listeners.indexOf(listener);
+      if (idx >= 0) this.listeners.splice(idx, 1);
+    };
+  }
+
+  // ─── Private ────────────────────────────────────────────────
+
+  private syncThemeIntoConfig(): void {
+    this.config = {
+      ...this.config,
+      theme: this.theme,
+    };
+  }
+
+  private notifyListeners(): void {
+    for (const listener of this.listeners) {
+      listener(this.config, this.theme);
+    }
+  }
+
+  private recordHistory(): void {
+    this.pushHistorySnapshot(this.exportSnapshot());
+  }
+
+  private pushHistorySnapshot(snapshot: ConfiguratorSnapshot, replaceCurrent = false): void {
+    if (this.suppressHistory) return;
+
+    const serialized = JSON.stringify(snapshot);
+    const currentSerialized =
+      this.historyIndex >= 0 && this.history[this.historyIndex]
+        ? JSON.stringify(this.history[this.historyIndex])
+        : null;
+
+    if (replaceCurrent && this.historyIndex >= 0) {
+      this.history[this.historyIndex] = snapshot;
+      return;
+    }
+
+    if (serialized === currentSerialized) return;
+
+    this.history = this.history.slice(0, this.historyIndex + 1);
+    this.history.push(snapshot);
+    this.historyIndex = this.history.length - 1;
+  }
+
+  private restoreSnapshot(snapshot: ConfiguratorSnapshot): void {
+    this.suppressHistory = true;
+    this.config = snapshot.config as unknown as AgentWidgetConfig;
+    this.theme = createTheme(snapshot.theme, { validate: false });
+    this.syncThemeIntoConfig();
+    this.suppressHistory = false;
+    this.notifyListeners();
+  }
+}

package/src/theme-editor/types.ts

@@ -0,0 +1,177 @@
+/** Field definition types for the declarative configurator system (headless — no DOM) */
+
+import type { DeepPartial, PersonaTheme } from '../types/theme';
+import type { AgentWidgetConfig } from '../types';
+
+// ─── Field System ────────────────────────────────────────────────
+
+export type FieldType =
+  | 'color'
+  | 'slider'
+  | 'toggle'
+  | 'select'
+  | 'text'
+  | 'chip-list'
+  | 'color-scale'
+  | 'token-ref'
+  | 'role-assignment';
+
+export interface SliderOptions {
+  min: number;
+  max: number;
+  step: number;
+  unit?: 'px' | 'rem' | 'none';
+  /** Treat max value as 9999px (border-radius: full) */
+  isRadiusFull?: boolean;
+}
+
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+export interface ColorScaleOptions {
+  /** Which palette color family (e.g., 'primary', 'gray') */
+  colorFamily: string;
+}
+
+export interface TokenRefOptions {
+  /** Token type to filter available references */
+  tokenType: 'color' | 'spacing' | 'radius' | 'shadow' | 'typography';
+  /** Available palette families to reference */
+  families?: string[];
+}
+
+// ─── Role Assignment System ─────────────────────────────────────
+
+/** Which kind of value a role target expects */
+export type RoleTargetKind = 'background' | 'foreground' | 'border' | 'accent';
+
+/** A single token path that a role assignment writes to */
+export interface RoleTarget {
+  /** Theme token path (e.g., 'components.message.user.background') */
+  path: string;
+  /** What kind of value this target expects */
+  kind: RoleTargetKind;
+}
+
+/** An intensity preset (e.g., Solid uses .500 shades, Soft uses .100 shades) */
+export interface RoleIntensity {
+  id: string;
+  label: string;
+}
+
+/** Options for a role-assignment field */
+export interface RoleAssignmentOptions {
+  /** Unique role identifier */
+  roleId: string;
+  /** Helper text shown below the role name */
+  helper: string;
+  /** Token paths this role writes to */
+  targets: RoleTarget[];
+  /** Available intensity presets */
+  intensities: RoleIntensity[];
+  /** Which data-persona-theme-zone this role corresponds to (for preview highlighting) */
+  previewZone?: string;
+}
+
+export interface FieldDef {
+  id: string;
+  label: string;
+  description?: string;
+  type: FieldType;
+  /** Dot-path into the config/theme object */
+  path: string;
+  defaultValue?: unknown;
+  /** Slider-specific options */
+  slider?: SliderOptions;
+  /** Select-specific options */
+  options?: SelectOption[];
+  /** Color-scale-specific options */
+  colorScale?: ColorScaleOptions;
+  /** Token-ref-specific options */
+  tokenRef?: TokenRefOptions;
+  /** Role-assignment-specific options */
+  roleAssignment?: RoleAssignmentOptions;
+  /** CSS property hint for value formatting */
+  cssProperty?: string;
+  /** Whether this is a theme path (vs config path) */
+  isThemePath?: boolean;
+  /** Convert stored value into a control-friendly value */
+  formatValue?: (value: unknown) => unknown;
+  /** Convert control input back into the stored value shape */
+  parseValue?: (value: unknown) => unknown;
+}
+
+export interface SectionDef {
+  id: string;
+  title: string;
+  description?: string;
+  fields: FieldDef[];
+  /** Whether the section starts collapsed */
+  collapsed?: boolean;
+  /** Preset buttons for this section */
+  presets?: SectionPreset[];
+}
+
+export interface SectionPreset {
+  id: string;
+  label: string;
+  values: Record<string, unknown>;
+}
+
+export interface TabDef {
+  id: string;
+  label: string;
+  icon?: string;
+  sections: SectionDef[];
+}
+
+export interface SubGroupDef {
+  label: string;
+  sections: SectionDef[];
+  /** When true, the sub-group starts collapsed and must be explicitly expanded */
+  collapsedByDefault?: boolean;
+}
+
+// ─── Preset System ───────────────────────────────────────────────
+
+/** Extract the toolCall config type from AgentWidgetConfig */
+type AgentWidgetToolCallConfig = NonNullable<AgentWidgetConfig['toolCall']>;
+
+export interface ThemeEditorPreset {
+  id: string;
+  name: string;
+  description: string;
+  theme: DeepPartial<PersonaTheme>;
+  darkTheme?: DeepPartial<PersonaTheme>;
+  /** Tool call styling for light mode */
+  toolCall?: AgentWidgetToolCallConfig;
+  /** Tool call styling for dark mode (falls back to toolCall if not set) */
+  darkToolCall?: AgentWidgetToolCallConfig;
+  preview: {
+    primary: string;
+    surface: string;
+    accent: string;
+  };
+  darkPreview?: {
+    primary: string;
+    surface: string;
+    accent: string;
+  };
+  /** Tags for filtering/categorization */
+  tags?: string[];
+}
+
+// ─── State ───────────────────────────────────────────────────────
+
+export interface ConfiguratorSnapshot {
+  version: 2;
+  config: Record<string, unknown>;
+  theme: PersonaTheme;
+}
+
+export type ConfigChangeListener = (config: AgentWidgetConfig, theme: PersonaTheme) => void;
+
+/** Callback for when a control value changes */
+export type OnChangeCallback = (path: string, value: unknown) => void;

package/src/theme-editor.ts

@@ -0,0 +1,2 @@
+/** Entry point for @runtypelabs/persona/theme-editor */
+export * from './theme-editor/index';

package/src/theme-reference.ts

@@ -138,6 +138,8 @@ export const THEME_TOKEN_DOCS = {
       approval:
         'requested (background, border, text), approve (background, foreground), deny (background, foreground).',
       attachment: 'image (background, border).',
+      scrollToBottom:
+        'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
       toolBubble: 'shadow — tool call row box-shadow.',
       reasoningBubble: 'shadow — reasoning/thinking row box-shadow.',
       composer: 'shadow — message input form box-shadow.',
@@ -201,6 +203,12 @@ export const THEME_TOKEN_DOCS = {
       properties:
         'enabled, iconColor, backgroundColor, borderWidth, borderColor, borderRadius, size.',
     },
+    scrollToBottom: {
+      description:
+        'Shared transcript + event-stream jump-to-latest affordance.',
+      properties:
+        'features.scrollToBottom.enabled, features.scrollToBottom.iconName, features.scrollToBottom.label (empty string renders icon-only). Defaults: enabled=true, iconName="arrow-down", label="".',
+    },
     toolCall: {
       description: 'Tool call display styling.',
       properties:

package/src/types/theme.ts

@@ -25,6 +25,7 @@ export interface ColorPalette {
   success: ColorShade;
   warning: ColorShade;
   error: ColorShade;
+  info: ColorShade;
   [key: string]: ColorShade;
 }
 
@@ -392,6 +393,14 @@ export interface LabelButtonTokens {
   gap?: string;
 }
 
+/** Scroll-to-bottom pill chrome shared by transcript + event stream. */
+export interface ScrollToBottomTokens extends ComponentTokenSet {
+  size?: string;
+  gap?: string;
+  fontSize?: string;
+  iconSize?: string;
+}
+
 /** Toggle group chrome (used by createToggleGroup). */
 export interface ToggleGroupTokens {
   /** Gap between toggle buttons. Default: 0 (connected). */
@@ -419,6 +428,8 @@ export interface ComponentTokens {
   iconButton?: IconButtonTokens;
   /** Label button styling tokens. */
   labelButton?: LabelButtonTokens;
+  /** Scroll-to-bottom indicator styling tokens. */
+  scrollToBottom?: ScrollToBottomTokens;
   /** Toggle group styling tokens. */
   toggleGroup?: ToggleGroupTokens;
   /** Artifact toolbar, tab strip, and pane chrome. */

package/src/types.ts

@@ -552,10 +552,32 @@ export type AgentWidgetArtifactsFeature = {
   }) => HTMLElement | null;
 };
 
+export type AgentWidgetScrollToBottomFeature = {
+  /**
+   * When true, Persona shows a scroll-to-bottom affordance when the user breaks
+   * away from the latest transcript or event stream content.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Lucide icon name used for the affordance.
+   * @default "arrow-down"
+   */
+  iconName?: string;
+  /**
+   * Optional label text shown next to the icon. Set to an empty string for an
+   * icon-only affordance.
+   * @default ""
+   */
+  label?: string;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
   showEventStreamToggle?: boolean;
+  /** Shared transcript + event stream scroll-to-bottom affordance. */
+  scrollToBottom?: AgentWidgetScrollToBottomFeature;
   /** Configuration for the Event Stream inspector view */
   eventStream?: EventStreamConfig;
   /** Optional artifact sidebar (split pane / mobile drawer) */