@tenphi/glaze 0.0.0-snapshot.78261ef → 0.0.0-snapshot.7dca259

package/dist/index.mjs

@@ -96,7 +96,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];
@@ -341,9 +346,30 @@ 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);
 };
+/**
+* Convert OKLab to OKHSL.
+* Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
+* Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
+*/
 const oklabToOkhsl = (lab) => {
 	const L = lab[0];
 	const a = lab[1];
@@ -354,6 +380,12 @@ const oklabToOkhsl = (lab) => {
 		0,
 		toe(L)
 	];
+	const L_EXTREME_EPSILON = 1e-6;
+	if (L >= 1 - L_EXTREME_EPSILON || L <= L_EXTREME_EPSILON) return [
+		0,
+		0,
+		toe(L)
+	];
 	const a_ = a / C;
 	const b_ = b / C;
 	let h = Math.atan2(b, a) * (180 / Math.PI);
@@ -391,32 +423,108 @@ function srgbToOkhsl(rgb) {
 	]));
 }
 /**
+* Convert CSS HSL (sRGB-based) to gamma-encoded sRGB [r, g, b] in 0–1 range.
+* h: 0–360, s: 0–1, l: 0–1.
+*
+* Note: CSS HSL is not the same as OKHSL — it's HSL in the sRGB color space.
+* Use this when parsing `hsl(...)` strings before passing to `srgbToOkhsl`.
+*/
+function hslToSrgb(h, s, l) {
+	const hh = (h % 360 + 360) % 360 / 360;
+	const ss = clampVal(s, 0, 1);
+	const ll = clampVal(l, 0, 1);
+	if (ss === 0) return [
+		ll,
+		ll,
+		ll
+	];
+	const q = ll < .5 ? ll * (1 + ss) : ll + ss - ll * ss;
+	const p = 2 * ll - q;
+	const hueToChannel = (t) => {
+		let tt = t;
+		if (tt < 0) tt += 1;
+		if (tt > 1) tt -= 1;
+		if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+		if (tt < 1 / 2) return q;
+		if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+		return p;
+	};
+	return [
+		hueToChannel(hh + 1 / 3),
+		hueToChannel(hh),
+		hueToChannel(hh - 1 / 3)
+	];
+}
+/**
 * Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
 * Returns null if the string is not a valid hex color.
+*
+* For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
+* use {@link parseHexAlpha}.
 */
 function parseHex(hex) {
+	const result = parseHexAlpha(hex);
+	if (!result || result.alpha !== void 0) return null;
+	return result.rgb;
+}
+/**
+* Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
+* sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
+* Returns null if the string is not a valid hex color.
+*/
+function parseHexAlpha(hex) {
 	const h = hex.startsWith("#") ? hex.slice(1) : hex;
 	if (h.length === 3) {
 		const r = parseInt(h[0] + h[0], 16);
 		const g = parseInt(h[1] + h[1], 16);
 		const b = parseInt(h[2] + h[2], 16);
 		if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
-		return [
+		return { rgb: [
 			r / 255,
 			g / 255,
 			b / 255
-		];
+		] };
+	}
+	if (h.length === 4) {
+		const r = parseInt(h[0] + h[0], 16);
+		const g = parseInt(h[1] + h[1], 16);
+		const b = parseInt(h[2] + h[2], 16);
+		const a = parseInt(h[3] + h[3], 16);
+		if (isNaN(r) || isNaN(g) || isNaN(b) || isNaN(a)) return null;
+		return {
+			rgb: [
+				r / 255,
+				g / 255,
+				b / 255
+			],
+			alpha: a / 255
+		};
 	}
 	if (h.length === 6) {
 		const r = parseInt(h.slice(0, 2), 16);
 		const g = parseInt(h.slice(2, 4), 16);
 		const b = parseInt(h.slice(4, 6), 16);
 		if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
-		return [
+		return { rgb: [
 			r / 255,
 			g / 255,
 			b / 255
-		];
+		] };
+	}
+	if (h.length === 8) {
+		const r = parseInt(h.slice(0, 2), 16);
+		const g = parseInt(h.slice(2, 4), 16);
+		const b = parseInt(h.slice(4, 6), 16);
+		const a = parseInt(h.slice(6, 8), 16);
+		if (isNaN(r) || isNaN(g) || isNaN(b) || isNaN(a)) return null;
+		return {
+			rgb: [
+				r / 255,
+				g / 255,
+				b / 255
+			],
+			alpha: a / 255
+		};
 	}
 	return null;
 }
@@ -471,15 +579,392 @@ function formatOklch(h, s, l) {
 	return `oklch(${fmt$1(L, 4)} ${fmt$1(C, 4)} ${fmt$1(hh, 2)})`;
 }
 
