# Shaders std vocabulary (engine 4.0.4)

Compose shaders from these words with `defineShader` from `shaders/std`. Every word is a plain TypeScript
function; the engine lowers the composition to WGSL at runtime. A `wgsl` body is the escape hatch.

## Defining a shader

### defineShader & wgsl (`shaders/std` top level) — https://shaders.com/docs/primitives/define

A shader is a plain object: a name, the props a user can set, and one field that says what it
draws. Hand it to `defineShader` and it becomes a component you can mount, nest, blend, mask
and animate like any shader in the library.

- `defineShader<T extends ComponentProps>(definition: StdDefinition<T>): GpuShaderDefinition<T>` — Define a shader component from a plain object: its props, and one field that says what it draws.
- `wgsl(spec: WgslSpec): WgslBody
wgsl(body: string): WgslBody
wgsl(strings: TemplateStringsArray, ...values: unknown[]): WgslBody` — Write the per-pixel math by hand, as one WGSL function body that returns a `vec4f` color.
- `registerShader<T extends GpuShaderDefinition<any>>(definition: T): T` — Make a user-defined shader findable by its `name`, so preset JSON can reference it as `type: 'Halo'`.
- `unregisterShader(name: string): void` — Forget a user-defined shader by name.
- `getRegisteredShader(name: string): GpuShaderDefinition | undefined` — Look up a user-defined shader by name.
- `getRegisteredShaders(): GpuShaderDefinition[]` — Every user-defined shader currently registered, oldest first.
- `onShaderRegistered(listener: (name: string, definition: GpuShaderDefinition | null) => void): () => void` — Be told when a user-defined shader is registered, replaced or removed.
- `class WgslBody` — What `wgsl` returns: a body ready to sit in `paint:` or `effect:`.

### Props & values (`shaders/std` top level) — https://shaders.com/docs/primitives/values

How a definition points at its own props. `p('radius')` is a **prop ref**: hand it to any word
that takes a color, a position or a number and the word reads that prop live on the GPU, with
drivers and animation applied, and no rebuild when the value changes. A **Scalar** is a number
built from props and masks. `radialMask(…)` returns one, so does `oscillating(…)` from
`motion`, and `.times(p('intensity'))` scales one by a prop. Words that take a `ScalarInput`
accept either a prop ref or a Scalar.

- `p(name: string): PropRef` — Reference one of the definition's props by name, wherever a word asks for a value.
- `class Scalar` — A number built from props: what `radialMask(…)`, `motion.oscillating(…)` and `.times()` return.

### Identity & recompile rules (`shaders/std` top level) — https://shaders.com/docs/primitives/slots

Two small kinds of rule that make a filter cheap. An **identity rule** sits on a filter
definition's `identityWhen:` and says when the filter does nothing: while it holds, the layer
inside passes through untouched and the effect costs no GPU time. A **recompile rule** sits
on a prop's `recompile:` and says which changes rebuild the shader rather than just update a
value.

- `crosses(value: number): RecompileRule` — Rebuild the shader only when the prop crosses `value`, not on every change.
- `isZero(prop: string): IdentityRule` — Skip the filter entirely while `prop` is exactly 0.
- `isValue(prop: string, value: unknown): IdentityRule` — Skip the filter entirely while `prop` equals `value`, for a filter whose no-op is not 0.
- `allOf(...rules: IdentityRule[]): IdentityRule` — Skip the filter only while every rule holds, for a no-op that needs several props at rest.
- `identityWhenever(props: string[], when: (values: Record<string, unknown>) => boolean): IdentityRule` — Skip the filter when your own test of the props' values says so.
- `recompileWhen(predicate: (prev: any, next: any) => boolean): RecompileRule` — Rebuild when your own test of the old and new value says so, for a threshold `crosses` cannot express.

### Context & invocation (`shaders/std` top level) — https://shaders.com/docs/primitives/invoke

The **context** is what every pixel knows about its surroundings: its coordinate (`uv`, 0–1
across the canvas with y down), the clock (`time`, in seconds), the canvas shape (`aspect`,
`viewportSize`) and the mouse (`pointer`). `ctx` names these as tokens you can pass to a word
or bind in a `wgsl` body's `inputs`.

- `ctx.uv: CtxToken` — The pixel's coordinate: 0–1 across the canvas, y down.
- `ctx.time: CtxToken` — The global clock in seconds.
- `ctx.aspect: CtxToken` — The canvas's width divided by its height.
- `ctx.pointer: CtxToken` — The mouse position in uv (0–1, y down).
- `ctx.viewportSize: CtxToken` — The frame size in device pixels, as a `vec2f`.
- `ctx.logicalViewportSize: CtxToken` — The frame size in CSS pixels, as a `vec2f`, for feature counts that should not change with screen density.
- `paintFrame(params: GpuFragmentParams): {uv: Expr; viewport: Expr}` — The coordinate and frame size a hand-written `paint:` builder should draw in.
- `uniformOf(ref: PropRef, params: {uniforms: Record<string, Expr>}): Expr` — The live GPU value of a prop, for a hand-written builder: `uniformOf(p('radius'), params)`.
- `resolveScalar(input: Scalar | ScalarSource, params: SlotParams): Expr` — A `Scalar` or prop ref as a GPU value, for a hand-written builder.
- `resolveArg(spec: ArgSpec, params: FilterParams): Expr` — Any input value a word accepts (a prop ref, a `Scalar`, a context token, a number) as a GPU value inside a filter's builder.
- `resolveArgIn(spec: ArgSpec, params: SlotParams): Expr` — `resolveArg` for any host, including a warp's `map:` factory.
- `pointwiseOp(fn: unknown, hint: string, args: ArgSpec[], extra?: {compose?: PointwiseEffect['compose']; setup?: PointwiseEffect['setup']}): PointwiseEffect` — Wrap a compiled GPU function as a pointwise filter effect: the child's color goes in first, then `args`.

### List props (`shaders/std` top level) — https://shaders.com/docs/primitives/lists

A **list prop** holds any number of items of the same shape: lights, points, anchors. Declare
it with `listPropConfig`: each item is a small record of typed fields (`position`, `color`,
`number`, `boolean`) and the list has a `maxItems` cap. The editor renders it as an add and
remove list, every position field becomes a draggable handle, and any position can follow the
mouse. Adding or removing an item at runtime never rebuilds the shader.

- `listOf(params: {uniforms: Record<string, Expr>}, prop: string): ListRef` — Read a list prop inside a hand-written builder: its live item count and each item's fields.
- `accumulate(list: ListRef, body: (i: Expr) => Expr, opts: {zero?: 'f32' | 'vec3f'; deps?: Expr[]; hint?: string} = {}): Expr` — Add up a per-item value over every item of a list, in a real GPU loop over the live count.

## Painting

### Fields, palettes & ramps (`import {paint} from 'shaders/std'`) — https://shaders.com/docs/primitives/paint

The words every gradient and most textures are drawn with. A **field** is a number per pixel
(`Field`): the distance from a point, a noise value, a flow pattern. A **palette** turns a
number into a color (`Palette`): two colors, or a multi-stop ramp, mixed in the color space
your definition declares. `rampOver` joins the two and is the single most common line in a
generator.

- `rampOver(field: Field, palette: Palette, opts?: {edges?: PropRef}): Paint` — A paint that colors each pixel by looking its field value up in a palette.
- `pair(a: PropRef, b: PropRef, space: PropRef): Palette` — A palette of two color props, mixed in the color space named by the `space` prop.
- `stops(space: PropRef): Palette` — The standard multi-stop palette, read from the `stops`, `colorA` and `colorB` props.
- `standardPalette(t: Expr, params: GpuFragmentParams): Expr` — The color for a 0–1 value from the standard palette props: `colorA`, `colorB`, `stops`, `colorSpace`.
- `noiseField(basis: NoiseBasis): Field` — A field of smooth noise in the chosen flavor.
- `warped(field: Field, opts: {amount: FieldScalar; amountScale?: number; timeScale?: number}): Field` — Makes a field flow like liquid by bending its coordinate with moving noise.
- `scaledVolume(field: Field, opts: {scale: FieldScalar}): Field` — Gives a noise field a zoomable, aspect-correct coordinate.
- `tone(field: Field, opts: {glow: FieldScalar; contrast: FieldScalar; balance: FieldScalar; invert: true}): Field` — Reshapes a 0–1 field with glow, contrast and balance controls, then flips it.
- `threshold(field: Field, opts: {low: number; high: number; bias?: FieldScalar}): Field` — Turns a signed field (−1 to 1) into a soft 0–1 mask.
- `rings(field: Field, count: FieldScalar): Field` — Repeats a field as concentric bands.
- `tiles(field: Field, count: FieldScalar): Field` — Repeats a field `count` times, always wrapping.
- `share(field: Field): Field` — Evaluates a field once and lets several words read the same result.
- `flowField(slots: {detail: FieldScalar}): Field` — A swirling, animated wave pattern from −1 to 1.
- `pulse(field: Field, opts: {speed: number; span: number; depth: number}): Field` — A gentle brightness pulse that follows a pattern field, hovering around 1.
- `shimmered(paint: Paint, gain: Field): Paint` — Multiplies a paint's color and alpha by a gain field, for a slow shimmer over a pattern.
- `wrapRamp(opts: {t: Expr; cycles: Expr | number}): Expr` — Runs a palette value back and forth `cycles` times so a ramp repeats without a seam.
- `foldRamp(t: Expr): Expr` — Folds any number into 0–1 as a seamless zigzag: up from 0 to 1, back down, every 2 units.
- `warpedPoint(opts: {at: Expr; time: Expr | number; amount: Expr | number; levels?: 1 | 2}): Expr` — A 3D position pushed around by moving noise, for reading several fields at one warped spot.
- `warpStep(opts: {
    at: Expr
    scale: number
    z: Expr | number
    offsets: [[number, number], [number, number]]
    reach: number
    strength: Expr | number
}): Expr` — One step of a chained warp: pushes a 2D position by two noise reads and hands them back.
- `scatterField(opts: {
    at: Expr
    count: Expr | number
    seed: Expr | number
    drift: Expr | number
    aspect: Expr | number
    time: Expr | number
    softness: Expr | number
    /** The points precomputed each frame by `scatteredAnchors`. When given, `drift`, `aspect` and `time` are ignored here. */
    anchors?: Expr
}): Expr` — A mesh-gradient field: up to 8 drifting points scattered across the canvas, blended by nearness.
- `scatteredAnchors(params: GpuFragmentParams, slots: {count: PropRef; seed: PropRef; drift: PropRef; field: string}): Expr` — Computes the `scatterField` points once per frame instead of once per pixel.
- `quadBlend(slots: {a: PropRef; b: PropRef; c: PropRef; d: PropRef; space: PropRef}): (t1: Expr, t2: Expr, params: GpuFragmentParams) => Expr` — A four-color blend on a square: `a` to `b` across the top, `c` to `d` across the bottom, then top to bottom.
- `colorLadder3(slots: {a: PropRef; b: PropRef; c: PropRef; space: PropRef}): (t1: Expr, t2: Expr, params: GpuFragmentParams) => Expr` — A three-color blend: `a` to `b` by the first value, then on to `c` by the second.
- `hueWheel(h: Expr): Expr` — A rainbow color for a hue value: 0 is red, cycling through the spectrum and back every 1.
- `dist.conic(slots: {center: PropRef; rotation: FieldScalar}): Field` — A sweep around a center, like a clock hand: 0 to 1 once around.
- `dist.diamond(slots: {center: PropRef; size: FieldScalar; rotation: FieldScalar; roundness: FieldScalar}): Field` — A diamond-shaped gradient spreading out from a center.
- `dist.linear(slots: {from: PropRef; to: PropRef; angle: FieldScalar}): Field` — A straight gradient from one point to another.
- `dist.radial(slots: {center: PropRef; radius: FieldScalar; aspect: FieldScalar; skew: FieldScalar}): Field` — A round or elliptical gradient spreading out from a center.
- `dist.spiral(slots: {center: PropRef; scale: FieldScalar; width: FieldScalar; falloff: FieldScalar; softness: FieldScalar}): Field` — A turning spiral stripe: 0 on the background, 1 on the stroke.

### Gradients (`import {gradients} from 'shaders/std'`) — https://shaders.com/docs/primitives/gradients

Finished gradient paints: a flat fill, a color wheel that cycles over time, a cloud of five
colored points, and a beam of light between two points. Each word binds your props and
returns a paint, so a definition is the props plus one line. They are complete looks rather
than building blocks. For a gradient of your own shape, compose a `dist` field with `rampOver`
from the fields words instead.

- `solidColor(color: PropRef): Paint` — A flat fill in one color prop.
- `beam(slots: {
    from: PropRef
    to: PropRef
    thickness: {start: ArgSpec; end: ArgSpec}
    softness: {start: ArgSpec; end: ArgSpec}
    colors: {inside: PropRef; outside: PropRef}
    space: PropRef
}): Paint` — A glowing beam of light between two points.
- `colorWheel(slots: {
    mode: PropRef
    direction: ArgSpec
    scale: ArgSpec
    palette: {a: PropRef; b: PropRef; c: PropRef}
    space: PropRef
}): Paint` — A striped gradient that slides across the canvas, cycling through its colors over time.
- `pointCloudGradient(slots: {
    points: {color: PropRef; position: PropRef}[]
    smoothness: ArgSpec
    space: PropRef
}): Paint` — Five colored points placed anywhere on the canvas, each pixel taking the colors of the points nearest it.

### Patterns & tiling (`import {patterns} from 'shaders/std'`) — https://shaders.com/docs/primitives/patterns

Repeating patterns you can color and animate: checkers, stripes, zigzags, rings, falling
streaks, and tiled lattices of squares, hexagons, triangles, bricks, truchet arcs, woven
threads and isometric cubes, plus the print-screen filters (halftone dots, CMYK plates and
dithering). Most pattern words return a **mask**: a number per pixel that is 1 on the pattern
and 0 off it. The lattice words also return a per-cell **shade**, a brightness factor around 1
that `vary` multiplies into a fill so every tile reads slightly different.

