@motion-proto/live-tokens 0.1.1 → 0.3.2

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);
+    }
+  }
+}

package/src/lib/themeService.ts

@@ -0,0 +1,101 @@
+import { tick } from 'svelte';
+import type { Theme, ThemeMeta } from './themeTypes';
+import type { EditorState } from './editorTypes';
+import {
+  versionedFileResource,
+  sanitizeFileName as sanitizeFileNameImpl,
+} from './files/versionedFileResource';
+import { loadFromFile as loadEditorState, toTheme, markSaved } from './editorStore';
+import { activeFileName } from './editorConfigStore';
+import { applyFontSources, applyFontStacks } from './fontLoader';
+import { migrateThemeFonts } from './fontMigration';
+
+// ── API helpers ──────────────────────────────────────────────
+//
+// All theme CRUD goes through `versionedFileResource('/api/themes')` —
+// shared with `componentConfigService`'s per-component clients. Theme-specific
+// response shapes (ThemeMeta list payload, ProductionInfo) are layered on top
+// via the generic type parameters.
+
+export interface ProductionInfo {
+  fileName: string;
+  name: string;
+  updatedAt: string;
+  cssVariables: Record<string, string>;
+}
+
+const themeResource = versionedFileResource<Theme, ThemeMeta, ProductionInfo>({
+  baseUrl: '/api/themes',
+});
+
+export async function listThemes(): Promise<ThemeMeta[]> {
+  const data = await themeResource.list();
+  return data.files;
+}
+
+export const loadTheme = (fileName: string): Promise<Theme> => themeResource.load(fileName);
+export const saveTheme = (fileName: string, data: Theme): Promise<void> =>
+  themeResource.save(fileName, data);
+export const deleteTheme = (fileName: string): Promise<void> => themeResource.remove(fileName);
+
+export async function getActiveTheme(): Promise<Theme | null> {
+  return themeResource.getActive();
+}
+
+export const setActiveFile = (fileName: string): Promise<void> => themeResource.setActive(fileName);
+
+// ── Production API helpers ─────────────────────────────────
+
+export const getProductionInfo = (): Promise<ProductionInfo> => themeResource.getProductionInfo();
+
+export async function setProductionFile(
+  fileName: string,
+): Promise<{ ok: boolean; fileName: string; name: string }> {
+  const data = await themeResource.setProduction(fileName);
+  return { ok: data.ok, fileName: data.fileName, name: data.name };
+}
+
+/** Sanitize a display name to a safe file name. Re-exported from the shared
+ * `files/versionedFileResource` so the dev-server plugin can import the
+ * canonical pure helper without depending on this module's CSS imports. */
+export const sanitizeFileName = sanitizeFileNameImpl;
+
+// ── Theme save/load orchestration ──────────────────────────
+//
+// `persistTheme` and `hydrateTheme` are the canonical entry points for
+// round-tripping editor state to disk. Callers (e.g. `EditorShell`) need
+// only handle UI-level concerns (status flashing, error chrome) and
+// delegate the actual orchestration here.
+
+/** Snapshot the editor state to disk under `fileName`, mark the file active,
+ *  and clear the dirty flag. The caller is responsible for surfacing
+ *  saving / saved / error UI states around this call. */
+export async function persistTheme(
+  state: EditorState,
+  fileName: string,
+  displayName: string,
+): Promise<void> {
+  await tick();
+  const theme = toTheme(state, { name: displayName });
+  await saveTheme(fileName, theme);
+  await setActiveFile(fileName);
+  activeFileName.set(fileName);
+  markSaved();
+}
+
+/** Load a theme file into the editor state and re-apply font side-effects
+ *  (@font-face rules + `--font-*` CSS vars on :root). */
+export async function hydrateTheme(fileName: string): Promise<void> {
+  const theme = await loadTheme(fileName);
+  migrateThemeFonts(theme);
+  loadEditorState(theme);
+  // Font data is in state.fonts via loadEditorState; the DOM-side-effect
+  // helpers still need to run so @font-face rules and --font-* CSS vars
+  // land on :root.
+  if (theme.fontSources && theme.fontSources.length > 0) {
+    applyFontSources(theme.fontSources);
+  }
+  if (theme.fontStacks && theme.fontStacks.length > 0) {
+    applyFontStacks(theme.fontStacks, theme.fontSources ?? []);
+  }
+}

package/src/lib/themeTypes.ts

