reze-engine 0.42.3 → 0.50.0

package/dist/shaders/passes/scene-contract.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The scene pass's attachment contract, in one place.
+ *
+ * Everything drawn INSIDE the scene pass — models, ground, outline hulls,
+ * particles, ribbons, and the transparent depth prepass — shares one set of
+ * attachments, and therefore one set of formats, blends and write masks. That
+ * agreement used to be restated at every pipeline that joins the pass and in
+ * every shader that writes to it, which is why adding an attachment was
+ * dangerous rather than tedious: a class left behind does not fail loudly, it
+ * fails as a validation error naming a pipeline that was never edited.
+ *
+ * So the contract is DATA here, and the pipelines ask for it by render class.
+ * Adding the id attachment (MRT) becomes one edit in this file plus a per-class
+ * decision about whether that class writes it — which is the shape of the
+ * question, and now the shape of the code.
+ *
+ * WHAT IS NOT HERE. Two passes look like they belong and do not:
+ *   - the FIELD pass has its own pair of rgba16float targets, its own blend and
+ *     no MSAA. It is a different pass with a different contract.
+ *   - the gizmo and selection-edge pipelines draw to the SWAPCHAIN in their own
+ *     unmultisampled pass, so the presentation format is the whole of their
+ *     contract. The plan listed gizmo as a scene render class; the code says
+ *     otherwise, and the code is right.
+ */
+/** The scene pass's attachments, as the engine has them at init. Passed in
+ *  rather than imported: hdr is chosen per device (rg11b10ufloat where it is
+ *  available and blendable, rgba16float otherwise). */
+export type SceneFormats = {
+    /** The HDR colour attachment, @location(0). */
+    hdr: GPUTextureFormat;
+    /** The aux attachment, @location(1) — (bloom mask, coverage). */
+    aux: GPUTextureFormat;
+};
+/**
+ * The id attachment's format: (material index, object index), one u16 each.
+ *
+ * Two 16-bit channels rather than one 32-bit: 32-bit formats are not
+ * multisamplable, and this attachment is multisampled with the rest of the
+ * pass. Uint targets take no blend at all per spec, which is exactly right —
+ * an averaged id is not an id.
+ */
+export declare const SCENE_ID_FORMAT: GPUTextureFormat;
+/** Called by the engine at init, after probing the device. */
+export declare function setMrtIds(on: boolean): void;
+export declare function mrtIdsEnabled(): boolean;
+/**
+ * What is being drawn, which is the only thing that varies.
+ *
+ * The classes differ ONLY in blend and write mask; formats are the pass's, not
+ * the draw's. A class here is a thing with a reason, not a pipeline name — two
+ * pipelines that blend the same way share one.
+ */
+type SceneRenderClass = 
+/** Models, opaque and transparent. Straight alpha over. */
+"material"
+/** The shadow-catcher floor. Blends PREMULTIPLIED, not like a material: its
+ *  coverage is a lit surface plus a colourless shadow layer, so it weights
+ *  its own colour before the blend sees it. */
+ | "ground"
+/** Backface-expanded hulls. Also a material blend — it is geometry. */
+ | "outline"
+/** Particles and ribbons in their default, non-additive mode. */
+ | "particle"
+/** Particles declaring `// @blend additive` — LIGHT rather than matter, so
+ *  colour sums and alpha is left alone: a glow must not claim coverage it
+ *  never occluded. The aux target sums with it, which is what lets an
+ *  additive effect reach the bloom gate at all. */
+ | "particle-additive"
+/** Ribbons. Additive colour like the above, but premultiplied by the
+ *  fragment's own alpha on the way in (src-alpha, one) rather than added
+ *  whole, and an ordinary alpha-over aux so a ribbon's mask does not
+ *  saturate along every overlap. */
+ | "trail"
+/** The transparent depth prepass: it exists to write DEPTH after the fabric's
+ *  colour blended, so an outline drawn later is occluded behind it. It must
+ *  therefore write no colour at all — the targets exist only to make the
+ *  pipeline compatible with the pass it joins. */
+ | "depth-prepass";
+/**
+ * The colour targets a scene-pass pipeline of this class declares, in
+ * attachment order.
+ *
+ * Fresh objects every call, deliberately: a caller that mutated a shared
+ * descriptor would change every pipeline built after it, and the ones built
+ * before would keep the old value — a difference that only shows up as one
+ * pipeline blending unlike its neighbours.
+ */
+export declare function sceneTargets(cls: SceneRenderClass, formats: SceneFormats): GPUColorTargetState[];
+/**
+ * The pass's colour attachments, in order — for the things that describe the
+ * pass itself rather than a draw within it.
+ *
+ * A render bundle declares the formats it will be replayed into and is rejected
+ * against a pass that does not match, so the bundle encoder has to move in
+ * lockstep with the targets above. It restated the list independently until
+ * this existed, which made it the one consumer an MRT change would have missed
+ * — a bundle is recorded once and replayed, so the failure would have arrived
+ * at replay, naming the bundle rather than the attachment that changed.
+ */
+export declare function sceneColorFormats(formats: SceneFormats): GPUTextureFormat[];
+/**
+ * The fragment-output struct a scene-pass shader returns.
+ *
+ * Emitted rather than written out per file so that the attachment list has one
+ * author. The struct and the targets above have to agree on count and order,
+ * and they now disagree in one file rather than in five.
+ *
+ * Only the shaders that will GAIN an output take this today — the materials
+ * (hand-written and graph-generated alike, through COMMON_FS_OUT_WGSL) and the
+ * ground. Outline, particles and ribbons keep their own declarations on
+ * purpose: they never write the id, so they would take an `id: false` argument
+ * forever, and their structs carry comments about their own blend that belong
+ * where they are.
+ */
+export declare function sceneFsOutWgsl(opts?: {
+    name?: string;
+    aux?: string;
+}): string;
+/**
+ * The line a fragment shader assigns its id with, or nothing when ids are off.
+ *
+ * Emitted rather than written into each shader for the same reason as the
+ * struct: with ids off there must be no assignment either, and a shader cannot
+ * ask the device what it supports.
+ */
+export declare function sceneIdWriteWgsl(out: string, material: string, object: string): string;
+export {};
+//# sourceMappingURL=scene-contract.d.ts.map