- `strokeOver(layers: {fill: PaintSlot; stroke: PaintSlot; mask: PaintSlot; space?: PropRef}): PatternPaint` — Two colors mixed through a mask: `fill` where the mask is 0, `stroke` where it is 1.
- `withAlpha(color: PaintSlot, alpha: PaintSlot): PatternPaint` — A color with its alpha replaced by a separately built mask.
- `checkerCells(slots: {cells: PropRef; softness: PropRef}): PatternPaint` — A checkerboard mask: 1 on one set of squares, 0 on the other, with clean edges at any size.
- `stripeBands(slots: {
    angle: PropRef
    density: PropRef
    balance: PropRef
    softness: PropRef
    offset: PropRef
}): PatternPaint` — A mask of straight parallel stripes that scroll with the layer's clock.
- `zigzagBands(slots: {
    count: PropRef
    angle: PropRef
    balance: PropRef
    softness: PropRef
    offset: PropRef
}): PatternPaint` — A mask of chevron (zigzag) stripes that scroll with the layer's clock.
- `ringWaves(slots: {
    center: PropRef
    frequency: PropRef
    thickness: PropRef
    softness: PropRef
    phase: PropRef
}): PatternPaint` — A mask of concentric rings spreading out from a point, animated by the layer's clock.
- `fallingStreaks(slots: {
    angle: PropRef
    density: PropRef
    speedVariance: PropRef
    trailLength: PropRef
    strokeWidth: PropRef
    rounding: PropRef
    balance: PropRef
}): {mask: PatternPaint; fade: PatternPaint}` — Streaks that fall across the canvas in columns, each column at its own random speed.
- `dotLattice(slots: {
    density: PropRef
    dotSize: PropRef
    offset: PropRef
    speedVariance: PropRef
    twinkle: PropRef
}): PatternPaint` — A mask of round dots on a square grid, with optional row stagger, drift and twinkle.
- `cellFrame(slots: {cells: PropRef; rotation: PropRef; convention: CellFrameConvention}): PatternPaint` — The shared coordinate system of a tiled pattern: how many cells fit down the canvas height and how far the whole lattice is rotated.
- `gridLines(slots: {
    frame: PatternPaint
    thickness: PropRef
    softness: PropRef
    variation: PropRef
}): {lines: PatternPaint; shade: PatternPaint}` — Square grid lines drawn in a `cellFrame`, plus a per-cell shade for the fill.
- `hexLines(slots: {
    frame: PatternPaint
    thickness: PropRef
    softness: PropRef
    variation: PropRef
}): {lines: PatternPaint; shade: PatternPaint}` — Honeycomb lines (pointy-top hexagons) drawn in a `cellFrame`, plus a per-cell shade.
- `triangleLines(slots: {
    frame: PatternPaint
    thickness: PropRef
    softness: PropRef
    variation: PropRef
    speedVariance: PropRef
}): {lines: PatternPaint; shade: PatternPaint}` — A lattice of equilateral triangles drawn in a `cellFrame`, with rows that can drift.
- `brickCourses(slots: {
    cellsX: PropRef
    cellsY: PropRef
    mortar: PropRef
    softness: PropRef
    variation: PropRef
    rotation: PropRef
    offset: PropRef
    speedVariance: PropRef
    seed: PropRef
}): {bricks: PatternPaint; shade: PatternPaint}` — A brick wall: staggered rows with mortar gaps, optional rotation and per-row drift.
- `truchetArcs(slots: {
    frame: PatternPaint
    thickness: PropRef
    softness: PropRef
    seed: PropRef
}): PatternPaint` — A maze of quarter-circle arcs, two per tile, flipped at random so they join into flowing curves.
- `weaveThreads(slots: {
    frame: PatternPaint
    gap: PropRef
    /** `[horizontal, vertical]` thread colors. */
    colors: [PropRef, PropRef]
}): PatternPaint` — Two sets of threads woven over and under each other, returned as a finished color.
- `isoCubeFaces(slots: {
    frame: PatternPaint
    thickness: PropRef
    softness: PropRef
}): {random: PatternPaint; tone: PatternPaint; wire: PatternPaint}` — Tumbling blocks: three shaded rhombus faces per hexagon that read as a field of 3D cubes.
- `vary(color: PaintSlot, factor: PaintSlot): PatternPaint` — A color lightened or darkened per cell by a shade factor, alpha untouched.
- `sampleMapsAtCellCentres(slots: {
    cells: PropRef
    rotation?: PropRef
    props: string[]
}): GpuMapSampleUVs` — Makes map-driven props change per whole cell instead of per pixel, so a mapped dot size or line thickness grows cell by cell rather than being cut off mid-cell.
- `times(a: PaintSlot, b: PaintSlot): PatternPaint` — The product of two values: a mask scaled by a prop, an RGB dimmed by a shade, two masks combined.
- `mixOf(from: PaintSlot, to: PaintSlot, amount: PaintSlot): PatternPaint` — A straight blend from one value to another by an amount from 0 to 1.
- `alphaOf(color: PaintSlot): PatternPaint` — The alpha channel of a color, as a number per pixel.
- `rgbOf(color: PaintSlot): PatternPaint` — The RGB channels of a color, without its alpha.
- `opaque(rgb: PaintSlot): PatternPaint` — An RGB value finished as a fully opaque color.
- `dotScreen(slots: {angle: PropRef; frequency: PropRef}): GatherEffect` — A classic halftone filter: the layer inside it redrawn as a grid of dots that grow where it is bright.
- `cmykPress(slots: {
    paper: PropRef
    frequency: PropRef
    misprint: PropRef
    misprintAngle: PropRef
    plates: InkPlateSpec[]
}): GatherEffect` — A four-color print filter: the layer inside it separated into ink plates, each screened into dots at its own angle and laid down on paper in order.
- `inkPlate(spec: InkPlateSpec): InkPlateSpec` — Declares one ink plate for `cmykPress`.
- `dotScreenMask(uv: Expr, aspect: Expr, angle: Expr, intensity: Expr, frequency: Expr): Expr` — The dot coverage of one halftone screen: 1 inside a dot, 0 between, with the dot size set by an ink amount.
- `inkTransmission(inkColor: Expr, inkMask: Expr): Expr` — How much light passes one ink plate: white where the dot mask is 0, the ink color where it is 1.
- `chosenBy<K extends string>(prop: PropRef, read: (raw: unknown) => K, recipes: Record<K, GatherEffect>): GatherEffect` — Picks one whole effect recipe from a select prop, decided when the shader compiles.
- `pixelGrid(slots: {size: PropRef}): PixelGrid` — The pixel grid of a dither: the layer inside it chopped into square cells of a given size.
- `quantise(slots: {grid: PixelGrid; pattern: PropRef; threshold: PropRef; spread: PropRef}): GatherStage` — Reduces each grid cell of the layer inside to 0 or 1 using a dither pattern.
- `ditherInks(slots: {
    grid: PixelGrid
    levels: GatherStage
    mode: PropRef
    colors: [PropRef, PropRef]
}): GatherEffect` — A dither filter: colors the 0/1 levels from `quantise`, either with two colors of your own or with darkened and brightened versions of the layer's own pixels.
- `scatterPoint(coord: Expr, opts: ScatterOptions): ScatteredPoint` — One random point in each cell of a square grid: the classic scatter for glitter, stars, dust and sparkles.
- `scatterPoints(coord: Expr, opts: ScatterOptions): ScatteredPoint[]` — The scattered points of the four grid cells nearest the pixel, so anything drawn up to half a cell from its point shows whole, never clipped at a cell edge.

### Figures & strokes (`import {figures} from 'shaders/std'`) — https://shaders.com/docs/primitives/figures

Drawn lines: a straight segment and a traveling sine wave. Each word binds your props and
returns a paint that draws the stroke in one color prop with an antialiased edge and leaves
everything else transparent, so it layers cleanly over what sits behind it.

- `strokedSegment(slots: StrokedSegmentSlots): Paint` — A straight line between two points, solid, dashed or dotted, with square or round ends.
- `sineStroke(slots: SineStrokeSlots): Paint` — A wavy line that travels along itself, drawn as a soft band.

### Layering & output (`import {compose} from 'shaders/std'`) — https://shaders.com/docs/primitives/compose

The words that finish a `paint:` function. `layers` stacks several colors into one, back to
front, each with an optional opacity and an optional factor it is seen through. `layered`
builds N variations of one recipe from a data list and sums them, which is how curtains,
cloud banks and echo trails get their depth cheaply.

- `layers(entries: Layer[]): Expr` — Stacks colors into one, first entry at the back.
- `emissiveAlpha(rgb: Expr, hint: string = 'emissive'): Expr` — Turns an rgb light value into a color with alpha, so glows composite over transparency.
- `dithered(color: Expr, params: GpuFragmentParams): Expr` — Adds a tiny amount of noise to a final color so long soft gradients show no banding.
- `layered<T>(layerData: readonly T[], build: (layer: T, index: number) => {value: Expr; weight: Expr}): {weightedSum: Expr; totalWeight: Expr}` — Builds N variations of one thing from a data list and sums them with weights.

### Media (`import {media} from 'shaders/std'`) — https://shaders.com/docs/primitives/media

Pixels that come from an image, a video or the user's camera instead of from math. Each word
loads its source, fits it into the layer the way CSS `object-fit` fits an image into a box,
and returns the GPU half of a definition. Spread it into `defineShader({...})` next to your
props, with `role: 'media'` and `species: 'custom'`.

- `imageMedia(opts: MediaFitSlots & {
    /** The URL prop. */
    src: PropRef
    /** A debug label for the texture, shown in GPU tooling. */
    label: string
    /** Called when the image fails to load. */
    onError?: (error: unknown, url: string) => void
}): MediaSurfaceHalf` — An image from a URL prop, fitted into the layer.
- `videoMedia(opts: MediaFitSlots & {
    /** The URL prop. */
    src: PropRef
    /** The loop prop, synced to the video each frame. */
    loop: PropRef
    /** Milliseconds to wait for the video's metadata before giving up. */
    metadataTimeoutMs: number
    onError?: (error: unknown, info: {url: string | null; stage: 'acquire' | 'autoplay'}) => void
}): MediaSurfaceHalf` — A video from a URL prop, playing in the layer.
- `webcamMedia(opts: MediaFitSlots & {
    /** The selfie-mirror boolean prop. */
    mirror: PropRef
    /** The `getUserMedia` constraints to request the camera with. */
    constraints: MediaStreamConstraints
    /** The key the definition's `naturalSizeKey: {fixed}` uses (a webcam has no URL). */
    naturalSizeKey: string
    onError?: (error: unknown, info: {url: string | null; stage: 'acquire' | 'autoplay'}) => void
}): MediaSurfaceHalf` — The user's camera, live in the layer.

## Noise, light & materials

### Noise (`import {noise} from 'shaders/std'`) — https://shaders.com/docs/primitives/noise

Words for grainy, cloudy, cellular and streaked surfaces: the textures behind clouds, film
grain, stone, water and brushed metal. Read a noise recipe from the inside out, in four
steps. A **basis** is the raw pattern, one number per point (`gaborGrains`, `curlSpeed`,
`blueSpeckle`, or a `noiseField` from paint). A **framing** decides where on the canvas the
basis is sampled and how big it is: `seededPlane` for almost everything, `pixelGrid` for
patterns that live on pixels. A **tone** word turns the raw number into a 0–1 ramp position
with contrast and balance controls: `noiseTone` for a 0–1 basis, `signedTone` for a −1 to 1
one, or `unitized` to convert first. A **ramp** closes it: `rampOver` with `stops` or
`linearPair` gives the field color.

- `seededPlane(field: Field, slots: {scale: PropRef; seed: PropRef}): Field` — Frames a field on a zoomable plane: how big the pattern is and where it starts.
- `evolving(field: Field, opts: {rate: number}): Field` — Makes a 3D noise basis morph in place over time instead of sliding across the canvas.
- `noiseTone(field: Field, slots?: {contrast?: PropRef; balance?: PropRef}): Field` — The standard contrast and balance controls of a noise texture, turning a 0–1 field into the ramp position.
- `unitized(field: Field): Field` — Turns a signed field (−1 to 1) into a unit field (0 to 1).
- `signedTone(field: Field, slots: {contrast: PropRef; balance: PropRef}): Field` — Contrast and balance for a signed field (−1 to 1), applied before it is squashed to 0–1.
- `gainTone(field: Field, slots: {contrast: PropRef; balance: PropRef}): Field` — Contrast as a multiplier and balance as a shift over a 0–1 field, not flipped.
- `gaborGrains(slots: {frequency: PropRef}): Field` — Oriented sine grains: short striped patches, each facing a random way, like brushed metal or wood grain.
- `waveletBands(slots: {detail: PropRef}): Field` — Rotating bands of wavelets: layered ripples that turn against each other, a watery interference look.
- `curlSpeed(opts: {rate: number}): Field` — How fast a swirling flow moves at each point: soft eddies and streams that morph in place.
- `erosionRidges(): Field` — Terrain eroded by water: sharp branching ridges with gullies running off them.
- `scratchStreaks(slots: {thickness: PropRef}): Field` — Fine hairline scratches, like a scuffed surface, flickering on the layer's clock.
- `pixelGrid(field: Field, slots: {grain: PropRef; seed: PropRef}): Field` — Frames a field on the pixel grid: one value per block of `grain` device pixels.
- `blueSpeckle(): Field` — Fine, even speckle with no clumps: blue noise, one random value per pixel block.
- `scaledPlane(field: Field, slots: {scale: PropRef}): Field` — Frames a field on the aspect-corrected canvas plane, zoomed by a plain multiplier.
- `linearPair(a: PropRef, b: PropRef): Palette` — A two-color palette mixed in linear RGB, for a definition with no color-space prop.
- `fractalNoise(slots: {
    angle: PropRef
    detail: PropRef
    contrast: PropRef
    octaves: PropRef
    seed: PropRef
    space: PropRef
}): Paint` — A complete fractal-noise paint: layered simplex noise that morphs over time, read through the color ramp.
- `worleyNoise(slots: {
    scale: PropRef
    jitter: PropRef
    lacunarity: PropRef
    persistence: PropRef
    contrast: PropRef
    balance: PropRef
    seed: PropRef
    /** Compile-time prop: `'f1' | 'f2' | 'f2MinusF1' | 'f1PlusF2' | 'f1TimesF2'`. */
    mode: PropRef
    /** Compile-time prop: `'euclidean' | 'manhattan' | 'chebyshev'`. */
    distance: PropRef
    /** Compile-time prop: 1 to 4. */
    octaves: PropRef
    space: PropRef
}): Paint` — A complete cellular-noise paint: distances to drifting cell points, read through the color ramp.
- `transformWorleyMode(value: string): number` — The `transform` for a `worleyNoise` `mode` prop: maps `'f1'`, `'f2'`, `'f2MinusF1'`, `'f1PlusF2'` or `'f1TimesF2'` to the number the paint reads.
- `transformWorleyDistance(value: string): number` — The `transform` for a `worleyNoise` `distance` prop: maps `'euclidean'`, `'manhattan'` or `'chebyshev'` to the number the paint reads.
- `cellDistances(slots: {scale: PropRef; seed: PropRef}): Field` — Distances from each pixel to its nearest two cell points, as `(d1, d2)`: the raw material for Voronoi fills and borders.
- `cellFill(cells: Field, slots: {edgeIntensity: PropRef}): Field` — A 0–1 fill for each cell: 0 at the cell's point, 1 at its boundary, whatever the cell size.
- `cellBorders(cells: Field, slots: {softness: PropRef; scale: PropRef}): Field` — A mask of the lines between cells: 0 on a boundary, 1 inside a cell.
- `borderOverlay(paint: Paint, mask: Field, slots: {color: PropRef}): Paint` — Draws a color over a paint wherever a mask falls to 0, keeping the paint's alpha.
- `waves(axes: {x: Expr | number; y?: Expr | number; t?: Expr | number}, schedule: WaveTerm[]): Expr` — Overlapping traveling sine waves from a schedule written as data: the organic wobble behind blob edges, water lines and drifting fills.
- `wavyLine(opts: {
    along: Expr | number
    time: Expr | number
    waves: {freq: number; speed: number; amount: number; phase?: Expr | number}[]
}): Expr` — The height of an animated wavy line at a point along it: a stack of traveling sines.
- `organicWaves(opts: {frequency: number; detail?: number; drift?: number; seed?: number}): WaveTerm[]` — A ready-made `waves` schedule from three knobs, for when you have no hand-tuned constants.
- `ribbons(slots: {
    from: PropRef
    to: PropRef
    count: PropRef
    width: PropRef
    amplitude: PropRef
    frequency: PropRef
    softness: PropRef
    spread: PropRef
    pinEdges: PropRef
    colorScale: PropRef
    colorVariance: PropRef
}): Paint` — Flowing gradient-colored ribbons between two points: the Strands look.
- `overRgb(paint: Paint, ...stages: RgbStage[]): Paint` — Runs color-only steps over a paint, in order, leaving its alpha alone.
- `backToP3(slots: {space?: PropRef}): RgbStage` — Brings `ribbons` color from its working color space back to display color.
- `tonePow(): RgbStage` — A gentle lift of the mid-tones (rgb to the power 0.85), as an `overRgb` step.
- `noiseRelief(basis: ReliefBasis): (params: GpuFragmentParams) => Expr` — 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.
- `clothCoords(coords: {along: Expr | number; across: Expr | number}, folds: Fold[], opts: DrapeOptions & {foreshorten?: number}): {along: Expr; across: Expr}` — Where on the unfolded cloth a point lands: the material coordinates to draw a pattern in, so it follows the folds instead of floating over them.
- `drapedFolds(coords: {along: Expr | number; across: Expr | number}, folds: Fold[], opts: DrapeOptions): Expr` — The height of a draped cloth at a point: rounded ridges running along one direction, each rippling and swaying along its length, gathered where the cloth is pinned.
- `foldSet(opts: {
    count: number
    seed: Expr | number
    spread: Expr | number
    width: Expr | number
    height: Expr | number
    jitter?: number
}): Fold[]` — Lays out the ridges of a draped cloth: `count` folds spread evenly across `spread`, each nudged sideways, widened and raised by a seeded amount so no two are alike.
- `reliefBases.stone: { readonly fn: TgpuFn<(p: Vec2f) => F32>; readonly hint: "stone12"; }` — Marbled stone height field.
- `reliefBases.wool: { readonly fn: TgpuFn<(p: Vec2f) => F32>; readonly hint: "wool12"; }` — Interwoven fibrous fabric height field.

