shaders 3.2.475 → 4.0.0

package/dist/core/std/effects/blurs.d.ts

@@ -5,129 +5,375 @@ import { ArgSpec } from '../invoke';
 import { GatherEffect } from '../types';
 import { PropRef } from '../values';
 
-/** The sampling stage: produce the initial color from the child RTT. */
+/**
+ * The first stage of a stacked effect: reads the child as a texture and returns the starting
+ * color at this pixel.
+ *
+ * Pass one to `gatherStack` as its first argument. The overlay stages then edit its result in order.
+ * @see gatherStack, OverlayStage, childTap
+ */
 export type SampleStage = (params: RttFilterParams) => Expr;
-/** One post-sample overlay stage: color in → color out. */
+/**
+ * One editing stage of a stacked effect: takes the color so far and returns the edited color.
+ *
+ * Stages run in the order you list them in `gatherStack`.
+ * @see gatherStack, SampleStage
+ */
 export type OverlayStage = (color: Expr, params: RttFilterParams) => Expr;
-/** Compose a gather effect from a sampling stage and an ordered list of overlays. */
+/**
+ * Assemble an effect from one sampling stage and an ordered list of overlay stages.
+ *
+ * The child renders to a texture, the sampling stage reads it, and each overlay edits the result
+ * in turn. Put the result in a filter's `effect:` field. Pass `{resultAlpha: 'straight'}` only
+ * when the stack already returns straight (not premultiplied) alpha, as `crispTap` and
+ * `refractedTaps` do.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(rgbSplit({amount: p('colorShift')}), [scanlines({frequency: p('lines'), intensity: 0.3}), opaque()])
+ * ```
+ * @tip An empty overlay list is fine: `gatherStack(stage, [])` wraps a lone sampling stage.
+ * @see SampleStage, OverlayStage, GatherFrame
+ */
 export declare function gatherStack(sample: SampleStage, overlays: OverlayStage[], opts?: {
     resultAlpha?: 'premultiplied' | 'straight';
 }): GatherEffect;
 /**
- * A shared geometry frame: one Expr (usually an `asLocal` struct) that several stages of a
- * recipe read. The producer is memoized per composition, so every stage sees the same local.
+ * A geometry that several stages of one effect share: a warped coordinate, a surface normal, a
+ * coverage mask.
+ *
+ * Make one with a frame word (`sphereFrame`, `glitchFrame`, `fluteFrame`, `peelFrame`), keep it
+ * in a module constant, and hand that same frame to every stage. It is computed once per pixel
+ * however many stages read it.
+ * @see sphereFrame, glitchFrame, fluteFrame, peelFrame
  */
 export type GatherFrame = (params: RttFilterParams) => Expr;
 /**
- * RGB split: sample the child at ±`amount·0.002` horizontal offsets and take red from the +tap,
- * green from the centre, blue from the −tap.
+ * The child with its red and blue pulled a little to either side, like a misaligned CRT.
+ *
+ * `amount` is the shift; 1 moves red and blue each by 0.002 of the canvas width, 0–10 is the
+ * usual range. Returns a three-channel color, so finish the stack with `opaque`.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(rgbSplit({amount: p('colorShift')}), [opaque()])
+ * ```
+ * @see glitchRgbSplit, scanlines, phosphorMask, opaque
  */
 export declare function rgbSplit(opts: {
     amount: ArgSpec;
 }): SampleStage;
-/** VHS tape-warp UVs: vec4(lumaUV.xy, chromaUV.zw) from the wobble/jitter tape geometry, driven by
- *  the global clock × speed. Feed into {@link chromaSmearTaps}. */
+/**
+ * The wobbling, jittering coordinates of a worn VHS tape, to feed into `chromaSmearTaps`.
+ *
+ * `wobble` (0–5) is the tape damage: waves, creases and head-switching noise that burst on and
+ * off over time. `jitter` (0–1) is fine per-scanline noise. `speed` scales the global clock,
+ * so the definition needs no `animatedTime`.
+ *
+ * @example
+ * ```ts
+ * chromaSmearTaps({warp: tapeWarp({wobble: p('wobble'), jitter: p('scanlineNoise'), speed: p('speed')}), smear: p('smear')})
+ * ```
+ * @see chromaSmearTaps, beatPulse
+ */
 export declare function tapeWarp(opts: {
     wobble: ArgSpec;
     jitter: ArgSpec;
     speed: ArgSpec;
 }): (params: RttFilterParams) => Expr;
 /**
- * Chroma smear: one sharp luma tap + 5 chroma taps trailing by `smear·0.0075` each, recombined
- * through YIQ (sharp Y, smeared I/Q). Alpha comes from the luma tap.
+ * The child sampled like a VHS deck: brightness stays sharp while color bleeds sideways.
+ *
+ * `warp` is the coordinate set from `tapeWarp`. `smear` sets how far color trails; positive
+ * trails it to the right, negative to the left, −2 to 2 is the usual range. Alpha comes from the
+ * sharp tap.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(chromaSmearTaps({warp: tapeWarp({wobble: p('wobble'), jitter: p('noise'), speed: p('speed')}), smear: p('smear')}), [beatPulse({wobble: p('wobble'), speed: p('speed')})])
+ * ```
+ * @see tapeWarp, beatPulse, rgbSplit
  */
 export declare function chromaSmearTaps(opts: {
     warp: (params: RttFilterParams) => Expr;
     smear: ArgSpec;
 }): SampleStage;
-/** Brightness/contrast adjustment around mid-grey. */
+/**
+ * The brightest color in a small ring around a point: the layer grown outward, so a spot
+ * just outside a bright area still reads as bright.
+ *
+ * `read` samples the layer at a uv and returns straight color (pass `params.sampleStraight`).
+ * `center` is the uv to look around; `radius` is the ring's radius per axis in uv, as a
+ * `vec2` (divide a pixel radius by the viewport size). `taps` points sit evenly round the
+ * ring starting at `angle` degrees, plus the centre itself. Returns the brightest of them as
+ * `color` (straight) and its brightness as `luma` (Rec.709 luminance times alpha).
+ *
+ * @example
+ * ```ts
+ * const {color, luma} = brightestNear(params.sampleStraight, pointUV, {radius: div(p, viewport), taps: 4, angle: 45})
+ * ```
+ * @tip Thin bright details smaller than the gap between taps can slip through; more taps
+ * close the gaps at one sample each.
+ * @see gatherStack
+ */
+export declare function brightestNear(read: (uv: Expr) => Expr, center: Expr, opts: {
+    radius: Expr;
+    taps: number;
+    angle?: number;
+}): {
+    color: Expr;
+    luma: Expr;
+};
+/**
+ * Brightness and contrast, pivoting around mid-grey.
+ *
+ * 1 leaves both unchanged; 0.5–2 is the usual range. Works on the three-channel color of a
+ * stack begun with `rgbSplit`.
+ *
+ * @example
+ * ```ts
+ * adjust({brightness: p('brightness'), contrast: p('contrast')})
+ * ```
+ * @see rgbSplit, scanlines, opaque
+ */
 export declare function adjust(opts: {
     brightness: ArgSpec;
     contrast: ArgSpec;
 }): OverlayStage;
