@newtonedev/colors 0.0.1 → 1.1.0

package/README.md

@@ -33,26 +33,25 @@ const hexValues = scale.map(oklchToHex);
 
 | Option | Type | Default | Description |
 |---|---|---|---|
+| `contrast.light` | `number` | `1` | How light the lightest step is (0–1). 0 = near-white, 1 = pure white. |
+| `contrast.dark` | `number` | `1` | How dark the darkest step is (0–1). 0 = near-black, 1 = pure black. |
 | `hue` | `number` | — | Hue angle in degrees (0–360) |
-| `steps` | `number` | — | Number of steps (minimum 2) |
-| `chroma.value` | `number` | `1` | How much of the gamut to use (0–1). 0 = achromatic, 1 = maximum. |
-| `chroma.offset` | `number` | `0.5` | Where in the scale chroma peaks (0 = lightest end, 1 = darkest end). |
-| `gamut` | `"srgb" \| "display-p3"` | `"srgb"` | Target gamut for chroma boundary. |
-| `lightest` | `number` | `1` | Lightness of the lightest step. |
-| `darkest` | `number` | `0` | Lightness of the darkest step. |
+| `chroma.amount` | `number` | `0` | How much of the gamut to use (0–1). 0 = achromatic, 1 = maximum. |
+| `chroma.balance` | `number` | `0.5` | How chroma is distributed along the scale (0 = toward lightest, 1 = toward darkest). |
+| `isP3` | `boolean` | `false` | Use Display P3 gamut instead of sRGB. |
 | `grading` | `Grading` | — | Global hue grading shared across all palettes. |
-| `gradient` | `Gradient` | — | Per-palette one-sided hue grade. |
+| `shift` | `Shift` | — | Per-palette one-sided hue shift. Defaults to the dark end; set `light: true` for the light end. |
 
 ---
 
 ## Key color workflow
 
-Derive scale parameters from a brand color, then locate it in the generated scale:
+Derive scale parameters from a known color, then locate it in the generated scale:
 
 ```ts
 import { keyColor, generateScale, findNearest, oklchToHex } from "newtone-colors";
 
-const key = keyColor("#3B82F6", { gamut: "srgb", lightest: 0.96, darkest: 0.16 });
+const key = keyColor("#3B82F6", { contrast: { light: 0, dark: 0 } });
 const scale = generateScale({ ...key, steps: 11 });
 const { index } = findNearest(key.resolved.oklch, scale);
 
@@ -60,7 +59,7 @@ const { index } = findNearest(key.resolved.oklch, scale);
 console.log(oklchToHex(scale[index]));
 ```
 
-`keyColor` derives `hue` and `chroma` (value + offset) from the color and returns them ready to spread into `ScaleOptions`. The `chroma.offset` is computed from where the color's lightness falls within the scale range, so the chroma peak aligns with the key color's position.
+`keyColor` derives `hue` and `chroma` (amount + balance) from the color and returns them ready to spread into `ScaleOptions`. The `chroma.balance` is computed from where the color's lightness falls within the scale range, so the chroma distribution is centered around the key color's position.
 
 The reverse direction — step to hex — is already covered by `oklchToHex(scale[index])`.
 
@@ -72,22 +71,22 @@ Shift hues at the light or dark end of the scale toward a target hue, using vect
 
 ```ts
 import { generateScale } from "newtone-colors";
-import type { Grading, Gradient } from "newtone-colors";
+import type { Grading, Shift } from "newtone-colors";
 
 // Global: affects all palettes equally
 const grading: Grading = {
-  lightHue: 145,  lightValue: 0.15,  // light end shifts toward 145°
-  darkHue: 25,    darkValue: 0.15,   // dark end shifts toward 25°
+  light: { hue: 145, amount: 0.15 },  // light end shifts toward 145°
+  dark:  { hue: 25,  amount: 0.15 },  // dark end shifts toward 25°
 };
 
-// Per-palette: one-sided, stronger
-const gradient: Gradient = {
+// Per-palette: one-sided, stronger. Omit `light` or set false for dark end.
+const shift: Shift = {
   hue: 200,
-  value: 0.3,
-  direction: "dark",  // only affects the dark end
+  amount: 0.3,
+  // light: true  ← uncomment to target the light end instead
 };
 
-const scale = generateScale({ hue: 264, steps: 11, grading, gradient });
+const scale = generateScale({ hue: 264, grading, shift });
 ```
 
 ---