package/dist/shaders/passes/scene-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-contract.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/scene-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;uDAEuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,GAAG,EAAE,gBAAgB,CAAA;IACrB,iEAAiE;IACjE,GAAG,EAAE,gBAAgB,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBAA6B,CAAA;AAkB3D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB;AACnB,2DAA2D;AACzD,UAAU;AACZ;;+CAE+C;GAC7C,QAAQ;AACV,uEAAuE;GACrE,SAAS;AACX,iEAAiE;GAC/D,UAAU;AACZ;;;mDAGmD;GACjD,mBAAmB;AACrB;;;oCAGoC;GAClC,OAAO;AACT;;;kDAGkD;GAChD,eAAe,CAAA;AAwEnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAqBhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAE3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmB7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF"}

package/dist/shaders/passes/scene-contract.js

@@ -0,0 +1,207 @@
+/**
+ * The scene pass's attachment contract, in one place.
+ *
+ * Everything drawn INSIDE the scene pass — models, ground, outline hulls,
+ * particles, ribbons, and the transparent depth prepass — shares one set of
+ * attachments, and therefore one set of formats, blends and write masks. That
+ * agreement used to be restated at every pipeline that joins the pass and in
+ * every shader that writes to it, which is why adding an attachment was
+ * dangerous rather than tedious: a class left behind does not fail loudly, it
+ * fails as a validation error naming a pipeline that was never edited.
+ *
+ * So the contract is DATA here, and the pipelines ask for it by render class.
+ * Adding the id attachment (MRT) becomes one edit in this file plus a per-class
+ * decision about whether that class writes it — which is the shape of the
+ * question, and now the shape of the code.
+ *
+ * WHAT IS NOT HERE. Two passes look like they belong and do not:
+ *   - the FIELD pass has its own pair of rgba16float targets, its own blend and
+ *     no MSAA. It is a different pass with a different contract.
+ *   - the gizmo and selection-edge pipelines draw to the SWAPCHAIN in their own
+ *     unmultisampled pass, so the presentation format is the whole of their
+ *     contract. The plan listed gizmo as a scene render class; the code says
+ *     otherwise, and the code is right.
+ */
+/**
+ * The id attachment's format: (material index, object index), one u16 each.
+ *
+ * Two 16-bit channels rather than one 32-bit: 32-bit formats are not
+ * multisamplable, and this attachment is multisampled with the rest of the
+ * pass. Uint targets take no blend at all per spec, which is exactly right —
+ * an averaged id is not an id.
+ */
+export const SCENE_ID_FORMAT = "rg16uint";
+/**
+ * Whether the scene pass carries the id attachment.
+ *
+ * Runtime rather than a compile-time constant, and mutable, because it is not
+ * only a decision — it is a CAPABILITY. Multisampled rg16uint has to be probed
+ * on the device (see the engine's init), and a device that cannot do it must
+ * leave this off. That forces the shaders to be assembled after the probe,
+ * which is why the two shader modules that gain an output stopped being
+ * module-level constants: a string baked at import cannot know what the device
+ * said.
+ *
+ * Set ONCE at init, before any pipeline or shader module is built. Nothing
+ * reads it per frame.
+ */
+let mrtIds = false;
+/** Called by the engine at init, after probing the device. */
+export function setMrtIds(on) {
+    mrtIds = on;
+}
+export function mrtIdsEnabled() {
+    return mrtIds;
+}
+const ALPHA_OVER = {
+    color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+    alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+};
+/** Colour sums; alpha is not touched (src zero, dst one). */
+const ADD_KEEP_ALPHA = {
+    color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+    alpha: { srcFactor: "zero", dstFactor: "one", operation: "add" },
+};
+/** Both channels sum. rg8unorm clamps at 1, which is the saturation alpha-over
+ *  would have reached anyway. */
+const ADD_BOTH = {
+    color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+    alpha: { srcFactor: "one", dstFactor: "one", operation: "add" },
+};
+/**
+ * OVER for something that arrives ALREADY premultiplied: take the source whole
+ * and let it displace the destination by its own coverage.
+ *
+ * The ground needs this and nothing else does. Every other class writes a
+ * straight colour and an alpha, and the src-alpha factor premultiplies it once
+ * on the way in. The ground cannot: its coverage is the SUM of a lit surface
+ * and a colourless shadow-catcher layer, so it has to weight its own colour by
+ * the surface's share before it gets here. Handed to the src-alpha blend, that
+ * weighting happened a second time.
+ */
+const PREMULTIPLIED_OVER = {
+    color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+    alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+};
+/** Additive, premultiplied by the fragment's alpha as it writes. */
+const ADD_PREMULTIPLIED = {
+    color: { srcFactor: "src-alpha", dstFactor: "one", operation: "add" },
+    alpha: { srcFactor: "zero", dstFactor: "one", operation: "add" },
+};
+/**
+ * Which classes actually WRITE an id, and so gain a fragment output for it.
+ *
+ * Everything else keeps its shader exactly as it is and takes the id target at
+ * writeMask 0 — legal, specified, and free. The alternative (leaving the target
+ * off those pipelines) is not available: every pipeline in a pass must agree
+ * with the pass's attachments.
+ *
+ * The ground is in because a mark placed by id needs the floor to have one.
+ * Transparent fabric writes ids too — dissolving a dress needs the dress's own
+ * pixels, and last write wins there, which is a documented choice rather than a
+ * consequence. Outline hulls, particles and ribbons are OUT: they are not
+ * things you would ever address by id, and a hull would overwrite the id of the
+ * body it traces.
+ */
+const WRITES_ID = new Set(["material", "ground"]);
+/** The blends each class writes its two attachments with. */
+const BLENDS = {
+    material: [ALPHA_OVER, ALPHA_OVER],
+    // PREMULTIPLIED colour, alone among the classes — see the blend's own note.
+    // The aux is ordinary alpha-over: the ground writes its mask unweighted, like
+    // everything else, and coverage is what the blend applies.
+    ground: [PREMULTIPLIED_OVER, ALPHA_OVER],
+    outline: [ALPHA_OVER, ALPHA_OVER],
+    particle: [ALPHA_OVER, ALPHA_OVER],
+    "particle-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
+    trail: [ADD_PREMULTIPLIED, ALPHA_OVER],
+};
+/**
+ * The colour targets a scene-pass pipeline of this class declares, in
+ * attachment order.
+ *
+ * Fresh objects every call, deliberately: a caller that mutated a shared
+ * descriptor would change every pipeline built after it, and the ones built
+ * before would keep the old value — a difference that only shows up as one
+ * pipeline blending unlike its neighbours.
+ */
+export function sceneTargets(cls, formats) {
+    const targets = cls === "depth-prepass"
+        ? // Format only, and writeMask 0. Note the asymmetry this leans on, which
+            // is the same one the id target leans on below: a target the shader has
+            // no output for is legal at writeMask 0 (gpuweb#1918), while an output
+            // with no target is NOT governed (gpuweb#5341). This is the specified
+            // direction, and it is the only one this file ever uses.
+            [
+                { format: formats.hdr, writeMask: 0 },
+                { format: formats.aux, writeMask: 0 },
+            ]
+        : (() => {
+            const [color, aux] = BLENDS[cls];
+            return [
+                { format: formats.hdr, blend: { color: { ...color.color }, alpha: { ...color.alpha } } },
+                { format: formats.aux, blend: { color: { ...aux.color }, alpha: { ...aux.alpha } } },
+            ];
+        })();
+    if (mrtIds)
+        targets.push({ format: SCENE_ID_FORMAT, writeMask: WRITES_ID.has(cls) ? 0xf : 0 });
+    return targets;
+}
+/**
+ * The pass's colour attachments, in order — for the things that describe the
+ * pass itself rather than a draw within it.
+ *
+ * A render bundle declares the formats it will be replayed into and is rejected
+ * against a pass that does not match, so the bundle encoder has to move in
+ * lockstep with the targets above. It restated the list independently until
+ * this existed, which made it the one consumer an MRT change would have missed
+ * — a bundle is recorded once and replayed, so the failure would have arrived
+ * at replay, naming the bundle rather than the attachment that changed.
+ */
+export function sceneColorFormats(formats) {
+    return mrtIds ? [formats.hdr, formats.aux, SCENE_ID_FORMAT] : [formats.hdr, formats.aux];
+}
+/**
+ * The fragment-output struct a scene-pass shader returns.
+ *
+ * Emitted rather than written out per file so that the attachment list has one
+ * author. The struct and the targets above have to agree on count and order,
+ * and they now disagree in one file rather than in five.
+ *
+ * Only the shaders that will GAIN an output take this today — the materials
+ * (hand-written and graph-generated alike, through COMMON_FS_OUT_WGSL) and the
+ * ground. Outline, particles and ribbons keep their own declarations on
+ * purpose: they never write the id, so they would take an `id: false` argument
+ * forever, and their structs carry comments about their own blend that belong
+ * where they are.
+ */
+export function sceneFsOutWgsl(opts) {
+    const name = opts?.name ?? "FSOut";
+    const aux = opts?.aux ?? "mask";
+    // No @interpolate here, deliberately. The plan called for
+    // `@location(2) @interpolate(flat)`, and that attribute is only legal on a
+    // vertex OUTPUT or a fragment INPUT — a fragment output is neither, so it
+    // would not compile. It is also unnecessary: the id is read from the per-draw
+    // uniform, not carried across the triangle as a varying, so there is no
+    // interpolation to suppress. (A varying carrying it WOULD need flat, since an
+    // integer varying must be.)
+    //
+    // vec2u for rg16uint: the output type must be compatible with the format, and
+    // uint targets take no blend, which is what makes last-write-wins the rule.
+    const id = mrtIds ? `  @location(2) id: vec2u,\n` : "";
+    return `struct ${name} {
+  @location(0) color: vec4f,
+  @location(1) ${aux}: vec4f,
+${id}};
+`;
+}
+/**
+ * The line a fragment shader assigns its id with, or nothing when ids are off.
+ *
+ * Emitted rather than written into each shader for the same reason as the
+ * struct: with ids off there must be no assignment either, and a shader cannot
+ * ask the device what it supports.
+ */
+export function sceneIdWriteWgsl(out, material, object) {
+    return mrtIds ? `  ${out}.id = vec2u(${material}, ${object});\n` : "";
+}

