@tenphi/glaze 0.0.0-snapshot.63c08ea → 0.0.0-snapshot.6b78fce

package/dist/index.d.mts

@@ -62,6 +62,24 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * selected spec rather than an outer pair).
  */
 declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg', outerExplicitHC?: boolean): ResolvedContrast;
+/**
+ * Resolve a `contrast` spec — including its outer `[normal, highContrast]`
+ * pair — at a manual contrast `level` (0–100), by resolving both ends and
+ * interpolating the numeric target.
+ *
+ * Level 0 / 100 delegate verbatim to {@link resolveContrastForMode}, so the
+ * endpoints are bit-identical to classic normal / high-contrast resolution.
+ * Resolving each end fully first also means every rule that governs the
+ * escalation still applies at both ends for free: preset mapping, the
+ * `APCA_MAX_LC` clamp, and the explicit-HC suppression that cancels the
+ * `AA → AAA` promotion and the `+15 Lc` enhancement.
+ *
+ * Throws when the two ends measure in different metrics — a WCAG ratio and an
+ * APCA Lc live on different scales, so there is no target between them. Such a
+ * pair is rejected at authoring time by `validateColorDefs`; this is the guard
+ * for direct callers.
+ */
+declare function resolveContrastForLevel(spec: HCPair<ContrastSpec>, level: number, polarity?: 'fg' | 'bg'): ResolvedContrast;
 /**
  * APCA lightness contrast (Lc), signed: positive for dark text on light bg,
  * negative for light text on dark bg. Inputs are screen luminances (0–1).
@@ -84,10 +102,31 @@ interface FindToneForContrastOptions {
   epsilon?: number;
   /** Maximum binary-search iterations per branch. Default: 18. */
   maxIterations?: number;
-  /** Preferred search direction before auto-flip is considered. */
+  /**
+   * Preferred search direction before auto-flip is considered. Default: the
+   * side whose bound scores higher (the only open side when `preferredTone`
+   * sits on a bound); a tie within float noise starts `'darker'`.
+   */
   initialDirection?: 'lighter' | 'darker';
-  /** Auto-flip tone direction when contrast can't be met. Default: false. */
+  /**
+   * Also search the opposite direction. Default: false. When both directions
+   * meet the target, the result nearer `preferredTone` wins; a gap within
+   * twice the search resolution is a tie and keeps `initialDirection`.
+   */
   flip?: boolean;
+  /**
+   * When `flip` is on and *both* directions meet the target, keep
+   * `initialDirection` instead of taking whichever result lands nearer the
+   * preferred tone. Default: false (nearest wins).
+   *
+   * The nearest-wins tie-break is unstable along a ramp of targets: which side
+   * is nearer shifts as the target grows, so a color can swap sides between two
+   * adjacent targets. Set this when a caller needs the side to be a property of
+   * the color rather than of the target — the manual contrast level does. The
+   * flip itself is unaffected: an initial direction that cannot reach the
+   * target still falls back to the opposite side.
+   */
+  preferInitial?: boolean;
   /** Use the hue-independent "safe" chroma boundary. Default: false. */
   pastel?: boolean;
 }
