@motion-proto/live-tokens 0.1.1 → 0.3.2

package/src/lib/editorCore.ts

@@ -0,0 +1,402 @@
+/**
+ * State-core for the editor store.
+ *
+ * Owns the writable, history stacks (undo/redo), and the unified `Scope`
+ * primitive that brackets a series of mutations. Exposes `editorState`
+ * (Readable), `mutate` for unscoped one-shots, `transaction(label, fn)` for
+ * sync closure form, `beginSliderGesture(label)` for window-pointerup wiring,
+ * and the `beginScope/commitScope/cancelScope` trio for explicit handle-based
+ * scopes (the only form palette panels need). Domain slices import `mutate`
+ * and friends from here.
+ *
+ * The Scope primitive (M6 fold) — two orthogonal axes:
+ *  - `collapseToOne` — on commit, all intra-scope mutations collapse to a
+ *    single history entry (the pre-scope snapshot).
+ *  - `clipUndoFloor` — while the scope is active, undo() is clipped to the
+ *    scope's start; on commit, intra-scope past entries are dropped from
+ *    history so the snapshot becomes the single undo target.
+ *
+ * Mapping to use cases:
+ *  - `mutate`               — unscoped one-shot (no scope at all).
+ *  - drag gesture / atomic  — scope { collapseToOne: true,  clipUndoFloor: false }.
+ *  - palette panel session  — scope { collapseToOne: true,  clipUndoFloor: true  }.
+ *
+ * Two side-effect hooks are wired by `editorStore.ts` at boot:
+ *  - `setEmptyStateFactory` — produces a fresh state tree.
+ *  - `setPersistHook` — debounced localStorage write.
+ *
+ * Hooks are nullable on first import so the module evaluates cleanly even
+ * when consumed from contexts that don't need persistence (SSR, isolated
+ * unit tests).
+ */
+
+import { writable, derived, get, type Readable } from 'svelte/store';
+import type { EditorState } from './editorTypes';
+
+const HISTORY_MAX = 100;
+
+// ── Hooks (wired by editorStore at boot) ──────────────────────────────────
+
+let emptyStateFactory: () => EditorState = () => ({} as EditorState);
+let persistHook: () => void = () => {};
+
+export function setEmptyStateFactory(fn: () => EditorState): void {
+  emptyStateFactory = fn;
+}
+export function setPersistHook(fn: () => void): void {
+  persistHook = fn;
+}
+
+/** Trigger the persistence hook. Used by seed paths that bypass `mutate`. */
+export function persist(): void {
+  persistHook();
+}
+
+// ── Store + history machine ───────────────────────────────────────────────
+
+export const store = writable<EditorState>(emptyStateFactory());
+
+// History stacks hold snapshots that are independent of the current state
+// reference (always created via structuredClone at push time). This lets
+// mutate / undo / redo use in-place mutation on the live state without
+// corrupting history entries.
+const past: EditorState[] = [];
+const future: EditorState[] = [];
+let savedAtIndex = 0;
+
+// A counter that bumps on every history-affecting change, so `derived`
+// stores (canUndo, canRedo, dirty) re-evaluate. The history arrays
+// themselves live outside Svelte reactivity.
+const historyTick = writable(0);
+function bumpTick() { historyTick.update((n) => n + 1); }
+
+/** Push `entry` onto past[], handling overflow + clearing future. */
+function pushPast(entry: EditorState): void {
+  past.push(entry);
+  if (past.length > HISTORY_MAX) {
+    past.shift();
+    if (savedAtIndex > 0) savedAtIndex--;
+  }
+  future.length = 0;
+}
+
+// ── Scope primitive ───────────────────────────────────────────────────────
+
+/**
+ * A handle for a bracketed series of mutations. Returned by `beginScope` and
+ * passed back to `commitScope`/`cancelScope`. The shape is public but its
+ * fields are read-only from outside this module — callers treat it as an
+ * opaque ticket.
+ *
+ * Two orthogonal axes:
+ *  - collapseToOne: on commit, everything in the scope collapses to one
+ *    history entry (the pre-scope snapshot).
+ *  - clipUndoFloor: while the scope is active, undo() cannot pop past
+ *    entries pushed before the scope began; on commit, intra-scope past
+ *    entries are dropped (past.length = historyIdx).
+ */
+export interface Scope {
+  readonly snapshot: EditorState;
+  readonly label: string;
+  readonly collapseToOne: boolean;
+  readonly clipUndoFloor: boolean;
+  /** past.length captured at scope start — only consulted when clipUndoFloor. */
+  readonly historyIdx: number;
+  /** Set by `mutate()` when at least one mutation is applied within the scope. */
+  changed: boolean;
+}
+
+// Two scope slots: one for in-flight non-clipping scopes (drag gestures,
+// atomic edits), one for clipping scopes (palette edit sessions). They can
+// coexist — a slider drag inside an open palette session is the canonical
+// case — so they're tracked independently. `mutate` consults `transactionScope`
+// to suppress per-mutate pushes; `undo` consults `clippingScope` to enforce
+// the floor.
+let transactionScope: Scope | null = null;
+let clippingScope: Scope | null = null;
+
+/**
+ * Open a new scope. Returns a handle the caller passes back to
+ * `commitScope`/`cancelScope`. The handle's `clipUndoFloor` flag determines
+ * which internal slot the scope occupies; if a slot is already filled, the
+ * prior scope is auto-committed (transaction slot) or auto-committed
+ * (clipping slot) — matching the prior wrapper behavior.
+ */
+export function beginScope(opts: {
+  label: string;
+  collapseToOne: boolean;
+  clipUndoFloor: boolean;
+}): Scope {
+  const scope: Scope = {
+    snapshot: structuredClone(get(store)),
+    label: opts.label,
+    collapseToOne: opts.collapseToOne,
+    clipUndoFloor: opts.clipUndoFloor,
+    historyIdx: past.length,
+    changed: false,
+  };
+  if (opts.clipUndoFloor) {
+    if (clippingScope) commitScope(clippingScope);
+    clippingScope = scope;
+  } else {
+    if (transactionScope) {
+      if (import.meta.env.DEV) {
+        console.warn(
+          `[editorStore] beginScope("${opts.label}") while "${transactionScope.label}" is still open; aborting previous`,
+        );
+      }
+      cancelScope(transactionScope, { silent: true });
+    }
+    transactionScope = scope;
+  }
+  return scope;
+}
+
+/**
+ * Commit the given scope. If collapseToOne, all intra-scope past entries
+ * (those pushed since `historyIdx`) are dropped and the pre-scope snapshot
+ * is pushed in their place — but only if anything actually changed.
+ *
+ * "Did anything change" is computed by state-equality (JSON) when
+ * `clipUndoFloor` is set, because the scope's intra-scope mutations were
+ * applied to history AND then dropped — the only signal left is whether
+ * the live state still matches the snapshot. For non-clipping scopes,
+ * the `changed` flag is the source of truth: empty scopes skip the commit
+ * entirely.
+ */
+export function commitScope(scope: Scope): void {
+  // Clear the slot first so internal aborts triggered during commit don't
+  // recurse against the same scope.
+  if (scope.clipUndoFloor) {
+    if (clippingScope !== scope) return;
+    if (transactionScope) cancelScope(transactionScope, { silent: true });
+    clippingScope = null;
+  } else {
+    if (transactionScope !== scope) return;
+    transactionScope = null;
+  }
+
+  if (scope.collapseToOne) {
+    if (scope.clipUndoFloor) {
+      // Clipping path: intra-scope entries were each pushed by mutate()
+      // (they had to be, so undo within the scope could walk them back).
+      // On commit, drop them and push the pre-scope snapshot iff state is
+      // not back at the snapshot.
+      past.length = scope.historyIdx;
+      const snapshotJson = JSON.stringify(scope.snapshot);
+      const currentJson = JSON.stringify(get(store));
+      const changedByEquality = snapshotJson !== currentJson;
+      if (changedByEquality) {
+        pushPast(scope.snapshot);
+        persistHook();
+      }
+      bumpTick();
+      if (import.meta.env.DEV) {
+        console.debug('[editorStore] commitScope (clipping) →', {
+          label: scope.label,
+          pastLen: past.length,
+          snapshotPalettes: paletteSnapshot(scope.snapshot),
+          currentPalettes: paletteSnapshot(get(store)),
+        });
+      }
+      return;
+    }
+    // Non-clipping path: intra-scope mutations were applied to the store
+    // but NOT pushed individually. Push the pre-scope snapshot iff anything
+    // changed.
+    if (!scope.changed) return;
+    pushPast(scope.snapshot);
+    bumpTick();
+    persistHook();
+    return;
+  }
+  // Future: a non-collapsing scope would be a no-op on commit (entries
+  // already live in past[]). Not used today.
+  bumpTick();
+}
+
+/**
+ * Cancel the given scope. Always reverts state to the snapshot and drops
+ * intra-scope past entries. The `silent` flag controls whether the cancel
+ * surfaces as a tick + persist:
+ *  - silent: false (default) — used when the user aborts a scope
+ *    explicitly (e.g., palette panel X). Refreshes dirty + persist so the
+ *    UI reflects the discard.
+ *  - silent: true — used by internal auto-aborts (a stray transaction
+ *    being killed by undo() / by a competing scope). UI observes the state
+ *    revert, but `dirty` reflects the pre-scope position because no tick
+ *    fires and no persist runs.
+ */
+export function cancelScope(scope: Scope, opts?: { silent?: boolean }): void {
+  // Clear the slot first so any code observing the state revert doesn't see
+  // a stale "scope still open" view.
+  if (scope.clipUndoFloor) {
+    if (clippingScope !== scope) return;
+    if (transactionScope) cancelScope(transactionScope, { silent: true });
+    clippingScope = null;
+  } else {
+    if (transactionScope !== scope) return;
+    transactionScope = null;
+  }
+
+  past.length = scope.historyIdx;
+  if (scope.clipUndoFloor) future.length = 0;
+  store.set(scope.snapshot);
+  if (opts?.silent) return;
+  bumpTick();
+  persistHook();
+  if (import.meta.env.DEV && scope.clipUndoFloor) {
+    console.debug('[editorStore] cancelScope (clipping) →', {
+      label: scope.label,
+      pastLen: past.length,
+      restoredPalettes: paletteSnapshot(scope.snapshot),
+    });
+  }
+}
+
+export const editorState: Readable<EditorState> = { subscribe: store.subscribe };
+
+export function mutate(label: string, fn: (draft: EditorState) => void): void {
+  if (import.meta.env.DEV && !label) {
+    console.warn('[editorStore] mutate() called without a label');
+  }
+  if (transactionScope) {
+    // Inside a non-clipping scope: don't push individually; just mark the
+    // scope dirty and apply. The scope's commit pushes one collapsed entry.
+    transactionScope.changed = true;
+    if (clippingScope) clippingScope.changed = true;
+    store.update((s) => { fn(s); return s; });
+    return;
+  }
+  // No transaction scope: each mutate is its own history entry. Inside a
+  // clipping scope this still pushes per-mutate entries (so undo within the
+  // scope walks them back), and the scope's commit will collapse them.
+  if (clippingScope) clippingScope.changed = true;
+  const current = get(store);
+  pushPast(structuredClone(current));
+  store.update((s) => { fn(s); return s; });
+  bumpTick();
+  persistHook();
+}
+
+/**
+ * Slider-drag helper: opens a non-clipping scope on pointerdown and commits
+ * it on the next window-level pointerup / pointercancel. Groups a drag
+ * gesture under one history entry so undo rolls the whole drag back as a
+ * single step.
+ */
+export function beginSliderGesture(label: string): void {
+  if (typeof window === 'undefined') return;
+  const scope = beginScope({ label, collapseToOne: true, clipUndoFloor: false });
+  const end = () => {
+    commitScope(scope);
+    window.removeEventListener('pointerup', end);
+    window.removeEventListener('pointercancel', end);
+  };
+  window.addEventListener('pointerup', end);
+  window.addEventListener('pointercancel', end);
+}
+
+/**
+ * Sync closure form: opens a non-clipping scope, runs `fn`, and commits.
+ * If `fn` throws, the scope is silently cancelled (state reverted, no
+ * persist) and the error is re-thrown.
+ */
+export function transaction<T>(label: string, fn: (draft: EditorState) => T): T {
+  const scope = beginScope({ label, collapseToOne: true, clipUndoFloor: false });
+  try {
+    let result!: T;
+    mutate(label, (draft) => { result = fn(draft); });
+    commitScope(scope);
+    return result;
+  } catch (e) {
+    cancelScope(scope, { silent: true });
+    throw e;
+  }
+}
+
+// ── Undo / redo ───────────────────────────────────────────────────────────
+
+export function undo(): boolean {
+  if (transactionScope) cancelScope(transactionScope, { silent: true });
+  const floor = clippingScope ? clippingScope.historyIdx : 0;
+  if (past.length <= floor) return false;
+  future.push(structuredClone(get(store)));
+  const previous = past.pop()!;
+  store.set(previous);
+  bumpTick();
+  persistHook();
+  if (import.meta.env.DEV) {
+    console.debug('[editorStore] undo →', {
+      pastLen: past.length, floor,
+      palettes: paletteSnapshot(previous),
+      inClippingScope: !!clippingScope,
+    });
+  }
+  return true;
+}
+
+export function redo(): boolean {
+  if (transactionScope) cancelScope(transactionScope, { silent: true });
+  if (future.length === 0) return false;
+  past.push(structuredClone(get(store)));
+  const next = future.pop()!;
+  store.set(next);
+  bumpTick();
+  persistHook();
+  return true;
+}
+
+export const canUndo: Readable<boolean> = derived(historyTick, () => past.length > 0);
+export const canRedo: Readable<boolean> = derived(historyTick, () => future.length > 0);
+export const dirty:   Readable<boolean> = derived(historyTick, () => past.length !== savedAtIndex);
+
+export function markSaved(): void {
+  savedAtIndex = past.length;
+  bumpTick();
+}
+
+/**
+ * Reset history + transient scope state without touching the store. Used by
+ * `loadFromFile` ("open a different document" — undo cannot cross a theme
+ * load). The caller is responsible for `store.set(next)` and `persistHook()`.
+ */
+export function resetHistoryForLoad(): void {
+  past.length = 0;
+  future.length = 0;
+  savedAtIndex = 0;
+  transactionScope = null;
+  bumpTick();
+}
+
+/**
+ * Test-only: clear all core history + transient scope state and reset the
+ * store to `emptyStateFactory()`. The full `__resetForTests` in editorStore
+ * also resets renderer + per-slice baselines.
+ */
+export function __resetCoreForTests(): void {
+  past.length = 0;
+  future.length = 0;
+  savedAtIndex = 0;
+  transactionScope = null;
+  clippingScope = null;
+  store.set(emptyStateFactory());
+  bumpTick();
+}
+
+/** Test-only accessors — internal history state is module-private otherwise. */
+export function __getHistoryLengths(): { past: number; future: number } {
+  return { past: past.length, future: future.length };
+}
+export function __getPastAt(idx: number): EditorState | undefined {
+  return past[idx];
+}
+
+/** Dev-only: compact digest of each palette's baseColor + overrides count. */
+function paletteSnapshot(s: EditorState): Record<string, { base: string; overrides: number }> {
+  const out: Record<string, { base: string; overrides: number }> = {};
+  for (const [k, v] of Object.entries(s.palettes ?? {})) {
+    out[k] = { base: v.baseColor, overrides: Object.keys(v.overrides).length };
+  }
+  return out;
+}

