@tenphi/glaze 0.0.0-snapshot.9a14acf → 0.0.0-snapshot.9dc79fc

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,94 @@ 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;
403
455
  /**
404
- * Target minimum gap between pigment lightness and bg lightness (0-1).
405
- * Default: 0.05.
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.
406
458
  */
407
- minGapTarget?: number;
408
- /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
409
- alphaMax?: number;
459
+ tint?: number;
410
460
  /**
411
- * Blend weight (0-1) pulling pigment hue toward bg hue.
412
- * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
461
+ * Where the pigment sits (0–1): the fraction of the way from the surface's
462
+ * tone to black (shadow) / white (glow). Default: 1 (pure black / white),
463
+ * the most reach. Lower values let a `tint` show at the cost of reach.
413
464
  */
414
- bgHueBlend?: number;
465
+ reach?: number;
466
+ /**
467
+ * Pull (0–1) of the pigment hue from the surface's hue toward the object's
468
+ * (`fg`) hue. Default: 0. Needs `fg`, a `tint`, and `reach` below 1 to show.
469
+ */
470
+ hueBleed?: number;
471
+ }
472
+ /**
473
+ * Tuning for `shadow` colors: the shared {@link LightingTuning}. It has no
474
+ * `headroom` — a shadow darkens toward black, and nothing goes below black —
475
+ * so a `headroom` set on a shadow's tuning throws.
476
+ */
477
+ type ShadowTuning = LightingTuning;
478
+ /** Tuning for `glow` colors: the shared {@link LightingTuning} plus HDR `headroom`. */
479
+ interface GlowTuning extends LightingTuning {
480
+ /**
481
+ * Stops above SDR white a glow may use when its step crosses white. Default:
482
+ * 0 (SDR only). Counted in stops — doublings of SDR white's luminance — not
483
+ * as a ratio: `1` allows up to 2× white, `2` up to 4×. Must be a finite
484
+ * number ≥ 0; values above 2 clamp to 2 with a one-time warning.
485
+ *
486
+ * Only a glow whose target tone (surface tone + `intensity × k`) passes 100
487
+ * gets an HDR value: the variant's `hdr`, an opaque exposure of what SDR
488
+ * paints at its brightest — the pigment at full opacity, or a white surface
489
+ * no pigment can lift — plus a gain in stops. A pigment that cannot lift a
490
+ * non-white surface at all (`reach: 0` on a gray surface, say) paints
491
+ * nothing in SDR, so it gets no HDR value either and keeps the SDR "cannot
492
+ * reach" warning. On a chromatic surface a `reach: 0` gray can measure
493
+ * slightly brighter than the surface and pins at full opacity instead.
494
+ * Nothing about the SDR variant changes. The gain lands the exact step when
495
+ * the headroom allows it; the brightest channel caps at `2^headroom`.
496
+ * High-contrast schemes use the same headroom.
497
+ *
498
+ * The HDR value lands the whole step, not just the part past white. A
499
+ * full-reach glow (the default `reach: 1`) is pinned at white, so its HDR
500
+ * value starts at white (`exposure` → 0) as the target passes 100. A glow
501
+ * with `reach` below 1 is pinned at its pigment, below white: just under 100
502
+ * it stays short there (and warns), and just past 100 its HDR value jumps to
503
+ * the exact step.
504
+ */
505
+ headroom?: number;
415
506
  }