+//#endregion
+//#region src/config.ts
+/**
+* Build a fresh defaults object. Called from module init and from
+* `resetConfig()` so the two paths can't drift.
+*/
+function defaultConfig() {
+	return {
+		lightTone: {
+			lo: 13,
+			hi: 100,
+			eps: .05
+		},
+		darkTone: {
+			lo: 10,
+			hi: 95,
+			eps: .05
+		},
+		darkDesaturation: .1,
+		saturationTaper: .15,
+		states: {
+			dark: "@dark",
+			highContrast: "@high-contrast"
+		},
+		modes: {
+			dark: true,
+			highContrast: false
+		},
+		autoFlip: true
+	};
+}
+let globalConfig = defaultConfig();
+/**
+* Monotonic counter incremented on every `configure()` / `resetConfig()`
+* call. Theme / palette caches read this to invalidate stale resolve
+* results when the config changes between exports.
+*/
+let configVersion = 0;
+/** Live reference to the current config. Mutated by `configure()` / `resetConfig()`. */
+function getConfig() {
+	return globalConfig;
+}
+function getConfigVersion() {
+	return configVersion;
+}
+/**
+* Public-facing snapshot used by `glaze.getConfig()`. Returns a shallow
+* copy so callers can't mutate the live config.
+*/
+function snapshotConfig() {
+	return { ...globalConfig };
+}
+function configure(config) {
+	configVersion++;
+	globalConfig = {
+		lightTone: config.lightTone ?? globalConfig.lightTone,
+		darkTone: config.darkTone ?? globalConfig.darkTone,
+		darkDesaturation: config.darkDesaturation ?? globalConfig.darkDesaturation,
+		saturationTaper: config.saturationTaper ?? globalConfig.saturationTaper,
+		states: {
+			dark: config.states?.dark ?? globalConfig.states.dark,
+			highContrast: config.states?.highContrast ?? globalConfig.states.highContrast
+		},
+		modes: {
+			dark: config.modes?.dark ?? globalConfig.modes.dark,
+			highContrast: config.modes?.highContrast ?? globalConfig.modes.highContrast
+		},
+		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
+		autoFlip: config.autoFlip ?? globalConfig.autoFlip
+	};
+}
+function resetConfig() {
+	configVersion++;
+	globalConfig = defaultConfig();
+}
+/**
+* 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 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 {
+		lightTone: override.lightTone !== void 0 ? override.lightTone : base.lightTone,
+		darkTone: override.darkTone !== void 0 ? override.darkTone : base.darkTone,
+		darkDesaturation: override.darkDesaturation ?? base.darkDesaturation,
+		saturationTaper: override.saturationTaper ?? base.saturationTaper,
+		states: base.states,
+		modes: base.modes,
+		shadowTuning: override.shadowTuning ?? base.shadowTuning,
+		autoFlip: override.autoFlip ?? base.autoFlip
+	};
+}
+
+//#endregion
+//#region src/hc-pair.ts
+function pairNormal(p) {
+	return Array.isArray(p) ? p[0] : p;
+}
+function pairHC(p) {
+	return Array.isArray(p) ? p[1] : 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.
+*/
+function parseRelativeOrAbsolute(value) {
+	if (typeof value === "number") return {
+		value,
+		relative: false
+	};
+	return {
+		value: parseFloat(value),
+		relative: true
+	};
+}
+/**
+* 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.
+*/
+function resolveEffectiveHue(seedHue, defHue) {
+	if (defHue === void 0) return seedHue;
+	const parsed = parseRelativeOrAbsolute(defHue);
+	if (parsed.relative) return ((seedHue + parsed.value) % 360 + 360) % 360;
+	return (parsed.value % 360 + 360) % 360;
+}
+/**
+* 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 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 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.
 *
-* 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`.
+* 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,
@@ -490,15 +975,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);
@@ -508,326 +1053,238 @@ 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.007;
-	const yBase = gamutClampedLuminance(baseLinearRgb);
-	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
-	if (crPref >= searchTarget) return {
-		lightness: preferredLightness,
-		contrast: crPref,
-		met: true,
-		branch: "preferred"
+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 && !flip) return {
+		...initialResult,
+		lower: initialIsLower
 	};
-	const [minL, maxL] = lightnessRange;
-	const darkerResult = preferredLightness > minL ? searchBranch(hue, saturation, minL, preferredLightness, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : null;
-	const lighterResult = preferredLightness < maxL ? searchBranch(hue, saturation, preferredLightness, maxL, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : null;
-	if (darkerResult) darkerResult.met = darkerResult.contrast >= target;
-	if (lighterResult) lighterResult.met = lighterResult.contrast >= target;
-	const darkerPasses = darkerResult?.met ?? false;
-	const lighterPasses = lighterResult?.met ?? false;
-	if (darkerPasses && lighterPasses) {
-		if (Math.abs(darkerResult.lightness - preferredLightness) <= Math.abs(lighterResult.lightness - preferredLightness)) return {
-			...darkerResult,
-			branch: "darker"
+	if (flip) {
+		const oppositeResult = (initialIsLower ? distanceAnchor < hi : distanceAnchor > lo) ? runBranch(!initialIsLower) : null;
+		if (oppositeResult) oppositeResult.met = oppositeResult.contrast >= target;
+		if (initialResult.met && oppositeResult?.met) return Math.abs(initialResult.pos - distanceAnchor) <= Math.abs(oppositeResult.pos - distanceAnchor) ? {
+			...initialResult,
+			lower: initialIsLower
+		} : {
+			...oppositeResult,
+			lower: !initialIsLower,
+			flipped: true
 		};
-		return {
-			...lighterResult,
-			branch: "lighter"
+		if (initialResult.met) return {
+			...initialResult,
+			lower: initialIsLower
+		};
+		if (oppositeResult?.met) return {
+			...oppositeResult,
+			lower: !initialIsLower,
+			flipped: true
 		};
 	}
-	if (darkerPasses) return {
-		...darkerResult,
-		branch: "darker"
+	const extreme = initialIsLower ? lo : hi;
+	return {
+		pos: extreme,
+		contrast: metricScore(metric, lum(extreme), yBase),
+		met: false,
+		lower: initialIsLower
 	};
-	if (lighterPasses) return {
-		...lighterResult,
-		branch: "lighter"
+}
+/**
+* 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"
 	};
-	const candidates = [];
-	if (darkerResult) candidates.push({
-		...darkerResult,
-		branch: "darker"
-	});
-	if (lighterResult) candidates.push({
-		...lighterResult,
-		branch: "lighter"
-	});
-	if (candidates.length === 0) return {
-		lightness: preferredLightness,
-		contrast: crPref,
+	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"
 	};
-	candidates.sort((a, b) => b.contrast - a.contrast);
-	return candidates[0];
+	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 } : {}
+	};
 }
 /**
-* 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
-	};
-	if (highPasses) return {
-		lightness: high,
-		contrast: crHigh,
-		met: true
-	};
-	return crLow >= crHigh ? {
-		lightness: low,
-		contrast: crLow,
-		met: false
-	} : {
-		lightness: high,
-		contrast: crHigh,
-		met: false
-	};
-}
-/**
-* 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,
-		met: true
-	};
-	const darkerResult = preferredValue > 0 ? searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
-	const lighterResult = preferredValue < 1 ? searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
-	if (darkerResult) darkerResult.met = darkerResult.contrast >= target;
-	if (lighterResult) lighterResult.met = lighterResult.contrast >= target;
-	const darkerPasses = darkerResult?.met ?? false;
-	const lighterPasses = lighterResult?.met ?? false;
-	if (darkerPasses && lighterPasses) {
-		if (Math.abs(darkerResult.lightness - preferredValue) <= Math.abs(lighterResult.lightness - preferredValue)) return {
-			value: darkerResult.lightness,
-			contrast: darkerResult.contrast,
-			met: true
-		};
-		return {
-			value: lighterResult.lightness,
-			contrast: lighterResult.contrast,
-			met: true
-		};
-	}
-	if (darkerPasses) return {
-		value: darkerResult.lightness,
-		contrast: darkerResult.contrast,
-		met: true
-	};
-	if (lighterPasses) return {
-		value: lighterResult.lightness,
-		contrast: lighterResult.contrast,
+		contrast: scorePref,
 		met: true
 	};
-	const candidates = [];
-	if (darkerResult) candidates.push({
-		...darkerResult,
-		branch: "lower"
-	});
-	if (lighterResult) candidates.push({
-		...lighterResult,
-		branch: "upper"
-	});
-	if (candidates.length === 0) return {
+	const canLower = preferredValue > 0;
+	const canUpper = preferredValue < 1;
+	let initialIsLower;
+	if (canLower && !canUpper) initialIsLower = true;
+	else if (!canLower && canUpper) initialIsLower = false;
+	else if (!canLower && !canUpper) return {
 		value: preferredValue,
-		contrast: crPref,
+		contrast: scorePref,
 		met: false
 	};
-	candidates.sort((a, b) => b.contrast - a.contrast);
+	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: candidates[0].lightness,
-		contrast: candidates[0].contrast,
-		met: candidates[0].met
+		value: solved.pos,
+		contrast: solved.contrast,
+		met: solved.met,
+		...solved.flipped ? { flipped: true } : {}
 	};
 }
 
 //#endregion
-//#region src/glaze.ts
+//#region src/shadow.ts
 /**
-* Glaze — OKHSL-based color theme generator.
+* Shadow color computation.
 *
-* Generates robust light, dark, and high-contrast colors from a hue/saturation
-* seed, preserving contrast for UI pairs via explicit dependencies.
-*/
-let globalConfig = {
-	lightLightness: [10, 100],
-	darkLightness: [15, 95],
-	darkDesaturation: .1,
-	darkCurve: .5,
-	states: {
-		dark: "@dark",
-		highContrast: "@high-contrast"
-	},
-	modes: {
-		dark: true,
-		highContrast: false
-	}
-};
-function pairNormal(p) {
-	return Array.isArray(p) ? p[0] : p;
-}
-function pairHC(p) {
-	return Array.isArray(p) ? p[1] : p;
-}
+* Owns the shadow / mix def predicates, default tuning constants, the
+* tuning merge, and the actual `computeShadow` math (hue blend,
+* saturation cap, lightness clamp, alpha curve). The resolver consumes
+* this module per scheme variant.
+*/
 function isShadowDef(def) {
 	return def.type === "shadow";
 }
@@ -841,15 +1298,14 @@ const DEFAULT_SHADOW_TUNING = {
 	lightnessBounds: [.05, .2],
 	minGapTarget: .05,
 	alphaMax: 1,
-	bgHueBlend: .2,
-	darkShadowCurve: .4
+	bgHueBlend: .2
 };
