@motion-proto/live-tokens 0.1.1 → 0.3.2

package/src/lib/slices/components.ts

@@ -0,0 +1,362 @@
+/**
+ * Components slice — per-component `{ activeFile, aliases, config, unlinked? }`.
+ *
+ * `aliases` are the typed component-token → semantic-token map (each entry is
+ * a `CssVarRef` discriminated union: `{ kind: 'token', name }` or
+ * `{ kind: 'literal', value }`). The renderer emits each alias entry as
+ * `var(<name>)` for tokens or as the raw literal for literals.
+ *
+ * `config` carries literal-valued knobs that don't follow the alias →
+ * `var(...)` shape (e.g. `--dialog-confirm-variant: 'primary'`). The set of
+ * keys routed to config lives in `componentConfigKeys`.
+ *
+ * Themes and components are orthogonal: `loadFromFile` preserves
+ * `state.components`.
+ *
+ * Sharing semantics: tokens with the same groupKey (registered explicitly
+ * via `registerComponentSchema`) are siblings. Each individual sibling can opt out of the group: `unlinked`
+ * lists the specific variable names that have detached, leaving the rest
+ * of the group intact. `setComponentAliasLinked` writes the alias to every
+ * sibling that is *currently linked* (i.e. not in `unlinked`) plus the
+ * target itself, re-joining it to the group; `unlinkComponentProperty`
+ * detaches just that one variable. The `unlinked` list persists across
+ * theme loads.
+ *
+ * Dirty tracking: `savedComponents` is the on-disk snapshot baseline (one
+ * stringified `{aliases, config}` bag per component). `componentDirty`
+ * re-evaluates on any state change or baseline bump. The baseline is set
+ * explicitly by the load path (`setSavedComponentBaseline`) — `loadComponentActive`
+ * and `seedComponentsFromApi` in editorStore call into this from their migration
+ * pipeline.
+ */
+import { writable, derived, get, type Readable } from 'svelte/store';
+import type { CssVarRef, EditorState } from '../editorTypes';
+import { store, mutate } from '../editorCore';
+
+const EMPTY_COMPONENT_BASELINE = JSON.stringify({ aliases: {}, config: {} });
+
+export function componentBaseline(slice: { aliases: Record<string, CssVarRef>; config: Record<string, unknown> }): string {
+  return JSON.stringify({ aliases: slice.aliases, config: slice.config });
+}
+
+export function componentsToVars(components: EditorState['components']): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const slice of Object.values(components)) {
+    for (const [varName, ref] of Object.entries(slice.aliases)) {
+      out[varName] = ref.kind === 'token' ? `var(${ref.name})` : ref.value;
+    }
+  }
+  return out;
+}
+
+export function getComponentOwnedVarNames(state: EditorState): string[] {
+  const names: string[] = [];
+  for (const slice of Object.values(state.components)) {
+    for (const name of Object.keys(slice.aliases)) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * Loader: themes and components are orthogonal — component aliases live
+ * in their own files, not the theme JSON. Preserve the current slice
+ * across theme loads and strip any component-owned vars that may have
+ * leaked into the theme's cssVariables bag. Mutates `next` and `rawVars`
+ * in place.
+ */
+export function loadComponentsFromVars(
+  next: EditorState,
+  rawVars: Record<string, string>,
+): void {
+  next.components = structuredClone(get(store).components);
+  for (const name of getComponentOwnedVarNames(next)) delete rawVars[name];
+}
+
+// Module-private baseline for per-component dirty detection. Parallels
+// `savedAtIndex` + `historyTick` for the global flag; `componentSavedTick`
+// drives re-derivation when the baseline changes.
+const savedComponents: Record<string, string> = {};
+const componentSavedTick = writable(0);
+function bumpComponentSavedTick(): void { componentSavedTick.update((n) => n + 1); }
+
+export const componentDirty: Readable<Record<string, boolean>> = derived(
+  [store, componentSavedTick],
+  ([$state]) => {
+    const out: Record<string, boolean> = {};
+    for (const [comp, slice] of Object.entries($state.components)) {
+      out[comp] = componentBaseline(slice) !== (savedComponents[comp] ?? EMPTY_COMPONENT_BASELINE);
+    }
+    return out;
+  },
+);
+
+export function setComponentAlias(component: string, varName: string, ref: CssVarRef): void {
+  mutate(`set alias ${component}/${varName}`, (s) => {
+    const existing = s.components[component];
+    if (existing) {
+      existing.aliases[varName] = ref;
+    } else {
+      s.components[component] = { activeFile: 'default', aliases: { [varName]: ref }, config: {} };
+    }
+  });
+}
+
+export function clearComponentAlias(component: string, varName: string): void {
+  mutate(`clear alias ${component}/${varName}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    delete slice.aliases[varName];
+  });
+}
+
+export function setComponentConfig(component: string, key: string, value: unknown): void {
+  mutate(`set config ${component}/${key}`, (s) => {
+    const existing = s.components[component];
+    if (existing) {
+      existing.config[key] = value;
+    } else {
+      s.components[component] = { activeFile: 'default', aliases: {}, config: { [key]: value } };
+    }
+  });
+}
+
+export function clearComponentConfig(component: string, key: string): void {
+  mutate(`clear config ${component}/${key}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    delete slice.config[key];
+  });
+}
+
+function componentVarPrefix(component: string): string {
+  return `--${component}-`;
+}
+
+/**
+ * Per-component groupKey schema registered by editor modules. Maps each
+ * declared variable to its groupKey (the explicit sibling-set identifier).
+ * Tokens with the same groupKey are siblings; tokens not in the schema fall
+ * back to last-dash property inference so unmigrated editors keep working.
+ */
+const componentSchemas: Record<string, Map<string, string>> = {};
+/** Inverse of `componentSchemas`: groupKey → declared variables sharing it.
+ *  This is the linkage topology declared by the editor, independent of which
+ *  aliases the user happens to have saved. */
+const componentSchemaSiblings: Record<string, Map<string, string[]>> = {};
+
+const TYPOGRAPHY_PROP_SUFFIXES = ['font-family', 'font-size', 'font-weight', 'line-height'] as const;
+
+/** Pull the slot identifier off a typography variable name, e.g.
+ *  `--card-primary-title-font-family` → `'title'`. Returns null for
+ *  non-typography vars, where the slot concept doesn't apply. */
+function typographySlotOf(varName: string): string | null {
+  for (const suffix of TYPOGRAPHY_PROP_SUFFIXES) {
+    if (!varName.endsWith('-' + suffix)) continue;
+    const head = varName.slice(0, -(suffix.length + 1));
+    const lastDash = head.lastIndexOf('-');
+    if (lastDash < 0) return null;
+    return head.slice(lastDash + 1);
+  }
+  return null;
+}
+
+/**
+ * Register a component's token → groupKey mapping. Editors call this at
+ * module load (top of `<script>`) so sibling lookups can prefer explicit
+ * groupKeys over name-derived inference. Re-registration overwrites prior
+ * entries for the same component.
+ *
+ * Warns when a single groupKey covers typography variables whose name-derived
+ * slots differ — e.g. `groupKey: 'font-family'` covering both
+ * `--card-primary-title-font-family` and `--card-primary-body-font-family`.
+ * Slot prefixes (`title-font-family` vs `body-font-family`) are required so
+ * each slot is independently linkable. See `src/styles/CONVENTIONS.md`.
+ */
+export function registerComponentSchema(
+  component: string,
+  tokens: ReadonlyArray<{ variable: string; groupKey?: string }>,
+): void {
+  const map = new Map<string, string>();
+  const siblings = new Map<string, string[]>();
+  for (const t of tokens) {
+    if (!t.groupKey) continue;
+    map.set(t.variable, t.groupKey);
+    const list = siblings.get(t.groupKey) ?? [];
+    list.push(t.variable);
+    siblings.set(t.groupKey, list);
+  }
+  componentSchemas[component] = map;
+  componentSchemaSiblings[component] = siblings;
+
+  for (const [groupKey, vars] of siblings) {
+    const slots = new Set<string>();
+    for (const v of vars) {
+      const slot = typographySlotOf(v);
+      if (slot) slots.add(slot);
+    }
+    if (slots.size > 1) {
+      const slotList = [...slots];
+      const examples = slotList.map((s) => `"${s}-${groupKey}"`).join(', ');
+      console.warn(
+        `[registerComponentSchema] component "${component}" groupKey "${groupKey}" links typography variables with distinct slots: ${slotList.join(', ')}. ` +
+          `Use slot-prefixed groupKeys (e.g. ${examples}) so each slot is independently linkable.`,
+      );
+    }
+  }
+}
+
+/**
+ * Resolve a variable's groupKey from the component's registered schema.
+ * Returns null when the variable has no declared groupKey (i.e. it isn't a
+ * member of any sibling group).
+ */
+function getGroupKey(component: string, varName: string): string | null {
+  return componentSchemas[component]?.get(varName) ?? null;
+}
+
+/**
+ * Variables that share `varName`'s groupKey, i.e. are declared as one
+ * linkage group. The editor's registered schema is the source of truth — the
+ * declared topology is reported regardless of which aliases happen to be
+ * persisted in the slice, so link UI reflects the editor's intent rather than
+ * leaking through the on-disk state. Falls back to a slice scan only when the
+ * variable isn't declared (legacy/inferred groupKey).
+ */
+export function getComponentPropertySiblings(component: string, varName: string): string[] {
+  const groupKey = getGroupKey(component, varName);
+  if (!groupKey) return [];
+  const declared = componentSchemaSiblings[component]?.get(groupKey);
+  if (declared && declared.length > 0) return declared.slice();
+  const slice = get(store).components[component];
+  if (!slice) return [];
+  const siblings: string[] = [];
+  for (const v of Object.keys(slice.aliases)) {
+    if (getGroupKey(component, v) === groupKey) siblings.push(v);
+  }
+  return siblings;
+}
+
+function cssVarRefEqual(a: CssVarRef | undefined, b: CssVarRef | undefined): boolean {
+  if (!a || !b) return a === b;
+  if (a.kind !== b.kind) return false;
+  return a.kind === 'token'
+    ? a.name === (b as { kind: 'token'; name: string }).name
+    : a.value === (b as { kind: 'literal'; value: string }).value;
+}
+
+/** True iff `varName` is not individually opted out, has ≥2 declared siblings,
+ *  and the linked siblings agree — either all sharing the same explicit alias,
+ *  or all having no override (linked at the upstream default). */
+export function isComponentPropertyLinked(component: string, varName: string): boolean {
+  const slice = get(store).components[component];
+  if (slice?.unlinked?.includes(varName)) return false;
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (siblings.length < 2) return false;
+  const unlinkedList = slice?.unlinked ?? [];
+  const linkedSiblings = siblings.filter((v) => !unlinkedList.includes(v));
+  if (linkedSiblings.length < 2) return false;
+  const aliases = slice?.aliases ?? {};
+  const first = aliases[linkedSiblings[0]];
+  return linkedSiblings.every((v) => cssVarRefEqual(aliases[v], first));
+}
+
+/** Write `ref` to `varName` and every sibling currently linked (not in `unlinked`),
+ *  and remove `varName` from the unlinked list so it rejoins the group. */
+export function setComponentAliasLinked(component: string, varName: string, ref: CssVarRef): void {
+  const groupKey = getGroupKey(component, varName);
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (!groupKey || siblings.length === 0) {
+    setComponentAlias(component, varName, ref);
+    return;
+  }
+  mutate(`link ${component}/${groupKey}`, (s) => {
+    const slice = s.components[component] ?? (s.components[component] = { activeFile: 'default', aliases: {}, config: {} });
+    const unlinked = (slice.unlinked ?? []).filter((p) => p !== varName);
+    slice.aliases[varName] = ref;
+    for (const v of siblings) {
+      if (v === varName) continue;
+      if (!unlinked.includes(v)) slice.aliases[v] = ref;
+    }
+    if (unlinked.length === 0) delete slice.unlinked;
+    else slice.unlinked = unlinked;
+  });
+}
+
+/** Clear `varName` and every sibling currently linked (not in `unlinked`). */
+export function clearComponentAliasLinked(component: string, varName: string): void {
+  const groupKey = getGroupKey(component, varName);
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (!groupKey || siblings.length === 0) {
+    clearComponentAlias(component, varName);
+    return;
+  }
+  mutate(`clear link ${component}/${groupKey}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    const unlinked = slice.unlinked ?? [];
+    for (const v of siblings) {
+      if (v === varName || !unlinked.includes(v)) delete slice.aliases[v];
+    }
+  });
+}
+
+/** Detach a single property from its sibling group. Other siblings stay linked
+ *  to each other; only `varName` becomes independently editable. */
+export function unlinkComponentProperty(component: string, varName: string): void {
+  const groupKey = getGroupKey(component, varName);
+  if (!groupKey) return;
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (siblings.length < 2) return;
+  mutate(`unlink ${component}/${varName}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    const unlinked = slice.unlinked ?? [];
+    if (!unlinked.includes(varName)) {
+      slice.unlinked = [...unlinked, varName];
+    }
+  });
+}
+
+/** Rejoin `varName` to its sibling group as pure metadata: drop it from the
+ *  `unlinked` list without writing any alias. Use when the group has no
+ *  overrides yet (linked at the upstream default) and the user just wants to
+ *  re-engage membership — `setComponentAliasLinked` requires a ref to write,
+ *  which there is none of in that state. */
+export function relinkComponentProperty(component: string, varName: string): void {
+  const slice = get(store).components[component];
+  if (!slice?.unlinked?.includes(varName)) return;
+  mutate(`relink ${component}/${varName}`, (s) => {
+    const next = s.components[component];
+    if (!next?.unlinked) return;
+    const remaining = next.unlinked.filter((v) => v !== varName);
+    if (remaining.length === 0) delete next.unlinked;
+    else next.unlinked = remaining;
+  });
+}
+
+export function markComponentSaved(component: string): void {
+  const slice = get(store).components[component];
+  if (!slice) return;
+  savedComponents[component] = componentBaseline(slice);
+  bumpComponentSavedTick();
+}
+
+/**
+ * Set the on-disk baseline for a component without touching the store.
+ * Called by `loadComponentActive` / `seedComponentsFromApi` after their
+ * migration step so the post-load state reads clean.
+ */
+export function setSavedComponentBaseline(component: string, baseline: string): void {
+  savedComponents[component] = baseline;
+}
+
+/** Notify subscribers that the dirty baseline changed. */
+export function notifyComponentSavedChanged(): void {
+  bumpComponentSavedTick();
+}
+
+/** Test-only: clear the baseline and the dirty signal. */
+export function __resetComponentsForTests(): void {
+  for (const k of Object.keys(savedComponents)) delete savedComponents[k];
+  bumpComponentSavedTick();
+}

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