@tenphi/glaze 0.0.0-snapshot.c3d484c → 0.0.0-snapshot.c61bbdf

package/dist/index.d.cts

@@ -296,7 +296,7 @@ interface RegularColorDef {
    */
   from?: GlazeColorValue;
   /**
-   * Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
+   * Tone value (0–100, contrast-uniform — see `docs/okhst.mdx`).
    * - Number: absolute tone.
    * - String ('+N' / '-N'): relative to base color's tone (requires `base`).
    * - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
@@ -390,44 +390,63 @@ interface RegularColorDef {
    */
   inherit?: boolean;
 }
-/** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
-interface ShadowTuning {
-  /** Fraction of fg saturation kept in pigment (0-1). Default: 0.18. */
-  saturationFactor?: number;
-  /** Upper clamp on pigment saturation (0-1). Default: 0.25. */
-  maxSaturation?: number;
-  /** Multiplier for bg lightness → pigment lightness. Default: 0.25. */
-  lightnessFactor?: number;
-  /** [min, max] clamp for pigment lightness (0-1). Default: [0.05, 0.20]. */
-  lightnessBounds?: [number, number];
+/**
+ * Tuning shared by `shadow` and `glow`. Global defaults come from
+ * `shadowTuning` / `glowTuning`; a per-color `tuning` merges over them field
+ * by field.
+ */
+interface LightingTuning {
   /**
-   * Target minimum gap between pigment lightness and bg lightness (0-1).
-   * Default: 0.05.
+   * β — how strongly the object (`fg`) scales the step. The step is
+   * `intensity × k` with `k = max(0, 1 + β · d · (t_bg − t_fg) / 100)`,
+   * `d = +1` for a shadow and `−1` for a glow: a darker object deepens its
+   * shadow, a lighter one strengthens its glow. An object at the surface's
+   * own tone (or no `fg`) gives exactly `intensity`. `0` ignores the object.
+   * Default: 0.5.
    */
-  minGapTarget?: number;
-  /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
-  alphaMax?: number;
+  objectInfluence?: number;
   /**
-   * Blend weight (0-1) pulling pigment hue toward bg hue.
-   * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
+   * 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.
    */
-  bgHueBlend?: number;
+  tint?: number;
+  /**
+   * Where the pigment sits (0–1): the fraction of the way from the surface's
+   * tone to black (shadow) / white (glow). Default: 1 (pure black / white),
+   * the most reach. Lower values let a `tint` show at the cost of reach.
+   */
+  reach?: number;
+  /**
+   * Pull (0–1) of the pigment hue from the surface's hue toward the object's
+   * (`fg`) hue. Default: 0. Needs `fg`, a `tint`, and `reach` below 1 to show.
+   */
+  hueBleed?: number;
 }
