shaders 3.2.474 → 4.0.0

package/dist/core/std/sim/grids.d.ts

@@ -1,9 +1,9 @@
 import { GpuComputeNode, GpuFragmentParams } from '../../gpu/contract';
 import { ComputeStep } from '../../gpu/compute';
 
-/** The TypeGPU root, via the contract (direct `typegpu` imports are restricted to src/gpu/). */
+/** The GPU device handle the build callback receives, for creating the buffers and passes your stages use. */
 export type GridRoot = NonNullable<GpuFragmentParams['gpu']>['root'];
-/** The renderer's per-frame params, as the grid consumers read them. */
+/** What the renderer reports each frame: the pointer in uv, the frame delta in seconds, the canvas size in pixels. */
 export interface GridFrameParams {
     pointer?: {
         x: number;
@@ -15,95 +15,210 @@ export interface GridFrameParams {
         height: number;
     };
 }
-/** One frame of the simulation, handed to every stage. */
+/** One frame, as every stage sees it: the clamped delta, the clock, and your props. */
 export interface GridFrame {
-    /** `fp.deltaTime ?? 0`, clamped to `clampDt`. */
+    /** Seconds since the last frame, never more than `clampDt`. */
     dt: number;
-    /** `Date.now()` this frame — the settle gates' clock. */
+    /** Wall-clock milliseconds this frame. */
     now: number;
+    /** A numeric prop's current value, or `fallback` when it is not a number this frame. */
     num(key: string, fallback: number): number;
+    /** Any prop's current value. */
     getCpuValue(key: string): unknown;
     frameParams: GridFrameParams;
 }
-/** One stage of the frame program. Phases run in order: ready → tick → skip → emit. */
+/**
+ * One stage of the frame. Build them with `op.*` rather than by hand.
+ *
+ * Each frame runs every stage's `ready`, then every `tick`, then every `skip`, then every
+ * `emit`, in list order.
+ */
 export interface GridStage {
-    /** Frame gate: false → the whole frame returns null (a late-bound input is still pending). */
+    /** Return false to run nothing this frame (an input the stage needs has not arrived yet). */
     ready?(): boolean;
-    /** Pre-gate bookkeeping (pointer smoothing, activity flags). */
+    /** Bookkeeping before any gate: pointer smoothing, activity flags. */
     tick?(f: GridFrame): void;
-    /** Settle gate: true → skip the frame entirely (the last published texture persists). */
+    /** Return true to skip the whole frame. The last published texture stays on screen. */
     skip?(f: GridFrame): boolean;
-    /** Push this stage's dispatches / uniform writes. */
+    /** Add this stage's GPU passes and value writes to the frame. */
     emit?(f: GridFrame, nodes: ComputeStep[]): void;
 }
+/** What a GPU grid simulation declares: its outputs, its frame-delta clamp, and its stages. */
 export interface GridSimConfig {
-    /** Compute outputs the fragment samples (state/display textures, child RTT handles). */
+    /** The textures the fragment samples, by the name it reads them under in `computeOutputs`. */
     outputs: Record<string, unknown>;
-    /** Late input binding (child RTT → luma prepass, child-modulated kernels). Spread only if set. */
+    /** Receive the child's picture once it exists (it is allocated after the layer composes). */
     bindInputs?: (resolve: (key: string) => {
         texture: unknown;
     } | undefined) => void;
-    /** Frame-delta clamp (seconds). */
+    /** Longest frame step accepted, in seconds. 0.016–0.05 keeps a tab switch from jumping the field. */
     clampDt: number;
-    /** Frames with `dt <= 0`: run anyway (default) or skip (Liquify's guard). */
+    /** What to do on a frame with no elapsed time: run anyway (default) or skip it. */
     zeroDt?: 'run' | 'skip';
+    /** The frame program, in order. */
     stages: GridStage[];
 }
 /**
- * The grid-simulation noun. Spread it into a definition: `...gridSim((params, root) => ({...}))`.
- * The build callback runs at compute-node creation (per instance, after the no-device bail); it may
- * return null to opt out entirely (a required child is missing).
+ * A field of cells advanced every frame by an ordered list of stages. Spread it into a
+ * definition next to a `gpu.fragment` that samples one of its outputs.
+ *
+ * The build callback runs once per instance of the layer, with the GPU device, and returns the
+ * outputs, the frame-delta clamp and the stages. Return null to run nothing (a required child is
+ * missing). Without a GPU the fragment should fall back to the child or to transparent.
+ *
+ * @example
+ * ```ts
+ * ...gridSim((params, root) => ({outputs: {state}, clampDt: 0.05, stages: [op.values('write', (f) => paramsU.write({dt: f.dt, radius: f.num('radius', 0.4)})), op.pass(update), op.publish(() => output)]}))
+ * ```
+ * @tip Everything created in the build callback (buffers, passes, trackers) belongs to that layer instance. Create nothing at module scope that holds per-frame state.
+ * @see op, hostGridProgram, simulate, fluidSim, feedbackSim
  */
 export declare function gridSim(build: (params: GpuFragmentParams, root: GridRoot) => GridSimConfig | null): {
     compute: GpuComputeNode;
 };
-/** A parity-alternating sort chain's handle: which ping-pong side is current after this frame. */
+/** A sort chain's stage, which also reports which of its two buffers holds the current result. */
 export interface SortPassStage extends GridStage {
     side(): 'A' | 'B';
 }
+/**
+ * The stages a grid frame is built from. List them in `stages` in the order they should run.
+ *
+ * Bookkeeping: `host` (before any gate), `values` (write this frame's values), `readyWhen`
+ * (wait for an input), `settle` (sleep once the field is still). Work: `pass` (one GPU pass),
+ * `cache` (a pass picked per frame), `seedOnce` (a one-shot reset), `iterate` (a pass N times),
+ * `sortPass` (a compare-swap chain), `publish` (write the result the layer samples).
+ *
+ * @example
+ * ```ts
+ * stages: [op.readyWhen(() => ready), op.values('write', (f) => paramsU.write({dt: f.dt})), op.iterate({count: () => 8, step: (i, nodes) => nodes.push(react.with(i % 2 ? groupBA : groupAB))}), op.publish(() => output)]
+ * ```
+ * @tip A `values` stage sits before the passes that read it. Stages run in list order.
+ * @see gridSim
+ */
 export declare const op: {
-    /** Named pre-gate host step (pointer smoothing, activity flags). Runs in the tick phase. */
+    /**
+     * A named step that runs before any gate: pointer smoothing, activity flags, anything a
+     * later `settle` needs to know.
+     *
+     * @example
+     * ```ts
+     * op.host('cursor', (f) => { active = (f.frameParams.pointer?.x ?? 0.5) !== lastX })
+     * ```
+     * @see values, settle
+     */
     readonly host: (name: string, run: (f: GridFrame) => void) => GridStage;
-    /** Named emit-phase host step (per-frame uniform writes / prop derivation). */
+    /**
+     * A named step that writes this frame's values for the passes after it.
+     *
+     * @example
+     * ```ts
+     * op.values('write', (f) => paramsU.write({dt: f.dt, radius: f.num('radius', 0.4)}))
+     * ```
+     * @tip Read props here with `f.num('prop', fallback)` so a prop that is briefly not a number cannot reach the GPU as `undefined`.
+     * @see host, pass
+     */
     readonly values: (name: string, run: (f: GridFrame) => void) => GridStage;
     /**
-     * Settle gate: once nothing has driven the sim for `settleMs` of SIMULATED time, skip frames
-     * entirely — the last published texture persists on screen, so a settled sim costs zero GPU time.
+     * Sleep the simulation once nothing has driven it for `settleMs` of simulated time. Frames
+     * are skipped and the last published texture stays on screen, so a still field costs nothing.
      *
-     * Simulated, not wall-clock: a hidden tab stops rAF, so no frames step the field while the user
-     * is away. Measured on the wall clock the gate would freeze the sim the moment the tab came back
-     * with the field still fully visible (it never decayed). Only frames that actually dispatch
-     * count toward the settle budget.
+     * `activeWhen` says whether something drove the field this frame. `settleMs` is how long the
+     * field takes to fade after the last activity, in milliseconds.
+     *
+     * @example
+     * ```ts
+     * op.settle({activeWhen: () => moving, settleMs: (f) => 4000 / Math.max(f.num('decay', 1), 0.1)})
+     * ```
+     * @tip Simulated time, not wall-clock: a hidden tab does not count, so the field is still fading when the user comes back.
+     * @see host
      */
     readonly settle: (opts: {
         activeWhen: (f: GridFrame) => boolean;
         settleMs: (f: GridFrame) => number;
     }) => GridStage;
-    /** Frame gate on a late-bound input (child RTT arriving via `bindInputs`). */
+    /**
+     * Run nothing until `fn` returns true, typically once the child's picture has arrived
+     * through `bindInputs`.
+     *
+     * @example
+     * ```ts
+     * op.readyWhen(() => lumaReady)
+     * ```
+     * @see cache
+     */
     readonly readyWhen: (fn: () => boolean) => GridStage;
-    /** One dispatch of a fixed pass. */
+    /**
+     * One GPU pass, the same every frame.
+     *
+     * @example
+     * ```ts
+     * op.pass(update)
+     * ```
+     * @see cache, iterate, publish
+     */
     readonly pass: (step: ComputeStep) => GridStage;
-    /** A per-frame cache prepass, resolved per frame (PixelSort's late-rebound child-luma snapshot). */
+    /**
+     * A GPU pass chosen per frame, for a pass whose input is rebound after the frame starts.
+     *
+     * @example
+     * ```ts
+     * op.cache(() => lumaPipeline)
+     * ```
+     * @see readyWhen, pass
+     */
     readonly cache: (step: (f: GridFrame) => ComputeStep) => GridStage;
-    /** The publish tail: write the sim state into the texture the fragment samples. Resolved per
-     *  frame so it can follow a ping-pong side (`() => output.with(side() === 'A' ? bgA : bgB)`). */
+    /**
+     * The last stage: write the state into the texture the layer samples. Chosen per frame so it
+     * can follow whichever buffer holds the current result.
+     *
+     * @example
+     * ```ts
+     * op.publish(() => outputPass.with(sort.side() === 'A' ? outputBgA : outputBgB))
+     * ```
+     * @see pass, sortPass
+     */
     readonly publish: (step: (f: GridFrame) => ComputeStep) => GridStage;
-    /** One-shot (re)initialisation ahead of the step loop, latched on `staleWhen`. */
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * op.seedOnce({pass: seed, staleWhen: () => needsSeed, onSeed: () => { needsSeed = false }})
+     * ```
+     * @see iterate
+     */
     readonly seedOnce: (opts: {
         pass: ComputeStep;
         staleWhen: (f: GridFrame) => boolean;
         onSeed?: () => void;
     }) => GridStage;
-    /** N ordered iterations of a step (the caller's `step` handles its own ping-pong swap). */
+    /**
+     * Run a step `count` times this frame. Your `step` adds the pass for iteration `i` and picks
+     * which buffer it reads and writes.
+     *
+     * @example
+     * ```ts
+     * op.iterate({count: (f) => Math.round(f.num('speed', 8)), step: (i, nodes) => nodes.push(react.with(i % 2 ? groupBA : groupAB))})
+     * ```
+     * @tip A reaction-diffusion field reads smoother when you raise the iteration count than when you raise the step size.
+     * @see pass, sortPass
+     */
     readonly iterate: (opts: {
         count: (f: GridFrame) => number;
         step: (i: number, nodes: ComputeStep[], f: GridFrame) => void;
     }) => GridStage;
     /**
-     * Odd-even transposition sort chain: `passes` compare-swap dispatches, alternating parity and
-     * ping-pong side per pass. The parity tick PERSISTS across frames (harness policy — a new frame
-     * continues the transposition sequence where the last one stopped, which is what makes the sort
-     * converge "bit by bit"). `side()` reports the current buffer for the publish pass.
+     * 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. `side()` tells `publish` which buffer
+     * holds the current order.
+     *
+     * @example
+     * ```ts
+     * const sort = op.sortPass({passes: () => 1 + Math.round(strength * 4), pass: (parity, side) => (parity ? swap1 : swap0).with(side === 'A' ? groupAB : groupBA)})
+     * ```
+     * @tip The alternation continues across frames instead of restarting, which is what makes the sort settle bit by bit.
+     * @see publish, iterate
      */
     readonly sortPass: (opts: {
         passes: (f: GridFrame) => number;
@@ -111,9 +226,18 @@ export declare const op: {
     }) => SortPassStage;
 };
 /**
- * Viewport dimensions with the standard resize-tracked fallback: `tracked()` is the last
- * `onResize` value (what a texture-space prepass wants), `safe(fp)` prefers this frame's reported
- * dimensions and floors both at 1 (what an aspect computation wants).
+ * The canvas size in pixels, kept current across resizes, in the two forms a stage wants.
+ *
+ * `tracked()` is the size at the last resize, for a pass that works in the canvas's own pixels.
+ * `safe(fp)` prefers the size this frame reports and never returns less than 1, for an aspect
+ * ratio.
+ *
+ * @example
+ * ```ts
+ * const viewport = trackedViewport(params)
+ * op.values('write', (f) => { const s = viewport.safe(f.frameParams); paramsU.write({aspect: s.width / s.height}) })
+ * ```
+ * @see gridSim
  */
 export declare function trackedViewport(params: GpuFragmentParams): {
     tracked(): {
@@ -125,9 +249,9 @@ export declare function trackedViewport(params: GpuFragmentParams): {
         height: number;
     };
 };
-/** One frame of a CPU grid program. */
+/** One frame of a JavaScript-stepped grid: the clamped delta, the clock and the pointer in uv. */
 export interface HostFrame {
-    /** Wall-clock delta since the last frame, clamped (these sims ignore the renderer's deltaTime). */
+    /** Seconds since the last frame, never more than `clampDt`. */
     dt: number;
     now: number;
     pointer: {
@@ -136,24 +260,52 @@ export interface HostFrame {
     };
     frameParams: unknown;
 }
-/** A named CPU step. Return `'skip'` to end the frame (idle gate). */
+/** One named JavaScript step. Return `'skip'` to end the frame early. */
 export interface HostStep {
     name: string;
     run(f: HostFrame): void | 'skip';
 }
+/**
+ * One named step of a JavaScript-stepped grid. Return `'skip'` to end the frame here, which is
+ * how an idle gate is written.
+ *
+ * @example
+ * ```ts
+ * hostStep('dtGuard', (f) => (f.dt <= 0 ? 'skip' : undefined))
+ * ```
+ * @see hostGridProgram
+ */
 export declare const hostStep: (name: string, run: (f: HostFrame) => void | "skip") => HostStep;
 /**
- * An ordered CPU frame program for `onBeforeRender`: wall-clock dt (clamped), then each named step
- * in order until one skips.
+ * A frame program for a small grid stepped in plain JavaScript: the steps run in order every
+ * frame until one returns `'skip'`. Hand the result to `onBeforeRender`.
+ *
+ * Use it when the field is small (a 32×32 flow grid) and the arithmetic reads better as loops.
+ * Publish the cells with `hostFieldTexture` in the last step.
+ *
+ * @example
+ * ```ts
+ * onBeforeRender(hostGridProgram({clampDt: 0.016, steps: [hostStep('advect', (f) => advect(f.dt)), hostStep('publish', () => { pack(field.texData); field.upload() })]}))
+ * ```
+ * @see hostStep, hostFieldTexture, gridSim
  */
 export declare function hostGridProgram(opts: {
     clampDt: number;
     steps: HostStep[];
 }): (fp: unknown) => void;
 /**
- * The CPU field's GPU face: an rgba16float data texture (filterable — a filtering sampler rejects
- * r32float, so cells are half-encoded before upload) registered as a media texture the fragment
- * samples. `texData` is the upload staging buffer the publish step packs into.
+ * The texture a JavaScript-stepped grid is read through. Pack the cells into `texData` (four
+ * half-floats per cell, row by row), call `upload()`, and sample `texture` in the fragment.
+ *
+ * `size` is the grid's side in cells. The texture filters smoothly, so a coarse grid reads as
+ * a continuous field.
+ *
+ * @example
+ * ```ts
+ * const field = hostFieldTexture(params, {size: 32, label: 'flow'})
+ * ```
+ * @tip Values go in as half-floats: convert each number with `toHalfFloat` before writing it into `texData`.
+ * @see hostGridProgram
  */
 export declare function hostFieldTexture(params: GpuFragmentParams, opts: {
     size: number;

package/dist/core/std/sim/grids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grids.d.ts","sourceRoot":"","sources":["../../../src/std/sim/grids.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grids.d.ts","sourceRoot":"","sources":["../../../src/std/sim/grids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA+BH,OAAO,KAAK,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AACzE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAA;AAElD,8GAA8G;AAE9G,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAEpE,sHAAsH;AACtH,MAAM,WAAW,eAAe;IAC5B,OAAO,CAAC,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAA;CAC/C;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACtB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAA;IACV,0CAA0C;IAE1C,GAAG,EAAE,MAAM,CAAA;IACX,wFAAwF;IACxF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1C,gCAAgC;IAChC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,WAAW,EAAE,eAAe,CAAA;CAC/B;AAED;;;;;GAKG;AAEH,MAAM,WAAW,SAAS;IACtB,6FAA6F;IAE7F,KAAK,CAAC,IAAI,OAAO,CAAA;IACjB,sEAAsE;IACtE,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,uFAAuF;IACvF,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;IAC5B,iEAAiE;IACjE,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAA;CAClD;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC1B,8FAA8F;IAE9F,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,6FAA6F;IAE7F,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,GAAG,SAAS,KAAK,IAAI,CAAA;IAC/E,qGAAqG;IACrG,OAAO,EAAE,MAAM,CAAA;IACf,mFAAmF;IAEnF,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,mCAAmC;IACnC,MAAM,EAAE,SAAS,EAAE,CAAA;CACtB;AAED;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,OAAO,CACnB,KAAK,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,KAAK,aAAa,GAAG,IAAI,GAC3E;IAAC,OAAO,EAAE,cAAc,CAAA;CAAC,CAgC3B;AAID,kGAAkG;AAElG,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC5C,IAAI,IAAI,GAAG,GAAG,GAAG,CAAA;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,EAAE;IACX;;;;;;;;;OASG;0BAEQ,MAAM,OAAO,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,KAAG,SAAS;IAK1D;;;;;;;;;OASG;4BAEU,MAAM,OAAO,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,KAAG,SAAS;IAK5D;;;;;;;;;;;;;OAaG;4BAKU;QAAC,UAAU,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC;QAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,MAAM,CAAA;KAAC,KAAG,SAAS;IAepG;;;;;;;;;OASG;6BACW,MAAM,OAAO,KAAG,SAAS;IAIvC;;;;;;;;OAQG;0BACQ,WAAW,KAAG,SAAS;IAIlC;;;;;;;;OAQG;2BAES,CAAC,CAAC,EAAE,SAAS,KAAK,WAAW,KAAG,SAAS;IAIrD;;;;;;;;;OASG;6BACW,CAAC,CAAC,EAAE,SAAS,KAAK,WAAW,KAAG,SAAS;IAIvD;;;;;;;;;OASG;8BACY;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;KAAC,KAAG,SAAS;IAUzG;;;;;;;;;;OAUG;6BAEW;QAAC,KAAK,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,SAAS,KAAK,IAAI,CAAA;KAAC,KAAG,SAAS;IAS1H;;;;;;;;;;;OAWG;8BAIY;QAAC,MAAM,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG,KAAK,WAAW,CAAA;KAAC,KAAG,aAAa;CAelH,CAAA;AAIV;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG;IACxD,OAAO,IAAI;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,EAAE,eAAe,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAA;CAC7D,CAcA;AAQD,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACtB,+DAA+D;IAE/D,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;IAC/B,WAAW,EAAE,OAAO,CAAA;CACvB;AAED,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,MAAM,CAAA;CACnC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,SAAU,MAAM,OAAO,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,KAAG,QAAyB,CAAA;AAEvG;;;;;;;;;;;;GAYG;AAEH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAUjG;AAED;;;;;;;;;;;;;GAaG;AAIH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GACpC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC,iBAAiB,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAAC,MAAM,IAAI,IAAI,CAAA;CAAC,CAMxG"}

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

@@ -0,0 +1,14 @@
+/**
+ * std/sim — the simulation vocabulary (compute-backed state), grouped by family. The grid
+ * simulation nouns (`simulate`, `op`, `GridSim`) stay top-level on `shaders/std`; these are the
+ * L1 words the agent, fluid, feedback and grid simulations are built from.
+ */
+export * as agents from './agents';
+export * as agentForces from './agentForces';
+export * as agentFrame from './agentFrame';
+export * as agentRender from './agentRender';
+export * as feedback from './feedback';
+export * as fluids from './fluids';
+export * as grids from './grids';
+export * as shapeFields from './shapeFields';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/std/sim/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,UAAU,CAAA;AAClC,OAAO,KAAK,WAAW,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,UAAU,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,WAAW,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,MAAM,MAAM,UAAU,CAAA;AAClC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,WAAW,MAAM,eAAe,CAAA"}

package/dist/core/std/sim/shapeFields.d.ts

@@ -77,10 +77,66 @@ declare function analytic3d(layout: RotatedFieldLayout, baked: ShapeField3): Sha
  * border-touching feature can even read inside).
  */
 declare function svgLifted3d(layout: RotatedFieldLayout, baked: ShapeField3): ShapeField3;
+/**
+ * The signed-distance function of the shape a swarm lives in, for `force.containment`.
+ *
+ * Four builders, one per shape source. Each returns a `ShapeField3`: a GPU function from a
+ * shape-local 3D point to a signed distance, negative inside. `analyticExtruded` takes a flat
+ * shape (circle, polygon, star…) and gives it a depth from `params.halfDepth`. `svgExtruded`
+ * does the same for an SVG outline uploaded as a distance texture. `analytic3d` wraps a true
+ * 3D solid so it rotates under the swarm. `svgLifted3d` wraps an SVG lifted into 3D.
+ *
+ * @example
+ * ```ts
+ * force.containment(simLayout, {field: shapeField.analyticExtruded(simLayout, buildAnalyticSdfFn(shapeType)), gradEps: 0.02, wall: {featherFrom: -0.1, featherTo: 0.01, base: 1.1, springK: 22}, recall: {from: 1.5, to: 1.9, k: 9}, homing: {from: 0.12, to: 0.45, k: 5}, entrainment: {featherHalf: 0.05}})
+ * ```
+ * @tip Pick the builder at bake time from the shape props and hand ONE field to the integrator. The swarm never needs to know which kind it is.
+ * @see force, integrator
+ */
 export declare const shapeField: {
+    /**
+     * A flat shape given depth: the 2D distance of a circle, polygon or star, extruded in z by
+     * `params.halfDepth`. The shape's sub-props are read live from `params.sa*`.
+     *
+     * @example
+     * ```ts
+     * shapeField.analyticExtruded(simLayout, buildAnalyticSdfFn('hexagon'))
+     * ```
+     * @see svgExtruded, analytic3d
+     */
     readonly analyticExtruded: typeof analyticExtruded;
+    /**
+     * An SVG outline given depth: the outline's distance texture, extruded in z by
+     * `params.halfDepth`. `size` is the texture's side in texels.
+     *
+     * @example
+     * ```ts
+     * shapeField.svgExtruded(simLayout, svgSdfLayout, {size: 512})
+     * ```
+     * @tip Outside the texture's footprint the distance keeps growing, so strays still find their way back.
+     * @see analyticExtruded, svgLifted3d
+     */
     readonly svgExtruded: typeof svgExtruded;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * shapeField.analytic3d(setup3d.layout, setup3d.sdfFn as ShapeField3)
+     * ```
+     * @see analyticExtruded, svgLifted3d
+     */
     readonly analytic3d: typeof analytic3d;
+    /**
+     * An SVG outline lifted into a 3D solid, rotated by the shape's live rotation.
+     *
+     * @example
+     * ```ts
+     * shapeField.svgLifted3d(setup3d.layout, setup3d.sdfFn as ShapeField3)
+     * ```
+     * @see svgExtruded, analytic3d
+     */
     readonly svgLifted3d: typeof svgLifted3d;
 };
 export {};

package/dist/core/std/sim/shapeFields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shapeFields.d.ts","sourceRoot":"","sources":["../../../src/std/sim/shapeFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAO,CAAC,EAAa,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AAU9C,wEAAwE;AACxE,KAAK,aAAa,GAAG,CACjB,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAC9E,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KACjE;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAEzB;4EAC4E;AAC5E,UAAU,0BAA0B;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,UAAU,aAAa;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACtB;AAED,wFAAwF;AACxF,UAAU,kBAAkB;IACxB,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;SAAC,CAAA;KAAC,CAAA;CAC/D;AAED;;;GAGG;AACH,iBAAS,gBAAgB,CACrB,MAAM,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;KAAC,CAAA;CAAC,EACnE,KAAK,EAAE,aAAa,GACrB,WAAW,CAQb;AAED;;;;;;GAMG;AACH,iBAAS,WAAW,CAChB,MAAM,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAA;CAAC,EACrE,SAAS,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;KAAC,CAAA;CAAC,EAC9E,GAAG,EAAE;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACpB,WAAW,CAcb;AAED;;;;GAIG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAK/E;AAED;;;;;GAKG;AACH,iBAAS,WAAW,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAQhF;AAED,eAAO,MAAM,UAAU;;;;;CAKb,CAAA"}
+{"version":3,"file":"shapeFields.d.ts","sourceRoot":"","sources":["../../../src/std/sim/shapeFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAO,CAAC,EAAa,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AAU9C,wEAAwE;AACxE,KAAK,aAAa,GAAG,CACjB,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAC9E,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KACjE;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAEzB;4EAC4E;AAC5E,UAAU,0BAA0B;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,UAAU,aAAa;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACtB;AAED,wFAAwF;AACxF,UAAU,kBAAkB;IACxB,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;SAAC,CAAA;KAAC,CAAA;CAC/D;AAED;;;GAGG;AACH,iBAAS,gBAAgB,CACrB,MAAM,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;KAAC,CAAA;CAAC,EACnE,KAAK,EAAE,aAAa,GACrB,WAAW,CAQb;AAED;;;;;;GAMG;AACH,iBAAS,WAAW,CAChB,MAAM,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAA;CAAC,EACrE,SAAS,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;KAAC,CAAA;CAAC,EAC9E,GAAG,EAAE;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACpB,WAAW,CAcb;AAED;;;;GAIG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAK/E;AAED;;;;;GAKG;AACH,iBAAS,WAAW,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAQhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU;IACnB;;;;;;;;;OASG;;IAIH;;;;;;;;;;OAUG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;CAGG,CAAA"}

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

@@ -1,62 +1,164 @@
 import { PropRef } from './values';
 import { PointerSignal, PointerSpeedSignal } from './signal';
 
-/** Damped `avg − prev` wave propagation. Needs `history: 2` (reads t−1 AND t−2). */
+/**
+ * A step that makes the grid ripple like a water surface, fading by `damping`.
+ *
+ * Needs `history: 2` on the grid, because a wave reads the two previous frames. `damping`
+ * is a prop on a 0–20 scale: 0 rings forever, 20 dies in a few frames.
+ */
 export interface WaveOp {
     readonly kind: 'op.wave';
     readonly damping: PropRef;
 }
-/** Gaussian brush injection at a positioned signal, scaled by an amount signal. */
+/**
+ * A step that presses a soft round brush into the grid wherever the pointer moves.
+ *
+ * `at` is the pointer signal, `amount` the pointer-speed signal that scales the push (a still
+ * pointer adds nothing), `radius` a prop on a 0.1–1 scale.
+ */
 export interface SplatOp {
     readonly kind: 'op.splat';
     readonly at: PointerSignal;
     readonly amount: PointerSpeedSignal;
     readonly radius: PropRef;
 }
-/** Central-difference gradient of the field → an RG vector-field texture (a derive op). */
+/**
+ * A derived output: the slope of the grid at every cell, as a 2D vector.
+ *
+ * This is what a distortion wants: `displaceBy` moves each pixel along the slope.
+ */
 export interface GradientOp {
     readonly kind: 'op.gradient';
 }
+/** Any step that advances the grid each frame. */
 export type GridStepOp = WaveOp | SplatOp;
+/** Any output derived from the grid after the steps have run. */
 export type GridDeriveOp = GradientOp;
+/**
+ * The steps and outputs a grid simulation is built from.
+ *
+ * `op.wave` and `op.splat` go in `step` and run in order once per frame. `op.gradient` goes in
+ * `derive`, named, and becomes an output an effect can read with `sim.output('name')`.
+ *
+ * @example
+ * ```ts
+ * step: [op.wave({damping: p('decay')}), op.splat({at: pointer({teleportGuard: 'on'}), amount: pointerSpeed({max: 2}), radius: p('radius')})],
+ * derive: {displacement: op.gradient()},
+ * ```
+ * @tip The current engine implements exactly `[op.wave, op.splat]` with `op.gradient` derived. Other combinations throw at definition time.
+ * @see simulate, GridSim
+ */
 export declare const op: {
+    /**
+     * A wave step: the grid ripples outward from any disturbance and fades by `damping` (a prop,
+     * 0–20).
+     *
+     * @example
+     * ```ts
+     * op.wave({damping: p('decay')})
+     * ```
+     * @tip Declare `history: 2` on the grid. A wave needs the two previous frames.
+     * @see op.splat
+     */
     readonly wave: (config: {
         damping: PropRef;
     }) => WaveOp;
+    /**
+     * A brush step: a soft round push into the grid at the pointer, scaled by how fast it
+     * moves. `radius` is a prop on a 0.1–1 scale.
+     *
+     * @example
+     * ```ts
+     * op.splat({at: pointer({teleportGuard: 'on'}), amount: pointerSpeed({max: 2}), radius: p('radius')})
+     * ```
+     * @tip Use `pointer({teleportGuard: 'on'})`. The pointer entering the canvas is then not a stroke.
+     * @see op.wave, pointer, pointerSpeed
+     */
     readonly splat: (config: {
         at: PointerSignal;
         amount: PointerSpeedSignal;
         radius: PropRef;
     }) => SplatOp;
+    /**
+     * A derived output: the grid's slope at every cell as a 2D vector, ready for `displaceBy`.
+     *
+     * @example
+     * ```ts
+     * derive: {displacement: op.gradient()}
+     * ```
+     * @see displaceBy
+     */
     readonly gradient: () => GradientOp;
 };
+/**
+ * What a grid simulation declares: its size, how many past frames it keeps, its steps, and its
+ * named outputs.
+ */
 export interface GridSimConfig {
-    /** Square grid resolution (state texels per side). */
+    /** Cells per side of the square grid. 128 is plenty for a ripple field. */
     resolution: number;
-    /** History levels the step ops read (the wave equation needs 2: t−1 and t−2). */
+    /** How many past frames the steps read. A wave needs 2. */
     history: number;
-    /** Ordered per-texel step ops, run once per frame. */
+    /** The steps that advance the grid, run in this order once per frame. */
     step: GridStepOp[];
-    /** Named derived outputs, consumable as fields by effects (`sim.output(name)`). */
+    /** Named outputs an effect can read through `sim.output(name)`. */
     derive: Record<string, GridDeriveOp>;
-    /** Rest semantics: when the engine may stop dispatching. */
+    /** Let the engine stop running the simulation once the field has faded to nothing. */
     rest?: {
         settlesWhen: 'derived-from-damping';
     };
 }
-/** A reference to one of a simulation's derived outputs (feeds effect slots). */
+/**
+ * A handle to one named output of a simulation, the thing you hand to `displaceBy`.
+ *
+ * @see displaceBy, GridSim
+ */
 export interface SimOutputRef {
     readonly kind: 'simOutput';
     readonly sim: GridSim;
     readonly output: string;
 }
-/** A declared grid simulation. Reference its outputs by identity: `sim.output('name')`. */
+/**
+ * A declared grid simulation. Read its outputs with `output('name')` and pass them to an effect.
+ *
+ * @example
+ * ```ts
+ * effect: displaceBy(waves.output('displacement'), {strength: p('intensity'), chromatic: p('chromaticSplit'), edges: p('edges')})
+ * ```
+ * @tip Asking for an output that was not declared in `derive` throws with the list of names that were.
+ * @see simulate, SimOutputRef
+ */
 export declare class GridSim {
     readonly config: GridSimConfig;
     constructor(config: GridSimConfig);
     output(name: string): SimOutputRef;
 }
+/**
+ * Declare a simulation the engine runs for you. `simulate.grid` gives a square grid of numbers
+ * advanced once per frame by the steps you list.
+ *
+ * Declare it once at module scope, then read its outputs inside the definition. The engine
+ * allocates the state, keeps the history, tracks the pointer and sleeps the simulation once it
+ * has settled.
+ *
+ * @example
+ * ```ts
+ * const waves = simulate.grid({resolution: 128, history: 2, step: [op.wave({damping: p('decay')}), op.splat({at: pointer({teleportGuard: 'on'}), amount: pointerSpeed({max: 2}), radius: p('radius')})], derive: {displacement: op.gradient()}, rest: {settlesWhen: 'derived-from-damping'}})
+ * ```
+ * @tip Reach for `sim.grids`, `sim.fluids`, `sim.feedback` or `sim.agents` only when the effect needs its own GPU step. If a wave field and a displacement say it, stay here.
+ * @see op, GridSim, displaceBy
+ */
 export declare const simulate: {
+    /**
+     * A square grid of numbers advanced once per frame by `step`, with named outputs in `derive`.
+     *
+     * @example
+     * ```ts
+     * const waves = simulate.grid({resolution: 128, history: 2, step: [op.wave({damping: p('decay')}), op.splat({at: pointer({teleportGuard: 'on'}), amount: pointerSpeed({max: 2}), radius: p('radius')})], derive: {displacement: op.gradient()}})
+     * ```
+     * @see op, GridSim
+     */
     readonly grid: (config: GridSimConfig) => GridSim;
 };
 //# sourceMappingURL=sim.d.ts.map