@soulcraft/theme 1.0.0

package/src/stores/theme.svelte.ts

@@ -0,0 +1,320 @@
+/**
+ * @module stores/theme.svelte
+ * @description Product-aware Svelte 5 theme store for all Soulcraft products.
+ *
+ * Manages theme selection, persistence, and CSS custom property injection across
+ * the 4-level cascade (catalog → kit → custom → user). Supports an optional
+ * separate editor theme for Workshop's syntax highlighting use case.
+ *
+ * Product modes:
+ * - `'workshop'` — emits --theme-* vars + Workshop backward-compat aliases (--bg-dark, etc.)
+ *   Also supports `editorThemeId` for separate Monaco/Shiki themes.
+ * - `'venue'` — client-side (rare; Venue normally uses SSR injection from hooks.server.ts).
+ *   Emits --theme-* vars + Venue brand aliases (--brand-primary, etc.).
+ *
+ * @example
+ * ```ts
+ * // Workshop (src/stores/themeStore.svelte.ts):
+ * import { createThemeStore } from '@soulcraft/theme/stores/theme.svelte';
+ * export const themeStore = createThemeStore({ product: 'workshop' });
+ * ```
+ */
+
+import { CATALOG_BY_ID, getThemesGrouped } from '../catalog.js';
+import { buildThemeCss, buildWorkshopAliasCss, buildBrandAliasCss, buildWorkshopDerivedCss } from '../css.js';
+import { oklchToHex } from '../oklch.js';
+import type { ThemeDefinition, ThemeName } from '../types.js';
+
+/** Browser detection without SvelteKit's $app/environment dependency. */
+const isBrowser = typeof window !== 'undefined';
+
+/** Product types supported by the ThemeStore. */
+export type ThemeProduct = 'workshop' | 'venue' | 'skillvill' | 'portal';
+
+/** Options for creating a ThemeStore instance. */
+export interface ThemeStoreOptions {
+  /** Which product context this store serves. Determines which CSS aliases are emitted. */
+  product: ThemeProduct;
+  /** localStorage key for persisting the selected theme. @default 'appTheme' */
+  storageKey?: string;
+  /** ID of the default catalog theme. @default 'soulcraft-dark' */
+  defaultThemeId?: ThemeName;
+}
+
+/**
+ * Product-aware theme store using Svelte 5 runes.
+ *
+ * Manages the current catalog theme (plus an optional separate editor theme for
+ * Workshop), persists selection to localStorage, and applies `--theme-*` CSS custom
+ * properties to `document.documentElement` on every theme change.
+ */
+class ThemeStore {
+  /** Currently active application theme ID. */
+  currentThemeId = $state<ThemeName>('soulcraft-dark');
+  /**
+   * Optional separate editor theme ID.
+   * When set, Monaco and Shiki use this instead of `currentThemeId`.
+   * Workshop-specific; other products leave this null.
+   */
+  editorThemeId = $state<ThemeName | null>(null);
+
+  /** Convenience alias matching Workshop's legacy `currentTheme` property name. */
+  get currentTheme(): ThemeName { return this.currentThemeId; }
+  /** Convenience alias matching Workshop's legacy `editorTheme` property name. */
+  get editorTheme(): ThemeName | null { return this.editorThemeId; }
+
+  constructor(private options: ThemeStoreOptions) {
+    if (!isBrowser) return;
+
+    const key = options.storageKey ?? 'appTheme';
+    const saved = localStorage.getItem(key);
+    if (saved && CATALOG_BY_ID.has(saved)) {
+      this.currentThemeId = saved as ThemeName;
+      this.applyTheme(this.currentThemeId);
+    } else {
+      const fallback = options.defaultThemeId ?? 'soulcraft-dark';
+      this.currentThemeId = fallback;
+      this.applyTheme(fallback);
+    }
+
+    const savedEditor = localStorage.getItem(`${key}:editor`);
+    if (savedEditor && CATALOG_BY_ID.has(savedEditor)) {
+      this.editorThemeId = savedEditor as ThemeName;
+    }
+  }
+
+  /**
+   * Check whether a string is a valid catalog theme ID.
+   *
+   * @param id - The string to validate.
+   * @returns True if `id` is a known catalog theme ID.
+   */
+  isValidTheme(id: string): boolean {
+    return CATALOG_BY_ID.has(id);
+  }
+
+  /**
+   * Get the ThemeDefinition for a given theme ID.
+   *
+   * @param id - A catalog theme ID.
+   * @returns The ThemeDefinition, or null if not found.
+   */
+  getTheme(id: string): ThemeDefinition | null {
+    return CATALOG_BY_ID.get(id) ?? null;
+  }
+
+  /**
+   * Get the effective editor theme ID.
+   * Returns `editorThemeId` if set, otherwise falls back to `currentThemeId`.
+   *
+   * @returns The theme ID to use for Monaco/Shiki rendering.
+   */
+  getEffectiveEditorTheme(): ThemeName {
+    return this.editorThemeId ?? this.currentThemeId;
+  }
+
+  /**
+   * Set the application theme and persist to localStorage.
+   *
+   * @param id - A valid catalog theme ID.
+   */
+  setTheme(id: ThemeName): void {
+    this.currentThemeId = id;
+    this.applyTheme(id);
+
+    if (isBrowser) {
+      const key = this.options.storageKey ?? 'appTheme';
+      localStorage.setItem(key, id);
+      window.dispatchEvent(new CustomEvent('themeChanged', {
+        detail: { appTheme: id, editorTheme: this.getEffectiveEditorTheme() }
+      }));
+    }
+  }
+
+  /**
+   * Set the editor theme override and persist to localStorage.
+   * Pass null to clear the override and use the app theme.
+   *
+   * @param id - A valid catalog theme ID, or null to clear.
+   */
+  setEditorTheme(id: ThemeName | null): void {
+    this.editorThemeId = id;
+
+    if (isBrowser) {
+      const key = `${this.options.storageKey ?? 'appTheme'}:editor`;
+      if (id) {
+        localStorage.setItem(key, id);
+      } else {
+        localStorage.removeItem(key);
+      }
+      window.dispatchEvent(new CustomEvent('themeChanged', {
+        detail: { appTheme: this.currentThemeId, editorTheme: this.getEffectiveEditorTheme() }
+      }));
+    }
+  }
+
+  /**
+   * Return all available theme IDs in catalog order.
+   *
+   * @returns Array of all 23 theme IDs.
+   */
+  getAvailableThemes(): ThemeName[] {
+    return Array.from(CATALOG_BY_ID.keys()) as ThemeName[];
+  }
+
+  /**
+   * Return the ThemeDefinition for the current active theme.
+   *
+   * @returns The current ThemeDefinition.
+   */
+  getCurrentTheme(): ThemeDefinition {
+    return CATALOG_BY_ID.get(this.currentThemeId)!;
+  }
+
+  /**
+   * Get themes grouped by category for rendering the picker UI.
+   * Equivalent to Workshop's legacy `getThemesByCategory()`.
+   *
+   * @returns Object with `soulcraft`, `dark`, and `light` arrays.
+   */
+  getThemesByCategory(): Record<string, ThemeDefinition[]> {
+    return getThemesGrouped();
+  }
+
+  // ─── Internal CSS injection ─────────────────────────────────────────────
+
+  /**
+   * Apply a theme by setting CSS custom properties on `document.documentElement`.
+   *
+   * Sets `--theme-*` variables plus product-specific backward-compat aliases.
+   * Also updates `document.body` background and color for immediate visual feedback.
+   *
+   * @param id - The catalog theme ID to apply.
+   */
+  applyTheme(id: ThemeName): void {
+    if (!isBrowser) return;
+    const theme = CATALOG_BY_ID.get(id);
+    if (!theme) return;
+
+    const root  = document.documentElement;
+    const body  = document.body;
+    const { colors } = theme;
+
+    // ── Core --theme-* vars ───────────────────────────────────────────────
+    root.style.setProperty('--theme-bg-base',          colors.bgBase);
+    root.style.setProperty('--theme-bg-surface',       colors.bgSurface);
+    root.style.setProperty('--theme-bg-elevated',      colors.bgElevated);
+    root.style.setProperty('--theme-text-primary',     colors.textPrimary);
+    root.style.setProperty('--theme-text-secondary',   colors.textSecondary);
+    root.style.setProperty('--theme-primary',          colors.primary);
+    root.style.setProperty('--theme-primary-light',    colors.primaryLight);
+    root.style.setProperty('--theme-primary-dark',     colors.primaryDark);
+    root.style.setProperty('--theme-accent',           colors.accent);
+    root.style.setProperty('--theme-accent-light',     colors.accentLight);
+    root.style.setProperty('--theme-glass',            colors.glass);
+    root.style.setProperty('--theme-glass-border',     colors.glassBorder);
+    root.style.setProperty('--theme-success',          colors.success);
+    root.style.setProperty('--theme-warning',          colors.warning);
+    root.style.setProperty('--theme-error',            colors.error);
+    root.style.setProperty('--theme-font-display',     theme.fonts.displayFont);
+    root.style.setProperty('--theme-font-body',        theme.fonts.bodyFont);
+
+    // ── Product-specific backward-compat aliases ──────────────────────────
+    if (this.options.product === 'workshop') {
+      // Legacy Workshop vars — --bg-dark, --primary, --glass-border, etc.
+      root.style.setProperty('--bg-dark',            colors.bgBase);
+      root.style.setProperty('--bg-medium',          colors.bgSurface);
+      root.style.setProperty('--bg-light',           colors.bgElevated);
+      root.style.setProperty('--text-primary',       colors.textPrimary);
+      root.style.setProperty('--text-secondary',     colors.textSecondary);
+      root.style.setProperty('--primary',            colors.primary);
+      root.style.setProperty('--primary-light',      colors.primaryLight);
+      root.style.setProperty('--primary-dark',       colors.primaryDark);
+      root.style.setProperty('--accent',             colors.accent);
+      root.style.setProperty('--accent-light',       colors.accentLight);
+      root.style.setProperty('--glass',              colors.glass);
+      root.style.setProperty('--glass-border',       colors.glassBorder);
+      root.style.setProperty('--success',            colors.success);
+      root.style.setProperty('--warning',            colors.warning);
+      root.style.setProperty('--error',              colors.error);
+      // Semantic surface aliases
+      root.style.setProperty('--surface-primary',    colors.bgBase);
+      root.style.setProperty('--surface-secondary',  colors.bgSurface);
+      root.style.setProperty('--surface-tertiary',   colors.bgElevated);
+      root.style.setProperty('--surface-hover',      colors.bgElevated);
+      root.style.setProperty('--border-subtle',      colors.glassBorder);
+      root.style.setProperty('--accent-muted',       colors.primaryLight);
+      root.style.setProperty('--accent-subtle',      colors.primary.replace(/\)$/, ' / 0.13)').replace('oklch(', 'oklch('));
+      root.style.setProperty('--accent-hover',       colors.primaryDark);
+      root.style.setProperty('--text-muted',         colors.textSecondary);
+      root.style.setProperty('--success-subtle',     colors.success.replace(/\)$/, ' / 0.13)').replace('oklch(', 'oklch('));
+    } else if (this.options.product === 'venue') {
+      // Legacy Venue brand vars
+      root.style.setProperty('--brand-primary',      colors.primary);
+      root.style.setProperty('--brand-background',   colors.bgBase);
+      root.style.setProperty('--brand-accent',       colors.accent);
+      root.style.setProperty('--brand-text',         colors.textPrimary);
+      root.style.setProperty('--brand-font-display', theme.fonts.displayFont);
+      root.style.setProperty('--brand-font-body',    theme.fonts.bodyFont);
+    }
+
+    // ── Immediate body visual feedback ────────────────────────────────────
+    if (body) {
+      body.style.background = `linear-gradient(135deg, ${colors.bgBase} 0%, ${colors.bgSurface} 50%, ${colors.bgBase} 100%)`;
+      body.style.color = colors.textPrimary;
+    }
+
+    // Force CSS recalculation by toggling a timestamp var
+    root.style.setProperty('--theme-timestamp', Date.now().toString());
+  }
+
+  /**
+   * Get the oklch colors as a hex color map for Shiki/Monaco token registration.
+   *
+   * Shiki requires hex color strings in its VS Code theme format. This method
+   * converts the current theme's oklch colors to hex for that bridging use case.
+   *
+   * @param id - Theme ID to convert. Defaults to current theme.
+   * @returns Object mapping semantic color names to hex strings.
+   */
+  getHexColorsForShiki(id?: ThemeName): Record<string, string> | null {
+    const theme = CATALOG_BY_ID.get(id ?? this.currentThemeId);
+    if (!theme) return null;
+    const { colors } = theme;
+    return {
+      bgBase:        oklchToHex(colors.bgBase),
+      bgElevated:    oklchToHex(colors.bgElevated),
+      textPrimary:   oklchToHex(colors.textPrimary),
+      textSecondary: oklchToHex(colors.textSecondary),
+      primary:       oklchToHex(colors.primary),
+      primaryLight:  oklchToHex(colors.primaryLight),
+      accent:        oklchToHex(colors.accent),
+      accentLight:   oklchToHex(colors.accentLight),
+      success:       oklchToHex(colors.success),
+      warning:       oklchToHex(colors.warning),
+      error:         oklchToHex(colors.error),
+    };
+  }
+}
+
+/**
+ * Create a product-aware ThemeStore instance.
+ *
+ * @param options - Store configuration including product type and optional keys.
+ * @returns A reactive Svelte 5 ThemeStore instance.
+ *
+ * @example
+ * ```ts
+ * // Workshop:
+ * export const themeStore = createThemeStore({ product: 'workshop' });
+ *
+ * // Venue client-side (rare):
+ * export const themeStore = createThemeStore({ product: 'venue' });
+ * ```
+ */
+export function createThemeStore(options: ThemeStoreOptions): ThemeStore {
+  return new ThemeStore(options);
+}
+
+export type { ThemeStore };
+export type { ThemeDefinition, ThemeName };