package/dist/shaders/passes/sim.d.ts

@@ -0,0 +1,34 @@
+import { type CastLayout } from "./particles";
+export declare const SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export declare const SIM_FORMAT: GPUTextureFormat;
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export declare function parseSimSize(wgsl: string, max: number): number;
+/** Whether this effect drives a grid at all. */
+export declare function simEntryPoint(wgsl: string): boolean;
+/**
+ * `rzSim(uv)`, for a shader that READS the grid rather than steps it.
+ *
+ * Always compiled in, even for an effect with no grid — it then samples a 1×1
+ * of zeroes. An accessor that exists only sometimes is one an author has to
+ * guard, and a missing function is a compile error rather than a blank result.
+ */
+export declare function simReadApi(group: number, tex: number, samp: number, size: number): string;
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export declare function simClockApi(timeExpr: string): string;
+/**
+ * The step shader: one invocation per texel, once per frame.
+ *
+ * The previous grid is bound as a SAMPLED texture and the next as a storage
+ * texture, which is what makes the two different resources and the whole thing
+ * legal — a shader cannot read and write one texture coherently, and the
+ * ping-pong is not an optimisation but the only correct way to do this.
+ *
+ * Sampled rather than only fetched, because advection needs to read BETWEEN
+ * texels: a semi-Lagrangian step asks "what was at the place this parcel came
+ * from", and that place is almost never a texel centre. Point-sampling it is
+ * what turns smoke into a staircase.
+ */
+export declare function buildSimShader(wgsl: string, size: number, _cast: CastLayout): string;
+//# sourceMappingURL=sim.d.ts.map

