@tenphi/glaze 0.0.0-snapshot.cdd8acc → 0.0.0-snapshot.d38eee5

package/dist/index.cjs

@@ -98,7 +98,12 @@ const K2 = .03;
 const K3 = (1 + K1) / (1 + K2);
 const EPSILON = 1e-10;
 const constrainAngle = (angle) => (angle % 360 + 360) % 360;
+/**
+* OKHSL toe function: maps OKLab lightness L to perceptual lightness l.
+* Exported for the OKHST tone transfers in `okhst.ts`.
+*/
 const toe = (x) => .5 * (K3 * x - K1 + Math.sqrt((K3 * x - K1) * (K3 * x - K1) + 4 * K2 * K3 * x));
+/** Inverse OKHSL toe: maps perceptual lightness l back to OKLab lightness L. */
 const toeInv = (x) => (x ** 2 + K1 * x) / (K3 * (x + K2));
 const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 const dotXY = (a, b) => a[0] * b[0] + a[1] * b[1];
@@ -253,10 +258,48 @@ const getCs = (L, a, b, cusp) => {
 		cMax
 	];
 };
+const CYAN_A = Math.cos(199.8 * Math.PI / 180);
+const CYAN_B = Math.sin(199.8 * Math.PI / 180);
+const BLUE_A = Math.cos(267.4 * Math.PI / 180);
+const BLUE_B = Math.sin(267.4 * Math.PI / 180);
+let cyanCusp;
+let blueCusp;
+/**
+* Computes the maximum safe OKLCH chroma that fits inside the sRGB gamut
+* for all possible hues at a given OKLab lightness `L`.
+*/
+function computeSafeChromaOKLCH(L) {
+	if (!cyanCusp) cyanCusp = findCuspOKLCH(CYAN_A, CYAN_B);
+	if (!blueCusp) blueCusp = findCuspOKLCH(BLUE_A, BLUE_B);
+	const c1 = findGamutIntersectionOKLCH(CYAN_A, CYAN_B, L, 1, L, cyanCusp);
+	const c2 = findGamutIntersectionOKLCH(BLUE_A, BLUE_B, L, 1, L, blueCusp);
+	return Math.min(c1, c2);
+}
+/** Per-hue cusp-lightness cache. The cusp is mode-independent, so keying on
+* a rounded hue is safe and keeps the cache small. */
+const cuspLightnessCache = /* @__PURE__ */ new Map();
+/**
+* OKHSL lightness of the gamut cusp for a hue — the lightness where the
+* realizable chroma peaks. Reuses the same `find_cusp` OKHSL already runs for
+* its `s` normalization (no new color math); the OKLab cusp lightness is run
+* through the OKHSL `toe` and clamped to `[0.001, 0.999]` so divisions that
+* key off it stay safe. Cached per (rounded) hue.
+*
+* @param h Hue, 0–360.
+*/
+function cuspLightness(h) {
+	const key = Math.round(constrainAngle(h) * 100) / 100;
+	const cached = cuspLightnessCache.get(key);
+	if (cached !== void 0) return cached;
+	const hNorm = key / 360;
+	const lc = clampVal(toe(findCuspOKLCH(Math.cos(TAU * hNorm), Math.sin(TAU * hNorm))[0]), .001, .999);
+	cuspLightnessCache.set(key, lc);
+	return lc;
+}
 /**
 * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
 */
-function okhslToOklab(h, s, l) {
+function okhslToOklab(h, s, l, pastel = false) {
 	const L = toeInv(l);
 	let a = 0;
 	let b = 0;
@@ -264,24 +307,30 @@ function okhslToOklab(h, s, l) {
 	if (L !== 0 && L !== 1 && s !== 0) {
 		const a_ = Math.cos(TAU * hNorm);
 		const b_ = Math.sin(TAU * hNorm);
-		const [c0, cMid, cMax] = getCs(L, a_, b_, findCuspOKLCH(a_, b_));
-		const mid = .8;
-		const midInv = 1.25;
-		let t, k0, k1, k2;
-		if (s < mid) {
-			t = midInv * s;
-			k0 = 0;
-			k1 = mid * c0;
-			k2 = 1 - k1 / cMid;
+		if (pastel) {
+			const c = s * computeSafeChromaOKLCH(L);
+			a = c * a_;
+			b = c * b_;
 		} else {
-			t = 5 * (s - .8);
-			k0 = cMid;
-			k1 = .2 * cMid ** 2 * 1.25 ** 2 / c0;
-			k2 = 1 - k1 / (cMax - cMid);
+			const [c0, cMid, cMax] = getCs(L, a_, b_, findCuspOKLCH(a_, b_));
+			const mid = .8;
+			const midInv = 1.25;
+			let t, k0, k1, k2;
+			if (s < mid) {
+				t = midInv * s;
+				k0 = 0;
+				k1 = mid * c0;
+				k2 = 1 - k1 / cMid;
+			} else {
+				t = 5 * (s - .8);
+				k0 = cMid;
+				k1 = .2 * cMid ** 2 * 1.25 ** 2 / c0;
+				k2 = 1 - k1 / (cMax - cMid);
+			}
+			const c = k0 + t * k1 / (1 - k2 * t);
+			a = c * a_;
+			b = c * b_;
 		}
-		const c = k0 + t * k1 / (1 - k2 * t);
-		a = c * a_;
-		b = c * b_;
 	}
 	return [
 		L,
@@ -293,8 +342,8 @@ function okhslToOklab(h, s, l) {
 * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
 * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
 */
-function okhslToLinearSrgb(h, s, l) {
-	return OKLabToLinearSRGB(okhslToOklab(h, s, l));
+function okhslToLinearSrgb(h, s, l, pastel = false) {
+	return OKLabToLinearSRGB(okhslToOklab(h, s, l, pastel));
 }
 /**
 * Compute relative luminance Y from linear sRGB channels.
@@ -324,8 +373,8 @@ const sRGBGammaToLinear = (val) => {
 /**
 * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
 */
-function okhslToSrgb(h, s, l) {
-	const lin = okhslToLinearSrgb(h, s, l);
+function okhslToSrgb(h, s, l, pastel = false) {
+	const lin = okhslToLinearSrgb(h, s, l, pastel);
 	return [
 		Math.max(0, Math.min(1, sRGBLinearToGamma(lin[0]))),
 		Math.max(0, Math.min(1, sRGBLinearToGamma(lin[1]))),
@@ -343,6 +392,22 @@ function gamutClampedLuminance(linearRgb) {
 	const b = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2]))));
 	return .2126 * r + .7152 * g + .0722 * b;
 }
+/**
+* Compute APCA screen luminance (`Ys`) from linear sRGB.
+*
+* APCA does not use the WCAG piecewise sRGB EOTF; it defines its own
+* luminance as `0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
+* gamma-encoded (display) channels with a simple 2.4 exponent. The APCA
+* soft-clamp threshold in `apcaContrast` is calibrated against this basis,
+* so the solver must feed it `Ys`, not WCAG relative luminance. Channels
+* are gamut-clamped to [0, 1] first, matching `gamutClampedLuminance`.
+*/
+function apcaLuminanceFromLinearRgb(linearRgb) {
+	const r = Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0])));
+	const g = Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1])));
+	const b = Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2])));
+	return .2126 * Math.pow(r, 2.4) + .7152 * Math.pow(g, 2.4) + .0722 * Math.pow(b, 2.4);
+}
 const linearSrgbToOklab = (rgb) => {
 	return transform(cbrt3(transform(rgb, linear_sRGB_to_LMS_M)), LMS_to_OKLab_M);
 };
