reze-engine 0.42.3 → 0.50.0

package/dist/shaders/passes/composite.js

@@ -1,3 +1,11 @@
+import { RZ_LIGHT_STRUCT_WGSL } from "../lights";
+import { anchorAliasWgsl } from "../anchor-table";
+import { CAST_API } from "../cast-api";
+import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api";
+import { audioApi } from "../audio-api";
+import { lyricsApi, lyricsTextApi } from "../lyrics-api";
+import { midiApi } from "../midi-api";
+import { gridReadApi } from "./grid";
 // Composite: HDR scene + bloom pyramid → Filmic tone map → gamma → swapchain.
 // Bloom tint/intensity applied at combine (EEVEE treats them as combine-stage params, not prefilter).
 //
@@ -69,20 +77,9 @@ export function parseEffectAnchors(wgsl, max) {
         .map((m) => ({ bone: m[1], trail: m[2] !== undefined }))
         .slice(0, max);
 }
-/**
- * The caps the cast buffer is built to, shared by the shader below and by the
- * engine that fills it. Interpolated into the WGSL rather than written twice:
- * the layout arithmetic on both sides has to agree exactly, and two literals
- * that must match are two literals that eventually will not.
- *
- * All three are MINIMUMS. Raising one breaks nothing, because effects read
- * through accessors and loop to the count functions; lowering one does.
- */
-export const EFFECT_SUBJECTS = 4;
-export const EFFECT_ANCHORS = 8;
-export const EFFECT_TRAIL_SAMPLES = 128;
-/** vec4 slot where the trails begin — after the subjects and the anchors. */
-export const EFFECT_TRAIL_BASE = EFFECT_SUBJECTS * 3 + EFFECT_ANCHORS * EFFECT_SUBJECTS * 3;
+// The cast's caps live in cast-layout.ts — re-exported here because half the
+// engine imports them from this file and the constants did not move in meaning.
+export { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "../cast-layout";
 const COMPOSITE_HEAD = /* wgsl */ `
 // Pipeline-override constant: the engine creates two composite pipelines, one
 // with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.
@@ -148,13 +145,39 @@ override APPLY_GAMMA: bool = true;
 // vec4 slots: [0 .. 11] four subjects, three each (root+valid, hip, bounds);
 // then MAX_ANCHORS × four subjects, three each (pos+valid, vel, fwd).
 @group(0) @binding(11) var<storage, read> _rzCast: array<vec4f>;
+// The FIELD LAYER: the user's background/foreground mounts, rendered at half
+// resolution in their own pass (see buildFieldShader) and sampled here. Field
+// effects are glows, fog, shafts, gradients — low-frequency by nature — and
+// running them per quarter-pixel was the single largest per-frame cost an
+// effect could add. Bilinear upsampling is invisible at that frequency.
+// The field layer, ONE PAIR PER RESOLUTION. 15/16 are full res, 20/21 half.
+// An effect draws into the pair it declared, so a starfield that upsamples
+// perfectly no longer pays full-resolution pixels because a neighbour needed
+// crisp edges. Both pairs are read every frame and combined full-over-half
+// below; a pair NO effect draws into is bound to a 1x1 transparent texture
+// instead of a target, so nothing has to clear a full-res pair to hand this
+// shader the transparent black it would then read.
+@group(0) @binding(15) var fieldBgTex: texture_2d<f32>;
+@group(0) @binding(16) var fieldFgTex: texture_2d<f32>;
+@group(0) @binding(20) var fieldBgHalfTex: texture_2d<f32>;
+@group(0) @binding(21) var fieldFgHalfTex: texture_2d<f32>;
 
+/** Two field layers into one, premultiplied OVER, top in front. A resolution
+ *  boundary is a layer boundary: within a pair, effects blend in document
+ *  order; across pairs, full res wins. (No backticks in here — this string is
+ *  a TS template literal and one ends it mid-shader.) */
+fn rzFieldMerge(top: vec4f, bot: vec4f) -> vec4f {
+  return vec4f(top.rgb + bot.rgb * (1.0 - top.a), top.a + bot.a * (1.0 - top.a));
+}
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
 
 fn linearDepth(coord: vec2<i32>) -> f32 {
   let z = textureLoad(depthTex, coord, 0);
-  // projA > 1 for every valid z in [0,1], so the divisor never crosses zero.
+  // projA and projB are m[10] and m[14] of whatever projection the camera built,
+  // so this one line inverts both conventions. Non-reversed puts projA just above
+  // 1; reversed puts it slightly below 0. Either way (z - projA) keeps its sign
+  // across the whole of z in [0,1], so the divisor never crosses zero.
   return clamp(dofU[2].y / (z - dofU[2].x), 0.05, 100000.0);
 }
 
@@ -242,7 +265,21 @@ fn viewTransform(c: vec3f) -> vec3f {
   if (mode > 0.5) { return vec3f(srgb_encode(c.r), srgb_encode(c.g), srgb_encode(c.b)); }
   return vec3f(filmic(c.r), filmic(c.g), filmic(c.b));
 }
-
+`;
+/**
+ * The scene half of the effect API — camera, projection, cast, trails.
+ *
+ * Split out of COMPOSITE_HEAD so the SIM pass can have it too. One effect file
+ * is spliced into every module it has a mount in, so a file with both a grid and
+ * a foreground compiles its foreground inside the grid shader, where every
+ * rzCameraPos() in it has to resolve. Sharing the block is better than stubbing
+ * it twice, and it means a kernel can legitimately ask where a bone is — which
+ * is exactly what a wake wants.
+ *
+ * Depends on `viewU` and `_rzCast` being declared by the including module, and
+ * on nothing else: no textures, no samplers.
+ */
+export const EFFECT_SCENE_API = /* wgsl */ `
 // ── The effect API ────────────────────────────────────────────────────────────
 //
 // Named rz*, for the engine. The prefix earns its place twice: user code is
@@ -288,104 +325,22 @@ fn rzProject(p: vec3f) -> vec3f {
   return vec3f(ndc * 0.5 + 0.5, z);
 }
 
-/** A character, as much of one as a shader needs. */
-struct RzSubject {
-  /** On the FLOOR, under the body — where a ring or a magic circle belongs. */
-  root: vec3f,
-  /** At the hips, the middle of the body — where an aura belongs. */
-  center: vec3f,
-  /** Bounding sphere: xyz centre, w radius. Deliberately generous — cull with it. */
-  bounds: vec4f,
-  /** False past the end of the cast, and every field is then zero. */
-  valid: bool,
-}
-
-/** One bone an effect asked for, by name, at the top of its own source. */
-struct RzAnchor {
-  pos: vec3f,
-  /** World units per second, from the previous frame. Direction for a trail,
-   *  magnitude for anything that should react to how hard someone is moving. */
-  vel: vec3f,
-  /** The bone's forward axis — which way a foot points, where a head looks. */
-  fwd: vec3f,
-  /** False when this rig has no such bone. Check it: the alternative is drawing
-   *  a hand effect at the world origin on every model that spells it differently. */
-  valid: bool,
-}
-
-const RZ_MAX_ANCHORS: i32 = ${EFFECT_ANCHORS};
-
-/**
- * Character i. Loop to rzSubjectCount(), never to a constant — the caps here are
- * MINIMUMS and are free to grow, which is only true while nobody hardcodes them.
- */
-fn rzSubject(i: i32) -> RzSubject {
-  var s: RzSubject;
-  s.valid = i >= 0 && i < rzSubjectCount();
-  if (!s.valid) { return s; }
-  let b = i * 3;
-  s.root = _rzCast[b].xyz;
-  s.center = _rzCast[b + 1].xyz;
-  s.bounds = _rzCast[b + 2];
-  return s;
-}
+fn rzCamPos() -> vec3f { return rzCameraPos(); }
+fn rzCameraRight() -> vec3f { return viewU[3].xyz; }
+fn rzCameraUp() -> vec3f { return viewU[4].xyz; }
+fn rzCameraForward() -> vec3f { return viewU[5].xyz; }
 
-/**
- * The slot-th bone this effect declared, on character subject.
- *
- * Slots are the order of the declarations at the top of your source:
- *
- *     // @anchor 左手首
- *     // @anchor 頭
- *
- * gives you slot 0 and slot 1. Any bone name the model has works; valid is
- * false when it does not have it, which is the normal case across rigs that
- * spell things differently.
- */
-fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
-  var a: RzAnchor;
-  a.valid = false;
-  if (subject < 0 || subject >= rzSubjectCount() || slot < 0 || slot >= RZ_MAX_ANCHORS) { return a; }
-  let b = ${EFFECT_SUBJECTS * 3} + (slot * ${EFFECT_SUBJECTS} + subject) * 3;
-  a.valid = _rzCast[b].w > 0.5;
-  a.pos = _rzCast[b].xyz;
-  a.vel = _rzCast[b + 1].xyz;
-  a.fwd = _rzCast[b + 2].xyz;
-  return a;
-}
+// The cast — subjects, anchors, trails — is CAST_API, shared verbatim with the
+// particle and trail modules. It used to be written out here, a second time, and
+// the two copies had drifted: this one had rzAnchor and that one did not.
+${CAST_API}
 
-const RZ_TRAIL_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
+// The hashes, the noise and rzFalloff — EFFECT_MATH_API, the same text the
+// particle and trail modules get. The field module used to be missing most of
+// it, so a helper an author wrote for one mount failed to compile in another
+// for no reason visible in the file.
+${EFFECT_MATH_API}${PARTICLE_STRUCT_WGSL}
 
-/**
- * How many path samples this anchor has. Zero unless it was declared with
- * trail, and it climbs from zero as the trail fills after the effect loads.
- *
- * Loop to THIS, never to RZ_TRAIL_SAMPLES: the cap is a minimum and is free to
- * grow, which stays true only while nobody hardcodes it.
- */
-fn rzTrailCount(subject: i32, slot: i32) -> i32 {
-  if (subject < 0 || subject >= rzSubjectCount() || slot < 0 || slot >= RZ_MAX_ANCHORS) { return 0; }
-  return i32(_rzCast[${EFFECT_SUBJECTS * 3} + (slot * ${EFFECT_SUBJECTS} + subject) * 3 + 2].w);
-}
-
-/**
- * Sample i of an anchor's path: xyz where it was, w how many seconds ago.
- *
- * i = 0 is NOW and they run backwards in time, so a ribbon is drawn by walking i
- * upward and fading on .w. Sampled at a fixed rate on the SCENE clock, not the
- * display's — so the path is identical in the editor, in an export, and in a
- * re-export, and its spacing does not change with framerate.
- *
- * This is what a hand trail wants instead of position and velocity. One position
- * and one velocity is a straight segment that jitters, because a velocity is a
- * difference between two frames; a path is what actually happened.
- */
-fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
-  let n = rzTrailCount(subject, slot);
-  if (i < 0 || i >= n) { return vec4f(0.0); }
-  let base = ${EFFECT_TRAIL_BASE} + (slot * ${EFFECT_SUBJECTS} + subject) * RZ_TRAIL_SAMPLES;
-  return _rzCast[base + i];
-}
 
 fn bgResolution() -> vec2f { return rzResolution(); }
 fn bgCameraPos() -> vec3f { return rzCameraPos(); }
@@ -432,6 +387,7 @@ fn rzWorldPos(ray: vec3f, depth: f32) -> vec3f {
 }
 
 fn bgWorldPos(ray: vec3f, depth: f32) -> vec3f { return rzWorldPos(ray, depth); }
+${RZ_LIGHT_STRUCT_WGSL}
 
 /** Color grading, applied to the tonemapped SCENE (not the background — see the
  *  call site). The core is ASC CDL, the film-industry interchange standard:
@@ -555,6 +511,19 @@ const COMPOSITE_BODY = /* wgsl */ `
       let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2π)
       let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/π
       bgPm = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;