package/dist/shaders/passes/sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/sim.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAgC7C,eAAO,MAAM,OAAO,OAAO,CAAA;AAC3B,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,gBAAgC,CAAA;AAEzD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BzF;AAED;8DAC8D;AAC9D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAwDpF"}

package/dist/shaders/passes/sim.js

@@ -0,0 +1,169 @@
+import { audioApi } from "../audio-api";
+import { scoreApi } from "../score-api";
+import { EFFECT_SCENE_API } from "./composite";
+// A persistent grid an effect can step and read: the one thing an effect could
+// not have before, which is MEMORY.
+//
+// Every other mount is a pure function of position and time. A field shader
+// recomputes its noise from scratch every frame; a trail reads history the
+// engine happens to keep. Neither can build on what it produced last frame, and
+// a whole class of effect is nothing but that:
+//
+//   Fog that a dancer walks through does not "look displaced near her" — it IS
+//   displaced, and stays displaced, and creeps back over seconds. Water does not
+//   look rippled where a foot landed; a ripple leaves and propagates and
+//   reflects off the far edge long after the foot is gone. Both are the same
+//   shape of thing — a grid, stepped by its own previous value.
+//
+// It is also the only way to get the LOOK of a fluid, not merely its motion.
+// Advection compounds: each frame's field is the last one pushed sideways, and a
+// few hundred frames of that stretches and folds a smooth field into filaments
+// and vortex sheets finer than the grid storing them. No noise function
+// produces that, at any octave count, because the structure is not a function of
+// position at all — it is a function of history.
+//
+// The engine owns the ping-pong, the dispatch and the sampling. The author owns
+// the KERNEL, which is the part that differs: advection for smoke, the wave
+// equation for water, a decaying stamp for footprints. That split is the same
+// one the particle mounts make, and for the same reason — the loop is identical
+// in every such effect and the physics never is.
+// A megatexel of rgba16float is 8MB, and two of those is the whole cost. What
+// actually bounds this is the STEP: one invocation per texel per frame, each
+// taking a dozen samples, so doubling the side quadruples the work.
+export const SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export const SIM_FORMAT = "rgba16float";
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export function parseSimSize(wgsl, max) {
+    const m = /^\s*\/\/\s*@sim\s+(\d+)\s*$/m.exec(wgsl);
+    if (!m)
+        return 0;
+    // Clamped rather than rejected, as the particle count is: an author asking for
+    // 4096 gets the most the engine will give and a scene that still runs.
+    return Math.max(8, Math.min(max, parseInt(m[1], 10)));
+}
+/** Whether this effect drives a grid at all. */
+export function simEntryPoint(wgsl) {
+    return /\bfn\s+simStep\s*\(/.test(wgsl);
+}
+/**
+ * `rzSim(uv)`, for a shader that READS the grid rather than steps it.
+ *
+ * Always compiled in, even for an effect with no grid — it then samples a 1×1
+ * of zeroes. An accessor that exists only sometimes is one an author has to
+ * guard, and a missing function is a compile error rather than a blank result.
+ */
+export function simReadApi(group, tex, samp, size) {
+    return /* wgsl */ `
+const RZ_SIM_SIZE: f32 = ${size > 0 ? size : 1}.0;
+@group(${group}) @binding(${tex}) var _rzSimTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzSimSamp: sampler;
+
+/**
+ * The grid, bilinearly sampled. uv is 0..1 across it, and what that MEANS in
+ * the world is the effect's own business — the engine deliberately does not
+ * impose a mapping, because a fog laid over a stage and a ripple field around a
+ * character want different ones and both are two lines of arithmetic.
+ */
+fn rzSim(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+fn rzSimSize() -> f32 { return RZ_SIM_SIZE; }
+fn rzSimTexel() -> f32 { return 1.0 / RZ_SIM_SIZE; }
+
+// ── The step-only half, defined here too and never called here ──
+//
+// One effect file is spliced into EVERY module it has a mount in, so a file
+// with a grid compiles its simStep inside the field and particle shaders as
+// well — where it is dead code that nothing calls, but still code that has to
+// resolve. Leaving these out is a compile error on a function the author was
+// right to write. rzSimPrev reads the current grid rather than a previous one,
+// which is the honest answer outside the step: there is no previous frame here.
+fn rzSimPrev(uv: vec2f) -> vec4f { return rzSim(uv); }
+fn rzSimFrame() -> i32 { return 1; }
+`;
+}
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export function simClockApi(timeExpr) {
+    return /* wgsl */ `
+fn rzTime() -> f32 { return ${timeExpr}; }
+fn rzDt() -> f32 { return 0.0; }
+`;
+}
+const SIM_UNIFORMS = /* wgsl */ `
+struct SimU {
+  time: f32,
+  dt: f32,
+  size: f32,
+  frame: f32,
+}
+`;
+/**
+ * The step shader: one invocation per texel, once per frame.
+ *
+ * The previous grid is bound as a SAMPLED texture and the next as a storage
+ * texture, which is what makes the two different resources and the whole thing
+ * legal — a shader cannot read and write one texture coherently, and the
+ * ping-pong is not an optimisation but the only correct way to do this.
+ *
+ * Sampled rather than only fetched, because advection needs to read BETWEEN
+ * texels: a semi-Lagrangian step asks "what was at the place this parcel came
+ * from", and that place is almost never a texel centre. Point-sampling it is
+ * what turns smoke into a staircase.
+ */
+export function buildSimShader(wgsl, size, _cast) {
+    return (SIM_UNIFORMS +
+        /* wgsl */ `
+@group(0) @binding(0) var<uniform> su: SimU;
+@group(0) @binding(1) var _rzSimPrevTex: texture_2d<f32>;
+@group(0) @binding(2) var _rzSimSamp: sampler;
+@group(0) @binding(3) var _rzSimOut: texture_storage_2d<${SIM_FORMAT}, write>;
+@group(0) @binding(4) var<storage, read> _rzCast: array<vec4f>;
+// The same view uniform the composite reads, so the scene API below is the real
+// thing here rather than a stub — a kernel can ask where a bone is, and a
+// foreground spliced into this module resolves its camera calls.
+@group(0) @binding(6) var<uniform> viewU: array<vec4<f32>, 15>;
+
+fn rzTime() -> f32 { return su.time; }
+fn rzDt() -> f32 { return su.dt; }
+/** Texels per side. */
+fn rzSimSize() -> f32 { return su.size; }
+/** One texel, in uv — the step a neighbour lookup takes. */
+fn rzSimTexel() -> f32 { return 1.0 / su.size; }
+/**
+ * Steps since this effect was installed. Zero on the very first one, which is
+ * the only chance to seed a grid: everything after it builds on what is there.
+ */
+fn rzSimFrame() -> i32 { return i32(su.frame); }
+
+/** The grid as it was LAST frame, bilinear. The only input a kernel really has. */
+fn rzSimPrev(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimPrevTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+` +
+        EFFECT_SCENE_API +
+        audioApi(0, 5) +
+        scoreApi(0, 7) +
+        // rzSim itself, so a kernel may read the grid it is writing — through the
+        // PREVIOUS frame's texture, which is the only version of it that exists
+        // while the current one is still being written.
+        /* wgsl */ `
+fn rzSim(uv: vec2f) -> vec4f { return rzSimPrev(uv); }
+` +
+        "\n// ── user effect (setEffect) ──\n" +
+        wgsl +
+        /* wgsl */ `
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let n = u32(${size});
+  if (gid.x >= n || gid.y >= n) { return; }
+  let xy = vec2i(i32(gid.x), i32(gid.y));
+  // The texel CENTRE, so a kernel that reads its own uv back through rzSimPrev
+  // lands on itself rather than a quarter-texel off.
+  let uv = (vec2f(f32(gid.x), f32(gid.y)) + vec2f(0.5)) / su.size;
+  textureStore(_rzSimOut, xy, simStep(uv, textureLoad(_rzSimPrevTex, xy, 0), su.dt));
+}
+`);
+}

package/dist/shaders/passes/trails.d.ts

@@ -0,0 +1,59 @@
+type TrailSource = {
+    /** The author's WGSL verbatim. */
+    wgsl: string;
+    /** How many ribbons to draw — one per trailed anchor. */
+    slots: number;
+    /** For each ribbon, the LOCAL anchor slot it belongs to. Identity when every
+     *  anchor is trailed; otherwise it skips the untrailed ones. */
+    ribbonSlots: number[];
+    /** Additive, like most glowing ribbons, or straight alpha. */
+    blend: "alpha" | "additive";
+    bloom: boolean;
+};
+/**
+ * Sub-segments drawn between each pair of recorded samples.
+ *
+ * The path is sampled at a fixed rate on the scene clock, so a fast hand leaves
+ * its samples far apart and a strip drawn straight between them is visibly
+ * faceted. Four sub-segments on a Catmull-Rom curve through the neighbours costs
+ * four times the vertices — which is nothing, they are vertices — and removes
+ * both the faceting and most of the jitter, since a spline tangent varies
+ * smoothly where a per-segment direction snaps about whenever the hand slows.
+ */
+export declare const TRAIL_SUBDIVISIONS = 6;
+/** Does the source define the trail contract? Both are required together. */
+export declare function trailEntryPoints(wgsl: string): {
+    width: boolean;
+    shade: boolean;
+};
+/**
+ * One quad per segment, laid out flat across every anchor and character.
+ *
+ * The instance index encodes all three — segment, subject, slot — so a scene
+ * with three dancers and eight declared bones is still ONE draw call and needs
+ * nothing computed on the CPU per frame. Instances past the end of a real trail
+ * collapse to a degenerate quad, which costs a vertex shader invocation and no
+ * fragments; the alternative is a compacted instance list, which costs a
+ * readback every frame to save exactly that.
+ *
+ * The ribbon faces the camera per SEGMENT rather than as a whole: the side
+ * vector is the segment direction crossed with the direction to the eye, so a
+ * ribbon that loops back on itself stays visible along its entire length instead
+ * of vanishing edge-on where it turns.
+ */
+export declare function buildTrailShader(src: TrailSource, cast: {
+    subjects: number;
+    samples: number;
+    base: number;
+    trailBase: number;
+    slots: number;
+    alias: number[];
+    /** Depth convention of the scene buffer this layer tests against. The
+     *  occlusion compare below is MANUAL (the layer has no depth attachment),
+     *  so it does not flip with the pipelines' depthCompare — it has to be
+     *  emitted the right way round at build time. On a reversed-Z device,
+     *  larger z is CLOSER; the unflipped test drew ribbons only when occluded. */
+    reversedZ: boolean;
+}): string;
+export {};
+//# sourceMappingURL=trails.d.ts.map

package/dist/shaders/passes/trails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAwBA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6SR"}