@tenphi/glaze 0.5.8 → 0.6.0

package/dist/index.d.cts

@@ -6,6 +6,7 @@
  * against a base color. Used by glaze when resolving dependent colors
  * with `contrast`.
  */
+type LinearRgb = [number, number, number];
 type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 type MinContrast$1 = number | ContrastPreset;
 interface FindLightnessForContrastOptions {
@@ -42,6 +43,39 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * against a base color, staying as close to `preferredLightness` as possible.
  */
 declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
+interface FindValueForMixContrastOptions {
+  /** Preferred mix parameter (0–1). */
+  preferredValue: number;
+  /** Base color as linear sRGB. */
+  baseLinearRgb: LinearRgb;
+  /** Target color as linear sRGB. */
+  targetLinearRgb: LinearRgb;
+  /** WCAG contrast target. */
+  contrast: MinContrast$1;
+  /**
+   * Compute the luminance of the mixed color at parameter t.
+   * For opaque: luminance of OKHSL-interpolated color.
+   * For transparent: luminance of alpha-composited color over base.
+   */
+  luminanceAtValue: (t: number) => number;
+  /** Convergence threshold. Default: 1e-4. */
+  epsilon?: number;
+  /** Maximum binary-search iterations per branch. Default: 20. */
+  maxIterations?: number;
+}
+interface FindValueForMixContrastResult {
+  /** Chosen mix parameter (0–1). */
+  value: number;
+  /** Achieved WCAG contrast ratio. */
+  contrast: number;
+  /** Whether the target was reached. */
+  met: boolean;
+}
+/**
+ * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
+ * target against a base color, staying as close to `preferredValue` as possible.
+ */
+declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
 //#endregion
 //#region src/types.d.ts
 /** A value or [normal, high-contrast] pair. */
@@ -144,7 +178,41 @@ interface ShadowColorDef {
   /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
   tuning?: ShadowTuning;
 }
-type ColorDef = RegularColorDef | ShadowColorDef;
+interface MixColorDef {
+  type: 'mix';
+  /** Background/base color name — the "from" color. */
+  base: string;
+  /** Target color name — the "to" color to mix toward. */
+  target: string;
+  /**
+   * Mix ratio 0–100 (0 = pure base, 100 = pure target).
+   * In 'transparent' blend mode, this controls the opacity of the target.
+   * Supports [normal, highContrast] pair.
+   */
+  value: HCPair<number>;
+  /**
+   * Blending mode. Default: 'opaque'.
+   * - 'opaque': produces a solid color by interpolating base and target.
+   * - 'transparent': produces the target color with alpha = value/100.
+   */
+  blend?: 'opaque' | 'transparent';
+  /**
+   * Interpolation color space for opaque blending. Default: 'okhsl'.
+   * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
+   * - 'srgb': linear sRGB interpolation, matches browser compositing.
+   *
+   * Ignored for 'transparent' blend (always composites in linear sRGB).
+   */
+  space?: 'okhsl' | 'srgb';
+  /**
+   * Minimum WCAG contrast between the base and the resulting color.
+   * In 'opaque' mode, adjusts the mix ratio to meet contrast.
+   * In 'transparent' mode, adjusts opacity to meet contrast against the composite.
+   * Supports [normal, highContrast] pair.
+   */
+  contrast?: HCPair<MinContrast>;
+}
+type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
 /** Resolved color for a single scheme variant. */
 interface ResolvedColorVariant {
@@ -394,6 +462,10 @@ declare namespace glaze {
  * computation for WCAG 2 contrast calculations, and multi-format output
  * (okhsl, rgb, hsl, oklch).
  */
+/**
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+ */
+declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
 /**
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
  * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
@@ -413,9 +485,11 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
  */
 declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
 /**
- * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+ * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
+ * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
+ * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
  */
-declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
+declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
 /**
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
@@ -447,5 +521,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
  */
 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 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 };
+export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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 MixColorDef, type OkhslColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -6,6 +6,7 @@
  * against a base color. Used by glaze when resolving dependent colors
  * with `contrast`.
  */
+type LinearRgb = [number, number, number];
 type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 type MinContrast$1 = number | ContrastPreset;
 interface FindLightnessForContrastOptions {
@@ -42,6 +43,39 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * against a base color, staying as close to `preferredLightness` as possible.
  */
 declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
+interface FindValueForMixContrastOptions {
+  /** Preferred mix parameter (0–1). */
+  preferredValue: number;
+  /** Base color as linear sRGB. */
+  baseLinearRgb: LinearRgb;
+  /** Target color as linear sRGB. */
+  targetLinearRgb: LinearRgb;
+  /** WCAG contrast target. */
+  contrast: MinContrast$1;
+  /**
+   * Compute the luminance of the mixed color at parameter t.
+   * For opaque: luminance of OKHSL-interpolated color.
+   * For transparent: luminance of alpha-composited color over base.
+   */
+  luminanceAtValue: (t: number) => number;
+  /** Convergence threshold. Default: 1e-4. */
+  epsilon?: number;
+  /** Maximum binary-search iterations per branch. Default: 20. */
+  maxIterations?: number;
+}
+interface FindValueForMixContrastResult {
+  /** Chosen mix parameter (0–1). */
+  value: number;
+  /** Achieved WCAG contrast ratio. */
+  contrast: number;
+  /** Whether the target was reached. */
+  met: boolean;
+}
+/**
+ * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
+ * target against a base color, staying as close to `preferredValue` as possible.
+ */
+declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
 //#endregion
 //#region src/types.d.ts
 /** A value or [normal, high-contrast] pair. */
@@ -144,7 +178,41 @@ interface ShadowColorDef {
   /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
   tuning?: ShadowTuning;
 }
-type ColorDef = RegularColorDef | ShadowColorDef;
+interface MixColorDef {
+  type: 'mix';
+  /** Background/base color name — the "from" color. */
+  base: string;
+  /** Target color name — the "to" color to mix toward. */
+  target: string;
+  /**
+   * Mix ratio 0–100 (0 = pure base, 100 = pure target).
+   * In 'transparent' blend mode, this controls the opacity of the target.
+   * Supports [normal, highContrast] pair.
+   */
+  value: HCPair<number>;
+  /**
+   * Blending mode. Default: 'opaque'.
+   * - 'opaque': produces a solid color by interpolating base and target.
+   * - 'transparent': produces the target color with alpha = value/100.
+   */
+  blend?: 'opaque' | 'transparent';
+  /**
+   * Interpolation color space for opaque blending. Default: 'okhsl'.
+   * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
+   * - 'srgb': linear sRGB interpolation, matches browser compositing.
+   *
+   * Ignored for 'transparent' blend (always composites in linear sRGB).
+   */
+  space?: 'okhsl' | 'srgb';
+  /**
+   * Minimum WCAG contrast between the base and the resulting color.
+   * In 'opaque' mode, adjusts the mix ratio to meet contrast.
+   * In 'transparent' mode, adjusts opacity to meet contrast against the composite.
+   * Supports [normal, highContrast] pair.
+   */
+  contrast?: HCPair<MinContrast>;
+}
+type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
 /** Resolved color for a single scheme variant. */
 interface ResolvedColorVariant {
@@ -394,6 +462,10 @@ declare namespace glaze {
  * computation for WCAG 2 contrast calculations, and multi-format output
  * (okhsl, rgb, hsl, oklch).
  */
+/**
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+ */
+declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
 /**
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
  * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
@@ -413,9 +485,11 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
  */
 declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
 /**
- * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+ * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
+ * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
+ * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
  */
-declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
+declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
 /**
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
@@ -447,5 +521,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
  */
 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 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 };
+export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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 MixColorDef, type OkhslColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -79,8 +79,8 @@ const OKLab_to_linear_sRGB_coefficients = [
 		.73956515,
 		-.45954404,
 		.08285427,
-		.12541073,
-		-.14503204
+		.1254107,
+		.14503204
 	]],
 	[[.13110757611180954, 1.813339709266608], [
 		1.35733652,
@@ -252,10 +252,9 @@ const getCs = (L, a, b, cusp) => {
 	];
 };
 /**
-* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
-* Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
+* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
 */
-function okhslToLinearSrgb(h, s, l) {
+function okhslToOklab(h, s, l) {
 	const L = toeInv(l);
 	let a = 0;
 	let b = 0;
@@ -282,11 +281,18 @@ function okhslToLinearSrgb(h, s, l) {
 		a = c * a_;
 		b = c * b_;
 	}
-	return OKLabToLinearSRGB([
+	return [
 		L,
 		a,
 		b
-	]);
+	];
+}
+/**
+* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
+* Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
+*/
+function okhslToLinearSrgb(h, s, l) {
+	return OKLabToLinearSRGB(okhslToOklab(h, s, l));
 }
 /**
 * Compute relative luminance Y from linear sRGB channels.
@@ -325,40 +331,15 @@ function okhslToSrgb(h, s, l) {
 	];
 }
 /**
-* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+* Compute WCAG 2 relative luminance from linear sRGB, matching the browser
+* rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
+* This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
 */
-function okhslToOklab(h, s, l) {
-	const L = toeInv(l);
-	let a = 0;
-	let b = 0;
-	const hNorm = constrainAngle(h) / 360;
-	if (L !== 0 && L !== 1 && s !== 0) {
-		const a_ = Math.cos(TAU * hNorm);
-		const b_ = Math.sin(TAU * hNorm);
-		const [c0, cMid, cMax] = getCs(L, a_, b_, findCuspOKLCH(a_, b_));
-		const mid = .8;
-		const midInv = 1.25;
-		let t, k0, k1, k2;
-		if (s < mid) {
-			t = midInv * s;
-			k0 = 0;
-			k1 = mid * c0;
-			k2 = 1 - k1 / cMid;
-		} else {
-			t = 5 * (s - .8);
-			k0 = cMid;
-			k1 = .2 * cMid ** 2 * 1.25 ** 2 / c0;
-			k2 = 1 - k1 / (cMax - cMid);
-		}
-		const c = k0 + t * k1 / (1 - k2 * t);
-		a = c * a_;
-		b = c * b_;
-	}
-	return [
-		L,
-		a,
-		b
-	];
+function gamutClampedLuminance(linearRgb) {
+	const r = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0]))));
+	const g = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1]))));
+	const b = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2]))));
+	return .2126 * r + .7152 * g + .0722 * b;
 }
 const linearSrgbToOklab = (rgb) => {
 	return transform(cbrt3(transform(rgb, linear_sRGB_to_LMS_M)), LMS_to_OKLab_M);
@@ -511,17 +492,6 @@ function resolveMinContrast(value) {
 const CACHE_SIZE = 512;
 const luminanceCache = /* @__PURE__ */ new Map();
 const cacheOrder = [];
-/**
-* Compute WCAG 2 relative luminance from linear sRGB, matching the browser
-* rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
-* This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
-*/
-function gamutClampedLuminance(linearRgb) {
-	const r = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0]))));
-	const g = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1]))));
-	const b = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2]))));
-	return .2126 * r + .7152 * g + .0722 * b;
-}
 function cachedLuminance(h, s, l) {
 	const lRounded = Math.round(l * 1e4) / 1e4;
 	const key = `${h}|${s}|${lRounded}`;
@@ -699,6 +669,135 @@ function findLightnessForContrast(options) {
 	candidates.sort((a, b) => b.contrast - a.contrast);
 	return candidates[0];
 }
+/**
+* Binary-search one branch [lo, hi] for the nearest passing mix value
+* to `preferred`.
+*/
+function searchMixBranch(lo, hi, yBase, target, epsilon, maxIter, preferred, luminanceAt) {
+	const crLo = contrastRatioFromLuminance(luminanceAt(lo), yBase);
+	const crHi = contrastRatioFromLuminance(luminanceAt(hi), yBase);
+	if (crLo < target && crHi < target) {
+		if (crLo >= crHi) return {
+			lightness: lo,
+			contrast: crLo,
+			met: false
+		};
+		return {
+			lightness: hi,
+			contrast: crHi,
+			met: false
+		};
+	}
+	let low = lo;
+	let high = hi;
+	for (let i = 0; i < maxIter; i++) {
+		if (high - low < epsilon) break;
+		const mid = (low + high) / 2;
+		if (contrastRatioFromLuminance(luminanceAt(mid), yBase) >= target) if (mid < preferred) low = mid;
+		else high = mid;
+		else if (mid < preferred) high = mid;
+		else low = mid;
+	}
+	const crLow = contrastRatioFromLuminance(luminanceAt(low), yBase);
+	const crHigh = contrastRatioFromLuminance(luminanceAt(high), yBase);
+	const lowPasses = crLow >= target;
+	const highPasses = crHigh >= target;
+	if (lowPasses && highPasses) {
+		if (Math.abs(low - preferred) <= Math.abs(high - preferred)) return {
+			lightness: low,
+			contrast: crLow,
+			met: true
+		};
+		return {
+			lightness: high,
+			contrast: crHigh,
+			met: true
+		};
+	}
+	if (lowPasses) return {
+		lightness: low,
+		contrast: crLow,
+		met: true
+	};
+	if (highPasses) return {
+		lightness: high,
+		contrast: crHigh,
+		met: true
+	};
+	return crLow >= crHigh ? {
+		lightness: low,
+		contrast: crLow,
+		met: false
+	} : {
+		lightness: high,
+		contrast: crHigh,
+		met: false
+	};
+}
+/**
+* Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
+* target against a base color, staying as close to `preferredValue` as possible.
+*/
+function findValueForMixContrast(options) {
+	const { preferredValue, baseLinearRgb, contrast: contrastInput, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
+	const target = resolveMinContrast(contrastInput);
+	const searchTarget = target + .01;
+	const yBase = gamutClampedLuminance(baseLinearRgb);
+	const crPref = contrastRatioFromLuminance(luminanceAtValue(preferredValue), yBase);
+	if (crPref >= searchTarget) return {
+		value: preferredValue,
+		contrast: crPref,
+		met: true
+	};
+	const darkerResult = preferredValue > 0 ? searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
+	const lighterResult = preferredValue < 1 ? searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
+	if (darkerResult) darkerResult.met = darkerResult.contrast >= target;
+	if (lighterResult) lighterResult.met = lighterResult.contrast >= target;
+	const darkerPasses = darkerResult?.met ?? false;
+	const lighterPasses = lighterResult?.met ?? false;
+	if (darkerPasses && lighterPasses) {
+		if (Math.abs(darkerResult.lightness - preferredValue) <= Math.abs(lighterResult.lightness - preferredValue)) return {
+			value: darkerResult.lightness,
+			contrast: darkerResult.contrast,
+			met: true
+		};
+		return {
+			value: lighterResult.lightness,
+			contrast: lighterResult.contrast,
+			met: true
+		};
+	}
+	if (darkerPasses) return {
+		value: darkerResult.lightness,
+		contrast: darkerResult.contrast,
+		met: true
+	};
+	if (lighterPasses) return {
+		value: lighterResult.lightness,
+		contrast: lighterResult.contrast,
+		met: true
+	};
+	const candidates = [];
+	if (darkerResult) candidates.push({
+		...darkerResult,
+		branch: "lower"
+	});
+	if (lighterResult) candidates.push({
+		...lighterResult,
+		branch: "upper"
+	});
+	if (candidates.length === 0) return {
+		value: preferredValue,
+		contrast: crPref,
+		met: false
+	};
+	candidates.sort((a, b) => b.contrast - a.contrast);
+	return {
+		value: candidates[0].lightness,
+		contrast: candidates[0].contrast,
+		met: candidates[0].met
+	};
+}
 
 //#endregion
 //#region src/glaze.ts
@@ -730,6 +829,9 @@ function pairHC(p) {
 function isShadowDef(def) {
 	return def.type === "shadow";
 }
+function isMixDef(def) {
+	return def.type === "mix";
+}
 const DEFAULT_SHADOW_TUNING = {
 	saturationFactor: .18,
 	maxSaturation: .25,
@@ -797,6 +899,13 @@ function validateColorDefs(defs) {
 			}
 			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.`);
+			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".`);
@@ -815,6 +924,9 @@ function validateColorDefs(defs) {
 		if (isShadowDef(def)) {
 			dfs(def.bg);
 			if (def.fg) dfs(def.fg);
+		} else if (isMixDef(def)) {
+			dfs(def.base);
+			dfs(def.target);
 		} else {
 			const regDef = def;
 			if (regDef.base) dfs(regDef.base);
@@ -834,6 +946,9 @@ function topoSort(defs) {
 		if (isShadowDef(def)) {
 			visit(def.bg);
 			if (def.fg) visit(def.fg);
+		} else if (isMixDef(def)) {
+			visit(def.base);
+			visit(def.target);
 		} else {
 			const regDef = def;
 			if (regDef.base) visit(regDef.base);
@@ -949,6 +1064,7 @@ function getSchemeVariant(color, isDark, isHighContrast) {
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
+	if (isMixDef(def)) return resolveMixForScheme(def, ctx, isDark, isHighContrast);
 	const regDef = def;
 	const mode = regDef.mode ?? "auto";
 	const isRoot = isAbsoluteLightness(regDef.lightness) && !regDef.base;
@@ -994,6 +1110,83 @@ function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
 	const tuning = resolveShadowTuning(def.tuning);
 	return computeShadow(bgVariant, fgVariant, intensity, tuning);
 }
+function variantToLinearRgb(v) {
+	return okhslToLinearSrgb(v.h, v.s, v.l);
+}
+/**
+* Resolve hue for OKHSL mixing, handling achromatic colors.
+* When one color has no saturation, its hue is meaningless —
+* use the hue from the color that has saturation (matches CSS
+* color-mix "missing component" behavior).
+*/
+function mixHue(base, target, t) {
+	const SAT_EPSILON = 1e-6;
+	const baseHasSat = base.s > SAT_EPSILON;
+	const targetHasSat = target.s > SAT_EPSILON;
+	if (baseHasSat && targetHasSat) return circularLerp(base.h, target.h, t);
+	if (targetHasSat) return target.h;
+	return base.h;
+}
+function linearSrgbLerp(base, target, t) {
+	return [
+		base[0] + (target[0] - base[0]) * t,
+		base[1] + (target[1] - base[1]) * t,
+		base[2] + (target[2] - base[2]) * t
+	];
+}
+function linearRgbToVariant(rgb) {
+	const [h, s, l] = srgbToOkhsl([
+		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[0]))),
+		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[1]))),
+		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[2])))
+	]);
+	return {
+		h,
+		s,
+		l,
+		alpha: 1
+	};
+}
+function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
+	const baseResolved = ctx.resolved.get(def.base);
+	const targetResolved = ctx.resolved.get(def.target);
+	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
+	const targetVariant = getSchemeVariant(targetResolved, isDark, isHighContrast);
+	let t = clamp(isHighContrast ? pairHC(def.value) : pairNormal(def.value), 0, 100) / 100;
+	const blend = def.blend ?? "opaque";
+	const space = def.space ?? "okhsl";
+	const baseLinear = variantToLinearRgb(baseVariant);
+	const targetLinear = variantToLinearRgb(targetVariant);
+	if (def.contrast !== void 0) {
+		const minCr = isHighContrast ? pairHC(def.contrast) : pairNormal(def.contrast);
+		let luminanceAt;
+		if (blend === "transparent") luminanceAt = (v) => gamutClampedLuminance(linearSrgbLerp(baseLinear, targetLinear, v));
+		else if (space === "srgb") luminanceAt = (v) => gamutClampedLuminance(linearSrgbLerp(baseLinear, targetLinear, v));
+		else luminanceAt = (v) => {
+			return gamutClampedLuminance(okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v));
+		};
+		t = findValueForMixContrast({
+			preferredValue: t,
+			baseLinearRgb: baseLinear,
+			targetLinearRgb: targetLinear,
+			contrast: minCr,
+			luminanceAtValue: luminanceAt
+		}).value;
+	}
+	if (blend === "transparent") return {
+		h: targetVariant.h,
+		s: targetVariant.s,
+		l: targetVariant.l,
+		alpha: clamp(t, 0, 1)
+	};
+	if (space === "srgb") return linearRgbToVariant(linearSrgbLerp(baseLinear, targetLinear, t));
+	return {
+		h: mixHue(baseVariant, targetVariant, t),
+		s: clamp(baseVariant.s + (targetVariant.s - baseVariant.s) * t, 0, 1),
+		l: clamp(baseVariant.l + (targetVariant.l - baseVariant.l) * t, 0, 1),
+		alpha: 1
+	};
+}
 function resolveAllColors(hue, saturation, defs) {
 	validateColorDefs(defs);
 	const order = topoSort(defs);
@@ -1004,7 +1197,8 @@ function resolveAllColors(hue, saturation, defs) {
 		resolved: /* @__PURE__ */ new Map()
 	};
 	function defMode(def) {
-		return isShadowDef(def) ? void 0 : def.mode ?? "auto";
+		if (isShadowDef(def) || isMixDef(def)) return void 0;
+		return def.mode ?? "auto";
 	}
 	const lightMap = /* @__PURE__ */ new Map();
 	for (const name of order) {
@@ -1442,5 +1636,5 @@ glaze.resetConfig = function resetConfig() {
 };
 
 //#endregion
-export { contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.mjs.map