+/** Tuning for `shadow` colors. Same shape as {@link GlowTuning}. */
+type ShadowTuning = LightingTuning;
+/** Tuning for `glow` colors. Same shape as {@link ShadowTuning}. */
+type GlowTuning = LightingTuning;
+/**
+ * A translucent dark overlay that lands the surface (`bg`) exactly
+ * `intensity` tones darker in every scheme — a shade for state layers and
+ * scrims, or, with `fg`, an object-aware drop shadow.
+ */
 interface ShadowColorDef {
   type: 'shadow';
   /**
-   * Background color name — the surface the shadow sits on.
-   * Must reference a non-shadow color in the same theme.
+   * The surface the shadow falls on. Must reference a color that is not a
+   * shadow or glow.
    */
   bg: string;
   /**
-   * Foreground color name for tinting and intensity modulation.
-   * Must reference a non-shadow color in the same theme.
-   * Omit for achromatic shadow at full user-specified intensity.
+   * The object casting the shadow (e.g. the card). A darker object casts a
+   * deeper shadow, a lighter one a softer shadow — see
+   * `LightingTuning.objectInfluence`. Omit for an exact shade of `intensity`
+   * tones. Must reference a color that is not a shadow or glow.
    */
   fg?: string;
   /**
-   * Shadow intensity, 0-100.
+   * Tone step, 0–100: how many tones darker than `bg` the composite lands.
    * Supports [normal, highContrast] pair.
    */
   intensity: HCPair<number>;
@@ -446,6 +465,44 @@ interface ShadowColorDef {
    */
   inherit?: boolean;
 }
+/**
+ * The mirror of {@link ShadowColorDef}: a translucent light overlay that lands
+ * the surface (`bg`) exactly `intensity` tones lighter in every scheme — for
+ * dark-mode elevation, edge highlights, and lightening state layers.
+ */
+interface GlowColorDef {
+  type: 'glow';
+  /**
+   * The surface the glow falls on. Must reference a color that is not a
+   * shadow or glow.
+   */
+  bg: string;
+  /**
+   * The object emitting the glow. A lighter object glows stronger, a darker
+   * one weaker — see `LightingTuning.objectInfluence`. Omit for an exact tint
+   * of `intensity` tones. Must reference a color that is not a shadow or glow.
+   */
+  fg?: string;
+  /**
+   * Tone step, 0–100: how many tones lighter than `bg` the composite lands.
+   * Supports [normal, highContrast] pair.
+   */
+  intensity: HCPair<number>;
+  /** Override default tuning. Merged field-by-field with global `glowTuning`. */
+  tuning?: GlowTuning;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
+   */
+  pastel?: boolean;
+  /**
+   * Whether this color is inherited by child themes created via `extend()`.
+   * Default: true. Set to false to make this color local to the current theme.
+   */
+  inherit?: boolean;
+}
 interface MixColorDef {
   type: 'mix';
   /** Background/base color name — the "from" color. */
@@ -467,9 +524,12 @@ interface MixColorDef {
   /**
    * Interpolation color space for opaque blending. Default: 'okhsl'.
    * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
-   * - 'srgb': linear sRGB interpolation, matches browser compositing.
+   * - 'srgb': linear-light sRGB interpolation (like CSS
+   *   `color-mix(in srgb-linear, …)`).
    *
-   * Ignored for 'transparent' blend (always composites in linear sRGB).
+   * Ignored for 'transparent' blend: the browser composites that one, and
+   * its contrast solve models the browser (`source-over` on gamma-encoded
+   * sRGB).
    */
   space?: 'okhsl' | 'srgb';
   /**
@@ -499,7 +559,7 @@ interface MixColorDef {
    */
   inherit?: boolean;
 }
-type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
+type ColorDef = RegularColorDef | ShadowColorDef | GlowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
 /**
  * Resolved color for a single scheme variant.
@@ -531,7 +591,7 @@ interface ResolvedColor {
   dark: ResolvedColorVariant;
   lightContrast: ResolvedColorVariant;
   darkContrast: ResolvedColorVariant;
-  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
+  /** Adaptation mode of a regular color; `undefined` for shadow / glow / mix. */
   mode?: AdaptationMode;
 }
 /**
@@ -571,6 +631,8 @@ interface GlazeConfig {
   modes?: GlazeOutputModes;
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
+  /** Default tuning for all glow colors. Per-color tuning merges field-by-field. */
+  glowTuning?: GlowTuning;
   /**
    * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
    * contrast (`100`), or `'auto'` (the default) to take the authored normal
@@ -590,7 +652,7 @@ interface GlazeConfig {
    * approximation, and a color keeps to one side of its base as the level moves.
    *
    * Pass `'auto'` to leave manual mode; `configure()` never clears a field by
-   * omission. See `docs/api.md` for the ramp's edge cases (un-interpolable
+   * omission. See `docs/reference/contrast.md` for the ramp's edge cases (un-interpolable
    * pairs, side changes) and the export-freeze rule.
    *
    * @default 'auto'
@@ -629,6 +691,7 @@ interface GlazeConfigResolved {
   };
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
+  glowTuning?: GlowTuning;
   autoFlip: boolean;
   /**
    * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
@@ -690,12 +753,22 @@ interface GlazeConfigOverride {
    * standalone color tokens.
    */
   shadowTuning?: ShadowTuning;
+  /**
+   * Glow tuning defaults. Only meaningful for themes; harmless on
+   * standalone color tokens.
+   */
+  glowTuning?: GlowTuning;
 }
 /**
  * Current authoring-export schema version. Bump when the export shape
  * changes in a non-compatible way. Written on every `.export()` snapshot.
+ *
+ * - `1` — Glaze 2.x.
+ * - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
+ *   `glow` was added. Version-1 theme snapshots that carry shadow defs or a
+ *   `shadowTuning` are rejected on restore.
  */
-declare const GLAZE_EXPORT_VERSION: 1;
+declare const GLAZE_EXPORT_VERSION: 2;
 /** Literal type of {@link GLAZE_EXPORT_VERSION}. */
 type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
 /** Discriminator for authoring export snapshots. */
@@ -720,24 +793,25 @@ interface GlazeThemeExport {
    */
   config?: GlazeConfigOverride;
 }
