@tenphi/glaze 0.0.0-snapshot.02f3ca5

package/dist/index.d.cts

@@ -0,0 +1,916 @@
+//#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 {
+  /** 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];
+  /** Convergence threshold. Default: 1e-4. */
+  epsilon?: number;
+  /** Maximum binary-search iterations per branch. Default: 14. */
+  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.
+   */
+  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.
+   */
+  flip?: boolean;
+}
+interface FindLightnessForContrastResult {
+  /** Chosen lightness in 0–1. */
+  lightness: number;
+  /** Achieved WCAG contrast ratio. */
+  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.
+   */
+  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.
+ */
+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;
+  /**
+   * 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.
+   */
+  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.
+ */
+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];
+type MinContrast = number | ContrastPreset;
+type AdaptationMode = 'auto' | 'fixed' | 'static';
+/** A signed relative offset string, e.g. '+20' or '-15.5'. */
+type RelativeValue = `+${number}` | `-${number}`;
+/** Color format for output. */
+type GlazeColorFormat = 'okhsl' | 'rgb' | 'hsl' | 'oklch';
+/**
+ * Controls which scheme variants are generated in the export.
+ * Light is always included (it's the default).
+ */
+interface GlazeOutputModes {
+  /** Include dark scheme variants. Default: true. */
+  dark?: boolean;
+  /** Include high-contrast variants (both light-HC and dark-HC). Default: false. */
+  highContrast?: boolean;
+}
+/** Hex color string for DX hints. Runtime validation in `parseHex()`. */
+type HexColor = `#${string}`;
+/** Direct OKHSL color input. */
+interface OkhslColor {
+  h: number;
+  s: number;
+  l: number;
+}
+/** sRGB components in 0–255 (value-shorthand object form). */
+interface RgbColor {
+  r: number;
+  g: number;
+  b: number;
+}
+/** OKLCh components matching CSS `oklch(L C H)` (L/C: 0–1, H: degrees). */
+interface OklchColor {
+  l: number;
+  c: number;
+  h: number;
+}
+interface RegularColorDef {
+  /**
+   * Lightness value (0–100).
+   * - Number: absolute lightness.
+   * - String ('+N' / '-N'): relative to base color's lightness (requires `base`).
+   */
+  lightness?: HCPair<number | RelativeValue>;
+  /** Saturation factor applied to the seed saturation (0–1, default: 1). */
+  saturation?: number;
+  /**
+   * Hue override for this color.
+   * - Number: absolute hue (0–360).
+   * - String ('+N' / '-N'): relative to the theme seed hue.
+   */
+  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>;
+  /** Adaptation mode. Default: 'auto'. */
+  mode?: AdaptationMode;
+  /**
+   * 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`
+   * 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 {
+  /** Fraction of fg saturation kept in pigment (0-1). Default: 0.18. */
+  saturationFactor?: number;
+  /** Upper clamp on pigment saturation (0-1). Default: 0.25. */
+  maxSaturation?: number;
+  /** Multiplier for bg lightness → pigment lightness. Default: 0.25. */
+  lightnessFactor?: number;
+  /** [min, max] clamp for pigment lightness (0-1). Default: [0.05, 0.20]. */
+  lightnessBounds?: [number, number];
+  /**
+   * Target minimum gap between pigment lightness and bg lightness (0-1).
+   * Default: 0.05.
+   */
+  minGapTarget?: number;
+  /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
+  alphaMax?: number;
+  /**
+   * Blend weight (0-1) pulling pigment hue toward bg hue.
+   * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
+   */
+  bgHueBlend?: number;
+}
+interface ShadowColorDef {
+  type: 'shadow';
+  /**
+   * Background color name — the surface the shadow sits on.
+   * Must reference a non-shadow color in the same theme.
+   */
+  bg: string;
+  /**
+   * Foreground color name for tinting and intensity modulation.
+   * Must reference a non-shadow color in the same theme.
+   * Omit for achromatic shadow at full user-specified intensity.
+   */
+  fg?: string;
+  /**
+   * Shadow intensity, 0-100.
+   * Supports [normal, highContrast] pair.
+   */
+  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;
+}
+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 {
+  /** OKHSL hue (0–360). */
+  h: number;
+  /** OKHSL saturation (0–1). */
+  s: number;
+  /** OKHSL lightness (0–1). */
+  l: number;
+  /** Opacity (0–1). Default: 1. */
+  alpha: number;
+}
+/** Fully resolved color across all scheme variants. */
+interface ResolvedColor {
+  name: string;
+  light: ResolvedColorVariant;
+  dark: ResolvedColorVariant;
+  lightContrast: ResolvedColorVariant;
+  darkContrast: ResolvedColorVariant;
+  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
+  mode?: AdaptationMode;
+}
+interface GlazeConfig {
+  /** Light scheme lightness window [lo, hi]. Default: [10, 100]. */
+  lightLightness?: [number, number];
+  /** Dark scheme lightness window [lo, hi]. Default: [15, 95]. */
+  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;
+    highContrast?: string;
+  };
+  /** Which scheme variants to include in exports. Default: both true. */
+  modes?: GlazeOutputModes;
+  /** 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.
+   *
+   * When enabled (default `true`), the solver searches the requested
+   * lightness 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
+   * 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).
+   */
+  autoFlip?: boolean;
+}
+interface GlazeConfigResolved {
+  lightLightness: [number, number];
+  darkLightness: [number, number];
+  darkDesaturation: number;
+  darkCurve: HCPair<number>;
+  states: {
+    dark: string;
+    highContrast: string;
+  };
+  modes: Required<GlazeOutputModes>;
+  shadowTuning?: ShadowTuning;
+  autoFlip: boolean;
+}
+/** Serialized theme configuration (no resolved values). */
+interface GlazeThemeExport {
+  hue: number;
+  saturation: number;
+  colors: ColorMap;
+}
+/** Input for `glaze.shadow()` standalone factory. */
+interface GlazeShadowInput {
+  /**
+   * Background color — accepts any `GlazeColorValue` form: hex
+   * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
+   * / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
+   * `{ l, c, h }`). 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 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).
+ *
+ * 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.
+ * - `{ 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;
+/** 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. 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`.
+   *
+   * 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 / CSS strings / `{ r, g, b }` / `{ h, s, l }` / …),
+   * 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):
+ *
+ * - **Value-shorthand** (hex / `rgb()` / `hsl()` / `okhsl()` / `oklch()`
+ *   strings, `{ r, g, b }`, `{ h, s, l }`, `{ l, c, h }`):
+ *   - `lightLightness: false` — preserve input exactly.
+ *   - `darkLightness: globalConfig.darkLightness` — snapshotted at create time.
+ *
+ * - **Structured inputs** (`{ hue, saturation, lightness, ... }`):
+ *   - `lightLightness: globalConfig.lightLightness` — theme light window.
+ *   - `darkLightness: globalConfig.darkLightness` — theme dark window.
+ *
+ * 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 at create time: `false`
+   * (preserve input) for value-shorthand inputs; plain
+   * `globalConfig.lightLightness` for structured inputs only. Pass
+   * `false` to preserve input lightness in light mode.
+   */
+  lightLightness?: false | [number, number];
+  /**
+   * Dark-mode lightness window. Snapshotted from `globalConfig` at
+   * create time for value-shorthand and 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 {
+  /** Resolve the color across all scheme variants. */
+  resolve(): ResolvedColor;
+  /** Export as a flat token map (no color name key). */
+  token(options?: GlazeTokenOptions): Record<string, string>;
+  /**
+   * Export as a tasty style-to-state binding (no color name key).
+   * Uses `#name` keys and state aliases (`''`, `@dark`, etc.).
+   * @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;
+  /**
+   * Auto-flip setting snapshotted at creation time from
+   * `globalConfig.autoFlip`. Only present when it differs from the
+   * global default (`true`). Rehydrated tokens use this value instead
+   * of whatever is current in `globalConfig`.
+   */
+  autoFlip?: boolean;
+}
+/**
+ * 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). */
+  readonly hue: number;
+  /** The saturation seed (0–100). */
+  readonly saturation: number;
+  /** Add/replace colors (additive merge with existing definitions). */
+  colors(defs: ColorMap): void;
+  /** Get a color definition by name. */
+  color(name: string): ColorDef | undefined;
+  /** Set a single color definition. */
+  color(name: string, def: ColorDef): void;
+  /** Remove one or more color definitions. */
+  remove(names: string | string[]): void;
+  /** Check if a color is defined. */
+  has(name: string): boolean;
+  /** List all defined color names. */
+  list(): string[];
+  /** Clear all color definitions. */
+  reset(): void;
+  /** Export the theme configuration as a JSON-safe object. */
+  export(): GlazeThemeExport;
+  /** Create a child theme inheriting all color definitions. */
+  extend(options: GlazeExtendOptions): GlazeTheme;
+  /** Resolve all colors and return the result map. */
+  resolve(): Map<string, ResolvedColor>;
+  /**
+   * Export as a flat token map grouped by scheme variant.
+   *
+   * ```ts
+   * theme.tokens()
+   * // → { light: { surface: 'okhsl(...)' }, dark: { surface: 'okhsl(...)' } }
+   * ```
+   */
+  tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
+  /**
+   * 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://tasty.style/docs
+   */
+  tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
+  /** Export as plain JSON. */
+  json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
+  /** Export as CSS custom property declarations. */
+  css(options?: GlazeCssOptions): GlazeCssResult;
+}
+interface GlazeExtendOptions {
+  hue?: number;
+  saturation?: number;
+  colors?: ColorMap;
+}
+interface GlazeTokenOptions {
+  /** Prefix mode. `true` uses "<themeName>-", or provide a custom map. */
+  prefix?: boolean | Record<string, string>;
+  /** Override state aliases for this export. */
+  states?: {
+    dark?: string;
+    highContrast?: string;
+  };
+  /** Override which scheme variants to include. */
+  modes?: GlazeOutputModes;
+  /** Output color format. Default: 'okhsl'. */
+  format?: GlazeColorFormat;
+}
+interface GlazeJsonOptions {
+  /** Override which scheme variants to include. */
+  modes?: GlazeOutputModes;
+  /** Output color format. Default: 'okhsl'. */
+  format?: GlazeColorFormat;
+}
+interface GlazeCssOptions {
+  /** Output color format. Default: 'rgb'. */
+  format?: GlazeColorFormat;
+  /** Suffix appended to each CSS custom property name. Default: '-color'. */
+  suffix?: string;
+}
+/** CSS custom property declarations grouped by scheme variant. */
+interface GlazeCssResult {
+  light: string;
+  dark: string;
+  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
+   * const palette = glaze.palette({ brand, accent }, { primary: 'brand' });
+   * palette.tokens()
+   * // → { light: { 'brand-surface': '...', 'surface': '...', 'accent-surface': '...' } }
+   * ```
+   */
+  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.).
+   * Prefix defaults to `true`. Inherits the palette-level `primary`.
+   * @see https://tasty.style/docs
+   */
+  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 & GlazePaletteExportOptions): GlazeCssResult;
+}
+//#endregion
+//#region src/glaze.d.ts
+type PaletteInput = Record<string, GlazeTheme>;
+/**
+ * Create a single-hue glaze theme.
+ *
+ * @example
+ * ```ts
+ * const primary = glaze({ hue: 280, saturation: 80 });
+ * // or shorthand:
+ * const primary = glaze(280, 80);
+ * ```
+ */
+declare function glaze(hueOrOptions: number | {
+  hue: number;
+  saturation: number;
+}, saturation?: number): GlazeTheme;
+declare namespace glaze {
+  var configure: (config: GlazeConfig) => void;
+  var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
+  var from: (data: GlazeThemeExport) => GlazeTheme;
+  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;
+}
+//#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).
+ */
+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.
+ */
+declare function okhslToLinearSrgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * Compute relative luminance Y from linear sRGB channels.
+ * Per WCAG 2: Y = 0.2126·R + 0.7152·G + 0.0722·B
+ */
+declare function relativeLuminanceFromLinearRgb(rgb: [number, number, number]): number;
+/**
+ * WCAG 2 contrast ratio from two luminance values.
+ */
+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];
+/**
+ * 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 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.
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+//#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 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 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 };
+//# sourceMappingURL=index.d.cts.map