-/** Sinusoidal scanlines over uv.y. */
+/**
+ * Horizontal scanlines darkening the child in a smooth wave.
+ *
+ * `frequency` is the number of lines from top to bottom (100–800). `intensity` (0–1) is how
+ * dark the troughs get. Works on the three-channel color of a stack begun with `rgbSplit`.
+ *
+ * @example
+ * ```ts
+ * scanlines({frequency: p('scanlineFrequency'), intensity: p('scanlineIntensity')})
+ * ```
+ * @see distortedScanlines, phosphorMask, vignetteOverlay
+ */
 export declare function scanlines(opts: {
     frequency: ArgSpec;
     intensity: ArgSpec;
 }): OverlayStage;
-/** Subtle RGB phosphor mask; `pitch` is the phosphor cell size. */
+/**
+ * A faint red, green and blue phosphor stripe pattern across the child.
+ *
+ * `pitch` sets how many stripes fit across the canvas, about half of `pitch`; 8–128 is the usual
+ * range. Works on the three-channel color of a stack begun with `rgbSplit`.
+ *
+ * @example
+ * ```ts
+ * phosphorMask({pitch: p('pixelSize')})
+ * ```
+ * @see scanlines, rgbSplit
+ */
 export declare function phosphorMask(opts: {
     pitch: ArgSpec;
 }): OverlayStage;
-/** Aspect-corrected circular vignette darkening. */
+/**
+ * Darkens the child toward its corners.
+ *
+ * `radius` (0–1) is how far the darkening reaches inward, 0 for the edges only and 1 for all the
+ * way to the centre. `intensity` (0–1) blends it in. Round on any canvas shape. Works on the
+ * three-channel color of a stack begun with `rgbSplit`.
+ *
+ * @example
+ * ```ts
+ * vignetteOverlay({radius: p('vignetteRadius'), intensity: p('vignetteIntensity')})
+ * ```
+ * @see scanlines, opaque
+ */
 export declare function vignetteOverlay(opts: {
     radius: ArgSpec;
     intensity: ArgSpec;
 }): OverlayStage;
-/** Finish a vec3 color stack as an opaque vec4 (alpha 1). */
+/**
+ * Closes a three-channel stack as a solid color with alpha 1.
+ *
+ * Put it last after `rgbSplit`, `adjust`, `scanlines`, `phosphorMask` or `vignetteOverlay`,
+ * which work on color only and drop the child's alpha.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(rgbSplit({amount: 1}), [scanlines({frequency: 200, intensity: 0.3}), opaque()])
+ * ```
+ * @see rgbSplit, gatherStack
+ */
 export declare function opaque(): OverlayStage;
-/** AC beat: a very subtle brightness pulse from the global clock, clamped to [0,1]. */
+/**
+ * A faint brightness throb, like the mains hum of an old television.
+ *
+ * `wobble` scales the throb (0 turns it off). `speed` scales the global clock. Works on the
+ * four-channel color of a stack begun with `chromaSmearTaps`.
+ *
+ * @example
+ * ```ts
+ * beatPulse({wobble: p('wobble'), speed: p('speed')})
+ * ```
+ * @see chromaSmearTaps, tapeWarp
+ */
 export declare function beatPulse(opts: {
     wobble: ArgSpec;
     speed: ArgSpec;
 }): OverlayStage;
-/** A motion-blur tap trajectory: the path kind plus the prop that anchors it. */
+/**
+ * The path a motion blur smears along: its kind plus the prop that anchors it.
+ *
+ * Make one with `blurPath.linear`, `blurPath.orbit` or `blurPath.zoom` and pass it to `motionBlur`.
+ * @see blurPath, motionBlur
+ */
 export interface BlurPathSpec {
     readonly kind: motionBlurKit.MotionBlurPathKind;
     readonly focus: PropRef;
 }