+      if (bg.w > 2.5) {
+        // Mode 3: the texels are scene-linear RADIANCE, not display wallpaper.
+        // Same exposure, same view transform, same user gamma as the scene —
+        // one film for everything in frame, which is what makes a sun roll off
+        // like a sun instead of clipping at texture white. bg.x carries the
+        // world STRENGTH (the colour slot is dead in equirect modes). The
+        // scene's grade stays scene-only, the documented rule above.
+        var sky = max(viewTransform(bgPm * bg.x * viewU[0].x), vec3f(0.0));
+        if (APPLY_GAMMA) {
+          sky = pow(sky, vec3f(viewU[0].y));
+        }
+        bgPm = sky;
+      }
     }
     BACKGROUND_CALL
   }
@@ -562,6 +531,11 @@ const COMPOSITE_BODY = /* wgsl */ `
   // expression, because the foreground mount composites onto it.
   var outRgb = disp * sceneAlpha + bgPm * (1.0 - sceneAlpha);
   var outA = sceneAlpha + bgA * (1.0 - sceneAlpha);
+  // Ribbons are NOT read here any more: they draw inside the scene pass, so
+  // they are already in disp — tone mapped, and bloomed, which they never
+  // were while this line existed. Sampling them here as well would draw them
+  // twice, and the layer nothing clears would go stale the moment an effect
+  // was removed.
   FOREGROUND_CALL
   return vec4f(outRgb, outA);
 }
@@ -571,28 +545,29 @@ const COMPOSITE_BODY = /* wgsl */ `
 // OVER onto the base layer. No `if` around it: the pipeline is rebuilt per
 // effect, so this text only exists in variants whose WGSL defines background().
 const BACKGROUND_CALL = /* wgsl */ `
-    let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-    let bgFx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
-    bgPm = bgFx.rgb * bgFx.a + bgPm * (1.0 - bgFx.a);
+    // The field layer is PREMULTIPLIED: N effects blend into it in document
+    // order, and premultiplied is the only form in which repeated OVER composes
+    // associatively — straight alpha would need the divide back out on every
+    // draw. So rgb is already scaled by its own alpha and must not be again.
+    // With one effect drawing over a cleared target this is identical to the
+    // straight form it replaced.
+    let bgFx = rzFieldMerge(
+      clamp(textureSampleLevel(fieldBgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)),
+      clamp(textureSampleLevel(fieldBgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)));
+    bgPm = bgFx.rgb + bgPm * (1.0 - bgFx.a);
     bgA = bgFx.a + bgA * (1.0 - bgFx.a);
 `;
 // Same OVER, one layer later — onto the finished frame rather than onto the
 // base. Ungated by design: a foreground runs at every pixel, including the ones
 // the model covers, because covering them is the point.
 const FOREGROUND_CALL = /* wgsl */ `
-  let fgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-  // The scene's own depth, so the effect can tell what is in front of it: a
-  // petal compares its distance against this and lets the model take the pixel,
-  // and fog's alpha is nothing but a function of it. Pixels the scene never drew
-  // read the far plane, so distance fog closes over the backdrop too.
-  let fgFx = clamp(foreground(dir, fgUv, viewU[6].x, linearDepth(coord)), vec4f(0.0), vec4f(1.0));
-  outRgb = fgFx.rgb * fgFx.a + outRgb * (1.0 - fgFx.a);
+  // Premultiplied, as the background layer above — same reason.
+  let fgFx = rzFieldMerge(
+    clamp(textureSampleLevel(fieldFgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)),
+    clamp(textureSampleLevel(fieldFgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)));
+  outRgb = fgFx.rgb + outRgb * (1.0 - fgFx.a);
   outA = fgFx.a + outA * (1.0 - fgFx.a);
 `;