@@ -99,10 +98,10 @@ Map slider values (0–1) to lightness bounds. The defaults keep the scale away
 ```ts
 import { resolveLightest, resolveDarkest } from "newtone-colors";
 
-const lightest = resolveLightest(0);  // → 0.96 (MIN_LIGHTEST_L)
-const darkest  = resolveDarkest(0);   // → 0.16 (MAX_DARKEST_L)
+const lightL = resolveLightest(0);  // → 0.96 (MIN_LIGHTEST_L)
+const darkL  = resolveDarkest(0);   // → 0.16 (MAX_DARKEST_L)
 
-const scale = generateScale({ hue: 264, steps: 11, lightest, darkest });
+const scale = generateScale({ contrast: { light: 0, dark: 0 }, hue: 264, steps: 11 });
 ```
 
 See [docs/constants.md](docs/constants.md) for all hardcoded values and their rationale.
@@ -145,9 +144,9 @@ Resolve any hex or OKLCH input to scale-ready parameters, with automatic gamut m
 ```ts
 import { resolveColor } from "newtone-colors";
 
-const result = resolveColor("#E74C3C", "srgb");
+const result = resolveColor("#E74C3C");
 result.hue;          // extracted hue
-result.chromaRatio;  // chroma as fraction of gamut boundary → ScaleOptions.chroma.value
+result.chromaRatio;  // chroma as fraction of gamut boundary → ScaleOptions.chroma.amount
 result.wasRemapped;  // true if the color was outside the target gamut
 result.original;     // original OKLCH before mapping
 ```

package/dist/__tests__/key-color.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=key-color.test.d.ts.map

package/dist/__tests__/key-color.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-color.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/key-color.test.ts"],"names":[],"mappings":""}

package/dist/config.d.ts

@@ -4,6 +4,18 @@
  * Edit this file to adjust the perceptual behavior of every scale and
  * grading operation across the library.
  */
+/**
+ * Default number of steps in a generated scale.
+ * Fixed at 26 — enough for a full design token set with fine lightness
+ * increments without redundancy.
+ */
+export declare const DEFAULT_SCALE_STEPS = 26;
+/**
+ * Default hue when none is provided.
+ * 0° is the start of the OKLCH hue wheel (red region). Arbitrary but
+ * deterministic — callers should always supply an explicit hue.
+ */
+export declare const DEFAULT_HUE = 0;
 /**
  * Lightest step's lightness when the whites slider is at 0.
  * slider 0 → L = MIN_LIGHTEST_L, slider 1 → L = 1.0 (pure white).
@@ -15,20 +27,28 @@ export declare const MIN_LIGHTEST_L = 0.96;
  */
 export declare const MAX_DARKEST_L = 0.16;
 /**
- * How far a global grade reaches into the scale from each end (0–1).
- * Light grading fades to zero at t = GRADE_REACH.
- * Dark grading fades to zero at t = 1 − GRADE_REACH.
+ * How far global grading reaches into the scale from each end (0–1).
+ * Light grading fades to zero at t = GRADING_REACH.
+ * Dark grading fades to zero at t = 1 − GRADING_REACH.
+ */
+export declare const GRADING_REACH: number;
+/** Maximum amount for global grading. Inputs above this are clamped. */
+export declare const MAX_GRADING_AMOUNT = 0.25;
+/**
+ * Fraction of the gamut boundary injected as chroma when global grading
+ * is active. Ensures grading has a visible tinting effect even on
+ * achromatic (chroma.amount = 0) palettes.
+ *
+ * Only global grading injects chroma — per-palette shift does not.
  */
-export declare const GRADE_REACH: number;
-/** Maximum blend intensity for global grading. Inputs above this are clamped. */
-export declare const MAX_GRADE_INTENSITY = 0.25;
+export declare const GRADING_CHROMA_RATIO = 0.5;
 /**
- * How far a local (per-palette) grade reaches into the scale from each end (0–1).
- * Slightly wider than GRADE_REACH to give per-palette grading more room.
+ * How far per-palette hue shift reaches into the scale from each end (0–1).
+ * Slightly wider than GRADING_REACH to give per-palette shifts more room.
  */