-/** The tap trajectories {@link motionBlur} can follow. */
+/**
+ * The three paths `motionBlur` can smear along.
+ *
+ * @example
+ * ```ts
+ * effect: motionBlur({path: blurPath.zoom(p('center')), amount: p('intensity')})
+ * ```
+ * @see motionBlur
+ */
 export declare const blurPath: {
-    /** Straight-line smear along a fixed direction (an angle prop, in degrees). */
+    /**
+     * A straight streak along an angle prop, in degrees (0 points right, 90 points down).
+     * @example
+     * ```ts
+     * effect: motionBlur({path: blurPath.linear(p('angle')), amount: p('intensity')})
+     * ```
+     * @see motionBlur
+     */
     linear: (angle: PropRef) => BlurPathSpec;
-    /** Arc smear rotating around a center point (a position prop). */
+    /**
+     * An arc streak rotating around a center prop (a position in uv).
+     * @example
+     * ```ts
+     * effect: motionBlur({path: blurPath.orbit(p('center')), amount: p('intensity')})
+     * ```
+     * @see motionBlur
+     */
     orbit: (center: PropRef) => BlurPathSpec;
-    /** Radial smear streaking outward from a center point (a position prop). */
+    /**
+     * A radial streak rushing outward from a center prop (a position in uv).
+     * @example
+     * ```ts
+     * effect: motionBlur({path: blurPath.zoom(p('center')), amount: p('intensity')})
+     * ```
+     * @see motionBlur
+     */
     zoom: (center: PropRef) => BlurPathSpec;
 };
 /**
- * Motion blur: 32 Gaussian-weighted samples of the child gathered along a tap trajectory —
- * `blurPath.linear` (directional), `blurPath.orbit` (rotational), or `blurPath.zoom` (radial).
+ * Smears the child along a path: a straight streak, an arc around a point, or a zoom out of a point.
+ *
+ * `amount` is a 0–100 intensity. A linear streak spans about twice `amount` in pixels; at 100 an
+ * orbit sweeps about 29 degrees and a zoom pulls in from twice the distance to its center.
+ *
+ * @example
+ * ```ts
+ * effect: motionBlur({path: blurPath.linear(p('angle')), amount: p('intensity')})
+ * ```
+ * @tip Samples past the canvas edge repeat the border color. Wrap the layer in a larger group if the smear must fade out instead.
+ * @see blurPath, gaussianBlur, scatter
  */
 export declare function motionBlur(opts: {
     path: BlurPathSpec;
     amount: ArgSpec;
 }): GatherEffect;
 /**
- * Scatter: displace every pixel by a per-pixel random offset of up to `amount` pixels — a
- * grain-like diffusion, not a Gaussian blur. `edges` binds a structural edge-mode prop
- * ('stretch' | 'transparent' | 'mirror' | 'wrap').
+ * Scatters every pixel of the child by a random offset: a grainy diffusion, not a smooth blur.
+ *
+ * `amount` is the largest offset in pixels. `edges` is a prop with `transform: transformEdges`
+ * and `compileTime: true` ('stretch' | 'transparent' | 'mirror' | 'wrap') that says what to read
+ * where an offset lands outside the canvas.
+ *
+ * @example
+ * ```ts
+ * effect: scatter({amount: p('intensity'), edges: p('edges')})
+ * ```
+ * @see gaussianBlur, motionBlur
  */
 export declare function scatter(opts: {
     amount: ArgSpec;
     edges: PropRef;
 }): GatherEffect;
 /**
- * Sharpen: a 5-tap unsharp-mask convolution — centre × (1 + 4·amount) minus the four orthogonal
- * one-pixel neighbours × amount. At `amount` 0 the kernel is the identity.
+ * Sharpens the child by boosting the contrast between each pixel and its neighbours.
+ *
+ * `amount` 0 leaves the child unchanged; 0–5 is the usual range. Alpha is untouched.
+ *
+ * @example
+ * ```ts
+ * effect: sharpen(p('sharpness'))
+ * ```
+ * @tip Declare `identityWhen: isZero('sharpness')` and `recompile: crosses(0)` on the prop so 0 costs nothing.
+ * @see gaussianBlur, scatter
  */
 export declare function sharpen(amount: ArgSpec): GatherEffect;
 /**
- * Pixelate: quantise the child to a grid of `scale` cells along the longest edge, sampling each
- * cell once, and cut each cell to a rounded rectangle via `gap` (spacing) and `roundness`
- * (0 = square, 1 = circle) — the cut is an alpha mask, not a coordinate bend.
+ * Turns the child into a grid of flat cells, each showing one color.
+ *
+ * `scale` is the number of cells along the canvas's longer edge (1–200; more cells means smaller
+ * pixels). `gap` (0–1) is the transparent space between cells as a fraction of a cell.
+ * `roundness` (0–1) rounds each cell from a square to a circle.
+ *
+ * @example
+ * ```ts
+ * effect: pixelate({scale: p('scale'), gap: p('gap'), roundness: p('roundness')})
+ * ```
+ * @see scatter, sharpen
  */
 export declare function pixelate(opts: {
     scale: ArgSpec;
     gap: ArgSpec;
     roundness: ArgSpec;
 }): GatherEffect;