-function resolveShadowTuning(perColor) {
+function resolveShadowTuning(perColor, globalTuning) {
 	return {
 		...DEFAULT_SHADOW_TUNING,
-		...globalConfig.shadowTuning,
+		...globalTuning,
 		...perColor,
-		lightnessBounds: perColor?.lightnessBounds ?? globalConfig.shadowTuning?.lightnessBounds ?? DEFAULT_SHADOW_TUNING.lightnessBounds
+		lightnessBounds: perColor?.lightnessBounds ?? globalTuning?.lightnessBounds ?? DEFAULT_SHADOW_TUNING.lightnessBounds
 	};
 }
 function circularLerp(a, b, t) {
@@ -890,36 +1346,49 @@ function computeShadow(bg, fg, intensity, tuning) {
 		alpha
 	};
 }
-function validateColorDefs(defs) {
-	const names = new Set(Object.keys(defs));
+
+//#endregion
+//#region src/validation.ts
+/**
+* Color graph validation and topological sort.
+*
+* `validateColorDefs` rejects bad references (missing / shadow-referencing /
+* 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.
+*/
+function validateColorDefs(defs, externalBases) {
+	const localNames = new Set(Object.keys(defs));
+	const allNames = new Set([...localNames, ...externalBases ? externalBases.keys() : []]);
 	for (const [name, def] of Object.entries(defs)) {
 		if (isShadowDef(def)) {
-			if (!names.has(def.bg)) throw new Error(`glaze: shadow "${name}" references non-existent bg "${def.bg}".`);
-			if (isShadowDef(defs[def.bg])) throw new Error(`glaze: shadow "${name}" bg "${def.bg}" references another shadow color.`);
+			if (!allNames.has(def.bg)) throw new Error(`glaze: shadow "${name}" references non-existent bg "${def.bg}".`);
+			if (localNames.has(def.bg) && isShadowDef(defs[def.bg])) throw new Error(`glaze: shadow "${name}" bg "${def.bg}" references another shadow color.`);
 			if (def.fg !== void 0) {
-				if (!names.has(def.fg)) throw new Error(`glaze: shadow "${name}" references non-existent fg "${def.fg}".`);
-				if (isShadowDef(defs[def.fg])) throw new Error(`glaze: shadow "${name}" fg "${def.fg}" references another shadow color.`);
+				if (!allNames.has(def.fg)) throw new Error(`glaze: shadow "${name}" references non-existent fg "${def.fg}".`);
+				if (localNames.has(def.fg) && isShadowDef(defs[def.fg])) throw new Error(`glaze: shadow "${name}" fg "${def.fg}" references another shadow color.`);
 			}
 			continue;
 		}
 		if (isMixDef(def)) {
-			if (!names.has(def.base)) throw new Error(`glaze: mix "${name}" references non-existent base "${def.base}".`);
-			if (!names.has(def.target)) throw new Error(`glaze: mix "${name}" references non-existent target "${def.target}".`);
-			if (isShadowDef(defs[def.base])) throw new Error(`glaze: mix "${name}" base "${def.base}" references a shadow color.`);
-			if (isShadowDef(defs[def.target])) throw new Error(`glaze: mix "${name}" target "${def.target}" references a shadow color.`);
+			if (!allNames.has(def.base)) throw new Error(`glaze: mix "${name}" references non-existent base "${def.base}".`);
+			if (!allNames.has(def.target)) throw new Error(`glaze: mix "${name}" references non-existent target "${def.target}".`);
+			if (localNames.has(def.base) && isShadowDef(defs[def.base])) throw new Error(`glaze: mix "${name}" base "${def.base}" references a shadow color.`);
+			if (localNames.has(def.target) && isShadowDef(defs[def.target])) throw new Error(`glaze: mix "${name}" target "${def.target}" references a shadow color.`);
 			continue;
 		}
 		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.base && !names.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
-		if (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 (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 (!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();
 	function dfs(name) {
+		if (!localNames.has(name)) return;
 		if (inStack.has(name)) throw new Error(`glaze: circular base reference detected involving "${name}".`);
 		if (visited.has(name)) return;
 		inStack.add(name);
@@ -937,7 +1406,7 @@ function validateColorDefs(defs) {
 		inStack.delete(name);
 		visited.add(name);
 	}
-	for (const name of names) dfs(name);
+	for (const name of localNames) dfs(name);
 }
 function topoSort(defs) {
 	const result = [];
@@ -946,6 +1415,7 @@ function topoSort(defs) {
 		if (visited.has(name)) return;
 		visited.add(name);
 		const def = defs[name];
+		if (def === void 0) return;
 		if (isShadowDef(def)) {
 			visit(def.bg);
 			if (def.fg) visit(def.fg);
@@ -961,83 +1431,132 @@ function topoSort(defs) {
 	for (const name of Object.keys(defs)) visit(name);
 	return result;
 }
-function lightnessWindow(isHighContrast, kind) {
-	if (isHighContrast) return [0, 100];
-	return kind === "dark" ? globalConfig.darkLightness : globalConfig.lightLightness;
-}
-function mapLightnessLight(l, mode, isHighContrast) {
-	if (mode === "static") return l;
-	const [lo, hi] = lightnessWindow(isHighContrast, "light");
-	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) {
-	if (mode === "static") return l;
-	const beta = isHighContrast ? pairHC(globalConfig.darkCurve) : pairNormal(globalConfig.darkCurve);
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark");
-	if (mode === "fixed") return l * (darkHi - darkLo) / 100 + darkLo;
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light");
-	const t = (lightHi - (l * (lightHi - lightLo) / 100 + lightLo)) / (lightHi - lightLo);
-	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
-}
-function lightMappedToDark(lightL, isHighContrast) {
-	const beta = isHighContrast ? pairHC(globalConfig.darkCurve) : pairNormal(globalConfig.darkCurve);
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light");
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark");
-	const t = (lightHi - clamp(lightL, lightLo, lightHi)) / (lightHi - lightLo);
-	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
-}
-function mapSaturationDark(s, mode) {
-	if (mode === "static") return s;
-	return s * (1 - globalConfig.darkDesaturation);
-}
-function schemeLightnessRange(isDark, mode, isHighContrast) {
-	if (mode === "static") return [0, 1];
-	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light");
-	return [lo / 100, hi / 100];
+
+//#endregion
+//#region src/warnings.ts
+/**
+* Contrast-warning dispatcher.
+*
+* Tokens memoize their resolution, but a long-lived process (e.g. a dev
+* server with HMR) can re-resolve the same theme many times. The cache
+* here dedupes warnings within a session with a soft cap to keep noise
+* bounded.
+*/
+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 overshoots to absorb rounding noise, so an actual
+* value within ~2x that overshoot is effectively a pass.
+*/
+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 metricLabel(c) {
+	return c.metric === "apca" ? `APCA Lc ${c.target.toFixed(1)}` : `WCAG ${c.target.toFixed(2)}`;
+}
+function dedupe(key) {
+	if (contrastWarnCache.has(key)) return true;
+	if (contrastWarnCache.size >= CONTRAST_WARN_CACHE_LIMIT) contrastWarnCache.clear();
+	contrastWarnCache.add(key);
+	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.`);
 }
-function clamp(v, min, max) {
-	return Math.max(min, Math.min(max, v));
+/**
+* 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
+//#region src/resolver.ts
 /**
-* Parse a value that can be absolute (number) or relative (signed string).
-* Returns the numeric value and whether it's relative.
+* Color resolution engine.
+*
+* Runs the four-pass solver (light → light-HC → dark → dark-HC) that
+* turns a `ColorMap` into a fully resolved `ResolvedColor` per name.
+* 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.
 */
-function parseRelativeOrAbsolute(value) {
-	if (typeof value === "number") return {
-		value,
-		relative: false
+function getSchemeVariant(color, isDark, isHighContrast) {
+	if (isDark && isHighContrast) return color.darkContrast;
+	if (isDark) return color.dark;
+	if (isHighContrast) return color.lightContrast;
+	return color.light;
+}
+/** Edge adapter: resolved variant (`t`) → OKHSL-lightness variant. */
+function toOkhslVariant(v) {
+	const c = variantToOkhsl(v);
+	return {
+		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 {
-		value: parseFloat(value),
-		relative: true
+		h: c.h,
+		s: c.s,
+		t: c.t,
+		alpha: v.alpha
 	};
 }
-/**
-* Compute the effective hue for a color, given the theme seed hue
-* and an optional per-color hue override.
-*/
-function resolveEffectiveHue(seedHue, defHue) {
-	if (defHue === void 0) return seedHue;
-	const parsed = parseRelativeOrAbsolute(defHue);
-	if (parsed.relative) return ((seedHue + parsed.value) % 360 + 360) % 360;
-	return (parsed.value % 360 + 360) % 360;
+function resolveContrastSpec(spec, isHighContrast) {
+	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast);
 }
 /**
-* Check whether a lightness value represents an absolute root definition
-* (i.e. a number, not a relative string).
+* 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 isAbsoluteLightness(lightness) {
-	if (lightness === void 0) return false;
-	return typeof (Array.isArray(lightness) ? lightness[0] : lightness) === "number";
-}
-function resolveRootColor(_name, def, _ctx, isHighContrast) {
-	const rawL = def.lightness;
+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 {
-		lightL: clamp(parseRelativeOrAbsolute(isHighContrast ? pairHC(rawL) : pairNormal(rawL)).value, 0, 100),
+		authorTone: clamp(parseToneValue(isHighContrast ? pairHC(rawT) : pairNormal(rawT)).value, 0, 100),
 		satFactor: clamp(def.saturation ?? 1, 0, 1)
 	};
 }
@@ -1047,104 +1566,90 @@ 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);
-			else preferredL = clamp(baseL + delta, 0, 100);
-		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode, isHighContrast);
-		else preferredL = mapLightnessLight(parsed.value, mode, isHighContrast);
+		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 effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode) : satFactor * ctx.saturation / 100;
-		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
-		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast);
+		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast);
+		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config) : satFactor * ctx.saturation / 100;
+		const baseOkhsl = toOkhslVariant(baseVariant);
+		const baseLinearRgb = okhslToLinearSrgb(baseOkhsl.h, baseOkhsl.s, baseOkhsl.l);
+		const toneRange = schemeToneRange(isDark, mode, isHighContrast, ctx.config);
+		let initialDirection;
+		if (preferredTone < baseTone) initialDirection = "darker";
+		else if (preferredTone > baseTone) initialDirection = "lighter";
+		const result = findToneForContrast({
+			hue: effectiveHue,
+			saturation: effectiveSat,
+			preferredTone: clamp(preferredTone / 100, toneRange[0], toneRange[1]),
+			baseLinearRgb,
+			contrast: resolvedContrast,
+			toneRange: [0, 1],
+			initialDirection,
+			flip,
+			saturationTaper: ctx.config.saturationTaper
+		});
+		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, resolvedContrast, result.contrast);
 		return {
-			l: findLightnessForContrast({
-				hue: effectiveHue,
-				saturation: effectiveSat,
-				preferredLightness: clamp(preferredL / 100, windowRange[0], windowRange[1]),
-				baseLinearRgb,
-				contrast: minCr,
-				lightnessRange: [0, 1]
-			}).lightness * 100,
+			tone: result.tone * 100,
 			satFactor
 		};
 	}
 	return {
-		l: clamp(preferredL, 0, 100),
+		tone: clamp(preferredTone, 0, 100),
 		satFactor
 	};
 }
-function getSchemeVariant(color, isDark, isHighContrast) {
-	if (isDark && isHighContrast) return color.darkContrast;
-	if (isDark) return color.dark;
-	if (isHighContrast) return color.lightContrast;
-	return color.light;
-}
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	if (isShadowDef(def)) return resolveShadowForScheme(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);
-		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
-	} else if (isDark && !isRoot) {
-		finalL = lightL;
-		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
-	} else if (isRoot) {
-		finalL = mapLightnessLight(lightL, mode, isHighContrast);
-		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);
-	const result = computeShadow(bgVariant, fgVariant, intensity, tuning);
-	if (isDark && tuning.darkShadowCurve < 1 && result.alpha > 0) {
-		const normalized = result.alpha / tuning.alphaMax;
-		const exponent = 1 / tuning.darkShadowCurve;
-		result.alpha = tuning.alphaMax * Math.pow(normalized, exponent);
-	}
-	return result;
+	const tuning = resolveShadowTuning(def.tuning, ctx.config.shadowTuning);
+	return toToneVariant(computeShadow(bgVariant, fgVariant, intensity, tuning));
 }
-function variantToLinearRgb(v) {
+function okhslVariantToLinearRgb(v) {
 	return okhslToLinearSrgb(v.h, v.s, v.l);
 }
 /**
@@ -1168,77 +1673,81 @@ 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,
-			luminanceAtValue: luminanceAt
+			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 resolveAllColors(hue, saturation, defs) {
-	validateColorDefs(defs);
-	const order = topoSort(defs);
-	const ctx = {
-		hue,
-		saturation,
-		defs,
-		resolved: /* @__PURE__ */ new Map()
-	};
-	function defMode(def) {
-		if (isShadowDef(def) || isMixDef(def)) return void 0;
-		return def.mode ?? "auto";
-	}
-	const lightMap = /* @__PURE__ */ new Map();
+function defMode(def) {
+	if (isShadowDef(def) || isMixDef(def)) return void 0;
+	return def.mode ?? "auto";
+}
+/**
+* Run a single resolve pass over all local names. Pass 1 lazily creates
+* each `ResolvedColor` (all four slots seeded with the just-resolved
+* variant) the first time it sees a name; later passes update the
+* `target` slot on the existing record.
+*/
+function runPass(order, defs, ctx, isDark, isHighContrast, target) {
+	const out = /* @__PURE__ */ new Map();
 	for (const name of order) {
-		const variant = resolveColorForScheme(name, defs[name], ctx, false, false);
-		lightMap.set(name, variant);
-		ctx.resolved.set(name, {
+		const variant = resolveColorForScheme(name, defs[name], ctx, isDark, isHighContrast);
+		out.set(name, variant);
+		const existing = ctx.resolved.get(name);
+		if (existing) ctx.resolved.set(name, {
+			...existing,
+			[target]: variant
+		});
+		else ctx.resolved.set(name, {
 			name,
 			light: variant,
 			dark: variant,
@@ -1247,49 +1756,87 @@ function resolveAllColors(hue, saturation, defs) {
 			mode: defMode(defs[name])
 		});
 	}
-	const lightHCMap = /* @__PURE__ */ new Map();
-	for (const name of order) ctx.resolved.set(name, {
-		...ctx.resolved.get(name),
-		lightContrast: lightMap.get(name)
-	});
-	for (const name of order) {
-		const variant = resolveColorForScheme(name, defs[name], ctx, false, true);
-		lightHCMap.set(name, variant);
-		ctx.resolved.set(name, {
-			...ctx.resolved.get(name),
-			lightContrast: variant
-		});
-	}
-	const darkMap = /* @__PURE__ */ new Map();
-	for (const name of order) ctx.resolved.set(name, {
-		name,
-		light: lightMap.get(name),
-		dark: lightMap.get(name),
-		lightContrast: lightHCMap.get(name),
-		darkContrast: lightHCMap.get(name),
-		mode: defMode(defs[name])
-	});
+	return out;
+}
+/**
+* Re-seed a single variant slot with a previously-resolved map so the
+* upcoming pass reads sensible fallbacks via `getSchemeVariant`.
+*/
+function seedField(order, ctx, field, source) {
 	for (const name of order) {
-		const variant = resolveColorForScheme(name, defs[name], ctx, true, false);
-		darkMap.set(name, variant);
+		const existing = ctx.resolved.get(name);
 		ctx.resolved.set(name, {
-			...ctx.resolved.get(name),
-			dark: variant
+			...existing,
+			[field]: source.get(name)
 		});
 	}
-	const darkHCMap = /* @__PURE__ */ new Map();
-	for (const name of order) ctx.resolved.set(name, {
-		...ctx.resolved.get(name),
-		darkContrast: darkMap.get(name)
-	});
+}
+/**
+* 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 variant = resolveColorForScheme(name, defs[name], ctx, true, true);
-		darkHCMap.set(name, variant);
-		ctx.resolved.set(name, {
-			...ctx.resolved.get(name),
-			darkContrast: variant
-		});
+		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);
+	const ctx = {
+		hue,
+		saturation,
+		defs,
+		resolved: /* @__PURE__ */ new Map(),
+		config
+	};
+	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
+	const lightMap = runPass(order, defs, ctx, false, false, "light");
+	seedField(order, ctx, "lightContrast", lightMap);
+	const lightHCMap = runPass(order, defs, ctx, false, true, "lightContrast");
+	seedField(order, ctx, "dark", lightMap);
+	seedField(order, ctx, "darkContrast", lightHCMap);
+	const darkMap = runPass(order, defs, ctx, true, false, "dark");
+	seedField(order, ctx, "darkContrast", darkMap);
+	const darkHCMap = runPass(order, defs, ctx, true, true, "darkContrast");
 	const result = /* @__PURE__ */ new Map();
 	for (const name of order) result.set(name, {
 		name,
@@ -1299,8 +1846,22 @@ function resolveAllColors(hue, saturation, defs) {
 		darkContrast: darkHCMap.get(name),
 		mode: defMode(defs[name])
 	});
+	verifyContrastDrift(order, defs, result);
 	return result;
 }
+
+//#endregion
+//#region src/formatters.ts
+/**
+* Output formatting for resolved color maps.
+*
+* Owns the CSS-string formatter dispatch table (`okhsl` / `rgb` / `hsl` /
+* `oklch`) and the four token-map shapes Glaze emits:
+* - `buildTokenMap` — Tasty style-to-state bindings (`#name` keys, state aliases).
+* - `buildFlatTokenMap` — `{ light, dark, ... }` per-variant maps.
+* - `buildJsonMap` — `{ name: { light, dark, ... } }` per-color JSON.
+* - `buildCssMap` — CSS custom property declaration strings per variant.
+*/
 const formatters = {
 	okhsl: formatOkhsl,
 	rgb: formatRgb,
@@ -1311,15 +1872,17 @@ 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)})`;
 }
 function resolveModes(override) {
+	const cfg = getConfig();
 	return {
-		dark: override?.dark ?? globalConfig.modes.dark,
-		highContrast: override?.highContrast ?? globalConfig.modes.highContrast
+		dark: override?.dark ?? cfg.modes.dark,
+		highContrast: override?.highContrast ?? cfg.modes.highContrast
 	};
 }
 function buildTokenMap(resolved, prefix, states, modes, format = "okhsl") {
@@ -1380,97 +1943,606 @@ function buildCssMap(resolved, prefix, suffix, format) {
 		darkContrast: lines.darkContrast.join("\n")
 	};
 }
-function createTheme(hue, saturation, initialColors) {
-	let colorDefs = initialColors ? { ...initialColors } : {};
+
+//#endregion
+//#region src/color-token.ts
+/**
+* Standalone single-color tokens (`glaze.color()` / `glaze.colorFrom()`).
+*
+* Owns the value-shorthand parser (hex, `rgb()` / `hsl()` / `okhsl()` /
+* `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
+* tokens. The snapshot is built eagerly in
+* `buildValueFormConfigOverride()` / `buildStructuredConfigOverride()`.
+* The token's resolved variants are then memoized on first
+* `.resolve()` / `.token()` / ... call.
+*/
+/** 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 tone / contrast. */
+const STANDALONE_SEED = "seed";
+/** Internal name of an externally-resolved `GlazeColorToken` injected as a base reference. */
+const STANDALONE_BASE = "externalBase";
+/** Reserved internal names that user-supplied `name` must not collide with. */
+const RESERVED_STANDALONE_NAMES = new Set([
+	STANDALONE_VALUE,
+	STANDALONE_SEED,
+	STANDALONE_BASE
+]);
+/**
+* Build the per-token effective config override for a value-form color.
+*
+* 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 {
-		get hue() {
-			return hue;
-		},
-		get saturation() {
-			return saturation;
-		},
-		colors(defs) {
-			colorDefs = {
-				...colorDefs,
-				...defs
-			};
-		},
-		color(name, def) {
-			if (def === void 0) return colorDefs[name];
-			colorDefs[name] = def;
-		},
-		remove(names) {
-			const list = Array.isArray(names) ? names : [names];
-			for (const name of list) delete colorDefs[name];
-		},
-		has(name) {
-			return name in colorDefs;
-		},
-		list() {
-			return Object.keys(colorDefs);
-		},
-		reset() {
-			colorDefs = {};
-		},
-		export() {
-			return {
-				hue,
-				saturation,
-				colors: { ...colorDefs }
-			};
-		},
-		extend(options) {
-			const newHue = options.hue ?? hue;
-			const newSat = options.saturation ?? saturation;
-			const inheritedColors = {};
-			for (const [name, def] of Object.entries(colorDefs)) if (def.inherit !== false) inheritedColors[name] = def;
-			return createTheme(newHue, newSat, options.colors ? {
-				...inheritedColors,
-				...options.colors
-			} : { ...inheritedColors });
-		},
-		resolve() {
-			return resolveAllColors(hue, saturation, colorDefs);
-		},
-		tokens(options) {
-			return buildFlatTokenMap(resolveAllColors(hue, saturation, colorDefs), "", resolveModes(options?.modes), options?.format);
-		},
-		tasty(options) {
-			return buildTokenMap(resolveAllColors(hue, saturation, colorDefs), "", {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
-			}, resolveModes(options?.modes), options?.format);
-		},
-		json(options) {
-			return buildJsonMap(resolveAllColors(hue, saturation, colorDefs), resolveModes(options?.modes), options?.format);
-		},
-		css(options) {
-			return buildCssMap(resolveAllColors(hue, saturation, colorDefs), "", options?.suffix ?? "-color", options?.format ?? "rgb");
-		}
+		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : false,
+		darkTone: userOverride?.darkTone !== void 0 ? userOverride.darkTone : cfg.darkTone,
+		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
+		saturationTaper: userOverride?.saturationTaper ?? cfg.saturationTaper,
+		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
+		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
 	};
 }
-function resolvePrefix(options, themeName, defaultPrefix = false) {
-	const prefix = options?.prefix ?? defaultPrefix;
-	if (prefix === true) return `${themeName}-`;
-	if (typeof prefix === "object" && prefix !== null) return prefix[themeName] ?? `${themeName}-`;
-	return "";
+/**
+* Build the per-token effective config override for a structured-form color.
+*
+* Both light and dark windows snapshot from global at create time.
+* User override fields win.
+*/
+function buildStructuredConfigOverride(userOverride) {
+	const cfg = getConfig();
+	return {
+		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : cfg.lightTone,
+		darkTone: userOverride?.darkTone !== void 0 ? userOverride.darkTone : cfg.darkTone,
+		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
+		saturationTaper: userOverride?.saturationTaper ?? cfg.saturationTaper,
+		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
+		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
+	};
 }
-function validatePrimaryTheme(primary, themes) {
-	if (primary !== void 0 && !(primary in themes)) {
-		const available = Object.keys(themes).join(", ");
-		throw new Error(`glaze: primary theme "${primary}" not found in palette. Available: ${available}.`);
-	}
+/**
+* Build the `GlazeConfigResolved` to pass to `resolveAllColors` from a
+* snapshot override. Uses `defaultConfig()` as the base so all required
+* fields are present; the snapshot fields win.
+*/
+function resolvedConfigFromOverride(override) {
+	return mergeConfig(defaultConfig(), override);
 }
 /**
-* Resolve the effective primary for an export call.
-* `false` disables, a string overrides, `undefined` inherits from palette.
+* Matches the CSS color functions Glaze itself emits (`rgb()`, `hsl()`,
+* `okhsl()`, `oklch()`) plus their legacy alpha aliases (`rgba()`, `hsla()`).
+*
+* Only bare numeric components are supported. Named colors (`red`),
+* relative-color syntax (`from <color> ...`), and angle units other
+* than bare degrees (`deg` is the only suffix tolerated by `parseFloat`)
+* are out of scope.
 */
-function resolveEffectivePrimary(exportPrimary, palettePrimary) {
-	if (exportPrimary === false) return void 0;
-	return exportPrimary ?? palettePrimary;
+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);
 }
 /**
-* Filter a resolved color map, skipping keys already in `seen`.
+* Split the body of a CSS color function into its components and detect
+* whether an alpha channel was present.
+*
+* Handles both modern slash syntax (`R G B / A` or `R, G, B / A`) and
+* legacy comma syntax (`R, G, B, A`). The alpha value itself is discarded
+* by the caller — standalone Glaze colors have no opacity field.
+*/
+function splitColorBody(body) {
+	const slashIdx = body.indexOf("/");
+	if (slashIdx !== -1) return {
+		components: body.slice(0, slashIdx).trim().split(/[\s,]+/).filter(Boolean),
+		hadAlpha: body.slice(slashIdx + 1).trim().length > 0
+	};
+	const components = body.split(/[\s,]+/).filter(Boolean);
+	if (components.length === 4) {
+		components.pop();
+		return {
+			components,
+			hadAlpha: true
+		};
+	}
+	return {
+		components,
+		hadAlpha: false
+	};
+}
+function warnDroppedAlpha(input) {
+	console.warn(`glaze: alpha component dropped from "${input}" (standalone color has no opacity field).`);
+}
+function parseColorString(input) {
+	if (input.startsWith("#")) {
+		const parsed = parseHexAlpha(input);
+		if (!parsed) throw new Error(`glaze: invalid hex color "${input}".`);
+		if (parsed.alpha !== void 0) warnDroppedAlpha(input);
+		const [h, s, l] = srgbToOkhsl(parsed.rgb);
+		return {
+			h,
+			s,
+			l
+		};
+	}
+	const m = input.match(COLOR_FN_RE);
+	if (!m) throw new Error(`glaze: unsupported color string "${input}".`);
+	const fn = m[1].toLowerCase();
+	const { components, hadAlpha } = splitColorBody(m[2].trim());
+	if (hadAlpha) warnDroppedAlpha(input);
+	if (components.length !== 3) throw new Error(`glaze: expected 3 components in "${input}".`);
+	switch (fn) {
+		case "rgb":
+		case "rgba": {
+			const [h, s, l] = srgbToOkhsl([
+				parseNumberOrPercent(components[0], 255) / 255,
+				parseNumberOrPercent(components[1], 255) / 255,
+				parseNumberOrPercent(components[2], 255) / 255
+			]);
+			return {
+				h,
+				s,
+				l
+			};
+		}
+		case "hsl":
+		case "hsla": {
+			const [oh, os, ol] = srgbToOkhsl(hslToSrgb(parseFloat(components[0]), parseNumberOrPercent(components[1], 1), parseNumberOrPercent(components[2], 1)));
+			return {
+				h: oh,
+				s: os,
+				l: ol
+			};
+		}
+		case "okhsl": return {
+			h: parseFloat(components[0]),
+			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);
+			const hRad = parseFloat(components[2]) * Math.PI / 180;
+			const [h, s, l] = oklabToOkhsl([
+				L,
+				C * Math.cos(hRad),
+				C * Math.sin(hRad)
+			]);
+			return {
+				h,
+				s,
+				l
+			};
+		}
+	}
+	throw new Error(`glaze: unsupported color function "${fn}".`);
+}
+/**
+* Validate a user-supplied `OkhslColor`. Catches the common 0-100 vs 0-1
+* confusion (the structured form uses 0-100, OKHSL objects use 0-1).
+*/
+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, tone } (which uses 0–100)?");
+}
+/** Validate a user-supplied `{ r, g, b }` object in 0–255. */
+function validateRgbColor(value) {
+	for (const key of [
+		"r",
+		"g",
+		"b"
+	]) {
+		const n = value[key];
+		if (!Number.isFinite(n) || n < 0 || n > 255) throw new Error(`glaze.color: RgbColor ${key} must be a finite number in 0–255 (got ${n}).`);
+	}
+}
+/** Validate a user-supplied `{ l, c, h }` OKLCh object. */
+function validateOklchColor(value) {
+	const { l, c, h } = value;
+	if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h)) throw new Error("glaze.color: OklchColor l/c/h must be finite numbers.");
+	if (l > 1.5 || c > 1.5) throw new Error("glaze.color: OklchColor l/c must be in 0–1 range (matching oklch() strings).");
+}
+function oklchComponentsToOkhsl(l, c, hDeg) {
+	const hRad = hDeg * Math.PI / 180;
+	const [h, s, outL] = oklabToOkhsl([
+		l,
+		c * Math.cos(hRad),
+		c * Math.sin(hRad)
+	]);
+	return {
+		h,
+		s,
+		l: outL
+	};
+}
+function isRgbColorObject(value) {
+	return "r" in value && "g" in value && "b" in 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`.
+*/
+function validateStandaloneOpacity(value) {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`glaze.color: opacity must be a finite number in 0–1 (got ${value}).`);
+}
+/**
+* Validate a structured `GlazeColorInput`. Range-checks the `hue` /
+* `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
+* validation lives in one place.
+*/
+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 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.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}).`);
+	}
+	if (input.opacity !== void 0) validateStandaloneOpacity(input.opacity);
+}
+/**
+* Validate a user-supplied `name` override. Rejects empty / whitespace-only
+* strings and names colliding with `glaze`'s reserved internal sentinels.
+*/
+function validateStandaloneName(name) {
+	if (typeof name !== "string" || name.trim() === "") throw new Error("glaze.color: name must be a non-empty string. Omit `name` if you do not want to set a debug label.");
+	if (RESERVED_STANDALONE_NAMES.has(name)) {
+		const reserved = [...RESERVED_STANDALONE_NAMES].map((n) => `"${n}"`).join(", ");
+		throw new Error(`glaze.color: name "${name}" is reserved (used internally). Reserved names are: ${reserved}. Pick a different name.`);
+	}
+}
+/**
+* Extract an OKHSL color from any `GlazeColorValue` form. Also used by
+* `glaze.shadow()` so all shadow inputs (hex, color functions, OKHSL,
+* literal objects) go through one parser.
+*/
+function extractOkhslFromValue(value) {
+	if (typeof value === "string") return parseColorString(value);
+	if (Array.isArray(value)) throw new Error("glaze.color: RGB tuple [r, g, b] is no longer supported — use { r, g, b } instead.");
+	if (isRgbColorObject(value)) {
+		validateRgbColor(value);
+		const [h, s, l] = srgbToOkhsl([
+			value.r / 255,
+			value.g / 255,
+			value.b / 255
+		]);
+		return {
+			h,
+			s,
+			l
+		};
+	}
+	if (isOklchColorObject(value)) {
+		validateOklchColor(value);
+		return oklchComponentsToOkhsl(value.l, value.c, value.h);
+	}
+	if (isOkhstColorObject(value)) {
+		validateOkhstColor(value);
+		return okhstToOkhsl(value);
+	}
+	validateOkhslColor(value);
+	return value;
+}
+/**
+* Build the `ColorMap` for a value-shorthand `glaze.color()` call.
+*
+* The user-facing color (`STANDALONE_VALUE`) defaults to `mode: 'auto'`
+* across every value-shorthand form.
+*
+* 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.
+*/
+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 toneOption = options?.tone;
+	const hasExternalBase = options?.base !== void 0;
+	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,
+		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
+	};
+	const defs = { [primary]: valueDef };
+	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
+		hue: main.h,
+		saturation: 1,
+		tone: seedTone,
+		mode: "static"
+	};
+	return {
+		seedHue,
+		seedSaturation,
+		defs,
+		primary
+	};
+}
+function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, baseToken, exportData) {
+	let cached;
+	const resolveOnce = () => {
+		if (cached) return cached;
+		cached = resolveAllColors(seedHue, seedSaturation, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
+		return cached;
+	};
+	const resolveStates = (options) => {
+		const cfg = getConfig();
+		return {
+			dark: options?.states?.dark ?? cfg.states.dark,
+			highContrast: options?.states?.highContrast ?? cfg.states.highContrast
+		};
+	};
+	const tokenLike = (options) => {
+		return buildTokenMap(resolveOnce(), "", resolveStates(options), resolveModes(options?.modes), options?.format)[`#${primary}`];
+	};
+	return {
+		resolve() {
+			return resolveOnce().get(primary);
+		},
+		token: tokenLike,
+		tasty: tokenLike,
+		json(options) {
+			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), options?.format)[primary];
+		},
+		css(options) {
+			return buildCssMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.suffix ?? "-color", options.format ?? "rgb");
+		},
+		export: exportData
+	};
+}
+/**
+* When a value/`from` color links to a base that was created via 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) {
+	if (!base) return void 0;
+	const exp = base.export();
+	if (exp.form !== "structured") return base;
+	const linkingConfig = {
+		...exp.config ?? {},
+		lightTone: false
+	};
+	return colorFromExport({
+		...exp,
+		config: linkingConfig
+	});
+}
+/**
+* Resolve `base` (which may be a token reference or a raw color value)
+* into a `GlazeColorToken`. Raw values are auto-wrapped via
+* `createColorTokenFromValue` so they pick up the same auto-invert
+* defaults as an explicit wrap. Returns `undefined` when no base is provided.
+*/
+function resolveBaseToken(base) {
+	if (base === void 0) return void 0;
+	if (isGlazeColorToken(base)) return base;
+	return createColorTokenFromValue(base, void 0, void 0);
+}
+/**
+* Discriminate a `GlazeColorToken` from a raw `GlazeColorValue`.
+*/
+function isGlazeColorToken(candidate) {
+	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "resolve" in candidate && typeof candidate.resolve === "function";
+}
+function createColorToken(input, configOverride) {
+	validateStructuredInput(input);
+	const userName = input.name;
+	if (userName !== void 0) validateStandaloneName(userName);
+	const primary = userName ?? STANDALONE_VALUE;
+	const baseToken = resolveBaseToken(input.base);
+	const hasExternalBase = baseToken !== void 0;
+	const needsSeedAnchor = !hasExternalBase && input.contrast !== void 0;
+	const defs = { [primary]: {
+		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) {
+		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 = () => ({
+		form: "structured",
+		input: buildStructuredInputExport(input),
+		config: effectiveConfigOverride
+	});
+	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveConfig, baseToken, exportData);
+}
+function createColorTokenFromValue(value, options, configOverride) {
+	const main = extractOkhslFromValue(value);
+	const linkingBase = toLinkingBase(resolveBaseToken(options?.base));
+	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options);
+	const effectiveConfigOverride = buildValueFormConfigOverride(configOverride);
+	const effectiveConfig = resolvedConfigFromOverride(effectiveConfigOverride);
+	const exportData = () => ({
+		form: "value",
+		input: value,
+		...options !== void 0 ? { overrides: buildOverridesExport(options) } : {},
+		config: effectiveConfigOverride
+	});
+	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, linkingBase, exportData);
+}
+/**
+* Build a JSON-safe snapshot of `GlazeColorOverrides`. `base` is
+* recursively serialized when it was originally a token; raw values are
+* preserved as-is so `glaze.colorFrom(...)` round-trips them.
+*/
+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.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;
+	if (options.base !== void 0) out.base = isGlazeColorToken(options.base) ? options.base.export() : options.base;
+	return out;
+}
+function buildStructuredInputExport(input) {
+	const out = {
+		hue: input.hue,
+		saturation: input.saturation,
+		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;
+	if (input.base !== void 0) out.base = isGlazeColorToken(input.base) ? input.base.export() : input.base;
+	return out;
+}
+/**
+* Discriminate a `GlazeColorTokenExport` from a raw `GlazeColorValue`.
+*/
+function isExportedToken(candidate) {
+	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "form" in candidate && (candidate.form === "value" || candidate.form === "structured");
+}
+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.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;
+	if (data.base !== void 0) out.base = isExportedToken(data.base) ? colorFromExport(data.base) : data.base;
+	return out;
+}
+function rehydrateStructuredInput(data) {
+	const out = {
+		hue: data.hue,
+		saturation: data.saturation,
+		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;
+	if (data.base !== void 0) out.base = isExportedToken(data.base) ? colorFromExport(data.base) : data.base;
+	return out;
+}
+/**
+* Rehydrate a token from its `.export()` snapshot. Recursively rebuilds
+* any base dependency. Inverse of `GlazeColorToken.export()`.
+*
+* The stored `config` field contains the full effective config override
+* snapshotted at creation time, so the rehydrated token is deterministic
+* regardless of subsequent `glaze.configure()` calls.
+*/
+function colorFromExport(data) {
+	if (data === null || typeof data !== "object") throw new Error(`glaze.colorFrom: expected an object from token.export(), got ${data === null ? "null" : typeof data}.`);
+	if (data.form !== "value" && data.form !== "structured") throw new Error(`glaze.colorFrom: invalid "form" field — expected "value" or "structured" (got ${JSON.stringify(data.form)}).`);
+	if (data.input === void 0) throw new Error(`glaze.colorFrom: missing "input" field — expected the original ${data.form === "value" ? "GlazeColorValue" : "GlazeColorInput"}.`);
+	if (data.form === "value") {
+		const value = data.input;
+		return createColorTokenFromValue(value, data.overrides ? rehydrateOverrides(data.overrides) : void 0, data.config);
+	}
+	return createColorToken(rehydrateStructuredInput(data.input), data.config);
+}
+
+//#endregion
+//#region src/palette.ts
+/**
+* Palette factory.
+*
+* Composes multiple themes into a single token namespace with optional
+* theme-name prefixes and a "primary theme" that also surfaces an
+* unprefixed copy of its tokens. All four export methods (`tokens` /
+* `tasty` / `json` / `css`) share a `buildPaletteOutput` driver that
+* handles validation, per-theme iteration, prefix resolution, collision
+* filtering, and primary duplication.
+*/
+function resolvePrefix(options, themeName, defaultPrefix = false) {
+	const prefix = options?.prefix ?? defaultPrefix;
+	if (prefix === true) return `${themeName}-`;
+	if (typeof prefix === "object" && prefix !== null) return prefix[themeName] ?? `${themeName}-`;
+	return "";
+}
+function validatePrimaryTheme(primary, themes) {
+	if (primary !== void 0 && !(primary in themes)) {
+		const available = Object.keys(themes).join(", ");
+		throw new Error(`glaze: primary theme "${primary}" not found in palette. Available: ${available}.`);
+	}
+}
+/**
+* Resolve the effective primary for an export call.
+* `false` disables, a string overrides, `undefined` inherits from palette.
+*/
+function resolveEffectivePrimary(exportPrimary, palettePrimary) {
+	if (exportPrimary === false) return void 0;
+	return exportPrimary ?? palettePrimary;
+}
+/**
+* Filter a resolved color map, skipping keys already in `seen`.
 * Warns on collision and keeps the first-written value (first-write-wins).
 * Returns a new map containing only non-colliding entries.
 */
@@ -1488,51 +2560,43 @@ function filterCollisions(resolved, prefix, seen, themeName, isPrimary) {
 	}
 	return filtered;
 }
