types.ts

/**
 * Glaze type definitions.
 */

import type { ApcaPreset, ContrastPreset } from './contrast-solver';

// ============================================================================
// Value types
// ============================================================================

/** A value or [normal, high-contrast] pair. */
export type HCPair<T> = T | [T, T];

/** Bare WCAG contrast target: a ratio number or a named preset. */
export 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 or preset), 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] }`, `{ apca: ['content', 'body'] }`).
 */
export type ContrastSpec =
  | number
  | ContrastPreset
  | { wcag: HCPair<number | ContrastPreset> }
  | { apca: HCPair<number | ApcaPreset> };

// ============================================================================
// Color role
// ============================================================================

/**
 * The semantic role a color plays against its base, used to fix APCA contrast
 * polarity (which side is the foreground vs the background). WCAG is
 * symmetric, so role never changes WCAG results.
 */
export type Role = 'text' | 'surface' | 'border';

/**
 * Any string accepted as a `role`. Canonical values plus aliases normalized by
 * `normalizeRole` (see `roles.ts`): `surface` (bg/background/fill/canvas/
 * paper/layer), `text` (fg/foreground/content/ink/label/stroke), `border`
 * (divider/outline/separator/hairline/rule).
 */
export type RoleInput =
  | Role
  | 'bg'
  | 'background'
  | 'fill'
  | 'canvas'
  | 'paper'
  | 'layer'
  | 'fg'
  | 'foreground'
  | 'content'
  | 'ink'
  | 'label'
  | 'stroke'
  | 'divider'
  | 'outline'
  | 'separator'
  | 'hairline'
  | 'rule';

export type AdaptationMode = 'auto' | 'fixed' | 'static';

/** A signed relative offset string, e.g. '+20' or '-15.5'. */
export 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.
 */
export 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).
 */
export type ToneValue = number | RelativeValue | ExtremeValue;

/** Color format for output. */
export type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';

/**
 * Controls which scheme variants are generated in the export.
 * Light is always included (it's the default).
 */
export interface GlazeOutputModes {
  /** Include dark scheme variants. Default: true. */
  dark?: boolean;
  /**
   * Include high-contrast variants (both light-HC and dark-HC). Default: false.
   *
   * Independent of `contrastLevel` — the level positions the normal variants
   * while these stay the true high-contrast resolution, so the two compose. The
   * exception is a global level of 100, where the normal variants already *are*
   * the high-contrast ones: the tier would duplicate them and is dropped.
   * @see GlazeConfig.contrastLevel
   */
  highContrast?: boolean;
}

// ============================================================================
// Color definitions
// ============================================================================

/** Hex color string for DX hints. Runtime validation in `parseHex()`. */
export type HexColor = `#${string}`;

/** Direct OKHSL color input. */
export interface OkhslColor {
  h: number;
  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).
 */
export interface OkhstColor {
  h: number;
  s: number;
  t: number;
}

/** sRGB components in 0–255 (value-shorthand object form). */
export interface RgbColor {
  r: number;
  g: number;
  b: number;
}

/** OKLCh components matching CSS `oklch(L C H)` (L/C: 0–1, H: degrees). */
export interface OklchColor {
  l: number;
  c: number;
  h: number;
}

export interface RegularColorDef {
  /**
   * Seed this color from a literal color instead of from the theme.
   *
   * Accepts the same values as `glaze.color()` — hex, `rgb()`, `hsl()`,
   * `okhsl()`, `okhst()`, `oklch()`, or a value object. It supplies three
   * things at once: `hue`, `tone`, and — unlike every other color in a theme —
   * an **absolute saturation** rather than a factor of the seed. That last
   * part is the point: a color can now be more saturated than its theme, so
   * honoring a brand color no longer means re-seeding the whole theme to reach
   * it.
   *
   * The **light, normal-contrast** variant reproduces the value exactly
   * (a local `lightTone: false`, matching the value-shorthand form of
   * `glaze.color()`). Dark and high-contrast variants adapt as usual — they
   * are where readability outranks fidelity, and a color pinned across every
   * scheme would defeat both. A `contrast` floor still applies everywhere and
   * still only moves the color when the authored value misses it.
   *
   * Sibling fields override what the value supplied, so
   * `{ from: '#2F5BFF', hue: 300 }` keeps its saturation and tone but rotates
   * the hue.
   */
  from?: GlazeColorValue;
  /**
   * 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).
   *
   * Defaults to the tone of `from` when that is set.
   */
  tone?: HCPair<ToneValue>;
  /**
   * Saturation factor applied to the seed saturation (0–1, default: 1).
   *
   * With `from`, an explicit value here is still a factor of the seed and
   * overrides the absolute saturation the color carried.
   */
  saturation?: number;
  /**
   * Hue override for this color.
   * - Number: absolute hue (0–360).
   * - String ('+N' / '-N'): relative to the theme seed hue.
   */
  hue?: number | RelativeValue;
  /**
   * Dark-scheme hue override. Applies to the `dark` and `darkContrast`
   * variants; falls back to `hue` when omitted.
   * - Number: absolute hue (0–360).
   * - String ('+N' / '-N'): relative to the theme's **dark** seed hue
   *   (`GlazeTheme.darkHue`, itself defaulting to the light seed hue).
   *
   * Ignored under `mode: 'static'`, which pins one value across all schemes.
   */
  darkHue?: number | RelativeValue;
  /**
   * Dark-scheme saturation factor (0–1) applied to the dark seed
   * saturation. Applies to the `dark` and `darkContrast` variants; falls
   * back to `saturation` when omitted.
   *
   * When set, the global `darkDesaturation` reduction is **not** applied on
   * top — the resulting saturation is taken literally. Ignored under
   * `mode: 'static'`.
   */
  darkSaturation?: number;