-export declare const LOCAL_GRADE_REACH: number;
-/** Maximum blend intensity for local grading. Inputs above this are clamped. */
-export declare const MAX_LOCAL_GRADE_INTENSITY = 0.5;
+export declare const SHIFT_REACH: number;
+/** Maximum amount for per-palette hue shift. Inputs above this are clamped. */
+export declare const MAX_SHIFT_AMOUNT = 0.5;
 /**
  * Just-noticeable difference threshold (deltaEOK).
  * Colors with distance below this are considered perceptually identical.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,aAAa,OAAO,CAAC;AAIlC;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAQ,CAAC;AAEjC,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAI7C;;;;GAIG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAI7B;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,aAAa,OAAO,CAAC;AAIlC;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAQ,CAAC;AAEnC,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAQ,CAAC;AAEjC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAIpC;;;;GAIG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC"}

package/dist/contrast/apca.d.ts

@@ -10,5 +10,21 @@ import type { Srgb } from "../types.js";
  * IMPORTANT: Uses its own linearization (simple 2.4 gamma),
  * NOT the IEC piecewise sRGB transfer function.
  */
+/**
+ * Practical maximum APCA Lc magnitude used for normalization.
+ * BoW tops out at ~+106, WoB at ~-108; we use 108 as a symmetric ceiling.
+ */
+export declare const APCA_LC_MAX = 108;
+/**
+ * Normalize a raw APCA Lc value to the range [-1, +1].
+ *   +1 = maximum dark-on-light contrast (BoW)
+ *   -1 = maximum light-on-dark contrast (WoB)
+ *    0 = no meaningful contrast
+ */
+export declare function apcaToNormalized(lc: number): number;
+/**
+ * Convert a normalized contrast value [-1, +1] back to a raw APCA Lc value.
+ */
+export declare function normalizedToApca(normalized: number): number;
 export declare function apcaContrast(textColor: Srgb, bgColor: Srgb): number;
 //# sourceMappingURL=apca.d.ts.map

