@motion-proto/live-tokens 0.1.0 → 0.3.1

package/src/lib/slices/domainVars.ts

@@ -0,0 +1,15 @@
+/**
+ * Aggregated CSS-var names owned by store domains. Consumers that scrape
+ * the DOM (e.g. the save flow still pulling palette ramps emitted by
+ * PaletteEditor) use this to drop domain-owned keys from their scraped bag
+ * so the store stays the single source of truth.
+ */
+import { COLUMN_VAR_NAMES } from './columns';
+import { OVERLAY_VAR_NAMES } from './overlays';
+import { SHADOW_VAR_NAMES } from './shadows';
+
+export const DOMAIN_VAR_NAMES: readonly string[] = [
+  ...COLUMN_VAR_NAMES,
+  ...OVERLAY_VAR_NAMES,
+  ...SHADOW_VAR_NAMES,
+];

package/src/lib/slices/fonts.ts

@@ -0,0 +1,30 @@
+/**
+ * Fonts slice — sources + stacks. No derived CSS vars owned by this store
+ * (the `--font-*` vars are written by `applyFontStacks` in fontLoader, and
+ * @font-face rules by `applyFontSources`). We own the *data* (sources +
+ * stacks); callers still invoke the DOM-side-effect helpers themselves
+ * after mutating.
+ */
+import type { FontSource, FontStack } from '../themeTypes';
+import { store, mutate, persist } from '../editorCore';
+
+export function setFontSources(sources: FontSource[]): void {
+  mutate('update font sources', (s) => { s.fonts.sources = sources; });
+}
+
+export function setFontStacks(stacks: FontStack[]): void {
+  mutate('update font stacks', (s) => { s.fonts.stacks = stacks; });
+}
+
+/**
+ * Populate fonts from the server's active theme at boot. Does not push
+ * a history entry — the boot load is a starting point, not an edit.
+ */
+export function seedFontsFromTheme(sources: FontSource[], stacks: FontStack[]): void {
+  store.update((s) => {
+    s.fonts.sources = structuredClone(sources);
+    s.fonts.stacks = structuredClone(stacks);
+    return s;
+  });
+  persist();
+}

package/src/lib/slices/gradients.ts

