@tenphi/glaze 0.0.0-snapshot.ce4ace8 → 0.0.0-snapshot.d79cac8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -102,9 +102,17 @@ interface FindToneForContrastOptions {
102
102
  epsilon?: number;
103
103
  /** Maximum binary-search iterations per branch. Default: 18. */
104
104
  maxIterations?: number;
105
- /** Preferred search direction before auto-flip is considered. */
105
+ /**
106
+ * Preferred search direction before auto-flip is considered. Default: the
107
+ * side whose bound scores higher (the only open side when `preferredTone`
108
+ * sits on a bound); a tie within float noise starts `'darker'`.
109
+ */
106
110
  initialDirection?: 'lighter' | 'darker';
107
- /** Auto-flip tone direction when contrast can't be met. Default: false. */
111
+ /**
112
+ * Also search the opposite direction. Default: false. When both directions
113
+ * meet the target, the result nearer `preferredTone` wins; a gap within
114
+ * twice the search resolution is a tie and keeps `initialDirection`.
115
+ */
108
116
  flip?: boolean;
109
117
  /**
110
118
  * When `flip` is on and *both* directions meet the target, keep
@@ -129,26 +137,42 @@ interface FindToneForContrastResult {
129
137
  contrast: number;
130
138
  /** Whether the target was reached. */
131
139
  met: boolean;
132
- /** Which branch was selected. */
140
+ /**
141
+ * The side the result was found on. The two sides meet at `preferredTone`,
142
+ * so a met result sits on that side of the base too. `'preferred'` whenever
143
+ * a met result is `preferredTone` itself: it already cleared the
144
+ * overshooting search target, or it clears the bare target and no search
145
+ * could improve on it — no searched side met the floor, or the starting
146
+ * side's only position was `preferredTone` (it sits on that side's bound).
147
+ * Also `'preferred'` when `toneRange` leaves no room to search, met or not.
148
+ * An unmet result otherwise reports the side whose extreme it pinned to.
149
+ */
133
150
  branch: 'lighter' | 'darker' | 'preferred';
134
151
  /** Whether the result auto-flipped to the opposite direction. */
135
152
  flipped?: boolean;
136
153
  }
137
154
  /**
138
155
  * Find the tone that satisfies a contrast floor against a base color,
139
- * staying as close to `preferredTone` as possible.
156
+ * staying as close to `preferredTone` as possible. A searched result keeps the
157
+ * overshoot (1% for WCAG, 0.5 Lc for APCA). When no searched side reaches the
158
+ * floor, the result pins to the initial direction's extreme, unmet — unless
159
+ * `preferredTone` itself clears the bare target, which is then kept as met
160
+ * (`branch: 'preferred'`, the same label a met result gets when the starting
161
+ * side's only position is `preferredTone`).
140
162
  */
141
163
  declare function findToneForContrast(options: FindToneForContrastOptions): FindToneForContrastResult;