@@ -98,26 +137,37 @@ interface FindToneForContrastResult {
   contrast: number;
   /** Whether the target was reached. */
   met: boolean;
-  /** Which branch was selected. */
+  /**
+   * The side the result was found on. The two sides meet at `preferredTone`,
+   * so a met result sits on that side of the base too. `'preferred'` when the
+   * result is `preferredTone` itself: it already cleared the overshooting
+   * search target, or no searched side met the floor while it clears the bare
+   * target (or there was no room to search).
+   */
   branch: 'lighter' | 'darker' | 'preferred';
   /** Whether the result auto-flipped to the opposite direction. */
   flipped?: boolean;
 }
 /**
  * Find the tone that satisfies a contrast floor against a base color,
- * staying as close to `preferredTone` as possible.
+ * staying as close to `preferredTone` as possible. A searched result keeps the
+ * overshoot (1% for WCAG, 0.5 Lc for APCA). When no searched side reaches the
+ * floor, the result pins to the initial direction's extreme, unmet — unless
+ * `preferredTone` itself clears the bare target, which is then kept as met.
  */
 declare function findToneForContrast(options: FindToneForContrastOptions): FindToneForContrastResult;
 interface FindValueForMixContrastOptions {
   /** Preferred mix parameter (0–1). */
   preferredValue: number;
-  /** Base color as linear sRGB. */
+  /** Base color as linear sRGB — the color the mix is measured against. */
   baseLinearRgb: LinearRgb;
-  /** Target color as linear sRGB. */
-  targetLinearRgb: LinearRgb;
   /** Resolved contrast floor (metric + target). */
   contrast: ResolvedContrast;
-  /** Compute the luminance of the mixed color at parameter t. */
+  /**
+   * Luminance of the mixed color at parameter t, in the metric's basis
+   * ({@link metricLuminance}). This closure is the only view the solver has of
+   * the mix's target color, blend, and color space.
+   */
   luminanceAtValue: (t: number) => number;
   /** Convergence threshold. Default: 1e-4. */
   epsilon?: number;
@@ -135,6 +185,9 @@ interface FindValueForMixContrastResult {
 /**
  * Find the mix parameter (ratio or opacity) that satisfies a contrast floor
  * against a base color, staying as close to `preferredValue` as possible.
+ * Misses pin to the initial direction's end like the tone solver, and a
+ * `preferredValue` that clears the bare target is kept as met when no searched
+ * side reaches the floor (a value of 1 has no room toward the target).
  */
 declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
 //#endregion
@@ -200,7 +253,15 @@ type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
 interface GlazeOutputModes {
   /** Include dark scheme variants. Default: true. */
   dark?: boolean;
-  /** Include high-contrast variants (both light-HC and dark-HC). Default: false. */
+  /**
+   * 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;
 }
 /** Hex color string for DX hints. Runtime validation in `parseHex()`. */
@@ -234,13 +295,43 @@ interface OklchColor {
 }
 interface RegularColorDef {
   /**
-   * Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
+   * 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.mdx`).
    * - 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). */
+  /**
+   * 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.
@@ -248,6 +339,26 @@ interface RegularColorDef {
    * - 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;
   /**
@@ -261,7 +372,8 @@ interface RegularColorDef {
    * 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.
+   *   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`).
    *
@@ -280,8 +392,8 @@ interface RegularColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -300,44 +412,63 @@ interface RegularColorDef {
    */
   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];
+/**
+ * Tuning shared by `shadow` and `glow`. Global defaults come from
+ * `shadowTuning` / `glowTuning`; a per-color `tuning` merges over them field
+ * by field.
+ */
+interface LightingTuning {
+  /**
+   * β — how strongly the object (`fg`) scales the step. The step is
+   * `intensity × k` with `k = max(0, 1 + β · d · (t_bg − t_fg) / 100)`,
+   * `d = +1` for a shadow and `−1` for a glow: a darker object deepens its
+   * shadow, a lighter one strengthens its glow. An object at the surface's
+   * own tone (or no `fg`) gives exactly `intensity`. `0` ignores the object.
+   * Default: 0.5.
+   */
+  objectInfluence?: number;
+  /**
+   * Pigment saturation (0–1) in the surface's hue. Default: 0 (neutral black /
+   * white). Shows only with `reach` below 1 — pure black and white have no hue.
+   */
+  tint?: number;
   /**
-   * Target minimum gap between pigment lightness and bg lightness (0-1).
-   * Default: 0.05.
+   * Where the pigment sits (0–1): the fraction of the way from the surface's
+   * tone to black (shadow) / white (glow). Default: 1 (pure black / white),
+   * the most reach. Lower values let a `tint` show at the cost of reach.
    */
-  minGapTarget?: number;
-  /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
-  alphaMax?: number;
+  reach?: number;
   /**
-   * Blend weight (0-1) pulling pigment hue toward bg hue.
-   * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
+   * Pull (0–1) of the pigment hue from the surface's hue toward the object's
+   * (`fg`) hue. Default: 0. Needs `fg`, a `tint`, and `reach` below 1 to show.
    */
-  bgHueBlend?: number;
+  hueBleed?: number;
 }
+/** Tuning for `shadow` colors. Same shape as {@link GlowTuning}. */
+type ShadowTuning = LightingTuning;
+/** Tuning for `glow` colors. Same shape as {@link ShadowTuning}. */
+type GlowTuning = LightingTuning;
+/**
+ * A translucent dark overlay that lands the surface (`bg`) exactly
+ * `intensity` tones darker in every scheme — a shade for state layers and
+ * scrims, or, with `fg`, an object-aware drop shadow.
+ */
 interface ShadowColorDef {
   type: 'shadow';
   /**
-   * Background color name — the surface the shadow sits on.
-   * Must reference a non-shadow color in the same theme.
+   * The surface the shadow falls on. Must reference a color that is not a
+   * shadow or glow.
    */
   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.
+   * The object casting the shadow (e.g. the card). A darker object casts a
+   * deeper shadow, a lighter one a softer shadow — see
+   * `LightingTuning.objectInfluence`. Omit for an exact shade of `intensity`
+   * tones. Must reference a color that is not a shadow or glow.
    */
   fg?: string;
   /**
-   * Shadow intensity, 0-100.
+   * Tone step, 0–100: how many tones darker than `bg` the composite lands.
    * Supports [normal, highContrast] pair.
    */
   intensity: HCPair<number>;
@@ -346,8 +477,46 @@ interface ShadowColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * 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;
+}
+/**
+ * The mirror of {@link ShadowColorDef}: a translucent light overlay that lands
+ * the surface (`bg`) exactly `intensity` tones lighter in every scheme — for
+ * dark-mode elevation, edge highlights, and lightening state layers.
+ */
+interface GlowColorDef {
+  type: 'glow';
+  /**
+   * The surface the glow falls on. Must reference a color that is not a
+   * shadow or glow.
+   */
+  bg: string;
+  /**
+   * The object emitting the glow. A lighter object glows stronger, a darker
+   * one weaker — see `LightingTuning.objectInfluence`. Omit for an exact tint
+   * of `intensity` tones. Must reference a color that is not a shadow or glow.
+   */
+  fg?: string;
+  /**
+   * Tone step, 0–100: how many tones lighter than `bg` the composite lands.
+   * Supports [normal, highContrast] pair.
+   */
+  intensity: HCPair<number>;
+  /** Override default tuning. Merged field-by-field with global `glowTuning`. */
+  tuning?: GlowTuning;
+  /**
+   * 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;
   /**
@@ -377,9 +546,12 @@ interface MixColorDef {
   /**
    * Interpolation color space for opaque blending. Default: 'okhsl'.
    * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
-   * - 'srgb': linear sRGB interpolation, matches browser compositing.
+   * - 'srgb': linear-light sRGB interpolation (like CSS
+   *   `color-mix(in srgb-linear, …)`).
    *
-   * Ignored for 'transparent' blend (always composites in linear sRGB).
+   * Ignored for 'transparent' blend: the browser composites that one, and
+   * its contrast solve models the browser (`source-over` on gamma-encoded
+   * sRGB).
    */
   space?: 'okhsl' | 'srgb';
   /**
@@ -393,8 +565,8 @@ interface MixColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -409,7 +581,7 @@ interface MixColorDef {
    */
   inherit?: boolean;
 }
-type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
+type ColorDef = RegularColorDef | ShadowColorDef | GlowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
 /**
  * Resolved color for a single scheme variant.
@@ -441,7 +613,7 @@ interface ResolvedColor {
   dark: ResolvedColorVariant;
   lightContrast: ResolvedColorVariant;
   darkContrast: ResolvedColorVariant;
-  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
+  /** Adaptation mode of a regular color; `undefined` for shadow / glow / mix. */
   mode?: AdaptationMode;
 }
 /**
@@ -474,10 +646,40 @@ interface GlazeConfig {
     dark?: string;
     highContrast?: string;
   };
-  /** Which scheme variants to include in exports. Default: both true. */
+  /**
+   * 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;
+  /** Default tuning for all glow colors. Per-color tuning merges field-by-field. */
+  glowTuning?: GlowTuning;
+  /**
+   * 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/reference/contrast.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.
    *
@@ -493,13 +695,6 @@ interface GlazeConfig {
    * falls back to the originally requested tone).
    */
   autoFlip?: boolean;
-  /**
-   * If true, uses a hue-independent "safe" chroma limit across all colors
-   * so that scaling saturation never exceeds the sRGB boundary at any hue
-   * for the given lightness.
-   * @default false
-   */
-  pastel?: boolean;
   /**
    * 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
@@ -518,14 +713,27 @@ interface GlazeConfigResolved {
   };
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
+  glowTuning?: GlowTuning;
   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.
+ * 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).
  */
@@ -539,9 +747,22 @@ interface GlazeConfigOverride {
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
   /**
-   * If true, uses a hue-independent "safe" chroma limit across all colors
-   * so that scaling saturation never exceeds the sRGB boundary at any hue
-   * for the given lightness.
+   * 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;
   /**
@@ -554,39 +775,81 @@ interface GlazeConfigOverride {
    * standalone color tokens.
    */
   shadowTuning?: ShadowTuning;
+  /**
+   * Glow tuning defaults. Only meaningful for themes; harmless on
+   * standalone color tokens.
+   */
+  glowTuning?: GlowTuning;
 }
+/**
+ * Current authoring-export schema version. Bump when the export shape
+ * changes in a non-compatible way. Written on every `.export()` snapshot.
+ *
+ * - `1` — Glaze 2.x.
+ * - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
+ *   `glow` was added. Version-1 theme snapshots that carry shadow defs or a
+ *   `shadowTuning` are rejected on restore.
+ */
+declare const GLAZE_EXPORT_VERSION: 2;
+/** Literal type of {@link GLAZE_EXPORT_VERSION}. */
+type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
+/** Discriminator for authoring export snapshots. */
+type GlazeExportKind = 'theme' | 'color' | 'palette';
 /** Serialized theme configuration (no resolved values). */
 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;
-  /** Per-theme config override, if any. */
+  /**
+   * 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;
 }
-/** Input for `glaze.shadow()` standalone factory. */
-interface GlazeShadowInput {
+/** Input for the `glaze.shadow()` and `glaze.glow()` standalone factories. */
+interface GlazeLightingInput {
   /**
-   * 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.
+   * The surface — accepts any `GlazeColorValue` form: hex
+   * (`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` /
+   * `okhsl()` / `okhst()` / `oklch()` strings, or literal objects
+   * (`{ r, g, b }`, `{ h, s, l }`, `{ h, s, t }`, `{ l, c, h }`). Alpha
+   * components are dropped with a warning.
    */
   bg: GlazeColorValue;
-  /**
-   * Foreground color for tinting + intensity modulation. Accepts the
-   * same forms as `bg`.
-   */
+  /** The object casting the shadow / emitting the glow. Same forms as `bg`. */
   fg?: GlazeColorValue;
-  /** Intensity 0-100. */
+  /** Tone step, 0–100. */
   intensity: number;
-  tuning?: ShadowTuning;
+  tuning?: LightingTuning;
 }
+/** Input for `glaze.shadow()`. */
+type GlazeShadowInput = GlazeLightingInput;
+/** Input for `glaze.glow()`. */
+type GlazeGlowInput = GlazeLightingInput;
 /** Input for the structured `glaze.color()` overload. */
 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;
@@ -603,29 +866,33 @@ interface GlazeColorInput {
    */
   base?: GlazeColorToken | GlazeColorValue;
   /**
-   * Contrast floor against `base`. Requires `base` to be set. A bare
+   * Contrast floor. Without `base`, solved against the token's own input
+   * color (`hue`, `saturation`, normal `tone`), held fixed in every scheme;
+   * with `base`, against the base's resolved variant per scheme. 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.
+   * used) and as `resolve().name`. A debug label only: it does not
+   * affect output keys or the token's `role`.
    */
   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 global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * 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.
+   * Semantic role against the token's anchor (`base`, or its own input
+   * color when `contrast` is set without one): how this token is used.
+   * Fixes APCA contrast polarity; WCAG ignores it. Defaults to `'text'` —
+   * the token is the foreground and the anchor the background, with or
+   * without `base`. Unlike a theme color, a token never infers its role
+   * from `name`, so `inferRole` has no effect on it.
    */
   role?: RoleInput;
 }
@@ -633,17 +900,35 @@ interface GlazeColorInput {
  * 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).
+ * Strings cover hex with a leading `#` (`#rgb` / `#rgba` / `#rrggbb` /
+ * `#rrggbbaa`) and the five color functions Glaze itself emits: `rgb()`,
+ * `hsl()`, `okhsl()`, `okhst()`, `oklch()`, plus the `rgba()` / `hsla()`
+ * aliases. Function names are case-insensitive; components are numbers or
+ * percentages, separated by spaces or commas. Their scales:
+ * - `rgb()` — channels 0–255, or percentages (`100%` is 255).
+ * - `hsl()` / `okhsl()` / `okhst()` — saturation, lightness and tone are
+ *   percentages or bare 0–1 fractions: `hsl(120 50% 50%)` or
+ *   `hsl(120 0.5 0.5)`. Unlike CSS, a bare `hsl(120 50 50)` does not mean
+ *   50%; it is out of range and resolves to white without a warning.
+ * - `oklch()` — L 0–1 or a percentage; C bare, or a percentage where
+ *   `100%` is 0.4.
+ * - Hue is in degrees, bare or with `deg`. Other angle units (`turn`,
+ *   `rad`, `grad`) are misread as degrees rather than rejected.
+ *
+ * An alpha component (hex alpha, `/ A`, or any fourth component) is
+ * dropped with a warning. Named colors, other color functions, and
+ * relative color syntax throw.
  *
- * 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.
+ * Literal object forms, told apart by their keys:
  * - `{ r, g, b }` — sRGB 0–255.
  * - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
+ * - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1, so `t: 0.7` is
+ *   tone 70.
+ * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1).
+ *
+ * An object `s`, `l`, `t` or `c` above 1.5 throws, which catches 0–100
+ * input; the OKHSL / OKHST errors point to the structured form. String
+ * components have no such check.
  */
 type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
 /** Color overrides for the `from` and value-shorthand inputs. */
@@ -656,6 +941,23 @@ interface GlazeColorOverrides {
   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()`);
@@ -668,11 +970,11 @@ interface GlazeColorOverrides {
   /**
    * 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 tone (`lightTone: false`) and snapshot
-   * `globalConfig.darkTone` on the dark side. Only the structured
-   * `{ hue, saturation, tone }` form also snapshots
-   * `globalConfig.lightTone`.
+   * 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
@@ -725,20 +1027,24 @@ interface GlazeColorOverrides {
   /**
    * 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.
+   * used) and as `resolve().name`. A debug label only: it does not
+   * affect output keys or the token's `role`.
    */
   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 global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * 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`.
+   * Semantic role against the token's anchor (`base`, or the literal seed
+   * when `contrast` / a relative `tone` is set without one): how this token
+   * is used. Fixes APCA contrast polarity; WCAG ignores it. Defaults to
+   * `'text'` — the token is the foreground and the anchor the background,
+   * with or without `base`. Unlike a theme color, a token never infers its
+   * role from `name`, so `inferRole` has no effect on it.
    */
   role?: RoleInput;
 }
