@motion-proto/live-tokens 0.50.0 → 0.53.0

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

@@ -1,137 +1,3 @@
-// OKLCH color space conversions — hand-rolled, no dependencies
-// Pipeline: sRGB hex → linear RGB → OKLab (via M1×M2 + cube root) → OKLCH (polar)
-
-export interface Oklch {
-  l: number; // 0..1
-  c: number; // 0..~0.4
-  h: number; // 0..360
-}
-
-// --- sRGB gamma ---
-
-function srgbToLinear(c: number): number {
-  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
-}
-
-function linearToSrgb(c: number): number {
-  return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
-}
-
-// --- Hex ↔ linear RGB ---
-
-function hexToLinearRgb(hex: string): [number, number, number] {
-  const r = parseInt(hex.slice(1, 3), 16) / 255;
-  const g = parseInt(hex.slice(3, 5), 16) / 255;
-  const b = parseInt(hex.slice(5, 7), 16) / 255;
-  return [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)];
-}
-
-function linearRgbToHex(r: number, g: number, b: number): string {
-  const toHex = (c: number) => {
-    const v = Math.round(Math.max(0, Math.min(1, linearToSrgb(c))) * 255);
-    return v.toString(16).padStart(2, '0');
-  };
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
-}
-
-// --- Linear RGB ↔ OKLab ---
-// Uses the two-matrix approach from Björn Ottosson's blog
-
-function linearRgbToOklab(r: number, g: number, b: number): [number, number, number] {
-  const l_ = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
-  const m_ = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
-  const s_ = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
-
-  const l = Math.cbrt(l_);
-  const m = Math.cbrt(m_);
-  const s = Math.cbrt(s_);
-
-  return [
-    0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
-    1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
-    0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s,
-  ];
-}
-
-function oklabToLinearRgb(L: number, a: number, b: number): [number, number, number] {
-  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
-  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
-  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
-
-  const l = l_ * l_ * l_;
-  const m = m_ * m_ * m_;
-  const s = s_ * s_ * s_;
-
-  return [
-    +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
-    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
-    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
-  ];
-}
-
-// --- OKLab ↔ OKLCH ---
-
-function oklabToOklch(L: number, a: number, b: number): Oklch {
-  const c = Math.sqrt(a * a + b * b);
-  let h = (Math.atan2(b, a) * 180) / Math.PI;
-  if (h < 0) h += 360;
-  return { l: L, c, h };
-}
-
-function oklchToOklab(l: number, c: number, h: number): [number, number, number] {
-  const hRad = (h * Math.PI) / 180;
-  return [l, c * Math.cos(hRad), c * Math.sin(hRad)];
-}
-
-// --- Public API ---
-
-export function hexToOklch(hex: string): Oklch {
-  const [r, g, b] = hexToLinearRgb(hex);
-  const [L, a, bVal] = linearRgbToOklab(r, g, b);
-  return oklabToOklch(L, a, bVal);
-}
-
-export function oklchToHex(l: number, c: number, h: number): string {
-  const [L, a, b] = oklchToOklab(l, c, h);
-  const [r, g, bVal] = oklabToLinearRgb(L, a, b);
-  return linearRgbToHex(r, g, bVal);
-}
-
-function isInGamut(r: number, g: number, b: number): boolean {
-  const eps = 0.0001;
-  return r >= -eps && r <= 1 + eps && g >= -eps && g <= 1 + eps && b >= -eps && b <= 1 + eps;
-}
-
-/** The clamped sRGB projection: reduce chroma into gamut, then serialize to hex.
- *  This is the correct projection for unclamped stored intent — naive
- *  `oklchToHex` per-channel clips (shifting hue), this preserves hue and L. */
-export function oklchToHexClamped(l: number, c: number, h: number): string {
-  const g = gamutClamp(l, c, h);
-  return oklchToHex(g.l, g.c, g.h);
-}
-
-export function gamutClamp(l: number, c: number, h: number): Oklch {
-  // Clamp lightness
-  if (l <= 0) return { l: 0, c: 0, h };
-  if (l >= 1) return { l: 1, c: 0, h };
-
-  // Binary search: reduce chroma until in sRGB gamut
-  const [L, a, b] = oklchToOklab(l, c, h);
-  const [r, g, bVal] = oklabToLinearRgb(L, a, b);
-
-  if (isInGamut(r, g, bVal)) return { l, c, h };
-
-  let lo = 0;
-  let hi = c;
-  for (let i = 0; i < 20; i++) {
-    const mid = (lo + hi) / 2;
-    const [La, aa, ba] = oklchToOklab(l, mid, h);
-    const [rr, gg, bb] = oklabToLinearRgb(La, aa, ba);
-    if (isInGamut(rr, gg, bb)) {
-      lo = mid;
-    } else {
-      hi = mid;
-    }
-  }
-  return { l, c: lo, h };
-}
+// The math lives in the system layer because `src/system` ships to consumers
+// and cannot import from `src/editor`; `backgroundContrast.ts` needs it too.
+export * from '../../../system/internal/oklch';

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

