@soulcraft/theme 1.0.0

package/src/oklch.ts

@@ -0,0 +1,299 @@
+/**
+ * @module oklch
+ * @description OKLCH color space conversion utilities.
+ *
+ * Implements the full conversion chain between hex/rgba CSS colors and OKLCH
+ * (CSS Color 4) using Björn Ottosson's OKLab math. All conversions are
+ * numerically accurate to 4 decimal places.
+ *
+ * Conversion chain:
+ *   hex → linear sRGB → LMS → LMS' (cube root) → OKLab → OKLCH
+ *   OKLCH → OKLab → LMS' → LMS → linear sRGB → sRGB → hex
+ *
+ * @see https://bottosson.github.io/posts/oklab/
+ */
+
+import type { OklchColor } from './types.js';
+
+// ─── Internal conversion helpers ─────────────────────────────────────────────
+
+/**
+ * Expand sRGB gamma to linear light value.
+ * @param c - Component in [0, 1] sRGB space.
+ */
+function gammaExpand(c: number): number {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * Compress linear light to sRGB gamma value.
+ * @param c - Component in [0, 1] linear space.
+ */
+function gammaCompress(c: number): number {
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+
+/**
+ * Clamp a number to [0, 1].
+ * @param v - Input value.
+ */
+function clamp01(v: number): number {
+  return Math.max(0, Math.min(1, v));
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Format numeric OKLCH components into a CSS OKLCH string.
+ *
+ * @param L - Lightness in [0, 1].
+ * @param C - Chroma in [0, 0.4+].
+ * @param H - Hue in [0, 360).
+ * @param alpha - Optional alpha in [0, 1]. Omitted if 1 or undefined.
+ * @returns A valid CSS `oklch(...)` color string.
+ *
+ * @example
+ * formatOklch(0.624, 0.082, 181.4) // → 'oklch(0.6240 0.0820 181.4)'
+ * formatOklch(1, 0, 0, 0.05)       // → 'oklch(1.0000 0.0000 0.0 / 0.05)'
+ */
+export function formatOklch(L: number, C: number, H: number, alpha?: number): OklchColor {
+  const l = L.toFixed(4);
+  const c = C.toFixed(4);
+  const h = H.toFixed(1);
+  if (alpha !== undefined && alpha < 1) {
+    return `oklch(${l} ${c} ${h} / ${alpha})`;
+  }
+  return `oklch(${l} ${c} ${h})`;
+}
+
+/**
+ * Parse a CSS OKLCH string into its numeric components.
+ *
+ * Handles both `oklch(L C H)` and `oklch(L C H / A)` formats.
+ * Returns null if the string cannot be parsed as OKLCH.
+ *
+ * @param oklch - An oklch() CSS color string.
+ * @returns Tuple `[L, C, H, alpha?]` or null on parse failure.
+ *
+ * @example
+ * parseOklch('oklch(0.624 0.082 181.4)')     // → [0.624, 0.082, 181.4]
+ * parseOklch('oklch(1 0 0 / 0.05)')          // → [1, 0, 0, 0.05]
+ */
+export function parseOklch(oklch: OklchColor): [L: number, C: number, H: number, A?: number] | null {
+  const raw = oklch.trim();
+  if (!raw.startsWith('oklch(') || !raw.endsWith(')')) return null;
+  const inner = raw.slice(6, -1).trim();
+  // Avoid destructuring from .split()/.map() to keep element types concrete under
+  // noUncheckedIndexedAccess — use indexOf + slice instead.
+  const slashIdx = inner.indexOf('/');
+  const colorStr = (slashIdx === -1 ? inner : inner.slice(0, slashIdx)).trim();
+  const alphaStr = slashIdx === -1 ? undefined : inner.slice(slashIdx + 1).trim();
+  const parts = colorStr.split(/\s+/);
+  if (parts.length !== 3) return null;
+  // Number() accepts string|undefined (any), so index access is safe here.
+  const L = Number(parts[0]);
+  const C = Number(parts[1]);
+  const H = Number(parts[2]);
+  if (isNaN(L) || isNaN(C) || isNaN(H)) return null;
+  if (alphaStr !== undefined) {
+    const A = Number(alphaStr);
+    if (isNaN(A)) return null;
+    return [L, C, H, A];
+  }
+  return [L, C, H];
+}
+
+/**
+ * Convert a CSS hex color string to an OKLCH color string.
+ *
+ * Supports 3-digit (#abc), 6-digit (#aabbcc), and 8-digit (#aabbccdd) hex.
+ * Alpha from 8-digit hex is preserved in the output.
+ *
+ * @param hex - A CSS hex color string.
+ * @returns An OKLCH color string.
+ *
+ * @example
+ * hexToOklch('#2a9d8f') // → 'oklch(0.6240 0.0820 181.4)'
+ * hexToOklch('#0a0e1a') // → 'oklch(0.0519 0.0228 261.6)'
+ */
+export function hexToOklch(hex: string): OklchColor {
+  let h = hex.replace('#', '');
+  // Expand 3-digit hex
+  // Use charAt() instead of bracket notation: with noUncheckedIndexedAccess,
+  // string[n] widens to string|undefined, but charAt() always returns string.
+  if (h.length === 3) h = h.charAt(0)+h.charAt(0)+h.charAt(1)+h.charAt(1)+h.charAt(2)+h.charAt(2);
+
+  const r8 = parseInt(h.slice(0, 2), 16);
+  const g8 = parseInt(h.slice(2, 4), 16);
+  const b8 = parseInt(h.slice(4, 6), 16);
+  const alpha = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : undefined;
+
+  const [L, C, H] = rgbToOklchComponents(r8 / 255, g8 / 255, b8 / 255);
+  return formatOklch(L, C, H, alpha !== undefined && alpha < 1 ? alpha : undefined);
+}
+
+/**
+ * Convert a CSS rgba() or rgb() string to an OKLCH color string.
+ *
+ * Preserves the alpha channel. Channel values are 0–255; alpha is 0–1.
+ *
+ * @param rgba - A CSS `rgba()` or `rgb()` color string.
+ * @returns An OKLCH color string, or a white fallback if parsing fails.
+ *
+ * @example
+ * rgbaToOklch('rgba(255, 255, 255, 0.05)') // → 'oklch(1.0000 0.0000 0.0 / 0.05)'
+ * rgbaToOklch('rgba(122, 162, 247, 0.2)')  // → 'oklch(0.7148 0.1201 264.4 / 0.2)'
+ */
+export function rgbaToOklch(rgba: string): OklchColor {
+  const m = rgba.match(/rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)/);
+  if (!m) return 'oklch(1 0 0)';
+  const r = Number(m[1]) / 255;
+  const g = Number(m[2]) / 255;
+  const b = Number(m[3]) / 255;
+  const alpha = m[4] !== undefined ? Number(m[4]) : undefined;
+  const [L, C, H] = rgbToOklchComponents(r, g, b);
+  return formatOklch(L, C, H, alpha !== undefined && alpha < 1 ? alpha : undefined);
+}
+
+/**
+ * Convert an OKLCH color string to a CSS hex color string.
+ *
+ * Alpha values below 1.0 are encoded as the 8-digit hex `#rrggbbaa` format.
+ * Out-of-gamut values are clamped to the sRGB range.
+ *
+ * @param oklch - An OKLCH color string.
+ * @returns A lowercase hex color string (e.g. '#2a9d8f').
+ *
+ * @example
+ * oklchToHex('oklch(0.624 0.082 181.4)')  // → '#2a9d8f'
+ * oklchToHex('oklch(1 0 0 / 0.05)')       // → '#ffffff0d'
+ */
+export function oklchToHex(oklch: OklchColor): string {
+  const parsed = parseOklch(oklch);
+  if (!parsed) return '#000000';
+  const [L, C, H, alpha] = parsed;
+
+  // OKLCH → OKLab
+  const H_rad = H * (Math.PI / 180);
+  const a = C * Math.cos(H_rad);
+  const b = C * Math.sin(H_rad);
+
+  // OKLab → LMS'
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+
+  // LMS' → LMS
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+
+  // LMS → linear sRGB
+  const lr =  4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const lg = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const lb = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+
+  // Linear sRGB → sRGB, clamp, convert to byte
+  const r = Math.round(clamp01(gammaCompress(lr)) * 255);
+  const g = Math.round(clamp01(gammaCompress(lg)) * 255);
+  const bv = Math.round(clamp01(gammaCompress(lb)) * 255);
+
+  const hex = '#' + [r, g, bv].map(v => v.toString(16).padStart(2, '0')).join('');
+  if (alpha !== undefined && alpha < 1) {
+    const a8 = Math.round(alpha * 255).toString(16).padStart(2, '0');
+    return hex + a8;
+  }
+  return hex;
+}
+
+/**
+ * Return an OKLCH color with the alpha component replaced or added.
+ *
+ * @param oklch - Source OKLCH color string.
+ * @param alpha - New alpha value in [0, 1].
+ * @returns OKLCH string with modified alpha.
+ *
+ * @example
+ * withAlpha('oklch(0.624 0.082 181.4)', 0.13) // → 'oklch(0.6240 0.0820 181.4 / 0.13)'
+ */
+export function withAlpha(oklch: OklchColor, alpha: number): OklchColor {
+  const parsed = parseOklch(oklch);
+  if (!parsed) return oklch;
+  const [L, C, H] = parsed;
+  return formatOklch(L, C, H, alpha);
+}
+
+/**
+ * Return an OKLCH color with the lightness component modified by a delta.
+ *
+ * @param oklch - Source OKLCH color string.
+ * @param delta - Amount to add to lightness (negative to darken).
+ * @returns OKLCH string with modified lightness, clamped to [0, 1].
+ *
+ * @example
+ * adjustL('oklch(0.624 0.082 181.4)', 0.1) // → 'oklch(0.7240 0.0820 181.4)'
+ */
+export function adjustL(oklch: OklchColor, delta: number): OklchColor {
+  const parsed = parseOklch(oklch);
+  if (!parsed) return oklch;
+  const [L, C, H, alpha] = parsed;
+  return formatOklch(clamp01(L + delta), C, H, alpha);
+}
+
+/**
+ * Return an OKLCH color with the hue rotated by the given degrees.
+ *
+ * @param oklch - Source OKLCH color string.
+ * @param degrees - Degrees to rotate the hue (can be negative).
+ * @returns OKLCH string with rotated hue in [0, 360).
+ *
+ * @example
+ * rotateH('oklch(0.624 0.082 181.4)', 150) // → 'oklch(0.6240 0.0820 331.4)'
+ */
+export function rotateH(oklch: OklchColor, degrees: number): OklchColor {
+  const parsed = parseOklch(oklch);
+  if (!parsed) return oklch;
+  const [L, C, H, alpha] = parsed;
+  const newH = ((H + degrees) % 360 + 360) % 360;
+  return formatOklch(L, C, newH, alpha);
+}
+
+// ─── Internal: core conversion ────────────────────────────────────────────────
+
+/**
+ * Convert normalized sRGB [0,1] components to OKLCH [L, C, H].
+ * Uses Björn Ottosson's OKLab conversion matrices.
+ *
+ * @param r - Red in [0, 1] sRGB space.
+ * @param g - Green in [0, 1] sRGB space.
+ * @param b - Blue in [0, 1] sRGB space.
+ * @returns Tuple [L, C, H].
+ */
+function rgbToOklchComponents(r: number, g: number, b: number): [number, number, number] {
+  // sRGB → linear
+  const rl = gammaExpand(r);
+  const gl = gammaExpand(g);
+  const bl = gammaExpand(b);
+
+  // Linear sRGB → LMS (Björn Ottosson M1)
+  const l = 0.4122214708 * rl + 0.5363325363 * gl + 0.0514459929 * bl;
+  const m = 0.2119034982 * rl + 0.6806995451 * gl + 0.1073969566 * bl;
+  const s = 0.0883024619 * rl + 0.2817188376 * gl + 0.6299787005 * bl;
+
+  // LMS → LMS' (cube root, safe for negatives)
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+
+  // LMS' → OKLab (Björn Ottosson M2)
+  const L = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+  const a = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_;
+  const bv = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_;
+
+  // OKLab → OKLCH
+  const C = Math.sqrt(a * a + bv * bv);
+  let H = Math.atan2(bv, a) * (180 / Math.PI);
+  if (H < 0) H += 360;
+
+  return [L, C, H];
+}

package/src/resolve.ts

@@ -0,0 +1,103 @@
+/**
+ * @module resolve
+ * @description 4-level theme cascade resolver.
+ *
+ * Resolves the active theme by merging layers in priority order:
+ *
+ * 1. Catalog theme (base — predefined or soulcraft-dark fallback)
+ * 2. Kit seed (auto-derived palette from brand colors, merged on top)
+ * 3. Custom overrides (admin-edited per-deployment, merged on top)
+ * 4. User preference (if valid catalog ID, replaces the entire cascade result)
+ *
+ * Layer 4 (user preference) is the "escape hatch" for end-users who want
+ * a specific catalog theme regardless of what the kit author set.
+ *
+ * @example
+ * ```ts
+ * // Venue: kit provides seed, admin adds overrides
+ * const theme = resolveTheme({
+ *   catalogId: 'soulcraft-light',
+ *   kitSeed: { primary: 'oklch(0.72 0.15 25)', bgBase: 'oklch(0.96 0.02 80)' },
+ *   customOverrides: { displayFont: 'Fraunces', bodyFont: 'Inter' },
+ * });
+ *
+ * // Workshop: user picks their own theme
+ * const theme = resolveTheme({ userThemeId: 'tokyo-night' });
+ * ```
+ */
+
+import { CATALOG_BY_ID } from './catalog.js';
+import { deriveFullPalette } from './derive.js';
+import type { ThemeCascadeInput, ThemeDefinition, ThemeColors, ThemeFonts } from './types.js';
+
+const DEFAULT_ID = 'soulcraft-dark';
+
+/**
+ * Resolve the active theme from a 4-level cascade specification.
+ *
+ * @param input - Cascade inputs. All fields are optional; defaults to soulcraft-dark.
+ * @returns A fully-resolved ThemeDefinition ready for CSS injection.
+ *
+ * @example
+ * ```ts
+ * // Kit-branded Venue deployment
+ * const theme = resolveTheme({
+ *   catalogId: 'soulcraft-light',
+ *   kitSeed: venueKit.venue.theme,
+ *   customOverrides: organization?.theme,
+ * });
+ *
+ * // Workshop user preference
+ * const theme = resolveTheme({ userThemeId: 'dracula' });
+ *
+ * // No inputs → soulcraft-dark
+ * const theme = resolveTheme({});
+ * ```
+ */
+export function resolveTheme(input: ThemeCascadeInput): ThemeDefinition {
+  // ── Layer 4: user preference takes total precedence ──────────────────────
+  if (input.userThemeId) {
+    const userTheme = CATALOG_BY_ID.get(input.userThemeId);
+    if (userTheme) return userTheme;
+    // Invalid userThemeId → fall through to cascade
+  }
+
+  // ── Layer 1: catalog base ─────────────────────────────────────────────────
+  const base = CATALOG_BY_ID.get(input.catalogId ?? DEFAULT_ID) ??
+               CATALOG_BY_ID.get(DEFAULT_ID)!;
+
+  let colors: ThemeColors = { ...base.colors };
+  let fonts:  ThemeFonts  = { ...base.fonts };
+
+  // ── Layer 2: kit seed ─────────────────────────────────────────────────────
+  if (input.kitSeed) {
+    const derived = deriveFullPalette(input.kitSeed);
+    colors = { ...colors, ...derived };
+    if (input.kitSeed.displayFont) fonts.displayFont = input.kitSeed.displayFont;
+    if (input.kitSeed.bodyFont)    fonts.bodyFont    = input.kitSeed.bodyFont;
+  }
+
+  // ── Layer 3: custom overrides ─────────────────────────────────────────────
+  if (input.customOverrides) {
+    const { displayFont, bodyFont, ...colorOverrides } = input.customOverrides;
+    colors = { ...colors, ...colorOverrides };
+    if (displayFont) fonts.displayFont = displayFont;
+    if (bodyFont)    fonts.bodyFont    = bodyFont;
+  }
+
+  // Build resolved meta
+  const hasKit    = !!input.kitSeed;
+  const hasCustm  = !!input.customOverrides;
+  const resolvedId = hasKit || hasCustm
+    ? `${input.catalogId ?? DEFAULT_ID}+${hasKit ? 'kit' : ''}${hasCustm ? '+custom' : ''}`
+    : (input.catalogId ?? DEFAULT_ID);
+
+  return {
+    meta: {
+      ...base.meta,
+      id: resolvedId,
+    },
+    colors,
+    fonts,
+  };
+}

package/src/stores/font-size.svelte.ts

@@ -0,0 +1,158 @@
+/**
+ * @module stores/font-size.svelte
+ * @description Svelte 5 font size store for content and interface scale control.
+ *
+ * Manages two independent font size settings:
+ * - `contentSize` — editor text, preview panels, chat messages (default 14px)
+ * - `interfaceSize` — docks, explorers, UI labels (default 13px)
+ *
+ * Persists to localStorage and injects `--font-size-content` and
+ * `--font-size-interface` CSS custom properties on `document.documentElement`.
+ *
+ * Ported from Workshop's `src/lib/stores/fontSizeStore.ts` (legacy Svelte writable)
+ * to Svelte 5 runes. API-compatible replacement.
+ *
+ * @example
+ * ```ts
+ * import { createFontSizeStore } from '@soulcraft/theme/stores/font-size.svelte';
+ * export const fontSizeStore = createFontSizeStore();
+ *
+ * // In a component:
+ * fontSizeStore.setContentSize(16);
+ * ```
+ */
+
+const isBrowser = typeof window !== 'undefined';
+const STORAGE_KEY = 'workshop:fontSizes';
+
+/** The two independently-controllable font size axes. */
+export interface FontSizeSettings {
+  /** Font size in px for editor, preview, and chat content areas. @default 14 */
+  contentSize: number;
+  /** Font size in px for dock labels, explorer items, and UI chrome. @default 13 */
+  interfaceSize: number;
+}
+
+const DEFAULTS: FontSizeSettings = { contentSize: 14, interfaceSize: 13 };
+
+/** Preset options shown in the FontSizeControl picker UI. */
+export const FONT_SIZE_PRESETS = {
+  content: [
+    { label: 'Small', value: 12 },
+    { label: 'Medium (default)', value: 14 },
+    { label: 'Large', value: 16 },
+    { label: 'X-Large', value: 18 },
+  ],
+  interface: [
+    { label: 'Small', value: 11 },
+    { label: 'Medium (default)', value: 13 },
+    { label: 'Large', value: 15 },
+    { label: 'X-Large', value: 17 },
+  ],
+} as const;
+
+/** Load persisted settings from localStorage, falling back to defaults. */
+function loadSettings(): FontSizeSettings {
+  if (!isBrowser) return DEFAULTS;
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      const parsed = JSON.parse(stored) as Partial<FontSizeSettings>;
+      return {
+        contentSize:   parsed.contentSize   ?? DEFAULTS.contentSize,
+        interfaceSize: parsed.interfaceSize ?? DEFAULTS.interfaceSize,
+      };
+    }
+  } catch {
+    // Corrupted localStorage — use defaults
+  }
+  return DEFAULTS;
+}
+
+/**
+ * Reactive font size store using Svelte 5 runes.
+ */
+class FontSizeStore {
+  /** Content area font size in px. Reactive; changes trigger CSS var update. */
+  contentSize  = $state<number>(DEFAULTS.contentSize);
+  /** Interface chrome font size in px. Reactive; changes trigger CSS var update. */
+  interfaceSize = $state<number>(DEFAULTS.interfaceSize);
+
+  constructor() {
+    const saved = loadSettings();
+    this.contentSize   = saved.contentSize;
+    this.interfaceSize = saved.interfaceSize;
+    this.applyCSSVariables(saved);
+  }
+
+  /**
+   * Set the content area font size and persist.
+   * @param size - Font size in pixels.
+   */
+  setContentSize(size: number): void {
+    this.contentSize = size;
+    const settings = { contentSize: size, interfaceSize: this.interfaceSize };
+    this.applyCSSVariables(settings);
+    this.saveSettings(settings);
+  }
+
+  /**
+   * Set the interface chrome font size and persist.
+   * @param size - Font size in pixels.
+   */
+  setInterfaceSize(size: number): void {
+    this.interfaceSize = size;
+    const settings = { contentSize: this.contentSize, interfaceSize: size };
+    this.applyCSSVariables(settings);
+    this.saveSettings(settings);
+  }
+
+  /**
+   * Reset both sizes to their defaults and persist.
+   */
+  reset(): void {
+    this.contentSize   = DEFAULTS.contentSize;
+    this.interfaceSize = DEFAULTS.interfaceSize;
+    this.applyCSSVariables(DEFAULTS);
+    this.saveSettings(DEFAULTS);
+  }
+
+  /** Return current settings as a plain object. */
+  get current(): FontSizeSettings {
+    return { contentSize: this.contentSize, interfaceSize: this.interfaceSize };
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────
+
+  private applyCSSVariables(s: FontSizeSettings): void {
+    if (!isBrowser) return;
+    document.documentElement.style.setProperty('--font-size-content',   `${s.contentSize}px`);
+    document.documentElement.style.setProperty('--font-size-interface', `${s.interfaceSize}px`);
+  }
+
+  private saveSettings(s: FontSizeSettings): void {
+    if (!isBrowser) return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(s));
+    } catch {
+      // localStorage unavailable — ignore
+    }
+  }
+}
+
+/**
+ * Create a FontSizeStore instance.
+ *
+ * @returns A reactive Svelte 5 FontSizeStore.
+ *
+ * @example
+ * ```ts
+ * export const fontSizeStore = createFontSizeStore();
+ * fontSizeStore.setContentSize(16);
+ * ```
+ */
+export function createFontSizeStore(): FontSizeStore {
+  return new FontSizeStore();
+}
+
+export type { FontSizeStore };