@tenphi/glaze 0.13.0 → 0.14.0

package/dist/index.cjs

@@ -98,7 +98,12 @@ const K2 = .03;
 const K3 = (1 + K1) / (1 + K2);
 const EPSILON = 1e-10;
 const constrainAngle = (angle) => (angle % 360 + 360) % 360;
+/**
+* OKHSL toe function: maps OKLab lightness L to perceptual lightness l.
+* Exported for the OKHST tone transfers in `okhst.ts`.
+*/
 const toe = (x) => .5 * (K3 * x - K1 + Math.sqrt((K3 * x - K1) * (K3 * x - K1) + 4 * K2 * K3 * x));
+/** Inverse OKHSL toe: maps perceptual lightness l back to OKLab lightness L. */
 const toeInv = (x) => (x ** 2 + K1 * x) / (K3 * (x + K2));
 const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 const dotXY = (a, b) => a[0] * b[0] + a[1] * b[1];
@@ -343,6 +348,22 @@ function gamutClampedLuminance(linearRgb) {
 	const b = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2]))));
 	return .2126 * r + .7152 * g + .0722 * b;
 }
+/**
+* Compute APCA screen luminance (`Ys`) from linear sRGB.
+*
+* APCA does not use the WCAG piecewise sRGB EOTF; it defines its own
+* luminance as `0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
+* gamma-encoded (display) channels with a simple 2.4 exponent. The APCA
+* soft-clamp threshold in `apcaContrast` is calibrated against this basis,
+* so the solver must feed it `Ys`, not WCAG relative luminance. Channels
+* are gamut-clamped to [0, 1] first, matching `gamutClampedLuminance`.
+*/
+function apcaLuminanceFromLinearRgb(linearRgb) {
+	const r = Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0])));
+	const g = Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1])));
+	const b = Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2])));
+	return .2126 * Math.pow(r, 2.4) + .7152 * Math.pow(g, 2.4) + .0722 * Math.pow(b, 2.4);
+}
 const linearSrgbToOklab = (rgb) => {
 	return transform(cbrt3(transform(rgb, linear_sRGB_to_LMS_M)), LMS_to_OKLab_M);
 };