  /** Name of another color in the same theme (dependent color). */
  base?: string;
  /**
   * 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. If the mirrored target is also
   *   out of range, keep the original delta and clamp on the authored side.
   * - `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.
   */
  autoFlip?: 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 tone, so `contrast` and `opacity`
   * should not be combined (a console.warn is emitted).
   */
  opacity?: number;

  /**
   * Per-color override for the hue-independent "safe" chroma limit used in
   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
   * Falls through to the per-theme / per-token `pastel` override when omitted.
   * @see GlazeConfigOverride.pastel
   */
  pastel?: boolean;

  /**
   * Semantic role against `base`: how this color is used. Fixes APCA contrast
   * polarity (the argument order in `apcaContrast`). WCAG is symmetric so it
   * never affects WCAG results.
   *
   * Resolution: explicit `role` wins; else inferred from the color name when
   * `inferRole` is enabled (default); else the opposite of the base's role;
   * else defaults to `'text'` (foreground).
   */
  role?: RoleInput;

  /**
   * 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). */
export 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;
}

export 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;

  /**
   * Per-color override for the hue-independent "safe" chroma limit used in
   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
   * Falls through to the per-theme / per-token `pastel` override when omitted.
   * @see GlazeConfigOverride.pastel
   */
  pastel?: boolean;

  /**
   * 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;
}

export 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 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.
   * A bare number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the
   * metric. Supports [normal, highContrast] pair.
   */
  contrast?: HCPair<ContrastSpec>;

  /**
   * Per-color override for the hue-independent "safe" chroma limit used in
   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
   * Falls through to the per-theme / per-token `pastel` override when omitted.
   * @see GlazeConfigOverride.pastel
   */
  pastel?: boolean;

  /**
   * Semantic role of the mixed result against `base`. Same semantics as
   * `RegularColorDef.role` (fixes APCA polarity). Resolution and defaults
   * are identical.
   */
  role?: RoleInput;

  /**
   * 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;
}

export type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;

export type ColorMap = Record<string, ColorDef>;

// ============================================================================
// Resolved internal types
// ============================================================================

/**
 * 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.
 */
export interface ResolvedColorVariant {
  /** OKHSL hue (0–360). */
  h: number;
  /** OKHSL saturation (0–1). */
  s: number;
  /** Canonical tone (0–1, reference eps). */
  t: number;
  /** Opacity (0–1). Default: 1. */
  alpha: number;
  /**
   * Effective `pastel` flag used while resolving this variant (author def or
   * config fallback). Carried on the variant so output formatting matches the
   * gamut mapping applied during resolution.
   */
  pastel?: boolean;
}

/** Fully resolved color across all scheme variants. */
export interface ResolvedColor {
  name: string;
  light: ResolvedColorVariant;
  dark: ResolvedColorVariant;
  lightContrast: ResolvedColorVariant;
  darkContrast: ResolvedColorVariant;
  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
  mode?: AdaptationMode;
}

// ============================================================================
// Configuration
// ============================================================================

/**
 * 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.
 */
export type ToneWindow =
  | false
  | [number, number]
  | { lo: number; hi: number; eps: number };

