@tenphi/glaze 0.4.0 → 0.5.1

package/dist/index.d.mts

@@ -62,7 +62,15 @@ interface GlazeOutputModes {
   /** Include high-contrast variants (both light-HC and dark-HC). Default: false. */
   highContrast?: boolean;
 }
-interface ColorDef {
+/** Hex color string for DX hints. Runtime validation in `parseHex()`. */
+type HexColor = `#${string}`;
+/** Direct OKHSL color input. */
+interface OkhslColor {
+  h: number;
+  s: number;
+  l: number;
+}
+interface RegularColorDef {
   /**
    * Lightness value (0–100).
    * - Number: absolute lightness.
@@ -83,7 +91,60 @@ interface ColorDef {
   contrast?: HCPair<MinContrast>;
   /** Adaptation mode. Default: 'auto'. */
   mode?: AdaptationMode;
+  /**
+   * Fixed opacity (0–1).
+   * Output includes alpha in the CSS value.
+   * Does not affect contrast resolution — a semi-transparent color
+   * has no fixed perceived lightness, so `contrast` and `opacity`
+   * should not be combined (a console.warn is emitted).
+   */
+  opacity?: number;
 }
+/** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
+interface ShadowTuning {
+  /** Fraction of fg saturation kept in pigment (0-1). Default: 0.18. */
+  saturationFactor?: number;
+  /** Upper clamp on pigment saturation (0-1). Default: 0.25. */
+  maxSaturation?: number;
+  /** Multiplier for bg lightness → pigment lightness. Default: 0.25. */
+  lightnessFactor?: number;
+  /** [min, max] clamp for pigment lightness (0-1). Default: [0.05, 0.20]. */
+  lightnessBounds?: [number, number];
+  /**
+   * Target minimum gap between pigment lightness and bg lightness (0-1).
+   * Default: 0.05.
+   */
+  minGapTarget?: number;
+  /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
+  alphaMax?: number;
+  /**
+   * Blend weight (0-1) pulling pigment hue toward bg hue.
+   * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
+   */
+  bgHueBlend?: number;
+}
+interface ShadowColorDef {
+  type: 'shadow';
+  /**
+   * Background color name — the surface the shadow sits on.
+   * Must reference a non-shadow color in the same theme.
+   */
+  bg: string;
+  /**
+   * Foreground color name for tinting and intensity modulation.
+   * Must reference a non-shadow color in the same theme.
+   * Omit for achromatic shadow at full user-specified intensity.
+   */
+  fg?: string;
+  /**
+   * Shadow intensity, 0-100.
+   * Supports [normal, highContrast] pair.
+   */
+  intensity: HCPair<number>;
+  /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
+  tuning?: ShadowTuning;
+}
+type ColorDef = RegularColorDef | ShadowColorDef;
 type ColorMap = Record<string, ColorDef>;
 /** Resolved color for a single scheme variant. */
 interface ResolvedColorVariant {
@@ -93,6 +154,8 @@ interface ResolvedColorVariant {
   s: number;
   /** OKHSL lightness (0–1). */
   l: number;
+  /** Opacity (0–1). Default: 1. */
+  alpha: number;
 }
 /** Fully resolved color across all scheme variants. */
 interface ResolvedColor {
@@ -101,7 +164,8 @@ interface ResolvedColor {
   dark: ResolvedColorVariant;
   lightContrast: ResolvedColorVariant;
   darkContrast: ResolvedColorVariant;
-  mode: AdaptationMode;
+  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
+  mode?: AdaptationMode;
 }
 interface GlazeConfig {
   /** Dark scheme lightness window [lo, hi]. Default: [10, 90]. */
@@ -115,6 +179,8 @@ interface GlazeConfig {
   };
   /** Which scheme variants to include in exports. Default: both true. */
   modes?: GlazeOutputModes;
+  /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
+  shadowTuning?: ShadowTuning;
 }
 interface GlazeConfigResolved {
   darkLightness: [number, number];
@@ -124,6 +190,7 @@ interface GlazeConfigResolved {
     highContrast: string;
   };
   modes: Required<GlazeOutputModes>;
+  shadowTuning?: ShadowTuning;
 }
 /** Serialized theme configuration (no resolved values). */
 interface GlazeThemeExport {
@@ -131,6 +198,16 @@ interface GlazeThemeExport {
   saturation: number;
   colors: ColorMap;
 }
+/** Input for `glaze.shadow()` standalone factory. */
+interface GlazeShadowInput {
+  /** Background color — hex string or OKHSL { h, s (0-1), l (0-1) }. */
+  bg: HexColor | OkhslColor;
+  /** Foreground color for tinting + intensity modulation. */
+  fg?: HexColor | OkhslColor;
+  /** Intensity 0-100. */
+  intensity: number;
+  tuning?: ShadowTuning;
+}
 /** Input for `glaze.color()` standalone factory. */
 interface GlazeColorInput {
   hue: number;
@@ -298,6 +375,8 @@ declare namespace glaze {
   };
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeColorInput) => GlazeColorToken;
+  var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
+  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var getConfig: () => GlazeConfigResolved;
@@ -350,20 +429,20 @@ declare function parseHex(hex: string): [number, number, number] | null;
  */
 declare function formatOkhsl(h: number, s: number, l: number): string;
 /**
- * Format OKHSL values as a CSS `rgb(R, G, B)` string with fractional 0–255 values.
+ * Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
 declare function formatRgb(h: number, s: number, l: number): string;
 /**
- * Format OKHSL values as a CSS `hsl(H, S%, L%)` string.
+ * Format OKHSL values as a CSS `hsl(H S% L%)` string.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
 declare function formatHsl(h: number, s: number, l: number): string;
 /**
- * Format OKHSL values as a CSS `oklch(L% C H)` string.
+ * Format OKHSL values as a CSS `oklch(L C H)` string.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
 declare function formatOklch(h: number, s: number, l: number): string;
 //#endregion
-export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorToken, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type MinContrast, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorToken, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazeShadowInput, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type MinContrast, type OkhslColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -439,23 +439,26 @@ function parseHex(hex) {
 	}
 	return null;
 }
+function fmt$1(value, decimals) {
+	return parseFloat(value.toFixed(decimals)).toString();
+}
 /**
 * Format OKHSL values as a CSS `okhsl(H S% L%)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatOkhsl(h, s, l) {
-	return `okhsl(${h.toFixed(1)} ${s.toFixed(1)}% ${l.toFixed(1)}%)`;
+	return `okhsl(${fmt$1(h, 1)} ${fmt$1(s, 1)}% ${fmt$1(l, 1)}%)`;
 }
 /**
-* Format OKHSL values as a CSS `rgb(R, G, B)` string with fractional 0–255 values.
+* Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatRgb(h, s, l) {
 	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100);
-	return `rgb(${(r * 255).toFixed(3)}, ${(g * 255).toFixed(3)}, ${(b * 255).toFixed(3)})`;
+	return `rgb(${Math.round(r * 255)} ${Math.round(g * 255)} ${Math.round(b * 255)})`;
 }
 /**
-* Format OKHSL values as a CSS `hsl(H, S%, L%)` string.
+* Format OKHSL values as a CSS `hsl(H S% L%)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatHsl(h, s, l) {
@@ -472,10 +475,10 @@ function formatHsl(h, s, l) {
 		else if (max === g) hh = ((b - r) / delta + 2) * 60;
 		else hh = ((r - g) / delta + 4) * 60;
 	}
-	return `hsl(${hh.toFixed(1)}, ${(ss * 100).toFixed(1)}%, ${(ll * 100).toFixed(1)}%)`;
+	return `hsl(${fmt$1(hh, 1)} ${fmt$1(ss * 100, 1)}% ${fmt$1(ll * 100, 1)}%)`;
 }
 /**
-* Format OKHSL values as a CSS `oklch(L% C H)` string.
+* Format OKHSL values as a CSS `oklch(L C H)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatOklch(h, s, l) {
@@ -483,7 +486,7 @@ function formatOklch(h, s, l) {
 	const C = Math.sqrt(a * a + b * b);
 	let hh = Math.atan2(b, a) * (180 / Math.PI);
 	hh = constrainAngle(hh);
-	return `oklch(${(L * 100).toFixed(1)}% ${C.toFixed(4)} ${hh.toFixed(1)})`;
+	return `oklch(${fmt$1(L, 4)} ${fmt$1(C, 4)} ${fmt$1(hh, 1)})`;
 }
 
 //#endregion
@@ -709,14 +712,84 @@ function pairNormal(p) {
 function pairHC(p) {
 	return Array.isArray(p) ? p[1] : p;
 }
+function isShadowDef(def) {
+	return def.type === "shadow";
+}
+const DEFAULT_SHADOW_TUNING = {
+	saturationFactor: .18,
+	maxSaturation: .25,
+	lightnessFactor: .25,
+	lightnessBounds: [.05, .2],
+	minGapTarget: .05,
+	alphaMax: 1,
+	bgHueBlend: .2
+};
+function resolveShadowTuning(perColor) {
+	return {
+		...DEFAULT_SHADOW_TUNING,
+		...globalConfig.shadowTuning,
+		...perColor,
+		lightnessBounds: perColor?.lightnessBounds ?? globalConfig.shadowTuning?.lightnessBounds ?? DEFAULT_SHADOW_TUNING.lightnessBounds
+	};
+}
+function circularLerp(a, b, t) {
+	let diff = b - a;
+	if (diff > 180) diff -= 360;
+	else if (diff < -180) diff += 360;
+	return ((a + diff * t) % 360 + 360) % 360;
+}
+/**
+* Compute the canonical max-contrast reference t value for normalization.
+* Uses bg.l=1, fg.l=0, intensity=100 — the theoretical maximum.
+* This is a fixed constant per tuning configuration, ensuring uniform
+* scaling across all bg/fg pairs at low intensities.
+*/
+function computeRefT(tuning) {
+	const EPSILON = 1e-6;
+	let lShRef = clamp(tuning.lightnessFactor, tuning.lightnessBounds[0], tuning.lightnessBounds[1]);
+	lShRef = Math.max(Math.min(lShRef, 1 - tuning.minGapTarget), 0);
+	return 1 / Math.max(1 - lShRef, EPSILON);
+}
+function computeShadow(bg, fg, intensity, tuning) {
+	const EPSILON = 1e-6;
+	const clampedIntensity = clamp(intensity, 0, 100);
+	const contrastWeight = fg ? Math.abs(bg.l - fg.l) : 1;
+	const deltaL = clampedIntensity / 100 * contrastWeight;
+	const h = fg ? circularLerp(fg.h, bg.h, tuning.bgHueBlend) : bg.h;
+	const s = fg ? Math.min(fg.s * tuning.saturationFactor, tuning.maxSaturation) : 0;
+	let lSh = clamp(bg.l * tuning.lightnessFactor, tuning.lightnessBounds[0], tuning.lightnessBounds[1]);
+	lSh = Math.max(Math.min(lSh, bg.l - tuning.minGapTarget), 0);
+	const t = deltaL / Math.max(bg.l - lSh, EPSILON);
+	const tRef = computeRefT(tuning);
+	const norm = Math.tanh(tRef / tuning.alphaMax);
+	const alpha = Math.min(tuning.alphaMax * Math.tanh(t / tuning.alphaMax) / norm, tuning.alphaMax);
+	return {
+		h,
+		s,
+		l: lSh,
+		alpha
+	};
+}
 function validateColorDefs(defs) {
 	const names = new Set(Object.keys(defs));
 	for (const [name, def] of Object.entries(defs)) {
-		if (def.contrast !== void 0 && !def.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
-		if (def.lightness !== void 0 && !isAbsoluteLightness(def.lightness) && !def.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
-		if (isAbsoluteLightness(def.lightness) && def.base !== void 0) console.warn(`glaze: color "${name}" has absolute "lightness" and "base". Absolute lightness takes precedence.`);
-		if (def.base && !names.has(def.base)) throw new Error(`glaze: color "${name}" references non-existent base "${def.base}".`);
-		if (!isAbsoluteLightness(def.lightness) && def.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
+		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 (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.`);
+			}
+			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 (isAbsoluteLightness(regDef.lightness) && regDef.base !== void 0) console.warn(`glaze: color "${name}" has absolute "lightness" and "base". Absolute lightness takes precedence.`);
+		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 (!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();
@@ -725,7 +798,13 @@ function validateColorDefs(defs) {
 		if (visited.has(name)) return;
 		inStack.add(name);
 		const def = defs[name];
-		if (def.base && !isAbsoluteLightness(def.lightness)) dfs(def.base);
+		if (isShadowDef(def)) {
+			dfs(def.bg);
+			if (def.fg) dfs(def.fg);
+		} else {
+			const regDef = def;
+			if (regDef.base && !isAbsoluteLightness(regDef.lightness)) dfs(regDef.base);
+		}
 		inStack.delete(name);
 		visited.add(name);
 	}
@@ -738,7 +817,13 @@ function topoSort(defs) {
 		if (visited.has(name)) return;
 		visited.add(name);
 		const def = defs[name];
-		if (def.base && !isAbsoluteLightness(def.lightness)) visit(def.base);
+		if (isShadowDef(def)) {
+			visit(def.bg);
+			if (def.fg) visit(def.fg);
+		} else {
+			const regDef = def;
+			if (regDef.base && !isAbsoluteLightness(regDef.lightness)) visit(regDef.base);
+		}
 		result.push(name);
 	}
 	for (const name of Object.keys(defs)) visit(name);
@@ -802,11 +887,8 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 	if (!baseResolved) throw new Error(`glaze: base "${baseName}" not yet resolved for "${name}".`);
 	const mode = def.mode ?? "auto";
 	const satFactor = clamp(def.saturation ?? 1, 0, 1);
-	let baseL;
-	if (isDark && isHighContrast) baseL = baseResolved.darkContrast.l * 100;
-	else if (isDark) baseL = baseResolved.dark.l * 100;
-	else if (isHighContrast) baseL = baseResolved.lightContrast.l * 100;
-	else baseL = baseResolved.light.l * 100;
+	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
+	const baseL = baseVariant.l * 100;
 	let preferredL;
 	const rawLightness = def.lightness;
 	if (rawLightness === void 0) preferredL = baseL;
@@ -823,27 +905,7 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 	if (rawContrast !== void 0) {
 		const minCr = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
 		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode) : satFactor * ctx.saturation / 100;
-		let baseH;
-		let baseS;
-		let baseLNorm;
-		if (isDark && isHighContrast) {
-			baseH = baseResolved.darkContrast.h;
-			baseS = baseResolved.darkContrast.s;
-			baseLNorm = baseResolved.darkContrast.l;
-		} else if (isDark) {
-			baseH = baseResolved.dark.h;
-			baseS = baseResolved.dark.s;
-			baseLNorm = baseResolved.dark.l;
-		} else if (isHighContrast) {
-			baseH = baseResolved.lightContrast.h;
-			baseS = baseResolved.lightContrast.s;
-			baseLNorm = baseResolved.lightContrast.l;
-		} else {
-			baseH = baseResolved.light.h;
-			baseS = baseResolved.light.s;
-			baseLNorm = baseResolved.light.l;
-		}
-		const baseLinearRgb = okhslToLinearSrgb(baseH, baseS, baseLNorm);
+		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
 		return {
 			l: findLightnessForContrast({
 				hue: effectiveHue,
@@ -860,18 +922,26 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 		satFactor
 	};
 }
+function getSchemeVariant(color, isDark, isHighContrast) {
+	if (isDark && isHighContrast) return color.darkContrast;
+	if (isDark) return color.dark;
+	if (isHighContrast) return color.lightContrast;
+	return color.light;
+}
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
-	const mode = def.mode ?? "auto";
-	const isRoot = isAbsoluteLightness(def.lightness) && !def.base;
-	const effectiveHue = resolveEffectiveHue(ctx.hue, def.hue);
+	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
+	const regDef = def;
+	const mode = regDef.mode ?? "auto";
+	const isRoot = isAbsoluteLightness(regDef.lightness) && !regDef.base;
+	const effectiveHue = resolveEffectiveHue(ctx.hue, regDef.hue);
 	let lightL;
 	let satFactor;
 	if (isRoot) {
-		const root = resolveRootColor(name, def, ctx, isHighContrast);
+		const root = resolveRootColor(name, regDef, ctx, isHighContrast);
 		lightL = root.lightL;
 		satFactor = root.satFactor;
 	} else {
-		const dep = resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue);
+		const dep = resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, effectiveHue);
 		lightL = dep.l;
 		satFactor = dep.satFactor;
 	}
@@ -890,9 +960,18 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	return {
 		h: effectiveHue,
 		s: clamp(finalSat, 0, 1),
-		l: clamp(finalL / 100, 0, 1)
+		l: clamp(finalL / 100, 0, 1),
+		alpha: regDef.opacity ?? 1
 	};
 }
+function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
+	const bgVariant = getSchemeVariant(ctx.resolved.get(def.bg), 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);
+	return computeShadow(bgVariant, fgVariant, intensity, tuning);
+}
 function resolveAllColors(hue, saturation, defs) {
 	validateColorDefs(defs);
 	const order = topoSort(defs);
@@ -902,6 +981,9 @@ function resolveAllColors(hue, saturation, defs) {
 		defs,
 		resolved: /* @__PURE__ */ new Map()
 	};
+	function defMode(def) {
+		return isShadowDef(def) ? void 0 : def.mode ?? "auto";
+	}
 	const lightMap = /* @__PURE__ */ new Map();
 	for (const name of order) {
 		const variant = resolveColorForScheme(name, defs[name], ctx, false, false);
@@ -912,7 +994,7 @@ function resolveAllColors(hue, saturation, defs) {
 			dark: variant,
 			lightContrast: variant,
 			darkContrast: variant,
-			mode: defs[name].mode ?? "auto"
+			mode: defMode(defs[name])
 		});
 	}
 	const lightHCMap = /* @__PURE__ */ new Map();
@@ -935,7 +1017,7 @@ function resolveAllColors(hue, saturation, defs) {
 		dark: lightMap.get(name),
 		lightContrast: lightHCMap.get(name),
 		darkContrast: lightHCMap.get(name),
-		mode: defs[name].mode ?? "auto"
+		mode: defMode(defs[name])
 	});
 	for (const name of order) {
 		const variant = resolveColorForScheme(name, defs[name], ctx, true, false);
@@ -965,7 +1047,7 @@ function resolveAllColors(hue, saturation, defs) {
 		dark: darkMap.get(name),
 		lightContrast: lightHCMap.get(name),
 		darkContrast: darkHCMap.get(name),
-		mode: defs[name].mode ?? "auto"
+		mode: defMode(defs[name])
 	});
 	return result;
 }
@@ -975,8 +1057,14 @@ const formatters = {
 	hsl: formatHsl,
 	oklch: formatOklch
 };
+function fmt(value, decimals) {
+	return parseFloat(value.toFixed(decimals)).toString();
+}
 function formatVariant(v, format = "okhsl") {
-	return formatters[format](v.h, v.s * 100, v.l * 100);
+	const base = formatters[format](v.h, v.s * 100, v.l * 100);
+	if (v.alpha >= 1) return base;
+	const closing = base.lastIndexOf(")");
+	return `${base.slice(0, closing)} / ${fmt(v.alpha, 4)})`;
 }
 function resolveModes(override) {
 	return {
@@ -1227,7 +1315,8 @@ glaze.configure = function configure(config) {
 		modes: {
 			dark: config.modes?.dark ?? globalConfig.modes.dark,
 			highContrast: config.modes?.highContrast ?? globalConfig.modes.highContrast
-		}
+		},
+		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning
 	};
 };
 /**
@@ -1249,6 +1338,40 @@ glaze.color = function color(input) {
 	return createColorToken(input);
 };
 /**
+* Compute a shadow color from a bg/fg pair and intensity.
+*/
+glaze.shadow = function shadow(input) {
+	const bg = parseOkhslInput(input.bg);
+	const fg = input.fg ? parseOkhslInput(input.fg) : void 0;
+	const tuning = resolveShadowTuning(input.tuning);
+	return computeShadow({
+		...bg,
+		alpha: 1
+	}, fg ? {
+		...fg,
+		alpha: 1
+	} : void 0, input.intensity, tuning);
+};
+/**
+* Format a resolved color variant as a CSS string.
+*/
+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.
 */