+/**
+* Shared per-theme driver for `tokens` / `tasty` / `css`. `json` skips
+* this because it doesn't do collision filtering or primary duplication.
+*/
+function buildPaletteOutput(themes, paletteOptions, options, buildOne, merge, empty) {
+	const effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
+	if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
+	const acc = empty();
+	const seen = /* @__PURE__ */ new Map();
+	for (const [themeName, theme] of Object.entries(themes)) {
+		const resolved = theme.resolve();
+		const prefix = resolvePrefix(options, themeName, true);
+		merge(acc, buildOne(filterCollisions(resolved, prefix, seen, themeName), prefix));
+		if (themeName === effectivePrimary) merge(acc, buildOne(filterCollisions(resolved, "", seen, themeName, true), ""));
+	}
+	return acc;
+}
 function createPalette(themes, paletteOptions) {
 	validatePrimaryTheme(paletteOptions?.primary, themes);
 	return {
 		tokens(options) {
-			const effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
-			if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
 			const modes = resolveModes(options?.modes);
-			const allTokens = {};
-			const seen = /* @__PURE__ */ new Map();
-			for (const [themeName, theme] of Object.entries(themes)) {
-				const resolved = theme.resolve();
-				const prefix = resolvePrefix(options, themeName, true);
-				const tokens = buildFlatTokenMap(filterCollisions(resolved, prefix, seen, themeName), prefix, modes, options?.format);
-				for (const variant of Object.keys(tokens)) {
-					if (!allTokens[variant]) allTokens[variant] = {};
-					Object.assign(allTokens[variant], tokens[variant]);
+			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix) => buildFlatTokenMap(filtered, prefix, modes, options?.format), (acc, part) => {
+				for (const variant of Object.keys(part)) {
+					if (!acc[variant]) acc[variant] = {};
+					Object.assign(acc[variant], part[variant]);
 				}
-				if (themeName === effectivePrimary) {
-					const unprefixed = buildFlatTokenMap(filterCollisions(resolved, "", seen, themeName, true), "", modes, options?.format);
-					for (const variant of Object.keys(unprefixed)) Object.assign(allTokens[variant], unprefixed[variant]);
-				}
-			}
-			return allTokens;
+			}, () => ({}));
 		},
 		tasty(options) {
-			const effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
-			if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
+			const cfg = getConfig();
 			const states = {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
+				dark: options?.states?.dark ?? cfg.states.dark,
+				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
 			};
 			const modes = resolveModes(options?.modes);
-			const allTokens = {};
-			const seen = /* @__PURE__ */ new Map();
-			for (const [themeName, theme] of Object.entries(themes)) {
-				const resolved = theme.resolve();
-				const prefix = resolvePrefix(options, themeName, true);
-				const tokens = buildTokenMap(filterCollisions(resolved, prefix, seen, themeName), prefix, states, modes, options?.format);
-				Object.assign(allTokens, tokens);
-				if (themeName === effectivePrimary) {
-					const unprefixed = buildTokenMap(filterCollisions(resolved, "", seen, themeName, true), "", states, modes, options?.format);
-					Object.assign(allTokens, unprefixed);
-				}
-			}
-			return allTokens;
+			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix) => buildTokenMap(filtered, prefix, states, modes, options?.format), (acc, part) => Object.assign(acc, part), () => ({}));
 		},
 		json(options) {
 			const modes = resolveModes(options?.modes);
@@ -1541,132 +2605,262 @@ function createPalette(themes, paletteOptions) {
 			return result;
 		},
 		css(options) {
-			const effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
-			if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
 			const suffix = options?.suffix ?? "-color";
 			const format = options?.format ?? "rgb";
-			const allLines = {
-				light: [],
-				dark: [],
-				lightContrast: [],
-				darkContrast: []
-			};
-			const seen = /* @__PURE__ */ new Map();
-			for (const [themeName, theme] of Object.entries(themes)) {
-				const resolved = theme.resolve();
-				const prefix = resolvePrefix(options, themeName, true);
-				const css = buildCssMap(filterCollisions(resolved, prefix, seen, themeName), prefix, suffix, format);
+			const lines = buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix) => buildCssMap(filtered, prefix, suffix, format), (acc, part) => {
 				for (const key of [
 					"light",
 					"dark",
 					"lightContrast",
 					"darkContrast"
-				]) if (css[key]) allLines[key].push(css[key]);
-				if (themeName === effectivePrimary) {
-					const unprefixed = buildCssMap(filterCollisions(resolved, "", seen, themeName, true), "", suffix, format);
-					for (const key of [
-						"light",
-						"dark",
-						"lightContrast",
-						"darkContrast"
-					]) if (unprefixed[key]) allLines[key].push(unprefixed[key]);
-				}
-			}
+				]) if (part[key]) acc[key].push(part[key]);
+			}, () => ({
+				light: [],
+				dark: [],
+				lightContrast: [],
+				darkContrast: []
+			}));
 			return {
-				light: allLines.light.join("\n"),
-				dark: allLines.dark.join("\n"),
-				lightContrast: allLines.lightContrast.join("\n"),
-				darkContrast: allLines.darkContrast.join("\n")
+				light: lines.light.join("\n"),
+				dark: lines.dark.join("\n"),
+				lightContrast: lines.lightContrast.join("\n"),
+				darkContrast: lines.darkContrast.join("\n")
 			};
 		}
 	};
 }