export interface GlazeConfig {
  /** 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;
  /**
   * State alias names for Tasty token export. Default to media-query states
   * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`)
   * so tokens react to the OS preference without registering custom states.
   */
  states?: {
    dark?: string;
    highContrast?: string;
  };
  /**
   * Which scheme variants to include in exports. Defaults: `dark: true`,
   * `highContrast: false`.
   */
  modes?: GlazeOutputModes;
  /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
  shadowTuning?: ShadowTuning;
  /**
   * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
   * contrast (`100`), or `'auto'` (the default) to take the authored normal
   * entries as-is.
   *
   * With a number, Glaze resolves the `light` / `dark` variants *at* that level.
   * That is all it does: `lightContrast` / `darkContrast` stay the true
   * high-contrast resolution at every level, and `modes.highContrast` alone
   * decides whether they are emitted. Level `0` therefore reproduces `'auto'`
   * bit for bit. At `100` the normal variants *are* the high-contrast ones, so a
   * separate tier would duplicate them and a global level of 100 drops it.
   *
   * The level interpolates all three things that make high contrast differ:
   * authored `[normal, highContrast]` pairs, the tone-window widening, and
   * the `AA → AAA` / APCA `+15 Lc` escalation. Contrast floors are re-solved
   * at the interpolated target, so every level is a solution rather than an
   * approximation, and a color keeps to one side of its base as the level moves.
   *
   * Pass `'auto'` to leave manual mode; `configure()` never clears a field by
   * omission. See `docs/api.md` for the ramp's edge cases (un-interpolable
   * pairs, side changes) and the export-freeze rule.
   *
   * @default 'auto'
   */
  contrastLevel?: number | 'auto';
  /**
   * Automatically flip tone direction when contrast can't be met.
   *
   * When enabled (default `true`), the solver searches the requested
   * 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 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 tone is pinned to its extreme (never
   * falls back to the originally requested tone).
   */
  autoFlip?: boolean;
  /**
   * If true (default), infer a color's `role` from its name when no explicit
   * `role` is set. Set to `false` to opt out of name-based inference (the
   * base-opposite and default-foreground fallbacks still apply).
   * @default true
   */
  inferRole?: boolean;
}

export interface GlazeConfigResolved {
  lightTone: ToneWindow;
  darkTone: ToneWindow;
  darkDesaturation: number;
  states: {
    dark: string;
    highContrast: string;
  };
  modes: Required<GlazeOutputModes>;
  shadowTuning?: ShadowTuning;
  autoFlip: boolean;
  /**
   * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
   * the authored normal entries as-is.
   * @see GlazeConfig.contrastLevel
   */
  contrastLevel: number | 'auto';
  /**
   * Instance-level pastel default (`def.pastel ?? config.pastel`).
   * Not set via `glaze.configure()` — only via per-theme / per-token
   * `GlazeConfigOverride` (default `false`).
   */
  pastel: boolean;
  inferRole: 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
 * (`pastel` is instance-only and defaults to `false` when omitted).
 *
 * `false` for a tone window disables clamping (full range at reference eps).
 */
export interface GlazeConfigOverride {
  /** 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;
  /** Whether to auto-flip tone when contrast can't be met. */
  autoFlip?: boolean;
  /**
   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out of a
   * global level and take the authored normal entries as-is. Either way the
   * instance keeps its high-contrast tier; a per-instance level never changes
   * which modes are emitted.
   *
   * Only an instance-authored level is frozen into `.export()` snapshots — a
   * level inherited from the global config is treated as a live preference and
   * re-read at restore time.
   *
   * @see GlazeConfig.contrastLevel
   */
  contrastLevel?: number | 'auto';
  /**
   * Instance-level pastel default for colors that omit per-color `pastel`.
   * Not available on `glaze.configure()` — set here or per-color.
   * @default false
   */
  pastel?: boolean;
  /**
   * If true, infer a color's `role` from its name when no explicit `role` is
   * set. Falls through to the live global at resolve time when omitted.
   */
  inferRole?: boolean;
  /**
   * Shadow tuning defaults. Only meaningful for themes; harmless on
   * standalone color tokens.
   */
  shadowTuning?: ShadowTuning;
}

// ============================================================================
// Serialization
// ============================================================================

/**
 * Current authoring-export schema version. Bump when the export shape
 * changes in a non-compatible way. Written on every `.export()` snapshot.
 */
export const GLAZE_EXPORT_VERSION = 1 as const;

/** Literal type of {@link GLAZE_EXPORT_VERSION}. */
export type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;

/** Discriminator for authoring export snapshots. */
export type GlazeExportKind = 'theme' | 'color' | 'palette';

/** Serialized theme configuration (no resolved values). */
export interface GlazeThemeExport {
  /** Snapshot kind. Always written by `theme.export()`; optional on legacy hand-written configs. */
  kind?: 'theme';
  /** Schema version. Always written by `theme.export()`; optional on legacy configs. */
  version?: number;
  hue: number;
  saturation: number;
  /** Dark-scheme seed hue (0–360). Omitted when the theme reuses `hue`. */
  darkHue?: number;
  /** Dark-scheme seed saturation (0–100). Omitted when the theme reuses `saturation`. */
  darkSaturation?: number;
  colors: ColorMap;
  /**
   * Effective config freeze from `.export()` —
   * `getConfig() ∪ instance local ∪ exportArg`. May be sparse on legacy
   * snapshots (omitted fields fall through to the live global at restore).
   */
  config?: GlazeConfigOverride;
}

// ============================================================================
// Standalone shadow
// ============================================================================

/** Input for `glaze.shadow()` standalone factory. */
export 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;
}

