@tenphi/glaze 0.11.1 → 0.12.0

package/dist/index.cjs

@@ -579,7 +579,8 @@ function defaultConfig() {
 		modes: {
 			dark: true,
 			highContrast: false
-		}
+		},
+		autoFlip: true
 	};
 }
 let globalConfig = defaultConfig();
@@ -618,7 +619,8 @@ 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() {
@@ -827,47 +829,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 +968,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
 	};
 }
 
@@ -1309,13 +1334,19 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode) : satFactor * ctx.saturation / 100;
 		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
 		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast, ctx.scaling);
+		const autoFlip = ctx.autoFlip ?? getConfig().autoFlip;
+		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: autoFlip
 		});
 		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, minCr, result.contrast);
 		return {
@@ -1431,12 +1462,14 @@ function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
 		else luminanceAt = (v) => {
 			return gamutClampedLuminance(okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v));
 		};
+		const autoFlip = ctx.autoFlip ?? getConfig().autoFlip;
 		t = findValueForMixContrast({
 			preferredValue: t,
 			baseLinearRgb: baseLinear,
 			targetLinearRgb: targetLinear,
 			contrast: minCr,
-			luminanceAtValue: luminanceAt
+			luminanceAtValue: luminanceAt,
+			flip: autoFlip
 		}).value;
 	}
 	if (blend === "transparent") return {
@@ -1497,15 +1530,17 @@ function seedField(order, ctx, field, source) {
 		});
 	}
 }
-function resolveAllColors(hue, saturation, defs, scaling, externalBases) {
+function resolveAllColors(hue, saturation, defs, scaling, externalBases, overrideAutoFlip) {
 	validateColorDefs(defs, externalBases);
 	const order = topoSort(defs);
+	const cfg = getConfig();
 	const ctx = {
 		hue,
 		saturation,
 		defs,
 		resolved: /* @__PURE__ */ new Map(),
-		scaling
+		scaling,
+		autoFlip: overrideAutoFlip ?? cfg.autoFlip
 	};
 	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
 	const lightMap = runPass(order, defs, ctx, false, false, "light");
@@ -1627,7 +1662,7 @@ 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.
 *
@@ -1650,29 +1685,24 @@ 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).
-*
-* 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) {
+* Create-time scaling for all value-shorthand `glaze.color()` inputs.
+* Light lightness is preserved (`lightLightness: false`); dark uses the
+* theme window from `globalConfig.darkLightness`, snapshotted at create
+* time so later `configure()` does not retroactively change tokens.
+*/
+function defaultValueShorthandScaling() {
+	return {
+		lightLightness: false,
+		darkLightness: getConfig().darkLightness
+	};
+}
+/**
+* Create-time scaling for structured `glaze.color({ hue, saturation,
+* lightness, ... })`. Both windows come from `globalConfig` so the
+* token behaves like an ordinary theme color on light and dark sides.
+*/
+function defaultStructuredScaling() {
 	const cfg = getConfig();
-	if (isString) {
-		const [darkLo] = cfg.darkLightness;
-		return {
-			lightLightness: false,
-			darkLightness: [darkLo, 100]
-		};
-	}
 	return {
 		lightLightness: cfg.lightLightness,
 		darkLightness: cfg.darkLightness
@@ -1806,9 +1836,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 +1916,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 +1934,10 @@ function extractOkhslFromValue(value) {
 			l
 		};
 	}
+	if (isOklchColorObject(value)) {
+		validateOklchColor(value);
+		return oklchComponentsToOkhsl(value.l, value.c, value.h);
+	}
 	validateOkhslColor(value);
 	return value;
 }
@@ -1880,11 +1945,9 @@ 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, using the snapshotted
+* `globalConfig.darkLightness` window (light lightness preserved via
+* `lightLightness: false`).
 *
 * When the user requests `contrast` or relative `lightness`, a hidden
 * `STANDALONE_SEED` def is synthesized at `mode: 'static'`. That keeps
@@ -1925,11 +1988,11 @@ function buildStandaloneValueDefs(main, options) {
 		primary
 	};
 }