@@ -0,0 +1,146 @@
+import type { CurveAnchor } from '../ui/curveEngine';
+
+export type GradientStyle = 'linear' | 'radial' | 'conic';
+
+export interface GradientStop {
+  position: number;
+  paletteLabel: string;
+}
+
+export interface PaletteConfig {
+  baseColor: string;
+  tintHue: number;
+  tintChroma?: number;
+  lightnessCurve: CurveAnchor[];
+  saturationCurve: CurveAnchor[];
+  grayLightnessCurve: CurveAnchor[];
+  graySaturationCurve: CurveAnchor[];
+  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>;
+  curveOffset: Record<string, number>;
+  overrides: Record<string, string>;
+  snappedScales: string[];
+  emptyMode?: 'solid' | 'gradient';
+  emptyStep?: string;
+  gradientStyle?: GradientStyle;
+  gradientAngle?: number;
+  gradientReverse?: boolean;
+  gradientStops?: GradientStop[];
+  gradientSize?: 'page' | 'window';
+  anchorToBase?: boolean;
+}
+
+export type FontSourceKind = 'google' | 'typekit' | 'css-url' | 'font-face';
+
+export interface FontFamily {
+  id: string;
+  name: string;
+  cssName: string;
+  weights?: number[];
+  italics?: boolean;
+}
+
+export interface FontSource {
+  id: string;
+  kind: FontSourceKind;
+  url?: string;
+  cssText?: string;
+  families: FontFamily[];
+  label?: string;
+}
+
+export type SystemCascadePreset = 'system-ui-sans' | 'system-ui-serif' | 'system-ui-mono';
+export type GenericFamily = 'sans-serif' | 'serif' | 'monospace' | 'cursive' | 'fantasy';
+export type FontStackVariable = '--font-display' | '--font-sans' | '--font-serif' | '--font-mono';
+
+export type FontStackSlot =
+  | { kind: 'project'; familyId: string }
+  | { kind: 'system'; preset: SystemCascadePreset }
+  | { kind: 'generic'; value: GenericFamily };
+
+export interface FontStack {
+  variable: FontStackVariable;
+  slots: FontStackSlot[];
+}
+
+export interface Theme {
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  editorConfigs: Record<string, PaletteConfig>;
+  cssVariables: Record<string, string>;
+  fontSources?: FontSource[];
+  fontStacks?: FontStack[];
+  /**
+   * Server-attached file-name marker for round-tripping the file identity
+   * back to the client. Set by `themeFileApi`'s GET handlers; read by
+   * `themeInit` to seed `activeFileName`. Optional and not persisted to disk.
+   */
+  _fileName?: string;
+  /**
+   * Migration stamp. Absent on legacy files, treated as 0; the loader runs
+   * any registered theme migrations whose `fromVersion >= file.schemaVersion`.
+   * Save paths stamp the current value so resaved files skip past
+   * migrations.
+   */
+  schemaVersion?: number;
+}
+
+export interface ThemeMeta {
+  name: string;
+  fileName: string;
+  updatedAt: string;
+  isActive: boolean;
+}
+
+export interface ComponentConfig {
+  name: string;
+  component: string;
+  createdAt: string;
+  updatedAt: string;
+  aliases: Record<string, string>;
+  config?: Record<string, unknown>;
+  /**
+   * Server-attached file-name marker. Same role as `Theme._fileName`. Set by
+   * the component-configs GET handlers; not persisted to disk.
+   */
+  _fileName?: string;
+  /**
+   * Migration stamp. Absent on legacy files, treated as 0. See `Theme.schemaVersion`.
+   */
+  schemaVersion?: number;
+}
+
+export interface ComponentConfigMeta {
+  name: string;
+  fileName: string;
+  updatedAt: string;
+  isActive: boolean;
+  isProduction: boolean;
+}
+
+/**
+ * Manifest that captures an entire site state — the active theme plus the
+ * active config for every component. Loading a preset flips the relevant
+ * `_active.json` pointers; the underlying theme + component-config files stay
+ * the source of truth, so editing them flows through any preset that
+ * references them.
+ */
+export interface Preset {
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  /** File basename (no `.json`) of the theme this preset pins. */
+  theme: string;
+  /** Map of componentId → config file basename. Components omitted here fall
+   *  back to "default" at apply time. */
+  componentConfigs: Record<string, string>;
+  /** Server-attached file-name marker. Same role as `Theme._fileName`. */
+  _fileName?: string;
+}
+
+export interface PresetMeta {
+  name: string;
+  fileName: string;
+  updatedAt: string;
+  isActive: boolean;
+}