// ============================================================================
// Standalone color token
// ============================================================================

/** Input for the structured `glaze.color()` overload. */
export interface GlazeColorInput {
  hue: number;
  saturation: number;
  tone: HCPair<number | ExtremeValue>;
  saturationFactor?: number;
  /**
   * Dark-scheme hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
   * to the dark seed hue, which defaults to `hue`. Falls back to `hue`.
   */
  darkHue?: number | RelativeValue;
  /** Dark-scheme seed saturation (0–100). Defaults to `saturation`. */
  darkSaturation?: number;
  /** Dark-scheme multiplier on the dark seed (0–1). Defaults to `saturationFactor`. */
  darkSaturationFactor?: number;
  mode?: AdaptationMode;
  /** Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. */
  autoFlip?: boolean;
  /**
   * Fixed opacity (0–1). Output includes alpha in the CSS value.
   * 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 `tone`
   * anchor to the base per scheme.
   */
  base?: GlazeColorToken | GlazeColorValue;
  /**
   * Contrast floor against `base`. Requires `base` to be set. A bare
   * number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
   */
  contrast?: HCPair<ContrastSpec>;
  /**
   * 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-color override for the hue-independent "safe" chroma limit used in
   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
   * Falls through to the per-theme / per-token `pastel` override when omitted.
   * @see GlazeConfigOverride.pastel
   */
  pastel?: boolean;

  /**
   * Semantic role against `base` / the literal seed: how this token is used.
   * Fixes APCA contrast polarity. Same resolution chain as
   * `RegularColorDef.role` (explicit → name inference → opposite of base →
   * `'text'`). For standalone tokens the name is internal, so set `role`
   * explicitly or rely on the base-opposite / foreground default.
   */
  role?: RoleInput;
}

/**
 * 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.
 * - `{ 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.
 */
export type GlazeColorValue =
  | string
  | OkhslColor
  | OkhstColor
  | RgbColor
  | OklchColor;

/** Color overrides for the `from` and value-shorthand inputs. */
export 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;
  /**
   * Dark-scheme hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
   * to the dark seed hue, which defaults to the (possibly overridden) seed
   * hue. Falls back to `hue` when omitted.
   */
  darkHue?: number | RelativeValue;
  /**
   * Dark-scheme seed saturation (0–100). Defaults to `saturation`. When set,
   * the global `darkDesaturation` reduction is not applied on top.
   */
  darkSaturation?: number;
  /**
   * Dark-scheme multiplier on the dark seed (0–1). Defaults to
   * `saturationFactor`. When set, the global `darkDesaturation` reduction is
   * not applied on top.
   */
  darkSaturationFactor?: number;
  /**
   * 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.
   */
  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. Value-shorthand inputs (strings and literal objects)
   * preserve light tone via a local `lightTone: false` default; other
   * omitted config fields fall through to the live global at resolve
   * time. Structured `{ hue, saturation, tone }` form also falls
   * through for both tone windows unless overridden.
   *
   * Pass `'fixed'` explicitly to opt back into the linear, non-
   * inverting mapping; pass `'static'` to pin the same tone
   * across every variant.
   */
  mode?: AdaptationMode;

  /**
   * Flip out-of-bounds results (relative `tone` overshoot / unmet
   * `contrast`) to the opposite side instead of clamping. Defaults to
   * the global `autoFlip`.
   */
  autoFlip?: 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`
   * (bare number/preset = WCAG; `{ wcag }` / `{ apca }` to pick the metric).
   */
  contrast?: HCPair<ContrastSpec>;

  /**
   * 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 `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`/`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
   * 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 tone
   * 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-color override for the hue-independent "safe" chroma limit used in
   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
   * Falls through to the per-theme / per-token `pastel` override when omitted.
   * @see GlazeConfigOverride.pastel
   */
  pastel?: boolean;

  /**
   * Semantic role against `base` / the literal seed: how this token is used.
   * Fixes APCA contrast polarity. Same resolution chain as
   * `RegularColorDef.role`.
   */
  role?: RoleInput;
}

