@tenphi/glaze 0.0.0-snapshot.94c4efb → 0.0.0-snapshot.9a14acf

package/AGENTS.md

@@ -0,0 +1,132 @@
+# AGENTS.md — @tenphi/glaze
+
+## Package Overview
+
+- **Package:** `@tenphi/glaze`
+- **Repository:** [https://github.com/tenphi/glaze](https://github.com/tenphi/glaze)
+- **Description:** Zero-dependency color theme generator built on OKHST (OKHSL with a contrast-uniform **tone** axis), with WCAG + APCA contrast solving for light, dark, and high-contrast schemes.
+- **Runtime:** Node >= 20, browsers, edge. Pure math, no I/O.
+- **Output formats:** ESM + CJS, with full `.d.ts`.
+
+## Project Structure
+
+```
+glaze/
+├── src/                       Source
+├── docs/                      Long-form docs (okhst / api / methodology / migration)
+├── assets/                    Logo + brand assets
+├── scripts/                   Repo helpers
+├── README.md                  Compact intro
+├── AGENTS.md                  This file
+├── CHANGELOG.md               Auto-generated by Changesets
+├── package.json
+├── tsconfig.json
+├── tsdown.config.ts           Build config
+├── vitest.config.ts           Test config
+└── eslint.config.js
+```
+
+### `src/` files
+
+| File | Description |
+|---|---|
+| [src/index.ts](src/index.ts) | Public barrel; re-exports `glaze`, every public type, the contrast-solver utilities, and the OKHSL/sRGB/OKLab math helpers. |
+| [src/glaze.ts](src/glaze.ts) | `glaze()` factory + attached statics: `palette`, `paletteFrom`, `color`, `colorFrom`, `themeFrom`, `from` (alias), `fromHex`, `fromRgb`, `shadow`, `format`, `configure`, `getConfig`, `resetConfig`, `isThemeExport` / `isColorTokenExport` / `isPaletteExport`. Thin wiring layer over the focused modules below. |
+| [src/theme.ts](src/theme.ts) | Single-theme factory (`createTheme`). Owns the mutable `ColorMap`, the `resolve()` cache (versioned against `getConfigVersion()`), and the `tokens` / `tasty` / `json` / `css` / `extend` / `export` methods. `export(override?)` deep-clones defs and freezes effective config with `kind`/`version`. |
+| [src/palette.ts](src/palette.ts) | Multi-theme composition (`createPalette` / `createPaletteFromExport`). Shared per-theme driver `buildPaletteOutput` handles prefix resolution, primary duplication, collision filtering. Authoring: `export(override?)`, `theme` / `themes` / `list` / `primary`. |
+| [src/color-token.ts](src/color-token.ts) | Standalone `glaze.color()` tokens. Parses values through `color-value.ts`; owns the structured-input validator, the two factory paths, sparse local config + live resolve, and the JSON-safe export / `glaze.colorFrom` rehydrate round-trip. |
+| [src/color-value.ts](src/color-value.ts) | `GlazeColorValue` parsing + validation: hex (3/6/8), the `rgb()` / `hsl()` / `okhsl()` / `okhst()` / `oklch()` functions, and the four value-object shapes, all normalized to OKHSL by `extractOkhslFromValue`. Split out of `color-token.ts` so the resolver can reach it for a theme color's `from` without closing an import cycle. Leaf module — depends only on the color math. |
+| [src/serialize.ts](src/serialize.ts) | Authoring-export helpers: `GLAZE_EXPORT_VERSION`, `assertExportKind` / `assertExportVersion`, and `isThemeExport` / `isColorTokenExport` / `isPaletteExport` type guards. |
+| [src/resolver.ts](src/resolver.ts) | Four-pass solver (light → light-HC → dark → dark-HC), dropping to two-pass (light → dark) with mirrored HC slots only at `contrastLevel: 100`, where the normal passes already are the HC ones (`hcMirrorsNormal`). Under any other manual level `passTone` / `passNumber` / `resolveContrastSpec` feed interpolated inputs into the two *normal* passes and a probe solve at the nearer endpoint pins which side of its base a contrast-solved color sits on; the HC passes bypass the level and the probe entirely, so the HC tier is bit-identical to `'auto'`. Stores canonical tone (`t`) in variants; per-scheme branches for regular, shadow, and mix defs; integrates the contrast solver, and the OKHST tone helpers. `resolveChannels` owns per-scheme hue/saturation (incl. the `darkHue` / `darkSaturation` seed + def overrides, the `darkDesaturation` bypass, and the absolute hue/saturation a `from` color carries in place of the seed factor) and feeds both the emitted variant and the contrast solver. `configForColor` gives a `from` color a local `lightTone: false` so its light variant reproduces the authored value. Converts to/from OKHSL lightness only at the mix/shadow edges. Pre-seeds externally-resolved bases for `glaze.color({ base })`. |
+| [src/okhst.ts](src/okhst.ts) | The OKHST tone layer. `REF_EPS`, tone↔lightness transfers (`toTone`/`fromTone`, `toneFromY`/`yFromTone`), OKHST↔OKHSL conversions, `variantToOkhsl` (tone→lightness at render), `normalizeToneWindow` (`[lo,hi]` / `{lo,hi,eps}` / `false` → `{lo,hi,eps}`), `mapToneForScheme` (scheme inversion + window remap, HC bypass), `mapSaturationDark` (the `darkDesaturation` reducer the resolver skips when a dark saturation is authored), and `schemeToneRange` for the solver. `activeWindow` owns the HC window bypass and its continuous form under `contrastLevel`. Only tone adapts here — hue/saturation are the resolver's business. |
+| [src/contrast-solver.ts](src/contrast-solver.ts) | Tone-based binary-search solver for WCAG **and** APCA. Public API: `findToneForContrast` (incl. the `preferInitial` tie-break the manual level uses on its normal passes to keep a color's side stable), `findValueForMixContrast`, `resolveContrastForMode`, `resolveContrastForLevel` (both ends resolved, target interpolated for a manual `contrastLevel`; throws on a metric switch), `contrastMetricOf`, `resolveMinContrast`, `apcaContrast`. Closed-form WCAG seed + tone search. |
+| [src/shadow.ts](src/shadow.ts) | Shadow + mix def predicates (`isShadowDef`, `isMixDef`), default `ShadowTuning`, tuning merge, the actual `computeShadow` math (hue blend, saturation cap, lightness clamp, `tanh` alpha curve) operating on OKHSL lightness at the edge, and `circularLerp` for hue. |
+| [src/hc-pair.ts](src/hc-pair.ts) | Tiny shared helpers: HC-pair selection (`pairNormal` / `pairHC`), HC-pair interpolation for the manual contrast level (`contrastFraction`, `hcMirrorsNormal` — the level-100 "HC slots are duplicates" predicate, `levelFraction`, `numberAt`, `parseToneValueAt`, `PAIR_SWITCH`), tone-value parsing (`parseToneValue` for absolute / relative / `'max'`/`'min'` extremes, `isExtremeTone`), root-tone discrimination (`isAbsoluteTone`, now incl. extremes), `clamp` / `lerp`, hue resolution (`resolveEffectiveHue`), relative-value parsing. Leaf module — types only, so every other module can import it. |
+| [src/formatters.ts](src/formatters.ts) | Variant→string dispatch (`okhsl` / `rgb` / `hsl` / `oklch`) and the four token-map shapes Glaze emits: `buildTokenMap` ([Tasty](https://tasty.style) `#name` keys + state aliases), `buildFlatTokenMap` (per-variant maps), `buildJsonMap` (per-color JSON), `buildCssMap` (CSS custom-property declarations). For `splitHue` it emits the light hue declarations plus, via `darkHueDeclarations` in `channels.ts`, the whole dark set when a `darkHue` makes it differ. Also the `resolveModes` helper used everywhere. |
+| [src/okhsl-color-math.ts](src/okhsl-color-math.ts) | OKHSL ↔ linear-sRGB ↔ gamma-sRGB ↔ OKLab conversions, hex parsing (3/6/8 digits), gamut clamping, and the `formatOkhsl` / `formatOkhst` / `formatRgb` / `formatHsl` / `formatOklch` writers. Converters and writers share one scale — `h` 0–360, `s` / `l` / `t` 0–1 — so any converter composes with any writer (the 0–100 tone axis lives in `okhst.ts`'s `toTone` / `fromTone`, not here); `warnPercentScale` catches pre-2.0 percentage-scale input instead of emitting a plausible wrong color. The only file with the actual color science. |
+| [src/config.ts](src/config.ts) | Global config singleton. `defaultConfig()` is the one source of truth for defaults; `configure()` mutates the live object and bumps a monotonic `configVersion` so theme caches invalidate. `snapshotConfig()` powers `glaze.getConfig()`. `freezeConfigForExport()` freezes resolve-relevant fields for authoring export (`pastel` is instance-only; `contrastLevel` is frozen only when instance-authored, since a global level is a live preference). `normalizeContrastLevel()` validates the manual contrast level. |
+| [src/validation.ts](src/validation.ts) | `validateColorDefs` (missing references, shadow-bg-cannot-be-shadow, mix-cannot-target-shadow, contrast-without-base, relative-without-base, WCAG-vs-APCA metric switch in a `contrast` pair, etc.) + `topoSort` so the resolver processes each color after its dependencies. |
+| [src/warnings.ts](src/warnings.ts) | Deduped contrast-unmet warnings. Caps cache at 256 entries to keep dev-server output bounded. |
+| [src/types.ts](src/types.ts) | All public TypeScript types: `HCPair`, `MinContrast`, `ContrastSpec`, `RelativeValue`, `ExtremeValue` (`'max'`/`'min'`), `ToneValue`, `AdaptationMode`, `OkhstColor`, `ToneWindow` (`[lo,hi]` \| `{lo,hi,eps}` \| `false`), `ColorDef` discriminated union (with `tone` + `flip` + `darkHue` / `darkSaturation`), `GlazeConfig` (with `lightTone` / `darkTone` / `autoFlip` / `contrastLevel`), `GlazeThemeSeed` (`hue` / `saturation` + optional dark pair), `GlazeTheme`, `GlazePalette`, `GlazeColorToken`, the `*Export` shapes, etc. `ResolvedColorVariant` stores `{ h, s, t, alpha }`. |
+| `src/glaze.test.ts` | Main test suite — covers the factory surface, resolver behavior, palette composition, shadow/mix algorithms, the manual contrast level, and the standalone color token round-trip. |
+| `src/contrast-solver.test.ts` | Tests for the binary-search solver in isolation. |
+| `src/hc-pair.test.ts` | Tests for the pure HC-pair selection and interpolation helpers. |
+| `src/okhsl-color-math.test.ts` | Tests for the format writers' 0–1 scale contract, the percentage-scale guard, and producer→writer composition. |
+
+### `docs/` files
+
+| File | Description |
+|---|---|
+| [docs/okhst.md](docs/okhst.md) | The OKHST color model spec — tone math, `REF_EPS`, the T↔L invariant, the scheme pipeline, calibrated window defaults, the contrast metric, and the APCA verification step. Source of truth for the color model. |
+| [docs/api.md](docs/api.md) | Full API reference. Every method, every option, every type. Reads as a lookup, not a tutorial. |
+| [docs/methodology.md](docs/methodology.md) | Palette design methodology — how to build a palette from scratch. Covers naming conventions, surface ladders, the accent anchor pattern, contrast-driven disabled chips, shadows, and `extend` composition. |
+| [docs/migration.md](docs/migration.md) | Migration & integration guide — choosing an export shape, wiring tokens into [Tasty](https://tasty.style) / CSS / JSON, prefix-map strategies, migrating from a legacy color system, and common pitfalls. |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `pnpm build` | Build ESM + CJS via tsdown (with `.d.ts` and sourcemaps). |
+| `pnpm test` | Run all tests (Vitest 4). |
+| `pnpm test -- <pattern>` | Run a subset of tests. |
+| `pnpm test:watch` | Tests in watch mode. |
+| `pnpm test:coverage` | Tests with coverage report. |
+| `pnpm typecheck` | Type-check without emitting. |
+| `pnpm lint` | ESLint over `src/`. |
+| `pnpm lint:fix` | ESLint with `--fix`. |
+| `pnpm format` | Prettier write `src/**/*.ts`. |
+| `pnpm format:check` | Prettier check (no writes). |
+| `pnpm changeset` | Create a changeset entry. |
+| `pnpm release` | Build and publish (used by CI). |
+
+## Stack
+
+- **Language:** TypeScript (strict mode, `consistent-type-imports` enforced)
+- **Build:** [tsdown](https://github.com/rolldown/tsdown) — ESM + CJS, unbundled, dts + sourcemaps
+- **Test:** [Vitest 4](https://vitest.dev/) with globals enabled
+- **Lint:** ESLint 10 + typescript-eslint + `eslint-config-prettier`
+- **Format:** Prettier — single quotes, semicolons, trailing commas, 80 cols
+- **Versioning:** [Changesets](https://github.com/changesets/changesets)
+- **Package manager:** pnpm 11
+
+## Code Conventions
+
+- TypeScript strict mode; `consistent-type-imports` enforced.
+- Test files use `*.test.ts` and live next to the module they test in `src/`.
+- Unused vars prefixed with `_` are allowed.
+- **No runtime dependencies** — every bit of math is implemented from scratch.
+- Functional API pattern: `glaze()` factory with attached static methods; no classes.
+- Each module starts with a JSDoc block describing its responsibility — keep these in sync when behavior changes.
+
+## Adding a New Color Type
+
+If you need to add a fourth `ColorDef` variant (alongside regular / shadow / mix), touch these files in order:
+
+1. [src/types.ts](src/types.ts) — add the new interface and extend the `ColorDef` discriminated union.
+2. [src/shadow.ts](src/shadow.ts) — add a discriminator predicate (`isFooDef`).
+3. [src/validation.ts](src/validation.ts) — extend `validateColorDefs` (missing-reference / cycle handling) and `topoSort` (record the new dependency edges).
+4. [src/resolver.ts](src/resolver.ts) — add a per-scheme `resolveFooForScheme` branch and dispatch from `resolveColorForScheme`.
+5. [src/formatters.ts](src/formatters.ts) — only if the output shape differs (it usually doesn't; the resolver returns a normal `ResolvedColorVariant`).
+6. `src/glaze.test.ts` — add coverage for the new def, including HC pairs, dark-mode behavior, and inheritance through `extend`.
+
+For a new public method on `glaze` (e.g. another statics entry), the wiring lives entirely in [src/glaze.ts](src/glaze.ts); the implementation should still go in a focused module.
+
+## CI/CD & Release
+
+- **CI:** Runs lint, format check, typecheck, build, and tests on push to `main` and PRs.
+- **Release:** On push to `main`, `changesets/action` either creates a version PR or publishes to npm.
+- **Snapshot:** Comment `/snapshot` on a PR to publish a `0.0.0-snapshot.<sha>` release.
+- **npm trusted publishing:** Uses OIDC provenance via the `release` GitHub environment; the workflow requires `environment: release` for npm to accept the OIDC token.
+- **`RELEASE_TOKEN` secret:** Fine-grained GitHub PAT (repo-scoped, `contents: write` + `pull-requests: write`) used by `changesets/action` for Git pushes and PR creation. Rotate before expiry.
+- **Repo settings required:** Settings → Actions → General → Workflow permissions → "Allow GitHub Actions to create and approve pull requests" must be enabled.
+
+## Before Pushing Changes
+
+Follow [`.cursor/commands/submit-changes.md`](.cursor/commands/submit-changes.md) for the full release-oriented workflow. At minimum:
+
+1. **Typecheck** — `pnpm typecheck`. Stop and fix errors before continuing.
+2. **Lint** — `pnpm lint`. Stop and fix errors before continuing.
+3. **Format** — `pnpm format` so the diff matches Prettier output.
+4. **Changeset** — for any user-visible change (features, fixes, refactors, perf, docs that affect published behavior), add a markdown file in `.changeset/` with a `patch` / `minor` / `major` bump and a concise user-facing summary. Skip only for purely internal changes (CI, repo churn, tests with no behavior change).
+5. **Commit** — Conventional Commits (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`). Optional scope. Keep the subject short. Include the changeset file in the same commit.
+6. **Push** — never push to `main`. Confirm the current branch, then `git push -u origin HEAD`.

package/README.md

@@ -32,7 +32,7 @@ contrast floor.
 - **Mix colors** — blend two colors with OKHSL or sRGB interpolation, opaque or transparent, with optional contrast solving
 - **Shadow colors** — OKHSL-native shadow computation with automatic alpha, fg/bg tinting, and per-scheme adaptation
 - **Light + Dark + High-Contrast** — all schemes from one definition
-- **Manual contrast level** — swap the high-contrast tier for a `0–100` slider; `0` is your normal palette, `100` the high-contrast one, and every level in between is solved, not approximated
+- **Manual contrast level** — put your normal palette on a `0–100` slider between itself and the high-contrast one; every level in between is solved, not approximated, and the high-contrast tier stays available on top
 - **Per-color hue override** — absolute or relative hue shifts within a theme
 - **Multi-format output** — native `rgb`, `hsl`, and `oklch`, plus
   [Tasty](https://tasty.style)-compatible `okhsl` and `okhst`
@@ -143,14 +143,15 @@ In Glaze, a **scheme variant** is one of `light`, `dark`, `lightContrast`, or
 
 ## Documentation
 
+- Explore the tone axis in the [interactive playground](https://glaze.tenphi.me/playground/).
 - Start with [the methodology](docs/methodology.md) to design a palette.
 - Use [migration and integration](docs/migration.md) to wire it into an
   application or replace an existing color system.
 - Keep the [API reference](docs/api.md) nearby for every method and option.
 - Read [OKHST in Glaze](docs/okhst.md) for the product-level color model, or
   the [full OKHST specification](https://github.com/tenphi/okhst) for its math.
-- [`AGENTS.md`](AGENTS.md) — source-tree orientation for contributors.
+- [`AGENTS.md`](https://github.com/tenphi/glaze/blob/main/AGENTS.md) — source-tree orientation for contributors.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/tenphi/glaze/blob/main/LICENSE)

package/dist/index.cjs

@@ -372,6 +372,7 @@ const sRGBGammaToLinear = (val) => {
 };
 /**
 * 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.
 */
 function okhslToSrgb(h, s, l, pastel = false) {
 	const lin = okhslToLinearSrgb(h, s, l, pastel);
@@ -581,47 +582,72 @@ function fmt$1(value, decimals) {
 	return parseFloat(value.toFixed(decimals)).toString();
 }
 /**
+* Every `format*` writer takes `s` / `l` / `t` on the **0–1 factor scale** —
+* the same scale every producer in the library hands back (`resolve()`,
+* `variantToOkhsl`, `srgbToOkhsl`, `oklabToOkhsl`, `okhslToOklab`,
+* `okhslToSrgb`). The percentages are an output detail: the writers multiply
+* by 100 themselves when the CSS syntax asks for a percentage.
+*
+* Before 2.0 the writers took 0–100 while everything producing those values
+* returned 0–1, so the obvious composition was off by 100x and failed
+* silently — `0.7` is a legal percentage, so the result was a valid CSS string
+* naming a near-black color. A value above 1 can only be that old
+* percentage-scale input, so warn about it loudly rather than emit a wrong
+* color quietly.
+*/
+const scaleWarnCache = /* @__PURE__ */ new Set();
+function warnPercentScale(fn, ...values) {
+	if (!values.some((v) => v > 1.000001)) return;
+	if (!scaleWarnCache.has(fn)) {
+		scaleWarnCache.add(fn);
+		console.warn(`glaze: ${fn}() got a value above 1 — it takes the 0-1 factors every Glaze producer returns (resolve(), variantToOkhsl, srgbToOkhsl), not 0-100 percentages. Divide by 100, or drop the "* 100" left over from the pre-2.0 signature.`);
+	}
+}
+/**
 * 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatOkhsl(h, s, l, pastel = false) {
+	warnPercentScale("formatOkhsl", s, l);
 	let outS = s;
-	if (pastel) outS = oklabToOkhsl(okhslToOklab(h, s / 100, l / 100, true), false)[1] * 100;
-	return `okhsl(${fmt$1(h, 2)} ${fmt$1(outS, 2)}% ${fmt$1(l, 2)}%)`;
+	if (pastel) outS = oklabToOkhsl(okhslToOklab(h, s, l, true), false)[1];
+	return `okhsl(${fmt$1(h, 2)} ${fmt$1(outS * 100, 2)}% ${fmt$1(l * 100, 2)}%)`;
 }
 /**
 * Format OKHST values as a CSS `okhst(H S% T%)` string.
-* h: 0–360, s: 0–100, t: 0–100 (percentage scale for s and t).
+* h: 0–360, s: 0–1, t: 0–1 (factor scale, matching `ResolvedColorVariant`).
 *
 * Pastel recompute matches `formatOkhsl`: convert via OKLab so external
 * parsers that only understand non-pastel OKHST render identically.
 */
 function formatOkhst(h, s, t, pastel = false) {
+	warnPercentScale("formatOkhst", s, t);
 	let outS = s;
 	if (pastel) {
 		const REF_EPS = .05;
 		const den = Math.log(1 + REF_EPS) - Math.log(REF_EPS);
-		const y = Math.exp(t / 100 * den + Math.log(REF_EPS)) - REF_EPS;
-		const l = toe(Math.cbrt(Math.max(0, y)));
-		outS = oklabToOkhsl(okhslToOklab(h, s / 100, l, true), false)[1] * 100;
+		const y = Math.exp(t * den + Math.log(REF_EPS)) - REF_EPS;
+		outS = oklabToOkhsl(okhslToOklab(h, s, toe(Math.cbrt(Math.max(0, y))), true), false)[1];
 	}
-	return `okhst(${fmt$1(h, 2)} ${fmt$1(outS, 2)}% ${fmt$1(t, 2)}%)`;
+	return `okhst(${fmt$1(h, 2)} ${fmt$1(outS * 100, 2)}% ${fmt$1(t * 100, 2)}%)`;
 }
 /**
 * Format OKHSL values as a CSS `rgb(R G B)` string.
 * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
-* h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatRgb(h, s, l, pastel = false) {
-	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100, pastel);
+	warnPercentScale("formatRgb", s, l);
+	const [r, g, b] = okhslToSrgb(h, s, l, pastel);
 	return `rgb(${parseFloat((r * 255).toFixed(2))} ${parseFloat((g * 255).toFixed(2))} ${parseFloat((b * 255).toFixed(2))})`;
 }
 /**
 * 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatHsl(h, s, l, pastel = false) {
-	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100, pastel);
+	warnPercentScale("formatHsl", s, l);
+	const [r, g, b] = okhslToSrgb(h, s, l, pastel);
 	const max = Math.max(r, g, b);
 	const min = Math.min(r, g, b);
 	const delta = max - min;
@@ -638,10 +664,11 @@ function formatHsl(h, s, l, pastel = false) {
 }
 /**
 * 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).
+* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
 */
 function formatOklch(h, s, l, pastel = false) {
-	const [L, C, hh] = okhslToOklch(h, s / 100, l / 100, pastel);
+	warnPercentScale("formatOklch", s, l);
+	const [L, C, hh] = okhslToOklch(h, s, l, pastel);
 	return `oklch(${fmt$1(L, 4)} ${fmt$1(C, 4)} ${fmt$1(hh, 2)})`;
 }
 /**
@@ -906,10 +933,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;
@@ -917,6 +948,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
@@ -1101,7 +1146,11 @@ function okhslToOkhst(c) {
 }
 /**
 * Edge adapter: a resolved variant stores canonical tone `t` (0–1). Convert
-* it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect.
+* it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect —
+* `s` and `l` on the same 0–1 factor scale, so `const { h, s, l } =
+* variantToOkhsl(v)` destructures straight into `formatOkhsl` / `formatRgb` /
+* `okhslToLinearSrgb` with no rescaling. `alpha` stays on the variant; use
+* `glaze.format(v, format)` for a string that carries it.
 */
 function variantToOkhsl(v) {
 	return {
@@ -2276,12 +2325,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
@@ -2538,7 +2589,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({
@@ -2727,10 +2778,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();
@@ -2765,9 +2817,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];
@@ -2792,10 +2844,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");
 	}
@@ -2803,7 +2855,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");
 	}
@@ -3005,10 +3057,10 @@ function fmt(value, decimals) {
 function formatVariant(v, format = "oklch", pastel = false) {
 	const effectivePastel = v.pastel ?? pastel;
 	let base;
-	if (format === "okhst") base = formatOkhst(v.h, v.s * 100, v.t * 100, effectivePastel);
+	if (format === "okhst") base = formatOkhst(v.h, v.s, v.t, effectivePastel);
 	else {
 		const { l } = variantToOkhsl(v);
-		base = formatters[format](v.h, v.s * 100, l * 100, effectivePastel);
+		base = formatters[format](v.h, v.s, l, effectivePastel);
 	}
 	if (v.alpha >= 1) return base;
 	const closing = base.lastIndexOf(")");
@@ -3024,7 +3076,7 @@ function formatVariantHue(v, plan, pastel = false) {
 	const [L, C] = okhslToOklch(v.h, v.s, l, effectivePastel);
 	let base;
 	if (plan.inline) if (v.s <= 1e-6) base = `oklch(${fmt(L, 4)} 0 0)`;
-	else base = formatOklch(v.h, v.s * 100, l * 100, effectivePastel);
+	else base = formatOklch(v.h, v.s, l, effectivePastel);
 	else base = `oklch(${fmt(L, 4)} ${fmt(C, 4)} ${plan.hueVar})`;
 	if (v.alpha >= 1) return base;
 	const closing = base.lastIndexOf(")");
@@ -3037,23 +3089,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) {