@@ -568,10 +589,18 @@ function formatOklch(h, s, l) {
 */
 function defaultConfig() {
 	return {
-		lightLightness: [10, 100],
-		darkLightness: [15, 95],
+		lightTone: {
+			lo: 10,
+			hi: 100,
+			eps: .05
+		},
+		darkTone: {
+			lo: 15,
+			hi: 95,
+			eps: .05
+		},
 		darkDesaturation: .1,
-		darkCurve: .5,
+		saturationTaper: .15,
 		states: {
 			dark: "@dark",
 			highContrast: "@high-contrast"
@@ -607,10 +636,10 @@ function snapshotConfig() {
 function configure(config) {
 	configVersion++;
 	globalConfig = {
-		lightLightness: config.lightLightness ?? globalConfig.lightLightness,
-		darkLightness: config.darkLightness ?? globalConfig.darkLightness,
+		lightTone: config.lightTone ?? globalConfig.lightTone,
+		darkTone: config.darkTone ?? globalConfig.darkTone,
 		darkDesaturation: config.darkDesaturation ?? globalConfig.darkDesaturation,
-		darkCurve: config.darkCurve ?? globalConfig.darkCurve,
+		saturationTaper: config.saturationTaper ?? globalConfig.saturationTaper,
 		states: {
 			dark: config.states?.dark ?? globalConfig.states.dark,
 			highContrast: config.states?.highContrast ?? globalConfig.states.highContrast
@@ -630,16 +659,16 @@ function resetConfig() {
 /**
 * Merge a per-instance config override over a base resolved config.
 * Only fields present in `override` are replaced; others fall through
-* from `base`. `false` for lightness windows passes through as-is
-* (treated as `[0, 100]` by `lightnessWindow()` in scheme-mapping).
+* from `base`. `false` for tone windows passes through as-is
+* (treated as the full range by `activeWindow()` in okhst.ts).
 */
 function mergeConfig(base, override) {
 	if (!override) return base;
 	return {
-		lightLightness: override.lightLightness !== void 0 ? override.lightLightness : base.lightLightness,
-		darkLightness: override.darkLightness !== void 0 ? override.darkLightness : base.darkLightness,
+		lightTone: override.lightTone !== void 0 ? override.lightTone : base.lightTone,
+		darkTone: override.darkTone !== void 0 ? override.darkTone : base.darkTone,
 		darkDesaturation: override.darkDesaturation ?? base.darkDesaturation,
-		darkCurve: override.darkCurve ?? base.darkCurve,
+		saturationTaper: override.saturationTaper ?? base.saturationTaper,
 		states: base.states,
 		modes: base.modes,
 		shadowTuning: override.shadowTuning ?? base.shadowTuning,
@@ -658,6 +687,10 @@ function pairHC(p) {
 function clamp(v, min, max) {
 	return Math.max(min, Math.min(max, v));
 }
+/** Whether a tone value is an extreme keyword (`'max'` / `'min'`). */
+function isExtremeTone(value) {
+	return value === "max" || value === "min";
+}
 /**
 * Parse a value that can be absolute (number) or relative (signed string).
 * Returns the numeric value and whether it's relative.
@@ -673,6 +706,31 @@ function parseRelativeOrAbsolute(value) {
 	};
 }
 /**
+* Parse a tone value into a normalized shape.
+* - `'max'` / `'min'` → `{ kind: 'extreme', value: 100 | 0 }` (an absolute
+*   author tone before scheme mapping — `'max'` is 100, `'min'` is 0).
+* - `'+N'` / `'-N'` → `{ kind: 'relative', value: ±N }`.
+* - number → `{ kind: 'absolute', value }`.
+*/
+function parseToneValue(value) {
+	if (value === "max") return {
+		kind: "extreme",
+		value: 100
+	};
+	if (value === "min") return {
+		kind: "extreme",
+		value: 0
+	};
+	if (typeof value === "number") return {
+		kind: "absolute",
+		value
+	};
+	return {
+		kind: "relative",
+		value: parseFloat(value)
+	};
+}
+/**
 * Compute the effective hue for a color, given the theme seed hue
 * and an optional per-color hue override.
 */
@@ -683,23 +741,232 @@ function resolveEffectiveHue(seedHue, defHue) {
 	return (parsed.value % 360 + 360) % 360;
 }
 /**
-* Check whether a lightness value represents an absolute root definition
-* (i.e. a number, not a relative string).
+* Check whether a tone value represents an absolute root definition
+* (i.e. a number, not a relative string). Extreme keywords (`'max'` /
+* `'min'`) also count — they need no base.
+*/
+function isAbsoluteTone(tone) {
+	if (tone === void 0) return false;
+	const normal = Array.isArray(tone) ? tone[0] : tone;
+	return typeof normal === "number" || isExtremeTone(normal);
+}
+
+//#endregion
+//#region src/okhst.ts
+/**
+* OKHST — the contrast-uniform tone space.
+*
+* OKHST is OKHSL with its lightness axis replaced by a contrast-uniform
+* "tone" axis. It shares `h` / `s` with OKHSL verbatim and swaps `l` for
+* `t`. This module owns:
+*
+* - the closed-form tone transfers (`toTone` / `fromTone`) at a fixed
+*   reference eps, plus the gray luminance helpers (`lToY` / `yToL`),
+* - the `{ h, s, t }` <-> `{ h, s, l }` color-space converters,
+* - the resolved-variant edge adapter (`variantToOkhsl`),
+* - the per-scheme tone mapping that replaced the Möbius dark curve
+*   (`mapToneForScheme`), the saturation reducers, and the solver's
+*   scheme tone range.
+*
+* See `docs/okhst.md` for the full specification and the calibrated
+* default constants.
+*/
+/**
+* Reference eps for the OKHST color space. WCAG 2 contrast is
+* `(Y_hi + 0.05) / (Y_lo + 0.05)`, so an eps of `0.05` makes equal tone
+* steps yield equal WCAG contrast. This is the canonical eps used by
+* `okhst()` input, `{ h, s, t }` input, stored `ResolvedColorVariant.t`,
+* relative `tone` offsets, and the contrast solver.
+*/
+const REF_EPS = .05;
+/**
+* Gray luminance from OKHSL lightness. For an achromatic color the OKLab
+* lightness is `toeInv(l)` and luminance is its cube.
+*/
+function lToY(l) {
+	const L = toeInv(l);
+	return L * L * L;
+}
+/** OKHSL lightness from gray luminance — exact inverse of {@link lToY}. */
+function yToL(y) {
+	return toe(Math.cbrt(Math.max(0, y)));
+}
+/**
+* Map a luminance `Y` (0–1) to tone (0–100) at the given eps.
+* `toneFromY(0) === 0` and `toneFromY(1) === 100` for any eps.
+*/
+function toneFromY(y, eps = REF_EPS) {
+	return (Math.log(y + eps) - Math.log(eps)) / (Math.log(1 + eps) - Math.log(eps)) * 100;
+}
+/** Map a tone (0–100) back to luminance (0–1). Inverse of {@link toneFromY}. */
+function yFromTone(t, eps = REF_EPS) {
+	const den = Math.log(1 + eps) - Math.log(eps);
+	return Math.exp(t / 100 * den + Math.log(eps)) - eps;
+}
+/** OKHSL lightness (0–1) -> tone (0–100). */
+function toTone(l, eps = REF_EPS) {
+	return toneFromY(lToY(l), eps);
+}
+/** Tone (0–100) -> OKHSL lightness (0–1). Inverse of {@link toTone}. */
+function fromTone(t, eps = REF_EPS) {
+	return yToL(yFromTone(t, eps));
+}
+/** Convert OKHST `{ h, s, t }` (t in 0–1) to OKHSL `{ h, s, l }`. */
+function okhstToOkhsl(c) {
+	return {
+		h: c.h,
+		s: c.s,
+		l: clamp(fromTone(c.t * 100), 0, 1)
+	};
+}
+/** Convert OKHSL `{ h, s, l }` to OKHST `{ h, s, t }` (t in 0–1). */
+function okhslToOkhst(c) {
+	return {
+		h: c.h,
+		s: c.s,
+		t: clamp(toTone(c.l) / 100, 0, 1)
+	};
+}
+/**
+* Edge adapter: a resolved variant stores canonical tone `t` (0–1). Convert
+* it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect.
+*/
+function variantToOkhsl(v) {
+	return {
+		h: v.h,
+		s: v.s,
+		l: clamp(fromTone(v.t * 100), 0, 1)
+	};
+}
+/**
+* Normalize any {@link ToneWindow} form to `{ lo, hi, eps }`.
+* - `false`: full range `[0, 100]` at the reference eps (boundaries removed,
+*   curve preserved).
+* - `[lo, hi]`: endpoints at the reference eps (the common form).
+* - `{ lo, hi, eps }`: passed through (advanced eps tuning).
+*/
+function normalizeToneWindow(win) {
+	if (win === false) return {
+		lo: 0,
+		hi: 100,
+		eps: REF_EPS
+	};
+	if (Array.isArray(win)) return {
+		lo: win[0],
+		hi: win[1],
+		eps: REF_EPS
+	};
+	return {
+		lo: win.lo,
+		hi: win.hi,
+		eps: win.eps
+	};
+}
+/**
+* Resolve the active tone window for a scheme as OKHSL-lightness endpoints.
+* - HC variants always return the full range `[0, 100]` with the mode eps.
+* - `false` (= "no clamping") is treated as `[0, 100]` with the reference eps.
+*/
+function activeWindow(isHighContrast, kind, config) {
+	const win = normalizeToneWindow(kind === "dark" ? config.darkTone : config.lightTone);
+	if (isHighContrast) return {
+		lo: 0,
+		hi: 100,
+		eps: win.eps
+	};
+	return win;
+}
+/**
+* Remap an authored tone (0–100) into a scheme window and return the final
+* OKHSL lightness (0–100). The window endpoints are OKHSL lightnesses; the
+* author tone is positioned within the window's tone interval (using the
+* window's render eps), then converted back to lightness.
+*/
+function remapToneToLightness(authorTone, win) {
+	const loT = toTone(win.lo / 100, win.eps);
+	const hiT = toTone(win.hi / 100, win.eps);
+	return clamp(fromTone(loT + authorTone / 100 * (hiT - loT), win.eps) * 100, 0, 100);
+}
+/**
+* Map an authored tone for a scheme and return the canonical stored tone
+* (0–100, reference eps).
+*
+* - `static`: identity — the same tone renders in every scheme.
+* - `auto` + dark: invert (`100 - tone`) then remap into the dark window.
+* - `auto`/`fixed` + light, or `fixed` + dark: remap, no inversion.
+*
+* The window remap uses the mode's render eps to land a final OKHSL
+* lightness; that lightness is then re-expressed as canonical tone so
+* relative offsets and contrast stay comparable across schemes.
+*/
+function mapToneForScheme(authorTone, mode, isDark, isHighContrast, config) {
+	if (mode === "static") return clamp(authorTone, 0, 100);
+	const win = activeWindow(isHighContrast, isDark ? "dark" : "light", config);
+	return clamp(toTone(remapToneToLightness(clamp(isDark && mode === "auto" ? 100 - authorTone : authorTone, 0, 100), win) / 100), 0, 100);
+}
+/** Dark-scheme desaturation reducer (unchanged from the legacy pipeline). */
+function mapSaturationDark(s, mode, config) {
+	if (mode === "static") return s;
+	return s * (1 - config.darkDesaturation);
+}
+/** Smoothstep `0..1`. */
+function smoothstep(x) {
+	const t = clamp(x, 0, 1);
+	return t * t * (3 - 2 * t);
+}
+/** Fraction of the tone range over which the taper ramps in, per end. */
+const TAPER_REGION = .15;
+/**
+* Gently taper saturation toward the tone extremes, where in-gamut chroma
+* collapses and high saturation reads as noise. `taper` is the *strength*
+* (0–1): the maximum fraction of saturation removed at the very edges. The
+* rolloff ramps in smoothly over the outer {@link TAPER_REGION} of tone on
+* each end, so mid-tones are untouched and high-tone surfaces keep most of
+* their color. `taper = 0` disables the effect.
+*
+* @param s Saturation (0–1).
+* @param toneFinal Stored canonical tone (0–1).
+* @param taper Strength (0–1); default config is a gentle 0.15.
 */
-function isAbsoluteLightness(lightness) {
-	if (lightness === void 0) return false;
-	return typeof (Array.isArray(lightness) ? lightness[0] : lightness) === "number";
+function saturationEnvelope(s, toneFinal, taper) {
+	if (taper <= 0) return s;
+	const t = clamp(toneFinal, 0, 1);
+	const strength = clamp(taper, 0, 1);
+	const edge = Math.min(t, 1 - t);
+	if (edge >= TAPER_REGION) return s;
+	return s * (1 - strength * (1 - smoothstep(edge / TAPER_REGION)));
+}
+/**
+* Tone search range (0–1) for the contrast solver in a given scheme.
+* `static` searches the full range; otherwise the scheme window's tone
+* endpoints (HC bypasses to full range).
+*/
+function schemeToneRange(isDark, mode, isHighContrast, config) {
+	if (mode === "static") return [0, 1];
+	const win = activeWindow(isHighContrast, isDark ? "dark" : "light", config);
+	return [clamp(toTone(win.lo / 100) / 100, 0, 1), clamp(toTone(win.hi / 100) / 100, 0, 1)];
 }
 
 //#endregion
 //#region src/contrast-solver.ts
 /**
-* OKHSL Contrast Solver
+* Contrast solver — operates in OKHST tone.
 *
-* Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
-* against a base color. Used by glaze when resolving dependent colors
-* with `contrast`.
+* Finds the tone closest to a preferred tone that satisfies a contrast
+* floor (WCAG 2 ratio or APCA Lc) against a base color. Because tone is
+* contrast-uniform, the WCAG branch gets a closed-form seed and the search
+* converges quickly.
+*
+* Public API: `findToneForContrast`, `findValueForMixContrast`,
+* `resolveMinContrast`, `resolveContrastForMode`, `apcaContrast`.
+*/
+/**
+* Luminance of a linear-sRGB color in the basis the metric expects: WCAG
+* relative luminance for `wcag`, APCA screen luminance (`Ys`) for `apca`.
 */
+function metricLuminance(metric, linearRgb) {
+	return metric === "apca" ? apcaLuminanceFromLinearRgb(linearRgb) : gamutClampedLuminance(linearRgb);
+}
 const CONTRAST_PRESETS = {
 	AA: 4.5,
 	AAA: 7,
@@ -710,15 +977,75 @@ function resolveMinContrast(value) {
 	if (typeof value === "number") return Math.max(1, value);
 	return CONTRAST_PRESETS[value];
 }
+function pickPair(p, isHighContrast) {
+	return Array.isArray(p) ? isHighContrast ? p[1] : p[0] : p;
+}
+/**
+* Resolve a `ContrastSpec` (already selected from any outer HC pair) for a
+* given mode into `{ metric, target }`. Handles the inner metric HC pair and
+* preset resolution.
+*/
+function resolveContrastForMode(spec, isHighContrast) {
+	if (typeof spec === "number" || typeof spec === "string") return {
+		metric: "wcag",
+		target: resolveMinContrast(spec)
+	};
+	if ("apca" in spec) return {
+		metric: "apca",
+		target: Math.abs(pickPair(spec.apca, isHighContrast))
+	};
+	return {
+		metric: "wcag",
+		target: resolveMinContrast(pickPair(spec.wcag, isHighContrast))
+	};
+}
+const APCA_EXPONENTS = {
+	mainTRC: 2.4,
+	normBG: .56,
+	normTXT: .57,
+	revTXT: .62,
+	revBG: .65
+};
+const APCA_BLACK_THRESH = .022;
+const APCA_BLACK_CLIP = 1.414;
+const APCA_DELTA_Y_MIN = 5e-4;
+const APCA_SCALE = 1.14;
+const APCA_LO_OFFSET = .027;
+function apcaSoftClamp(y) {
+	const yc = Math.max(0, y);
+	if (yc >= APCA_BLACK_THRESH) return yc;
+	return yc + Math.pow(APCA_BLACK_THRESH - yc, APCA_BLACK_CLIP);
+}
+/**
+* APCA lightness contrast (Lc), signed: positive for dark text on light bg,
+* negative for light text on dark bg. Inputs are screen luminances (0–1).
+*/
+function apcaContrast(yText, yBg) {
+	const txt = apcaSoftClamp(yText);
+	const bg = apcaSoftClamp(yBg);
+	if (Math.abs(bg - txt) < APCA_DELTA_Y_MIN) return 0;
+	let sapc;
+	if (bg > txt) {
+		sapc = (Math.pow(bg, APCA_EXPONENTS.normBG) - Math.pow(txt, APCA_EXPONENTS.normTXT)) * APCA_SCALE;
+		return sapc < .1 ? 0 : (sapc - APCA_LO_OFFSET) * 100;
+	}
+	sapc = (Math.pow(bg, APCA_EXPONENTS.revBG) - Math.pow(txt, APCA_EXPONENTS.revTXT)) * APCA_SCALE;
+	return sapc > -.1 ? 0 : (sapc + APCA_LO_OFFSET) * 100;
+}
 const CACHE_SIZE = 512;
 const luminanceCache = /* @__PURE__ */ new Map();
 const cacheOrder = [];
-function cachedLuminance(h, s, l) {
-	const lRounded = Math.round(l * 1e4) / 1e4;
-	const key = `${h}|${s}|${lRounded}`;
+/**
+* Luminance of an OKHST color `(h, s, t)` with t in 0–1 (reference eps), in
+* the metric's luminance basis. The metric is part of the cache key because
+* WCAG and APCA derive different luminances from the same color.
+*/
+function cachedLuminance(metric, h, s, t) {
+	const tRounded = Math.round(t * 1e4) / 1e4;
+	const key = `${metric}|${h}|${s}|${tRounded}`;
 	const cached = luminanceCache.get(key);
 	if (cached !== void 0) return cached;
-	const y = gamutClampedLuminance(okhslToLinearSrgb(h, s, lRounded));
+	const y = metricLuminance(metric, okhslToLinearSrgb(h, s, fromTone(tRounded * 100, REF_EPS)));
 	if (luminanceCache.size >= CACHE_SIZE) {
 		const evict = cacheOrder.shift();
 		luminanceCache.delete(evict);
@@ -728,263 +1055,192 @@ function cachedLuminance(h, s, l) {
 	return y;
 }
 /**
-* Binary search one branch [lo, hi] for the nearest passing lightness to `preferred`.
+* Score a candidate luminance against the base for a metric. Returns a value
+* that is `>= target` exactly when the floor is met (WCAG ratio, or APCA Lc
+* magnitude).
 */
-function searchBranch(h, s, lo, hi, yBase, target, epsilon, maxIter, preferred) {
-	const yLo = cachedLuminance(h, s, lo);
-	const yHi = cachedLuminance(h, s, hi);
-	const crLo = contrastRatioFromLuminance(yLo, yBase);
-	const crHi = contrastRatioFromLuminance(yHi, yBase);
-	if (crLo < target && crHi < target) {
-		if (crLo >= crHi) return {
-			lightness: lo,
-			contrast: crLo,
-			met: false
-		};
-		return {
-			lightness: hi,
-			contrast: crHi,
-			met: false
-		};
-	}
+function metricScore(metric, yCandidate, yBase) {
+	if (metric === "wcag") return contrastRatioFromLuminance(yCandidate, yBase);
+	return Math.abs(apcaContrast(yCandidate, yBase));
+}
+/**
+* Binary search one branch `[lo, hi]` for the position nearest to `anchor`
+* that meets `target`. The domain is whatever `lum` interprets (tone 0–1 or
+* mix parameter 0–1); the search is identical in both cases.
+*/
+function searchBranch(lum, lo, hi, yBase, metric, target, epsilon, maxIter, anchor) {
+	const scoreLo = metricScore(metric, lum(lo), yBase);
+	const scoreHi = metricScore(metric, lum(hi), yBase);
+	if (scoreLo < target && scoreHi < target) return scoreLo >= scoreHi ? {
+		pos: lo,
+		contrast: scoreLo,
+		met: false
+	} : {
+		pos: hi,
+		contrast: scoreHi,
+		met: false
+	};
 	let low = lo;
 	let high = hi;
 	for (let i = 0; i < maxIter; i++) {
 		if (high - low < epsilon) break;
 		const mid = (low + high) / 2;
-		if (contrastRatioFromLuminance(cachedLuminance(h, s, mid), yBase) >= target) if (mid < preferred) low = mid;
+		if (metricScore(metric, lum(mid), yBase) >= target) if (mid < anchor) low = mid;
 		else high = mid;
-		else if (mid < preferred) high = mid;
+		else if (mid < anchor) high = mid;
 		else low = mid;
 	}
-	const yLow = cachedLuminance(h, s, low);
-	const yHigh = cachedLuminance(h, s, high);
-	const crLow = contrastRatioFromLuminance(yLow, yBase);
-	const crHigh = contrastRatioFromLuminance(yHigh, yBase);
-	const lowPasses = crLow >= target;
-	const highPasses = crHigh >= target;
-	if (lowPasses && highPasses) {
-		if (Math.abs(low - preferred) <= Math.abs(high - preferred)) return {
-			lightness: low,
-			contrast: crLow,
-			met: true
-		};
-		return {
-			lightness: high,
-			contrast: crHigh,
-			met: true
-		};
-	}
+	const scoreLow = metricScore(metric, lum(low), yBase);
+	const scoreHigh = metricScore(metric, lum(high), yBase);
+	const lowPasses = scoreLow >= target;
+	const highPasses = scoreHigh >= target;
+	if (lowPasses && highPasses) return Math.abs(low - anchor) <= Math.abs(high - anchor) ? {
+		pos: low,
+		contrast: scoreLow,
+		met: true
+	} : {
+		pos: high,
+		contrast: scoreHigh,
+		met: true
+	};
 	if (lowPasses) return {
-		lightness: low,
-		contrast: crLow,
+		pos: low,
+		contrast: scoreLow,
 		met: true
 	};
 	if (highPasses) return {
-		lightness: high,
-		contrast: crHigh,
+		pos: high,
+		contrast: scoreHigh,
 		met: true
 	};
-	return coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter);
-}
-/**
-* Fallback coarse scan when binary search is unstable near gamut edges.
-*/
-function coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter) {
-	const STEPS = 64;
-	const step = (hi - lo) / STEPS;
-	let bestL = lo;
-	let bestCr = 0;
-	let bestMet = false;
-	for (let i = 0; i <= STEPS; i++) {
-		const l = lo + step * i;
-		const cr = contrastRatioFromLuminance(cachedLuminance(h, s, l), yBase);
-		if (cr >= target && !bestMet) {
-			bestL = l;
-			bestCr = cr;
-			bestMet = true;
-		} else if (cr >= target && bestMet) {
-			bestL = l;
-			bestCr = cr;
-		} else if (!bestMet && cr > bestCr) {
-			bestL = l;
-			bestCr = cr;
-		}
-	}
-	if (bestMet && bestL > lo + step) {
-		let rLo = bestL - step;
-		let rHi = bestL;
-		for (let i = 0; i < maxIter; i++) {
-			if (rHi - rLo < epsilon) break;
-			const mid = (rLo + rHi) / 2;
-			const cr = contrastRatioFromLuminance(cachedLuminance(h, s, mid), yBase);
-			if (cr >= target) {
-				rHi = mid;
-				bestL = mid;
-				bestCr = cr;
-			} else rLo = mid;
-		}
-	}
-	return {
-		lightness: bestL,
-		contrast: bestCr,
-		met: bestMet
+	return scoreLow >= scoreHigh ? {
+		pos: low,
+		contrast: scoreLow,
+		met: false
+	} : {
+		pos: high,
+		contrast: scoreHigh,
+		met: false
 	};
 }
 /**
-* Find the OKHSL lightness that satisfies a WCAG 2 contrast target
-* against a base color, staying as close to `preferredLightness` as possible.
+* Closed-form WCAG tone seed: the gray tone whose luminance produces exactly
+* the target ratio against the base, on the requested side. Used to bias the
+* preferred tone before the search so chromatic refinement starts close.
 */
-function findLightnessForContrast(options) {
-	const { hue, saturation, preferredLightness, baseLinearRgb, contrast: contrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
-	const target = resolveMinContrast(contrastInput);
-	const searchTarget = target * 1.01;
-	const yBase = gamutClampedLuminance(baseLinearRgb);
-	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
-	if (crPref >= searchTarget) return {
-		lightness: preferredLightness,
-		contrast: crPref,
-		met: true,
-		branch: "preferred"
-	};
-	const [minL, maxL] = lightnessRange;
-	const canDarker = preferredLightness > minL;
-	const canLighter = preferredLightness < maxL;
-	let initialIsDarker;
-	if (options.initialDirection !== void 0) initialIsDarker = options.initialDirection === "darker";
-	else if (canDarker && !canLighter) initialIsDarker = true;
-	else if (!canDarker && canLighter) initialIsDarker = false;
-	else if (!canDarker && !canLighter) return {
-		lightness: preferredLightness,
-		contrast: crPref,
-		met: false,
-		branch: "preferred"
-	};
-	else {
-		const yMinExt = cachedLuminance(hue, saturation, minL);
-		const yMaxExt = cachedLuminance(hue, saturation, maxL);
-		initialIsDarker = contrastRatioFromLuminance(yMinExt, yBase) >= contrastRatioFromLuminance(yMaxExt, yBase);
-	}
-	const searchInitial = () => initialIsDarker ? searchBranch(hue, saturation, minL, preferredLightness, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : searchBranch(hue, saturation, preferredLightness, maxL, yBase, searchTarget, epsilon, maxIterations, preferredLightness);
-	const searchOpposite = () => initialIsDarker ? searchBranch(hue, saturation, preferredLightness, maxL, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : searchBranch(hue, saturation, minL, preferredLightness, yBase, searchTarget, epsilon, maxIterations, preferredLightness);
-	const initialBranchName = initialIsDarker ? "darker" : "lighter";
-	const oppositeBranchName = initialIsDarker ? "lighter" : "darker";
-	const initialResult = searchInitial();
+function wcagToneSeed(yBase, target, darker) {
+	const yTarget = darker ? (yBase + .05) / target - .05 : target * (yBase + .05) - .05;
+	const yClamped = Math.max(0, Math.min(1, yTarget));
+	return Math.max(0, Math.min(1, toneFromY(yClamped, REF_EPS) / 100));
+}
+function solveNearestContrast(opts) {
+	const { lum, yBase, metric, target, searchTarget, lo, hi, searchAnchor, distanceAnchor, epsilon, maxIterations, flip, initialIsLower } = opts;
+	const runBranch = (lower) => lower ? searchBranch(lum, lo, searchAnchor, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor) : searchBranch(lum, searchAnchor, hi, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor);
+	const initialResult = runBranch(initialIsLower);
 	initialResult.met = initialResult.contrast >= target;
-	if (initialResult.met && !options.flip) return {
+	if (initialResult.met && !flip) return {
 		...initialResult,
-		branch: initialBranchName
+		lower: initialIsLower
 	};
-	if (options.flip) {
-		const oppositeResult = (initialIsDarker ? canLighter : canDarker) ? searchOpposite() : null;
+	if (flip) {
+		const oppositeResult = (initialIsLower ? distanceAnchor < hi : distanceAnchor > lo) ? runBranch(!initialIsLower) : null;
 		if (oppositeResult) oppositeResult.met = oppositeResult.contrast >= target;
-		if (initialResult.met && oppositeResult?.met) {
-			if (Math.abs(initialResult.lightness - preferredLightness) <= Math.abs(oppositeResult.lightness - preferredLightness)) return {
-				...initialResult,
-				branch: initialBranchName
-			};
-			return {
-				...oppositeResult,
-				branch: oppositeBranchName,
-				flipped: true
-			};
-		}
+		if (initialResult.met && oppositeResult?.met) return Math.abs(initialResult.pos - distanceAnchor) <= Math.abs(oppositeResult.pos - distanceAnchor) ? {
+			...initialResult,
+			lower: initialIsLower
+		} : {
+			...oppositeResult,
+			lower: !initialIsLower,
+			flipped: true
+		};
 		if (initialResult.met) return {
 			...initialResult,
-			branch: initialBranchName
+			lower: initialIsLower
 		};
 		if (oppositeResult?.met) return {
 			...oppositeResult,
-			branch: oppositeBranchName,
+			lower: !initialIsLower,
 			flipped: true
 		};
 	}
-	const extreme = initialIsDarker ? minL : maxL;
+	const extreme = initialIsLower ? lo : hi;
 	return {
-		lightness: extreme,
-		contrast: contrastRatioFromLuminance(cachedLuminance(hue, saturation, extreme), yBase),
+		pos: extreme,
+		contrast: metricScore(metric, lum(extreme), yBase),
 		met: false,
-		branch: initialBranchName
+		lower: initialIsLower
 	};
 }
 /**
-* Binary-search one branch [lo, hi] for the nearest passing mix value
-* to `preferred`.
-*/
-function searchMixBranch(lo, hi, yBase, target, epsilon, maxIter, preferred, luminanceAt) {
-	const crLo = contrastRatioFromLuminance(luminanceAt(lo), yBase);
-	const crHi = contrastRatioFromLuminance(luminanceAt(hi), yBase);
-	if (crLo < target && crHi < target) {
-		if (crLo >= crHi) return {
-			lightness: lo,
-			contrast: crLo,
-			met: false
-		};
-		return {
-			lightness: hi,
-			contrast: crHi,
-			met: false
-		};
-	}
-	let low = lo;
-	let high = hi;
-	for (let i = 0; i < maxIter; i++) {
-		if (high - low < epsilon) break;
-		const mid = (low + high) / 2;
-		if (contrastRatioFromLuminance(luminanceAt(mid), yBase) >= target) if (mid < preferred) low = mid;
-		else high = mid;
-		else if (mid < preferred) high = mid;
-		else low = mid;
-	}
-	const crLow = contrastRatioFromLuminance(luminanceAt(low), yBase);
-	const crHigh = contrastRatioFromLuminance(luminanceAt(high), yBase);
-	const lowPasses = crLow >= target;
-	const highPasses = crHigh >= target;
-	if (lowPasses && highPasses) {
-		if (Math.abs(low - preferred) <= Math.abs(high - preferred)) return {
-			lightness: low,
-			contrast: crLow,
-			met: true
-		};
-		return {
-			lightness: high,
-			contrast: crHigh,
-			met: true
-		};
-	}
-	if (lowPasses) return {
-		lightness: low,
-		contrast: crLow,
-		met: true
+* Find the tone that satisfies a contrast floor against a base color,
+* staying as close to `preferredTone` as possible.
+*/
+function findToneForContrast(options) {
+	const { hue, saturation, preferredTone, baseLinearRgb, contrast, toneRange = [0, 1], epsilon = 1e-4, maxIterations = 18 } = options;
+	const { metric, target } = contrast;
+	const searchTarget = metric === "wcag" ? target * 1.01 : target + .5;
+	const yBase = metricLuminance(metric, baseLinearRgb);
+	const taper = options.saturationTaper ?? 0;
+	const lum = taper > 0 ? (t) => {
+		return metricLuminance(metric, okhslToLinearSrgb(hue, saturationEnvelope(saturation, t, taper), fromTone(t * 100, REF_EPS)));
+	} : (t) => cachedLuminance(metric, hue, saturation, t);
+	const scorePref = metricScore(metric, lum(preferredTone), yBase);
+	if (scorePref >= searchTarget) return {
+		tone: preferredTone,
+		contrast: scorePref,
+		met: true,
+		branch: "preferred"
 	};
-	if (highPasses) return {
-		lightness: high,
-		contrast: crHigh,
-		met: true
+	const [minT, maxT] = toneRange;
+	const canDarker = preferredTone > minT;
+	const canLighter = preferredTone < maxT;
+	let initialIsDarker;
+	if (options.initialDirection !== void 0) initialIsDarker = options.initialDirection === "darker";
+	else if (canDarker && !canLighter) initialIsDarker = true;
+	else if (!canDarker && canLighter) initialIsDarker = false;
+	else if (!canDarker && !canLighter) return {
+		tone: preferredTone,
+		contrast: scorePref,
+		met: false,
+		branch: "preferred"
 	};
-	return crLow >= crHigh ? {
-		lightness: low,
-		contrast: crLow,
-		met: false
-	} : {
-		lightness: high,
-		contrast: crHigh,
-		met: false
+	else initialIsDarker = metricScore(metric, lum(minT), yBase) >= metricScore(metric, lum(maxT), yBase);
+	const solved = solveNearestContrast({
+		lum,
+		yBase,
+		metric,
+		target,
+		searchTarget,
+		lo: minT,
+		hi: maxT,
+		searchAnchor: metric === "wcag" ? clamp(initialIsDarker ? Math.min(preferredTone, wcagToneSeed(yBase, target, true)) : Math.max(preferredTone, wcagToneSeed(yBase, target, false)), minT, maxT) : preferredTone,
+		distanceAnchor: preferredTone,
+		epsilon,
+		maxIterations,
+		flip: options.flip ?? false,
+		initialIsLower: initialIsDarker
+	});
+	return {
+		tone: solved.pos,
+		contrast: solved.contrast,
+		met: solved.met,
+		branch: solved.lower ? "darker" : "lighter",
+		...solved.flipped ? { flipped: true } : {}
 	};
 }
 /**
-* Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
-* target against a base color, staying as close to `preferredValue` as possible.
+* Find the mix parameter (ratio or opacity) that satisfies a contrast floor
+* against a base color, staying as close to `preferredValue` as possible.
 */
 function findValueForMixContrast(options) {
-	const { preferredValue, baseLinearRgb, contrast: contrastInput, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
-	const target = resolveMinContrast(contrastInput);
-	const searchTarget = target * 1.01;
-	const yBase = gamutClampedLuminance(baseLinearRgb);
-	const crPref = contrastRatioFromLuminance(luminanceAtValue(preferredValue), yBase);
-	if (crPref >= searchTarget) return {
+	const { preferredValue, baseLinearRgb, contrast, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
+	const { metric, target } = contrast;
+	const searchTarget = metric === "wcag" ? target * 1.01 : target + .5;
+	const yBase = metricLuminance(metric, baseLinearRgb);
+	const scorePref = metricScore(metric, luminanceAtValue(preferredValue), yBase);
+	if (scorePref >= searchTarget) return {
 		value: preferredValue,
-		contrast: crPref,
+		contrast: scorePref,
 		met: true
 	};
 	const canLower = preferredValue > 0;
@@ -994,52 +1250,30 @@ function findValueForMixContrast(options) {
 	else if (!canLower && canUpper) initialIsLower = false;
 	else if (!canLower && !canUpper) return {
 		value: preferredValue,
-		contrast: crPref,
+		contrast: scorePref,
 		met: false
 	};
-	else initialIsLower = contrastRatioFromLuminance(luminanceAtValue(0), yBase) >= contrastRatioFromLuminance(luminanceAtValue(1), yBase);
-	const searchInitial = () => initialIsLower ? searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue);
-	const searchOpposite = () => initialIsLower ? searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue);
-	const initialResult = searchInitial();
-	initialResult.met = initialResult.contrast >= target;
-	if (initialResult.met && !options.flip) return {
-		value: initialResult.lightness,
-		contrast: initialResult.contrast,
-		met: true
-	};
-	if (options.flip) {
-		const oppositeResult = (initialIsLower ? canUpper : canLower) ? searchOpposite() : null;
-		if (oppositeResult) oppositeResult.met = oppositeResult.contrast >= target;
-		if (initialResult.met && oppositeResult?.met) {
-			if (Math.abs(initialResult.lightness - preferredValue) <= Math.abs(oppositeResult.lightness - preferredValue)) return {
-				value: initialResult.lightness,
-				contrast: initialResult.contrast,
-				met: true
-			};
-			return {
-				value: oppositeResult.lightness,
-				contrast: oppositeResult.contrast,
-				met: true,
-				flipped: true
-			};
-		}
-		if (initialResult.met) return {
-			value: initialResult.lightness,
-			contrast: initialResult.contrast,
-			met: true
-		};
-		if (oppositeResult?.met) return {
-			value: oppositeResult.lightness,
-			contrast: oppositeResult.contrast,
-			met: true,
-			flipped: true
-		};
-	}
-	const extreme = initialIsLower ? 0 : 1;
+	else initialIsLower = metricScore(metric, luminanceAtValue(0), yBase) >= metricScore(metric, luminanceAtValue(1), yBase);
+	const solved = solveNearestContrast({
+		lum: luminanceAtValue,
+		yBase,
+		metric,
+		target,
+		searchTarget,
+		lo: 0,
+		hi: 1,
+		searchAnchor: preferredValue,
+		distanceAnchor: preferredValue,
+		epsilon,
+		maxIterations,
+		flip: options.flip ?? false,
+		initialIsLower
+	});
 	return {
-		value: extreme,
-		contrast: contrastRatioFromLuminance(luminanceAtValue(extreme), yBase),
-		met: false
+		value: solved.pos,
+		contrast: solved.contrast,
+		met: solved.met,
+		...solved.flipped ? { flipped: true } : {}
 	};
 }
 
@@ -1115,73 +1349,13 @@ function computeShadow(bg, fg, intensity, tuning) {
 	};
 }
 
-//#endregion
-//#region src/scheme-mapping.ts
-/**
-* Light / dark scheme lightness mappings.
-*
-* Owns the active lightness window selection (from a resolved effective
-* config passed in), the Möbius curve used by the `'auto'` dark
-* adaptation, and the saturation-desaturation reducer for dark mode.
-*
-* All functions take a `GlazeConfigResolved` so the full config
-* (including per-instance overrides) is available without re-reading
-* the global singleton inside the resolver.
-*/
-/**
-* Resolve the active lightness window for a scheme.
-* - HC variants always return `[0, 100]` (no clamping in high-contrast).
-* - `false` (= "no clamping") is treated as `[0, 100]`.
-* - Otherwise uses the window from the resolved effective config.
-*/
-function lightnessWindow(isHighContrast, kind, config) {
-	if (isHighContrast) return [0, 100];
-	const win = kind === "dark" ? config.darkLightness : config.lightLightness;
-	if (win === false) return [0, 100];
-	return win;
-}
-function mapLightnessLight(l, mode, isHighContrast, config) {
-	if (mode === "static") return l;
-	const [lo, hi] = lightnessWindow(isHighContrast, "light", config);
-	return l * (hi - lo) / 100 + lo;
-}
-function mobiusCurve(t, beta) {
-	if (beta >= 1) return t;
-	return t / (t + beta * (1 - t));
-}
-function mapLightnessDark(l, mode, isHighContrast, config) {
-	if (mode === "static") return l;
-	const beta = isHighContrast ? pairHC(config.darkCurve) : pairNormal(config.darkCurve);
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", config);
-	if (mode === "fixed") return l * (darkHi - darkLo) / 100 + darkLo;
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", config);
-	const t = (lightHi - (l * (lightHi - lightLo) / 100 + lightLo)) / (lightHi - lightLo);
-	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
-}
-function lightMappedToDark(lightL, isHighContrast, config) {
-	const beta = isHighContrast ? pairHC(config.darkCurve) : pairNormal(config.darkCurve);
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", config);
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", config);
-	const t = (lightHi - clamp(lightL, lightLo, lightHi)) / (lightHi - lightLo);
-	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
-}
-function mapSaturationDark(s, mode, config) {
-	if (mode === "static") return s;
-	return s * (1 - config.darkDesaturation);
-}
-function schemeLightnessRange(isDark, mode, isHighContrast, config) {
-	if (mode === "static") return [0, 1];
-	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light", config);
-	return [lo / 100, hi / 100];
-}
-
 //#endregion
 //#region src/validation.ts
 /**
 * Color graph validation and topological sort.
 *
 * `validateColorDefs` rejects bad references (missing / shadow-referencing /
-* base/contrast/lightness mismatches) and detects cycles before the
+* base/contrast/tone mismatches) and detects cycles before the
 * resolver runs. `topoSort` orders defs so each color is processed after
 * its base / bg / fg / target dependencies.
 */
@@ -1207,11 +1381,11 @@ function validateColorDefs(defs, externalBases) {
 		}
 		const regDef = def;
 		if (regDef.contrast !== void 0 && !regDef.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
-		if (regDef.lightness !== void 0 && !isAbsoluteLightness(regDef.lightness) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
+		if (regDef.tone !== void 0 && !isAbsoluteTone(regDef.tone) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "tone" without "base".`);
 		if (regDef.base && !allNames.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
 		if (regDef.base && localNames.has(regDef.base) && isShadowDef(defs[regDef.base])) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a shadow color.`);
-		if (!isAbsoluteLightness(regDef.lightness) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
-		if (regDef.contrast !== void 0 && regDef.opacity !== void 0) console.warn(`glaze: color "${name}" has both "contrast" and "opacity". Opacity makes perceived lightness unpredictable.`);
+		if (!isAbsoluteTone(regDef.tone) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "tone" (root) or "base" (dependent).`);
+		if (regDef.contrast !== void 0 && regDef.opacity !== void 0) console.warn(`glaze: color "${name}" has both "contrast" and "opacity". Opacity makes perceived tone unpredictable.`);
 	}
 	const visited = /* @__PURE__ */ new Set();
 	const inStack = /* @__PURE__ */ new Set();
@@ -1274,30 +1448,46 @@ const CONTRAST_WARN_CACHE_LIMIT = 256;
 const contrastWarnCache = /* @__PURE__ */ new Set();
 /**
 * Slack factor below the requested target before we emit a warning.
-* The contrast solver already overshoots by `OVERSHOOT` (currently 1%)
-* to absorb rounding noise (`see findLightnessForContrast` in
-* `contrast-solver.ts`), so an `actual` ratio within ~2x that overshoot
-* is effectively a pass and not worth nagging the user about.
+* The contrast solver overshoots to absorb rounding noise, so an actual
+* value within ~2x that overshoot is effectively a pass.
 */
-const CONTRAST_WARN_SLACK = .98;
+const CONTRAST_WARN_SLACK_WCAG = .98;
+/** APCA Lc is on a 0–106 scale; allow a small absolute slack. */
+const CONTRAST_WARN_SLACK_APCA = 1.5;
 function schemeLabel(isDark, isHighContrast) {
 	if (isDark && isHighContrast) return "darkContrast";
 	if (isDark) return "dark";
 	if (isHighContrast) return "lightContrast";
 	return "light";
 }
-function formatContrastTarget(input, ratio) {
-	return typeof input === "string" ? `"${input}" (${ratio.toFixed(2)})` : ratio.toFixed(2);
+function metricLabel(c) {
+	return c.metric === "apca" ? `APCA Lc ${c.target.toFixed(1)}` : `WCAG ${c.target.toFixed(2)}`;
 }
-function warnContrastUnmet(name, isDark, isHighContrast, target, actual) {
-	const targetRatio = resolveMinContrast(target);
-	if (actual >= targetRatio * CONTRAST_WARN_SLACK) return;
-	const scheme = schemeLabel(isDark, isHighContrast);
-	const key = `${name}|${scheme}|${targetRatio.toFixed(3)}|${actual.toFixed(2)}`;
-	if (contrastWarnCache.has(key)) return;
+function dedupe(key) {
+	if (contrastWarnCache.has(key)) return true;
 	if (contrastWarnCache.size >= CONTRAST_WARN_CACHE_LIMIT) contrastWarnCache.clear();
 	contrastWarnCache.add(key);
-	console.warn(`glaze: color "${name}" cannot meet contrast ${formatContrastTarget(target, targetRatio)} in ${scheme} scheme (got ${actual.toFixed(2)}). Try widening the lightness window, lowering the contrast target, or picking a base color further from this color's lightness.`);
+	return false;
+}
+/** Warn when the solver could not reach the requested contrast floor. */
+function warnContrastUnmet(name, isDark, isHighContrast, contrast, actual) {
+	if (actual >= (contrast.metric === "apca" ? contrast.target - CONTRAST_WARN_SLACK_APCA : contrast.target * CONTRAST_WARN_SLACK_WCAG)) return;
+	const scheme = schemeLabel(isDark, isHighContrast);
+	if (dedupe(`unmet|${name}|${scheme}|${contrast.metric}|${contrast.target.toFixed(2)}|${actual.toFixed(2)}`)) return;
+	console.warn(`glaze: color "${name}" cannot meet ${metricLabel(contrast)} in ${scheme} scheme (got ${actual.toFixed(2)}). Try widening the tone window, lowering the contrast target, or picking a base color further from this color's tone.`);
+}
+/**
+* Verification (§10): a chromatic swatch inherits the gray tone's
+* lightness but drifts in real luminance, so a contrast-floored color may
+* land slightly under the contrast its tone implies. Emit an advisory
+* warning when the actual measured contrast drifts below the target.
+*/
+function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase) {
+	const actual = contrast.metric === "apca" ? Math.abs(apcaContrast(yColor, yBase)) : contrastRatioFromLuminance(yColor, yBase);
+	if (actual >= (contrast.metric === "apca" ? contrast.target - CONTRAST_WARN_SLACK_APCA : contrast.target * CONTRAST_WARN_SLACK_WCAG)) return;
+	const scheme = schemeLabel(isDark, isHighContrast);
+	if (dedupe(`drift|${name}|${scheme}|${contrast.metric}|${contrast.target.toFixed(2)}|${actual.toFixed(2)}`)) return;
+	console.warn(`glaze: color "${name}" drifts below ${metricLabel(contrast)} in ${scheme} scheme (measured ${actual.toFixed(2)}). Chromatic luminance differs from the gray tone; nudge the tone or saturation if the floor matters.`);
 }
 
 //#endregion
@@ -1310,6 +1500,11 @@ function warnContrastUnmet(name, isDark, isHighContrast, target, actual) {
 * Owns the per-scheme resolve helpers for regular, shadow, and mix
 * color defs.
 *
+* Variants are stored in OKHST: `h` / `s` are OKHSL hue/saturation and
+* `t` is the canonical contrast-uniform tone (0–1, reference eps). The
+* resolver works in tone for regular colors and converts to/from OKHSL
+* lightness only at the mix/shadow and luminance edges.
+*
 * Every function receives a single `GlazeConfigResolved` so the full
 * per-instance config (including overrides) is available without
 * re-reading the global singleton mid-resolve.
@@ -1320,10 +1515,50 @@ function getSchemeVariant(color, isDark, isHighContrast) {
 	if (isHighContrast) return color.lightContrast;
 	return color.light;
 }
-function resolveRootColor(_name, def, _ctx, isHighContrast) {
-	const rawL = def.lightness;
+/** Edge adapter: resolved variant (`t`) → OKHSL-lightness variant. */
+function toOkhslVariant(v) {
+	const c = variantToOkhsl(v);
 	return {
-		lightL: clamp(parseRelativeOrAbsolute(isHighContrast ? pairHC(rawL) : pairNormal(rawL)).value, 0, 100),
+		h: c.h,
+		s: c.s,
+		l: c.l,
+		alpha: v.alpha
+	};
+}
+/** Edge adapter: OKHSL-lightness variant → resolved variant (`t`). */
+function toToneVariant(v) {
+	const c = okhslToOkhst({
+		h: v.h,
+		s: v.s,
+		l: v.l
+	});
+	return {
+		h: c.h,
+		s: c.s,
+		t: c.t,
+		alpha: v.alpha
+	};
+}
+function resolveContrastSpec(spec, isHighContrast) {
+	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast);
+}
+/**
+* Apply the relative-tone delta against a base, honoring `flip`.
+*
+* When `flip` is on and `base + delta` falls outside `[0, 100]`, mirror the
+* delta to the other side of the base (so an offset that would clamp instead
+* reflects back into range). When off, the caller clamps as usual.
+*/
+function applyToneFlip(delta, baseTone, flip) {
+	if (!flip) return delta;
+	const target = baseTone + delta;
+	if (target >= 0 && target <= 100) return delta;
+	return -delta;
+}
+function resolveRootColor(def, isHighContrast) {
+	const rawT = def.tone;
+	return {
+		authorTone: clamp(parseToneValue(isHighContrast ? pairHC(rawT) : pairNormal(rawT)).value, 0, 100),
 		satFactor: clamp(def.saturation ?? 1, 0, 1)
 	};
 }
@@ -1333,47 +1568,49 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 	if (!baseResolved) throw new Error(`glaze: base "${baseName}" not yet resolved for "${name}".`);
 	const mode = def.mode ?? "auto";
 	const satFactor = clamp(def.saturation ?? 1, 0, 1);
+	const flip = def.flip ?? ctx.config.autoFlip;
 	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
-	const baseL = baseVariant.l * 100;
-	let preferredL;
-	const rawLightness = def.lightness;
-	if (rawLightness === void 0) preferredL = baseL;
+	const baseTone = baseVariant.t * 100;
+	let preferredTone;
+	const rawTone = def.tone;
+	if (rawTone === void 0) preferredTone = baseTone;
 	else {
-		const parsed = parseRelativeOrAbsolute(isHighContrast ? pairHC(rawLightness) : pairNormal(rawLightness));
-		if (parsed.relative) {
-			const delta = parsed.value;
-			if (isDark && mode === "auto") preferredL = lightMappedToDark(clamp(getSchemeVariant(baseResolved, false, isHighContrast).l * 100 + delta, 0, 100), isHighContrast, ctx.config);
-			else preferredL = clamp(baseL + delta, 0, 100);
-		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode, isHighContrast, ctx.config);
-		else preferredL = mapLightnessLight(parsed.value, mode, isHighContrast, ctx.config);
+		const parsed = parseToneValue(isHighContrast ? pairHC(rawTone) : pairNormal(rawTone));
+		if (parsed.kind === "relative") if (isDark && mode === "auto") {
+			const baseLightTone = getSchemeVariant(baseResolved, false, isHighContrast).t * 100;
+			preferredTone = mapToneForScheme(clamp(baseLightTone + applyToneFlip(parsed.value, baseLightTone, flip), 0, 100), "auto", true, isHighContrast, ctx.config);
+		} else preferredTone = clamp(baseTone + applyToneFlip(parsed.value, baseTone, flip), 0, 100);
+		else preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, ctx.config);
 	}
 	const rawContrast = def.contrast;
 	if (rawContrast !== void 0) {
-		const minCr = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
+		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast);
 		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config) : satFactor * ctx.saturation / 100;
-		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
-		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast, ctx.config);
+		const baseOkhsl = toOkhslVariant(baseVariant);
+		const baseLinearRgb = okhslToLinearSrgb(baseOkhsl.h, baseOkhsl.s, baseOkhsl.l);
+		const toneRange = schemeToneRange(isDark, mode, isHighContrast, ctx.config);
 		let initialDirection;
-		if (preferredL < baseL) initialDirection = "darker";
-		else if (preferredL > baseL) initialDirection = "lighter";
-		const result = findLightnessForContrast({
+		if (preferredTone < baseTone) initialDirection = "darker";
+		else if (preferredTone > baseTone) initialDirection = "lighter";
+		const result = findToneForContrast({
 			hue: effectiveHue,
 			saturation: effectiveSat,
-			preferredLightness: clamp(preferredL / 100, windowRange[0], windowRange[1]),
+			preferredTone: clamp(preferredTone / 100, toneRange[0], toneRange[1]),
 			baseLinearRgb,
-			contrast: minCr,
-			lightnessRange: [0, 1],
+			contrast: resolvedContrast,
+			toneRange: [0, 1],
 			initialDirection,
-			flip: ctx.config.autoFlip
+			flip,
+			saturationTaper: ctx.config.saturationTaper
 		});
-		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, minCr, result.contrast);
+		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, resolvedContrast, result.contrast);
 		return {
-			l: result.lightness * 100,
+			tone: result.tone * 100,
 			satFactor
 		};
 	}
 	return {
-		l: clamp(preferredL, 0, 100),
+		tone: clamp(preferredTone, 0, 100),
 		satFactor
 	};
 }
@@ -1382,50 +1619,39 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	if (isMixDef(def)) return resolveMixForScheme(def, ctx, isDark, isHighContrast);
 	const regDef = def;
 	const mode = regDef.mode ?? "auto";
-	const isRoot = isAbsoluteLightness(regDef.lightness) && !regDef.base;
+	const isRoot = isAbsoluteTone(regDef.tone) && !regDef.base;
 	const effectiveHue = resolveEffectiveHue(ctx.hue, regDef.hue);
-	let lightL;
+	let finalTone;
 	let satFactor;
 	if (isRoot) {
-		const root = resolveRootColor(name, regDef, ctx, isHighContrast);
-		lightL = root.lightL;
+		const root = resolveRootColor(regDef, isHighContrast);
+		finalTone = mapToneForScheme(root.authorTone, mode, isDark, isHighContrast, ctx.config);
 		satFactor = root.satFactor;
 	} else {
 		const dep = resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, effectiveHue);
-		lightL = dep.l;
+		finalTone = dep.tone;
 		satFactor = dep.satFactor;
 	}
-	let finalL;
-	let finalSat;
-	if (isDark && isRoot) {
-		finalL = mapLightnessDark(lightL, mode, isHighContrast, ctx.config);
-		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config);
-	} else if (isDark && !isRoot) {
-		finalL = lightL;
-		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config);
-	} else if (isRoot) {
-		finalL = mapLightnessLight(lightL, mode, isHighContrast, ctx.config);
-		finalSat = satFactor * ctx.saturation / 100;
-	} else {
-		finalL = lightL;
-		finalSat = satFactor * ctx.saturation / 100;
-	}
+	const baseSat = satFactor * ctx.saturation / 100;
+	let finalSat = isDark ? mapSaturationDark(baseSat, mode, ctx.config) : baseSat;
+	const toneFraction = clamp(finalTone / 100, 0, 1);
+	finalSat = saturationEnvelope(finalSat, toneFraction, ctx.config.saturationTaper);
 	return {
 		h: effectiveHue,
 		s: clamp(finalSat, 0, 1),
-		l: clamp(finalL / 100, 0, 1),
+		t: toneFraction,
 		alpha: regDef.opacity ?? 1
 	};
 }
 function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
-	const bgVariant = getSchemeVariant(ctx.resolved.get(def.bg), isDark, isHighContrast);
+	const bgVariant = toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.bg), isDark, isHighContrast));
 	let fgVariant;
-	if (def.fg) fgVariant = getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast);
+	if (def.fg) fgVariant = toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast));
 	const intensity = isHighContrast ? pairHC(def.intensity) : pairNormal(def.intensity);
 	const tuning = resolveShadowTuning(def.tuning, ctx.config.shadowTuning);
-	return computeShadow(bgVariant, fgVariant, intensity, tuning);
+	return toToneVariant(computeShadow(bgVariant, fgVariant, intensity, tuning));
 }
-function variantToLinearRgb(v) {
+function okhslVariantToLinearRgb(v) {
 	return okhslToLinearSrgb(v.h, v.s, v.l);
 }
 /**
@@ -1449,59 +1675,59 @@ function linearSrgbLerp(base, target, t) {
 		base[2] + (target[2] - base[2]) * t
 	];
 }
-function linearRgbToVariant(rgb) {
+function linearRgbToToneVariant(rgb) {
 	const [h, s, l] = srgbToOkhsl([
 		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[0]))),
 		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[1]))),
 		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[2])))
 	]);
-	return {
+	return toToneVariant({
 		h,
 		s,
 		l,
 		alpha: 1
-	};
+	});
 }
 function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
 	const baseResolved = ctx.resolved.get(def.base);
 	const targetResolved = ctx.resolved.get(def.target);
-	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
-	const targetVariant = getSchemeVariant(targetResolved, isDark, isHighContrast);
+	const baseVariant = toOkhslVariant(getSchemeVariant(baseResolved, isDark, isHighContrast));
+	const targetVariant = toOkhslVariant(getSchemeVariant(targetResolved, isDark, isHighContrast));
 	let t = clamp(isHighContrast ? pairHC(def.value) : pairNormal(def.value), 0, 100) / 100;
 	const blend = def.blend ?? "opaque";
 	const space = def.space ?? "okhsl";
-	const baseLinear = variantToLinearRgb(baseVariant);
-	const targetLinear = variantToLinearRgb(targetVariant);
+	const baseLinear = okhslVariantToLinearRgb(baseVariant);
+	const targetLinear = okhslVariantToLinearRgb(targetVariant);
 	if (def.contrast !== void 0) {
-		const minCr = isHighContrast ? pairHC(def.contrast) : pairNormal(def.contrast);
+		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast);
+		const metric = resolvedContrast.metric;
 		let luminanceAt;
-		if (blend === "transparent") luminanceAt = (v) => gamutClampedLuminance(linearSrgbLerp(baseLinear, targetLinear, v));
-		else if (space === "srgb") luminanceAt = (v) => gamutClampedLuminance(linearSrgbLerp(baseLinear, targetLinear, v));
+		if (blend === "transparent" || space === "srgb") luminanceAt = (v) => metricLuminance(metric, linearSrgbLerp(baseLinear, targetLinear, v));
 		else luminanceAt = (v) => {
-			return gamutClampedLuminance(okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v));
+			return metricLuminance(metric, okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v));
 		};
 		t = findValueForMixContrast({
 			preferredValue: t,
 			baseLinearRgb: baseLinear,
 			targetLinearRgb: targetLinear,
-			contrast: minCr,
+			contrast: resolvedContrast,
 			luminanceAtValue: luminanceAt,
 			flip: ctx.config.autoFlip
 		}).value;
 	}
-	if (blend === "transparent") return {
+	if (blend === "transparent") return toToneVariant({
 		h: targetVariant.h,
 		s: targetVariant.s,
 		l: targetVariant.l,
 		alpha: clamp(t, 0, 1)
-	};
-	if (space === "srgb") return linearRgbToVariant(linearSrgbLerp(baseLinear, targetLinear, t));
-	return {
+	});
+	if (space === "srgb") return linearRgbToToneVariant(linearSrgbLerp(baseLinear, targetLinear, t));
+	return toToneVariant({
 		h: mixHue(baseVariant, targetVariant, t),
 		s: clamp(baseVariant.s + (targetVariant.s - baseVariant.s) * t, 0, 1),
 		l: clamp(baseVariant.l + (targetVariant.l - baseVariant.l) * t, 0, 1),
 		alpha: 1
-	};
+	});
 }
 function defMode(def) {
 	if (isShadowDef(def) || isMixDef(def)) return void 0;
@@ -1547,6 +1773,53 @@ function seedField(order, ctx, field, source) {
 		});
 	}
 }
+/**
+* After the four passes, surface chromatic contrast drift (§10): a color
+* resolved with a `base` + `contrast` may land slightly under the contrast
+* its tone implies because chromatic luminance drifts from the gray tone.
+*/
+function verifyContrastDrift(order, defs, result) {
+	for (const name of order) {
+		const def = defs[name];
+		if (isShadowDef(def) || isMixDef(def)) continue;
+		const regDef = def;
+		if (regDef.contrast === void 0 || !regDef.base) continue;
+		const color = result.get(name);
+		const base = result.get(regDef.base);
+		if (!color || !base) continue;
+		for (const s of [
+			{
+				isDark: false,
+				isHighContrast: false,
+				field: "light"
+			},
+			{
+				isDark: false,
+				isHighContrast: true,
+				field: "lightContrast"
+			},
+			{
+				isDark: true,
+				isHighContrast: false,
+				field: "dark"
+			},
+			{
+				isDark: true,
+				isHighContrast: true,
+				field: "darkContrast"
+			}
+		]) {
+			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast);
+			const cVariant = color[s.field];
+			const bVariant = base[s.field];
+			const cOkhsl = toOkhslVariant(cVariant);
+			const bOkhsl = toOkhslVariant(bVariant);
+			const yC = metricLuminance(spec.metric, okhslToLinearSrgb(cOkhsl.h, cOkhsl.s, cOkhsl.l));
+			const yB = metricLuminance(spec.metric, okhslToLinearSrgb(bOkhsl.h, bOkhsl.s, bOkhsl.l));
+			warnContrastDrift(name, s.isDark, s.isHighContrast, spec, yC, yB);
+		}
+	}
+}
 function resolveAllColors(hue, saturation, defs, config, externalBases) {
 	validateColorDefs(defs, externalBases);
 	const order = topoSort(defs);
@@ -1575,6 +1848,7 @@ function resolveAllColors(hue, saturation, defs, config, externalBases) {
 		darkContrast: darkHCMap.get(name),
 		mode: defMode(defs[name])
 	});
+	verifyContrastDrift(order, defs, result);
 	return result;
 }
 
@@ -1600,7 +1874,8 @@ function fmt(value, decimals) {
 	return parseFloat(value.toFixed(decimals)).toString();
 }
 function formatVariant(v, format = "okhsl") {
-	const base = formatters[format](v.h, v.s * 100, v.l * 100);
+	const { l } = variantToOkhsl(v);
+	const base = formatters[format](v.h, v.s * 100, l * 100);
 	if (v.alpha >= 1) return base;
 	const closing = base.lastIndexOf(")");
 	return `${base.slice(0, closing)} / ${fmt(v.alpha, 4)})`;
@@ -1677,9 +1952,9 @@ function buildCssMap(resolved, prefix, suffix, format) {
 * Standalone single-color tokens (`glaze.color()` / `glaze.colorFrom()`).
 *
 * Owns the value-shorthand parser (hex, `rgb()` / `hsl()` / `okhsl()` /
-* `oklch()`, `{ r, g, b }`, `{ h, s, l }`, `{ l, c, h }`), the structured-input
-* validator, the two factory paths (value vs structured), and the
-* JSON-safe export / rehydration round-trip.
+* `okhst()` / `oklch()`, `{ r, g, b }`, `{ h, s, l }`, `{ h, s, t }`,
+* `{ l, c, h }`), the structured-input validator, the two factory paths
+* (value vs structured), and the JSON-safe export / rehydration round-trip.
 *
 * Standalone tokens snapshot the full effective config at create time
 * so later `configure()` calls do not retroactively change exported
@@ -1690,7 +1965,7 @@ function buildCssMap(resolved, prefix, suffix, format) {
 */
 /** Internal name of the user-facing standalone color in the synthesized def map. */
 const STANDALONE_VALUE = "value";
-/** Internal name of the hidden static-anchor seed used for relative lightness / contrast. */
+/** Internal name of the hidden static-anchor seed used for relative tone / contrast. */
 const STANDALONE_SEED = "seed";
 /** Internal name of an externally-resolved `GlazeColorToken` injected as a base reference. */
 const STANDALONE_BASE = "externalBase";
@@ -1703,17 +1978,17 @@ const RESERVED_STANDALONE_NAMES = new Set([
 /**
 * Build the per-token effective config override for a value-form color.
 *
-* Light window defaults to `false` (preserve input lightness exactly).
+* Light window defaults to `false` (preserve input tone exactly).
 * All other fields snapshot from global at create time. User override
 * fields win over all defaults.
 */
 function buildValueFormConfigOverride(userOverride) {
 	const cfg = getConfig();
 	return {
-		lightLightness: userOverride?.lightLightness !== void 0 ? userOverride.lightLightness : false,
-		darkLightness: userOverride?.darkLightness !== void 0 ? userOverride.darkLightness : cfg.darkLightness,
+		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : false,
+		darkTone: userOverride?.darkTone !== void 0 ? userOverride.darkTone : cfg.darkTone,
 		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
-		darkCurve: userOverride?.darkCurve ?? cfg.darkCurve,
+		saturationTaper: userOverride?.saturationTaper ?? cfg.saturationTaper,
 		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
 		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
 	};
@@ -1727,10 +2002,10 @@ function buildValueFormConfigOverride(userOverride) {
 function buildStructuredConfigOverride(userOverride) {
 	const cfg = getConfig();
 	return {
-		lightLightness: userOverride?.lightLightness !== void 0 ? userOverride.lightLightness : cfg.lightLightness,
-		darkLightness: userOverride?.darkLightness !== void 0 ? userOverride.darkLightness : cfg.darkLightness,
+		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : cfg.lightTone,
+		darkTone: userOverride?.darkTone !== void 0 ? userOverride.darkTone : cfg.darkTone,
 		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
-		darkCurve: userOverride?.darkCurve ?? cfg.darkCurve,
+		saturationTaper: userOverride?.saturationTaper ?? cfg.saturationTaper,
 		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
 		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
 	};
@@ -1752,7 +2027,7 @@ function resolvedConfigFromOverride(override) {
 * than bare degrees (`deg` is the only suffix tolerated by `parseFloat`)
 * are out of scope.
 */
-const COLOR_FN_RE = /^(rgba?|hsla?|okhsl|oklch)\(\s*([^)]*)\s*\)$/i;
+const COLOR_FN_RE = /^(rgba?|hsla?|okhsl|okhst|oklch)\(\s*([^)]*)\s*\)$/i;
 function parseNumberOrPercent(raw, percentScale) {
 	if (raw.endsWith("%")) return parseFloat(raw) / 100 * percentScale;
 	return parseFloat(raw);
@@ -1833,6 +2108,11 @@ function parseColorString(input) {
 			s: parseNumberOrPercent(components[1], 1),
 			l: parseNumberOrPercent(components[2], 1)
 		};
+		case "okhst": return okhstToOkhsl({
+			h: parseFloat(components[0]),
+			s: parseNumberOrPercent(components[1], 1),
+			t: parseNumberOrPercent(components[2], 1)
+		});
 		case "oklch": {
 			const L = parseNumberOrPercent(components[0], 1);
 			const C = parseNumberOrPercent(components[1], .4);
@@ -1858,7 +2138,7 @@ function parseColorString(input) {
 function validateOkhslColor(value) {
 	const { h, s, l } = value;
 	if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(l)) throw new Error("glaze.color: OkhslColor h/s/l must be finite numbers.");
-	if (s > 1.5 || l > 1.5) throw new Error("glaze.color: OkhslColor s/l must be in 0–1 range. Did you mean the structured form { hue, saturation, lightness } (which uses 0–100)?");
+	if (s > 1.5 || l > 1.5) throw new Error("glaze.color: OkhslColor s/l must be in 0–1 range. Did you mean the structured form { hue, saturation, tone } (which uses 0–100)?");
 }
 /** Validate a user-supplied `{ r, g, b }` object in 0–255. */
 function validateRgbColor(value) {
@@ -1896,6 +2176,15 @@ function isRgbColorObject(value) {
 function isOklchColorObject(value) {
 	return "c" in value && "l" in value && "h" in value;
 }
+function isOkhstColorObject(value) {
+	return "t" in value && "h" in value && "s" in value;
+}
+/** Validate a user-supplied `{ h, s, t }` OKHST object (s/t in 0–1). */
+function validateOkhstColor(value) {
+	const { h, s, t } = value;
+	if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(t)) throw new Error("glaze.color: OkhstColor h/s/t must be finite numbers.");
+	if (s > 1.5 || t > 1.5) throw new Error("glaze.color: OkhstColor s/t must be in 0–1 range. Did you mean the structured form { hue, saturation, tone } (which uses 0–100)?");
+}
 /**
 * Validate a user-supplied `opacity` override on `glaze.color()`.
 * Must be a finite number in `0..=1`.
@@ -1905,7 +2194,7 @@ function validateStandaloneOpacity(value) {
 }
 /**
 * Validate a structured `GlazeColorInput`. Range-checks the `hue` /
-* `saturation` / `lightness` numerics (and any HC-pair second value)
+* `saturation` / `tone` numerics (and any HC-pair second value)
 * before the resolver sees them so out-of-range or non-finite inputs
 * fail with a helpful, top-level error rather than producing a
 * NaN-laden token. `opacity` is checked here too so all input
@@ -1914,13 +2203,14 @@ function validateStandaloneOpacity(value) {
 function validateStructuredInput(input) {
 	if (!Number.isFinite(input.hue)) throw new Error(`glaze.color: structured hue must be a finite number (got ${input.hue}).`);
 	if (!Number.isFinite(input.saturation) || input.saturation < 0 || input.saturation > 100) throw new Error(`glaze.color: structured saturation must be a finite number in 0–100 (got ${input.saturation}).`);
-	const checkLightness = (value, label) => {
-		if (!Number.isFinite(value) || value < 0 || value > 100) throw new Error(`glaze.color: structured ${label} must be a finite number in 0–100 (got ${value}).`);
+	const checkTone = (value, label) => {
+		if (value === "max" || value === "min") return;
+		if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) throw new Error(`glaze.color: structured ${label} must be a finite number in 0–100 or 'max'/'min' (got ${String(value)}).`);
 	};
-	if (Array.isArray(input.lightness)) {
-		checkLightness(input.lightness[0], "lightness[normal]");
-		checkLightness(input.lightness[1], "lightness[hc]");
-	} else checkLightness(input.lightness, "lightness");
+	if (Array.isArray(input.tone)) {
+		checkTone(input.tone[0], "tone[normal]");
+		checkTone(input.tone[1], "tone[hc]");
+	} else checkTone(input.tone, "tone");
 	if (input.saturationFactor !== void 0) {
 		if (!Number.isFinite(input.saturationFactor) || input.saturationFactor < 0 || input.saturationFactor > 1) throw new Error(`glaze.color: structured saturationFactor must be a finite number in 0–1 (got ${input.saturationFactor}).`);
 	}
@@ -1962,6 +2252,10 @@ function extractOkhslFromValue(value) {
 		validateOklchColor(value);
 		return oklchComponentsToOkhsl(value.l, value.c, value.h);
 	}
+	if (isOkhstColorObject(value)) {
+		validateOkhstColor(value);
+		return okhstToOkhsl(value);
+	}
 	validateOkhslColor(value);
 	return value;
 }
@@ -1971,7 +2265,7 @@ function extractOkhslFromValue(value) {
 * The user-facing color (`STANDALONE_VALUE`) defaults to `mode: 'auto'`
 * across every value-shorthand form.
 *
-* When the user requests `contrast` or relative `lightness`, a hidden
+* When the user requests `contrast` or relative `tone`, a hidden
 * `STANDALONE_SEED` def is synthesized at `mode: 'static'`. That keeps
 * the seed pinned to the literal user-provided color across all four
 * variants, so the contrast solver always anchors against it.
@@ -1980,19 +2274,21 @@ function buildStandaloneValueDefs(main, options) {
 	const seedHue = typeof options?.hue === "number" ? options.hue : main.h;
 	const seedSaturation = options?.saturation ?? main.s * 100;
 	const relativeHue = typeof options?.hue === "string" ? options.hue : void 0;
-	const lightnessOption = options?.lightness;
+	const toneOption = options?.tone;
 	const hasExternalBase = options?.base !== void 0;
-	const needsSeedAnchor = !hasExternalBase && (options?.contrast !== void 0 || lightnessOption !== void 0 && !isAbsoluteLightness(lightnessOption));
+	const needsSeedAnchor = !hasExternalBase && (options?.contrast !== void 0 || toneOption !== void 0 && !isAbsoluteTone(toneOption));
 	if (options?.opacity !== void 0) validateStandaloneOpacity(options.opacity);
 	const userName = options?.name;
 	if (userName !== void 0) validateStandaloneName(userName);
 	const primary = userName ?? STANDALONE_VALUE;
+	const seedTone = toTone(main.l);
 	const valueDef = {
 		hue: relativeHue,
 		saturation: options?.saturationFactor,
-		lightness: lightnessOption ?? main.l * 100,
+		tone: toneOption ?? seedTone,
 		contrast: options?.contrast,
 		mode: options?.mode ?? "auto",
+		flip: options?.flip,
 		opacity: options?.opacity,
 		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
 	};
@@ -2000,7 +2296,7 @@ function buildStandaloneValueDefs(main, options) {
 	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
 		hue: main.h,
 		saturation: 1,
-		lightness: main.l * 100,
+		tone: seedTone,
 		mode: "static"
 	};
 	return {
@@ -2044,9 +2340,9 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 }
 /**
 * When a value/`from` color links to a base that was created via the
-* structured form (with explicit `hue`/`saturation`/`lightness`), resolve
-* that base with `lightLightness: false` for the linking math so the
-* contrast/lightness anchor matches the input lightness — not the
+* structured form (with explicit `hue`/`saturation`/`tone`), resolve
+* that base with `lightTone: false` for the linking math so the
+* contrast/tone anchor matches the input tone — not the
 * windowed output. The original base token's `.resolve()` is unaffected.
 */
 function toLinkingBase(base) {
@@ -2055,7 +2351,7 @@ function toLinkingBase(base) {
 	if (exp.form !== "structured") return base;
 	const linkingConfig = {
 		...exp.config ?? {},
-		lightLightness: false
+		lightTone: false
 	};
 	return colorFromExport({
 		...exp,
@@ -2088,18 +2384,22 @@ function createColorToken(input, configOverride) {
 	const hasExternalBase = baseToken !== void 0;
 	const needsSeedAnchor = !hasExternalBase && input.contrast !== void 0;
 	const defs = { [primary]: {
-		lightness: input.lightness,
+		tone: input.tone,
 		saturation: input.saturationFactor,
 		mode: input.mode ?? "auto",
+		flip: input.flip,
 		contrast: input.contrast,
 		opacity: input.opacity,
 		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
 	} };
-	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
-		lightness: pairNormal(input.lightness),
-		saturation: 1,
-		mode: "static"
-	};
+	if (needsSeedAnchor) {
+		const seedTone = pairNormal(input.tone);
+		defs[STANDALONE_SEED] = {
+			tone: seedTone === "max" ? 100 : seedTone === "min" ? 0 : seedTone,
+			saturation: 1,
+			mode: "static"
+		};
+	}
 	const effectiveConfigOverride = buildStructuredConfigOverride(configOverride);
 	const effectiveConfig = resolvedConfigFromOverride(effectiveConfigOverride);
 	const exportData = () => ({
@@ -2132,9 +2432,10 @@ function buildOverridesExport(options) {
 	const out = {};
 	if (options.hue !== void 0) out.hue = options.hue;
 	if (options.saturation !== void 0) out.saturation = options.saturation;
-	if (options.lightness !== void 0) out.lightness = options.lightness;
+	if (options.tone !== void 0) out.tone = options.tone;
 	if (options.saturationFactor !== void 0) out.saturationFactor = options.saturationFactor;
 	if (options.mode !== void 0) out.mode = options.mode;
+	if (options.flip !== void 0) out.flip = options.flip;
 	if (options.contrast !== void 0) out.contrast = options.contrast;
 	if (options.opacity !== void 0) out.opacity = options.opacity;
 	if (options.name !== void 0) out.name = options.name;
@@ -2145,10 +2446,11 @@ function buildStructuredInputExport(input) {
 	const out = {
 		hue: input.hue,
 		saturation: input.saturation,
-		lightness: input.lightness
+		tone: input.tone
 	};
 	if (input.saturationFactor !== void 0) out.saturationFactor = input.saturationFactor;
 	if (input.mode !== void 0) out.mode = input.mode;
+	if (input.flip !== void 0) out.flip = input.flip;
 	if (input.opacity !== void 0) out.opacity = input.opacity;
 	if (input.contrast !== void 0) out.contrast = input.contrast;
 	if (input.name !== void 0) out.name = input.name;
@@ -2165,9 +2467,10 @@ function rehydrateOverrides(data) {
 	const out = {};
 	if (data.hue !== void 0) out.hue = data.hue;
 	if (data.saturation !== void 0) out.saturation = data.saturation;
-	if (data.lightness !== void 0) out.lightness = data.lightness;
+	if (data.tone !== void 0) out.tone = data.tone;
 	if (data.saturationFactor !== void 0) out.saturationFactor = data.saturationFactor;
 	if (data.mode !== void 0) out.mode = data.mode;
+	if (data.flip !== void 0) out.flip = data.flip;
 	if (data.contrast !== void 0) out.contrast = data.contrast;
 	if (data.opacity !== void 0) out.opacity = data.opacity;
 	if (data.name !== void 0) out.name = data.name;
@@ -2178,10 +2481,11 @@ function rehydrateStructuredInput(data) {
 	const out = {
 		hue: data.hue,
 		saturation: data.saturation,
-		lightness: data.lightness
+		tone: data.tone
 	};
 	if (data.saturationFactor !== void 0) out.saturationFactor = data.saturationFactor;
 	if (data.mode !== void 0) out.mode = data.mode;
+	if (data.flip !== void 0) out.flip = data.flip;
 	if (data.opacity !== void 0) out.opacity = data.opacity;
 	if (data.contrast !== void 0) out.contrast = data.contrast;
 	if (data.name !== void 0) out.name = data.name;
@@ -2450,7 +2754,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 //#endregion
 //#region src/glaze.ts
 /**
-* Glaze — OKHSL-based color theme generator.
+* Glaze — OKHST color theme generator.
 *
 * Public API entry. Wires `glaze()` and its attached static methods to
 * the focused modules in this folder:
@@ -2465,7 +2769,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 * Create a single-hue glaze theme.
 *
 * An optional `config` override can be supplied to customize the resolve
-* behavior for this theme (lightness windows, dark curve, etc.). The
+* behavior for this theme (tone windows, saturation taper, etc.). The
 * override is **merged over the live global config at resolve time** —
 * the theme still reacts to later `configure()` calls for fields it
 * didn't override.
@@ -2476,7 +2780,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 * // or shorthand:
 * const primary = glaze({ hue: 280, saturation: 80 });
 * // with config override:
-* const raw = glaze(280, 80, { lightLightness: false });
+* const raw = glaze(280, 80, { lightTone: false });
 * ```
 */
 function glaze(hueOrOptions, saturation, config) {
@@ -2502,15 +2806,15 @@ glaze.from = function from(data) {
 *
 * | Shape | Example | Notes |
 * |---|---|---|
-* | Bare string | `'#26fcb2'`, `'rgb(38 252 178)'` | Hex or CSS color function |
-* | Value object | `{ h: 152, s: 0.95, l: 0.74 }` | OKHSL, `{r,g,b}`, `{l,c,h}` |
+* | Bare string | `'#26fcb2'`, `'rgb(38 252 178)'` | Hex or CSS color function (incl. `okhst()`) |
+* | Value object | `{ h: 152, s: 0.95, l: 0.74 }` | OKHSL, OKHST (`{h,s,t}`), `{r,g,b}`, `{l,c,h}` |
 * | `{ from, ...overrides }` | `{ from: '#fff', base: bg, contrast: 'AA' }` | Value + color overrides |
-* | Structured | `{ hue: 152, saturation: 95, lightness: 74 }` | Full theme-style token |
+* | Structured | `{ hue: 152, saturation: 95, tone: 74 }` | Full theme-style token |
 *
 * **arg2 — config override** (optional, all shapes):
 * Overrides the resolve-relevant global config fields for this token.
 * Fields that are omitted fall through to the live global config at
-* create time (and are snapshotted). Pass `false` for a lightness window
+* create time (and are snapshotted). Pass `false` for a tone window
 * to disable clamping entirely.
 *
 * ```ts
@@ -2521,19 +2825,19 @@ glaze.from = function from(data) {
 * glaze.color({ from: '#fff', base: bg, contrast: 'AA' })
 *
 * // Structured form — full theme-style token
-* glaze.color({ hue: 152, saturation: 95, lightness: 74 })
+* glaze.color({ hue: 152, saturation: 95, tone: 74 })
 *
 * // Config override on any form
-* glaze.color('#26fcb2', { darkLightness: false, autoFlip: false })
-* glaze.color({ from: '#fff', base: bg }, { darkCurve: 0.3 })
+* glaze.color('#26fcb2', { darkTone: false, autoFlip: false })
+* glaze.color({ from: '#fff', base: bg }, { saturationTaper: 0 })
 * ```
 *
 * Defaults: every form defaults to `mode: 'auto'`. Value-shorthand forms
-* (bare strings and value objects) preserve light lightness exactly
-* (`lightLightness: false` internally). Structured form snapshots both
-* lightness windows from `globalConfig` at create time.
+* (bare strings and value objects) preserve light tone exactly
+* (`lightTone: false` internally). Structured form snapshots both
+* tone windows from `globalConfig` at create time.
 *
-* Relative `lightness: '+N'` and `contrast` anchor to the literal seed by
+* Relative `tone: '+N'` and `contrast` anchor to the literal seed by
 * default; when `base` is set they anchor to the base's resolved variant
 * per scheme. Relative `hue: '+N'` always anchors to the seed, not the base.
 */
@@ -2559,13 +2863,24 @@ glaze.shadow = function shadow(input) {
 	const fg = input.fg ? extractOkhslFromValue(input.fg) : void 0;
 	const cfg = getConfig();
 	const tuning = resolveShadowTuning(input.tuning, cfg.shadowTuning);
-	return computeShadow({
+	const result = computeShadow({
 		...bg,
 		alpha: 1
 	}, fg ? {
 		...fg,
 		alpha: 1
 	} : void 0, input.intensity, tuning);
+	const { h, s, t } = okhslToOkhst({
+		h: result.h,
+		s: result.s,
+		l: result.l
+	});
+	return {
+		h,
+		s,
+		t,
+		alpha: result.alpha
+	};
 };
 /** Format a resolved color variant as a CSS string. */
 glaze.format = function format(variant, colorFormat) {
@@ -2623,23 +2938,33 @@ glaze.resetConfig = function resetConfig$1() {
 };
 
 //#endregion
+exports.REF_EPS = REF_EPS;
+exports.apcaContrast = apcaContrast;
 exports.contrastRatioFromLuminance = contrastRatioFromLuminance;
-exports.findLightnessForContrast = findLightnessForContrast;
+exports.findToneForContrast = findToneForContrast;
 exports.findValueForMixContrast = findValueForMixContrast;
 exports.formatHsl = formatHsl;
 exports.formatOkhsl = formatOkhsl;
 exports.formatOklch = formatOklch;
 exports.formatRgb = formatRgb;
+exports.fromTone = fromTone;
 exports.gamutClampedLuminance = gamutClampedLuminance;
 exports.glaze = glaze;
 exports.hslToSrgb = hslToSrgb;
 exports.okhslToLinearSrgb = okhslToLinearSrgb;
+exports.okhslToOkhst = okhslToOkhst;
 exports.okhslToOklab = okhslToOklab;
 exports.okhslToSrgb = okhslToSrgb;
+exports.okhstToOkhsl = okhstToOkhsl;
 exports.oklabToOkhsl = oklabToOkhsl;
 exports.parseHex = parseHex;
 exports.parseHexAlpha = parseHexAlpha;
 exports.relativeLuminanceFromLinearRgb = relativeLuminanceFromLinearRgb;
+exports.resolveContrastForMode = resolveContrastForMode;
 exports.resolveMinContrast = resolveMinContrast;
 exports.srgbToOkhsl = srgbToOkhsl;
+exports.toTone = toTone;
+exports.toneFromY = toneFromY;
+exports.variantToOkhsl = variantToOkhsl;
+exports.yFromTone = yFromTone;
 //# sourceMappingURL=index.cjs.map