@tenphi/glaze 1.4.0 → 1.5.0

package/dist/index.d.cts

@@ -234,9 +234,10 @@ interface GlazeOutputModes {
   /**
    * Include high-contrast variants (both light-HC and dark-HC). Default: false.
    *
-   * Inert while a global `contrastLevel` is set: a manual level has no separate
-   * high-contrast tier, so this reads as "emit high-contrast variants when
-   * contrast is automatic".
+   * Independent of `contrastLevel` — the level positions the normal variants
+   * while these stay the true high-contrast resolution, so the two compose. The
+   * exception is a global level of 100, where the normal variants already *are*
+   * the high-contrast ones: the tier would duplicate them and is dropped.
    * @see GlazeConfig.contrastLevel
    */
   highContrast?: boolean;
@@ -572,15 +573,15 @@ interface GlazeConfig {
   shadowTuning?: ShadowTuning;
   /**
    * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
-   * contrast (`100`), or `'auto'` (the default) to keep the two-tier
-   * normal + high-contrast model.
+   * contrast (`100`), or `'auto'` (the default) to take the authored normal
+   * entries as-is.
    *
-   * With a number, Glaze resolves the `light` / `dark` variants *at* that
-   * level and stops emitting a separate high-contrast tier:
-   * `lightContrast` / `darkContrast` mirror their normal counterparts and
-   * `modes.highContrast` defaults to `false`. Level `0` is therefore "normal
-   * contrast, no high-contrast tier"; `100` is "the high-contrast scheme as
-   * the only scheme".
+   * With a number, Glaze resolves the `light` / `dark` variants *at* that level.
+   * That is all it does: `lightContrast` / `darkContrast` stay the true
+   * high-contrast resolution at every level, and `modes.highContrast` alone
+   * decides whether they are emitted. Level `0` therefore reproduces `'auto'`
+   * bit for bit. At `100` the normal variants *are* the high-contrast ones, so a
+   * separate tier would duplicate them and a global level of 100 drops it.
    *
    * The level interpolates all three things that make high contrast differ:
    * authored `[normal, highContrast]` pairs, the tone-window widening, and
@@ -630,8 +631,8 @@ interface GlazeConfigResolved {
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
   /**
-   * Manual contrast level (0–100), or `'auto'` for the two-tier
-   * normal + high-contrast model.
+   * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
+   * the authored normal entries as-is.
    * @see GlazeConfig.contrastLevel
    */
   contrastLevel: number | 'auto';
@@ -661,8 +662,10 @@ interface GlazeConfigOverride {
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
   /**
-   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out
-   * of a global level and keep the two-tier normal + high-contrast model.
+   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out of a
+   * global level and take the authored normal entries as-is. Either way the
+   * instance keeps its high-contrast tier; a per-instance level never changes
+   * which modes are emitted.
    *
    * Only an instance-authored level is frozen into `.export()` snapshots — a
    * level inherited from the global config is treated as a live preference and

package/dist/index.d.mts

@@ -234,9 +234,10 @@ interface GlazeOutputModes {
   /**
    * Include high-contrast variants (both light-HC and dark-HC). Default: false.
    *
-   * Inert while a global `contrastLevel` is set: a manual level has no separate
-   * high-contrast tier, so this reads as "emit high-contrast variants when
-   * contrast is automatic".
+   * Independent of `contrastLevel` — the level positions the normal variants
+   * while these stay the true high-contrast resolution, so the two compose. The
+   * exception is a global level of 100, where the normal variants already *are*
+   * the high-contrast ones: the tier would duplicate them and is dropped.
    * @see GlazeConfig.contrastLevel
    */
   highContrast?: boolean;
@@ -572,15 +573,15 @@ interface GlazeConfig {
   shadowTuning?: ShadowTuning;
   /**
    * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
-   * contrast (`100`), or `'auto'` (the default) to keep the two-tier
-   * normal + high-contrast model.
+   * contrast (`100`), or `'auto'` (the default) to take the authored normal
+   * entries as-is.
    *
-   * With a number, Glaze resolves the `light` / `dark` variants *at* that
-   * level and stops emitting a separate high-contrast tier:
-   * `lightContrast` / `darkContrast` mirror their normal counterparts and
-   * `modes.highContrast` defaults to `false`. Level `0` is therefore "normal
-   * contrast, no high-contrast tier"; `100` is "the high-contrast scheme as
-   * the only scheme".
+   * With a number, Glaze resolves the `light` / `dark` variants *at* that level.
+   * That is all it does: `lightContrast` / `darkContrast` stay the true
+   * high-contrast resolution at every level, and `modes.highContrast` alone
+   * decides whether they are emitted. Level `0` therefore reproduces `'auto'`
+   * bit for bit. At `100` the normal variants *are* the high-contrast ones, so a
+   * separate tier would duplicate them and a global level of 100 drops it.
    *
    * The level interpolates all three things that make high contrast differ:
    * authored `[normal, highContrast]` pairs, the tone-window widening, and
@@ -630,8 +631,8 @@ interface GlazeConfigResolved {
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
   /**
-   * Manual contrast level (0–100), or `'auto'` for the two-tier
-   * normal + high-contrast model.
+   * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
+   * the authored normal entries as-is.
    * @see GlazeConfig.contrastLevel
    */
   contrastLevel: number | 'auto';
@@ -661,8 +662,10 @@ interface GlazeConfigOverride {
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
   /**
-   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out
-   * of a global level and keep the two-tier normal + high-contrast model.
+   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out of a
+   * global level and take the authored normal entries as-is. Either way the
+   * instance keeps its high-contrast tier; a per-instance level never changes
+   * which modes are emitted.
    *
    * Only an instance-authored level is frozen into `.export()` snapshots — a
    * level inherited from the global config is treated as a live preference and

package/dist/index.mjs

@@ -904,10 +904,14 @@ function levelFraction(level) {
 }
 /**
 * Manual-contrast blend fraction (0–1) for a resolved config, or `undefined`
-* in `'auto'` mode (the two-tier normal + high-contrast model).
+* in `'auto'` mode, where the normal variants take the authored normal entries
+* as-is.
 *
-* Note `contrastLevel: 0` yields `0`, not `undefined`: "pinned to normal
-* contrast with no high-contrast tier" is a distinct state from `'auto'`.
+* Note `contrastLevel: 0` yields `0`, not `undefined`. The two select different
+* branches, and an authored `0` is a slider position that `.export()` freezes
+* where an absent level is not — but they are not an *output* distinction: at
+* fraction 0 every interpolation returns its normal entry verbatim, so level 0
+* reproduces `'auto'` bit for bit.
 */
 function contrastFraction(config) {
 	const level = config.contrastLevel;
@@ -915,6 +919,20 @@ function contrastFraction(config) {
 	return levelFraction(level);
 }
 /**
+* Whether the high-contrast variants are exact duplicates of the normal ones —
+* true only at `contrastLevel: 100`, where the normal passes already resolve at
+* full contrast.
+*
+* The level otherwise says nothing about high contrast: it positions the normal
+* variants, while `lightContrast` / `darkContrast` stay the true high-contrast
+* resolution at every level. This predicate marks the one level where that tier
+* carries no new information, so callers can skip the two high-contrast passes,
+* their drift checks, and the redundant output tier.
+*/
+function hcMirrorsNormal(config) {
+	return contrastFraction(config) === 1;
+}
+/**
 * A numeric HC pair at a blend fraction (shadow `intensity`, mix `value`).
 *
 * The endpoints return the authored entry *by identity* rather than through
@@ -2274,12 +2292,14 @@ function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase
 * Color resolution engine.
 *
 * Runs the four-pass solver (light → light-HC → dark → dark-HC) that
-* turns a `ColorMap` into a fully resolved `ResolvedColor` per name — or,
-* under a manual `contrastLevel`, a two-pass solver (light → dark) whose
-* authored HC pairs, tone window, and contrast targets are interpolated at
-* that level and whose high-contrast slots mirror the normal ones.
-* Owns the per-scheme resolve helpers for regular, shadow, and mix
-* color defs.
+* turns a `ColorMap` into a fully resolved `ResolvedColor` per name. A manual
+* `contrastLevel` interpolates the authored HC pairs, tone window, and contrast
+* targets at that level for the two *normal* passes only; the high-contrast
+* 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.
 *
 * Variants are stored in OKHST: `h` / `s` are OKHSL hue/saturation and
 * `t` is the canonical contrast-uniform tone (0–1, reference eps). The
@@ -2536,7 +2556,7 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, channels,
 			flip,
 			pastel
 		};
-		const level = contrastFraction(ctx.config);
+		const level = isHighContrast ? void 0 : contrastFraction(config);
 		let preferInitial = false;
 		if (level !== void 0 && level > 0 && level < 1) {
 			initialDirection = findToneForContrast({
@@ -2725,10 +2745,11 @@ function seedField(order, ctx, field, source) {
 * 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` only the two emitted variants are checked
-* (the high-contrast slots are mirrors), and the spec is resolved at the level
-* so the check measures the output against the target it was actually solved
-* for.
+* 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
+* level 100 the high-contrast slots are mirrors and are skipped: the normal
+* schemes already carry that check, and repeating it would emit a byte-identical
+* advisory under a different scheme label, which dedupes as a separate key.
 */
 function verifyContrastDrift(order, defs, result, config) {
 	const roles = /* @__PURE__ */ new Map();
@@ -2763,9 +2784,9 @@ function verifyContrastDrift(order, defs, result, config) {
 				field: "darkContrast"
 			}
 		];
-		const manual = contrastFraction(config) !== void 0;
+		const mirrored = hcMirrorsNormal(config);
 		for (const s of schemes) {
-			if (manual && s.isHighContrast) continue;
+			if (mirrored && s.isHighContrast) continue;
 			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast, config, polarity);
 			const cVariant = color[s.field];
 			const bVariant = base[s.field];
@@ -2790,10 +2811,10 @@ function resolveAllColors(seed, defs, config, externalBases) {
 		roles: /* @__PURE__ */ new Map()
 	};
 	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
-	const manual = contrastFraction(config) !== void 0;
+	const mirrored = hcMirrorsNormal(config);
 	const lightMap = runPass(order, defs, ctx, false, false, "light");
 	let lightHCMap = lightMap;
-	if (!manual) {
+	if (!mirrored) {
 		seedField(order, ctx, "lightContrast", lightMap);
 		lightHCMap = runPass(order, defs, ctx, false, true, "lightContrast");
 	}
@@ -2801,7 +2822,7 @@ function resolveAllColors(seed, defs, config, externalBases) {
 	seedField(order, ctx, "darkContrast", lightHCMap);
 	const darkMap = runPass(order, defs, ctx, true, false, "dark");
 	let darkHCMap = darkMap;
-	if (!manual) {
+	if (!mirrored) {
 		seedField(order, ctx, "darkContrast", darkMap);
 		darkHCMap = runPass(order, defs, ctx, true, true, "darkContrast");
 	}
@@ -3035,23 +3056,28 @@ function formatColorValue(v, format, pastel, huePlan) {
 /**
 * Resolve the effective output modes for an export.
 *
-* A global manual `contrastLevel` turns off high-contrast output outright: the
-* level *is* the contrast preference, so a separate high-contrast tier has no
-* meaning alongside it. `modes.highContrast` therefore reads as "emit a separate
-* high-contrast set **when** contrast is automatic" — it goes inert under a
-* manual level rather than fighting it, and silently, since switching a
-* preference from auto to manual is normal use and not a mistake to report.
+* `modes.highContrast` and `contrastLevel` are independent: the level positions
+* the normal variants, the high-contrast tier stays the true high-contrast
+* resolution, and the two compose — a slider raises the baseline while a
+* `prefers-contrast: more` block still escalates on top of it.
+*
+* The one exception is a **global** level of 100, where the normal variants
+* already *are* the high-contrast ones. The tier would be an exact duplicate, so
+* it is dropped and a single light/dark set is emitted — including against an
+* explicit `highContrast: true` override, which has nothing different left to
+* ask for.
 *
 * A level set on a single theme or token does not change which modes are
-* emitted: sibling themes in a palette may still have a real high-contrast
-* tier, and the manual one correctly reports its own resolved values there —
-* the alternative would drop its colors from that tier entirely.
+* emitted: `modes` is global-only, and a palette must not have one sibling
+* collapse the shared token structure. A per-instance level of 100 therefore
+* still reports into the tier, with values equal to its own normal ones.
 */
 function resolveModes(override) {
 	const cfg = getConfig();
+	const highContrast = override?.highContrast ?? cfg.modes.highContrast;
 	return {
 		dark: override?.dark ?? cfg.modes.dark,
-		highContrast: contrastFraction(cfg) !== void 0 ? false : override?.highContrast ?? cfg.modes.highContrast
+		highContrast: highContrast && !hcMirrorsNormal(cfg)
 	};
 }
 function buildTokenMap(resolved, prefix, states, modes, format = "oklch", pastel = false, channelCtx) {