@tenphi/glaze 1.1.1 → 1.3.0

package/dist/index.cjs

@@ -701,9 +701,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()`
@@ -742,7 +754,8 @@ function configure(config) {
 		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
 		autoFlip: config.autoFlip ?? globalConfig.autoFlip,
 		pastel: false,
-		inferRole: config.inferRole ?? globalConfig.inferRole
+		inferRole: config.inferRole ?? globalConfig.inferRole,
+		contrastLevel: normalizeContrastLevel(config.contrastLevel ?? globalConfig.contrastLevel)
 	};
 }
 function resetConfig() {
@@ -772,7 +785,8 @@ function mergeConfig(base, override) {
 		shadowTuning: override.shadowTuning ?? base.shadowTuning,
 		autoFlip: override.autoFlip ?? base.autoFlip,
 		pastel: override.pastel ?? false,
-		inferRole: override.inferRole ?? base.inferRole
+		inferRole: override.inferRole ?? base.inferRole,
+		contrastLevel: normalizeContrastLevel(override.contrastLevel ?? base.contrastLevel)
 	};
 }
 /**
@@ -796,6 +810,8 @@ function freezeConfigForExport(instanceLocal, exportArg) {
 		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);
 }
 
@@ -922,6 +938,43 @@ 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 (the two-tier normal + high-contrast model).
+*
+* Note `contrastLevel: 0` yields `0`, not `undefined`: "pinned to normal
+* contrast with no high-contrast tier" is a distinct state from `'auto'`.
+*/
+function contrastFraction(config) {
+	const level = config.contrastLevel;
+	if (typeof level !== "number" || !Number.isFinite(level)) return void 0;
+	return levelFraction(level);
+}
+/**
+* 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";
@@ -966,6 +1019,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.
 */
@@ -1001,7 +1082,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.
@@ -1100,7 +1183,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);
@@ -1109,7 +1197,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
@@ -1133,6 +1232,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);
@@ -1147,7 +1249,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];
@@ -1166,7 +1269,8 @@ function schemeToneRange(isDark, mode, isHighContrast, config) {
 * converges quickly.
 *
 * Public API: `findToneForContrast`, `findValueForMixContrast`,
-* `resolveMinContrast`, `resolveContrastForMode`, `apcaContrast`.
+* `resolveMinContrast`, `resolveContrastForMode`, `resolveContrastForLevel`,
+* `apcaContrast`.
 */
 /**
 * Luminance of a linear-sRGB color in the basis the metric expects: WCAG
@@ -1239,6 +1343,13 @@ 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
@@ -1274,6 +1385,36 @@ function resolveContrastForMode(spec, isHighContrast, polarity, outerExplicitHC)
 		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,
@@ -1414,7 +1555,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;
@@ -1425,14 +1566,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
@@ -1495,6 +1642,7 @@ function findToneForContrast(options) {
 		epsilon,
 		maxIterations,
 		flip: options.flip ?? false,
+		preferInitial: options.preferInitial ?? false,
 		initialIsLower: initialIsDarker,
 		polarity
 	});
@@ -1545,6 +1693,7 @@ function findValueForMixContrast(options) {
 		epsilon,
 		maxIterations,
 		flip: options.flip ?? false,
+		preferInitial: false,
 		initialIsLower,
 		polarity
 	});
@@ -1746,6 +1895,22 @@ function computeShadow(bg, fg, intensity, tuning) {
 * resolver runs. `topoSort` orders defs so each color is processed after
 * its base / bg / fg / target dependencies.
 */
+/**
+* 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() : []]);
@@ -1764,9 +1929,11 @@ 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.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}".`);
@@ -1883,7 +2050,10 @@ 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.
+* turns a `ColorMap` into a fully resolved `ResolvedColor` per name — or,
+* under a manual `contrastLevel`, a two-pass solver (light → dark) whose
+* authored HC pairs, tone window, and contrast targets are interpolated at
+* that level and whose high-contrast slots mirror the normal ones.
 * Owns the per-scheme resolve helpers for regular, shadow, and mix
 * color defs.
 *