142
164
  interface FindValueForMixContrastOptions {
143
165
  /** Preferred mix parameter (0–1). */
144
166
  preferredValue: number;
145
- /** Base color as linear sRGB. */
167
+ /** Base color as linear sRGB — the color the mix is measured against. */
146
168
  baseLinearRgb: LinearRgb;
147
- /** Target color as linear sRGB. */
148
- targetLinearRgb: LinearRgb;
149
169
  /** Resolved contrast floor (metric + target). */
150
170
  contrast: ResolvedContrast;
151
- /** Compute the luminance of the mixed color at parameter t. */
171
+ /**
172
+ * Luminance of the mixed color at parameter t, in the metric's basis
173
+ * ({@link metricLuminance}). This closure is the only view the solver has of
174
+ * the mix's target color, blend, and color space.
175
+ */
152
176
  luminanceAtValue: (t: number) => number;
153
177
  /** Convergence threshold. Default: 1e-4. */
154
178
  epsilon?: number;
@@ -166,6 +190,9 @@ interface FindValueForMixContrastResult {
166
190
  /**
167
191
  * Find the mix parameter (ratio or opacity) that satisfies a contrast floor
168
192
  * against a base color, staying as close to `preferredValue` as possible.
193
+ * Misses pin to the initial direction's end like the tone solver, and a
194
+ * `preferredValue` that clears the bare target is kept as met when no searched
195
+ * side reaches the floor (a value of 1 has no room toward the target).
169
196
  */
170
197
  declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
171
198
  //#endregion
@@ -224,6 +251,13 @@ type ExtremeValue = 'max' | 'min';
224
251
  type ToneValue = number | RelativeValue | ExtremeValue;
225
252
  /** Color format for output. */
226
253
  type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
254
+ /**
255
+ * Output format for an HDR glow value (`glaze.formatHdr()`). Only
256
+ * `'srgb-linear'` — `color(srgb-linear R G B)` with channels that may exceed
257
+ * 1 — since OKLCH lightness clamps at parse time and `rgb()` / `hsl()` cannot
258
+ * go past white.
259
+ */
260
+ type GlazeHdrFormat = 'srgb-linear';
227
261
  /**
228
262
  * Controls which scheme variants are generated in the export.
229
263
  * Light is always included (it's the default).
@@ -241,6 +275,19 @@ interface GlazeOutputModes {
241
275
  * @see GlazeConfig.contrastLevel
242
276
  */
243
277
  highContrast?: boolean;
278
+ /**
279
+ * Include the HDR tier of glows past SDR white (`variant.hdr`, set by
280
+ * `GlowTuning.headroom`). Default: false — every exporter's output stays
281
+ * byte-identical to SDR even when a headroom is set.
282
+ *
283
+ * When on, each exporter adds the HDR values next to the SDR ones it
284
+ * already emits (only for the scheme variants the other modes include),
285
+ * always written as `color(srgb-linear R G B)`: Tasty `hdr` state keys,
286
+ * `json()` `lightHdr` / `darkHdr` / … keys, `tokens()` `lightHdr` / … maps,
287
+ * Tailwind blocks under `hdrSelector`, DTCG `$extensions`. `css()` reads
288
+ * its own `hdr` option, which falls back to this.
289
+ */
290
+ hdr?: boolean;
244
291
  }
245
292
  /** Hex color string for DX hints. Runtime validation in `parseHex()`. */
246
293
  type HexColor = `#${string}`;
@@ -296,7 +343,7 @@ interface RegularColorDef {
296
343
  */
297
344
  from?: GlazeColorValue;
298
345
  /**
299
- * Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
346
+ * Tone value (0–100, contrast-uniform — see `docs/okhst.mdx`).
300
347
  * - Number: absolute tone.
301
348
  * - String ('+N' / '-N'): relative to base color's tone (requires `base`).
302
349
  * - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
@@ -390,44 +437,96 @@ interface RegularColorDef {
390
437
  */
391
438
  inherit?: boolean;
392
439
  }
393
- /** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
394
- interface ShadowTuning {
395
- /** Fraction of fg saturation kept in pigment (0-1). Default: 0.18. */
396
- saturationFactor?: number;
397
- /** Upper clamp on pigment saturation (0-1). Default: 0.25. */
398
- maxSaturation?: number;
399
- /** Multiplier for bg lightness → pigment lightness. Default: 0.25. */
400
- lightnessFactor?: number;
401
- /** [min, max] clamp for pigment lightness (0-1). Default: [0.05, 0.20]. */
402
- lightnessBounds?: [number, number];
440
+ /**
441
+ * Tuning shared by `shadow` and `glow`. Global defaults come from
442
+ * `shadowTuning` / `glowTuning`; a per-color `tuning` merges over them field
443
+ * by field.
444
+ */
445
+ interface LightingTuning {
446
+ /**
447
+ * β — how strongly the object (`fg`) scales the step. The step is
448
+ * `intensity × k` with `k = max(0, 1 + β · d · (t_bg − t_fg) / 100)`,
449
+ * `d = +1` for a shadow and `−1` for a glow: a darker object deepens its
450
+ * shadow, a lighter one strengthens its glow. An object at the surface's
451
+ * own tone (or no `fg`) gives exactly `intensity`. `0` ignores the object.
452
+ * Default: 0.5.
453
+ */
454
+ objectInfluence?: number;
455
+ /**
456
+ * Pigment saturation (0–1) in the surface's hue. Default: 0 (neutral black /
457
+ * white). Shows only with `reach` below 1 — pure black and white have no hue.
458
+ * A neutral surface has no hue either: there the tint takes the object's
459
+ * hue with `hueBleed` above 0, and the pigment stays neutral otherwise.
460
+ */
461
+ tint?: number;
403
462
  /**
404
- * Target minimum gap between pigment lightness and bg lightness (0-1).
405
- * Default: 0.05.
463
+ * Where the pigment sits (0–1): the fraction of the way from the surface's
464
+ * tone to black (shadow) / white (glow). Default: 1 (pure black / white),
465
+ * the most reach. Lower values let a `tint` show at the cost of reach.
406
466
  */
407
- minGapTarget?: number;
408
- /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
409
- alphaMax?: number;
467
+ reach?: number;
410
468
  /**
411
- * Blend weight (0-1) pulling pigment hue toward bg hue.
412
- * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
469
+ * Pull (0–1) of the pigment hue from the surface's hue toward the object's
470
+ * (`fg`) hue. Default: 0. Needs `fg`, a `tint`, and `reach` below 1 to show.
413
471
  */
414
- bgHueBlend?: number;
472
+ hueBleed?: number;
415
473
  }
474
+ /**
475
+ * Tuning for `shadow` colors: the shared {@link LightingTuning}. It has no
476
+ * `headroom` — a shadow darkens toward black, and nothing goes below black —
477
+ * so a `headroom` set on a shadow's tuning throws.
478
+ */
479
+ type ShadowTuning = LightingTuning;
480
+ /** Tuning for `glow` colors: the shared {@link LightingTuning} plus HDR `headroom`. */
481
+ interface GlowTuning extends LightingTuning {
482
+ /**
483
+ * Stops above SDR white a glow may use when its step crosses white. Default:
484
+ * 0 (SDR only). Counted in stops — doublings of SDR white's luminance — not
485
+ * as a ratio: `1` allows up to 2× white, `2` up to 4×. Must be a finite
486
+ * number ≥ 0; values above 2 clamp to 2 with a one-time warning.
487
+ *
488
+ * Only a glow whose target tone (surface tone + `intensity × k`) passes 100
489
+ * gets an HDR value: the variant's `hdr`, an opaque exposure of what SDR
490
+ * paints at its brightest — the pigment at full opacity, or a white surface
491
+ * no pigment can lift — plus a gain in stops. A pigment that cannot lift a
492
+ * non-white surface at all (`reach: 0` on a gray surface, say) paints
493
+ * nothing in SDR, so it gets no HDR value either and keeps the SDR "cannot
494
+ * reach" warning. On a chromatic surface a `reach: 0` gray can measure
495
+ * slightly brighter than the surface and pins at full opacity instead.
496
+ * Nothing about the SDR variant changes. The gain lands the exact step when
497
+ * the headroom allows it; the brightest channel caps at `2^headroom`.
498
+ * High-contrast schemes use the same headroom.
499
+ *
500
+ * The HDR value lands the whole step, not just the part past white. A
501
+ * full-reach glow (the default `reach: 1`) is pinned at white, so its HDR
502
+ * value starts at white (`exposure` → 0) as the target passes 100. A glow
503
+ * with `reach` below 1 is pinned at its pigment, below white: just under 100
504
+ * it stays short there (and warns), and just past 100 its HDR value jumps to
505
+ * the exact step.
506
+ */
507
+ headroom?: number;
508
+ }
509
+ /**
510
+ * A translucent dark overlay that lands the surface (`bg`) exactly
511
+ * `intensity` tones darker in every scheme — a shade for state layers and
512
+ * scrims, or, with `fg`, an object-aware drop shadow.
513
+ */
416
514
  interface ShadowColorDef {
417
515
  type: 'shadow';
418
516
  /**
419
- * Background color name — the surface the shadow sits on.
420
- * Must reference a non-shadow color in the same theme.
517
+ * The surface the shadow falls on. Must reference a color that is not a
518
+ * shadow or glow.
421
519
  */
422
520
  bg: string;
423
521
  /**
424
- * Foreground color name for tinting and intensity modulation.
425
- * Must reference a non-shadow color in the same theme.
426
- * Omit for achromatic shadow at full user-specified intensity.
522
+ * The object casting the shadow (e.g. the card). A darker object casts a
523
+ * deeper shadow, a lighter one a softer shadow — see
524
+ * `LightingTuning.objectInfluence`. Omit for an exact shade of `intensity`
525
+ * tones. Must reference a color that is not a shadow or glow.
427
526
  */
428
527
  fg?: string;
429
528
  /**
430
- * Shadow intensity, 0-100.
529
+ * Tone step, 0–100: how many tones darker than `bg` the composite lands.
431
530
  * Supports [normal, highContrast] pair.
432
531
  */
433
532
  intensity: HCPair<number>;
@@ -446,6 +545,44 @@ interface ShadowColorDef {
446
545
  */
447
546
  inherit?: boolean;
448
547
  }
548
+ /**
549
+ * The mirror of {@link ShadowColorDef}: a translucent light overlay that lands
550
+ * the surface (`bg`) exactly `intensity` tones lighter in every scheme — for
551
+ * dark-mode elevation, edge highlights, and lightening state layers.
552
+ */
553
+ interface GlowColorDef {
554
+ type: 'glow';
555
+ /**
556
+ * The surface the glow falls on. Must reference a color that is not a
557
+ * shadow or glow.
558
+ */
559
+ bg: string;
560
+ /**
561
+ * The object emitting the glow. A lighter object glows stronger, a darker
562
+ * one weaker — see `LightingTuning.objectInfluence`. Omit for an exact tint
563
+ * of `intensity` tones. Must reference a color that is not a shadow or glow.
564
+ */
565
+ fg?: string;
566
+ /**
567
+ * Tone step, 0–100: how many tones lighter than `bg` the composite lands.
568
+ * Supports [normal, highContrast] pair.
569
+ */
570
+ intensity: HCPair<number>;
571
+ /** Override default tuning. Merged field-by-field with global `glowTuning`. */
572
+ tuning?: GlowTuning;
573
+ /**
574
+ * Per-color override for the hue-independent "safe" chroma limit used in
575
+ * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
576
+ * Falls through to the per-theme / per-token `pastel` override when omitted.
577
+ * @see GlazeConfigOverride.pastel
578
+ */
579
+ pastel?: boolean;
580
+ /**
581
+ * Whether this color is inherited by child themes created via `extend()`.
582
+ * Default: true. Set to false to make this color local to the current theme.
583
+ */
584
+ inherit?: boolean;
585
+ }
449
586
  interface MixColorDef {
450
587
  type: 'mix';
451
588
  /** Background/base color name — the "from" color. */
@@ -467,9 +604,12 @@ interface MixColorDef {
467
604
  /**
468
605
  * Interpolation color space for opaque blending. Default: 'okhsl'.
469
606
  * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
470
- * - 'srgb': linear sRGB interpolation, matches browser compositing.
607
+ * - 'srgb': linear-light sRGB interpolation (like CSS
608
+ * `color-mix(in srgb-linear, …)`).
471
609
  *
472
- * Ignored for 'transparent' blend (always composites in linear sRGB).
610
+ * Ignored for 'transparent' blend: the browser composites that one, and
611
+ * its contrast solve models the browser (`source-over` on gamma-encoded
612
+ * sRGB).
473
613
  */
474
614
  space?: 'okhsl' | 'srgb';
475
615
  /**
@@ -499,7 +639,7 @@ interface MixColorDef {
499
639
  */
500
640
  inherit?: boolean;
501
641
  }
502
- type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
642
+ type ColorDef = RegularColorDef | ShadowColorDef | GlowColorDef | MixColorDef;
503
643
  type ColorMap = Record<string, ColorDef>;
504
644
  /**
505
645
  * Resolved color for a single scheme variant.
@@ -523,6 +663,35 @@ interface ResolvedColorVariant {
523
663
  * gamut mapping applied during resolution.
524
664
  */
525
665
  pastel?: boolean;
666
+ /**
667
+ * HDR tier of a glow whose step crosses SDR white, present only when the
668
+ * glow's `headroom` is above 0, its target tone passes 100, and SDR is
669
+ * pinned at its brightest — the pigment at full opacity, or a white surface
670
+ * (see `GlowTuning.headroom`). Absent everywhere else — shadows, mixes,
671
+ * regular colors, a glow whose pigment cannot lift a non-white surface, and
672
+ * every glow at the default headroom of 0.
673
+ */
674
+ hdr?: ResolvedHdr;
675
+ }
676
+ /**
677
+ * The HDR value of a glow past SDR white: an opaque base plus a gain. The base
678
+ * is what SDR paints at its brightest — the glow's pigment at full opacity, or
679
+ * the white surface it cannot lift — and the HDR color is that base's linear
680
+ * sRGB times `2^exposure`. Format it with `glaze.formatHdr()`.
681
+ *
682
+ * Stored in OKHST like the variant. `s` is always standard (non-pastel)
683
+ * OKHSL saturation, whatever the variant's `pastel`, since the base is an
684
+ * arbitrary in-gamut composite.
685
+ */
686
+ interface ResolvedHdr {
687
+ /** Base OKHSL hue (0–360). */
688
+ h: number;
689
+ /** Base OKHSL saturation (0–1, non-pastel). */
690
+ s: number;
691
+ /** Base canonical tone (0–1, reference eps). */
692
+ t: number;
693
+ /** Gain over the base in stops (`log2` of the linear factor), above 0. */
694
+ exposure: number;
526
695
  }
527
696
  /** Fully resolved color across all scheme variants. */
528
697
  interface ResolvedColor {
@@ -531,7 +700,7 @@ interface ResolvedColor {
531
700
  dark: ResolvedColorVariant;
532
701
  lightContrast: ResolvedColorVariant;
533
702
  darkContrast: ResolvedColorVariant;
534
- /** Adaptation mode. Present only for regular colors, omitted for shadows. */
703
+ /** Adaptation mode of a regular color; `undefined` for shadow / glow / mix. */
535
704
  mode?: AdaptationMode;
536
705
  }
537
706
  /**
@@ -557,20 +726,31 @@ interface GlazeConfig {
557
726
  darkDesaturation?: number;
558
727
  /**
559
728
  * State alias names for Tasty token export. Default to media-query states
560
- * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`)
561
- * so tokens react to the OS preference without registering custom states.
729
+ * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`
730
+ * / `'@media(dynamic-range: high)'`) so tokens react to the OS preference
731
+ * and the display without registering custom states. `hdr` keys an HDR
732
+ * glow value and is used only with `modes.hdr`.
562
733
  */
563
734
  states?: {
564
735
  dark?: string;
565
736
  highContrast?: string;
737
+ hdr?: string;
566
738
  };
567
739
  /**
568
740
  * Which scheme variants to include in exports. Defaults: `dark: true`,
569
- * `highContrast: false`.
741
+ * `highContrast: false`, `hdr: false`.
570
742
  */
571
743
  modes?: GlazeOutputModes;
572
- /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
744
+ /**
745
+ * Default tuning for all shadow colors. Per-color tuning merges field-by-field.
746
+ * A `headroom` here throws: it is a glow-only field.
747
+ */
573
748
  shadowTuning?: ShadowTuning;
749
+ /**
750
+ * Default tuning for all glow colors, including HDR `headroom`. Per-color
751
+ * tuning merges field-by-field.
752
+ */
753
+ glowTuning?: GlowTuning;
574
754
  /**
575
755
  * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
576
756
  * contrast (`100`), or `'auto'` (the default) to take the authored normal
@@ -590,7 +770,7 @@ interface GlazeConfig {
590
770
  * approximation, and a color keeps to one side of its base as the level moves.
591
771
  *
592
772
  * Pass `'auto'` to leave manual mode; `configure()` never clears a field by
593
- * omission. See `docs/api.md` for the ramp's edge cases (un-interpolable
773
+ * omission. See `docs/reference/contrast.md` for the ramp's edge cases (un-interpolable
594
774
  * pairs, side changes) and the export-freeze rule.
595
775
  *
596
776
  * @default 'auto'
@@ -626,9 +806,11 @@ interface GlazeConfigResolved {
626
806
  states: {
627
807
  dark: string;
628
808
  highContrast: string;
809
+ hdr: string;
629
810
  };
630
811
  modes: Required<GlazeOutputModes>;
631
812
  shadowTuning?: ShadowTuning;
813
+ glowTuning?: GlowTuning;
632
814
  autoFlip: boolean;
633
815
  /**
634
816
  * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
@@ -690,12 +872,22 @@ interface GlazeConfigOverride {
690
872
  * standalone color tokens.
691
873
  */
692
874
  shadowTuning?: ShadowTuning;
875
+ /**
876
+ * Glow tuning defaults. Only meaningful for themes; harmless on
877
+ * standalone color tokens.
878
+ */
879
+ glowTuning?: GlowTuning;
693
880
  }
694
881
  /**
695
882
  * Current authoring-export schema version. Bump when the export shape
696
883
  * changes in a non-compatible way. Written on every `.export()` snapshot.
884
+ *
885
+ * - `1` — Glaze 2.x.
886
+ * - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
887
+ * `glow` was added. Version-1 theme snapshots that carry shadow defs or a
888
+ * `shadowTuning` are rejected on restore.
697
889
  */
698
- declare const GLAZE_EXPORT_VERSION: 1;
890
+ declare const GLAZE_EXPORT_VERSION: 2;
699
891
  /** Literal type of {@link GLAZE_EXPORT_VERSION}. */
700
892
  type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
701
893
  /** Discriminator for authoring export snapshots. */
@@ -720,23 +912,27 @@ interface GlazeThemeExport {
720
912
  */
721
913
  config?: GlazeConfigOverride;
722
914
  }
723
- /** Input for `glaze.shadow()` standalone factory. */
724
- interface GlazeShadowInput {
915
+ /** Input for the `glaze.shadow()` and `glaze.glow()` standalone factories. */
916
+ interface GlazeLightingInput {
725
917
  /**
726
- * Background color — accepts any `GlazeColorValue` form: hex
727
- * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
728
- * / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
729
- * `{ l, c, h }`). Alpha components are dropped with a warning.
918
+ * The surface — accepts any `GlazeColorValue` form: hex
919
+ * (`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` /
920
+ * `okhsl()` / `okhst()` / `oklch()` strings, or literal objects
921
+ * (`{ r, g, b }`, `{ h, s, l }`, `{ h, s, t }`, `{ l, c, h }`). Alpha
922
+ * components are dropped with a warning.
730
923
  */
731
924
  bg: GlazeColorValue;
732
- /**
733
- * Foreground color for tinting + intensity modulation. Accepts the
734
- * same forms as `bg`.
735
- */
925
+ /** The object casting the shadow / emitting the glow. Same forms as `bg`. */
736
926
  fg?: GlazeColorValue;
737
- /** Intensity 0-100. */
927
+ /** Tone step, 0–100. */
738
928
  intensity: number;
739
- tuning?: ShadowTuning;
929
+ tuning?: LightingTuning;
930
+ }
931
+ /** Input for `glaze.shadow()`. */
932
+ type GlazeShadowInput = GlazeLightingInput;
933
+ /** Input for `glaze.glow()`: the shared input, with glow tuning (`headroom`). */
934
+ interface GlazeGlowInput extends GlazeLightingInput {
935
+ tuning?: GlowTuning;
740
936
  }
741
937
  /** Input for the structured `glaze.color()` overload. */
742
938
  interface GlazeColorInput {
@@ -769,14 +965,17 @@ interface GlazeColorInput {
769
965
  */
770
966
  base?: GlazeColorToken | GlazeColorValue;
771
967
  /**
772
- * Contrast floor against `base`. Requires `base` to be set. A bare
968
+ * Contrast floor. Without `base`, solved against the token's own input
969
+ * color (`hue`, `saturation`, normal `tone`), held fixed in every scheme;
970
+ * with `base`, against the base's resolved variant per scheme. A bare
773
971
  * number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
774
972
  */
775
973
  contrast?: HCPair<ContrastSpec>;
776
974
  /**
777
975
  * Optional human-readable name for the token. Used in error and
778
976
  * warning messages (otherwise an internal name like `"value"` is
779
- * used). Does not affect output keys.
977
+ * used) and as `resolve().name`. A debug label only: it does not
978
+ * affect output keys or the token's `role`.
780
979
  */
781
980
  name?: string;
782
981
  /**
@@ -787,11 +986,12 @@ interface GlazeColorInput {
787
986
  */
788
987
  pastel?: boolean;
789
988
  /**
790
- * Semantic role against `base` / the literal seed: how this token is used.
791
- * Fixes APCA contrast polarity. Same resolution chain as
792
- * `RegularColorDef.role` (explicit → name inference → opposite of base →
793
- * `'text'`). For standalone tokens the name is internal, so set `role`
794
- * explicitly or rely on the base-opposite / foreground default.
989
+ * Semantic role against the token's anchor (`base`, or its own input
990
+ * color when `contrast` is set without one): how this token is used.
991
+ * Fixes APCA contrast polarity; WCAG ignores it. Defaults to `'text'` —
992
+ * the token is the foreground and the anchor the background, with or
993
+ * without `base`. Unlike a theme color, a token never infers its role
994
+ * from `name`, so `inferRole` has no effect on it.
795
995
  */
796
996
  role?: RoleInput;
797
997
  }
@@ -799,17 +999,35 @@ interface GlazeColorInput {
799
999
  * Any single-color input form accepted by the value-shorthand
800
1000
  * overload of `glaze.color()`.
801
1001
  *
802
- * Strings cover hex (`#rgb` / `#rrggbb` / `#rrggbbaa`, alpha dropped
803
- * with a warning) and the four CSS color functions Glaze itself emits:
804
- * `rgb()`, `hsl()`, `okhsl()`, `oklch()` (alpha components also dropped
805
- * with a warning).
1002
+ * Strings cover hex with a leading `#` (`#rgb` / `#rgba` / `#rrggbb` /
1003
+ * `#rrggbbaa`) and the five color functions Glaze itself emits: `rgb()`,
1004
+ * `hsl()`, `okhsl()`, `okhst()`, `oklch()`, plus the `rgba()` / `hsla()`
1005
+ * aliases. Function names are case-insensitive; components are numbers or
1006
+ * percentages, separated by spaces or commas. Their scales:
1007
+ * - `rgb()` — channels 0–255, or percentages (`100%` is 255).
1008
+ * - `hsl()` / `okhsl()` / `okhst()` — saturation, lightness and tone are
1009
+ * percentages or bare 0–1 fractions: `hsl(120 50% 50%)` or
1010
+ * `hsl(120 0.5 0.5)`. Unlike CSS, a bare `hsl(120 50 50)` does not mean
1011
+ * 50%; it is out of range and resolves to white without a warning.
1012
+ * - `oklch()` — L 0–1 or a percentage; C bare, or a percentage where
1013
+ * `100%` is 0.4.
1014
+ * - Hue is in degrees, bare or with `deg`. Other angle units (`turn`,
1015
+ * `rad`, `grad`) are misread as degrees rather than rejected.
1016
+ *
1017
+ * An alpha component (hex alpha, `/ A`, or any fourth component) is
1018
+ * dropped with a warning. Named colors, other color functions, and
1019
+ * relative color syntax throw.
806
1020
  *
807
- * Literal object forms:
808
- * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l`
809
- * throws with a hint to use the structured form.
810
- * - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1.
1021
+ * Literal object forms, told apart by their keys:
811
1022
  * - `{ r, g, b }` — sRGB 0–255.
812
1023
  * - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
1024
+ * - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1, so `t: 0.7` is
1025
+ * tone 70.
1026
+ * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1).
1027
+ *
1028
+ * An object `s`, `l`, `t` or `c` above 1.5 throws, which catches 0–100
1029
+ * input; the OKHSL / OKHST errors point to the structured form. String
1030
+ * components have no such check.
813
1031
  */
814
1032
  type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
815
1033
  /** Color overrides for the `from` and value-shorthand inputs. */
@@ -888,11 +1106,10 @@ interface GlazeColorOverrides {
888
1106
  * tone per-scheme (matches theme behavior for dependent colors).
889
1107
  * - Relative `hue: '+N'` / `'-N'` still anchors to the seed (the
890
1108
  * value passed to `glaze.color()`), not the base.
891
- * - When the base was created via the structured form (with explicit
892
- * `hue`/`saturation`/`tone`), it is resolved at full range
893
- * (`lightTone: false`) for the linking math — ensuring the
894
- * contrast/tone anchor matches the input tone, not the
895
- * windowed output. The base's own `.resolve()` output is unaffected.
1109
+ * - The link resolves against the base token's own variants in every
1110
+ * scheme: what the base paints, under its own config, whatever form
1111
+ * the base was made in. A light `'+0'` lands on the base and a light
1112
+ * `contrast` floor is measured against it.
896
1113
  *
897
1114
  * The base token's `.resolve()` is called lazily on first resolve and
898
1115
  * its result is captured by reference; later mutations to the base's
@@ -908,7 +1125,8 @@ interface GlazeColorOverrides {
908
1125
  /**
909
1126
  * Optional human-readable name for the token. Used in error and
910
1127
  * warning messages (otherwise an internal name like `"value"` is
911
- * used). Does not affect output keys.
1128
+ * used) and as `resolve().name`. A debug label only: it does not
1129
+ * affect output keys or the token's `role`.
912
1130
  */
913
1131
  name?: string;
914
1132
  /**
@@ -919,9 +1137,12 @@ interface GlazeColorOverrides {
919
1137
  */
920
1138
  pastel?: boolean;
921
1139
  /**
922
- * Semantic role against `base` / the literal seed: how this token is used.
923
- * Fixes APCA contrast polarity. Same resolution chain as
924
- * `RegularColorDef.role`.
1140
+ * Semantic role against the token's anchor (`base`, or the literal seed
1141
+ * when `contrast` / a relative `tone` is set without one): how this token
1142
+ * is used. Fixes APCA contrast polarity; WCAG ignores it. Defaults to
1143
+ * `'text'` — the token is the foreground and the anchor the background,
1144
+ * with or without `base`. Unlike a theme color, a token never infers its
1145
+ * role from `name`, so `inferRole` has no effect on it.
925
1146
  */
926
1147
  role?: RoleInput;
927
1148
  }
@@ -954,8 +1175,9 @@ interface GlazeColorCssOptions {
954
1175
  */
955
1176
  suffix?: string;
956
1177
  /**
957
- * Emit hue as a separate custom property, referenced via `var()`.
958
- * Requires `format: 'oklch'` and a pastel token. oklch + all-pastel only.
1178
+ * Emit hue as a separate `--{name}-hue` custom property, referenced via
1179
+ * `var()`. Requires `format: 'oklch'` (any other format throws) and a
1180
+ * pastel token.
959
1181
  */
960
1182
  splitHue?: boolean;
961
1183
  }
@@ -1144,16 +1366,26 @@ interface GlazeTheme {
1144
1366
  * theme.tokens()
1145
1367
  * // → { light: { surface: 'okhsl(...)' }, dark: { surface: 'okhsl(...)' } }
1146
1368
  * ```
1369
+ *
1370
+ * With `modes.hdr`, each scheme map is followed by a dense `<scheme>Hdr`
1371
+ * map (`lightHdr`, `darkHdr`, …): every glow with an HDR value in any
1372
+ * emitted scheme, as `color(srgb-linear …)`, or its SDR value where that
1373
+ * scheme has none.
1147
1374
  */
1148
1375
  tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
1149
1376
  /**
1150
1377
  * Export as tasty style-to-state bindings.
1151
1378
  * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
1152
1379
  * Spread into component styles or register as a recipe via `configure({ recipes })`.
1380
+ * With `modes.hdr`, a glow's HDR value follows each SDR key that has one,
1381
+ * under `states.hdr` (`'@media(dynamic-range: high)'`) combined with it.
1153
1382
  * @see https://tasty.style/docs
1154
1383
  */
1155
- tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
1156
- /** Export as plain JSON. */
1384
+ tasty(options?: GlazeTastyOptions): Record<string, Record<string, string>>;
1385
+ /**
1386
+ * Export as plain JSON. With `modes.hdr`, a glow variant with an HDR value
1387
+ * adds a `<scheme>Hdr` key (`lightHdr`, …) right after its SDR key.
1388
+ */
1157
1389
  json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
1158
1390
  /** Export as CSS custom property declarations. */
1159
1391
  css(options?: GlazeCssOptions): GlazeCssResult;
@@ -1190,35 +1422,48 @@ interface GlazeExtendOptions {
1190
1422
  /** Config override for the child theme. Merged with the parent's override. */
1191
1423
  config?: GlazeConfigOverride;
1192
1424
  }
1425
+ /**
1426
+ * Options for `token.token()` / `token.tasty()`, and the base of the theme and
1427
+ * palette `tasty()` options: output format, scheme variants, state aliases.
1428
+ */
1193
1429
  interface GlazeTokenOptions {
1194
- /** Prefix mode. `true` uses "<themeName>-", or provide a custom map. */
1195
- prefix?: boolean | Record<string, string>;
1196
- /** Override state aliases for this export. */
1430
+ /**
1431
+ * Override state aliases for this export. `hdr` keys an HDR glow value
1432
+ * (with `modes.hdr`); a `glaze.color()` token is never a glow, so it never
1433
+ * uses it.
1434
+ */
1197
1435
  states?: {
1198
1436
  dark?: string;
1199
1437
  highContrast?: string;
1438
+ hdr?: string;
1200
1439
  };
1201
1440
  /** Override which scheme variants to include. */
1202
1441
  modes?: GlazeOutputModes;
1203
1442
  /** Output color format. Default: 'oklch'. */
1204
1443
  format?: GlazeColorFormat;
1444
+ }
1445
+ /** Options for `theme.tasty()`. */
1446
+ interface GlazeTastyOptions extends GlazeTokenOptions {
1205
1447
  /**
1206
1448
  * Emit hue as a separate custom property, referenced via `var()`.
1207
- * Requires `format: 'oklch'` and every color to be pastel.
1449
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1450
+ * be pastel.
1208
1451
  */
1209
1452
  splitHue?: boolean;
1210
1453
  /**
1211
1454
  * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
1212
- * Palette export auto-derives this from the theme name.
1455
+ * Must not equal the name of a color that sets its own hue (throws).
1213
1456
  */
1214
1457
  name?: string;
1215
1458
  }
1459
+ /** Options for `theme.tokens()` / `theme.json()` and their palette and token counterparts. */
1216
1460
  interface GlazeJsonOptions {
1217
1461
  /** Override which scheme variants to include. */
1218
1462
  modes?: GlazeOutputModes;
1219
1463
  /** Output color format. Default: 'oklch'. */
1220
1464
  format?: GlazeColorFormat;
1221
1465
  }
1466
+ /** Options for `theme.css()`. */
1222
1467
  interface GlazeCssOptions {
1223
1468
  /** Output color format. Default: 'oklch'. */
1224
1469
  format?: GlazeColorFormat;
@@ -1226,22 +1471,43 @@ interface GlazeCssOptions {
1226
1471
  suffix?: string;
1227
1472
  /**
1228
1473
  * Emit hue as a separate custom property, referenced via `var()`.
1229
- * Requires `format: 'oklch'` and every color to be pastel.
1474
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1475
+ * be pastel.
1230
1476
  */
1231
1477
  splitHue?: boolean;
1232
1478
  /**
1233
1479
  * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
1234
- * Palette export auto-derives this from the theme name.
1480
+ * Must not equal the name of a color that sets its own hue (throws).
1235
1481
  */
1236
1482
  name?: string;
1483
+ /**
1484
+ * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
1485
+ * Default: the global `modes.hdr` (false). `css()` has no `modes` — it
1486
+ * always emits all four schemes — so this is its HDR switch.
1487
+ */
1488
+ hdr?: boolean;
1237
1489
  }
1238
- /** CSS custom property declarations grouped by scheme variant. */
1239
- interface GlazeCssResult {
1490
+ /** CSS custom property declarations for each scheme variant. */
1491
+ interface GlazeCssSchemeBlocks {
1240
1492
  light: string;
1241
1493
  dark: string;
1242
1494
  lightContrast: string;
1243
1495
  darkContrast: string;
1244
1496
  }
1497
+ /** CSS custom property declarations grouped by scheme variant. */
1498
+ interface GlazeCssResult extends GlazeCssSchemeBlocks {
1499
+ /**
1500
+ * The HDR tier, present when HDR output is on — the `hdr` option, which
1501
+ * defaults to the global `modes.hdr`: one block per scheme,
1502
+ * each re-declaring every color that has an HDR value in any scheme — its
1503
+ * HDR value (`color(srgb-linear R G B)`) where that scheme has one, and
1504
+ * the scheme's SDR declaration where it has none. The blocks are dense so
1505
+ * a light HDR value can never leak into dark: wire each one after the SDR
1506
+ * blocks, under the same selector plus `(dynamic-range: high)`. Every block
1507
+ * is an empty string when no color has an HDR value.
1508
+ */
1509
+ hdr?: GlazeCssSchemeBlocks;
1510
+ }
1245
1511
  /**
1246
1512
  * Color space used for DTCG `$value` color objects.
1247
1513
  * @see https://www.designtokens.org/
@@ -1271,14 +1537,49 @@ interface DtcgOklchColorValue {
1271
1537
  }
1272
1538
  /** A DTCG `$value` for a color token, in either supported color space. */
1273
1539
  type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;
1540
+ /**
1541
+ * The HDR value of a glow past SDR white, carried in a DTCG token's
1542
+ * `$extensions['me.tenphi.glaze'].hdr` (`$value` stays the SDR color, since
1543
+ * DTCG color components stop at 1). Maps onto native APIs: UIKit / AppKit
1544
+ * `exposure`, SwiftUI `exposureAdjust(exposure)` on `base`, or Android
1545
+ * `Color.pack(…components, LINEAR_EXTENDED_SRGB)` from `value`.
1546
+ */
1547
+ interface GlazeDtcgHdr {
1548
+ /** Gain over `base` in stops (`log2` of the linear factor), above 0. */
1549
+ exposure: number;
1550
+ /**
1551
+ * Luminance tone of the HDR value (e.g. `112`) — past 100 when the headroom
1552
+ * covers the step; a saturated base capped by `headroom` can land below 100,
1553
+ * though its brightest channel still exceeds 1.
1554
+ */
1555
+ tone: number;
1556
+ /** The opaque base (what SDR paints), as a DTCG sRGB color. */
1557
+ base: DtcgSrgbColorValue;
1558
+ /**
1559
+ * The HDR color: linear sRGB `base × 2^exposure`, its brightest channel
1560
+ * above 1 (the others may stay below).
1561
+ */
1562
+ value: {
1563
+ colorSpace: 'srgb-linear';
1564
+ components: [number, number, number];
1565
+ };
1566
+ }
1567
+ /** The Glaze namespace of a DTCG token's `$extensions`. */
1568
+ interface GlazeDtcgExtensions {
1569
+ 'me.tenphi.glaze': {
1570
+ /** Present only with `modes.hdr`, on a glow variant that has an HDR value. */hdr: GlazeDtcgHdr;
1571
+ };
1572
+ }
1274
1573
  /**
1275
1574
  * A single W3C DTCG color token: `{ $type: 'color', $value }`.
1276
- * `$description` is optional and not populated by Glaze today.
1575
+ * `$description` is optional and not populated by Glaze today. `$extensions`
1576
+ * is set only with `modes.hdr`, on a glow variant with an HDR value.
1277
1577
  */
1278
1578
  interface DtcgColorToken {
1279
1579
  $type: 'color';
1280
1580
  $value: DtcgColorValue;
1281
1581
  $description?: string;
1582
+ $extensions?: GlazeDtcgExtensions;
1282
1583
  }
1283
1584
  /**
1284
1585
  * A W3C Design Tokens Format Module (2025.10) token tree for one scheme.
@@ -1412,6 +1713,15 @@ interface GlazeTailwindOptions {
1412
1713
  * `.dark.high-contrast`).
1413
1714
  */
1414
1715
  highContrastSelector?: string;
1716
+ /**
1717
+ * Selector wrapping the HDR overrides, emitted with `modes.hdr` after every
1718
+ * SDR block. Default: `'@media (dynamic-range: high)'`. Each HDR block is
1719
+ * dense (every color with an HDR value in any emitted scheme, SDR value
1720
+ * where the scheme has none) and is scoped by this selector alone (light),
1721
+ * combined with `darkSelector` (dark), with `highContrastSelector` (light
1722
+ * high contrast), or with both.
1723
+ */
1724
+ hdrSelector?: string;
1415
1725
  }
1416
1726
  /** Options for `glaze.color().tailwind()`. `name` is required. */
1417
1727
  interface GlazeColorTailwindOptions extends GlazeTailwindOptions {
@@ -1434,7 +1744,10 @@ interface GlazePaletteOptions {
1434
1744
  */
1435
1745
  primary?: string;
1436
1746
  }
1437
- /** Options shared by palette `tokens()`, `tasty()`, and `css()` exports. */
1747
+ /**
1748
+ * Options shared by every palette export except `json()`: `tokens()`,
1749
+ * `tasty()`, `css()`, `dtcg()`, `dtcgResolver()`, and `tailwind()`.
1750
+ */
1438
1751
  interface GlazePaletteExportOptions {
1439
1752
  /**
1440
1753
  * Prefix mode. `true` uses `"<themeName>-"`, or provide a custom map.
@@ -1449,12 +1762,40 @@ interface GlazePaletteExportOptions {
1449
1762
  * When omitted, inherits the palette-level `primary`.
1450
1763
  */
1451
1764
  primary?: string | false;
1765
+ }
1766
+ /**
1767
+ * Options for `palette.tasty()`. There is no `name`: each theme's hue var is
1768
+ * named after the theme.
1769
+ */
1770
+ interface GlazePaletteTastyOptions extends GlazeTokenOptions, GlazePaletteExportOptions {
1452
1771
  /**
1453
1772
  * Emit hue as a separate custom property, referenced via `var()`.
1454
- * Requires `format: 'oklch'` and every color to be pastel.
1773
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1774
+ * be pastel. The theme-level hue var is `--{themeName}-hue`.
1455
1775
  */
1456
1776
  splitHue?: boolean;
1457
1777
  }
1778
+ /**
1779
+ * Options for `palette.css()`. There is no `name`: each theme's hue var is
1780
+ * named after the theme.
1781
+ */
1782
+ interface GlazePaletteCssOptions extends GlazePaletteExportOptions {
1783
+ /** Output color format. Default: 'oklch'. */
1784
+ format?: GlazeColorFormat;
1785
+ /** Suffix appended to each CSS custom property name. Default: '-color'. */
1786
+ suffix?: string;
1787
+ /**
1788
+ * Emit hue as a separate custom property, referenced via `var()`.
1789
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1790
+ * be pastel. The theme-level hue var is `--{themeName}-hue`.
1791
+ */
1792
+ splitHue?: boolean;
1793
+ /**
1794
+ * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
1795
+ * Default: the global `modes.hdr` (false).
1796
+ */
1797
+ hdr?: boolean;
1798
+ }
1458
1799
  interface GlazePalette {
1459
1800
  /** Theme names in insertion order. */
1460
1801
  list(): string[];
@@ -1492,13 +1833,14 @@ interface GlazePalette {
1492
1833
  * Prefix defaults to `true`. Inherits the palette-level `primary`.
1493
1834
  * @see https://tasty.style/docs
1494
1835
  */
1495
- tasty(options?: GlazeTokenOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
1496
- /** Export all themes as plain JSON grouped by theme name. */
1497
- json(options?: GlazeJsonOptions & {
1498
- prefix?: boolean | Record<string, string>;
1499
- }): Record<string, Record<string, Record<string, string>>>;
1836
+ tasty(options?: GlazePaletteTastyOptions): Record<string, Record<string, string>>;
1837
+ /**
1838
+ * Export all themes as plain JSON grouped by theme name. No prefix, primary
1839
+ * alias, or collision handling: each theme keeps its own key.
1840
+ */
1841
+ json(options?: GlazeJsonOptions): Record<string, Record<string, Record<string, string>>>;
1500
1842
  /** Export all themes as CSS custom property declarations. */
1501
- css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
1843
+ css(options?: GlazePaletteCssOptions): GlazeCssResult;
1502
1844
  /**
1503
1845
  * Export all themes as W3C DTCG documents, one per scheme variant.
1504
1846
  * Prefix defaults to `true`. Inherits the palette-level `primary`.
@@ -1520,14 +1862,6 @@ interface GlazePalette {
1520
1862
  tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
1521
1863
  }
1522
1864
  //#endregion
1523
- //#region src/serialize.d.ts
1524
- /** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
1525
- declare function isThemeExport(data: unknown): data is GlazeThemeExport;
1526
- /** Type guard for color-token authoring snapshots. */
1527
- declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
1528
- /** Type guard for palette authoring snapshots. */
1529
- declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
1530
- //#endregion
1531
1865
  //#region src/glaze.d.ts
1532
1866
  type PaletteInput = Record<string, GlazeTheme>;
1533
1867
  /**
@@ -1553,9 +1887,13 @@ type PaletteInput = Record<string, GlazeTheme>;
1553
1887
  * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
1554
1888
  * // with config override:
1555
1889
  * const raw = glaze(280, 80, { lightTone: false });
1890
+ * const rawSeed = glaze({ hue: 280, saturation: 80 }, { lightTone: false });
1556
1891
  * ```
1557
1892
  */
1558
- declare function glaze(hueOrOptions: number | GlazeThemeSeed, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
1893
+ declare function glaze(hue: number, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
1894
+ declare function glaze(seed: GlazeThemeSeed, config?: GlazeConfigOverride): GlazeTheme;
1895
+ /** @deprecated Pass the config second: `glaze(seed, config)`. */
1896
+ declare function glaze(seed: GlazeThemeSeed, saturation: undefined, config?: GlazeConfigOverride): GlazeTheme;
1559
1897
  declare namespace glaze {
1560
1898
  var configure: (config: GlazeConfig) => void;
1561
1899
  var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
@@ -1563,18 +1901,28 @@ declare namespace glaze {
1563
1901
  var from: (data: GlazeThemeExport) => GlazeTheme;
1564
1902
  var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
1565
1903
  var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
1904
+ var glow: (input: GlazeGlowInput) => ResolvedColorVariant;
1566
1905
  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
1906
+ var formatHdr: (variant: ResolvedColorVariant, hdrFormat?: GlazeHdrFormat) => string | undefined;
1567
1907
  var fromHex: (hex: string) => GlazeTheme;
1568
1908
  var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
1569
1909
  var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
1570
1910
  var paletteFrom: (data: GlazePaletteExport) => GlazePalette;
1571
- var isThemeExport: typeof isThemeExport;
1572
- var isColorTokenExport: typeof isColorTokenExport;
1573
- var isPaletteExport: typeof isPaletteExport;
1911
+ var isThemeExport: (value: unknown) => value is GlazeThemeExport;
1912
+ var isColorTokenExport: (value: unknown) => value is GlazeColorTokenExport;
1913
+ var isPaletteExport: (value: unknown) => value is GlazePaletteExport;
1574
1914
  var getConfig: () => GlazeConfigResolved;
1575
1915
  var resetConfig: () => void;
1576
1916
  }
1577
1917
  //#endregion
1918
+ //#region src/serialize.d.ts
1919
+ /** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
1920
+ declare function isThemeExport(data: unknown): data is GlazeThemeExport;
1921
+ /** Type guard for color-token authoring snapshots. */
1922
+ declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
1923
+ /** Type guard for palette authoring snapshots. */
1924
+ declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
1925
+ //#endregion
1578
1926
  //#region src/channels.d.ts
1579
1927
  interface HueDeclaration {
1580
1928
  prop: string;
@@ -1583,7 +1931,7 @@ interface HueDeclaration {
1583
1931
  interface HuePlan {
1584
1932
  /** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
1585
1933
  hueVar: string;
1586
- /** When true, emit a full inline color (shadow/mix/achromatic). */
1934
+ /** When true, emit a full inline color (shadow/glow/mix/achromatic). */
1587
1935
  inline: boolean;
1588
1936
  /** Scheme-independent `--*-hue` declarations for this color. */
1589
1937
  declarations: HueDeclaration[];
@@ -1619,12 +1967,14 @@ interface ChannelCtx {
1619
1967
  * emits raw CSS or non-Tasty token maps.
1620
1968
  */
1621
1969
  declare function assertNativeFormat(format: GlazeColorFormat | undefined, method: string): void;
1970
+ /** The modes `assertAllPastel` reads: which schemes are emitted. */
1971
+ type SchemeModes = Required<Pick<GlazeOutputModes, 'dark' | 'highContrast'>>;
1622
1972
  /**
1623
1973
  * Throw when `splitHue` is enabled but any exported color is not pastel.
1624
1974
  * Hue rotation is only clip-free when chroma is bounded by the hue-independent
1625
1975
  * safe chroma (`computeSafeChromaOKLCH`).
1626
1976
  */
1627
- declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: Required<GlazeOutputModes>): void;
1977
+ declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: SchemeModes): void;
1628
1978
  //#endregion
1629
1979
  //#region src/roles.d.ts
1630
1980
  /**
@@ -1720,7 +2070,11 @@ declare function variantToOkhsl(v: {
1720
2070
  *
1721
2071
  * Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
1722
2072
  * for both contrast metrics (WCAG 2 relative luminance and APCA screen
1723
- * luminance `Ys`), and multi-format output (okhsl, rgb, hsl, oklch).
2073
+ * luminance `Ys` — both the exact functions the contrast solver uses, and
2074
+ * both public), strict hex parsing (`parseHex` / `parseHexAlpha` check every
2075
+ * digit), and multi-format output (okhsl, rgb, hsl, oklch, plus the
2076
+ * `color(srgb-linear …)` writer for HDR glow values, whose channels may exceed
2077
+ * 1).
1724
2078
  */
1725
2079
  type Vec3 = [number, number, number];
1726
2080
  /**
@@ -1766,6 +2120,22 @@ declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean):
1766
2120
  * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
1767
2121
  */
1768
2122
  declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
2123
+ /**
2124
+ * Compute APCA screen luminance (`Ys`) from linear sRGB.
2125
+ *
2126
+ * APCA does not use the WCAG piecewise sRGB EOTF; it defines its own
2127
+ * luminance as `0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
2128
+ * gamma-encoded (display) channels with a simple 2.4 exponent. The APCA
2129
+ * soft-clamp threshold in `apcaContrast` is calibrated against this basis,
2130
+ * so the solver must feed it `Ys`, not WCAG relative luminance. Channels
2131
+ * are gamut-clamped to [0, 1] first, matching `gamutClampedLuminance`.
2132
+ *
2133
+ * This is exactly the luminance Glaze's contrast solver (and its drift
2134
+ * check) feeds `apcaContrast`, so
2135
+ * `apcaContrast(apcaLuminanceFromLinearRgb(text), apcaLuminanceFromLinearRgb(bg))`
2136
+ * reproduces the solver's Lc for a resolved pair.
2137
+ */
2138
+ declare function apcaLuminanceFromLinearRgb(linearRgb: [number, number, number]): number;
1769
2139
  /**
1770
2140
  * Convert OKLab to OKHSL.
1771
2141
  * Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
@@ -1775,6 +2145,11 @@ declare const oklabToOkhsl: (lab: Vec3, pastel?: boolean) => Vec3;
1775
2145
  /**
1776
2146
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
1777
2147
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
2148
+ *
2149
+ * A gray reads with saturation 0 (its computed hue is kept). Its OKLab
2150
+ * residue would otherwise come out as a saturation that grows toward white
2151
+ * (`#fefefe` reads 1.6e-5, `rgb(254.999 254.999 254.999)` 1.6e-2), which a
2152
+ * color carries into every scheme and an OKHSL mix reads as a hue.
1778
2153
  */
1779
2154
  declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [number, number, number];
1780
2155
  /**
@@ -1787,7 +2162,9 @@ declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [
1787
2162
  declare function hslToSrgb(h: number, s: number, l: number): [number, number, number];
1788
2163
  /**
1789
2164
  * Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
1790
- * Returns null if the string is not a valid hex color.
2165
+ * The leading `#` is optional. Returns null if the string is not a valid hex
2166
+ * color: a wrong length, any character outside `0-9a-f` (case-insensitive),
2167
+ * or a form with alpha.
1791
2168
  *
1792
2169
  * For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
1793
2170
  * use {@link parseHexAlpha}.
@@ -1796,7 +2173,12 @@ declare function parseHex(hex: string): [number, number, number] | null;
1796
2173
  /**
1797
2174
  * Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
1798
2175
  * sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
1799
- * Returns null if the string is not a valid hex color.
2176
+ * The leading `#` is optional. Returns null if the string is not a valid hex
2177
+ * color: a wrong length or any character outside `0-9a-f`
2178
+ * (case-insensitive).
2179
+ *
2180
+ * Every digit is checked up front: `parseInt` alone stops at the first bad
2181
+ * character, so `'#1z2z3z'` would otherwise read as `#010203`.
1800
2182
  */
1801
2183
  declare function parseHexAlpha(hex: string): {
1802
2184
  rgb: [number, number, number];
@@ -1831,6 +2213,14 @@ declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): s
1831
2213
  * h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
1832
2214
  */
1833
2215
  declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
2216
+ /**
2217
+ * Format linear sRGB channels as a CSS `color(srgb-linear R G B)` string with
2218
+ * 4 decimals. Unlike the other writers it takes linear light, not OKHSL, and
2219
+ * does not clamp: a channel may exceed 1, which is how an HDR glow value
2220
+ * (`glaze.formatHdr()`) goes past SDR white — `1` is SDR white, `2` one stop
2221
+ * above it. Opaque only; HDR values carry no alpha.
2222
+ */
2223
+ declare function formatSrgbLinear(rgb: [number, number, number]): string;
1834
2224
  /**
1835
2225
  * Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
1836
2226
  * string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
@@ -1844,5 +2234,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
1844
2234
  */
1845
2235
  declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
1846
2236
  //#endregion
1847
- 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 GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, 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, 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 };
2237
+ 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 GlazeCssSchemeBlocks, type GlazeDtcgExtensions, type GlazeDtcgHdr, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeGlowInput, type GlazeHdrFormat, 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 ResolvedHdr, 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, formatSrgbLinear, 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 };
1848
2238
  //# sourceMappingURL=index.d.cts.map