-// Derivative builtins are illegal in non-uniform control flow (WGSL uniformity
-// analysis rejects the pipeline), so the coverage gate below can only wrap
-// effect code that doesn't use them. Checked textually at build time.
-const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/;
 /** The condition on the background block (equirect sample + background effect).
  *
  *  Two jobs. It skips the block behind pixels the model fully covers — the
@@ -601,33 +576,148 @@ const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/;
  *  most). And with no background effect compiled in, it also skips the block
  *  entirely unless the equirect needs it.
  *
- *  The equirect uses explicit-LOD sampling, which is always legal in non-uniform
- *  flow; only derivative-using effects must keep uniform control flow and forgo
- *  the coverage half. The test is textual over the whole file, so a foreground
- *  that uses fwidth costs the background its gate — conservative, and only ever
- *  in the direction of correctness. (The foreground mount itself sits in uniform
- *  flow, so derivatives are always legal there.) */
+ *  Everything the gate wraps is an explicit-LOD sample or a texture read, both
+ *  always legal in non-uniform flow. It used to also wrap the user's code, which
+ *  meant an effect using a derivative builtin had to forfeit the gate; that
+ *  carve-out went with the field pass, and the last of it is below. */
 function backgroundCondition(effect) {
     // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
     // sharp scene fully covered can end up needing background behind its blur.
+    // (The old derivative carve-out is gone with the inline user code: the field
+    // pass runs the whole quad, which is uniform control flow by construction.)
     const coverage = "sceneAlpha < 0.999";
     if (!effect?.hasBackground)
         return `bg.w > 1.5 && ${coverage}`;
-    return USES_DERIVATIVES.test(effect.wgsl) ? "true" : coverage;
+    return coverage;
 }
 export function buildCompositeShader(effect) {
     const body = COMPOSITE_BODY.replace("BACKGROUND_COND", backgroundCondition(effect))
         .replace("BACKGROUND_CALL", effect?.hasBackground ? BACKGROUND_CALL.trim() : "")
         .replace("FOREGROUND_CALL", effect?.hasForeground ? FOREGROUND_CALL.trim() : "");
-    if (!effect)
-        return COMPOSITE_HEAD + body;
+    // The composite is STATIC either way now: the user's code compiles in the
+    // field module alone, and the composite only decides whether to sample it.
+    return COMPOSITE_HEAD +
+        EFFECT_SCENE_API + anchorAliasWgsl(effect?.alias ?? []) + audioApi(0, 13) + midiApi(0, 19) + lyricsApi(0, 24) + body;
+}
+/**
+ * The field pass: the user's background/foreground mounts at half resolution,
+ * into two rgba16f targets the composite bilinearly upsamples.
+ *
+ * The fragment reconstructs the FULL-resolution pixel it stands in for and runs
+ * the original derivation verbatim — same ndc, same ray, same uv, same depth
+ * read — so an effect cannot tell it moved; it is simply asked half as often
+ * in each direction.
+ */
+/**
+ * Reading the scene's id attachment from a field effect — the consumer the MRT
+ * work exists for.
+ *
+ * A field effect covers the whole screen and has no idea what it is drawing
+ * over. These make it addressable: mask a glow to one character, dissolve one
+ * material, outline the thing someone selected. Without them the id buffer is
+ * written every frame and read by nobody.
+ *
+ * MULTISAMPLED AND UNRESOLVED, so it is read the way it is written —
+ * textureLoad of sample 0, the same rule linearDepth already follows. An
+ * averaged id belongs to nothing.
+ *
+ * When ids are OFF the buffer does not exist, so the accessors are still
+ * DECLARED and answer 0 — the reserved nothing. An effect that masks by id then
+ * masks nothing at all, which is a scene that renders rather than a shader that
+ * will not compile.
+ */
+function idApi(on, group, binding) {
+    if (!on) {
+        return /* wgsl */ `
+fn rzObjectAt(uv: vec2f) -> u32 { return 0u; }
+fn rzMaterialAt(uv: vec2f) -> u32 { return 0u; }
+`;
+    }
+    return /* wgsl */ `
+@group(${group}) @binding(${binding}) var _rzIdTex: texture_multisampled_2d<u32>;
+
+/** Which OBJECT drew this pixel — compare against rzSubjectId(i). 0 = nothing. */
+fn rzObjectAt(uv: vec2f) -> u32 {
+  let sz = vec2f(textureDimensions(_rzIdTex));
+  let p = vec2<i32>(clamp(uv, vec2f(0.0), vec2f(1.0)) * sz);
+  return textureLoad(_rzIdTex, clamp(p, vec2<i32>(0), vec2<i32>(sz) - vec2<i32>(1)), 0).y;
+}
+
+/** Which MATERIAL drew it, within that object. 0 = nothing. */
+fn rzMaterialAt(uv: vec2f) -> u32 {
+  let sz = vec2f(textureDimensions(_rzIdTex));
+  let p = vec2<i32>(clamp(uv, vec2f(0.0), vec2f(1.0)) * sz);
+  return textureLoad(_rzIdTex, clamp(p, vec2<i32>(0), vec2<i32>(sz) - vec2<i32>(1)), 0).x;
+}
+`;
+}
+export function buildFieldShader(effect) {
+    const bgLine = effect.hasBackground
+        ? "out.bg = clamp(background(dir, uv, _rzFieldClock.x), vec4f(0.0), vec4f(1.0));"
+        : "";
+    const fgLine = effect.hasForeground
+        ? "out.fg = clamp(foreground(dir, uv, _rzFieldClock.x, linearDepth(vec2<i32>(min(fx, fullSz - 1.0)))), vec4f(0.0), vec4f(1.0));"
+        : "";
     return (COMPOSITE_HEAD +
+        EFFECT_SCENE_API +
+        anchorAliasWgsl(effect.alias ?? []) +
+        audioApi(0, 13) +
+        midiApi(0, 19) +
+        lyricsApi(0, 24) +
+        // The words themselves — the atlas rides the grid's sampler, which is
+        // declared just below and resolves module-wide.
+        lyricsTextApi(0, 25, "_rzGridSamp") +
+        // The persistent grid, always bound — a 1×1 of zeroes when the effect has
+        // none, so rzGrid() is a function that always exists rather than one an
+        // author has to know whether they are allowed to call.
+        gridReadApi(0, 17, 18, effect.gridSize) +
+        clockApi("_rzFieldClock.x", "0.0") +
+        viewportApi("viewU[6].w") +
+        trailSlotsApi(effect.trailCount) +
+        idApi(effect.ids === true, 0, 23) +
         "\n// ── user effect (setEffect) ──\n" +
         effect.paramsDecl +
         "\n" +
         effect.wgsl +
         "\n" +
-        body);
+        /* wgsl */ `
+@group(0) @binding(14) var<uniform> fieldU: vec4f;
+/**
+ * THIS EFFECT'S OWN clock, seconds since it was installed.
+ *
+ * Per effect, and that is the whole point of it existing. The time argument
+ * used to come from viewU[6].x, which is measured from the FIRST installed
+ * effect's epoch — so every later effect started mid-stream, and an effect
+ * whose lightEmit read its own epoch disagreed with its own background()
+ * about what time it was. One buffer per effect, one answer.
+ */
+@group(0) @binding(22) var<uniform> _rzFieldClock: vec4f;
+
+@vertex fn fieldVs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  let x = f32((vi & 1u) << 2u) - 1.0;
+  let y = f32((vi & 2u) << 1u) - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+struct FieldOut {
+  @location(0) bg: vec4f,
+  @location(1) fg: vec4f,
+}
+
+@fragment fn fieldFs(@builtin(position) fragCoord: vec4f) -> FieldOut {
+  let fullSz = fieldU.zw;
+  let fx = fragCoord.xy * (fullSz / max(fieldU.xy, vec2f(1.0)));
+  let ndc = vec2f(fx.x / fullSz.x * 2.0 - 1.0, 1.0 - fx.y / fullSz.y * 2.0);
+  let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
+  let uv = vec2f(fx.x / fullSz.x, 1.0 - fx.y / fullSz.y);
+  var out: FieldOut;
+  out.bg = vec4f(0.0);
+  out.fg = vec4f(0.0);
+  ${bgLine}
+  ${fgLine}
+  return out;
+}
+`);
 }
 /** Kept for compatibility with existing imports (the base, no-effect shader). */
 export const COMPOSITE_SHADER_WGSL = buildCompositeShader(null);

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

