@tenphi/glaze 0.11.1 → 0.13.0

package/dist/index.cjs

@@ -579,7 +579,8 @@ function defaultConfig() {
 		modes: {
 			dark: true,
 			highContrast: false
-		}
+		},
+		autoFlip: true
 	};
 }
 let globalConfig = defaultConfig();
@@ -618,13 +619,33 @@ function configure(config) {
 			dark: config.modes?.dark ?? globalConfig.modes.dark,
 			highContrast: config.modes?.highContrast ?? globalConfig.modes.highContrast
 		},
-		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning
+		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
+		autoFlip: config.autoFlip ?? globalConfig.autoFlip
 	};
 }
 function resetConfig() {
 	configVersion++;
 	globalConfig = defaultConfig();
 }
+/**
+* Merge a per-instance config override over a base resolved config.
+* Only fields present in `override` are replaced; others fall through
+* from `base`. `false` for lightness windows passes through as-is
+* (treated as `[0, 100]` by `lightnessWindow()` in scheme-mapping).
+*/
+function mergeConfig(base, override) {
+	if (!override) return base;
+	return {
+		lightLightness: override.lightLightness !== void 0 ? override.lightLightness : base.lightLightness,
+		darkLightness: override.darkLightness !== void 0 ? override.darkLightness : base.darkLightness,
+		darkDesaturation: override.darkDesaturation ?? base.darkDesaturation,
+		darkCurve: override.darkCurve ?? base.darkCurve,
+		states: base.states,
+		modes: base.modes,
+		shadowTuning: override.shadowTuning ?? base.shadowTuning,
+		autoFlip: override.autoFlip ?? base.autoFlip
+	};
+}
 
 //#endregion
 //#region src/hc-pair.ts
@@ -827,47 +848,64 @@ function findLightnessForContrast(options) {
 		branch: "preferred"
 	};
 	const [minL, maxL] = lightnessRange;