package/src/lib/editorKeybindings.ts

@@ -0,0 +1,52 @@
+import { undo, redo } from './editorStore';
+
+/**
+ * Install Cmd/Ctrl+Z → undo and Cmd/Ctrl+Shift+Z → redo.
+ *
+ * Native browser text-undo inside inputs / textareas / contenteditable is
+ * left intact: those targets are passed through untouched. Editor undo fires
+ * only when focus is outside editable elements.
+ *
+ * Scope this installer to the pages where the editor is actually mounted
+ * (Editor.svelte) so Cmd+Z on the landing / component-editor pages isn't hijacked.
+ *
+ * Returns a cleanup function (use in Svelte's onMount return).
+ */
+export function installEditorKeybindings(): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  window.addEventListener('keydown', handleKeydown);
+  return () => window.removeEventListener('keydown', handleKeydown);
+}
+
+function handleKeydown(e: KeyboardEvent): void {
+  const mod = e.metaKey || e.ctrlKey;
+  if (!mod) return;
+  if (e.key !== 'z' && e.key !== 'Z') return;
+
+  const target = e.target as HTMLElement | null;
+  if (target && isEditable(target)) return;
+
+  e.preventDefault();
+  if (e.shiftKey) redo();
+  else undo();
+}
+
+// Input types whose native Cmd+Z editing we want to preserve. Everything
+// else (range, checkbox, radio, button, color, etc.) has no meaningful
+// native undo — passing the event through would mean editor undo silently
+// does nothing whenever a slider or checkbox has focus.
+const TEXT_INPUT_TYPES = new Set([
+  'text', 'search', 'email', 'url', 'tel', 'password', 'number',
+  'date', 'datetime-local', 'month', 'time', 'week',
+]);
+
+function isEditable(el: HTMLElement): boolean {
+  const tag = el.tagName;
+  if (tag === 'TEXTAREA') return true;
+  if (tag === 'INPUT') {
+    const type = ((el as HTMLInputElement).type || 'text').toLowerCase();
+    return TEXT_INPUT_TYPES.has(type);
+  }
+  return el.isContentEditable;
+}