@@ -0,0 +1,2 @@
+export declare const CULL_COMPUTE_WGSL = "\nstruct DrawMeta {\n  lo: vec3f,      // model-space AABB min \u2014 read only for RIGID models\n  model: u32,     // index into models[]\n  hi: vec3f,      // model-space AABB max\n  flags: u32,     // bit0 = casts shadow\n};\n\nstruct ModelRec {\n  xform: mat4x4f, // model space -> world; meaningful only when RIGID\n  sphere: vec4f,  // world-space centre.xyz + radius.w; meaningful when SKINNED\n  flags: u32,     // bit0 = visible, bit1 = rigid\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n};\n\n// Camera planes at 0..5, light planes at 6..11, mirror planes at 12..17.\n// counts.x = draw count, counts.y = 0 to pass everything (setCullEnabled).\nstruct Frusta {\n  planes: array<vec4f, 18>,\n  counts: vec4u,\n};\n\n@group(0) @binding(0) var<storage, read> metas: array<DrawMeta>;\n@group(0) @binding(1) var<storage, read> models: array<ModelRec>;\n@group(0) @binding(2) var<uniform> frusta: Frusta;\n@group(0) @binding(3) var<storage, read_write> cameraArgs: array<u32>;\n@group(0) @binding(4) var<storage, read_write> shadowArgs: array<u32>;\n// 1 = the user hid this material, or a material morph drove its alpha to zero.\n// Here rather than in the encode loop because a render bundle bakes its draw\n// list: a face VMD rewrites the morph-hidden set every frame, so a bundle that\n// invalidated on it would re-record every frame and cost more than it saves.\n@group(0) @binding(5) var<storage, read> hidden: array<u32>;\n@group(0) @binding(6) var<storage, read_write> mirrorArgs: array<u32>;\n\nconst DRAW_CASTS_SHADOW: u32 = 1u;\nconst MODEL_VISIBLE: u32 = 1u;\nconst MODEL_RIGID: u32 = 2u;\n\n// Signed distance of the AABB's most-positive corner: the centre distance plus\n// the extent projected onto |n|. Negative means every corner is behind the\n// plane, which is the only case that can reject.\nfn aabbVisible(base: u32, c: vec3f, e: vec3f) -> bool {\n  for (var i = 0u; i < 6u; i = i + 1u) {\n    let p = frusta.planes[base + i];\n    if (dot(p.xyz, c) + p.w + dot(e, abs(p.xyz)) < 0.0) { return false; }\n  }\n  return true;\n}\n\nfn sphereVisible(base: u32, s: vec4f) -> bool {\n  for (var i = 0u; i < 6u; i = i + 1u) {\n    let p = frusta.planes[base + i];\n    if (dot(p.xyz, s.xyz) + p.w + s.w < 0.0) { return false; }\n  }\n  return true;\n}\n\n@compute @workgroup_size(64)\nfn cs(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let i = gid.x;\n  if (i >= frusta.counts.x) { return; }\n\n  // Named dm, not meta: \"meta\" is a WGSL reserved word (reserved for future use,\n  // so it parses nowhere). No backticks anywhere in this string either \u2014 it is a\n  // template literal, and one would end the shader mid-comment.\n  let dm = metas[i];\n  let m = models[dm.model];\n  let visible = (m.flags & MODEL_VISIBLE) != 0u;\n\n  var inCamera = false;\n  var inLight = false;\n  var inMirror = false;\n  if (visible) {\n    if ((m.flags & MODEL_RIGID) != 0u) {\n      let c = (dm.lo + dm.hi) * 0.5;\n      let e = (dm.hi - dm.lo) * 0.5;\n      let wc = (m.xform * vec4f(c, 1.0)).xyz;\n      // Extent of the transformed box: the abs of the linear part applied to the\n      // half-extent. Exact for the axis-aligned case, conservative for a rotation.\n      let a = mat3x3f(abs(m.xform[0].xyz), abs(m.xform[1].xyz), abs(m.xform[2].xyz));\n      let we = a * e;\n      inCamera = aabbVisible(0u, wc, we);\n      inLight = aabbVisible(6u, wc, we);\n      inMirror = aabbVisible(12u, wc, we);\n    } else {\n      inCamera = sphereVisible(0u, m.sphere);\n      inLight = sphereVisible(6u, m.sphere);\n      inMirror = sphereVisible(12u, m.sphere);\n    }\n  }\n\n  // Culling off (setCullEnabled) passes everything, so a scene can be A/B'd\n  // against its own unculled self without rebuilding anything. The pass still\n  // runs, so the diagnostics keep reporting. It bypasses the FRUSTUM only \u2014\n  // a hidden material is not culled, it is switched off, and answering \"is this\n  // gone because of culling?\" requires the two to stay separable.\n  let off = frusta.counts.y == 0u;\n  let shown = hidden[i] == 0u;\n  let castsShadow = (dm.flags & DRAW_CASTS_SHADOW) != 0u;\n  cameraArgs[i * 5u + 1u] = select(0u, 1u, (inCamera || off) && shown);\n  shadowArgs[i * 5u + 1u] = select(0u, 1u, ((inLight && castsShadow) || off) && shown);\n  mirrorArgs[i * 5u + 1u] = select(0u, 1u, (inMirror || off) && shown);\n}\n";
+//# sourceMappingURL=cull.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cull.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/cull.ts"],"names":[],"mappings":"AAiCA,eAAO,MAAM,iBAAiB,uwIAyG7B,CAAA"}

