shaders 3.2.475 → 4.0.0

package/dist/core/std/paint/light.d.ts

@@ -4,12 +4,24 @@ import { PointwiseEffect } from '../types';
 import { PropRef } from '../values';
 import { ArgSpec } from '../invoke';
 
-/** A lowered light value — evaluate against the composition params. */
+/**
+ * A light or a frame waiting for the shader's params. Call it with `params` inside a
+ * `paint` or `effect` function to get its value at this pixel.
+ */
 export type LightValue = (params: GpuFragmentParams) => Expr;
 /**
- * `rayBands` — banded shimmer along an axis: a traveling sine over `along`, lifted to
- * [0, 1] and sharpened by a power curve. Higher `sharpness` narrows the bright bands.
- * Feed a noise-warped `along` for organic rays (aurora curtains, godray shimmer, fabric).
+ * Bright bands that travel along a coordinate, for aurora curtains or shimmering rays.
+ *
+ * Returns a 0–1 field. `along` is the coordinate the bands cross (a uv axis, or a
+ * noise-warped one for organic rays), `frequency` the band count per unit of it, and
+ * `time` × `speed` how fast they travel. `sharpness` above 1 narrows the bright bands.
+ *
+ * @example
+ * ```ts
+ * const rays = rayBands({along: params.ctx.uv.member('x'), frequency: 12, time: animatedTime(params), speed: 0.3, sharpness: 2})
+ * ```
+ * @tip Add a noise field to `along` before passing it and the straight bands turn into curtains.
+ * @see rayLobes, streakBand
  */
 export declare function rayBands(opts: {
     along: Expr;
@@ -20,19 +32,35 @@ export declare function rayBands(opts: {
     sharpness: Expr | number;
 }): Expr;
 /**
- * `emitterFalloff` — how light spilling from an emitter dims with distance `d` from it:
- * `(radius / (radius + d))^power` — 1 at the emitter, softened over `radius`, then a 1/d
- * line-emitter tail at power 1 tightening toward a 1/d² point-emitter tail at power 2. The
- * long-tailed cousin of the gaussian {@link glowSpot}: real irradiance, not a soft blob.
+ * How light spilling from an emitter dims with distance, with a long realistic tail.
+ *
+ * Returns 1 at the emitter, softened over `radius`, then fading like real light. `d` and
+ * `radius` share a unit (usually aspect-corrected uv). `power` 1 fades like a line of light,
+ * `power` 2 like a point. Use it where `glowPoint` looks too much like a soft blob.
+ *
+ * @example
+ * ```ts
+ * const spill = emitterFalloff(frame.member('x'), {radius: p('radius'), power: 2})
+ * ```
+ * @see glowPoint, glowSpot
  */
 export declare function emitterFalloff(d: Expr, opts: {
     radius: Expr | number;
     power: Expr | number;
 }): Expr;
 /**
- * `glowAt` — a round gaussian glow at a position in aspect-corrected UV space:
- * `exp(−0.5·dist²/sizeSq)`. Takes the SQUARED radius (callers usually drive several glows from
- * CPU-computed data). The positional cousin of {@link glowSpot}.
+ * A soft round glow at a position on the canvas.
+ *
+ * Returns a 0–1 field, 1 at the position. `x` and `y` are in uv (0–1, y down), `aspect` is
+ * the canvas width over height so the glow stays round, and `sizeSq` is the glow radius
+ * squared. Pass several with different positions and sum them with `additive`.
+ *
+ * @example
+ * ```ts
+ * const glow = glowAt({uv: params.ctx.uv, aspect: params.ctx.aspect, x: 0.5, y: 0.4, sizeSq: 0.02})
+ * ```
+ * @tip The radius goes in squared: a glow 0.15 across the canvas is `sizeSq: 0.0225`.
+ * @see glowSpot, glowPoint, radialFrame
  */
 export declare function glowAt(opts: {
     uv: Expr;
@@ -42,10 +70,17 @@ export declare function glowAt(opts: {
     sizeSq: Expr | number;
 }): Expr;
 /**
- * `domeNormal` — a fake surface: the normal field of a flat disc treated as a bulging dome
- * ("make it look puffy" — the Bevel & Emboss family's opening move). Geometry only; light
- * it with {@link shine}. `bulge.tilt` sets how far normals lean outward at the rim,
- * `bulge.drop` how much the dome flattens toward the edge. Defaults are the house dome.
+ * The surface normals of a flat disc treated as a puffy dome, ready to light with `shine`.
+ *
+ * `delta` is the offset from the disc center, `dist` its length and `radius` the disc size,
+ * all in the same unit. `bulge.tilt` (default 0.2) sets how far the normals lean outward at
+ * the rim and `bulge.drop` (default 0.1) how much the dome flattens toward its edge.
+ *
+ * @example
+ * ```ts
+ * const highlight = shine({normal: domeNormal({delta, dist, radius}), light: vec3(0.3, -0.5, 0.8), gloss: 32})
+ * ```
+ * @see shine
  */
 export declare function domeNormal(opts: {
     delta: Expr;
@@ -57,10 +92,18 @@ export declare function domeNormal(opts: {
     };
 }): Expr;
 /**
- * `shine` — light a normal field: the specular lobe of a unit light direction against
- * `normal`, viewed along +z (the 2.5D worldview). Returns the RAW lobe — scale by
- * intensity × coverage at the call site. Shines anything that yields a normal: a
- * {@link domeNormal}, a bevel, a heightfield slope, a material surface.
+ * A specular highlight on any surface that gives you a normal.
+ *
+ * Returns the raw 0–1 highlight, viewed straight on. Multiply it by your intensity and the
+ * shape's coverage yourself. `light` is a unit direction toward the light and `gloss` sets
+ * the highlight's tightness (8 is broad, 32 is a small hot spot). Works with `domeNormal`,
+ * a bevel, or a heightfield slope.
+ *
+ * @example
+ * ```ts
+ * const highlight = mul(shine({normal, light: vec3(0.3, -0.5, 0.8), gloss: p('gloss')}), mask)
+ * ```
+ * @see domeNormal
  */
 export declare function shine(opts: {
     normal: Expr;
@@ -68,74 +111,194 @@ export declare function shine(opts: {
     gloss: Expr | number;
 }): Expr;
 /**
- * A light part over a frame's local coordinates. Radial-frame parts read
- * `vec2(dist, angle)`; beam-frame parts read `vec2(u, v)`.
+ * A light shaped over a frame's coordinates. Parts for `radialFrame` read distance and
+ * angle (`vec2(dist, angle)`); parts for `beamFrame` read distance along and across the
+ * beam (`vec2(u, v)`). Evaluate one with `withFrame`, combine several with `modulate`.
  */
 export type LightPart = (frame: Expr, params: GpuFragmentParams) => Expr;
 /**
- * Distance + angle (`vec2(dist, angle)`) around an unflipped centre prop in aspect-corrected
- * space — the radial frame of a burst, halo or sweep.
+ * The frame for a burst, halo or sweep around a center prop.
+ *
+ * Gives each pixel its distance and angle from the center as `vec2(dist, angle)`. Distance
+ * is in aspect-corrected uv (0.5 is half the canvas height), the angle in radians. `center`
+ * is a position prop. Evaluate parts in it with `withFrame`.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(radialFrame(p('center')), modulate(rayLobes({count: p('rays'), spin: -1, sharpness: 4}), featherMask({radius: p('radius'), feather: 0.5})), 'burst')
+ * ```
+ * @see withFrame, seamlessRadialFrame, beamFrame
  */
 export declare function radialFrame(center: PropRef): LightValue;
 /**
- * The seam-free radial frame volumetric rays march in — distance plus a wrap-free angular
- * coordinate around `center`.
+ * The frame `noiseRays` needs: a radial frame around a center prop with no visible seam.
+ *
+ * Patterns that repeat around an angle show a line where the angle wraps. This frame carries
+ * what a part needs to hide it. Only `noiseRays` reads it. `center` is a position prop.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(seamlessRadialFrame(p('center')), noiseRays({density: p('density'), intensity: p('intensity'), spotty: p('spotty')}))
+ * ```
+ * @tip The other radial parts (`glowPoint`, `rayLobes`, `featherMask`) read `radialFrame`, not this one. Its layout is different.
+ * @see noiseRays, radialFrame
  */
 export declare function seamlessRadialFrame(center: PropRef): LightValue;
 /**
- * The local frame of a beam anchored at a point and aimed at the canvas centre:
- * `vec2(u, v)` — distance along the beam and lateral offset — in aspect-corrected space.
- * Reads the raw filter context (a pointwise effect's frame, not a generator's).
+ * The frame of a beam that starts at an anchor prop and points at the canvas center.
+ *
+ * Gives each pixel its distance along the beam and its sideways offset from it as
+ * `vec2(u, v)`, in aspect-corrected uv. Drag the anchor anywhere and the beam still points
+ * inward. Built for filters over a child (a light leak inside `screenGlow`), where it reads
+ * the child's uv.
+ *
+ * @example
+ * ```ts
+ * const frame = local(beamFrame(p('position'))(params), 'leakFrame')
+ * ```
+ * @see beamBloom, beamStreaks, screenGlow
  */
 export declare function beamFrame(anchor: PropRef): LightValue;
 /**
- * Evaluate a light part in a frame — the composition root of a framed light recipe. A `hint`
- * names the stage and binds the frame as a WGSL local (required when the part reads the frame
- * more than once).
+ * Evaluate a light part in a frame.
+ *
+ * This is where a framed light starts: a frame, then the part (or `modulate` of several)
+ * drawn in it. Pass a name as the third argument when the part reads the frame more than
+ * once, so the frame is computed once per pixel. `modulate` always reads it more than once.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(radialFrame(p('center')), modulate(softRayLobes({count: p('rayCount'), softness: p('softness'), spin: -1}), featherMask({radius: p('radius'), feather: p('feather')})), 'burstFrame')
+ * ```
+ * @tip Without the name, a `modulate` of two parts computes the frame twice.
+ * @see radialFrame, beamFrame, modulate
  */
 export declare function withFrame(frame: LightValue, part: LightPart, hint?: string): LightValue;
-/** Multiply light parts over one frame (a mask over a pattern). */
+/**
+ * Multiply light parts drawn in the same frame, such as a mask over a pattern.
+ *
+ * @example
+ * ```ts
+ * modulate(rayLobes({count: 12, spin: -1, sharpness: 4}), glowPoint({sharpness: 6}), featherMask({radius: p('radius'), feather: 0.4}))
+ * ```
+ * @see withFrame, additive
+ */
 export declare function modulate(first: LightPart, ...rest: LightPart[]): LightPart;
-/** Rotating sine ray lobes around the frame angle — `count` lobes, spun by the animated clock × `spin`, narrowed by `sharpness`. */
+/**
+ * Soft rays fanning out from the center of a radial frame, turning with the layer's clock.
+ *
+ * Returns a 0–1 field with `count` rays. `spin` is a plain number that scales the clock:
+ * 1 turns counter-clockwise, -1 clockwise, 0 holds still. `sharpness` above 1 narrows the
+ * bright rays, below 1 widens them.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(radialFrame(p('center')), rayLobes({count: p('rays'), spin: -1, sharpness: 4}))
+ * ```
+ * @see softRayLobes, raySpikes, radialFrame
+ */
 export declare function rayLobes(slots: {
     count: ArgSpec;
     spin: number;
     sharpness: ArgSpec;
 }): LightPart;
 /**
- * {@link rayLobes} driven by a designer-facing softness slider (softness inverts into the lobe
- * exponent, so soft rays widen without moving their centres). `spin` scales the animated clock
- * (negative = clockwise).
+ * `rayLobes` with a softness slider instead of a sharpness.
+ *
+ * `softness` 0 gives crisp rays and 1 gives wide soft ones. The rays widen without moving.
+ * `spin` is a plain number scaling the layer's clock: negative turns clockwise.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(radialFrame(p('center')), softRayLobes({count: p('rayCount'), softness: p('softness'), spin: -1}))
+ * ```
+ * @see rayLobes, featherMask
  */
 export declare function softRayLobes(slots: {
     count: ArgSpec;
     softness: ArgSpec;
     spin: number;
 }): LightPart;
-/** Diffraction-style spikes with hard nulls — pass `blades / 2` as `halfCount`; high power thins. */
+/**
+ * Thin star spikes with dark gaps between them, like light through a camera aperture.
+ *
+ * Returns a 0–1 field with twice `halfCount` spikes, so pass half the spike count you want.
+ * `power` from 3 to 8 makes them thinner. The spikes do not turn.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(radialFrame(p('center')), modulate(raySpikes({halfCount: 3, power: 5}), glowPoint({sharpness: 12})))
+ * ```
+ * @see rayLobes, flareStarburst
+ */
 export declare function raySpikes(slots: {
     halfCount: ArgSpec;
     power: ArgSpec;
 }): LightPart;
-/** Three concentric chromatic ring bands (R outside, B inside for positive spread) as an RGB. */
+/**
+ * Three thin colored rings around the center, the rainbow edge of a lens or a halo.
+ *
+ * Returns an RGB, not a field. The red ring sits at `center` + `spread`, green at `center`,
+ * blue at `center` - `spread`, each `width` wide, all in the frame's distance unit. A
+ * positive `spread` puts red outside, as a real lens does.
+ *
+ * @example
+ * ```ts
+ * const rings = withFrame(radialFrame(p('center')), ringBand({center: p('radius'), spread: 0.01, width: 0.02}))(params)
+ * ```
+ * @see flareHalo, glowPoint
+ */
 export declare function ringBand(slots: {
     center: ArgSpec;
     spread: ArgSpec;
     width: ArgSpec;
 }): LightPart;
-/** An isotropic Gaussian falloff over the frame distance: `exp(-(dist² · sharpness))`. */
+/**
+ * A soft glow at the center of a radial frame with no hard edge.
+ *
+ * Returns a 0–1 field, 1 at the center. `sharpness` is one over the radius squared, so a
+ * larger value gives a tighter glow: for a glow that reaches radius `r`, pass `1 / (r * r)`.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(radialFrame(p('center')), glowPoint({sharpness: 8}))
+ * ```
+ * @tip Sharpness is not a radius. Turning it up makes the glow smaller.
+ * @see featherMask, emitterFalloff, glowAt
+ */
 export declare function glowPoint(slots: {
     sharpness: ArgSpec;
 }): LightPart;
-/** The outer fade of a bounded radial light: 1 inside `radius`, fading over the last `feather` fraction. */
+/**
+ * A round mask that is solid inside a radius and fades out at its edge.
+ *
+ * Returns 1 inside, fading to 0 at `radius` (in the frame's distance unit). `feather` is the
+ * fraction of the radius spent fading: 0 is a hard edge, 1 fades all the way from the
+ * center. Multiply it with a pattern in `modulate` to give a light an outer edge.
+ *
+ * @example
+ * ```ts
+ * modulate(rayLobes({count: 12, spin: -1, sharpness: 4}), featherMask({radius: p('radius'), feather: p('feather')}))
+ * ```
+ * @see glowPoint, modulate
+ */
 export declare function featherMask(slots: {
     radius: ArgSpec;
     feather: ArgSpec;
 }): LightPart;
 /**
- * Two seam-free noise layers accumulated into a volumetric ray coverage over the frame,
- * animated on the definition's clock: `density` sets sector frequency, `intensity` ray
- * visibility, `spotty` the spot density along each ray.
+ * Volumetric god rays: shafts of light drifting outward from the center, moving on the
+ * layer's clock.
+ *
+ * Returns a 0–1 coverage. `density` sets how many shafts, `intensity` (0–1) how visible they
+ * are, and `spotty` breaks each shaft into drifting spots along its length. Draw it in
+ * `seamlessRadialFrame`, not `radialFrame`.
+ *
+ * @example
+ * ```ts
+ * coverage: withFrame(seamlessRadialFrame(p('center')), noiseRays({density: p('density'), intensity: p('intensity'), spotty: p('spotty')}))
+ * ```
+ * @see seamlessRadialFrame, coverageOver
  */
 export declare function noiseRays(slots: {
     density: ArgSpec;
@@ -143,36 +306,150 @@ export declare function noiseRays(slots: {
     spotty: ArgSpec;
 }): LightPart;
 /**
- * The slow drift/breathing signal pack of a bleeding light: breath gain in `.x`, streak drift
- * offsets in the rest. `flicker` sets the breathing depth, `seed` re-rolls the pattern.
+ * The slow breathing and drifting signals that keep a light leak alive.
+ *
+ * Call the result with a clock and the params. It returns four numbers: `.x` is a
+ * brightness gain to multiply your light by (1 with `flicker` at 0, breathing between 0.25
+ * and 1.75 at 1), and the rest are the slow drifts `beamBloom` and `beamStreaks` read. Pass
+ * the whole value to them as `drift`. `seed` re-rolls the pattern.
+ *
+ * @example
+ * ```ts
+ * const drift = local(slowDrift({seed: p('seed'), flicker: p('flicker')})(animatedTime(params), params), 'leakDrift')
+ * ```
+ * @see beamBloom, beamStreaks, beamFrame
  */
 export declare function slowDrift(slots: {
     seed: ArgSpec;
     flicker: ArgSpec;
 }): (clock: Expr, params: GpuFragmentParams) => Expr;
-/** The main anisotropic glow pool (`.x`) and its wider shoulder (`.y`) along a beam frame. */
+/**
+ * The soft pool of light at the start of a beam, with a wider faint shoulder around it.
+ *
+ * Call the result with a `beamFrame` value, a `slowDrift` value and the params. It returns
+ * `vec2(main, shoulder)`, two 0–1 fields you usually add together. `spread` is the pool's
+ * size in the frame's unit (aspect-corrected uv), at least 0.05.
+ *
+ * @example
+ * ```ts
+ * const bloom = beamBloom({spread: p('spread')})(frame, drift, params)
+ * const heat = add(mul(bloom.member('x'), 1.25), bloom.member('y'))
+ * ```
+ * @see beamFrame, slowDrift, beamStreaks
+ */
 export declare function beamBloom(slots: {
     spread: ArgSpec;
 }): (frame: Expr, drift: Expr, params: GpuFragmentParams) => Expr;
-/** Drifting parallel streak bands further into the frame along the beam. */
+/**
+ * Two bright bands crossing a beam further along it, slowly drifting, like light bouncing
+ * inside a film camera.
+ *
+ * Call the result with a `beamFrame` value, a `slowDrift` value and the params. It returns
+ * a field scaled by `strength` (0 turns the bands off). `spread` is the same value you gave
+ * `beamBloom`, so the bands sit past the pool.
+ *
+ * @example
+ * ```ts
+ * const streaks = beamStreaks({spread: p('spread'), strength: p('streaks')})(frame, drift, params)
+ * ```
+ * @see beamBloom, slowDrift, streakBand
+ */
 export declare function beamStreaks(slots: {
     spread: ArgSpec;
     strength: ArgSpec;
 }): (frame: Expr, drift: Expr, params: GpuFragmentParams) => Expr;
-/** Hash dither over a heat field to hide ramp banding. */
+/**
+ * Adds a trace of noise to a heat field so long soft ramps do not show bands.
+ *
+ * Pass the summed heat, the pixel's uv and a clock. Use it right before `heatRamp`. This is
+ * for a heat field, not a color: use `compose.dithered` for a finished color.
+ *
+ * @example
+ * ```ts
+ * return heatRamp({hot: p('colorHot'), mid: p('colorMid'), fringe: p('colorFringe')}).taps(dithered(heat, params.ctx.uv, animatedTime(params)), params)
+ * ```
+ * @see heatRamp
+ */
 export declare function dithered(heat: Expr, uv: Expr, clock: Expr): Expr;
 /**
- * An elliptical Gaussian glow over a pre-normalized 2D offset (each axis already divided by its
- * own radius): `exp(-(du² + dv²) · sharpness)`. The core of a bloom, a glare, or a soft pool.
+ * A soft oval glow over an offset you have already scaled, the core of a bloom or a glare.
+ *
+ * Returns a 0–1 field. Divide each axis of the offset by its own radius first: `du` and
+ * `dv` at different radii make the glow oval. `sharpness` larger gives a tighter glow.
+ *
+ * @example
+ * ```ts
+ * const pool = glowSpot(div(dx, p('width')), div(dy, p('height')), 2)
+ * ```
+ * @see glowAt, glowPoint, beamBloom
  */
 export declare function glowSpot(du: Expr, dv: Expr, sharpness: Expr): Expr;
-/** One soft Gaussian band across a 1D coordinate, peaking at `center` with the given `width`. */
+/**
+ * A four-point star of light: a round core with a thin ray along each axis, like a glint
+ * off glitter or a star in a photograph.
+ *
+ * `offset` is the pixel's position relative to the star's centre, as a `vec2`, in whatever
+ * unit you measure the star in (CSS pixels suit small glints). Returns the brightness: 1 at
+ * the centre, falling off along the rays and faster everywhere else. `core` is the core's
+ * sharpness (larger is a smaller dot). `rayLength` and `rayWidth` are falloff rates along and
+ * across each ray (smaller rayLength is a longer ray). `rays` is the rays' brightness
+ * relative to the core.
+ *
+ * @example
+ * ```ts
+ * const glint = starGlint(offset, {core: 0.9, rayLength: 0.45, rayWidth: 1.6, rays: 0.25})
+ * ```
+ * @tip Multiply by a `flashes` blink for a sparkle that comes and goes. Set `reach` to half
+ * the cell size when the glints sit on a `scatterPoints` grid, so long rays never hit a cell edge.
+ * @see glowSpot, raySpikes, flareStarburst
+ */
+export declare function starGlint(offset: Expr, opts: {
+    core: Expr | number;
+    rayLength: Expr | number;
+    rayWidth: Expr | number;
+    rays: Expr | number;
+    /** Optional: the glint fades to nothing by this distance from its centre (measured along the larger axis). */
+    reach?: Expr | number;
+}): Expr;
+/**
+ * One soft band across a single coordinate, peaking at `center`.
+ *
+ * Returns a 0–1 field, 1 at `center`, fading over `width` on each side. `u`, `center` and
+ * `width` share a unit. Multiply or add several for a stack of parallel bands.
+ *
+ * @example
+ * ```ts
+ * const bar = streakBand(params.ctx.uv.member('y'), 0.5, p('width'))
+ * ```
+ * @see rayBands, beamStreaks
+ */
 export declare function streakBand(u: Expr, center: Expr, width: Expr): Expr;
-/** Project a point onto a segment: `vec2(t, distance)` with `t` clamped to [0,1]. */
+/**
+ * Where a pixel falls along a line from `a` to `b`, and how far it is from that line.
+ *
+ * Returns `vec2(t, distance)`. `t` runs 0 at `a` to 1 at `b` and is clamped, so the ends
+ * are rounded. All three points share a unit. Feed both values to `lightBeam`.
+ *
+ * @example
+ * ```ts
+ * const seg = segmentProject(uv, p('start'), p('end'))
+ * ```
+ * @see lightBeam
+ */
 export declare function segmentProject(p: Expr, a: Expr, b: Expr): Expr;
 /**
- * The glow cross-section of a tapered beam: thickness/softness interpolate end-to-end along the
- * segment parameter; returns `vec2(colorT, alpha)`.
+ * The glow of a beam that can be thicker or softer at one end than the other.
+ *
+ * Give it the distance from the line and the position along it from `segmentProject`.
+ * Thickness and softness blend from `start` to `end` along the beam, in the distance unit.
+ * Returns `vec2(colorT, alpha)`: `alpha` is 1 inside the beam and fades to 0 outside, and
+ * `colorT` runs 0 at the core to 1 at the edge so you can shade the two differently.
+ *
+ * @example
+ * ```ts
+ * const beam = lightBeam(seg.member('y'), seg.member('x'), {start: p('startThickness'), end: p('endThickness')}, {start: p('startSoftness'), end: p('endSoftness')})
+ * ```
+ * @see segmentProject
  */
 export declare function lightBeam(dist: Expr, t: Expr, thickness: {
     start: Expr;
@@ -182,8 +459,17 @@ export declare function lightBeam(dist: Expr, t: Expr, thickness: {
     end: Expr;
 }): Expr;
 /**
- * The shared frame of a camera flare: light position, flare axis, master fade (intensity ×
- * edge fade × shimmer), and the pixel's polar coordinates about the light.
+ * The shared frame of a camera lens flare, which every `flare*` part reads.
+ *
+ * `position` is the light's position prop. `intensity` scales the whole flare and
+ * `edgeFade` (0–1) dims it as the light nears the canvas edge. Bind it once with a name and
+ * hand the same value to each part, then close the stack with `flareComposite`.
+ *
+ * @example
+ * ```ts
+ * const flare = local(flareFrame({position: p('lightPosition'), intensity: p('intensity'), edgeFade: p('edgeFade')})(params), 'flare')
+ * ```
+ * @see flareCore, flareGlare, flareHalo, flareStarburst, flareStreak, lensGhost, flareComposite
  */
 export declare function flareFrame(slots: {
     position: PropRef;
@@ -191,56 +477,163 @@ export declare function flareFrame(slots: {
     edgeFade: ArgSpec;
 }): LightValue;
 /**
- * One internal-reflection ghost disc along the flare axis: `disc` = offset/size/bright/hollow,
- * `tint` = r/g/b/gPhase.
+ * One ghost disc of a lens flare, the faint circles that line up across from the light.
+ *
+ * Call the result once per ghost with the flare frame, a `disc` and a `tint`, and sum the
+ * calls with `additive`. `disc` is `[offset, size, brightness, hollow]`: how far along the
+ * axis from the light (scaled by `spread`), radius in aspect-corrected uv, brightness, and
+ * 0–1 for a solid disc to a ring. `tint` is `[r, g, b, phase]`, the color and a shimmer
+ * offset. `chroma` (0–1) adds a rainbow rim. Returns an RGB.
+ *
+ * @example
+ * ```ts
+ * const ghost = lensGhost({intensity: p('ghostIntensity'), spread: p('ghostSpread'), chroma: p('ghostChroma')})
+ * const ghosts = additive(ghost(flare, [0.15, 0.20, 0.30, 0.10], [1.0, 0.95, 0.90, 0.0], params), ghost(flare, [0.30, 0.12, 0.25, 0.65], [1.0, 0.85, 0.55, 2.17], params))
+ * ```
+ * @see flareFrame, additive, flareHalo
  */
 export declare function lensGhost(slots: {
     intensity: ArgSpec;
     spread: ArgSpec;
     chroma: ArgSpec;
 }): (flare: Expr, disc: [number, number, number, number], tint: [number, number, number, number], params: GpuFragmentParams) => Expr;
-/** The chromatic halo ring about the light. */
+/**
+ * The rainbow halo ring of a lens flare, drawn across the canvas from the light.
+ *
+ * Call the result with the flare frame and the params. The ring centers on the point
+ * opposite the light through the canvas center. `radius` is in aspect-corrected uv,
+ * `chroma` (0–1) splits it into colors and `softness` widens it. Returns an RGB.
+ *
+ * @example
+ * ```ts
+ * flareHalo({intensity: p('haloIntensity'), radius: p('haloRadius'), chroma: p('haloChroma'), softness: p('haloSoftness')})(flare, params)
+ * ```
+ * @see flareFrame, ringBand, lensGhost
+ */
 export declare function flareHalo(slots: {
     intensity: ArgSpec;
     radius: ArgSpec;
     chroma: ArgSpec;
     softness: ArgSpec;
 }): (flare: Expr, params: GpuFragmentParams) => Expr;
-/** The diffraction-spike starburst about the light. */
+/**
+ * The star of thin spikes around the light in a lens flare.
+ *
+ * Call the result with the flare frame and the params. `points` is the number of spikes.
+ * They turn slowly with the layer's clock and carry a faint rainbow tint. Returns an RGB.
+ *
+ * @example
+ * ```ts
+ * flareStarburst({intensity: p('starburstIntensity'), points: p('starburstPoints')})(flare, params)
+ * ```
+ * @see flareFrame, raySpikes
+ */
 export declare function flareStarburst(slots: {
     intensity: ArgSpec;
     points: ArgSpec;
 }): (flare: Expr, params: GpuFragmentParams) => Expr;
-/** The anamorphic horizontal streak through the light. */
+/**
+ * The horizontal widescreen streak through the light in a lens flare.
+ *
+ * Call the result with the flare frame and the params. `length` is the streak's reach in
+ * uv. Blue spreads furthest, giving the streak its cyan edges. Returns an RGB.
+ *
+ * @example
+ * ```ts
+ * flareStreak({intensity: p('streakIntensity'), length: p('streakLength')})(flare, params)
+ * ```
+ * @see flareFrame, streakBand
+ */
 export declare function flareStreak(slots: {
     intensity: ArgSpec;
     length: ArgSpec;
 }): (flare: Expr, params: GpuFragmentParams) => Expr;
-/** The broad veiling glare about the light. */
+/**
+ * The broad warm-white wash around the light that lifts contrast near it.
+ *
+ * Call the result with the flare frame and the params. `size` is the wash radius in
+ * aspect-corrected uv. Returns an RGB.
+ *
+ * @example
+ * ```ts
+ * flareGlare({intensity: p('glareIntensity'), size: p('glareSize')})(flare, params)
+ * ```
+ * @see flareFrame, flareCore
+ */
 export declare function flareGlare(slots: {
     intensity: ArgSpec;
     size: ArgSpec;
 }): (flare: Expr, params: GpuFragmentParams) => Expr;
-/** The bright core at the light itself. */
+/**
+ * The bright point at the light itself: a hard pinpoint inside a small soft glow.
+ *
+ * Call the result with the flare frame and the params. Returns an RGB.
+ *
+ * @example
+ * ```ts
+ * flareCore({intensity: p('intensity')})(flare, params)
+ * ```
+ * @see flareFrame, flareGlare
+ */
 export declare function flareCore(slots: {
     intensity: ArgSpec;
 }): (flare: Expr, params: GpuFragmentParams) => Expr;
-/** Finish an additive light stack: scale by the frame's master fade with a luminance-derived alpha. */
+/**
+ * Closes a lens flare: turns the summed flare parts into the color to return from `paint`.
+ *
+ * Pass the `additive` sum of the parts and the flare frame. The frame's intensity, edge fade
+ * and shimmer are applied here, and alpha comes from how bright the flare is.
+ *
+ * @example
+ * ```ts
+ * return flareComposite(additive(ghosts, halo, starburst, streak, glare, core), flare)
+ * ```
+ * @see additive, flareFrame
+ */
 export declare function flareComposite(total: Expr, flare: Expr): Expr;
 /**
- * Quadratic corner-darkening mask about the frame centre, aspect-corrected from the effective
- * viewport. `strength` 0 disables it; `scale` remaps a designer-range slider into mask units.
+ * Darkens the corners of the canvas.
+ *
+ * Returns a field that is 1 at the center and falls toward 0 in the corners, kept round on
+ * any canvas shape. Multiply your color by it. `strength` 0 leaves the image alone and
+ * about 2 takes the corners to black. `scale` multiplies `strength`, for mapping a 0–100
+ * slider onto that range.
+ *
+ * @example
+ * ```ts
+ * const vig = vignetteMask({strength: p('vignette'), scale: 0.025})(params)
+ * return vec4(mul(rgb, vig), 1)
+ * ```
+ * @see featherMask
  */
 export declare function vignetteMask(slots: {
     strength: ArgSpec;
     scale?: number;
 }): LightValue;
-/** Sum additive light contributions: `a + b + c + …` in the given order. */
+/**
+ * Adds lights together, since light from several sources simply sums.
+ *
+ * @example
+ * ```ts
+ * const total = additive(glare, halo, core)
+ * ```
+ * @see modulate, flareComposite
+ */
 export declare function additive(first: Expr, ...rest: Expr[]): Expr;
 /**
- * A slot-bound overexposure ramp (fringe → mid → hot, with chromatic per-channel taps): binds the
- * three ramp color props and yields the RGB of any heat field. The visible "color story" part
- * of a light leak or glow.
+ * The colors of overexposed light, from a dim fringe through a mid tone to a hot core.
+ *
+ * Pass three color props. Call `.taps(heat, params)` on the result to turn a heat field into
+ * RGB: heat 0 is black, the fringe color shows first, the mid color by 0.5, the hot color
+ * above 1, and the light keeps getting brighter up to a heat of 1.6. Each channel reads a
+ * slightly different heat, which gives bright edges their color fringing.
+ *
+ * @example
+ * ```ts
+ * return heatRamp({hot: p('colorHot'), mid: p('colorMid'), fringe: p('colorFringe')}).taps(heat, params)
+ * ```
+ * @tip Run the heat through `dithered` first on long soft ramps.
+ * @see dithered, screenGlow
  */
 export declare function heatRamp(colors: {
     hot: PropRef;
@@ -248,15 +641,26 @@ export declare function heatRamp(colors: {
     fringe: PropRef;
 }): {
     kind: "heatRamp";
-    /** The chromatic RGB of a heat field (three offset ramp taps). */
+    /** The RGB of a heat field through this ramp. */
     taps: (heat: Expr, params: {
         uniforms: Record<string, Expr>;
     }) => Expr;
 };
+/** What `heatRamp` returns: call its `taps(heat, params)` to color a heat field. */
 export type HeatRamp = ReturnType<typeof heatRamp>;
 /**
- * Mix `color` over `background` component-wise (rgb AND alpha) by a coverage field; `hint`
- * names the coverage stage's WGSL local.
+ * Blends from a background color to a light color by a coverage field, as a finished paint.
+ *
+ * `color` and `background` are color props, `coverage` a 0–1 light such as a `withFrame`
+ * result. Both the color and the alpha blend, so a transparent background gives a light that
+ * fades to nothing. Pass a `hint` name when the coverage is expensive. Use `coverageOver`
+ * when you want real layer compositing instead of a plain blend.
+ *
+ * @example
+ * ```ts
+ * paint: coverageMix({color: p('color'), background: p('background'), coverage: withFrame(radialFrame(p('center')), glowPoint({sharpness: 6}), 'glow'), hint: 'glowAlpha'})
+ * ```
+ * @see coverageOver, withFrame
  */
 export declare function coverageMix(slots: {
     color: PropRef;
@@ -264,16 +668,36 @@ export declare function coverageMix(slots: {
     coverage: LightValue;
     hint?: string;
 }): LightValue;
-/** Straight-alpha composite of `color` over `background` by a coverage field (linear RGB). */
+/**
+ * Lays a light color over a background color by a coverage field, like a layer with an
+ * opacity mask, as a finished paint.
+ *
+ * `color` and `background` are color props, `coverage` a 0–1 light. The color's own alpha
+ * counts as opacity, so a half-transparent ray color shows the background through it.
+ *
+ * @example
+ * ```ts
+ * paint: coverageOver({color: p('rayColor'), background: p('backgroundColor'), coverage: withFrame(seamlessRadialFrame(p('center')), noiseRays({density: p('density'), intensity: p('intensity'), spotty: p('spotty')}))})
+ * ```
+ * @see coverageMix, noiseRays
+ */
 export declare function coverageOver(slots: {
     color: PropRef;
     background: PropRef;
     coverage: LightValue;
 }): LightValue;
 /**
- * Screen-composite an emitted glow RGB over the child, exposure-style: screen blend +
- * overexposure push + a slight halation lift; emitted light raises alpha over transparent
- * areas too. The pointwise composition root of a light-bleed filter.
+ * An `effect` that shines emitted light onto the layer inside it, the way light hits film.
+ *
+ * Pass a function that builds the light's RGB from the params. The light is screened over
+ * the child, pushed toward overexposure where it is bright, and shows even over transparent
+ * areas. Build the light with `beamFrame`, `beamBloom`, `beamStreaks` and `heatRamp`.
+ *
+ * @example
+ * ```ts
+ * effect: screenGlow((params) => heatRamp({hot: p('colorHot'), mid: p('colorMid'), fringe: p('colorFringe')}).taps(heat, params))
+ * ```
+ * @see heatRamp, beamFrame
  */
 export declare function screenGlow(glow: (params: FilterParams) => Expr): PointwiseEffect;
 //# sourceMappingURL=light.d.ts.map