@@ -0,0 +1,153 @@
+/**
+ * Gradients slice — fixed four-slot scale (--gradient-1 … --gradient-4),
+ * each rendering to a single CSS var. Stops carry token-name references
+ * (`--color-brand-500`); the renderer wraps them in `var(...)` so palette
+ * edits flow through.
+ */
+import type { EditorState, GradientToken, GradientTokenStop, GradientType } from '../editorTypes';
+import { mutate } from '../editorCore';
+
+export function makeDefaultGradients(): GradientToken[] {
+  return [
+    {
+      variable: '--gradient-1',
+      type: 'linear',
+      angle: 90,
+      stops: [
+        { position: 0, color: '--color-brand-500' },
+        { position: 100, color: '--color-accent-500' },
+      ],
+    },
+    {
+      variable: '--gradient-2',
+      type: 'linear',
+      angle: 135,
+      stops: [
+        { position: 0, color: '--color-brand-500' },
+        { position: 100, color: '--color-special-500' },
+      ],
+    },
+    {
+      variable: '--gradient-3',
+      type: 'linear',
+      angle: 90,
+      stops: [
+        { position: 0, color: '--color-success-500' },
+        { position: 100, color: '--color-info-500' },
+      ],
+    },
+    {
+      variable: '--gradient-4',
+      type: 'linear',
+      angle: 45,
+      stops: [
+        { position: 0, color: '--color-danger-500' },
+        { position: 100, color: '--color-warning-500' },
+      ],
+    },
+  ];
+}
+
+function formatGradientStop(s: GradientTokenStop): string {
+  const base = s.color.startsWith('--') ? `var(${s.color})` : s.color;
+  const opacity = s.opacity ?? 100;
+  const color = opacity >= 100
+    ? base
+    : `color-mix(in srgb, ${base} ${opacity}%, transparent)`;
+  return `${color} ${s.position}%`;
+}
+
+/** Stops portion only — used by the palette selector to materialize a
+ *  linear-gradient with a per-slot angle override while keeping the token's
+ *  stop list (and its `var(--color-…)` refs, which propagate palette edits). */
+export function formatGradientStops(t: GradientToken): string {
+  return t.stops.map(formatGradientStop).join(', ');
+}
+
+function formatGradient(t: GradientToken): string {
+  const stops = formatGradientStops(t);
+  if (t.type === 'linear') return `linear-gradient(${t.angle}deg, ${stops})`;
+  return `radial-gradient(${stops})`;
+}
+
+export function gradientsToVars(g: EditorState['gradients']): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const t of g.tokens) out[t.variable] = formatGradient(t);
+  return out;
+}
+
+function findGradient(s: EditorState, variable: string): GradientToken | undefined {
+  return s.gradients.tokens.find((t) => t.variable === variable);
+}
+
+/** Replace a gradient's type, angle, and stops in one shot. Used by the editor
+ *  to restore a pre-edit snapshot on Cancel. */
+export function setGradient(
+  variable: string,
+  next: { type: GradientType; angle: number; stops: GradientTokenStop[] },
+): void {
+  mutate(`replace gradient ${variable}`, (s) => {
+    const t = findGradient(s, variable);
+    if (!t) return;
+    t.type = next.type;
+    t.angle = next.angle;
+    t.stops = next.stops.map((st) => ({ ...st }));
+  });
+}
+
+export function setGradientType(variable: string, type: GradientType): void {
+  mutate(`set gradient type ${variable}`, (s) => {
+    const t = findGradient(s, variable);
+    if (t) t.type = type;
+  });
+}
+
+export function setGradientAngle(variable: string, angle: number): void {
+  mutate(`set gradient angle ${variable}`, (s) => {
+    const t = findGradient(s, variable);
+    if (t) t.angle = angle;
+  });
+}
+
+export function setGradientStop(variable: string, index: number, stop: Partial<GradientTokenStop>): void {
+  mutate(`set gradient stop ${variable}[${index}]`, (s) => {
+    const t = findGradient(s, variable);
+    if (!t || !t.stops[index]) return;
+    if (stop.position !== undefined) t.stops[index].position = stop.position;
+    if (stop.color !== undefined) t.stops[index].color = stop.color;
+    if (stop.opacity !== undefined) t.stops[index].opacity = stop.opacity;
+  });
+}
+
+export function addGradientStop(variable: string, stop: GradientTokenStop): void {
+  mutate(`add gradient stop ${variable}`, (s) => {
+    const t = findGradient(s, variable);
+    if (!t) return;
+    t.stops.push(stop);
+    t.stops.sort((a, b) => a.position - b.position);
+  });
+}
+
+export function removeGradientStop(variable: string, index: number): void {
+  mutate(`remove gradient stop ${variable}[${index}]`, (s) => {
+    const t = findGradient(s, variable);
+    if (!t || t.stops.length <= 2) return;
+    t.stops.splice(index, 1);
+  });
+}
+
+export function addGradientToken(token: GradientToken): void {
+  mutate(`add gradient ${token.variable}`, (s) => {
+    if (findGradient(s, token.variable)) return;
+    s.gradients.tokens.push({
+      ...token,
+      stops: token.stops.map((st) => ({ ...st })),
+    });
+  });
+}
+
+export function removeGradientToken(variable: string): void {
+  mutate(`remove gradient ${variable}`, (s) => {
+    s.gradients.tokens = s.gradients.tokens.filter((t) => t.variable !== variable);
+  });
+}

package/src/lib/slices/overlays.ts