@@ -351,7 +416,7 @@ const linearSrgbToOklab = (rgb) => {
 * 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 oklabToOkhsl = (lab, pastel = false) => {
 	const L = lab[0];
 	const a = lab[1];
 	const b = lab[2];
@@ -361,23 +426,32 @@ 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);
 	h = constrainAngle(h);
-	const [c0, cMid, cMax] = getCs(L, a_, b_, findCuspOKLCH(a_, b_));
-	const mid = .8;
-	const midInv = 1.25;
 	let s;
-	if (C < cMid) {
-		const k1 = mid * c0;
-		s = C / (k1 + C * (1 - k1 / cMid)) / midInv;
-	} else {
-		const k0 = cMid;
-		const k1 = .2 * cMid ** 2 * 1.25 ** 2 / c0;
-		const k2 = 1 - k1 / (cMax - cMid);
-		const cDiff = C - k0;
-		s = mid + cDiff / (k1 + cDiff * k2) / 5;
+	if (pastel) s = C / computeSafeChromaOKLCH(L);
+	else {
+		const [c0, cMid, cMax] = getCs(L, a_, b_, findCuspOKLCH(a_, b_));
+		const mid = .8;
+		const midInv = 1.25;
+		if (C < cMid) {
+			const k1 = mid * c0;
+			s = C / (k1 + C * (1 - k1 / cMid)) / midInv;
+		} else {
+			const k0 = cMid;
+			const k1 = .2 * cMid ** 2 * 1.25 ** 2 / c0;
+			const k2 = 1 - k1 / (cMax - cMid);
+			const cDiff = C - k0;
+			s = mid + cDiff / (k1 + cDiff * k2) / 5;
+		}
 	}
 	const l = toe(L);
 	return [
@@ -390,12 +464,12 @@ const oklabToOkhsl = (lab) => {
 * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
 * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
 */
-function srgbToOkhsl(rgb) {
+function srgbToOkhsl(rgb, pastel = false) {
 	return oklabToOkhsl(linearSrgbToOklab([
 		sRGBGammaToLinear(rgb[0]),
 		sRGBGammaToLinear(rgb[1]),
 		sRGBGammaToLinear(rgb[2])
-	]));
+	]), pastel);
 }
 /**
 * Convert CSS HSL (sRGB-based) to gamma-encoded sRGB [r, g, b] in 0–1 range.
@@ -433,30 +507,73 @@ function hslToSrgb(h, s, l) {
 /**
 * 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;
 }
@@ -467,24 +584,26 @@ function fmt$1(value, decimals) {
 * Format OKHSL values as a CSS `okhsl(H S% L%)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
-function formatOkhsl(h, s, l) {
-	return `okhsl(${fmt$1(h, 2)} ${fmt$1(s, 2)}% ${fmt$1(l, 2)}%)`;
+function formatOkhsl(h, s, l, pastel = false) {
+	let outS = s;
+	if (pastel) outS = oklabToOkhsl(okhslToOklab(h, s / 100, l / 100, true), false)[1] * 100;
+	return `okhsl(${fmt$1(h, 2)} ${fmt$1(outS, 2)}% ${fmt$1(l, 2)}%)`;
 }
 /**
 * Format OKHSL values as a CSS `rgb(R G B)` string.
 * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
-function formatRgb(h, s, l) {
-	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100);
+function formatRgb(h, s, l, pastel = false) {
+	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100, pastel);
 	return `rgb(${parseFloat((r * 255).toFixed(2))} ${parseFloat((g * 255).toFixed(2))} ${parseFloat((b * 255).toFixed(2))})`;
 }
 /**
 * Format OKHSL values as a CSS `hsl(H S% L%)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
-function formatHsl(h, s, l) {
-	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100);
+function formatHsl(h, s, l, pastel = false) {
+	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100, pastel);
 	const max = Math.max(r, g, b);
 	const min = Math.min(r, g, b);
 	const delta = max - min;
@@ -503,23 +622,392 @@ function formatHsl(h, s, l) {
 * Format OKHSL values as a CSS `oklch(L C H)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
-function formatOklch(h, s, l) {
-	const [L, a, b] = okhslToOklab(h, s / 100, l / 100);
+function formatOklch(h, s, l, pastel = false) {
+	const [L, a, b] = okhslToOklab(h, s / 100, l / 100, pastel);
 	const C = Math.sqrt(a * a + b * b);
 	let hh = Math.atan2(b, a) * (180 / Math.PI);
 	hh = constrainAngle(hh);
 	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: 10,
+			hi: 100,
+			eps: .05
+		},
+		darkTone: {
+			lo: 15,
+			hi: 95,
+			eps: .05
+		},
+		darkDesaturation: .1,
+		states: {
+			dark: "@dark",
+			highContrast: "@high-contrast"
+		},
+		modes: {
+			dark: true,
+			highContrast: false
+		},
+		autoFlip: true,
+		pastel: false,
+		inferRole: 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,
+		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,
+		pastel: config.pastel ?? globalConfig.pastel,
+		inferRole: config.inferRole ?? globalConfig.inferRole
+	};
+}
+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,
+		states: base.states,
+		modes: base.modes,
+		shadowTuning: override.shadowTuning ?? base.shadowTuning,
+		autoFlip: override.autoFlip ?? base.autoFlip,
+		pastel: override.pastel ?? base.pastel,
+		inferRole: override.inferRole ?? base.inferRole
+	};
+}
+
+//#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 dark desaturation reducer, 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);
+}
+/**
+* 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 APCA_PRESETS = {
+	preferred: 90,
+	body: 75,
+	content: 60,
+	large: 45,
+	"non-text": 30,
+	min: 15
+};
+/**
+* Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
+* keyword mapped to its Lc value. The magnitude is forced non-negative.
+*/
+function resolveApcaTarget(value) {
+	if (typeof value === "number") return Math.abs(value);
+	return APCA_PRESETS[value];
+}
 const CONTRAST_PRESETS = {
 	AA: 4.5,
 	AAA: 7,
@@ -530,15 +1018,77 @@ 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. `polarity` is passed through to the result for the APCA
+* branch (it controls argument order in the solver); WCAG ignores it.
+*/
+function resolveContrastForMode(spec, isHighContrast, polarity) {
+	if (typeof spec === "number" || typeof spec === "string") return {
+		metric: "wcag",
+		target: resolveMinContrast(spec)
+	};
+	if ("apca" in spec) return {
+		metric: "apca",
+		target: resolveApcaTarget(pickPair(spec.apca, isHighContrast)),
+		polarity: polarity ?? "fg"
+	};
+	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, pastel) {
+	const tRounded = Math.round(t * 1e4) / 1e4;
+	const key = `${metric}|${h}|${s}|${tRounded}|${pastel}`;
 	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), pastel));
 	if (luminanceCache.size >= CACHE_SIZE) {
 		const evict = cacheOrder.shift();
 		luminanceCache.delete(evict);
@@ -548,326 +1098,350 @@ 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). For APCA, `polarity` selects the argument order: `'fg'` (the
+* default) treats the candidate as the text against a background base
+* (`apcaContrast(yCandidate, yBase)`); `'bg'` treats the candidate as the
+* background (`apcaContrast(yBase, yCandidate)`). The magnitude is taken
+* either way. WCAG is symmetric, so polarity is ignored there.
 */
-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, polarity) {
+	if (metric === "wcag") return contrastRatioFromLuminance(yCandidate, yBase);
+	const lc = polarity === "bg" ? apcaContrast(yBase, yCandidate) : apcaContrast(yCandidate, yBase);
+	return Math.abs(lc);
+}
+/**
+* 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, polarity) {
+	const scoreLo = metricScore(metric, lum(lo), yBase, polarity);
+	const scoreHi = metricScore(metric, lum(hi), yBase, polarity);
+	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, polarity) >= 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, polarity);
+	const scoreHigh = metricScore(metric, lum(high), yBase, polarity);
+	const lowPasses = scoreLow >= target;
+	const highPasses = scoreHigh >= target;
+	if (lowPasses && highPasses) return Math.abs(low - anchor) <= Math.abs(high - anchor) ? {
+		pos: low,
+		contrast: scoreLow,
+		met: true
+	} : {
+		pos: high,
+		contrast: scoreHigh,
+		met: true
+	};
 	if (lowPasses) return {
-		lightness: low,
-		contrast: crLow,
+		pos: low,
+		contrast: scoreLow,
 		met: true
 	};
 	if (highPasses) return {
-		lightness: high,
-		contrast: crHigh,
+		pos: high,
+		contrast: scoreHigh,
 		met: true
 	};
-	return coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter);
-}
-/**
-* Fallback coarse scan when binary search is unstable near gamut edges.
-*/
-function coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter) {
-	const STEPS = 64;
-	const step = (hi - lo) / STEPS;
-	let bestL = lo;
-	let bestCr = 0;
-	let bestMet = false;
-	for (let i = 0; i <= STEPS; i++) {
-		const l = lo + step * i;
-		const cr = contrastRatioFromLuminance(cachedLuminance(h, s, l), yBase);
-		if (cr >= target && !bestMet) {
-			bestL = l;
-			bestCr = cr;
-			bestMet = true;
-		} else if (cr >= target && bestMet) {
-			bestL = l;
-			bestCr = cr;
-		} else if (!bestMet && cr > bestCr) {
-			bestL = l;
-			bestCr = cr;
-		}
-	}
-	if (bestMet && bestL > lo + step) {
-		let rLo = bestL - step;
-		let rHi = bestL;
-		for (let i = 0; i < maxIter; i++) {
-			if (rHi - rLo < epsilon) break;
-			const mid = (rLo + rHi) / 2;
-			const cr = contrastRatioFromLuminance(cachedLuminance(h, s, mid), yBase);
-			if (cr >= target) {
-				rHi = mid;
-				bestL = mid;
-				bestCr = cr;
-			} else rLo = mid;
-		}
-	}
-	return {
-		lightness: bestL,
-		contrast: bestCr,
-		met: bestMet
+	return scoreLow >= scoreHigh ? {
+		pos: low,
+		contrast: scoreLow,
+		met: false
+	} : {
+		pos: high,
+		contrast: scoreHigh,
+		met: false
 	};
 }
 /**
-* Find the OKHSL lightness that satisfies a WCAG 2 contrast target
-* against a base color, staying as close to `preferredLightness` as possible.
+* Closed-form WCAG tone seed: the gray tone whose luminance produces exactly
+* the target ratio against the base, on the requested side. Used to bias the
+* preferred tone before the search so chromatic refinement starts close.
 */
-function findLightnessForContrast(options) {
-	const { hue, saturation, preferredLightness, baseLinearRgb, contrast: contrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
-	const target = resolveMinContrast(contrastInput);
-	const searchTarget = target * 1.01;
-	const yBase = gamutClampedLuminance(baseLinearRgb);
-	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
-	if (crPref >= searchTarget) return {
-		lightness: preferredLightness,
-		contrast: crPref,
-		met: true,
-		branch: "preferred"
+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, polarity } = opts;
+	const runBranch = (lower) => lower ? searchBranch(lum, lo, searchAnchor, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor, polarity) : searchBranch(lum, searchAnchor, hi, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor, polarity);
+	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"
-	};
-	if (lighterPasses) return {
-		...lighterResult,
-		branch: "lighter"
-	};
-	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 extreme = initialIsLower ? lo : hi;
+	return {
+		pos: extreme,
+		contrast: metricScore(metric, lum(extreme), yBase, polarity),
 		met: false,
-		branch: "preferred"
+		lower: initialIsLower
 	};
-	candidates.sort((a, b) => b.contrast - a.contrast);
-	return candidates[0];
 }
 /**
-* Binary-search one branch [lo, hi] for the nearest passing mix value
-* to `preferred`.
+* Find the tone that satisfies a contrast floor against a base color,
+* staying as close to `preferredTone` as possible.
 */
-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
+function findToneForContrast(options) {
+	const { hue, saturation, preferredTone, baseLinearRgb, contrast, toneRange = [0, 1], epsilon = 1e-4, maxIterations = 18, pastel = false } = options;
+	const { metric, target, polarity } = contrast;
+	const searchTarget = metric === "wcag" ? target * 1.01 : target + .5;
+	const yBase = metricLuminance(metric, baseLinearRgb);
+	const lum = (t) => cachedLuminance(metric, hue, saturation, t, pastel);
+	const scorePref = metricScore(metric, lum(preferredTone), yBase, polarity);
+	if (scorePref >= searchTarget) return {
+		tone: preferredTone,
+		contrast: scorePref,
+		met: true,
+		branch: "preferred"
 	};
-	if (highPasses) return {
-		lightness: high,
-		contrast: crHigh,
-		met: true
+	const [minT, maxT] = toneRange;
+	const canDarker = preferredTone > minT;
+	const canLighter = preferredTone < maxT;
+	let initialIsDarker;
+	if (options.initialDirection !== void 0) initialIsDarker = options.initialDirection === "darker";
+	else if (canDarker && !canLighter) initialIsDarker = true;
+	else if (!canDarker && canLighter) initialIsDarker = false;
+	else if (!canDarker && !canLighter) return {
+		tone: preferredTone,
+		contrast: scorePref,
+		met: false,
+		branch: "preferred"
 	};
-	return crLow >= crHigh ? {
-		lightness: low,
-		contrast: crLow,
-		met: false
-	} : {
-		lightness: high,
-		contrast: crHigh,
-		met: false
+	else initialIsDarker = metricScore(metric, lum(minT), yBase, polarity) >= metricScore(metric, lum(maxT), yBase, polarity);
+	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,
+		polarity
+	});
+	return {
+		tone: solved.pos,
+		contrast: solved.contrast,
+		met: solved.met,
+		branch: solved.lower ? "darker" : "lighter",
+		...solved.flipped ? { flipped: true } : {}
 	};
 }
 /**
-* Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
-* target against a base color, staying as close to `preferredValue` as possible.
+* Find the mix parameter (ratio or opacity) that satisfies a contrast floor
+* against a base color, staying as close to `preferredValue` as possible.
 */
 function findValueForMixContrast(options) {
-	const { preferredValue, baseLinearRgb, contrast: contrastInput, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
-	const target = resolveMinContrast(contrastInput);
-	const searchTarget = target * 1.01;
-	const yBase = gamutClampedLuminance(baseLinearRgb);
-	const crPref = contrastRatioFromLuminance(luminanceAtValue(preferredValue), yBase);
-	if (crPref >= searchTarget) return {
+	const { preferredValue, baseLinearRgb, contrast, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
+	const { metric, target, polarity } = contrast;
+	const searchTarget = metric === "wcag" ? target * 1.01 : target + .5;
+	const yBase = metricLuminance(metric, baseLinearRgb);
+	const scorePref = metricScore(metric, luminanceAtValue(preferredValue), yBase, polarity);
+	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, polarity) >= metricScore(metric, luminanceAtValue(1), yBase, polarity);
+	const solved = solveNearestContrast({
+		lum: luminanceAtValue,
+		yBase,
+		metric,
+		target,
+		searchTarget,
+		lo: 0,
+		hi: 1,
+		searchAnchor: preferredValue,
+		distanceAnchor: preferredValue,
+		epsilon,
+		maxIterations,
+		flip: options.flip ?? false,
+		initialIsLower,
+		polarity
+	});
 	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/roles.ts
+const SURFACE_KEYWORDS = new Set([
+	"surface",
+	"bg",
+	"background",
+	"fill",
+	"canvas",
+	"paper",
+	"layer"
+]);
+const TEXT_KEYWORDS = new Set([
+	"text",
+	"fg",
+	"foreground",
+	"content",
+	"ink",
+	"label",
+	"stroke"
+]);
+const BORDER_KEYWORDS = new Set([
+	"border",
+	"divider",
+	"outline",
+	"separator",
+	"hairline",
+	"rule"
+]);
+const ALIAS_TO_ROLE = {
+	surface: "surface",
+	bg: "surface",
+	background: "surface",
+	fill: "surface",
+	canvas: "surface",
+	paper: "surface",
+	layer: "surface",
+	text: "text",
+	fg: "text",
+	foreground: "text",
+	content: "text",
+	ink: "text",
+	label: "text",
+	stroke: "text",
+	border: "border",
+	divider: "border",
+	outline: "border",
+	separator: "border",
+	hairline: "border",
+	rule: "border"
+};
 /**
-* Glaze — OKHSL-based color theme generator.
-*
-* 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
+* Normalize a `RoleInput` (canonical value or alias) into a canonical `Role`.
+* Returns `undefined` for unrecognized strings so callers can fall through to
+* the next step of the resolution chain.
+*/
+function normalizeRole(input) {
+	if (input === void 0) return void 0;
+	return ALIAS_TO_ROLE[input];
+}
+/**
+* Tokenize a color name into lowercase keyword tokens, splitting on
+* non-alphanumeric boundaries and at camelCase boundaries. Examples:
+* - `'button-text'` → `['button', 'text']`
+* - `'inputBg'` → `['input', 'bg']`
+* - `'card_border-outline'` → `['card', 'border', 'outline']`
+*/
+function tokenizeName(name) {
+	const pieces = name.split(/[^0-9a-zA-Z]+/).filter(Boolean);
+	const tokens = [];
+	for (const piece of pieces) {
+		const sub = piece.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/\s+/).filter(Boolean);
+		for (const s of sub) tokens.push(s.toLowerCase());
 	}
-};
-function pairNormal(p) {
-	return Array.isArray(p) ? p[0] : p;
+	return tokens;
 }
-function pairHC(p) {
-	return Array.isArray(p) ? p[1] : p;
+/**
+* Infer a `Role` from a color name by matching its tokens against the role
+* keyword sets. When multiple tokens match, the **last** recognized token
+* wins (so `button-text` → `text`, `input-bg` → `surface`, `card-border` →
+* `border`). Returns `undefined` when no token matches.
+*/
+function inferRoleFromName(name) {
+	const tokens = tokenizeName(name);
+	let inferred;
+	for (const token of tokens) if (SURFACE_KEYWORDS.has(token)) inferred = "surface";
+	else if (TEXT_KEYWORDS.has(token)) inferred = "text";
+	else if (BORDER_KEYWORDS.has(token)) inferred = "border";
+	return inferred;
+}
+/**
+* Map a role to its APCA polarity. `text` and `border` are foreground spots
+* against their base (the candidate is the text argument); `surface` is the
+* background (the base is the text argument).
+*/
+function roleToPolarity(role) {
+	return role === "surface" ? "bg" : "fg";
+}
+/**
+* The opposite role of `role`, used when a color with no explicit role and no
+* inferable name depends on a base: the dependent color plays the opposite
+* role of its base. `surface` ↔ `text`; `border` is treated as a foreground
+* spot, so its opposite is `surface`.
+*/
+function oppositeRole(role) {
+	if (role === "surface") return "text";
+	return "surface";
 }
+
+//#endregion
+//#region src/shadow.ts
+/**
+* Shadow color computation.
+*
+* 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";
 }
@@ -883,12 +1457,12 @@ const DEFAULT_SHADOW_TUNING = {
 	alphaMax: 1,
 	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) {
@@ -929,36 +1503,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);
@@ -976,7 +1563,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 = [];
@@ -985,6 +1572,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);
@@ -1000,185 +1588,278 @@ 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(contrast.polarity === "bg" ? apcaContrast(yBase, yColor) : 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,
+		pastel: v.pastel
 	};
+}
+/** 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.
+* Resolve the role of a base color referenced by `baseName`, returning the
+* role the *dependent* color should take (the opposite of the base's role).
+* A base that lives in `defs` recursively resolves and is inverted via
+* `oppositeRole`; an external base (no local def, e.g. an injected standalone
+* token) is treated as a background, so the dependent defaults to foreground
+* (`'text'`).
 */
-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 resolveBaseRoleInMap(baseName, defs, inferRole, roles) {
+	if (!baseName) return void 0;
+	const baseDef = defs[baseName];
+	if (!baseDef) return "text";
+	return oppositeRole(resolveRoleInMap(baseName, baseDef, defs, inferRole, roles));
+}
+/**
+* Role-resolution core that does not need a full `ResolveContext`. Shared by
+* the resolver (via `resolveRole`) and `verifyContrastDrift`.
+*/
+function resolveRoleInMap(name, def, defs, inferRole, roles) {
+	const cached = roles.get(name);
+	if (cached) return cached;
+	let role;
+	if (isShadowDef(def)) role = "surface";
+	else if (isMixDef(def)) role = normalizeRole(def.role) ?? (inferRole ? inferRoleFromName(name) : void 0) ?? resolveBaseRoleInMap(def.base, defs, inferRole, roles) ?? "text";
+	else {
+		const regDef = def;
+		role = normalizeRole(regDef.role) ?? (inferRole ? inferRoleFromName(name) : void 0) ?? resolveBaseRoleInMap(regDef.base, defs, inferRole, roles) ?? "text";
+	}
+	const finalRole = role ?? "text";
+	roles.set(name, finalRole);
+	return finalRole;
 }
 /**
-* Check whether a lightness value represents an absolute root definition
-* (i.e. a number, not a relative string).
+* Resolve a color's semantic `role` (text / surface / border) per the chain:
+*   1. explicit `def.role` (normalized)
+*   2. inferred from the color name when `config.inferRole` is on
+*   3. opposite of the base's role
+*   4. `'text'` (foreground) default
+*
+* Memoized on `ctx.roles` so the four scheme passes share one resolution.
+* Shadows have no contrast participation and default to `'surface'`.
 */
-function isAbsoluteLightness(lightness) {
-	if (lightness === void 0) return false;
-	return typeof (Array.isArray(lightness) ? lightness[0] : lightness) === "number";
+function resolveRole(name, def, ctx) {
+	return resolveRoleInMap(name, def, ctx.defs, ctx.config.inferRole, ctx.roles);
 }
-function resolveRootColor(_name, def, _ctx, isHighContrast) {
-	const rawL = def.lightness;
+function resolveContrastSpec(spec, isHighContrast, polarity) {
+	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast, polarity);
+}
+/**
+* Apply the relative-tone delta against a base, honoring `flip`.
+*
+* When `flip` is on and `base + delta` falls outside `[0, 100]`, mirror the
+* delta to the other side of the base (so an offset that would clamp instead
+* reflects back into range). When off, the caller clamps as usual.
+*/
+function applyToneFlip(delta, baseTone, flip) {
+	if (!flip) return delta;
+	const target = baseTone + delta;
+	if (target >= 0 && target <= 100) return delta;
+	return -delta;
+}
+function resolveRootColor(def, isHighContrast) {
+	const rawT = def.tone;
 	return {
-		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)
 	};
 }
-function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue) {
+function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue, polarity, effectivePastel) {
 	const baseName = def.base;
 	const baseResolved = ctx.resolved.get(baseName);
 	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 pastel = effectivePastel;
 	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, polarity);
+		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, baseVariant.pastel ?? ctx.config.pastel);
+		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,
+			pastel
+		});
+		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);
+	if (isMixDef(def)) return resolveMixForScheme(name, 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;
+	const polarity = roleToPolarity(resolveRole(name, def, ctx));
+	const pastel = regDef.pastel ?? ctx.config.pastel;
+	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;
+		const dep = resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, effectiveHue, polarity, pastel);
+		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;
+	const finalSat = isDark ? mapSaturationDark(baseSat, mode, ctx.config) : baseSat;
+	const toneFraction = clamp(finalTone / 100, 0, 1);
 	return {
 		h: effectiveHue,
 		s: clamp(finalSat, 0, 1),
-		l: clamp(finalL / 100, 0, 1),
-		alpha: regDef.opacity ?? 1
+		t: toneFraction,
+		alpha: regDef.opacity ?? 1,
+		pastel
 	};
 }
 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);
