@tenphi/glaze 0.9.3 → 0.10.1

package/dist/index.cjs

@@ -346,6 +346,11 @@ function gamutClampedLuminance(linearRgb) {
 const linearSrgbToOklab = (rgb) => {
 	return transform(cbrt3(transform(rgb, linear_sRGB_to_LMS_M)), LMS_to_OKLab_M);
 };
+/**
+* Convert OKLab to OKHSL.
+* Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
+* Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
+*/
 const oklabToOkhsl = (lab) => {
 	const L = lab[0];
 	const a = lab[1];
@@ -356,6 +361,12 @@ const oklabToOkhsl = (lab) => {
 		0,
 		toe(L)
 	];
+	const L_EXTREME_EPSILON = 1e-6;
+	if (L >= 1 - L_EXTREME_EPSILON || L <= L_EXTREME_EPSILON) return [
+		0,
+		0,
+		toe(L)
+	];
 	const a_ = a / C;
 	const b_ = b / C;
 	let h = Math.atan2(b, a) * (180 / Math.PI);
@@ -393,32 +404,108 @@ function srgbToOkhsl(rgb) {
 	]));
 }
 /**
+* Convert CSS HSL (sRGB-based) to gamma-encoded sRGB [r, g, b] in 0–1 range.
+* h: 0–360, s: 0–1, l: 0–1.
+*
+* Note: CSS HSL is not the same as OKHSL — it's HSL in the sRGB color space.
+* Use this when parsing `hsl(...)` strings before passing to `srgbToOkhsl`.
+*/
+function hslToSrgb(h, s, l) {
+	const hh = (h % 360 + 360) % 360 / 360;
+	const ss = clampVal(s, 0, 1);
+	const ll = clampVal(l, 0, 1);
+	if (ss === 0) return [
+		ll,
+		ll,
+		ll
+	];
+	const q = ll < .5 ? ll * (1 + ss) : ll + ss - ll * ss;
+	const p = 2 * ll - q;
+	const hueToChannel = (t) => {
+		let tt = t;
+		if (tt < 0) tt += 1;
+		if (tt > 1) tt -= 1;
+		if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+		if (tt < 1 / 2) return q;
+		if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+		return p;
+	};
+	return [
+		hueToChannel(hh + 1 / 3),
+		hueToChannel(hh),
+		hueToChannel(hh - 1 / 3)
+	];
+}
+/**
 * Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
 * Returns null if the string is not a valid hex color.
+*
+* For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
+* use {@link parseHexAlpha}.
 */
 function parseHex(hex) {
+	const result = parseHexAlpha(hex);
+	if (!result || result.alpha !== void 0) return null;
+	return result.rgb;
+}
+/**
+* Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
+* sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
+* Returns null if the string is not a valid hex color.
+*/
+function parseHexAlpha(hex) {
 	const h = hex.startsWith("#") ? hex.slice(1) : hex;
 	if (h.length === 3) {
 		const r = parseInt(h[0] + h[0], 16);
 		const g = parseInt(h[1] + h[1], 16);
 		const b = parseInt(h[2] + h[2], 16);
 		if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
-		return [
+		return { rgb: [
 			r / 255,
 			g / 255,
 			b / 255
-		];
+		] };
+	}
+	if (h.length === 4) {
+		const r = parseInt(h[0] + h[0], 16);
+		const g = parseInt(h[1] + h[1], 16);
+		const b = parseInt(h[2] + h[2], 16);
+		const a = parseInt(h[3] + h[3], 16);
+		if (isNaN(r) || isNaN(g) || isNaN(b) || isNaN(a)) return null;
+		return {
+			rgb: [
+				r / 255,
+				g / 255,
+				b / 255
+			],
+			alpha: a / 255
+		};
 	}
 	if (h.length === 6) {
 		const r = parseInt(h.slice(0, 2), 16);
 		const g = parseInt(h.slice(2, 4), 16);
 		const b = parseInt(h.slice(4, 6), 16);
 		if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
-		return [
+		return { rgb: [
 			r / 255,
 			g / 255,
 			b / 255
-		];
+		] };
+	}
+	if (h.length === 8) {
+		const r = parseInt(h.slice(0, 2), 16);
+		const g = parseInt(h.slice(2, 4), 16);
+		const b = parseInt(h.slice(4, 6), 16);
+		const a = parseInt(h.slice(6, 8), 16);
+		if (isNaN(r) || isNaN(g) || isNaN(b) || isNaN(a)) return null;
+		return {
+			rgb: [
+				r / 255,
+				g / 255,
+				b / 255
+			],
+			alpha: a / 255
+		};
 	}
 	return null;
 }
