@tenphi/glaze 1.2.0 → 1.3.1

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
@@ -2002,13 +2188,15 @@ function applyToneFlip(delta, baseTone, flip) {
 * 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 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);
 }
-function resolveRootColor(def, isHighContrast) {
-	const rawT = def.tone;
-	return clamp(parseToneValue(isHighContrast ? pairHC(rawT) : pairNormal(rawT)).value, 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.
@@ -2053,39 +2241,50 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, channels,
 	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 if (parsed.kind === "extreme" && isDark && mode !== "static") {
-			isExtreme = true;
-			preferredTone = extremeDarkTone(parsed.value, mode, isHighContrast, baseResolved, baseTone, ctx.config);
-		} else {
+		else {
 			isExtreme = parsed.kind === "extreme";
-			preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, ctx.config);
+			if (isExtreme && isDark && mode !== "static") preferredTone = extremeDarkTone(parsed.value, mode, isHighContrast, baseResolved, ctx.config);
+			else preferredTone = mapToneForScheme(parsed.value, mode, isDark, isHighContrast, ctx.config);
 		}
 	}
 	const rawContrast = def.contrast;
 	if (rawContrast !== void 0) {
-		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast, polarity);
+		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);
+		const preferredRange = isExtreme ? [0, 1] : schemeToneRange(isDark, mode, isHighContrast, ctx.config);
 		let initialDirection;
 		if (preferredTone < baseTone) initialDirection = "darker";
 		else if (preferredTone > baseTone) initialDirection = "lighter";
-		const seedTone = isExtreme ? clamp(preferredTone / 100, 0, 1) : clamp(preferredTone / 100, toneRange[0], toneRange[1]);
-		const result = findToneForContrast({
+		const solve = {
 			hue: channels.hue,
 			saturation: channels.saturation,
-			preferredTone: seedTone,
+			preferredTone: clamp(preferredTone / 100, preferredRange[0], preferredRange[1]),
 			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 result.tone * 100;
@@ -2101,7 +2300,7 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	const channels = resolveChannels(regDef, ctx, isDark);
 	const polarity = roleToPolarity(resolveRole(name, def, ctx));
 	const pastel = regDef.pastel ?? ctx.config.pastel;
-	const finalTone = isRoot ? mapToneForScheme(resolveRootColor(regDef, isHighContrast), mode, isDark, isHighContrast, ctx.config) : resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, channels, polarity, pastel);
+	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: channels.hue,
 		s: channels.saturation,
@@ -2114,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)),
@@ -2163,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));
@@ -2171,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));
@@ -2255,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();
@@ -2270,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,
@@ -2291,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);
@@ -2316,14 +2523,21 @@ function resolveAllColors(seed, defs, config, externalBases) {
 		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,
@@ -2347,7 +2561,9 @@ function resolveAllColors(seed, defs, config, externalBases) {
 *
 * 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`.
+* 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) {
@@ -2369,23 +2585,28 @@ function themeHuePlan(name, def, variant, ctx, scheme) {
 	const regDef = def;
 	const baseHueVar = `var(--${ctx.baseName}-hue)`;
 	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 {
+	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) return {
 		hueVar: baseHueVar,
 		inline: false,
 		declarations: []
 	};
+	const authored = scheme === "dark" ? regDef.darkHue ?? regDef.hue : regDef.hue;
+	if (authored === void 0) return {
+		hueVar: `var(${prop})`,
+		inline: false,
+		declarations: [{
+			prop,
+			value: baseHueVar
+		}]
+	};
 	const parsed = parseRelativeOrAbsolute(authored);
 	if (parsed.relative) {
 		const sign = parsed.value >= 0 ? "+" : "-";
@@ -2432,7 +2653,7 @@ function buildHuePlan(name, def, variant, ctx, scheme = "light") {
 	return themeHuePlan(name, def, variant, ctx, scheme);
 }
 /** Collect unique hue declarations across all colors (theme + per-color). */
-function collectHueDeclarations(resolved, ctx, scheme = "light") {
+function collectHueDeclarations(resolved, ctx, scheme) {
 	if (ctx.emitDeclarations === false) return [];
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
@@ -2453,21 +2674,24 @@ function collectHueDeclarations(resolved, ctx, scheme = "light") {
 	return out;
 }
 /**
-* Dark-scheme hue declarations, or `[]` when dark resolves to the same hues as
-* light (the common case — no `darkHue` anywhere).
+* 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** set is returned rather than only the entries
-* whose text changed. A relative declaration reads
+* 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 darkHueDeclarations(resolved, ctx) {
-	const dark = collectHueDeclarations(resolved, ctx, "dark");
+function buildHueDeclarations(resolved, ctx) {
 	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;
+	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();
@@ -2531,19 +2755,35 @@ 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) {
-		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 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],
@@ -2600,8 +2840,9 @@ function buildCssMap(resolved, prefix, suffix, format, pastel = false, channelCt
 	};
 	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};`);
-		for (const decl of darkHueDeclarations(resolved, channelCtx)) {
+		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};`);
 		}
@@ -4112,6 +4353,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;