package/dist/contrast/apca.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apca.d.ts","sourceRoot":"","sources":["../../src/contrast/apca.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAoBxC;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAmCnE"}
+{"version":3,"file":"apca.d.ts","sourceRoot":"","sources":["../../src/contrast/apca.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAoBxC;;;;;;;;;;GAUG;AACH;;;GAGG;AACH,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAmCnE"}

package/dist/gamut/max-chroma.d.ts

@@ -1,8 +1,13 @@
 import type { Gamut } from "../types.js";
 /**
- * Find the maximum gamut chroma for a given OKLCH lightness and hue.
- * Binary search on chroma [0, upperBound].
- * @param gamut Target gamut (default: 'srgb'). P3 searches up to 0.5.
+ * Find the maximum in-gamut chroma for a given OKLCH lightness and hue.
+ *
+ * Binary search over [0, upperBound], converging to 1e-6 precision.
+ * Upper bounds are empirically safe ceilings — no in-gamut color at any
+ * lightness or hue exceeds C = 0.4 in sRGB or C = 0.5 in Display P3.
+ * Searching beyond these would waste iterations with no benefit.
+ *
+ * Returns 0 for L ≤ 0 or L ≥ 1 (pure black and white carry no chroma).
  */
 export declare function maxChroma(L: number, h: number, gamut?: Gamut): number;
 //# sourceMappingURL=max-chroma.d.ts.map

package/dist/gamut/max-chroma.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"max-chroma.d.ts","sourceRoot":"","sources":["../../src/gamut/max-chroma.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAKhD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,KAAc,GAAG,MAAM,CAsB7E"}
+{"version":3,"file":"max-chroma.d.ts","sourceRoot":"","sources":["../../src/gamut/max-chroma.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAKhD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,KAAc,GAAG,MAAM,CAsB7E"}

package/dist/index.cjs

@@ -304,6 +304,13 @@ function contrastTextHex(background) {
 }
 
 // src/contrast/apca.ts
+var APCA_LC_MAX = 108;
+function apcaToNormalized(lc) {
+  return Math.max(-1, Math.min(1, lc / APCA_LC_MAX));
+}
+function normalizedToApca(normalized) {
+  return normalized * APCA_LC_MAX;
+}
 function apcaContrast(textColor, bgColor) {
   let txtY = APCA_SRGB_R * textColor.r ** APCA_MAIN_TRC + APCA_SRGB_G * textColor.g ** APCA_MAIN_TRC + APCA_SRGB_B * textColor.b ** APCA_MAIN_TRC;
   let bgY = APCA_SRGB_R * bgColor.r ** APCA_MAIN_TRC + APCA_SRGB_G * bgColor.g ** APCA_MAIN_TRC + APCA_SRGB_B * bgColor.b ** APCA_MAIN_TRC;
@@ -345,84 +352,147 @@ function mix(a, b, t) {
 }
 
 // src/config.ts
+var DEFAULT_SCALE_STEPS = 26;
+var DEFAULT_HUE = 0;
 var MIN_LIGHTEST_L = 0.96;
 var MAX_DARKEST_L = 0.16;
-var GRADE_REACH = 3 / 5;
-var MAX_GRADE_INTENSITY = 0.25;
-var LOCAL_GRADE_REACH = 2 / 3;
-var MAX_LOCAL_GRADE_INTENSITY = 0.5;
+var GRADING_REACH = 3 / 5;
+var MAX_GRADING_AMOUNT = 0.25;
+var GRADING_CHROMA_RATIO = 0.5;
+var SHIFT_REACH = 2 / 3;
+var MAX_SHIFT_AMOUNT = 0.5;
 var PERCEPTUAL_JND = 0.02;
 
 // src/scale/hue-grade.ts
-function gradeHue(baseHue, t, grade, reach = GRADE_REACH, maxIntensity = MAX_GRADE_INTENSITY) {
-  const { lightHue, lightValue, darkHue, darkValue } = grade;
-  const li = Math.max(0, Math.min(maxIntensity, lightValue));
-  const di = Math.max(0, Math.min(maxIntensity, darkValue));
+function gradeHue(baseHue, t, grade, reach = GRADING_REACH, maxIntensity = MAX_GRADING_AMOUNT) {
+  const li = Math.max(0, Math.min(maxIntensity, grade.light?.amount ?? 0));
+  const di = Math.max(0, Math.min(maxIntensity, grade.dark?.amount ?? 0));
   if (li === 0 && di === 0) return baseHue;
   const lightInfluence = t <= reach ? 0.5 * (1 + Math.cos(Math.PI * t / reach)) : 0;
   const darkInfluence = t >= 1 - reach ? 0.5 * (1 + Math.cos(Math.PI * (1 - t) / reach)) : 0;
-  const toRad = Math.PI / 180;
-  const baseRad = baseHue * toRad;
+  const toRad2 = Math.PI / 180;
+  const baseRad = baseHue * toRad2;
   const bx = Math.cos(baseRad);
   const by = Math.sin(baseRad);
   let dx = 0;
   let dy = 0;
   if (lightInfluence > 0 && li > 0) {
     const blend = lightInfluence * li;
-    const lRad = lightHue * toRad;
+    const lRad = grade.light.hue * toRad2;
     dx += blend * (Math.cos(lRad) - bx);
     dy += blend * (Math.sin(lRad) - by);
   }
   if (darkInfluence > 0 && di > 0) {
     const blend = darkInfluence * di;
-    const dRad = darkHue * toRad;
+    const dRad = grade.dark.hue * toRad2;
     dx += blend * (Math.cos(dRad) - bx);
     dy += blend * (Math.sin(dRad) - by);
   }
   const rx = bx + dx;
   const ry = by + dy;
   if (rx * rx + ry * ry < 1e-20) return baseHue;
-  return (Math.atan2(ry, rx) / toRad + 360) % 360;
+  return (Math.atan2(ry, rx) / toRad2 + 360) % 360;
+}
+function gradingInfluence(t, grading) {
+  const li = Math.max(0, Math.min(MAX_GRADING_AMOUNT, grading.light?.amount ?? 0));
+  const di = Math.max(0, Math.min(MAX_GRADING_AMOUNT, grading.dark?.amount ?? 0));
+  if (li === 0 && di === 0) return 0;
+  const lightInfluence = t <= GRADING_REACH ? 0.5 * (1 + Math.cos(Math.PI * t / GRADING_REACH)) : 0;
+  const darkInfluence = t >= 1 - GRADING_REACH ? 0.5 * (1 + Math.cos(Math.PI * (1 - t) / GRADING_REACH)) : 0;
+  const lightBlend = lightInfluence * (li / MAX_GRADING_AMOUNT);
+  const darkBlend = darkInfluence * (di / MAX_GRADING_AMOUNT);
+  return Math.max(lightBlend, darkBlend);
 }
 function resolveGradedHue(baseHue, t, globalGrade, localGrade) {
   let h = baseHue;
+  if (localGrade) h = gradeHue(h, t, localGrade, SHIFT_REACH, MAX_SHIFT_AMOUNT);
   if (globalGrade) h = gradeHue(h, t, globalGrade);
-  if (localGrade) h = gradeHue(h, t, localGrade, LOCAL_GRADE_REACH, MAX_LOCAL_GRADE_INTENSITY);
   return h;
 }
-function buildOneSidedGrade(hue, value, side) {
-  return side === "light" ? { lightHue: hue, lightValue: value, darkHue: 0, darkValue: 0 } : { lightHue: 0, lightValue: 0, darkHue: hue, darkValue: value };
+function buildOneSidedGrade(hue, amount, light = false) {
+  return light ? { light: { hue, amount } } : { dark: { hue, amount } };
+}
+
+// src/scale/dynamic-range.ts
+function resolveLightest(slider) {
+  const s = Math.max(0, Math.min(1, slider));
+  return MIN_LIGHTEST_L + s * (1 - MIN_LIGHTEST_L);
+}
+function resolveDarkest(slider) {
+  const s = Math.max(0, Math.min(1, slider));
+  return MAX_DARKEST_L * (1 - s);
+}
+function lightnessToScaleT(L, lightestL, darkestL) {
+  const range = lightestL - darkestL;
+  if (range <= 0) return 0.5;
+  return Math.max(0, Math.min(1, (lightestL - L) / range));
 }
 
 // src/scale/generate.ts
-function generateScale(options) {
+var toRad = Math.PI / 180;
+function applyGradingOverlay(C, h, L, t, grading, gamut) {
+  const li = Math.max(0, Math.min(MAX_GRADING_AMOUNT, grading.light?.amount ?? 0));
+  const di = Math.max(0, Math.min(MAX_GRADING_AMOUNT, grading.dark?.amount ?? 0));
+  if (li === 0 && di === 0) return { C, h };
+  const lightFade = t <= GRADING_REACH ? 0.5 * (1 + Math.cos(Math.PI * t / GRADING_REACH)) : 0;
+  const darkFade = t >= 1 - GRADING_REACH ? 0.5 * (1 + Math.cos(Math.PI * (1 - t) / GRADING_REACH)) : 0;
+  const lightBlend = lightFade * (li / MAX_GRADING_AMOUNT);
+  const darkBlend = darkFade * (di / MAX_GRADING_AMOUNT);
+  if (lightBlend === 0 && darkBlend === 0) return { C, h };
+  const hRad = h * toRad;
+  let a = C * Math.cos(hRad);
+  let b = C * Math.sin(hRad);
+  if (lightBlend > 0) {
+    const lh = grading.light.hue;
+    const lRad = lh * toRad;
+    const lC = maxChroma(L, lh, gamut) * GRADING_CHROMA_RATIO * lightBlend;
+    a += lC * Math.cos(lRad);
+    b += lC * Math.sin(lRad);
+  }
+  if (darkBlend > 0) {
+    const dh = grading.dark.hue;
+    const dRad = dh * toRad;
+    const dC = maxChroma(L, dh, gamut) * GRADING_CHROMA_RATIO * darkBlend;
+    a += dC * Math.cos(dRad);
+    b += dC * Math.sin(dRad);
+  }
+  let newC = Math.sqrt(a * a + b * b);
+  let newH = (Math.atan2(b, a) / toRad + 360) % 360;
+  newC = Math.min(newC, maxChroma(L, newH, gamut));
+  return { C: newC, h: newH };
+}
+function generateScale(options = {}) {
   const {
-    hue,
-    steps,
+    contrast,
+    hue = DEFAULT_HUE,
     chroma,
-    gamut = "srgb",
-    lightest = 1,
-    darkest = 0,
+    isP3 = false,
     grading,
-    gradient
+    shift
   } = options;
-  const chromaRatio = chroma?.value ?? 1;
-  const chromaPeak = chroma?.offset ?? 0.5;
+  const gamut = isP3 ? "display-p3" : "srgb";
+  const steps = DEFAULT_SCALE_STEPS;
+  const chromaRatio = chroma?.amount ?? 0;
+  const chromaPeak = chroma?.balance ?? 0.5;
   const hueGrade = grading;
-  const localHueGrade = gradient ? buildOneSidedGrade(gradient.hue, gradient.value, gradient.direction) : void 0;
-  if (steps < 2) return [];
+  const localHueGrade = shift ? buildOneSidedGrade(shift.hue, shift.amount, shift.light) : void 0;
   const ratio = Math.max(0, Math.min(1, chromaRatio));
   const peak = Math.max(0, Math.min(1, chromaPeak));
-  const lightestL = Math.max(0, Math.min(1, lightest));
-  const darkestL = Math.max(0, Math.min(1, darkest));
+  const lightestL = resolveLightest(contrast?.light ?? 1);
+  const darkestL = resolveDarkest(contrast?.dark ?? 1);
   const hueAt = (t) => resolveGradedHue(hue, t, hueGrade, localHueGrade);
   if (peak === 0.5 || ratio === 0 || ratio >= 1) {
     const scale2 = [];
     for (let i = 0; i < steps; i++) {
       const t = i / (steps - 1);
       const L = lightestL - t * (lightestL - darkestL);
-      const h = hueAt(t);
-      const C = maxChroma(L, h, gamut) * ratio;
+      let h = hueAt(t);
+      let C = Math.min(maxChroma(L, hue, gamut) * ratio, maxChroma(L, h, gamut));
+      if (hueGrade) {
+        const overlay = applyGradingOverlay(C, h, L, t, hueGrade, gamut);
+        C = overlay.C;
+        h = overlay.h;
+      }
       scale2.push({ L, C, h });
     }
     return scale2;
@@ -434,7 +504,7 @@ function generateScale(options) {
   for (let i = 0; i <= N; i++) {
     const t = i / N;
     const L = lightestL - t * (lightestL - darkestL);
-    const C = maxChroma(L, hueAt(t), gamut);
+    const C = maxChroma(L, hue, gamut);
     boundarySamples.push({ t, C });
     if (C > peakBoundaryC) {
       peakBoundaryC = C;
@@ -463,7 +533,7 @@ function generateScale(options) {
   for (let i = 0; i < steps; i++) {
     const t = i / (steps - 1);
     const L = lightestL - t * (lightestL - darkestL);
-    const h = hueAt(t);
+    let h = hueAt(t);
     let tWarped;
     if (t <= targetT) {
       tWarped = t * (peakT / targetT);
@@ -471,16 +541,22 @@ function generateScale(options) {
       tWarped = peakT + (t - targetT) * ((1 - peakT) / (1 - targetT));
     }
     const Lwarped = lightestL - tWarped * (lightestL - darkestL);
-    const warpedC = maxChroma(Lwarped, hueAt(tWarped), gamut) * ratio;
+    const warpedC = maxChroma(Lwarped, hue, gamut) * ratio;
     const boundaryC = maxChroma(L, h, gamut);
-    const C = Math.min(warpedC, boundaryC);
+    let C = Math.min(warpedC, boundaryC);
+    if (hueGrade) {
+      const overlay = applyGradingOverlay(C, h, L, t, hueGrade, gamut);
+      C = overlay.C;
+      h = overlay.h;
+    }
     scale.push({ L, C, h });
   }
   return scale;
 }
 
 // src/scale/resolve-color.ts
-function resolveColor(input, gamut = "srgb") {
+function resolveColor(input, isP3 = false) {
+  const gamut = isP3 ? "display-p3" : "srgb";
   const isHex = typeof input === "string";
   const original = isHex ? hexToOklch(input) : input;
   let inGamut;
@@ -503,70 +579,48 @@ function resolveColor(input, gamut = "srgb") {
     chromaRatio: Math.min(1, chromaRatio)
   };
 }
-function findNearest(target, scale) {
-  if (scale.length === 0) {
-    throw new Error("findNearest: scale must not be empty");
-  }
-  let bestIndex = 0;
-  let bestDistance = Infinity;
-  for (let i = 0; i < scale.length; i++) {
-    const d = deltaEOK(target, scale[i]);
-    if (d < bestDistance) {
-      bestDistance = d;
-      bestIndex = i;
-    }
-  }
-  return {
-    index: bestIndex,
-    color: scale[bestIndex],
-    distance: bestDistance
-  };
-}
-
-// src/scale/dynamic-range.ts
-function resolveLightest(slider) {
-  const s = Math.max(0, Math.min(1, slider));
-  return MIN_LIGHTEST_L + s * (1 - MIN_LIGHTEST_L);
-}
-function resolveDarkest(slider) {
-  const s = Math.max(0, Math.min(1, slider));
-  return MAX_DARKEST_L * (1 - s);
-}
-function lightnessToScaleT(L, lightestL, darkestL) {
-  const range = lightestL - darkestL;
-  if (range <= 0) return 0.5;
-  return Math.max(0, Math.min(1, (lightestL - L) / range));
-}
 
 // src/scale/key-color.ts
 function keyColor(color, options) {
-  const { gamut = "srgb", lightest = 1, darkest = 0 } = options ?? {};
-  const resolved = resolveColor(color, gamut);
-  const offset = lightnessToScaleT(resolved.oklch.L, lightest, darkest);
+  const { isP3 = false, contrast, steps = DEFAULT_SCALE_STEPS } = options ?? {};
+  const resolved = resolveColor(color, isP3);
+  const lightestL = resolveLightest(contrast?.light ?? 1);
+  const darkestL = resolveDarkest(contrast?.dark ?? 1);
+  const balance = lightnessToScaleT(resolved.oklch.L, lightestL, darkestL);
+  const stepIndex = Math.round(balance * Math.max(0, steps - 1));
   return {
     hue: resolved.hue,
-    chroma: { value: resolved.chromaRatio, offset },
-    resolved
+    chroma: { amount: resolved.chromaRatio, balance },
+    stepIndex,
+    hex: resolved.hex,
+    oklch: resolved.oklch,
+    wasRemapped: resolved.wasRemapped,
+    original: resolved.original
   };
 }
 
-exports.GRADE_REACH = GRADE_REACH;
-exports.LOCAL_GRADE_REACH = LOCAL_GRADE_REACH;
+exports.APCA_LC_MAX = APCA_LC_MAX;
+exports.DEFAULT_HUE = DEFAULT_HUE;
+exports.DEFAULT_SCALE_STEPS = DEFAULT_SCALE_STEPS;
+exports.GRADING_CHROMA_RATIO = GRADING_CHROMA_RATIO;
+exports.GRADING_REACH = GRADING_REACH;
 exports.MAX_DARKEST_L = MAX_DARKEST_L;
-exports.MAX_GRADE_INTENSITY = MAX_GRADE_INTENSITY;
-exports.MAX_LOCAL_GRADE_INTENSITY = MAX_LOCAL_GRADE_INTENSITY;
+exports.MAX_GRADING_AMOUNT = MAX_GRADING_AMOUNT;
+exports.MAX_SHIFT_AMOUNT = MAX_SHIFT_AMOUNT;
 exports.MIN_LIGHTEST_L = MIN_LIGHTEST_L;
 exports.PERCEPTUAL_JND = PERCEPTUAL_JND;
+exports.SHIFT_REACH = SHIFT_REACH;
 exports.apcaContrast = apcaContrast;
+exports.apcaToNormalized = apcaToNormalized;
 exports.buildOneSidedGrade = buildOneSidedGrade;
 exports.clampSrgb = clampSrgb;
 exports.contrastTextHex = contrastTextHex;
 exports.deltaEOK = deltaEOK;
 exports.deltaEOKLab = deltaEOKLab;
-exports.findNearest = findNearest;
 exports.gamutMap = gamutMap;
 exports.generateScale = generateScale;
 exports.gradeHue = gradeHue;
+exports.gradingInfluence = gradingInfluence;
 exports.hexToOklch = hexToOklch;
 exports.hexToSrgb = hexToSrgb;
 exports.isInGamut = isInGamut;
@@ -578,6 +632,7 @@ exports.linearSrgbToOklab = linearSrgbToOklab;
 exports.linearSrgbToSrgb = linearSrgbToSrgb;
 exports.maxChroma = maxChroma;
 exports.mix = mix;
+exports.normalizedToApca = normalizedToApca;
 exports.oklabToLinearP3 = oklabToLinearP3;
 exports.oklabToLinearSrgb = oklabToLinearSrgb;
 exports.oklabToOklch = oklabToOklch;
@@ -587,10 +642,7 @@ exports.oklchToOklab = oklchToOklab;
 exports.oklchToP3 = oklchToP3;
 exports.oklchToSrgb = oklchToSrgb;
 exports.p3ToOklch = p3ToOklch;
-exports.resolveColor = resolveColor;
-exports.resolveDarkest = resolveDarkest;
 exports.resolveGradedHue = resolveGradedHue;
-exports.resolveLightest = resolveLightest;
 exports.srgbChannelToLinear = srgbChannelToLinear;
 exports.srgbToHex = srgbToHex;
 exports.srgbToLinearSrgb = srgbToLinearSrgb;