-/** Input for `glaze.shadow()` standalone factory. */
-interface GlazeShadowInput {
+/** Input for the `glaze.shadow()` and `glaze.glow()` standalone factories. */
+interface GlazeLightingInput {
   /**
-   * Background color — accepts any `GlazeColorValue` form: hex
+   * The surface — accepts any `GlazeColorValue` form: hex
    * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
    * / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
    * `{ l, c, h }`). Alpha components are dropped with a warning.
    */
   bg: GlazeColorValue;
-  /**
-   * Foreground color for tinting + intensity modulation. Accepts the
-   * same forms as `bg`.
-   */
+  /** The object casting the shadow / emitting the glow. Same forms as `bg`. */
   fg?: GlazeColorValue;
-  /** Intensity 0-100. */
+  /** Tone step, 0–100. */
   intensity: number;
-  tuning?: ShadowTuning;
+  tuning?: LightingTuning;
 }
+/** Input for `glaze.shadow()`. */
+type GlazeShadowInput = GlazeLightingInput;
+/** Input for `glaze.glow()`. */
+type GlazeGlowInput = GlazeLightingInput;
 /** Input for the structured `glaze.color()` overload. */
 interface GlazeColorInput {
   hue: number;
@@ -1553,9 +1627,13 @@ type PaletteInput = Record<string, GlazeTheme>;
  * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
  * // with config override:
  * const raw = glaze(280, 80, { lightTone: false });
+ * const rawSeed = glaze({ hue: 280, saturation: 80 }, { lightTone: false });
  * ```
  */
-declare function glaze(hueOrOptions: number | GlazeThemeSeed, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(hue: number, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(seed: GlazeThemeSeed, config?: GlazeConfigOverride): GlazeTheme;
+/** @deprecated Pass the config second: `glaze(seed, config)`. */
+declare function glaze(seed: GlazeThemeSeed, saturation: undefined, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
@@ -1563,6 +1641,7 @@ declare namespace glaze {
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
+  var glow: (input: GlazeGlowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
@@ -1583,7 +1662,7 @@ interface HueDeclaration {
 interface HuePlan {
   /** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
   hueVar: string;
-  /** When true, emit a full inline color (shadow/mix/achromatic). */
+  /** When true, emit a full inline color (shadow/glow/mix/achromatic). */
   inline: boolean;
   /** Scheme-independent `--*-hue` declarations for this color. */
   declarations: HueDeclaration[];
@@ -1844,5 +1923,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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 };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeGlowInput, type GlazeJsonOptions, type GlazeLightingInput, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, type GlazeTokenOptions, type GlowColorDef, type GlowTuning, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type LightingTuning, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -296,7 +296,7 @@ interface RegularColorDef {
    */
   from?: GlazeColorValue;
   /**
-   * Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
+   * Tone value (0–100, contrast-uniform — see `docs/okhst.mdx`).
    * - Number: absolute tone.
    * - String ('+N' / '-N'): relative to base color's tone (requires `base`).
    * - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
@@ -390,44 +390,63 @@ interface RegularColorDef {
    */
   inherit?: boolean;
 }
-/** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
-interface ShadowTuning {
-  /** Fraction of fg saturation kept in pigment (0-1). Default: 0.18. */
-  saturationFactor?: number;
-  /** Upper clamp on pigment saturation (0-1). Default: 0.25. */
-  maxSaturation?: number;
-  /** Multiplier for bg lightness → pigment lightness. Default: 0.25. */
-  lightnessFactor?: number;
-  /** [min, max] clamp for pigment lightness (0-1). Default: [0.05, 0.20]. */
-  lightnessBounds?: [number, number];
+/**
+ * Tuning shared by `shadow` and `glow`. Global defaults come from
+ * `shadowTuning` / `glowTuning`; a per-color `tuning` merges over them field
+ * by field.
+ */
+interface LightingTuning {
   /**
-   * Target minimum gap between pigment lightness and bg lightness (0-1).
-   * Default: 0.05.
+   * β — how strongly the object (`fg`) scales the step. The step is
+   * `intensity × k` with `k = max(0, 1 + β · d · (t_bg − t_fg) / 100)`,
+   * `d = +1` for a shadow and `−1` for a glow: a darker object deepens its
+   * shadow, a lighter one strengthens its glow. An object at the surface's
+   * own tone (or no `fg`) gives exactly `intensity`. `0` ignores the object.
+   * Default: 0.5.
    */
-  minGapTarget?: number;
-  /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
-  alphaMax?: number;
+  objectInfluence?: number;
   /**
-   * Blend weight (0-1) pulling pigment hue toward bg hue.
-   * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
+   * 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.
    */
-  bgHueBlend?: number;
+  tint?: number;
+  /**
+   * Where the pigment sits (0–1): the fraction of the way from the surface's
+   * tone to black (shadow) / white (glow). Default: 1 (pure black / white),
+   * the most reach. Lower values let a `tint` show at the cost of reach.
+   */
+  reach?: number;
+  /**
+   * Pull (0–1) of the pigment hue from the surface's hue toward the object's
+   * (`fg`) hue. Default: 0. Needs `fg`, a `tint`, and `reach` below 1 to show.
+   */
+  hueBleed?: number;
 }
+/** Tuning for `shadow` colors. Same shape as {@link GlowTuning}. */
+type ShadowTuning = LightingTuning;
+/** Tuning for `glow` colors. Same shape as {@link ShadowTuning}. */
+type GlowTuning = LightingTuning;
+/**
+ * A translucent dark overlay that lands the surface (`bg`) exactly
+ * `intensity` tones darker in every scheme — a shade for state layers and
+ * scrims, or, with `fg`, an object-aware drop shadow.
+ */
 interface ShadowColorDef {
   type: 'shadow';
   /**
-   * Background color name — the surface the shadow sits on.
-   * Must reference a non-shadow color in the same theme.
+   * The surface the shadow falls on. Must reference a color that is not a
+   * shadow or glow.
    */
   bg: string;
   /**
-   * Foreground color name for tinting and intensity modulation.
-   * Must reference a non-shadow color in the same theme.
-   * Omit for achromatic shadow at full user-specified intensity.
+   * The object casting the shadow (e.g. the card). A darker object casts a
+   * deeper shadow, a lighter one a softer shadow — see
+   * `LightingTuning.objectInfluence`. Omit for an exact shade of `intensity`
+   * tones. Must reference a color that is not a shadow or glow.
    */
   fg?: string;
   /**
-   * Shadow intensity, 0-100.
+   * Tone step, 0–100: how many tones darker than `bg` the composite lands.
    * Supports [normal, highContrast] pair.
    */
   intensity: HCPair<number>;
@@ -446,6 +465,44 @@ interface ShadowColorDef {
    */
   inherit?: boolean;
 }
+/**
+ * The mirror of {@link ShadowColorDef}: a translucent light overlay that lands
+ * the surface (`bg`) exactly `intensity` tones lighter in every scheme — for
+ * dark-mode elevation, edge highlights, and lightening state layers.
+ */
+interface GlowColorDef {
+  type: 'glow';
+  /**
+   * The surface the glow falls on. Must reference a color that is not a
+   * shadow or glow.
+   */
+  bg: string;
+  /**
+   * The object emitting the glow. A lighter object glows stronger, a darker
+   * one weaker — see `LightingTuning.objectInfluence`. Omit for an exact tint
+   * of `intensity` tones. Must reference a color that is not a shadow or glow.
+   */
+  fg?: string;
+  /**
+   * Tone step, 0–100: how many tones lighter than `bg` the composite lands.
+   * Supports [normal, highContrast] pair.
+   */
+  intensity: HCPair<number>;
+  /** Override default tuning. Merged field-by-field with global `glowTuning`. */
+  tuning?: GlowTuning;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
+   */
+  pastel?: boolean;
+  /**
+   * Whether this color is inherited by child themes created via `extend()`.
+   * Default: true. Set to false to make this color local to the current theme.
+   */
+  inherit?: boolean;
+}
 interface MixColorDef {
   type: 'mix';
   /** Background/base color name — the "from" color. */
@@ -467,9 +524,12 @@ interface MixColorDef {
   /**
    * Interpolation color space for opaque blending. Default: 'okhsl'.
    * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
-   * - 'srgb': linear sRGB interpolation, matches browser compositing.
+   * - 'srgb': linear-light sRGB interpolation (like CSS
+   *   `color-mix(in srgb-linear, …)`).
    *
-   * Ignored for 'transparent' blend (always composites in linear sRGB).
+   * Ignored for 'transparent' blend: the browser composites that one, and
+   * its contrast solve models the browser (`source-over` on gamma-encoded
+   * sRGB).
    */
   space?: 'okhsl' | 'srgb';
   /**
@@ -499,7 +559,7 @@ interface MixColorDef {
    */
   inherit?: boolean;
 }
-type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
+type ColorDef = RegularColorDef | ShadowColorDef | GlowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
 /**
  * Resolved color for a single scheme variant.
@@ -531,7 +591,7 @@ interface ResolvedColor {
   dark: ResolvedColorVariant;
   lightContrast: ResolvedColorVariant;
   darkContrast: ResolvedColorVariant;
-  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
+  /** Adaptation mode of a regular color; `undefined` for shadow / glow / mix. */
   mode?: AdaptationMode;
 }
 /**
@@ -571,6 +631,8 @@ interface GlazeConfig {
   modes?: GlazeOutputModes;
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
+  /** Default tuning for all glow colors. Per-color tuning merges field-by-field. */
+  glowTuning?: GlowTuning;
   /**
    * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
    * contrast (`100`), or `'auto'` (the default) to take the authored normal
@@ -590,7 +652,7 @@ interface GlazeConfig {
    * approximation, and a color keeps to one side of its base as the level moves.
    *
    * Pass `'auto'` to leave manual mode; `configure()` never clears a field by
-   * omission. See `docs/api.md` for the ramp's edge cases (un-interpolable
+   * omission. See `docs/reference/contrast.md` for the ramp's edge cases (un-interpolable
    * pairs, side changes) and the export-freeze rule.
    *
    * @default 'auto'
@@ -629,6 +691,7 @@ interface GlazeConfigResolved {
   };
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
+  glowTuning?: GlowTuning;
   autoFlip: boolean;
   /**
    * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
@@ -690,12 +753,22 @@ interface GlazeConfigOverride {
    * standalone color tokens.
    */
   shadowTuning?: ShadowTuning;
+  /**
+   * Glow tuning defaults. Only meaningful for themes; harmless on
+   * standalone color tokens.
+   */
+  glowTuning?: GlowTuning;
 }
 /**
  * Current authoring-export schema version. Bump when the export shape
  * changes in a non-compatible way. Written on every `.export()` snapshot.
+ *
+ * - `1` — Glaze 2.x.
+ * - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
+ *   `glow` was added. Version-1 theme snapshots that carry shadow defs or a
+ *   `shadowTuning` are rejected on restore.
  */
-declare const GLAZE_EXPORT_VERSION: 1;
+declare const GLAZE_EXPORT_VERSION: 2;
 /** Literal type of {@link GLAZE_EXPORT_VERSION}. */
 type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
 /** Discriminator for authoring export snapshots. */
@@ -720,24 +793,25 @@ interface GlazeThemeExport {
    */
   config?: GlazeConfigOverride;
 }
-/** Input for `glaze.shadow()` standalone factory. */
-interface GlazeShadowInput {
+/** Input for the `glaze.shadow()` and `glaze.glow()` standalone factories. */
+interface GlazeLightingInput {
   /**
-   * Background color — accepts any `GlazeColorValue` form: hex
+   * The surface — accepts any `GlazeColorValue` form: hex
    * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
    * / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
    * `{ l, c, h }`). Alpha components are dropped with a warning.
    */
   bg: GlazeColorValue;
-  /**
-   * Foreground color for tinting + intensity modulation. Accepts the
-   * same forms as `bg`.
-   */
+  /** The object casting the shadow / emitting the glow. Same forms as `bg`. */
   fg?: GlazeColorValue;
-  /** Intensity 0-100. */
+  /** Tone step, 0–100. */
   intensity: number;
-  tuning?: ShadowTuning;
+  tuning?: LightingTuning;
 }
+/** Input for `glaze.shadow()`. */
+type GlazeShadowInput = GlazeLightingInput;
+/** Input for `glaze.glow()`. */
+type GlazeGlowInput = GlazeLightingInput;
 /** Input for the structured `glaze.color()` overload. */
 interface GlazeColorInput {
   hue: number;
@@ -1553,9 +1627,13 @@ type PaletteInput = Record<string, GlazeTheme>;
  * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
  * // with config override:
  * const raw = glaze(280, 80, { lightTone: false });
+ * const rawSeed = glaze({ hue: 280, saturation: 80 }, { lightTone: false });
  * ```
  */
-declare function glaze(hueOrOptions: number | GlazeThemeSeed, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(hue: number, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(seed: GlazeThemeSeed, config?: GlazeConfigOverride): GlazeTheme;
+/** @deprecated Pass the config second: `glaze(seed, config)`. */
+declare function glaze(seed: GlazeThemeSeed, saturation: undefined, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
@@ -1563,6 +1641,7 @@ declare namespace glaze {
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
+  var glow: (input: GlazeGlowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
@@ -1583,7 +1662,7 @@ interface HueDeclaration {
 interface HuePlan {
   /** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
   hueVar: string;
-  /** When true, emit a full inline color (shadow/mix/achromatic). */
+  /** When true, emit a full inline color (shadow/glow/mix/achromatic). */
   inline: boolean;
   /** Scheme-independent `--*-hue` declarations for this color. */
   declarations: HueDeclaration[];
@@ -1844,5 +1923,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, 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 };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeGlowInput, type GlazeJsonOptions, type GlazeLightingInput, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, type GlazeTokenOptions, type GlowColorDef, type GlowTuning, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type LightingTuning, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map