-	return computeShadow(bgVariant, fgVariant, intensity, tuning);
+	const tuning = resolveShadowTuning(def.tuning, ctx.config.shadowTuning);
+	return {
+		...toToneVariant(computeShadow(bgVariant, fgVariant, intensity, tuning)),
+		pastel: def.pastel ?? ctx.config.pastel
+	};
 }
-function variantToLinearRgb(v) {
-	return okhslToLinearSrgb(v.h, v.s, v.l);
+function okhslVariantToLinearRgb(v, pastel) {
+	return okhslToLinearSrgb(v.h, v.s, v.l, pastel);
 }
 /**
 * Resolve hue for OKHSL mixing, handling achromatic colors.
@@ -1201,77 +1882,92 @@ function linearSrgbLerp(base, target, t) {
 		base[2] + (target[2] - base[2]) * t
 	];
 }
-function linearRgbToVariant(rgb) {
+function linearRgbToToneVariant(rgb, pastel) {
 	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 {
+	], pastel);
+	return toToneVariant({
 		h,
 		s,
 		l,
 		alpha: 1
-	};
+	});
 }
-function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
+function resolveMixForScheme(name, 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 polarity = roleToPolarity(resolveRole(name, def, ctx));
+	const pastel = def.pastel ?? ctx.config.pastel;
+	const baseLinear = okhslVariantToLinearRgb(baseVariant, baseVariant.pastel ?? ctx.config.pastel);
+	const targetLinear = okhslVariantToLinearRgb(targetVariant, targetVariant.pastel ?? ctx.config.pastel);
 	if (def.contrast !== void 0) {
-		const minCr = isHighContrast ? pairHC(def.contrast) : pairNormal(def.contrast);
+		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast, polarity);
+		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, pastel));
 		};
 		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 {
-		h: targetVariant.h,
-		s: targetVariant.s,
-		l: targetVariant.l,
-		alpha: clamp(t, 0, 1)
+		...toToneVariant({
+			h: targetVariant.h,
+			s: targetVariant.s,
+			l: targetVariant.l,
+			alpha: clamp(t, 0, 1)
+		}),
+		pastel
+	};
+	if (space === "srgb") return {
+		...linearRgbToToneVariant(linearSrgbLerp(baseLinear, targetLinear, t), pastel),
+		pastel
 	};
-	if (space === "srgb") return linearRgbToVariant(linearSrgbLerp(baseLinear, targetLinear, t));
 	return {
-		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
+		...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
+		}),
+		pastel
 	};
 }
-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,
@@ -1280,49 +1976,92 @@ 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, config) {
+	const roles = /* @__PURE__ */ new Map();
 	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;
+		const polarity = roleToPolarity(resolveRoleInMap(name, def, defs, config.inferRole, roles));
+		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, polarity);
+			const cVariant = color[s.field];
+			const bVariant = base[s.field];
+			const cOkhsl = toOkhslVariant(cVariant);
+			const bOkhsl = toOkhslVariant(bVariant);
+			const cPastel = cVariant.pastel ?? config.pastel;
+			const bPastel = bVariant.pastel ?? config.pastel;
+			const yC = metricLuminance(spec.metric, okhslToLinearSrgb(cOkhsl.h, cOkhsl.s, cOkhsl.l, cPastel));
+			const yB = metricLuminance(spec.metric, okhslToLinearSrgb(bOkhsl.h, bOkhsl.s, bOkhsl.l, bPastel));
+			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,
+		roles: /* @__PURE__ */ new Map()
+	};
+	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,
@@ -1332,8 +2071,22 @@ function resolveAllColors(hue, saturation, defs) {
 		darkContrast: darkHCMap.get(name),
 		mode: defMode(defs[name])
 	});