-	const darkerResult = preferredLightness > minL ? searchBranch(hue, saturation, minL, preferredLightness, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : null;
-	const lighterResult = preferredLightness < maxL ? searchBranch(hue, saturation, preferredLightness, maxL, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : null;
-	if (darkerResult) darkerResult.met = darkerResult.contrast >= target;
-	if (lighterResult) lighterResult.met = lighterResult.contrast >= target;
-	const darkerPasses = darkerResult?.met ?? false;
-	const lighterPasses = lighterResult?.met ?? false;
-	if (darkerPasses && lighterPasses) {
-		if (Math.abs(darkerResult.lightness - preferredLightness) <= Math.abs(lighterResult.lightness - preferredLightness)) return {
-			...darkerResult,
-			branch: "darker"
-		};
-		return {
-			...lighterResult,
-			branch: "lighter"
-		};
-	}
-	if (darkerPasses) return {
-		...darkerResult,
-		branch: "darker"
-	};
-	if (lighterPasses) return {
-		...lighterResult,
-		branch: "lighter"
-	};
-	const candidates = [];
-	if (darkerResult) candidates.push({
-		...darkerResult,
-		branch: "darker"
-	});
-	if (lighterResult) candidates.push({
-		...lighterResult,
-		branch: "lighter"
-	});
-	if (candidates.length === 0) return {
+	const canDarker = preferredLightness > minL;
+	const canLighter = preferredLightness < maxL;
+	let initialIsDarker;
+	if (options.initialDirection !== void 0) initialIsDarker = options.initialDirection === "darker";
+	else if (canDarker && !canLighter) initialIsDarker = true;
+	else if (!canDarker && canLighter) initialIsDarker = false;
+	else if (!canDarker && !canLighter) return {
 		lightness: preferredLightness,
 		contrast: crPref,
 		met: false,
 		branch: "preferred"
 	};
-	candidates.sort((a, b) => b.contrast - a.contrast);
-	return candidates[0];
+	else {
+		const yMinExt = cachedLuminance(hue, saturation, minL);
+		const yMaxExt = cachedLuminance(hue, saturation, maxL);
+		initialIsDarker = contrastRatioFromLuminance(yMinExt, yBase) >= contrastRatioFromLuminance(yMaxExt, yBase);
+	}
+	const searchInitial = () => initialIsDarker ? searchBranch(hue, saturation, minL, preferredLightness, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : searchBranch(hue, saturation, preferredLightness, maxL, yBase, searchTarget, epsilon, maxIterations, preferredLightness);
+	const searchOpposite = () => initialIsDarker ? searchBranch(hue, saturation, preferredLightness, maxL, yBase, searchTarget, epsilon, maxIterations, preferredLightness) : searchBranch(hue, saturation, minL, preferredLightness, yBase, searchTarget, epsilon, maxIterations, preferredLightness);
+	const initialBranchName = initialIsDarker ? "darker" : "lighter";
+	const oppositeBranchName = initialIsDarker ? "lighter" : "darker";
+	const initialResult = searchInitial();
+	initialResult.met = initialResult.contrast >= target;
+	if (initialResult.met && !options.flip) return {
+		...initialResult,
+		branch: initialBranchName
+	};
+	if (options.flip) {
+		const oppositeResult = (initialIsDarker ? canLighter : canDarker) ? searchOpposite() : null;
+		if (oppositeResult) oppositeResult.met = oppositeResult.contrast >= target;
+		if (initialResult.met && oppositeResult?.met) {
+			if (Math.abs(initialResult.lightness - preferredLightness) <= Math.abs(oppositeResult.lightness - preferredLightness)) return {
+				...initialResult,
+				branch: initialBranchName
+			};
+			return {
+				...oppositeResult,
+				branch: oppositeBranchName,
+				flipped: true
+			};
+		}
+		if (initialResult.met) return {
+			...initialResult,
+			branch: initialBranchName
+		};
+		if (oppositeResult?.met) return {
+			...oppositeResult,
+			branch: oppositeBranchName,
+			flipped: true
+		};
+	}
+	const extreme = initialIsDarker ? minL : maxL;
+	return {
+		lightness: extreme,
+		contrast: contrastRatioFromLuminance(cachedLuminance(hue, saturation, extreme), yBase),
+		met: false,
+		branch: initialBranchName
+	};
 }
 /**
 * Binary-search one branch [lo, hi] for the nearest passing mix value
@@ -949,53 +987,59 @@ function findValueForMixContrast(options) {
 		contrast: crPref,
 		met: true
 	};
-	const darkerResult = preferredValue > 0 ? searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
-	const lighterResult = preferredValue < 1 ? searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
-	if (darkerResult) darkerResult.met = darkerResult.contrast >= target;
-	if (lighterResult) lighterResult.met = lighterResult.contrast >= target;
-	const darkerPasses = darkerResult?.met ?? false;
-	const lighterPasses = lighterResult?.met ?? false;
-	if (darkerPasses && lighterPasses) {
-		if (Math.abs(darkerResult.lightness - preferredValue) <= Math.abs(lighterResult.lightness - preferredValue)) return {
-			value: darkerResult.lightness,
-			contrast: darkerResult.contrast,
-			met: true
-		};
-		return {
-			value: lighterResult.lightness,
-			contrast: lighterResult.contrast,
-			met: true
-		};
-	}
-	if (darkerPasses) return {
-		value: darkerResult.lightness,
-		contrast: darkerResult.contrast,
-		met: true
-	};
-	if (lighterPasses) return {
-		value: lighterResult.lightness,
-		contrast: lighterResult.contrast,
-		met: true
-	};
-	const candidates = [];
-	if (darkerResult) candidates.push({
-		...darkerResult,
-		branch: "lower"
-	});
-	if (lighterResult) candidates.push({
-		...lighterResult,
-		branch: "upper"
-	});
-	if (candidates.length === 0) return {
+	const canLower = preferredValue > 0;
+	const canUpper = preferredValue < 1;
+	let initialIsLower;
+	if (canLower && !canUpper) initialIsLower = true;
+	else if (!canLower && canUpper) initialIsLower = false;
+	else if (!canLower && !canUpper) return {
 		value: preferredValue,
 		contrast: crPref,
 		met: false
 	};
-	candidates.sort((a, b) => b.contrast - a.contrast);
+	else initialIsLower = contrastRatioFromLuminance(luminanceAtValue(0), yBase) >= contrastRatioFromLuminance(luminanceAtValue(1), yBase);
+	const searchInitial = () => initialIsLower ? searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue);
+	const searchOpposite = () => initialIsLower ? searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue);
+	const initialResult = searchInitial();
+	initialResult.met = initialResult.contrast >= target;
+	if (initialResult.met && !options.flip) return {
+		value: initialResult.lightness,
+		contrast: initialResult.contrast,
+		met: true
+	};
+	if (options.flip) {
+		const oppositeResult = (initialIsLower ? canUpper : canLower) ? searchOpposite() : null;
+		if (oppositeResult) oppositeResult.met = oppositeResult.contrast >= target;
+		if (initialResult.met && oppositeResult?.met) {
+			if (Math.abs(initialResult.lightness - preferredValue) <= Math.abs(oppositeResult.lightness - preferredValue)) return {
+				value: initialResult.lightness,
+				contrast: initialResult.contrast,
+				met: true
+			};
+			return {
+				value: oppositeResult.lightness,
+				contrast: oppositeResult.contrast,
+				met: true,
+				flipped: true
+			};
+		}
+		if (initialResult.met) return {
+			value: initialResult.lightness,
+			contrast: initialResult.contrast,
+			met: true
+		};
+		if (oppositeResult?.met) return {
+			value: oppositeResult.lightness,
+			contrast: oppositeResult.contrast,
+			met: true,
+			flipped: true
+		};
+	}
+	const extreme = initialIsLower ? 0 : 1;
 	return {
-		value: candidates[0].lightness,
-		contrast: candidates[0].contrast,
-		met: candidates[0].met
+		value: extreme,
+		contrast: contrastRatioFromLuminance(luminanceAtValue(extreme), yBase),
+		met: false
 	};
 }
 
@@ -1024,8 +1068,7 @@ const DEFAULT_SHADOW_TUNING = {
 	alphaMax: 1,
 	bgHueBlend: .2
 };
-function resolveShadowTuning(perColor) {
-	const globalTuning = getConfig().shadowTuning;
+function resolveShadowTuning(perColor, globalTuning) {
 	return {
 		...DEFAULT_SHADOW_TUNING,
 		...globalTuning,
@@ -1077,61 +1120,58 @@ function computeShadow(bg, fg, intensity, tuning) {
 /**
 * Light / dark scheme lightness mappings.
 *
-* Owns the active lightness window selection (with per-call scaling
-* overrides and high-contrast handling), the Möbius curve used by the
-* `'auto'` dark adaptation, and the saturation-desaturation reducer
-* for dark mode.
+* Owns the active lightness window selection (from a resolved effective
+* config passed in), the Möbius curve used by the `'auto'` dark
+* adaptation, and the saturation-desaturation reducer for dark mode.
+*
+* All functions take a `GlazeConfigResolved` so the full config
+* (including per-instance overrides) is available without re-reading
+* the global singleton inside the resolver.
 */
 /**
 * Resolve the active lightness window for a scheme.
-* - HC variants always return `[0, 100]` (existing behavior, predates per-call overrides).
-* - Otherwise, per-call `scaling` (e.g. from `glaze.color()`'s third arg) wins;
-*   `false` is interpreted as `[0, 100]` (no remap). Falls back to `globalConfig.*Lightness`.
+* - HC variants always return `[0, 100]` (no clamping in high-contrast).
+* - `false` (= "no clamping") is treated as `[0, 100]`.
+* - Otherwise uses the window from the resolved effective config.
 */
-function lightnessWindow(isHighContrast, kind, scaling) {
+function lightnessWindow(isHighContrast, kind, config) {
 	if (isHighContrast) return [0, 100];
-	if (scaling) {
-		const override = kind === "dark" ? scaling.darkLightness : scaling.lightLightness;
-		if (override === false) return [0, 100];
-		if (override !== void 0) return override;
-	}
-	const cfg = getConfig();
-	return kind === "dark" ? cfg.darkLightness : cfg.lightLightness;
+	const win = kind === "dark" ? config.darkLightness : config.lightLightness;
+	if (win === false) return [0, 100];
+	return win;
 }
-function mapLightnessLight(l, mode, isHighContrast, scaling) {
+function mapLightnessLight(l, mode, isHighContrast, config) {
 	if (mode === "static") return l;
-	const [lo, hi] = lightnessWindow(isHighContrast, "light", scaling);
+	const [lo, hi] = lightnessWindow(isHighContrast, "light", config);
 	return l * (hi - lo) / 100 + lo;
 }
 function mobiusCurve(t, beta) {
 	if (beta >= 1) return t;
 	return t / (t + beta * (1 - t));
 }
-function mapLightnessDark(l, mode, isHighContrast, scaling) {
+function mapLightnessDark(l, mode, isHighContrast, config) {
 	if (mode === "static") return l;
-	const cfg = getConfig();
-	const beta = isHighContrast ? pairHC(cfg.darkCurve) : pairNormal(cfg.darkCurve);
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", scaling);
+	const beta = isHighContrast ? pairHC(config.darkCurve) : pairNormal(config.darkCurve);
+	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", config);
 	if (mode === "fixed") return l * (darkHi - darkLo) / 100 + darkLo;
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", scaling);
+	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", config);
 	const t = (lightHi - (l * (lightHi - lightLo) / 100 + lightLo)) / (lightHi - lightLo);
 	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
 }
-function lightMappedToDark(lightL, isHighContrast, scaling) {
-	const cfg = getConfig();
-	const beta = isHighContrast ? pairHC(cfg.darkCurve) : pairNormal(cfg.darkCurve);
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", scaling);
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", scaling);
+function lightMappedToDark(lightL, isHighContrast, config) {
+	const beta = isHighContrast ? pairHC(config.darkCurve) : pairNormal(config.darkCurve);
+	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", config);
+	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", config);
 	const t = (lightHi - clamp(lightL, lightLo, lightHi)) / (lightHi - lightLo);
 	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
 }
-function mapSaturationDark(s, mode) {
+function mapSaturationDark(s, mode, config) {
 	if (mode === "static") return s;
-	return s * (1 - getConfig().darkDesaturation);
+	return s * (1 - config.darkDesaturation);
 }
-function schemeLightnessRange(isDark, mode, isHighContrast, scaling) {
+function schemeLightnessRange(isDark, mode, isHighContrast, config) {
 	if (mode === "static") return [0, 1];
-	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light", scaling);
+	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light", config);
 	return [lo / 100, hi / 100];
 }
 
@@ -1269,6 +1309,10 @@ function warnContrastUnmet(name, isDark, isHighContrast, target, actual) {
 * turns a `ColorMap` into a fully resolved `ResolvedColor` per name.
 * Owns the per-scheme resolve helpers for regular, shadow, and mix
 * color defs.
+*
+* Every function receives a single `GlazeConfigResolved` so the full
+* per-instance config (including overrides) is available without
+* re-reading the global singleton mid-resolve.
 */
 function getSchemeVariant(color, isDark, isHighContrast) {
 	if (isDark && isHighContrast) return color.darkContrast;
@@ -1298,24 +1342,29 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 		const parsed = parseRelativeOrAbsolute(isHighContrast ? pairHC(rawLightness) : pairNormal(rawLightness));
 		if (parsed.relative) {
 			const delta = parsed.value;
-			if (isDark && mode === "auto") preferredL = lightMappedToDark(clamp(getSchemeVariant(baseResolved, false, isHighContrast).l * 100 + delta, 0, 100), isHighContrast, ctx.scaling);
+			if (isDark && mode === "auto") preferredL = lightMappedToDark(clamp(getSchemeVariant(baseResolved, false, isHighContrast).l * 100 + delta, 0, 100), isHighContrast, ctx.config);
 			else preferredL = clamp(baseL + delta, 0, 100);
-		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode, isHighContrast, ctx.scaling);
-		else preferredL = mapLightnessLight(parsed.value, mode, isHighContrast, ctx.scaling);
+		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode, isHighContrast, ctx.config);
+		else preferredL = mapLightnessLight(parsed.value, mode, isHighContrast, ctx.config);
 	}
 	const rawContrast = def.contrast;
 	if (rawContrast !== void 0) {
 		const minCr = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
-		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode) : satFactor * ctx.saturation / 100;
+		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config) : satFactor * ctx.saturation / 100;
 		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
-		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast, ctx.scaling);
+		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast, ctx.config);
+		let initialDirection;
+		if (preferredL < baseL) initialDirection = "darker";
+		else if (preferredL > baseL) initialDirection = "lighter";
 		const result = findLightnessForContrast({
 			hue: effectiveHue,
 			saturation: effectiveSat,
 			preferredLightness: clamp(preferredL / 100, windowRange[0], windowRange[1]),
 			baseLinearRgb,
 			contrast: minCr,
-			lightnessRange: [0, 1]
+			lightnessRange: [0, 1],
+			initialDirection,
+			flip: ctx.config.autoFlip
 		});
 		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, minCr, result.contrast);
 		return {
@@ -1349,13 +1398,13 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	let finalL;
 	let finalSat;
 	if (isDark && isRoot) {
-		finalL = mapLightnessDark(lightL, mode, isHighContrast, ctx.scaling);
-		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
+		finalL = mapLightnessDark(lightL, mode, isHighContrast, ctx.config);
+		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config);
 	} else if (isDark && !isRoot) {
 		finalL = lightL;
-		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
+		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config);
 	} else if (isRoot) {
-		finalL = mapLightnessLight(lightL, mode, isHighContrast, ctx.scaling);
+		finalL = mapLightnessLight(lightL, mode, isHighContrast, ctx.config);
 		finalSat = satFactor * ctx.saturation / 100;
 	} else {
 		finalL = lightL;
@@ -1373,7 +1422,7 @@ function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
 	let fgVariant;
 	if (def.fg) fgVariant = getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast);
 	const intensity = isHighContrast ? pairHC(def.intensity) : pairNormal(def.intensity);
-	const tuning = resolveShadowTuning(def.tuning);
+	const tuning = resolveShadowTuning(def.tuning, ctx.config.shadowTuning);
 	return computeShadow(bgVariant, fgVariant, intensity, tuning);
 }
 function variantToLinearRgb(v) {
@@ -1436,7 +1485,8 @@ function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
 			baseLinearRgb: baseLinear,
 			targetLinearRgb: targetLinear,
 			contrast: minCr,
-			luminanceAtValue: luminanceAt
+			luminanceAtValue: luminanceAt,
+			flip: ctx.config.autoFlip
 		}).value;
 	}
 	if (blend === "transparent") return {
@@ -1497,7 +1547,7 @@ function seedField(order, ctx, field, source) {
 		});
 	}
 }
