@tenphi/glaze 0.0.0-snapshot.fdc17e3 → 0.0.0-snapshot.fe6eee0

package/dist/index.cjs

@@ -372,6 +372,7 @@ const sRGBGammaToLinear = (val) => {
 };
 /**
 * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
+* h: 0–360, s: 0–1, l: 0–1. Returns [r, g, b] with each channel 0–1.
 */
 function okhslToSrgb(h, s, l, pastel = false) {
 	const lin = okhslToLinearSrgb(h, s, l, pastel);
@@ -581,47 +582,72 @@ function fmt$1(value, decimals) {
 	return parseFloat(value.toFixed(decimals)).toString();
 }
 /**
+* Every `format*` writer takes `s` / `l` / `t` on the **0–1 factor scale** —
+* the same scale every producer in the library hands back (`resolve()`,
+* `variantToOkhsl`, `srgbToOkhsl`, `oklabToOkhsl`, `okhslToOklab`,
+* `okhslToSrgb`). The percentages are an output detail: the writers multiply
+* by 100 themselves when the CSS syntax asks for a percentage.
+*
+* Before 2.0 the writers took 0–100 while everything producing those values
+* returned 0–1, so the obvious composition was off by 100x and failed
+* silently — `0.7` is a legal percentage, so the result was a valid CSS string
+* naming a near-black color. A value above 1 can only be that old
+* percentage-scale input, so warn about it loudly rather than emit a wrong
+* color quietly.
+*/
+const scaleWarnCache = /* @__PURE__ */ new Set();
+function warnPercentScale(fn, ...values) {
+	if (!values.some((v) => v > 1.000001)) return;
+	if (!scaleWarnCache.has(fn)) {
+		scaleWarnCache.add(fn);
+		console.warn(`glaze: ${fn}() got a value above 1 — it takes the 0-1 factors every Glaze producer returns (resolve(), variantToOkhsl, srgbToOkhsl), not 0-100 percentages. Divide by 100, or drop the "* 100" left over from the pre-2.0 signature.`);
+	}
+}
+/**
 * 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatOkhsl(h, s, l, pastel = false) {
+	warnPercentScale("formatOkhsl", s, l);
 	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)}%)`;
+	if (pastel) outS = oklabToOkhsl(okhslToOklab(h, s, l, true), false)[1];
+	return `okhsl(${fmt$1(h, 2)} ${fmt$1(outS * 100, 2)}% ${fmt$1(l * 100, 2)}%)`;
 }
 /**
 * Format OKHST values as a CSS `okhst(H S% T%)` string.
-* h: 0–360, s: 0–100, t: 0–100 (percentage scale for s and t).
+* h: 0–360, s: 0–1, t: 0–1 (factor scale, matching `ResolvedColorVariant`).
 *
 * Pastel recompute matches `formatOkhsl`: convert via OKLab so external
 * parsers that only understand non-pastel OKHST render identically.
 */
 function formatOkhst(h, s, t, pastel = false) {
+	warnPercentScale("formatOkhst", s, t);
 	let outS = s;
 	if (pastel) {
 		const REF_EPS = .05;
 		const den = Math.log(1 + REF_EPS) - Math.log(REF_EPS);
-		const y = Math.exp(t / 100 * den + Math.log(REF_EPS)) - REF_EPS;
-		const l = toe(Math.cbrt(Math.max(0, y)));
-		outS = oklabToOkhsl(okhslToOklab(h, s / 100, l, true), false)[1] * 100;
+		const y = Math.exp(t * den + Math.log(REF_EPS)) - REF_EPS;
+		outS = oklabToOkhsl(okhslToOklab(h, s, toe(Math.cbrt(Math.max(0, y))), true), false)[1];
 	}
-	return `okhst(${fmt$1(h, 2)} ${fmt$1(outS, 2)}% ${fmt$1(t, 2)}%)`;
+	return `okhst(${fmt$1(h, 2)} ${fmt$1(outS * 100, 2)}% ${fmt$1(t * 100, 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatRgb(h, s, l, pastel = false) {
-	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100, pastel);
+	warnPercentScale("formatRgb", s, l);
+	const [r, g, b] = okhslToSrgb(h, s, l, 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatHsl(h, s, l, pastel = false) {
-	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100, pastel);
+	warnPercentScale("formatHsl", s, l);
+	const [r, g, b] = okhslToSrgb(h, s, l, pastel);
 	const max = Math.max(r, g, b);
 	const min = Math.min(r, g, b);
 	const delta = max - min;
@@ -638,10 +664,11 @@ function formatHsl(h, s, l, pastel = false) {
 }
 /**
 * 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatOklch(h, s, l, pastel = false) {
-	const [L, C, hh] = okhslToOklch(h, s / 100, l / 100, pastel);
+	warnPercentScale("formatOklch", s, l);
+	const [L, C, hh] = okhslToOklch(h, s, l, pastel);
 	return `oklch(${fmt$1(L, 4)} ${fmt$1(C, 4)} ${fmt$1(hh, 2)})`;
 }
 /**
@@ -675,6 +702,8 @@ function okhslToOklch(h, s, l, pastel = false) {
 /**
 * Build a fresh defaults object. Called from module init and from
 * `resetConfig()` so the two paths can't drift.
+*
+* `pastel: false` is a fixed instance default — not globally configurable.
 */
 function defaultConfig() {
 	return {
@@ -690,8 +719,8 @@ function defaultConfig() {
 		},
 		darkDesaturation: .1,
 		states: {
-			dark: "@dark",
-			highContrast: "@high-contrast"
+			dark: "@media(prefers-color-scheme: dark)",
+			highContrast: "@media(prefers-contrast: more)"
 		},
 		modes: {
 			dark: true,
@@ -699,9 +728,21 @@ function defaultConfig() {
 		},
 		autoFlip: true,
 		pastel: false,
-		inferRole: true
+		inferRole: true,
+		contrastLevel: "auto"
 	};
 }
+/**
+* Validate an authored `contrastLevel`. Numbers clamp to 0–100 so a slider
+* can't produce an out-of-range level; a non-finite number throws rather than
+* silently reading as `'auto'`, which would turn a `NaN` slider value into an
+* invisible no-op.
+*/
+function normalizeContrastLevel(value) {
+	if (value === void 0 || value === "auto") return "auto";
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`glaze: contrastLevel must be a finite number 0–100 or 'auto' (got ${String(value)}).`);
+	return Math.max(0, Math.min(100, value));
+}
 let globalConfig = defaultConfig();
 /**
 * Monotonic counter incremented on every `configure()` / `resetConfig()`
@@ -739,8 +780,9 @@ function configure(config) {
 		},
 		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
 		autoFlip: config.autoFlip ?? globalConfig.autoFlip,
-		pastel: config.pastel ?? globalConfig.pastel,
-		inferRole: config.inferRole ?? globalConfig.inferRole
+		pastel: false,
+		inferRole: config.inferRole ?? globalConfig.inferRole,
+		contrastLevel: normalizeContrastLevel(config.contrastLevel ?? globalConfig.contrastLevel)
 	};
 }
 function resetConfig() {
@@ -752,9 +794,15 @@ function resetConfig() {
 * 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).
+*
+* `pastel` is instance-only: `override.pastel ?? false`, never inherited
+* from the global base.
 */
 function mergeConfig(base, override) {
-	if (!override) return base;
+	if (!override) return base.pastel === false ? base : {
+		...base,
+		pastel: false
+	};
 	return {
 		lightTone: override.lightTone !== void 0 ? override.lightTone : base.lightTone,
 		darkTone: override.darkTone !== void 0 ? override.darkTone : base.darkTone,
@@ -763,55 +811,101 @@ function mergeConfig(base, override) {
 		modes: base.modes,
 		shadowTuning: override.shadowTuning ?? base.shadowTuning,
 		autoFlip: override.autoFlip ?? base.autoFlip,
-		pastel: override.pastel ?? base.pastel,
-		inferRole: override.inferRole ?? base.inferRole
+		pastel: override.pastel ?? false,
+		inferRole: override.inferRole ?? base.inferRole,
+		contrastLevel: normalizeContrastLevel(override.contrastLevel ?? base.contrastLevel)
+	};
+}
+/**
+* Freeze `getConfig() ∪ instanceLocal ∪ exportArg` as a plain, resolve-relevant
+* override for authoring export, so restored snapshots pin these fields. Later
+* wins; nested objects (`shadowTuning`) replace wholesale. The final
+* `structuredClone` detaches tone-window / shadow objects that `mergeConfig`
+* may still share with the live global config.
+*/
+function freezeConfigForExport(instanceLocal, exportArg) {
+	const effective = mergeConfig(getConfig(), {
+		...instanceLocal,
+		...exportArg
+	});
+	const out = {
+		lightTone: effective.lightTone,
+		darkTone: effective.darkTone,
+		darkDesaturation: effective.darkDesaturation,
+		autoFlip: effective.autoFlip,
+		pastel: effective.pastel,
+		inferRole: effective.inferRole
 	};
+	if (effective.shadowTuning !== void 0) out.shadowTuning = effective.shadowTuning;
+	const authoredLevel = exportArg?.contrastLevel ?? instanceLocal?.contrastLevel;
+	if (authoredLevel !== void 0) out.contrastLevel = normalizeContrastLevel(authoredLevel);
+	return structuredClone(out);
 }
 
 //#endregion
-//#region src/format-guard.ts
-const NON_NATIVE_FORMATS = new Set(["okhsl", "okhst"]);
+//#region src/types.ts
 /**
-* Throw when a non-native Glaze color space is requested for an export that
-* emits raw CSS or non-Tasty token maps.
+* Current authoring-export schema version. Bump when the export shape
+* changes in a non-compatible way. Written on every `.export()` snapshot.
 */
-function assertNativeFormat(format, method) {
-	if (format !== void 0 && NON_NATIVE_FORMATS.has(format)) throw new Error(`glaze: ${format} output is only supported by tasty() (not a native CSS color space). Use tasty({ format: '${format}' }) or pick a native format (oklch|hsl|rgb) for ${method}().`);
+const GLAZE_EXPORT_VERSION = 1;
+
+//#endregion
+//#region src/serialize.ts
+/**
+* Authoring-export helpers: schema version, type guards, and restore
+* validation shared by `themeFrom` / `colorFrom` / `paletteFrom`.
+*/
+function isPlainObject(data) {
+	return typeof data === "object" && data !== null && !Array.isArray(data);
 }
-const SCHEME_FIELDS = [
-	{
-		field: "light",
-		modes: () => true
-	},
-	{
-		field: "dark",
-		modes: (m) => m.dark
-	},
-	{
-		field: "lightContrast",
-		modes: (m) => m.highContrast
-	},
-	{
-		field: "darkContrast",
-		modes: (m) => m.dark && m.highContrast
-	}
-];
 /**
-* Throw when `splitHue` is enabled but any exported color is not pastel.
-* Hue rotation is only clip-free when chroma is bounded by the hue-independent
-* safe chroma (`computeSafeChromaOKLCH`).
+* Reject unknown / invalid schema versions. Missing `version` is allowed
+* (legacy snapshots). Present versions must be an integer in
+* `1..=GLAZE_EXPORT_VERSION`.
 */
-function assertAllPastel(resolved, modes) {
-	const nonPastel = [];
-	for (const [name, color] of resolved) for (const { field, modes: active } of SCHEME_FIELDS) {
-		if (!active(modes)) continue;
-		if (color[field].pastel !== true) {
-			if (!nonPastel.includes(name)) nonPastel.push(name);
-			break;
-		}
-	}
-	if (nonPastel.length === 0) return;
-	throw new Error(`glaze: splitHue requires every color to be pastel (hue rotation is only clip-free when chroma is bounded by the hue-independent safe chroma). Non-pastel: ${nonPastel.join(", ")}. Set pastel: true (global or per-color) or drop splitHue.`);
+function assertExportVersion(data, factory) {
+	if (data.version === void 0) return;
+	if (typeof data.version !== "number" || !Number.isInteger(data.version) || data.version < 1) throw new Error(`${factory}: invalid "version" field — expected an integer >= 1 (got ${JSON.stringify(data.version)}).`);
+	if (data.version > GLAZE_EXPORT_VERSION) throw new Error(`${factory}: unsupported export version ${data.version} (this library supports version ${GLAZE_EXPORT_VERSION}). Upgrade @tenphi/glaze to load this snapshot.`);
+}
+/**
+* When `kind` is present, it must match the factory. Missing `kind` is
+* allowed for legacy snapshots.
+*/
+function assertExportKind(data, expected, factory) {
+	if (data.kind === void 0) return;
+	if (data.kind !== expected) throw new Error(`${factory}: expected kind "${expected}", got ${JSON.stringify(data.kind)}.`);
+}
+function hasThemeShape(data) {
+	return typeof data.hue === "number" && typeof data.saturation === "number" && !("form" in data) && !("themes" in data);
+}
+function hasColorTokenShape(data) {
+	return data.form === "value" || data.form === "structured";
+}
+function hasPaletteShape(data) {
+	return isPlainObject(data.themes) && !("form" in data) && typeof data.hue !== "number";
+}
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+function isThemeExport(data) {
+	if (!isPlainObject(data)) return false;
+	if (data.kind === "theme") return hasThemeShape(data);
+	if (data.kind !== void 0) return false;
+	return hasThemeShape(data);
+}
+/** Type guard for color-token authoring snapshots. */
+function isColorTokenExport(data) {
+	if (!isPlainObject(data)) return false;
+	if (data.kind === "color") return hasColorTokenShape(data);
+	if (data.kind !== void 0) return false;
+	return hasColorTokenShape(data);
+}
+/** Type guard for palette authoring snapshots. */
+function isPaletteExport(data) {
+	if (!isPlainObject(data)) return false;
+	if (data.kind === "palette") return hasPaletteShape(data);
+	if (data.kind !== void 0) return false;
+	return hasPaletteShape(data);
 }
 
 //#endregion
@@ -825,6 +919,61 @@ function pairHC(p) {
 function clamp(v, min, max) {
 	return Math.max(min, Math.min(max, v));
 }
+function lerp(a, b, f) {
+	return a + (b - a) * f;
+}
+/**
+* Blend fraction at/above which an un-interpolable HC pair switches from its
+* normal entry to its high-contrast one (level 50).
+*/
+const PAIR_SWITCH = .5;
+/** Blend fraction (0–1) for an authored 0–100 contrast level. */
+function levelFraction(level) {
+	return clamp(level, 0, 100) / 100;
+}
+/**
+* Manual-contrast blend fraction (0–1) for a resolved config, or `undefined`
+* in `'auto'` mode, where the normal variants take the authored normal entries
+* as-is.
+*
+* Note `contrastLevel: 0` yields `0`, not `undefined`. The two select different
+* branches, and an authored `0` is a slider position that `.export()` freezes
+* where an absent level is not — but they are not an *output* distinction: at
+* fraction 0 every interpolation returns its normal entry verbatim, so level 0
+* reproduces `'auto'` bit for bit.
+*/
+function contrastFraction(config) {
+	const level = config.contrastLevel;
+	if (typeof level !== "number" || !Number.isFinite(level)) return void 0;
+	return levelFraction(level);
+}
+/**
+* Whether the high-contrast variants are exact duplicates of the normal ones —
+* true only at `contrastLevel: 100`, where the normal passes already resolve at
+* full contrast.
+*
+* The level otherwise says nothing about high contrast: it positions the normal
+* variants, while `lightContrast` / `darkContrast` stay the true high-contrast
+* resolution at every level. This predicate marks the one level where that tier
+* carries no new information, so callers can skip the two high-contrast passes,
+* their drift checks, and the redundant output tier.
+*/
+function hcMirrorsNormal(config) {
+	return contrastFraction(config) === 1;
+}
+/**
+* A numeric HC pair at a blend fraction (shadow `intensity`, mix `value`).
+*
+* The endpoints return the authored entry *by identity* rather than through
+* float arithmetic — `a + (b - a) * 1` is not bit-exactly `b` in IEEE 754, and
+* levels 0 / 100 must reproduce the classic output exactly.
+*/
+function numberAt(p, f) {
+	if (!Array.isArray(p)) return p;
+	if (f <= 0) return p[0];
+	if (f >= 1) return p[1];
+	return lerp(p[0], p[1], f);
+}
 /** Whether a tone value is an extreme keyword (`'max'` / `'min'`). */
 function isExtremeTone(value) {
 	return value === "max" || value === "min";
@@ -869,6 +1018,34 @@ function parseToneValue(value) {
 	};
 }
 /**
+* Parse an authored tone pair at a manual-contrast blend fraction, returning
+* the same normalized shape as {@link parseToneValue}.
+*
+* Same-kind numeric pairs interpolate their magnitude — absolute tones
+* (`[30, 20]` → 25 at level 50) and relative deltas (`['+10', '+20']` → +15).
+* Everything else is un-interpolable and switches at {@link PAIR_SWITCH}:
+* extremes carry no magnitude, and a mixed-kind pair would change *which*
+* resolver branch runs mid-ramp (absolute remap vs. extreme-against-base vs.
+* base-anchored delta), putting a discontinuity at level 100 — exactly where
+* the output must stay bit-exact.
+*
+* Returns a parsed struct rather than a `ToneValue` so a blended relative
+* delta never round-trips through a `'+15.5'` string, and so `kind` — which
+* selects the resolver branch — cannot drift.
+*/
+function parseToneValueAt(p, f) {
+	if (!Array.isArray(p)) return parseToneValue(p);
+	if (f <= 0) return parseToneValue(p[0]);
+	if (f >= 1) return parseToneValue(p[1]);
+	const normal = parseToneValue(p[0]);
+	const hc = parseToneValue(p[1]);
+	if (normal.kind === hc.kind && normal.kind !== "extreme") return {
+		kind: normal.kind,
+		value: lerp(normal.value, hc.value, f)
+	};
+	return f < PAIR_SWITCH ? normal : hc;
+}
+/**
 * Compute the effective hue for a color, given the theme seed hue
 * and an optional per-color hue override.
 */
@@ -904,7 +1081,9 @@ function isAbsoluteTone(tone) {
 * - 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.
+*   tone range,
+* - the scheme tone window, including the high-contrast bypass and its
+*   continuous generalization under a manual contrast level.
 *
 * See `docs/okhst.md` for the full specification and the calibrated
 * default constants.
@@ -967,7 +1146,11 @@ function okhslToOkhst(c) {
 }
 /**
 * 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.
+* it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect —
+* `s` and `l` on the same 0–1 factor scale, so `const { h, s, l } =
+* variantToOkhsl(v)` destructures straight into `formatOkhsl` / `formatRgb` /
+* `okhslToLinearSrgb` with no rescaling. `alpha` stays on the variant; use
+* `glaze.format(v, format)` for a string that carries it.
 */
 function variantToOkhsl(v) {
 	return {
@@ -1003,7 +1186,12 @@ function normalizeToneWindow(win) {
 /**
 * 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.
+* - Under a manual `contrastLevel`, each endpoint is interpolated toward that
+*   full range: light `10 → 0` / `100 → 100`, dark `15 → 0` / `95 → 100`. The
+*   endpoints are exact — level 0 returns the configured window and level 100
+*   the same literal the HC branch returns.
+* - `false` (= "no clamping") is treated as `[0, 100]` with the reference eps,
+*   and is therefore level-invariant.
 */
 function activeWindow(isHighContrast, kind, config) {
 	const win = normalizeToneWindow(kind === "dark" ? config.darkTone : config.lightTone);
@@ -1012,7 +1200,18 @@ function activeWindow(isHighContrast, kind, config) {
 		hi: 100,
 		eps: win.eps
 	};
-	return win;
+	const f = contrastFraction(config);
+	if (f === void 0 || f <= 0) return win;
+	if (f >= 1) return {
+		lo: 0,
+		hi: 100,
+		eps: win.eps
+	};
+	return {
+		lo: lerp(win.lo, 0, f),
+		hi: lerp(win.hi, 100, f),
+		eps: win.eps
+	};
 }
 /**
 * Remap an authored tone (0–100) into a scheme window and return the final
@@ -1036,6 +1235,9 @@ function remapToneToLightness(authorTone, win) {
 * 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.
+*
+* A manual `contrastLevel` widens the window continuously (see
+* `activeWindow`); inversion is unaffected.
 */
 function mapToneForScheme(authorTone, mode, isDark, isHighContrast, config) {
 	if (mode === "static") return clamp(authorTone, 0, 100);
@@ -1050,7 +1252,8 @@ function mapSaturationDark(s, mode, config) {
 /**
 * 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).
+* endpoints (HC bypasses to full range, a manual `contrastLevel` widens
+* toward it — see `activeWindow`).
 */
 function schemeToneRange(isDark, mode, isHighContrast, config) {
 	if (mode === "static") return [0, 1];
@@ -1059,147 +1262,491 @@ function schemeToneRange(isDark, mode, isHighContrast, config) {
 }
 
 //#endregion
-//#region src/contrast-solver.ts
+//#region src/color-value.ts
 /**
-* 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.
+* Parsing and validation for `GlazeColorValue` — the literal color forms.
 *
-* 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`.
+* Hex, the CSS color functions Glaze emits, and the four value-object shapes all
+* land here and come out as OKHSL. Split out of `color-token.ts` so both
+* consumers can reach it without an import cycle: standalone `glaze.color()`
+* tokens build on it, and the resolver needs it for a theme color's `from`. It
+* depends on nothing but the color math, which is what keeps that true.
 */
-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.
+* 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 resolveApcaTarget(value) {
-	if (typeof value === "number") return Math.abs(value);
-	return APCA_PRESETS[value];
-}
-const CONTRAST_PRESETS = {
-	AA: 4.5,
-	AAA: 7,
-	"AA-large": 3,
-	"AAA-large": 4.5
-};
-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;
+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);
 }
 /**
-* 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.
+* 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 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"
+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 {
-		metric: "wcag",
-		target: resolveMinContrast(pickPair(spec.wcag, isHighContrast))
+		components,
+		hadAlpha: false
 	};
 }
-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;
+function warnDroppedAlpha(input) {
+	console.warn(`glaze: alpha component dropped from "${input}" (standalone color has no opacity field).`);
 }
-const CACHE_SIZE = 512;
-const luminanceCache = /* @__PURE__ */ new Map();
-const cacheOrder = [];
-/**
-* 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 = metricLuminance(metric, okhslToLinearSrgb(h, s, fromTone(tRounded * 100, REF_EPS), pastel));
-	if (luminanceCache.size >= CACHE_SIZE) {
-		const evict = cacheOrder.shift();
-		luminanceCache.delete(evict);
+function parseColorString(input) {
+	if (input.startsWith("#")) {
+		const parsed = parseHexAlpha(input);
+		if (!parsed) throw new Error(`glaze: invalid hex color "${input}".`);
+		if (parsed.alpha !== void 0) warnDroppedAlpha(input);
+		const [h, s, l] = srgbToOkhsl(parsed.rgb);
+		return {
+			h,
+			s,
+			l
+		};
 	}
-	luminanceCache.set(key, y);
-	cacheOrder.push(key);
-	return y;
-}
-/**
-* 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 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
+	const m = input.match(COLOR_FN_RE);
+	if (!m) throw new Error(`glaze: unsupported color string "${input}".`);
+	const fn = m[1].toLowerCase();
+	const { components, hadAlpha } = splitColorBody(m[2].trim());
+	if (hadAlpha) warnDroppedAlpha(input);
+	if (components.length !== 3) throw new Error(`glaze: expected 3 components in "${input}".`);
+	switch (fn) {
+		case "rgb":
+		case "rgba": {
+			const [h, s, l] = srgbToOkhsl([
+				parseNumberOrPercent(components[0], 255) / 255,
+				parseNumberOrPercent(components[1], 255) / 255,
+				parseNumberOrPercent(components[2], 255) / 255
+			]);
+			return {
+				h,
+				s,
+				l
+			};
+		}
+		case "hsl":
+		case "hsla": {
+			const [oh, os, ol] = srgbToOkhsl(hslToSrgb(parseFloat(components[0]), parseNumberOrPercent(components[1], 1), parseNumberOrPercent(components[2], 1)));
+			return {
+				h: oh,
+				s: os,
+				l: ol
+			};
+		}
+		case "okhsl": return {
+			h: parseFloat(components[0]),
+			s: parseNumberOrPercent(components[1], 1),
+			l: parseNumberOrPercent(components[2], 1)
+		};
+		case "okhst": return okhstToOkhsl({
+			h: parseFloat(components[0]),
+			s: parseNumberOrPercent(components[1], 1),
+			t: parseNumberOrPercent(components[2], 1)
+		});
+		case "oklch": {
+			const L = parseNumberOrPercent(components[0], 1);
+			const C = parseNumberOrPercent(components[1], .4);
+			const hRad = parseFloat(components[2]) * Math.PI / 180;
+			const [h, s, l] = oklabToOkhsl([
+				L,
+				C * Math.cos(hRad),
+				C * Math.sin(hRad)
+			]);
+			return {
+				h,
+				s,
+				l
+			};
+		}
+	}
+	throw new Error(`glaze: unsupported color function "${fn}".`);
+}
+/**
+* Validate a user-supplied `OkhslColor`. Catches the common 0-100 vs 0-1
+* confusion (the structured form uses 0-100, OKHSL objects use 0-1).
+*/
+function validateOkhslColor(value) {
+	const { h, s, l } = value;
+	if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(l)) throw new Error("glaze.color: OkhslColor h/s/l must be finite numbers.");
+	if (s > 1.5 || l > 1.5) throw new Error("glaze.color: OkhslColor s/l must be in 0–1 range. Did you mean the structured form { hue, saturation, tone } (which uses 0–100)?");
+}
+/** Validate a user-supplied `{ r, g, b }` object in 0–255. */
+function validateRgbColor(value) {
+	for (const key of [
+		"r",
+		"g",
+		"b"
+	]) {
+		const n = value[key];
+		if (!Number.isFinite(n) || n < 0 || n > 255) throw new Error(`glaze.color: RgbColor ${key} must be a finite number in 0–255 (got ${n}).`);
+	}
+}
+/** Validate a user-supplied `{ l, c, h }` OKLCh object. */
+function validateOklchColor(value) {
+	const { l, c, h } = value;
+	if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h)) throw new Error("glaze.color: OklchColor l/c/h must be finite numbers.");
+	if (l > 1.5 || c > 1.5) throw new Error("glaze.color: OklchColor l/c must be in 0–1 range (matching oklch() strings).");
+}
+function oklchComponentsToOkhsl(l, c, hDeg) {
+	const hRad = hDeg * Math.PI / 180;
+	const [h, s, outL] = oklabToOkhsl([
+		l,
+		c * Math.cos(hRad),
+		c * Math.sin(hRad)
+	]);
+	return {
+		h,
+		s,
+		l: outL
+	};
+}
+function isRgbColorObject(value) {
+	return "r" in value && "g" in value && "b" in value;
+}
+function isOklchColorObject(value) {
+	return "c" in value && "l" in value && "h" in value;
+}
+function isOkhstColorObject(value) {
+	return "t" in value && "h" in value && "s" in value;
+}
+/** Validate a user-supplied `{ h, s, t }` OKHST object (s/t in 0–1). */
+function validateOkhstColor(value) {
+	const { h, s, t } = value;
+	if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(t)) throw new Error("glaze.color: OkhstColor h/s/t must be finite numbers.");
+	if (s > 1.5 || t > 1.5) throw new Error("glaze.color: OkhstColor s/t must be in 0–1 range. Did you mean the structured form { hue, saturation, tone } (which uses 0–100)?");
+}
+/**
+* Extract an OKHSL color from any `GlazeColorValue` form. Also used by
+* `glaze.shadow()` so all shadow inputs (hex, color functions, OKHSL,
+* literal objects) go through one parser.
+*/
+function extractOkhslFromValue(value) {
+	if (typeof value === "string") return parseColorString(value);
+	if (Array.isArray(value)) throw new Error("glaze.color: RGB tuple [r, g, b] is no longer supported — use { r, g, b } instead.");
+	if (isRgbColorObject(value)) {
+		validateRgbColor(value);
+		const [h, s, l] = srgbToOkhsl([
+			value.r / 255,
+			value.g / 255,
+			value.b / 255
+		]);
+		return {
+			h,
+			s,
+			l
+		};
+	}
+	if (isOklchColorObject(value)) {
+		validateOklchColor(value);
+		return oklchComponentsToOkhsl(value.l, value.c, value.h);
+	}
+	if (isOkhstColorObject(value)) {
+		validateOkhstColor(value);
+		return okhstToOkhsl(value);
+	}
+	validateOkhslColor(value);
+	return value;
+}
+
+//#endregion
+//#region src/format-guard.ts
+const NON_NATIVE_FORMATS = new Set(["okhsl", "okhst"]);
+/**
+* Throw when a non-native Glaze color space is requested for an export that
+* emits raw CSS or non-Tasty token maps.
+*/
+function assertNativeFormat(format, method) {
+	if (format !== void 0 && NON_NATIVE_FORMATS.has(format)) throw new Error(`glaze: ${format} output is only supported by tasty() (not a native CSS color space). Use tasty({ format: '${format}' }) or pick a native format (oklch|hsl|rgb) for ${method}().`);
+}
+const SCHEME_FIELDS = [
+	{
+		field: "light",
+		modes: () => true
+	},
+	{
+		field: "dark",
+		modes: (m) => m.dark
+	},
+	{
+		field: "lightContrast",
+		modes: (m) => m.highContrast
+	},
+	{
+		field: "darkContrast",
+		modes: (m) => m.dark && m.highContrast
+	}
+];
+/**
+* Throw when `splitHue` is enabled but any exported color is not pastel.
+* Hue rotation is only clip-free when chroma is bounded by the hue-independent
+* safe chroma (`computeSafeChromaOKLCH`).
+*/
+function assertAllPastel(resolved, modes) {
+	const nonPastel = [];
+	for (const [name, color] of resolved) for (const { field, modes: active } of SCHEME_FIELDS) {
+		if (!active(modes)) continue;
+		if (color[field].pastel !== true) {
+			if (!nonPastel.includes(name)) nonPastel.push(name);
+			break;
+		}
+	}
+	if (nonPastel.length === 0) return;
+	throw new Error(`glaze: splitHue requires every color to be pastel (hue rotation is only clip-free when chroma is bounded by the hue-independent safe chroma). Non-pastel: ${nonPastel.join(", ")}. Set pastel: true (per-theme, per-token, or per-color) or drop splitHue.`);
+}
+
+//#endregion
+//#region src/contrast-solver.ts
+/**
+* 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.
+*
+* Public API: `findToneForContrast`, `findValueForMixContrast`,
+* `resolveMinContrast`, `resolveContrastForMode`, `resolveContrastForLevel`,
+* `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
+};
+/**
+* APCA-W3 "Enhanced Level" delta added to a bare APCA target in high-contrast
+* mode when no explicit HC value is provided (analogous to WCAG AAA over AA).
+* Only applied when neither the outer `contrast` pair nor the inner `apca`
+* pair carries an explicit HC entry.
+*/
+const APCA_HC_ENHANCEMENT = 15;
+/** Upper bound for an APCA Lc target after HC enhancement. */
+const APCA_MAX_LC = 106;
+/**
+* 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,
+	"AA-large": 3,
+	"AAA-large": 4.5
+};
+/**
+* WCAG high-contrast auto-promotion (analog of APCA's Enhanced Level). A bare
+* AA / AA-large preset is promoted to its spec-defined "Enhanced" successor
+* (SC 1.4.3 → SC 1.4.6) in high-contrast mode. AAA / AAA-large are already
+* the top WCAG tier and are left unchanged. Bare numeric targets have no
+* defined successor tier and are also left unchanged. An explicit HC value
+* (outer or inner pair) always overrides.
+*/
+const WCAG_HC_PROMOTION = {
+	AA: "AAA",
+	"AA-large": "AAA-large"
+};
+function resolveMinContrast(value) {
+	if (typeof value === "number") return Math.max(1, value);
+	return CONTRAST_PRESETS[value];
+}
+/**
+* Resolve a WCAG target (number or preset) for a mode, applying the
+* high-contrast auto-promotion when `explicitHC` is false and the value is an
+* AA-family preset. Bare numbers and AAA-family presets pass through.
+*/
+function resolveWcagTarget(value, isHighContrast, explicitHC) {
+	if (typeof value === "number") return resolveMinContrast(value);
+	if (isHighContrast && !explicitHC) {
+		const promoted = WCAG_HC_PROMOTION[value];
+		if (promoted !== void 0) return resolveMinContrast(promoted);
+	}
+	return resolveMinContrast(value);
+}
+function pickPair(p, isHighContrast) {
+	return Array.isArray(p) ? isHighContrast ? p[1] : p[0] : p;
+}
+/**
+* The metric a single `ContrastSpec` measures in. Bare numbers and WCAG
+* presets are `'wcag'`; only an `{ apca }` object is `'apca'`.
+*/
+function contrastMetricOf(spec) {
+	return typeof spec === "object" && "apca" in spec ? "apca" : "wcag";
+}
+/**
+* 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.
+*
+* `outerExplicitHC` indicates whether the caller selected this `spec` from an
+* explicit high-contrast entry of the outer `contrast` pair. Together with the
+* inner metric pair, it decides whether the HC auto-enhancement fires:
+*  - APCA: +15 Lc "Enhanced Level" boost when neither level is explicit.
+*  - WCAG: AA → AAA / AA-large → AAA-large promotion (SC 1.4.3 → 1.4.6) when
+*    neither level is explicit. AAA-family presets and bare numbers are left
+*    unchanged (AAA is the top WCAG tier).
+* Defaults to `false` (correct for direct callers, which pass a single
+* selected spec rather than an outer pair).
+*/
+function resolveContrastForMode(spec, isHighContrast, polarity, outerExplicitHC) {
+	if (typeof spec === "number" || typeof spec === "string") return {
+		metric: "wcag",
+		target: resolveWcagTarget(spec, isHighContrast, !!outerExplicitHC)
+	};
+	if ("apca" in spec) {
+		const baseTarget = resolveApcaTarget(pickPair(spec.apca, isHighContrast));
+		const innerExplicitHC = Array.isArray(spec.apca);
+		return {
+			metric: "apca",
+			target: isHighContrast && !outerExplicitHC && !innerExplicitHC ? Math.min(baseTarget + APCA_HC_ENHANCEMENT, APCA_MAX_LC) : baseTarget,
+			polarity: polarity ?? "fg"
+		};
+	}
+	const innerExplicitHC = Array.isArray(spec.wcag);
+	return {
+		metric: "wcag",
+		target: resolveWcagTarget(pickPair(spec.wcag, isHighContrast), isHighContrast, !!outerExplicitHC || innerExplicitHC)
+	};
+}
+/**
+* Resolve a `contrast` spec — including its outer `[normal, highContrast]`
+* pair — at a manual contrast `level` (0–100), by resolving both ends and
+* interpolating the numeric target.
+*
+* Level 0 / 100 delegate verbatim to {@link resolveContrastForMode}, so the
+* endpoints are bit-identical to classic normal / high-contrast resolution.
+* Resolving each end fully first also means every rule that governs the
+* escalation still applies at both ends for free: preset mapping, the
+* `APCA_MAX_LC` clamp, and the explicit-HC suppression that cancels the
+* `AA → AAA` promotion and the `+15 Lc` enhancement.
+*
+* Throws when the two ends measure in different metrics — a WCAG ratio and an
+* APCA Lc live on different scales, so there is no target between them. Such a
+* pair is rejected at authoring time by `validateColorDefs`; this is the guard
+* for direct callers.
+*/
+function resolveContrastForLevel(spec, level, polarity) {
+	const outerExplicitHC = Array.isArray(spec);
+	const f = levelFraction(level);
+	const normal = resolveContrastForMode(pairNormal(spec), false, polarity, outerExplicitHC);
+	if (f <= 0) return normal;
+	const hc = resolveContrastForMode(pairHC(spec), true, polarity, outerExplicitHC);
+	if (f >= 1) return hc;
+	if (normal.metric !== hc.metric) throw new Error(`glaze: a "contrast" pair cannot switch metric between its normal (${normal.metric}) and high-contrast (${hc.metric}) entry — the two targets are on different scales. Use one metric for both entries.`);
+	return {
+		...normal,
+		target: lerp(normal.target, hc.target, f)
+	};
+}
+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 = [];
+/**
+* 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 = metricLuminance(metric, okhslToLinearSrgb(h, s, fromTone(tRounded * 100, REF_EPS), pastel));
+	if (luminanceCache.size >= CACHE_SIZE) {
+		const evict = cacheOrder.shift();
+		luminanceCache.delete(evict);
+	}
+	luminanceCache.set(key, y);
+	cacheOrder.push(key);
+	return y;
+}
+/**
+* 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 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) {
@@ -1268,7 +1815,7 @@ function wcagToneSeed(yBase, target, darker) {
 	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 { lum, yBase, metric, target, searchTarget, lo, hi, searchAnchor, distanceAnchor, epsilon, maxIterations, flip, preferInitial, 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;
@@ -1279,14 +1826,20 @@ function solveNearestContrast(opts) {
 	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
-		};
+		if (initialResult.met && oppositeResult?.met) {
+			if (preferInitial) return {
+				...initialResult,
+				lower: initialIsLower
+			};
+			return Math.abs(initialResult.pos - distanceAnchor) <= Math.abs(oppositeResult.pos - distanceAnchor) ? {
+				...initialResult,
+				lower: initialIsLower
+			} : {
+				...oppositeResult,
+				lower: !initialIsLower,
+				flipped: true
+			};
+		}
 		if (initialResult.met) return {
 			...initialResult,
 			lower: initialIsLower
@@ -1349,6 +1902,7 @@ function findToneForContrast(options) {
 		epsilon,
 		maxIterations,
 		flip: options.flip ?? false,
+		preferInitial: options.preferInitial ?? false,
 		initialIsLower: initialIsDarker,
 		polarity
 	});
@@ -1399,6 +1953,7 @@ function findValueForMixContrast(options) {
 		epsilon,
 		maxIterations,
 		flip: options.flip ?? false,
+		preferInitial: false,
 		initialIsLower,
 		polarity
 	});
@@ -1600,6 +2155,32 @@ function computeShadow(bg, fg, intensity, tuning) {
 * resolver runs. `topoSort` orders defs so each color is processed after
 * its base / bg / fg / target dependencies.
 */