+	verifyContrastDrift(order, defs, result, config);
 	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,
@@ -1343,56 +2096,59 @@ const formatters = {
 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);
+function formatVariant(v, format = "okhsl", pastel = false) {
+	const effectivePastel = v.pastel ?? pastel;
+	const { l } = variantToOkhsl(v);
+	const base = formatters[format](v.h, v.s * 100, l * 100, effectivePastel);
 	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") {
+function buildTokenMap(resolved, prefix, states, modes, format = "okhsl", pastel = false) {
 	const tokens = {};
 	for (const [name, color] of resolved) {
 		const key = `#${prefix}${name}`;
-		const entry = { "": formatVariant(color.light, format) };
-		if (modes.dark) entry[states.dark] = formatVariant(color.dark, format);
-		if (modes.highContrast) entry[states.highContrast] = formatVariant(color.lightContrast, format);
-		if (modes.dark && modes.highContrast) entry[`${states.dark} & ${states.highContrast}`] = formatVariant(color.darkContrast, format);
+		const entry = { "": formatVariant(color.light, format, pastel) };
+		if (modes.dark) entry[states.dark] = formatVariant(color.dark, format, pastel);
+		if (modes.highContrast) entry[states.highContrast] = formatVariant(color.lightContrast, format, pastel);
+		if (modes.dark && modes.highContrast) entry[`${states.dark} & ${states.highContrast}`] = formatVariant(color.darkContrast, format, pastel);
 		tokens[key] = entry;
 	}
 	return tokens;
 }
-function buildFlatTokenMap(resolved, prefix, modes, format = "okhsl") {
+function buildFlatTokenMap(resolved, prefix, modes, format = "okhsl", pastel = false) {
 	const result = { light: {} };
 	if (modes.dark) result.dark = {};
 	if (modes.highContrast) result.lightContrast = {};
 	if (modes.dark && modes.highContrast) result.darkContrast = {};
 	for (const [name, color] of resolved) {
 		const key = `${prefix}${name}`;
-		result.light[key] = formatVariant(color.light, format);
-		if (modes.dark) result.dark[key] = formatVariant(color.dark, format);
-		if (modes.highContrast) result.lightContrast[key] = formatVariant(color.lightContrast, format);
-		if (modes.dark && modes.highContrast) result.darkContrast[key] = formatVariant(color.darkContrast, format);
+		result.light[key] = formatVariant(color.light, format, pastel);
+		if (modes.dark) result.dark[key] = formatVariant(color.dark, format, pastel);
+		if (modes.highContrast) result.lightContrast[key] = formatVariant(color.lightContrast, format, pastel);
+		if (modes.dark && modes.highContrast) result.darkContrast[key] = formatVariant(color.darkContrast, format, pastel);
 	}
 	return result;
 }
-function buildJsonMap(resolved, modes, format = "okhsl") {
+function buildJsonMap(resolved, modes, format = "okhsl", pastel = false) {
 	const result = {};
 	for (const [name, color] of resolved) {
-		const entry = { light: formatVariant(color.light, format) };
-		if (modes.dark) entry.dark = formatVariant(color.dark, format);
-		if (modes.highContrast) entry.lightContrast = formatVariant(color.lightContrast, format);
-		if (modes.dark && modes.highContrast) entry.darkContrast = formatVariant(color.darkContrast, format);
+		const entry = { light: formatVariant(color.light, format, pastel) };
+		if (modes.dark) entry.dark = formatVariant(color.dark, format, pastel);
+		if (modes.highContrast) entry.lightContrast = formatVariant(color.lightContrast, format, pastel);
+		if (modes.dark && modes.highContrast) entry.darkContrast = formatVariant(color.darkContrast, format, pastel);
 		result[name] = entry;
 	}
 	return result;
 }
-function buildCssMap(resolved, prefix, suffix, format) {
+function buildCssMap(resolved, prefix, suffix, format, pastel = false) {
 	const lines = {
 		light: [],
 		dark: [],
@@ -1401,10 +2157,10 @@ function buildCssMap(resolved, prefix, suffix, format) {
 	};
 	for (const [name, color] of resolved) {
 		const prop = `--${prefix}${name}${suffix}`;
-		lines.light.push(`${prop}: ${formatVariant(color.light, format)};`);
-		lines.dark.push(`${prop}: ${formatVariant(color.dark, format)};`);
-		lines.lightContrast.push(`${prop}: ${formatVariant(color.lightContrast, format)};`);
-		lines.darkContrast.push(`${prop}: ${formatVariant(color.darkContrast, format)};`);
+		lines.light.push(`${prop}: ${formatVariant(color.light, format, pastel)};`);
+		lines.dark.push(`${prop}: ${formatVariant(color.dark, format, pastel)};`);
+		lines.lightContrast.push(`${prop}: ${formatVariant(color.lightContrast, format, pastel)};`);
+		lines.darkContrast.push(`${prop}: ${formatVariant(color.darkContrast, format, pastel)};`);
 	}
 	return {
 		light: lines.light.join("\n"),
@@ -1413,218 +2169,127 @@ 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,
+		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,
+		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`.
-* Warns on collision and keeps the first-written value (first-write-wins).
-* Returns a new map containing only non-colliding entries.
+* 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 filterCollisions(resolved, prefix, seen, themeName, isPrimary) {
-	const filtered = /* @__PURE__ */ new Map();
-	const label = isPrimary ? `${themeName} (primary)` : themeName;
-	for (const [name, color] of resolved) {
-		const key = `${prefix}${name}`;
-		if (seen.has(key)) {
-			console.warn(`glaze: token "${key}" from theme "${label}" collides with theme "${seen.get(key)}" — skipping.`);
-			continue;
-		}
-		seen.set(key, label);
-		filtered.set(name, color);
+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 filtered;
-}
-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]);
-				}
-				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 states = {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.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;
-		},
-		json(options) {
-			const modes = resolveModes(options?.modes);
-			const result = {};
-			for (const [themeName, theme] of Object.entries(themes)) result[themeName] = buildJsonMap(theme.resolve(), modes, options?.format);
-			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);
-				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]);
-				}
-			}
-			return {
-				light: allLines.light.join("\n"),
-				dark: allLines.dark.join("\n"),
-				lightContrast: allLines.lightContrast.join("\n"),
-				darkContrast: allLines.darkContrast.join("\n")
-			};
-		}
+		components,
+		hadAlpha: false
 	};
 }
-/** Matches CSS color functions Glaze itself emits, plus their legacy alpha aliases. */
-const COLOR_FN_RE = /^(rgba?|hsla?|okhsl|oklch)\(\s*([^)]*)\s*\)$/i;
-function parseNumberOrPercent(raw, percentScale) {
-	if (raw.endsWith("%")) return parseFloat(raw) / 100 * percentScale;
-	return parseFloat(raw);
+function warnDroppedAlpha(input) {
+	console.warn(`glaze: alpha component dropped from "${input}" (standalone color has no opacity field).`);
 }
 function parseColorString(input) {
 	if (input.startsWith("#")) {
-		const rgb = parseHex(input);
-		if (!rgb) throw new Error(`glaze: invalid hex color "${input}".`);
-		const [h, s, l] = srgbToOkhsl(rgb);
+		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,
@@ -1634,29 +2299,16 @@ function parseColorString(input) {
 	const m = input.match(COLOR_FN_RE);
 	if (!m) throw new Error(`glaze: unsupported color string "${input}".`);
 	const fn = m[1].toLowerCase();
-	const body = m[2].trim();
-	let parts;
-	let hasAlpha = false;
-	const slashIdx = body.indexOf("/");
-	if (slashIdx !== -1) {
-		parts = body.slice(0, slashIdx).trim().split(/[\s,]+/).filter(Boolean);
-		hasAlpha = body.slice(slashIdx + 1).trim().length > 0;
-	} else {
-		parts = body.split(/[\s,]+/).filter(Boolean);
-		if (parts.length === 4) {
-			parts.pop();
-			hasAlpha = true;
-		}
-	}
-	if (hasAlpha) console.warn(`glaze: alpha component dropped from "${input}" (standalone color has no opacity field).`);
-	if (parts.length !== 3) throw new Error(`glaze: expected 3 components in "${input}".`);
+	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(parts[0], 255) / 255,
-				parseNumberOrPercent(parts[1], 255) / 255,
-				parseNumberOrPercent(parts[2], 255) / 255
+				parseNumberOrPercent(components[0], 255) / 255,
+				parseNumberOrPercent(components[1], 255) / 255,
+				parseNumberOrPercent(components[2], 255) / 255
 			]);
 			return {
 				h,
@@ -1666,7 +2318,7 @@ function parseColorString(input) {
 		}
 		case "hsl":
 		case "hsla": {
-			const [oh, os, ol] = srgbToOkhsl(hslToSrgb(parseFloat(parts[0]), parseNumberOrPercent(parts[1], 1), parseNumberOrPercent(parts[2], 1)));
+			const [oh, os, ol] = srgbToOkhsl(hslToSrgb(parseFloat(components[0]), parseNumberOrPercent(components[1], 1), parseNumberOrPercent(components[2], 1)));
 			return {
 				h: oh,
 				s: os,
@@ -1674,14 +2326,19 @@ function parseColorString(input) {
 			};
 		}
 		case "okhsl": return {
-			h: parseFloat(parts[0]),
-			s: parseNumberOrPercent(parts[1], 1),
-			l: parseNumberOrPercent(parts[2], 1)
+			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(parts[0], 1);
-			const C = parseFloat(parts[1]);
-			const hRad = parseFloat(parts[2]) * Math.PI / 180;
+			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),
@@ -1696,14 +2353,116 @@ function parseColorString(input) {
 	}
 	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)) {
-		const [r, g, b] = 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([
-			r / 255,
-			g / 255,
-			b / 255
+			value.r / 255,
+			value.g / 255,
+			value.b / 255
 		]);
 		return {
 			h,
@@ -1711,185 +2470,660 @@ function extractOkhslFromValue(value) {
 			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;
 }
-function buildValueDefs(main, options) {
-	const absoluteSeedHue = typeof options?.hue === "number" ? options.hue : main.h;
+/**
+* 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;
-	if (options?.base !== void 0) {
-		const baseOkhsl = extractOkhslFromValue(options.base);
-		const baseSatFactor = seedSaturation > 0 ? Math.min(baseOkhsl.s * 100 / seedSaturation, 1) : 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,
+		pastel: options?.pastel,
+		role: options?.role,
+		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 {
-			seedHue: absoluteSeedHue,
-			seedSaturation,
-			defs: {
-				__base__: {
-					hue: baseOkhsl.h,
-					saturation: baseSatFactor,
-					lightness: baseOkhsl.l * 100,
-					mode: options.mode
-				},
-				__color__: {
-					base: "__base__",
-					hue: relativeHue,
-					saturation: options.saturationFactor,
-					lightness: options.lightness ?? main.l * 100,
-					contrast: options.contrast,
-					mode: options.mode
-				}
-			},
-			primary: "__color__"
+			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, effectiveConfig.pastel)[`#${primary}`];
+	};
 	return {
-		seedHue: absoluteSeedHue,
-		seedSaturation,
-		defs: { __color__: {
-			hue: relativeHue,
-			saturation: options?.saturationFactor,
-			lightness: options?.lightness ?? main.l * 100,
-			contrast: options?.contrast,
-			mode: options?.mode
-		} },
-		primary: "__color__"
-	};
-}
-function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary) {
-	const resolveStates = (options) => ({
-		dark: options?.states?.dark ?? globalConfig.states.dark,
-		highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
+		resolve() {
+			return resolveOnce().get(primary);
+		},
+		token: tokenLike,
+		tasty: tokenLike,
+		json(options) {
+			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), options?.format, effectiveConfig.pastel)[primary];
+		},
+		css(options) {
+			return buildCssMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.suffix ?? "-color", options.format ?? "rgb", effectiveConfig.pastel);
+		},
+		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,
+		pastel: input.pastel,
+		role: input.role,
+		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.pastel !== void 0) out.pastel = options.pastel;
+	if (options.role !== void 0) out.role = options.role;
+	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.pastel !== void 0) out.pastel = input.pastel;
+	if (input.role !== void 0) out.role = input.role;
+	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.pastel !== void 0) out.pastel = data.pastel;
+	if (data.role !== void 0) out.role = data.role;
+	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.pastel !== void 0) out.pastel = data.pastel;
+	if (data.role !== void 0) out.role = data.role;
+	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.
+*/
+function filterCollisions(resolved, prefix, seen, themeName, isPrimary) {
+	const filtered = /* @__PURE__ */ new Map();
+	const label = isPrimary ? `${themeName} (primary)` : themeName;
+	for (const [name, color] of resolved) {
+		const key = `${prefix}${name}`;
+		if (seen.has(key)) {
+			console.warn(`glaze: token "${key}" from theme "${label}" collides with theme "${seen.get(key)}" — skipping.`);
+			continue;
+		}
+		seen.set(key, label);
+		filtered.set(name, color);
+	}
+	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 pastel = theme.getConfig().pastel;
+		const prefix = resolvePrefix(options, themeName, true);
+		merge(acc, buildOne(filterCollisions(resolved, prefix, seen, themeName), prefix, pastel));
+		if (themeName === effectivePrimary) merge(acc, buildOne(filterCollisions(resolved, "", seen, themeName, true), "", pastel));
+	}
+	return acc;
+}
+function createPalette(themes, paletteOptions) {
+	validatePrimaryTheme(paletteOptions?.primary, themes);
 	return {
+		tokens(options) {
+			const modes = resolveModes(options?.modes);
+			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildFlatTokenMap(filtered, prefix, modes, options?.format, pastel), (acc, part) => {
+				for (const variant of Object.keys(part)) {
+					if (!acc[variant]) acc[variant] = {};
+					Object.assign(acc[variant], part[variant]);
+				}
+			}, () => ({}));
+		},
+		tasty(options) {
+			const cfg = getConfig();
+			const states = {
+				dark: options?.states?.dark ?? cfg.states.dark,
+				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
+			};
+			const modes = resolveModes(options?.modes);
+			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildTokenMap(filtered, prefix, states, modes, options?.format, pastel), (acc, part) => Object.assign(acc, part), () => ({}));
+		},
+		json(options) {
+			const modes = resolveModes(options?.modes);
+			const result = {};
+			for (const [themeName, theme] of Object.entries(themes)) result[themeName] = buildJsonMap(theme.resolve(), modes, options?.format, theme.getConfig().pastel);
+			return result;
+		},
+		css(options) {
+			const suffix = options?.suffix ?? "-color";
+			const format = options?.format ?? "rgb";
+			const lines = buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildCssMap(filtered, prefix, suffix, format, pastel), (acc, part) => {
+				for (const key of [
+					"light",
+					"dark",
+					"lightContrast",
+					"darkContrast"
+				]) if (part[key]) acc[key].push(part[key]);
+			}, () => ({
+				light: [],
+				dark: [],
+				lightContrast: [],
+				darkContrast: []
+			}));
+			return {
+				light: lines.light.join("\n"),
+				dark: lines.dark.join("\n"),
+				lightContrast: lines.lightContrast.join("\n"),
+				darkContrast: lines.darkContrast.join("\n")
+			};
+		}
+	};
+}
+
+//#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;
+		},
+		getConfig() {
+			return getEffectiveConfig();
+		},
+		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(seedHue, seedSaturation, defs).get(primary);
+			return new Map(resolveCached());
 		},