package/dist/shaders/passes/cull.js

@@ -0,0 +1,138 @@
+// GPU frustum cull writing indirect draw arguments.
+//
+// One dispatch covers every material draw in the scene and writes THREE
+// argument buffers — the camera pass, the shadow pass and the mirror pass —
+// because they differ only in which frustum they test against, and splitting
+// them into separate dispatches would read the same metadata each time. See
+// docs/frame-graph.md.
+//
+// The MIRROR frustum is the camera frustum reflected about the floor plane: an
+// object is visible in the mirror exactly when its reflection is visible to
+// the camera, i.e. when the object itself lies in the reflected frustum. The
+// camera args would be WRONG for it — a close-up of the floor shows a dancer's
+// reflection while the dancer herself is out of frame. When no reflection is
+// active the CPU writes the camera planes into the mirror slots, so the args
+// stay sane for bundles that never execute.
+//
+// The compute writes ONLY `instanceCount` (word 1 of each 5-word record). The
+// other four words — indexCount, firstIndex, baseVertex, firstInstance — are
+// seeded by the CPU when the draw list changes, which is the same moment the
+// metadata buffer is uploaded. Nothing about them varies per frame, so shipping
+// them through the compute would be a per-frame write in exchange for nothing.
+//
+// Two bound kinds, because a skinned mesh has no usable model-space bounds:
+//   RIGID   — every bone of the model shares one skin matrix (a stage, or a
+//             character still in its bind pose), so each material's load-time
+//             model-space AABB is valid and gets transformed by that matrix.
+//             This is what makes a 200-material stage worth culling at all.
+//   SKINNED — animation invalidates per-material bounds, so the whole model is
+//             one world-space sphere derived from its posed bone positions.
+//
+// Planes are NORMALIZED on the CPU. The AABB test would tolerate unnormalized
+// planes (distance and extent scale together), the sphere test would not.
+export const CULL_COMPUTE_WGSL = /* wgsl */ `
+struct DrawMeta {
+  lo: vec3f,      // model-space AABB min — read only for RIGID models
+  model: u32,     // index into models[]
+  hi: vec3f,      // model-space AABB max
+  flags: u32,     // bit0 = casts shadow
+};
+
+struct ModelRec {
+  xform: mat4x4f, // model space -> world; meaningful only when RIGID
+  sphere: vec4f,  // world-space centre.xyz + radius.w; meaningful when SKINNED
+  flags: u32,     // bit0 = visible, bit1 = rigid
+  pad0: u32,
+  pad1: u32,
+  pad2: u32,
+};
+
+// Camera planes at 0..5, light planes at 6..11, mirror planes at 12..17.
+// counts.x = draw count, counts.y = 0 to pass everything (setCullEnabled).
+struct Frusta {
+  planes: array<vec4f, 18>,
+  counts: vec4u,
+};
+
+@group(0) @binding(0) var<storage, read> metas: array<DrawMeta>;
+@group(0) @binding(1) var<storage, read> models: array<ModelRec>;
+@group(0) @binding(2) var<uniform> frusta: Frusta;
+@group(0) @binding(3) var<storage, read_write> cameraArgs: array<u32>;
+@group(0) @binding(4) var<storage, read_write> shadowArgs: array<u32>;
+// 1 = the user hid this material, or a material morph drove its alpha to zero.
+// Here rather than in the encode loop because a render bundle bakes its draw
+// list: a face VMD rewrites the morph-hidden set every frame, so a bundle that
+// invalidated on it would re-record every frame and cost more than it saves.
+@group(0) @binding(5) var<storage, read> hidden: array<u32>;
+@group(0) @binding(6) var<storage, read_write> mirrorArgs: array<u32>;
+
+const DRAW_CASTS_SHADOW: u32 = 1u;
+const MODEL_VISIBLE: u32 = 1u;
+const MODEL_RIGID: u32 = 2u;
+
+// Signed distance of the AABB's most-positive corner: the centre distance plus
+// the extent projected onto |n|. Negative means every corner is behind the
+// plane, which is the only case that can reject.
+fn aabbVisible(base: u32, c: vec3f, e: vec3f) -> bool {
+  for (var i = 0u; i < 6u; i = i + 1u) {
+    let p = frusta.planes[base + i];
+    if (dot(p.xyz, c) + p.w + dot(e, abs(p.xyz)) < 0.0) { return false; }
+  }
+  return true;
+}
+
+fn sphereVisible(base: u32, s: vec4f) -> bool {
+  for (var i = 0u; i < 6u; i = i + 1u) {
+    let p = frusta.planes[base + i];
+    if (dot(p.xyz, s.xyz) + p.w + s.w < 0.0) { return false; }
+  }
+  return true;
+}
+
+@compute @workgroup_size(64)
+fn cs(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  if (i >= frusta.counts.x) { return; }
+
+  // Named dm, not meta: "meta" is a WGSL reserved word (reserved for future use,
+  // so it parses nowhere). No backticks anywhere in this string either — it is a
+  // template literal, and one would end the shader mid-comment.
+  let dm = metas[i];
+  let m = models[dm.model];
+  let visible = (m.flags & MODEL_VISIBLE) != 0u;
+
+  var inCamera = false;
+  var inLight = false;
+  var inMirror = false;
+  if (visible) {
+    if ((m.flags & MODEL_RIGID) != 0u) {
+      let c = (dm.lo + dm.hi) * 0.5;
+      let e = (dm.hi - dm.lo) * 0.5;
+      let wc = (m.xform * vec4f(c, 1.0)).xyz;
+      // Extent of the transformed box: the abs of the linear part applied to the
+      // half-extent. Exact for the axis-aligned case, conservative for a rotation.
+      let a = mat3x3f(abs(m.xform[0].xyz), abs(m.xform[1].xyz), abs(m.xform[2].xyz));
+      let we = a * e;
+      inCamera = aabbVisible(0u, wc, we);
+      inLight = aabbVisible(6u, wc, we);
+      inMirror = aabbVisible(12u, wc, we);
+    } else {
+      inCamera = sphereVisible(0u, m.sphere);
+      inLight = sphereVisible(6u, m.sphere);
+      inMirror = sphereVisible(12u, m.sphere);
+    }
+  }
+
+  // Culling off (setCullEnabled) passes everything, so a scene can be A/B'd
+  // against its own unculled self without rebuilding anything. The pass still
+  // runs, so the diagnostics keep reporting. It bypasses the FRUSTUM only —
+  // a hidden material is not culled, it is switched off, and answering "is this
+  // gone because of culling?" requires the two to stay separable.
+  let off = frusta.counts.y == 0u;
+  let shown = hidden[i] == 0u;
+  let castsShadow = (dm.flags & DRAW_CASTS_SHADOW) != 0u;
+  cameraArgs[i * 5u + 1u] = select(0u, 1u, (inCamera || off) && shown);
+  shadowArgs[i * 5u + 1u] = select(0u, 1u, ((inLight && castsShadow) || off) && shown);
+  mirrorArgs[i * 5u + 1u] = select(0u, 1u, (inMirror || off) && shown);
+}
+`;