-function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData) {
+function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData, autoFlip) {
 	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, effectiveScaling, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0, autoFlip);
 		return cached;
 	};
 	const resolveStates = (options) => {
@@ -1968,7 +2031,7 @@ function resolveBaseToken(base) {
 	if (isGlazeColorToken(base)) return base;
 	return createColorTokenFromValue(base, void 0, void 0);
 }
-function createColorToken(input, scaling) {
+function createColorToken(input, scaling, overrideAutoFlip) {
 	validateStructuredInput(input);
 	const userName = input.name;
 	if (userName !== void 0) validateStandaloneName(userName);
@@ -1989,27 +2052,30 @@ function createColorToken(input, scaling) {
 		saturation: 1,
 		mode: "static"
 	};
-	const effectiveScaling = scaling ?? defaultStandaloneScaling(false);
+	const effectiveScaling = scaling ?? defaultStructuredScaling();
+	const autoFlip = overrideAutoFlip ?? getConfig().autoFlip;
 	const exportData = () => ({
 		form: "structured",
 		input: buildStructuredInputExport(input),
-		scaling: effectiveScaling
+		scaling: effectiveScaling,
+		autoFlip
 	});
-	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveScaling, baseToken, exportData);
+	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveScaling, baseToken, exportData, autoFlip);
 }
-function createColorTokenFromValue(value, options, scaling) {
-	const inputIsString = typeof value === "string";
+function createColorTokenFromValue(value, options, scaling, overrideAutoFlip) {
 	const main = extractOkhslFromValue(value);
 	const baseToken = resolveBaseToken(options?.base);
 	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options);
-	const effectiveScaling = scaling ?? defaultStandaloneScaling(inputIsString);
+	const effectiveScaling = scaling ?? defaultValueShorthandScaling();
+	const autoFlip = overrideAutoFlip ?? getConfig().autoFlip;
 	const exportData = () => ({
 		form: "value",
 		input: value,
 		...options !== void 0 ? { overrides: buildOverridesExport(options) } : {},
-		scaling: effectiveScaling
+		scaling: effectiveScaling,
+		autoFlip
 	});
-	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData);
+	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData, autoFlip);
 }
 /**
 * Build a JSON-safe snapshot of `GlazeColorOverrides`. `base` is
@@ -2088,9 +2154,15 @@ 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);
+		const overrides = data.overrides ? rehydrateOverrides(data.overrides) : void 0;
+		const cfg = getConfig();
+		const effectiveAutoFlip = data.autoFlip ?? cfg.autoFlip;
+		return createColorTokenFromValue(value, overrides, data.scaling, effectiveAutoFlip);
 	}
-	return createColorToken(rehydrateStructuredInput(data.input), data.scaling);
+	const input = rehydrateStructuredInput(data.input);
+	const cfg = getConfig();
+	const effectiveAutoFlip = data.autoFlip ?? cfg.autoFlip;
+	return createColorToken(input, data.scaling, effectiveAutoFlip);
 }
 
 //#endregion
@@ -2366,22 +2438,16 @@ glaze.from = function from(data) {
 *   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.
+*   emits (`rgb()`, `hsl()`, `okhsl()`, `oklch()`), or literal objects
+*   `{ r, g, b }` (0–255), `{ h, s, l }` (OKHSL 0–1), `{ l, c, h }`
+*   (OKLCh, matching `oklch()` strings).
 *
-* 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.
+* Defaults: every input form defaults to `mode: 'auto'`. Value-shorthand
+* (strings and literal objects) snapshots `{ lightLightness: false,
+* darkLightness: globalConfig.darkLightness }` — light preserves the
+* input; dark uses the theme window. Structured `{ hue, saturation,
+* lightness, ... }` snapshots both `globalConfig` windows like a theme
+* color.
 *
 * Pass `{ mode: 'fixed' }` to opt back into the legacy linear, non-
 * inverting mapping, or `{ mode: 'static' }` to pin the same lightness
@@ -2406,7 +2472,7 @@ glaze.color = function color(input, arg2, arg3) {
 *
 * 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);