@@ -0,0 +1,132 @@
+/**
+ * Overlays slice — overlay + hover RGBA tokens. Defaults are editor-defined
+ * (mirror what `VariablesTab` historically initialised into local let state)
+ * and diverge from tokens.css by design: the editor starts with a neutral
+ * palette and tokens.css continues to win until first edit.
+ */
+import type { EditorState, OverlayToken } from '../editorTypes';
+
+export function makeDefaultOverlayTokens(): OverlayToken[] {
+  return [
+    { variable: '--overlay-lowest', label: 'Lowest', r: 0, g: 0, b: 0, opacity: 0.05 },
+    { variable: '--overlay-lower',  label: 'Lower',  r: 0, g: 0, b: 0, opacity: 0.1  },
+    { variable: '--overlay-low',    label: 'Low',    r: 0, g: 0, b: 0, opacity: 0.2  },
+    { variable: '--overlay',        label: 'Base',   r: 0, g: 0, b: 0, opacity: 0.3  },
+    { variable: '--overlay-high',   label: 'High',   r: 0, g: 0, b: 0, opacity: 0.5  },
+    { variable: '--overlay-higher', label: 'Higher', r: 0, g: 0, b: 0, opacity: 0.7  },
+    { variable: '--overlay-highest',label: 'Highest',r: 0, g: 0, b: 0, opacity: 0.95 },
+  ];
+}
+
+export function makeDefaultHoverTokens(): OverlayToken[] {
+  return [
+    { variable: '--hover-low',  label: 'Low',  r: 255, g: 255, b: 255, opacity: 0.05 },
+    { variable: '--hover',      label: 'Base', r: 255, g: 255, b: 255, opacity: 0.1  },
+    { variable: '--hover-high', label: 'High', r: 255, g: 255, b: 255, opacity: 0.15 },
+  ];
+}
+
+export function makeDefaultOverlaysState(): EditorState['overlays'] {
+  return {
+    tokens: makeDefaultOverlayTokens(),
+    hoverTokens: makeDefaultHoverTokens(),
+    globals: {
+      overlay: { hue: 0, saturation: 0, lightness: 0, opacityMin: 0.05, opacityMax: 0.95 },
+      hover:   { hue: 0, saturation: 0, lightness: 100, opacityMin: 0.05, opacityMax: 0.15 },
+    },
+  };
+}
+
+export const OVERLAY_VAR_NAMES = [
+  '--overlay-lowest', '--overlay-lower', '--overlay-low', '--overlay',
+  '--overlay-high', '--overlay-higher', '--overlay-highest',
+  '--hover-low', '--hover', '--hover-high',
+] as const;
+
+// Accepts rgb(), rgba(), and #rrggbb[aa] — themes saved by the editor
+// always use rgba(), but loading hand-written files shouldn't break.
+export const RGBA_RE = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)/i;
+export const HEX_RE = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i;
+
+export function parseRgba(raw: string): { r: number; g: number; b: number; opacity: number } | null {
+  const s = raw.trim();
+  const m = s.match(RGBA_RE);
+  if (m) {
+    const r = parseInt(m[1], 10);
+    const g = parseInt(m[2], 10);
+    const b = parseInt(m[3], 10);
+    const a = m[4] !== undefined ? parseFloat(m[4]) : 1;
+    if (![r, g, b].every((n) => Number.isFinite(n) && n >= 0 && n <= 255)) return null;
+    return { r, g, b, opacity: Number.isFinite(a) ? a : 1 };
+  }
+  const h = s.match(HEX_RE);
+  if (h) {
+    const hex = h[1];
+    const alpha = h[2] !== undefined ? parseInt(h[2], 16) / 255 : 1;
+    return {
+      r: parseInt(hex.slice(0, 2), 16),
+      g: parseInt(hex.slice(2, 4), 16),
+      b: parseInt(hex.slice(4, 6), 16),
+      opacity: Math.round(alpha * 100) / 100,
+    };
+  }
+  return null;
+}
+
+export function overlayTokenToRgba(t: OverlayToken): string {
+  return `rgba(${t.r}, ${t.g}, ${t.b}, ${t.opacity})`;
+}
+
+export function overlaysToVars(o: EditorState['overlays']): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const t of o.tokens) out[t.variable] = overlayTokenToRgba(t);
+  for (const t of o.hoverTokens) out[t.variable] = overlayTokenToRgba(t);
+  return out;
+}
+
+function tokensEqualDefault(tokens: OverlayToken[], defaults: OverlayToken[]): boolean {
+  if (tokens.length !== defaults.length) return false;
+  for (let i = 0; i < tokens.length; i++) {
+    const a = tokens[i]; const b = defaults[i];
+    if (a.variable !== b.variable || a.r !== b.r || a.g !== b.g || a.b !== b.b || a.opacity !== b.opacity) return false;
+  }
+  return true;
+}
+
+/**
+ * Same pattern as columns: only emit overlay CSS vars once state diverges
+ * from the editor defaults. tokens.css owns the rgba values until the
+ * user touches any overlay control (or loads a theme that already
+ * contains overrides).
+ */
+export function overlaysEqualsDefault(o: EditorState['overlays']): boolean {
+  return tokensEqualDefault(o.tokens, makeDefaultOverlayTokens())
+    && tokensEqualDefault(o.hoverTokens, makeDefaultHoverTokens());
+}
+
+export function applyOverlayVarsToState(overlays: EditorState['overlays'], vars: Record<string, string>): void {
+  const applyTo = (list: OverlayToken[]) => {
+    for (const t of list) {
+      const raw = vars[t.variable];
+      if (!raw) continue;
+      const parsed = parseRgba(raw);
+      if (!parsed) continue;
+      t.r = parsed.r; t.g = parsed.g; t.b = parsed.b; t.opacity = parsed.opacity;
+    }
+  };
+  applyTo(overlays.tokens);
+  applyTo(overlays.hoverTokens);
+}
+
+/**
+ * Loader: route overlay/hover entries from a freshly-loaded theme's vars
+ * bag into `next.overlays` and remove them from the bag. Mutates `next`
+ * and `rawVars` in place.
+ */
+export function loadOverlaysFromVars(
+  next: EditorState,
+  rawVars: Record<string, string>,
+): void {
+  applyOverlayVarsToState(next.overlays, rawVars);
+  for (const name of OVERLAY_VAR_NAMES) delete rawVars[name];
+}