### Light (`import {light} from 'shaders/std'`) — https://shaders.com/docs/primitives/light

Words for drawing light: glows, rays, beams, flares and halos, plus the frames they are drawn
in. A **frame** is the coordinate system a light evaluates in. `radialFrame` gives each pixel
its distance and angle from a center; `beamFrame` gives its distance along and across a beam.
**Parts** such as `glowPoint`, `rayLobes` and `featherMask` shape a light over a frame and
return a *field*, a 0–1 number per pixel. `withFrame` evaluates a part in a frame,
`modulate` multiplies parts (a mask over a pattern), and `additive` sums finished lights.

- `glowAt(opts: {uv: Expr; aspect: Expr | number; x: Expr | number; y: Expr | number; sizeSq: Expr | number}): Expr` — A soft round glow at a position on the canvas.
- `glowSpot(du: Expr, dv: Expr, sharpness: Expr): Expr` — A soft oval glow over an offset you have already scaled, the core of a bloom or a glare.
- `emitterFalloff(d: Expr, opts: {radius: Expr | number; power: Expr | number}): Expr` — How light spilling from an emitter dims with distance, with a long realistic tail.
- `radialFrame(center: PropRef): LightValue` — The frame for a burst, halo or sweep around a center prop.
- `seamlessRadialFrame(center: PropRef): LightValue` — The frame `noiseRays` needs: a radial frame around a center prop with no visible seam.
- `beamFrame(anchor: PropRef): LightValue` — The frame of a beam that starts at an anchor prop and points at the canvas center.
- `withFrame(frame: LightValue, part: LightPart, hint?: string): LightValue` — Evaluate a light part in a frame.
- `modulate(first: LightPart, ...rest: LightPart[]): LightPart` — Multiply light parts drawn in the same frame, such as a mask over a pattern.
- `glowPoint(slots: {sharpness: ArgSpec}): LightPart` — A soft glow at the center of a radial frame with no hard edge.
- `featherMask(slots: {radius: ArgSpec; feather: ArgSpec}): LightPart` — A round mask that is solid inside a radius and fades out at its edge.
- `rayLobes(slots: {count: ArgSpec; spin: number; sharpness: ArgSpec}): LightPart` — Soft rays fanning out from the center of a radial frame, turning with the layer's clock.
- `softRayLobes(slots: {count: ArgSpec; softness: ArgSpec; spin: number}): LightPart` — `rayLobes` with a softness slider instead of a sharpness.
- `raySpikes(slots: {halfCount: ArgSpec; power: ArgSpec}): LightPart` — Thin star spikes with dark gaps between them, like light through a camera aperture.
- `ringBand(slots: {center: ArgSpec; spread: ArgSpec; width: ArgSpec}): LightPart` — Three thin colored rings around the center, the rainbow edge of a lens or a halo.
- `noiseRays(slots: {density: ArgSpec; intensity: ArgSpec; spotty: ArgSpec}): LightPart` — Volumetric god rays: shafts of light drifting outward from the center, moving on the layer's clock.
- `rayBands(opts: {
    along: Expr
    frequency: Expr | number
    time: Expr | number
    speed: Expr | number
    phase?: Expr | number
    sharpness: Expr | number
}): Expr` — Bright bands that travel along a coordinate, for aurora curtains or shimmering rays.
- `shine(opts: {normal: Expr; light: Expr; gloss: Expr | number}): Expr` — A specular highlight on any surface that gives you a normal.
- `domeNormal(opts: {
    delta: Expr
    dist: Expr
    radius: Expr | number
    bulge?: {tilt?: number; drop?: number}
}): Expr` — The surface normals of a flat disc treated as a puffy dome, ready to light with `shine`.
- `additive(first: Expr, ...rest: Expr[]): Expr` — Adds lights together, since light from several sources simply sums.
- `heatRamp(colors: {hot: PropRef; mid: PropRef; fringe: PropRef}): { kind: "heatRamp"; taps: (heat: Expr, params: { uniforms: Record<string, Expr>; }) => Expr; }` — The colors of overexposed light, from a dim fringe through a mid tone to a hot core.
- `vignetteMask(slots: {strength: ArgSpec; scale?: number}): LightValue` — Darkens the corners of the canvas.
- `screenGlow(glow: (params: FilterParams) => Expr): PointwiseEffect` — An `effect` that shines emitted light onto the layer inside it, the way light hits film.
- `coverageMix(slots: {color: PropRef; background: PropRef; coverage: LightValue; hint?: string}): LightValue` — Blends from a background color to a light color by a coverage field, as a finished paint.
- `coverageOver(slots: {color: PropRef; background: PropRef; coverage: LightValue}): LightValue` — Lays a light color over a background color by a coverage field, like a layer with an opacity mask, as a finished paint.
- `slowDrift(slots: {seed: ArgSpec; flicker: ArgSpec}): (clock: Expr, params: GpuFragmentParams) => Expr` — The slow breathing and drifting signals that keep a light leak alive.
- `beamBloom(slots: {spread: ArgSpec}): (frame: Expr, drift: Expr, params: GpuFragmentParams) => Expr` — The soft pool of light at the start of a beam, with a wider faint shoulder around it.
- `beamStreaks(slots: {spread: ArgSpec; strength: ArgSpec}): (frame: Expr, drift: Expr, params: GpuFragmentParams) => Expr` — Two bright bands crossing a beam further along it, slowly drifting, like light bouncing inside a film camera.
- `streakBand(u: Expr, center: Expr, width: Expr): Expr` — One soft band across a single coordinate, peaking at `center`.
- `lightBeam(dist: Expr, t: Expr, thickness: {start: Expr; end: Expr}, softness: {start: Expr; end: Expr}): Expr` — The glow of a beam that can be thicker or softer at one end than the other.
- `segmentProject(p: Expr, a: Expr, b: Expr): Expr` — Where a pixel falls along a line from `a` to `b`, and how far it is from that line.
- `flareFrame(slots: {position: PropRef; intensity: ArgSpec; edgeFade: ArgSpec}): LightValue` — The shared frame of a camera lens flare, which every `flare*` part reads.
- `lensGhost(slots: {intensity: ArgSpec; spread: ArgSpec; chroma: ArgSpec}): (flare: Expr, disc: [number, number, number, number], tint: [number, number, number, number], params: GpuFragmentParams) => Expr` — One ghost disc of a lens flare, the faint circles that line up across from the light.
- `flareHalo(slots: {intensity: ArgSpec; radius: ArgSpec; chroma: ArgSpec; softness: ArgSpec}): (flare: Expr, params: GpuFragmentParams) => Expr` — The rainbow halo ring of a lens flare, drawn across the canvas from the light.
- `flareStarburst(slots: {intensity: ArgSpec; points: ArgSpec}): (flare: Expr, params: GpuFragmentParams) => Expr` — The star of thin spikes around the light in a lens flare.
- `flareStreak(slots: {intensity: ArgSpec; length: ArgSpec}): (flare: Expr, params: GpuFragmentParams) => Expr` — The horizontal widescreen streak through the light in a lens flare.
- `flareGlare(slots: {intensity: ArgSpec; size: ArgSpec}): (flare: Expr, params: GpuFragmentParams) => Expr` — The broad warm-white wash around the light that lifts contrast near it.
- `flareCore(slots: {intensity: ArgSpec}): (flare: Expr, params: GpuFragmentParams) => Expr` — The bright point at the light itself: a hard pinpoint inside a small soft glow.
- `flareComposite(total: Expr, flare: Expr): Expr` — Closes a lens flare: turns the summed flare parts into the color to return from `paint`.
- `dithered(heat: Expr, uv: Expr, clock: Expr): Expr` — Adds a trace of noise to a heat field so long soft ramps do not show bands.
- `starGlint(offset: Expr, opts: {
    core: Expr | number
    rayLength: Expr | number
    rayWidth: Expr | number
    rays: Expr | number
    /** Optional: the glint fades to nothing by this distance from its centre (measured along the larger axis). */
    reach?: Expr | number
}): Expr` — A four-point star of light: a round core with a thin ray along each axis, like a glint off glitter or a star in a photograph.

### Materials & surfaces (`import {materials} from 'shaders/std'`) — https://shaders.com/docs/primitives/materials

Words that shade a surface so a shape reads as glass, metal, plastic or stone. A material is
three things: a **normal** (which way the surface faces at this pixel), a **light** (where it
comes from) and a **response** (how the surface answers: diffuse, glint, mirror, tint).
`shapedSurface` turns a shape prop into a surface you can shade. It hands your `surface`
function a frame with the shape's distance field, and `surfaceField` binds what you read from
it: the signed distance, the pixel size, the neighbour taps.

- `shapedSurface(spec: ShapedSurfaceSpec): ShapedSurfaceEffect` — Turns a shape prop into a surface your material shades.
- `surfaceField(frame: SurfaceFrame, params: GpuFragmentParams, opts: {scale?: Expr} = {}): SurfaceField` — The first line of a material: the field taps, the signed distance and the pixel size, bound once.
- `geometricNormal(frame: SurfaceFrame, field: SurfaceField, opts: {bevelWidth: Expr; bevelShape: Expr; sharpness?: number; eps?: number; hint?: string}): Expr` — The surface normal of the shape, whichever kind of shape is active.
- `marchedNormal(field: SurfaceField, sharpness: number = 5, hint: string = 'nGeo'): Expr` — The surface normal of a 3D shape, from the marched depth.
- `nudgeNormal(n: Expr, dx: Expr, dy: Expr, hint: string = 'n'): Expr` — Tilts a normal by a slope in x and y, turning a height field into relief.
- `tiltNormal(n: Expr, frame: DirectionFrame, slopes: {along?: Expr; across?: Expr}, hint: string = 'n'): Expr` — Tilts a normal along and across a direction, for brushed or woven relief.
- `tiltAlong(n: Expr, axis: Expr, amount: Expr, hint: string = 'n'): Expr` — Tilts a normal along one 2D direction by a slope amount.
- `fdSlope(sampleAt: (p: Expr) => Expr, p: Expr, eps: number, hint: string = 'fd'): {value: Expr; dx: Expr; dy: Expr}` — The value and slope of any field at a point: `value`, `dx` and `dy`.
- `perlinSlope(q: Expr, gain: Expr | number): Expr` — The slope of smooth noise at a point, for wavy or molten relief.
- `fieldSlope(field: SurfaceField, eps: number = 0.01): Expr` — The direction the shape's distance grows in: a 2D vector pointing outward at this pixel.
- `surfacePattern(frame: SurfaceFrame, field: SurfaceField, opts: {uv?: Expr} = {}): Expr` — Coordinates for a pattern that sticks to the shape's surface.
- `keyLightAt(dir: Expr, elevation: number, hint: string = 'kl'): Expr` — A key light from an angle: the light direction `.L` and the half vector `.H` for highlights.
- `keyLightXY(x: Expr, y: Expr, elevation: number, hint: string = 'kl'): Expr` — A key light from explicit x and y components, for a second or a crossed light.
- `lightVec3(dir: Expr, z: number, hint: string = 'L'): Expr` — A 3D light direction from a `direction()` vector and an elevation.
- `placementPoint(params: GpuFragmentParams, position: Expr, hint: string = 'placed'): Expr` — A position prop in the shape's own coordinates, so you can compare it with the field.
- `pointLightFrom(light: {position: Expr; height: Expr | number}, at: Expr, hint: string = 'pl'): {L: Expr; toLight: Expr; distance: Expr}` — A point light as seen from a point on the shape: the 3D light vector `L`, the 2D direction `toLight` and the `distance`.
- `inverseSquare(distance: Expr, range: Expr | number): Expr` — How a point light fades with distance: 1 at the source, half at `range`.
- `lambert(normal: Expr, light: Expr, opts: {wrap?: Expr | number} = {}): Expr` — How much a light falls on a surface: 0 facing away, 1 facing it.
- `sharpGlint(ndh: Expr, sharpness: Expr, cfg: Expr): Expr` — A highlight whose tightness follows a sharpness slider.
- `dualLobeGlint(ndh: Expr, opts: {
    /** `[exponent, gain]` of the hot core lobe. */
    core: [number, number]
    /** `[exponent, gain]` of the wide halo lobe. */
    halo: [number, number]
    softness?: Expr
    gain: Expr
}): Expr` — A highlight with a tight hot core and a wide dim halo.
- `anisoSpecular(opts: {
    normal: Expr
    /** The 2D grain direction. */
    tangent: Expr
    /** A unit 3D light direction (see `lightVec3`). */
    light: Expr
    view: Expr
    alphas: {along: Expr; across: Expr}
    gain?: Expr | number
}): Expr` — A highlight stretched along a grain, as on brushed metal or carbon fibre.
- `wardAlphas(roughness: Expr | number, anisotropy: Expr | number): {along: Expr; across: Expr}` — Turns roughness and anisotropy sliders (0–1 each) into the two lobe widths `anisoSpecular` takes.
- `viewRay(params: GpuFragmentParams, field: Pick<SurfaceField, 'aspect'>, fov: number = 0.6): Expr` — The direction the viewer looks along at this pixel, for reflections that sweep across a face.
- `grazingOf(n: Expr, view: Expr): Expr` — How edge-on the surface is to the viewer: 0 face-on, 1 grazing.
- `grazingFlat(n: Expr): Expr` — How edge-on the surface is to a straight-on viewer: 0 face-on, 1 grazing.
- `fresnelBoost(grazing: Expr, opts: {power?: number; amount: Expr | number}): Expr` — A multiplier that brightens grazing edges: 1 face-on, up to `1 + amount` at the rim.
- `schlickFresnel(grazing: Expr, opts: {r0?: number; gain: Expr | number; power?: number}): Expr` — How mirror-like a surface is at this pixel: `r0` face-on, rising to `r0 + gain` at the rim.
- `studioSoftboxes(x: Expr, y: Expr, opts: {
    /** A `direction()` vector that rotates the studio. */
    rotation: Expr
    keyRadius: Expr | number
    drift: Expr | number
    strength: Expr | number
    skyGain: number
}): Expr` — The brightness of a five-light studio seen in a reflected direction.
- `smearAlong(opts: {center: Expr; axis: Expr; spread: Expr; taps?: number; sigma?: number; hint?: string}, sample: (x: Expr, y: Expr) => Expr): Expr` — Blurs any 2D lookup along a direction, for streaked reflections and motion smear.
- `opticalThickness(field: SurfaceField, frame: SurfaceFrame): Expr` — How much material the view passes through at this pixel: 0 at the edge, up to about 1.2 deep inside.
- `beerLambert(thickness: Expr, absorb: Expr): Expr` — How much light survives a thickness of tinted material, per channel.
- `cosineRainbow(t: Expr, phases: [number, number, number]): Expr` — A smooth rainbow color from a value that wraps every 1.
- `tintRamp(t: Expr, dark: Expr, light: Expr): Expr` — Maps a lighting value (0 dark, 1 light) onto two colors.
- `neutralTone(rgb: Expr): Expr` — Compresses bright color back into range without shifting its hue.
- `exposureTone(rgb: Expr): Expr` — Turns light that piles past 1 into a soft burn toward white, like film.
- `silhouette(field: SurfaceField, edgeSoftness: Expr): Expr` — The shape's coverage at this pixel: 1 inside, 0 outside, soft across the edge.
- `insideShape(sdf: Expr, pxH: Expr): Expr` — True inside the shape and up to two pixels outside it.
- `guarded(cond: Expr, inner: Expr, fallback: Expr, hint: string = 'guarded', deps: Expr[] = []): Expr` — Evaluates an expression only where a condition holds, and a cheap fallback everywhere else.
- `surfaceNoise(x: Expr | number, y: Expr | number): Expr` — Smooth signed noise at a 2D point, roughly −1 to 1, with features about one unit wide.
- `surfaceNoiseAt(p: Expr): Expr` — `surfaceNoise` at a 2D point you already hold.
- `volumeNoiseAt(p: Expr): Expr` — Smooth signed noise at a 3D point, roughly −1 to 1.
- `cellNoiseAt(p: Expr): Expr` — Cellular noise at a 2D point: 0 at each cell's seed point, rising toward the cell walls.
- `valueNoise(x: Expr | number, y: Expr | number): Expr` — Smooth noise 0–1 at a 2D point, softer and blockier than `surfaceNoise`.
- `hashNoise(x: Expr | number, y: Expr | number): Expr` — Random 0–1 per point, with no smoothness between neighbours.
- `interleavedNoise(pixel: Expr, clock: Expr | number = 0): Expr` — A 0–1 dither pattern over device pixels where neighbours differ as much as possible.
- `grainNoise(coords: {along: Expr; across: Expr}, opts: {freq: [Expr | number, Expr | number]; offset?: [number, number]; drift?: Expr}): Expr` — One octave of smooth signed noise along and across a direction, for grain.
- `flowWarp(warpInput: Expr, flowT: Expr): Expr` — A slowly folding 2D offset to add to pattern coordinates, for molten or wind-blown motion.
- `sensorGrain(rgb: Expr, opts: {amount: Expr | number; pixel: Expr; clock: Expr | number}): Expr` — Adds a fine per-pixel brightness jitter, so rendered light reads as photographed.
- `pointStars(p: Expr, opts: {
    /** Frequency of the per-point variation field relative to `p` (slow, about 0.1). */
    variationFreq: number
    /** Point radius as `[base, jitter]`: base plus variation times jitter. */
    radius: [number, number]
    /** The band of the variation field that keeps a point at all. Narrower is sparser. */
    keep: [number, number]
    /** Brightness as `[base, gain]`: base plus variation squared times gain. */
    brightness: [number, number]
    /** A per-point shimmer factor built from the variation field (see `twinkle`). */
    shimmer?: (variation: Expr) => Expr
    /** Overall gain. */
    gain: Expr
    /** Color the glints: variation mixes `from` to `to`, scaled by the glint times `gain`. */
    tint?: {from: [number, number, number]; to: [number, number, number]; gain: number}
    hint?: string
}): {glint: Expr; variation: Expr; rgb?: Expr}` — A plane of sparse glinting points: stars, glitter, dust.
- `twinkle(t: Expr, phase: Expr, opts: {amount: Expr; rate: number; spread: number}): Expr` — A brightness factor that shimmers over time, different for each element.
- `shellRefract(frame: SurfaceFrame, n: Expr, amount: Expr): {
    x: Expr
    y: Expr
    centered: {x: Expr; y: Expr}
}` — Coordinates for what sits inside a glass shell, bent where the shell curves.
- `rotationSensor(frame: SurfaceFrame): {x: Expr; y: Expr}` — How far a 3D shape has rotated, as a 2D pan you can move content by.
- `nearestEdge(sdfUV: Expr, sdf: Expr, slope: Expr, hint: string = 'edge'): {point: Expr; normal: Expr}` — The closest point on the shape's edge to this pixel, and the outward normal there.
- `continuedField(frame: SurfaceFrame, field: SurfaceField, params: GpuFragmentParams): {sdf: Expr; outward: Expr; at: (uv: Expr) => Expr}` — The distance field extended past the edge of an SVG shape's texture.
- `fdCurvature(sampleAt: (p: Expr) => Expr, p: Expr, eps: number, hint: string = 'fd'): {value: Expr; dx: Expr; dy: Expr; curvature: Expr}` — The value, slope and curvature of any field at a point: `value`, `dx`, `dy` and `curvature`.
- `sheenLobe(opts: {
    normal: Expr
    light: Expr
    view: Expr
    roughness: Expr | number
    gain?: Expr | number
}): Expr` — The soft glow of light scattered off fibres where a surface turns edge-on to the viewer: the velvet sheen on the flanks of satin, velour and wool.

