shaders 3.2.474 → 4.0.0

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

@@ -0,0 +1,15 @@
+/**
+ * std/effects — the filter-side vocabulary, grouped by family. Each family is a namespace:
+ * `effects.color.saturate(...)`, `effects.blurs.gaussianBlur(...)`, `effects.reveal.coverage(...)`.
+ */
+export * as blurs from './blurs';
+export * as color from './color';
+export * as edgeGlow from './edgeGlow';
+export * as fracture from './fracture';
+export * as instances from './instances';
+export * as lens from './lens';
+export * as overlay from './overlay';
+export * as pointerFields from './pointerFields';
+export * as reveal from './reveal';
+export * as stylize from './stylize';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/std/effects/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/std/effects/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,SAAS,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAA;AAC9B,OAAO,KAAK,OAAO,MAAM,WAAW,CAAA;AACpC,OAAO,KAAK,aAAa,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,UAAU,CAAA;AAClC,OAAO,KAAK,OAAO,MAAM,WAAW,CAAA"}

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

@@ -1,15 +1,26 @@
 import { Expr, GpuFragmentParams } from '../../gpu/contract';
 import { PropRef } from '../values';
 
+/**
+ * The props of a grid layout: `columns` and `rows` (counts), `gapX` and `gapY` (fractions of
+ * the canvas width and height), `stagger` (0 to 1, shifts every other row by that much of a
+ * cell) and `flip`, a compile-time select that mirrors alternate cells (`'none'`,
+ * `'alternate-flip-x'`, `'alternate-flip-y'`, `'both'`).
+ */
 export interface GridSlots {
     columns: PropRef;
     rows: PropRef;
     gapX: PropRef;
     gapY: PropRef;
     stagger: PropRef;
-    /** Structural: alternate-mirror mode ('none' | flip-x | flip-y | both). */
+    /** A compile-time select: `'none'`, `'alternate-flip-x'`, `'alternate-flip-y'` or `'both'`. */
     flip: PropRef;
 }