+/**
+* Does this color sit at an absolute tone — either authored, or carried by a
+* `from` value? That is the test for "root" (placed on its own) as opposed to
+* "dependent" (placed relative to a base), and it is what lets a bare
+* `{ from: '#2F5BFF' }` stand as a complete color definition.
+*/
+function hasAbsoluteTone(def) {
+	if (def.tone === void 0) return def.from !== void 0;
+	return isAbsoluteTone(def.tone);
+}
+/**
+* Reject a `contrast` pair whose two entries measure in different metrics.
+*
+* A WCAG ratio and an APCA Lc are different scales, so `[4.5, { apca: 75 }]`
+* asks one color to be judged two incompatible ways. There is no target between
+* them for a manual `contrastLevel` to resolve, and even in `'auto'` mode the
+* two variants become incomparable. Pick one metric and pair its values
+* instead: `{ wcag: [4.5, 7] }` or `{ apca: [60, 90] }`.
+*/
+function assertConsistentContrastMetric(name, contrast) {
+	if (contrast === void 0 || !Array.isArray(contrast)) return;
+	const normal = contrastMetricOf(pairNormal(contrast));
+	const hc = contrastMetricOf(pairHC(contrast));
+	if (normal === hc) return;
+	throw new Error(`glaze: color "${name}" has a "contrast" pair that switches metric (${normal} → ${hc}). A WCAG ratio and an APCA Lc are different scales; use one metric for both entries, e.g. { ${normal}: [normal, highContrast] }.`);
+}
 function validateColorDefs(defs, externalBases) {
 	const localNames = new Set(Object.keys(defs));
 	const allNames = new Set([...localNames, ...externalBases ? externalBases.keys() : []]);
@@ -1618,14 +2199,21 @@ function validateColorDefs(defs, externalBases) {
 			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.`);
+			assertConsistentContrastMetric(name, def.contrast);
 			continue;
 		}
 		const regDef = def;
+		assertConsistentContrastMetric(name, regDef.contrast);
+		if (regDef.from !== void 0) try {
+			extractOkhslFromValue(regDef.from);
+		} catch (error) {
+			throw new Error(`glaze: color "${name}" has an invalid "from" value. ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
 		if (regDef.contrast !== void 0 && !regDef.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
 		if (regDef.tone !== void 0 && !isAbsoluteTone(regDef.tone) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "tone" without "base".`);
 		if (regDef.base && !allNames.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
 		if (regDef.base && localNames.has(regDef.base) && isShadowDef(defs[regDef.base])) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a shadow color.`);
-		if (!isAbsoluteTone(regDef.tone) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "tone" (root) or "base" (dependent).`);
+		if (!hasAbsoluteTone(regDef) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "tone" (root), "from" (a literal color), 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();
@@ -1737,9 +2325,14 @@ function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase
 * 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.
+* turns a `ColorMap` into a fully resolved `ResolvedColor` per name. A manual
+* `contrastLevel` interpolates the authored HC pairs, tone window, and contrast
+* targets at that level for the two *normal* passes only; the high-contrast
+* passes bypass the level entirely, so the high-contrast slots are the same
+* values `'auto'` resolves. At level 100 the normal passes already are the
+* high-contrast ones, so the solver drops to two passes (light → dark) and
+* mirrors the slots. 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
@@ -1826,109 +2419,212 @@ function resolveRoleInMap(name, def, defs, inferRole, roles) {
 function resolveRole(name, def, ctx) {
 	return resolveRoleInMap(name, def, ctx.defs, ctx.config.inferRole, ctx.roles);
 }
-function resolveContrastSpec(spec, isHighContrast, polarity) {
-	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast, polarity);
+function resolveContrastSpec(spec, isHighContrast, config, polarity) {
+	if (!isHighContrast && contrastFraction(config) !== void 0) return resolveContrastForLevel(spec, config.contrastLevel, polarity);
+	const outerExplicitHC = Array.isArray(spec);
+	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast, polarity, outerExplicitHC);
+}
+/**
+* The authored tone for this pass: the pair's own entry in `'auto'` mode, or
+* the manual-level interpolation. Returns the parsed struct so the `kind` —
+* which selects the branch in `resolveDependentColor` — is fixed here once.
+*/
+function passTone(tone, isHighContrast, config) {
+	const f = contrastFraction(config);
+	return f === void 0 || isHighContrast ? parseToneValue(isHighContrast ? pairHC(tone) : pairNormal(tone)) : parseToneValueAt(tone, f);
+}
+/** The authored numeric pair for this pass (shadow `intensity`, mix `value`). */
+function passNumber(p, isHighContrast, config) {
+	const f = contrastFraction(config);
+	if (f === void 0 || isHighContrast) return isHighContrast ? pairHC(p) : pairNormal(p);
+	return numberAt(p, f);
 }
 /**
 * 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.
+* When `flip` is on and `base + delta` falls outside `[0, 100]`, try mirroring
+* the delta to the other side of the base. If the mirrored target is also out
+* of range, keep the original delta so the caller clamps on the authored side.
+* 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;
+	const mirrored = baseTone - delta;
+	if (mirrored >= 0 && mirrored <= 100) return -delta;
+	return delta;
+}
+/**
+* Dark position for an extreme tone (`'max'` / `'min'`) anchored to a base.
+*
+* A windowed dark remap compresses the base→extreme span, so the pair loses
+* contrast in dark. Instead, measure the tone shift the light scheme applied
+* between the base and the extreme, then replay it against the base's dark
+* tone: `auto` mirrors the sign (both ends invert), `fixed` keeps it. The
+* result is clamped to `[0, 100]` only — crossing the dark tone window is
+* intended, since the author asked for the extreme.
+*/
+function extremeDarkTone(authorTone, mode, isHighContrast, baseResolved, config) {
+	const extremeLightTone = mapToneForScheme(authorTone, mode, false, isHighContrast, config);
+	const lightBase = getSchemeVariant(baseResolved, false, isHighContrast);
+	const darkBase = getSchemeVariant(baseResolved, true, isHighContrast);
+	const shift = extremeLightTone - lightBase.t * 100;
+	return clamp(darkBase.t * 100 + (mode === "auto" ? -shift : shift), 0, 100);
+}
+/**
+* Hue, absolute saturation (0–1) and tone (0–100) read off a color def's `from`.
+*
+* Deliberately not memoized. Keying a cache on the def object looks free — a
+* resolve reads this a handful of times per color — but defs are stored by
+* reference, so mutating one in place and re-setting it would invalidate the
+* theme's own cache while a def-keyed cache quietly served the old color. The
+* parse is a few microseconds against a resolve that is already cached; that is
+* not a trade worth a staleness bug.
+*/
+function fromSeed(def) {
+	if (def.from === void 0) return void 0;
+	const { h, s, l } = extractOkhslFromValue(def.from);
+	return {
+		hue: h,
+		saturation: s,
+		tone: toTone(l)
+	};
 }
-function resolveRootColor(def, isHighContrast) {
-	const rawT = def.tone;
+/**
+* The config this color resolves against.
+*
+* A `from` color carries a literal value, so its light variant has to survive
+* the light tone window intact — hence a local `lightTone: false`, the same
+* default the value-shorthand form of `glaze.color()` applies. Only the light
+* window is dropped: dark and high contrast keep theirs, because that is where
+* the color is expected to adapt.
+*/
+function configForColor(def, config) {
+	if (def.from === void 0) return config;
 	return {
-		authorTone: clamp(parseToneValue(isHighContrast ? pairHC(rawT) : pairNormal(rawT)).value, 0, 100),
-		satFactor: clamp(def.saturation ?? 1, 0, 1)
+		...config,
+		lightTone: false
 	};
 }
-function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue, polarity, effectivePastel) {
+function resolveRootColor(def, isHighContrast, config) {
+	if (def.tone === void 0) return clamp(fromSeed(def).tone, 0, 100);
+	return clamp(passTone(def.tone, isHighContrast, config).value, 0, 100);
+}
+/**
+* Effective hue and saturation for one color in one scheme.
+*
+* Dark schemes read the dark seed pair and the color's `darkHue` /
+* `darkSaturation`, each falling back to its light counterpart. An explicit
+* dark saturation — on the seed or the def — is taken literally; the global
+* `darkDesaturation` reduction applies only when neither is authored.
+* `mode: 'static'` pins one value across every scheme, so it skips all of it.
+*
+* Shared by `resolveColorForScheme` (the emitted variant) and
+* `resolveDependentColor` (the contrast solver's inputs) so the solver always
+* measures the color it is actually going to produce.
+*/
+function resolveChannels(def, ctx, isDark) {
+	const mode = def.mode ?? "auto";
+	const satFactor = clamp(def.saturation ?? 1, 0, 1);
+	const seed = fromSeed(def);
+	const fromHue = seed !== void 0 && def.hue === void 0 ? seed.hue : void 0;
+	const fromSaturation = seed !== void 0 && def.saturation === void 0 ? seed.saturation : void 0;
+	if (!isDark || mode === "static") return {
+		hue: fromHue ?? resolveEffectiveHue(ctx.hue, def.hue),
+		saturation: fromSaturation ?? clamp(satFactor * ctx.saturation / 100, 0, 1)
+	};
+	const darkSeedSaturation = ctx.darkSaturation ?? ctx.saturation;
+	const darkFactor = clamp(def.darkSaturation ?? satFactor, 0, 1);
+	const fromDark = fromSaturation !== void 0 && def.darkSaturation === void 0;
+	const raw = fromDark ? fromSaturation : darkFactor * darkSeedSaturation / 100;
+	const explicitDark = fromDark ? false : def.darkSaturation !== void 0 || ctx.darkSaturation !== void 0;
+	return {
+		hue: fromHue !== void 0 && def.darkHue === void 0 ? fromHue : resolveEffectiveHue(ctx.darkHue ?? ctx.hue, def.darkHue ?? def.hue),
+		saturation: clamp(explicitDark ? raw : mapSaturationDark(raw, mode, ctx.config), 0, 1)
+	};
+}
+function resolveDependentColor(name, def, ctx, isHighContrast, isDark, channels, 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 flip = def.autoFlip ?? ctx.config.autoFlip;
 	const pastel = effectivePastel;
+	const config = configForColor(def, ctx.config);
 	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
 	const baseTone = baseVariant.t * 100;
 	let preferredTone;
-	const rawTone = def.tone;
+	let isExtreme = false;
+	const seed = fromSeed(def);
+	const rawTone = def.tone ?? (seed !== void 0 ? seed.tone : void 0);
 	if (rawTone === void 0) preferredTone = baseTone;
 	else {
-		const parsed = parseToneValue(isHighContrast ? pairHC(rawTone) : pairNormal(rawTone));
+		const parsed = passTone(rawTone, isHighContrast, config);
 		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);
+			preferredTone = mapToneForScheme(clamp(baseLightTone + applyToneFlip(parsed.value, baseLightTone, flip), 0, 100), "auto", true, isHighContrast, config);
 		} else preferredTone = clamp(baseTone + applyToneFlip(parsed.value, baseTone, flip), 0, 100);
-		else preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, ctx.config);
+		else {
+			isExtreme = parsed.kind === "extreme";
+			if (isExtreme && isDark && mode !== "static") preferredTone = extremeDarkTone(parsed.value, mode, isHighContrast, baseResolved, config);
+			else preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, config);
+		}
 	}
 	const rawContrast = def.contrast;
 	if (rawContrast !== void 0) {
-		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast, polarity);
-		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config) : satFactor * ctx.saturation / 100;
+		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast, config, polarity);
 		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);
+		const preferredRange = isExtreme ? [0, 1] : schemeToneRange(isDark, mode, isHighContrast, 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]),
+		const solve = {
+			hue: channels.hue,
+			saturation: channels.saturation,
+			preferredTone: clamp(preferredTone / 100, preferredRange[0], preferredRange[1]),
 			baseLinearRgb,
-			contrast: resolvedContrast,
 			toneRange: [0, 1],
-			initialDirection,
 			flip,
 			pastel
+		};
+		const level = isHighContrast ? void 0 : contrastFraction(config);
+		let preferInitial = false;
+		if (level !== void 0 && level > 0 && level < 1) {
+			initialDirection = findToneForContrast({
+				...solve,
+				contrast: resolveContrastForLevel(rawContrast, level < PAIR_SWITCH ? 0 : 100, polarity),
+				initialDirection
+			}).tone * 100 < baseTone ? "darker" : "lighter";
+			preferInitial = true;
+		}
+		const result = findToneForContrast({
+			...solve,
+			contrast: resolvedContrast,
+			initialDirection,
+			preferInitial
 		});
 		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, resolvedContrast, result.contrast);
-		return {
-			tone: result.tone * 100,
-			satFactor
-		};
+		return result.tone * 100;
 	}
-	return {
-		tone: clamp(preferredTone, 0, 100),
-		satFactor
-	};
+	return clamp(preferredTone, 0, 100);
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
 	if (isMixDef(def)) return resolveMixForScheme(name, def, ctx, isDark, isHighContrast);
 	const regDef = def;
 	const mode = regDef.mode ?? "auto";
-	const isRoot = isAbsoluteTone(regDef.tone) && !regDef.base;
-	const effectiveHue = resolveEffectiveHue(ctx.hue, regDef.hue);
+	const isRoot = hasAbsoluteTone(regDef) && !regDef.base;
+	const channels = resolveChannels(regDef, ctx, isDark);
 	const polarity = roleToPolarity(resolveRole(name, def, ctx));
 	const pastel = regDef.pastel ?? ctx.config.pastel;
-	let finalTone;
-	let satFactor;
-	if (isRoot) {
-		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, polarity, pastel);
-		finalTone = dep.tone;
-		satFactor = dep.satFactor;
-	}
-	const baseSat = satFactor * ctx.saturation / 100;
-	const finalSat = isDark ? mapSaturationDark(baseSat, mode, ctx.config) : baseSat;
-	const toneFraction = clamp(finalTone / 100, 0, 1);
+	const config = configForColor(regDef, ctx.config);
+	const finalTone = isRoot ? mapToneForScheme(resolveRootColor(regDef, isHighContrast, config), mode, isDark, isHighContrast, config) : resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, channels, polarity, pastel);
 	return {
-		h: effectiveHue,
-		s: clamp(finalSat, 0, 1),
-		t: toneFraction,
+		h: channels.hue,
+		s: channels.saturation,
+		t: clamp(finalTone / 100, 0, 1),
 		alpha: regDef.opacity ?? 1,
 		pastel
 	};
@@ -1937,7 +2633,7 @@ function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
 	const bgVariant = toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.bg), isDark, isHighContrast));
 	let fgVariant;
 	if (def.fg) fgVariant = toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast));
-	const intensity = isHighContrast ? pairHC(def.intensity) : pairNormal(def.intensity);
+	const intensity = passNumber(def.intensity, isHighContrast, ctx.config);
 	const tuning = resolveShadowTuning(def.tuning, ctx.config.shadowTuning);
 	return {
 		...toToneVariant(computeShadow(bgVariant, fgVariant, intensity, tuning)),
@@ -1968,6 +2664,27 @@ function linearSrgbLerp(base, target, t) {
 		base[2] + (target[2] - base[2]) * t
 	];
 }
+/** Gamma-encoded sRGB clamped to the display gamut — what a browser paints. */
+function toDisplayGamma(rgb) {
+	return [
+		clamp(sRGBLinearToGamma(rgb[0]), 0, 1),
+		clamp(sRGBLinearToGamma(rgb[1]), 0, 1),
+		clamp(sRGBLinearToGamma(rgb[2]), 0, 1)
+	];
+}
+/**
+* Browser alpha compositing: `source-over` interpolates the gamma-encoded
+* channels, not linear light (50% black over white paints `#808080`).
+* Takes display-gamma inputs and returns the composite as linear sRGB for
+* the luminance pipeline.
+*/
+function compositeOverGamma(baseGamma, targetGamma, alpha) {
+	return [
+		sRGBGammaToLinear(baseGamma[0] + (targetGamma[0] - baseGamma[0]) * alpha),
+		sRGBGammaToLinear(baseGamma[1] + (targetGamma[1] - baseGamma[1]) * alpha),
+		sRGBGammaToLinear(baseGamma[2] + (targetGamma[2] - baseGamma[2]) * alpha)
+	];
+}
 function linearRgbToToneVariant(rgb, pastel) {
 	const [h, s, l] = srgbToOkhsl([
 		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[0]))),
@@ -1986,7 +2703,7 @@ function resolveMixForScheme(name, def, ctx, isDark, isHighContrast) {
 	const targetResolved = ctx.resolved.get(def.target);
 	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;
+	let t = clamp(passNumber(def.value, isHighContrast, ctx.config), 0, 100) / 100;
 	const blend = def.blend ?? "opaque";
 	const space = def.space ?? "okhsl";
 	const polarity = roleToPolarity(resolveRole(name, def, ctx));
@@ -1994,10 +2711,14 @@ function resolveMixForScheme(name, def, ctx, isDark, isHighContrast) {
 	const baseLinear = okhslVariantToLinearRgb(baseVariant, baseVariant.pastel ?? ctx.config.pastel);
 	const targetLinear = okhslVariantToLinearRgb(targetVariant, targetVariant.pastel ?? ctx.config.pastel);
 	if (def.contrast !== void 0) {
-		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast, polarity);
+		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast, ctx.config, polarity);
 		const metric = resolvedContrast.metric;
 		let luminanceAt;
-		if (blend === "transparent" || space === "srgb") luminanceAt = (v) => metricLuminance(metric, linearSrgbLerp(baseLinear, targetLinear, v));
+		if (blend === "transparent") {
+			const baseGamma = toDisplayGamma(baseLinear);
+			const targetGamma = toDisplayGamma(targetLinear);
+			luminanceAt = (v) => metricLuminance(metric, compositeOverGamma(baseGamma, targetGamma, v));
+		} else if (space === "srgb") luminanceAt = (v) => metricLuminance(metric, linearSrgbLerp(baseLinear, targetLinear, v));
 		else luminanceAt = (v) => {
 			return metricLuminance(metric, okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v, pastel));
 		};
@@ -2078,9 +2799,15 @@ function seedField(order, ctx, field, source) {
 	}
 }
 /**
-* After the four passes, surface chromatic contrast drift (§10): a color
+* After the 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.
+*
+* Under a manual `contrastLevel` the spec is resolved at the level, so the check
+* measures each normal variant against the target it was actually solved for. At
+* level 100 the high-contrast slots are mirrors and are skipped: the normal
+* schemes already carry that check, and repeating it would emit a byte-identical
+* advisory under a different scheme label, which dedupes as a separate key.
 */
 function verifyContrastDrift(order, defs, result, config) {
 	const roles = /* @__PURE__ */ new Map();
@@ -2093,7 +2820,7 @@ function verifyContrastDrift(order, defs, result, config) {
 		const base = result.get(regDef.base);
 		if (!color || !base) continue;
 		const polarity = roleToPolarity(resolveRoleInMap(name, def, defs, config.inferRole, roles));
-		for (const s of [
+		const schemes = [
 			{
 				isDark: false,
 				isHighContrast: false,
@@ -2114,8 +2841,11 @@ function verifyContrastDrift(order, defs, result, config) {
 				isHighContrast: true,
 				field: "darkContrast"
 			}
-		]) {
-			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast, polarity);
+		];
+		const mirrored = hcMirrorsNormal(config);
+		for (const s of schemes) {
+			if (mirrored && s.isHighContrast) continue;
+			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast, config, polarity);
 			const cVariant = color[s.field];
 			const bVariant = base[s.field];
 			const cOkhsl = toOkhslVariant(cVariant);
@@ -2128,26 +2858,32 @@ function verifyContrastDrift(order, defs, result, config) {
 		}
 	}
 }
-function resolveAllColors(hue, saturation, defs, config, externalBases) {
+function resolveAllColors(seed, defs, config, externalBases) {
 	validateColorDefs(defs, externalBases);
 	const order = topoSort(defs);
 	const ctx = {
-		hue,
-		saturation,
+		...seed,
 		defs,
 		resolved: /* @__PURE__ */ new Map(),
 		config,
 		roles: /* @__PURE__ */ new Map()
 	};
 	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
+	const mirrored = hcMirrorsNormal(config);
 	const lightMap = runPass(order, defs, ctx, false, false, "light");
-	seedField(order, ctx, "lightContrast", lightMap);
-	const lightHCMap = runPass(order, defs, ctx, false, true, "lightContrast");
+	let lightHCMap = lightMap;
+	if (!mirrored) {
+		seedField(order, ctx, "lightContrast", lightMap);
+		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");
+	let darkHCMap = darkMap;
+	if (!mirrored) {
+		seedField(order, ctx, "darkContrast", darkMap);
+		darkHCMap = runPass(order, defs, ctx, true, true, "darkContrast");
+	}
 	const result = /* @__PURE__ */ new Map();
 	for (const name of order) result.set(name, {
 		name,
@@ -2166,8 +2902,14 @@ function resolveAllColors(hue, saturation, defs, config, externalBases) {
 /**
 * Hue channel planning for `splitHue` exports.
 *
-* Builds per-color hue var references and scheme-independent `--*-hue`
-* declarations for oklch CSS / Tasty output when every color is pastel.
+* Builds per-color hue var references and the `--*-hue` declarations backing
+* them for oklch CSS / Tasty output when every color is pastel.
+*
+* Hue is scheme-independent unless the theme or a color authors a dark hue,
+* so declarations are collected per scheme (`'light'` / `'dark'`) and the dark
+* set is emitted only when it actually differs — see `buildHueDeclarations`.
+* A color that authors a hue in *either* scheme gets its own var in both, so
+* the shared `var()` reference stays valid.
 */
 const ACHROMATIC_EPSILON = 1e-6;
 function cssProp(prefix, name, suffix) {
@@ -2176,7 +2918,11 @@ function cssProp(prefix, name, suffix) {
 function isAchromatic(v) {
 	return v.s <= ACHROMATIC_EPSILON;
 }
-function themeHuePlan(name, def, variant, ctx) {
+/** Seed hue backing `--{baseName}-hue` in a given scheme. */
+function schemeSeedHue(ctx, scheme) {
+	return scheme === "dark" ? ctx.darkSeedHue ?? ctx.seedHue : ctx.seedHue;
+}
+function themeHuePlan(name, def, variant, ctx, scheme) {
 	if (def === void 0 || isShadowDef(def) || isMixDef(def) || isAchromatic(variant)) return {
 		hueVar: "",
 		inline: true,
@@ -2184,13 +2930,40 @@ function themeHuePlan(name, def, variant, ctx) {
 	};
 	const regDef = def;
 	const baseHueVar = `var(--${ctx.baseName}-hue)`;
-	if (regDef.hue === void 0) return {
+	const prop = cssProp(ctx.prefix, name, "-hue");
+	if ((regDef.mode ?? "auto") === "static" && schemeSeedHue(ctx, "dark") !== ctx.seedHue) return {
+		hueVar: `var(${prop})`,
+		inline: false,
+		declarations: [{
+			prop,
+			value: String(variant.h)
+		}]
+	};
+	if (regDef.hue === void 0 && regDef.darkHue === void 0 && regDef.from === void 0) return {
 		hueVar: baseHueVar,
 		inline: false,
 		declarations: []
 	};
-	const parsed = parseRelativeOrAbsolute(regDef.hue);
-	const prop = cssProp(ctx.prefix, name, "-hue");
+	const authored = scheme === "dark" ? regDef.darkHue ?? regDef.hue : regDef.hue;
+	if (authored === void 0) {
+		if (regDef.from !== void 0) return {
+			hueVar: `var(${prop})`,
+			inline: false,
+			declarations: [{
+				prop,
+				value: String(variant.h)
+			}]
+		};
+		return {
+			hueVar: `var(${prop})`,
+			inline: false,
+			declarations: [{
+				prop,
+				value: baseHueVar
+			}]
+		};
+	}
+	const parsed = parseRelativeOrAbsolute(authored);
 	if (parsed.relative) {
 		const sign = parsed.value >= 0 ? "+" : "-";
 		const magnitude = Math.abs(parsed.value);
@@ -2214,13 +2987,13 @@ function themeHuePlan(name, def, variant, ctx) {
 		}]
 	};
 }
-function standaloneHuePlan(name, variant, ctx) {
+function standaloneHuePlan(name, variant, ctx, scheme) {
 	if (isAchromatic(variant)) return {
 		hueVar: "",
 		inline: true,
 		declarations: []
 	};
-	const hue = ctx.resolvedHue ?? variant.h;
+	const hue = scheme === "dark" ? variant.h : ctx.resolvedHue ?? variant.h;
 	const prop = cssProp(ctx.prefix, name, "-hue");
 	return {
 		hueVar: `var(${prop})`,
@@ -2231,12 +3004,12 @@ function standaloneHuePlan(name, variant, ctx) {
 		}]
 	};
 }
-function buildHuePlan(name, def, variant, ctx) {
-	if (ctx.mode === "standalone") return standaloneHuePlan(name, variant, ctx);
-	return themeHuePlan(name, def, variant, ctx);
+function buildHuePlan(name, def, variant, ctx, scheme = "light") {
+	if (ctx.mode === "standalone") return standaloneHuePlan(name, variant, ctx, scheme);
+	return themeHuePlan(name, def, variant, ctx, scheme);
 }
 /** Collect unique hue declarations across all colors (theme + per-color). */
-function collectHueDeclarations(resolved, ctx) {
+function collectHueDeclarations(resolved, ctx, scheme) {
 	if (ctx.emitDeclarations === false) return [];
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
@@ -2247,15 +3020,35 @@ function collectHueDeclarations(resolved, ctx) {
 	};
 	if (ctx.mode === "theme") push({
 		prop: `--${ctx.baseName}-hue`,
-		value: String(ctx.seedHue)
+		value: String(schemeSeedHue(ctx, scheme))
 	});
 	for (const [name, color] of resolved) {
 		const def = ctx.defs[name];
-		const plan = buildHuePlan(name, def, color.light, ctx);
+		const plan = buildHuePlan(name, def, scheme === "dark" ? color.dark : color.light, ctx, scheme);
 		for (const decl of plan.declarations) push(decl);
 	}
 	return out;
 }
+/**
+* Hue declarations for both schemes. `dark` is empty when it resolves to the
+* same hues as light — the common case, with no `darkHue` anywhere.
+*
+* When they differ, the **whole** dark set is returned rather than only the
+* entries whose text changed. A relative declaration reads
+* `calc(var(--theme-hue) + N)` in both schemes even though its resolved value
+* moves with the seed, and custom properties substitute `var()` at
+* computed-value time on the declaring element — so re-declaring
+* `--{baseName}-hue` alone would leave inherited per-color vars still holding
+* the light-substituted value.
+*/
+function buildHueDeclarations(resolved, ctx) {
+	const light = collectHueDeclarations(resolved, ctx, "light");
+	const dark = collectHueDeclarations(resolved, ctx, "dark");
+	return {
+		light,
+		dark: dark.length === light.length && dark.every((decl, i) => decl.prop === light[i].prop && decl.value === light[i].value) ? [] : dark
+	};
+}
 function buildHuePlans(resolved, ctx) {
 	const plans = /* @__PURE__ */ new Map();
 	for (const [name, color] of resolved) plans.set(name, buildHuePlan(name, ctx.defs[name], color.light, ctx));
@@ -2286,13 +3079,13 @@ const formatters = {
 function fmt(value, decimals) {
 	return parseFloat(value.toFixed(decimals)).toString();
 }
-function formatVariant(v, format = "okhsl", pastel = false) {
+function formatVariant(v, format = "oklch", pastel = false) {
 	const effectivePastel = v.pastel ?? pastel;
 	let base;
-	if (format === "okhst") base = formatOkhst(v.h, v.s * 100, v.t * 100, effectivePastel);
+	if (format === "okhst") base = formatOkhst(v.h, v.s, v.t, effectivePastel);
 	else {
 		const { l } = variantToOkhsl(v);
-		base = formatters[format](v.h, v.s * 100, l * 100, effectivePastel);
+		base = formatters[format](v.h, v.s, l, effectivePastel);
 	}
 	if (v.alpha >= 1) return base;
 	const closing = base.lastIndexOf(")");
@@ -2308,7 +3101,7 @@ function formatVariantHue(v, plan, pastel = false) {
 	const [L, C] = okhslToOklch(v.h, v.s, l, effectivePastel);
 	let base;
 	if (plan.inline) if (v.s <= 1e-6) base = `oklch(${fmt(L, 4)} 0 0)`;
-	else base = formatOklch(v.h, v.s * 100, l * 100, effectivePastel);
+	else base = formatOklch(v.h, v.s, l, effectivePastel);
 	else base = `oklch(${fmt(L, 4)} ${fmt(C, 4)} ${plan.hueVar})`;
 	if (v.alpha >= 1) return base;
 	const closing = base.lastIndexOf(")");
@@ -2318,28 +3111,47 @@ function formatColorValue(v, format, pastel, huePlan) {
 	if (format === "oklch" && huePlan !== void 0) return formatVariantHue(v, huePlan, pastel);
 	return formatVariant(v, format, pastel);
 }
+/**
+* Resolve the effective output modes for an export.
+*
+* `modes.highContrast` and `contrastLevel` are independent: the level positions
+* the normal variants, the high-contrast tier stays the true high-contrast
+* resolution, and the two compose — a slider raises the baseline while a
+* `prefers-contrast: more` block still escalates on top of it.
+*
+* The one exception is a **global** level of 100, where the normal variants
+* already *are* the high-contrast ones. The tier would be an exact duplicate, so
+* it is dropped and a single light/dark set is emitted — including against an
+* explicit `highContrast: true` override, which has nothing different left to
+* ask for.
+*
+* A level set on a single theme or token does not change which modes are
+* emitted: `modes` is global-only, and a palette must not have one sibling
+* collapse the shared token structure. A per-instance level of 100 therefore
+* still reports into the tier, with values equal to its own normal ones.
+*/
 function resolveModes(override) {
 	const cfg = getConfig();
+	const highContrast = override?.highContrast ?? cfg.modes.highContrast;
 	return {
 		dark: override?.dark ?? cfg.modes.dark,
-		highContrast: override?.highContrast ?? cfg.modes.highContrast
+		highContrast: highContrast && !hcMirrorsNormal(cfg)
 	};
 }
-function buildTokenMap(resolved, prefix, states, modes, format = "okhsl", pastel = false, channelCtx) {
+function buildTokenMap(resolved, prefix, states, modes, format = "oklch", pastel = false, channelCtx) {
 	const tokens = {};
 	const huePlans = channelCtx !== void 0 && format === "oklch" ? buildHuePlans(resolved, channelCtx) : void 0;
 	if (huePlans !== void 0 && channelCtx !== void 0) {
-		const emitDecls = channelCtx.emitDeclarations !== false;
-		if (emitDecls && channelCtx.mode === "theme") tokens[`#${channelCtx.baseName}-hue`] = { "": String(channelCtx.seedHue) };
-		for (const [name, color] of resolved) {
-			const plan = huePlans.get(name);
-			if (emitDecls) for (const decl of plan.declarations) {
-				const key = `#${decl.prop.slice(2)}`;
-				if (!(key in tokens)) tokens[key] = { "": decl.value };
-			}
-			const colorKey = `#${prefix}${name}`;
-			tokens[colorKey] = buildTokenEntry(color, states, modes, format, pastel, huePlans.get(name));
+		const hueDecls = buildHueDeclarations(resolved, channelCtx);
+		for (const decl of hueDecls.light) tokens[`$${decl.prop.slice(2)}`] = { "": decl.value };
+		if (modes.dark) for (const decl of hueDecls.dark) {
+			const key = `$${decl.prop.slice(2)}`;
+			tokens[key] = {
+				...tokens[key],
+				[states.dark]: decl.value
+			};
 		}
+		for (const [name, color] of resolved) tokens[`#${prefix}${name}`] = buildTokenEntry(color, states, modes, format, pastel, huePlans.get(name));
 		return tokens;
 	}
 	for (const [name, color] of resolved) {
@@ -2355,7 +3167,7 @@ function buildTokenEntry(color, states, modes, format, pastel, huePlan) {
 	if (modes.dark && modes.highContrast) entry[`${states.dark} & ${states.highContrast}`] = formatColorValue(color.darkContrast, format, pastel, huePlan);
 	return entry;
 }
-function buildFlatTokenMap(resolved, prefix, modes, format = "okhsl", pastel = false) {
+function buildFlatTokenMap(resolved, prefix, modes, format = "oklch", pastel = false) {
 	const result = { light: {} };
 	if (modes.dark) result.dark = {};
 	if (modes.highContrast) result.lightContrast = {};
@@ -2369,7 +3181,7 @@ function buildFlatTokenMap(resolved, prefix, modes, format = "okhsl", pastel = f
 	}
 	return result;
 }
-function buildJsonMap(resolved, modes, format = "okhsl", pastel = false) {
+function buildJsonMap(resolved, modes, format = "oklch", pastel = false) {
 	const result = {};
 	for (const [name, color] of resolved) {
 		const entry = { light: formatVariant(color.light, format, pastel) };
@@ -2388,7 +3200,14 @@ function buildCssMap(resolved, prefix, suffix, format, pastel = false, channelCt
 		darkContrast: []
 	};
 	const huePlans = channelCtx !== void 0 && format === "oklch" ? buildHuePlans(resolved, channelCtx) : void 0;
-	if (huePlans !== void 0 && channelCtx !== void 0) for (const decl of collectHueDeclarations(resolved, channelCtx)) lines.light.push(`${decl.prop}: ${decl.value};`);
+	if (huePlans !== void 0 && channelCtx !== void 0) {
+		const hueDecls = buildHueDeclarations(resolved, channelCtx);
+		for (const decl of hueDecls.light) lines.light.push(`${decl.prop}: ${decl.value};`);
+		for (const decl of hueDecls.dark) {
+			lines.dark.push(`${decl.prop}: ${decl.value};`);
+			lines.darkContrast.push(`${decl.prop}: ${decl.value};`);
+		}
+	}
 	for (const [name, color] of resolved) {
 		const prop = `--${prefix}${name}${suffix}`;
 		const plan = huePlans?.get(name);
@@ -2501,334 +3320,134 @@ const DEFAULT_DTCG_CONTEXT_NAMES = {
 function buildDtcgResolver(result, options) {
 	const setName = options?.setName ?? "base";
 	const modifierName = options?.modifierName ?? "scheme";
-	const ctx = {
-		...DEFAULT_DTCG_CONTEXT_NAMES,
-		...options?.contextNames
-	};
-	const contexts = { [ctx.light]: [] };
-	if (result.dark) contexts[ctx.dark] = [result.dark];
-	if (result.lightContrast) contexts[ctx.lightContrast] = [result.lightContrast];
-	if (result.darkContrast) contexts[ctx.darkContrast] = [result.darkContrast];
-	return {
-		version: options?.version ?? "2025.10",
-		sets: { [setName]: { sources: [result.light] } },
-		modifiers: { [modifierName]: {
-			default: ctx.light,
-			contexts
-		} },
-		resolutionOrder: [{ $ref: `#/sets/${setName}` }, { $ref: `#/modifiers/${modifierName}` }]
-	};
-}
-function tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel) {
-	const lines = {
-		light: [],
-		dark: [],
-		lightContrast: [],
-		darkContrast: []
-	};
-	for (const [name, color] of resolved) {
-		const prop = `--${cssPrefix}${themePrefix}${name}`;
-		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 lines;
-}
-function indentBlock(text, pad) {
-	return text.split("\n").map((line) => line.length === 0 ? line : pad + line).join("\n");
-}
-function emitRule(selector, body) {
-	return `${selector} {\n${indentBlock(body, "  ")}\n}`;
-}
-/**
-* Emit a CSS block for a set of declarations scoped by one or more selectors
-* / at-rules. Class-like selectors concatenate (`.dark.high-contrast`);
-* at-rules (`@media …`) nest `:root` (or the chained selector) inside.
-*/
-function emitScoped(scopes, declarations) {
-	if (declarations.length === 0) return void 0;
-	const atRules = [];
-	let selectorChain = "";
-	for (const scope of scopes) if (scope.startsWith("@")) atRules.push(scope);
-	else selectorChain += scope;
-	let css = emitRule(selectorChain || ":root", declarations.join("\n"));
-	for (const rule of atRules) css = emitRule(rule, css);
-	return css;
-}
-/**
-* Render accumulated per-scheme declaration lines as a Tailwind v4 CSS string:
-* an `@theme` block (light baseline) plus dark / high-contrast overrides under
-* the configured selectors. Empty blocks are skipped.
-*/
-function emitTailwindCss(lines, modes, darkSelector, highContrastSelector) {
-	const blocks = [];
-	if (lines.light.length > 0) blocks.push(emitRule("@theme", lines.light.join("\n")));
-	if (modes.dark) {
-		const dark = emitScoped([darkSelector], lines.dark);
-		if (dark) blocks.push(dark);
-	}
-	if (modes.highContrast) {
-		const hc = emitScoped([highContrastSelector], lines.lightContrast);
-		if (hc) blocks.push(hc);
-	}
-	if (modes.dark && modes.highContrast) {
-		const dhc = emitScoped([darkSelector, highContrastSelector], lines.darkContrast);
-		if (dhc) blocks.push(dhc);
-	}
-	return blocks.join("\n\n");
-}
-/**
-* Build per-scheme declaration lines for a single theme (used by
-* `theme.tailwind()` and as the palette `buildOne` step).
-*/
-function buildTailwindLines(resolved, themePrefix, cssPrefix, format, pastel) {
-	return tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel);
-}
-/**
-* Build a complete Tailwind v4 CSS string for a single theme.
-*/
-function buildTailwindMap(resolved, themePrefix, cssPrefix, modes, format, darkSelector, highContrastSelector, pastel = false) {
-	return emitTailwindCss(tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel), modes, darkSelector, highContrastSelector);
-}
-
-//#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 {
-		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
-	};
-}
-/**
-* 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
-	};
-}
-/**
-* 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);
-}
-/**
-* 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.
-*/
-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);
-}
-/**
-* Split the body of a CSS color function into its components and detect
-* whether an alpha channel was present.
-*
-* Handles both modern slash syntax (`R G B / A` or `R, G, B / A`) and
-* legacy comma syntax (`R, G, B, A`). The alpha value itself is discarded
-* by the caller — standalone Glaze colors have no opacity field.
-*/
-function splitColorBody(body) {
-	const slashIdx = body.indexOf("/");
-	if (slashIdx !== -1) return {
-		components: body.slice(0, slashIdx).trim().split(/[\s,]+/).filter(Boolean),
-		hadAlpha: body.slice(slashIdx + 1).trim().length > 0
-	};
-	const components = body.split(/[\s,]+/).filter(Boolean);
-	if (components.length === 4) {
-		components.pop();
-		return {
-			components,
-			hadAlpha: true
-		};
-	}
-	return {
-		components,
-		hadAlpha: false
-	};
-}
-function warnDroppedAlpha(input) {
-	console.warn(`glaze: alpha component dropped from "${input}" (standalone color has no opacity field).`);
-}
-function parseColorString(input) {
-	if (input.startsWith("#")) {
-		const parsed = parseHexAlpha(input);
-		if (!parsed) throw new Error(`glaze: invalid hex color "${input}".`);
-		if (parsed.alpha !== void 0) warnDroppedAlpha(input);
-		const [h, s, l] = srgbToOkhsl(parsed.rgb);
-		return {
-			h,
-			s,
-			l
-		};
-	}
-	const m = input.match(COLOR_FN_RE);
-	if (!m) throw new Error(`glaze: unsupported color string "${input}".`);
-	const fn = m[1].toLowerCase();
-	const { components, hadAlpha } = splitColorBody(m[2].trim());
-	if (hadAlpha) warnDroppedAlpha(input);
-	if (components.length !== 3) throw new Error(`glaze: expected 3 components in "${input}".`);
-	switch (fn) {
-		case "rgb":
-		case "rgba": {
-			const [h, s, l] = srgbToOkhsl([
-				parseNumberOrPercent(components[0], 255) / 255,
-				parseNumberOrPercent(components[1], 255) / 255,
-				parseNumberOrPercent(components[2], 255) / 255
-			]);
-			return {
-				h,
-				s,
-				l
-			};
-		}
-		case "hsl":
-		case "hsla": {
-			const [oh, os, ol] = srgbToOkhsl(hslToSrgb(parseFloat(components[0]), parseNumberOrPercent(components[1], 1), parseNumberOrPercent(components[2], 1)));
-			return {
-				h: oh,
-				s: os,
-				l: ol
-			};
-		}
-		case "okhsl": return {
-			h: parseFloat(components[0]),
-			s: parseNumberOrPercent(components[1], 1),
-			l: parseNumberOrPercent(components[2], 1)
-		};
-		case "okhst": return okhstToOkhsl({
-			h: parseFloat(components[0]),
-			s: parseNumberOrPercent(components[1], 1),
-			t: parseNumberOrPercent(components[2], 1)
-		});
-		case "oklch": {
-			const L = parseNumberOrPercent(components[0], 1);
-			const C = parseNumberOrPercent(components[1], .4);
-			const hRad = parseFloat(components[2]) * Math.PI / 180;
-			const [h, s, l] = oklabToOkhsl([
-				L,
-				C * Math.cos(hRad),
-				C * Math.sin(hRad)
-			]);
-			return {
-				h,
-				s,
-				l
-			};
-		}
+	const ctx = {
+		...DEFAULT_DTCG_CONTEXT_NAMES,
+		...options?.contextNames
+	};
+	const contexts = { [ctx.light]: [] };
+	if (result.dark) contexts[ctx.dark] = [result.dark];
+	if (result.lightContrast) contexts[ctx.lightContrast] = [result.lightContrast];
+	if (result.darkContrast) contexts[ctx.darkContrast] = [result.darkContrast];
+	return {
+		version: options?.version ?? "2025.10",
+		sets: { [setName]: { sources: [result.light] } },
+		modifiers: { [modifierName]: {
+			default: ctx.light,
+			contexts
+		} },
+		resolutionOrder: [{ $ref: `#/sets/${setName}` }, { $ref: `#/modifiers/${modifierName}` }]
+	};
+}
+function tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel) {
+	const lines = {
+		light: [],
+		dark: [],
+		lightContrast: [],
+		darkContrast: []
+	};
+	for (const [name, color] of resolved) {
+		const prop = `--${cssPrefix}${themePrefix}${name}`;
+		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)};`);
 	}
-	throw new Error(`glaze: unsupported color function "${fn}".`);
+	return lines;
+}
+function indentBlock(text, pad) {
+	return text.split("\n").map((line) => line.length === 0 ? line : pad + line).join("\n");
+}
+function emitRule(selector, body) {
+	return `${selector} {\n${indentBlock(body, "  ")}\n}`;
 }
 /**
-* 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).
+* Emit a CSS block for a set of declarations scoped by one or more selectors
+* / at-rules. Class-like selectors concatenate (`.dark.high-contrast`);
+* at-rules (`@media …`) nest `:root` (or the chained selector) inside.
 */
-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)?");
+function emitScoped(scopes, declarations) {
+	if (declarations.length === 0) return void 0;
+	const atRules = [];
+	let selectorChain = "";
+	for (const scope of scopes) if (scope.startsWith("@")) atRules.push(scope);
+	else selectorChain += scope;
+	let css = emitRule(selectorChain || ":root", declarations.join("\n"));
+	for (const rule of atRules) css = emitRule(rule, css);
+	return css;
 }
-/** 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}).`);
+/**
+* Render accumulated per-scheme declaration lines as a Tailwind v4 CSS string:
+* an `@theme` block (light baseline) plus dark / high-contrast overrides under
+* the configured selectors. Empty blocks are skipped.
+*/
+function emitTailwindCss(lines, modes, darkSelector, highContrastSelector) {
+	const blocks = [];
+	if (lines.light.length > 0) blocks.push(emitRule("@theme", lines.light.join("\n")));
+	if (modes.dark) {
+		const dark = emitScoped([darkSelector], lines.dark);
+		if (dark) blocks.push(dark);
+	}
+	if (modes.highContrast) {
+		const hc = emitScoped([highContrastSelector], lines.lightContrast);
+		if (hc) blocks.push(hc);
+	}
+	if (modes.dark && modes.highContrast) {
+		const dhc = emitScoped([darkSelector, highContrastSelector], lines.darkContrast);
+		if (dhc) blocks.push(dhc);
 	}
+	return blocks.join("\n\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).");
+/**
+* Build per-scheme declaration lines for a single theme (used by
+* `theme.tailwind()` and as the palette `buildOne` step).
+*/
+function buildTailwindLines(resolved, themePrefix, cssPrefix, format, pastel) {
+	return tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel);
 }
-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)
-	]);
+/**
+* Build a complete Tailwind v4 CSS string for a single theme.
+*/
+function buildTailwindMap(resolved, themePrefix, cssPrefix, modes, format, darkSelector, highContrastSelector, pastel = false) {
+	return emitTailwindCss(tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel), modes, darkSelector, highContrastSelector);
+}
+
+//#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.
+*
+* Tokens store a sparse local config override only. Resolve merges the
+* live global config with that local override (invalidated on
+* `configure()`). Authoring `.export(override?)` freezes
+* `getConfig() ∪ local ∪ override` at call time.
+*/
+/** 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
+]);
+/**
+* Value-form local override: `lightTone` defaults to `false` (preserve
+* input tone). User override fields win.
+*/
+function sparseValueFormLocal(userOverride) {
 	return {
-		h,
-		s,
-		l: outL
+		...userOverride,
+		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : false
 	};
 }
-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`.
@@ -2858,6 +3477,13 @@ function validateStructuredInput(input) {
 	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 (typeof input.darkHue === "number" && !Number.isFinite(input.darkHue)) throw new Error(`glaze.color: structured darkHue must be a finite number (got ${input.darkHue}).`);
+	if (input.darkSaturation !== void 0) {
+		if (!Number.isFinite(input.darkSaturation) || input.darkSaturation < 0 || input.darkSaturation > 100) throw new Error(`glaze.color: structured darkSaturation must be a finite number in 0–100 (got ${input.darkSaturation}).`);
+	}
+	if (input.darkSaturationFactor !== void 0) {
+		if (!Number.isFinite(input.darkSaturationFactor) || input.darkSaturationFactor < 0 || input.darkSaturationFactor > 1) throw new Error(`glaze.color: structured darkSaturationFactor must be a finite number in 0–1 (got ${input.darkSaturationFactor}).`);
+	}
 	if (input.opacity !== void 0) validateStandaloneOpacity(input.opacity);
 }
 /**
@@ -2872,36 +3498,16 @@ function validateStandaloneName(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.
+* Resolve `'max'` / `'min'` to their literal author tones (100 / 0).
+*
+* The hidden `STANDALONE_SEED` anchor exists only so `contrast` has something
+* to measure against — it is not an authored base. Pinning the extreme keeps
+* the token on the plain scheme mapping instead of the base-anchored dark
+* replay the resolver applies to real `base` references.
 */
-function extractOkhslFromValue(value) {
-	if (typeof value === "string") return parseColorString(value);
-	if (Array.isArray(value)) throw new Error("glaze.color: RGB tuple [r, g, b] is no longer supported — use { r, g, b } instead.");
-	if (isRgbColorObject(value)) {
-		validateRgbColor(value);
-		const [h, s, l] = srgbToOkhsl([
-			value.r / 255,
-			value.g / 255,
-			value.b / 255
-		]);
-		return {
-			h,
-			s,
-			l
-		};
-	}
-	if (isOklchColorObject(value)) {
-		validateOklchColor(value);
-		return oklchComponentsToOkhsl(value.l, value.c, value.h);
-	}
-	if (isOkhstColorObject(value)) {
-		validateOkhstColor(value);
-		return okhstToOkhsl(value);
-	}
-	validateOkhslColor(value);
-	return value;
+function pinExtremeTone(tone) {
+	const pin = (value) => value === "max" ? 100 : value === "min" ? 0 : value;
+	return Array.isArray(tone) ? [pin(tone[0]), pin(tone[1])] : pin(tone);
 }
 /**
 * Build the `ColorMap` for a value-shorthand `glaze.color()` call.
@@ -2909,6 +3515,10 @@ function extractOkhslFromValue(value) {
 * The user-facing color (`STANDALONE_VALUE`) defaults to `mode: 'auto'`
 * across every value-shorthand form.
 *
+* An absolute `hue` override becomes the seed while a relative one becomes a
+* def field; `darkHue` always lands on the def in either form, so an absolute
+* `darkHue` wins outright instead of being re-offset by a relative `hue`.
+*
 * 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
@@ -2926,13 +3536,16 @@ function buildStandaloneValueDefs(main, options) {
 	if (userName !== void 0) validateStandaloneName(userName);
 	const primary = userName ?? STANDALONE_VALUE;
 	const seedTone = toTone(main.l);
+	const primaryTone = toneOption ?? seedTone;
 	const valueDef = {
 		hue: relativeHue,
 		saturation: options?.saturationFactor,
-		tone: toneOption ?? seedTone,
+		darkHue: options?.darkHue,
+		darkSaturation: options?.darkSaturationFactor,
+		tone: needsSeedAnchor ? pinExtremeTone(primaryTone) : primaryTone,
 		contrast: options?.contrast,
 		mode: options?.mode ?? "auto",
-		flip: options?.flip,
+		autoFlip: options?.autoFlip,
 		opacity: options?.opacity,
 		pastel: options?.pastel,
 		role: options?.role,
@@ -2946,18 +3559,39 @@ function buildStandaloneValueDefs(main, options) {
 		mode: "static"
 	};
 	return {
-		seedHue,
-		seedSaturation,
+		seed: {
+			hue: seedHue,
+			saturation: seedSaturation,
+			darkSaturation: options?.darkSaturation
+		},
 		defs,
 		primary
 	};
 }
-function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, baseToken, exportData) {
-	let cached;
+function createColorTokenFromDefs(seed, defs, primary, configOverride, baseToken, buildExport) {
+	let cache = null;
+	function getEffectiveConfig() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version) return cache.effectiveConfig;
+		const effectiveConfig = mergeConfig(getConfig(), configOverride);
+		cache = {
+			map: null,
+			version,
+			effectiveConfig
+		};
+		return effectiveConfig;
+	}
 	const resolveOnce = () => {
-		if (cached) return cached;
-		cached = resolveAllColors(seedHue, seedSaturation, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
-		return cached;
+		const version = getConfigVersion();
+		if (cache && cache.version === version && cache.map) return cache.map;
+		const effectiveConfig = getEffectiveConfig();
+		const map = resolveAllColors(seed, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
+		cache = {
+			map,
+			version,
+			effectiveConfig
+		};
+		return map;
 	};
 	const resolveStates = (options) => {
 		const cfg = getConfig();
@@ -2967,7 +3601,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		};
 	};
 	const tokenLike = (options) => {
-		return buildTokenMap(resolveOnce(), "", resolveStates(options), resolveModes(options?.modes), options?.format, effectiveConfig.pastel)[`#${primary}`];
+		return buildTokenMap(resolveOnce(), "", resolveStates(options), resolveModes(options?.modes), options?.format ?? "oklch", getEffectiveConfig().pastel)[`#${primary}`];
 	};
 	return {
 		resolve() {
@@ -2978,10 +3612,10 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		json(options) {
 			const format = options?.format ?? "oklch";
 			assertNativeFormat(format, "json");
-			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), format, effectiveConfig.pastel)[primary];
+			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), format, getEffectiveConfig().pastel)[primary];
 		},
 		css(options) {
-			const format = options.format ?? "rgb";
+			const format = options.format ?? "oklch";
 			assertNativeFormat(format, "css");
 			const resolved = resolveOnce().get(primary);
 			const renamed = new Map([[options.name, resolved]]);
@@ -2989,7 +3623,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 			if (options.splitHue && format === "oklch") {
 				assertAllPastel(renamed, resolveModes());
 				channelCtx = {
-					seedHue,
+					seedHue: seed.hue,
 					baseName: options.name,
 					prefix: "",
 					defs: { [options.name]: defs[primary] },
@@ -2997,11 +3631,11 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 					resolvedHue: resolved.light.h
 				};
 			}
-			return buildCssMap(renamed, "", options.suffix ?? "-color", format, effectiveConfig.pastel, channelCtx);
+			return buildCssMap(renamed, "", options.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
 		},
 		dtcg(options) {
 			const modes = resolveModes(options?.modes);
-			const doc = buildDtcgMap(resolveOnce(), "", modes, options?.colorSpace ?? "srgb", effectiveConfig.pastel);
+			const doc = buildDtcgMap(resolveOnce(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
 			const result = { light: doc.light[primary] };
 			if (doc.dark) result.dark = doc.dark[primary];
 			if (doc.lightContrast) result.lightContrast = doc.lightContrast[primary];
@@ -3009,7 +3643,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 			return result;
 		},
 		dtcgResolver(options) {
-			const doc = buildDtcgMap(resolveOnce(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", effectiveConfig.pastel);
+			const doc = buildDtcgMap(resolveOnce(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
 			const name = options.name;
 			const result = { light: { [name]: doc.light[primary] } };
 			if (doc.dark) result.dark = { [name]: doc.dark[primary] };
@@ -3020,9 +3654,11 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		tailwind(options) {
 			const format = options.format ?? "oklch";
 			assertNativeFormat(format, "tailwind");
-			return buildTailwindMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.namespace ?? "color-", resolveModes(options?.modes), format, options.darkSelector ?? ".dark", options.highContrastSelector ?? ".high-contrast", effectiveConfig.pastel);
+			return buildTailwindMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.namespace ?? "color-", resolveModes(options?.modes), format, options.darkSelector ?? ".dark", options.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
 		},
-		export: exportData
+		export(override) {
+			return buildExport(override);
+		}
 	};
 }
 /**
@@ -3071,90 +3707,99 @@ function createColorToken(input, configOverride) {
 	const hasExternalBase = baseToken !== void 0;
 	const needsSeedAnchor = !hasExternalBase && input.contrast !== void 0;
 	const defs = { [primary]: {
-		tone: input.tone,
+		tone: needsSeedAnchor ? pinExtremeTone(input.tone) : input.tone,
 		saturation: input.saturationFactor,
+		darkHue: input.darkHue,
+		darkSaturation: input.darkSaturationFactor,
 		mode: input.mode ?? "auto",
-		flip: input.flip,
+		autoFlip: input.autoFlip,
 		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 = () => ({
+	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
+		tone: pinExtremeTone(pairNormal(input.tone)),
+		saturation: 1,
+		mode: "static"
+	};
+	const localOverride = configOverride;
+	return createColorTokenFromDefs({
+		hue: input.hue,
+		saturation: input.saturation,
+		darkSaturation: input.darkSaturation
+	}, defs, primary, localOverride, baseToken, (exportArg) => ({
+		kind: "color",
+		version: GLAZE_EXPORT_VERSION,
 		form: "structured",
-		input: buildStructuredInputExport(input),
-		config: effectiveConfigOverride
-	});
-	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveConfig, baseToken, exportData);
+		input: buildStructuredInputExport(input, exportArg),
+		config: freezeConfigForExport(localOverride, exportArg)
+	}));
 }
 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 = () => ({
+	const { seed, defs, primary } = buildStandaloneValueDefs(main, options);
+	const localOverride = sparseValueFormLocal(configOverride);
+	return createColorTokenFromDefs(seed, defs, primary, localOverride, linkingBase, (exportArg) => ({
+		kind: "color",
+		version: GLAZE_EXPORT_VERSION,
 		form: "value",
 		input: value,
-		...options !== void 0 ? { overrides: buildOverridesExport(options) } : {},
-		config: effectiveConfigOverride
-	});
-	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, linkingBase, exportData);
+		...options !== void 0 ? { overrides: buildOverridesExport(options, exportArg) } : {},
+		config: freezeConfigForExport(localOverride, exportArg)
+	}));
 }
 /**
 * 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) {
+function buildOverridesExport(options, exportArg) {
 	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.darkHue !== void 0) out.darkHue = options.darkHue;
+	if (options.darkSaturation !== void 0) out.darkSaturation = options.darkSaturation;
+	if (options.darkSaturationFactor !== void 0) out.darkSaturationFactor = options.darkSaturationFactor;
 	if (options.mode !== void 0) out.mode = options.mode;
-	if (options.flip !== void 0) out.flip = options.flip;
+	if (options.autoFlip !== void 0) out.autoFlip = options.autoFlip;
 	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;
+	if (options.base !== void 0) out.base = isGlazeColorToken(options.base) ? options.base.export(exportArg) : options.base;
 	return out;
 }
-function buildStructuredInputExport(input) {
+function buildStructuredInputExport(input, exportArg) {
 	const out = {
 		hue: input.hue,
 		saturation: input.saturation,
 		tone: input.tone
 	};
 	if (input.saturationFactor !== void 0) out.saturationFactor = input.saturationFactor;
+	if (input.darkHue !== void 0) out.darkHue = input.darkHue;
+	if (input.darkSaturation !== void 0) out.darkSaturation = input.darkSaturation;
+	if (input.darkSaturationFactor !== void 0) out.darkSaturationFactor = input.darkSaturationFactor;
 	if (input.mode !== void 0) out.mode = input.mode;
-	if (input.flip !== void 0) out.flip = input.flip;
+	if (input.autoFlip !== void 0) out.autoFlip = input.autoFlip;
 	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;
+	if (input.base !== void 0) out.base = isGlazeColorToken(input.base) ? input.base.export(exportArg) : 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");
+	return isColorTokenExport(candidate);
 }
 function rehydrateOverrides(data) {
 	const out = {};
@@ -3162,8 +3807,11 @@ function rehydrateOverrides(data) {
 	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.darkHue !== void 0) out.darkHue = data.darkHue;
+	if (data.darkSaturation !== void 0) out.darkSaturation = data.darkSaturation;
+	if (data.darkSaturationFactor !== void 0) out.darkSaturationFactor = data.darkSaturationFactor;
 	if (data.mode !== void 0) out.mode = data.mode;
-	if (data.flip !== void 0) out.flip = data.flip;
+	if (data.autoFlip !== void 0) out.autoFlip = data.autoFlip;
 	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;
@@ -3179,8 +3827,11 @@ function rehydrateStructuredInput(data) {
 		tone: data.tone
 	};
 	if (data.saturationFactor !== void 0) out.saturationFactor = data.saturationFactor;
+	if (data.darkHue !== void 0) out.darkHue = data.darkHue;
+	if (data.darkSaturation !== void 0) out.darkSaturation = data.darkSaturation;
+	if (data.darkSaturationFactor !== void 0) out.darkSaturationFactor = data.darkSaturationFactor;
 	if (data.mode !== void 0) out.mode = data.mode;
-	if (data.flip !== void 0) out.flip = data.flip;
+	if (data.autoFlip !== void 0) out.autoFlip = data.autoFlip;
 	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;
@@ -3193,19 +3844,186 @@ function rehydrateStructuredInput(data) {
 * 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.
+* The stored `config` field is the freeze from export time — passed as
+* the instance local override so the rehydrated token stays pinned
+* against later `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}.`);
+	assertExportKind(data, "color", "glaze.colorFrom");
+	assertExportVersion(data, "glaze.colorFrom");
 	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);
+	return createColorToken(rehydrateStructuredInput(data.input), data.config);
+}
+
+//#endregion
+//#region src/theme.ts
+function createTheme(seed, initialColors, configOverride) {
+	const { hue, saturation, darkHue, darkSaturation } = seed;
+	let colorDefs = initialColors ? { ...initialColors } : {};
+	let cache = null;
+	function getEffectiveConfig() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version) return cache.effectiveConfig;
+		const effectiveConfig = mergeConfig(getConfig(), configOverride);
+		cache = {
+			map: null,
+			version,
+			effectiveConfig
+		};
+		return effectiveConfig;
+	}
+	function resolveCached() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version && cache.map) return cache.map;
+		const effectiveConfig = getEffectiveConfig();
+		const map = resolveAllColors(seed, colorDefs, effectiveConfig);
+		cache = {
+			map,
+			version,
+			effectiveConfig
+		};
+		return map;
+	}
+	function invalidate() {
+		cache = null;
+	}
+	function channelCtxFor(options, formatDefault, prefix) {
+		const format = options?.format ?? formatDefault;
+		if (!options?.splitHue || format !== "oklch") return void 0;
+		assertAllPastel(resolveCached(), resolveModes(options?.modes));
+		return {
+			seedHue: hue,
+			darkSeedHue: darkHue,
+			baseName: options.name ?? "theme",
+			prefix,
+			defs: colorDefs,
+			mode: "theme"
+		};
+	}
+	return {
+		get hue() {
+			return hue;
+		},
+		get saturation() {
+			return saturation;
+		},
+		get darkHue() {
+			return darkHue;
+		},
+		get darkSaturation() {
+			return darkSaturation;
+		},
+		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(override) {
+			return {
+				kind: "theme",
+				version: GLAZE_EXPORT_VERSION,
+				hue,
+				saturation,
+				...darkHue !== void 0 ? { darkHue } : {},
+				...darkSaturation !== void 0 ? { darkSaturation } : {},
+				colors: structuredClone(colorDefs),
+				config: freezeConfigForExport(configOverride, override)
+			};
+		},
+		extend(options) {
+			const childSeed = {
+				hue: options.hue ?? hue,
+				saturation: options.saturation ?? saturation,
+				darkHue: options.darkHue ?? darkHue,
+				darkSaturation: options.darkSaturation ?? darkSaturation
+			};
+			const inheritedColors = {};
+			for (const [name, def] of Object.entries(colorDefs)) if (def.inherit !== false) inheritedColors[name] = def;
+			return createTheme(childSeed, options.colors ? {
+				...inheritedColors,
+				...options.colors
+			} : { ...inheritedColors }, configOverride || options.config ? {
+				...configOverride ?? {},
+				...options.config ?? {}
+			} : void 0);
+		},
+		resolve() {
+			return new Map(resolveCached());
+		},
+		tokens(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tokens");
+			const modes = resolveModes(options?.modes);
+			return buildFlatTokenMap(resolveCached(), "", modes, format, getEffectiveConfig().pastel);
+		},
+		tasty(options) {
+			const cfg = getEffectiveConfig();
+			const states = {
+				dark: options?.states?.dark ?? cfg.states.dark,
+				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
+			};
+			const modes = resolveModes(options?.modes);
+			const format = options?.format ?? "oklch";
+			const channelCtx = channelCtxFor(options, "oklch", "");
+			return buildTokenMap(resolveCached(), "", states, modes, format, cfg.pastel, channelCtx);
+		},
+		json(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "json");
+			const modes = resolveModes(options?.modes);
+			return buildJsonMap(resolveCached(), modes, format, getEffectiveConfig().pastel);
+		},
+		css(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "css");
+			const channelCtx = channelCtxFor(options, "oklch", "");
+			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
+		},
+		dtcg(options) {
+			const modes = resolveModes(options?.modes);
+			return buildDtcgMap(resolveCached(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
+		},
+		dtcgResolver(options) {
+			return buildDtcgResolver(buildDtcgMap(resolveCached(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel), options);
+		},
+		tailwind(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tailwind");
+			const modes = resolveModes(options?.modes);
+			return buildTailwindMap(resolveCached(), "", options?.namespace ?? "color-", modes, format, options?.darkSelector ?? ".dark", options?.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
+		}
+	};
 }
 
 //#endregion
@@ -3262,6 +4080,7 @@ function channelCtxForTheme(theme, themeName, passPrefix, themedPrefix, splitHue
 	assertAllPastel(filtered, modes);
 	return {
 		seedHue: theme.hue,
+		darkSeedHue: theme.darkHue,
 		baseName: themeName,
 		prefix: themedPrefix,
 		defs: colorMapFromTheme(theme),
@@ -3287,6 +4106,32 @@ function buildPaletteOutput(themes, paletteOptions, options, buildOne, merge, em
 	}
 	return acc;
 }
+/** Rebuild a theme from a `theme.export()` snapshot. */
+function createThemeFromExport(data, factory = "glaze.themeFrom") {
+	if (data === null || typeof data !== "object") throw new Error(`${factory}: expected an object from theme.export(), got ${data === null ? "null" : typeof data}.`);
+	assertExportKind(data, "theme", factory);
+	assertExportVersion(data, factory);
+	if (typeof data.hue !== "number" || typeof data.saturation !== "number") throw new Error(`${factory}: expected numeric "hue" and "saturation" fields.`);
+	for (const field of ["darkHue", "darkSaturation"]) if (data[field] !== void 0 && typeof data[field] !== "number") throw new Error(`${factory}: expected "${field}" to be a number when present (got ${JSON.stringify(data[field])}).`);
+	return createTheme({
+		hue: data.hue,
+		saturation: data.saturation,
+		darkHue: data.darkHue,
+		darkSaturation: data.darkSaturation
+	}, data.colors, data.config);
+}
+/**
+* Rebuild a palette from a `palette.export()` snapshot.
+*/
+function createPaletteFromExport(data) {
+	if (data === null || typeof data !== "object") throw new Error(`glaze.paletteFrom: expected an object from palette.export(), got ${data === null ? "null" : typeof data}.`);
+	assertExportKind(data, "palette", "glaze.paletteFrom");
+	assertExportVersion(data, "glaze.paletteFrom");
+	if (data.themes === null || typeof data.themes !== "object") throw new Error(`glaze.paletteFrom: expected a "themes" object map of theme exports.`);
+	const rebuilt = {};
+	for (const [name, themeExport] of Object.entries(data.themes)) rebuilt[name] = createThemeFromExport(themeExport, `glaze.paletteFrom (theme "${name}")`);
+	return createPalette(rebuilt, { primary: data.primary });
+}
 function createPalette(themes, paletteOptions) {
 	validatePrimaryTheme(paletteOptions?.primary, themes);
 	const buildDtcgResult = (options) => {
@@ -3300,6 +4145,29 @@ function createPalette(themes, paletteOptions) {
 		}, () => ({ light: {} }));
 	};
 	return {
+		list() {
+			return Object.keys(themes);
+		},
+		get primary() {
+			return paletteOptions?.primary;
+		},
+		theme(name) {
+			return themes[name];
+		},
+		themes() {
+			return { ...themes };
+		},
+		export(override) {
+			const themesExport = {};
+			for (const [name, theme] of Object.entries(themes)) themesExport[name] = theme.export(override);
+			const out = {
+				kind: "palette",
+				version: GLAZE_EXPORT_VERSION,
+				themes: themesExport
+			};
+			if (paletteOptions?.primary !== void 0) out.primary = paletteOptions.primary;
+			return out;
+		},
 		tokens(options) {
 			const format = options?.format ?? "oklch";
 			assertNativeFormat(format, "tokens");
@@ -3318,7 +4186,7 @@ function createPalette(themes, paletteOptions) {
 				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
 			};
 			const modes = resolveModes(options?.modes);
-			const format = options?.format ?? "okhsl";
+			const format = options?.format ?? "oklch";
 			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel, themeName, theme) => {
 				return buildTokenMap(filtered, prefix, states, modes, format, pastel, channelCtxForTheme(theme, themeName, prefix, resolvePrefix(options, themeName, true), options?.splitHue, format, modes, filtered));
 			}, (acc, part) => Object.assign(acc, part), () => ({}));
@@ -3333,7 +4201,7 @@ function createPalette(themes, paletteOptions) {
 		},
 		css(options) {
 			const suffix = options?.suffix ?? "-color";
-			const format = options?.format ?? "rgb";
+			const format = options?.format ?? "oklch";
 			assertNativeFormat(format, "css");
 			const modes = resolveModes();
 			const lines = buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel, themeName, theme) => {
@@ -3388,150 +4256,6 @@ function createPalette(themes, paletteOptions) {
 	};
 }
 
-//#endregion
-//#region src/theme.ts
-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;
-	}
-	function channelCtxFor(options, formatDefault, prefix) {
-		const format = options?.format ?? formatDefault;
-		if (!options?.splitHue || format !== "oklch") return void 0;
-		assertAllPastel(resolveCached(), resolveModes(options?.modes));
-		return {
-			seedHue: hue,
-			baseName: options.name ?? "theme",
-			prefix,
-			defs: colorDefs,
-			mode: "theme"
-		};
-	}
-	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 new Map(resolveCached());
-		},
-		tokens(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "tokens");
-			const modes = resolveModes(options?.modes);
-			return buildFlatTokenMap(resolveCached(), "", modes, format, getEffectiveConfig().pastel);
-		},
-		tasty(options) {
-			const cfg = getEffectiveConfig();
-			const states = {
-				dark: options?.states?.dark ?? cfg.states.dark,
-				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
-			};
-			const modes = resolveModes(options?.modes);
-			const format = options?.format ?? "okhsl";
-			const channelCtx = channelCtxFor(options, "okhsl", "");
-			return buildTokenMap(resolveCached(), "", states, modes, format, cfg.pastel, channelCtx);
-		},
-		json(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "json");
-			const modes = resolveModes(options?.modes);
-			return buildJsonMap(resolveCached(), modes, format, getEffectiveConfig().pastel);
-		},
-		css(options) {
-			const format = options?.format ?? "rgb";
-			assertNativeFormat(format, "css");
-			const channelCtx = channelCtxFor(options, "rgb", "");
-			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
-		},
-		dtcg(options) {
-			const modes = resolveModes(options?.modes);
-			return buildDtcgMap(resolveCached(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
-		},
-		dtcgResolver(options) {
-			return buildDtcgResolver(buildDtcgMap(resolveCached(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel), options);
-		},
-		tailwind(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "tailwind");
-			const modes = resolveModes(options?.modes);
-			return buildTailwindMap(resolveCached(), "", options?.namespace ?? "color-", modes, format, options?.darkSelector ?? ".dark", options?.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
-		}
-	};
-}
-
 //#endregion
 //#region src/glaze.ts
 /**
@@ -3545,6 +4269,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 * - `shadow.ts` — standalone shadow factory (`glaze.shadow`)
 * - `formatters.ts` — variant → string (`glaze.format`)
 * - `config.ts` — global config singleton
+* - `serialize.ts` — authoring export type guards / version checks
 */
 /**
 * Create a single-hue glaze theme.
@@ -3555,18 +4280,28 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 * the theme still reacts to later `configure()` calls for fields it
 * didn't override.
 *
+* The object form also accepts `darkHue` / `darkSaturation` — a separate
+* seed pair for the dark and dark-high-contrast schemes. Both default to
+* their light counterparts, and an explicit `darkSaturation` opts the theme
+* out of the global `darkDesaturation` reduction.
+*
 * @example
 * ```ts
 * const primary = glaze(280, 80);
 * // or shorthand:
 * const primary = glaze({ hue: 280, saturation: 80 });
+* // with a retuned dark seed:
+* const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
 * // with config override:
 * const raw = glaze(280, 80, { lightTone: false });
 * ```
 */
 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);
+	if (typeof hueOrOptions === "number") return createTheme({
+		hue: hueOrOptions,
+		saturation: saturation ?? 100
+	}, void 0, config);
+	return createTheme(hueOrOptions, void 0, config);
 }
 /** Configure global glaze settings. */
 glaze.configure = function configure$1(config) {
@@ -3576,10 +4311,15 @@ glaze.configure = function configure$1(config) {
 glaze.palette = function palette(themes, options) {
 	return createPalette(themes, options);
 };
-/** Create a theme from a serialized export. */
-glaze.from = function from(data) {
-	return createTheme(data.hue, data.saturation, data.colors, data.config);
+/**
+* Create a theme from a serialized `theme.export()` snapshot.
+* Prefer this over the legacy `glaze.from` alias.
+*/
+glaze.themeFrom = function themeFrom(data) {
+	return createThemeFromExport(data);
 };
+/** Compat alias for `glaze.themeFrom`. */
+glaze.from = glaze.themeFrom;
 /**
 * Create a standalone single-color token.
 *
@@ -3595,8 +4335,8 @@ glaze.from = function from(data) {
 * **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.
+* resolve time. Pass `false` for a tone window to disable clamping
+* entirely. `pastel` is instance-only (not set via `configure()`).
 *
 * ```ts
 * // Bare string — no overrides
@@ -3615,8 +4355,8 @@ glaze.from = function from(data) {
 *
 * 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.
+* (`lightTone: false` locally). Structured form falls through to the live
+* global tone windows for omitted fields.
 *
 * Relative `tone: '+N'` and `contrast` anchor to the literal seed by
 * default; when `base` is set they anchor to the base's resolved variant
@@ -3675,7 +4415,10 @@ glaze.fromHex = function fromHex(hex) {
 	const rgb = parseHex(hex);
 	if (!rgb) throw new Error(`glaze: invalid hex color "${hex}".`);
 	const [h, s] = srgbToOkhsl(rgb);
-	return createTheme(h, s * 100);
+	return createTheme({
+		hue: h,
+		saturation: s * 100
+	});
 };
 /**
 * Create a theme from RGB values (0–255).
@@ -3687,15 +4430,18 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 		g / 255,
 		b / 255
 	]);
-	return createTheme(h, s * 100);
+	return createTheme({
+		hue: h,
+		saturation: s * 100
+	});
 };
 /**
 * 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.
+* and the effective config freeze from export time. The reconstructed
+* token pins that freeze as its local override.
 *
 * @example
 * ```ts
@@ -3709,6 +4455,18 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 glaze.colorFrom = function colorFrom(data) {
 	return colorFromExport(data);
 };
+/**
+* Rehydrate a palette from a `palette.export()` snapshot.
+*/
+glaze.paletteFrom = function paletteFrom(data) {
+	return createPaletteFromExport(data);
+};
+/** Type guard for theme authoring snapshots. */
+glaze.isThemeExport = isThemeExport;
+/** Type guard for color-token authoring snapshots. */
+glaze.isColorTokenExport = isColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+glaze.isPaletteExport = isPaletteExport;
 /** Get the current global configuration (for testing/debugging). */
 glaze.getConfig = function getConfig() {
 	return snapshotConfig();
@@ -3719,6 +4477,10 @@ glaze.resetConfig = function resetConfig$1() {
 };
 
 //#endregion
+exports.APCA_HC_ENHANCEMENT = APCA_HC_ENHANCEMENT;
+exports.APCA_MAX_LC = APCA_MAX_LC;
+exports.APCA_PRESETS = APCA_PRESETS;
+exports.GLAZE_EXPORT_VERSION = GLAZE_EXPORT_VERSION;
 exports.REF_EPS = REF_EPS;
 exports.apcaContrast = apcaContrast;
 exports.assertAllPastel = assertAllPastel;
@@ -3737,6 +4499,9 @@ exports.gamutClampedLuminance = gamutClampedLuminance;
 exports.glaze = glaze;
 exports.hslToSrgb = hslToSrgb;
 exports.inferRoleFromName = inferRoleFromName;
+exports.isColorTokenExport = isColorTokenExport;
+exports.isPaletteExport = isPaletteExport;
+exports.isThemeExport = isThemeExport;
 exports.normalizeRole = normalizeRole;
 exports.okhslToLinearSrgb = okhslToLinearSrgb;
 exports.okhslToOkhst = okhslToOkhst;
@@ -3750,6 +4515,7 @@ exports.parseHex = parseHex;
 exports.parseHexAlpha = parseHexAlpha;
 exports.relativeLuminanceFromLinearRgb = relativeLuminanceFromLinearRgb;
 exports.resolveApcaTarget = resolveApcaTarget;
+exports.resolveContrastForLevel = resolveContrastForLevel;
 exports.resolveContrastForMode = resolveContrastForMode;
 exports.resolveMinContrast = resolveMinContrast;
 exports.roleToPolarity = roleToPolarity;