shaders 3.2.475 → 4.0.0

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

@@ -3,35 +3,47 @@ import { Field, Paint, Palette } from './fields';
 import { PropRef } from '../values';
 
 /**
- * One wave: coefficients on the named axes (frequency along x/y, drift speed along t) plus
- * an optional phase. Every field is serializable data — a wave is `{x: 3.2, t: 0.8}`:
- * "a wave across x at frequency 3.2, drifting at speed 0.8". Negative coefficients reverse
- * direction. Coefficient `1` emits the bare axis (no `× 1`).
+ * One traveling sine wave, written as plain data.
+ *
+ * `x`, `y` and `t` are the wave's frequency along that axis: larger is tighter, and `t` is
+ * its drift speed along the layer's clock. Leave an axis out to ignore it. A negative value
+ * runs the wave the other way. `phase` shifts the wave, in radians.
  */
 export interface Wave {
     x?: number;
     y?: number;
     t?: number;
-    /** Radians, or a `hashPhase(...)` Expr for seeded decorrelation. */
+    /** Radians, or `hashPhase(...)` for a seeded random phase. */
     phase?: Expr | number;
 }
 /**
- * One term of a schedule: a single wave, or a product of waves (the "organic" move — an
- * x-wave × a y-wave interferes instead of striping). `weight` scales the term (default 1,
- * emitted only when ≠ 1).
+ * One term of a wave schedule: a single wave, or several multiplied together.
+ *
+ * Multiplying an x-wave by a y-wave gives an interference pattern instead of stripes.
+ * `weight` scales the term, default 1.
  */
 export interface WaveTerm {
     waves: Wave[];
     weight?: number;
 }
 /**
- * `waves` — overlapping traveling sine waves, schedule as data. The engine under every
- * "organic wobble": evaluates `Σ weightᵢ · Π sin(x·kx + y·ky + t·kt + phase)` over the
- * named axes, SIGNED output (tone words shape it; `warped` coords warp it — both stay
- * outside, deliberately). Emission is deterministic — terms sum in schedule order, waves
- * multiply in wave order, axes emit x → y → t → phase — so a ported schedule reproduces
- * its original arithmetic. Schedules are the caller's look; `organicWaves` generates one
- * from intent when nobody has hand-tuned constants to preserve.
+ * Overlapping traveling sine waves from a schedule written as data: the organic wobble
+ * behind blob edges, water lines and drifting fills.
+ *
+ * Pass the coordinates to wave over (`x`, optionally `y`, and `t` for the layer's clock)
+ * and a list of terms. Each term multiplies its waves and the terms add up. The result is
+ * signed: one wave runs −1 to 1, a schedule runs within about ±(sum of weights). It returns
+ * an expression, not a field, so it slots into `paint: (params) => …` recipes and math.
+ *
+ * @example
+ * ```ts
+ * const wobble = waves({x: delta.member('x'), y: delta.member('y'), t: time}, [
+ *   {waves: [{x: 3, t: 0.8}, {y: 2.2, t: -0.5}]},
+ *   {waves: [{x: 5.1, y: -3.3, t: 0.6}], weight: 0.5},
+ * ])
+ * ```
+ * @tip Keep the schedule as constants next to the definition. It is the look, so keep it where you can tune it.
+ * @see wavyLine, organicWaves, hashPhase
  */
 export declare function waves(axes: {
     x: Expr | number;
@@ -39,10 +51,18 @@ export declare function waves(axes: {
     t?: Expr | number;
 }, schedule: WaveTerm[]): Expr;
 /**
- * `wavyLine` — an animated organic curve: the offset of a line at coordinate `along`, as a
- * weighted stack of traveling sines. Sugar over {@link waves} on one axis; give each wave a
- * `hashPhase` to decorrelate a family of lines. Curtain paths, water horizons, wavy
- * baselines, cloth edges.
+ * The height of an animated wavy line at a point along it: a stack of traveling sines.
+ *
+ * `along` is the coordinate along the line and `time` the layer's clock. Each wave has a
+ * `freq` (tightness), a `speed` (drift along the clock), an `amount` (height) and an
+ * optional `phase` in radians. Signed, within ±(sum of amounts). Add it to a baseline to get
+ * the curve. Give each line of a family its own `hashPhase` so they do not move in step.
+ *
+ * @example
+ * ```ts
+ * const arc = wavyLine({along: x, time: t, waves: [{freq: 1.4, speed: 0.3, amount: 0.5}, {freq: 3.1, speed: -0.2, amount: 0.2}]})
+ * ```
+ * @see waves, hashPhase
  */
 export declare function wavyLine(opts: {
     along: Expr | number;
@@ -55,12 +75,19 @@ export declare function wavyLine(opts: {
     }[];
 }): Expr;
 /**
- * `organicWaves` — generate a {@link waves} schedule from intent, for authors (human or AI)
- * who don't have hand-tuned constants to preserve. Three knobs + seed, deliberately
- * (knobs grow under pressure from real use, never speculatively): `frequency` sets the base
- * scale, `detail` the number of product-pair layers (each ~1.8× finer, half the weight),
- * `drift` the animation speed. Deterministic per seed. TUNING CANDIDATE — constants pending
- * an eye pass; treat the output as a starting point, not a spec.
+ * A ready-made `waves` schedule from three knobs, for when you have no hand-tuned constants.
+ *
+ * `frequency` sets the size of the largest waves. `detail` is how many finer layers stack on
+ * top (default 3, each about 1.8× finer and half as strong). `drift` is the animation speed
+ * (default 0.5). The same `seed` always gives the same schedule. Weights are normalized so
+ * the summed wave stays within about −1 to 1. Treat the result as a starting point to tune.
+ *
+ * @example
+ * ```ts
+ * const wobble = waves({x: delta.member('x'), y: delta.member('y'), t: time}, organicWaves({frequency: 3, detail: 3, drift: 0.4}))
+ * ```
+ * @tip The schedule uses x, y and t, so the axes you pass to `waves` must provide all three.
+ * @see waves
  */
 export declare function organicWaves(opts: {
     frequency: number;
@@ -69,96 +96,273 @@ export declare function organicWaves(opts: {
     seed?: number;
 }): WaveTerm[];
 /**
- * The exponential-scale noise framing: aspect-correct the UV, scale by `exp(scale)` (each +1
- * on the slider doubles-ish the frequency), offset by `seed`. Hands the inner field a vec2
- * pattern position.
+ * Frames a field on a zoomable plane: how big the pattern is and where it starts.
+ *
+ * Takes the canvas position, corrects it for aspect ratio, zooms it by `scale` and slides it
+ * by `seed`, then hands a 2D pattern position to the field inside. `scale` is exponential:
+ * each +1 makes the pattern about 2.7× finer, so a slider from −2 to 5 runs from coarse to
+ * fine. A different `seed` shows a different part of the pattern. The framing every noise
+ * texture opens with.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(unitized(gaborGrains({frequency: p('frequency')})), {scale: p('scale'), seed: p('seed')})), stops(p('colorSpace')))
+ * ```
+ * @tip `noiseField` bases take a 3D position. Put `evolving` between `seededPlane` and the basis, even at `rate: 0`, to supply the third axis.
+ * @see evolving, pixelGrid, scaledPlane
  */
 export declare function seededPlane(field: Field, slots: {
     scale: PropRef;
     seed: PropRef;
 }): Field;
 /**
- * The RAW-divide exponential-scale framing (Scratches' historical domain — the unguarded
- * aspect divide is part of its exact arithmetic).
+ * @internal Scratches' historical framing: `seededPlane` with an unguarded aspect divide,
+ * kept so that shader's exact arithmetic is preserved. Authors use `seededPlane`.
  */
 export declare function rawPlane(field: Field, slots: {
     scale: PropRef;
     seed: PropRef;
 }): Field;
 /**
- * The per-pixel framing: floor the device-pixel position into `grain`-sized cells, offset by
- * `seed` — for patterns defined on the pixel grid (blue noise) rather than in UV space.
+ * Frames a field on the pixel grid: one value per block of `grain` device pixels.
+ *
+ * For patterns that live on pixels rather than on the canvas (blue noise, dither). `grain`
+ * is the block size in pixels (1 = every pixel), `seed` picks a different block of the
+ * pattern. The field inside gets whole-number pixel coordinates.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(pixelGrid(blueSpeckle(), {grain: p('grain'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see blueSpeckle, seededPlane
  */
 export declare function pixelGrid(field: Field, slots: {
     grain: PropRef;
     seed: PropRef;
 }): Field;
 /**
- * The linear-scale noise framing: aspect-correct the UV and multiply by `scale` directly (no
- * exponential remap), bound as a local — for recipes whose parts read the same plane position
- * several times.
+ * Frames a field on the aspect-corrected canvas plane, zoomed by a plain multiplier.
+ *
+ * Unlike `seededPlane`, `scale` is linear: roughly the number of pattern cells across the
+ * canvas height. There is no seed. The position is computed once, so a recipe whose parts
+ * read it several times pays for it once.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(unitized(scaledPlane(waveletBands({detail: p('detail')}), {scale: p('scale')})), stops(p('colorSpace')))
+ * ```
+ * @see seededPlane, cellDistances
  */
 export declare function scaledPlane(field: Field, slots: {
     scale: PropRef;
 }): Field;
 /**
- * Lift a vec2 pattern position into 3D by walking the third axis with time — the difference
- * between noise that MORPHS in place (this) and noise that slides. `rate` scales the
- * evolution independently of the node's `speed` prop.
+ * Makes a 3D noise basis morph in place over time instead of sliding across the canvas.
+ *
+ * Wraps a basis that takes a 3D position (`noiseField`): the 2D pattern position from the
+ * framing outside becomes `(x, y, time × rate)`. `rate` multiplies the layer's clock, on top
+ * of the definition's `speed` prop. It sits between the framing and the basis.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(evolving(noiseField('perlin'), {rate: 0.3}), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @tip The clock is the definition's `animatedTime: {speed: 'speed'}`. Without it nothing moves.
+ * @see seededPlane, curlSpeed
  */
 export declare function evolving(field: Field, opts: {
     rate: number;
 }): Field;
-/** Oriented sine grains at `frequency` waves per cell, phase-driven by the node's clock. Signed. */
+/**
+ * Oriented sine grains: short striped patches, each facing a random way, like brushed metal
+ * or wood grain.
+ *
+ * `frequency` is how many stripes fit in one grain (1 to 24, default 8). The stripes slide
+ * along their grain on the layer's clock. Signed, −1 to 1: wrap it in `unitized` before a
+ * tone word. Takes a 2D position, so frame it with `seededPlane`.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(unitized(gaborGrains({frequency: p('frequency')})), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see waveletBands, unitized
+ */
 export declare function gaborGrains(slots: {
     frequency: PropRef;
 }): Field;
-/** Rotating banded wavelets; `detail` is the per-octave frequency ratio. Phase-animated, signed. */
+/**
+ * Rotating bands of wavelets: layered ripples that turn against each other, a watery
+ * interference look.
+ *
+ * `detail` is the frequency ratio between the four layers (1.05 to 2, default 1.24; higher
+ * adds finer ripples). The bands slide on the layer's clock. Signed, about −1 to 1: wrap it
+ * in `unitized` before a tone word. Takes a 2D position.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(unitized(waveletBands({detail: p('detail')})), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see gaborGrains, unitized
+ */
 export declare function waveletBands(slots: {
     detail: PropRef;
 }): Field;
-/** Spatial-high-pass blue-noise speckle over a pixel-grid coordinate. Static, unit range. */
+/**
+ * Fine, even speckle with no clumps: blue noise, one random value per pixel block.
+ *
+ * Still (no animation). Unit range, about 0 to 1, so it feeds `noiseTone` directly. Only
+ * makes sense over `pixelGrid`, which gives it the pixel coordinates it expects.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(pixelGrid(blueSpeckle(), {grain: p('grain'), seed: p('seed')})), stops(p('colorSpace')))
+ * ```
+ * @tip A good dither or film-grain layer over another shader at low opacity.
+ * @see pixelGrid
+ */
 export declare function blueSpeckle(): Field;
-/** Branching hydraulic-erosion ridge height (the `.x` of the erosion field). Static, signed. */
+/**
+ * Terrain eroded by water: sharp branching ridges with gullies running off them.
+ *
+ * Still (no animation). Signed, centred on 0: wrap it in `unitized` before a tone word.
+ * Takes a 2D position, so frame it with `seededPlane`.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(unitized(erosionRidges()), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see unitized, seededPlane
+ */
 export declare function erosionRidges(): Field;
-/** Swirling curl-flow speed (√2-normalized magnitude), morphing in place at `rate` × the clock. */
+/**
+ * How fast a swirling flow moves at each point: soft eddies and streams that morph in place.
+ *
+ * `rate` multiplies the layer's clock. Never negative and mostly 0 to 1, so it feeds
+ * `noiseTone` directly. Takes a 2D position, so frame it with `seededPlane`.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(curlSpeed({rate: 0.2}), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see evolving, noiseTone
+ */
 export declare function curlSpeed(opts: {
     rate: number;
 }): Field;
-/** Fine hairline streaks at `thickness`, flickering on the node's clock. Fragment-only (fwidth). */
+/**
+ * Fine hairline scratches, like a scuffed surface, flickering on the layer's clock.
+ *
+ * `thickness` widens the bright core of each streak (0.2 to 5, default 1). The value is 0
+ * off a streak and rises well past 1 on one, so send it through `noiseTone`, which clamps.
+ * Takes a 2D position. Works in a `paint:` only, not in a compute pass.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(scratchStreaks({thickness: p('thickness')}), {scale: p('scale'), seed: p('seed')})), linearPair(p('colorA'), p('colorB')))
+ * ```
+ * @see noiseTone, linearPair
+ */
 export declare function scratchStreaks(slots: {
     thickness: PropRef;
 }): Field;
-/** Remap a signed [-1,1] field to the unit range (`v · 0.5 + 0.5`). */
+/**
+ * Turns a signed field (−1 to 1) into a unit field (0 to 1).
+ *
+ * Put it directly around a signed basis (`gaborGrains`, `waveletBands`, `erosionRidges`,
+ * `noiseField('mx3signed')`) so `noiseTone` and the palette see 0 to 1. Or skip it and use
+ * `signedTone`, which takes the signed value itself.
+ *
+ * @example
+ * ```ts
+ * seededPlane(unitized(gaborGrains({frequency: p('frequency')})), {scale: p('scale'), seed: p('seed')})
+ * ```
+ * @see signedTone, noiseTone
+ */
 export declare function unitized(field: Field): Field;
 /**
- * The shared noise tone tail: additive contrast about mid-grey + balance shift, inverted so a
- * ramp's colorA reads as the LOW end. `contrast`/`balance` omitted = 0 (identity) for
- * textures without tone controls.
+ * The standard contrast and balance controls of a noise texture, turning a 0–1 field into
+ * the ramp position.
+ *
+ * `contrast` steepens the field around mid-grey (0 = unchanged, positive = sharper, negative
+ * = flatter). `balance` shifts the whole range (positive = more of the first color). Leave
+ * the slots out for a texture without those controls. The result is flipped: where the
+ * field is high the ramp shows its first color. Expects a unit field, so put `unitized`
+ * around a signed basis first.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(evolving(noiseField('perlin'), {rate: 0.3}), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @tip Contrast here is additive: 0 is the identity, not 1. Default the prop to 0.
+ * @see signedTone, gainTone, unitized
  */
 export declare function noiseTone(field: Field, slots?: {
     contrast?: PropRef;
     balance?: PropRef;
 }): Field;
 /**
- * The signed tone tail: contrast/balance applied to the RAW [-1,1] field BEFORE the squash to
- * [0,1] (then inverted), so high contrast rides further before clipping.
+ * Contrast and balance for a signed field (−1 to 1), applied before it is squashed to 0–1.
+ *
+ * The same controls as `noiseTone` (`contrast` 0 = unchanged, `balance` shifts), but working
+ * on the raw signed value lets high contrast push further before it clips. Flipped like
+ * `noiseTone`: a high field shows the first color. Use it in place of `unitized` plus
+ * `noiseTone`.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(signedTone(seededPlane(evolving(noiseField('mx3signed'), {rate: 0.5}), {scale: p('scale'), seed: p('seed')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see noiseTone, unitized
  */
 export declare function signedTone(field: Field, slots: {
     contrast: PropRef;
     balance: PropRef;
 }): Field;
-/** The multiplicative tone tail (contrast is a gain, 1 = identity), non-inverted — Worley's shape. */
+/**
+ * Contrast as a multiplier and balance as a shift over a 0–1 field, not flipped.
+ *
+ * `contrast` 1 leaves the field alone (a slider from 0.25 to 4 works well) and `balance`
+ * shifts it. Low field values read the first color. The tone inside `worleyNoise`. Reach for
+ * it when a "1 = normal" contrast slider fits better than `noiseTone`'s "0 = normal".
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(gainTone(cellFill(cellDistances({scale: p('scale'), seed: p('seed')}), {edgeIntensity: p('edgeIntensity')}), {contrast: p('contrast'), balance: p('balance')}), stops(p('colorSpace')))
+ * ```
+ * @see noiseTone, worleyNoise
+ */
 export declare function gainTone(field: Field, slots: {
     contrast: PropRef;
     balance: PropRef;
 }): Field;
-/** Two endpoint color props mixed in LINEAR space — for definitions without a color-space prop. */
+/**
+ * A two-color palette mixed in linear RGB, for a definition with no color-space prop.
+ *
+ * Reads two color props. Use `pair` or `stops` from paint when the definition has a
+ * `colorSpace` prop.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(noiseTone(seededPlane(scratchStreaks({thickness: p('thickness')}), {scale: p('scale'), seed: p('seed')})), linearPair(p('colorA'), p('colorB')))
+ * ```
+ * @see pair, stops
+ */
 export declare function linearPair(a: PropRef, b: PropRef): Palette;
 /**
- * Multi-octave fractal Brownian motion: rotated centred plane → gated 8-octave golden-angle
- * fBm over MaterialX simplex → weight-normalized unit field → stop ramp. `octaves` gates the
- * fixed loop at runtime, so the slider does not recompile.
+ * A complete fractal-noise paint: layered simplex noise that morphs over time, read through
+ * the color ramp.
+ *
+ * `angle` rotates the pattern (degrees). `octaves` is how many layers stack (1 to 8, changed
+ * live without a recompile), `detail` how much finer each layer is (1 to 4) and `contrast`
+ * how much weaker (0.1 to 1). `seed` re-mixes the layers. `space` is the color-space prop.
+ * Reads the definition's `colorA`, `colorB` and, when present, `stops` props.
+ *
+ * @example
+ * ```ts
+ * paint: fractalNoise({angle: p('angle'), detail: p('detail'), contrast: p('contrast'), octaves: p('octaves'), seed: p('seed'), space: p('colorSpace')})
+ * ```
+ * @tip Declare `animatedTime: {speed: 'speed'}` on the definition. The morphing runs on the layer's clock.
+ * @see worleyNoise, noiseField
  */
 export declare function fractalNoise(slots: {
     angle: PropRef;
@@ -169,9 +373,24 @@ export declare function fractalNoise(slots: {
     space: PropRef;
 }): Paint;
 /**
- * Cellular (Worley) noise: aspect plane → gated 4-octave cellular sum (nearest-2 distances
- * under a selectable metric, reduced per `mode`) → per-mode normalization → gain tone → ramp.
- * `mode`/`distance`/`octaves` are compile-time props read as CPU values and folded to literals.
+ * A complete cellular-noise paint: distances to drifting cell points, read through the
+ * color ramp.
+ *
+ * `scale` is the number of cells across (1 to 30) and `jitter` how far the points wander
+ * from a grid (0 = rigid grid, 1 = random). `mode` picks the distance field: `'f1'`
+ * (cells), `'f2'`, `'f2MinusF1'` (edges), `'f1PlusF2'`, `'f1TimesF2'`. `distance` picks the
+ * cell shape: `'euclidean'` (round), `'manhattan'` (diamond), `'chebyshev'` (square).
+ * `octaves` (1 to 4) stacks finer layers, with `lacunarity` and `persistence` setting how
+ * much finer and weaker. `contrast` is a multiplier (1 = unchanged) and `balance` a shift.
+ * Low values read the first color. `mode`, `distance` and `octaves` are compile-time props.
+ * Reads the definition's `colorA`, `colorB` and, when present, `stops` props.
+ *
+ * @example
+ * ```ts
+ * paint: worleyNoise({scale: p('scale'), jitter: p('jitter'), lacunarity: p('lacunarity'), persistence: p('persistence'), contrast: p('contrast'), balance: p('balance'), seed: p('seed'), mode: p('mode'), distance: p('distance'), octaves: p('octaves'), space: p('colorSpace')})
+ * ```
+ * @tip Give the `mode` and `distance` props `transformWorleyMode` and `transformWorleyDistance` as their `transform`.
+ * @see cellDistances, transformWorleyMode, transformWorleyDistance, fractalNoise
  */
 export declare function worleyNoise(slots: {
     scale: PropRef;
@@ -181,59 +400,144 @@ export declare function worleyNoise(slots: {
     contrast: PropRef;
     balance: PropRef;
     seed: PropRef;
-    /** Compile-time: the field reduction (f1/f2/…), read from prop values. */
+    /** Compile-time prop: `'f1' | 'f2' | 'f2MinusF1' | 'f1PlusF2' | 'f1TimesF2'`. */
     mode: PropRef;
-    /** Compile-time: the distance metric, read from prop values. */
+    /** Compile-time prop: `'euclidean' | 'manhattan' | 'chebyshev'`. */
     distance: PropRef;
-    /** Compile-time: the octave gate (1–4), read from prop values. */
+    /** Compile-time prop: 1 to 4. */
     octaves: PropRef;
     space: PropRef;
 }): Paint;
 /**
- * Nearest-two cellular distances `vec2(d1, d2)` over the aspect plane at `scale`, the cell
- * points drifting on the node's clock. Wrap in `share` when a fill and a border mask read
- * the same evaluation.
+ * Distances from each pixel to its nearest two cell points, as `(d1, d2)`: the raw material
+ * for Voronoi fills and borders.
+ *
+ * `scale` is the number of cells across and `seed` picks a different set of points. The
+ * points drift on the layer's clock. Feed it to `cellFill` or `cellBorders`, and wrap it in
+ * `share` when both read it.
+ *
+ * @example
+ * ```ts
+ * const cells = share(cellDistances({scale: p('scale'), seed: p('seed')}))
+ * ```
+ * @see cellFill, cellBorders, share
  */
 export declare function cellDistances(slots: {
     scale: PropRef;
     seed: PropRef;
 }): Field;
-/** The F1/F2 fill gradient: `edgeIntensity` sets how far the edge color reaches into each cell. */
+/**
+ * A 0–1 fill for each cell: 0 at the cell's point, 1 at its boundary, whatever the cell size.
+ *
+ * `edgeIntensity` (0 to 1) is how far the boundary color reaches into the cell. Takes the
+ * `(d1, d2)` field from `cellDistances`. Ramp it directly: the first color lands at the cell
+ * centres.
+ *
+ * @example
+ * ```ts
+ * paint: rampOver(cellFill(cells, {edgeIntensity: p('edgeIntensity')}), stops(p('colorSpace')))
+ * ```
+ * @see cellDistances, cellBorders
+ */
 export declare function cellFill(cells: Field, slots: {
     edgeIntensity: PropRef;
 }): Field;
 /**
- * The cell boundary-line mask (0 on a boundary, 1 inside a cell); `scale` compensates the
- * line width for the cell count.
+ * A mask of the lines between cells: 0 on a boundary, 1 inside a cell.
+ *
+ * `softness` is the line width (0 to about 0.4). Pass the same `scale` as `cellDistances`
+ * so the lines keep their width when the cell count changes. Takes the `(d1, d2)` field.
+ * Use it as the `mask` of `borderOverlay`.
+ *
+ * @example
+ * ```ts
+ * cellBorders(cells, {softness: p('edgeSoftness'), scale: p('scale')})
+ * ```
+ * @see cellDistances, borderOverlay
  */
 export declare function cellBorders(cells: Field, slots: {
     softness: PropRef;
     scale: PropRef;
 }): Field;
 /**
- * Overlay `color` on a paint's rgb where `mask` falls to 0; the base paint keeps its alpha.
- * The base binds as a local: both the overlay mix and the alpha read it.
+ * Draws a color over a paint wherever a mask falls to 0, keeping the paint's alpha.
+ *
+ * `mask` is 1 where the paint shows through and 0 where `color` covers it. The Voronoi
+ * border move: fill the cells, then overlay the border lines.
+ *
+ * @example
+ * ```ts
+ * paint: borderOverlay(rampOver(cellFill(cells, {edgeIntensity: p('edgeIntensity')}), stops(p('colorSpace'))), cellBorders(cells, {softness: p('edgeSoftness'), scale: p('scale')}), {color: p('colorBorder')})
+ * ```
+ * @see cellBorders, cellFill
  */
 export declare function borderOverlay(paint: Paint, mask: Field, slots: {
     color: PropRef;
 }): Paint;
-/** An rgb-only stage for {@link overRgb} — maps a paint's rgb; alpha passes through. */
+/** A color-only step for `overRgb`: takes a paint's rgb and returns new rgb. Alpha is not touched. */
 export type RgbStage = (rgb: Expr, params: GpuFragmentParams) => Expr;
-/** Apply rgb-only stages over a paint, threading the base alpha through unchanged. */
+/**
+ * Runs color-only steps over a paint, in order, leaving its alpha alone.
+ *
+ * This is how `ribbons` is closed: the ribbons come out in the working color space,
+ * `backToP3` brings them to display color and `tonePow` lifts them.
+ *
+ * @example
+ * ```ts
+ * const strands = ribbons({from: p('start'), to: p('end'), count: p('lineCount'), width: p('lineWidth'), amplitude: p('amplitude'), frequency: p('frequency'), softness: p('softness'), spread: p('spread'), pinEdges: p('pinEdges'), colorScale: p('colorScale'), colorVariance: p('colorVariance')})
+ * paint: overRgb(strands, backToP3({space: p('colorSpace')}), tonePow())
+ * ```
+ * @see ribbons, backToP3, tonePow
+ */
 export declare function overRgb(paint: Paint, ...stages: RgbStage[]): Paint;
-/** The closing working-space → P3-linear back-conversion at the compile-time `space` mode. */
+/**
+ * Brings `ribbons` color from its working color space back to display color.
+ *
+ * `space` is the definition's compile-time color-space prop; leave it out for linear. Put it
+ * first in `overRgb`, right after the ribbons.
+ *
+ * @example
+ * ```ts
+ * paint: overRgb(strands, backToP3({space: p('colorSpace')}), tonePow())
+ * ```
+ * @see overRgb, ribbons
+ */
 export declare function backToP3(slots: {
     space?: PropRef;
 }): RgbStage;
-/** The `pow(rgb, 0.85)` tone lift. */
+/**
+ * A gentle lift of the mid-tones (rgb to the power 0.85), as an `overRgb` step.
+ *
+ * @example
+ * ```ts
+ * paint: overRgb(strands, backToP3({space: p('colorSpace')}), tonePow())
+ * ```
+ * @see overRgb
+ */
 export declare function tonePow(): RgbStage;
 /**
- * `ribbons` — flowing, gradient-colored ribbons between two anchors (the ribbons genre
- * primitive): an ATOMIC runtime-count reduce — each ribbon's working-space gradient lookup
- * lives inside the loop — returning working-space rgba. Close it with {@link backToP3} (and
- * {@link tonePow}) via {@link overRgb}. Reads BOTH of the definition's clocks: the main one
- * drives the wave motion, the `color` extra clock
- * (`extraAnimatedTimes: {color: ...}` stays declared on the definition) scrolls the colors.
+ * Flowing gradient-colored ribbons between two points: the Strands look.
+ *
+ * `from` and `to` are position props. `count` is how many ribbons, `width` and `softness`
+ * their thickness and edge (0 to 1), `spread` how far apart they sit (0 to 1), `amplitude`
+ * and `frequency` the size and tightness of the wave (0 to 5). `pinEdges` is a boolean prop
+ * that gathers the ribbons at both ends. `colorScale` (1 to 6) is how many times the
+ * gradient repeats along a ribbon and `colorVariance` (0 to 1) how far each ribbon is offset
+ * in it. The gradient comes from the definition's `stops` prop. The color comes out in the
+ * working color space, so close it with `overRgb(ribbons(…), backToP3({space}), tonePow())`.
+ * The wave runs on `animatedTime: {speed: 'speed'}` and the colors scroll on a second clock,
+ * `extraAnimatedTimes: {color: 'colorSpeed'}`. Declare both on the definition.
+ *
+ * @example
+ * ```ts
+ * paint: overRgb(
+ *   ribbons({from: p('start'), to: p('end'), count: p('lineCount'), width: p('lineWidth'), amplitude: p('amplitude'), frequency: p('frequency'), softness: p('softness'), spread: p('spread'), pinEdges: p('pinEdges'), colorScale: p('colorScale'), colorVariance: p('colorVariance')}),
+ *   backToP3({space: p('colorSpace')}),
+ *   tonePow(),
+ * )
+ * ```
+ * @tip Add `stops: colorStopsPropConfig()` to the props. The ribbons read the stop list, not `colorA` / `colorB`.
+ * @see overRgb, backToP3, tonePow
  */
 export declare function ribbons(slots: {
     from: PropRef;
@@ -248,14 +552,23 @@ export declare function ribbons(slots: {
     colorScale: PropRef;
     colorVariance: PropRef;
 }): Paint;
-/** One entry of {@link reliefBases}: a kit height-field basis for {@link noiseRelief}. */
+/** A height field `noiseRelief` can emboss a layer with. Pick one from `reliefBases`. */
 export interface ReliefBasis {
-    /** The `(vec2f) → f32` height field sampled by the relief filter. */
+    /** The height function: a 2D position in, a height out. */
     readonly fn: unknown;
-    /** The emitted WGSL height-fn name. */
+    /** Its name in the compiled shader. */
     readonly hint: string;
 }
-/** The height fields {@link noiseRelief} accepts. */
+/**
+ * The height fields `noiseRelief` accepts: `stone` (marbled stone) and `wool` (interwoven
+ * fibres).
+ *
+ * @example
+ * ```ts
+ * gpu: {fragment: noiseRelief(reliefBases.wool)}
+ * ```
+ * @see noiseRelief
+ */
 export declare const reliefBases: {
     /** Marbled stone height field. */
     readonly stone: {
@@ -269,13 +582,49 @@ export declare const reliefBases: {
     };
 };
 /**
- * Relief filter over child content: sample the child texture through a Perlin-gradient surface
- * distortion, then modulate its brightness by the `basis` height field (an RTT filter — the
- * definition keeps `requiresRTT`/`requiresChild` and the shared `reliefStylizeProps` block).
+ * Embosses the layer inside with a textured surface: the child is slightly distorted, then
+ * lit by a height field so it reads as carved stone or woven cloth.
+ *
+ * A filter, not a paint. Set it as the definition's fragment with `requiresRTT` and
+ * `requiresChild`, and give the definition props named `intensity`, `scale`, `contrast`,
+ * `distortion` and `seed`. `basis` is an entry of `reliefBases`.
+ *
+ * @example
+ * ```ts
+ * export const Stone = defineShader({
+ *   name: 'Stone',
+ *   requiresRTT: true,
+ *   requiresChild: true,
+ *   props: {intensity: {default: 0.5}, scale: {default: 1}, contrast: {default: 0}, distortion: {default: 0.15}, seed: {default: 0}},
+ *   gpu: {fragment: noiseRelief(reliefBases.stone)},
+ * })
+ * ```
+ * @tip The library shaders build those five props with `reliefStylizeProps` from the utilities, which also sets their sliders.
+ * @see reliefBases
  */
 export declare function noiseRelief(basis: ReliefBasis): (params: GpuFragmentParams) => Expr;
-/** The Worley prop enum transforms + the historical hash alias, for the shader definition. */
+/**
+ * The `transform` for a `worleyNoise` `mode` prop: maps `'f1'`, `'f2'`, `'f2MinusF1'`,
+ * `'f1PlusF2'` or `'f1TimesF2'` to the number the paint reads.
+ *
+ * @example
+ * ```ts
+ * mode: {default: 'f1', transform: transformWorleyMode, compileTime: true}
+ * ```
+ * @see worleyNoise, transformWorleyDistance
+ */
 export declare const transformWorleyMode: (value: string) => number;
+/**
+ * The `transform` for a `worleyNoise` `distance` prop: maps `'euclidean'`, `'manhattan'` or
+ * `'chebyshev'` to the number the paint reads.
+ *
+ * @example
+ * ```ts
+ * distance: {default: 'euclidean', transform: transformWorleyDistance, compileTime: true}
+ * ```
+ * @see worleyNoise, transformWorleyMode
+ */
 export declare const transformWorleyDistance: (value: string) => number;
+/** @internal The raw cell hash under WorleyNoise's historical name, re-exported for an external importer. */
 export declare const worleyHash: import('typegpu').TgpuFn<(p: import('typegpu/data').Vec2f) => import('typegpu/data').Vec2f>;
 //# sourceMappingURL=noise.d.ts.map