/**
 * Object input for `glaze.color()` that carries a raw color value plus
 * optional color overrides in the same object.
 *
 * ```ts
 * glaze.color({ from: '#1a1a2e', base: bg, contrast: 'AA' })
 * glaze.color({ from: { r: 38, g: 252, b: 178 }, tone: '+10' })
 * ```
 */
export interface GlazeFromInput extends GlazeColorOverrides {
  /** The source color value. Accepts the same forms as a bare `GlazeColorValue`. */
  from: GlazeColorValue;
}

/** Options for `GlazeColorToken.css()`. */
export 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: 'oklch'. */
  format?: GlazeColorFormat;
  /**
   * Suffix appended to the name. Default: '-color' (matches
   * `theme.css` default).
   */
  suffix?: string;
  /**
   * Emit hue as a separate custom property, referenced via `var()`.
   * Requires `format: 'oklch'` and a pastel token. oklch + all-pastel only.
   */
  splitHue?: boolean;
}

/** Return type for `glaze.color()`. */
export 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 (`''`, `'@media(prefers-color-scheme: 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;
  /**
   * Export as W3C DTCG color tokens (one per scheme variant, no color name
   * key). Each entry is a full `{ $type: 'color', $value }` token.
   * @see https://www.designtokens.org/
   */
  dtcg(options?: GlazeDtcgOptions): GlazeColorDtcgResult;
  /**
   * Export as a single W3C DTCG Resolver-Module document for this color,
   * keyed by `name` across all scheme variants. `name` is required.
   * @see https://www.designtokens.org/
   */
  dtcgResolver(
    options: GlazeColorDtcgResolverOptions,
  ): GlazeDtcgResolverDocument;
  /**
   * Export as a Tailwind CSS v4 `@theme` block (light baseline) plus dark /
   * high-contrast overrides. Returns a single ready-to-paste CSS string.
   * `name` is required (forms `--color-<name>`).
   * @see https://tailwindcss.com/docs/theme
   */
  tailwind(options: GlazeColorTailwindOptions): string;
  /**
   * Serialize the token as a JSON-safe object. Captures the original
   * input value, overrides, and config so it can be rehydrated via
   * `glaze.colorFrom(...)`. `base` is recursively serialized.
   * Optional `override` is merged over the instance local at export time.
   */
  export(override?: GlazeConfigOverride): GlazeColorTokenExport;
}

/**
 * JSON-safe serialization of a `glaze.color()` token. Pass to
 * `glaze.colorFrom(...)` to rehydrate.
 */
export interface GlazeColorTokenExport {
  /** Snapshot kind. Always written by `token.export()`; optional on legacy snapshots. */
  kind?: 'color';
  /** Schema version. Always written by `token.export()`; optional on legacy snapshots. */
  version?: number;
  /**
   * Discriminator for the source overload that created the token.
   * - `'value'`: created via `glaze.color(value)` or `glaze.color({ from, ...overrides })`.
   * - `'structured'`: created via `glaze.color({ hue, saturation, ... })`.
   */
  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;
  /**
   * Effective config freeze from `.export()` — `getConfig() ∪ local ∪
   * exportArg` at call time. Used by `glaze.colorFrom()` to pin
   * deterministic behavior across later `configure()` calls.
   */
  config?: GlazeConfigOverride;
}

/**
 * JSON-safe serialization of a `glaze.palette()` composition.
 * Pass to `glaze.paletteFrom(...)` to rehydrate.
 */
export interface GlazePaletteExport {
  /** Snapshot kind. Always written by `palette.export()`. */
  kind?: 'palette';
  /** Schema version. Always written by `palette.export()`. */
  version?: number;
  /** Per-theme authoring snapshots keyed by theme name. */
  themes: Record<string, GlazeThemeExport>;
  /** Primary theme name, if set on the palette. */
  primary?: string;
}

/**
 * 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.
 */
export interface GlazeColorInputExport {
  hue: number;
  saturation: number;
  tone: HCPair<number | ExtremeValue>;
  saturationFactor?: number;
  darkHue?: number | RelativeValue;
  darkSaturation?: number;
  darkSaturationFactor?: number;
  mode?: AdaptationMode;
  autoFlip?: boolean;
  opacity?: number;
  base?: GlazeColorTokenExport | GlazeColorValue;
  contrast?: HCPair<ContrastSpec>;
  name?: string;
  pastel?: boolean;
  role?: RoleInput;
}

/**
 * Serializable shape of `GlazeColorOverrides`. `base` is replaced by
 * its export (or left as a `GlazeColorValue` if it was originally a value).
 */
export interface GlazeColorOverridesExport {
  hue?: number | RelativeValue;
  saturation?: number;
  darkHue?: number | RelativeValue;
  darkSaturation?: number;
  darkSaturationFactor?: number;
  tone?: HCPair<ToneValue>;
  saturationFactor?: number;
  mode?: AdaptationMode;
  autoFlip?: boolean;
  contrast?: HCPair<ContrastSpec>;
  base?: GlazeColorTokenExport | GlazeColorValue;
  opacity?: number;
  name?: string;
  pastel?: boolean;
  role?: RoleInput;
}

// ============================================================================
// Theme API
// ============================================================================

/**
 * The hue/saturation seed pair a theme resolves against.
 *
 * `darkHue` / `darkSaturation` are a separate seed for the `dark` and
 * `darkContrast` variants; each falls back to its light counterpart. Setting
 * `darkSaturation` opts the theme out of the global `darkDesaturation`
 * reduction — the authored value is used literally.
 */
export interface GlazeThemeSeed {
  /** Light-scheme hue seed (0–360). */
  hue: number;
  /** Light-scheme saturation seed (0–100). */
  saturation: number;
  /** Dark-scheme hue seed (0–360). Defaults to `hue`. */
  darkHue?: number;
  /** Dark-scheme saturation seed (0–100). Defaults to `saturation`. */
  darkSaturation?: number;
}

export interface GlazeTheme {
  /** The hue seed (0–360). */
  readonly hue: number;
  /** The saturation seed (0–100). */
  readonly saturation: number;
  /** The dark-scheme hue seed (0–360), or `undefined` when `hue` is reused. */
  readonly darkHue: number | undefined;
  /** The dark-scheme saturation seed (0–100), or `undefined` when `saturation` is reused. */
  readonly darkSaturation: number | undefined;
  /** 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. */
  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(override?: GlazeConfigOverride): 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 (`''`, `'@media(prefers-color-scheme: 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;

  /**
   * Export as W3C Design Tokens Format Module (2025.10) documents, one per
   * scheme variant. Consumable by Figma, Tokens Studio, Style Dictionary,
   * Terrazzo, and any DTCG-compatible tool.
   * @see https://www.designtokens.org/
   */
  dtcg(options?: GlazeDtcgOptions): GlazeDtcgResult;

  /**
   * Export as a single W3C DTCG Resolver-Module document describing every
   * scheme variant as one `sets` entry plus a single `scheme` modifier with a
   * context per variant. Consumable by resolver tools such as Dispersa.
   * @see https://www.designtokens.org/
   */
  dtcgResolver(options?: GlazeDtcgResolverOptions): GlazeDtcgResolverDocument;

  /**
   * Export as a Tailwind CSS v4 `@theme` block (light baseline) plus dark /
   * high-contrast overrides under configurable selectors. Returns a single
   * ready-to-paste CSS string.
   * @see https://tailwindcss.com/docs/theme
   */
  tailwind(options?: GlazeTailwindOptions): string;
}

