@tenphi/glaze 0.0.0-snapshot.0fcd6cf → 0.0.0-snapshot.12fd135

package/dist/index.d.cts

@@ -252,12 +252,20 @@ type ToneValue = number | RelativeValue | ExtremeValue;
 /** Color format for output. */
 type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
 /**
- * Output format for an HDR glow value (`glaze.formatHdr()`). Only
- * `'srgb-linear'` — `color(srgb-linear R G B)` with channels that may exceed
- * 1 — since OKLCH lightness clamps at parse time and `rgb()` / `hsl()` cannot
- * go past white.
+ * Output format for an HDR glow value (`glaze.formatHdr()`), its brightest
+ * channel past 1 (SDR white):
+ * - `'srgb'` (default, and what every exporter writes) — extended
+ *   `color(srgb R G B)`: the sRGB transfer function continued past 1, the
+ *   channels a WebGPU `'srgb'` canvas and the platform extended-sRGB color
+ *   spaces take as they are.
+ * - `'srgb-linear'` — `color(srgb-linear R G B)`: the same color in linear
+ *   light, for consumers that take linear channels.
+ *
+ * No other form: OKLCH lightness clamps at parse time, `rgb()` / `hsl()`
+ * cannot go past white, and the `rec2100-*` spaces would tie the value to an
+ * absolute reference white it doesn't need.
  */
-type GlazeHdrFormat = 'srgb-linear';
+type GlazeHdrFormat = 'srgb' | 'srgb-linear';
 /**
  * Controls which scheme variants are generated in the export.
  * Light is always included (it's the default).
@@ -282,10 +290,16 @@ interface GlazeOutputModes {
    *
    * When on, each exporter adds the HDR values next to the SDR ones it
    * already emits (only for the scheme variants the other modes include),
-   * always written as `color(srgb-linear R G B)`: Tasty `hdr` state keys,
+   * always written as extended `color(srgb R G B)`: Tasty `hdr` state keys,
    * `json()` `lightHdr` / `darkHdr` / … keys, `tokens()` `lightHdr` / … maps,
    * Tailwind blocks under `hdrSelector`, DTCG `$extensions`. `css()` reads
    * its own `hdr` option, which falls back to this.
+   *
+   * The data tiers (DTCG, `json()`, `tokens()`) are what native apps and
+   * WebGPU canvases read. The CSS-family tiers (Tasty, `css()`, Tailwind) are
+   * experimental: no browser paints a CSS color past SDR white yet. Prefer
+   * turning this on per call (`theme.dtcg({ modes: { hdr: true } })`) over
+   * globally.
    */
   hdr?: boolean;
 }