-function createColorToken(input) {
-	const defs = { __color__: {
-		lightness: input.lightness,
-		saturation: input.saturationFactor,
-		mode: input.mode
-	} };
+
+//#endregion
+//#region src/theme.ts
+/**
+* Theme factory.
+*
+* Wraps a hue/saturation seed, a mutable `ColorMap`, and an optional
+* per-theme `GlazeConfigOverride`. Exposes `tokens()` / `tasty()` /
+* `json()` / `css()` / `resolve()` / `export()` / `extend()`.
+*
+* The per-theme config override is **merged over the live global config at
+* resolve time** so the theme still reacts to later `configure()` calls
+* for fields it didn't override. The merged config is memoized by
+* `configVersion` to avoid rebuilding it on every export call.
+*/
+function createTheme(hue, saturation, initialColors, configOverride) {
+	let colorDefs = initialColors ? { ...initialColors } : {};
+	let cache = null;
+	function getEffectiveConfig() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version) return cache.effectiveConfig;
+		return mergeConfig(getConfig(), configOverride);
+	}
+	function resolveCached() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version) return cache.map;
+		const effectiveConfig = mergeConfig(getConfig(), configOverride);
+		const map = resolveAllColors(hue, saturation, colorDefs, effectiveConfig);
+		cache = {
+			map,
+			version,
+			effectiveConfig
+		};
+		return map;
+	}
+	function invalidate() {
+		cache = null;
+	}
 	return {
+		get hue() {
+			return hue;
+		},
+		get saturation() {
+			return saturation;
+		},
+		colors(defs) {
+			colorDefs = {
+				...colorDefs,
+				...defs
+			};
+			invalidate();
+		},
+		color(name, def) {
+			if (def === void 0) return colorDefs[name];
+			colorDefs[name] = def;
+			invalidate();
+		},
+		remove(names) {
+			const list = Array.isArray(names) ? names : [names];
+			for (const name of list) delete colorDefs[name];
+			invalidate();
+		},
+		has(name) {
+			return name in colorDefs;
+		},
+		list() {
+			return Object.keys(colorDefs);
+		},
+		reset() {
+			colorDefs = {};
+			invalidate();
+		},
+		export() {
+			const out = {
+				hue,
+				saturation,
+				colors: { ...colorDefs }
+			};
+			if (configOverride !== void 0) out.config = configOverride;
+			return out;
+		},
+		extend(options) {
+			const newHue = options.hue ?? hue;
+			const newSat = options.saturation ?? saturation;
+			const inheritedColors = {};
+			for (const [name, def] of Object.entries(colorDefs)) if (def.inherit !== false) inheritedColors[name] = def;
+			return createTheme(newHue, newSat, options.colors ? {
+				...inheritedColors,
+				...options.colors
+			} : { ...inheritedColors }, configOverride || options.config ? {
+				...configOverride ?? {},
+				...options.config ?? {}
+			} : void 0);
+		},
 		resolve() {
-			return resolveAllColors(input.hue, input.saturation, defs).get("__color__");
+			return new Map(resolveCached());
 		},
-		token(options) {
-			return buildTokenMap(resolveAllColors(input.hue, input.saturation, defs), "", {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
-			}, resolveModes(options?.modes), options?.format)["#__color__"];
+		tokens(options) {
+			const modes = resolveModes(options?.modes);
+			return buildFlatTokenMap(resolveCached(), "", modes, options?.format);
 		},
 		tasty(options) {
-			return buildTokenMap(resolveAllColors(input.hue, input.saturation, defs), "", {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
-			}, resolveModes(options?.modes), options?.format)["#__color__"];
+			const cfg = getEffectiveConfig();
+			const states = {
+				dark: options?.states?.dark ?? cfg.states.dark,
+				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
+			};
+			const modes = resolveModes(options?.modes);
+			return buildTokenMap(resolveCached(), "", states, modes, options?.format);
 		},
 		json(options) {
-			return buildJsonMap(resolveAllColors(input.hue, input.saturation, defs), resolveModes(options?.modes), options?.format)["__color__"];
+			const modes = resolveModes(options?.modes);
+			return buildJsonMap(resolveCached(), modes, options?.format);
+		},
+		css(options) {
+			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", options?.format ?? "rgb");
 		}
 	};
 }