export interface GlazeExtendOptions {
  hue?: number;
  saturation?: number;
  /** Replace the dark-scheme hue seed (0–360). Defaults to the parent's. */
  darkHue?: number;
  /** Replace the dark-scheme saturation seed (0–100). Defaults to the parent's. */
  darkSaturation?: number;
  colors?: ColorMap;
  /** Config override for the child theme. Merged with the parent's override. */
  config?: GlazeConfigOverride;
}

// ============================================================================
// Palette API
// ============================================================================

export 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: 'oklch'. */
  format?: GlazeColorFormat;
  /**
   * Emit hue as a separate custom property, referenced via `var()`.
   * Requires `format: 'oklch'` and every color to be pastel.
   */
  splitHue?: boolean;
  /**
   * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
   * Palette export auto-derives this from the theme name.
   */
  name?: string;
}

export interface GlazeJsonOptions {
  /** Override which scheme variants to include. */
  modes?: GlazeOutputModes;
  /** Output color format. Default: 'oklch'. */
  format?: GlazeColorFormat;
}

export interface GlazeCssOptions {
  /** Output color format. Default: 'oklch'. */
  format?: GlazeColorFormat;
  /** Suffix appended to each CSS custom property name. Default: '-color'. */
  suffix?: string;
  /**
   * Emit hue as a separate custom property, referenced via `var()`.
   * Requires `format: 'oklch'` and every color to be pastel.
   */
  splitHue?: boolean;
  /**
   * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
   * Palette export auto-derives this from the theme name.
   */
  name?: string;
}

/** CSS custom property declarations grouped by scheme variant. */
export interface GlazeCssResult {
  light: string;
  dark: string;
  lightContrast: string;
  darkContrast: string;
}

// ============================================================================
// DTCG & Tailwind export types
// ============================================================================

/**
 * Color space used for DTCG `$value` color objects.
 * @see https://www.designtokens.org/
 */