507
+ /**
508
+ * A translucent dark overlay that lands the surface (`bg`) exactly
509
+ * `intensity` tones darker in every scheme — a shade for state layers and
510
+ * scrims, or, with `fg`, an object-aware drop shadow.
511
+ */
416
512
  interface ShadowColorDef {
417
513
  type: 'shadow';
418
514
  /**
419
- * Background color name — the surface the shadow sits on.
420
- * Must reference a non-shadow color in the same theme.
515
+ * The surface the shadow falls on. Must reference a color that is not a
516
+ * shadow or glow.
421
517
  */
422
518
  bg: string;
423
519
  /**
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.
520
+ * The object casting the shadow (e.g. the card). A darker object casts a
521
+ * deeper shadow, a lighter one a softer shadow — see
522
+ * `LightingTuning.objectInfluence`. Omit for an exact shade of `intensity`
523
+ * tones. Must reference a color that is not a shadow or glow.
427
524
  */
428
525
  fg?: string;
429
526
  /**
430
- * Shadow intensity, 0-100.
527
+ * Tone step, 0–100: how many tones darker than `bg` the composite lands.
431
528
  * Supports [normal, highContrast] pair.
432
529
  */
433
530
  intensity: HCPair<number>;
@@ -446,6 +543,44 @@ interface ShadowColorDef {
446
543
  */
447
544
  inherit?: boolean;
448
545
  }
546
+ /**
547
+ * The mirror of {@link ShadowColorDef}: a translucent light overlay that lands
548
+ * the surface (`bg`) exactly `intensity` tones lighter in every scheme — for
549
+ * dark-mode elevation, edge highlights, and lightening state layers.
550
+ */
551
+ interface GlowColorDef {
552
+ type: 'glow';
553
+ /**
554
+ * The surface the glow falls on. Must reference a color that is not a
555
+ * shadow or glow.
556
+ */
557
+ bg: string;
558
+ /**
559
+ * The object emitting the glow. A lighter object glows stronger, a darker
560
+ * one weaker — see `LightingTuning.objectInfluence`. Omit for an exact tint
561
+ * of `intensity` tones. Must reference a color that is not a shadow or glow.
562
+ */
563
+ fg?: string;
564
+ /**
565
+ * Tone step, 0–100: how many tones lighter than `bg` the composite lands.
566
+ * Supports [normal, highContrast] pair.
567
+ */
568
+ intensity: HCPair<number>;
569
+ /** Override default tuning. Merged field-by-field with global `glowTuning`. */
570
+ tuning?: GlowTuning;
571
+ /**
572
+ * Per-color override for the hue-independent "safe" chroma limit used in
573
+ * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
574
+ * Falls through to the per-theme / per-token `pastel` override when omitted.
575
+ * @see GlazeConfigOverride.pastel
576
+ */
577
+ pastel?: boolean;
578
+ /**
579
+ * Whether this color is inherited by child themes created via `extend()`.
580
+ * Default: true. Set to false to make this color local to the current theme.
581
+ */
582
+ inherit?: boolean;
583
+ }
449
584
  interface MixColorDef {
450
585
  type: 'mix';
451
586
  /** Background/base color name — the "from" color. */
@@ -467,9 +602,12 @@ interface MixColorDef {
467
602
  /**
468
603
  * Interpolation color space for opaque blending. Default: 'okhsl'.
469
604
  * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
470
- * - 'srgb': linear sRGB interpolation, matches browser compositing.
605
+ * - 'srgb': linear-light sRGB interpolation (like CSS
606
+ * `color-mix(in srgb-linear, …)`).
471
607
  *
472
- * Ignored for 'transparent' blend (always composites in linear sRGB).
608
+ * Ignored for 'transparent' blend: the browser composites that one, and
609
+ * its contrast solve models the browser (`source-over` on gamma-encoded
610
+ * sRGB).
473
611
  */
474
612
  space?: 'okhsl' | 'srgb';
475
613
  /**
@@ -499,7 +637,7 @@ interface MixColorDef {
499
637
  */
500
638
  inherit?: boolean;
501
639
  }
502
- type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
640
+ type ColorDef = RegularColorDef | ShadowColorDef | GlowColorDef | MixColorDef;
503
641
  type ColorMap = Record<string, ColorDef>;
504
642
  /**
505
643
  * Resolved color for a single scheme variant.
@@ -523,6 +661,35 @@ interface ResolvedColorVariant {
523
661
  * gamut mapping applied during resolution.
524
662
  */
525
663
  pastel?: boolean;
664
+ /**
665
+ * HDR tier of a glow whose step crosses SDR white, present only when the
666
+ * glow's `headroom` is above 0, its target tone passes 100, and SDR is
667
+ * pinned at its brightest — the pigment at full opacity, or a white surface
668
+ * (see `GlowTuning.headroom`). Absent everywhere else — shadows, mixes,
669
+ * regular colors, a glow whose pigment cannot lift a non-white surface, and
670
+ * every glow at the default headroom of 0.
671
+ */
672
+ hdr?: ResolvedHdr;
673
+ }
674
+ /**
675
+ * The HDR value of a glow past SDR white: an opaque base plus a gain. The base
676
+ * is what SDR paints at its brightest — the glow's pigment at full opacity, or
677
+ * the white surface it cannot lift — and the HDR color is that base's linear
678
+ * sRGB times `2^exposure`. Format it with `glaze.formatHdr()`.
679
+ *
680
+ * Stored in OKHST like the variant. `s` is always standard (non-pastel)
681
+ * OKHSL saturation, whatever the variant's `pastel`, since the base is an
682
+ * arbitrary in-gamut composite.
683
+ */
684
+ interface ResolvedHdr {
685
+ /** Base OKHSL hue (0–360). */
686
+ h: number;
687
+ /** Base OKHSL saturation (0–1, non-pastel). */
688
+ s: number;
689
+ /** Base canonical tone (0–1, reference eps). */
690
+ t: number;
691
+ /** Gain over the base in stops (`log2` of the linear factor), above 0. */
692
+ exposure: number;
526
693
  }
527
694
  /** Fully resolved color across all scheme variants. */
528
695
  interface ResolvedColor {
@@ -531,7 +698,7 @@ interface ResolvedColor {
531
698
  dark: ResolvedColorVariant;
532
699
  lightContrast: ResolvedColorVariant;
533
700
  darkContrast: ResolvedColorVariant;
534
- /** Adaptation mode. Present only for regular colors, omitted for shadows. */
701
+ /** Adaptation mode of a regular color; `undefined` for shadow / glow / mix. */
535
702
  mode?: AdaptationMode;
536
703
  }
537
704
  /**
@@ -557,20 +724,31 @@ interface GlazeConfig {
557
724
  darkDesaturation?: number;
558
725
  /**
559
726
  * 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.
727
+ * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`
728
+ * / `'@media(dynamic-range: high)'`) so tokens react to the OS preference
729
+ * and the display without registering custom states. `hdr` keys an HDR
730
+ * glow value and is used only with `modes.hdr`.
562
731
  */
563
732
  states?: {
564
733
  dark?: string;
565
734
  highContrast?: string;
735
+ hdr?: string;
566
736
  };
567
737
  /**
568
738
  * Which scheme variants to include in exports. Defaults: `dark: true`,
569
- * `highContrast: false`.
739
+ * `highContrast: false`, `hdr: false`.
570
740
  */
571
741
  modes?: GlazeOutputModes;
572
- /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
742
+ /**
743
+ * Default tuning for all shadow colors. Per-color tuning merges field-by-field.
744
+ * A `headroom` here throws: it is a glow-only field.
745
+ */
573
746
  shadowTuning?: ShadowTuning;
747
+ /**
748
+ * Default tuning for all glow colors, including HDR `headroom`. Per-color
749
+ * tuning merges field-by-field.
750
+ */
751
+ glowTuning?: GlowTuning;
574
752
  /**
575
753
  * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
576
754
  * contrast (`100`), or `'auto'` (the default) to take the authored normal
@@ -590,7 +768,7 @@ interface GlazeConfig {
590
768
  * approximation, and a color keeps to one side of its base as the level moves.
591
769
  *
592
770
  * 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
771
+ * omission. See `docs/reference/contrast.md` for the ramp's edge cases (un-interpolable
594
772
  * pairs, side changes) and the export-freeze rule.
595
773
  *
596
774
  * @default 'auto'
@@ -626,9 +804,11 @@ interface GlazeConfigResolved {
626
804
  states: {
627
805
  dark: string;
628
806
  highContrast: string;
807
+ hdr: string;
629
808
  };
630
809
  modes: Required<GlazeOutputModes>;
631
810
  shadowTuning?: ShadowTuning;
811
+ glowTuning?: GlowTuning;
632
812
  autoFlip: boolean;
633
813
  /**
634
814
  * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
@@ -690,12 +870,22 @@ interface GlazeConfigOverride {
690
870
  * standalone color tokens.
691
871
  */
692
872
  shadowTuning?: ShadowTuning;
873
+ /**
874
+ * Glow tuning defaults. Only meaningful for themes; harmless on
875
+ * standalone color tokens.
876
+ */
877
+ glowTuning?: GlowTuning;
693
878
  }
694
879
  /**
695
880
  * Current authoring-export schema version. Bump when the export shape
696
881
  * changes in a non-compatible way. Written on every `.export()` snapshot.
882
+ *
883
+ * - `1` — Glaze 2.x.
884
+ * - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
885
+ * `glow` was added. Version-1 theme snapshots that carry shadow defs or a
886
+ * `shadowTuning` are rejected on restore.
697
887
  */
698
- declare const GLAZE_EXPORT_VERSION: 1;
888
+ declare const GLAZE_EXPORT_VERSION: 2;
699
889
  /** Literal type of {@link GLAZE_EXPORT_VERSION}. */
700
890
  type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
701
891
  /** Discriminator for authoring export snapshots. */
@@ -720,23 +910,27 @@ interface GlazeThemeExport {
720
910
  */
721
911
  config?: GlazeConfigOverride;
722
912
  }
723
- /** Input for `glaze.shadow()` standalone factory. */
724
- interface GlazeShadowInput {
913
+ /** Input for the `glaze.shadow()` and `glaze.glow()` standalone factories. */
914
+ interface GlazeLightingInput {
725
915
  /**
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.
916
+ * The surface — accepts any `GlazeColorValue` form: hex
917
+ * (`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` /
918
+ * `okhsl()` / `okhst()` / `oklch()` strings, or literal objects
919
+ * (`{ r, g, b }`, `{ h, s, l }`, `{ h, s, t }`, `{ l, c, h }`). Alpha
920
+ * components are dropped with a warning.
730
921
  */
731
922
  bg: GlazeColorValue;
732
- /**
733
- * Foreground color for tinting + intensity modulation. Accepts the
734
- * same forms as `bg`.
735
- */
923
+ /** The object casting the shadow / emitting the glow. Same forms as `bg`. */
736
924
  fg?: GlazeColorValue;
737
- /** Intensity 0-100. */
925
+ /** Tone step, 0–100. */
738
926
  intensity: number;
739
- tuning?: ShadowTuning;
927
+ tuning?: LightingTuning;
928
+ }
929
+ /** Input for `glaze.shadow()`. */
930
+ type GlazeShadowInput = GlazeLightingInput;
931
+ /** Input for `glaze.glow()`: the shared input, with glow tuning (`headroom`). */
932
+ interface GlazeGlowInput extends GlazeLightingInput {
933
+ tuning?: GlowTuning;
740
934
  }
741
935
  /** Input for the structured `glaze.color()` overload. */
742
936
  interface GlazeColorInput {
@@ -769,14 +963,17 @@ interface GlazeColorInput {
769
963
  */
770
964
  base?: GlazeColorToken | GlazeColorValue;
771
965
  /**
772
- * Contrast floor against `base`. Requires `base` to be set. A bare
966
+ * Contrast floor. Without `base`, solved against the token's own input
967
+ * color (`hue`, `saturation`, normal `tone`), held fixed in every scheme;
968
+ * with `base`, against the base's resolved variant per scheme. A bare
773
969
  * number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
774
970
  */
775
971
  contrast?: HCPair<ContrastSpec>;
776
972
  /**
777
973
  * Optional human-readable name for the token. Used in error and
778
974
  * warning messages (otherwise an internal name like `"value"` is
779
- * used). Does not affect output keys.
975
+ * used) and as `resolve().name`. A debug label only: it does not
976
+ * affect output keys or the token's `role`.
780
977
  */
781
978
  name?: string;
782
979
  /**
@@ -787,11 +984,12 @@ interface GlazeColorInput {
787
984
  */
788
985
  pastel?: boolean;
789
986
  /**
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.
987
+ * Semantic role against the token's anchor (`base`, or its own input
988
+ * color when `contrast` is set without one): how this token is used.
989
+ * Fixes APCA contrast polarity; WCAG ignores it. Defaults to `'text'` —
990
+ * the token is the foreground and the anchor the background, with or
991
+ * without `base`. Unlike a theme color, a token never infers its role
992
+ * from `name`, so `inferRole` has no effect on it.
795
993
  */
796
994
  role?: RoleInput;
797
995
  }
@@ -799,17 +997,35 @@ interface GlazeColorInput {
799
997
  * Any single-color input form accepted by the value-shorthand
800
998
  * overload of `glaze.color()`.
801
999
  *
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).
1000
+ * Strings cover hex with a leading `#` (`#rgb` / `#rgba` / `#rrggbb` /
1001
+ * `#rrggbbaa`) and the five color functions Glaze itself emits: `rgb()`,
1002
+ * `hsl()`, `okhsl()`, `okhst()`, `oklch()`, plus the `rgba()` / `hsla()`
1003
+ * aliases. Function names are case-insensitive; components are numbers or
1004
+ * percentages, separated by spaces or commas. Their scales:
1005
+ * - `rgb()` — channels 0–255, or percentages (`100%` is 255).
1006
+ * - `hsl()` / `okhsl()` / `okhst()` — saturation, lightness and tone are
1007
+ * percentages or bare 0–1 fractions: `hsl(120 50% 50%)` or
1008
+ * `hsl(120 0.5 0.5)`. Unlike CSS, a bare `hsl(120 50 50)` does not mean
1009
+ * 50%; it is out of range and resolves to white without a warning.
1010
+ * - `oklch()` — L 0–1 or a percentage; C bare, or a percentage where
1011
+ * `100%` is 0.4.
1012
+ * - Hue is in degrees, bare or with `deg`. Other angle units (`turn`,
1013
+ * `rad`, `grad`) are misread as degrees rather than rejected.
1014
+ *
1015
+ * An alpha component (hex alpha, `/ A`, or any fourth component) is
1016
+ * dropped with a warning. Named colors, other color functions, and
1017
+ * relative color syntax throw.
806
1018
  *
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.
1019
+ * Literal object forms, told apart by their keys:
811
1020
  * - `{ r, g, b }` — sRGB 0–255.
812
1021
  * - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
1022
+ * - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1, so `t: 0.7` is
1023
+ * tone 70.
1024
+ * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1).
1025
+ *
1026
+ * An object `s`, `l`, `t` or `c` above 1.5 throws, which catches 0–100
1027
+ * input; the OKHSL / OKHST errors point to the structured form. String
1028
+ * components have no such check.
813
1029
  */
814
1030
  type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
815
1031
  /** Color overrides for the `from` and value-shorthand inputs. */
@@ -908,7 +1124,8 @@ interface GlazeColorOverrides {
908
1124
  /**
909
1125
  * Optional human-readable name for the token. Used in error and
910
1126
  * warning messages (otherwise an internal name like `"value"` is
911
- * used). Does not affect output keys.
1127
+ * used) and as `resolve().name`. A debug label only: it does not
1128
+ * affect output keys or the token's `role`.
912
1129
  */
913
1130
  name?: string;
914
1131
  /**
@@ -919,9 +1136,12 @@ interface GlazeColorOverrides {
919
1136
  */
920
1137
  pastel?: boolean;
921
1138
  /**
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`.
1139
+ * Semantic role against the token's anchor (`base`, or the literal seed
1140
+ * when `contrast` / a relative `tone` is set without one): how this token
1141
+ * is used. Fixes APCA contrast polarity; WCAG ignores it. Defaults to
1142
+ * `'text'` — the token is the foreground and the anchor the background,
1143
+ * with or without `base`. Unlike a theme color, a token never infers its
1144
+ * role from `name`, so `inferRole` has no effect on it.
925
1145
  */
926
1146
  role?: RoleInput;
927
1147
  }
@@ -954,8 +1174,9 @@ interface GlazeColorCssOptions {
954
1174
  */
955
1175
  suffix?: string;
956
1176
  /**
957
- * Emit hue as a separate custom property, referenced via `var()`.
958
- * Requires `format: 'oklch'` and a pastel token. oklch + all-pastel only.
1177
+ * Emit hue as a separate `--{name}-hue` custom property, referenced via
1178
+ * `var()`. Requires `format: 'oklch'` (any other format throws) and a
1179
+ * pastel token.
959
1180
  */
960
1181
  splitHue?: boolean;
961
1182
  }
@@ -1144,16 +1365,26 @@ interface GlazeTheme {
1144
1365
  * theme.tokens()
1145
1366
  * // → { light: { surface: 'okhsl(...)' }, dark: { surface: 'okhsl(...)' } }
1146
1367
  * ```
1368
+ *
1369
+ * With `modes.hdr`, each scheme map is followed by a dense `<scheme>Hdr`
1370
+ * map (`lightHdr`, `darkHdr`, …): every glow with an HDR value in any
1371
+ * emitted scheme, as `color(srgb-linear …)`, or its SDR value where that
1372
+ * scheme has none.
1147
1373
  */
1148
1374
  tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
1149
1375
  /**
1150
1376
  * Export as tasty style-to-state bindings.
1151
1377
  * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
1152
1378
  * Spread into component styles or register as a recipe via `configure({ recipes })`.
1379
+ * With `modes.hdr`, a glow's HDR value follows each SDR key that has one,
1380
+ * under `states.hdr` (`'@media(dynamic-range: high)'`) combined with it.
1153
1381
  * @see https://tasty.style/docs
1154
1382
  */
1155
- tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
1156
- /** Export as plain JSON. */
1383
+ tasty(options?: GlazeTastyOptions): Record<string, Record<string, string>>;
1384
+ /**
1385
+ * Export as plain JSON. With `modes.hdr`, a glow variant with an HDR value
1386
+ * adds a `<scheme>Hdr` key (`lightHdr`, …) right after its SDR key.
1387
+ */
1157
1388
  json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
1158
1389
  /** Export as CSS custom property declarations. */
1159
1390
  css(options?: GlazeCssOptions): GlazeCssResult;
@@ -1190,35 +1421,48 @@ interface GlazeExtendOptions {
1190
1421
  /** Config override for the child theme. Merged with the parent's override. */
1191
1422
  config?: GlazeConfigOverride;
1192
1423
  }
1424
+ /**
1425
+ * Options for `token.token()` / `token.tasty()`, and the base of the theme and
1426
+ * palette `tasty()` options: output format, scheme variants, state aliases.
1427
+ */
1193
1428
  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. */
1429
+ /**
1430
+ * Override state aliases for this export. `hdr` keys an HDR glow value
1431
+ * (with `modes.hdr`); a `glaze.color()` token is never a glow, so it never
1432
+ * uses it.
1433
+ */
1197
1434
  states?: {
1198
1435
  dark?: string;
1199
1436
  highContrast?: string;
1437
+ hdr?: string;
1200
1438
  };
1201
1439
  /** Override which scheme variants to include. */
1202
1440
  modes?: GlazeOutputModes;
1203
1441
  /** Output color format. Default: 'oklch'. */
1204
1442
  format?: GlazeColorFormat;
1443
+ }
1444
+ /** Options for `theme.tasty()`. */
1445
+ interface GlazeTastyOptions extends GlazeTokenOptions {
1205
1446
  /**
1206
1447
  * Emit hue as a separate custom property, referenced via `var()`.
1207
- * Requires `format: 'oklch'` and every color to be pastel.
1448
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1449
+ * be pastel.
1208
1450
  */
1209
1451
  splitHue?: boolean;
1210
1452
  /**
1211
1453
  * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
1212
- * Palette export auto-derives this from the theme name.
1454
+ * Must not equal the name of a color that sets its own hue (throws).
1213
1455
  */
1214
1456
  name?: string;
1215
1457
  }
1458
+ /** Options for `theme.tokens()` / `theme.json()` and their palette and token counterparts. */
1216
1459
  interface GlazeJsonOptions {
1217
1460
  /** Override which scheme variants to include. */
1218
1461
  modes?: GlazeOutputModes;
1219
1462
  /** Output color format. Default: 'oklch'. */
1220
1463
  format?: GlazeColorFormat;
1221
1464
  }
1465
+ /** Options for `theme.css()`. */
1222
1466
  interface GlazeCssOptions {
1223
1467
  /** Output color format. Default: 'oklch'. */
1224
1468
  format?: GlazeColorFormat;
@@ -1226,22 +1470,43 @@ interface GlazeCssOptions {
1226
1470
  suffix?: string;
1227
1471
  /**
1228
1472
  * Emit hue as a separate custom property, referenced via `var()`.
1229
- * Requires `format: 'oklch'` and every color to be pastel.
1473
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1474
+ * be pastel.
1230
1475
  */
1231
1476
  splitHue?: boolean;
1232
1477
  /**
1233
1478
  * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
1234
- * Palette export auto-derives this from the theme name.
1479
+ * Must not equal the name of a color that sets its own hue (throws).
1235
1480
  */
1236
1481
  name?: string;
1482
+ /**
1483
+ * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
1484
+ * Default: the global `modes.hdr` (false). `css()` has no `modes` — it
1485
+ * always emits all four schemes — so this is its HDR switch.
1486
+ */
1487
+ hdr?: boolean;
1237
1488
  }
1238
- /** CSS custom property declarations grouped by scheme variant. */
1239
- interface GlazeCssResult {
1489
+ /** CSS custom property declarations for each scheme variant. */
1490
+ interface GlazeCssSchemeBlocks {
1240
1491
  light: string;
1241
1492
  dark: string;
1242
1493
  lightContrast: string;
1243
1494
  darkContrast: string;
1244
1495
  }
1496
+ /** CSS custom property declarations grouped by scheme variant. */
1497
+ interface GlazeCssResult extends GlazeCssSchemeBlocks {
1498
+ /**
1499
+ * The HDR tier, present when HDR output is on — the `hdr` option, which
1500
+ * defaults to the global `modes.hdr`: one block per scheme,
1501
+ * each re-declaring every color that has an HDR value in any scheme — its
1502
+ * HDR value (`color(srgb-linear R G B)`) where that scheme has one, and
1503
+ * the scheme's SDR declaration where it has none. The blocks are dense so
1504
+ * a light HDR value can never leak into dark: wire each one after the SDR
1505
+ * blocks, under the same selector plus `(dynamic-range: high)`. Every block
1506
+ * is an empty string when no color has an HDR value.
1507
+ */
1508
+ hdr?: GlazeCssSchemeBlocks;
1509
+ }
1245
1510
  /**
1246
1511
  * Color space used for DTCG `$value` color objects.
1247
1512
  * @see https://www.designtokens.org/
@@ -1271,14 +1536,49 @@ interface DtcgOklchColorValue {
1271
1536
  }
1272
1537
  /** A DTCG `$value` for a color token, in either supported color space. */
1273
1538
  type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;
1539
+ /**
1540
+ * The HDR value of a glow past SDR white, carried in a DTCG token's
1541
+ * `$extensions['me.tenphi.glaze'].hdr` (`$value` stays the SDR color, since
1542
+ * DTCG color components stop at 1). Maps onto native APIs: UIKit / AppKit
1543
+ * `exposure`, SwiftUI `exposureAdjust(exposure)` on `base`, or Android
1544
+ * `Color.pack(…components, LINEAR_EXTENDED_SRGB)` from `value`.
1545
+ */
1546
+ interface GlazeDtcgHdr {
1547
+ /** Gain over `base` in stops (`log2` of the linear factor), above 0. */
1548
+ exposure: number;
1549
+ /**
1550
+ * Luminance tone of the HDR value (e.g. `112`) — past 100 when the headroom
1551
+ * covers the step; a saturated base capped by `headroom` can land below 100,
1552
+ * though its brightest channel still exceeds 1.
1553
+ */
1554
+ tone: number;
1555
+ /** The opaque base (what SDR paints), as a DTCG sRGB color. */
1556
+ base: DtcgSrgbColorValue;
1557
+ /**
1558
+ * The HDR color: linear sRGB `base × 2^exposure`, its brightest channel
1559
+ * above 1 (the others may stay below).
1560
+ */
1561
+ value: {
1562
+ colorSpace: 'srgb-linear';
1563
+ components: [number, number, number];
1564
+ };
1565
+ }
1566
+ /** The Glaze namespace of a DTCG token's `$extensions`. */
1567
+ interface GlazeDtcgExtensions {
1568
+ 'me.tenphi.glaze': {
1569
+ /** Present only with `modes.hdr`, on a glow variant that has an HDR value. */hdr: GlazeDtcgHdr;
1570
+ };
1571
+ }
1274
1572
  /**
1275
1573
  * A single W3C DTCG color token: `{ $type: 'color', $value }`.
1276
- * `$description` is optional and not populated by Glaze today.
1574
+ * `$description` is optional and not populated by Glaze today. `$extensions`
1575
+ * is set only with `modes.hdr`, on a glow variant with an HDR value.
1277
1576
  */
1278
1577
  interface DtcgColorToken {
1279
1578
  $type: 'color';
1280
1579
  $value: DtcgColorValue;
1281
1580
  $description?: string;
1581
+ $extensions?: GlazeDtcgExtensions;
1282
1582
  }
1283
1583
  /**
1284
1584
  * A W3C Design Tokens Format Module (2025.10) token tree for one scheme.
@@ -1412,6 +1712,15 @@ interface GlazeTailwindOptions {
1412
1712
  * `.dark.high-contrast`).
1413
1713
  */
1414
1714
  highContrastSelector?: string;
1715
+ /**
1716
+ * Selector wrapping the HDR overrides, emitted with `modes.hdr` after every
1717
+ * SDR block. Default: `'@media (dynamic-range: high)'`. Each HDR block is
1718
+ * dense (every color with an HDR value in any emitted scheme, SDR value
1719
+ * where the scheme has none) and is scoped by this selector alone (light),
1720
+ * combined with `darkSelector` (dark), with `highContrastSelector` (light
1721
+ * high contrast), or with both.
1722
+ */
1723
+ hdrSelector?: string;
1415
1724
  }
1416
1725
  /** Options for `glaze.color().tailwind()`. `name` is required. */
1417
1726
  interface GlazeColorTailwindOptions extends GlazeTailwindOptions {
@@ -1434,7 +1743,10 @@ interface GlazePaletteOptions {
1434
1743
  */
1435
1744
  primary?: string;
1436
1745
  }
1437
- /** Options shared by palette `tokens()`, `tasty()`, and `css()` exports. */
1746
+ /**
1747
+ * Options shared by every palette export except `json()`: `tokens()`,
1748
+ * `tasty()`, `css()`, `dtcg()`, `dtcgResolver()`, and `tailwind()`.
1749
+ */
1438
1750
  interface GlazePaletteExportOptions {
1439
1751
  /**
1440
1752
  * Prefix mode. `true` uses `"<themeName>-"`, or provide a custom map.
@@ -1449,11 +1761,39 @@ interface GlazePaletteExportOptions {
1449
1761
  * When omitted, inherits the palette-level `primary`.
1450
1762
  */
1451
1763
  primary?: string | false;
1764
+ }
1765
+ /**
1766
+ * Options for `palette.tasty()`. There is no `name`: each theme's hue var is
1767
+ * named after the theme.
1768
+ */
1769
+ interface GlazePaletteTastyOptions extends GlazeTokenOptions, GlazePaletteExportOptions {
1770
+ /**
1771
+ * Emit hue as a separate custom property, referenced via `var()`.
1772
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1773
+ * be pastel. The theme-level hue var is `--{themeName}-hue`.
1774
+ */
1775
+ splitHue?: boolean;
1776
+ }
1777
+ /**
1778
+ * Options for `palette.css()`. There is no `name`: each theme's hue var is
1779
+ * named after the theme.
1780
+ */
1781
+ interface GlazePaletteCssOptions extends GlazePaletteExportOptions {
1782
+ /** Output color format. Default: 'oklch'. */
1783
+ format?: GlazeColorFormat;
1784
+ /** Suffix appended to each CSS custom property name. Default: '-color'. */
1785
+ suffix?: string;
1452
1786
  /**
1453
1787
  * Emit hue as a separate custom property, referenced via `var()`.
1454
- * Requires `format: 'oklch'` and every color to be pastel.
1788
+ * Requires `format: 'oklch'` (any other format throws) and every color to
1789
+ * be pastel. The theme-level hue var is `--{themeName}-hue`.
1455
1790
  */
1456
1791
  splitHue?: boolean;
1792
+ /**
1793
+ * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
1794
+ * Default: the global `modes.hdr` (false).
1795
+ */
1796
+ hdr?: boolean;
1457
1797
  }
1458
1798
  interface GlazePalette {
1459
1799
  /** Theme names in insertion order. */
@@ -1492,13 +1832,14 @@ interface GlazePalette {
1492
1832
  * Prefix defaults to `true`. Inherits the palette-level `primary`.
1493
1833
  * @see https://tasty.style/docs
1494
1834
  */
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>>>;
1835
+ tasty(options?: GlazePaletteTastyOptions): Record<string, Record<string, string>>;
1836
+ /**
1837
+ * Export all themes as plain JSON grouped by theme name. No prefix, primary
1838
+ * alias, or collision handling: each theme keeps its own key.
1839
+ */
1840
+ json(options?: GlazeJsonOptions): Record<string, Record<string, Record<string, string>>>;
1500
1841
  /** Export all themes as CSS custom property declarations. */
1501
- css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
1842
+ css(options?: GlazePaletteCssOptions): GlazeCssResult;
1502
1843
  /**
1503
1844
  * Export all themes as W3C DTCG documents, one per scheme variant.
1504
1845
  * Prefix defaults to `true`. Inherits the palette-level `primary`.
@@ -1553,9 +1894,13 @@ type PaletteInput = Record<string, GlazeTheme>;
1553
1894
  * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
1554
1895
  * // with config override:
1555
1896
  * const raw = glaze(280, 80, { lightTone: false });
1897
+ * const rawSeed = glaze({ hue: 280, saturation: 80 }, { lightTone: false });
1556
1898
  * ```
1557
1899
  */
1558
- declare function glaze(hueOrOptions: number | GlazeThemeSeed, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
1900
+ declare function glaze(hue: number, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
1901
+ declare function glaze(seed: GlazeThemeSeed, config?: GlazeConfigOverride): GlazeTheme;
1902
+ /** @deprecated Pass the config second: `glaze(seed, config)`. */
1903
+ declare function glaze(seed: GlazeThemeSeed, saturation: undefined, config?: GlazeConfigOverride): GlazeTheme;
1559
1904
  declare namespace glaze {
1560
1905
  var configure: (config: GlazeConfig) => void;
1561
1906
  var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
@@ -1563,7 +1908,9 @@ declare namespace glaze {
1563
1908
  var from: (data: GlazeThemeExport) => GlazeTheme;
1564
1909
  var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
1565
1910
  var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
1911
+ var glow: (input: GlazeGlowInput) => ResolvedColorVariant;
1566
1912
  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
1913
+ var formatHdr: (variant: ResolvedColorVariant, hdrFormat?: GlazeHdrFormat) => string | undefined;
1567
1914
  var fromHex: (hex: string) => GlazeTheme;
1568
1915
  var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
1569
1916
  var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
@@ -1583,7 +1930,7 @@ interface HueDeclaration {
1583
1930
  interface HuePlan {
1584
1931
  /** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
1585
1932
  hueVar: string;
1586
- /** When true, emit a full inline color (shadow/mix/achromatic). */
1933
+ /** When true, emit a full inline color (shadow/glow/mix/achromatic). */
1587
1934
  inline: boolean;
1588
1935
  /** Scheme-independent `--*-hue` declarations for this color. */
1589
1936
  declarations: HueDeclaration[];
@@ -1720,7 +2067,11 @@ declare function variantToOkhsl(v: {
1720
2067
  *
1721
2068
  * Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
1722
2069
  * for both contrast metrics (WCAG 2 relative luminance and APCA screen
1723
- * luminance `Ys`), and multi-format output (okhsl, rgb, hsl, oklch).
2070
+ * luminance `Ys` — both the exact functions the contrast solver uses, and
2071
+ * both public), strict hex parsing (`parseHex` / `parseHexAlpha` check every
2072
+ * digit), and multi-format output (okhsl, rgb, hsl, oklch, plus the
2073
+ * `color(srgb-linear …)` writer for HDR glow values, whose channels may exceed
2074
+ * 1).
1724
2075
  */
1725
2076
  type Vec3 = [number, number, number];
1726
2077
  /**
@@ -1766,6 +2117,22 @@ declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean):
1766
2117
  * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
1767
2118
  */
1768
2119
  declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
2120
+ /**
2121
+ * Compute APCA screen luminance (`Ys`) from linear sRGB.
2122
+ *
2123
+ * APCA does not use the WCAG piecewise sRGB EOTF; it defines its own
2124
+ * luminance as `0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
2125
+ * gamma-encoded (display) channels with a simple 2.4 exponent. The APCA
2126
+ * soft-clamp threshold in `apcaContrast` is calibrated against this basis,
2127
+ * so the solver must feed it `Ys`, not WCAG relative luminance. Channels
2128
+ * are gamut-clamped to [0, 1] first, matching `gamutClampedLuminance`.
2129
+ *
2130
+ * This is exactly the luminance Glaze's contrast solver (and its drift
2131
+ * check) feeds `apcaContrast`, so
2132
+ * `apcaContrast(apcaLuminanceFromLinearRgb(text), apcaLuminanceFromLinearRgb(bg))`
2133
+ * reproduces the solver's Lc for a resolved pair.
2134
+ */
2135
+ declare function apcaLuminanceFromLinearRgb(linearRgb: [number, number, number]): number;
1769
2136
  /**
1770
2137
  * Convert OKLab to OKHSL.
1771
2138
  * Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
@@ -1787,7 +2154,9 @@ declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [
1787
2154
  declare function hslToSrgb(h: number, s: number, l: number): [number, number, number];
1788
2155
  /**
1789
2156
  * 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.
2157
+ * The leading `#` is optional. Returns null if the string is not a valid hex
2158
+ * color: a wrong length, any character outside `0-9a-f` (case-insensitive),
2159
+ * or a form with alpha.
1791
2160
  *
1792
2161
  * For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
1793
2162
  * use {@link parseHexAlpha}.
@@ -1796,7 +2165,12 @@ declare function parseHex(hex: string): [number, number, number] | null;
1796
2165
  /**
1797
2166
  * Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
1798
2167
  * 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.
2168
+ * The leading `#` is optional. Returns null if the string is not a valid hex
2169
+ * color: a wrong length or any character outside `0-9a-f`
2170
+ * (case-insensitive).
2171
+ *
2172
+ * Every digit is checked up front: `parseInt` alone stops at the first bad
2173
+ * character, so `'#1z2z3z'` would otherwise read as `#010203`.
1800
2174
  */
1801
2175
  declare function parseHexAlpha(hex: string): {
1802
2176
  rgb: [number, number, number];
@@ -1831,6 +2205,14 @@ declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): s
1831
2205
  * h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
1832
2206
  */
1833
2207
  declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
2208
+ /**
2209
+ * Format linear sRGB channels as a CSS `color(srgb-linear R G B)` string with
2210
+ * 4 decimals. Unlike the other writers it takes linear light, not OKHSL, and
2211
+ * does not clamp: a channel may exceed 1, which is how an HDR glow value
2212
+ * (`glaze.formatHdr()`) goes past SDR white — `1` is SDR white, `2` one stop
2213
+ * above it. Opaque only; HDR values carry no alpha.
2214
+ */
2215
+ declare function formatSrgbLinear(rgb: [number, number, number]): string;
1834
2216
  /**
1835
2217
  * Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
1836
2218
  * string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
@@ -1844,5 +2226,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
1844
2226
  */
1845
2227
  declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
1846
2228
  //#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 };
2229
+ 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
2230
  //# sourceMappingURL=index.d.cts.map