shaders 3.2.475 → 4.0.0

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

@@ -2,16 +2,31 @@ import { Expr, GpuFragmentParams } from '../../gpu/contract';
 import { PropRef } from '../values';
 import { ArgSpec } from '../invoke';
 
-/** A generator paint — what a `role: 'generator'` definition's `paint:` field takes. */
+/** What a generator's `paint:` field takes: a function that returns the color at this pixel. */
 export type Paint = (params: GpuFragmentParams) => Expr;
-/** A scalar field over a coordinate. Metric fields take a vec2 UV; domain combinators may pass vec3. */
+/**
+ * A number per pixel, computed from a coordinate.
+ *
+ * Distance fields (`dist.*`) and `flowField` take a uv coordinate (0–1 across the canvas, y
+ * down). Noise fields take a 3D coordinate, so wrap them in `scaledVolume`.
+ */
 export type Field = (params: GpuFragmentParams, coord: Expr) => Expr;
-/** A color lookup at a field parameter t ∈ [0,1]. Build via {@link pair} or {@link stops}. */
+/**
+ * A color for a field value between 0 and 1.
+ *
+ * Build one with `pair` (two colors) or `stops` (a multi-stop ramp), then hand it to `rampOver`.
+ */
 export type Palette = (t: Expr, params: GpuFragmentParams) => Expr;
 /**
- * A scalar slot: a prop/scalar/number, optionally affine-mapped — `{base, add, mul}`
- * resolves to `(base + add) * mul` (for props whose UI range needs remapping into the
- * field's own units, e.g. a 0–100 balance slider to a ±0.3 bias).
+ * A number input: a prop `p('name')`, a plain number, or a prop remapped as `{base, add, mul}`.
+ *
+ * The remapped form resolves to `(base + add) * mul`. Use it when a slider's range is not the
+ * unit the word wants, such as a 0–100 slider that should become a small bias.
+ *
+ * @example
+ * ```ts
+ * threshold(field, {low: 0.3, high: 0.7, bias: {base: p('blend'), add: -50, mul: 0.006}})
+ * ```
  */
 export type FieldScalar = ArgSpec | {
     base: ArgSpec;
@@ -19,19 +34,29 @@ export type FieldScalar = ArgSpec | {
     mul?: number;
 };
 /**
+ * @internal
  * Compile-time color-space mode reader — robust to a raw string (a preset loaded before the
  * prop transform ran) as well as the bridge-mapped number.
  */
 export declare function colorSpaceModeOf(raw: unknown): number;
 /**
+ * @internal
  * Pick the color-mix body for the compile-time color space bound by `space` (linear when
  * absent). The mode is a compile-time prop value, so it JS-branches to a specialised variant
  * and participates in the structural hash.
  */
 export declare function mixColorsIn(space: PropRef | undefined, params: GpuFragmentParams): import('typegpu').TgpuFn<(colorA: import('typegpu/data').Vec4f, colorB: import('typegpu/data').Vec4f, t: import('typegpu/data').F32) => import('typegpu/data').Vec4f> | import('typegpu').TgpuFn<(colorA: import('typegpu/data').Vec4f, colorB: import('typegpu/data').Vec4f, t: import('typegpu/data').F32) => import('typegpu/data').Vec4f> | import('typegpu').TgpuFn<(colorA: import('typegpu/data').Vec4f, colorB: import('typegpu/data').Vec4f, t: import('typegpu/data').F32) => import('typegpu/data').Vec4f> | import('typegpu').TgpuFn<(colorA: import('typegpu/data').Vec4f, colorB: import('typegpu/data').Vec4f, t: import('typegpu/data').F32) => import('typegpu/data').Vec4f> | import('typegpu').TgpuFn<(colorA: import('typegpu/data').Vec4f, colorB: import('typegpu/data').Vec4f, t: import('typegpu/data').F32) => import('typegpu/data').Vec4f> | import('typegpu').TgpuFn<(colorA: import('typegpu/data').Vec4f, colorB: import('typegpu/data').Vec4f, t: import('typegpu/data').F32) => import('typegpu/data').Vec4f>;
 /**
- * A 3-color ladder A → B (by `t1`) → C (by `t2`) in the compile-time color `space`, chaining
- * the space's mix variant.
+ * A three-color blend: `a` to `b` by the first value, then on to `c` by the second.
+ *
+ * Returns a function you call with two 0–1 values and the params. Both mixes happen in the
+ * color space named by the `space` prop (mark it `compileTime`).
+ *
+ * @example
+ * ```ts
+ * paint: (params) => colorLadder3({a: p('colorA'), b: p('colorB'), c: p('colorC'), space: p('colorSpace')})(t1, t2, params)
+ * ```
+ * @see pair, quadBlend
  */
 export declare function colorLadder3(slots: {
     a: PropRef;
@@ -39,46 +64,122 @@ export declare function colorLadder3(slots: {
     c: PropRef;
     space: PropRef;
 }): (t1: Expr, t2: Expr, params: GpuFragmentParams) => Expr;
-/** Two endpoint color props mixed in the structural `space`. */
+/**
+ * A palette of two color props, mixed in the color space named by the `space` prop.
+ *
+ * Mark the `space` prop `compileTime`. Field value 0 gives `a`, 1 gives `b`.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(dist.radial({center: p('center'), radius: p('radius'), aspect: 1, skew: 0}), pair(p('colorA'), p('colorB'), p('colorSpace')))
+ * ```
+ * @see stops, standardPalette
+ */
 export declare function pair(a: PropRef, b: PropRef, space: PropRef): Palette;
 /**
- * The standard stop ramp: when the `stops` prop packs >1 active stops (the fixed
- * `colorsArray`/`positionsArray`/`convertedColorsArray`/`stopCount` uniforms from
- * `colorStopsPropConfig`), the working-space accumulation loop runs; otherwise it falls
- * back to the `colorA`/`colorB` pair. Both in the structural `space`.
+ * The standard multi-stop palette, read from the `stops`, `colorA` and `colorB` props.
+ *
+ * Declare `stops: colorStopsPropConfig()` plus `colorA` and `colorB` on the definition. When
+ * the user has set two or more stops the ramp uses them, otherwise it mixes `colorA` to
+ * `colorB`. Both mix in the color space named by the `space` prop (mark it `compileTime`).
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(dist.linear({from: p('start'), to: p('end'), angle: p('angle')}), stops(p('colorSpace')), {edges: p('edges')})
+ * ```
+ * @tip The prop names are fixed: `stops`, `colorA`, `colorB`. Use `pair` when yours differ.
+ * @see pair, standardPalette
  */
 export declare function stops(space: PropRef): Palette;
 /**
- * The generator paint: evaluate `field` at the composed UV and look its parameter up in
- * `palette`. With an `edges` slot (a structural prop) the parameter is edge-handled first —
- * stretch (clamp), transparent (alpha fades to 0 outside the [0,1] band), mirror, or wrap —
- * and clamped for the color lookup. Without one, the field's parameter feeds the palette
- * raw (fields that bound themselves — rings, sweeps, tone — need no clamp).
+ * A paint that colors each pixel by looking its field value up in a palette.
+ *
+ * Pass an `edges` prop (values `stretch`, `transparent`, `mirror`, `wrap`, marked
+ * `compileTime`) to choose what happens where the field runs past 0–1: hold the end colors,
+ * fade to transparent, bounce back, or repeat. Without it the value goes to the palette as
+ * is, which is right for fields that already stay in range such as `rings` or `tone`.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(dist.linear({from: p('start'), to: p('end'), angle: p('angle')}), stops(p('colorSpace')), {edges: p('edges')})
+ * ```
+ * @tip This is the whole recipe for a gradient: a `dist.*` field, a palette, done.
+ * @see dist, pair, stops, rings, tiles
  */
 export declare function rampOver(field: Field, palette: Palette, opts?: {
     edges?: PropRef;
 }): Paint;
-/** Metric-distance field producers — each maps the screen UV to a raw gradient parameter. */
+/**
+ * Distance fields: the shape of a gradient, as a number that grows away from a line or point.
+ *
+ * Each takes position props made with `transformPosition` and returns 0 at the start and 1
+ * at the end, unbounded beyond. Feed one to `rampOver`.
+ *
+ * @see rampOver, rings, tiles
+ */
 export declare const dist: {
-    /** Projection onto the `from`→`to` axis, rotated by `angle` (degrees) about the midpoint. */
+    /**
+     * A straight gradient from one point to another.
+     *
+     * 0 at `from`, 1 at `to`. `angle` in degrees turns the whole gradient about the midpoint.
+     *
+     * @example
+     * ```ts
+     * paint: rampOver(dist.linear({from: p('start'), to: p('end'), angle: p('angle')}), stops(p('colorSpace')), {edges: p('edges')})
+     * ```
+     * @see rampOver
+     */
     linear(slots: {
         from: PropRef;
         to: PropRef;
         angle: FieldScalar;
     }): Field;
-    /** Elliptical radial distance from `center`, normalized by `radius`; `aspect` stretches, `skew` rotates the axis. */
+    /**
+     * A round or elliptical gradient spreading out from a center.
+     *
+     * 0 at `center`, 1 at `radius` (a fraction of the canvas height). `aspect` 1 is a circle,
+     * larger values squeeze it horizontally. `skew` in degrees tilts the ellipse.
+     *
+     * @example
+     * ```ts
+     * paint: rampOver(rings(dist.radial({center: p('center'), radius: p('radius'), aspect: p('aspect'), skew: p('skewAngle')}), p('repeat')), stops(p('colorSpace')))
+     * ```
+     * @see rings
+     */
     radial(slots: {
         center: PropRef;
         radius: FieldScalar;
         aspect: FieldScalar;
         skew: FieldScalar;
     }): Field;
-    /** Angular sweep around `center`, CCW from 3-o'clock, shifted by `rotation` (degrees). */
+    /**
+     * A sweep around a center, like a clock hand: 0 to 1 once around.
+     *
+     * The sweep starts at the left of the center and runs counter-clockwise. `rotation` in
+     * degrees moves the start. Wrap it in `tiles` to repeat the sweep.
+     *
+     * @example
+     * ```ts
+     * paint: rampOver(tiles(dist.conic({center: p('center'), rotation: p('rotation')}), p('repeat')), stops(p('colorSpace')))
+     * ```
+     * @see tiles
+     */
     conic(slots: {
         center: PropRef;
         rotation: FieldScalar;
     }): Field;
-    /** Diamond (L1 → L∞ via `roundness`) distance from `center`, tilted by `rotation`, normalized by `size`. */
+    /**
+     * A diamond-shaped gradient spreading out from a center.
+     *
+     * 0 at `center`, 1 at `size` (a fraction of the canvas height). `roundness` 0 is a sharp
+     * diamond and 1 is a square. `rotation` in degrees tilts it.
+     *
+     * @example
+     * ```ts
+     * paint: rampOver(rings(dist.diamond({center: p('center'), size: p('size'), rotation: p('rotation'), roundness: p('roundness')}), p('repeat')), stops(p('colorSpace')))
+     * ```
+     * @see rings
+     */
     diamond(slots: {
         center: PropRef;
         size: FieldScalar;
@@ -86,10 +187,17 @@ export declare const dist: {
         roundness: FieldScalar;
     }): Field;
     /**
-     * Animated spiral stripe coverage around `center` (0 = background, 1 = stroke), spun by
-     * the definition's `animatedTime` clock. Stays a fused kit body: its anti-aliasing reads
-     * `fwidth` of the spiral parameter, so the offset must be derived inside the same
-     * fragment-scope function the derivatives sample.
+     * A turning spiral stripe: 0 on the background, 1 on the stroke.
+     *
+     * It spins on the layer's clock, so declare `animatedTime: {speed: 'speed'}`. `scale` sets
+     * how many turns fit, `width` (0–2) the stroke thickness, `falloff` (0–1) thins the stroke
+     * away from the center, `softness` (0–1) blurs its edge. Unlike the other distance fields
+     * this one is already 0–1, so pair it with a palette of background and stroke colors.
+     *
+     * @example
+     * ```ts
+     * paint: rampOver(dist.spiral({center: p('center'), scale: p('scale'), width: p('strokeWidth'), falloff: p('strokeFalloff'), softness: p('softness')}), pair(p('background'), p('stroke'), p('colorSpace')))
+     * ```
      */
     spiral(slots: {
         center: PropRef;
@@ -99,15 +207,47 @@ export declare const dist: {
         softness: FieldScalar;
     }): Field;
 };
-/** Concentric repetition: `count` ≤ 1 clamps, above 1 tiles rings via fract (a runtime select). */
+/**
+ * Repeats a field as concentric bands.
+ *
+ * `count` above 1 restarts the field every 1/count, so a radial gradient becomes rings. At 1
+ * or below the field is clamped to 0–1, and values under 1 stretch the gradient further out.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(rings(dist.radial({center: p('center'), radius: p('radius'), aspect: 1, skew: 0}), p('repeat')), stops(p('colorSpace')))
+ * ```
+ * @tip Each band restarts at the first color rather than bouncing back. For a mirrored repeat, pass `edges` to `rampOver` instead.
+ * @see tiles, rampOver
+ */
 export declare function rings(field: Field, count: FieldScalar): Field;
-/** Wrapped repetition: every cycle tiles via fract (angular sweeps, starbursts). */
+/**
+ * Repeats a field `count` times, always wrapping.
+ *
+ * Made for sweeps: `tiles(dist.conic(...), 4)` gives four sectors. Any count works, including
+ * fractions.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(tiles(dist.conic({center: p('center'), rotation: p('rotation')}), p('repeat')), stops(p('colorSpace')))
+ * ```
+ * @see rings
+ */
 export declare function tiles(field: Field, count: FieldScalar): Field;
 /**
- * Tone-shape a unit field: `glow` spreads via pow, `contrast` is multiplicative around
- * mid-grey, `balance` is a percent-centred (0–100) shift, `invert` flips the result so a
- * multi-stop ramp's stop0…stopN reads in the expected direction. Currently the glow-gamma
- * inverted shape (the one the kit tone library implements for unit fields).
+ * Reshapes a 0–1 field with glow, contrast and balance controls, then flips it.
+ *
+ * `glow` is a spread control: 5 leaves the field alone, lower values pull the bright parts
+ * into tight cores, higher values spread them into a wash. `contrast` scales around the
+ * middle, 1 is neutral. `balance` is 0–100 with 50 neutral. `invert` is always true: the
+ * result is flipped so the palette's first color lands where the field is high.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(tone(scaledVolume(noiseField('mx3'), {scale: p('scale')}), {glow: p('intensity'), contrast: p('contrast'), balance: p('balance'), invert: true}), stops(p('colorSpace')))
+ * ```
+ * @tip Raising `balance` pushes more of the canvas toward the first color.
+ * @see threshold, noiseField
  */
 export declare function tone(field: Field, opts: {
     glow: FieldScalar;
@@ -115,16 +255,35 @@ export declare function tone(field: Field, opts: {
     balance: FieldScalar;
     invert: true;
 }): Field;
-/** Soft threshold over a signed [-1,1] field: normalize to [0,1], add `bias`, smoothstep `low`→`high`. */
+/**
+ * Turns a signed field (−1 to 1) into a soft 0–1 mask.
+ *
+ * The field is first mapped to 0–1 and shifted by `bias`, then eased from 0 at `low` to 1 at
+ * `high`. Bring `low` and `high` together for a hard edge.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(threshold(flowField({detail: p('detail')}), {low: 0.3, high: 0.7, bias: {base: p('blend'), add: -50, mul: 0.006}}), stops(p('colorSpace')))
+ * ```
+ * @see flowField, tone
+ */
 export declare function threshold(field: Field, opts: {
     low: number;
     high: number;
     bias?: FieldScalar;
 }): Field;
 /**
- * Share one field evaluation between consumers: the first read binds a WGSL local, later
- * reads reuse it (a threshold and a shimmer reading the same flow pattern must not
- * re-derive it). Cached per composition.
+ * Evaluates a field once and lets several words read the same result.
+ *
+ * Wrap a field in `share` when it feeds two places, such as a `threshold` and a `pulse`.
+ *
+ * @example
+ * ```ts
+ * const pattern = share(flowField({detail: p('detail')}))
+ * // then: threshold(pattern, ...) and pulse(pattern, ...)
+ * ```
+ * @tip One result per layer, whatever coordinate it is asked for. Do not use it to sample the same field at two offsets.
+ * @see flowField, pulse
  */
 export declare function share(field: Field): Field;
 /** Noise bases usable as a {@link noiseField} — unit-range ([0,1]) samples over a vec3 coordinate. */
@@ -150,52 +309,131 @@ declare const NOISE_BASES: {
         readonly hint: "mxNoiseFloat3";
     };
 };
+/**
+ * The noise flavors `noiseField` can sample.
+ *
+ * `mx3` is smooth all-purpose noise, `perlin` classic gradient noise, `value` softer and
+ * blockier. All three return 0–1. `mx3signed` returns −1 to 1 for use with `threshold`.
+ */
 export type NoiseBasis = keyof typeof NOISE_BASES;
-/** Sample a noise basis at the incoming (vec3) coordinate. Compose under a domain producer. */
+/**
+ * A field of smooth noise in the chosen flavor.
+ *
+ * Noise needs a 3D coordinate, so put it inside `scaledVolume` (and `warped` for motion).
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(scaledVolume(noiseField('mx3'), {scale: p('scale')}), stops(p('colorSpace')))
+ * ```
+ * @see scaledVolume, warped, tone
+ */
 export declare function noiseField(basis: NoiseBasis): Field;
 /**
- * Domain-warp the inner field's coordinate (Inigo-Quilez two-level warp over the given
- * noise basis): noise displaces the sampling position before feeding the field, which is
- * what turns smooth noise into flowing plasma. `amount` (optionally pre-scaled by
- * `amountScale`) sets the displacement; the warp evolves on the definition's
- * `animatedTime` clock scaled by `timeScale`.
+ * Makes a field flow like liquid by bending its coordinate with moving noise.
+ *
+ * `amount` sets how far the coordinate is pushed (0 is off), `amountScale` multiplies it so
+ * a 0–1 slider can reach further. The motion runs on the layer's clock times `timeScale`, so
+ * declare `animatedTime: {speed: 'speed'}`. Needs a 3D coordinate: put it inside `scaledVolume`.
+ *
+ * @example
+ * ```ts
+ * scaledVolume(warped(noiseField('mx3'), {amount: p('warp'), amountScale: 4, timeScale: 0.125}), {scale: p('scale')})
+ * ```
+ * @see noiseField, scaledVolume, warpedPoint
  */
 export declare function warped(field: Field, opts: {
     amount: FieldScalar;
     amountScale?: number;
     timeScale?: number;
 }): Field;
-/** Lift a vec3-coordinate field onto the screen: aspect-corrected z=0 slab, zoomed exponentially by `scale`. */
+/**
+ * Gives a noise field a zoomable, aspect-correct coordinate.
+ *
+ * Turns the pixel's uv into a 3D point so `noiseField` and `warped` can read it. `scale` zooms
+ * exponentially: 1 is neutral and each step up magnifies about 2.7 times. A 0–4 slider works
+ * well.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(scaledVolume(noiseField('perlin'), {scale: p('scale')}), stops(p('colorSpace')))
+ * ```
+ * @see noiseField, warped
+ */
 export declare function scaledVolume(field: Field, opts: {
     scale: FieldScalar;
 }): Field;
 /**
- * The layered trig flow pattern: three nested sin/cos layers, each domain-warping the
- * previous, combined into one signed [-1,1] field. Animated by the definition's
- * `animatedTime` clock; reads the raw coordinate it is given (no aspect correction — the
- * pattern is viewport-relative by design).
+ * A swirling, animated wave pattern from −1 to 1.
+ *
+ * `detail` sets how fine the swirls are. It moves on the layer's clock, so declare
+ * `animatedTime: {speed: 'speed'}`. Feed it to `threshold` for color bands or to `pulse` for
+ * a shimmer.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(threshold(flowField({detail: p('detail')}), {low: 0.3, high: 0.7}), stops(p('colorSpace')))
+ * ```
+ * @see threshold, pulse, share
  */
 export declare function flowField(slots: {
     detail: FieldScalar;
 }): Field;
-/** A subtle brightness pulse from a pattern field: `sin(t·speed + pattern·span)·depth + 1`. */
+/**
+ * A gentle brightness pulse that follows a pattern field, hovering around 1.
+ *
+ * The result swings between 1 − `depth` and 1 + `depth`, so `depth` around 0.02 is subtle.
+ * `speed` is how fast it breathes, `span` how much the pattern staggers the phase. Use it as
+ * the gain in `shimmered`.
+ *
+ * @example
+ * ```ts
+ * paint: shimmered(rampOver(threshold(pattern, {low: 0.3, high: 0.7}), stops(p('colorSpace'))), pulse(pattern, {speed: 2.5, span: 8, depth: 0.015}))
+ * ```
+ * @see shimmered, flowField
+ */
 export declare function pulse(field: Field, opts: {
     speed: number;
     span: number;
     depth: number;
 }): Field;
 /**
- * The classic six-segment hue wheel: a cyclic hue coordinate (any real; wraps) → rgb.
- * The rotating-rainbow palette (Prism's fan, ColorWheel-class effects).
+ * A rainbow color for a hue value: 0 is red, cycling through the spectrum and back every 1.
+ *
+ * Takes any number and wraps it. Returns an rgb color with no alpha.
+ *
+ * @example
+ * ```ts
+ * const rgb = hueWheel(math.add(math.mul(angle, 0.42), animatedTime(params)))
+ * ```
  */
 export declare function hueWheel(h: Expr): Expr;
-/** Scale a paint's whole color (rgb AND alpha) by a gain field evaluated at the raw canvas UV. */
+/**
+ * Multiplies a paint's color and alpha by a gain field, for a slow shimmer over a pattern.
+ *
+ * The gain is read at the raw canvas uv. Build it with `pulse`.
+ *
+ * @example
+ * ```ts
+ * paint: shimmered(rampOver(field, stops(p('colorSpace'))), pulse(field, {speed: 2.5, span: 8, depth: 0.015}))
+ * ```
+ * @see pulse
+ */
 export declare function shimmered(paint: Paint, gain: Field): Paint;
 /**
- * `scatterField` — a smooth scalar field blending unit values scattered organically across the
- * canvas (the mesh-gradient genre primitive): golden-spiral points, gently drifting, blended by
- * inverse distance. `softness` is the IDW exponent (higher = crisper cells); `count` gates the
- * fixed-8 GPU loop at runtime.
+ * A mesh-gradient field: up to 8 drifting points scattered across the canvas, blended by nearness.
+ *
+ * Each point carries a fixed 0–1 value and the result is their distance-weighted average, so
+ * a palette lookup gives soft patches of color. `at` is an aspect-corrected coordinate (x runs
+ * 0 to the aspect ratio, y 0–1). `count` is 1–8, `seed` reshuffles the layout, `drift` (0–1)
+ * sets how far points wander on `time`, `softness` sharpens the patches as it rises. Pass
+ * `anchors` from `scatteredAnchors` to skip recomputing the points per pixel.
+ *
+ * @example
+ * ```ts
+ * const t = scatterField({at: uv, count: uniformOf(p('count'), params), seed, drift: uniformOf(p('drift'), params), aspect, time, softness: 3})
+ * return standardPalette(t, params)
+ * ```
+ * @see scatteredAnchors, wrapRamp, standardPalette
  */
 export declare function scatterField(opts: {
     at: Expr;
@@ -205,24 +443,22 @@ export declare function scatterField(opts: {
     aspect: Expr | number;
     time: Expr | number;
     softness: Expr | number;
-    /**
-     * The constellation pre-computed on the CPU (see {@link scatteredAnchors}) — an
-     * `array<vec4f, 4>` extraField holding the 8 anchors packed 4-per-vec4. When given, the GPU
-     * skips re-deriving every anchor per pixel (`drift`/`aspect`/`time` are then read on the CPU
-     * side and ignored here).
-     */
+    /** The points precomputed each frame by `scatteredAnchors`. When given, `drift`, `aspect` and `time` are ignored here. */
     anchors?: Expr;
 }): Expr;
 /**
- * `scatteredAnchors` — drive an `array<vec4f, 4>` extraField with the {@link scatterField}
- * constellation, computed ONCE per frame on the CPU (the pixel-invariant half of the field:
- * 8 anchor positions from count/seed/drift/aspect/animated time). The definition declares
- * `extraFields: {<field>: {schema: schema.arrayOf(schema.vec4f, 4), initial: 16 zeros}}`; this word
- * registers the per-frame writer and returns the field's GPU accessor to pass as
- * `scatterField({anchors})`. Reads the node's live `_animTime` (the same accumulator the GPU
- * warp reads), so anchors and warp stay on one clock. Dirty-keyed: a static composition (speed 0,
- * no edits) writes nothing. In a GPU-free composition (tests) `_animTime` is unavailable and the
- * field keeps its initial value.
+ * Computes the `scatterField` points once per frame instead of once per pixel.
+ *
+ * Declare a field on the definition, `extraFields: {meshAnchors: {schema: schema.arrayOf(schema.vec4f, 4), initial: new Array(16).fill(0)}}`,
+ * name it in `field`, and pass the result as `anchors` to `scatterField`. The points follow
+ * the layer's clock, so declare `animatedTime`.
+ *
+ * @example
+ * ```ts
+ * const anchors = scatteredAnchors(params, {count: p('count'), seed: p('seed'), drift: p('drift'), field: 'meshAnchors'})
+ * const t = scatterField({at: uv, count: uniformOf(p('count'), params), seed, drift: 0, aspect: 1, time: 0, softness: 3, anchors})
+ * ```
+ * @see scatterField
  */
 export declare function scatteredAnchors(params: GpuFragmentParams, slots: {
     count: PropRef;
@@ -231,25 +467,48 @@ export declare function scatteredAnchors(params: GpuFragmentParams, slots: {
     field: string;
 }): Expr;
 /**
- * `wrapRamp` — traverse a palette through `cycles` half-cycles as `t` rises, folding back at the
- * ends (seam-free triangle wave; identity at cycles = 1); sub-pixel bands fade to the palette
- * mid instead of shimmering. Fragment-only (fwidth).
+ * Runs a palette value back and forth `cycles` times so a ramp repeats without a seam.
+ *
+ * At `cycles` 1 the value passes through unchanged. Where the bands get thinner than a pixel
+ * they fade to the palette's middle instead of flickering. Use it on the value before the
+ * palette lookup, in a `paint:` function.
+ *
+ * @example
+ * ```ts
+ * return standardPalette(wrapRamp({t: field, cycles: math.add(1, math.mul(uniformOf(p('wrapping'), params), 6))}), params)
+ * ```
+ * @tip Not for use inside a `guarded` branch. Reach for `foldRamp` there.
+ * @see foldRamp, scatterField
  */
 export declare function wrapRamp(opts: {
     t: Expr;
     cycles: Expr | number;
 }): Expr;
 /**
- * `foldRamp` — fold an unbounded palette parameter back into [0, 1] as a seam-free triangle
- * wave (0→1→0 every 2 units of `t`). The derivative-free cousin of {@link wrapRamp}: no
- * sub-pixel fade, so it is safe inside a `guarded` branch (non-uniform control flow, where
- * `fwidth` is not). Scale `t` first to set the cycle length.
+ * Folds any number into 0–1 as a seamless zigzag: up from 0 to 1, back down, every 2 units.
+ *
+ * Scale the value first to set the cycle length. Safe anywhere, including inside a `guarded`
+ * branch.
+ *
+ * @example
+ * ```ts
+ * const rgb = stops(p('colorSpace'))(foldRamp(phase), params).member('rgb')
+ * ```
+ * @see wrapRamp
  */
 export declare function foldRamp(t: Expr): Expr;
 /**
- * `warpedPoint` — the domain-warped position itself (two Inigo-Quilez warp levels over MaterialX
- * noise), for recipes that need the warped COORDINATE (to feed several fields) rather than one
- * warped field sample (`warped`). Same memoized 'warpDomain' instance as {@link warped}.
+ * A 3D position pushed around by moving noise, for reading several fields at one warped spot.
+ *
+ * `at` is the 3D point to warp, `time` drives the motion, `amount` how far it is pushed.
+ * `levels` 2 (default) is the full warp, 1 is a cheaper single pass for low-power devices.
+ * Use `warped` instead when one field is enough.
+ *
+ * @example
+ * ```ts
+ * const q = warpedPoint({at: math.vec3(x, y, seed), time: math.mul(t, 0.3), amount: 0.5, levels: isMobileGpuViewport() ? 1 : 2})
+ * ```
+ * @see warped, warpStep
  */
 export declare function warpedPoint(opts: {
     at: Expr;
@@ -258,10 +517,19 @@ export declare function warpedPoint(opts: {
     levels?: 1 | 2;
 }): Expr;
 /**
- * `warpStep` — one chained Inigo-Quilez domain-warp level: displace a position by two
- * decorrelated noise reads (returned as `.z`/`.w` for tail stages to shade with). Chain steps
- * by feeding one step's `.xy` to the next. `offsets` are the two decorrelation offsets — the
- * caller's look data.
+ * One step of a chained warp: pushes a 2D position by two noise reads and hands them back.
+ *
+ * Returns a vec4: `xy` is the warped position, `zw` the two noise values, useful for shading
+ * later. Chain steps by feeding one step's `xy` into the next. `scale` sets the noise
+ * frequency, `z` is a time or seed slice, `offsets` two fixed 2D offsets that keep the reads
+ * apart, and the push distance is `reach` times `strength`.
+ *
+ * @example
+ * ```ts
+ * const level1 = warpStep({at: uv, scale: 1.2, z: math.mul(t, 0.5), offsets: [[5.2, 1.3], [1.7, 9.2]], reach: 0.4, strength: uniformOf(p('warp'), params)})
+ * const level2 = warpStep({at: level1.member('xy'), scale: 2.4, z: t, offsets: [[8.3, 2.8], [2.1, 6.4]], reach: 0.25, strength: uniformOf(p('warp'), params)})
+ * ```
+ * @see warpedPoint, quadBlend
  */
 export declare function warpStep(opts: {
     at: Expr;
@@ -272,17 +540,32 @@ export declare function warpStep(opts: {
     strength: Expr | number;
 }): Expr;
 /**
- * The standard multi-stop / two-color palette, read from the definition's standard palette
- * props (colorA/colorB/stops/colorSpace). The coordinate is consumed once — the stops loop
- * takes it as a fn parameter.
+ * The color for a 0–1 value from the standard palette props: `colorA`, `colorB`, `stops`, `colorSpace`.
+ *
+ * Declare those four props (`stops: colorStopsPropConfig()`, `colorSpace` marked `compileTime`).
+ * It has the shape of a `Palette`, so it drops straight into `rampOver`, or call it yourself
+ * inside a `paint:` function.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(scaledVolume(noiseField('mx3'), {scale: p('scale')}), standardPalette)
+ * ```
+ * @see stops, pair
  */
 export declare function standardPalette(t: Expr, params: GpuFragmentParams): Expr;
 /**
- * A 2D 4-color blend: row1 = A→B by `t1`, row2 = C→D by `t1`, base = row1→row2 by `t2`, in
- * the compile-time color `space`. For a non-linear space the four endpoint conversions are
- * pixel-invariant, so the word's per-frame driver preconverts them (dirty-keyed) into the
- * `convA`–`convD` vec3 extraFields the definition declares, and the GPU mixes the
- * preconverted values with a single back-conversion.
+ * A four-color blend on a square: `a` to `b` across the top, `c` to `d` across the bottom, then top to bottom.
+ *
+ * Returns a function you call with two 0–1 values (across, then down) and the params. Mixes
+ * in the color space named by the `space` prop (mark it `compileTime`). For any space other
+ * than linear, declare `extraFields` named `convA`, `convB`, `convC`, `convD`, each
+ * `{schema: schema.vec3f, initial: [0, 0, 0]}`.
+ *
+ * @example
+ * ```ts
+ * const base = quadBlend({a: p('colorA'), b: p('colorB'), c: p('colorC'), d: p('colorD'), space: p('colorSpace')})(t1, t2, params)
+ * ```
+ * @see colorLadder3, pair
  */
 export declare function quadBlend(slots: {
     a: PropRef;