### Volumes (`import {volume} from 'shaders/std'`) — https://shaders.com/docs/primitives/volume

Words for filling a shape with something you look through: smoke, gas, tinted glass, a
starfield behind a window. They work inside a shape-effect material, the `surface:` of
`shapedSurface` from `materials`. An **interior ray** is the line of sight through the shape:
where it enters, how far it travels inside, and where it is at any depth. A **medium** is a
density at each point inside. A **march** walks the ray front to back, adding up what each
sample glows and how much it dims what lies behind it.

- `interiorRay(field: SurfaceField, frame: SurfaceFrame, opts: {origin: {x: Expr; y: Expr}; view?: Expr; shear?: number; lengthScale?: number}): InteriorRay` — The line of sight through a shape: where it enters, how far it travels inside, and where it is at any depth.
- `volumeMarch(opts: {
        steps: number
        entry: Expr
        length: Expr
        /** A per-pixel offset added to each step's position along the ray, as a fraction of the ray. */
        jitter?: Expr
        /** A multiplier on every sample's `emit`. */
        emissionGain?: Expr
        hint?: string
    }, sample: (step: VolumeMarchStep) => {emit: Expr; absorb: Expr}): {color: Expr; transmittance: Expr}` — Walk a ray through the medium front to back, adding up what glows and what dims.
- `turbulentMedium(p: {x: Expr; y: Expr; z: Expr}, opts: {frequency: Expr; drift?: Expr; seed?: Expr; billow?: Expr; hint?: string}): {density: Expr; mid: Expr; fine: Expr}` — A billowing cloud density at a point inside the shape.
- `parallaxPlane(ray: InteriorRay, opts: {depth: number; pan?: {x: Expr; y: Expr}; panRate?: number; hint?: string}): {x: Expr; y: Expr; z: Expr}` — A flat layer at a fixed depth inside the shape, like scenery seen through a window.

### Radiance (`import {radiance} from 'shaders/std'`) — https://shaders.com/docs/primitives/radiance

Words for light a shape gives off or blocks. Colored point lights strike the shape's
silhouette, the lit edges spill light into their surroundings, and the shape's body casts
shadows, so light stays out of a ring's hole and off the far side of a wall. They work inside
a shape-effect material, the `surface:` of `shapedSurface` from `materials`. The shape is a
**signed distance**, a function from a point to its distance from the edge, and every word
here marches rays against it.

- `irradianceField(spec: IrradianceFieldSpec): {
    compute: GpuComputeNode
    sample: (params: GpuFragmentParams) => Expr | undefined
}` — The light spilling from a shape's edges, gathered once into a texture and read per pixel.
- `shadowVisibility(spec: ShadowSpec): Expr` — How much of a light reaches a point, 1 when nothing is in the way and 0 when the shape blocks it.
- `gatherIrradiance(spec: GatherSpec): Expr` — The light arriving at a pixel from a glowing shape edge, with the shape's body blocking it.

### Voxels (`import {voxels} from 'shaders/std'`) — https://shaders.com/docs/primitives/voxels

One word, `voxelSurface`, rebuilds any shape out of blocks. A flat shape becomes chunky
pixel art, an SVG a slab of bricks, a 3D shape a lit voxel model. It asks you for one thing:
the color of a single block. For that it hands your `surface` a **voxel frame**, everything
a material needs already worked out: the block's normal, how open its surroundings are, how
much shadow other blocks cast on it, its cell position, a random number that stays fixed to
that block, how high and how deep it sits, and how close the pixel is to the face's edge.

- `voxelSurface(spec: VoxelSurfaceSpec): ShapedSurfaceEffect` — Rebuild the shape from blocks and shade each block with your `surface`.

## Shapes, frames & warps

### Shapes (`import {shape} from 'shaders/std'`) — https://shaders.com/docs/primitives/shape

The 2D shapes: a circle, a star, a heart and a dozen more, each as a function of a point
that tells you how far that point is from the shape's edge. The number is a **signed
distance**: negative inside, zero on the edge, positive outside. Sizes are in uv, where 1 is
the canvas height.

- `circle(x: Val, y: Val, radius: Val): Expr` — A circle of a given radius.
- `ellipse(x: Val, y: Val, radiusX: Val, radiusY: Val): Expr` — An ellipse with separate horizontal and vertical radii.
- `roundedRect(x: Val, y: Val, width: Val, height: Val, rounding: Val): Expr` — A rectangle with rounded corners.
- `polygon(x: Val, y: Val, radius: Val, sides: Val): Expr` — A regular polygon with any number of sides.
- `star(x: Val, y: Val, outerRadius: Val, sides: Val, innerRatio: Val): Expr` — A star with straight sides and sharp points.
- `flower(x: Val, y: Val, outerRadius: Val, sides: Val, innerRatio: Val): Expr` — A flower with pointed petals and V-shaped valleys between them.
- `heart(x: Val, y: Val, radius: Val): Expr` — A heart, point down at rotation 0.
- `ring(x: Val, y: Val, radius: Val, thickness: Val): Expr` — A ring: a circular band around a centre.
- `arc(x: Val, y: Val, radius: Val, halfAngle: Val): Expr` — A pie wedge: a filled sector of a circle.
- `APERTURE_TO_HALF_ANGLE: 0.008726646259971648` — The factor that turns an opening angle in degrees into the half-angle `arc` takes.
- `vesica(x: Val, y: Val, radius: Val, spread: Val): Expr` — A vesica: the lens where two equal circles overlap.
- `crescent(x: Val, y: Val, outerRadius: Val, innerRatio: Val, offset: Val): Expr` — A crescent: a disc with a smaller disc bitten out of it.
- `teardrop(x: Val, y: Val, radius: Val, height: Val): Expr` — A teardrop: a round bulb tapering to a sharp point, point up at rotation 0.
- `cross(x: Val, y: Val, size: Val, thickness: Val, rounding: Val): Expr` — A plus-shaped cross with four equal arms.
- `trapezoid(x: Val, y: Val, topWidth: Val, bottomWidth: Val, height: Val): Expr` — A trapezoid: a four-sided shape with a flat top and bottom of different widths.
- `parallelogram(x: Val, y: Val, width: Val, height: Val, skew: Val): Expr` — A parallelogram: a rectangle with its top edge slid sideways.

### Frames & coordinates (`import {frames} from 'shaders/std'`) — https://shaders.com/docs/primitives/frames

Frames are how a generator measures its pixels. Instead of raw uv you get named numbers
ready to use: the distance from a centre, how far along and across a line between two
points, or the axes of a chosen direction. `surfaceOf` is the starting point: the canvas's
`uv` (0–1, y down), its size in pixels and its aspect ratio. Every frame is aspect-corrected,
so 1 is the canvas height and a circle stays round on a wide canvas.

- `surfaceOf(params: GpuFragmentParams): {uv: Expr; viewport: Expr; aspect: Expr}` — The canvas a generator paints on: its `uv`, its `viewport` size in pixels and its `aspect`.
- `centredFrame(slots: {center: PropRef}): (params: GpuFragmentParams, surface: { uv: Expr; aspect: Expr; }) => CentredFrame` — A frame centred on a position prop: each pixel's offset from the centre and its distance.
- `segmentFrame(slots: {from: PropRef; to: PropRef}): (params: GpuFragmentParams, surface: { uv: Expr; aspect: Expr; }) => SegmentFrame` — A frame along the line between two position props: how far each pixel is along it and across it.
- `direction(angleDeg: Expr | number, hint: string = 'dir'): Expr` — A direction in degrees as a unit vector.
- `directionFrame(angleDeg: Expr | number, hint: string = 'grain'): DirectionFrame` — The two axes of a direction given in degrees, for patterns that run along it.
- `sectorFold(x: Expr, y: Expr, sectorAngle: Expr, center: number = 0.5): Expr` — Fold a point into one mirrored wedge around a centre: the kaleidoscope fold.
- `rawSurfaceOf(params: GpuFragmentParams): {uv: Expr; viewport: Expr; aspect: Expr}` — The canvas like `surfaceOf`, but always measured against the whole canvas, never a fitted box.

### Warps (`import {warps} from 'shaders/std'`) — https://shaders.com/docs/primitives/warps

Words for the `map:` field. A **warp** is a component that moves the pixels of the layer
inside it (the child): for every pixel on screen, the map says where in the child to look.
Twisting, bulging, mirroring, tilting and wiping are all warps. Positions are in uv (0–1
across the canvas, y down) and angles are in degrees.

- `twirl(slots: {center: ArgSpec; intensity: ArgSpec}): UvMapSource` — Twist the child around `center`, turning more the farther a pixel is from it.
- `bulge(slots: {center: ArgSpec; strength: ArgSpec; radius: ArgSpec; falloff: ArgSpec}): UvMapSource` — Magnify or pinch the child inside a disc around `center`.
- `mirrorLine(slots: {center: ArgSpec; angle: ArgSpec}): UvMapSource` — Mirror the child across a line through `center` at `angle`.
- `flip(slots: {flipX: ArgSpec; flipY: ArgSpec}): UvMapSource` — Flip the child horizontally, vertically, or both.
- `kaleidoscope(slots: {center: ArgSpec; segments: ArgSpec; angle: ArgSpec}): UvMapSource` — Fold the child into mirrored pie slices around `center`.
- `perspective(slots: {
    center: ArgSpec
    pan: ArgSpec
    tilt: ArgSpec
    fov: ArgSpec
    zoom: ArgSpec
    offset: ArgSpec
}): UvMapSource` — Tilt the child in 3D, as if it were a card turned away from the camera.
- `cornerPin(slots: {
    topLeft: ArgSpec
    topRight: ArgSpec
    bottomRight: ArgSpec
    bottomLeft: ArgSpec
    amount: ArgSpec
}): UvMapSource` — Pin the four corners of the child to new positions, with true perspective between them.
- `bend(slots: {strength: ArgSpec; falloff: ArgSpec; angle: ArgSpec}): UvMapSource` — Curve the child like a bent sheet seen in perspective, so its ends swell or shrink.
- `stretch(slots: {center: ArgSpec; strength: ArgSpec; angle: ArgSpec; falloff: ArgSpec}): UvMapSource` — Stretch the child along one direction, starting at `center`.
- `wave(slots: {strength: ArgSpec; frequency: ArgSpec; angle: ArgSpec; waveType: PropRef}): UvMapSource` — Ripple the child with a travelling wave.
- `flowNoise(slots: {strength: ArgSpec; detail: ArgSpec; seed: PropRef}): UvMapSource` — Push the child around with a slowly flowing liquid motion.
- `toPolar(slots: {center: ArgSpec; wrap: ArgSpec; radius: ArgSpec; intensity: ArgSpec}): UvMapSource` — Unroll the child around `center`, so angle becomes x and distance becomes y.
- `fromPolar(slots: {center: ArgSpec; scale: ArgSpec; intensity: ArgSpec}): UvMapSource` — Wrap the child into a circle around `center`, reading its x as angle and its y as distance.
- `concentricRings(slots: {
    center: ArgSpec
    intensity: ArgSpec
    rings: ArgSpec
    smoothness: ArgSpec
    seed: ArgSpec
    speedRandomness: ArgSpec
}): UvMapSource` — Cut the child into rings around `center` and spin each ring by its own amount.
- `barOffset(slots: {count: ArgSpec; angle: ArgSpec; intensity: ArgSpec; seed: ArgSpec}): UvMapSource` — Cut the child into parallel bars and shift each one sideways by a random amount.
- `slicedSlide(slots: {angle: ArgSpec; count: ArgSpec; progress: ArgSpec}): UvMapSource` — Slice the child into strips that slide out of frame in alternating directions.
- `liquidDisplace(slots: {intensity: ArgSpec; output: string}): UvMapSource` — Move the child smoothly by a displacement field your own simulation produces.
- `gridCellDisplace(slots: {gridSize: ArgSpec; output: string}): UvMapSource` — Move the child by a displacement field your own simulation produces, one grid cell at a time.
- `displaceByLayer(slots: {
    source: PropRef
    amount: ArgSpec
    channels: PropRef
    angle: ArgSpec
    edges: PropRef
}): GatherEffect` — Distort the child using another layer's pixels as a displacement map.