@@ -771,8 +1077,9 @@ interface GlazeColorCssOptions {
    */
   suffix?: string;
   /**
-   * Emit hue as a separate custom property, referenced via `var()`.
-   * Requires `format: 'oklch'` and a pastel token. oklch + all-pastel only.
+   * Emit hue as a separate `--{name}-hue` custom property, referenced via
+   * `var()`. Requires `format: 'oklch'` (any other format throws) and a
+   * pastel token.
    */
   splitHue?: boolean;
 }
@@ -815,14 +1122,19 @@ interface GlazeColorToken {
    * 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(): GlazeColorTokenExport;
+  export(override?: GlazeConfigOverride): GlazeColorTokenExport;
 }
 /**
  * JSON-safe serialization of a `glaze.color()` token. Pass to
  * `glaze.colorFrom(...)` to rehydrate.
  */
 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 })`.
@@ -837,14 +1149,26 @@ interface GlazeColorTokenExport {
    */
   overrides?: GlazeColorOverridesExport;
   /**
-   * Effective config snapshot at creation time — captures the merged
-   * result of the global config + any per-call override at the moment
-   * the token was created. Only fields that differ from their
-   * post-merge defaults are present. Used by `glaze.colorFrom()` to
-   * reproduce deterministic behavior across `configure()` calls.
+   * 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.
+ */
+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
@@ -855,6 +1179,9 @@ interface GlazeColorInputExport {
   saturation: number;
   tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
+  darkHue?: number | RelativeValue;
+  darkSaturation?: number;
+  darkSaturationFactor?: number;
   mode?: AdaptationMode;
   autoFlip?: boolean;
   opacity?: number;
@@ -871,6 +1198,9 @@ interface GlazeColorInputExport {
 interface GlazeColorOverridesExport {
   hue?: number | RelativeValue;
   saturation?: number;
+  darkHue?: number | RelativeValue;
+  darkSaturation?: number;
+  darkSaturationFactor?: number;
   tone?: HCPair<ToneValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
@@ -882,11 +1212,33 @@ interface GlazeColorOverridesExport {
   pastel?: boolean;
   role?: RoleInput;
 }
+/**
+ * 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.
+ */
+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;
+}
 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). */
@@ -904,7 +1256,7 @@ interface GlazeTheme {
   /** Clear all color definitions. */
   reset(): void;
   /** Export the theme configuration as a JSON-safe object. */
-  export(): GlazeThemeExport;
+  export(override?: GlazeConfigOverride): GlazeThemeExport;
   /** Create a child theme inheriting all color definitions. */
   extend(options: GlazeExtendOptions): GlazeTheme;
   /** Resolve all colors and return the result map. */
@@ -924,7 +1276,7 @@ interface GlazeTheme {
    * 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>>;
+  tasty(options?: GlazeTastyOptions): Record<string, Record<string, string>>;
   /** Export as plain JSON. */
   json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /** Export as CSS custom property declarations. */
@@ -954,13 +1306,19 @@ interface GlazeTheme {
 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;
 }
+/**
+ * Options for `token.token()` / `token.tasty()`, and the base of the theme and
+ * palette `tasty()` options: output format, scheme variants, state aliases.
+ */
 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;
@@ -970,23 +1328,29 @@ interface GlazeTokenOptions {
   modes?: GlazeOutputModes;
   /** Output color format. Default: 'oklch'. */
   format?: GlazeColorFormat;
+}
+/** Options for `theme.tasty()`. */
+interface GlazeTastyOptions extends GlazeTokenOptions {
   /**
    * Emit hue as a separate custom property, referenced via `var()`.
-   * Requires `format: 'oklch'` and every color to be pastel.
+   * Requires `format: 'oklch'` (any other format throws) 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.
+   * Must not equal the name of a color that sets its own hue (throws).
    */
   name?: string;
 }
+/** Options for `theme.tokens()` / `theme.json()` and their palette and token counterparts. */
 interface GlazeJsonOptions {
   /** Override which scheme variants to include. */
   modes?: GlazeOutputModes;
   /** Output color format. Default: 'oklch'. */
   format?: GlazeColorFormat;
 }
+/** Options for `theme.css()`. */
 interface GlazeCssOptions {
   /** Output color format. Default: 'oklch'. */
   format?: GlazeColorFormat;
@@ -994,12 +1358,13 @@ interface GlazeCssOptions {
   suffix?: string;
   /**
    * Emit hue as a separate custom property, referenced via `var()`.
-   * Requires `format: 'oklch'` and every color to be pastel.
+   * Requires `format: 'oklch'` (any other format throws) 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.
+   * Must not equal the name of a color that sets its own hue (throws).
    */
   name?: string;
 }
@@ -1202,7 +1567,10 @@ interface GlazePaletteOptions {
    */
   primary?: string;
 }
-/** Options shared by palette `tokens()`, `tasty()`, and `css()` exports. */
+/**
+ * Options shared by every palette export except `json()`: `tokens()`,
+ * `tasty()`, `css()`, `dtcg()`, `dtcgResolver()`, and `tailwind()`.
+ */
 interface GlazePaletteExportOptions {
   /**
    * Prefix mode. `true` uses `"<themeName>-"`, or provide a custom map.
@@ -1217,13 +1585,54 @@ interface GlazePaletteExportOptions {
    * When omitted, inherits the palette-level `primary`.
    */
   primary?: string | false;
+}
+/**
+ * Options for `palette.tasty()`. There is no `name`: each theme's hue var is
+ * named after the theme.
+ */
+interface GlazePaletteTastyOptions extends GlazeTokenOptions, GlazePaletteExportOptions {
   /**
    * Emit hue as a separate custom property, referenced via `var()`.
-   * Requires `format: 'oklch'` and every color to be pastel.
+   * Requires `format: 'oklch'` (any other format throws) and every color to
+   * be pastel. The theme-level hue var is `--{themeName}-hue`.
+   */
+  splitHue?: boolean;
+}
+/**
+ * Options for `palette.css()`. There is no `name`: each theme's hue var is
+ * named after the theme.
+ */
+interface GlazePaletteCssOptions extends GlazePaletteExportOptions {
+  /** 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'` (any other format throws) and every color to
+   * be pastel. The theme-level hue var is `--{themeName}-hue`.
    */
   splitHue?: boolean;
 }
 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.