+/**
+ * The props of a radial layout: `count`, `radius` (a fraction of the canvas height),
+ * `startAngle` and `sweep` (degrees), and `faceCenter`, a boolean that turns each copy to face
+ * the middle of the circle.
+ */
 export interface RadialSlots {
     count: PropRef;
     radius: PropRef;
@@ -17,11 +28,16 @@ export interface RadialSlots {
     sweep: PropRef;
     faceCenter: PropRef;
 }
+/**
+ * The props of a line layout: `count`, `direction` (degrees, 0 points right) and `spacing`
+ * between copies (a fraction of the canvas height).
+ */
 export interface LineSlots {
     count: PropRef;
     direction: PropRef;
     spacing: PropRef;
 }
+/** One layout, built by `grid`, `radial` or `line`. */
 export type PlacementSpec = {
     kind: 'grid';
     slots: GridSlots;
@@ -32,10 +48,43 @@ export type PlacementSpec = {
     kind: 'line';
     slots: LineSlots;
 };
+/**
+ * Copies in rows and columns, filling this layer's bounding box.
+ *
+ * Pass it as the recipe's `placement`, or as one member of `byMode`.
+ *
+ * @example
+ * ```ts
+ * placement: grid({columns: p('columns'), rows: p('rows'), gapX: p('gapX'), gapY: p('gapY'), stagger: p('stagger'), flip: p('flip')})
+ * ```
+ * @tip Mark `flip` `compileTime: true`. Only the chosen mirroring is compiled in.
+ * @see radial, line, byMode
+ */
 export declare const grid: (slots: GridSlots) => PlacementSpec;
+/**
+ * Copies around a circle centred on the layer inside.
+ *
+ * `sweep` at 360 spaces them evenly all the way round; smaller sweeps make an arc starting at
+ * `startAngle`.
+ *
+ * @example
+ * ```ts
+ * placement: radial({count: p('count'), radius: p('radius'), startAngle: p('startAngle'), sweep: p('sweep'), faceCenter: p('faceCenter')})
+ * ```
+ * @see grid, line, byMode
+ */
 export declare const radial: (slots: RadialSlots) => PlacementSpec;
+/**
+ * Copies in a row, marching away from the layer inside in one direction.
+ *
+ * @example
+ * ```ts
+ * placement: line({count: p('count'), direction: p('direction'), spacing: p('spacing')})
+ * ```
+ * @see grid, radial, byMode
+ */
 export declare const line: (slots: LineSlots) => PlacementSpec;
-/** Pick a placement member by a structural mode prop — only the active member emits. */
+/** A layout chosen by a select prop, built by `byMode`. */
 export interface PlacementPick {
     mode: PropRef;
     members: {
@@ -44,7 +93,26 @@ export interface PlacementPick {
         linear: PlacementSpec;
     };
 }
+/**
+ * Lets one select prop switch between a grid, a radial and a linear layout.
+ *
+ * `mode` is a compile-time select with the values `'grid'`, `'radial'` and `'linear'`; only
+ * the chosen layout is compiled in.
+ *
+ * @example
+ * ```ts
+ * placement: byMode(p('mode'), {grid: grid({...}), radial: radial({...}), linear: line({...})})
+ * ```
+ * @see grid, radial, line
+ */
 export declare const byMode: (mode: PropRef, members: PlacementPick["members"]) => PlacementPick;
+/**
+ * How each copy differs from the last. `scale` and `opacity` multiply with every copy (1 keeps
+ * them equal), `rotation` adds per copy in radians (give the prop a degrees-to-radians
+ * transform). The `jitter` props (0 to 1) add seeded randomness to position, rotation, scale
+ * and opacity; `seed` re-rolls it. `phase` (0 to 1) slides the whole layout by one cell or one
+ * copy and wraps seamlessly, for looping animation.
+ */
 export interface VariationSlots {
     scale: PropRef;
     rotation: PropRef;
@@ -56,11 +124,12 @@ export interface VariationSlots {
         opacity: PropRef;
     };
     seed: PropRef;
-    /** Seamless layout animation phase (wraps at 1). */
+    /** Layout animation phase, 0 to 1; 1 is the same layout as 0. */
     phase: PropRef;
 }
+/** Everything `repeatInstances` needs: what to copy, where to put the copies, and how they vary. */
 export interface RepeatInstancesRecipe {
-    /** Crop insets applied to the sampled source rect. */
+    /** Crop insets on the copied area, each a fraction (0 to 0.49) of its width or height. */
     source: {
         crop: {
             left: PropRef;
@@ -71,14 +140,24 @@ export interface RepeatInstancesRecipe {
     };
     placement: PlacementPick | PlacementSpec;
     variation: VariationSlots;
-    /** Per-instance hue rotation (radians/instance); active when the prop is non-zero. */
+    /** Hue rotation added per copy, in radians. Off at 0; give the prop `recompile: crosses(0)`. */
     hueShift?: PropRef;
-    /** Structural stacking order ('forward' | 'backward'). */
+    /** A compile-time select: `'forward'` stacks later copies on top, `'backward'` underneath. */
     order: PropRef;
 }
 /**
- * Build the instance-repeat fragment: placement frame → per-instance variation
- * (→ hue-shift stage) → premultiplied over-accumulation of the child sampled per instance.
+ * Many copies of the layer inside, laid out and varied as the recipe says.
+ *
+ * Returns the fragment for `gpu.fragment` on a definition with `requiresRTT`, `requiresChild`
+ * and `wantsBoundsParams` set. Copies stack with normal alpha in the recipe's `order`. The
+ * result is straight alpha.
+ *
+ * @example
+ * ```ts
+ * gpu: {fragment: repeatInstances({source: {crop: {left: p('cropLeft'), right: p('cropRight'), top: p('cropTop'), bottom: p('cropBottom')}}, placement: radial({count: p('count'), radius: p('radius'), startAngle: p('startAngle'), sweep: p('sweep'), faceCenter: p('faceCenter')}), variation: {scale: p('instanceScale'), rotation: p('instanceRotation'), opacity: p('instanceOpacity'), jitter: {position: p('jitterPosition'), rotation: p('jitterRotation'), scale: p('jitterScale'), opacity: p('jitterOpacity')}, seed: p('seed'), phase: p('phase')}, hueShift: p('hueShift'), order: p('zOrder')})}
+ * ```
+ * @tip `hueShift` costs nothing at 0. Give the prop `recompile: crosses(0)` so it switches on cleanly.
+ * @see grid, radial, line, byMode
  */
 export declare function repeatInstances(recipe: RepeatInstancesRecipe): (params: GpuFragmentParams) => Expr;
 //# sourceMappingURL=instances.d.ts.map

package/dist/core/std/effects/instances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/std/effects/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,IAAI,EAAoB,KAAK,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AAGjF,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAMtC,MAAM,WAAW,SAAS;IACtB,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,2EAA2E;IAC3E,IAAI,EAAE,OAAO,CAAA;CAChB;AACD,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;CACtB;AACD,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,MAAM,aAAa,GACnB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAC,GAChC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAC,GACpC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAC,CAAA;AAEtC,eAAO,MAAM,IAAI,UAAW,SAAS,KAAG,aAAwC,CAAA;AAChF,eAAO,MAAM,MAAM,UAAW,WAAW,KAAG,aAA0C,CAAA;AACtF,eAAO,MAAM,IAAI,UAAW,SAAS,KAAG,aAAwC,CAAA;AAEhF,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE;QAAC,IAAI,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAC,CAAA;CAC/E;AACD,eAAO,MAAM,MAAM,SAAU,OAAO,WAAW,aAAa,CAAC,SAAS,CAAC,KAAG,aAAkC,CAAA;AAI5G,MAAM,WAAW,cAAc;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,CAAA;IAChF,IAAI,EAAE,OAAO,CAAA;IACb,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,qBAAqB;IAClC,sDAAsD;IACtD,MAAM,EAAE;QAAC,IAAI,EAAE;YAAC,IAAI,EAAE,OAAO,CAAC;YAAC,KAAK,EAAE,OAAO,CAAC;YAAC,GAAG,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,OAAO,CAAA;SAAC,CAAA;KAAC,CAAA;IAC9E,SAAS,EAAE,aAAa,GAAG,aAAa,CAAA;IACxC,SAAS,EAAE,cAAc,CAAA;IACzB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAA;CACjB;AAKD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,YACzC,iBAAiB,KAAG,IAAI,CA+F3C"}
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/std/effects/instances.ts"],"names":[],"mappings":"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"}

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

@@ -4,12 +4,22 @@ import { ArgSpec } from '../invoke';
 import { PropRef } from '../values';
 import { SampleStage } from './blurs';
 
+/** @internal The per-channel sample coordinate behind `chromaticFan`. */
 export declare const chromaticOffsetUV: import('typegpu').TgpuFn<(uv: d.Vec2f, angle: d.F32, strength: d.F32, aspect: d.F32, channelOffset: d.F32) => d.Vec2f>;
 /**
- * Chromatic fan: sample the child at three per-channel offset UVs along `angle` (each channel's
- * signed multiplier × `strength`) and recombine R/G/B — alpha from the green tap, so a centred
- * green (offset 0) keeps the silhouette put. Not a uvRemap candidate: three DIFFERENT sample UVs
- * can't fold into one coordinate.
+ * Split the child into red, green and blue copies pushed apart along one direction.
+ *
+ * `angle` is in degrees (0 pushes along x); give the prop `transform: transformAngle`.
+ * `strength` is 0–1, where 1 moves a channel by a tenth of the canvas height. `red`, `green`
+ * and `blue` multiply that shift per channel, usually −1, 0 and 1. Returns a sampling stage;
+ * wrap it in `gatherStack` to make the effect.
+ *
+ * @example
+ * ```ts
+ * effect: gatherStack(chromaticFan({strength: p('strength'), angle: p('angle'), red: p('redOffset'), green: p('greenOffset'), blue: p('blueOffset')}), [])
+ * ```
+ * @tip Alpha comes from the green copy, so keep `green` at 0 to hold the layer's outline in place.
+ * @see gatherStack, spectralLens
  */
 export declare function chromaticFan(opts: {
     strength: ArgSpec;
@@ -18,36 +28,62 @@ export declare function chromaticFan(opts: {
     green: ArgSpec;
     blue: ArgSpec;
 }): SampleStage;
-/** The prop roles the spectral-lens recipe binds. */
+/** The props `spectralLens` reads. Every field is a prop ref (`p('name')`); ranges are the useful slider ranges. */
 export interface SpectralLensSlots {
+    /** Position prop (`transform: transformPosition`) the split, focus, warp and swirl pivot around. */
     center: PropRef;
+    /** 0–1, how far apart the color copies are pushed; 0 is off. */
     spread: PropRef;
+    /** −1 to 1, slides the copies toward one end of the spread; 0 spaces them evenly. */
     bias: PropRef;
+    /** Direction of the spread in degrees (`transform: transformAngle`). */
     angle: PropRef;
+    /** 0–1, bends the spread from a straight line (0) to a burst out from the center (1). */
     perspective: PropRef;
+    /** Number of color copies, 2–50; more is smoother and costlier. */
     count: PropRef;
+    /** 0–1, how strongly each copy takes its own color from the spectrum; 0 keeps the original color. */
     dispersion: PropRef;
+    /** −1 to 1, where the dispersion lands: −1 only near the center, 1 only toward the edges. */
     dispersionShift: PropRef;
+    /** 0–1, turns the dispersion colors around the hue wheel; 1 is a full turn. */
     dispersionColor: PropRef;
+    /** 0–1, fades the split out in a round zone at the center. */
     focusCenter: PropRef;
+    /** 0–1, fades the split out toward the edges; 1 restores the original image there. */
     focusEdges: PropRef;
+    /** −1 to 1, rotates the copies around the center by an angle that grows along the spread. */
     swirl: PropRef;
+    /** 0–1, scatters the spread direction with noise; 0 is off. */
     noise: PropRef;
+    /** 0–1, how fine the direction noise is. */
     noiseFrequency: PropRef;
+    /** 0–1, shifts the noise pattern (a seed). */
     noiseOffset: PropRef;
+    /** −1 to 1, fisheye bulge (positive) or pincushion pinch (negative). */
     lensBulge: PropRef;
+    /** 0–1, squeezes the image toward a circular outline. */
     lensCircle: PropRef;
+    /** 0–1, breaks up the copy edges with grain. */
     grainMixer: PropRef;
+    /** 0–1, black-and-white grain laid over the result. */
     grainOverlay: PropRef;
 }
 /**
- * The spectral-lens recipe: split the child into shifting chromatic layers (a runtime-count
- * gather fan) with barrel/pincushion lens warp, optional circular crop, swirl, noise scatter and
- * film grain. Composed from the kit's lens statement parts — lensGeometry → spreadAxis →
- * spectralFan → grainOverlay, all appending to one statement stream (they share locals via the
- * fresh prefix). The fan loop is raw WGSL because per-iteration texture sampling can't fold
- * into the Expr graph; the accumulated result is premultiplied → straight alpha on the way out
- * like every RTT filter.
+ * Fan the child out into many color-shifted copies through a warped lens, the spectral-lens look.
+ *
+ * A whole fragment for a `gpu:` definition; the child is read as a texture. `count` copies
+ * spread along `angle` around `center`, `dispersion` colors them across the spectrum, the
+ * focus slots fade the split near the center and the edges, `lensBulge` and `lensCircle`
+ * warp the whole image, and `swirl`, `noise` and the grain slots scatter it. Every slot is a
+ * prop ref; the field list on `SpectralLensSlots` gives units and ranges.
+ *
+ * @example
+ * ```ts
+ * gpu: {fragment: spectralLens({center: p('center'), spread: p('spread'), bias: p('bias'), angle: p('angle'), perspective: p('perspective'), count: p('count'), dispersion: p('dispersion'), dispersionShift: p('dispersionShift'), dispersionColor: p('dispersionColor'), focusCenter: p('focusCenter'), focusEdges: p('focusEdges'), swirl: p('swirl'), noise: p('noise'), noiseFrequency: p('noiseFrequency'), noiseOffset: p('noiseOffset'), lensBulge: p('lensBulge'), lensCircle: p('lensCircle'), grainMixer: p('grainMixer'), grainOverlay: p('grainOverlay')})}
+ * ```
+ * @tip Every pixel samples the child `count` times, and phones cap `count` at 24. Keep it low on large canvases.
+ * @see chromaticFan
  */
 export declare function spectralLens(slots: SpectralLensSlots): (params: GpuFragmentParams) => Expr;
 //# sourceMappingURL=lens.d.ts.map

package/dist/core/std/effects/lens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../../../src/std/effects/lens.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAC,iBAAiB,EAAc,MAAM,oBAAoB,CAAA;AACtE,OAAO,EAAC,IAAI,EAAc,MAAM,oBAAoB,CAAA;AAEpD,OAAO,EAAO,CAAC,EAAa,MAAM,qBAAqB,CAAA;AAEvD,OAAO,EAAa,KAAK,OAAO,EAAC,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AACtC,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAA;AAQxC,eAAO,MAAM,iBAAiB,wHAQxB,CAAA;AAEN;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,EAAE,OAAO,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,IAAI,EAAE,OAAO,CAAA;CAChB,GAAG,WAAW,CAYd;AAID,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,cAAc,EAAE,OAAO,CAAA;IACvB,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,YAAY,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CA2B1F"}
+{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../../../src/std/effects/lens.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAC,iBAAiB,EAAc,MAAM,oBAAoB,CAAA;AACtE,OAAO,EAAC,IAAI,EAAc,MAAM,oBAAoB,CAAA;AAEpD,OAAO,EAAO,CAAC,EAAa,MAAM,qBAAqB,CAAA;AAEvD,OAAO,EAAa,KAAK,OAAO,EAAC,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AACtC,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAA;AAQxC,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,wHAQxB,CAAA;AAEN;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,EAAE,OAAO,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,IAAI,EAAE,OAAO,CAAA;CAChB,GAAG,WAAW,CAed;AAID,oHAAoH;AACpH,MAAM,WAAW,iBAAiB;IAC9B,oGAAoG;IACpG,MAAM,EAAE,OAAO,CAAA;IACf,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,OAAO,CAAA;IACb,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAA;IACd,yFAAyF;IACzF,WAAW,EAAE,OAAO,CAAA;IACpB,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAA;IACd,qGAAqG;IACrG,UAAU,EAAE,OAAO,CAAA;IACnB,6FAA6F;IAC7F,eAAe,EAAE,OAAO,CAAA;IACxB,+EAA+E;IAC/E,eAAe,EAAE,OAAO,CAAA;IACxB,8DAA8D;IAC9D,WAAW,EAAE,OAAO,CAAA;IACpB,sFAAsF;IACtF,UAAU,EAAE,OAAO,CAAA;IACnB,6FAA6F;IAC7F,KAAK,EAAE,OAAO,CAAA;IACd,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAA;IACd,4CAA4C;IAC5C,cAAc,EAAE,OAAO,CAAA;IACvB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAA;IACpB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAA;IAClB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAA;IACnB,gDAAgD;IAChD,UAAU,EAAE,OAAO,CAAA;IACnB,uDAAuD;IACvD,YAAY,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAkC1F"}

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

@@ -1,66 +1,107 @@
 import { Expr as ExprT, GpuFragmentParams } from '../../gpu/contract';
 import { PropRef } from '../values';
 /**
- * std/effects — the HUD-drawing vocabulary shared by the overlay-role shaders (ObjectTracker,
- * KeyFrames): premultiplied "over" compositing, round-rect signed distance, the corner-bracket
- * stroke mask, and the premultiplied→straight output convention. The part BODIES live in
- * kit/overlayParts (statement-level string builders — see the rationale there); this module is
- * the std-facing surface shader definitions import.
+ * std/effects/overlay — HUD overlays: whole fragments that draw detection boxes or motion trackers over the layer inside.
  *
- * Only multi-consumer vocabulary lives here (the pass-4 rule: single-consumer stages stay in
- * their shader file as named parts).
+ * Both words return a fragment for a `gpu:` definition. They read the child as a texture,
+ * look for content in it (bright, dark, colored or opaque areas) and draw chrome over it:
+ * bounding boxes and labels for `detectionOverlay`, pursuing tracker gizmos with keyframe
+ * trails for `motionTrackerHud`. Sizes are in pixels on a 1080-pixel-tall canvas and scale
+ * with the canvas height. Colors are color props (`transform: transformColor`).
  */
 export { overPremul, roundRectSD, cornerBracketMask, straightFromPremul } from '../../gpu/kit/overlayParts';
-/** The prop roles the detection-overlay recipe binds. */
+/** The props `detectionOverlay` reads. Every field is a prop ref (`p('name')`). Props marked "select" are declared `compileTime: true`. */
 export interface DetectionOverlaySlots {
+    /** Select: what counts as an object, `'alpha' | 'bright' | 'dark' | 'red' | 'green' | 'blue'`. */
     detectionMode: PropRef;
+    /** 0–1, how strong the content must be to count. */
     threshold: PropRef;
+    /** Select: how the canvas is cut into cells, `'grid' | 'quadtree' | 'mosaic'`. */
     layout: PropRef;
+    /** Base cell size in pixels (24–800). */
     cellSize: PropRef;
+    /** Select (integer 1–5): how many times a quadtree or mosaic cell may split in four. Ignored by `'grid'`. */
     maxDepth: PropRef;
+    /** Select: `'full'` box outline or `'corners'` brackets. */
     boxStyle: PropRef;
+    /** Outline thickness in pixels. */
     lineWidth: PropRef;
+    /** Outline corner radius in pixels (full boxes only). */
     cornerRadius: PropRef;
+    /** Box outline color. */
     strokeColor: PropRef;
+    /** Box fill color; use a translucent one. */
     fillColor: PropRef;
+    /** Label text color. */
     labelColor: PropRef;
+    /** Label pill color. */
     labelBackgroundColor: PropRef;
+    /** Select: what the label says, `'none' | 'dimensions' | 'percentage'`. */
     labelMode: PropRef;
+    /** Select: the box corner the label sits at, `'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'`. */
     labelPosition: PropRef;
+    /** Boolean prop (`transform: transformBoolean`): label inside the box (on) or outside (off). */
     labelInset: PropRef;
+    /** Label pill corner radius in pixels. */
     labelRadius: PropRef;
+    /** Google Fonts family for the label (a `font-family` prop). */
     fontFamily: PropRef;
+    /** Font weight for the label (a `font-weight` prop). */
     fontWeight: PropRef;
+    /** Label text size as a fraction of canvas height (0.01–0.5). */
     fontSize: PropRef;
+    /** Label letter spacing in em. */
     letterSpacing: PropRef;
 }
 /**
- * The detection-overlay recipe: each pixel walks a spatial partition of the canvas to its leaf
- * cell, scans that leaf for content (coverage + a content-tight bbox), and — if the leaf holds
- * an object — composites a bounding box + an optional glyph-pill label over the source. One
- * raw-WGSL builder over the kit's detection parts: the walk is JS-unrolled over compile-time
- * `maxDepth`, each cell scan a JS-unrolled N×N textureSampleLevel loop, bbox accumulation via
- * `select`-folds (uniform control flow, AA stays valid). Compile-time branches (detectionMode /
- * layout / maxDepth / boxStyle / labelMode / labelPosition) read propValues.
+ * Draw computer-vision style detection boxes over whatever the child contains.
+ *
+ * A whole fragment for a `gpu:` definition. The canvas is cut into cells (`layout`,
+ * `cellSize`, `maxDepth`); each cell that holds content of the chosen kind (`detectionMode`
+ * above `threshold`) gets a box drawn tight around that content, with an optional label
+ * showing its size or coverage. The child shows through underneath. Every slot is a prop
+ * ref; the field list on `DetectionOverlaySlots` gives units and options.
+ *
+ * @example
+ * ```ts
+ * gpu: {fragment: detectionOverlay({detectionMode: p('detectionMode'), threshold: p('threshold'), layout: p('layout'), cellSize: p('cellSize'), maxDepth: p('maxDepth'), boxStyle: p('boxStyle'), lineWidth: p('lineWidth'), cornerRadius: p('cornerRadius'), strokeColor: p('strokeColor'), fillColor: p('fillColor'), labelColor: p('labelColor'), labelBackgroundColor: p('labelBackgroundColor'), labelMode: p('labelMode'), labelPosition: p('labelPosition'), labelInset: p('labelInset'), labelRadius: p('labelRadius'), fontFamily: p('fontFamily'), fontWeight: p('fontWeight'), fontSize: p('fontSize'), letterSpacing: p('letterSpacing')})}
+ * ```
+ * @tip Cost grows with `maxDepth`; 2 is plenty for most layouts. Set `labelMode` to `'none'` to skip the text pass entirely.
+ * @see motionTrackerHud
  */
 export declare function detectionOverlay(slots: DetectionOverlaySlots): (params: GpuFragmentParams) => ExprT;
-/** The prop roles the motion-tracker HUD recipe binds. */
+/** The props `motionTrackerHud` reads. Every field is a prop ref (`p('name')`). */
 export interface MotionTrackerHudSlots {
+    /** How many trackers to draw, 1–64. Must be the same prop the tracker simulation reads. */
     trackers: PropRef;
+    /** 0–1, how visible the keyframe trail behind each tracker is. */
     trail: PropRef;
+    /** Gizmo size in pixels (8–80). */
     markerSize: PropRef;
+    /** Stroke width in pixels. */
     lineWidth: PropRef;
+    /** Color of the tracker gizmo (brackets, crosshair, dot). */
     markerColor: PropRef;
+    /** Color of the keyframe diamonds along the trail. */
     keyframeColor: PropRef;
+    /** Color of the motion path between keyframes. */
     pathColor: PropRef;
 }
 /**
- * The motion-tracker HUD fragment: ONE copy of the draw body in a runtime loop over the tracker
- * count, reading the pursuit sim's state rows (`trackState` compute output). Per pixel each
- * tracker costs 2 cache-resident loads (head + trail AABB) unless the pixel is inside its padded
- * box, where the trail-ring stamps (keyframe diamond + path segment) and the bracket gizmo run.
- * The AABB cull is an atomic raw-WGSL core: a runtime-count loop whose draw body sits behind a
- * per-tracker early-out, which no Expr-graph fold can express inside emitted control flow.
+ * Draw motion-tracker gizmos that chase content across the child, leaving keyframe trails.
+ *
+ * A whole fragment for a `gpu:` definition. It only draws; the trackers themselves come from
+ * the tracker pursuit simulation, which the same definition must run as its `compute:` pass
+ * (`trackerSim.createTrackerPursuitSim` from the kit, as the KeyFrames shader does). Without
+ * that pass the child passes through untouched. Every slot is a prop ref; the field list on
+ * `MotionTrackerHudSlots` gives units.
+ *
+ * @example
+ * ```ts
+ * gpu: {fragment: motionTrackerHud({trackers: p('trackers'), trail: p('trail'), markerSize: p('markerSize'), lineWidth: p('lineWidth'), markerColor: p('markerColor'), keyframeColor: p('keyframeColor'), pathColor: p('pathColor')})}
+ * ```
+ * @tip Copy the KeyFrames shader as a whole; the compute pass and this fragment share the `trackers` prop and the detection props.
+ * @see detectionOverlay
  */
 export declare function motionTrackerHud(slots: MotionTrackerHudSlots): (params: GpuFragmentParams) => ExprT;
 //# sourceMappingURL=overlay.d.ts.map

package/dist/core/std/effects/overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/std/effects/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAC,MAAM,4BAA4B,CAAA;AAGzG,OAAO,KAAK,EAAC,IAAI,IAAI,KAAK,EAAE,iBAAiB,EAAc,MAAM,oBAAoB,CAAA;AAIrF,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAKtC,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IAClC,aAAa,EAAE,OAAO,CAAA;IACtB,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,OAAO,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;IACrB,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,SAAS,EAAE,OAAO,CAAA;IAClB,aAAa,EAAE,OAAO,CAAA;IACtB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,EAAE,OAAO,CAAA;IACjB,aAAa,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,KAAK,CAoFnG;AAOD,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IAClC,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,SAAS,EAAE,OAAO,CAAA;IAClB,WAAW,EAAE,OAAO,CAAA;IACpB,aAAa,EAAE,OAAO,CAAA;IACtB,SAAS,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,KAAK,CAiEnG"}
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/std/effects/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EAAC,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAC,MAAM,4BAA4B,CAAA;AAGzG,OAAO,KAAK,EAAC,IAAI,IAAI,KAAK,EAAE,iBAAiB,EAAc,MAAM,oBAAoB,CAAA;AAIrF,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAKtC,2IAA2I;AAC3I,MAAM,WAAW,qBAAqB;IAClC,kGAAkG;IAClG,aAAa,EAAE,OAAO,CAAA;IACtB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAA;IAClB,kFAAkF;IAClF,MAAM,EAAE,OAAO,CAAA;IACf,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAA;IACjB,6GAA6G;IAC7G,QAAQ,EAAE,OAAO,CAAA;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAA;IACjB,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAA;IAClB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAA;IACrB,yBAAyB;IACzB,WAAW,EAAE,OAAO,CAAA;IACpB,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAA;IAClB,wBAAwB;IACxB,UAAU,EAAE,OAAO,CAAA;IACnB,wBAAwB;IACxB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAA;IAClB,6GAA6G;IAC7G,aAAa,EAAE,OAAO,CAAA;IACtB,gGAAgG;IAChG,UAAU,EAAE,OAAO,CAAA;IACnB,0CAA0C;IAC1C,WAAW,EAAE,OAAO,CAAA;IACpB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAA;IACnB,wDAAwD;IACxD,UAAU,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAA;IACjB,kCAAkC;IAClC,aAAa,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,KAAK,CA2FnG;AAOD,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IAClC,2FAA2F;IAC3F,QAAQ,EAAE,OAAO,CAAA;IACjB,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAA;IACd,mCAAmC;IACnC,UAAU,EAAE,OAAO,CAAA;IACnB,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAA;IAClB,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAA;IACpB,sDAAsD;IACtD,aAAa,EAAE,OAAO,CAAA;IACtB,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,KAAK,CAuEnG"}

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

@@ -3,22 +3,42 @@ import { d } from '../../gpu/kit/index';
 import { GridSimConfig, GridRoot } from '../sim/grids';
 import { PropRef } from '../values';
 
+/** The smallest grid `pointerSplatField` runs on: 8 cells per side. */
 export declare const SPLAT_MIN_GRID = 8;
+/** The largest grid `pointerSplatField` runs on: 128 cells per side. */
 export declare const SPLAT_MAX_GRID = 128;
-/** The effective (clamped, floored) splat grid resolution — the shader's recompile key. */
+/**
+ * The grid size `pointerSplatField` really uses for a prop value: floored, then held to 8–128.
+ *
+ * Use it in the `gridSize` prop's recompile rule, so the simulation rebuilds only when the cell
+ * count changes and not on every drag of the slider.
+ *
+ * @example
+ * ```ts
+ * gridSize: {default: 20, recompile: recompileWhen((prev, next) => clampSplatGridSize(prev as number) !== clampSplatGridSize(next as number))}
+ * ```
+ * @see pointerSplatField
+ */
 export declare const clampSplatGridSize: (v: number) => number;
-/** Splat update kernel factory (grid size baked): per-cell dissipation + Gaussian cursor-velocity
- *  splat + clamp. No neighbour reads → single buffer, no ping-pong. Every cell updated. */
+/** @internal The splat update kernel factory behind `pointerSplatField`. */
 export declare function makeSplatUpdateKernel(gridSize: number): import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
-/** Splat output kernel factory (grid size baked): copy the per-cell displacement into RG. */
+/** @internal The splat output kernel factory behind `pointerSplatField`. */
 export declare function makeSplatOutputKernel(gridSize: number): import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
 /**
- * The pointer-splat field sim: a mouse-driven grid displacement field on a single vec4 state
- * buffer (createStateBuffer; WebGPU zero-inits → flat), as the std grid pipeline:
- * cursor-velocity smoothing → settle gate → params write → the in-place update pass (dissipate +
- * splat + clamp, one fused kernel) → the output publish under `slots.output`. CHILD-INDEPENDENT
- * (no bindInputs). The grid resolution is baked per-compose from `slots.gridSize` (kernel
- * factories) — pair that prop with a `clampSplatGridSize` recompile rule.
+ * A field the cursor smears: cells near the pointer move with it, then fade back to rest.
+ *
+ * Spread it with `...sim.grids.gridSim(...)`. `gridSize` is the cells per side (8 to 128,
+ * see `clampSplatGridSize`). `decay` (about 0 to 10) is how fast the smear fades; `intensity`
+ * (about 0 to 5) how hard the cursor pushes; `radius` the brush size (1 is about 5% of the
+ * canvas). The field is published under `output` for a warp map such as
+ * `warps.gridCellDisplace`.
+ *
+ * @example
+ * ```ts
+ * ...sim.grids.gridSim(pointerSplatField({gridSize: p('gridSize'), decay: p('decay'), intensity: p('intensity'), radius: p('radius'), output: 'displacement'}))
+ * ```
+ * @tip Add `uvRemapIdentityWhen: ({computeOutputs}) => !computeOutputs?.displacement` so the warp is a no-op before the field exists.
+ * @see springLatticeField, clampSplatGridSize
  */
 export declare function pointerSplatField(slots: {
     gridSize: PropRef;
@@ -27,19 +47,24 @@ export declare function pointerSplatField(slots: {
     radius: PropRef;
     output: string;
 }): (params: GpuFragmentParams, root: GridRoot) => GridSimConfig;
-/** Spring-lattice step (4 structural + 4 shear springs + return-to-rest, semi-implicit Euler,
- *  cursor impulse injection). 2D-dispatched with the interior border guard. */
+/** @internal The spring-lattice step kernel behind `springLatticeField`. */
 export declare const springLatticeKernel: import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
-/** Copy the displacement (xy) of the current buffer into the RG displacement texture. */
+/** @internal The spring-lattice output kernel behind `springLatticeField`. */
 export declare const springLatticeOutputKernel: import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
 /**
- * The spring-lattice field sim: a spring-mass cloth over two ping-pong vec4 state buffers
- * (createStateBuffer; WebGPU zero-inits → the cloth starts at rest), as the std grid pipeline:
- * cursor-impulse tracking → settle gate → params write → 2 fixed substeps (A→B, B→A — A is
- * always current, B is scratch, so the bind groups are fixed) → output publish from A under
- * `slots.output`. CHILD-INDEPENDENT → no bindInputs. NB: no childNode guard — in the analytic
- * uvRemap fold path the composer passes childNode=undefined (the child is folded, not sampled);
- * the sim must still run there so `uvRemap` can read its displacement.
+ * A cloth of springs the cursor pushes: it stretches, rings and settles like fabric.
+ *
+ * Spread it with `...sim.grids.gridSim(...)`. `stiffness` (about 1 to 30) is how rigid the cloth
+ * is; `damping` (about 0 to 10) how quickly it stops moving; `radius` the push area (1 is about
+ * 8% of the canvas). The grid is fixed at 64 cells per side. The field is published under
+ * `output` for a warp map such as `warps.liquidDisplace`.
+ *
+ * @example
+ * ```ts
+ * ...sim.grids.gridSim(springLatticeField({stiffness: p('stiffness'), damping: p('damping'), radius: p('radius'), output: 'displacement'}))
+ * ```
+ * @tip Add `uvRemapIdentityWhen: ({computeOutputs}) => !computeOutputs?.displacement` so the warp is a no-op before the field exists.
+ * @see pointerSplatField
  */
 export declare function springLatticeField(slots: {
     stiffness: PropRef;

package/dist/core/std/effects/pointerFields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pointerFields.d.ts","sourceRoot":"","sources":["../../../src/std/effects/pointerFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAO,CAAC,EAAM,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAsB,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,cAAc,CAAA;AACnF,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAMtC,eAAO,MAAM,cAAc,IAAI,CAAA;AAC/B,eAAO,MAAM,cAAc,MAAM,CAAA;AAKjC,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,MAAO,MAAM,KAAG,MAA2E,CAAA;AAe1H;2FAC2F;AAC3F,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,8DAuBrD;AAED,6FAA6F;AAC7F,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,8DAOrD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACrC,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACjB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,KAAK,aAAa,CAqE/D;AAwBD;+EAC+E;AAC/E,eAAO,MAAM,mBAAmB,4DAoDH,CAAA;AAE7B,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,4DAKP,CAAA;AAE/B;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACtC,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACjB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,KAAK,aAAa,CA+E/D"}
+{"version":3,"file":"pointerFields.d.ts","sourceRoot":"","sources":["../../../src/std/effects/pointerFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAO,CAAC,EAAM,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAsB,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,cAAc,CAAA;AACnF,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAMtC,uEAAuE;AACvE,eAAO,MAAM,cAAc,IAAI,CAAA;AAC/B,wEAAwE;AACxE,eAAO,MAAM,cAAc,MAAM,CAAA;AAKjC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,MAAO,MAAM,KAAG,MAA2E,CAAA;AAe1H,4EAA4E;AAG5E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,8DAuBrD;AAED,4EAA4E;AAE5E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,8DAOrD;AAED;;;;;;;;;;;;;;;GAeG;AAOH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACrC,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACjB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,KAAK,aAAa,CAqE/D;AAwBD,4EAA4E;AAG5E,eAAO,MAAM,mBAAmB,4DAoDH,CAAA;AAE7B,8EAA8E;AAE9E,eAAO,MAAM,yBAAyB,4DAKP,CAAA;AAE/B;;;;;;;;;;;;;;GAcG;AAQH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACtC,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACjB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,KAAK,aAAa,CA+E/D"}