-		token(options) {
-			return buildTokenMap(resolveAllColors(seedHue, seedSaturation, defs), "", resolveStates(options), resolveModes(options?.modes), options?.format)[`#${primary}`];
+		tokens(options) {
+			const modes = resolveModes(options?.modes);
+			return buildFlatTokenMap(resolveCached(), "", modes, options?.format, getEffectiveConfig().pastel);
 		},
 		tasty(options) {
-			return buildTokenMap(resolveAllColors(seedHue, seedSaturation, defs), "", resolveStates(options), resolveModes(options?.modes), options?.format)[`#${primary}`];
+			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, cfg.pastel);
 		},
 		json(options) {
-			return buildJsonMap(resolveAllColors(seedHue, seedSaturation, defs), resolveModes(options?.modes), options?.format)[primary];
+			const modes = resolveModes(options?.modes);
+			return buildJsonMap(resolveCached(), modes, options?.format, getEffectiveConfig().pastel);
 		},
 		css(options) {
-			const resolved = resolveAllColors(seedHue, seedSaturation, defs);
-			return buildCssMap(new Map([[options.name, resolved.get(primary)]]), "", options.suffix ?? "-color", options.format ?? "rgb");
+			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", options?.format ?? "rgb", getEffectiveConfig().pastel);
 		}
 	};
 }