@@ -1242,13 +1651,14 @@ interface GlazePalette {
    * 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>>>;
+  tasty(options?: GlazePaletteTastyOptions): Record<string, Record<string, string>>;
+  /**
+   * Export all themes as plain JSON grouped by theme name. No prefix, primary
+   * alias, or collision handling: each theme keeps its own key.
+   */
+  json(options?: GlazeJsonOptions): Record<string, Record<string, Record<string, string>>>;
   /** Export all themes as CSS custom property declarations. */
-  css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
+  css(options?: GlazePaletteCssOptions): GlazeCssResult;
   /**
    * Export all themes as W3C DTCG documents, one per scheme variant.
    * Prefix defaults to `true`. Inherits the palette-level `primary`.
@@ -1270,6 +1680,14 @@ interface GlazePalette {
   tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
 }
 //#endregion
+//#region src/serialize.d.ts
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+declare function isThemeExport(data: unknown): data is GlazeThemeExport;
+/** Type guard for color-token authoring snapshots. */
+declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
+//#endregion
 //#region src/glaze.d.ts
 type PaletteInput = Record<string, GlazeTheme>;
 /**
@@ -1281,29 +1699,43 @@ type PaletteInput = Record<string, GlazeTheme>;
  * the theme still reacts to later `configure()` calls for fields it
  * didn't override.
  *
+ * The object form also accepts `darkHue` / `darkSaturation` — a separate
+ * seed pair for the dark and dark-high-contrast schemes. Both default to
+ * their light counterparts, and an explicit `darkSaturation` opts the theme
+ * out of the global `darkDesaturation` reduction.
+ *
  * @example
  * ```ts
  * const primary = glaze(280, 80);
  * // or shorthand:
  * const primary = glaze({ hue: 280, saturation: 80 });
+ * // with a retuned dark seed:
+ * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
  * // with config override:
  * const raw = glaze(280, 80, { lightTone: false });
+ * const rawSeed = glaze({ hue: 280, saturation: 80 }, { lightTone: false });
  * ```
  */
-declare function glaze(hueOrOptions: number | {
-  hue: number;
-  saturation: number;
-}, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(hue: number, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(seed: GlazeThemeSeed, config?: GlazeConfigOverride): GlazeTheme;
+/** @deprecated Pass the config second: `glaze(seed, config)`. */
+declare function glaze(seed: GlazeThemeSeed, saturation: undefined, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
+  var themeFrom: (data: GlazeThemeExport) => GlazeTheme;
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
+  var glow: (input: GlazeGlowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
+  var paletteFrom: (data: GlazePaletteExport) => GlazePalette;
+  var isThemeExport: typeof isThemeExport;
+  var isColorTokenExport: typeof isColorTokenExport;
+  var isPaletteExport: typeof isPaletteExport;
   var getConfig: () => GlazeConfigResolved;
   var resetConfig: () => void;
 }
@@ -1316,13 +1748,18 @@ interface HueDeclaration {
 interface HuePlan {
   /** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
   hueVar: string;
-  /** When true, emit a full inline color (shadow/mix/achromatic). */
+  /** When true, emit a full inline color (shadow/glow/mix/achromatic). */
   inline: boolean;
   /** Scheme-independent `--*-hue` declarations for this color. */
   declarations: HueDeclaration[];
 }
 interface ChannelCtx {
   seedHue: number;
+  /**
+   * Dark-scheme seed hue, when the theme authored one. Drives the dark
+   * `--{baseName}-hue` value; falls back to `seedHue`.
+   */
+  darkSeedHue?: number;
   /** Theme-level hue var base name (without `--` / `-hue`). */
   baseName: string;
   /** Token / custom-property name prefix used for hue var naming (`brand-` etc.). */
@@ -1426,7 +1863,11 @@ declare function okhslToOkhst(c: {
 };
 /**
  * Edge adapter: a resolved variant stores canonical tone `t` (0–1). Convert
- * it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect.
+ * it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect —
+ * `s` and `l` on the same 0–1 factor scale, so `const { h, s, l } =
+ * variantToOkhsl(v)` destructures straight into `formatOkhsl` / `formatRgb` /
+ * `okhslToLinearSrgb` with no rescaling. `alpha` stays on the variant; use
+ * `glaze.format(v, format)` for a string that carries it.
  */
 declare function variantToOkhsl(v: {
   h: number;
@@ -1444,7 +1885,9 @@ declare function variantToOkhsl(v: {
  *
  * Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
  * for both contrast metrics (WCAG 2 relative luminance and APCA screen
- * luminance `Ys`), and multi-format output (okhsl, rgb, hsl, oklch).
+ * luminance `Ys` — both the exact functions the contrast solver uses, and
+ * both public), strict hex parsing (`parseHex` / `parseHexAlpha` check every
+ * digit), and multi-format output (okhsl, rgb, hsl, oklch).
  */
 type Vec3 = [number, number, number];
 /**
@@ -1481,6 +1924,7 @@ declare function relativeLuminanceFromLinearRgb(rgb: [number, number, number]):
 declare function contrastRatioFromLuminance(yA: number, yB: number): number;
 /**
  * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
+ * h: 0–360, s: 0–1, l: 0–1. Returns [r, g, b] with each channel 0–1.
  */
 declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 /**
@@ -1489,6 +1933,22 @@ declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean):
  * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
  */
 declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
+/**
+ * Compute APCA screen luminance (`Ys`) from linear sRGB.
+ *
+ * APCA does not use the WCAG piecewise sRGB EOTF; it defines its own
+ * luminance as `0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
+ * gamma-encoded (display) channels with a simple 2.4 exponent. The APCA
+ * soft-clamp threshold in `apcaContrast` is calibrated against this basis,
+ * so the solver must feed it `Ys`, not WCAG relative luminance. Channels
+ * are gamut-clamped to [0, 1] first, matching `gamutClampedLuminance`.
+ *
+ * This is exactly the luminance Glaze's contrast solver (and its drift
+ * check) feeds `apcaContrast`, so
+ * `apcaContrast(apcaLuminanceFromLinearRgb(text), apcaLuminanceFromLinearRgb(bg))`
+ * reproduces the solver's Lc for a resolved pair.
+ */
+declare function apcaLuminanceFromLinearRgb(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.
@@ -1510,7 +1970,9 @@ declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [
 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.
+ * The leading `#` is optional. Returns null if the string is not a valid hex
+ * color: a wrong length, any character outside `0-9a-f` (case-insensitive),
+ * or a form with alpha.
  *
  * For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
  * use {@link parseHexAlpha}.
@@ -1519,7 +1981,12 @@ 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.
+ * The leading `#` is optional. Returns null if the string is not a valid hex
+ * color: a wrong length or any character outside `0-9a-f`
+ * (case-insensitive).
+ *
+ * Every digit is checked up front: `parseInt` alone stops at the first bad
+ * character, so `'#1z2z3z'` would otherwise read as `#010203`.
  */
 declare function parseHexAlpha(hex: string): {
   rgb: [number, number, number];
@@ -1527,12 +1994,12 @@ declare function parseHexAlpha(hex: string): {
 } | 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).
+ * h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
  */
 declare function formatOkhsl(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHST values as a CSS `okhst(H S% T%)` string.
- * h: 0–360, s: 0–100, t: 0–100 (percentage scale for s and t).
+ * h: 0–360, s: 0–1, t: 0–1 (factor scale, matching `ResolvedColorVariant`).
  *
  * Pastel recompute matches `formatOkhsl`: convert via OKLab so external
  * parsers that only understand non-pastel OKHST render identically.
@@ -1541,17 +2008,17 @@ declare function formatOkhst(h: number, s: number, t: number, pastel?: boolean):
 /**
  * Format OKHSL values as a CSS `rgb(R G B)` string.
  * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
- * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ * h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
  */
 declare function formatRgb(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `hsl(H S% L%)` string.
- * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ * h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
  */
 declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `oklch(L C H)` string.
- * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ * h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
  */
 declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
 /**
@@ -1567,5 +2034,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeGlowInput, type GlazeJsonOptions, type GlazeLightingInput, type GlazeOutputModes, type GlazePalette, type GlazePaletteCssOptions, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazePaletteTastyOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTastyOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, type GlazeTokenOptions, type GlowColorDef, type GlowTuning, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type LightingTuning, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, apcaLuminanceFromLinearRgb, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map