shaders 3.2.474 → 4.0.0

package/dist/core/std/warps.d.ts

@@ -4,32 +4,52 @@ import { GatherEffect } from './types';
 import { PropRef } from './values';
 
 /**
- * Reflect content across the line through `center` at `angle` (degrees).
+ * Mirror the child across a line through `center` at `angle`.
  *
- * The reflection body returns a hard 0/1 side selector alongside the reflected coordinate,
- * so `selectMap` picks per pixel between the original coordinate (near side) and the
- * reflected one (far side). Selecting COORDINATES and sampling once is pixel-identical to
- * mixing two sampled colours by the same hard selector, with one texture fetch instead of
- * two, and both halves go through the same reconstruction filter so the filtering never
- * changes across the mirror line.
+ * `center` is in uv, `angle` in degrees. One side of the line stays as it is and the other side
+ * shows its reflection.
+ *
+ * @example
+ * ```ts
+ * map: warps.mirrorLine({center: p('center'), angle: p('angle')})
+ * ```
+ * @tip Pair it with an `edges` prop that defaults to `'mirror'` so the reflected half never runs out of picture.
+ * @see flip, kaleidoscope
  */
 export declare function mirrorLine(slots: {
     center: ArgSpec;
     angle: ArgSpec;
 }): UvMapSource;
 /**
- * Mirror content across the canvas axes. `flipX`/`flipY` bind boolean props stored as ±1
- * uniforms (transformBoolean). The map sends [0,1] onto [0,1], so pair it with
- * `edges: 'none'` — no lookup can land outside the source.
+ * Flip the child horizontally, vertically, or both.
+ *
+ * `flipX` and `flipY` are boolean props declared with `transform: transformBoolean`. The flip
+ * never looks outside the child, so set `edges: 'none'` on the definition.
+ *
+ * @example
+ * ```ts
+ * map: warps.flip({flipX: p('flipX'), flipY: p('flipY')}),
+ * edges: 'none',
+ * ```
+ * @see mirrorLine
  */
 export declare function flip(slots: {
     flipX: ArgSpec;
     flipY: ArgSpec;
 }): UvMapSource;
 /**
- * Bend the ends of the frame toward (or away from) the viewer like a curved display —
- * the inverse bent-sheet projection, under real perspective. `angle` sets the bend axis in
- * degrees; `falloff` concentrates the bend toward the ends.
+ * Curve the child like a bent sheet seen in perspective, so its ends swell or shrink.
+ *
+ * `strength` runs −1 to 1 and its sign picks the bend direction. `angle` is the bend axis in
+ * degrees. `falloff` (0–1) keeps more of the middle flat and pushes the bend toward the ends.
+ * Where the sheet leaves the frame there is nothing to show, so pair it with an `edges` prop
+ * that defaults to `'transparent'`.
+ *
+ * @example
+ * ```ts
+ * map: warps.bend({strength: p('strength'), falloff: p('falloff'), angle: p('angle')})
+ * ```
+ * @see perspective, cornerPin
  */
 export declare function bend(slots: {
     strength: ArgSpec;
@@ -37,8 +57,16 @@ export declare function bend(slots: {
     angle: ArgSpec;
 }): UvMapSource;
 /**
- * Magnify or pinch content around `center` — positive strength bulges out, negative
- * pinches in, with `radius`/`falloff` shaping the affected disc.
+ * Magnify or pinch the child inside a disc around `center`.
+ *
+ * `strength` runs −1 to 1: positive bulges out, negative pinches in. `radius` sets the size of
+ * the disc (1 reaches about half the canvas height). `falloff` runs 0 (hard edge) to 1 (soft).
+ *
+ * @example
+ * ```ts
+ * map: warps.bulge({center: p('center'), strength: p('strength'), radius: p('radius'), falloff: p('falloff')})
+ * ```
+ * @see twirl, stretch
  */
 export declare function bulge(slots: {
     center: ArgSpec;
@@ -46,20 +74,51 @@ export declare function bulge(slots: {
     radius: ArgSpec;
     falloff: ArgSpec;
 }): UvMapSource;
-/** Rotate and twist content around `center`, with the twist angle growing with distance. */
+/**
+ * Twist the child around `center`, turning more the farther a pixel is from it.
+ *
+ * `intensity` is the twist in radians per unit of distance, so the canvas edge turns by about
+ * `intensity` radians. Negative values twist the other way. The library uses −5 to 5.
+ *
+ * @example
+ * ```ts
+ * map: warps.twirl({center: p('center'), intensity: p('intensity')})
+ * ```
+ * @see bulge, concentricRings
+ */
 export declare function twirl(slots: {
     center: ArgSpec;
     intensity: ArgSpec;
 }): UvMapSource;
-/** Fold content into radial mirrored segments around `center` (`angle` in degrees). */
+/**
+ * Fold the child into mirrored pie slices around `center`.
+ *
+ * `segments` is the number of slices (2 or more). `angle` rotates the whole pattern, in
+ * degrees. Pair it with an `edges` prop that defaults to `'mirror'`.
+ *
+ * @example
+ * ```ts
+ * map: warps.kaleidoscope({center: p('center'), segments: p('segments'), angle: p('angle')})
+ * ```
+ * @see mirrorLine, toPolar
+ */
 export declare function kaleidoscope(slots: {
     center: ArgSpec;
     segments: ArgSpec;
     angle: ArgSpec;
 }): UvMapSource;
 /**
- * Stretch content along a direction (`angle` in degrees) away from `center`, with
- * `falloff` controlling how sharply the stretch ramps in past the center.
+ * Stretch the child along one direction, starting at `center`.
+ *
+ * `angle` is the direction in degrees. Content on the side `angle` points to is pulled out;
+ * the other side is left alone. `strength` (0–1) sets how far. `falloff` (0–1) softens the
+ * start of the stretch, from a hard line at 0 to a long ramp at 1.
+ *
+ * @example
+ * ```ts
+ * map: warps.stretch({center: p('center'), strength: p('strength'), angle: p('angle'), falloff: p('falloff')})
+ * ```
+ * @see bulge, bend
  */
 export declare function stretch(slots: {
     center: ArgSpec;
@@ -68,10 +127,19 @@ export declare function stretch(slots: {
     falloff: ArgSpec;
 }): UvMapSource;
 /**
- * Displace content along a direction by an animated wave. `waveType` binds a compile-time
- * prop (sine/triangle/square/sawtooth/bounce): the producer branches once per composition
- * and only the active waveform body is emitted — no runtime branch. The phase advances by
- * the definition's animated clock (declare `animatedTime: {speed: 'speed'}`), at half rate.
+ * Ripple the child with a travelling wave.
+ *
+ * `angle` is the travel direction in degrees, `frequency` the number of waves across the
+ * canvas, `strength` (0–1) how far pixels move. `waveType` is a prop marked
+ * `compileTime: true` holding `'sine'`, `'triangle'`, `'square'`, `'sawtooth'` or `'bounce'`.
+ * The wave moves with the layer's clock, so declare `animatedTime: {speed: 'speed'}`.
+ *
+ * @example
+ * ```ts
+ * map: warps.wave({strength: p('strength'), frequency: p('frequency'), angle: p('angle'), waveType: p('waveType')})
+ * ```
+ * @tip Changing `waveType` recompiles the shader; the other inputs update live.
+ * @see flowNoise, barOffset
  */
 export declare function wave(slots: {
     strength: ArgSpec;
@@ -80,11 +148,17 @@ export declare function wave(slots: {
     waveType: PropRef;
 }): UvMapSource;
 /**
- * Convert rectangular coordinates to polar space around `center` (`wrap` scales the
- * angular range, `radius` the radial one), lerped toward the identity by `intensity` —
- * 0 leaves the content alone, 1 is the full coordinate-system change. `lerpToIdentity`
- * blends COORDINATES, not colours, so intermediate values are a genuine partial warp
- * rather than a cross-fade.
+ * Unroll the child around `center`, so angle becomes x and distance becomes y.
+ *
+ * `wrap` scales how many times the child repeats around (1 is once). `radius` scales the
+ * distance axis. `intensity` runs 0 (no change) to 1 (the full polar unwrap), and the values
+ * between are a real partial warp, not a cross-fade.
+ *
+ * @example
+ * ```ts
+ * map: warps.toPolar({center: p('center'), wrap: p('wrap'), radius: p('radius'), intensity: p('intensity')})
+ * ```
+ * @see fromPolar, kaleidoscope
  */
 export declare function toPolar(slots: {
     center: ArgSpec;
@@ -93,8 +167,16 @@ export declare function toPolar(slots: {
     intensity: ArgSpec;
 }): UvMapSource;
 /**
- * Convert polar coordinates back to rectangular space around `center` (the mirror of
- * {@link toPolar}), lerped toward the identity by `intensity`.
+ * Wrap the child into a circle around `center`, reading its x as angle and its y as distance.
+ *
+ * The reverse of `toPolar`. `scale` sets how large the circle is. `intensity` runs 0 (no
+ * change) to 1 (the full wrap).
+ *
+ * @example
+ * ```ts
+ * map: warps.fromPolar({center: p('center'), scale: p('scale'), intensity: p('intensity')})
+ * ```
+ * @see toPolar
  */
 export declare function fromPolar(slots: {
     center: ArgSpec;
@@ -102,12 +184,17 @@ export declare function fromPolar(slots: {
     intensity: ArgSpec;
 }): UvMapSource;
 /**
- * Pin each corner of the content to an arbitrary position — a true square→quad corner-pin
- * homography, inverted analytically. The body returns a packed `vec3f` (projected
- * coordinate in `.xy`, front-facing gate in `.z`), so the map returns the COVERAGE form:
- * the warp role applies coverage to sampled alpha on the fragment path and to the coverage
- * mask on the analytic path, clipping the folded-back region either way. `amount` blends
- * each corner toward its neutral rectangle position.
+ * Pin the four corners of the child to new positions, with true perspective between them.
+ *
+ * The corners are positions in uv. `amount` (0–1) blends each corner from its normal place
+ * (0) to the pinned position (1). Pixels outside the pinned quad are clipped to transparent
+ * whatever the edge mode.
+ *
+ * @example
+ * ```ts
+ * map: warps.cornerPin({topLeft: p('topLeft'), topRight: p('topRight'), bottomRight: p('bottomRight'), bottomLeft: p('bottomLeft'), amount: p('amount')})
+ * ```
+ * @see perspective, bend
  */
 export declare function cornerPin(slots: {
     topLeft: ArgSpec;
@@ -117,9 +204,17 @@ export declare function cornerPin(slots: {
     amount: ArgSpec;
 }): UvMapSource;
 /**
- * Rotate the plane in 3D space with pan and tilt (degrees), `fov` controlling perspective
- * intensity and `zoom` scaling the sampled area. The map ignores `aspect` — it samples in
- * raw UV space, unlike the other warps here.
+ * Tilt the child in 3D, as if it were a card turned away from the camera.
+ *
+ * `pan` and `tilt` are the turns in degrees (−90 to 90). `fov` is the camera's field of view
+ * in degrees: wider means stronger perspective. `zoom` scales the picture (1 is unchanged).
+ * `center` is the pivot and `offset` shifts the result, both in uv.
+ *
+ * @example
+ * ```ts
+ * map: warps.perspective({center: p('center'), pan: p('pan'), tilt: p('tilt'), fov: p('fov'), zoom: p('zoom'), offset: p('offset')})
+ * ```
+ * @see cornerPin, bend
  */
 export declare function perspective(slots: {
     center: ArgSpec;
@@ -130,10 +225,18 @@ export declare function perspective(slots: {
     offset: ArgSpec;
 }): UvMapSource;
 /**
- * Concentric rings that each rotate the content by different amounts — per-ring hashed
- * static + animated rotation, blended between adjacent rings along the shortest angular
- * path. The ring rotation advances by the definition's animated clock (declare
- * `animatedTime: {speed: 'speed'}`).
+ * Cut the child into rings around `center` and spin each ring by its own amount.
+ *
+ * `rings` is how many rings fit in one unit of distance. `intensity` is the largest still
+ * rotation a ring can have, in degrees. `smoothness` (0–1) blends neighbouring rings instead
+ * of cutting between them. `seed` reshuffles the per-ring amounts and `speedRandomness`
+ * (0–1) lets rings spin at different rates. Declare `animatedTime: {speed: 'speed'}`.
+ *
+ * @example
+ * ```ts
+ * map: warps.concentricRings({center: p('center'), intensity: p('intensity'), rings: p('rings'), smoothness: p('smoothness'), seed: p('seed'), speedRandomness: p('speedRandomness')})
+ * ```
+ * @see twirl, barOffset
  */
 export declare function concentricRings(slots: {
     center: ArgSpec;
@@ -144,13 +247,19 @@ export declare function concentricRings(slots: {
     speedRandomness: ArgSpec;
 }): UvMapSource;
 /**
- * Fluid-like distortion with constant smooth motion: three noise layers drifting through a
- * 3D field, combined and normalised so the flow speed is constant and `strength` is the
- * only magnitude control. Reads TWO animated clocks — the primary flow drift and the
- * `evolution` extra clock (declare `animatedTime: {speed: ...}` plus
- * `extraAnimatedTimes: {evolution: ...}`), each at 1/10 rate. `seed` binds a prop added to
- * both clocks on the GPU, shifting the noise domain along the drift/evolution axes — a
- * different static pattern per seed value, even at speed 0.
+ * Push the child around with a slowly flowing liquid motion.
+ *
+ * `strength` is how far pixels move, in uv (the library uses 0–0.5). `detail` scales the flow
+ * pattern (higher is finer). `seed` is a prop that picks a different pattern, even when still.
+ * Two clocks drive it: declare `animatedTime: {speed: 'speed'}` for the drift and
+ * `extraAnimatedTimes: {evolution: 'evolutionSpeed'}` for the pattern slowly reshaping.
+ *
+ * @example
+ * ```ts
+ * map: warps.flowNoise({strength: p('strength'), detail: p('detail'), seed: p('seed')})
+ * ```
+ * @tip Speed 0 on both clocks gives a fixed distortion you can still change with `seed`.
+ * @see wave, liquidDisplace
  */
 export declare function flowNoise(slots: {
     strength: ArgSpec;
@@ -158,9 +267,18 @@ export declare function flowNoise(slots: {
     seed: PropRef;
 }): UvMapSource;
 /**
- * Slice the content into strips that slide away in alternating directions — the "shredder"
- * transition. At progress 1 every lookup is out of bounds, so pair it with a fixed
- * TRANSPARENT edge mode (`edges: 1`): clipping the vacated space is what makes it a wipe.
+ * Slice the child into strips that slide out of frame in alternating directions.
+ *
+ * A wipe transition. `progress` runs 0 (whole) to 1 (gone). `angle` is the cut direction in
+ * degrees and `count` the number of strips. Set `edges: 1` (transparent) on the definition so
+ * the vacated space clears instead of smearing.
+ *
+ * @example
+ * ```ts
+ * map: warps.slicedSlide({angle: p('angle'), count: p('sliceCount'), progress: p('progress')}),
+ * edges: 1,
+ * ```
+ * @see barOffset
  */
 export declare function slicedSlide(slots: {
     angle: ArgSpec;
@@ -168,9 +286,17 @@ export declare function slicedSlide(slots: {
     progress: ArgSpec;
 }): UvMapSource;
 /**
- * Slice content into parallel bars, each offset independently by a hash for a fractured or
- * glitch-like look. Each bar drifts at its own hashed rate by the definition's animated
- * clock (declare `animatedTime: {speed: 'speed'}`).
+ * Cut the child into parallel bars and shift each one sideways by a random amount.
+ *
+ * A glitch or fractured look. `count` is the number of bars across the canvas, `angle` their
+ * direction in degrees, `intensity` (0–1) how far they shift. `seed` reshuffles the offsets.
+ * Bars drift with the layer's clock, so declare `animatedTime: {speed: 'speed'}`.
+ *
+ * @example
+ * ```ts
+ * map: warps.barOffset({count: p('count'), angle: p('angle'), intensity: p('intensity'), seed: p('seed')})
+ * ```
+ * @see slicedSlide, concentricRings
  */
 export declare function barOffset(slots: {
     count: ArgSpec;
@@ -179,40 +305,59 @@ export declare function barOffset(slots: {
     seed: ArgSpec;
 }): UvMapSource;
 /**
- * Displace by this node's own compute-generated displacement field, sampled per grid cell:
- * snap the incoming UV to the centre of its `gridSize` cell, read the displacement texture
- * there, offset (±0.1 clamp), then edge-handle.
+ * Move the child by a displacement field your own simulation produces, one grid cell at a time.
  *
- * When the compute texture is absent (GPU-free composition, or before the compute hook has
- * run) the map substitutes a zero displacement and keeps its structure identical — pair the
- * definition with `uvRemapIdentityWhen` so the analytic path returns the incoming remap
- * verbatim in that case instead.
+ * `output` names the simulation output (the same name you gave the field), `gridSize` the
+ * number of cells across the shorter side of the canvas. Every pixel in a cell moves together,
+ * by at most a tenth of the canvas. Add `uvRemapIdentityWhen: ({computeOutputs}) =>
+ * !computeOutputs?.<output>` to the definition so the warp does nothing until the field exists.
+ *
+ * @example
+ * ```ts
+ * map: warps.gridCellDisplace({gridSize: p('gridSize'), output: 'displacement'}),
+ * uvRemapIdentityWhen: ({computeOutputs}) => !computeOutputs?.displacement,
+ * ```
+ * @see liquidDisplace
  */
 export declare function gridCellDisplace(slots: {
     gridSize: ArgSpec;
     output: string;
 }): UvMapSource;
 /**
- * Displace by this node's own compute-generated displacement field, sampled continuously at
- * the incoming UV and scaled by `intensity` (±0.15 clamp) — the liquid/cloth look. Same
- * absent-texture handling as {@link gridCellDisplace}: zero displacement here, with
- * `uvRemapIdentityWhen` covering the analytic path on the definition.
+ * Move the child smoothly by a displacement field your own simulation produces.
+ *
+ * The liquid or cloth look. `output` names the simulation output. `intensity` scales the
+ * movement (the library uses 0–20), capped at about 15% of the canvas. Add
+ * `uvRemapIdentityWhen: ({computeOutputs}) => !computeOutputs?.<output>` to the definition so
+ * the warp does nothing until the field exists.
+ *
+ * @example
+ * ```ts
+ * map: warps.liquidDisplace({intensity: p('intensity'), output: 'displacement'}),
+ * uvRemapIdentityWhen: ({computeOutputs}) => !computeOutputs?.displacement,
+ * ```
+ * @see gridCellDisplace, flowNoise
  */
 export declare function liquidDisplace(slots: {
     intensity: ArgSpec;
     output: string;
 }): UvMapSource;
 /**
- * Distort the child using ANOTHER LAYER's pixels as a displacement map — the classic
- * Photoshop/AE displacement, driven cross-layer rather than by a procedural field, hence a
- * gather effect (the source arrives via `getLayerTexture`, the same shared RTT boundary
- * prop maps use, so the layer renders once even when it's also visible on canvas). An
- * animated source layer displaces live.
+ * Distort the child using another layer's pixels as a displacement map.
+ *
+ * This one goes in `effect:`, not `map:`, because it reads a second layer. `source` is a prop
+ * marked `compileTime: true` that holds the other layer's id. `amount` (0–1) sets how far
+ * pixels move. `channels` is a prop holding `'twoAxis'` (red moves x, green moves y) or
+ * `'directional'` (brightness pushes along `angle`, in degrees). Mid-grey means no movement.
+ * `edges` is a prop marked `compileTime: true` holding `'stretch'`, `'transparent'`,
+ * `'mirror'` or `'wrap'`. With no source selected the child passes through unchanged.
  *
- * `source` binds the compile-time layer prop; `channels` picks the applier at composition
- * (red/green two-axis vs luminance along `angle`); `edges` binds the compile-time edge
- * mode. No source selected (or an unresolvable id) → a sharp passthrough of the child,
- * exactly as sampled at the incoming coordinate.
+ * @example
+ * ```ts
+ * effect: warps.displaceByLayer({source: p('source'), amount: p('amount'), channels: p('channelMode'), angle: p('angle'), edges: p('edges')})
+ * ```
+ * @tip An animated source layer displaces live.
+ * @see liquidDisplace
  */
 export declare function displaceByLayer(slots: {
     source: PropRef;

package/dist/core/std/warps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warps.d.ts","sourceRoot":"","sources":["../../src/std/warps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"warps.d.ts","sourceRoot":"","sources":["../../src/std/warps.ts"],"names":[],"mappings":"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"}

package/dist/core/std/wgsl.d.ts

@@ -0,0 +1,115 @@
+import { Expr, GpuFragmentParams } from '../gpu/contract';
+import { PropConfig } from '../types';
+import { ArgSpec } from './invoke';
+
+/** The WGSL types a bound name can have inside a body. */
+export type WgslType = 'f32' | 'vec2f' | 'vec3f' | 'vec4f' | 'texture_2d<f32>' | 'sampler';
+/**
+ * One entry of `inputs`: the value to bind under a name — a prop `p('x')`, a context token
+ * `ctx.time`, a `Scalar`, or a number — optionally with its WGSL type spelled out as
+ * `{value, type}`. A prop takes its own type; a `Scalar` or a number is `f32`.
+ */
+export type WgslInput = ArgSpec | {
+    readonly value: ArgSpec;
+    readonly type: WgslType;
+};
+/** The long form of a body: `wgsl({body, inputs, alpha, name})`. */
+export interface WgslSpec {
+    /** The WGSL statements. Must `return` a `vec4f` color. */
+    readonly body: string;
+    /** Extra names to bind, on top of the props and context values bound automatically. */
+    readonly inputs?: Record<string, WgslInput>;
+    /**
+     * Gather filters only: what alpha the returned color is in. `'premultiplied'` (default)
+     * lets the engine unpremultiply it for you; `'straight'` returns it as-is.
+     */
+    readonly alpha?: 'premultiplied' | 'straight';
+    /** A readable name for the generated WGSL function. Defaults to the definition's name. */
+    readonly name?: string;
+}
+/** What `wgsl` returns: a body ready to sit in `paint:` or `effect:`. */
+export declare class WgslBody {
+    readonly kind: "wgsl";
+    readonly spec: WgslSpec;
+    /** The names the body refers to (comments stripped, member accesses excluded). */
+    readonly identifiers: ReadonlySet<string>;
+    /** Lowered `tgpu.fn`s, one per distinct parameter signature. */
+    private readonly fns;
+    constructor(spec: WgslSpec);
+    /** True when the body samples `childTexture`, which makes it a gather filter. */
+    get samplesChild(): boolean;
+    /** @internal — the `tgpu.fn` for a parameter signature, created once per body. */
+    fnFor(signature: string, make: () => unknown): unknown;
+}
+/**
+ * True when a value came from `wgsl`.
+ *
+ * @internal
+ */
+export declare function isWgslBody(value: unknown): value is WgslBody;
+/**
+ * Write the per-pixel math by hand, as one WGSL function body that returns a `vec4f` color.
+ *
+ * Put it in `paint:` for a generator or `effect:` for a filter. Every name the body uses is
+ * bound for you. The definition's props come by name: colors as `vec4f` in linear RGB with
+ * alpha, positions as `vec2f` in uv, numbers and booleans as `f32`, select props as their
+ * numeric value. The context comes as `uv` (0–1 across the canvas, y down), `time` (seconds;
+ * the layer's own clock when `animatedTime` is declared, paused at speed 0), `aspect` (width
+ * / height), `viewport` (the frame size in device pixels) and `pointer` (the mouse in uv). In
+ * an `effect:` body `child` is the color of the layer inside at this pixel. Sample
+ * `childTexture` with `childSampler` instead when you need neighbouring pixels (a blur, a
+ * displacement): that gives the filter its own render pass and hands you premultiplied
+ * color, which is unpremultiplied for you on the way out. Template values (`${OCTAVES}`) are
+ * pasted in as text, so a constant can be a loop bound.
+ *
+ * Use the `{body, inputs, alpha}` form to bind extra names (`inputs: {t: ctx.time, k: 4}`) or
+ * to say a gather body already returns straight alpha (`alpha: 'straight'`).
+ *
+ * @example
+ * ```ts
+ * paint: wgsl`
+ *   let d = length((uv - center) * vec2f(aspect, 1.0)) / radius;
+ *   return vec4f(mix(outer.rgb, inner.rgb, 1.0 - smoothstep(0.0, 1.0, d)), 1.0);
+ * `
+ * ```
+ * @example
+ * ```ts
+ * // A gather filter: the layer inside, sampled at a rippled coordinate.
+ * effect: wgsl`
+ *   let wave = sin(length(uv - center) * frequency - time * 4.0) * amplitude;
+ *   return textureSample(childTexture, childSampler, uv + wave);
+ * `
+ * ```
+ * @tip The names `uv`, `time`, `aspect`, `viewport`, `pointer`, `child`, `childTexture` and `childSampler` belong to the body; a prop spelled the same is not bound, so rename the prop.
+ * @see defineShader, ctx, p
+ */
+export declare function wgsl(spec: WgslSpec): WgslBody;
+export declare function wgsl(body: string): WgslBody;
+export declare function wgsl(strings: TemplateStringsArray, ...values: unknown[]): WgslBody;
+/**
+ * @internal The identifiers a body references. Member accesses (`color.rgb` → `rgb`) are
+ * skipped by the negative lookbehind, so a prop named like a swizzle is never bound by
+ * accident.
+ */
+export declare function scanIdentifiers(source: string): ReadonlySet<string>;
+/**
+ * @internal The WGSL type a prop binds as, from its config — mirroring the uniform bridge's
+ * packing rules so the parameter type always matches the struct field. `null` for a prop
+ * that is CPU-only (never a struct field) or expands to arrays (color stops / lists).
+ */
+export declare function wgslTypeForProp(config: PropConfig<unknown>): WgslType | null;
+/** Where a body runs: a generator's `paint:`, or a pointwise or gather filter's `effect:`. */
+export type WgslHost = 'generator' | 'pointwise' | 'gather';
+/**
+ * Lower a body for a host. Returns the composition-time builder: it selects the bindings
+ * the body references, builds (once per signature) the string-form `tgpu.fn`, and returns
+ * the `call(...)` Expr.
+ */
+export declare function lowerWgsl(body: WgslBody, host: WgslHost, definition: {
+    name: string;
+    props: Record<string, PropConfig<unknown>>;
+    animatedTime?: {
+        speed: string;
+    };
+}): (params: GpuFragmentParams) => Expr;
+//# sourceMappingURL=wgsl.d.ts.map

package/dist/core/std/wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl.d.ts","sourceRoot":"","sources":["../../src/std/wgsl.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAC,IAAI,EAAE,KAAK,iBAAiB,EAAC,MAAM,iBAAiB,CAAA;AAO5D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,UAAU,CAAA;AAMxC,OAAO,EAAe,KAAK,OAAO,EAAC,MAAM,UAAU,CAAA;AAInD,0DAA0D;AAC1D,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAAA;AAE1F;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,CAAA;AAEpF,oEAAoE;AACpE,MAAM,WAAW,QAAQ;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC3C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,UAAU,CAAA;IAC7C,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,yEAAyE;AACzE,qBAAa,QAAQ;IACjB,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAS;IAC/B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACzC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;gBAErC,IAAI,EAAE,QAAQ;IAW1B,iFAAiF;IACjF,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,kFAAkF;IAClF,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,GAAG,OAAO;CAQzD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAA;AAC9C,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAA;AAC5C,wBAAgB,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAA;AAkCnF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAKnE;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,QAAQ,GAAG,IAAI,CAkC5E;AAID,8FAA8F;AAC9F,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAA;AAkC3D;;;;GAIG;AACH,wBAAgB,SAAS,CACrB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IAAC,YAAY,CAAC,EAAE;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,GACvG,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CA0BrC"}