@motion-proto/live-tokens 0.7.1 → 0.8.0

package/src/editor/core/palettes/paletteDerivation.ts

@@ -298,3 +298,72 @@ export function palettesToVars(palettes: Record<string, PaletteConfig>): Record<
   }
   return out;
 }
+
+const HEX_RE = /^#[0-9a-f]{6}$/i;
+
+/**
+ * Reconcile palette typed state against the catch-all `cssVariables` bag and
+ * report the set of variable names the typed slice now owns. Two operations:
+ *
+ *   - **Snap** (gated by `_imported`): for any palette whose `_imported` flag
+ *     is true, the imported `--color-{ns}-500` value is treated as the
+ *     authoritative anchor. Chromatic palettes get `baseColor` snapped to it;
+ *     gray palettes (Neutral/Alternate) get `tintHue` + `tintChroma` derived
+ *     from it via OKLCH. The flag is then cleared. Editor-authored palettes
+ *     (no `_imported`) are left untouched — see `temp/manifest-robustness-plan.md`
+ *     §9 for why "snap on any divergence" was wrong: it would have flipped
+ *     `themes/default.json`'s accent from teal to olive on first read.
+ *
+ *   - **Consume** (always): every variable the palette's derivation produces
+ *     is reported in `consumed` so the caller can strip it from
+ *     `cssVariables`. The renderer (`editorRenderer.ts:42`) overlays
+ *     `palettesToVars(palettes)` on top of `cssVariables` regardless, so
+ *     stripped keys were dead data anyway. Stripping makes the file
+ *     invariant explicit: catch-all carries only tokens no typed slice owns.
+ *
+ * Returns the updated palette map plus the two sets. Pure: no DOM, no I/O,
+ * no module state. Idempotent on second call with the same input (no anchor
+ * to snap to after first call's strip).
+ */
+export function reconcilePalettesFromCssVars(
+  palettes: Record<string, PaletteConfig>,
+  cssVars: Record<string, string>,
+): {
+  palettes: Record<string, PaletteConfig>;
+  consumed: ReadonlySet<string>;
+  snapped: ReadonlySet<string>;
+} {
+  const next: Record<string, PaletteConfig> = structuredClone(palettes);
+  const consumed = new Set<string>();
+  const snapped = new Set<string>();
+
+  for (const spec of PALETTE_SPECS) {
+    const current = next[spec.label];
+    if (current === undefined) continue;
+
+    if (current._imported === true) {
+      const anchorHex = cssVars[`--color-${spec.cssNamespace}-500`];
+      if (anchorHex && HEX_RE.test(anchorHex.trim())) {
+        const hex = anchorHex.trim();
+        if (spec.mode === 'gray') {
+          const { c, h } = hexToOklch(hex);
+          next[spec.label] = { ...current, tintHue: h, tintChroma: c, _imported: false };
+        } else {
+          next[spec.label] = { ...current, baseColor: hex, _imported: false };
+        }
+        snapped.add(spec.label);
+      } else {
+        // No anchor in cssVariables to snap to — flag has nothing to do; clear
+        // it so subsequent calls don't keep checking. Safe because the renderer
+        // is going to overlay palettesToVars anyway.
+        next[spec.label] = { ...current, _imported: false };
+      }
+    }
+
+    for (const k of Object.keys(derivePaletteVars(spec, next[spec.label]))) {
+      consumed.add(k);
+    }
+  }
+
+  return { palettes: next, consumed, snapped };
+}

package/src/editor/core/palettes/tokenRegistry.ts

@@ -23,6 +23,7 @@ import tokensCss from '../../../system/styles/tokens.css?raw';
 import { editorState } from '../store/editorStore';
 import type { EditorState } from '../store/editorTypes';
 import { extractGlobalRootBody } from '../themes/parsers/globalRootBlock';
+import { formatGradientValue } from '../themes/slices/gradients';
 
 // Re-exported for tests and downstream consumers that previously imported it
 // from this module. The canonical implementation lives in `./parsers/globalRootBlock`