+
+//#endregion
+//#region src/glaze.ts
+/**
+* Glaze — OKHST color theme generator.
+*
+* Public API entry. Wires `glaze()` and its attached static methods to
+* the focused modules in this folder:
+* - `theme.ts` — single-theme factory
+* - `palette.ts` — multi-theme composition
+* - `color-token.ts` — standalone single-color tokens (`glaze.color`)
+* - `shadow.ts` — standalone shadow factory (`glaze.shadow`)
+* - `formatters.ts` — variant → string (`glaze.format`)
+* - `config.ts` — global config singleton
+*/
 /**
 * Create a single-hue glaze theme.
 *
+* An optional `config` override can be supplied to customize the resolve
+* 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.
+*
 * @example
 * ```ts
-* const primary = glaze({ hue: 280, saturation: 80 });
-* // or shorthand:
 * const primary = glaze(280, 80);
+* // or shorthand:
+* const primary = glaze({ hue: 280, saturation: 80 });
+* // with config override:
+* const raw = glaze(280, 80, { lightTone: false });
 * ```
 */
-function glaze(hueOrOptions, saturation) {
-	if (typeof hueOrOptions === "number") return createTheme(hueOrOptions, saturation ?? 100);
-	return createTheme(hueOrOptions.hue, hueOrOptions.saturation);
+function glaze(hueOrOptions, saturation, config) {
+	if (typeof hueOrOptions === "number") return createTheme(hueOrOptions, saturation ?? 100, void 0, config);
+	return createTheme(hueOrOptions.hue, hueOrOptions.saturation, void 0, config);
 }
-/**
-* Configure global glaze settings.
-*/
-glaze.configure = function configure(config) {
-	globalConfig = {
-		lightLightness: config.lightLightness ?? globalConfig.lightLightness,
-		darkLightness: config.darkLightness ?? globalConfig.darkLightness,
-		darkDesaturation: config.darkDesaturation ?? globalConfig.darkDesaturation,
-		darkCurve: config.darkCurve ?? globalConfig.darkCurve,
-		states: {
-			dark: config.states?.dark ?? globalConfig.states.dark,
-			highContrast: config.states?.highContrast ?? globalConfig.states.highContrast
-		},
-		modes: {
-			dark: config.modes?.dark ?? globalConfig.modes.dark,
-			highContrast: config.modes?.highContrast ?? globalConfig.modes.highContrast
-		},
-		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning
-	};
+/** Configure global glaze settings. */
+glaze.configure = function configure$1(config) {
+	configure(config);
 };
-/**
-* Compose multiple themes into a palette.
-*/
+/** Compose multiple themes into a palette. */
 glaze.palette = function palette(themes, options) {
 	return createPalette(themes, options);
 };
-/**
-* Create a theme from a serialized export.
-*/
+/** Create a theme from a serialized export. */
 glaze.from = function from(data) {
-	return createTheme(data.hue, data.saturation, data.colors);
+	return createTheme(data.hue, data.saturation, data.colors, data.config);
 };
 /**
 * Create a standalone single-color token.
+*
+* **arg1 — the color** (four accepted shapes, discriminated by structure):
+*
+* | Shape | Example | Notes |
+* |---|---|---|
+* | 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, 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 tone window
+* to disable clamping entirely.
+*
+* ```ts
+* // Bare string — no overrides
+* glaze.color('#26fcb2')
+*
+* // From form — value + color overrides
+* glaze.color({ from: '#fff', base: bg, contrast: 'AA' })
+*
+* // Structured form — full theme-style token
+* glaze.color({ hue: 152, saturation: 95, tone: 74 })
+*
+* // Config override on any form
+* 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 tone exactly
+* (`lightTone: false` internally). Structured form snapshots both
+* tone windows from `globalConfig` at create time.
+*
+* 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.
 */
-glaze.color = function color(input) {
-	return createColorToken(input);
+glaze.color = function color(input, config) {
+	if (typeof input === "string") return createColorTokenFromValue(input, void 0, config);
+	const obj = input;
+	if ("from" in obj) {
+		const { from, ...overrides } = input;
+		return createColorTokenFromValue(from, overrides, config);
+	}
+	if ("hue" in obj) return createColorToken(input, config);
+	return createColorTokenFromValue(input, void 0, config);
 };
 /**
 * Compute a shadow color from a bg/fg pair and intensity.
+*
+* Both `bg` and `fg` accept any `GlazeColorValue` form: hex (`#rgb` /
+* `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()` / `oklch()`
+* strings, or `{ r, g, b }` / `{ h, s, l }` / `{ l, c, h }` objects.
 */
 glaze.shadow = function shadow(input) {
-	const bg = parseOkhslInput(input.bg);
-	const fg = input.fg ? parseOkhslInput(input.fg) : void 0;
-	const tuning = resolveShadowTuning(input.tuning);
+	const bg = extractOkhslFromValue(input.bg);
+	const fg = input.fg ? extractOkhslFromValue(input.fg) : void 0;
+	const cfg = getConfig();
+	const tuning = resolveShadowTuning(input.tuning, cfg.shadowTuning);
 	const result = computeShadow({
 		...bg,
 		alpha: 1
@@ -1674,32 +2868,22 @@ glaze.shadow = function shadow(input) {
 		...fg,
 		alpha: 1
 	} : void 0, input.intensity, tuning);
-	if (input.dark && tuning.darkShadowCurve < 1 && result.alpha > 0) {
-		const normalized = result.alpha / tuning.alphaMax;
-		const exponent = 1 / tuning.darkShadowCurve;
-		result.alpha = tuning.alphaMax * Math.pow(normalized, exponent);
-	}
-	return result;
+	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.
-*/
+/** Format a resolved color variant as a CSS string. */
 glaze.format = function format(variant, colorFormat) {
 	return formatVariant(variant, colorFormat);
 };
-function parseOkhslInput(input) {
-	if (typeof input === "string") {
-		const rgb = parseHex(input);
-		if (!rgb) throw new Error(`glaze: invalid hex color "${input}".`);
-		const [h, s, l] = srgbToOkhsl(rgb);
-		return {
-			h,
-			s,
-			l
-		};
-	}
-	return input;
-}
 /**
 * Create a theme from a hex color string.
 * Extracts hue and saturation from the color.
@@ -1723,31 +2907,34 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 	return createTheme(h, s * 100);
 };
 /**
-* Get the current global configuration (for testing/debugging).
+* Rehydrate a `glaze.color()` token from a `.export()` snapshot.
+*
+* The snapshot is a plain JSON-safe object containing the original
+* input value, overrides (with any `base` token recursively serialized),
+* and the effective config snapshot. The reconstructed token is identical
+* in behavior to the original at the time of export.
+*
+* @example
+* ```ts
+* const text = glaze.color({ from: '#1a1a1a', contrast: 'AA' });
+* const data = text.export();           // JSON-safe
+* localStorage.setItem('text', JSON.stringify(data));
+* // ...later...
+* const restored = glaze.colorFrom(JSON.parse(localStorage.getItem('text')!));
+* ```
 */
+glaze.colorFrom = function colorFrom(data) {
+	return colorFromExport(data);
+};
+/** Get the current global configuration (for testing/debugging). */
 glaze.getConfig = function getConfig() {
-	return { ...globalConfig };
+	return snapshotConfig();
 };
-/**
-* Reset global configuration to defaults.
-*/
-glaze.resetConfig = function resetConfig() {
-	globalConfig = {
-		lightLightness: [10, 100],
-		darkLightness: [15, 95],
-		darkDesaturation: .1,
-		darkCurve: .5,
-		states: {
-			dark: "@dark",
-			highContrast: "@high-contrast"
-		},
-		modes: {
-			dark: true,
-			highContrast: false
-		}
-	};
+/** Reset global configuration to defaults. */
+glaze.resetConfig = function resetConfig$1() {
+	resetConfig();
 };
 
 //#endregion
-export { contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { REF_EPS, apcaContrast, contrastRatioFromLuminance, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveContrastForMode, resolveMinContrast, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.mjs.map