### Masks (`import {mask} from 'shaders/std'`) — https://shaders.com/docs/primitives/mask

A mask is coverage: a number from 0 to 1 at every pixel that says how much of something
shows there. Multiply it into a color's alpha to cut a shape out of a paint, or hand it to
an effect as its amount so the effect fades in across the canvas. Most masks start from a
distance, how far this pixel is from a center, a line or a shape's edge, and the mask word
turns that distance into an edge. `softDisc` and `softBand` give soft, styled edges for orbs
and curtains. `crispFill` and `crispStroke` give clean anti-aliased fills and outlines from a
signed distance, such as one of the `shape` words. `radialMask` is the ready-made one for
effects: 0 at a center, 1 past a radius, plugged straight into an effect's amount.

- `radialMask(slots: {center: PropRef; radius: PropRef; falloff: PropRef}): Scalar` — An amount that is 0 near a center and grows to 1 with distance, for an effect's strength.
- `softDisc(opts: {
    dist: Expr
    radius: Expr | number
    softness: {width: Expr | number; curve: Expr | number}
}): Expr` — A filled disc with a soft, shaped edge.
- `crispFill(opts: {distance: Expr; footprint: Expr | number}): Expr` — A clean fill of a shape: 1 inside, 0 outside.
- `crispStroke(opts: {distance: Expr; width: Expr | number; footprint: Expr | number}): Expr` — A clean outline of a shape, or a drawn curve, of a given width.
- `softBand(opts: {
    distance: Expr
    below: {from: Expr | number; to: Expr | number}
    above: {from?: Expr | number; to: Expr | number}
}): Expr` — A soft band around a line, sharp on one side and long on the other.

### Math (`import {math} from 'shaders/std'`) — https://shaders.com/docs/primitives/math

The arithmetic you write your own paint with. Every word takes expressions or plain numbers
and returns an expression the GPU works out once per pixel: `mul(color, coverage)` fades a
color, `smoothstep(a, b, dist)` turns a distance into a soft mask, `mix(a, b, t)` blends two
colors. Props reach you as `params.uniforms.<name>` (or `uniformOf(p('name'), params)`), a
frame gives you the coordinate, and the words compose by nesting until you return a `vec4`
color from `paint:`. Wrap anything you read twice in `local` so it is computed once.

- `add(a: Val, b: Val): Expr` — The sum of two values.
- `sub(a: Val, b: Val): Expr` — The first value minus the second.
- `mul(a: Val, b: Val): Expr` — The product of two values.
- `div(a: Val, b: Val): Expr` — The first value divided by the second.
- `mix(a: Val, b: Val, t: Val): Expr` — A blend from `a` to `b` by `t`, where 0 gives `a` and 1 gives `b`.
- `smoothstep(e0: Val, e1: Val, x: Val): Expr` — A soft edge: 0 below `e0`, 1 above `e1`, an S-curve between.
- `clamp(x: Val, lo: Val, hi: Val): Expr` — The value limited to the range `lo`..`hi`.
- `local(e: Expr, hint: string): Expr` — A value computed once per pixel and shared by everything that reads it.
- `vec4(...parts: Val[]): Expr` — A 4D vector, usually the final color with alpha.
- `vec3(x: Val, y: Val, z: Val): Expr` — A 3D vector from three values, often a color without alpha.
- `vec2(x: Val, y: Val): Expr` — A 2D vector from two values.
- `splat3(x: Val): Expr` — One number copied into all three channels of a vec3.
- `length(v: Val): Expr` — The length of a vector.
- `distance(a: Val, b: Val): Expr` — The distance between two points.
- `abs(x: Val): Expr` — The value without its sign.
- `fract(x: Val): Expr` — The fractional part of a value, 0..1.
- `floor(x: Val): Expr` — The value rounded down to a whole number.
- `min(a: Val, b: Val): Expr` — The smaller of two values.
- `max(a: Val, b: Val): Expr` — The larger of two values.
- `sin(x: Val): Expr` — The sine of an angle in radians, −1..1.
- `cos(x: Val): Expr` — The cosine of an angle in radians, −1..1.
- `step(edge: Val, x: Val): Expr` — A hard edge: 0 when `x` is below `edge`, 1 from `edge` on.
- `pow(x: Val, y: Val): Expr` — The first value raised to the power of the second.
- `exp(x: Val): Expr` — e raised to the value.
- `sqrt(x: Val): Expr` — The square root of a value.
- `neg(a: Val): Expr` — The value with its sign flipped.
- `select(cond: Expr, ifTrue: Val, ifFalse: Val): Expr` — `ifTrue` when the condition holds, otherwise `ifFalse`.
- `lt(a: Val, b: Val): Expr` — True when `a` is less than `b`.
- `gt(a: Val, b: Val): Expr` — True when `a` is greater than `b`.
- `le(a: Val, b: Val): Expr` — True when `a` is less than or equal to `b`.
- `ge(a: Val, b: Val): Expr` — True when `a` is greater than or equal to `b`.
- `atan2(y: Val, x: Val): Expr` — The angle of the point (x, y) in radians, −π..π.
- `dot(a: Val, b: Val): Expr` — The dot product of two vectors.
- `normalize(v: Val): Expr` — The vector scaled to length 1.
- `rotate2(p: Val, cosA: Val, sinA: Val): Expr` — A 2D point rotated around the origin.
- `gaussBell(x: Expr, k: Val): Expr` — A bell curve: 1 at zero, falling toward 0 on both sides.
- `softPlus(x: Expr, k: Val): Expr` — A soft hinge: about 0 for values well below zero, about `x` above, rounded near zero.
- `hashPhase(seed: Val, salt: {k: number; big: number}): Expr` — A random but stable angle in radians, 0..2π, from a seed.
- `sign(x: Val): Expr` — −1, 0 or 1 by the sign of the value.
- `ceil(x: Val): Expr` — The value rounded up to a whole number.
- `log(x: Val): Expr` — The natural logarithm of a value.
- `exp2(x: Val): Expr` — 2 raised to the value.
- `tan(x: Val): Expr` — The tangent of an angle in radians.
- `cross(a: Val, b: Val): Expr` — The cross product of two 3D vectors.
- `reflect(i: Val, n: Val): Expr` — The direction `i` bounced off a surface with unit normal `n`.
- `refract(i: Val, n: Val, eta: Val): Expr` — The direction `i` bent through a surface with unit normal `n`.
- `float(n: number): Expr` — A plain number as an expression.

### Motion & timing (`import {motion} from 'shaders/std'`) — https://shaders.com/docs/primitives/motion

Words that turn a clock into rhythm. The clock is a number of seconds: declare
`animatedTime: {speed: 'speed'}` on the definition and read the layer's clock with
`animatedTime(params)`, and a speed prop and a pause button come for free. `cycle` splits
that clock into "which pass is this" and "how far through it are we", `cycleSeed` gives each
pass a stable random number, `oscillate` and `pulseTrain` shape it into a sweep or a blink,
and the easings bend a 0..1 progress. The result is a number you multiply into a color, a
radius or a coordinate.

- `oscillating(opts: {rate?: number; min?: Expr | number; max?: Expr | number; offset?: number; clock?: SignalClock}): Scalar` — A knob that sweeps between `min` and `max` on its own, for any slot that takes a prop.
- `pulsing(opts: {period: number; duty: number; soften?: number; clock?: SignalClock}): Scalar` — A knob that switches on and off in a rhythm, for any slot that takes a prop.
- `cycle(t: Expr, period: Expr | number): {progress: Expr; index: Expr}` — A repeating cycle as two numbers: `progress` (0..1 through the current cycle) and `index` (which cycle this is).
- `cycleSeed(index: Expr, salt: number = 0): Expr` — A random but stable number, 0..1, for each cycle index.
- `oscillate(t: Expr, opts: {rate?: number; min?: Expr | number; max?: Expr | number; offset?: number}): Expr` — A smooth back-and-forth between `min` and `max`.
- `pulseTrain(t: Expr, opts: {period: Expr | number; duty: Expr | number; soften?: number}): Expr` — An on/off rhythm: 1 for the first part of each cycle, 0 for the rest.
- `phase(t: Expr, period: Expr | number): Expr` — How far through a repeating cycle the clock is, 0..1.
- `easeInOut(x: Expr): Expr` — A 0..1 value that starts slow, speeds up, and slows again at the end.
- `easeOut(x: Expr): Expr` — A 0..1 value that starts fast and slows to a stop.
- `easeIn(x: Expr): Expr` — A 0..1 value that starts slow and speeds up.
- `flashes(t: Expr, opts: {rate: Expr | number; offset?: Expr | number; sharpness: 2 | 4 | 8 | 16}): Expr` — Short, bright flashes at a steady rate: dark most of the time, peaking briefly to 1.

### Signals (`import {signal} from 'shaders/std'`) — https://shaders.com/docs/primitives/signal

Live inputs a simulation reads every frame: where the pointer is and how fast it is moving.
You never read the numbers yourself. You hand a signal to a simulation step, such as the
splat step of a grid simulation, and the engine tracks the pointer, measures its speed in
uv per second, and feeds both in. `pointer` carries one choice, the teleport guard, which
stops a cursor that jumps into the canvas from slamming the field. `pointerSpeed` caps the
speed so a fast flick cannot overdrive it. Both are also exported at the top level of
`shaders/std`.

- `pointer(opts?: {teleportGuard?: 'on' | 'off'}): PointerSignal` — The pointer's position, for a simulation step that reacts to the cursor.
- `pointerSpeed(opts?: {max?: number}): PointerSpeedSignal` — The pointer's speed, capped at `max`, as the strength of a simulation step.
- `cpuHash01(x: number): number` — A random but stable number, 0..1, from a seed, computed in JavaScript.

## Filters & effects

### Filter effects (`shaders/std` top level) — https://shaders.com/docs/primitives/filter

Words for the `effect:` field. A **filter** is a component that changes the layer inside it
(the child). A definition with an `effect:` is a filter, nothing else to declare.

- `tintToward(color: PropRef, opts: {amount: ScalarInput}): TintTowardEffect` — Mix the child's color toward one color by an amount, leaving its alpha alone.
- `paintThrough(paint: Paint, opts: {by?: 'alpha' | 'luminance'} = {}): PointwiseEffect` — Show a paint through the child, so the child becomes the mask.
- `displaceBy(field: import('./sim').SimOutputRef, opts: {strength: PropRef; chromatic: PropRef; edges: PropRef}): DisplaceByEffect` — Push the child's pixels around by a vector field from one of your simulations.
- `pointwise(config: Omit<PointwiseEffect, 'kind'>): PointwiseEffect` — Write your own pointwise effect: a function of the child's color at this pixel.
- `gather(config: Omit<GatherEffect, 'kind'>): GatherEffect` — Write your own gather effect: a function that can read the child anywhere.

### Color effects (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.color

Words that recolor the layer inside them, one pixel at a time. Each returns a **pointwise
effect** for a filter definition's `effect:` field: it reads the child's color at this pixel
and returns the adjusted color, with alpha kept. Nothing is sampled from neighbouring
pixels, so these filters are cheap and stack freely. Pass props with `p('name')`; the units
are the ones the word names (degrees, 0–1 amounts, a multiplier around 1).

- `saturate(intensity: ArgSpec): PointwiseEffect` — Scale the child's saturation.
- `vibrance(intensity: ArgSpec): PointwiseEffect` — Boost muted colors while leaving already-vivid ones mostly alone.
- `hueRotate(shift: ArgSpec): PointwiseEffect` — Rotate the child's hue around the color wheel.
- `brightnessContrast(slots: {brightness: ArgSpec; contrast: ArgSpec}): PointwiseEffect` — Adjust the child's brightness and contrast together.
- `exposure(gain: ArgSpec): PointwiseEffect` — Multiply the child's brightness, like opening a camera's aperture.
- `grayscale(): PointwiseEffect` — Turn the child black and white, weighted the way the eye sees brightness.
- `invert(): PointwiseEffect` — Flip every color of the child to its negative.
- `solarize(slots: {threshold: ArgSpec; strength: ArgSpec}): PointwiseEffect` — Invert only the bright parts of the child, the darkroom solarization look.
- `posterize(steps: ArgSpec): PointwiseEffect` — Reduce the child to a few flat color levels, like a screen-printed poster.
- `tint(slots: {color: PropRef; amount: ArgSpec; preserveLuminosity: PropRef}): PointwiseEffect` — Wash the child toward one color.
- `duotone(slots: {colorA: PropRef; colorB: PropRef; blend: ArgSpec; colorSpace: PropRef}): PointwiseEffect` — Repaint the child in two colors: `colorA` for the shadows, `colorB` for the highlights.
- `tritone(slots: {colorA: PropRef; colorB: PropRef; colorC: PropRef; blendMid: ArgSpec; colorSpace: PropRef}): PointwiseEffect` — Repaint the child in three colors: `colorA` for the shadows, `colorB` for the midtones, `colorC` for the highlights.
- `gradientMap(slots: {
    palette: PropRef
    colorLow: PropRef
    colorMid: PropRef
    colorHigh: PropRef
    speed: PropRef
    contrast: ArgSpec
    blackPoint: ArgSpec
    whitePoint: ArgSpec
    strength: PropRef
    colorSpace: PropRef
}): PointwiseEffect` — Recolor the child by its brightness through a gradient, the Photoshop gradient map.
- `filmGrain(slots: {strength: ArgSpec; bias: ArgSpec; animated: PropRef}): PointwiseEffect` — Sprinkle film grain over the child, heaviest in the shadows.
- `isolines(slots: {
    source: PropRef
    levels: ArgSpec
    lineWidth: ArgSpec
    softness: ArgSpec
    gamma: ArgSpec
    invert: ArgSpec
    colorMode: PropRef
    lineColor: PropRef
    backgroundColor: PropRef
}): PointwiseEffect` — Draw topographic contour lines over the child, traced from its brightness or its alpha.
- `lutAtlasGrade(slots: {
    select: PropRef
    strength: PropRef
    size: number
    decode: (key: string) => Uint8Array
    fallback: string
    label: string
}): (color: Expr, params: FilterParams | GpuFragmentParams) => Expr` — Grade a color through a measured 3D color lookup table (LUT), the film-stock look.

### Blurs, glows & screens (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.blurs

Effects that read the layer inside them (the child) as a texture and rebuild it: blurs, glows,
sharpening, pixelation, shadows, retro screens, glitches, fluted glass, page peels and mirror
floors. A **pointwise** effect edits the child's color at one pixel; the words here are
**gather** effects, which sample the child at other pixels too, so they can smear, spread and
displace it. Every word here goes in a filter definition's `effect:` field, or spreads into a
definition when it needs its own pass over the child first.

