@tenphi/glaze 0.0.0-snapshot.4c063ef → 0.0.0-snapshot.4e8eab7

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. */
@@ -99,6 +133,11 @@ interface RegularColorDef {
    * should not be combined (a console.warn is emitted).
    */
   opacity?: number;
+  /**
+   * 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.
+   */
+  inherit?: boolean;
 }
 /** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
 interface ShadowTuning {
@@ -143,8 +182,52 @@ interface ShadowColorDef {
   intensity: HCPair<number>;
   /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
   tuning?: ShadowTuning;
+  /**
+   * 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.
+   */
+  inherit?: boolean;
 }
-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>;
+  /**
+   * 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.
+   */
+  inherit?: boolean;
+}
+type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
 /** Resolved color for a single scheme variant. */
 interface ResolvedColorVariant {
@@ -174,6 +257,13 @@ interface GlazeConfig {
   darkLightness?: [number, number];
   /** 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;
@@ -188,6 +278,7 @@ interface GlazeConfigResolved {
   lightLightness: [number, number];
   darkLightness: [number, number];
   darkDesaturation: number;
+  darkCurve: HCPair<number>;
   states: {
     dark: string;
     highContrast: string;
@@ -203,21 +294,196 @@ interface GlazeThemeExport {
 }
 /** Input for `glaze.shadow()` standalone factory. */
 interface GlazeShadowInput {
-  /** Background color — hex string or OKHSL { h, s (0-1), l (0-1) }. */
-  bg: HexColor | OkhslColor;
-  /** Foreground color for tinting + intensity modulation. */
-  fg?: HexColor | OkhslColor;
+  /**
+   * Background color — accepts any `GlazeColorValue` form: hex
+   * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
+   * / `oklch()` strings, an `OkhslColor` object, or an `[r, g, b]`
+   * (0–255) tuple. Alpha components are dropped with a warning.
+   */
+  bg: GlazeColorValue;
+  /**
+   * Foreground color for tinting + intensity modulation. Accepts the
+   * same forms as `bg`.
+   */
+  fg?: GlazeColorValue;
   /** Intensity 0-100. */
   intensity: number;
   tuning?: ShadowTuning;
 }
-/** Input for `glaze.color()` standalone factory. */
+/** Input for the structured `glaze.color()` overload. */
 interface GlazeColorInput {
   hue: number;
   saturation: number;
   lightness: HCPair<number>;
   saturationFactor?: number;
   mode?: AdaptationMode;
+  /**
+   * Fixed opacity (0–1). Output includes alpha in the CSS value.
+   * Combining with `contrast` is not recommended (perceived lightness
+   * 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`
+   * anchor to the base per scheme.
+   */
+  base?: GlazeColorToken | GlazeColorValue;
+  /**
+   * WCAG contrast floor against `base`. Requires `base` to be set.
+   */
+  contrast?: HCPair<MinContrast>;
+  /**
+   * Optional human-readable name for the token. Used in error and
+   * warning messages (otherwise an internal name like `"value"` is
+   * used). Does not affect output keys.
+   */
+  name?: string;
+}
+/**
+ * Any single-color input form accepted by the value-shorthand
+ * overload of `glaze.color()`.
+ *
+ * Strings cover hex (`#rgb` / `#rrggbb` / `#rrggbbaa`, alpha dropped
+ * with a warning) and the four CSS color functions Glaze itself emits:
+ * `rgb()`, `hsl()`, `okhsl()`, `oklch()` (alpha components also dropped
+ * with a warning).
+ *
+ * The OKHSL object form `{ h, s, l }` matches Glaze's native shape
+ * (h: 0–360, s/l: 0–1). Passing 0–100 values for `s`/`l` throws with
+ * a hint to use the structured `{ hue, saturation, lightness }` form.
+ *
+ * The tuple form is `[r, g, b]` in 0–255, matching `glaze.fromRgb`'s
+ * range. Out-of-range or non-finite components throw.
+ */
+type GlazeColorValue = string | OkhslColor | readonly [number, number, number];
+/** Optional overrides for `glaze.color(value, overrides?)`. */
+interface GlazeColorOverrides {
+  /**
+   * Override hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
+   * to the extracted (or overridden) seed hue — same semantics as
+   * `RegularColorDef.hue`.
+   */
+  hue?: number | RelativeValue;
+  /** 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()`).
+   * Supports HCPair for high-contrast.
+   */
+  lightness?: HCPair<number | RelativeValue>;
+  /** 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. The default *scaling* snapshot differs by input form:
+   * string inputs preserve their light lightness and extend the dark
+   * window to `[lo, 100]` (`#000` ↔ `#fff` flip), while `OkhslColor`
+   * and `[r, g, b]` tuple inputs snapshot the full `globalConfig.
+   * lightLightness` / `globalConfig.darkLightness` windows.
+   *
+   * Pass `'fixed'` explicitly to opt back into the legacy linear, non-
+   * inverting mapping; pass `'static'` to pin the same lightness
+   * across every variant.
+   */
+  mode?: AdaptationMode;
+  /**
+   * WCAG 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`.
+   */
+  contrast?: HCPair<MinContrast>;
+  /**
+   * Optional dependency on another color. Accepts either a
+   * `GlazeColorToken` (returned by another `glaze.color()`) or a raw
+   * `GlazeColorValue` (hex / `rgb()` / `OkhslColor` / `[r, g, b]`),
+   * which is automatically wrapped in `glaze.color(value)`.
+   *
+   * 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 `hue: '+N'` / `'-N'` still anchors to the seed (the
+   *   value passed to `glaze.color()`), not the base.
+   *
+   * The base token's `.resolve()` is called lazily on first resolve and
+   * its result is captured by reference; later mutations to the base's
+   * defining call don't apply (matches existing token snapshot semantics).
+   */
+  base?: GlazeColorToken | GlazeColorValue;
+  /**
+   * Fixed opacity (0–1). Output includes alpha in the CSS value.
+   * Combining with `contrast` is not recommended (perceived lightness
+   * becomes unpredictable) — a `console.warn` is emitted in that case.
+   */
+  opacity?: number;
+  /**
+   * Optional human-readable name for the token. Used in error and
+   * warning messages (otherwise an internal name like `"value"` is
+   * used). Does not affect output keys.
+   */
+  name?: string;
+}
+/**
+ * Per-call lightness-window overrides for `glaze.color()`. Mirrors
+ * the field names from `GlazeConfig`.
+ *
+ * Defaults for `glaze.color()` vary by input form, and both fields are
+ * snapshotted from `globalConfig` at color-creation time so later
+ * `glaze.configure()` calls don't retroactively change already-created
+ * tokens (and `token.export()` round-trips byte-for-byte):
+ *
+ * - **String inputs** (`'#1a1a1a'`, `'rgb(...)'`, `'okhsl(...)'`, ...):
+ *   - `lightLightness: false` — preserve input exactly.
+ *   - `darkLightness: [globalConfig.darkLightness[0], 100]` — extended
+ *     dark window so the auto-mode dark variant can Möbius-invert all
+ *     the way up to white.
+ *
+ * - **`OkhslColor` / `[r, g, b]` tuple / structured inputs**:
+ *   - `lightLightness: globalConfig.lightLightness` — same light window
+ *     theme colors use, snapshotted at create time.
+ *   - `darkLightness: globalConfig.darkLightness` — same dark window
+ *     theme colors use, snapshotted at create time.
+ *
+ * Passing this object replaces both fields at once. To keep one
+ * field's default while overriding the other, restate the default
+ * explicitly.
+ */
+interface GlazeColorScaling {
+  /**
+   * Light-mode lightness window. Snapshotted from `globalConfig` at
+   * create time: `false` (preserve input) for string inputs, plain
+   * `globalConfig.lightLightness` for object / tuple / structured
+   * inputs. Pass `false` to preserve input lightness in light mode.
+   */
+  lightLightness?: false | [number, number];
+  /**
+   * Dark-mode lightness window. Snapshotted from `globalConfig` at
+   * create time: extended `[globalConfig.darkLightness[0], 100]` for
+   * string inputs, plain `globalConfig.darkLightness` for object /
+   * tuple / structured inputs. Pass `false` to preserve input
+   * lightness in dark mode too.
+   */
+  darkLightness?: false | [number, number];
+}
+/** Options for `GlazeColorToken.css()`. */
+interface GlazeColorCssOptions {
+  /**
+   * Custom property base name (without leading `--`). Required.
+   * Becomes the variable identifier in the output, e.g.
+   * `name: 'brand'` → `--brand-color: …`.
+   */
+  name: string;
+  /** Output color format. Default: 'rgb' (matches `theme.css` default). */
+  format?: GlazeColorFormat;
+  /**
+   * Suffix appended to the name. Default: '-color' (matches
+   * `theme.css` default).
+   */
+  suffix?: string;
 }
 /** Return type for `glaze.color()`. */
 interface GlazeColorToken {
@@ -228,11 +494,71 @@ interface GlazeColorToken {
   /**
    * Export as a tasty style-to-state binding (no color name key).
    * Uses `#name` keys and state aliases (`''`, `@dark`, etc.).
-   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions): Record<string, string>;
   /** Export as a flat JSON map (no color name key). */
   json(options?: GlazeJsonOptions): Record<string, string>;
+  /** Export as CSS custom property declarations grouped by scheme variant. */
+  css(options: GlazeColorCssOptions): GlazeCssResult;
+  /**
+   * Serialize the token as a JSON-safe object. Captures the original
+   * input value, overrides, and scaling so it can be rehydrated via
+   * `glaze.colorFrom(...)`. `base` is recursively serialized.
+   */
+  export(): GlazeColorTokenExport;
+}
+/**
+ * JSON-safe serialization of a `glaze.color()` token. Pass to
+ * `glaze.colorFrom(...)` to rehydrate.
+ */
+interface GlazeColorTokenExport {
+  /**
+   * Discriminator for the source overload that created the token.
+   * - `'value'`: created via `glaze.color(value, overrides?, scaling?)`.
+   * - `'structured'`: created via `glaze.color({ hue, saturation, ... }, scaling?)`.
+   */
+  form: 'value' | 'structured';
+  /** Original input. For `form: 'value'` this is the raw `GlazeColorValue`; for `form: 'structured'` this is the structured input. */
+  input: GlazeColorValue | GlazeColorInputExport;
+  /**
+   * Overrides recorded at creation time. `base` is recursively
+   * serialized. Only present for `form: 'value'`.
+   */
+  overrides?: GlazeColorOverridesExport;
+  /** Lightness scaling override, if any. */
+  scaling?: GlazeColorScaling;
+}
+/**
+ * Serializable shape of a structured `glaze.color({...})` input.
+ * Differs from `GlazeColorInput` only in that `base` is replaced by an
+ * `export` instead of a token reference.
+ */
+interface GlazeColorInputExport {
+  hue: number;
+  saturation: number;
+  lightness: HCPair<number>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  opacity?: number;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  contrast?: HCPair<MinContrast>;
+  name?: string;
+}
+/**
+ * Serializable shape of `GlazeColorOverrides`. `base` is replaced by
+ * its export (or left as a `GlazeColorValue` if it was originally a value).
+ */
+interface GlazeColorOverridesExport {
+  hue?: number | RelativeValue;
+  saturation?: number;
+  lightness?: HCPair<number | RelativeValue>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  contrast?: HCPair<MinContrast>;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  opacity?: number;
+  name?: string;
 }
 interface GlazeTheme {
   /** The hue seed (0–360). */
@@ -272,7 +598,7 @@ interface GlazeTheme {
    * Export as tasty style-to-state bindings.
    * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
    * Spread into component styles or register as a recipe via `configure({ recipes })`.
-   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
   /** Export as plain JSON. */
@@ -317,33 +643,64 @@ interface GlazeCssResult {
   lightContrast: string;
   darkContrast: string;
 }
+/** Options for `glaze.palette()` creation. */
+interface GlazePaletteOptions {
+  /**
+   * Name of the primary theme. The primary theme's tokens are duplicated
+   * without prefix in all exports, providing convenient short aliases
+   * alongside the prefixed versions. Can be overridden per-export.
+   *
+   * @example
+   * ```ts
+   * const palette = glaze.palette({ brand, accent }, { primary: 'brand' });
+   * palette.tokens()
+   * // → { light: { 'brand-surface': '...', 'surface': '...', 'accent-surface': '...' } }
+   * ```
+   */
+  primary?: string;
+}
+/** Options shared by palette `tokens()`, `tasty()`, and `css()` exports. */
+interface GlazePaletteExportOptions {
+  /**
+   * Prefix mode. `true` uses `"<themeName>-"`, or provide a custom map.
+   * Defaults to `true` for palette export methods.
+   * Set to `false` explicitly to disable prefixing. Colliding keys
+   * produce a console.warn and the first-written value wins.
+   */
+  prefix?: boolean | Record<string, string>;
+  /**
+   * Override the palette-level primary theme for this export.
+   * Pass a theme name to set/change the primary, or `false` to disable it.
+   * When omitted, inherits the palette-level `primary`.
+   */
+  primary?: string | false;
+}
 interface GlazePalette {
   /**
    * Export all themes as a flat token map grouped by scheme variant.
+   * Prefix defaults to `true` — all tokens are prefixed with the theme name.
+   * Inherits the palette-level `primary`; override per-call or pass `false` to disable.
    *
    * ```ts
-   * palette.tokens({ prefix: true })
-   * // → { light: { 'primary-surface': 'okhsl(...)' }, dark: { 'primary-surface': 'okhsl(...)' } }
+   * const palette = glaze.palette({ brand, accent }, { primary: 'brand' });
+   * palette.tokens()
+   * // → { light: { 'brand-surface': '...', 'surface': '...', 'accent-surface': '...' } }
    * ```
    */
-  tokens(options?: GlazeJsonOptions & {
-    prefix?: boolean | Record<string, string>;
-  }): Record<string, Record<string, string>>;
+  tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
   /**
    * Export all themes as tasty style-to-state bindings.
    * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
-   * Spread into component styles or register as a recipe via `configure({ recipes })`.
-   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   * Prefix defaults to `true`. Inherits the palette-level `primary`.
+   * @see https://tasty.style/docs
    */
-  tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
-  /** Export all themes as plain JSON. */
+  tasty(options?: GlazeTokenOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
+  /** Export all themes as plain JSON grouped by theme name. */
   json(options?: GlazeJsonOptions & {
     prefix?: boolean | Record<string, string>;
   }): Record<string, Record<string, Record<string, string>>>;
   /** Export all themes as CSS custom property declarations. */
-  css(options?: GlazeCssOptions & {
-    prefix?: boolean | Record<string, string>;
-  }): GlazeCssResult;
+  css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
 }
 //#endregion
 //#region src/glaze.d.ts
@@ -364,24 +721,24 @@ declare function glaze(hueOrOptions: number | {
 }, saturation?: number): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
-  var palette: (themes: PaletteInput) => {
-    tokens(options?: GlazeJsonOptions & {
-      prefix?: boolean | Record<string, string>;
-    }): Record<string, Record<string, string>>;
-    tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
+  var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => {
+    tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
+    tasty(options?: GlazeTokenOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
     json(options?: GlazeJsonOptions & {
       prefix?: boolean | Record<string, string>;
     }): Record<string, Record<string, Record<string, string>>>;
-    css(options?: GlazeCssOptions & {
-      prefix?: boolean | Record<string, string>;
-    }): GlazeCssResult;
+    css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
   };
   var from: (data: GlazeThemeExport) => GlazeTheme;
-  var color: (input: GlazeColorInput) => GlazeColorToken;
+  var color: {
+    (input: GlazeColorInput, scaling?: GlazeColorScaling): GlazeColorToken;
+    (value: GlazeColorValue, overrides?: GlazeColorOverrides, scaling?: GlazeColorScaling): GlazeColorToken;
+  };
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
+  var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
   var getConfig: () => GlazeConfigResolved;
   var resetConfig: () => void;
 }
@@ -394,6 +751,11 @@ declare namespace glaze {
  * computation for WCAG 2 contrast calculations, and multi-format output
  * (okhsl, rgb, hsl, oklch).
  */
+type Vec3 = [number, 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];
 /**
  * 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,26 +775,55 @@ 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 OKLab to OKHSL.
+ * 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;
 /**
  * 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];
+/**
+ * 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.
+ *
+ * Note: CSS HSL is not the same as OKHSL — it's HSL in the sRGB color space.
+ * Use this when parsing `hsl(...)` strings before passing to `srgbToOkhsl`.
+ */
+declare function hslToSrgb(h: number, s: number, l: number): [number, number, number];
 /**
  * Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
  * Returns null if the string is not a valid hex color.
+ *
+ * For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
+ * use {@link parseHexAlpha}.
  */
 declare function parseHex(hex: string): [number, number, number] | null;
+/**
+ * Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
+ * sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
+ * Returns null if the string is not a valid hex color.
+ */
+declare function parseHexAlpha(hex: string): {
+  rgb: [number, number, number];
+  alpha?: number;
+} | null;
 /**
  * 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;
 /**
- * Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
+ * 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;
@@ -447,5 +838,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 GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorScaling, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, 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 RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.cts.map