package/src/tailwind/tokens.css

@@ -0,0 +1,57 @@
+/**
+ * @soulcraft/theme — Shared Tailwind CSS 4 design tokens.
+ *
+ * Defines the @theme block that bridges runtime CSS custom properties
+ * (--theme-*) to Tailwind utility classes (bg-theme-base, text-theme-text, etc.).
+ *
+ * The --theme-* variables are set at runtime by:
+ * - ThemeStore.applyTheme() (client-side, Workshop)
+ * - hooks.server.ts themeInjector (SSR, Venue)
+ *
+ * Import this file in app.css alongside Tailwind:
+ *   @import '@soulcraft/theme/tailwind/tokens.css';
+ *   @import 'tailwindcss';
+ *
+ * This generates Tailwind utilities:
+ *   bg-theme-base      bg-theme-surface    bg-theme-elevated
+ *   text-theme-text    text-theme-text-muted
+ *   bg-theme-primary   bg-theme-primary-light   bg-theme-primary-dark
+ *   bg-theme-accent    bg-theme-accent-light
+ *   bg-theme-glass     border-theme-glass-border
+ *   text-theme-success text-theme-warning  text-theme-error
+ *   font-display       font-body           font-mono
+ */
+
+@theme {
+  /* ── Background scale ───────────────────────────────────────────────────── */
+  --color-theme-base:           var(--theme-bg-base);
+  --color-theme-surface:        var(--theme-bg-surface);
+  --color-theme-elevated:       var(--theme-bg-elevated);
+
+  /* ── Text scale ─────────────────────────────────────────────────────────── */
+  --color-theme-text:           var(--theme-text-primary);
+  --color-theme-text-muted:     var(--theme-text-secondary);
+
+  /* ── Brand: primary ─────────────────────────────────────────────────────── */
+  --color-theme-primary:        var(--theme-primary);
+  --color-theme-primary-light:  var(--theme-primary-light);
+  --color-theme-primary-dark:   var(--theme-primary-dark);
+
+  /* ── Brand: accent ──────────────────────────────────────────────────────── */
+  --color-theme-accent:         var(--theme-accent);
+  --color-theme-accent-light:   var(--theme-accent-light);
+
+  /* ── Glass / overlay ────────────────────────────────────────────────────── */
+  --color-theme-glass:          var(--theme-glass);
+  --color-theme-glass-border:   var(--theme-glass-border);
+
+  /* ── Semantic status (same across all themes) ───────────────────────────── */
+  --color-theme-success:        var(--theme-success);
+  --color-theme-warning:        var(--theme-warning);
+  --color-theme-error:          var(--theme-error);
+
+  /* ── Typography ─────────────────────────────────────────────────────────── */
+  --font-display: var(--theme-font-display, system-ui), serif;
+  --font-body:    var(--theme-font-body, system-ui), ui-sans-serif, system-ui, sans-serif;
+  --font-mono:    'JetBrains Mono', ui-monospace, monospace;
+}