-function resolveAllColors(hue, saturation, defs, scaling, externalBases) {
+function resolveAllColors(hue, saturation, defs, config, externalBases) {
 	validateColorDefs(defs, externalBases);
 	const order = topoSort(defs);
 	const ctx = {
@@ -1505,7 +1555,7 @@ function resolveAllColors(hue, saturation, defs, scaling, externalBases) {
 		saturation,
 		defs,
 		resolved: /* @__PURE__ */ new Map(),
-		scaling
+		config
 	};
 	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
 	const lightMap = runPass(order, defs, ctx, false, false, "light");
@@ -1627,15 +1677,16 @@ function buildCssMap(resolved, prefix, suffix, format) {
 * Standalone single-color tokens (`glaze.color()` / `glaze.colorFrom()`).
 *
 * Owns the value-shorthand parser (hex, `rgb()` / `hsl()` / `okhsl()` /
-* `oklch()`, OkhslColor object, [r, g, b] tuple), the structured-input
+* `oklch()`, `{ r, g, b }`, `{ h, s, l }`, `{ 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 relevant `globalConfig` fields at
-* create time so later `configure()` calls do not retroactively change
-* exported tokens — the snapshot is captured eagerly in
-* `defaultStandaloneScaling()`. The token's resolved variants are then
-* memoized on first `.resolve()` / `.token()` / ... call.
+* 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";
@@ -1650,44 +1701,47 @@ const RESERVED_STANDALONE_NAMES = new Set([
 	STANDALONE_BASE
 ]);
 /**
-* Build the create-time scaling snapshot used when the caller did not
-* pass an explicit `scaling`. All windows are snapshotted from the
-* current `globalConfig` so later `glaze.configure()` calls don't
-* retroactively change the resolved variants of an already-created
-* token (matches the documented "frozen at create time" semantics).
+* Build the per-token effective config override for a value-form color.
 *
-* String value-shorthand inputs preserve their light lightness exactly
-* (`lightLightness: false`) and use an extended dark window
-* `[globalConfig.darkLightness[0], 100]` so a totally-black input can
-* Möbius-invert to totally-white in dark mode. Object / tuple /
-* structured inputs snapshot both windows from `globalConfig` verbatim
-* so they behave like an ordinary theme color (auto-adapted on both
-* sides).
-*/
-function defaultStandaloneScaling(isString) {
+* Light window defaults to `false` (preserve input lightness exactly).
+* All other fields snapshot from global at create time. User override
+* fields win over all defaults.
+*/
+function buildValueFormConfigOverride(userOverride) {
 	const cfg = getConfig();
-	if (isString) {
-		const [darkLo] = cfg.darkLightness;
-		return {
-			lightLightness: false,
-			darkLightness: [darkLo, 100]
-		};
-	}
 	return {
-		lightLightness: cfg.lightLightness,
-		darkLightness: cfg.darkLightness
+		lightLightness: userOverride?.lightLightness !== void 0 ? userOverride.lightLightness : false,
+		darkLightness: userOverride?.darkLightness !== void 0 ? userOverride.darkLightness : cfg.darkLightness,
+		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
+		darkCurve: userOverride?.darkCurve ?? cfg.darkCurve,
+		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
+		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
 	};
 }
 /**
-* Discriminate a `GlazeColorToken` from a raw `GlazeColorValue`.
-* Used to widen `base?` so it accepts either a token reference or a
-* raw value (auto-wrapped into `glaze.color(value)`).
+* 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 isGlazeColorToken(candidate) {
-	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "resolve" in candidate && typeof candidate.resolve === "function";
+function buildStructuredConfigOverride(userOverride) {
+	const cfg = getConfig();
+	return {
+		lightLightness: userOverride?.lightLightness !== void 0 ? userOverride.lightLightness : cfg.lightLightness,
+		darkLightness: userOverride?.darkLightness !== void 0 ? userOverride.darkLightness : cfg.darkLightness,
+		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
+		darkCurve: userOverride?.darkCurve ?? cfg.darkCurve,
+		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
+		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
+	};
 }
-function isStructuredColorInput(input) {
-	return typeof input === "object" && input !== null && !Array.isArray(input) && "hue" in input && "lightness" in input;
+/**
+* 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()`,
@@ -1806,9 +1860,41 @@ function validateOkhslColor(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, lightness } (which uses 0–100)?");
 }
-/** Validate a user-supplied `[r, g, b]` tuple in 0-255. */
-function validateRgbTuple(value) {
-	for (const n of value) if (!Number.isFinite(n) || n < 0 || n > 255) throw new Error(`glaze.color: RGB tuple components must be finite numbers in 0–255 (got [${value.join(", ")}]).`);
+/** 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;
 }
 /**
 * Validate a user-supplied `opacity` override on `glaze.color()`.
@@ -1854,18 +1940,17 @@ function validateStandaloneName(name) {
 /**
 * Extract an OKHSL color from any `GlazeColorValue` form. Also used by
 * `glaze.shadow()` so all shadow inputs (hex, color functions, OKHSL,
-* RGB tuple) go through one parser.
+* literal objects) go through one parser.
 */
 function extractOkhslFromValue(value) {
 	if (typeof value === "string") return parseColorString(value);
-	if (Array.isArray(value)) {
-		const tuple = value;
-		validateRgbTuple(tuple);
-		const [r, g, b] = tuple;
+	if (Array.isArray(value)) throw new Error("glaze.color: RGB tuple [r, g, b] is no longer supported — use { r, g, b } instead.");
+	if (isRgbColorObject(value)) {
+		validateRgbColor(value);
 		const [h, s, l] = srgbToOkhsl([
-			r / 255,
-			g / 255,
-			b / 255
+			value.r / 255,
+			value.g / 255,
+			value.b / 255
 		]);
 		return {
 			h,
@@ -1873,6 +1958,10 @@ function extractOkhslFromValue(value) {
 			l
 		};
 	}
+	if (isOklchColorObject(value)) {
+		validateOklchColor(value);
+		return oklchComponentsToOkhsl(value.l, value.c, value.h);
+	}
 	validateOkhslColor(value);
 	return value;
 }
@@ -1880,11 +1969,7 @@ function extractOkhslFromValue(value) {
 * Build the `ColorMap` for a value-shorthand `glaze.color()` call.
 *
 * The user-facing color (`STANDALONE_VALUE`) defaults to `mode: 'auto'`
-* across every value-shorthand form. String inputs pair with the
-* extended dark window so a totally-black input renders as totally-white
-* in dark mode; `OkhslColor` / RGB-tuple inputs auto-adapt into the
-* snapshotted `globalConfig.lightLightness` / `globalConfig.darkLightness`
-* windows.
+* across every value-shorthand form.
 *
 * When the user requests `contrast` or relative `lightness`, a hidden
 * `STANDALONE_SEED` def is synthesized at `mode: 'static'`. That keeps
@@ -1925,11 +2010,11 @@ function buildStandaloneValueDefs(main, options) {
 		primary
 	};
 }
-function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData) {
+function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, baseToken, exportData) {
 	let cached;
 	const resolveOnce = () => {
 		if (cached) return cached;
-		cached = resolveAllColors(seedHue, seedSaturation, defs, effectiveScaling, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
+		cached = resolveAllColors(seedHue, seedSaturation, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
 		return cached;
 	};
 	const resolveStates = (options) => {
@@ -1958,17 +2043,43 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 	};
 }
 /**
+* When a value/`from` color links to a base that was created via the
+* structured form (with explicit `hue`/`saturation`/`lightness`), resolve
+* that base with `lightLightness: false` for the linking math so the
+* contrast/lightness anchor matches the input lightness — not the
+* windowed output. The original base token's `.resolve()` is unaffected.
+*/
+function toLinkingBase(base) {
+	if (!base) return void 0;
+	const exp = base.export();
+	if (exp.form !== "structured") return base;
+	const linkingConfig = {
+		...exp.config ?? {},
+		lightLightness: false
+	};
+	return colorFromExport({
+		...exp,
+		config: linkingConfig
+	});
+}
+/**
 * Resolve `base` (which may be a token reference or a raw color value)
 * into a `GlazeColorToken`. Raw values are auto-wrapped via
-* `glaze.color(value)` so they pick up the same auto-invert defaults as
-* an explicit wrap. Returns `undefined` when no base is provided.
+* `createColorTokenFromValue` so they pick up the same auto-invert
+* defaults as an explicit wrap. Returns `undefined` when no base is provided.
 */
 function resolveBaseToken(base) {
 	if (base === void 0) return void 0;
 	if (isGlazeColorToken(base)) return base;
 	return createColorTokenFromValue(base, void 0, void 0);
 }
-function createColorToken(input, scaling) {
+/**
+* Discriminate a `GlazeColorToken` from a raw `GlazeColorValue`.
+*/
+function isGlazeColorToken(candidate) {
+	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "resolve" in candidate && typeof candidate.resolve === "function";
+}
+function createColorToken(input, configOverride) {
 	validateStructuredInput(input);
 	const userName = input.name;
 	if (userName !== void 0) validateStandaloneName(userName);
@@ -1989,27 +2100,28 @@ function createColorToken(input, scaling) {
 		saturation: 1,
 		mode: "static"
 	};
-	const effectiveScaling = scaling ?? defaultStandaloneScaling(false);
+	const effectiveConfigOverride = buildStructuredConfigOverride(configOverride);
+	const effectiveConfig = resolvedConfigFromOverride(effectiveConfigOverride);
 	const exportData = () => ({
 		form: "structured",
 		input: buildStructuredInputExport(input),
-		scaling: effectiveScaling
+		config: effectiveConfigOverride
 	});
-	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveScaling, baseToken, exportData);
+	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveConfig, baseToken, exportData);
 }
-function createColorTokenFromValue(value, options, scaling) {
-	const inputIsString = typeof value === "string";
+function createColorTokenFromValue(value, options, configOverride) {
 	const main = extractOkhslFromValue(value);
-	const baseToken = resolveBaseToken(options?.base);
+	const linkingBase = toLinkingBase(resolveBaseToken(options?.base));
 	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options);
-	const effectiveScaling = scaling ?? defaultStandaloneScaling(inputIsString);
+	const effectiveConfigOverride = buildValueFormConfigOverride(configOverride);
+	const effectiveConfig = resolvedConfigFromOverride(effectiveConfigOverride);
 	const exportData = () => ({
 		form: "value",
 		input: value,
 		...options !== void 0 ? { overrides: buildOverridesExport(options) } : {},
-		scaling: effectiveScaling
+		config: effectiveConfigOverride
 	});
-	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData);
+	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, linkingBase, exportData);
 }
 /**
 * Build a JSON-safe snapshot of `GlazeColorOverrides`. `base` is
@@ -2045,8 +2157,6 @@ function buildStructuredInputExport(input) {
 }
 /**
 * Discriminate a `GlazeColorTokenExport` from a raw `GlazeColorValue`.
-* `GlazeColorTokenExport` always has a `form` field set to either
-* `'value'` or `'structured'`; raw values never do.
 */
 function isExportedToken(candidate) {
 	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "form" in candidate && (candidate.form === "value" || candidate.form === "structured");
@@ -2081,6 +2191,10 @@ 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.
 */
 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}.`);
@@ -2088,9 +2202,9 @@ function colorFromExport(data) {
 	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.scaling);
+		return createColorTokenFromValue(value, data.overrides ? rehydrateOverrides(data.overrides) : void 0, data.config);
 	}
-	return createColorToken(rehydrateStructuredInput(data.input), data.scaling);
+	return createColorToken(rehydrateStructuredInput(data.input), data.config);
 }
 
 //#endregion
@@ -2219,21 +2333,32 @@ function createPalette(themes, paletteOptions) {
 /**
 * Theme factory.
 *
-* Wraps a hue/saturation seed and a mutable `ColorMap`, and exposes
-* `tokens()` / `tasty()` / `json()` / `css()` / `resolve()` / `export()`
-* / `extend()`. Caches the last resolve result so successive exports
-* with the same defs and config don't re-run the four-pass resolver.
+* Wraps a hue/saturation seed, a mutable `ColorMap`, and an optional
+* per-theme `GlazeConfigOverride`. Exposes `tokens()` / `tasty()` /
+* `json()` / `css()` / `resolve()` / `export()` / `extend()`.
+*
+* The per-theme config override is **merged over the live global config at
+* resolve time** so the theme still reacts to later `configure()` calls
+* for fields it didn't override. The merged config is memoized by
+* `configVersion` to avoid rebuilding it on every export call.
 */
-function createTheme(hue, saturation, initialColors) {
+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 map = resolveAllColors(hue, saturation, colorDefs);
+		const effectiveConfig = mergeConfig(getConfig(), configOverride);
+		const map = resolveAllColors(hue, saturation, colorDefs, effectiveConfig);
 		cache = {
 			map,
-			version
+			version,
+			effectiveConfig
 		};
 		return map;
 	}
@@ -2275,11 +2400,13 @@ function createTheme(hue, saturation, initialColors) {
 			invalidate();
 		},
 		export() {
-			return {
+			const out = {
 				hue,
 				saturation,
 				colors: { ...colorDefs }
 			};
+			if (configOverride !== void 0) out.config = configOverride;
+			return out;
 		},
 		extend(options) {
 			const newHue = options.hue ?? hue;
@@ -2289,7 +2416,10 @@ function createTheme(hue, saturation, initialColors) {
 			return createTheme(newHue, newSat, options.colors ? {
 				...inheritedColors,
 				...options.colors
-			} : { ...inheritedColors });
+			} : { ...inheritedColors }, configOverride || options.config ? {
+				...configOverride ?? {},
+				...options.config ?? {}
+			} : void 0);
 		},
 		resolve() {
 			return new Map(resolveCached());
@@ -2299,7 +2429,7 @@ function createTheme(hue, saturation, initialColors) {
 			return buildFlatTokenMap(resolveCached(), "", modes, options?.format);
 		},
 		tasty(options) {
-			const cfg = getConfig();
+			const cfg = getEffectiveConfig();
 			const states = {
 				dark: options?.states?.dark ?? cfg.states.dark,
 				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
@@ -2334,16 +2464,24 @@ function createTheme(hue, saturation, initialColors) {
 /**
 * Create a single-hue glaze theme.
 *
+* An optional `config` override can be supplied to customize the resolve
+* behavior for this theme (lightness windows, dark curve, etc.). The
+* override is **merged over the live global config at resolve time** —
+* the theme still reacts to later `configure()` calls for fields it
+* didn't override.
+*
 * @example
 * ```ts
-* const primary = glaze({ hue: 280, saturation: 80 });
-* // or shorthand:
 * const primary = glaze(280, 80);
+* // or shorthand:
+* const primary = glaze({ hue: 280, saturation: 80 });
+* // with config override:
+* const raw = glaze(280, 80, { lightLightness: false });
 * ```
 */
-function glaze(hueOrOptions, saturation) {
-	if (typeof hueOrOptions === "number") return createTheme(hueOrOptions, saturation ?? 100);
-	return createTheme(hueOrOptions.hue, hueOrOptions.saturation);
+function glaze(hueOrOptions, saturation, config) {
+	if (typeof hueOrOptions === "number") return createTheme(hueOrOptions, saturation ?? 100, void 0, config);
+	return createTheme(hueOrOptions.hue, hueOrOptions.saturation, void 0, config);
 }
 /** Configure global glaze settings. */
 glaze.configure = function configure$1(config) {
@@ -2355,63 +2493,72 @@ glaze.palette = function palette(themes, options) {
 };
 /** Create a theme from a serialized export. */
 glaze.from = function from(data) {
-	return createTheme(data.hue, data.saturation, data.colors);
+	return createTheme(data.hue, data.saturation, data.colors, data.config);
 };
 /**
 * Create a standalone single-color token.
 *
-* Two overloads:
-* - `glaze.color(input, scaling?)` — structured form:
-*   `{ hue, saturation, lightness, ... }` plus an optional per-call
-*   lightness-window override.
-* - `glaze.color(value, overrides?, scaling?)` — value-shorthand: a hex
-*   string (3/6/8 digits), one of the CSS color functions Glaze itself
-*   emits (`rgb()`, `hsl()`, `okhsl()`, `oklch()`), an `OkhslColor`
-*   object `{ h, s, l }` (0–1 ranges), or an `[r, g, b]` (0–255) tuple.
+* **arg1 — the color** (four accepted shapes, discriminated by structure):
 *
-* Defaults: every input form defaults to `mode: 'auto'` so colors
-* automatically adapt between light and dark like an ordinary theme
-* color. The scaling snapshot taken at create time differs by input
-* form:
-* - String value-shorthand: `{ lightLightness: false, darkLightness:
-*   [globalConfig.darkLightness[0], 100] }`. Light preserves the input
-*   exactly; dark Möbius-inverts up to 100, so `glaze.color('#000')`
-*   renders as `#fff` in dark mode (and `glaze.color('#fff')` falls to
-*   the dark `lo` floor).
-* - `OkhslColor` object / RGB-tuple / structured value-shorthand:
-*   `{ lightLightness: globalConfig.lightLightness, darkLightness:
-*   globalConfig.darkLightness }` — both windows come straight from
-*   `globalConfig`, so the resulting token behaves like a theme color.
+* | Shape | Example | Notes |
+* |---|---|---|
+* | Bare string | `'#26fcb2'`, `'rgb(38 252 178)'` | Hex or CSS color function |
+* | Value object | `{ h: 152, s: 0.95, l: 0.74 }` | OKHSL, `{r,g,b}`, `{l,c,h}` |
+* | `{ from, ...overrides }` | `{ from: '#fff', base: bg, contrast: 'AA' }` | Value + color overrides |
+* | Structured | `{ hue: 152, saturation: 95, lightness: 74 }` | Full theme-style token |
 *
-* Pass `{ mode: 'fixed' }` to opt back into the legacy linear, non-
-* inverting mapping, or `{ mode: 'static' }` to pin the same lightness
-* across every variant.
+* **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 lightness window
+* to disable clamping entirely.
 *
-* Relative `lightness: '+N'` and `contrast: <ratio>` are anchored to
-* the literal seed (the value passed in) by default, pinned at
-* `mode: 'static'` across all four variants. Pass `overrides.base` (a
-* `GlazeColorToken`) to anchor `contrast` and relative `lightness`
-* against another color's resolved variant per scheme instead. Relative
-* `hue: '+N'` always anchors to the seed.
+* ```ts
+* // Bare string — no overrides
+* glaze.color('#26fcb2')
 *
-* Alpha components in `rgba()` / `hsla()` / slash-alpha syntax and
-* 8-digit hex are parsed but dropped with a `console.warn`.
-*/
-glaze.color = function color(input, arg2, arg3) {
-	if (isStructuredColorInput(input)) return createColorToken(input, arg2);
-	return createColorTokenFromValue(input, arg2, arg3);
+* // From form — value + color overrides
+* glaze.color({ from: '#fff', base: bg, contrast: 'AA' })
+*
+* // Structured form — full theme-style token
+* glaze.color({ hue: 152, saturation: 95, lightness: 74 })
+*
+* // Config override on any form
+* glaze.color('#26fcb2', { darkLightness: false, autoFlip: false })
+* glaze.color({ from: '#fff', base: bg }, { darkCurve: 0.3 })
+* ```
+*
+* Defaults: every form defaults to `mode: 'auto'`. Value-shorthand forms
+* (bare strings and value objects) preserve light lightness exactly
+* (`lightLightness: false` internally). Structured form snapshots both
+* lightness windows from `globalConfig` at create time.
+*
+* Relative `lightness: '+N'` and `contrast` anchor to the literal seed by
+* default; when `base` is set they anchor to the base's resolved variant
+* per scheme. Relative `hue: '+N'` always anchors to the seed, not the base.
+*/
+glaze.color = function color(input, config) {
+	if (typeof input === "string") return createColorTokenFromValue(input, void 0, config);
+	const obj = input;
+	if ("from" in obj) {
+		const { from, ...overrides } = input;
+		return createColorTokenFromValue(from, overrides, config);
+	}
+	if ("hue" in obj) return createColorToken(input, config);
+	return createColorTokenFromValue(input, void 0, config);
 };
 /**
 * Compute a shadow color from a bg/fg pair and intensity.
 *
 * Both `bg` and `fg` accept any `GlazeColorValue` form: hex (`#rgb` /
 * `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()` / `oklch()`
-* strings, `OkhslColor` objects, or `[r, g, b]` (0–255) tuples.
+* strings, or `{ r, g, b }` / `{ h, s, l }` / `{ l, c, h }` objects.
 */
 glaze.shadow = function shadow(input) {
 	const bg = extractOkhslFromValue(input.bg);
 	const fg = input.fg ? extractOkhslFromValue(input.fg) : void 0;
-	const tuning = resolveShadowTuning(input.tuning);
+	const cfg = getConfig();
+	const tuning = resolveShadowTuning(input.tuning, cfg.shadowTuning);
 	return computeShadow({
 		...bg,
 		alpha: 1
@@ -2451,12 +2598,12 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 *
 * The snapshot is a plain JSON-safe object containing the original
 * input value, overrides (with any `base` token recursively serialized),
-* and the captured scaling. The reconstructed token is identical in
-* behavior to the original at the time of export.
+* and the effective config snapshot. The reconstructed token is identical
+* in behavior to the original at the time of export.
 *
 * @example
 * ```ts
-* const text = glaze.color('#1a1a1a', { contrast: 'AA' });
+* const text = glaze.color({ from: '#1a1a1a', contrast: 'AA' });
 * const data = text.export();           // JSON-safe
 * localStorage.setItem('text', JSON.stringify(data));
 * // ...later...