- `gaussianBlur(opts: {intensity: PropRef}): ComputeBackedEffect` — A soft, even blur of the child.
- `motionBlur(opts: {path: BlurPathSpec; amount: ArgSpec; detail?: MotionBlurDetailSlots}): GatherEffect` — Smears the child along a path: a straight streak, an arc around a point, or a zoom out of a point.
- `progressiveBlur(opts: {
    intensity: PropRef
    angle: PropRef
    center: PropRef
    falloff: PropRef
    detail?: VariableBlurDetailSlots
}): ComputeBackedEffect` — A blur that ramps from sharp to full strength in one direction across the child.
- `tiltShift(opts: {
    intensity: PropRef
    width: PropRef
    falloff: PropRef
    angle: PropRef
    center: PropRef
    detail?: VariableBlurDetailSlots
}): ComputeBackedEffect` — Keeps a band of the child in focus and blurs everything beyond it, like a tilt-shift lens.
- `bloom(opts: {intensity: PropRef; threshold: PropRef; size: PropRef}): ComputeBackedEffect` — A glow: the child's bright parts spread into a soft halo that adds back on top.
- `bokehDefocus(opts: {
    radius: PropRef
    gain: PropRef
    threshold: PropRef
    shape: PropRef
    blades: PropRef
    rotation: PropRef
    fringe: PropRef
    catEye?: PropRef
}): {compute: GpuComputeNode; gpu: {fragment: (params: GpuFragmentParams) => Expr}}` — A photographic lens blur where bright highlights bloom into aperture-shaped discs.
- `channelBlur(opts: {red: PropRef; green: PropRef; blue: PropRef}): ComputeBackedEffect` — Blurs red, green and blue by separate amounts, for a soft chromatic fringe.
- `scatter(opts: {amount: ArgSpec; edges: PropRef; chromatic?: PropRef}): GatherEffect` — Scatters every pixel of the child by a random offset: a grainy diffusion, not a smooth blur.
- `sharpen(amount: ArgSpec): GatherEffect` — Sharpens the child by boosting the contrast between each pixel and its neighbours.
- `pixelate(opts: {scale: ArgSpec; gap: ArgSpec; roundness: ArgSpec}): GatherEffect` — Turns the child into a grid of flat cells, each showing one color.
- `gatherStack(sample: SampleStage, overlays: OverlayStage[], opts?: {resultAlpha?: 'premultiplied' | 'straight'}): GatherEffect` — Assemble an effect from one sampling stage and an ordered list of overlay stages.
- `childTap(): SampleStage` — The child's own color at this pixel, unchanged.
- `shadowOffset(opts: {angle: ArgSpec; distance: ArgSpec}): (params: RttFilterParams) => Expr` — The coordinate a shadow reads the child's silhouette from: `distance` away in the compass direction `angle`.
- `silhouetteCoverage(opts: {at: (params: RttFilterParams) => Expr; blur: ArgSpec}): (params: RttFilterParams) => Expr` — A soft copy of the child's alpha silhouette: a number per pixel from 0 to 1.
- `shadowComposite(opts: {
    coverage: (params: RttFilterParams) => Expr
    color: PropRef
    intensity: ArgSpec
    cutout: PropRef
}): OverlayStage` — A tinted shadow behind the child.
- `rgbSplit(opts: {amount: ArgSpec}): SampleStage` — The child with its red and blue pulled a little to either side, like a misaligned CRT.
- `adjust(opts: {brightness: ArgSpec; contrast: ArgSpec}): OverlayStage` — Brightness and contrast, pivoting around mid-grey.
- `scanlines(opts: {frequency: ArgSpec; intensity: ArgSpec}): OverlayStage` — Horizontal scanlines darkening the child in a smooth wave.
- `phosphorMask(opts: {pitch: ArgSpec}): OverlayStage` — A faint red, green and blue phosphor stripe pattern across the child.
- `vignetteOverlay(opts: {radius: ArgSpec; intensity: ArgSpec}): OverlayStage` — Darkens the child toward its corners.
- `opaque(): OverlayStage` — Closes a three-channel stack as a solid color with alpha 1.
- `tapeWarp(opts: {wobble: ArgSpec; jitter: ArgSpec; speed: ArgSpec}): (params: RttFilterParams) => Expr` — The wobbling, jittering coordinates of a worn VHS tape, to feed into `chromaSmearTaps`.
- `chromaSmearTaps(opts: {warp: (params: RttFilterParams) => Expr; smear: ArgSpec}): SampleStage` — The child sampled like a VHS deck: brightness stays sharp while color bleeds sideways.
- `beatPulse(opts: {wobble: ArgSpec; speed: ArgSpec}): OverlayStage` — A faint brightness throb, like the mains hum of an old television.
- `glitchFrame(opts: {
    intensity: ArgSpec
    speed: ArgSpec
    blockDensity: ArgSpec
    mirrorAmount: ArgSpec
}): GatherFrame` — The shared geometry of a digital glitch: when bursts fire, which horizontal bands jitter, and which blocks shift or flip.
- `glitchRgbSplit(frame: GatherFrame, opts: {shift: ArgSpec}): SampleStage` — The child sampled through a glitch frame, with red and blue pulled apart inside the active bands.
- `colorBarFills(frame: GatherFrame, opts: {intensity: ArgSpec}): OverlayStage` — Neon color bars filling the blocks a glitch frame currently has active.
- `distortedScanlines(frame: GatherFrame, opts: {intensity: ArgSpec}): OverlayStage` — CRT-style scanlines that appear only where a glitch frame is currently distorting.
- `sphereFrame(opts: {center: ArgSpec; radius: ArgSpec; depth: ArgSpec}): GatherFrame` — 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.
- `crispTap(frame: GatherFrame): SampleStage` — One clean sample of the child at a frame's warped coordinate.
- `rimLit(frame: GatherFrame, opts: {
    position: ArgSpec
    intensity: ArgSpec
    softness: ArgSpec
    color: PropRef
}): OverlayStage` — A tinted rim of light around the edge of a bulged surface, added on top of the child's color.
- `fluteFrame(opts: {
    shape: PropRef
    angle: ArgSpec
    frequency: ArgSpec
    softness: ArgSpec
    waveAmplitude: ArgSpec
    waveFrequency: ArgSpec
    refraction: ArgSpec
    aberration: ArgSpec
}): GatherFrame` — 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.
- `refractedTaps(frame: GatherFrame, opts: {aberration: PropRef; edges: PropRef}): SampleStage` — The child seen through a flute frame, with edge handling and a color split when `aberration` is above 0.
- `fluteHighlight(frame: GatherFrame, opts: {
    lightAngle: ArgSpec
    highlight: ArgSpec
    softness: ArgSpec
    color: PropRef
}): OverlayStage` — A specular highlight running along each flute, added on top of the child's color.
- `peelFrame(opts: {corner: PropRef; amount: ArgSpec; radius: ArgSpec}): GatherFrame` — 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.
- `peelCompose(frame: GatherFrame, parts: {
    shade: PeelShade
    sheen: PeelShade
    overhang: PeelShade
    reveal: PeelShade
}): SampleStage` — A finished page peel: the cast shadows, the flat page and the lit curl, layered back to front.
- `curlShading(frame: GatherFrame, opts: {shading: ArgSpec}): PeelShade` — The darkening in the crook of a curl, easing to full brightness at the lip.
- `curlSheen(frame: GatherFrame, opts: {highlight: ArgSpec; softness: ArgSpec}): PeelShade` — The band of light running up a curl.
- `overhangShadow(frame: GatherFrame, opts: {amount: ArgSpec; shadow: ArgSpec}): PeelShade` — The shadow a lifted curl casts on the flat page just past the crease.
- `revealShadow(frame: GatherFrame, opts: {amount: ArgSpec; shadow: ArgSpec}): PeelShade` — The shadow on the surface a peel reveals, just inside the crease.
- `mirrorAcrossRow(line: PropRef): (params: GpuFragmentParams) => Expr` — The coordinate mirrored across a horizontal line, for reading a reflection below it.
- `depthRampBlur(opts: {line: PropRef; blur: PropRef; blurDistance: PropRef; halfKernel: number}): {compute: GpuComputeNode}` — The blur half of a mirror floor: blurs the child more the further a row sits below the line.
- `planarReflection(opts: {line: PropRef; distance: PropRef; falloff: PropRef; edges: PropRef}, original: Expr, reflection: (uv: Expr) => Expr, reflectedUV: (params: GpuFragmentParams) => Expr): (params: GpuFragmentParams) => Expr` — A mirror floor: the child as it is above a line, and its reflection fading out below it.
- `screenedBloom(slots: {
    strength: PropRef
    radius: PropRef
    tint: [number, number, number]
    threshold: number
    output: string
    extractName: string
}): {
    compute: GpuComputeNode
    screen: (base: Expr, at: Expr, params: GpuFragmentParams) => Expr
}` — A tinted glow of the child's bright parts, screened over a color you have already graded: film halation, phosphor bloom.
- `frameSway(slots: {amount: PropRef; field: string}): (params: GpuFragmentParams) => Expr` — A slight drifting shift and rotation of where the child is read from, like film in an unsteady projector gate.
- `blurPath.linear(angle: PropRef): BlurPathSpec` — A straight streak along an angle prop, in degrees (0 points right, 90 points down).
- `blurPath.orbit(center: PropRef): BlurPathSpec` — An arc streak rotating around a center prop (a position in uv).
- `blurPath.zoom(center: PropRef): BlurPathSpec` — A radial streak rushing outward from a center prop (a position in uv).
- `brightestNear(read: (uv: Expr) => Expr, center: Expr, opts: {radius: Expr; taps: number; angle?: number}): {
    color: Expr
    luma: Expr
}` — 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.

### Stylize (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.stylize

Hand-made looks for the layer inside: a watercolor wash, a chalk drawing on a board, ASCII
characters, and copper-plate line engraving. Each look is a recipe of two or three words. A
**stage** is one piece of the look that reads the layer once it is rendered to a texture (a
wobbled sample position, a brush, a ring of edge samples, a character grid). Build a stage once
and hand the same one to every word that needs it, so they agree. The closing word (`wash`,
`chalkSketch`, `linework`) returns the effect for `effect:`. The ASCII look closes with
`glyphTint`, which returns a fragment for `gpu.fragment` because it also needs a character
atlas drawn on the CPU.

- `wash(slots: {
    at: GatherStage
    brush: KuwaharaBrush
    grain: GatherStage
    paper: PropRef
    paperColor: PropRef
    strength: PropRef
}): GatherEffect` — The watercolor look: the layer inside flattened into soft patches of color over paper grain.
- `kuwahara(slots: {at: GatherStage; radius: PropRef}): KuwaharaBrush` — A painter's brush: the flattening that turns fine detail into soft patches of one color.
- `bleedWarp(slots: {amount: PropRef}): GatherStage` — A sample position that drifts slowly past hard edges, so paint bleeds instead of stopping.
- `paperGrain(slots: {amount: PropRef}): GatherStage` — Fine paper grain for the pigment to settle into, one brightness value per screen pixel.
- `chalkSketch(slots: {
    edges: SobelRing
    sensitivity: PropRef
    hatchScale: PropRef
    shading: PropRef
    grain: PropRef
    board: PropRef
    chalk: PropRef
}): GatherEffect` — The chalk-drawing look: edges become chalk strokes and dark areas fill with cross-hatching.
- `sobelTaps(slots: {spacing: PropRef}): SobelRing` — Eight brightness samples in a ring around each pixel, for finding edges.
- `linework(slots: {
    style: PropRef
    frequency: PropRef
    angle: PropRef
    center: PropRef
    relief: PropRef
    waviness: PropRef
    contrast: PropRef
    ink: PropRef
    paper: PropRef
}): GatherEffect` — The engraving look: the layer inside redrawn as ink lines that swell where it is dark.
- `glyphTint(slots: {
    grid: FragmentStage
    cell: FragmentStage
    glyph: FragmentStage
    alphaThreshold: PropRef
    preserveAlpha: PropRef
}): FragmentStage` — The finished ASCII look: each character tinted with its cell's color, everything else transparent.
- `glyphFor(slots: {
    grid: FragmentStage
    cell: FragmentStage
    gamma: PropRef
    atlas: (params: GpuFragmentParams) => KitTexture
}): FragmentStage` — The character drawn in each cell, picked by how bright the cell is.
- `charGrid(slots: {cellSize: PropRef; spacing: PropRef}): FragmentStage` — The character grid: which cell each pixel falls in, and where it sits inside that cell.
- `cellSample(slots: {grid: FragmentStage}): FragmentStage` — The color of the layer inside at the centre of each character cell.

### Lens (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.lens

Words for the color fringing a real lens leaves behind: the red, green and blue copies of
the layer inside pushed apart, or fanned out into a whole spectrum. Because they read the
child at several places per pixel, these are **gather effects**: the child is rendered to a
texture first and the effect samples it. `chromaticFan` is a sampling stage; hand it to
`gatherStack` (from `effects.blurs`) to turn it into the `effect:` of a filter definition,
optionally followed by more stages. `spectralLens` is a complete fragment for a `gpu:`
definition, with the lens warp, focus zones and grain built in.

- `chromaticFan(opts: {
    strength: ArgSpec
    angle: ArgSpec
    red: ArgSpec
    green: ArgSpec
    blue: ArgSpec
}): SampleStage` — Split the child into red, green and blue copies pushed apart along one direction.
- `spectralLens(slots: SpectralLensSlots): (params: GpuFragmentParams) => Expr` — Fan the child out into many color-shifted copies through a warped lens, the spectral-lens look.

### Reveals & wipes (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.reveal

Words that make the layer inside disappear in a chosen order: a straight edge, a growing
circle, a clock sweep, a grid of blocks, a noise dissolve. Every wipe is the same effect,
`reveal`, fed a different **coverage**: a number per pixel from 0 to 1 that says when that
pixel goes (0 first, 1 last). As the `progress` prop climbs from 0 to 1, pixels whose
coverage falls below it fade out across a soft front `feather` wide.

- `reveal(slots: RevealSlots): PointwiseEffect` — Fade the child away in coverage order as `progress` goes from 0 to 1.
- `coverage.directional(angleDeg: ArgSpec): Coverage` — A straight edge sweeping across the canvas.
- `coverage.radial(center: ArgSpec): Coverage` — A circle growing out from `center`, an iris wipe.
- `coverage.angular(center: ArgSpec, startDeg: ArgSpec, direction: PropRef | AngularDirection): Coverage` — A clock hand sweeping around `center`.
- `coverage.cells(size: ArgSpec): CellCoverage` — A grid of square cells `size` wide.
- `coverage.noise(scale: ArgSpec, seed: ArgSpec): Coverage` — Soft blobs eating the image away, the classic film dissolve.
- `class Coverage` — The order pixels disappear in: a number per pixel from 0 (goes first) to 1 (goes last).
- `class BandedCoverage` — A coverage cut into bands.
- `class CellCoverage` — The canvas cut into a grid of square cells, waiting for you to pick the order the cells go in.

### Instances (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.instances

Repeat the layer inside. `repeatInstances` draws many copies of it, laid out in a grid, around
a circle or along a line, each copy scaled, turned, faded and jittered a little more than the
last. It returns the fragment for `gpu.fragment`. The layout words (`grid`, `radial`, `line`)
say where the copies go, `byMode` lets one select prop switch between all three, and the
recipe's `variation` object says how the copies differ.

- `repeatInstances(recipe: RepeatInstancesRecipe): (params: GpuFragmentParams) => Expr` — Many copies of the layer inside, laid out and varied as the recipe says.
- `grid(slots: GridSlots): PlacementSpec` — Copies in rows and columns, filling this layer's bounding box.
- `radial(slots: RadialSlots): PlacementSpec` — Copies around a circle centred on the layer inside.
- `line(slots: LineSlots): PlacementSpec` — Copies in a row, marching away from the layer inside in one direction.
- `byMode(mode: PropRef, members: PlacementPick['members']): PlacementPick` — Lets one select prop switch between a grid, a radial and a linear layout.

### Fracture (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.fracture

