@motion-proto/live-tokens 0.50.0 → 0.52.1

package/dist-plugin/tokensCssMigrations/index.d.ts

@@ -52,6 +52,8 @@ interface TokensCssMigration {
  */
 /** Names declared as custom properties (`--x: …;`) anywhere in the source. */
 declare function collectDefinedTokens(css: string): Set<string>;
+/** Declared name → value, last declaration winning (as the cascade would). */
+declare function collectTokenValues(css: string): Map<string, string>;
 /** Names referenced via `var(--x)` anywhere in the source. */
 declare function collectReferencedTokens(css: string): Set<string>;
 interface ScaleEntry {
@@ -123,16 +125,25 @@ interface ContractViolation {
     id: string;
     /** Token names the migration removed or renamed away despite declaring `additive`. */
     removed: string[];
+    /** Token names whose value the migration rewrote despite declaring `additive`. */
+    changed: string[];
 }
 /**
- * Guardrail for the token-as-API contract: an `additive` migration must never
- * remove or rename a token. We verify behaviorally rather than trusting the
- * label — apply each additive migration to the package's own canonical
- * `tokens.css` (which defines the full current vocabulary) and flag any token
- * that disappears. A rename surfaces as the removal of its old name, so it is
- * caught too. This catches the dangerous direction: a breaking change shipped as
- * a backward-compatible one. (Over-labeling a no-op as `breaking` is harmless
- * and not checked.)
+ * Guardrail for the token-as-API contract: an `additive` migration must only
+ * ever insert new names — it must never remove or rename a token, and never
+ * rewrite the value of one a consumer already references. We verify
+ * behaviorally rather than trusting the label: apply each additive migration to
+ * the package's own canonical `tokens.css` (which defines the full current
+ * vocabulary) and flag any token that disappears or changes value. A rename
+ * surfaces as the removal of its old name, so it is caught too.
+ *
+ * The value half is what makes a value-rewriting migration (hex → `oklch()`)
+ * impossible to mislabel: it renames nothing, so a name-only guard would wave
+ * it through as additive and the dev plugin would auto-apply a breaking change
+ * to a consumer's vendored file.
+ *
+ * This catches the dangerous direction only. (Over-labeling a no-op as
+ * `breaking` is harmless and not checked.)
  */
 declare function findContractViolations(canonicalCss: string): ContractViolation[];
 type SemverBump = 'major' | 'minor' | 'patch' | 'none';
@@ -183,4 +194,4 @@ interface ValidateInput {
  */
 declare function validateTokensCss(input: ValidateInput): MissingToken[];
 
-export { type BreakingGateResult, type ComponentSource, type ContractViolation, type MissingToken, type RunResult, type SemverBump, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, enforceBreakingRequiresMajor, ensureScale, findContractViolations, removeToken, removeTokensMatching, renameToken, runAdditiveTokensCssMigrations, runTokensCssMigrations, semverBumpType, validateTokensCss };
+export { type BreakingGateResult, type ComponentSource, type ContractViolation, type MissingToken, type RunResult, type SemverBump, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, collectTokenValues, enforceBreakingRequiresMajor, ensureScale, findContractViolations, removeToken, removeTokensMatching, renameToken, runAdditiveTokensCssMigrations, runTokensCssMigrations, semverBumpType, validateTokensCss };

package/dist-plugin/tokensCssMigrations/index.js

@@ -2,6 +2,7 @@ import {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  collectTokenValues,
   enforceBreakingRequiresMajor,
   ensureScale,
   findContractViolations,
@@ -12,7 +13,8 @@ import {
   runTokensCssMigrations,
   semverBumpType,
   validateTokensCss
-} from "../chunk-44RSTAII.js";
+} from "../chunk-TKZBVIW5.js";
+import "../chunk-YR6GPXW2.js";
 import {
   readLiveTokensConfig
 } from "../chunk-D3ZVKOR4.js";
@@ -20,6 +22,7 @@ export {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  collectTokenValues,
   enforceBreakingRequiresMajor,
   ensureScale,
   findContractViolations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.50.0",
+  "version": "0.52.1",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -110,7 +110,9 @@
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:e2e": "playwright test",
+    "test:e2e": "npm run test:e2e:contract && npm run test:e2e:stateful",
+    "test:e2e:contract": "playwright test tests/e2e/component-render-contract.spec.ts tests/e2e/component-alias-contract.spec.ts --workers=4",
+    "test:e2e:stateful": "playwright test tests/e2e/live-editing.spec.ts tests/e2e/theme-workflow.spec.ts --workers=1",
     "test:e2e:components": "playwright test tests/e2e/component-render-contract.spec.ts",
     "test:e2e:ui": "playwright test --ui",
     "prepare:e2e": "node scripts/prepare-playwright-data.mjs",

package/src/editor/component-editor/NotificationEditor.svelte

@@ -87,12 +87,14 @@
   let dismissible = $state(false);
   let rightOption: ButtonVariantOption = $state('none');
   let leftOption: ButtonVariantOption = $state('none');
+  let headerAction = $state(false);
   let actions = $derived(((): NotificationActions => {
     const a: NotificationActions = {};
     const right = toVariant(rightOption);
     const left = toVariant(leftOption);
     if (right) a.right = { label: 'Confirm', variant: right, onClick: () => {} };
     if (left) a.left = { label: 'Cancel', variant: left, onClick: () => {} };
+    if (headerAction) a.header = { label: 'Action', onClick: () => {} };
     return a;
   })());
 </script>
@@ -112,6 +114,10 @@
           <input type="checkbox" bind:checked={dismissible} />
           <span>Dismissible</span>
         </label>
+        <label class="toolbar-check">
+          <input type="checkbox" bind:checked={headerAction} />
+          <span>Header button</span>
+        </label>
         <label class="toolbar-field">
           <span>Right button</span>
           <select class="canvas-toolbar-select" bind:value={rightOption}>

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/themes/generateColorsAndType.ts

@@ -5,7 +5,7 @@
  * `dist-plugin/generateColorsAndType`, so keep this module Node-safe (no DOM).
  */
 
-import { hexToOklch, type Oklch } from '../palettes/oklch';
+import { hexToOklch, cssColorToOklch, oklchToHexClamped, type Oklch } from '../palettes/oklch';
 import {
   PALETTE_SPECS,
   PALETTE_STEPS,
@@ -201,6 +201,15 @@ function surfaceVars(): string[] {
   ];
 }
 
+/** Derived vars serialize as `oklch()` while the WCAG contrast API is
+ *  sRGB-terminated (decision 7), so project back to hex at this boundary.
+ *  Gradient `--page-bg` parses to null and is skipped, as it was when these
+ *  call sites read hex directly. */
+function varToHex(value: string | undefined): string | null {
+  const parsed = value ? cssColorToOklch(value) : null;
+  return parsed ? oklchToHexClamped(parsed.l, parsed.c, parsed.h) : null;
+}
+
 function worstSurface(
   textHex: string,
   vars: Record<string, string>,
@@ -208,8 +217,8 @@ function worstSurface(
   let against = '';
   let ratio = Infinity;
   for (const surfVar of surfaceVars()) {
-    const surfHex = vars[surfVar];
-    if (!surfHex || !HEX_RE.test(surfHex)) continue;
+    const surfHex = varToHex(vars[surfVar]);
+    if (!surfHex) continue;
     const r = contrastRatio(textHex, surfHex);
     if (r < ratio) {
       ratio = r;
@@ -248,17 +257,18 @@ function runContrastGate(
     const vars = palettesToVars(configs);
     let anyFixed = false;
     for (const def of defs) {
-      const textHex = vars[def.textVar];
-      if (!textHex) continue;
+      const text = cssColorToOklch(vars[def.textVar] ?? '');
+      if (!text) continue;
+      const textHex = oklchToHexClamped(text.l, text.c, text.h);
       const worst = worstSurface(textHex, vars);
       if (worst.ratio >= def.floor) continue;
       const cfg = configs[def.paletteLabel];
       const seed = cfg.baseColor;
       const solved = findLForContrast({
-        against: vars[worst.against],
+        against: varToHex(vars[worst.against]) ?? '#000000',
         ratio: def.target,
         direction,
-        c: hexToOklch(textHex).c,
+        c: text.c,
         h: seed.h,
         lMax: Math.min(1, 2 * seed.l),
       });
@@ -271,7 +281,7 @@ function runContrastGate(
 
   const finalVars = palettesToVars(configs);
   const checks: ContrastCheck[] = defs.map((def) => {
-    const worst = worstSurface(finalVars[def.textVar] ?? '#000000', finalVars);
+    const worst = worstSurface(varToHex(finalVars[def.textVar]) ?? '#000000', finalVars);
     return {
       textVar: def.textVar,
       floor: def.floor,

package/src/editor/core/themes/themeTypes.ts

@@ -16,8 +16,17 @@ export interface PaletteConfig {
   baseColor: Oklch;
   lightnessCurve: CurveAnchor[];
   saturationCurve: CurveAnchor[];
-  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>;
+  /** Signed hue offset in degrees per step, applied on top of the base hue.
+   *  Absent means flat zero: the palette holds one hue, which is what every
+   *  theme saved before this field did. */
+  hueCurve?: CurveAnchor[];
+  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[]; hue?: CurveAnchor[] }>;
   curveOffset: Record<string, number>;
+  /** Per curve key: are the tangents derived from the points, or held by hand?
+   *  Only an explicit switch-off is recorded. A missing key means the curve's own
+   *  shape answers (`isAutoSmoothCurve`), which is what every theme saved before
+   *  the flag existed relies on. */
+  curveAutoSmooth?: Record<string, boolean>;
   overrides: Record<string, Oklch>;
   snappedScales: string[];
   emptyMode?: 'solid' | 'gradient';
@@ -30,11 +39,12 @@ export interface PaletteConfig {
   /**
    * Where the base color sits in the ramp while `anchorToBase` is on: the
    * PALETTE_STEPS index whose curve anchors are pinned to the base color
-   * (lightness = base L, saturation = multiplier 100). `displacedL` /
-   * `displacedS` remember the y of a pre-existing anchor (endpoint or
-   * user-authored) the placement overwrote at that x, so moving the
-   * placement or toggling off restores it instead of deleting it.
-   * `priorLightnessEndpoints` / `priorSaturationEndpoints` remember the two
+   * (lightness = base L, saturation = multiplier 100, hue delta = 0 when a
+   * hue curve exists). `displacedL` / `displacedS` / `displacedH` remember
+   * the y of a pre-existing anchor (endpoint or user-authored) the placement
+   * overwrote at that x, so moving the placement or toggling off restores it
+   * instead of deleting it. `priorLightnessEndpoints` /
+   * `priorSaturationEndpoints` / `priorHueEndpoints` remember the two
    * endpoints exactly as they stood before the curve's first-ever placement
    * (a smoothed reshape, not algebraically invertible the way a later
    * scaled-handle re-placement is), so a clear can still restore the true
@@ -44,8 +54,10 @@ export interface PaletteConfig {
     step: number;
     displacedL?: number;
     displacedS?: number;
+    displacedH?: number;
     priorLightnessEndpoints?: [CurveAnchor, CurveAnchor];
     priorSaturationEndpoints?: [CurveAnchor, CurveAnchor];
+    priorHueEndpoints?: [CurveAnchor, CurveAnchor];
   };
   /**
    * Set to true by importers when they overlay `cssVariables[--color-{ns}-*]`