-/** Sphere-bulge geometry: bulged UV + boundary coverage + surface normal. */
+/**
+ * The geometry of a sphere bulging out of the canvas: where each pixel reads the child from,
+ * where the sphere ends, and which way its surface faces.
+ *
+ * `center` is a position in uv. `radius` 1 is half the canvas height. `depth` is how far it bulges
+ * toward the viewer, 0 for flat and up to about 3. Feed the frame to `crispTap` and `rimLit`.
+ *
+ * @example
+ * ```ts
+ * const sphere = sphereFrame({center: p('center'), radius: p('radius'), depth: p('depth')})
+ * ```
+ * @see crispTap, rimLit, GatherFrame
+ */
 export declare function sphereFrame(opts: {
     center: ArgSpec;
     radius: ArgSpec;
     depth: ArgSpec;
 }): GatherFrame;
 /**
- * One Catmull-Rom tap at the frame's warped UV, unpremultiplied. Catmull-Rom, not bilinear: a
- * magnifying warp blows up its centre, and one bilinear tap turns any hard edge underneath
- * (text, a logo) into visible facets.
+ * One clean sample of the child at a frame's warped coordinate.
+ *
+ * Use it under a warp that magnifies: hard edges in the child (text, a logo) stay smooth instead
+ * of breaking into facets. Returns straight alpha, so close the stack with
+ * `{resultAlpha: 'straight'}`.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(crispTap(sphere), [rimLit(sphere, {position: p('light'), intensity: 0.5, softness: 0.5, color: p('lightColor')})], {resultAlpha: 'straight'})
+ * ```
+ * @see sphereFrame, rimLit, childTap
  */
 export declare function crispTap(frame: GatherFrame): SampleStage;
 /**
- * Directional fresnel rim over the frame's surface normal — the tinted rim is ADDED and the
- * alpha gated by the frame's boundary coverage. Added color is what a uv+mask analytic fold
- * can't carry, so a recipe with this stage stays on the RTT fragment path.
+ * A tinted rim of light around the edge of a bulged surface, added on top of the child's color.
+ *
+ * `position` is where the light sits, in uv. `intensity` (0–1) is its strength, 0 for off.
+ * `softness` (0–1) runs from a hard edge to a soft glow. `color` is a color prop. Outside the
+ * frame's surface the result is transparent.
+ *
+ * @example
+ * ```ts
+ * rimLit(sphere, {position: p('lightPosition'), intensity: p('lightIntensity'), softness: p('lightSoftness'), color: p('lightColor')})
+ * ```
+ * @see sphereFrame, crispTap, fluteHighlight
  */
 export declare function rimLit(frame: GatherFrame, opts: {
     position: ArgSpec;
@@ -136,9 +382,19 @@ export declare function rimLit(frame: GatherFrame, opts: {
     color: PropRef;
 }): OverlayStage;
 /**
- * The shared glitch geometry: burst pulse, jitter bands, block shifts, and mirror flips — its
- * burst/band hashes feed the split, fills, and scanlines. Animated by the GLOBAL clock scaled
- * by `speed` (not a per-node animated time).
+ * The shared geometry of a digital glitch: when bursts fire, which horizontal bands jitter, and
+ * which blocks shift or flip.
+ *
+ * `intensity` (0–1) sets both the strength and how often bursts happen. `speed` scales the global
+ * clock, so no `animatedTime` is needed. `blockDensity` is the base number of bands (2–50).
+ * `mirrorAmount` (0–1) is the chance a block shows flipped content. Keep the frame in a module
+ * constant and pass it to `glitchRgbSplit`, `colorBarFills` and `distortedScanlines`.
+ *
+ * @example
+ * ```ts
+ * const glitch = glitchFrame({intensity: p('intensity'), speed: p('speed'), blockDensity: p('blockDensity'), mirrorAmount: p('mirrorAmount')})
+ * ```
+ * @see glitchRgbSplit, colorBarFills, distortedScanlines, GatherFrame
  */
 export declare function glitchFrame(opts: {
     intensity: ArgSpec;
@@ -147,21 +403,60 @@ export declare function glitchFrame(opts: {
     mirrorAmount: ArgSpec;
 }): GatherFrame;
 /**
- * RGB-split sampling around the frame's mirrored coordinate. Alpha comes from the centred green
- * tap, so a transparent child stays transparent through the glitch.
+ * The child sampled through a glitch frame, with red and blue pulled apart inside the active bands.
+ *
+ * `shift` is the split distance, 0–20. A transparent child stays transparent through the glitch.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(glitchRgbSplit(glitch, {shift: p('rgbShift')}), [colorBarFills(glitch, {intensity: 0.2})])
+ * ```
+ * @see glitchFrame, colorBarFills, rgbSplit
  */
 export declare function glitchRgbSplit(frame: GatherFrame, opts: {
     shift: ArgSpec;
 }): SampleStage;
-/** Vivid color-bar fills in the frame's active glitch blocks. */
+/**
+ * Neon color bars filling the blocks a glitch frame currently has active.
+ *
+ * `intensity` (0–1) is how strongly the bars show. They respect the child's alpha.
+ *
+ * @example
+ * ```ts
+ * colorBarFills(glitch, {intensity: p('colorBarIntensity')})
+ * ```
+ * @see glitchFrame, glitchRgbSplit, distortedScanlines
+ */
 export declare function colorBarFills(frame: GatherFrame, opts: {
     intensity: ArgSpec;
 }): OverlayStage;
-/** CRT-style scanlines confined to the frame's distorted regions. */
+/**
+ * CRT-style scanlines that appear only where a glitch frame is currently distorting.
+ *
+ * `intensity` (0–1) is how visible they are.
+ *
+ * @example
+ * ```ts
+ * distortedScanlines(glitch, {intensity: p('scanlineIntensity')})
+ * ```
+ * @see glitchFrame, scanlines
+ */
 export declare function distortedScanlines(frame: GatherFrame, opts: {
     intensity: ArgSpec;
 }): OverlayStage;
-/** The two halves a compute-backed blur contributes to a custom-tier definition. */
+/**
+ * The two halves a heavy blur adds to a definition: a pass that blurs the child ahead of time,
+ * and the fragment that reads it.
+ *
+ * Spread the whole object into a definition that declares `species: 'custom'`,
+ * `requiresRTT: true` and `requiresChild: true`.
+ *
+ * @example
+ * ```ts
+ * ...gaussianBlur({intensity: p('intensity')})
+ * ```
+ * @see gaussianBlur, channelBlur, progressiveBlur, tiltShift, bloom
+ */
 export interface ComputeBackedEffect {
     compute: GpuComputeNode;
     gpu: {
@@ -169,18 +464,33 @@ export interface ComputeBackedEffect {
     };
 }
 /**
- * Gaussian blur: a 2-pass separable Gaussian at fixed compute resolution (decoupled from canvas).
- * A static/mouse/auto intensity runs the fixed-kernel path with a live per-frame radius read; an
- * intensity bound to a map fills a per-pixel radius map from the map source and runs the variable
- * Gaussian. color comes from the blurred buffer, alpha from the sharp child.
+ * A soft, even blur of the child.
+ *
+ * `intensity` is a prop from 0 to about 200; 100 is a blur radius of about 36 pixels. Bind the
+ * prop to a map to vary the blur across the canvas. Only color blurs; the child's alpha stays
+ * sharp, so soft edges need a group or mask around the layer.
+ *
+ * @example
+ * ```ts
+ * ...gaussianBlur({intensity: p('intensity')})
+ * ```
+ * @tip The blur runs at a fixed working resolution, so its cost does not grow with the canvas.
+ * @see channelBlur, progressiveBlur, tiltShift, bloom, motionBlur
  */
 export declare function gaussianBlur(opts: {
     intensity: PropRef;
 }): ComputeBackedEffect;
 /**
- * Channel blur: one fixed Gaussian at the MAX per-channel radius, with each channel mixed between
- * the sharp source and the blurred buffer by `channelRadius / maxRadius` — the max-intensity
- * channel takes the full blur, a zero channel stays exactly sharp.
+ * Blurs red, green and blue by separate amounts, for a soft chromatic fringe.
+ *
+ * Each of `red`, `green` and `blue` is a prop from 0 to 100; 100 is a radius of about 10 pixels.
+ * A channel at 0 stays exactly sharp.
+ *
+ * @example
+ * ```ts
+ * ...channelBlur({red: p('redIntensity'), green: p('greenIntensity'), blue: p('blueIntensity')})
+ * ```
+ * @see gaussianBlur, rgbSplit
  */
 export declare function channelBlur(opts: {
     red: PropRef;
@@ -188,9 +498,18 @@ export declare function channelBlur(opts: {
     blue: PropRef;
 }): ComputeBackedEffect;
 /**
- * Progressive blur: a variable-radius Gaussian whose per-pixel radius ramps directionally from
- * `center` along `angle` over `falloff`, up to the intensity's max radius. A map-driven intensity
- * samples the per-pixel max radius from the map source instead.
+ * A blur that ramps from sharp to full strength in one direction across the child.
+ *
+ * The ramp starts at `center` (a position in uv) and runs along `angle` (degrees, 0 points
+ * right), reaching full blur `falloff` (0–1, in uv) past the center. `intensity` (0–100) is the
+ * blur at the far end; 100 is a radius of about 36 pixels. Bind `intensity` to a map to vary the
+ * ceiling per pixel. Alpha stays sharp.
+ *
+ * @example
+ * ```ts
+ * ...progressiveBlur({intensity: p('intensity'), angle: p('angle'), center: p('center'), falloff: p('falloff')})
+ * ```
+ * @see tiltShift, gaussianBlur
  */
 export declare function progressiveBlur(opts: {
     intensity: PropRef;
@@ -199,10 +518,17 @@ export declare function progressiveBlur(opts: {
     falloff: PropRef;
 }): ComputeBackedEffect;
 /**
- * Tilt shift: a variable-radius Gaussian whose per-pixel radius ramps with perpendicular distance
- * from a focus line (halfKernel 14 — the ~36px max radius keeps tap spacing under the banding
- * threshold with ~40% fewer taps). The fragment re-derives the same blur amount to mix the
- * canvas-res sharp source against the compute-res blurred buffer, so in-focus pixels stay crisp.
+ * Keeps a band of the child in focus and blurs everything beyond it, like a tilt-shift lens.
+ *
+ * The band runs through `center` (a position in uv) at `angle` (degrees, 0 is horizontal) and
+ * is `width` wide (0–1, in uv). Beyond it the blur ramps to full strength over `falloff` (0–1).
+ * `intensity` (0–100) is the blur at the far edges. Pixels inside the band stay pixel-sharp.
+ *
+ * @example
+ * ```ts
+ * ...tiltShift({intensity: p('intensity'), width: p('width'), falloff: p('falloff'), angle: p('angle'), center: p('center')})
+ * ```
+ * @see progressiveBlur, gaussianBlur, bokehDefocus
  */
 export declare function tiltShift(opts: {
     intensity: PropRef;
@@ -212,32 +538,82 @@ export declare function tiltShift(opts: {
     center: PropRef;
 }): ComputeBackedEffect;
 /**
- * Bloom (Glow): bright-extract the child above `threshold` at aspect-aware compute resolution,
- * blur the extract by `size` (per-pixel from the map source when size carries a map driver), and
- * composite `original + bloom × intensity` with the halo allowed to extend past the child's alpha.
- * A scalar size of 0 skips compute entirely (pair it with `recompile: crosses(0)` on the size prop).
+ * A glow: the child's bright parts spread into a soft halo that adds back on top.
+ *
+ * Pixels brighter than `threshold` (0–1) glow. `size` is the halo's spread in pixels (clean up
+ * to about 72). `intensity` (0–50) is how bright the halo is. The halo reaches past the child's
+ * alpha, so a glowing shape lights up transparent space around it. At size 0 nothing runs; give
+ * the size prop `recompile: crosses(0)`.
+ *
+ * @example
+ * ```ts
+ * ...bloom({intensity: p('intensity'), threshold: p('threshold'), size: p('size')})
+ * ```
+ * @see screenedBloom, gaussianBlur, bokehDefocus
  */
 export declare function bloom(opts: {
     intensity: PropRef;
     threshold: PropRef;
     size: PropRef;
 }): ComputeBackedEffect;
-/** The plain centre tap of the child RTT (premultiplied). */
+/**
+ * The child's own color at this pixel, unchanged.
+ *
+ * The sampling stage for an effect that only adds something around the child, like a shadow.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(childTap(), [shadowComposite({coverage, color: p('color'), intensity: p('intensity'), cutout: p('cutout')})])
+ * ```
+ * @see shadowComposite, crispTap
+ */
 export declare function childTap(): SampleStage;
-/** The compass-angle shadow displacement: where to read the child's silhouette from. */
+/**
+ * The coordinate a shadow reads the child's silhouette from: `distance` away in the compass
+ * direction `angle`.
+ *
+ * `angle` is in degrees, 0 up, 90 right, 180 down. `distance` (0–1) is a fraction of the canvas
+ * height and covers the same number of pixels in either axis. Pass the result as the `at` of
+ * `silhouetteCoverage`.
+ *
+ * @example
+ * ```ts
+ * silhouetteCoverage({at: shadowOffset({angle: p('angle'), distance: p('distance')}), blur: p('blur')})
+ * ```
+ * @see silhouetteCoverage, shadowComposite
+ */
 export declare function shadowOffset(opts: {
     angle: ArgSpec;
     distance: ArgSpec;
 }): (params: RttFilterParams) => Expr;
-/** Two-pass separable Gaussian over the child's alpha silhouette, read at the `at` coordinate. */
+/**
+ * A soft copy of the child's alpha silhouette: a number per pixel from 0 to 1.
+ *
+ * `at` is where to read the silhouette from, usually `shadowOffset`. `blur` is the softness as a
+ * radius in pixels (0–20). Feed it to `shadowComposite` as the `coverage`.
+ *
+ * @example
+ * ```ts
+ * silhouetteCoverage({at: shadowOffset({angle: 135, distance: 0.1}), blur: p('blur')})
+ * ```
+ * @see shadowOffset, shadowComposite
+ */
 export declare function silhouetteCoverage(opts: {
     at: (params: RttFilterParams) => Expr;
     blur: ArgSpec;
 }): (params: RttFilterParams) => Expr;
 /**
- * Tint the coverage `color` × `intensity` and composite the shadow behind the child — or, with
- * `cutout` (a structural boolean prop), show only the shadow with the child's silhouette
- * punched out.
+ * A tinted shadow behind the child.
+ *
+ * `coverage` is the soft silhouette from `silhouetteCoverage`, tinted with `color` (a color
+ * prop) at `intensity` (0–1) and placed under the child. `cutout` is a boolean prop with
+ * `compileTime: true`; when true only the shadow shows, with the child's shape punched out of it.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(childTap(), [shadowComposite({coverage: silhouetteCoverage({at: shadowOffset({angle: p('angle'), distance: p('distance')}), blur: p('blur')}), color: p('color'), intensity: p('intensity'), cutout: p('cutout')})])
+ * ```
+ * @see childTap, shadowOffset, silhouetteCoverage
  */
 export declare function shadowComposite(opts: {
     coverage: (params: RttFilterParams) => Expr;
@@ -246,10 +622,23 @@ export declare function shadowComposite(opts: {
     cutout: PropRef;
 }): OverlayStage;
 /**
- * Fluted-glass geometry: refracted UV + chromatic offset + flute slope. `shape` binds a
- * compile-time prop baking the slope-exponent endpoints + waves flag. The flute pattern drifts
- * by the definition's animated clock (declare `animatedTime: {speed: 'speed'}`), negated so
- * positive speed drifts visually right at angle 0.
+ * The geometry of fluted (reeded) glass over the child: where each pixel reads through the
+ * glass, how far its colors split, and the slope of the flute at that point.
+ *
+ * `shape` is a `compileTime` prop whose transform maps 'bars', 'rounded' and 'waves' to 0, 1
+ * and 2. `angle` is in degrees, 0 for vertical flutes. `frequency` is the number of flutes
+ * across the longer edge (1–20). `softness` (0–1) eases each flute from flat-with-sharp-seams to
+ * a gentle curve. `waveAmplitude` and `waveFrequency` shape the waves variant only.
+ * `refraction` (0–4) is how hard each flute bends the child. `aberration` (0–1) is the color
+ * split at the seams. The pattern drifts on the layer's clock, so declare
+ * `animatedTime: {speed: 'speed'}`. Keep the frame in a module constant and pass it to
+ * `refractedTaps` and `fluteHighlight`.
+ *
+ * @example
+ * ```ts
+ * const flute = fluteFrame({shape: p('shape'), angle: p('angle'), frequency: p('frequency'), softness: p('softness'), waveAmplitude: p('waveAmplitude'), waveFrequency: p('waveFrequency'), refraction: p('refraction'), aberration: p('aberration')})
+ * ```
+ * @see refractedTaps, fluteHighlight, GatherFrame
  */
 export declare function fluteFrame(opts: {
     shape: PropRef;
@@ -262,18 +651,35 @@ export declare function fluteFrame(opts: {
     aberration: ArgSpec;
 }): GatherFrame;
 /**
- * The refracted tap(s) at the frame's UV, edge-clipped and unpremultiplied. `edges` binds the
- * compile-time sampling branch; `aberration` is a uniform whose on/off crossing is structural —
- * one tap vs a 3-tap chromatic split along the frame's offset (pair it with a crosses-0
- * recompile rule).
+ * The child seen through a flute frame, with edge handling and a color split when `aberration`
+ * is above 0.
+ *
+ * `edges` is a prop with `transform: transformEdges` and `compileTime: true`. `aberration` is
+ * the same prop the frame uses; give it a recompile rule that fires when it crosses 0. Returns
+ * straight alpha, so close the stack with `{resultAlpha: 'straight'}`.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(refractedTaps(flute, {aberration: p('aberration'), edges: p('edges')}), [fluteHighlight(flute, {lightAngle: 30, highlight: 0.2, softness: 0.3, color: p('highlightColor')})], {resultAlpha: 'straight'})
+ * ```
+ * @see fluteFrame, fluteHighlight, crispTap
  */
 export declare function refractedTaps(frame: GatherFrame, opts: {
     aberration: PropRef;
     edges: PropRef;
 }): SampleStage;
 /**
- * Blinn specular over the frame's flute slope, tinted and added on top — weighted by alpha so
- * transparent regions pick up no phantom highlight.
+ * A specular highlight running along each flute, added on top of the child's color.
+ *
+ * `lightAngle` is the light's direction in degrees, 0 head-on and 90 grazing (−90 to 90).
+ * `highlight` (0–2) is its strength. `softness` (0–1) spreads the peak from pin-tight to a
+ * broad sheen. `color` is a color prop. Transparent parts of the child pick up no highlight.
+ *
+ * @example
+ * ```ts
+ * fluteHighlight(flute, {lightAngle: p('lightAngle'), highlight: p('highlight'), softness: p('highlightSoftness'), color: p('highlightColor')})
+ * ```
+ * @see fluteFrame, refractedTaps, rimLit
  */
 export declare function fluteHighlight(frame: GatherFrame, opts: {
     lightAngle: ArgSpec;
@@ -281,41 +687,106 @@ export declare function fluteHighlight(frame: GatherFrame, opts: {
     softness: ArgSpec;
     color: PropRef;
 }): OverlayStage;
-/** A scalar shading term of a peel recipe, read against the peel frame. */
+/**
+ * One shading term of a page peel: a number per pixel read against the peel frame.
+ *
+ * `curlShading`, `curlSheen`, `overhangShadow` and `revealShadow` each make one; `peelCompose`
+ * takes all four.
+ * @see peelCompose, peelFrame
+ */
 export type PeelShade = (params: RttFilterParams) => Expr;
 /**
- * Page-peel geometry: curl UV, fold angle, crease distances + shadow reaches. `corner` binds the
- * compile-time cpu-only STRING prop (no transform — an inline transform would make the bridge
- * write the string into an f32 field); its geometry lands as literal args.
+ * The geometry of a page curling up from one corner: where the curl reads the child from, how
+ * far it has turned, and how far each pixel is from the crease.
+ *
+ * `corner` is a `compileTime` string prop ('top-left' | 'top-right' | 'bottom-left' |
+ * 'bottom-right') with no transform. `amount` (0–1) is how far the peel has progressed, 0 flat
+ * and 1 fully peeled. `radius` is the tightness of the curl as a fraction of the page diagonal
+ * (0.02–0.4). Keep the frame in a module constant and pass it to the peel shading words and
+ * `peelCompose`.
+ *
+ * @example
+ * ```ts
+ * const peel = peelFrame({corner: p('corner'), amount: p('amount'), radius: p('radius')})
+ * ```
+ * @tip Leave the `corner` prop without a `transform`: it must stay a string for the frame to read.
+ * @see peelCompose, curlShading, curlSheen, overhangShadow, revealShadow
  */
 export declare function peelFrame(opts: {
     corner: PropRef;
     amount: ArgSpec;
     radius: ArgSpec;
 }): GatherFrame;
-/** Crook darkening down the underside of the curl. */
+/**
+ * The darkening in the crook of a curl, easing to full brightness at the lip.
+ *
+ * `shading` (0–1) is how deep the darkening goes.
+ *
+ * @example
+ * ```ts
+ * curlShading(peel, {shading: p('shading')})
+ * ```
+ * @see peelFrame, peelCompose, curlSheen
+ */
 export declare function curlShading(frame: GatherFrame, opts: {
     shading: ArgSpec;
 }): PeelShade;
-/** The specular band running up the curl. */
+/**
+ * The band of light running up a curl.
+ *
+ * `highlight` (0–1) is its strength. `softness` (0–1) runs from a tight gloss to a broad satin.
+ *
+ * @example
+ * ```ts
+ * curlSheen(peel, {highlight: p('highlight'), softness: p('highlightSoftness')})
+ * ```
+ * @see peelFrame, peelCompose, curlShading
+ */
 export declare function curlSheen(frame: GatherFrame, opts: {
     highlight: ArgSpec;
     softness: ArgSpec;
 }): PeelShade;
-/** The contact shadow the curl casts on the flat page past the crease. */
+/**
+ * The shadow a lifted curl casts on the flat page just past the crease.
+ *
+ * `amount` is the same peel amount the frame uses. `shadow` (0–1) is the shadow's strength.
+ *
+ * @example
+ * ```ts
+ * overhangShadow(peel, {amount: p('amount'), shadow: p('shadow')})
+ * ```
+ * @see peelFrame, peelCompose, revealShadow
+ */
 export declare function overhangShadow(frame: GatherFrame, opts: {
     amount: ArgSpec;
     shadow: ArgSpec;
 }): PeelShade;
-/** The shadow on the revealed backing just inside the crease. */
+/**
+ * The shadow on the surface a peel reveals, just inside the crease.
+ *
+ * `amount` is the same peel amount the frame uses. `shadow` (0–1) is the shadow's strength.
+ *
+ * @example
+ * ```ts
+ * revealShadow(peel, {amount: p('amount'), shadow: p('shadow')})
+ * ```
+ * @see peelFrame, peelCompose, overhangShadow
+ */
 export declare function revealShadow(frame: GatherFrame, opts: {
     amount: ArgSpec;
     shadow: ArgSpec;
 }): PeelShade;
 /**
- * The fold composite — cast shadow, shaded flat page, lit curl, back to front. Samples the child
- * at the frame's curl UV (the lip) and at the screen UV (the flat page). Premultiplied — the
- * gather species appends the unpremultiply tail.
+ * A finished page peel: the cast shadows, the flat page and the lit curl, layered back to front.
+ *
+ * The sampling stage of a peel. Pass the four shading terms built on the same frame. Wrap it in
+ * `gatherStack` with no overlays.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(peelCompose(peel, {shade: curlShading(peel, {shading: 0.55}), sheen: curlSheen(peel, {highlight: 0.4, softness: 0.2}), overhang: overhangShadow(peel, {amount: p('amount'), shadow: 1}), reveal: revealShadow(peel, {amount: p('amount'), shadow: 1})}), [])
+ * ```
+ * @see peelFrame, curlShading, curlSheen, overhangShadow, revealShadow
  */
 export declare function peelCompose(frame: GatherFrame, parts: {
     shade: PeelShade;
@@ -323,24 +794,11 @@ export declare function peelCompose(frame: GatherFrame, parts: {
     overhang: PeelShade;
     reveal: PeelShade;
 }): SampleStage;
-/**
- * Reflected sample coordinate: mirror across the horizontal line at `lineY`. Y is down (top=0),
- * so a point at uv.y > lineY reflects to `2·lineY - uv.y`. Pure function.
- */
+/** @internal */
 export declare const mirrorRowUV: import('typegpu').TgpuFn<(uv: d.Vec2f, lineY: d.F32) => d.Vec2f>;
-/**
- * Planar-reflection composite (pre-unpremultiply). Above the line returns the original content
- * untouched; below it, the (edge-handled) reflection sample composited "over" the original via
- * premultiplied alpha, faded by `visibility` (full up to distance−fadeWidth, smoothly to 0 by
- * `distance`; `falloff` is the fade-zone width as a fraction of distance). Pure function.
- */
+/** @internal */
 export declare const planarReflectionCompose: import('typegpu').TgpuFn<(original: d.Vec4f, refl: d.Vec4f, uvY: d.F32, lineY: d.F32, distance: d.F32, falloff: d.F32) => d.Vec4f>;
-/**
- * GPU-free construction of the depth-ramp blur-map fill graph. Per compute pixel, the desired
- * blur radius ramps with the row's depth below the line:
- * `blur × smoothstep(0, blurDistance, height − v) × DEPTH_RAMP_RADIUS_PX` (source pixels).
- * Row-based (depends only on cy/computeHeight); 2D dispatch, STORAGE textureStore.
- */
+/** @internal */
 export declare function buildDepthRampFillGraph(computeWidth: number, computeHeight: number): {
     layout: import('typegpu').TgpuBindGroupLayout<{
         blurMap: {
@@ -361,12 +819,34 @@ export declare function buildDepthRampFillGraph(computeWidth: number, computeHei
         blurDistance: d.F32;
     }>;
 };
-/** The reflected sample coordinate stage (identity above the line; the composite gates on it). */
+/**
+ * The coordinate mirrored across a horizontal line, for reading a reflection below it.
+ *
+ * `line` is a prop, 0–1 down the canvas in uv. Returns a function of the fragment params that
+ * gives the mirrored uv. Above the line the coordinate is still mirrored; `planarReflection`
+ * only shows the reflection below it.
+ *
+ * @example
+ * ```ts
+ * const reflectedUV = mirrorAcrossRow(p('height'))
+ * ```
+ * @see planarReflection, depthRampBlur
+ */
 export declare function mirrorAcrossRow(line: PropRef): (params: GpuFragmentParams) => Expr;
 /**
- * Depth-ramped variable blur (compute): RTT the child, fill a per-pixel radius map from the
- * line geometry, run kit/blur's variable Gaussian. Map-driven slots use their static scalar
- * (compute maps don't drive these per-pixel — the Blur/ProgressiveBlur precedent).
+ * The blur half of a mirror floor: blurs the child more the further a row sits below the line.
+ *
+ * `line` is the same 0–1 line prop as `mirrorAcrossRow`. `blur` is the blur far below the line,
+ * 0–5 where 1 is a radius of about 12 pixels. `blurDistance` (in uv, 0.01–1) is how far below
+ * the line the blur takes to reach full strength. `halfKernel` is the number of taps each side
+ * per pass; 30 is a good value. Spread it into a definition with `species: 'custom'` and read
+ * the result in the fragment as `computeOutputs.blurredTexture`.
+ *
+ * @example
+ * ```ts
+ * ...depthRampBlur({line: p('height'), blur: p('blur'), blurDistance: p('blurDistance'), halfKernel: 30})
+ * ```
+ * @see planarReflection, mirrorAcrossRow, progressiveBlur
  */
 export declare function depthRampBlur(opts: {
     line: PropRef;
@@ -376,26 +856,47 @@ export declare function depthRampBlur(opts: {
 }): {
     compute: GpuComputeNode;
 };
-/** The over-composite stage: the (edge-handled) reflection tap composited "over" the original
- *  below the line, faded to transparent over `distance`/`falloff`. */
+/**
+ * A mirror floor: the child as it is above a line, and its reflection fading out below it.
+ *
+ * `line` (0–1 in uv), `distance` (how far below the line the reflection stays visible, in uv)
+ * and `falloff` (the width of the fade as a fraction of `distance`) are props. `edges` is a prop
+ * with `transform: transformEdges` and `compileTime: true`. `original` is the child's color at
+ * this pixel, `reflection` samples the child (or its blurred copy) at a coordinate, and
+ * `reflectedUV` is usually `mirrorAcrossRow(line)`. Returns a fragment function whose result is
+ * premultiplied; unpremultiply it before returning from `gpu.fragment`.
+ *
+ * @example
+ * ```ts
+ * planarReflection({line: p('height'), distance: p('distance'), falloff: p('falloff'), edges: p('edges')}, source.sample(ctx.uv), (uv) => blurred.sample(uv), mirrorAcrossRow(p('height')))(params)
+ * ```
+ * @see mirrorAcrossRow, depthRampBlur
+ */
 export declare function planarReflection(opts: {
     line: PropRef;
     distance: PropRef;
     falloff: PropRef;
     edges: PropRef;
 }, original: Expr, reflection: (uv: Expr) => Expr, reflectedUV: (params: GpuFragmentParams) => Expr): (params: GpuFragmentParams) => Expr;
-/**
- * Screen a tinted glow (blurred bright highlights) over a base color.
- * `tintStrength = (rgb tint, strength)`. The glow's coverage extends the alpha into transparent
- * areas (Glow's aura precedent) so the halo isn't clipped to the child's α.
- */
+/** @internal */
 export declare const tintedScreenGlow: import('typegpu').TgpuFn<(base: d.Vec4f, glow: d.Vec4f, tintStrength: d.Vec4f) => d.Vec4f>;
 /**
- * Screened-bloom recipe: the compute half is the kit's highlight-bloom mechanism
- * (`withBloomCompute`: bright-extract + variable-Gaussian blur at capped compute resolution);
- * the screen half tints the blurred highlights and screens them back over the graded color
- * (no-op when the bloom buffer is absent — GPU-free resolve, or `strength` = 0, which returns
- * null from `compute`; pair the strength prop with `recompile: crosses(0)`).
+ * A tinted glow of the child's bright parts, screened over a color you have already graded:
+ * film halation, phosphor bloom.
+ *
+ * `strength` is a prop; at 0 the glow pass does not run, so give it `recompile: crosses(0)`.
+ * `radius` is a prop for the glow's spread in pixels. `tint` is an rgb triple (0–1) and
+ * `threshold` (0–1) the brightness a pixel must pass to glow. `output` and `extractName` are
+ * names unique to your definition. Returns `compute`, to set as the definition's `compute:`, and
+ * `screen(base, at, params)`, which screens the glow at coordinate `at` over `base` in the
+ * fragment. The glow reaches past the child's alpha.
+ *
+ * @example
+ * ```ts
+ * const halation = screenedBloom({strength: p('halation'), radius: p('halationRadius'), tint: [1, 0.38, 0.16], threshold: 0.62, output: 'halationTexture', extractName: 'myHalationExtract'})
+ * ```
+ * @tip Build it once at module level so the `compute:` field and the fragment read the same part.
+ * @see bloom, frameSway
  */
 export declare function screenedBloom(slots: {
     strength: PropRef;
@@ -408,28 +909,45 @@ export declare function screenedBloom(slots: {
     compute: GpuComputeNode;
     screen: (base: Expr, at: Expr, params: GpuFragmentParams) => Expr;
 };
-/**
- * Frame sway — a tiny animated translation + rotation about the frame centre, like an unsteady
- * projector gate. `amount` scales both amplitude and (via the gated clock) presence; `t` is the
- * per-frame sway-time accumulator. Returns the UV to sample the content at (a clamp sampler
- * handles the sliver pushed off-frame). amount=0 → returns `uv` unchanged.
- */
+/** @internal */
 export declare const swayUV: import('typegpu').TgpuFn<(uv: d.Vec2f, amount: d.F32, t: d.F32) => d.Vec2f>;
 /**
- * The frame-sway stage: a gated clock (the `field` extraField — advances only while `amount` > 0,
- * freezes rather than snapping back at 0) drives a tiny animated translation + rotation of the
- * content sample UV. Declare the extraField `{schema: f32, initial: 0}` on the definition.
+ * A slight drifting shift and rotation of where the child is read from, like film in an
+ * unsteady projector gate.
+ *
+ * `amount` is a prop from 0 to 1. `field` names an entry you declare in the definition's
+ * `extraFields` as `{schema: schema.f32, initial: 0}`; the sway's clock lives there. Returns a
+ * function of the fragment params that gives the uv to sample the child at. When `amount` drops
+ * to 0 the motion freezes in place rather than snapping back.
+ *
+ * @example
+ * ```ts
+ * const weave = frameSway({amount: p('weave'), field: 'weaveTime'})
+ * ```
+ * @tip Build it once at module level and call it inside `gpu.fragment`; it registers its own per-frame clock.
+ * @see screenedBloom
  */
 export declare function frameSway(slots: {
     amount: PropRef;
     field: string;
 }): (params: GpuFragmentParams) => Expr;
 /**
- * The bokeh-defocus recipe: the aperture-table gather compute (uniform-radius, or the map-driven
- * fork when `radius` binds a spatial map — mouse/auto radius stays a per-frame scalar) + the
- * defocused-buffer sampling fragment. The aperture (shape + blades) is fully RUNTIME: changing
- * it regenerates the CPU tap table and rewrites one small uniform — no recompile. Compute
- * unavailable (GPU-free resolve / no device) → sharp unpremultiplied passthrough.
+ * A photographic lens blur where bright highlights bloom into aperture-shaped discs.
+ *
+ * `radius` (0–100) is the defocus; 100 is a disc about 80 pixels across. `gain` (0–10) is how
+ * strongly highlights bloom and `threshold` (0–1) the brightness they must pass. `shape` is a
+ * string prop: 'blades' | 'circle' | 'star' | 'heart' | 'flower' | 'cross' | 'ring'. `blades`
+ * (0–9) counts blades or points for the blades, star and flower shapes; 0–2 is a round iris.
+ * `rotation` is in degrees and `fringe` (0–1) adds color fringing at the disc edges. Both color
+ * and coverage blur, so silhouettes soften like a real lens. Changing the aperture never
+ * recompiles. Spread it into a definition with `species: 'custom'`, `requiresRTT: true` and
+ * `requiresChild: true`.
+ *
+ * @example
+ * ```ts
+ * ...bokehDefocus({radius: p('radius'), gain: p('highlightGain'), threshold: p('highlightThreshold'), shape: p('bladeShape'), blades: p('bladeCount'), rotation: p('bladeRotation'), fringe: p('chromaticFringe')})
+ * ```
+ * @see gaussianBlur, tiltShift, bloom
  */
 export declare function bokehDefocus(opts: {
     radius: PropRef;