@@ -111,7 +112,9 @@ function buildOverlayRegistry(
   const overrides = new Map<string, string>();
   for (const slice of Object.values(components)) {
     for (const [varName, ref] of Object.entries(slice.aliases)) {
-      overrides.set(varName, ref.kind === 'token' ? `var(${ref.name})` : ref.value);
+      if (ref.kind === 'token') overrides.set(varName, `var(${ref.name})`);
+      else if (ref.kind === 'literal') overrides.set(varName, ref.value);
+      else overrides.set(varName, formatGradientValue(ref.value));
     }
   }
   const getDeclared = (v: string): string | null =>

package/src/editor/core/store/editorStore.ts

@@ -18,8 +18,8 @@
  * orchestrate across slices and stay here.
  */
 
-import type { CssVarRef, EditorState } from './editorTypes';
-import type { Theme } from '../themes/themeTypes';
+import type { CssVarRef, EditorState, GradientAliasValue } from './editorTypes';
+import type { AliasDiskValue, Theme } from '../themes/themeTypes';
 import { KNOWN_COMPONENT_CONFIG_KEYS } from '../components/componentConfigKeys';
 import {
   CURRENT_THEME_SCHEMA_VERSION,
@@ -205,12 +205,200 @@ export {
 // literal-valued knobs (per `KNOWN_COMPONENT_CONFIG_KEYS`) into the config
 // bucket and wraps the remainder as `CssVarRef` discriminated unions.
 
+/**
+ * Migrate a disk-shape alias bag through the registered migration runner.
+ *
+ * The runner is string-typed by contract (most migrations only do
+ * key/value string rewrites). Object-valued entries — currently just
+ * inline `{ kind: 'gradient', value: ... }` payloads — pass through
+ * untouched: we split the bag into string/object subsets, run the runner
+ * on the string subset, then merge.
+ *
+ * For sectiondivider's legacy 7-flat-token gradients we run a synthesis
+ * step BEFORE the migration runner that would strip those tokens. The
+ * synthesized gradient object lands in the object subset and survives
+ * the stripping pass.
+ */
 function migrateComponentAliases(
   component: string,
-  aliases: Record<string, string>,
+  aliasesIn: Record<string, AliasDiskValue>,
+  rawConfig: Record<string, unknown> | undefined,
   fileVersion: number,
-): Record<string, string> {
-  return runMigrations('component-config', fileVersion, aliases, { component });
+): { aliases: Record<string, AliasDiskValue>; config: Record<string, unknown> } {
+  const stringPart: Record<string, string> = {};
+  const objectPart: Record<string, AliasDiskValue> = {};
+  for (const [k, v] of Object.entries(aliasesIn)) {
+    if (typeof v === 'string') stringPart[k] = v;
+    else objectPart[k] = v;
+  }
+  // String-valued config entries join the migration input so a migration can
+  // rename or relocate them. After migration the bag flows through
+  // `splitAliasesAndConfig` which routes KNOWN keys back to config and the
+  // rest to aliases — this is what lets a migration *move* a key from the
+  // config bucket to the aliases bucket by also removing it from KNOWN.
+  // Config wins over an aliases-bucket collision on the same key: the legacy
+  // single-bucket → split-bucket move preserved "explicit config field beats
+  // legacy alias-bucketed value", and that contract still holds.
+  // Non-string config values (rare; reserved for future structured payloads)
+  // pass through untouched.
+  const configOut: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rawConfig ?? {})) {
+    if (typeof v === 'string') stringPart[k] = v;
+    else configOut[k] = v;
+  }
+  if (component === 'sectiondivider') {
+    synthesizeSectionDividerGradients(stringPart, objectPart);
+  }
+  const migratedString = runMigrations('component-config', fileVersion, stringPart, { component });
+  const migratedObject = component === 'sectiondivider'
+    ? renameSectionDividerObjectSlots(objectPart)
+    : objectPart;
+  return {
+    aliases: { ...migratedString, ...migratedObject },
+    config: configOut,
+  };
+}
+
+/**
+ * v8→v9 companion to `componentMigration_2026_05_20_sectiondividerSlimVariants`:
+ * the structured background payload is reshaped from six color families →
+ * three size variants (lg/md/sm). Canvas's gradient is taken as the canonical
+ * seed and fanned across all three new variants; other families' gradients
+ * are dropped. Idempotent — keys already at the final shape pass through.
+ *
+ * Sources accepted (in priority order, first-found wins for canvas's slot):
+ *   --sectiondivider-canvas-background  (current/in-progress shape)
+ *   --sectiondivider-canvas-gradient    (v7-era shape)
+ *   --sectiondivider-color-canvas-background  (intermediate shape that landed
+ *                                              briefly during the color-prop pivot)
+ *
+ * The migration runner only sees string keys, so this object-shape rename
+ * has to live alongside the runner call.
+ */
+const FAMILIES = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
+const SIZE_VARIANTS = ['lg', 'md', 'sm'] as const;
+function renameSectionDividerObjectSlots(
+  objectPart: Record<string, AliasDiskValue>,
+): Record<string, AliasDiskValue> {
+  // Find canvas's gradient under any historical key shape.
+  const canvasSourceKeys = [
+    '--sectiondivider-canvas-background',
+    '--sectiondivider-canvas-gradient',
+    '--sectiondivider-color-canvas-background',
+  ];
+  let canvasGradient: AliasDiskValue | undefined;
+  for (const key of canvasSourceKeys) {
+    if (objectPart[key] !== undefined) {
+      canvasGradient = objectPart[key];
+      break;
+    }
+  }
+
+  // If we found a canvas gradient (any era), fan it into the three new
+  // per-variant background slots and drop every other family's gradient.
+  // If no canvas gradient is found, pass through non-family keys verbatim
+  // so non-migration data (theme tokens, other components) isn't touched.
+  const out: Record<string, AliasDiskValue> = {};
+  for (const [key, value] of Object.entries(objectPart)) {
+    // Skip any sectiondivider per-family gradient; the canvas fan-out emits
+    // the canonical set below.
+    let isFamilyGradient = false;
+    for (const f of FAMILIES) {
+      if (
+        key === `--sectiondivider-${f}-background`
+        || key === `--sectiondivider-${f}-gradient`
+        || key === `--sectiondivider-color-${f}-background`
+      ) {
+        isFamilyGradient = true;
+        break;
+      }
+    }
+    // Pass through anything that's already at the final lg/md/sm shape so
+    // re-running the migration is idempotent.
+    if (isFamilyGradient) continue;
+    out[key] = value;
+  }
+  if (canvasGradient !== undefined) {
+    for (const v of SIZE_VARIANTS) {
+      out[`--sectiondivider-${v}-background`] = canvasGradient;
+    }
+  }
+  return out;
+}
+
+/** SectionDivider variants that ship gradient aliases. */
+const SECTIONDIVIDER_VARIANTS = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
+
+/**
+ * Collapse legacy 7-flat-token gradients (`{angle, stop-{1,2,3}-{color,position}}`)
+ * for each sectiondivider variant into one structured gradient alias at
+ * `--sectiondivider-{v}-gradient`. The flat tokens stay in `stringPart`
+ * for the migration runner to strip; the structured payload joins
+ * `objectPart` so the merge produces the new shape.
+ *
+ * Skips variants that already declare a gradient alias (object form) so
+ * round-tripping doesn't overwrite user edits.
+ */
+function synthesizeSectionDividerGradients(
+  stringPart: Record<string, string>,
+  objectPart: Record<string, AliasDiskValue>,
+): void {
+  const GRADIENT_ANGLE_TOKENS: Record<string, number> = {
+    '--gradient-angle-horizontal': 90,
+    '--gradient-angle-vertical': 180,
+    '--gradient-angle-diagonal': 135,
+    '--gradient-angle-counter-diagonal': 45,
+  };
+  const GRADIENT_STOP_POSITIONS: Record<string, number> = {
+    '--gradient-stop-start': 0,
+    '--gradient-stop-mid': 50,
+    '--gradient-stop-end': 100,
+  };
+  const parseAngle = (raw: string | undefined): number => {
+    if (!raw) return 135;
+    if (raw.startsWith('--')) return GRADIENT_ANGLE_TOKENS[raw] ?? 135;
+    const m = raw.match(/^(-?\d+(?:\.\d+)?)\s*deg$/i);
+    return m ? parseFloat(m[1]) : 135;
+  };
+  const parsePosition = (raw: string | undefined, fallback: number): number => {
+    if (!raw) return fallback;
+    if (raw.startsWith('--')) return GRADIENT_STOP_POSITIONS[raw] ?? fallback;
+    const m = raw.match(/^(-?\d+(?:\.\d+)?)\s*%$/);
+    return m ? parseFloat(m[1]) : fallback;
+  };
+  const parseStopColor = (raw: string | undefined): { color: string; opacity?: number } | null => {
+    if (!raw) return null;
+    if (raw.startsWith('--')) return { color: raw };
+    const mix = raw.match(/^color-mix\(\s*in\s+srgb\s*,\s*var\((--[a-z0-9-]+)\)\s+([\d.]+)%\s*,\s*transparent\s*\)$/i);
+    if (mix) return { color: mix[1], opacity: parseFloat(mix[2]) };
+    return null;
+  };
+  for (const v of SECTIONDIVIDER_VARIANTS) {
+    const slot = `--sectiondivider-${v}-gradient`;
+    if (slot in objectPart) continue;
+    const angleKey = `${slot}-angle`;
+    const has1 = stringPart[`${slot}-stop-1-color`] !== undefined;
+    const has2 = stringPart[`${slot}-stop-2-color`] !== undefined;
+    const has3 = stringPart[`${slot}-stop-3-color`] !== undefined;
+    if (!has1 && !has2 && !has3) continue;
+    const stops: { position: number; color: string; opacity?: number }[] = [];
+    const positionDefaults = [0, 50, 100];
+    for (let i = 1; i <= 3; i++) {
+      const c = parseStopColor(stringPart[`${slot}-stop-${i}-color`]);
+      if (!c) continue;
+      const pos = parsePosition(stringPart[`${slot}-stop-${i}-position`], positionDefaults[i - 1]);
+      stops.push({ position: pos, color: c.color, ...(c.opacity !== undefined ? { opacity: c.opacity } : {}) });
+    }
+    if (stops.length < 2) continue;
+    objectPart[slot] = {
+      kind: 'gradient',
+      value: {
+        type: 'linear',
+        angle: parseAngle(stringPart[angleKey]),
+        stops,
+      },
+    };
+  }
 }
 
 /**
@@ -219,12 +407,18 @@ function migrateComponentAliases(
  * config bucket, and wraps the remainder as `CssVarRef` discriminated unions.
  */
 function splitAliasesAndConfig(
-  rawAliases: Record<string, string>,
+  rawAliases: Record<string, AliasDiskValue>,
   rawConfig: Record<string, unknown> | undefined,
 ): { aliases: Record<string, CssVarRef>; config: Record<string, unknown> } {
   const aliases: Record<string, CssVarRef> = {};
   const config: Record<string, unknown> = { ...(rawConfig ?? {}) };
   for (const [key, value] of Object.entries(rawAliases)) {
+    if (typeof value !== 'string') {
+      if (value.kind === 'gradient') {
+        aliases[key] = { kind: 'gradient', value: value.value as GradientAliasValue };
+      }
+      continue;
+    }
     if (KNOWN_COMPONENT_CONFIG_KEYS.has(key)) {
       if (config[key] === undefined) config[key] = value;
       continue;
@@ -249,12 +443,12 @@ function splitAliasesAndConfig(
 export function loadComponentActive(
   component: string,
   activeFile: string,
-  aliases: Record<string, string>,
+  aliases: Record<string, AliasDiskValue>,
   config?: Record<string, unknown>,
   schemaVersion: number = 0,
 ): void {
-  const migrated = migrateComponentAliases(component, aliases, schemaVersion);
-  const split = splitAliasesAndConfig(migrated, config);
+  const migrated = migrateComponentAliases(component, aliases, config, schemaVersion);
+  const split = splitAliasesAndConfig(migrated.aliases, migrated.config);
   mutate(`load ${component}/${activeFile}`, (s) => {
     s.components[component] = { activeFile, aliases: { ...split.aliases }, config: { ...split.config } };
   });
@@ -264,7 +458,7 @@ export function loadComponentActive(
 
 export interface ComponentSeed {
   activeFile: string;
-  aliases: Record<string, string>;
+  aliases: Record<string, AliasDiskValue>;
   config?: Record<string, unknown>;
   schemaVersion?: number;
 }
@@ -282,8 +476,8 @@ export function seedComponentsFromApi(
   store.update((s) => {
     s.components = {};
     for (const [comp, cfg] of Object.entries(configs)) {
-      const migrated = migrateComponentAliases(comp, cfg.aliases, cfg.schemaVersion ?? 0);
-      const split = splitAliasesAndConfig(migrated, cfg.config);
+      const migrated = migrateComponentAliases(comp, cfg.aliases, cfg.config, cfg.schemaVersion ?? 0);
+      const split = splitAliasesAndConfig(migrated.aliases, migrated.config);
       s.components[comp] = { activeFile: cfg.activeFile, aliases: { ...split.aliases }, config: { ...split.config } };
       setSavedComponentBaseline(comp, componentBaseline(split));
     }

package/src/editor/core/store/editorTypes.ts

@@ -43,24 +43,25 @@ export interface ColumnsState {
   margin: number;
 }
 
-export type CssVarRef =
-  | { kind: 'token'; name: string }
-  | { kind: 'literal'; value: string };
-
-export interface ComponentSlice {
-  activeFile: string;
-  aliases: Record<string, CssVarRef>;
-  config: Record<string, unknown>;
-  unlinked?: string[];
-}
-
-export type GradientType = 'linear' | 'radial';
+/** Gradient render mode.
+ *  - `linear` / `radial`: real gradients with N stops + angle (linear) or radius (radial).
+ *  - `solid`: collapses to the first stop's color. Angle/radius/extra stops carried in
+ *    the payload but ignored by the renderer; toggling back restores the prior shape.
+ *  - `none`: transparent. Same carry-forward semantics — payload retained for
+ *    round-trip when the user toggles back to a real gradient. */
+export type GradientType = 'linear' | 'radial' | 'solid' | 'none';
 
 export interface GradientTokenStop {
   /** 0–100 percentage along the gradient axis. */
   position: number;
   /** CSS variable name the stop resolves through (e.g. '--color-brand-500'). */
   color: string;
+  /** When `false`, this stop is an explicit off-palette override: the stop
+   *  picker opens to any color (not family-filtered), and the stop is skipped
+   *  by family-swap rewrites so its color survives a variant family change.
+   *  Defaults to true (follow family) on read; absence is the same as `true`.
+   *  Only meaningful for gradients rendered inside a family-aware context. */
+  monochrome?: boolean;
   /** 0–100 alpha applied to the stop's color. Defaults to 100 (fully opaque). */
   opacity?: number;
 }
@@ -71,9 +72,51 @@ export interface GradientToken {
   type: GradientType;
   /** Degrees, applies to linear only. */
   angle: number;
+  /** Pixel radius for radial gradients. When absent or zero, the renderer
+   *  emits CSS's default ellipse/farthest-corner shape. */
+  radius?: number;
+  /** Horizontal center position for radial gradients, 0–100. Defaults to 50. */
+  centerX?: number;
+  /** Horizontal stretch factor for the radial ellipse (1–8). Defaults to 1.
+   *  With aspectY, the rendered semi-axes are `radius * aspect*`, so both
+   *  shape (ratio) and size are encoded together. Both = 1 keeps the legacy
+   *  `circle` render path verbatim. */
+  aspectX?: number;
+  /** Vertical stretch factor for the radial ellipse (1–8). Defaults to 1. */
+  aspectY?: number;
   stops: GradientTokenStop[];
 }
 
+/** Structured gradient payload carried inline on a component alias.
+ *  Mirrors GradientToken minus `variable` (the alias key itself is the
+ *  binding). Used when a component owns a per-instance gradient that
+ *  doesn't share the theme-level `--gradient-N` library. */
+export interface GradientAliasValue {
+  type: GradientType;
+  angle: number;
+  /** See GradientToken.radius. */
+  radius?: number;
+  /** See GradientToken.centerX. */
+  centerX?: number;
+  /** See GradientToken.aspectX. */
+  aspectX?: number;
+  /** See GradientToken.aspectY. */
+  aspectY?: number;
+  stops: GradientTokenStop[];
+}
+
+export type CssVarRef =
+  | { kind: 'token'; name: string }
+  | { kind: 'literal'; value: string }
+  | { kind: 'gradient'; value: GradientAliasValue };
+
+export interface ComponentSlice {
+  activeFile: string;
+  aliases: Record<string, CssVarRef>;
+  config: Record<string, unknown>;
+  unlinked?: string[];
+}
+
 /**
  * Single source of truth for everything a saved token file depends on, plus
  * the domain state currently scattered across VariablesTab local `let` fields.

package/src/editor/core/store/gradientSource.ts

@@ -0,0 +1,192 @@
+/**
+ * Source adapter for the visual gradient editor.
+ *
+ * `GradientEditor.svelte` was originally hard-wired to the theme-level
+ * gradient library (`state.gradients.tokens`). Components that own their
+ * own structured gradients (e.g. SectionDivider's per-variant slot) live
+ * in `state.components[...].aliases[...]` as a `kind: 'gradient'` ref.
+ *
+ * Wrapping both behind one source interface lets the editor read + write
+ * either backing store without leaking knowledge of which it's editing.
+ * The store-derived `current` field reactively exposes the current value;
+ * the mutator methods funnel each change through `mutate`, so undo /
+ * persistence still cover the edit identically to direct API calls.
+ */
+import { derived, get, type Readable } from 'svelte/store';
+import { editorState } from './editorStore';
+import type { GradientType, GradientTokenStop, GradientAliasValue, CssVarRef } from './editorTypes';
+import {
+  setGradient,
+  setGradientType,
+  setGradientAngle,
+  setGradientCenterX,
+  setGradientAspect,
+  setGradientStop,
+  addGradientStop,
+  removeGradientStop,
+} from '../themes/slices/gradients';
+import { setComponentAlias } from '../themes/slices/components';
+import { mutate } from './editorCore';
+
+export interface GradientSourceSnapshot {
+  type: GradientType;
+  angle: number;
+  /** Horizontal center for radial gradients, 0–100. */
+  centerX?: number;
+  /** Per-axis stretch factors for the radial ellipse (1 = unscaled). */
+  aspectX?: number;
+  aspectY?: number;
+  stops: GradientTokenStop[];
+}
+
+export interface GradientSource {
+  /** Reactive readable of the current gradient value (or undefined if missing). */
+  current: Readable<GradientSourceSnapshot | undefined>;
+  setAll(next: GradientSourceSnapshot): void;
+  setType(type: GradientType): void;
+  setAngle(angle: number): void;
+  setCenterX(centerX: number): void;
+  setAspect(aspect: { x: number; y: number }): void;
+  setStop(index: number, partial: Partial<GradientTokenStop>): void;
+  addStop(stop: GradientTokenStop): void;
+  removeStop(index: number): void;
+}
+
+/** Adapter for `--gradient-N` library tokens in `state.gradients.tokens`. */
+export function themeGradientSource(variable: string): GradientSource {
+  const current = derived(editorState, ($s) => {
+    const t = $s.gradients.tokens.find((g) => g.variable === variable);
+    if (!t) return undefined;
+    return {
+      type: t.type,
+      angle: t.angle,
+      centerX: t.centerX,
+      aspectX: t.aspectX,
+      aspectY: t.aspectY,
+      stops: t.stops.map((s) => ({ ...s })),
+    };
+  });
+  return {
+    current,
+    setAll: (next) => setGradient(variable, next),
+    setType: (t) => setGradientType(variable, t),
+    setAngle: (a) => setGradientAngle(variable, a),
+    setCenterX: (x) => setGradientCenterX(variable, x),
+    setAspect: (a) => setGradientAspect(variable, a),
+    setStop: (i, p) => setGradientStop(variable, i, p),
+    addStop: (s) => addGradientStop(variable, s),
+    removeStop: (i) => removeGradientStop(variable, i),
+  };
+}
+
+function readComponentGradient(component: string, varName: string): GradientAliasValue | undefined {
+  const ref = get(editorState).components[component]?.aliases[varName];
+  return ref?.kind === 'gradient' ? ref.value : undefined;
+}
+
+function writeComponentGradient(component: string, varName: string, value: GradientAliasValue): void {
+  const ref: CssVarRef = { kind: 'gradient', value };
+  setComponentAlias(component, varName, ref);
+}
+
+/** Adapter for component-owned gradients stored inline on a component alias. */
+export function componentGradientSource(component: string, varName: string): GradientSource {
+  const current = derived(editorState, ($s) => {
+    const ref = $s.components[component]?.aliases[varName];
+    if (ref?.kind !== 'gradient') return undefined;
+    return {
+      type: ref.value.type,
+      angle: ref.value.angle,
+      centerX: ref.value.centerX,
+      aspectX: ref.value.aspectX,
+      aspectY: ref.value.aspectY,
+      stops: ref.value.stops.map((s) => ({ ...s })),
+    };
+  });
+  /** Read-modify-write through `mutate` so each edit is one history entry
+   *  and the renderer + persistence cycle pick it up uniformly with the
+   *  theme-gradient path. */
+  const update = (label: string, mutator: (g: GradientAliasValue) => void): void => {
+    mutate(label, (s) => {
+      const slice = s.components[component] ?? (s.components[component] = { activeFile: 'default', aliases: {}, config: {} });
+      const ref = slice.aliases[varName];
+      const base: GradientAliasValue =
+        ref?.kind === 'gradient'
+          ? {
+              type: ref.value.type,
+              angle: ref.value.angle,
+              ...(ref.value.centerX !== undefined ? { centerX: ref.value.centerX } : {}),
+              ...(ref.value.aspectX !== undefined ? { aspectX: ref.value.aspectX } : {}),
+              ...(ref.value.aspectY !== undefined ? { aspectY: ref.value.aspectY } : {}),
+              stops: ref.value.stops.map((st) => ({ ...st })),
+            }
+          : { type: 'linear', angle: 135, stops: [] };
+      mutator(base);
+      slice.aliases[varName] = { kind: 'gradient', value: base };
+    });
+  };
+  return {
+    current,
+    setAll: (next) => writeComponentGradient(component, varName, {
+      type: next.type,
+      angle: next.angle,
+      ...(next.centerX !== undefined ? { centerX: next.centerX } : {}),
+      ...(next.aspectX !== undefined ? { aspectX: next.aspectX } : {}),
+      ...(next.aspectY !== undefined ? { aspectY: next.aspectY } : {}),
+      stops: next.stops.map((s) => ({ ...s })),
+    }),
+    setType: (t) => update(`set gradient type ${varName}`, (g) => { g.type = t; }),
+    setAngle: (a) => update(`set gradient angle ${varName}`, (g) => { g.angle = a; }),
+    setCenterX: (x) => update(`set gradient center ${varName}`, (g) => { g.centerX = x; }),
+    setAspect: (a) => update(`set gradient aspect ${varName}`, (g) => {
+      // Drop axes that equal 1 so persisted JSON stays minimal and pre-aspect
+      // data round-trips unchanged.
+      if (a.x === 1) delete g.aspectX;
+      else g.aspectX = a.x;
+      if (a.y === 1) delete g.aspectY;
+      else g.aspectY = a.y;
+    }),
+    setStop: (i, p) => update(`set gradient stop ${varName}[${i}]`, (g) => {
+      const stop = g.stops[i];
+      if (!stop) return;
+      if (p.position !== undefined) stop.position = p.position;
+      if (p.color !== undefined) stop.color = p.color;
+      if (p.opacity !== undefined) stop.opacity = p.opacity;
+      // `monochrome: true` is the implicit default — drop the field on write
+      // so the persisted shape stays minimal. Only the explicit override
+      // (`false`) needs to live on the stop.
+      if (p.monochrome !== undefined) {
+        if (p.monochrome === false) stop.monochrome = false;
+        else delete stop.monochrome;
+      }
+    }),
+    addStop: (s) => update(`add gradient stop ${varName}`, (g) => {
+      g.stops.push({ ...s });
+      g.stops.sort((a, b) => a.position - b.position);
+    }),
+    removeStop: (i) => update(`remove gradient stop ${varName}[${i}]`, (g) => {
+      if (g.stops.length <= 2) return;
+      g.stops.splice(i, 1);
+    }),
+  };
+}
+
+/** Snapshot helper for save/cancel flows. */
+export function snapshotGradient(source: GradientSource): GradientSourceSnapshot | null {
+  const cur = get(source.current);
+  if (!cur) return null;
+  return {
+    type: cur.type,
+    angle: cur.angle,
+    ...(cur.centerX !== undefined ? { centerX: cur.centerX } : {}),
+    ...(cur.aspectX !== undefined ? { aspectX: cur.aspectX } : {}),
+    ...(cur.aspectY !== undefined ? { aspectY: cur.aspectY } : {}),
+    stops: cur.stops.map((s) => ({ ...s })),
+  };
+}
+
+/** Read the component-side current gradient value used to seed UI defaults
+ *  outside the GradientSource flow (e.g. the Monochrome checkbox derivation). */
+export function readComponentGradientSync(component: string, varName: string): GradientAliasValue | undefined {
+  return readComponentGradient(component, varName);
+}

package/src/editor/core/themes/migrations/2026-05-19-collapsiblesection-drop-frame-surface.ts

@@ -0,0 +1,28 @@
+import type { Migration } from './index';
+
+/**
+ * 2026-05-19: drop `--collapsiblesection-container-frame-surface`.
+ *
+ * The frame-surface token only ever painted the outer `.es-root` background.
+ * Since `.section-header` covers that area with its own per-state surface, the
+ * frame-surface was only visible where the (typically transparent) frame
+ * border zone exposed it — a ring around the header. That made the token
+ * read as a "border" while being labeled "surface color" in the editor.
+ *
+ * Frame is now pure chrome: border color, border width, corner radius. The
+ * per-state header surface tokens already cover all the legitimate surface
+ * needs of the Container variant.
+ */
+function dropFrameSurface(rawVars: Record<string, string>, meta: { component?: string }): Record<string, string> {
+  if (meta.component !== 'collapsiblesection') return rawVars;
+  const { '--collapsiblesection-container-frame-surface': _drop, ...rest } = rawVars;
+  return rest;
+}
+
+export const componentMigration_2026_05_19_collapsiblesectionDropFrameSurface: Migration = {
+  id: '2026-05-19-collapsiblesection-drop-frame-surface',
+  fromVersion: 6,
+  toVersion: 7,
+  appliesTo: 'component-config',
+  apply: dropFrameSurface,
+};