Broken glass. The canvas splits into **shards** around a set of random sites; a pixel belongs
to the nearest site. Where a shard has moved, a **crack** opens along its border with the
next-nearest shard, and the layer inside bends and colour-splits across it like light through
a prism. `voronoiRegionField` is the compute hook (for `compute:`) that finds each pixel's
shard and the next-nearest one; it only recomputes when the seed changes. The crack words run
in the fragment: `crackGeom` measures the crack at a pixel, `crackRefractUV` bends one colour
channel across it, and `crackShardCompose` joins the three channels with a little light on
tilted shards.

- `voronoiRegionField(opts: {
    count: number
    size: number
    sites: (seed: number) => Float32Array
    seedProp: string
    seedDefault: number
    output: string
}): GpuComputeNode` — Splits the canvas into shards around random sites and records, per pixel, its shard and the next-nearest one.
- `crackGeom(uv: v2f, nPosX: number, nPosY: number, sPosX: number, sPosY: number, dispX: number, dispY: number, crackWidth: number): { crackIntensity: number; edgeNormal: v2f; displacedUV: v2f; disp: v2f; }` — How much crack there is at a pixel, and which way the shard under it has moved.
- `crackRefractUV(displacedUV: v2f, edgeNormal: v2f, crackIntensity: number, refractionStrength: number, chromaticSplit: number, channel: number): v2f` — Where to sample one color channel so the crack bends the light and splits it like a prism.
- `crackShardCompose(normalColor: v4f, rFinal: v4f, gFinal: v4f, bFinal: v4f, crackIntensity: number, disp: v2f, shardLighting: number): v4f` — The finished glass: the three refracted channels blended into the crack, with a hint of light on tilted shards.
- `cellLaneUVFor(laneWidth: number): TgpuFn<(idx: F32, field: F32) => Vec2f>` — Where one shard's value sits in a one-row data texture.

### Edge glow (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.edgeGlow

A band of light hugging the edge of any shape, with coloured spots racing around it. The words
live inside a `shapedSurface` surface function (from `materials`), which hands them the
shape's **distance field**: for every pixel, how far it is from the shape's edge, negative
inside. `edgeGlowBand` turns that distance into the glowing band (with drifting smoke) and
also gives the angle around the shape. `orbitSpotsAccum` places one colour's spots along that
angle. The spots of every colour are folded together, starting from `edgeGlowAccumZero` and
adding one colour at a time with the step from `edgeGlowAccumColorFor`, and `edgeGlowCompose`
turns the fold into the final colour with bloom. `heartbeatPulse` is the beat the band and the
spots share.

- `edgeGlowBand(fieldRaw: number, sdfUV: v2f, viewport: v2f, scale: number, thickness: number, softness: number, smokeSize: number, smokeAmt: number, animTime: number, pulse: number, beat: number): v2f` — The glowing band around the shape's edge, with drifting smoke, plus the angle around the shape.
- `orbitSpotsAccum(angle01: number, border: number, animTime: number, beat: number, spotsF: number, spotSize: number, pulse: number, intensity: number, softness: number, seed: number, colorIdxF: number): v2f` — The spots of one color orbiting the band, as coverage at this pixel.
- `heartbeatPulse(animTime: number): number` — A double heartbeat, 0 to 1, driven by the layer's clock.
- `edgeGlowAccumZero(): { rgb: v3f; w: number; ba: number; ac: v3f; aa: number; }` — The empty state to start folding colors into.
- `edgeGlowAccumColorFor(mode: number): TgpuFn<(st: WgslStruct<{ rgb: Vec3f; w: F32; ba: F32; ac: Vec3f; aa: F32; }>, color: Vec4f, sectors: Vec2f) => WgslStruct<{ rgb: Vec3f; w: F32; ba: F32; ac: Vec3f; aa: F32; }>>` — The fold step for one color space: adds one color's spots to the running state.
- `edgeGlowCompose(st: { rgb: v3f; w: number; ba: number; ac: v3f; aa: number; }, bloom: number): v4f` — The final color from the folded state, over a transparent background.
- `colorAtIndex(colors: v4f[], idx: number): v4f` — One color from a `stops` prop, by index.

### Overlays (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.overlay

Heads-up-display overlays: whole fragments that look at the layer inside, find things in it
and draw chrome on top. `detectionOverlay` cuts the canvas into cells, finds the bright,
dark, colored or opaque content in each and draws a bounding box with an optional label
around it, the computer-vision look. `motionTrackerHud` draws tracker gizmos that chase
content over time, dropping keyframe diamonds behind them along their paths.

- `detectionOverlay(slots: DetectionOverlaySlots): (params: GpuFragmentParams) => ExprT` — Draw computer-vision style detection boxes over whatever the child contains.
- `motionTrackerHud(slots: MotionTrackerHudSlots): (params: GpuFragmentParams) => ExprT` — Draw motion-tracker gizmos that chase content across the child, leaving keyframe trails.

### Pointer fields (`import {effects} from 'shaders/std'`) — https://shaders.com/docs/primitives/effects.pointerFields

Push fields the pointer stirs. Each word is a whole simulation: a grid of cells, each holding
how far the layer inside should shift there, that the cursor pushes and that settles back on
its own. Spread the word into a warp definition with `...sim.grids.gridSim(word)` and it
publishes the field under its `output` name; the warp's `map:` then reads it with
`warps.gridCellDisplace` (per cell, blocky) or `warps.liquidDisplace` (smoothly, scaled by an
intensity prop). The definition needs `usesPointer: true`.

- `pointerSplatField(slots: {
    gridSize: PropRef
    decay: PropRef
    intensity: PropRef
    radius: PropRef
    output: string
}): (params: GpuFragmentParams, root: GridRoot) => GridSimConfig` — A field the cursor smears: cells near the pointer move with it, then fade back to rest.
- `springLatticeField(slots: {
    stiffness: PropRef
    damping: PropRef
    radius: PropRef
    output: string
}): (params: GpuFragmentParams, root: GridRoot) => GridSimConfig` — A cloth of springs the cursor pushes: it stretches, rings and settles like fabric.
- `clampSplatGridSize(v: number): number` — The grid size `pointerSplatField` really uses for a prop value: floored, then held to 8–128.
- `SPLAT_MIN_GRID: 8` — The smallest grid `pointerSplatField` runs on: 8 cells per side.
- `SPLAT_MAX_GRID: 128` — The largest grid `pointerSplatField` runs on: 128 cells per side.

## Simulation

### Simulate (`shaders/std` top level) — https://shaders.com/docs/primitives/simulate

Say "simulate this" and let the engine run it. `simulate.grid` declares a square grid of
numbers that changes a little every frame: you list the steps that advance it (`op.wave`
makes it ripple, `op.splat` presses the pointer into it) and name the outputs you want derived
from it (`op.gradient`, the slope at every cell). The engine allocates the state, keeps the
history a wave needs, tracks the pointer, clamps the frame clock, and stops dispatching once
the field has faded to nothing. There is no GPU code in the definition at all.

- `simulate.grid(config: GridSimConfig): GridSim` — A square grid of numbers advanced once per frame by `step`, with named outputs in `derive`.
- `op.wave(config: {damping: PropRef}): WaveOp` — A wave step: the grid ripples outward from any disturbance and fades by `damping` (a prop, 0–20).
- `op.splat(config: {at: PointerSignal; amount: PointerSpeedSignal; radius: PropRef}): SplatOp` — A brush step: a soft round push into the grid at the pointer, scaled by how fast it moves.
- `op.gradient(): GradientOp` — A derived output: the grid's slope at every cell as a 2D vector, ready for `displaceBy`.
- `class GridSim` — A declared grid simulation.

### Grid programs (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.grids

A grid simulation is a fixed-size field of cells (a displacement per cell, two chemical
concentrations, a sort offset) that changes a little every frame. `gridSim` runs it: you
describe the frame as an ordered list of **stages** built with `op.*`, and the engine runs that
list every frame, owning the clock, the frame-delta clamp, the ready gate, the settle gate and
the outputs the layer samples. A stage is bookkeeping (`op.host`, `op.values`, `op.readyWhen`,
`op.settle`) or work (`op.pass`, `op.cache`, `op.seedOnce`, `op.iterate`, `op.sortPass`), and
every frame ends with `op.publish`, which writes the state into the texture the fragment reads.

- `gridSim(build: (params: GpuFragmentParams, root: GridRoot) => GridSimConfig | null): {compute: GpuComputeNode}` — A field of cells advanced every frame by an ordered list of stages.
- `op.values(name: string, run: (f: GridFrame) => void): GridStage` — A named step that writes this frame's values for the passes after it.
- `op.pass(step: ComputeStep): GridStage` — One GPU pass, the same every frame.
- `op.publish(step: (f: GridFrame) => ComputeStep): GridStage` — The last stage: write the state into the texture the layer samples.
- `op.iterate(opts: {count: (f: GridFrame) => number; step: (i: number, nodes: ComputeStep[], f: GridFrame) => void}): GridStage` — Run a step `count` times this frame.
- `op.seedOnce(opts: {pass: ComputeStep; staleWhen: (f: GridFrame) => boolean; onSeed?: () => void}): GridStage` — A one-shot reset run before the rest of the frame whenever `staleWhen` says the state is stale: on the first frame, or when a seed prop changes.
- `op.sortPass(opts: {passes: (f: GridFrame) => number; pass: (parity: 0 | 1, side: 'A' | 'B') => ComputeStep}): SortPassStage` — A compare-and-swap sort that converges a little more every frame: `passes` swaps per frame, alternating odd and even pairs and the two buffers.
- `op.cache(step: (f: GridFrame) => ComputeStep): GridStage` — A GPU pass chosen per frame, for a pass whose input is rebound after the frame starts.
- `op.readyWhen(fn: () => boolean): GridStage` — Run nothing until `fn` returns true, typically once the child's picture has arrived through `bindInputs`.
- `op.settle(opts: {activeWhen: (f: GridFrame) => boolean; settleMs: (f: GridFrame) => number}): GridStage` — Sleep the simulation once nothing has driven it for `settleMs` of simulated time.
- `op.host(name: string, run: (f: GridFrame) => void): GridStage` — A named step that runs before any gate: pointer smoothing, activity flags, anything a later `settle` needs to know.
- `trackedViewport(params: GpuFragmentParams): {
    tracked(): {width: number; height: number}
    safe(fp: GridFrameParams): {width: number; height: number}
}` — The canvas size in pixels, kept current across resizes, in the two forms a stage wants.
- `hostGridProgram(opts: {clampDt: number; steps: HostStep[]}): (fp: unknown) => void` — A frame program for a small grid stepped in plain JavaScript: the steps run in order every frame until one returns `'skip'`.
- `hostStep(name: string, run: (f: HostFrame) => void | 'skip'): HostStep` — One named step of a JavaScript-stepped grid.
- `hostFieldTexture(params: GpuFragmentParams, opts: {size: number; label: string}): {texData: Uint16Array; texture: ReturnType<GpuFragmentParams['registerMediaTexture']>; upload(): void}` — The texture a JavaScript-stepped grid is read through.

### Fluids (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.fluids

Smoke, ink and fog that flow. A fluid is a square grid of velocity plus a **dye** (a density
and an age, or a color) that the engine advances with a full fluid solve every frame:
swirl, pressure, advection. `fluidSim` owns the state buffers, the output texture, the solve
chain, the pointer tracker, the clock and the idle gate that sleeps a settled field. You bring
the parts that make the look and declare them by role.

- `fluidSim<TParams>(build: (params: GpuFragmentParams, root: FluidRoot) => FluidSimConfig<TParams>): {compute: GpuComputeNode}` — A fluid the engine solves every frame.
- `splat<TParams = unknown>(opts: {kernel: FluidKernel} | {setup: (ctx: FluidSetupCtx) => KitComputePipeline}): FluidEmitter<TParams>` — An emitter at a fixed source: one pass per frame that adds dye and momentum where your pass function says (a cone from a point, a line along an edge).
- `cursorRibbon<TParams = unknown, TPrepared = undefined>(opts: {
    /** Pointer tracking: smoothing, the teleport distance, the minimum drag. */
    tracker?: PointerVelocityTrackerOptions
    /** Whether the stroke emits this frame. A live frame keeps the simulation awake. */
    activeWhen: (ptr: PointerFrame, f: FluidFrame) => boolean
    /** Seconds after the last activity before the simulation may sleep. */
    fadeSeconds: (f: FluidFrame) => number
    /** Extra bookkeeping per frame before the idle gate. */
    // InkFlow's color-cycle time drift.
    onFrame?: (f: FluidFrame, ptr: PointerFrame) => void
    /** The stamp pass: a pass function, or a `setup` that builds one on resources of its own. */
    pass: {kernel: FluidKernel} | {setup: (ctx: FluidSetupCtx) => KitComputePipeline}
    /** This frame's stamps. */
    ribbon: (f: FluidFrame, ptr: PointerFrame, values: TParams) => CursorRibbonSpec<TPrepared>
}): FluidEmitter<TParams> & {ptr(): PointerFrame | null; active(): boolean}` — An emitter that paints along the pointer's stroke: a ribbon of stamps between last frame's position and this one, so a fast flick leaves a continuous line, not dots.
- `seededFieldInit<TParams>(opts: {
    kernel: FluidKernel
    /** The value whose change forces a re-seed. */
    seed: (f: FluidFrame) => number
    warm: {
        /** How many silent solves to run. */
        steps: number
        jacobiIters: number
        /** Simulated seconds per warm step. */
        dt: number
        /** Where the warm clock starts. Randomize it so two instances differ. */
        startTime: () => number
        /** The full values for a warm step at simulated time `t`. `t = 0` is the seed write. */
        values: (t: number, f: FluidFrame) => TParams
    }
}): FluidInitPart<TParams>` — A field that starts full: seed it from a pass function, then run the solve silently `warm.steps` times so the first visible frame already flows.
- `ambientForce(kernel: FluidKernel): FluidSolveStage` — A force applied to the whole field before every solve: a turbulence field, a steady wind.
- `restoreToward(kernel: FluidKernel): FluidSolveStage` — A correction applied after every solve: re-seed a color that the solve slowly blurs away.

### Feedback (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.feedback

Effects that remember the last frame. A feedback simulation keeps a picture of its own
previous output and advances it by one step of your rule every frame: read last frame's state,
apply the rule, write the new state. Temporal echoes, codec smears and decaying trails all live
here. `feedbackSim` keeps the two state textures and swaps them, keeps a display copy the layer
samples, binds the child's picture once it exists, and runs a clock you can scale with a speed
prop.

- `feedbackSim<TParams, TGroups = unknown>(build: (params: GpuFragmentParams, root: FeedbackRoot) => FeedbackSimConfig<TParams, TGroups>): {compute: GpuComputeNode}` — A simulation that advances a picture of its own last frame by one step of your rule, every frame.

### Agents (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.agents

Thousands of small things that move: flocks, motes, filings, swarms, particles standing on an
image. An agent simulation keeps a state per agent, moves every agent one step per frame, draws
each one into a shared canvas, and hands the result to the layer. `agentSim` owns the plumbing:
the state buffers, the output texture, the spawn on the first frame and again on a seed change,
the lower count on phones, the child's picture when one is needed, and the fragment that
samples the picture over the full canvas.

- `agentSim<TParams extends AnyWgslStruct>(cfg: AgentSimConfig<TParams>): AgentSimSpread` — A simulation of many agents, spread into a definition: `bake` assembles the steps from your declared parts, `frame` writes the per-frame values, and the fragment samples the picture.
- `renderAgents.orientedWorld(layout: WorldSplatLayout & RampResolveLayout, cfg: Omit<OrientedWorldSplatConfig, 'name'> & {
            ramp: Omit<RampResolveConfig, 'name' | 'res' | 'invGain'> & {invGain?: number}
            names: {splat: string; resolve: string}
            /** Give the splat the second resource group as well (a shape family's own resources). */
            extraOnSplat?: boolean
        }): RenderAgentsPipelines` — Agents with a heading, drawn as a shape pointing the way they move (or the way they are turned), colored from a rest color to an excited color.
