@tenphi/glaze 0.13.0 → 0.15.0

package/dist/index.d.mts

@@ -1,78 +1,66 @@
 //#region src/contrast-solver.d.ts
-/**
- * OKHSL Contrast Solver
- *
- * Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
- * 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 {
+/** Metric + numeric target after resolving a `ContrastSpec` for a mode. */
+interface ResolvedContrast {
+  metric: 'wcag' | 'apca';
+  /** WCAG ratio (>= 1) or APCA Lc magnitude (0–106). */
+  target: number;
+}
+declare function resolveMinContrast(value: MinContrast$1): number;
+/**
+ * Resolve a `ContrastSpec` (already selected from any outer HC pair) for a
+ * given mode into `{ metric, target }`. Handles the inner metric HC pair and
+ * preset resolution.
+ */
+declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean): ResolvedContrast;
+/**
+ * APCA lightness contrast (Lc), signed: positive for dark text on light bg,
+ * negative for light text on dark bg. Inputs are screen luminances (0–1).
+ */
+declare function apcaContrast(yText: number, yBg: number): number;
+interface FindToneForContrastOptions {
   /** Hue of the candidate color (0–360). */
   hue: number;
   /** Saturation of the candidate color (0–1). */
   saturation: number;
-  /** Preferred lightness of the candidate (0–1). */
-  preferredLightness: number;
-  /** Base/reference color as linear sRGB (channels may be outside 0–1 before clamp). */
-  baseLinearRgb: [number, number, number];
-  /** WCAG contrast ratio target floor. */
-  contrast: MinContrast$1;
-  /** Search bounds for lightness. Default: [0, 1]. */
-  lightnessRange?: [number, number];
+  /** Preferred tone of the candidate (0–1). */
+  preferredTone: number;
+  /** Base/reference color as linear sRGB. */
+  baseLinearRgb: LinearRgb;
+  /** Resolved contrast floor (metric + target). */
+  contrast: ResolvedContrast;
+  /** Search bounds for tone. Default: [0, 1]. */
+  toneRange?: [number, number];
   /** Convergence threshold. Default: 1e-4. */
   epsilon?: number;
-  /** Maximum binary-search iterations per branch. Default: 14. */
+  /** Maximum binary-search iterations per branch. Default: 18. */
   maxIterations?: number;
-  /**
-   * Preferred search direction before auto-flip is considered.
-   *
-   * Theme resolution sets this from the requested lightness relative to
-   * the base color so `autoFlip: false` preserves the authored direction.
-   * When omitted, the solver falls back to the side whose extreme has
-   * higher contrast against the base.
-   */
+  /** Preferred search direction before auto-flip is considered. */
   initialDirection?: 'lighter' | 'darker';
-  /**
-   * Auto-flip lightness direction when contrast can't be met.
-   *
-   * When `true`, the solver searches the initial direction first. If that side
-   * doesn't reach the target, it tries the opposite direction and
-   * uses it when it passes. If neither side passes, it returns the
-   * extreme lightness of the initial direction.
-   *
-   * When `false`, only the initial direction is considered. If it
-   * doesn't reach the target, the result is pinned to the initial
-   * direction's extreme — never to the original preferred lightness.
-   *
-   * Default: false.
-   */
+  /** Auto-flip tone direction when contrast can't be met. Default: false. */
   flip?: boolean;
+  /** Use the hue-independent "safe" chroma boundary. Default: false. */
+  pastel?: boolean;
 }