package/src/lib/editorPersistence.ts

@@ -0,0 +1,106 @@
+/**
+ * Persistence layer for the editor store — debounced localStorage write +
+ * eager hydrate at module load.
+ *
+ * `editorStore.ts` wires the persist hook to `schedulePersist` exported here
+ * so editorCore's mutate/undo/redo debounce-write through the same path.
+ * Seed paths that bypass `mutate` call `editorCore.persist()` (which routes
+ * to `schedulePersist`).
+ *
+ * Hydrate runs eagerly at first import so child components reading
+ * `$editorState` in their onMount see persisted state, not the transient
+ * empty default — Svelte mounts children before parents, so waiting for
+ * Editor's onMount is too late.
+ */
+
+import { get } from 'svelte/store';
+import type { EditorState } from './editorTypes';
+import { storageKey } from './editorConfig';
+import { store } from './editorCore';
+import { quietGet, quietSet } from './storage';
+import { makeDefaultGradients } from './slices/gradients';
+import { seedShadowsFromDom } from './slices/shadows';
+
+// Resolve the persist key lazily (per-call) so library consumers that invoke
+// `configureEditor({storagePrefix})` before the first store write get the
+// configured prefix even if `editorPersistence` was imported at module-load
+// time (M8). The function call is cheap; do not memoise — that defeats the point.
+function getPersistKey(): string {
+  return storageKey('editor-state');
+}
+export const PERSIST_DEBOUNCE_MS = 300;
+
+let emptyStateFactory: () => EditorState = () => ({} as EditorState);
+
+/** Wired by editorStore at boot — the factory composes per-slice defaults. */
+export function setEmptyStateFactory(fn: () => EditorState): void {
+  emptyStateFactory = fn;
+}
+
+let persistTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function schedulePersist(): void {
+  if (typeof localStorage === 'undefined') return;
+  if (persistTimer) clearTimeout(persistTimer);
+  persistTimer = setTimeout(persistNow, PERSIST_DEBOUNCE_MS);
+}
+
+export function persistNow(): void {
+  persistTimer = null;
+  // quota / serialization errors are not fatal; quietSet swallows them.
+  quietSet(getPersistKey(), JSON.stringify(get(store)));
+}
+
+function migrateGradients(state: EditorState): EditorState {
+  // Gradients are a fixed-slot scale (--gradient-1 … --gradient-4). If the
+  // persisted state predates the migration to fixed slots (e.g. it still has
+  // a token named --gradient-progress, or the count doesn't match), replace
+  // the gradients block with defaults rather than carrying stale entries.
+  const expected = makeDefaultGradients().map((g) => g.variable).sort();
+  const have = (state.gradients?.tokens ?? []).map((g) => g.variable).sort();
+  const matches =
+    have.length === expected.length &&
+    expected.every((v, i) => v === have[i]);
+  if (matches) return state;
+  return { ...state, gradients: { tokens: makeDefaultGradients() } };
+}
+
+export function hydrate(): void {
+  // Corrupt state, missing key, or unavailable storage all return null;
+  // the editor falls through to the empty default in that case.
+  const parsed = quietGet<unknown>(getPersistKey(), { parse: true });
+  if (parsed && typeof parsed === 'object') {
+    // Shallow-merge onto default shape so older persisted state missing
+    // newly-added domain fields still loads.
+    const merged = { ...emptyStateFactory(), ...(parsed as object) } as EditorState;
+    store.set(migrateGradients(merged));
+  }
+  // m13 fix: seed shadows from the DOM at hydrate time so the editor
+  // captures the tokens.css baseline regardless of whether the user opens
+  // the shadows tab. `seedShadowsFromDom` is a no-op when state already
+  // has tokens (e.g. we just loaded persisted state with shadows saved),
+  // so the seed only fires on a truly fresh boot. Deferred to next frame
+  // because tokens.css may not be applied yet at module-load time —
+  // `getComputedStyle` would return empty strings and `parseShadowCss`
+  // would reject every entry.
+  if (typeof requestAnimationFrame !== 'undefined') {
+    requestAnimationFrame(() => seedShadowsFromDom());
+  } else {
+    seedShadowsFromDom();
+  }
+}
+
+let hydrated = false;
+export function ensureHydrated(): void {
+  if (hydrated) return;
+  hydrated = true;
+  hydrate();
+}
+
+/**
+ * Kept for API parity with callers that opt-in from onMount. A no-op after
+ * the eager load below, but cheap to call multiple times.
+ */
+export async function initializeEditorStore(): Promise<void> {
+  ensureHydrated();
+}