@@ -455,6 +469,8 @@ interface LightingTuning {
   /**
    * Pigment saturation (0–1) in the surface's hue. Default: 0 (neutral black /
    * white). Shows only with `reach` below 1 — pure black and white have no hue.
+   * A neutral surface has no hue either: there the tint takes the object's
+   * hue with `hueBleed` above 0, and the pigment stays neutral otherwise.
    */
   tint?: number;
   /**
@@ -492,7 +508,7 @@ interface GlowTuning extends LightingTuning {
    * reach" warning. On a chromatic surface a `reach: 0` gray can measure
    * slightly brighter than the surface and pins at full opacity instead.
    * Nothing about the SDR variant changes. The gain lands the exact step when
-   * the headroom allows it; the brightest channel caps at `2^headroom`.
+   * the headroom allows it; the brightest linear channel caps at `2^headroom`.
    * High-contrast schemes use the same headroom.
    *
    * The HDR value lands the whole step, not just the part past white. A
@@ -675,7 +691,8 @@ interface ResolvedColorVariant {
  * The HDR value of a glow past SDR white: an opaque base plus a gain. The base
  * is what SDR paints at its brightest — the glow's pigment at full opacity, or
  * the white surface it cannot lift — and the HDR color is that base's linear
- * sRGB times `2^exposure`. Format it with `glaze.formatHdr()`.
+ * sRGB times `2^exposure`. Format it with `glaze.formatHdr()`, or read its
+ * channels with `hdrToSrgb()` / `hdrToLinearSrgb()`.
  *
  * Stored in OKHST like the variant. `s` is always standard (non-pastel)
  * OKHSL saturation, whatever the variant's `pastel`, since the base is an
@@ -727,7 +744,8 @@ interface GlazeConfig {
    * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`
    * / `'@media(dynamic-range: high)'`) so tokens react to the OS preference
    * and the display without registering custom states. `hdr` keys an HDR
-   * glow value and is used only with `modes.hdr`.
+   * glow value and is used only with `modes.hdr` (experimental, see
+   * `GlazeOutputModes.hdr`).
    */
   states?: {
     dark?: string;
@@ -1367,8 +1385,8 @@ interface GlazeTheme {
    *
    * With `modes.hdr`, each scheme map is followed by a dense `<scheme>Hdr`
    * map (`lightHdr`, `darkHdr`, …): every glow with an HDR value in any
-   * emitted scheme, as `color(srgb-linear …)`, or its SDR value where that
-   * scheme has none.
+   * emitted scheme, as extended `color(srgb …)`, or its SDR value where
+   * that scheme has none.
    */
   tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /**
@@ -1482,6 +1500,9 @@ interface GlazeCssOptions {
    * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
    * Default: the global `modes.hdr` (false). `css()` has no `modes` — it
    * always emits all four schemes — so this is its HDR switch.
+   * @experimental No browser paints a CSS color past SDR white yet, so this
+   * tier looks like SDR at best today, and its shape may change (for example
+   * to CSS `hdr-color()`) once one does.
    */
   hdr?: boolean;
 }
@@ -1498,7 +1519,7 @@ interface GlazeCssResult extends GlazeCssSchemeBlocks {
    * The HDR tier, present when HDR output is on — the `hdr` option, which
    * defaults to the global `modes.hdr`: one block per scheme,
    * each re-declaring every color that has an HDR value in any scheme — its
-   * HDR value (`color(srgb-linear R G B)`) where that scheme has one, and
+   * HDR value (extended `color(srgb R G B)`) where that scheme has one, and
    * the scheme's SDR declaration where it has none. The blocks are dense so
    * a light HDR value can never leak into dark: wire each one after the SDR
    * blocks, under the same selector plus `(dynamic-range: high)`. Every block
@@ -1538,9 +1559,11 @@ type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;
 /**
  * The HDR value of a glow past SDR white, carried in a DTCG token's
  * `$extensions['me.tenphi.glaze'].hdr` (`$value` stays the SDR color, since
- * DTCG color components stop at 1). Maps onto native APIs: UIKit / AppKit
- * `exposure`, SwiftUI `exposureAdjust(exposure)` on `base`, or Android
- * `Color.pack(…components, LINEAR_EXTENDED_SRGB)` from `value`.
+ * DTCG color components stop at 1). Maps onto native APIs: UIKit
+ * `UIColor(red:green:blue:alpha:exposure:)` (AppKit: its `NSColor` twin) from
+ * `base` and `exposure`, or Android
+ * `Color.pack(r, g, b, 1f, ColorSpace.get(ColorSpace.Named.EXTENDED_SRGB))`
+ * from `value`.
  */
 interface GlazeDtcgHdr {
   /** Gain over `base` in stops (`log2` of the linear factor), above 0. */
@@ -1554,11 +1577,12 @@ interface GlazeDtcgHdr {
   /** The opaque base (what SDR paints), as a DTCG sRGB color. */
   base: DtcgSrgbColorValue;
   /**
-   * The HDR color: linear sRGB `base × 2^exposure`, its brightest channel
+   * The HDR color, `base × 2^exposure` in linear light, as extended sRGB
+   * components (the numbers of `glaze.formatHdr()`): its brightest channel
    * above 1 (the others may stay below).
    */
   value: {
-    colorSpace: 'srgb-linear';
+    colorSpace: 'srgb';
     components: [number, number, number];
   };
 }
@@ -1718,6 +1742,9 @@ interface GlazeTailwindOptions {
    * where the scheme has none) and is scoped by this selector alone (light),
    * combined with `darkSelector` (dark), with `highContrastSelector` (light
    * high contrast), or with both.
+   * @experimental No browser paints a CSS color past SDR white yet, so this
+   * tier looks like SDR at best today, and its shape may change (for example
+   * to CSS `hdr-color()`) once one does.
    */
   hdrSelector?: string;
 }
@@ -1791,6 +1818,9 @@ interface GlazePaletteCssOptions extends GlazePaletteExportOptions {
   /**
    * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
    * Default: the global `modes.hdr` (false).
+   * @experimental No browser paints a CSS color past SDR white yet, so this
+   * tier looks like SDR at best today, and its shape may change (for example
+   * to CSS `hdr-color()`) once one does.
    */
   hdr?: boolean;
 }
@@ -1860,14 +1890,6 @@ interface GlazePalette {
   tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
 }
 //#endregion
-//#region src/serialize.d.ts
-/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
-declare function isThemeExport(data: unknown): data is GlazeThemeExport;
-/** Type guard for color-token authoring snapshots. */
-declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
-/** Type guard for palette authoring snapshots. */
-declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
-//#endregion
 //#region src/glaze.d.ts
 type PaletteInput = Record<string, GlazeTheme>;
 /**
@@ -1914,13 +1936,21 @@ declare namespace glaze {
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
   var paletteFrom: (data: GlazePaletteExport) => GlazePalette;
-  var isThemeExport: typeof isThemeExport;
-  var isColorTokenExport: typeof isColorTokenExport;
-  var isPaletteExport: typeof isPaletteExport;
+  var isThemeExport: (value: unknown) => value is GlazeThemeExport;
+  var isColorTokenExport: (value: unknown) => value is GlazeColorTokenExport;
+  var isPaletteExport: (value: unknown) => value is GlazePaletteExport;
   var getConfig: () => GlazeConfigResolved;
   var resetConfig: () => void;
 }
 //#endregion
+//#region src/serialize.d.ts
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+declare function isThemeExport(data: unknown): data is GlazeThemeExport;
+/** Type guard for color-token authoring snapshots. */
+declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
+//#endregion
 //#region src/channels.d.ts
 interface HueDeclaration {
   prop: string;
@@ -1965,12 +1995,14 @@ interface ChannelCtx {
  * emits raw CSS or non-Tasty token maps.
  */
 declare function assertNativeFormat(format: GlazeColorFormat | undefined, method: string): void;
+/** The modes `assertAllPastel` reads: which schemes are emitted. */
+type SchemeModes = Required<Pick<GlazeOutputModes, 'dark' | 'highContrast'>>;
 /**
  * Throw when `splitHue` is enabled but any exported color is not pastel.
  * Hue rotation is only clip-free when chroma is bounded by the hue-independent
  * safe chroma (`computeSafeChromaOKLCH`).
  */
-declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: Required<GlazeOutputModes>): void;
+declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: SchemeModes): void;
 //#endregion
 //#region src/roles.d.ts
 /**
@@ -2069,8 +2101,8 @@ declare function variantToOkhsl(v: {
  * luminance `Ys` — both the exact functions the contrast solver uses, and
  * both public), strict hex parsing (`parseHex` / `parseHexAlpha` check every
  * digit), and multi-format output (okhsl, rgb, hsl, oklch, plus the
- * `color(srgb-linear …)` writer for HDR glow values, whose channels may exceed
- * 1).
+ * unclamped `color(srgb …)` / `color(srgb-linear …)` writers for HDR glow
+ * values, whose channels may exceed 1).
  */
 type Vec3 = [number, number, number];
 /**
@@ -2141,6 +2173,11 @@ declare const oklabToOkhsl: (lab: Vec3, pastel?: boolean) => Vec3;
 /**
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
+ *
+ * A gray reads with saturation 0 (its computed hue is kept). Its OKLab
+ * residue would otherwise come out as a saturation that grows toward white
+ * (`#fefefe` reads 1.6e-5, `rgb(254.999 254.999 254.999)` 1.6e-2), which a
+ * color carries into every scheme and an OKHSL mix reads as a hue.
  */
 declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [number, number, number];
 /**
@@ -2208,10 +2245,21 @@ declare function formatOklch(h: number, s: number, l: number, pastel?: boolean):
  * Format linear sRGB channels as a CSS `color(srgb-linear R G B)` string with
  * 4 decimals. Unlike the other writers it takes linear light, not OKHSL, and
  * does not clamp: a channel may exceed 1, which is how an HDR glow value
- * (`glaze.formatHdr()`) goes past SDR white — `1` is SDR white, `2` one stop
- * above it. Opaque only; HDR values carry no alpha.
+ * written with `glaze.formatHdr(v, 'srgb-linear')` goes past SDR white — `1`
+ * is SDR white, `2` one stop above it (the default extended form is
+ * `formatSrgb`). Opaque only; HDR values carry no alpha.
  */
 declare function formatSrgbLinear(rgb: [number, number, number]): string;
+/**
+ * Format extended sRGB channels — gamma-encoded, with the transfer function
+ * continued past 1 (`sRGBLinearToGamma` does) — as a CSS `color(srgb R G B)`
+ * string with 4 decimals. Like `formatSrgbLinear` it takes the channels of
+ * its own space and does not clamp, so an HDR glow value
+ * (`glaze.formatHdr()`) can pass SDR white: `1` is SDR white, about `1.3533`
+ * one stop above it. CSS reads it as the same color as the matching
+ * `color(srgb-linear …)`. Opaque only; HDR values carry no alpha.
+ */
+declare function formatSrgb(rgb: [number, number, number]): string;
 /**
  * Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
  * string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
@@ -2225,5 +2273,21 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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 };
+//#region src/lighting.d.ts
+/**
+ * Linear sRGB of a resolved HDR value: the base's channels times
+ * `2^exposure`, unclamped (the brightest channel can reach `2^headroom`).
+ * The base is non-pastel OKHSL, so no `pastel` flag applies.
+ */
+declare function hdrToLinearSrgb(hdr: ResolvedHdr): [number, number, number];
+/**
+ * Extended sRGB of a resolved HDR value: `hdrToLinearSrgb` through the sRGB
+ * transfer function, continued past 1 the way CSS and the platform
+ * extended-sRGB spaces continue it, unclamped. These are the channels of
+ * `color(srgb R G B)` (`glaze.formatHdr()`), and what a WebGPU `'srgb'`
+ * canvas, `CGColorSpace.extendedSRGB`, and Android's `EXTENDED_SRGB` take.
+ */
+declare function hdrToSrgb(hdr: ResolvedHdr): [number, number, number];
+//#endregion
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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, formatSrgb, formatSrgbLinear, fromTone, gamutClampedLuminance, glaze, hdrToLinearSrgb, hdrToSrgb, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -252,12 +252,20 @@ type ToneValue = number | RelativeValue | ExtremeValue;
 /** Color format for output. */
 type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
 /**
- * Output format for an HDR glow value (`glaze.formatHdr()`). Only
- * `'srgb-linear'` — `color(srgb-linear R G B)` with channels that may exceed
- * 1 — since OKLCH lightness clamps at parse time and `rgb()` / `hsl()` cannot
- * go past white.
+ * Output format for an HDR glow value (`glaze.formatHdr()`), its brightest
+ * channel past 1 (SDR white):
+ * - `'srgb'` (default, and what every exporter writes) — extended
+ *   `color(srgb R G B)`: the sRGB transfer function continued past 1, the
+ *   channels a WebGPU `'srgb'` canvas and the platform extended-sRGB color
+ *   spaces take as they are.
+ * - `'srgb-linear'` — `color(srgb-linear R G B)`: the same color in linear
+ *   light, for consumers that take linear channels.
+ *
+ * No other form: OKLCH lightness clamps at parse time, `rgb()` / `hsl()`
+ * cannot go past white, and the `rec2100-*` spaces would tie the value to an
+ * absolute reference white it doesn't need.
  */
-type GlazeHdrFormat = 'srgb-linear';
+type GlazeHdrFormat = 'srgb' | 'srgb-linear';
 /**
  * Controls which scheme variants are generated in the export.
  * Light is always included (it's the default).
@@ -282,10 +290,16 @@ interface GlazeOutputModes {
    *
    * When on, each exporter adds the HDR values next to the SDR ones it
    * already emits (only for the scheme variants the other modes include),
-   * always written as `color(srgb-linear R G B)`: Tasty `hdr` state keys,
+   * always written as extended `color(srgb R G B)`: Tasty `hdr` state keys,
    * `json()` `lightHdr` / `darkHdr` / … keys, `tokens()` `lightHdr` / … maps,
    * Tailwind blocks under `hdrSelector`, DTCG `$extensions`. `css()` reads
    * its own `hdr` option, which falls back to this.
+   *
+   * The data tiers (DTCG, `json()`, `tokens()`) are what native apps and
+   * WebGPU canvases read. The CSS-family tiers (Tasty, `css()`, Tailwind) are
+   * experimental: no browser paints a CSS color past SDR white yet. Prefer
+   * turning this on per call (`theme.dtcg({ modes: { hdr: true } })`) over
+   * globally.
    */
   hdr?: boolean;
 }
@@ -455,6 +469,8 @@ interface LightingTuning {
   /**
    * Pigment saturation (0–1) in the surface's hue. Default: 0 (neutral black /
    * white). Shows only with `reach` below 1 — pure black and white have no hue.
+   * A neutral surface has no hue either: there the tint takes the object's
+   * hue with `hueBleed` above 0, and the pigment stays neutral otherwise.
    */
   tint?: number;
   /**
@@ -492,7 +508,7 @@ interface GlowTuning extends LightingTuning {
    * reach" warning. On a chromatic surface a `reach: 0` gray can measure
    * slightly brighter than the surface and pins at full opacity instead.
    * Nothing about the SDR variant changes. The gain lands the exact step when
-   * the headroom allows it; the brightest channel caps at `2^headroom`.
+   * the headroom allows it; the brightest linear channel caps at `2^headroom`.
    * High-contrast schemes use the same headroom.
    *
    * The HDR value lands the whole step, not just the part past white. A
@@ -675,7 +691,8 @@ interface ResolvedColorVariant {
  * The HDR value of a glow past SDR white: an opaque base plus a gain. The base
  * is what SDR paints at its brightest — the glow's pigment at full opacity, or
  * the white surface it cannot lift — and the HDR color is that base's linear
- * sRGB times `2^exposure`. Format it with `glaze.formatHdr()`.
+ * sRGB times `2^exposure`. Format it with `glaze.formatHdr()`, or read its
+ * channels with `hdrToSrgb()` / `hdrToLinearSrgb()`.
  *
  * Stored in OKHST like the variant. `s` is always standard (non-pastel)
  * OKHSL saturation, whatever the variant's `pastel`, since the base is an
@@ -727,7 +744,8 @@ interface GlazeConfig {
    * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`
    * / `'@media(dynamic-range: high)'`) so tokens react to the OS preference
    * and the display without registering custom states. `hdr` keys an HDR
-   * glow value and is used only with `modes.hdr`.
+   * glow value and is used only with `modes.hdr` (experimental, see
+   * `GlazeOutputModes.hdr`).
    */
   states?: {
     dark?: string;
@@ -1367,8 +1385,8 @@ interface GlazeTheme {
    *
    * With `modes.hdr`, each scheme map is followed by a dense `<scheme>Hdr`
    * map (`lightHdr`, `darkHdr`, …): every glow with an HDR value in any
-   * emitted scheme, as `color(srgb-linear …)`, or its SDR value where that
-   * scheme has none.
+   * emitted scheme, as extended `color(srgb …)`, or its SDR value where
+   * that scheme has none.
    */
   tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /**
@@ -1482,6 +1500,9 @@ interface GlazeCssOptions {
    * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
    * Default: the global `modes.hdr` (false). `css()` has no `modes` — it
    * always emits all four schemes — so this is its HDR switch.
+   * @experimental No browser paints a CSS color past SDR white yet, so this
+   * tier looks like SDR at best today, and its shape may change (for example
+   * to CSS `hdr-color()`) once one does.
    */
   hdr?: boolean;
 }
@@ -1498,7 +1519,7 @@ interface GlazeCssResult extends GlazeCssSchemeBlocks {
    * The HDR tier, present when HDR output is on — the `hdr` option, which
    * defaults to the global `modes.hdr`: one block per scheme,
    * each re-declaring every color that has an HDR value in any scheme — its
-   * HDR value (`color(srgb-linear R G B)`) where that scheme has one, and
+   * HDR value (extended `color(srgb R G B)`) where that scheme has one, and
    * the scheme's SDR declaration where it has none. The blocks are dense so
    * a light HDR value can never leak into dark: wire each one after the SDR
    * blocks, under the same selector plus `(dynamic-range: high)`. Every block
@@ -1538,9 +1559,11 @@ type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;
 /**
  * The HDR value of a glow past SDR white, carried in a DTCG token's
  * `$extensions['me.tenphi.glaze'].hdr` (`$value` stays the SDR color, since
- * DTCG color components stop at 1). Maps onto native APIs: UIKit / AppKit
- * `exposure`, SwiftUI `exposureAdjust(exposure)` on `base`, or Android
- * `Color.pack(…components, LINEAR_EXTENDED_SRGB)` from `value`.
+ * DTCG color components stop at 1). Maps onto native APIs: UIKit
+ * `UIColor(red:green:blue:alpha:exposure:)` (AppKit: its `NSColor` twin) from
+ * `base` and `exposure`, or Android
+ * `Color.pack(r, g, b, 1f, ColorSpace.get(ColorSpace.Named.EXTENDED_SRGB))`
+ * from `value`.
  */
 interface GlazeDtcgHdr {
   /** Gain over `base` in stops (`log2` of the linear factor), above 0. */
@@ -1554,11 +1577,12 @@ interface GlazeDtcgHdr {
   /** The opaque base (what SDR paints), as a DTCG sRGB color. */
   base: DtcgSrgbColorValue;
   /**
-   * The HDR color: linear sRGB `base × 2^exposure`, its brightest channel
+   * The HDR color, `base × 2^exposure` in linear light, as extended sRGB
+   * components (the numbers of `glaze.formatHdr()`): its brightest channel
    * above 1 (the others may stay below).
    */
   value: {
-    colorSpace: 'srgb-linear';
+    colorSpace: 'srgb';
     components: [number, number, number];
   };
 }
@@ -1718,6 +1742,9 @@ interface GlazeTailwindOptions {
    * where the scheme has none) and is scoped by this selector alone (light),
    * combined with `darkSelector` (dark), with `highContrastSelector` (light
    * high contrast), or with both.
+   * @experimental No browser paints a CSS color past SDR white yet, so this
+   * tier looks like SDR at best today, and its shape may change (for example
+   * to CSS `hdr-color()`) once one does.
    */
   hdrSelector?: string;
 }
@@ -1791,6 +1818,9 @@ interface GlazePaletteCssOptions extends GlazePaletteExportOptions {
   /**
    * Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
    * Default: the global `modes.hdr` (false).
+   * @experimental No browser paints a CSS color past SDR white yet, so this
+   * tier looks like SDR at best today, and its shape may change (for example
+   * to CSS `hdr-color()`) once one does.
    */
   hdr?: boolean;
 }
@@ -1860,14 +1890,6 @@ interface GlazePalette {
   tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
 }
 //#endregion
-//#region src/serialize.d.ts
-/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
-declare function isThemeExport(data: unknown): data is GlazeThemeExport;
-/** Type guard for color-token authoring snapshots. */
-declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
-/** Type guard for palette authoring snapshots. */
-declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
-//#endregion
 //#region src/glaze.d.ts
 type PaletteInput = Record<string, GlazeTheme>;
 /**
@@ -1914,13 +1936,21 @@ declare namespace glaze {
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
   var paletteFrom: (data: GlazePaletteExport) => GlazePalette;
-  var isThemeExport: typeof isThemeExport;
-  var isColorTokenExport: typeof isColorTokenExport;
-  var isPaletteExport: typeof isPaletteExport;
+  var isThemeExport: (value: unknown) => value is GlazeThemeExport;
+  var isColorTokenExport: (value: unknown) => value is GlazeColorTokenExport;
+  var isPaletteExport: (value: unknown) => value is GlazePaletteExport;
   var getConfig: () => GlazeConfigResolved;
   var resetConfig: () => void;
 }
 //#endregion
+//#region src/serialize.d.ts
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+declare function isThemeExport(data: unknown): data is GlazeThemeExport;
+/** Type guard for color-token authoring snapshots. */
+declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
+//#endregion
 //#region src/channels.d.ts
 interface HueDeclaration {
   prop: string;
@@ -1965,12 +1995,14 @@ interface ChannelCtx {
  * emits raw CSS or non-Tasty token maps.
  */
 declare function assertNativeFormat(format: GlazeColorFormat | undefined, method: string): void;
+/** The modes `assertAllPastel` reads: which schemes are emitted. */
+type SchemeModes = Required<Pick<GlazeOutputModes, 'dark' | 'highContrast'>>;
 /**
  * Throw when `splitHue` is enabled but any exported color is not pastel.
  * Hue rotation is only clip-free when chroma is bounded by the hue-independent
  * safe chroma (`computeSafeChromaOKLCH`).
  */
-declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: Required<GlazeOutputModes>): void;
+declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: SchemeModes): void;
 //#endregion
 //#region src/roles.d.ts
 /**
@@ -2069,8 +2101,8 @@ declare function variantToOkhsl(v: {
  * luminance `Ys` — both the exact functions the contrast solver uses, and
  * both public), strict hex parsing (`parseHex` / `parseHexAlpha` check every
  * digit), and multi-format output (okhsl, rgb, hsl, oklch, plus the
- * `color(srgb-linear …)` writer for HDR glow values, whose channels may exceed
- * 1).
+ * unclamped `color(srgb …)` / `color(srgb-linear …)` writers for HDR glow
+ * values, whose channels may exceed 1).
  */
 type Vec3 = [number, number, number];
 /**
@@ -2141,6 +2173,11 @@ declare const oklabToOkhsl: (lab: Vec3, pastel?: boolean) => Vec3;
 /**
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
+ *
+ * A gray reads with saturation 0 (its computed hue is kept). Its OKLab
+ * residue would otherwise come out as a saturation that grows toward white
+ * (`#fefefe` reads 1.6e-5, `rgb(254.999 254.999 254.999)` 1.6e-2), which a
+ * color carries into every scheme and an OKHSL mix reads as a hue.
  */
 declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [number, number, number];
 /**
@@ -2208,10 +2245,21 @@ declare function formatOklch(h: number, s: number, l: number, pastel?: boolean):
  * Format linear sRGB channels as a CSS `color(srgb-linear R G B)` string with
  * 4 decimals. Unlike the other writers it takes linear light, not OKHSL, and
  * does not clamp: a channel may exceed 1, which is how an HDR glow value
- * (`glaze.formatHdr()`) goes past SDR white — `1` is SDR white, `2` one stop
- * above it. Opaque only; HDR values carry no alpha.
+ * written with `glaze.formatHdr(v, 'srgb-linear')` goes past SDR white — `1`
+ * is SDR white, `2` one stop above it (the default extended form is
+ * `formatSrgb`). Opaque only; HDR values carry no alpha.
  */
 declare function formatSrgbLinear(rgb: [number, number, number]): string;
+/**
+ * Format extended sRGB channels — gamma-encoded, with the transfer function
+ * continued past 1 (`sRGBLinearToGamma` does) — as a CSS `color(srgb R G B)`
+ * string with 4 decimals. Like `formatSrgbLinear` it takes the channels of
+ * its own space and does not clamp, so an HDR glow value
+ * (`glaze.formatHdr()`) can pass SDR white: `1` is SDR white, about `1.3533`
+ * one stop above it. CSS reads it as the same color as the matching
+ * `color(srgb-linear …)`. Opaque only; HDR values carry no alpha.
+ */
+declare function formatSrgb(rgb: [number, number, number]): string;
 /**
  * Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
  * string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
@@ -2225,5 +2273,21 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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 };
+//#region src/lighting.d.ts
+/**
+ * Linear sRGB of a resolved HDR value: the base's channels times
+ * `2^exposure`, unclamped (the brightest channel can reach `2^headroom`).
+ * The base is non-pastel OKHSL, so no `pastel` flag applies.
+ */
+declare function hdrToLinearSrgb(hdr: ResolvedHdr): [number, number, number];
+/**
+ * Extended sRGB of a resolved HDR value: `hdrToLinearSrgb` through the sRGB
+ * transfer function, continued past 1 the way CSS and the platform
+ * extended-sRGB spaces continue it, unclamped. These are the channels of
+ * `color(srgb R G B)` (`glaze.formatHdr()`), and what a WebGPU `'srgb'`
+ * canvas, `CGColorSpace.extendedSRGB`, and Android's `EXTENDED_SRGB` take.
+ */
+declare function hdrToSrgb(hdr: ResolvedHdr): [number, number, number];
+//#endregion
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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, formatSrgb, formatSrgbLinear, fromTone, gamutClampedLuminance, glaze, hdrToLinearSrgb, hdrToSrgb, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map