-interface FindLightnessForContrastResult {
-  /** Chosen lightness in 0–1. */
-  lightness: number;
-  /** Achieved WCAG contrast ratio. */
+interface FindToneForContrastResult {
+  /** Chosen tone in 0–1. */
+  tone: number;
+  /** Achieved score (WCAG ratio or APCA Lc magnitude). */
   contrast: number;
   /** Whether the target was reached. */
   met: boolean;
   /** Which branch was selected. */
   branch: 'lighter' | 'darker' | 'preferred';
-  /**
-   * Whether the result was auto-flipped to the opposite direction.
-   * Only set when the initial direction failed and the opposite
-   * direction satisfied the target.
-   */
+  /** Whether the result auto-flipped to the opposite direction. */
   flipped?: boolean;
 }
-declare function resolveMinContrast(value: MinContrast$1): number;
 /**
- * Find the OKHSL lightness that satisfies a WCAG 2 contrast target
- * against a base color, staying as close to `preferredLightness` as possible.
+ * Find the tone that satisfies a contrast floor against a base color,
+ * staying as close to `preferredTone` as possible.
  */
-declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
+declare function findToneForContrast(options: FindToneForContrastOptions): FindToneForContrastResult;
 interface FindValueForMixContrastOptions {
   /** Preferred mix parameter (0–1). */
   preferredValue: number;
@@ -80,62 +68,69 @@ interface FindValueForMixContrastOptions {
   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.
-   */
+  /** Resolved contrast floor (metric + target). */
+  contrast: ResolvedContrast;
+  /** Compute the luminance of the mixed color at parameter t. */
   luminanceAtValue: (t: number) => number;
   /** Convergence threshold. Default: 1e-4. */
   epsilon?: number;
   /** Maximum binary-search iterations per branch. Default: 20. */
   maxIterations?: number;
-  /**
-   * Auto-flip mix direction when contrast can't be met.
-   *
-   * When `true`, the solver searches the initial direction first
-   * (the side whose extreme has higher contrast against the base).
-   * If that side doesn't reach the target, it tries the opposite
-   * direction and uses it when it passes. If neither side passes,
-   * it returns the extreme mix value of the initial direction.
-   *
-   * When `false`, only the initial direction is considered. If it
-   * doesn't reach the target, the result is pinned to the initial
-   * direction's extreme — never to the original preferred value.
-   *
-   * Default: false.
-   */
+  /** Auto-flip mix direction when contrast can't be met. Default: false. */
   flip?: boolean;
 }
 interface FindValueForMixContrastResult {
-  /** Chosen mix parameter (0–1). */
   value: number;
-  /** Achieved WCAG contrast ratio. */
   contrast: number;
-  /** Whether the target was reached. */
   met: boolean;
-  /**
-   * Whether the result was auto-flipped to the opposite direction.
-   * Only set when the initial direction failed and the opposite
-   * direction satisfied the target.
-   */
   flipped?: 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.
+ * Find the mix parameter (ratio or opacity) that satisfies a contrast floor
+ * 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. */
 type HCPair<T> = T | [T, T];
+/** Bare WCAG contrast target: a ratio number or a named preset. */
 type MinContrast = number | ContrastPreset;
+/**
+ * A contrast floor with a pluggable metric.
+ *
+ * - `number` / `ContrastPreset`: a WCAG ratio (bare form).
+ * - `{ wcag }`: WCAG ratio or preset, optionally an HC pair.
+ * - `{ apca }`: APCA Lc target (absolute value), optionally an HC pair.
+ *
+ * The `[normal, highContrast]` pair may live at the outer level
+ * (`[4.5, 7]`, `[{ wcag: 4.5 }, { wcag: 7 }]`) or inside the metric
+ * (`{ wcag: [4.5, 7] }`, `{ apca: [45, 60] }`).
+ */
+type ContrastSpec = number | ContrastPreset | {
+  wcag: HCPair<number | ContrastPreset>;
+} | {
+  apca: HCPair<number>;
+};
 type AdaptationMode = 'auto' | 'fixed' | 'static';
 /** A signed relative offset string, e.g. '+20' or '-15.5'. */
 type RelativeValue = `+${number}` | `-${number}`;
+/**
+ * Force a color to a tone extreme:
+ * - `'max'`: the highest tone in the active scheme range/window.
+ * - `'min'`: the lowest tone.
+ *
+ * Under `mode: 'auto'` the extreme inverts in the dark scheme (so `'max'`
+ * tracks the inversion and becomes the darkest tone). No `base` required.
+ */
+type ExtremeValue = 'max' | 'min';
+/**
+ * A tone value as authored on a color.
+ * - Number: absolute tone (0–100).
+ * - `'+N'` / `'-N'`: relative to the base's tone (requires `base`).
+ * - `'max'` / `'min'`: forced to the scheme's tone extreme (no base needed).
+ */
+type ToneValue = number | RelativeValue | ExtremeValue;
 /** Color format for output. */
 type GlazeColorFormat = 'okhsl' | 'rgb' | 'hsl' | 'oklch';
 /**
@@ -156,6 +151,15 @@ interface OkhslColor {
   s: number;
   l: number;
 }
+/**
+ * Direct OKHST color input — OKHSL with the lightness axis replaced by the
+ * contrast-uniform tone axis. `h`: 0–360, `s`: 0–1, `t`: 0–1 (tone).
+ */
+interface OkhstColor {
+  h: number;
+  s: number;
+  t: number;
+}
 /** sRGB components in 0–255 (value-shorthand object form). */
 interface RgbColor {
   r: number;
@@ -170,11 +174,12 @@ interface OklchColor {
 }
 interface RegularColorDef {
   /**
-   * Lightness value (0–100).
-   * - Number: absolute lightness.
-   * - String ('+N' / '-N'): relative to base color's lightness (requires `base`).
+   * Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
+   * - Number: absolute tone.
+   * - String ('+N' / '-N'): relative to base color's tone (requires `base`).
+   * - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
    */
-  lightness?: HCPair<number | RelativeValue>;
+  tone?: HCPair<ToneValue>;
   /** Saturation factor applied to the seed saturation (0–1, default: 1). */
   saturation?: number;
   /**
@@ -185,15 +190,30 @@ interface RegularColorDef {
   hue?: number | RelativeValue;
   /** Name of another color in the same theme (dependent color). */
   base?: string;
-  /** WCAG contrast ratio floor against the base color. */
-  contrast?: HCPair<MinContrast>;
+  /**
+   * Contrast floor against the base color. A bare number/preset is WCAG;
+   * use `{ wcag }` / `{ apca }` to pick the metric. Accepts an HC pair.
+   */
+  contrast?: HCPair<ContrastSpec>;
   /** Adaptation mode. Default: 'auto'. */
   mode?: AdaptationMode;
+  /**
+   * Whether to flip out-of-bounds results to the opposite side instead of
+   * clamping to the extreme. Affects both:
+   * - relative `tone`: when `base ± delta` exceeds `[0, 100]`, mirror the
+   *   delta to the other side of the base.
+   * - `contrast`: when the requested direction can't meet the floor, try the
+   *   opposite side (same as the global `autoFlip`).
+   *
+   * Defaults to the global `autoFlip` config (default `true`). Set `false`
+   * to clamp instead.
+   */
+  flip?: boolean;
   /**
    * Fixed opacity (0–1).
    * Output includes alpha in the CSS value.
    * Does not affect contrast resolution — a semi-transparent color
-   * has no fixed perceived lightness, so `contrast` and `opacity`
+   * has no fixed perceived tone, so `contrast` and `opacity`
    * should not be combined (a console.warn is emitted).
    */
   opacity?: number;
@@ -279,12 +299,13 @@ interface MixColorDef {
    */
   space?: 'okhsl' | 'srgb';
   /**
-   * Minimum WCAG contrast between the base and the resulting color.
+   * Minimum 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.
+   * A bare number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the
+   * metric. Supports [normal, highContrast] pair.
    */
-  contrast?: HCPair<MinContrast>;
+  contrast?: HCPair<ContrastSpec>;
   /**
    * Whether this color is inherited by child themes created via `extend()`.
    * Default: true. Set to false to make this color local to the current theme.
@@ -293,14 +314,20 @@ interface MixColorDef {
 }
 type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
-/** Resolved color for a single scheme variant. */
+/**
+ * Resolved color for a single scheme variant.
+ *
+ * Stored in OKHST: `h` / `s` are OKHSL hue/saturation, `t` is the canonical
+ * contrast-uniform tone (0–1, reference eps). Convert to OKHSL lightness via
+ * `variantToOkhsl` at the rendering / luminance edges.
+ */
 interface ResolvedColorVariant {
   /** OKHSL hue (0–360). */
   h: number;
   /** OKHSL saturation (0–1). */
   s: number;
-  /** OKHSL lightness (0–1). */
-  l: number;
+  /** Canonical tone (0–1, reference eps). */
+  t: number;
   /** Opacity (0–1). Default: 1. */
   alpha: number;
 }
@@ -315,24 +342,26 @@ interface ResolvedColor {
   mode?: AdaptationMode;
 }
 /**
- * Lightness window value. A `[lo, hi]` tuple (0–100) or `false` to disable
- * clamping entirely (equivalent to `[0, 100]`).
+ * A scheme tone window.
+ * - `[lo, hi]`: OKHSL-lightness endpoints (0–100) the authored tone is
+ *   remapped into, using the reference eps `0.05`. The common form.
+ * - `{ lo, hi, eps }`: same, with an explicit render curvature `eps`
+ *   (advanced — most palettes never need this).
+ * - `false`: disable clamping (full range `[0, 100]` at the reference eps).
+ *   This removes the *boundaries*, not the tone curve.
  */
-type LightnessWindow = false | [number, number];
+type ToneWindow = false | [number, number] | {
+  lo: number;
+  hi: number;
+  eps: number;
+};
 interface GlazeConfig {
-  /** Light scheme lightness window [lo, hi]. Default: [10, 100]. Pass `false` to disable clamping. */
-  lightLightness?: LightnessWindow;
-  /** Dark scheme lightness window [lo, hi]. Default: [15, 95]. Pass `false` to disable clamping. */
-  darkLightness?: LightnessWindow;
+  /** Light scheme tone window — `[lo, hi]` (default `[10, 100]`), `{ lo, hi, eps }` for advanced eps tuning, or `false` to disable clamping. */
+  lightTone?: ToneWindow;
+  /** Dark scheme tone window — `[lo, hi]` (default `[15, 95]`), `{ lo, hi, eps }`, or `false` to disable clamping. */
+  darkTone?: ToneWindow;
   /** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
   darkDesaturation?: number;
-  /**
-   * Möbius beta for dark auto-inversion (0–1).
-   * Lower values expand subtle near-white distinctions in dark mode.
-   * Set to 1 for linear (legacy) behavior. Default: 0.5.
-   * Accepts [normal, highContrast] pair for separate HC tuning.
-   */
-  darkCurve?: HCPair<number>;
   /** State alias names for token export. */
   states?: {
     dark?: string;
@@ -343,26 +372,32 @@ interface GlazeConfig {
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
   /**
-   * Automatically flip lightness direction when contrast can't be met.
+   * Automatically flip tone direction when contrast can't be met.
    *
    * When enabled (default `true`), the solver searches the requested
-   * lightness direction first. If that direction can't reach the target,
+   * tone direction first. If that direction can't reach the target,
    * it tries the opposite direction and uses it when it passes. If neither
-   * side passes, the lightness is pinned to the requested-direction
+   * side passes, the tone is pinned to the requested-direction
    * extreme and a warning is emitted.
    *
    * Set to `false` for strict "no flip" behavior. The opposite
    * direction is never considered: if the requested direction can't
-   * meet the target, the lightness is pinned to its extreme (never
-   * falls back to the originally requested lightness).
+   * meet the target, the tone is pinned to its extreme (never
+   * falls back to the originally requested tone).
    */
   autoFlip?: boolean;
+  /**
+   * If true, uses a hue-independent "safe" chroma limit across all colors
+   * so that scaling saturation never exceeds the sRGB boundary at any hue
+   * for the given lightness.
+   * @default false
+   */
+  pastel?: boolean;
 }
 interface GlazeConfigResolved {
-  lightLightness: LightnessWindow;
-  darkLightness: LightnessWindow;
+  lightTone: ToneWindow;
+  darkTone: ToneWindow;
   darkDesaturation: number;
-  darkCurve: HCPair<number>;
   states: {
     dark: string;
     highContrast: string;
@@ -370,25 +405,30 @@ interface GlazeConfigResolved {
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
+  pastel: boolean;
 }
 /**
  * Per-instance config override for `glaze.color()` and `glaze()` themes.
  * Fields that are set take priority over the live global config. Fields
  * that are omitted fall through to the live global at resolve time.
  *
- * `false` for a lightness window disables clamping (equivalent to `[0, 100]`).
+ * `false` for a tone window disables clamping (full range at reference eps).
  */
 interface GlazeConfigOverride {
-  /** Light scheme lightness window, or `false` to disable clamping. */
-  lightLightness?: LightnessWindow;
-  /** Dark scheme lightness window, or `false` to disable clamping. */
-  darkLightness?: LightnessWindow;
+  /** Light scheme tone window, or `false` to disable clamping. */
+  lightTone?: ToneWindow;
+  /** Dark scheme tone window, or `false` to disable clamping. */
+  darkTone?: ToneWindow;
   /** Saturation reduction factor for dark scheme (0–1). */
   darkDesaturation?: number;
-  /** Möbius beta for dark auto-inversion. Accepts [normal, hc] pair. */
-  darkCurve?: HCPair<number>;
-  /** Whether to auto-flip lightness when contrast can't be met. */
+  /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
+  /**
+   * If true, uses a hue-independent "safe" chroma limit across all colors
+   * so that scaling saturation never exceeds the sRGB boundary at any hue
+   * for the given lightness.
+   */
+  pastel?: boolean;
   /**
    * Shadow tuning defaults. Only meaningful for themes; harmless on
    * standalone color tokens.
@@ -425,25 +465,28 @@ interface GlazeShadowInput {
 interface GlazeColorInput {
   hue: number;
   saturation: number;
-  lightness: HCPair<number>;
+  tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
+  /** Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. */
+  flip?: boolean;
   /**
    * Fixed opacity (0–1). Output includes alpha in the CSS value.
-   * Combining with `contrast` is not recommended (perceived lightness
+   * Combining with `contrast` is not recommended (perceived tone
    * becomes unpredictable) — a `console.warn` is emitted in that case.
    */
   opacity?: number;
   /**
    * Optional dependency on another color. Same semantics as
-   * `GlazeColorOverrides.base` — `contrast` and relative `lightness`
+   * `GlazeColorOverrides.base` — `contrast` and relative `tone`
    * anchor to the base per scheme.
    */
   base?: GlazeColorToken | GlazeColorValue;
   /**
-   * WCAG contrast floor against `base`. Requires `base` to be set.
+   * Contrast floor against `base`. Requires `base` to be set. A bare
+   * number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
    */
-  contrast?: HCPair<MinContrast>;
+  contrast?: HCPair<ContrastSpec>;
   /**
    * Optional human-readable name for the token. Used in error and
    * warning messages (otherwise an internal name like `"value"` is
@@ -463,10 +506,11 @@ interface GlazeColorInput {
  * Literal object forms:
  * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l`
  *   throws with a hint to use the structured form.
+ * - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1.
  * - `{ r, g, b }` — sRGB 0–255.
  * - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
  */
-type GlazeColorValue = string | OkhslColor | RgbColor | OklchColor;
+type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
 /** Color overrides for the `from` and value-shorthand inputs. */
 interface GlazeColorOverrides {
   /**
@@ -478,33 +522,41 @@ interface GlazeColorOverrides {
   /** Override seed saturation (0–100). Default: extracted from value. */
   saturation?: number;
   /**
-   * Override lightness. Number is absolute (0–100); `'+N'`/`'-N'` is
-   * relative to the literal seed (the value passed to `glaze.color()`).
+   * Override tone. Number is absolute (0–100, contrast-uniform); `'+N'`/`'-N'`
+   * is relative to the literal seed (the value passed to `glaze.color()`);
+   * `'max'` / `'min'` force to the scheme's tone extreme.
    * Supports HCPair for high-contrast.
    */
-  lightness?: HCPair<number | RelativeValue>;
+  tone?: HCPair<ToneValue>;
   /** Saturation multiplier on the seed (0–1). Default: 1. */
   saturationFactor?: number;
   /**
    * Adaptation mode. Defaults to `'auto'` for every input form, so
    * colors automatically adapt between light and dark like an ordinary
    * theme color. All value-shorthand inputs (strings and literal objects)
-   * preserve light lightness (`lightLightness: false`) and snapshot
-   * `globalConfig.darkLightness` on the dark side. Only the structured
-   * `{ hue, saturation, lightness }` form also snapshots
-   * `globalConfig.lightLightness`.
+   * preserve light tone (`lightTone: false`) and snapshot
+   * `globalConfig.darkTone` on the dark side. Only the structured
+   * `{ hue, saturation, tone }` form also snapshots
+   * `globalConfig.lightTone`.
    *
-   * Pass `'fixed'` explicitly to opt back into the legacy linear, non-
-   * inverting mapping; pass `'static'` to pin the same lightness
+   * Pass `'fixed'` explicitly to opt back into the linear, non-
+   * inverting mapping; pass `'static'` to pin the same tone
    * across every variant.
    */
   mode?: AdaptationMode;
   /**
-   * WCAG contrast floor. By default solved against the literal seed
+   * Flip out-of-bounds results (relative `tone` overshoot / unmet
+   * `contrast`) to the opposite side instead of clamping. Defaults to
+   * the global `autoFlip`.
+   */
+  flip?: boolean;
+  /**
+   * Contrast floor. By default solved against the literal seed
    * (the value itself); when `base` is set, solved against the base's
-   * resolved variant per scheme. Same shape as `RegularColorDef.contrast`.
+   * resolved variant per scheme. Same shape as `RegularColorDef.contrast`
+   * (bare number/preset = WCAG; `{ wcag }` / `{ apca }` to pick the metric).
    */
-  contrast?: HCPair<MinContrast>;
+  contrast?: HCPair<ContrastSpec>;
   /**
    * Optional dependency on another color. Accepts either a
    * `GlazeColorToken` (returned by another `glaze.color()`) or a raw
@@ -514,14 +566,14 @@ interface GlazeColorOverrides {
    * When set:
    * - `contrast` is solved against the base's resolved variant
    *   per-scheme (light / dark / lightContrast / darkContrast).
-   * - Relative `lightness: '+N'` / `'-N'` is anchored to the base's
-   *   lightness per-scheme (matches theme behavior for dependent colors).
+   * - Relative `tone: '+N'` / `'-N'` is anchored to the base's
+   *   tone per-scheme (matches theme behavior for dependent colors).
    * - Relative `hue: '+N'` / `'-N'` still anchors to the seed (the
    *   value passed to `glaze.color()`), not the base.
    * - When the base was created via the structured form (with explicit
-   *   `hue`/`saturation`/`lightness`), it is resolved at full range
-   *   (`lightLightness: false`) for the linking math — ensuring the
-   *   contrast/lightness anchor matches the input lightness, not the
+   *   `hue`/`saturation`/`tone`), it is resolved at full range
+   *   (`lightTone: false`) for the linking math — ensuring the
+   *   contrast/tone anchor matches the input tone, not the
    *   windowed output. The base's own `.resolve()` output is unaffected.
    *
    * The base token's `.resolve()` is called lazily on first resolve and
@@ -531,7 +583,7 @@ interface GlazeColorOverrides {
   base?: GlazeColorToken | GlazeColorValue;
   /**
    * Fixed opacity (0–1). Output includes alpha in the CSS value.
-   * Combining with `contrast` is not recommended (perceived lightness
+   * Combining with `contrast` is not recommended (perceived tone
    * becomes unpredictable) — a `console.warn` is emitted in that case.
    */
   opacity?: number;
@@ -548,7 +600,7 @@ interface GlazeColorOverrides {
  *
  * ```ts
  * glaze.color({ from: '#1a1a2e', base: bg, contrast: 'AA' })
- * glaze.color({ from: { r: 38, g: 252, b: 178 }, lightness: '+10' })
+ * glaze.color({ from: { r: 38, g: 252, b: 178 }, tone: '+10' })
  * ```
  */
 interface GlazeFromInput extends GlazeColorOverrides {
@@ -629,12 +681,13 @@ interface GlazeColorTokenExport {
 interface GlazeColorInputExport {
   hue: number;
   saturation: number;
-  lightness: HCPair<number>;
+  tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
+  flip?: boolean;
   opacity?: number;
   base?: GlazeColorTokenExport | GlazeColorValue;
-  contrast?: HCPair<MinContrast>;
+  contrast?: HCPair<ContrastSpec>;
   name?: string;
 }
 /**
@@ -644,10 +697,11 @@ interface GlazeColorInputExport {
 interface GlazeColorOverridesExport {
   hue?: number | RelativeValue;
   saturation?: number;
-  lightness?: HCPair<number | RelativeValue>;
+  tone?: HCPair<ToneValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
-  contrast?: HCPair<MinContrast>;
+  flip?: boolean;
+  contrast?: HCPair<ContrastSpec>;
   base?: GlazeColorTokenExport | GlazeColorValue;
   opacity?: number;
   name?: string;
@@ -657,6 +711,8 @@ interface GlazeTheme {
   readonly hue: number;
   /** The saturation seed (0–100). */
   readonly saturation: number;
+  /** The effective config for this theme. */
+  getConfig(): GlazeConfigResolved;
   /** Add/replace colors (additive merge with existing definitions). */
   colors(defs: ColorMap): void;
   /** Get a color definition by name. */
@@ -803,7 +859,7 @@ type PaletteInput = Record<string, GlazeTheme>;
  * Create a single-hue glaze theme.
  *
  * An optional `config` override can be supplied to customize the resolve
- * behavior for this theme (lightness windows, dark curve, etc.). The
+ * 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.
@@ -814,7 +870,7 @@ type PaletteInput = Record<string, GlazeTheme>;
  * // or shorthand:
  * const primary = glaze({ hue: 280, saturation: 80 });
  * // with config override:
- * const raw = glaze(280, 80, { lightLightness: false });
+ * const raw = glaze(280, 80, { lightTone: false });
  * ```
  */
 declare function glaze(hueOrOptions: number | {
@@ -827,7 +883,7 @@ declare namespace glaze {
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
-  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
+  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
@@ -835,24 +891,92 @@ declare namespace glaze {
   var resetConfig: () => void;
 }
 //#endregion
+//#region src/okhst.d.ts
+/**
+ * Reference eps for the OKHST color space. WCAG 2 contrast is
+ * `(Y_hi + 0.05) / (Y_lo + 0.05)`, so an eps of `0.05` makes equal tone
+ * steps yield equal WCAG contrast. This is the canonical eps used by
+ * `okhst()` input, `{ h, s, t }` input, stored `ResolvedColorVariant.t`,
+ * relative `tone` offsets, and the contrast solver.
+ */
+declare const REF_EPS = 0.05;
+/**
+ * Map a luminance `Y` (0–1) to tone (0–100) at the given eps.
+ * `toneFromY(0) === 0` and `toneFromY(1) === 100` for any eps.
+ */
+declare function toneFromY(y: number, eps?: number): number;
+/** Map a tone (0–100) back to luminance (0–1). Inverse of {@link toneFromY}. */
+declare function yFromTone(t: number, eps?: number): number;
+/** OKHSL lightness (0–1) -> tone (0–100). */
+declare function toTone(l: number, eps?: number): number;
+/** Tone (0–100) -> OKHSL lightness (0–1). Inverse of {@link toTone}. */
+declare function fromTone(t: number, eps?: number): number;
+/** Convert OKHST `{ h, s, t }` (t in 0–1) to OKHSL `{ h, s, l }`. */
+declare function okhstToOkhsl(c: {
+  h: number;
+  s: number;
+  t: number;
+}): {
+  h: number;
+  s: number;
+  l: number;
+};
+/** Convert OKHSL `{ h, s, l }` to OKHST `{ h, s, t }` (t in 0–1). */
+declare function okhslToOkhst(c: {
+  h: number;
+  s: number;
+  l: number;
+}): {
+  h: number;
+  s: number;
+  t: number;
+};
+/**
+ * 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.
+ */
+declare function variantToOkhsl(v: {
+  h: number;
+  s: number;
+  t: number;
+}): {
+  h: number;
+  s: number;
+  l: number;
+};
+//#endregion
 //#region src/okhsl-color-math.d.ts
 /**
  * OKHSL color math primitives for the glaze theme generator.
  *
- * Provides bidirectional OKHSL ↔ sRGB conversion, relative luminance
- * computation for WCAG 2 contrast calculations, and multi-format output
- * (okhsl, rgb, hsl, oklch).
+ * Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
+ * for both contrast metrics (WCAG 2 relative luminance and APCA screen
+ * luminance `Ys`), and multi-format output (okhsl, rgb, hsl, oklch).
  */
 type Vec3 = [number, number, number];
+/**
+ * OKHSL toe function: maps OKLab lightness L to perceptual lightness l.
+ * Exported for the OKHST tone transfers in `okhst.ts`.
+ */
+/**
+ * OKHSL lightness of the gamut cusp for a hue — the lightness where the
+ * realizable chroma peaks. Reuses the same `find_cusp` OKHSL already runs for
+ * its `s` normalization (no new color math); the OKLab cusp lightness is run
+ * through the OKHSL `toe` and clamped to `[0.001, 0.999]` so divisions that
+ * key off it stay safe. Cached per (rounded) hue.
+ *
+ * @param h Hue, 0–360.
+ */
+declare function cuspLightness(h: number): number;
 /**
  * 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];
+declare function okhslToOklab(h: number, s: number, l: number, pastel?: boolean): [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.
  */
-declare function okhslToLinearSrgb(h: number, s: number, l: number): [number, number, number];
+declare function okhslToLinearSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 /**
  * Compute relative luminance Y from linear sRGB channels.
  * Per WCAG 2: Y = 0.2126·R + 0.7152·G + 0.0722·B
@@ -865,7 +989,7 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
 /**
  * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
  */
-declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
+declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 /**
  * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
  * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
@@ -877,12 +1001,12 @@ declare function gamutClampedLuminance(linearRgb: [number, number, number]): num
  * Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
  */
-declare const oklabToOkhsl: (lab: Vec3) => Vec3;
+declare const oklabToOkhsl: (lab: Vec3, pastel?: boolean) => Vec3;
 /**
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
  */
-declare function srgbToOkhsl(rgb: [number, number, number]): [number, number, number];
+declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [number, number, number];
 /**
  * Convert CSS HSL (sRGB-based) to gamma-encoded sRGB [r, g, b] in 0–1 range.
  * h: 0–360, s: 0–1, l: 0–1.
@@ -912,23 +1036,23 @@ declare function parseHexAlpha(hex: string): {
  * 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).
  */
-declare function formatOkhsl(h: number, s: number, l: number): string;
+declare function formatOkhsl(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * 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).
  */
-declare function formatRgb(h: number, s: number, l: number): string;
+declare function formatRgb(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `hsl(H S% L%)` string.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
-declare function formatHsl(h: number, s: number, l: number): string;
+declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `oklch(L C H)` string.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
-declare function formatOklch(h: number, s: number, l: number): string;
+declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
 //#endregion
-export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type LightnessWindow, type MinContrast, type MixColorDef, type OkhslColor, type OklchColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type RgbColor, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveContrastForMode, resolveMinContrast, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map