export type DtcgColorSpace = 'srgb' | 'oklch';

/**
 * A DTCG color `$value` in the sRGB color space: gamma sRGB components in
 * 0–1 plus a 6-digit `hex` hint. Universally understood by Figma, Tokens
 * Studio, Style Dictionary, and every DTCG reader.
 */
export interface DtcgSrgbColorValue {
  colorSpace: 'srgb';
  components: [number, number, number];
  hex: HexColor;
  /** Opacity 0–1. Omitted when fully opaque (alpha = 1). */
  alpha?: number;
}

/**
 * A DTCG color `$value` in the OKLCH color space: `[L, C, H]` components
 * (L/C: 0–1, H: degrees). Wide-gamut and Glaze-native; no `hex` is emitted.
 */
export interface DtcgOklchColorValue {
  colorSpace: 'oklch';
  components: [number, number, number];
  /** Opacity 0–1. Omitted when fully opaque (alpha = 1). */
  alpha?: number;
}

/** A DTCG `$value` for a color token, in either supported color space. */
export type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;

/**
 * A single W3C DTCG color token: `{ $type: 'color', $value }`.
 * `$description` is optional and not populated by Glaze today.
 */
export interface DtcgColorToken {
  $type: 'color';
  $value: DtcgColorValue;
  $description?: string;
}

/**
 * A W3C Design Tokens Format Module (2025.10) token tree for one scheme.
 * Glaze emits one document per scheme variant — the most tool-compatible
 * convention (one file per Style Dictionary theme / Tokens Studio set /
 * Figma variable mode).
 */
export type DtcgDocument = Record<string, DtcgColorToken>;

/** DTCG token documents grouped by scheme variant. Light is always present. */
export interface GlazeDtcgResult {
  light: DtcgDocument;
  dark?: DtcgDocument;
  lightContrast?: DtcgDocument;
  darkContrast?: DtcgDocument;
}

/** A single DTCG color token grouped by scheme variant (standalone tokens). */
export interface GlazeColorDtcgResult {
  light: DtcgColorToken;
  dark?: DtcgColorToken;
  lightContrast?: DtcgColorToken;
  darkContrast?: DtcgColorToken;
}

/** Options for `theme.dtcg()` / `palette.dtcg()`. */
export interface GlazeDtcgOptions {
  /** Override which scheme variants to include. */
  modes?: GlazeOutputModes;
  /**
   * DTCG color space. `'srgb'` (default) emits sRGB components plus a `hex`
   * hint — universally understood (Figma, Tokens Studio). `'oklch'` emits
   * OKLCH components with no hex — Glaze-native, wide-gamut.
   */
  colorSpace?: DtcgColorSpace;
}

// ============================================================================
// DTCG Resolver-Module export types
// (W3C Design Tokens Resolver Module — one document for all scheme variants)
// ============================================================================

/**
 * A node in a DTCG Resolver-Module token tree: either a leaf color token or a
 * nested group. A flat `DtcgDocument` (top-level color-name keys) is a valid
 * shallow tree, so Glaze's per-scheme documents slot directly into
 * `sets.<name>.sources` and `modifiers.<name>.contexts.<ctx>` entries.
 */
export interface DtcgTokenTree {
  [key: string]: DtcgColorToken | DtcgTokenTree;
}

/** A named set in a resolver document: a list of token-tree sources. */
export interface DtcgResolverSet {
  sources: DtcgTokenTree[];
}

/**
 * A named modifier (an axis such as `scheme`) in a resolver document.
 * `default` names the context applied when no override is selected; `contexts`
 * maps each context name to the token-tree overrides applied for it.
 */
export interface DtcgResolverModifier {
  default: string;
  contexts: Record<string, DtcgTokenTree[]>;
}

/** A JSON-pointer `$ref` entry in a resolver document's `resolutionOrder`. */
export interface DtcgResolverRef {
  $ref: string;
}

/**
 * A W3C DTCG Resolver-Module document. Describes every scheme variant in a
 * single file as `sets` (base token sources) plus `modifiers` (per-context
 * overrides) composed in `resolutionOrder`. Consumable by resolver tools such
 * as Dispersa.
 * @see https://www.designtokens.org/
 */
export interface GlazeDtcgResolverDocument {
  version: string;
  sets: Record<string, DtcgResolverSet>;
  modifiers: Record<string, DtcgResolverModifier>;
  resolutionOrder: DtcgResolverRef[];
}

/** Renaming of the four scheme variants as resolver-modifier context names. */
export interface GlazeDtcgResolverContextNames {
  light?: string;
  dark?: string;
  lightContrast?: string;
  darkContrast?: string;
}