package/src/lib/slices/palettes.ts

@@ -0,0 +1,26 @@
+/**
+ * Palettes slice — each PaletteEditor instance is keyed by `label`
+ * (e.g. "Neutral", "Primary"). The store owns the full `PaletteConfig` for
+ * each label; CSS-var emission is still done by `paletteDerivation`
+ * (palette derivation involves OKLCH + bezier curves) at render time.
+ */
+import type { PaletteConfig } from '../themeTypes';
+import { store, mutate, persist } from '../editorCore';
+
+export function setPaletteConfig(label: string, config: PaletteConfig): void {
+  mutate(`update palette ${label}`, (s) => {
+    s.palettes[label] = config;
+  });
+}
+
+/**
+ * Server-boot path: populate all palettes at once without a history entry.
+ * Mirrors `seedFontsFromTheme`.
+ */
+export function seedPalettesFromTheme(palettes: Record<string, PaletteConfig>): void {
+  store.update((s) => {
+    s.palettes = structuredClone(palettes);
+    return s;
+  });
+  persist();
+}

package/src/lib/slices/shadows.ts

@@ -0,0 +1,123 @@
+/**
+ * Shadows slice — five-token scale (sm/md/lg/xl/2xl) plus globals/overrides
+ * for the editor UI's shared sliders. Defaults come from tokens.css (not the
+ * editor), so state.shadows starts with `tokens: []` and we do not emit any
+ * shadow CSS vars until the editor has populated tokens (via
+ * `seedShadowsFromDom` on hydrate, or via `loadFromFile`). Once tokens exist,
+ * the renderer writes one CSS var per token derived from its
+ * x/y/blur/spread/hsla fields.
+ */
+import { get } from 'svelte/store';
+import type { EditorState, ShadowToken } from '../editorTypes';
+import { store, persist } from '../editorCore';
+
+export const SHADOW_VAR_NAMES = [
+  '--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl', '--shadow-2xl',
+] as const;
+
+// Identical literal set as SHADOW_VAR_NAMES — derived to avoid drift.
+export const SCALE_SHADOW_VARIABLES: ReadonlySet<string> = new Set(SHADOW_VAR_NAMES);
+
+export function computeShadowXY(angle: number, distance: number): { x: number; y: number } {
+  const rad = angle * (Math.PI / 180);
+  return {
+    x: Math.round(-distance * Math.cos(rad)),
+    y: Math.round(distance * Math.sin(rad)),
+  };
+}
+
+function computeAngleDistance(x: number, y: number): { angle: number; distance: number } {
+  const distance = Math.round(Math.sqrt(x * x + y * y));
+  if (distance === 0) return { angle: 135, distance: 0 };
+  let angle = Math.atan2(y, -x) * (180 / Math.PI);
+  if (angle < 0) angle += 360;
+  return { angle: Math.round(angle), distance };
+}
+
+export function shadowTokenCss(t: ShadowToken): string {
+  return `${t.x}px ${t.y}px ${t.blur}px ${t.spread}px hsla(${t.hue}, ${t.saturation}%, ${t.lightness}%, ${t.opacity})`;
+}
+
+export function defaultShadowOverride(): import('../editorTypes').ShadowOverrideFlags {
+  return { angle: false, opacity: false, color: false, distance: false, blur: false, size: false };
+}
+
+export function parseShadowCss(variable: string, raw: string): ShadowToken | null {
+  const m = raw.trim().match(/^(-?\d+)px\s+(-?\d+)px\s+(\d+)px\s+(-?\d+)px\s+hsla\(([\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)$/);
+  if (!m) return null;
+  const x = parseInt(m[1], 10);
+  const y = parseInt(m[2], 10);
+  const blur = parseInt(m[3], 10);
+  const spread = parseInt(m[4], 10);
+  const hue = Math.round(parseFloat(m[5]));
+  const saturation = Math.round(parseFloat(m[6]));
+  const lightness = Math.round(parseFloat(m[7]));
+  const opacity = parseFloat(m[8]);
+  const { angle, distance } = computeAngleDistance(x, y);
+  return { variable, x, y, blur, spread, opacity, hue, saturation, lightness, angle, distance };
+}
+
+export function shadowsToVars(shadows: EditorState['shadows']): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const t of shadows.tokens) out[t.variable] = shadowTokenCss(t);
+  return out;
+}
+
+export function applyShadowVarsToState(shadows: EditorState['shadows'], vars: Record<string, string>): void {
+  const parsed: ShadowToken[] = [];
+  for (const name of SHADOW_VAR_NAMES) {
+    const raw = vars[name];
+    if (!raw) continue;
+    const tok = parseShadowCss(name, raw);
+    if (tok) parsed.push(tok);
+  }
+  if (parsed.length > 0) shadows.tokens = parsed;
+}
+
+/**
+ * Loader: route shadow scale tokens from a freshly-loaded theme's vars bag
+ * into `next.shadows.tokens` and remove them from the bag. Globals/overrides
+ * are preserved across theme loads from the *current* state — themes don't
+ * carry editor-UI state — so the caller copies them in. Mutates `next` and
+ * `rawVars` in place.
+ */
+export function loadShadowsFromVars(
+  next: EditorState,
+  rawVars: Record<string, string>,
+): void {
+  applyShadowVarsToState(next.shadows, rawVars);
+  for (const name of SHADOW_VAR_NAMES) delete rawVars[name];
+  // Preserve shadow globals/overrides across theme loads so the editor UI
+  // reopens with the same controls the user was working with.
+  const current = get(store).shadows;
+  next.shadows.globals = structuredClone(current.globals);
+  next.shadows.overrides = structuredClone(current.overrides);
+}
+
+/**
+ * Seed state.shadows.tokens from computed styles on the document element.
+ * Captures the tokens.css baseline so the editor can mutate it. Does NOT push
+ * a history entry; the seed is treated as an initial snapshot, not a user
+ * edit. Persists so a reload doesn't re-seed from the DOM on every fresh
+ * session.
+ *
+ * Called from the persistence layer's `hydrate()` so the seed lands once on
+ * boot regardless of whether the user opens the shadows tab — m13 cleanup.
+ */
+export function seedShadowsFromDom(): void {
+  if (typeof document === 'undefined') return;
+  const current = get(store);
+  if (current.shadows.tokens.length > 0) return;
+  const cs = getComputedStyle(document.documentElement);
+  const parsed: ShadowToken[] = [];
+  for (const name of SHADOW_VAR_NAMES) {
+    const raw = cs.getPropertyValue(name).trim();
+    if (!raw) continue;
+    const tok = parseShadowCss(name, raw);
+    if (tok) parsed.push(tok);
+  }
+  if (parsed.length === 0) return;
+  store.update((s) => { s.shadows.tokens = parsed; return s; });
+  // No bumpTick — seed is hydration-equivalent, not an edit.
+  persist();
+}