package/dist/shaders/passes/field-blit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The field layer, drawn INTO the scene.
+ *
+ * Field effects render into their own targets at their own resolution — that
+ * part was always right. What was wrong was where the result landed: the
+ * composite sampled it AFTER tone mapping, which is why a field effect could
+ * never bloom, could never light anything, and tone mapped differently from the
+ * particle and ribbon mounts drawing the same kind of glow.
+ *
+ * Two draws inside the scene pass — background before any geometry, foreground
+ * after all of it — so the bloom pyramid sees field effects and one tone map
+ * covers the whole frame.
+ *
+ * NO DEPTH, neither written nor tested. A foreground is handed the scene's
+ * depth as a parameter and does its own occlusion; testing it here would
+ * occlude it a second time, and a background has nothing to test against.
+ *
+ * COVERAGE IS CLAMPED HERE. Additive field effects SUM their coverage into the
+ * layer (see FIELD_LAYER_BLEND_ADDITIVE), which is what stops the composite's
+ * unpremultiply from dividing colour by nothing — but N additive effects can
+ * sum past 1, and the layer is rgba16float so nothing stopped it on the way in.
+ * A coverage above 1 would darken what the layer is drawn over by more than
+ * fully covering it.
+ */
+export declare function fieldBlitShaderWgsl(): string;
+//# sourceMappingURL=field-blit.d.ts.map

package/dist/shaders/passes/field-blit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-blit.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/field-blit.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAuC5C"}