package/src/types.ts

@@ -0,0 +1,217 @@
+/**
+ * @module types
+ * @description Core TypeScript types for the @soulcraft/theme design system.
+ *
+ * Provides the unified ThemeColors interface that reconciles Workshop's 15-property
+ * hex/rgba palette with Venue's 6-property oklch VenueKitTheme. All color values
+ * are oklch strings for perceptually uniform palette operations.
+ *
+ * The type system has three levels of abstraction:
+ * - `ThemeSeed` — minimal 2-6 properties; kit authors write this
+ * - `ThemeColors` — the full 15-property palette; derived from a seed or defined directly
+ * - `ThemeDefinition` — colors + fonts + metadata; what the catalog stores
+ */
+
+/** An OKLCH color string as produced by {@link formatOklch} or CSS Color 4. */
+export type OklchColor = string;
+
+/**
+ * Theme category for grouping in the ThemePicker UI.
+ * Matches Workshop's existing getThemesByCategory() groupings.
+ */
+export type ThemeCategory = 'soulcraft' | 'dark' | 'light';
+
+/**
+ * The full 15-property unified color palette.
+ *
+ * Reconciles Workshop's `ThemeColors` (bgDark/bgMedium/bgLight naming) with
+ * Venue's `VenueKitTheme` (background/primary/accent naming). All values are
+ * OKLCH strings compatible with CSS Color 4 and Tailwind CSS 4.
+ *
+ * @example
+ * ```ts
+ * const colors: ThemeColors = {
+ *   bgBase: 'oklch(0.052 0.023 261.6)',
+ *   bgSurface: 'oklch(0.092 0.031 261.4)',
+ *   bgElevated: 'oklch(0.143 0.022 251.7)',
+ *   textPrimary: 'oklch(0.951 0.010 251.1)',
+ *   textSecondary: 'oklch(0.659 0.020 261.4)',
+ *   primary: 'oklch(0.624 0.082 181.4)',
+ *   primaryLight: 'oklch(0.742 0.094 181.4)',
+ *   primaryDark: 'oklch(0.316 0.053 211.0)',
+ *   accent: 'oklch(0.656 0.127 39.8)',
+ *   accentLight: 'oklch(0.755 0.107 55.4)',
+ *   glass: 'oklch(1 0 0 / 0.05)',
+ *   glassBorder: 'oklch(1 0 0 / 0.10)',
+ *   success: 'oklch(0.698 0.158 145.3)',
+ *   warning: 'oklch(0.762 0.161 76.8)',
+ *   error: 'oklch(0.628 0.200 25.6)',
+ * }
+ * ```
+ */
+export interface ThemeColors {
+  /** Deepest background. Workshop: bgDark. Venue: background. Tailwind: bg-theme-base. */
+  bgBase: OklchColor;
+  /** Mid-level surface. Workshop: bgMedium. Tailwind: bg-theme-surface. */
+  bgSurface: OklchColor;
+  /** Raised card/panel surface. Workshop: bgLight. Tailwind: bg-theme-elevated. */
+  bgElevated: OklchColor;
+
+  /** Primary text. Workshop: textPrimary. Venue: text. Tailwind: text-theme-text. */
+  textPrimary: OklchColor;
+  /** Secondary/muted text. Workshop: textSecondary. Tailwind: text-theme-text-muted. */
+  textSecondary: OklchColor;
+
+  /** Brand primary color. Workshop: primary. Venue: primary. Tailwind: bg-theme-primary. */
+  primary: OklchColor;
+  /** Lighter primary shade. Workshop: primaryLight. Tailwind: bg-theme-primary-light. */
+  primaryLight: OklchColor;
+  /** Darker primary shade. Workshop: primaryDark. Tailwind: bg-theme-primary-dark. */
+  primaryDark: OklchColor;
+
+  /** Accent/secondary brand color. Workshop: accent. Venue: accent. Tailwind: bg-theme-accent. */
+  accent: OklchColor;
+  /** Lighter accent shade. Workshop: accentLight. Tailwind: bg-theme-accent-light. */
+  accentLight: OklchColor;
+
+  /** Glass background for overlays. Workshop: glass. Tailwind: bg-theme-glass. */
+  glass: OklchColor;
+  /** Glass border for overlays. Workshop: glassBorder. Tailwind: border-theme-glass-border. */
+  glassBorder: OklchColor;
+
+  /** Success/positive semantic color. Tailwind: text-theme-success. */
+  success: OklchColor;
+  /** Warning/caution semantic color. Tailwind: text-theme-warning. */
+  warning: OklchColor;
+  /** Error/destructive semantic color. Tailwind: text-theme-error. */
+  error: OklchColor;
+}
+
+/**
+ * Font configuration for display headings and body text.
+ * Font names are Google Font names or CSS system font stack keywords.
+ */
+export interface ThemeFonts {
+  /**
+   * Google Font name or system font keyword for headings.
+   * @example 'Fraunces' | 'system-ui' | 'Inter'
+   */
+  displayFont: string;
+  /**
+   * Google Font name or system font keyword for body text.
+   * @example 'Inter' | 'system-ui'
+   */
+  bodyFont: string;
+}
+
+/**
+ * Metadata describing a theme's identity and rendering mode.
+ */
+export interface ThemeMeta {
+  /** Stable kebab-case identifier. @example 'soulcraft-dark' */
+  id: string;
+  /** Human-readable display name. @example 'Soulcraft Dark' */
+  name: string;
+  /** Category for grouping in the picker UI. */
+  category: ThemeCategory;
+  /** Whether this is a dark-mode theme (used for semantic status defaults). */
+  isDark: boolean;
+}
+
+/**
+ * A complete, fully-resolved theme: metadata + all 15 colors + fonts.
+ * This is what the catalog stores and what `resolveTheme()` returns.
+ */
+export interface ThemeDefinition {
+  /** Theme identity and rendering metadata. */
+  meta: ThemeMeta;
+  /** The full 15-property color palette (all OKLCH). */
+  colors: ThemeColors;
+  /** Display and body fonts for this theme. */
+  fonts: ThemeFonts;
+}
+
+/**
+ * Minimal input for kit authors to define a brand theme.
+ *
+ * Only `primary` and `bgBase` are required. All other properties are auto-derived
+ * by `deriveFullPalette()` using oklch arithmetic — surface levels from bgBase lightness,
+ * text from bgBase contrast, light/dark primary shades from hue, etc.
+ *
+ * Maps to `VenueKitTheme` in kit-schema. Kit authors specify this in `kit.json`
+ * under `venue.theme`.
+ *
+ * @example
+ * ```ts
+ * const seed: ThemeSeed = {
+ *   primary: 'oklch(0.72 0.15 25)',      // Rose brand color
+ *   bgBase: 'oklch(0.96 0.02 80)',        // Warm cream background
+ *   accent: 'oklch(0.80 0.12 75)',        // Amber accent
+ *   displayFont: 'Fraunces',
+ *   bodyFont: 'Inter',
+ * };
+ * ```
+ */
+export interface ThemeSeed {
+  /** Primary brand color. Required. */
+  primary: OklchColor;
+  /** Deepest background color. Required. */
+  bgBase: OklchColor;
+  /** Accent color. Derived from primary hue+150 if absent. */
+  accent?: OklchColor;
+  /** Primary text color. Derived from bgBase contrast if absent. */
+  textPrimary?: OklchColor;
+  /** Display/heading Google Font name. @default 'system-ui' */
+  displayFont?: string;
+  /** Body Google Font name. @default 'Inter' */
+  bodyFont?: string;
+}
+
+/**
+ * Input to the 4-level theme cascade resolver.
+ *
+ * Priority order (highest wins):
+ * 1. `catalogId` — base catalog theme
+ * 2. `kitSeed` — kit brand colors merged on top
+ * 3. `customOverrides` — admin-edited color/font overrides
+ * 4. `userThemeId` — end-user picks a catalog theme (overrides all if present)
+ */
+export interface ThemeCascadeInput {
+  /** Base catalog theme ID. Defaults to 'soulcraft-dark'. */
+  catalogId?: string;
+  /** Kit brand seed — derives a full palette and merges on top of the base. */
+  kitSeed?: ThemeSeed;
+  /** Admin-level overrides for specific colors or fonts. */
+  customOverrides?: Partial<ThemeColors & ThemeFonts>;
+  /** End-user theme preference. If set and valid, used instead of the cascade result. */
+  userThemeId?: string;
+}
+
+/**
+ * All 23 catalog theme IDs shipped with the package.
+ * Exported for type-safe theme name references in Workshop and other products.
+ */
+export type ThemeName =
+  | 'soulcraft-dark'
+  | 'soulcraft-light'
+  | 'tokyo-night'
+  | 'catppuccin-mocha'
+  | 'gruvbox-dark'
+  | 'material-theme-darker'
+  | 'material-theme-palenight'
+  | 'ayu-dark'
+  | 'synthwave-84'
+  | 'one-dark-pro'
+  | 'dracula'
+  | 'nord'
+  | 'monokai'
+  | 'night-owl'
+  | 'solarized-dark'
+  | 'github-dark'
+  | 'github-dark-dimmed'
+  | 'catppuccin-latte'
+  | 'gruvbox-light'
+  | 'solarized-light'
+  | 'github-light'
+  | 'one-light'
+  | 'material-theme-lighter';