@tenphi/glaze 0.0.0-snapshot.c3d484c → 0.0.0-snapshot.c61bbdf

package/dist/index.mjs

@@ -368,6 +368,27 @@ const sRGBGammaToLinear = (val) => {
 	const abs = Math.abs(val);
 	return abs <= .04045 ? val / 12.92 : sign * Math.pow((abs + .055) / 1.055, 2.4);
 };
+/** Gamma-encoded sRGB clamped to the display gamut — what a browser paints. */
+function toDisplayGamma(linearRgb) {
+	return [
+		Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0]))),
+		Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1]))),
+		Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2])))
+	];
+}
+/**
+* Browser alpha compositing: `source-over` interpolates the gamma-encoded
+* channels, not linear light (50% black over white paints `#808080`).
+* Takes display-gamma inputs and returns the composite as linear sRGB for
+* the luminance pipeline.
+*/
+function compositeOverGamma(baseGamma, overlayGamma, alpha) {
+	return [
+		sRGBGammaToLinear(baseGamma[0] + (overlayGamma[0] - baseGamma[0]) * alpha),
+		sRGBGammaToLinear(baseGamma[1] + (overlayGamma[1] - baseGamma[1]) * alpha),
+		sRGBGammaToLinear(baseGamma[2] + (overlayGamma[2] - baseGamma[2]) * alpha)
+	];
+}
 /**
 * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
 * h: 0–360, s: 0–1, l: 0–1. Returns [r, g, b] with each channel 0–1.
@@ -777,6 +798,7 @@ function configure(config) {
 			highContrast: config.modes?.highContrast ?? globalConfig.modes.highContrast
 		},
 		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
+		glowTuning: config.glowTuning ?? globalConfig.glowTuning,
 		autoFlip: config.autoFlip ?? globalConfig.autoFlip,
 		pastel: false,
 		inferRole: config.inferRole ?? globalConfig.inferRole,
@@ -808,6 +830,7 @@ function mergeConfig(base, override) {
 		states: base.states,
 		modes: base.modes,
 		shadowTuning: override.shadowTuning ?? base.shadowTuning,
+		glowTuning: override.glowTuning ?? base.glowTuning,
 		autoFlip: override.autoFlip ?? base.autoFlip,
 		pastel: override.pastel ?? false,
 		inferRole: override.inferRole ?? base.inferRole,
@@ -817,8 +840,8 @@ function mergeConfig(base, override) {
 /**
 * Freeze `getConfig() ∪ instanceLocal ∪ exportArg` as a plain, resolve-relevant
 * override for authoring export, so restored snapshots pin these fields. Later
-* wins; nested objects (`shadowTuning`) replace wholesale. The final
-* `structuredClone` detaches tone-window / shadow objects that `mergeConfig`
+* wins; nested objects (`shadowTuning` / `glowTuning`) replace wholesale. The
+* final `structuredClone` detaches tone-window / tuning objects that `mergeConfig`
 * may still share with the live global config.
 */
 function freezeConfigForExport(instanceLocal, exportArg) {
@@ -835,6 +858,7 @@ function freezeConfigForExport(instanceLocal, exportArg) {
 		inferRole: effective.inferRole
 	};
 	if (effective.shadowTuning !== void 0) out.shadowTuning = effective.shadowTuning;
+	if (effective.glowTuning !== void 0) out.glowTuning = effective.glowTuning;
 	const authoredLevel = exportArg?.contrastLevel ?? instanceLocal?.contrastLevel;
 	if (authoredLevel !== void 0) out.contrastLevel = normalizeContrastLevel(authoredLevel);
 	return structuredClone(out);
@@ -845,8 +869,13 @@ function freezeConfigForExport(instanceLocal, exportArg) {
 /**
 * Current authoring-export schema version. Bump when the export shape
 * changes in a non-compatible way. Written on every `.export()` snapshot.
+*
+* - `1` — Glaze 2.x.
+* - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
+*   `glow` was added. Version-1 theme snapshots that carry shadow defs or a
+*   `shadowTuning` are rejected on restore.
 */
-const GLAZE_EXPORT_VERSION = 1;
+const GLAZE_EXPORT_VERSION = 2;
 
 //#endregion
 //#region src/serialize.ts
@@ -868,6 +897,22 @@ function assertExportVersion(data, factory) {
 	if (data.version > GLAZE_EXPORT_VERSION) throw new Error(`${factory}: unsupported export version ${data.version} (this library supports version ${GLAZE_EXPORT_VERSION}). Upgrade @tenphi/glaze to load this snapshot.`);
 }
 /**
+* Reject a version-1 (Glaze 2) theme snapshot that carries shadow colors or a
+* `shadowTuning`. Glaze 3 changed what shadow `intensity`, `fg` and tuning
+* mean, so restoring one would silently re-render every shadow differently.
+* Version-1 snapshots without shadows load as before. `fallbackVersion` is the
+* enclosing palette's version, for a theme entry that carries none of its own.
+*/
+function assertNoLegacyShadows(data, factory, fallbackVersion) {
+	if ((data.version ?? fallbackVersion) !== 1) return;
+	const colors = isPlainObject(data.colors) ? data.colors : {};
+	const shadows = Object.keys(colors).filter((name) => isPlainObject(colors[name]) && colors[name].type === "shadow");
+	const hasTuning = isPlainObject(data.config) && data.config.shadowTuning !== void 0;
+	if (shadows.length === 0 && !hasTuning) return;
+	const what = shadows.length > 0 ? `shadow colors (${shadows.map((n) => JSON.stringify(n)).join(", ")})` : "a \"shadowTuning\" config";
+	throw new Error(`${factory}: this snapshot is export version 1 (Glaze 2) and contains ${what}. Glaze 3 changed what shadow "intensity", "fg" and tuning mean, so it would restore with different shadows. Re-author them as described in docs/migration.md ("3.0 — shadows and glows") and export again.`);
+}
+/**
 * When `kind` is present, it must match the factory. Missing `kind` is
 * allowed for legacy snapshots.
 */
@@ -960,7 +1005,7 @@ function hcMirrorsNormal(config) {
 	return contrastFraction(config) === 1;
 }
 /**
-* A numeric HC pair at a blend fraction (shadow `intensity`, mix `value`).
+* A numeric HC pair at a blend fraction (shadow / glow `intensity`, mix `value`).
 *
 * The endpoints return the authored entry *by identity* rather than through
 * float arithmetic — `a + (b - a) * 1` is not bit-exactly `b` in IEEE 754, and
@@ -1083,7 +1128,7 @@ function isAbsoluteTone(tone) {
 * - the scheme tone window, including the high-contrast bypass and its
 *   continuous generalization under a manual contrast level.
 *
-* See `docs/okhst.md` for the full specification and the calibrated
+* See `docs/okhst.mdx` for the full specification and the calibrated
 * default constants.
 */
 /**
@@ -1439,8 +1484,8 @@ function validateOkhstColor(value) {
 }
 /**
 * Extract an OKHSL color from any `GlazeColorValue` form. Also used by
-* `glaze.shadow()` so all shadow inputs (hex, color functions, OKHSL,
-* literal objects) go through one parser.
+* `glaze.shadow()` / `glaze.glow()` so all their inputs (hex, color
+* functions, OKHSL, literal objects) go through one parser.
 */
 function extractOkhslFromValue(value) {
 	if (typeof value === "string") return parseColorString(value);
@@ -2072,36 +2117,46 @@ function oppositeRole(role) {
 }
 
 //#endregion
-//#region src/shadow.ts
+//#region src/lighting.ts
 /**
-* Shadow color computation.
+* Shadow and glow color computation.
 *
-* Owns the shadow / mix def predicates, default tuning constants, the
-* tuning merge, and the actual `computeShadow` math (hue blend,
-* saturation cap, lightness clamp, alpha curve). The resolver consumes
-* this module per scheme variant.
+* Owns the shadow / glow / mix def predicates, the default lighting tuning
+* and its merge, and the exact lighting solver (`computeLighting`). Both
+* types emit a translucent pigment over a known surface (`bg`) whose opacity
+* is solved so the composite lands an exact tone step away from it: darker
+* for `shadow`, lighter for `glow`, in every scheme. Compositing is modeled
+* the way browsers paint it — `source-over` on gamma-encoded sRGB — and the
+* step is measured in the WCAG-shaped tone of the composite's luminance, so
+* it holds on chromatic surfaces too. An optional object (`fg`) scales the
+* step the way bounce light does. The resolver consumes this module per
+* scheme variant; `glaze.shadow()` / `glaze.glow()` call it directly.
 */
 function isShadowDef(def) {
 	return def.type === "shadow";
 }
+function isGlowDef(def) {
+	return def.type === "glow";
+}
+/** A `shadow` or `glow` def — the translucent overlay types. */
+function isLightingDef(def) {
+	return isShadowDef(def) || isGlowDef(def);
+}
 function isMixDef(def) {
 	return def.type === "mix";
 }
-const DEFAULT_SHADOW_TUNING = {
-	saturationFactor: .18,
-	maxSaturation: .25,
-	lightnessFactor: .25,
-	lightnessBounds: [.05, .2],
-	minGapTarget: .05,
-	alphaMax: 1,
-	bgHueBlend: .2
+const DEFAULT_LIGHTING_TUNING = {
+	objectInfluence: .5,
+	tint: 0,
+	reach: 1,
+	hueBleed: 0
 };
-function resolveShadowTuning(perColor, globalTuning) {
+/** Defaults ← global (`shadowTuning` / `glowTuning`) ← per-color, field by field. */
+function resolveLightingTuning(perColor, globalTuning) {
 	return {
-		...DEFAULT_SHADOW_TUNING,
+		...DEFAULT_LIGHTING_TUNING,
 		...globalTuning,
-		...perColor,
-		lightnessBounds: perColor?.lightnessBounds ?? globalTuning?.lightnessBounds ?? DEFAULT_SHADOW_TUNING.lightnessBounds
+		...perColor
 	};
 }
 function circularLerp(a, b, t) {
@@ -2110,47 +2165,122 @@ function circularLerp(a, b, t) {
 	else if (diff < -180) diff += 360;
 	return ((a + diff * t) % 360 + 360) % 360;
 }
+const SAT_EPSILON = 1e-6;
+const BISECT_ITERATIONS = 40;
+const GOLDEN = (Math.sqrt(5) - 1) / 2;
 /**
-* 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);
+* Object factor `k = max(0, 1 + β · d · (t_bg − t_fg) / 100)`, with `d = +1`
+* for a shadow and `−1` for a glow. Calibrated so an object at the surface's
+* own tone — or no object at all — gives exactly the authored step: a darker
+* object deepens its shadow, a lighter one strengthens its glow.
+*/
+function objectFactor(kind, bgTone, fgTone, objectInfluence) {
+	if (fgTone === void 0) return 1;
+	const d = kind === "shadow" ? 1 : -1;
+	return Math.max(0, 1 + objectInfluence * d * (bgTone - fgTone) / 100);
+}
+/**
+* The pigment: pure black (shadow) / pure white (glow) by default. `reach`
+* below 1 parks it part of the way from the surface's tone to that extreme so
+* a `tint` — saturation in the surface's hue, optionally pulled toward the
+* object's hue by `hueBleed` — can show.
+*/
+function pigmentFor(kind, bg, fg, bgTone, tuning) {
+	const reach = clamp(tuning.reach, 0, 1);
+	const tone = kind === "shadow" ? bgTone * (1 - reach) : bgTone + (100 - bgTone) * reach;
+	const bleed = clamp(tuning.hueBleed, 0, 1);
 	return {
-		h,
-		s,
-		l: lSh,
-		alpha
+		h: fg !== void 0 && fg.s > SAT_EPSILON && bleed > 0 ? circularLerp(bg.h, fg.h, bleed) : bg.h,
+		s: clamp(tuning.tint, 0, 1),
+		l: clamp(fromTone(tone), 0, 1)
+	};
+}
+/**
+* Solve the pigment opacity that moves `bg` exactly `intensity × k` tones
+* darker (shadow) or lighter (glow) once the browser composites it.
+*
+* The composite's luminance is convex in alpha (each gamma channel moves
+* linearly and the sRGB decode is convex), so the "has reached the step"
+* predicate is monotone whenever full opacity reaches it and a bisection
+* lands it exactly. When it doesn't, the step is out of reach — a glow on
+* white, a deep shadow on near-black — and the result pins to the pigment's
+* strongest composite, reporting what it reached in `reached`.
+*/
+function computeLighting(kind, bg, fg, intensity, tuning, pastel) {
+	const bgTone = toTone(bg.l);
+	const k = objectFactor(kind, bgTone, fg === void 0 ? void 0 : toTone(fg.l), tuning.objectInfluence);
+	const step = clamp(intensity, 0, 100) * k;
+	const pigment = pigmentFor(kind, bg, fg, bgTone, tuning);
+	const bgGamma = toDisplayGamma(okhslToLinearSrgb(bg.h, bg.s, bg.l, bg.pastel ?? pastel));
+	const pigmentGamma = toDisplayGamma(okhslToLinearSrgb(pigment.h, pigment.s, pigment.l, pastel));
+	const toneAt = (alpha) => toneFromY(relativeLuminanceFromLinearRgb(compositeOverGamma(bgGamma, pigmentGamma, alpha)));
+	const surfaceTone = toneAt(0);
+	const d = kind === "shadow" ? 1 : -1;
+	const gain = (alpha) => d * (surfaceTone - toneAt(alpha));
+	if (step <= 0) return {
+		...pigment,
+		alpha: 0,
+		step,
+		reached: 0
+	};
+	let hi = 1;
+	if (gain(1) < step) {
+		hi = kind === "shadow" ? strongestShadowAlpha(gain) : 1;
+		const reached = gain(hi);
+		if (reached < step) return reached > 0 ? {
+			...pigment,
+			alpha: hi,
+			step,
+			reached
+		} : {
+			...pigment,
+			alpha: 0,
+			step,
+			reached: 0
+		};
+	}
+	let lo = 0;
+	for (let i = 0; i < BISECT_ITERATIONS; i++) {
+		const mid = (lo + hi) / 2;
+		if (gain(mid) < step) lo = mid;
+		else hi = mid;
+	}
+	return {
+		...pigment,
+		alpha: hi,
+		step,
+		reached: gain(hi)
 	};
 }
+/**
+* Opacity of a shadow pigment's darkest composite. Full opacity for pure
+* black; a tinted pigment whose channels pull in different directions can
+* bottom out earlier, so a golden-section search over the unimodal gain finds
+* it and the better of that and full opacity wins. (A glow needs no search:
+* convex luminance peaks at an endpoint, and full opacity is the one that
+* lightens.)
+*/
+function strongestShadowAlpha(gain) {
+	let a = 0;
+	let b = 1;
+	for (let i = 0; i < BISECT_ITERATIONS; i++) {
+		const c = b - GOLDEN * (b - a);
+		const e = a + GOLDEN * (b - a);
+		if (gain(c) < gain(e)) a = c;
+		else b = e;
+	}
+	const peak = (a + b) / 2;
+	return gain(peak) > gain(1) ? peak : 1;
+}
 
 //#endregion
 //#region src/validation.ts
 /**
 * Color graph validation and topological sort.
 *
-* `validateColorDefs` rejects bad references (missing / shadow-referencing /
-* base/contrast/tone mismatches) and detects cycles before the
-* resolver runs. `topoSort` orders defs so each color is processed after
+* `validateColorDefs` rejects bad references (missing / shadow- or
+* glow-referencing / base/contrast/tone mismatches) and detects cycles before
+* the resolver runs. `topoSort` orders defs so each color is processed after
 * its base / bg / fg / target dependencies.
 */
 /**
@@ -2179,24 +2309,37 @@ function assertConsistentContrastMetric(name, contrast) {
 	if (normal === hc) return;
 	throw new Error(`glaze: color "${name}" has a "contrast" pair that switches metric (${normal} → ${hc}). A WCAG ratio and an APCA Lc are different scales; use one metric for both entries, e.g. { ${normal}: [normal, highContrast] }.`);
 }
+/**
+* `'shadow'` / `'glow'` when `ref` names a local translucent overlay — which
+* nothing may build on — else `undefined`.
+*/
+function overlayKindOf(defs, ref) {
+	const def = Object.hasOwn(defs, ref) ? defs[ref] : void 0;
+	return def !== void 0 && isLightingDef(def) ? def.type : void 0;
+}
 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 (!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 (!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.`);
+		if (isLightingDef(def)) {
+			const kind = def.type;
+			for (const field of ["bg", "fg"]) {
+				const ref = def[field];
+				if (ref === void 0) continue;
+				if (!allNames.has(ref)) throw new Error(`glaze: ${kind} "${name}" references non-existent ${field} "${ref}".`);
+				const refKind = overlayKindOf(defs, ref);
+				if (refKind !== void 0) throw new Error(`glaze: ${kind} "${name}" ${field} "${ref}" references a ${refKind} color.`);
 			}
 			continue;
 		}
 		if (isMixDef(def)) {
 			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.`);
+			for (const field of ["base", "target"]) {
+				const ref = def[field];
+				const refKind = overlayKindOf(defs, ref);
+				if (refKind !== void 0) throw new Error(`glaze: mix "${name}" ${field} "${ref}" references a ${refKind} color.`);
+			}
 			assertConsistentContrastMetric(name, def.contrast);
 			continue;
 		}
@@ -2210,7 +2353,8 @@ function validateColorDefs(defs, externalBases) {
 		if (regDef.contrast !== void 0 && !regDef.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
 		if (regDef.tone !== void 0 && !isAbsoluteTone(regDef.tone) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "tone" without "base".`);
 		if (regDef.base && !allNames.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
-		if (regDef.base && localNames.has(regDef.base) && isShadowDef(defs[regDef.base])) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a shadow color.`);
+		const baseKind = regDef.base && overlayKindOf(defs, regDef.base);
+		if (baseKind) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a ${baseKind} color.`);
 		if (!hasAbsoluteTone(regDef) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "tone" (root), "from" (a literal color), 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 tone unpredictable.`);
 	}
@@ -2222,7 +2366,7 @@ function validateColorDefs(defs, externalBases) {
 		if (visited.has(name)) return;
 		inStack.add(name);
 		const def = defs[name];
-		if (isShadowDef(def)) {
+		if (isLightingDef(def)) {
 			dfs(def.bg);
 			if (def.fg) dfs(def.fg);
 		} else if (isMixDef(def)) {
@@ -2245,7 +2389,7 @@ function topoSort(defs) {
 		visited.add(name);
 		const def = defs[name];
 		if (def === void 0) return;
-		if (isShadowDef(def)) {
+		if (isLightingDef(def)) {
 			visit(def.bg);
 			if (def.fg) visit(def.fg);
 		} else if (isMixDef(def)) {
@@ -2264,7 +2408,8 @@ function topoSort(defs) {
 //#endregion
 //#region src/warnings.ts
 /**
-* Contrast-warning dispatcher.
+* Resolve-time warning dispatcher: unmet contrast floors, chromatic contrast
+* drift, and out-of-reach shadow / glow steps.
 *
 * Tokens memoize their resolution, but a long-lived process (e.g. a dev
 * server with HMR) can re-resolve the same theme many times. The cache
@@ -2304,10 +2449,11 @@ function warnContrastUnmet(name, isDark, isHighContrast, contrast, actual) {
 	console.warn(`glaze: color "${name}" cannot meet ${metricLabel(contrast)} in ${scheme} scheme (got ${actual.toFixed(2)}). Try widening the tone window, lowering the contrast target, or picking a base color further from this color's tone.`);
 }
 /**
-* Verification (§10): a chromatic swatch inherits the gray tone's
-* lightness but drifts in real luminance, so a contrast-floored color may
-* land slightly under the contrast its tone implies. Emit an advisory
-* warning when the actual measured contrast drifts below the target.
+* Verification (the drift check in docs/okhst.mdx): a chromatic swatch
+* inherits the gray tone's lightness but drifts in real luminance, so a
+* contrast-floored color may land slightly under the contrast its tone
+* implies. Emit an advisory warning when the actual measured contrast
+* drifts below the target.
 */
 function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase) {
 	const actual = contrast.metric === "apca" ? Math.abs(contrast.polarity === "bg" ? apcaContrast(yBase, yColor) : apcaContrast(yColor, yBase)) : contrastRatioFromLuminance(yColor, yBase);
@@ -2316,6 +2462,23 @@ function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase
 	if (dedupe(`drift|${name}|${scheme}|${contrast.metric}|${contrast.target.toFixed(2)}|${actual.toFixed(2)}`)) return;
 	console.warn(`glaze: color "${name}" drifts below ${metricLabel(contrast)} in ${scheme} scheme (measured ${actual.toFixed(2)}). Chromatic luminance differs from the gray tone; nudge the tone or saturation if the floor matters.`);
 }
+/** Tone slack before an out-of-reach shadow / glow step is worth a warning. */
+const LIGHTING_WARN_SLACK = .05;
+/**
+* Warn when a `shadow` / `glow` step is out of reach of its pigment — a glow
+* on white, a deep shadow on near-black — so the composite pins to the
+* pigment's strongest and lands short. `name` is omitted for the standalone
+* `glaze.shadow()` / `glaze.glow()` factories, which have no scheme either.
+*/
+function warnLightingUnreachable(kind, name, scheme, step, reached) {
+	if (reached >= step - LIGHTING_WARN_SLACK) return;
+	const label = scheme ? schemeLabel(scheme.isDark, scheme.isHighContrast) : void 0;
+	if (dedupe(`lighting|${kind}|${name ?? ""}|${label ?? ""}|${step.toFixed(2)}|${reached.toFixed(2)}`)) return;
+	const subject = name === void 0 ? `glaze.${kind}()` : `${kind} "${name}"`;
+	const where = label === void 0 ? "" : ` in ${label} scheme`;
+	const extreme = kind === "shadow" ? "black" : "white";
+	console.warn(`glaze: ${subject} cannot reach a ${step.toFixed(1)}-tone step${where} (reached ${reached.toFixed(1)} at full strength). Lower the intensity, move the surface away from ${extreme}, or raise a tuned-down \`reach\`.`);
+}
 
 //#endregion
 //#region src/resolver.ts
@@ -2329,13 +2492,13 @@ function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase
 * passes bypass the level entirely, so the high-contrast slots are the same
 * values `'auto'` resolves. At level 100 the normal passes already are the
 * high-contrast ones, so the solver drops to two passes (light → dark) and
-* mirrors the slots. Owns the per-scheme resolve helpers for regular, shadow,
-* and mix color defs.
+* mirrors the slots. Owns the per-scheme resolve helpers for regular, shadow /
+* glow, and mix color defs.
 *
 * Variants are stored in OKHST: `h` / `s` are OKHSL hue/saturation and
 * `t` is the canonical contrast-uniform tone (0–1, reference eps). The
 * resolver works in tone for regular colors and converts to/from OKHSL
-* lightness only at the mix/shadow and luminance edges.
+* lightness only at the mix / shadow / glow and luminance edges.
 *
 * Every function receives a single `GlazeConfigResolved` so the full
 * per-instance config (including overrides) is available without
@@ -2394,7 +2557,7 @@ function resolveRoleInMap(name, def, defs, inferRole, roles) {
 	const cached = roles.get(name);
 	if (cached) return cached;
 	let role;
-	if (isShadowDef(def)) role = "surface";
+	if (isLightingDef(def)) role = "surface";
 	else if (isMixDef(def)) role = normalizeRole(def.role) ?? (inferRole ? inferRoleFromName(name) : void 0) ?? resolveBaseRoleInMap(def.base, defs, inferRole, roles) ?? "text";
 	else {
 		const regDef = def;
@@ -2412,7 +2575,7 @@ function resolveRoleInMap(name, def, defs, inferRole, roles) {
 *   4. `'text'` (foreground) default
 *
 * Memoized on `ctx.roles` so the four scheme passes share one resolution.
-* Shadows have no contrast participation and default to `'surface'`.
+* Shadows and glows have no contrast participation and default to `'surface'`.
 */
 function resolveRole(name, def, ctx) {
 	return resolveRoleInMap(name, def, ctx.defs, ctx.config.inferRole, ctx.roles);
@@ -2431,7 +2594,7 @@ function passTone(tone, isHighContrast, config) {
 	const f = contrastFraction(config);
 	return f === void 0 || isHighContrast ? parseToneValue(isHighContrast ? pairHC(tone) : pairNormal(tone)) : parseToneValueAt(tone, f);
 }
-/** The authored numeric pair for this pass (shadow `intensity`, mix `value`). */
+/** The authored numeric pair for this pass (shadow / glow `intensity`, mix `value`). */
 function passNumber(p, isHighContrast, config) {
 	const f = contrastFraction(config);
 	if (f === void 0 || isHighContrast) return isHighContrast ? pairHC(p) : pairNormal(p);
@@ -2609,7 +2772,7 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, channels,
 	return clamp(preferredTone, 0, 100);
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
-	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
+	if (isLightingDef(def)) return resolveLightingForScheme(name, def, ctx, isDark, isHighContrast);
 	if (isMixDef(def)) return resolveMixForScheme(name, def, ctx, isDark, isHighContrast);
 	const regDef = def;
 	const mode = regDef.mode ?? "auto";
@@ -2627,15 +2790,33 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 		pastel
 	};
 }
-function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
+/**
+* Shadow / glow: solve the pigment opacity that lands this scheme's `bg`
+* exactly `intensity × k` tones darker / lighter. `bg` and `fg` are read per
+* scheme, so the object factor `k` adapts on its own in dark and high contrast.
+*/
+function resolveLightingForScheme(name, def, ctx, isDark, isHighContrast) {
 	const bgVariant = toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.bg), isDark, isHighContrast));
-	let fgVariant;
-	if (def.fg) fgVariant = toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast));
+	const fgVariant = def.fg ? toOkhslVariant(getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast)) : void 0;
 	const intensity = passNumber(def.intensity, isHighContrast, ctx.config);
-	const tuning = resolveShadowTuning(def.tuning, ctx.config.shadowTuning);
+	const tuning = resolveLightingTuning(def.tuning, def.type === "shadow" ? ctx.config.shadowTuning : ctx.config.glowTuning);
+	const pastel = def.pastel ?? ctx.config.pastel;
+	const result = computeLighting(def.type, {
+		...bgVariant,
+		pastel: bgVariant.pastel ?? ctx.config.pastel
+	}, fgVariant, intensity, tuning, pastel);
+	warnLightingUnreachable(def.type, name, {
+		isDark,
+		isHighContrast
+	}, result.step, result.reached);
 	return {
-		...toToneVariant(computeShadow(bgVariant, fgVariant, intensity, tuning)),
-		pastel: def.pastel ?? ctx.config.pastel
+		...toToneVariant({
+			h: result.h,
+			s: result.s,
+			l: result.l,
+			alpha: result.alpha
+		}),
+		pastel
 	};
 }
 function okhslVariantToLinearRgb(v, pastel) {
@@ -2691,7 +2872,11 @@ function resolveMixForScheme(name, def, ctx, isDark, isHighContrast) {
 		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast, ctx.config, polarity);
 		const metric = resolvedContrast.metric;
 		let luminanceAt;
-		if (blend === "transparent" || space === "srgb") luminanceAt = (v) => metricLuminance(metric, linearSrgbLerp(baseLinear, targetLinear, v));
+		if (blend === "transparent") {
+			const baseGamma = toDisplayGamma(baseLinear);
+			const targetGamma = toDisplayGamma(targetLinear);
+			luminanceAt = (v) => metricLuminance(metric, compositeOverGamma(baseGamma, targetGamma, v));
+		} else if (space === "srgb") luminanceAt = (v) => metricLuminance(metric, linearSrgbLerp(baseLinear, targetLinear, v));
 		else luminanceAt = (v) => {
 			return metricLuminance(metric, okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v, pastel));
 		};
@@ -2728,7 +2913,7 @@ function resolveMixForScheme(name, def, ctx, isDark, isHighContrast) {
 	};
 }
 function defMode(def) {
-	if (isShadowDef(def) || isMixDef(def)) return void 0;
+	if (isLightingDef(def) || isMixDef(def)) return void 0;
 	return def.mode ?? "auto";
 }
 /**
@@ -2772,9 +2957,10 @@ function seedField(order, ctx, field, source) {
 	}
 }
 /**
-* After the passes, surface chromatic contrast drift (§10): a color
-* resolved with a `base` + `contrast` may land slightly under the contrast
-* its tone implies because chromatic luminance drifts from the gray tone.
+* After the passes, surface chromatic contrast drift (the drift check in
+* docs/okhst.mdx): a color resolved with a `base` + `contrast` may land
+* slightly under the contrast its tone implies because chromatic luminance
+* drifts from the gray tone.
 *
 * Under a manual `contrastLevel` the spec is resolved at the level, so the check
 * measures each normal variant against the target it was actually solved for. At
@@ -2786,7 +2972,7 @@ function verifyContrastDrift(order, defs, result, config) {
 	const roles = /* @__PURE__ */ new Map();
 	for (const name of order) {
 		const def = defs[name];
-		if (isShadowDef(def) || isMixDef(def)) continue;
+		if (isLightingDef(def) || isMixDef(def)) continue;
 		const regDef = def;
 		if (regDef.contrast === void 0 || !regDef.base) continue;
 		const color = result.get(name);
@@ -2896,7 +3082,7 @@ function schemeSeedHue(ctx, scheme) {
 	return scheme === "dark" ? ctx.darkSeedHue ?? ctx.seedHue : ctx.seedHue;
 }
 function themeHuePlan(name, def, variant, ctx, scheme) {
-	if (def === void 0 || isShadowDef(def) || isMixDef(def) || isAchromatic(variant)) return {
+	if (def === void 0 || isLightingDef(def) || isMixDef(def) || isAchromatic(variant)) return {
 		hueVar: "",
 		inline: true,
 		declarations: []
@@ -4080,10 +4266,11 @@ function buildPaletteOutput(themes, paletteOptions, options, buildOne, merge, em
 	return acc;
 }
 /** Rebuild a theme from a `theme.export()` snapshot. */
-function createThemeFromExport(data, factory = "glaze.themeFrom") {
+function createThemeFromExport(data, factory = "glaze.themeFrom", fallbackVersion) {
 	if (data === null || typeof data !== "object") throw new Error(`${factory}: expected an object from theme.export(), got ${data === null ? "null" : typeof data}.`);
 	assertExportKind(data, "theme", factory);
 	assertExportVersion(data, factory);
+	assertNoLegacyShadows(data, factory, fallbackVersion);
 	if (typeof data.hue !== "number" || typeof data.saturation !== "number") throw new Error(`${factory}: expected numeric "hue" and "saturation" fields.`);
 	for (const field of ["darkHue", "darkSaturation"]) if (data[field] !== void 0 && typeof data[field] !== "number") throw new Error(`${factory}: expected "${field}" to be a number when present (got ${JSON.stringify(data[field])}).`);
 	return createTheme({
@@ -4102,7 +4289,7 @@ function createPaletteFromExport(data) {
 	assertExportVersion(data, "glaze.paletteFrom");
 	if (data.themes === null || typeof data.themes !== "object") throw new Error(`glaze.paletteFrom: expected a "themes" object map of theme exports.`);
 	const rebuilt = {};
-	for (const [name, themeExport] of Object.entries(data.themes)) rebuilt[name] = createThemeFromExport(themeExport, `glaze.paletteFrom (theme "${name}")`);
+	for (const [name, themeExport] of Object.entries(data.themes)) rebuilt[name] = createThemeFromExport(themeExport, `glaze.paletteFrom (theme "${name}")`, data.version);
 	return createPalette(rebuilt, { primary: data.primary });
 }
 function createPalette(themes, paletteOptions) {
@@ -4239,42 +4426,17 @@ function createPalette(themes, paletteOptions) {
 * - `theme.ts` — single-theme factory
 * - `palette.ts` — multi-theme composition
 * - `color-token.ts` — standalone single-color tokens (`glaze.color`)
-* - `shadow.ts` — standalone shadow factory (`glaze.shadow`)
+* - `lighting.ts` — shadow / glow solver (`glaze.shadow`, `glaze.glow`)
 * - `formatters.ts` — variant → string (`glaze.format`)
 * - `config.ts` — global config singleton
 * - `serialize.ts` — authoring export type guards / version checks
 */
-/**
-* Create a single-hue glaze theme.
-*
-* An optional `config` override can be supplied to customize the resolve
-* behavior for this theme (tone windows, 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.
-*
-* The object form also accepts `darkHue` / `darkSaturation` — a separate
-* seed pair for the dark and dark-high-contrast schemes. Both default to
-* their light counterparts, and an explicit `darkSaturation` opts the theme
-* out of the global `darkDesaturation` reduction.
-*
-* @example
-* ```ts
-* const primary = glaze(280, 80);
-* // or shorthand:
-* const primary = glaze({ hue: 280, saturation: 80 });
-* // with a retuned dark seed:
-* const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
-* // with config override:
-* const raw = glaze(280, 80, { lightTone: false });
-* ```
-*/
-function glaze(hueOrOptions, saturation, config) {
+function glaze(hueOrOptions, saturationOrConfig, config) {
 	if (typeof hueOrOptions === "number") return createTheme({
 		hue: hueOrOptions,
-		saturation: saturation ?? 100
+		saturation: (typeof saturationOrConfig === "number" ? saturationOrConfig : void 0) ?? 100
 	}, void 0, config);
-	return createTheme(hueOrOptions, void 0, config);
+	return createTheme(hueOrOptions, void 0, typeof saturationOrConfig === "object" ? saturationOrConfig : config);
 }
 /** Configure global glaze settings. */
 glaze.configure = function configure$1(config) {
@@ -4345,25 +4507,14 @@ glaze.color = function color(input, 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, or `{ r, g, b }` / `{ h, s, l }` / `{ l, c, h }` objects.
-*/
-glaze.shadow = function shadow(input) {
+/** Shared body of `glaze.shadow()` / `glaze.glow()`. */
+function standaloneLighting(kind, input) {
 	const bg = extractOkhslFromValue(input.bg);
 	const fg = input.fg ? extractOkhslFromValue(input.fg) : void 0;
 	const cfg = getConfig();
-	const tuning = resolveShadowTuning(input.tuning, cfg.shadowTuning);
-	const result = computeShadow({
-		...bg,
-		alpha: 1
-	}, fg ? {
-		...fg,
-		alpha: 1
-	} : void 0, input.intensity, tuning);
+	const tuning = resolveLightingTuning(input.tuning, kind === "shadow" ? cfg.shadowTuning : cfg.glowTuning);
+	const result = computeLighting(kind, bg, fg, input.intensity, tuning, false);
+	warnLightingUnreachable(kind, void 0, void 0, result.step, result.reached);
 	const { h, s, t } = okhslToOkhst({
 		h: result.h,
 		s: result.s,
@@ -4375,6 +4526,27 @@ glaze.shadow = function shadow(input) {
 		t,
 		alpha: result.alpha
 	};
+}
+/**
+* Compute a shadow over a surface: a translucent pigment whose opacity lands
+* `bg` exactly `intensity` tones darker once the browser composites it. The
+* optional object `fg` scales the step (a darker object casts a deeper
+* shadow).
+*
+* Both `bg` and `fg` accept any `GlazeColorValue` form: hex (`#rgb` /
+* `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()` / `oklch()`
+* strings, or `{ r, g, b }` / `{ h, s, l }` / `{ l, c, h }` objects.
+*/
+glaze.shadow = function shadow(input) {
+	return standaloneLighting("shadow", input);
+};
+/**
+* Compute a glow over a surface — the mirror of `glaze.shadow()`: the
+* composite lands `bg` exactly `intensity` tones lighter, and a lighter
+* object `fg` glows stronger. Accepts the same inputs.
+*/
+glaze.glow = function glow(input) {
+	return standaloneLighting("glow", input);
 };
 /** Format a resolved color variant as a CSS string. */
 glaze.format = function format(variant, colorFormat, pastel) {