-function createColorToken(input) {
-	const defs = { __color__: {
-		lightness: input.lightness,
-		saturation: input.saturationFactor,
-		mode: input.mode
-	} };
-	return createColorTokenFromDefs(input.hue, input.saturation, defs, "__color__");
-}
-function createColorTokenFromValue(value, options) {
-	const { seedHue, seedSaturation, defs, primary } = buildValueDefs(extractOkhslFromValue(value), options);
-	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary);
-}
+
+//#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, 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);
 };
-function isStructuredColorInput(input) {
-	return typeof input === "object" && input !== null && !Array.isArray(input) && "hue" in input && "lightness" in input;
-}
 /**
 * Create a standalone single-color token.
 *
-* Two overloads:
-* - `glaze.color(input)` — structured form: `{ hue, saturation, lightness, ... }`.
-* - `glaze.color(value, overrides?)` — value-shorthand: a hex string,
-*   one of the CSS color functions Glaze itself emits
-*   (`rgb()`, `hsl()`, `okhsl()`, `oklch()`), an `OkhslColor` object
-*   `{ h, s, l }`, or an `[r, g, b]` (0–255) tuple. Optional overrides
-*   accept absolute or relative `hue` / `lightness`, `saturation`,
-*   `mode`, `base` (any value form), and `contrast` against the base.
-*/
-glaze.color = function color(input, options) {
-	if (isStructuredColorInput(input)) return createColorToken(input);
-	return createColorTokenFromValue(input, options);
+* **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 })
+* ```
+*
+* 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, 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);
-	return computeShadow({
+	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
 	}, fg ? {
 		...fg,
 		alpha: 1
 	} : void 0, input.intensity, tuning);
+	const { h, s, t } = okhslToOkhst({
+		h: result.h,
+		s: result.s,
+		l: result.l
+	});
+	return {
+		h,
+		s,
+		t,
+		alpha: result.alpha
+	};
 };
-/**
-* Format a resolved color variant as a CSS string.
-*/
-glaze.format = function format(variant, colorFormat) {
-	return formatVariant(variant, colorFormat);
+/** Format a resolved color variant as a CSS string. */
+glaze.format = function format(variant, colorFormat, pastel) {
+	return formatVariant(variant, colorFormat, pastel);
 };
-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.
@@ -1913,48 +3147,68 @@ 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
+exports.REF_EPS = REF_EPS;
+exports.apcaContrast = apcaContrast;
 exports.contrastRatioFromLuminance = contrastRatioFromLuminance;
-exports.findLightnessForContrast = findLightnessForContrast;
+exports.cuspLightness = cuspLightness;
+exports.findToneForContrast = findToneForContrast;
 exports.findValueForMixContrast = findValueForMixContrast;
 exports.formatHsl = formatHsl;
 exports.formatOkhsl = formatOkhsl;
 exports.formatOklch = formatOklch;
 exports.formatRgb = formatRgb;
+exports.fromTone = fromTone;
 exports.gamutClampedLuminance = gamutClampedLuminance;
 exports.glaze = glaze;
 exports.hslToSrgb = hslToSrgb;
+exports.inferRoleFromName = inferRoleFromName;
+exports.normalizeRole = normalizeRole;
 exports.okhslToLinearSrgb = okhslToLinearSrgb;
+exports.okhslToOkhst = okhslToOkhst;
 exports.okhslToOklab = okhslToOklab;
 exports.okhslToSrgb = okhslToSrgb;
+exports.okhstToOkhsl = okhstToOkhsl;
 exports.oklabToOkhsl = oklabToOkhsl;
+exports.oppositeRole = oppositeRole;
 exports.parseHex = parseHex;
+exports.parseHexAlpha = parseHexAlpha;
 exports.relativeLuminanceFromLinearRgb = relativeLuminanceFromLinearRgb;
+exports.resolveApcaTarget = resolveApcaTarget;
+exports.resolveContrastForMode = resolveContrastForMode;
 exports.resolveMinContrast = resolveMinContrast;
+exports.roleToPolarity = roleToPolarity;
 exports.srgbToOkhsl = srgbToOkhsl;
+exports.toTone = toTone;
+exports.toneFromY = toneFromY;
+exports.variantToOkhsl = variantToOkhsl;
+exports.yFromTone = yFromTone;
 //# sourceMappingURL=index.cjs.map