@@ -13,8 +13,8 @@
  * derives the same CSS vars from the persisted config.
  */
 
-import { hexToOklch, oklchToHexClamped, gamutClamp, type Oklch } from './oklch';
-import { type CurveAnchor, sampleCurve, makeAnchor, tangentAnchor } from '../../ui/curveEngine';
+import { cssColorToOklch, oklchToCssClamped, gamutClamp, type Oklch } from './oklch';
+import { type CurveAnchor, sampleCurve, makeAnchor, tangentAnchor, resmoothAutoCurve } from '../../ui/curveEngine';
 import type { PaletteConfig } from '../themes/themeTypes';
 
 export interface PaletteSpec {
@@ -108,8 +108,18 @@ export const SCALES: readonly Scale[] = [
 export const BW_GUARD_MIN_L = 0.17;
 export const BW_GUARD_MAX_L = 0.93;
 
-export const DEFAULT_PALETTE_LIGHTNESS = (): CurveAnchor[] => [makeAnchor(0, 95, 5), makeAnchor(100, 8, 5)];
-export const DEFAULT_PALETTE_SATURATION = (): CurveAnchor[] => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)];
+/** Defaults ship auto-shaped, so a curve nobody has touched is the one the editor
+ *  draws with Auto smooth on. Handle lengths come from the points, which is why
+ *  `makeAnchor`'s tangent argument is left off throughout. */
+const autoCurve = (...anchors: CurveAnchor[]): CurveAnchor[] => resmoothAutoCurve(anchors);
+
+export const DEFAULT_PALETTE_LIGHTNESS = (): CurveAnchor[] => autoCurve(makeAnchor(0, 95), makeAnchor(100, 8));
+export const DEFAULT_PALETTE_SATURATION = (): CurveAnchor[] => autoCurve(makeAnchor(0, 100), makeAnchor(100, 100));
+export const DEFAULT_PALETTE_HUE = (): CurveAnchor[] => autoCurve(makeAnchor(0, 0), makeAnchor(100, 0));
+
+/** Hue is cyclic, so derivation wraps rather than clamps. The trig accepts
+ *  any angle; `Oklch.h` is documented 0..360 and readouts print it. */
+const wrapHue = (h: number): number => ((h % 360) + 360) % 360;
 
 export type SchemeDirection = 'light' | 'dark';
 
@@ -133,31 +143,31 @@ export function scaleCurveDefaults(scheme: SchemeDirection = 'dark'): ScaleCurve
   if (scheme === 'light') {
     return {
       Surfaces: {
-        lightness:  () => [makeAnchor(0, 98, 5),   makeAnchor(100, 82, 5)],
-        saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)],
+        lightness:  () => autoCurve(makeAnchor(0, 98), makeAnchor(100, 82)),
+        saturation: () => autoCurve(makeAnchor(0, 100), makeAnchor(100, 100)),
       },
       Borders: {
-        lightness:  () => [makeAnchor(0, 92, 5),   makeAnchor(100, 45, 5)],
-        saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)],
+        lightness:  () => autoCurve(makeAnchor(0, 92), makeAnchor(100, 45)),
+        saturation: () => autoCurve(makeAnchor(0, 100), makeAnchor(100, 100)),
       },
       Text: {
-        lightness:  () => [makeAnchor(0, 30, 30),  makeAnchor(100, 120, 30)],
-        saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 15, 30)],
+        lightness:  () => autoCurve(makeAnchor(0, 30), makeAnchor(100, 120)),
+        saturation: () => autoCurve(makeAnchor(0, 100), makeAnchor(100, 15)),
       },
     };
   }
   return {
     Surfaces: {
-      lightness:  () => [makeAnchor(0, 15, 5),   makeAnchor(100, 47, 5)],
-      saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)],
+      lightness:  () => autoCurve(makeAnchor(0, 15), makeAnchor(100, 47)),
+      saturation: () => autoCurve(makeAnchor(0, 100), makeAnchor(100, 100)),
     },
     Borders: {
-      lightness:  () => [makeAnchor(0, 25, 5),   makeAnchor(100, 80, 5)],
-      saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)],
+      lightness:  () => autoCurve(makeAnchor(0, 25), makeAnchor(100, 80)),
+      saturation: () => autoCurve(makeAnchor(0, 100), makeAnchor(100, 100)),
     },
     Text: {
-      lightness:  () => [makeAnchor(0, 120, 30), makeAnchor(100, 55, 30)],
-      saturation: () => [makeAnchor(0, 100, 30), makeAnchor(100, 15, 30)],
+      lightness:  () => autoCurve(makeAnchor(0, 120), makeAnchor(100, 55)),
+      saturation: () => autoCurve(makeAnchor(0, 100), makeAnchor(100, 15)),
     },
   };
 }