package/src/lib/editorRenderer.ts

@@ -0,0 +1,74 @@
+/**
+ * DOM renderer for the editor store.
+ *
+ * Subscribes to the store and writes derived CSS variables to :root via
+ * `cssVarSync` (which fans out to the parent document for the overlay
+ * iframe). This module is where all DOM side effects live; everything
+ * upstream of `deriveCssVars` is pure-data.
+ *
+ * Importing this module on the client triggers `store.subscribe(...)`. The
+ * editorStore barrel re-exports from here so legacy `import '.../editorStore'`
+ * paths still wire up the renderer at module load.
+ */
+
+import type { EditorState } from './editorTypes';
+import { setCssVar, removeCssVar } from './cssVarSync';
+import { palettesToVars } from './paletteDerivation';
+import {
+  editorState,
+  columnsToVars,
+  columnsEqualsDefault,
+  overlaysToVars,
+  overlaysEqualsDefault,
+  shadowsToVars,
+  gradientsToVars,
+  componentsToVars,
+} from './editorStore';
+
+export function deriveCssVars(state: EditorState): Record<string, string> {
+  const out: Record<string, string> = { ...state.cssVars };
+  if (!columnsEqualsDefault(state.columns)) {
+    Object.assign(out, columnsToVars(state.columns));
+  }
+  if (!overlaysEqualsDefault(state.overlays)) {
+    Object.assign(out, overlaysToVars(state.overlays));
+  }
+  if (state.shadows.tokens.length > 0) {
+    Object.assign(out, shadowsToVars(state.shadows));
+  }
+  if (state.gradients.tokens.length > 0) {
+    Object.assign(out, gradientsToVars(state.gradients));
+  }
+  Object.assign(out, palettesToVars(state.palettes));
+  Object.assign(out, componentsToVars(state.components));
+  return out;
+}
+
+let lastApplied: Record<string, string> = {};
+let installed = false;
+
+/**
+ * Install the DOM subscriber. Called once from `editorStore.ts` after its
+ * exports are initialized — calling it earlier would TDZ-trip on `editorState`
+ * because of the editorStore ↔ editorRenderer circular import.
+ */
+export function installRenderer(): void {
+  if (installed) return;
+  installed = true;
+  if (typeof window === 'undefined') return;
+  editorState.subscribe((state) => {
+    const next = deriveCssVars(state);
+    for (const name in next) {
+      if (next[name] !== lastApplied[name]) setCssVar(name, next[name]);
+    }
+    for (const name in lastApplied) {
+      if (!(name in next)) removeCssVar(name);
+    }
+    lastApplied = next;
+  });
+}
+
+/** Test-only: clear the diff cache so independent test runs don't leak applied vars. */
+export function __resetRendererCacheForTests(): void {
+  lastApplied = {};
+}