package/src/lib/storage.ts

@@ -0,0 +1,88 @@
+/**
+ * Helpers for operations that are *intentionally* allowed to fail silently:
+ * boot-time storage reads, debounced storage writes, and dev-server fetches.
+ *
+ * Naming the silence ("quietGet", "quietSet", "safeFetch") communicates intent
+ * better than scattered `try { ... } catch {}` blocks, where the empty catch
+ * leaves it ambiguous whether the author considered the failure mode or just
+ * copied a nearby pattern.
+ */
+
+interface QuietGetOptions {
+  /** When true, the stored string is parsed as JSON. Parse failures return null. */
+  parse?: boolean;
+}
+
+/**
+ * Read a value from `localStorage`. Returns `null` on:
+ * - Missing key
+ * - Storage unavailable (private/incognito mode, quota, browser disabled)
+ * - JSON parse failure (when `parse: true`)
+ *
+ * Boot-time hydrate paths can call this without a try/catch and trust that
+ * a fresh-boot fallback will be used when storage isn't reachable.
+ */
+export function quietGet<T = string>(
+  key: string,
+  opts?: QuietGetOptions,
+): T | string | null {
+  try {
+    if (typeof localStorage === 'undefined') return null;
+    const raw = localStorage.getItem(key);
+    if (raw === null) return null;
+    if (opts?.parse) {
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return null;
+      }
+    }
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a value to `localStorage`. Returns `true` on success, `false` if
+ * storage was unavailable or the write failed (quota, security errors).
+ *
+ * Callers that want to know whether the write landed can branch on the
+ * return value; callers that don't care can ignore it.
+ */
+export function quietSet(key: string, value: string): boolean {
+  try {
+    if (typeof localStorage === 'undefined') return false;
+    localStorage.setItem(key, value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Fetch a JSON resource. Returns `null` on:
+ * - Network failure (offline, dev-server not running)
+ * - Non-2xx response
+ * - JSON parse failure
+ *
+ * Used for boot-time API calls where the editor must continue working even
+ * if the dev-server's themeFileApi (or component-config endpoints) is not
+ * available — the caller falls through to defaults.
+ */
+export async function safeFetch<T = unknown>(
+  url: string,
+  opts?: RequestInit,
+): Promise<T | null> {
+  try {
+    const res = await fetch(url, opts);
+    if (!res.ok) return null;
+    try {
+      return (await res.json()) as T;
+    } catch {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}

package/src/lib/themeInit.ts

@@ -0,0 +1,74 @@
+import type { Theme } from './themeTypes';
+import { activeFileName } from './editorConfigStore';
+import { migrateThemeFonts } from './fontMigration';
+import { applyFontSources, applyFontStacks } from './fontLoader';
+import { loadFromFile, seedComponentsFromApi } from './editorStore';
+import { getActiveComponentConfig } from './componentConfigService';
+import { safeFetch } from './storage';
+
+interface ComponentSummaryDto {
+  name: string;
+  activeFile: string;
+  productionFile: string;
+}
+
+interface ListComponentsDto {
+  components: ComponentSummaryDto[];
+}
+
+/**
+ * Fetch the active theme from the server and apply its CSS variables
+ * to :root before the app mounts. Seeds the editor store so PaletteEditors
+ * initialize from the theme instead of stale localStorage.
+ *
+ * Routes the theme through `loadFromFile` so palette-derived vars in
+ * `deriveCssVars` correctly overwrite any stale hexes baked into
+ * `theme.cssVariables` by `handleSave`'s scrape. Writing
+ * `theme.cssVariables` directly to inline :root (the previous approach)
+ * bypassed the store and left the subscriber's `lastApplied` diff cache
+ * out of sync, so palette-derived values stayed stale until a
+ * `PaletteEditor` mounted and re-emitted them.
+ *
+ * Network/parse failures fall through silently — `tokens.css` provides
+ * defaults and the components slice stays empty until first edit. We use
+ * `safeFetch` (instead of empty try/catch) to make the silence intentional.
+ */
+export async function initializeTheme(): Promise<void> {
+  const theme = await safeFetch<Theme>('/api/themes/active');
+  if (theme) {
+    migrateThemeFonts(theme);
+    loadFromFile(theme);
+    if (theme.fontSources && theme.fontSources.length > 0) {
+      applyFontSources(theme.fontSources);
+    }
+    if (theme.fontStacks && theme.fontStacks.length > 0) {
+      applyFontStacks(theme.fontStacks, theme.fontSources ?? []);
+    }
+    const fileName = theme._fileName || 'default';
+    activeFileName.set(fileName);
+  }
+
+  const list = await safeFetch<ListComponentsDto>('/api/component-configs');
+  if (list && Array.isArray(list.components)) {
+    const configs: Record<
+      string,
+      { activeFile: string; aliases: Record<string, string>; config?: Record<string, unknown>; schemaVersion?: number }
+    > = {};
+    await Promise.all(
+      list.components.map(async (c) => {
+        const cfg = await getActiveComponentConfig(c.name);
+        if (cfg) {
+          configs[c.name] = {
+            activeFile: c.activeFile,
+            aliases: cfg.aliases,
+            config: cfg.config,
+            schemaVersion: cfg.schemaVersion,
+          };
+        }
+      }),
+    );
+    if (Object.keys(configs).length > 0) {
+      seedComponentsFromApi(configs);
+    }
+  }
+}