@@ -810,6 +897,45 @@ function findValueForMixContrast(options) {
 * Generates robust light, dark, and high-contrast colors from a hue/saturation
 * seed, preserving contrast for UI pairs via explicit dependencies.
 */
+/** Internal name of the user-facing standalone color in the synthesized def map. */
+const STANDALONE_VALUE = "value";
+/** Internal name of the hidden static-anchor seed used for relative lightness / contrast. */
+const STANDALONE_SEED = "seed";
+/** Internal name of an externally-resolved `GlazeColorToken` injected as a base reference. */
+const STANDALONE_BASE = "externalBase";
+/**
+* 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 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 use `globalConfig.darkLightness` verbatim.
+*/
+function defaultStandaloneScaling(extendDark) {
+	const [lo, hi] = globalConfig.darkLightness;
+	return {
+		lightLightness: false,
+		darkLightness: extendDark ? [lo, 100] : [lo, hi]
+	};
+}
+/** Reserved internal names that user-supplied `name` must not collide with. */
+const RESERVED_STANDALONE_NAMES = new Set([
+	STANDALONE_VALUE,
+	STANDALONE_SEED,
+	STANDALONE_BASE
+]);
+/**
+* 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)`).
+*/
+function isGlazeColorToken(candidate) {
+	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "resolve" in candidate && typeof candidate.resolve === "function";
+}
 let globalConfig = {
 	lightLightness: [10, 100],
 	darkLightness: [15, 95],
@@ -830,6 +956,41 @@ function pairNormal(p) {
 function pairHC(p) {
 	return Array.isArray(p) ? p[1] : p;
 }
+/**
+* Dedupe contrast warnings within a single process. The cache survives
+* the lifetime of a token because tokens memoize their resolution; the
+* limit is a soft cap to keep noise bounded across long-lived sessions
+* (e.g. dev servers with HMR re-resolving themes repeatedly).
+*/
+const CONTRAST_WARN_CACHE_LIMIT = 256;
+const contrastWarnCache = /* @__PURE__ */ new Set();
+function schemeLabel(isDark, isHighContrast) {
+	if (isDark && isHighContrast) return "darkContrast";
+	if (isDark) return "dark";
+	if (isHighContrast) return "lightContrast";
+	return "light";
+}
+function formatContrastTarget(input, ratio) {
+	return typeof input === "string" ? `"${input}" (${ratio.toFixed(2)})` : ratio.toFixed(2);
+}
+/**
+* Slack factor below the requested target before we emit a warning.
+* The contrast solver already overshoots by `OVERSHOOT` (currently 1%)
+* to absorb rounding noise (`see findLightnessForContrast` in
+* `contrast-solver.ts`), so an `actual` ratio within ~2x that overshoot
+* is effectively a pass and not worth nagging the user about.
+*/
+const CONTRAST_WARN_SLACK = .98;
+function warnContrastUnmet(name, isDark, isHighContrast, target, actual) {
+	const targetRatio = resolveMinContrast(target);
+	if (actual >= targetRatio * CONTRAST_WARN_SLACK) return;
+	const scheme = schemeLabel(isDark, isHighContrast);
+	const key = `${name}|${scheme}|${targetRatio.toFixed(3)}|${actual.toFixed(2)}`;
+	if (contrastWarnCache.has(key)) return;
+	if (contrastWarnCache.size >= CONTRAST_WARN_CACHE_LIMIT) contrastWarnCache.clear();
+	contrastWarnCache.add(key);
+	console.warn(`glaze: color "${name}" cannot meet contrast ${formatContrastTarget(target, targetRatio)} in ${scheme} scheme (got ${actual.toFixed(2)}). Try widening the lightness window, lowering the contrast target, or picking a base color further from this color's lightness.`);
+}
 function isShadowDef(def) {
 	return def.type === "shadow";
 }
@@ -891,36 +1052,38 @@ function computeShadow(bg, fg, intensity, tuning) {
 		alpha
 	};
 }
-function validateColorDefs(defs) {
-	const names = new Set(Object.keys(defs));
+function validateColorDefs(defs, externalBases) {
+	const localNames = new Set(Object.keys(defs));
+	const allNames = new Set([...localNames, ...externalBases ? externalBases.keys() : []]);
 	for (const [name, def] of Object.entries(defs)) {
 		if (isShadowDef(def)) {
-			if (!names.has(def.bg)) throw new Error(`glaze: shadow "${name}" references non-existent bg "${def.bg}".`);
-			if (isShadowDef(defs[def.bg])) throw new Error(`glaze: shadow "${name}" bg "${def.bg}" references another shadow color.`);
+			if (!allNames.has(def.bg)) throw new Error(`glaze: shadow "${name}" references non-existent bg "${def.bg}".`);
+			if (localNames.has(def.bg) && isShadowDef(defs[def.bg])) throw new Error(`glaze: shadow "${name}" bg "${def.bg}" references another shadow color.`);
 			if (def.fg !== void 0) {
-				if (!names.has(def.fg)) throw new Error(`glaze: shadow "${name}" references non-existent fg "${def.fg}".`);
-				if (isShadowDef(defs[def.fg])) throw new Error(`glaze: shadow "${name}" fg "${def.fg}" references another shadow color.`);
+				if (!allNames.has(def.fg)) throw new Error(`glaze: shadow "${name}" references non-existent fg "${def.fg}".`);
+				if (localNames.has(def.fg) && isShadowDef(defs[def.fg])) throw new Error(`glaze: shadow "${name}" fg "${def.fg}" references another shadow color.`);
 			}
 			continue;
 		}
 		if (isMixDef(def)) {
-			if (!names.has(def.base)) throw new Error(`glaze: mix "${name}" references non-existent base "${def.base}".`);
-			if (!names.has(def.target)) throw new Error(`glaze: mix "${name}" references non-existent target "${def.target}".`);
-			if (isShadowDef(defs[def.base])) throw new Error(`glaze: mix "${name}" base "${def.base}" references a shadow color.`);
-			if (isShadowDef(defs[def.target])) throw new Error(`glaze: mix "${name}" target "${def.target}" references a shadow color.`);
+			if (!allNames.has(def.base)) throw new Error(`glaze: mix "${name}" references non-existent base "${def.base}".`);
+			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.`);
 			continue;
 		}
 		const regDef = def;
 		if (regDef.contrast !== void 0 && !regDef.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
 		if (regDef.lightness !== void 0 && !isAbsoluteLightness(regDef.lightness) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
-		if (regDef.base && !names.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
-		if (regDef.base && isShadowDef(defs[regDef.base])) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a shadow color.`);
+		if (regDef.base && !allNames.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
+		if (regDef.base && localNames.has(regDef.base) && isShadowDef(defs[regDef.base])) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a shadow color.`);
 		if (!isAbsoluteLightness(regDef.lightness) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
 		if (regDef.contrast !== void 0 && regDef.opacity !== void 0) console.warn(`glaze: color "${name}" has both "contrast" and "opacity". Opacity makes perceived lightness unpredictable.`);
 	}
 	const visited = /* @__PURE__ */ new Set();
 	const inStack = /* @__PURE__ */ new Set();
 	function dfs(name) {
+		if (!localNames.has(name)) return;
 		if (inStack.has(name)) throw new Error(`glaze: circular base reference detected involving "${name}".`);
 		if (visited.has(name)) return;
 		inStack.add(name);
@@ -938,7 +1101,7 @@ function validateColorDefs(defs) {
 		inStack.delete(name);
 		visited.add(name);
 	}
-	for (const name of names) dfs(name);
+	for (const name of localNames) dfs(name);
 }
 function topoSort(defs) {
 	const result = [];
@@ -947,6 +1110,7 @@ function topoSort(defs) {
 		if (visited.has(name)) return;
 		visited.add(name);
 		const def = defs[name];
+		if (def === void 0) return;
 		if (isShadowDef(def)) {
 			visit(def.bg);
 			if (def.fg) visit(def.fg);
@@ -962,32 +1126,43 @@ function topoSort(defs) {
 	for (const name of Object.keys(defs)) visit(name);
 	return result;
 }
-function lightnessWindow(isHighContrast, kind) {
+/**
+* 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`.
+*/
+function lightnessWindow(isHighContrast, kind, scaling) {
 	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;
+	}
 	return kind === "dark" ? globalConfig.darkLightness : globalConfig.lightLightness;
 }
-function mapLightnessLight(l, mode, isHighContrast) {
+function mapLightnessLight(l, mode, isHighContrast, scaling) {
 	if (mode === "static") return l;
-	const [lo, hi] = lightnessWindow(isHighContrast, "light");
+	const [lo, hi] = lightnessWindow(isHighContrast, "light", scaling);
 	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) {
+function mapLightnessDark(l, mode, isHighContrast, scaling) {
 	if (mode === "static") return l;
 	const beta = isHighContrast ? pairHC(globalConfig.darkCurve) : pairNormal(globalConfig.darkCurve);
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark");
+	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", scaling);
 	if (mode === "fixed") return l * (darkHi - darkLo) / 100 + darkLo;
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light");
+	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", scaling);
 	const t = (lightHi - (l * (lightHi - lightLo) / 100 + lightLo)) / (lightHi - lightLo);
 	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
 }
-function lightMappedToDark(lightL, isHighContrast) {
+function lightMappedToDark(lightL, isHighContrast, scaling) {
 	const beta = isHighContrast ? pairHC(globalConfig.darkCurve) : pairNormal(globalConfig.darkCurve);
-	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light");
-	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark");
+	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light", scaling);
+	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark", scaling);
 	const t = (lightHi - clamp(lightL, lightLo, lightHi)) / (lightHi - lightLo);
 	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
 }
@@ -995,9 +1170,9 @@ function mapSaturationDark(s, mode) {
 	if (mode === "static") return s;
 	return s * (1 - globalConfig.darkDesaturation);
 }
-function schemeLightnessRange(isDark, mode, isHighContrast) {
+function schemeLightnessRange(isDark, mode, isHighContrast, scaling) {
 	if (mode === "static") return [0, 1];
-	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light");
+	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light", scaling);
 	return [lo / 100, hi / 100];
 }
 function clamp(v, min, max) {
@@ -1057,26 +1232,28 @@ 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);
+			if (isDark && mode === "auto") preferredL = lightMappedToDark(clamp(getSchemeVariant(baseResolved, false, isHighContrast).l * 100 + delta, 0, 100), isHighContrast, ctx.scaling);
 			else preferredL = clamp(baseL + delta, 0, 100);
-		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode, isHighContrast);
-		else preferredL = mapLightnessLight(parsed.value, mode, isHighContrast);
+		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode, isHighContrast, ctx.scaling);
+		else preferredL = mapLightnessLight(parsed.value, mode, isHighContrast, ctx.scaling);
 	}
 	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 baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
-		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast);
+		const windowRange = schemeLightnessRange(isDark, mode, isHighContrast, ctx.scaling);
+		const result = findLightnessForContrast({
+			hue: effectiveHue,
+			saturation: effectiveSat,
+			preferredLightness: clamp(preferredL / 100, windowRange[0], windowRange[1]),
+			baseLinearRgb,
+			contrast: minCr,
+			lightnessRange: [0, 1]
+		});
+		if (!result.met) warnContrastUnmet(name, isDark, isHighContrast, minCr, result.contrast);
 		return {
-			l: findLightnessForContrast({
-				hue: effectiveHue,
-				saturation: effectiveSat,
-				preferredLightness: clamp(preferredL / 100, windowRange[0], windowRange[1]),
-				baseLinearRgb,
-				contrast: minCr,
-				lightnessRange: [0, 1]
-			}).lightness * 100,
+			l: result.lightness * 100,
 			satFactor
 		};
 	}
@@ -1112,13 +1289,13 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	let finalL;
 	let finalSat;
 	if (isDark && isRoot) {
-		finalL = mapLightnessDark(lightL, mode, isHighContrast);
+		finalL = mapLightnessDark(lightL, mode, isHighContrast, ctx.scaling);
 		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
 	} else if (isDark && !isRoot) {
 		finalL = lightL;
 		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
 	} else if (isRoot) {
-		finalL = mapLightnessLight(lightL, mode, isHighContrast);
+		finalL = mapLightnessLight(lightL, mode, isHighContrast, ctx.scaling);
 		finalSat = satFactor * ctx.saturation / 100;
 	} else {
 		finalL = lightL;
@@ -1216,15 +1393,17 @@ function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
 		alpha: 1
 	};
 }
-function resolveAllColors(hue, saturation, defs) {
-	validateColorDefs(defs);
+function resolveAllColors(hue, saturation, defs, scaling, externalBases) {
+	validateColorDefs(defs, externalBases);
 	const order = topoSort(defs);
 	const ctx = {
 		hue,
 		saturation,
 		defs,
-		resolved: /* @__PURE__ */ new Map()
+		resolved: /* @__PURE__ */ new Map(),
+		scaling
 	};
+	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
 	function defMode(def) {
 		if (isShadowDef(def) || isMixDef(def)) return void 0;
 		return def.mode ?? "auto";
@@ -1576,34 +1755,408 @@ function createPalette(themes, paletteOptions) {
 		}
 	};
 }
-function createColorToken(input) {
-	const defs = { __color__: {
-		lightness: input.lightness,
-		saturation: input.saturationFactor,
-		mode: input.mode
-	} };
+/**
+* Matches the CSS color functions Glaze itself emits (`rgb()`, `hsl()`,
+* `okhsl()`, `oklch()`) plus their legacy alpha aliases (`rgba()`, `hsla()`).
+*
+* Only bare numeric components are supported. Named colors (`red`),
+* relative-color syntax (`from <color> ...`), and angle units other
+* than bare degrees (`deg` is the only suffix tolerated by `parseFloat`)
+* are out of scope.
+*/
+const COLOR_FN_RE = /^(rgba?|hsla?|okhsl|oklch)\(\s*([^)]*)\s*\)$/i;
+function parseNumberOrPercent(raw, percentScale) {
+	if (raw.endsWith("%")) return parseFloat(raw) / 100 * percentScale;
+	return parseFloat(raw);
+}
+/**
+* Split the body of a CSS color function into its components and detect
+* whether an alpha channel was present.
+*
+* Handles both modern slash syntax (`R G B / A` or `R, G, B / A`) and
+* legacy comma syntax (`R, G, B, A`). The alpha value itself is discarded
+* by the caller — standalone Glaze colors have no opacity field.
+*/
+function splitColorBody(body) {
+	const slashIdx = body.indexOf("/");
+	if (slashIdx !== -1) return {
+		components: body.slice(0, slashIdx).trim().split(/[\s,]+/).filter(Boolean),
+		hadAlpha: body.slice(slashIdx + 1).trim().length > 0
+	};
+	const components = body.split(/[\s,]+/).filter(Boolean);
+	if (components.length === 4) {
+		components.pop();
+		return {
+			components,
+			hadAlpha: true
+		};
+	}
+	return {
+		components,
+		hadAlpha: false
+	};
+}
+function warnDroppedAlpha(input) {
+	console.warn(`glaze: alpha component dropped from "${input}" (standalone color has no opacity field).`);
+}
+function parseColorString(input) {
+	if (input.startsWith("#")) {
+		const parsed = parseHexAlpha(input);
+		if (!parsed) throw new Error(`glaze: invalid hex color "${input}".`);
+		if (parsed.alpha !== void 0) warnDroppedAlpha(input);
+		const [h, s, l] = srgbToOkhsl(parsed.rgb);
+		return {
+			h,
+			s,
+			l
+		};
+	}
+	const m = input.match(COLOR_FN_RE);
+	if (!m) throw new Error(`glaze: unsupported color string "${input}".`);
+	const fn = m[1].toLowerCase();
+	const { components, hadAlpha } = splitColorBody(m[2].trim());
+	if (hadAlpha) warnDroppedAlpha(input);
+	if (components.length !== 3) throw new Error(`glaze: expected 3 components in "${input}".`);
+	switch (fn) {
+		case "rgb":
+		case "rgba": {
+			const [h, s, l] = srgbToOkhsl([
+				parseNumberOrPercent(components[0], 255) / 255,
+				parseNumberOrPercent(components[1], 255) / 255,
+				parseNumberOrPercent(components[2], 255) / 255
+			]);
+			return {
+				h,
+				s,
+				l
+			};
+		}
+		case "hsl":
+		case "hsla": {
+			const [oh, os, ol] = srgbToOkhsl(hslToSrgb(parseFloat(components[0]), parseNumberOrPercent(components[1], 1), parseNumberOrPercent(components[2], 1)));
+			return {
+				h: oh,
+				s: os,
+				l: ol
+			};
+		}
+		case "okhsl": return {
+			h: parseFloat(components[0]),
+			s: parseNumberOrPercent(components[1], 1),
+			l: parseNumberOrPercent(components[2], 1)
+		};
+		case "oklch": {
+			const L = parseNumberOrPercent(components[0], 1);
+			const C = parseNumberOrPercent(components[1], .4);
+			const hRad = parseFloat(components[2]) * Math.PI / 180;
+			const [h, s, l] = oklabToOkhsl([
+				L,
+				C * Math.cos(hRad),
+				C * Math.sin(hRad)
+			]);
+			return {
+				h,
+				s,
+				l
+			};
+		}
+	}
+	throw new Error(`glaze: unsupported color function "${fn}".`);
+}
+/**
+* Validate a user-supplied `OkhslColor`. Catches the common 0-100 vs 0-1
+* confusion (the structured form uses 0-100, OKHSL objects use 0-1).
+*/
+function validateOkhslColor(value) {
+	const { h, s, l } = value;
+	if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(l)) throw new Error("glaze.color: OkhslColor h/s/l must be finite numbers.");
+	if (s > 1.5 || l > 1.5) throw new Error("glaze.color: OkhslColor s/l must be in 0–1 range. Did you mean the structured form { hue, saturation, 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 `opacity` override on `glaze.color()`.
+* Must be a finite number in `0..=1`.
+*/
+function validateStandaloneOpacity(value) {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`glaze.color: opacity must be a finite number in 0–1 (got ${value}).`);
+}
+/**
+* Validate a structured `GlazeColorInput`. Range-checks the `hue` /
+* `saturation` / `lightness` numerics (and any HC-pair second value)
+* before the resolver sees them so out-of-range or non-finite inputs
+* fail with a helpful, top-level error rather than producing a
+* NaN-laden token. `opacity` is checked here too so all input
+* validation lives in one place.
+*/
+function validateStructuredInput(input) {
+	if (!Number.isFinite(input.hue)) throw new Error(`glaze.color: structured hue must be a finite number (got ${input.hue}).`);
+	if (!Number.isFinite(input.saturation) || input.saturation < 0 || input.saturation > 100) throw new Error(`glaze.color: structured saturation must be a finite number in 0–100 (got ${input.saturation}).`);
+	const checkLightness = (value, label) => {
+		if (!Number.isFinite(value) || value < 0 || value > 100) throw new Error(`glaze.color: structured ${label} must be a finite number in 0–100 (got ${value}).`);
+	};
+	if (Array.isArray(input.lightness)) {
+		checkLightness(input.lightness[0], "lightness[normal]");
+		checkLightness(input.lightness[1], "lightness[hc]");
+	} else checkLightness(input.lightness, "lightness");
+	if (input.saturationFactor !== void 0) {
+		if (!Number.isFinite(input.saturationFactor) || input.saturationFactor < 0 || input.saturationFactor > 1) throw new Error(`glaze.color: structured saturationFactor must be a finite number in 0–1 (got ${input.saturationFactor}).`);
+	}
+	if (input.opacity !== void 0) validateStandaloneOpacity(input.opacity);
+}
+/**
+* Validate a user-supplied `name` override. Rejects empty / whitespace-only
+* strings and names colliding with `glaze`'s reserved internal sentinels.
+*/
+function validateStandaloneName(name) {
+	if (typeof name !== "string" || name.trim() === "") throw new Error("glaze.color: name must be a non-empty string. Omit `name` if you do not want to set a debug label.");
+	if (RESERVED_STANDALONE_NAMES.has(name)) {
+		const reserved = [...RESERVED_STANDALONE_NAMES].map((n) => `"${n}"`).join(", ");
+		throw new Error(`glaze.color: name "${name}" is reserved (used internally). Reserved names are: ${reserved}. Pick a different 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.
+*/
+function extractOkhslFromValue(value) {
+	if (typeof value === "string") return parseColorString(value);
+	if (Array.isArray(value)) {
+		const tuple = value;
+		validateRgbTuple(tuple);
+		const [r, g, b] = tuple;
+		const [h, s, l] = srgbToOkhsl([
+			r / 255,
+			g / 255,
+			b / 255
+		]);
+		return {
+			h,
+			s,
+			l
+		};
+	}
+	validateOkhslColor(value);
+	return value;
+}
+/**
+* Build the `ColorMap` for a value-shorthand `glaze.color()` call.
+*
+* The user-facing color (`STANDALONE_VALUE`) defaults to `mode: 'auto'`
+* for string inputs (Möbius-inverted dark variant — pairs with the
+* extended dark window so a totally-black input renders as totally-white
+* in dark mode) and `mode: 'fixed'` for `OkhslColor` / RGB-tuple inputs
+* (linear, no inversion).
+*
+* When the user requests `contrast` or relative `lightness`, a hidden
+* `STANDALONE_SEED` def is synthesized at `mode: 'static'`. That keeps
+* the seed pinned to the literal user-provided color across all four
+* variants, so the contrast solver always anchors against it.
+*/
+function buildStandaloneValueDefs(main, options, inputIsString) {
+	const seedHue = typeof options?.hue === "number" ? options.hue : main.h;
+	const seedSaturation = options?.saturation ?? main.s * 100;
+	const relativeHue = typeof options?.hue === "string" ? options.hue : void 0;
+	const lightnessOption = options?.lightness;
+	const hasExternalBase = options?.base !== void 0;
+	const needsSeedAnchor = !hasExternalBase && (options?.contrast !== void 0 || lightnessOption !== void 0 && !isAbsoluteLightness(lightnessOption));
+	if (options?.opacity !== void 0) validateStandaloneOpacity(options.opacity);
+	const userName = options?.name;
+	if (userName !== void 0) validateStandaloneName(userName);
+	const primary = userName ?? STANDALONE_VALUE;
+	const valueDef = {
+		hue: relativeHue,
+		saturation: options?.saturationFactor,
+		lightness: lightnessOption ?? main.l * 100,
+		contrast: options?.contrast,
+		mode: options?.mode ?? (inputIsString ? "auto" : "fixed"),
+		opacity: options?.opacity,
+		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
+	};
+	const defs = { [primary]: valueDef };
+	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
+		hue: main.h,
+		saturation: 1,
+		lightness: main.l * 100,
+		mode: "static"
+	};
+	return {
+		seedHue,
+		seedSaturation,
+		defs,
+		primary
+	};
+}
+function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, 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);
+		return cached;
+	};
+	const resolveStates = (options) => ({
+		dark: options?.states?.dark ?? globalConfig.states.dark,
+		highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
+	});
+	const tokenLike = (options) => {
+		return buildTokenMap(resolveOnce(), "", resolveStates(options), resolveModes(options?.modes), options?.format)[`#${primary}`];
+	};
 	return {
 		resolve() {
-			return resolveAllColors(input.hue, input.saturation, defs).get("__color__");
+			return resolveOnce().get(primary);
 		},
-		token(options) {
-			return buildTokenMap(resolveAllColors(input.hue, input.saturation, defs), "", {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
-			}, resolveModes(options?.modes), options?.format)["#__color__"];
+		token: tokenLike,
+		tasty: tokenLike,
+		json(options) {
+			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), options?.format)[primary];
 		},
-		tasty(options) {
-			return buildTokenMap(resolveAllColors(input.hue, input.saturation, defs), "", {
-				dark: options?.states?.dark ?? globalConfig.states.dark,
-				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
-			}, resolveModes(options?.modes), options?.format)["#__color__"];
+		css(options) {
+			return buildCssMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.suffix ?? "-color", options.format ?? "rgb");
 		},
-		json(options) {
-			return buildJsonMap(resolveAllColors(input.hue, input.saturation, defs), resolveModes(options?.modes), options?.format)["__color__"];
-		}
+		export: exportData
 	};
 }
 /**
+* 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.
+*/
+function resolveBaseToken(base) {
+	if (base === void 0) return void 0;
+	if (isGlazeColorToken(base)) return base;
+	return createColorTokenFromValue(base, void 0, void 0);
+}
+/**
+* Build a JSON-safe snapshot of `GlazeColorOverrides`. `base` is
+* recursively serialized when it was originally a token; raw values are
+* preserved as-is so `glaze.colorFrom(...)` round-trips them.
+*/
+function buildOverridesExport(options) {
+	const out = {};
+	if (options.hue !== void 0) out.hue = options.hue;
+	if (options.saturation !== void 0) out.saturation = options.saturation;
+	if (options.lightness !== void 0) out.lightness = options.lightness;
+	if (options.saturationFactor !== void 0) out.saturationFactor = options.saturationFactor;
+	if (options.mode !== void 0) out.mode = options.mode;
+	if (options.contrast !== void 0) out.contrast = options.contrast;
+	if (options.opacity !== void 0) out.opacity = options.opacity;
+	if (options.name !== void 0) out.name = options.name;
+	if (options.base !== void 0) out.base = isGlazeColorToken(options.base) ? options.base.export() : options.base;
+	return out;
+}
+function buildStructuredInputExport(input) {
+	const out = {
+		hue: input.hue,
+		saturation: input.saturation,
+		lightness: input.lightness
+	};
+	if (input.saturationFactor !== void 0) out.saturationFactor = input.saturationFactor;
+	if (input.mode !== void 0) out.mode = input.mode;
+	if (input.opacity !== void 0) out.opacity = input.opacity;
+	if (input.contrast !== void 0) out.contrast = input.contrast;
+	if (input.name !== void 0) out.name = input.name;
+	if (input.base !== void 0) out.base = isGlazeColorToken(input.base) ? input.base.export() : input.base;
+	return out;
+}
+function createColorToken(input, scaling) {
+	validateStructuredInput(input);
+	const userName = input.name;
+	if (userName !== void 0) validateStandaloneName(userName);
+	const primary = userName ?? STANDALONE_VALUE;
+	const baseToken = resolveBaseToken(input.base);
+	const hasExternalBase = baseToken !== void 0;
+	const needsSeedAnchor = !hasExternalBase && input.contrast !== void 0;
+	const defs = { [primary]: {
+		lightness: input.lightness,
+		saturation: input.saturationFactor,
+		mode: input.mode ?? "fixed",
+		contrast: input.contrast,
+		opacity: input.opacity,
+		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
+	} };
+	if (needsSeedAnchor) defs[STANDALONE_SEED] = {
+		lightness: pairNormal(input.lightness),
+		saturation: 1,
+		mode: "static"
+	};
+	const effectiveScaling = scaling ?? defaultStandaloneScaling(false);
+	const exportData = () => ({
+		form: "structured",
+		input: buildStructuredInputExport(input),
+		scaling: effectiveScaling
+	});
+	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveScaling, baseToken, exportData);
+}
+function createColorTokenFromValue(value, options, scaling) {
+	const inputIsString = typeof value === "string";
+	const main = extractOkhslFromValue(value);
+	const baseToken = resolveBaseToken(options?.base);
+	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options, inputIsString);
+	const effectiveScaling = scaling ?? defaultStandaloneScaling(inputIsString);
+	const exportData = () => ({
+		form: "value",
+		input: value,
+		...options !== void 0 ? { overrides: buildOverridesExport(options) } : {},
+		scaling: effectiveScaling
+	});
+	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveScaling, baseToken, exportData);
+}
+/**
+* Rehydrate a token from its `.export()` snapshot. Recursively rebuilds
+* any base dependency. Inverse of `GlazeColorToken.export()`.
+*/
+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}.`);
+	if (data.form !== "value" && data.form !== "structured") throw new Error(`glaze.colorFrom: invalid "form" field — expected "value" or "structured" (got ${JSON.stringify(data.form)}).`);
+	if (data.input === void 0) throw new Error(`glaze.colorFrom: missing "input" field — expected the original ${data.form === "value" ? "GlazeColorValue" : "GlazeColorInput"}.`);
+	if (data.form === "value") {
+		const value = data.input;
+		return createColorTokenFromValue(value, data.overrides ? rehydrateOverrides(data.overrides) : void 0, data.scaling);
+	}
+	return createColorToken(rehydrateStructuredInput(data.input), data.scaling);
+}
+function rehydrateOverrides(data) {
+	const out = {};
+	if (data.hue !== void 0) out.hue = data.hue;
+	if (data.saturation !== void 0) out.saturation = data.saturation;
+	if (data.lightness !== void 0) out.lightness = data.lightness;
+	if (data.saturationFactor !== void 0) out.saturationFactor = data.saturationFactor;
+	if (data.mode !== void 0) out.mode = data.mode;
+	if (data.contrast !== void 0) out.contrast = data.contrast;
+	if (data.opacity !== void 0) out.opacity = data.opacity;
+	if (data.name !== void 0) out.name = data.name;
+	if (data.base !== void 0) out.base = isExportedToken(data.base) ? colorFromExport(data.base) : data.base;
+	return out;
+}
+function rehydrateStructuredInput(data) {
+	const out = {
+		hue: data.hue,
+		saturation: data.saturation,
+		lightness: data.lightness
+	};
+	if (data.saturationFactor !== void 0) out.saturationFactor = data.saturationFactor;
+	if (data.mode !== void 0) out.mode = data.mode;
+	if (data.opacity !== void 0) out.opacity = data.opacity;
+	if (data.contrast !== void 0) out.contrast = data.contrast;
+	if (data.name !== void 0) out.name = data.name;
+	if (data.base !== void 0) out.base = isExportedToken(data.base) ? colorFromExport(data.base) : data.base;
+	return out;
+}
+/**
+* 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");
+}
+/**
 * Create a single-hue glaze theme.
 *
 * @example
@@ -1649,18 +2202,57 @@ glaze.palette = function palette(themes, options) {
 glaze.from = function from(data) {
 	return createTheme(data.hue, data.saturation, data.colors);
 };
+function isStructuredColorInput(input) {
+	return typeof input === "object" && input !== null && !Array.isArray(input) && "hue" in input && "lightness" in input;
+}
 /**
 * 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.
+*
+* Defaults vary by input form:
+* - String value-shorthand: `mode: 'auto'` with snapshotted scaling
+*   `{ 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 value-shorthand: `mode: 'fixed'`
+*   with `scaling: { lightLightness: false }` — light preserves the
+*   input; dark linearly maps into `globalConfig.darkLightness`.
+* - Structured form (`{ hue, saturation, lightness, ... }`):
+*   `mode: 'fixed'`; both windows come from `globalConfig`.
+*
+* 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.
+*
+* 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) {
-	return createColorToken(input);
+glaze.color = function color(input, arg2, arg3) {
+	if (isStructuredColorInput(input)) return createColorToken(input, arg2);
+	return createColorTokenFromValue(input, arg2, arg3);
 };
 /**
 * 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.
 */
 glaze.shadow = function shadow(input) {
-	const bg = parseOkhslInput(input.bg);
-	const fg = input.fg ? parseOkhslInput(input.fg) : void 0;
+	const bg = extractOkhslFromValue(input.bg);
+	const fg = input.fg ? extractOkhslFromValue(input.fg) : void 0;
 	const tuning = resolveShadowTuning(input.tuning);
 	return computeShadow({
 		...bg,
@@ -1676,19 +2268,6 @@ glaze.shadow = function shadow(input) {
 glaze.format = function format(variant, colorFormat) {
 	return formatVariant(variant, colorFormat);
 };
-function parseOkhslInput(input) {
-	if (typeof input === "string") {
-		const rgb = parseHex(input);
-		if (!rgb) throw new Error(`glaze: invalid hex color "${input}".`);
-		const [h, s, l] = srgbToOkhsl(rgb);
-		return {
-			h,
-			s,
-			l
-		};
-	}
-	return input;
-}
 /**
 * Create a theme from a hex color string.
 * Extracts hue and saturation from the color.
@@ -1712,6 +2291,26 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 	return createTheme(h, s * 100);
 };
 /**
+* Rehydrate a `glaze.color()` token from a `.export()` snapshot.
+*
+* The snapshot is a plain JSON-safe object containing the original
+* input value, overrides (with any `base` token recursively serialized),
+* and the captured scaling. 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 data = text.export();           // JSON-safe
+* localStorage.setItem('text', JSON.stringify(data));
+* // ...later...
+* const restored = glaze.colorFrom(JSON.parse(localStorage.getItem('text')!));
+* ```
+*/
+glaze.colorFrom = function colorFrom(data) {
+	return colorFromExport(data);
+};
+/**
 * Get the current global configuration (for testing/debugging).
 */
 glaze.getConfig = function getConfig() {
@@ -1747,10 +2346,13 @@ exports.formatOklch = formatOklch;
 exports.formatRgb = formatRgb;
 exports.gamutClampedLuminance = gamutClampedLuminance;
 exports.glaze = glaze;
+exports.hslToSrgb = hslToSrgb;
 exports.okhslToLinearSrgb = okhslToLinearSrgb;
 exports.okhslToOklab = okhslToOklab;
 exports.okhslToSrgb = okhslToSrgb;
+exports.oklabToOkhsl = oklabToOkhsl;
 exports.parseHex = parseHex;
+exports.parseHexAlpha = parseHexAlpha;
 exports.relativeLuminanceFromLinearRgb = relativeLuminanceFromLinearRgb;
 exports.resolveMinContrast = resolveMinContrast;
 exports.srgbToOkhsl = srgbToOkhsl;