@@ -191,10 +201,10 @@ export type DerivedValue =
 
 /** The single color → CSS-string projection, and the single clamp point for
  *  derived color: unclamped stored intent is chroma-reduced into sRGB gamut,
- *  then serialized (hex this wave; `oklch()` after Part B). Idempotent on the
- *  already-in-gamut per-step derivation output. `raw` passes through untouched. */
+ *  then serialized as `oklch()`. Idempotent on the already-in-gamut per-step
+ *  derivation output. `raw` passes through untouched. */
 export function serializeDerivedValue(value: DerivedValue): string {
-  return value.kind === 'raw' ? value.css : oklchToHexClamped(value.l, value.c, value.h);
+  return value.kind === 'raw' ? value.css : oklchToCssClamped(value.l, value.c, value.h);
 }
 
 export function computePaletteOklch(
@@ -203,12 +213,18 @@ export function computePaletteOklch(
   lightnessCurve: CurveAnchor[],
   saturationCurve: CurveAnchor[],
   curveOffset: Record<string, number>,
+  hueCurve?: CurveAnchor[],
 ): Oklch {
-  const { c: baseC, h } = base;
+  const { c: baseC } = base;
   const xPos = stepIndexToX(index);
   const targetL = Math.max(0, Math.min(100, sampleCurve(lightnessCurve, xPos) + (curveOffset.lightness ?? 0))) / 100;
   const satMul = Math.max(0, Math.min(2, (sampleCurve(saturationCurve, xPos) + (curveOffset.saturation ?? 0)) / 100));
   const targetC = baseC * satMul;
+  // Zero delta skips the wrap rather than folding through it: `%360` round-trips
+  // introduce a one-ULP drift for most floats already in range, which would break
+  // byte-identity (Global invariant 1) for every palette with no hue curve.
+  const hueDelta = (hueCurve ? sampleCurve(hueCurve, xPos) : 0) + (curveOffset.hue ?? 0);
+  const h = hueDelta === 0 ? base.h : wrapHue(base.h + hueDelta);
   return gamutClamp(targetL, targetC, h);
 }
 
@@ -348,9 +364,10 @@ export function liftCurveAnchor(
 }
 
 /**
- * Place the base color in the ramp: pin a lightness anchor (base L) and a
- * saturation anchor (multiplier 100) at the step whose lightness is nearest
- * the base L, so the picked color renders verbatim at that step. Placement
+ * Place the base color in the ramp: pin a lightness anchor (base L), a
+ * saturation anchor (multiplier 100), and, when a hue curve exists, a hue
+ * anchor (delta 0), all at the step whose lightness is nearest the base L,
+ * so the picked color renders verbatim at that step. Placement
  * is measured against the curve with the previous placement lifted out —
  * the pinned anchor equals base L at its own x by construction, so measuring
  * against it would be circular and the anchor could never move. Runs inside
@@ -362,6 +379,9 @@ export function syncBaseAnchor(cfg: PaletteConfig): void {
   const fresh = prev === undefined;
   let lCurve = cfg.lightnessCurve;
   let sCurve = cfg.saturationCurve;
+  // Hue is pinned only once a curve exists (RJC 5): an absent curve is flat
+  // zero already, so there is nothing to lift or re-place.
+  let hCurve = cfg.hueCurve;
   if (prev) {
     // Re-placing an existing anchor (a hue move, typically) must preserve
     // whatever is currently on the curve, edited or not — never restore the
@@ -370,6 +390,7 @@ export function syncBaseAnchor(cfg: PaletteConfig): void {
     const prevX = stepIndexToX(prev.step);
     lCurve = liftCurveAnchor(lCurve, prevX, prev.displacedL);
     sCurve = liftCurveAnchor(sCurve, prevX, prev.displacedS);
+    if (hCurve) hCurve = liftCurveAnchor(hCurve, prevX, prev.displacedH);
   }
   const step = nearestPaletteStep(lCurve, cfg.baseColor.l);
   const x = stepIndexToX(step);
@@ -377,6 +398,8 @@ export function syncBaseAnchor(cfg: PaletteConfig): void {
   const s = setCurveAnchor(sCurve, x, 100, fresh);
   cfg.lightnessCurve = l.curve;
   cfg.saturationCurve = s.curve;
+  const h = hCurve ? setCurveAnchor(hCurve, x, 0, fresh) : undefined;
+  if (h) cfg.hueCurve = h.curve;
   // priorEndpoints is captured once, on the curve's first-ever placement,
   // and carried forward untouched thereafter so a later clear can still
   // restore the true original regardless of how many times the anchor moved.
@@ -384,18 +407,27 @@ export function syncBaseAnchor(cfg: PaletteConfig): void {
     step,
     displacedL: l.displacedY,
     displacedS: s.displacedY,
+    displacedH: h?.displacedY,
     priorLightnessEndpoints: prev?.priorLightnessEndpoints ?? l.priorEndpoints,
     priorSaturationEndpoints: prev?.priorSaturationEndpoints ?? s.priorEndpoints,
+    // No else-branch reading `prev?.priorHueEndpoints`: that could only fire
+    // if a placed hue curve later went absent, which RJC 7 (reset never
+    // deletes) never lets happen.
+    priorHueEndpoints: h ? (prev?.priorHueEndpoints ?? h.priorEndpoints) : undefined,
   };
 }
 
-/** Toggle-off: lift the placement out of both curves and drop the flag. */
+/** Toggle-off: lift the placement out of every curve it touched (hue only
+ *  if present) and drop the flag. */
 export function clearBaseAnchor(cfg: PaletteConfig): void {
   const prev = cfg.anchorPlacement;
   if (prev) {
     const x = stepIndexToX(prev.step);
     cfg.lightnessCurve = liftCurveAnchor(cfg.lightnessCurve, x, prev.displacedL, prev.priorLightnessEndpoints);
     cfg.saturationCurve = liftCurveAnchor(cfg.saturationCurve, x, prev.displacedS, prev.priorSaturationEndpoints);
+    if (cfg.hueCurve) {
+      cfg.hueCurve = liftCurveAnchor(cfg.hueCurve, x, prev.displacedH, prev.priorHueEndpoints);
+    }
     cfg.anchorPlacement = undefined;
   }
   cfg.anchorToBase = false;
@@ -405,7 +437,7 @@ export function computeDerivedOklch(
   step: Step,
   base: Oklch,
   scaleTitle: string,
-  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>,
+  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[]; hue?: CurveAnchor[] }>,
   curveOffset: Record<string, number>,
 ): Oklch {
   const scale = SCALES.find((s) => s.title === scaleTitle)!;
@@ -413,8 +445,10 @@ export function computeDerivedOklch(
   const defs = defaultScaleCurves[scaleTitle];
   const lCurve = scaleCurves[scaleTitle]?.lightness ?? defs.lightness();
   const sCurve = scaleCurves[scaleTitle]?.saturation ?? defs.saturation();
+  const hCurve = scaleCurves[scaleTitle]?.hue;
   const lOff = curveOffset[`${scaleTitle}-lightness`] ?? 0;
   const sOff = curveOffset[`${scaleTitle}-saturation`] ?? 0;
+  const hOff = curveOffset[`${scaleTitle}-hue`] ?? 0;
   const { l: baseL, c: baseC, h: baseH } = base;
   let targetL: number;
   if (scale.isText) {
@@ -425,7 +459,10 @@ export function computeDerivedOklch(
   }
   const satMul = Math.max(0, Math.min(2, (sampleCurve(sCurve, xPos) + sOff) / 100));
   const targetC = baseC * satMul;
-  return gamutClamp(targetL, targetC, baseH);
+  // See computePaletteOklch: zero delta skips the wrap to preserve byte-identity.
+  const hueDelta = (hCurve ? sampleCurve(hCurve, xPos) : 0) + hOff;
+  const targetH = hueDelta === 0 ? baseH : wrapHue(baseH + hueDelta);
+  return gamutClamp(targetL, targetC, targetH);
 }
 
 export function scaleToCssVar(scaleTitle: string, stepName: string, cssNamespace: string | null): string | null {
@@ -461,7 +498,7 @@ export function derivePaletteValues(spec: PaletteSpec, config: PaletteConfig | u
     // Overrides are numeric OKLCH intent; pass straight through as color-kind.
     const value: DerivedValue = (k in overrides)
       ? { kind: 'color', ...overrides[k] }
-      : { kind: 'color', ...computePaletteOklch(index, baseColor, lightnessCurve, saturationCurve, curveOffset) };
+      : { kind: 'color', ...computePaletteOklch(index, baseColor, lightnessCurve, saturationCurve, curveOffset, config.hueCurve) };
     out[`--color-${spec.cssNamespace}-${ps.label}`] = value;
   });
 
@@ -512,8 +549,8 @@ export function derivePaletteValues(spec: PaletteSpec, config: PaletteConfig | u
       const stopsCss = sortedStops
         .map((s) => {
           const stopValue = out[`--color-${spec.cssNamespace}-${s.paletteLabel}`];
-          const hex = stopValue ? serializeDerivedValue(stopValue) : '#000000';
-          return `${hex} ${s.position}%`;
+          const css = stopValue ? serializeDerivedValue(stopValue) : 'oklch(0 0 0)';
+          return `${css} ${s.position}%`;
         })
         .join(', ');
       let gradient: string;
@@ -554,8 +591,6 @@ 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:
@@ -596,11 +631,13 @@ export function reconcilePalettesFromCssVars(
     if (current === undefined) continue;
 
     if (current._imported === true) {
-      const anchorHex = cssVars[`--color-${spec.cssNamespace}-500`];
-      if (anchorHex && HEX_RE.test(anchorHex.trim())) {
-        // Input boundary: the imported cssVariables anchor is a hex string;
-        // parse it to the OKLCH basis exactly once, here.
-        next[spec.label] = { ...current, baseColor: hexToOklch(anchorHex.trim()), _imported: false };
+      const anchor = cssVars[`--color-${spec.cssNamespace}-500`];
+      const anchorOklch = anchor ? cssColorToOklch(anchor) : null;
+      if (anchorOklch) {
+        // Input boundary: the imported cssVariables anchor is a CSS string in
+        // either serialization this system has shipped (hex before the OKLCH
+        // flip, `oklch()` after); parse it to the basis exactly once, here.
+        next[spec.label] = { ...current, baseColor: anchorOklch, _imported: false };
         syncBaseAnchor(next[spec.label]);
         snapped.add(spec.label);
       } else {
@@ -611,7 +648,12 @@ export function reconcilePalettesFromCssVars(
       }
     }
 
-    for (const k of Object.keys(derivePaletteVars(spec, next[spec.label]))) {
+    // Key names only: which variables this palette owns is a structural
+    // question, so read the IR rather than serializing values that are
+    // discarded. Callers reach here with pre-migration configs whose
+    // `baseColor` is still a hex string; serializing those derived NaNs used
+    // to produce junk strings nobody read.
+    for (const k of Object.keys(derivePaletteValues(spec, next[spec.label]))) {
       consumed.add(k);
     }
   }

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

@@ -28,6 +28,7 @@ import {
   CURRENT_COMPONENT_SCHEMA_VERSION,
   runMigrations,
 } from '../themes/migrations';
+import { migrateComponentConfig } from '../themes/migrateComponentConfig';
 import { renamePrimaryPaletteKey } from '../themes/migrations/2026-05-13-primary-to-brand';
 import {
   renameBackgroundPaletteKey,
@@ -220,202 +221,11 @@ export {
 // `fromVersion >= file.schemaVersion`, then `splitAliasesAndConfig` routes
 // 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,
-  aliasesIn: Record<string, AliasDiskValue>,
-  rawConfig: Record<string, unknown> | undefined,
-  fileVersion: number,
-): { 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,
-      },
-    };
-  }
-}
+//
+// The migration itself — `migrateComponentConfig`, plus its sectiondivider
+// gradient helpers — lives in `../themes/migrateComponentConfig` so the
+// server (`normalizeTheme`) can run the same pass over an embedded theme
+// config instead of reading it raw.
 
 /**
  * Disk-shape → in-memory split. Routes legacy single-bucket aliases that
@@ -459,7 +269,7 @@ export function toComponentSlice(
   config?: Record<string, unknown>,
   schemaVersion: number = 0,
 ): { aliases: Record<string, CssVarRef>; config: Record<string, unknown> } {
-  const migrated = migrateComponentAliases(component, aliases, config, schemaVersion);
+  const migrated = migrateComponentConfig(component, aliases, config, schemaVersion);
   return splitAliasesAndConfig(migrated.aliases, migrated.config);
 }