- `renderAgents.pointWorld(layout: PointWorldSplatLayout & Parameters<typeof resolve.tint>[0], cfg: Omit<PointWorldSplatConfig, 'name'> & {names: {splat: string; resolve: string}}): RenderAgentsPipelines` — Round motes with no heading, drawn in one tint with a live softness.
- `renderAgents.volume(layout: Parameters<typeof splat.volume>[0] & RampResolveLayout, cfg: Omit<VolumeSplatConfig, 'names'> & {
            ramp: Omit<RampResolveConfig, 'name' | 'res' | 'invGain'>
            names: VolumeSplatConfig['names'] & {resolve: string}
            extraOnSplat?: boolean
        }): RenderAgentsPipelines` — A 3D swarm seen in perspective: nearer particles draw larger and brighter, and the color runs from rest to excited with speed.
- `renderAgents.relief(layout: Parameters<typeof splat.relief>[0], cfg: Omit<ReliefSplatConfig, 'name'> & {
            out: [number, number]
            weightedColor: {alphaK: number}
            names: {splat: string; resolve: string}
        }): RenderAgentsPipelines` — Particles standing on an image, seen through a camera: each carries the child's color at its home, and nearer particles win the color where they overlap.

### Agent forces (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.agentForces

What pushes, turns and carries each agent. The physics of an agent simulation is a list of
parts folded into one update step by an **integrator**. A `force` returns a push for one
agent; a `torque` returns a turn; a `field` samples something at the agent's position (the
magnet at the cursor, a home on a grid); a `drift` is a built-in velocity. Every part is built
over your layout, which names the per-agent buffers and the per-frame values it reads, so the
same part works in any layer that provides those names.

- `integrator.steering2d(layout: SteeringLayout, cfg: {
    forces: AgentSteer2[]
    /** Excitement: effort above `rest` (in max-force units) charges by `gain`, and cools at `cool` per second. */
    agitation: {rest: number; gain: number; cool: number}
    /** Slowest cruise, as a fraction of each agent's top speed. */
    cruiseFloor: number
    /** Speed kept when an agent bounces off an edge (0–1). */
    wallRestitution: number
    name: string
}): (i: number) => void` — A flock under summed steering, kept cruising, arcing off the canvas edges.
- `integrator.forces3d(layout: VolumeSwarmLayout, cfg: {
    forces: AgentForce3[]
    maxSpeed: number
    posClamp: number
    name: string
}): (i: number) => void` — A 3D swarm under summed forces, with drag, a speed limit and a position clamp.
- `integrator.orientation2d(layout: OrientationLayout, cfg: {
    home: AgentHome2
    fieldAt: AgentFieldAt
    torques: AgentTorque[]
    maxOffset: number
    name: string
}): (i: number) => void` — Agents that turn in place under summed torques and drift a little toward the field.
- `integrator.drift2d(layout: DriftLayout, cfg: {
    drift: AgentDrift
    gust: (pos: d.v2f) => d.v2f
    name: string
}): (i: number) => void` — Motes that glide on a built-in drift plus a fading gust, wrapping around the canvas.
- `integrator.relief(layout: ReliefLayout, cfg: {
    channel: AgentChannel
    cursor: (homeW: d.v2f, off: d.v2f, z: number) => d.v3f
    stiffness: number
    maxSpeed: number
    /** Child alpha below which a particle is never latched. Match the render's `minAlpha`. */
    // Matches the splat's early-out.
    minAlpha: number
    name: string
}): (x: number, y: number) => void` — Particles standing on the child's image, rising by a color channel, springing home.
- `integrator.advect2d(layout: AdvectLayout, cfg: {
    gridN: number
    inertiaRate: number
    homeRate: number
    name: string
}): (i: number) => void` — Particles carried by a fluid's velocity texture, easing back to an even spread.
- `force.flocking(layout: SteeringLayout, cfg: {maxAgents: number}): AgentSteer2` — Separation, alignment and cohesion for a flock, with live weights and radii.
- `force.cursorSteer(layout: SteeringLayout): AgentSteer2` — The cursor on a flock: attract, scatter like a predator, or nothing.
- `force.wallTurn(layout: SteeringLayout): AgentSteer2` — A soft turn back toward the canvas near an edge, so a flock arcs instead of bouncing.
- `force.pressure(layout: VolumeSwarmLayout, cfg: {
    gridDim: number
    /** The grid covers shape-local [−domain, domain]³. */
    domain: number
    names: {clear: string; splat: string}
}): PressureForce` — Spread a 3D swarm evenly by pushing agents away from crowded cells of a density grid.
- `force.containment(layout: VolumeSwarmLayout, cfg: {
    field: ShapeField3
    /** How far apart the two samples of the field's slope are taken. 0.02 is typical. */
    // Central-difference epsilon for the field gradient.
    gradEps: number
    /** The spring at the surface: fades in from `featherFrom` to `featherTo` (signed distance), `base` push plus `springK` per unit outside. */
    // Strong outside, diffuse inside (a sharp feather packs a coherent shell).
    wall: {featherFrom: number; featherTo: number; base: number; springK: number}
    /** The pull home once an agent is `from`..`to` from the origin, with strength `k`. */
    // A hard clamp piles strays into lines.
    recall: {from: number; to: number; k: number}
    /** The pull toward the middle where the signed distance is `from`..`to`, with strength `k`. */
    // SDF-VALUE-driven pull toward the origin — direction-safe where the gradient degenerates.
    homing: {from: number; to: number; k: number}
    /** How wide a band around the surface the rotation drag fades over. */
    // Drag toward the rotating container's feature velocity ω×r, feathered to inside.
    entrainment: {featherHalf: number}
}): AgentForce3` — Keep a 3D swarm inside a shape: a spring at the surface, a pull back from far away, and a drag when the shape rotates.
- `force.cursorXY(layout: VolumeSwarmLayout): AgentForce3` — The cursor as a magnet on a 3D swarm, pushing away (or pulling in when the force is negative).
- `force.gravity(layout: VolumeSwarmLayout): AgentForce3` — A constant pull on a 3D swarm in the direction of `params.gravX, gravY`.
- `force.turbulence(layout: VolumeSwarmLayout, cfg: {posScale: number; timeX: number; timeY: number; seedScale: number; gain: number}): AgentForce3` — A per-agent jitter that keeps a 3D swarm alive, scaled by `params.agitation`.
- `force.cursorGust(layout: DriftLayout): (pos: d.v2f) => d.v2f` — A puff from the cursor on drifting motes, zero while the force slider sits at 0.
- `force.cursorInView(layout: ReliefLayout, cfg: {perspK: number}): (homeW: d.v2f, off: d.v2f, z: number) => d.v3f` — The cursor on an image relief, applied where each particle appears on screen.
- `torque.alignToField(layout: OrientationLayout): AgentTorque` — Swing onto the field's line like a compass needle.
- `torque.rest: (layout: OrientationLayout) => AgentTorque` — A weak swing back to each agent's rest angle, felt only where the field is faint.
- `field.dipoleOrRadial(layout: OrientationLayout): AgentFieldAt` — The field of a magnet at the cursor: a bar magnet along its travel, or a single pole.
- `field.jitteredGridHome(layout: OrientationLayout, cfg: {overscan: number}): AgentHome2` — Each agent's resting position on a jittered grid that runs past the canvas edges.
- `drift.variedHeading(layout: {readonly $: {readonly params: HeadingDriftParamsView}}): AgentDrift` — One shared heading and speed, each varied a little per mote.
- `FieldSample(props: { rhat: v2f; strength: number; phi: number; }): { rhat: v2f; strength: number; phi: number; }` — What a field sample carries: the direction away from the source (`rhat`), the `strength`, and the line angle `phi` in radians.
- `channel.alpha: AgentChannel` — The pixel's alpha.
- `channel.blue: AgentChannel` — The blue channel.
- `channel.byMode: Record<number, AgentChannel>` — The same seven by a select prop's number: 0 luminance, 1 inverted, 2 red, 3 green, 4 blue, 5 saturation, 6 alpha.
- `channel.green: AgentChannel` — The green channel.
- `channel.luminance: AgentChannel` — The color's brightness, 0 black to 1 white.
- `channel.luminanceInverted: AgentChannel` — One minus the brightness, so dark areas rise.
- `channel.red: AgentChannel` — The red channel.
- `channel.saturation: AgentChannel` — How colorful the pixel is, 0 grey to 1 pure.

### Agent frame (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.agentFrame

The once-per-frame arithmetic an agent simulation writes into its values. Inside `agentSim`'s
`frame` callback you turn props and the pointer into the numbers the GPU steps read. These are
the recipes that come up in every agent layer, as plain functions with no GPU in them: a drag
factor that does not depend on frame rate (`expDecay`), the pointer in the shape's own
coordinates (`pointerToShapeLocal`), a grid that fits the agent count (`fitJitteredGrid`,
`fitIsoGrid`), a direction that follows the cursor's travel (`createMotionAxis`), camera rows
for a 3D view (`cameraRowsYDown`), and the rotation bookkeeping a spinning shape needs to
carry its swarm along (`omegaFromRotationDeltas`, `entrainmentFromOmega`, `r3SubCellOffset`).

- `expDecay(rate: number, dt: number): number` — The per-frame multiplier that decays a value at `rate` per second, whatever the frame rate.
- `pointerToShapeLocal(opts: {
    pointerX: number
    pointerY: number
    centerX: number
    centerYv: number
    scale: number
    rotC: number
    rotS: number
    aspect: number
}): {x: number; y: number}` — The pointer in the shape's own coordinates: undo the layer's center, scale and rotation so a cursor force can act in the same space the swarm lives in (y up, isotropic).
- `createMotionAxis(opts?: {smoothing?: number; teleport?: number}): { update(x: number, y: number): { x: number; y: number; }; }` — A unit direction that follows where the pointer has been travelling, smoothed frame to frame.
- `fitJitteredGrid(count: number, domainX: number, overscan: number): { cols: number; cellW: number; cellH: number; }` — A grid of about `count` roughly square cells over the canvas plus an `overscan` border on every side, for agents that rest on a jittered grid.
- `fitIsoGrid(count: number, aspect: number, min: number, max: number): { w: number; h: number; }` — A W×H grid of square cells holding about `count` agents at the canvas `aspect`, each side clamped to `[min, max]`.
- `cameraRowsYDown(rx: number, ry: number, rz: number): {
    rowX: [number, number, number]
    rowY: [number, number, number]
    rowZ: [number, number, number]
}` — The three rows of a camera rotation for a 3D view drawn on a y-down canvas.
- `omegaFromRotationDeltas(prev: {x: number; y: number; z: number} | null, next: {x: number; y: number; z: number}, dt: number): {x: number; y: number; z: number} | null` — How fast a rotating shape's surface moves, from its rotation this frame and last frame, so a swarm inside it can be dragged along.
- `entrainmentFromOmega(om: {x: number; y: number; z: number}, opts: {cap: number; gainRate: number; gainMax: number}): { omegaX: number; omegaY: number; omegaZ: number; entrain: number; }` — The values `force.containment` reads for a rotating shape: the rotation rate capped at `cap`, and an `entrain` gain that grows with the rate up to `gainMax`.
- `r3SubCellOffset(frameIdx: number, cell: number): {x: number; y: number; z: number}` — A tiny offset for frame `frameIdx`, within one grid `cell`, that `force.pressure` reads to keep its density grid from lining up with the shape.

### Agent rendering (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.agentRender

How agents become a picture. Every agent frame ends the same way: each agent stamps its shape
into a shared canvas (the **splat**), then one pass turns the canvas into the output picture
and clears it for the next frame (the **resolve**). `renderAgents` in `sim.agents` pairs a
splat with its resolve for you; reach into this module when you need another pairing, or for
the `pointSlot` parts that give round motes their placement, brightness and size.

- `pointSlot.orbitalPlace(layout: {readonly $: {readonly params: {readonly time: number; readonly randomness: number}}}, cfg: {radius: number; rate: number}): PointWorldSplatConfig['place']` — The mote's drawn position: its stored position plus a slow circle of `radius` (canvas heights) at `rate` turns per second, both scaled by `params.randomness` and varied per mote.
- `pointSlot.twinkleBrightness(layout: {readonly $: {readonly params: {readonly time: number; readonly twinkle: number}}}, cfg: {freq: number}): PointWorldSplatConfig['brightness']` — The mote's brightness: a twinkle at `freq` cycles per second, blended in by `params.twinkle` (0 steady, 1 full shimmer), times a per-mote presence so some motes read nearer than others.
- `pointSlot.presenceRadius(layout: {readonly $: {readonly params: {readonly bodyR: number}}}): PointWorldSplatConfig['bodyRadius']` — The mote's size: `params.bodyR` scaled by the same per-mote presence as the brightness, so the motes that read nearer are bigger and brighter together.
- `splat.orientedWorld: (layout: WorldSplatLayout, cfg: OrientedWorldSplatConfig) => (i: number) => void` — Agents with a heading: arrows, streaks, squares, dots or comets drawn along the way they point.
- `splat.pointWorld: (layout: PointWorldSplatLayout, cfg: PointWorldSplatConfig) => (i: number) => void` — Round motes with a live softness, placed, brightened and sized by `pointSlot` parts.
- `splat.volume: (layout: VolumeRenderLayout, cfg: VolumeSplatConfig) => (i: number) => void` — A 3D swarm in perspective, recording speed for the ramp resolve.
- `splat.relief: (layout: ReliefRenderLayout, cfg: ReliefSplatConfig) => (x: number, y: number) => void` — Particles standing on an image, drawn in the child's color through a camera.
- `resolve.ramp: (layout: RampResolveLayout, cfg: RampResolveConfig) => (x: number, y: number) => void` — Rest-to-excited color from two colors, with optional motion trails.
- `resolve.tint: (layout: { readonly $: { readonly accumE: atomicU32[]; readonly outTex: StorageTex; readonly params: { readonly color: v4f; }; }; }, cfg: { res: number; name: string; }) => (x: number, y: number) => void` — One color, with an alpha from coverage.
- `resolve.weightedColor: (layout: ReliefRenderLayout, cfg: { fp: number; alphaK: number; name: string; }) => (x: number, y: number) => void` — The average of the colors that landed, nearer particles first.

### Shape fields (`import {sim} from 'shaders/std'`) — https://shaders.com/docs/primitives/sim.shapeFields

The shape a swarm is held inside. `force.containment` needs one thing from a shape: the signed
distance to its surface at any 3D point, negative inside and positive outside. `shapeField`
builds that distance function from whatever shape the layer was given, so one integrator serves
every shape kind: `analyticExtruded` gives a flat shape (circle, polygon, star) a depth;
`svgExtruded` does the same for an SVG outline uploaded as a distance texture; `analytic3d`
wraps a true 3D solid; `svgLifted3d` wraps an SVG lifted into 3D. The last two rotate with the
shape's live rotation, so the swarm follows the surface as it turns.

- `shapeField.analyticExtruded(layout: {readonly $: {readonly params: ExtrudedAnalyticParamsView}}, sdf2d: AnalyticSdf2d): ShapeField3` — A flat shape given depth: the 2D distance of a circle, polygon or star, extruded in z by `params.halfDepth`.
- `shapeField.svgExtruded(layout: {readonly $: {readonly params: {readonly halfDepth: number}}}, svgLayout: {readonly $: {readonly sdfSource: d.Infer<d.WgslTexture2d<d.F32>>}}, cfg: {size: number}): ShapeField3` — An SVG outline given depth: the outline's distance texture, extruded in z by `params.halfDepth`.
- `shapeField.analytic3d(layout: RotatedFieldLayout, baked: ShapeField3): ShapeField3` — A true 3D solid (sphere, torus, knot…) from its baked distance function, rotated by the shape's live rotation so the swarm follows the surface as it turns.
- `shapeField.svgLifted3d(layout: RotatedFieldLayout, baked: ShapeField3): ShapeField3` — An SVG outline lifted into a 3D solid, rotated by the shape's live rotation.