@@ -1972,11 +2142,27 @@ 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) {
+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]`, try mirroring
@@ -1992,65 +2178,118 @@ function applyToneFlip(delta, baseTone, flip) {
 	if (mirrored >= 0 && mirrored <= 100) return -delta;
 	return delta;
 }
-function resolveRootColor(def, isHighContrast) {
-	const rawT = def.tone;
+/**
+* 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, baseDarkTone, config) {
+	const delta = mapToneForScheme(authorTone, mode, false, isHighContrast, config) - getSchemeVariant(baseResolved, false, isHighContrast).t * 100;
+	return clamp(baseDarkTone + (mode === "auto" ? -delta : delta), 0, 100);
+}
+function resolveRootColor(def, isHighContrast, config) {
+	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);
+	if (!isDark || mode === "static") return {
+		hue: resolveEffectiveHue(ctx.hue, def.hue),
+		saturation: clamp(satFactor * ctx.saturation / 100, 0, 1)
+	};
+	const darkSeedSaturation = ctx.darkSaturation ?? ctx.saturation;
+	const darkFactor = clamp(def.darkSaturation ?? satFactor, 0, 1);
+	const explicitDark = def.darkSaturation !== void 0 || ctx.darkSaturation !== void 0;
+	const raw = darkFactor * darkSeedSaturation / 100;
 	return {
-		authorTone: clamp(parseToneValue(isHighContrast ? pairHC(rawT) : pairNormal(rawT)).value, 0, 100),
-		satFactor: clamp(def.saturation ?? 1, 0, 1)
+		hue: 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, effectiveHue, polarity, effectivePastel) {
+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.autoFlip ?? ctx.config.autoFlip;
 	const pastel = effectivePastel;
 	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
 	const baseTone = baseVariant.t * 100;
 	let preferredTone;
+	let isExtreme = false;
 	const rawTone = def.tone;
 	if (rawTone === void 0) preferredTone = baseTone;
 	else {
-		const parsed = parseToneValue(isHighContrast ? pairHC(rawTone) : pairNormal(rawTone));
+		const parsed = passTone(rawTone, isHighContrast, ctx.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);
 		} else preferredTone = clamp(baseTone + applyToneFlip(parsed.value, baseTone, flip), 0, 100);
-		else preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, ctx.config);
+		else if (parsed.kind === "extreme" && isDark && mode !== "static") {
+			isExtreme = true;
+			preferredTone = extremeDarkTone(parsed.value, mode, isHighContrast, baseResolved, baseTone, ctx.config);
+		} else {
+			isExtreme = parsed.kind === "extreme";
+			preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, ctx.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, ctx.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);
 		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 seedTone = isExtreme ? clamp(preferredTone / 100, 0, 1) : clamp(preferredTone / 100, toneRange[0], toneRange[1]);
+		const solve = {
+			hue: channels.hue,
+			saturation: channels.saturation,
+			preferredTone: seedTone,
 			baseLinearRgb,
-			contrast: resolvedContrast,
 			toneRange: [0, 1],
-			initialDirection,
 			flip,
 			pastel
+		};
+		const level = contrastFraction(ctx.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);
@@ -2058,27 +2297,14 @@ function resolveColorForScheme(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 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 finalTone = isRoot ? mapToneForScheme(resolveRootColor(regDef, isHighContrast, ctx.config), mode, isDark, isHighContrast, ctx.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
 	};
@@ -2087,7 +2313,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)),
@@ -2136,7 +2362,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));
@@ -2144,7 +2370,7 @@ 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));
@@ -2228,9 +2454,14 @@ 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` only the two emitted variants are checked
+* (the high-contrast slots are mirrors), and the spec is resolved at the level
+* so the check measures the output against the target it was actually solved
+* for.
 */
 function verifyContrastDrift(order, defs, result, config) {
 	const roles = /* @__PURE__ */ new Map();
@@ -2243,7 +2474,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,
@@ -2264,8 +2495,11 @@ function verifyContrastDrift(order, defs, result, config) {
 				isHighContrast: true,
 				field: "darkContrast"
 			}
-		]) {
-			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast, polarity);
+		];
+		const manual = contrastFraction(config) !== void 0;
+		for (const s of schemes) {
+			if (manual && 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);
@@ -2278,26 +2512,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 manual = contrastFraction(config) !== void 0;
 	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 (!manual) {
+		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 (!manual) {
+		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,
@@ -2316,8 +2556,12 @@ 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 `darkHueDeclarations`.
 */
 const ACHROMATIC_EPSILON = 1e-6;
 function cssProp(prefix, name, suffix) {
@@ -2326,7 +2570,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,
@@ -2334,13 +2582,25 @@ 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) {
+		const pinned = resolveEffectiveHue(ctx.seedHue, regDef.hue);
+		return {
+			hueVar: `var(${prop})`,
+			inline: false,
+			declarations: [{
+				prop,
+				value: String(pinned)
+			}]
+		};
+	}
+	const authored = scheme === "dark" ? regDef.darkHue ?? regDef.hue : regDef.hue;
+	if (authored === void 0) return {
 		hueVar: baseHueVar,
 		inline: false,
 		declarations: []
 	};
-	const parsed = parseRelativeOrAbsolute(regDef.hue);
-	const prop = cssProp(ctx.prefix, name, "-hue");
+	const parsed = parseRelativeOrAbsolute(authored);
 	if (parsed.relative) {
 		const sign = parsed.value >= 0 ? "+" : "-";
 		const magnitude = Math.abs(parsed.value);
@@ -2364,13 +2624,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})`,
@@ -2381,12 +2641,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 = "light") {
 	if (ctx.emitDeclarations === false) return [];
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
@@ -2397,15 +2657,32 @@ 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;
 }
+/**
+* Dark-scheme hue declarations, or `[]` when dark resolves to the same hues as
+* light (the common case — no `darkHue` anywhere).
+*
+* When they differ, the **whole** 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 darkHueDeclarations(resolved, ctx) {
+	const dark = collectHueDeclarations(resolved, ctx, "dark");
+	const light = collectHueDeclarations(resolved, ctx, "light");
+	return 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));
@@ -2468,28 +2745,41 @@ 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.
+*
+* A global manual `contrastLevel` turns off high-contrast output outright: the
+* level *is* the contrast preference, so a separate high-contrast tier has no
+* meaning alongside it. `modes.highContrast` therefore reads as "emit a separate
+* high-contrast set **when** contrast is automatic" — it goes inert under a
+* manual level rather than fighting it, and silently, since switching a
+* preference from auto to manual is normal use and not a mistake to report.
+*
+* A level set on a single theme or token does not change which modes are
+* emitted: sibling themes in a palette may still have a real high-contrast
+* tier, and the manual one correctly reports its own resolved values there —
+* the alternative would drop its colors from that tier entirely.
+*/
 function resolveModes(override) {
 	const cfg = getConfig();
 	return {
 		dark: override?.dark ?? cfg.modes.dark,
-		highContrast: override?.highContrast ?? cfg.modes.highContrast
+		highContrast: contrastFraction(cfg) !== void 0 ? false : override?.highContrast ?? cfg.modes.highContrast
 	};
 }
 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));
+		for (const decl of collectHueDeclarations(resolved, channelCtx)) tokens[`$${decl.prop.slice(2)}`] = { "": decl.value };
+		if (modes.dark) for (const decl of darkHueDeclarations(resolved, channelCtx)) {
+			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) {
@@ -2538,7 +2828,13 @@ 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) {
+		for (const decl of collectHueDeclarations(resolved, channelCtx)) lines.light.push(`${decl.prop}: ${decl.value};`);
+		for (const decl of darkHueDeclarations(resolved, channelCtx)) {
+			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);
@@ -2975,6 +3271,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);
 }
 /**
@@ -3021,11 +3324,27 @@ function extractOkhslFromValue(value) {
 	return value;
 }
 /**
+* 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 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.
 *
 * 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
@@ -3043,10 +3362,13 @@ 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",
 		autoFlip: options?.autoFlip,
@@ -3063,13 +3385,16 @@ 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, configOverride, baseToken, buildExport) {
+function createColorTokenFromDefs(seed, defs, primary, configOverride, baseToken, buildExport) {
 	let cache = null;
 	function getEffectiveConfig() {
 		const version = getConfigVersion();
@@ -3086,7 +3411,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, config
 		const version = getConfigVersion();
 		if (cache && cache.version === version && cache.map) return cache.map;
 		const effectiveConfig = getEffectiveConfig();
-		const map = resolveAllColors(seedHue, seedSaturation, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
+		const map = resolveAllColors(seed, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
 		cache = {
 			map,
 			version,
@@ -3124,7 +3449,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, config
 			if (options.splitHue && format === "oklch") {
 				assertAllPastel(renamed, resolveModes());
 				channelCtx = {
-					seedHue,
+					seedHue: seed.hue,
 					baseName: options.name,
 					prefix: "",
 					defs: { [options.name]: defs[primary] },
@@ -3208,8 +3533,10 @@ 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",
 		autoFlip: input.autoFlip,
 		contrast: input.contrast,
@@ -3218,16 +3545,17 @@ function createColorToken(input, configOverride) {
 		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"
-		};
-	}
+	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
+		tone: pinExtremeTone(pairNormal(input.tone)),
+		saturation: 1,
+		mode: "static"
+	};
 	const localOverride = configOverride;
-	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, localOverride, baseToken, (exportArg) => ({
+	return createColorTokenFromDefs({
+		hue: input.hue,
+		saturation: input.saturation,
+		darkSaturation: input.darkSaturation
+	}, defs, primary, localOverride, baseToken, (exportArg) => ({
 		kind: "color",
 		version: GLAZE_EXPORT_VERSION,
 		form: "structured",
@@ -3238,9 +3566,9 @@ function createColorToken(input, configOverride) {
 function createColorTokenFromValue(value, options, configOverride) {
 	const main = extractOkhslFromValue(value);
 	const linkingBase = toLinkingBase(resolveBaseToken(options?.base));
-	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options);
+	const { seed, defs, primary } = buildStandaloneValueDefs(main, options);
 	const localOverride = sparseValueFormLocal(configOverride);
-	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, localOverride, linkingBase, (exportArg) => ({
+	return createColorTokenFromDefs(seed, defs, primary, localOverride, linkingBase, (exportArg) => ({
 		kind: "color",
 		version: GLAZE_EXPORT_VERSION,
 		form: "value",
@@ -3260,6 +3588,9 @@ function buildOverridesExport(options, exportArg) {
 	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.autoFlip !== void 0) out.autoFlip = options.autoFlip;
 	if (options.contrast !== void 0) out.contrast = options.contrast;
@@ -3277,6 +3608,9 @@ function buildStructuredInputExport(input, exportArg) {
 		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.autoFlip !== void 0) out.autoFlip = input.autoFlip;
 	if (input.opacity !== void 0) out.opacity = input.opacity;
@@ -3299,6 +3633,9 @@ 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.autoFlip !== void 0) out.autoFlip = data.autoFlip;
 	if (data.contrast !== void 0) out.contrast = data.contrast;
@@ -3316,6 +3653,9 @@ 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.autoFlip !== void 0) out.autoFlip = data.autoFlip;
 	if (data.opacity !== void 0) out.opacity = data.opacity;
@@ -3349,7 +3689,8 @@ function colorFromExport(data) {
 
 //#endregion
 //#region src/theme.ts
-function createTheme(hue, saturation, initialColors, configOverride) {
+function createTheme(seed, initialColors, configOverride) {
+	const { hue, saturation, darkHue, darkSaturation } = seed;
 	let colorDefs = initialColors ? { ...initialColors } : {};
 	let cache = null;
 	function getEffectiveConfig() {
@@ -3367,7 +3708,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 		const version = getConfigVersion();
 		if (cache && cache.version === version && cache.map) return cache.map;
 		const effectiveConfig = getEffectiveConfig();
-		const map = resolveAllColors(hue, saturation, colorDefs, effectiveConfig);
+		const map = resolveAllColors(seed, colorDefs, effectiveConfig);
 		cache = {
 			map,
 			version,
@@ -3384,6 +3725,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 		assertAllPastel(resolveCached(), resolveModes(options?.modes));
 		return {
 			seedHue: hue,
+			darkSeedHue: darkHue,
 			baseName: options.name ?? "theme",
 			prefix,
 			defs: colorDefs,
@@ -3397,6 +3739,12 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 		get saturation() {
 			return saturation;
 		},
+		get darkHue() {
+			return darkHue;
+		},
+		get darkSaturation() {
+			return darkSaturation;
+		},
 		getConfig() {
 			return getEffectiveConfig();
 		},
@@ -3433,16 +3781,22 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 				version: GLAZE_EXPORT_VERSION,
 				hue,
 				saturation,
+				...darkHue !== void 0 ? { darkHue } : {},
+				...darkSaturation !== void 0 ? { darkSaturation } : {},
 				colors: structuredClone(colorDefs),
 				config: freezeConfigForExport(configOverride, override)
 			};
 		},
 		extend(options) {
-			const newHue = options.hue ?? hue;
-			const newSat = options.saturation ?? saturation;
+			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(newHue, newSat, options.colors ? {
+			return createTheme(childSeed, options.colors ? {
 				...inheritedColors,
 				...options.colors
 			} : { ...inheritedColors }, configOverride || options.config ? {
@@ -3552,6 +3906,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),
@@ -3583,7 +3938,13 @@ function createThemeFromExport(data, factory = "glaze.themeFrom") {
 	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.`);
-	return createTheme(data.hue, data.saturation, data.colors, data.config);
+	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.
@@ -3745,18 +4106,28 @@ function createPalette(themes, paletteOptions) {
 * 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) {
@@ -3870,7 +4241,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).
@@ -3882,7 +4256,10 @@ 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.
@@ -3964,6 +4341,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;