/**
 * Options for `theme.dtcgResolver()` / `palette.dtcgResolver()`. Extends
 * `GlazeDtcgOptions` so `modes` + `colorSpace` pass through to the underlying
 * per-scheme `dtcg()` build.
 */
export interface GlazeDtcgResolverOptions extends GlazeDtcgOptions {
  /** Name of the single set holding the default (light) token tree. Default `'base'`. */
  setName?: string;
  /**
   * Name of the modifier describing the scheme axis. Default `'scheme'`
   * (Glaze's term for the light / dark / high-contrast axis).
   */
  modifierName?: string;
  /**
   * Override the four context names emitted on the modifier. Defaults to the
   * Glaze variant keys: `light` / `dark` / `lightContrast` / `darkContrast`.
   */
  contextNames?: GlazeDtcgResolverContextNames;
  /** Resolver document version. Default `'2025.10'`. */
  version?: string;
}

/** Options for `glaze.color().dtcgResolver()`. `name` is required. */
export interface GlazeColorDtcgResolverOptions extends GlazeDtcgResolverOptions {
  /** Token name keying the color within each token tree. Required. */
  name: string;
}

/** Options for `theme.tailwind()` / `palette.tailwind()`. */
export interface GlazeTailwindOptions {
  /** Override which scheme variants to include. */
  modes?: GlazeOutputModes;
  /** Output color format. Default: 'oklch'. */
  format?: GlazeColorFormat;
  /**
   * CSS custom property namespace, forming `--<namespace><name>`.
   * Default: `'color-'` → `--color-surface`. (Tailwind v4's `--color-*`
   * convention, which auto-generates `bg-*` / `text-*` / `border-*`.)
   *
   * Named `namespace` rather than `prefix` to avoid clashing with the
   * palette theme-prefix option on `palette.tailwind()`.
   */
  namespace?: string;
  /**
   * Selector wrapping the dark-scheme overrides. Default: `'.dark'`.
   * Pass a media query such as `'@media (prefers-color-scheme: dark)'` to
   * drive dark mode from the OS preference instead of a class.
   */
  darkSelector?: string;
  /**
   * Selector wrapping the light high-contrast overrides. Default:
   * `'.high-contrast'`. The combined dark + high-contrast overrides are
   * emitted under `${darkSelector}${highContrastSelector}` (e.g.
   * `.dark.high-contrast`).
   */
  highContrastSelector?: string;
}

/** Options for `glaze.color().tailwind()`. `name` is required. */
export interface GlazeColorTailwindOptions extends GlazeTailwindOptions {
  /** Custom property base name (without leading `--`). Required. */
  name: string;
}

/** Options for `glaze.palette()` creation. */
export 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. */
export 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;
  /**
   * Emit hue as a separate custom property, referenced via `var()`.
   * Requires `format: 'oklch'` and every color to be pastel.
   */
  splitHue?: boolean;
}

export interface GlazePalette {
  /** Theme names in insertion order. */
  list(): string[];

  /** Primary theme name, if set at palette creation. */
  readonly primary: string | undefined;

  /** Get a theme by name. Returns the live instance held by the palette. */
  theme(name: string): GlazeTheme | undefined;

  /**
   * Shallow copy of the theme map (same instances the palette holds).
   * Mutating a returned theme affects subsequent palette exports.
   */
  themes(): Record<string, GlazeTheme>;

  /**
   * Export the palette authoring configuration as a JSON-safe object.
   * Restorable via `glaze.paletteFrom(...)`. Distinct from `json()`, which
   * emits resolved color strings. Optional `override` is forwarded to each
   * nested `theme.export(override)`.
   */
  export(override?: GlazeConfigOverride): GlazePaletteExport;

  /**
   * 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 (`''`, `'@media(prefers-color-scheme: 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;

  /**
   * Export all themes as W3C DTCG documents, one per scheme variant.
   * Prefix defaults to `true`. Inherits the palette-level `primary`.
   * @see https://www.designtokens.org/
   */
  dtcg(options?: GlazeDtcgOptions & GlazePaletteExportOptions): GlazeDtcgResult;

  /**
   * Export all themes as a single W3C DTCG Resolver-Module document. Prefix
   * defaults to `true`. Inherits the palette-level `primary`.
   * @see https://www.designtokens.org/
   */
  dtcgResolver(
    options?: GlazeDtcgResolverOptions & GlazePaletteExportOptions,
  ): GlazeDtcgResolverDocument;

  /**
   * Export all themes as a Tailwind CSS v4 `@theme` block plus dark /
   * high-contrast overrides. Returns a single ready-to-paste CSS string.
   * Prefix defaults to `true`.
   * @see https://tailwindcss.com/docs/theme
   */
  tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
}