reze-engine 0.39.0 → 0.41.0

package/src/model.ts

@@ -1141,42 +1141,6 @@ export class Model {
     return this.skeleton.inverseBindMatrices
   }
 
-  /** World-space positions of `count` vertices sampled evenly across the mesh
-   *  under the CURRENT pose — the model's skinning replayed on the CPU for
-   *  this one call, root transform included. Feed to Engine.emitParticles for
-   *  dissolve/materialize effects shaped like the model itself. */
-  sampleSurfacePoints(count: number): Float32Array {
-    const skin = this.getSkinMatrices()
-    const joints = this.skinning.joints
-    const weights = this.skinning.weights
-    const n = this.vertexCount
-    const c = Math.max(1, Math.min(count, n))
-    const out = new Float32Array(c * 3)
-    const step = n / c
-    for (let i = 0; i < c; i++) {
-      const v = Math.min(n - 1, Math.floor(i * step + Math.random() * step))
-      const vi = v * VERTEX_STRIDE
-      const px = this.vertexData[vi]
-      const py = this.vertexData[vi + 1]
-      const pz = this.vertexData[vi + 2]
-      let x = 0
-      let y = 0
-      let z = 0
-      for (let j = 0; j < 4; j++) {
-        const w = weights[v * 4 + j] / 255
-        if (w === 0) continue
-        const m = joints[v * 4 + j] * 16
-        x += w * (skin[m] * px + skin[m + 4] * py + skin[m + 8] * pz + skin[m + 12])
-        y += w * (skin[m + 1] * px + skin[m + 5] * py + skin[m + 9] * pz + skin[m + 13])
-        z += w * (skin[m + 2] * px + skin[m + 6] * py + skin[m + 10] * pz + skin[m + 14])
-      }
-      out[i * 3] = x
-      out[i * 3 + 1] = y
-      out[i * 3 + 2] = z
-    }
-    return out
-  }
-
   getSkinMatrices(): Float32Array {
     const boneCount = this.skeleton.bones.length
     const worldMats = this.runtimeSkeleton.worldMatrices

package/src/shaders/materials/nodes.ts

@@ -506,6 +506,27 @@ fn principled_sheen(NV: f32) -> f32 {
 //   sheen          — 0 disables. Scales the sheen diffuse add; cloth/stockings use ~0.7.
 //   sheen_tint     — 0 = white sheen, 1 = fully tinted by base. Multiplied by sheen,
 //                    so value is don't-care when sheen=0.
+// The PMX sphere map, applied the way MMD applies it: the texture is a
+// VIEW-SPACE lighting mask, sampled by the camera-space normal rather than by
+// any UV the mesh carries, which is why it tracks the viewer and reads as a
+// highlight. The material's own mode picks the operator — .sph (1) multiplies
+// the shaded base, .spa (2) adds — so a graph asks for the effect and the model
+// decides which it meant. Mode 0, or a material with no sphere texture (the 1×1
+// white fallback is bound then), is an exact no-op.
+fn pmx_sphere_map(base: vec3f, strength: f32, N: vec3f) -> vec3f {
+  if (material.sphereMode < 0.5) {
+    return base;
+  }
+  let camera_n = safe_normal((camera.view * vec4f(N, 0.0)).xyz);
+  let sphere_uv = clamp(camera_n.xy * 0.5 + vec2f(0.5), vec2f(0.0), vec2f(1.0));
+  let sphere_rgb = textureSample(sphereTexture, diffuseSampler, sphere_uv).rgb;
+  let amount = max(strength, 0.0);
+  if (material.sphereMode < 1.5) {
+    return mix(base, base * sphere_rgb, min(amount, 1.0));
+  }
+  return base + sphere_rgb * amount;
+}
+
 struct PrincipledIn {
   base: vec3f,
   metallic: f32,

package/src/shaders/passes/composite.ts

@@ -2,30 +2,51 @@
 // Bloom tint/intensity applied at combine (EEVEE treats them as combine-stage params, not prefilter).
 //
 // The shader is a TEMPLATE: buildCompositeShader() emits either the base pass or
-// a variant with a user background effect injected (setBackgroundEffect). The
-// effect is background mode 3, a sibling of the 360 equirect (mode 2) — it reuses
-// the same per-pixel view-ray reconstruction and composites in display space
-// under the scene, so it never affects lighting, bloom, or tonemapping.
+// a variant with user WGSL injected at one or both effect MOUNTS (setEffect).
+// The two mounts are the same idea on either side of the scene:
+//
+//   background(...)  under the scene — a sibling of the 360 equirect (mode 2),
+//                    reusing the same per-pixel view-ray reconstruction.
+//   foreground(...)  over the finished frame, handed the scene's depth in metres
+//                    so it can be occluded by whatever it passes behind.
+//
+// Both composite in display space, so neither affects lighting, bloom, or
+// tonemapping, and both are captured by offline export like any background.
 
-/** What a user background effect must define, documented once:
+/** What user effect WGSL may define, documented once. A file declares its own
+ *  mounts by which of these it defines — defining both is how one file is one
+ *  weather system (dark sky behind, rain in front):
  *
  *    fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+ *    fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
  *
- *  - `ray`  — normalized world-space view direction of this pixel (left-handed,
- *             +Z forward; identical to what the 360 skybox samples by).
- *  - `uv`   — 0..1 across the canvas, origin bottom-left (shadertoy-style).
- *  - `time` — seconds since the effect was applied.
+ *  - `ray`   — normalized world-space view direction of this pixel (left-handed,
+ *              +Z forward; identical to what the 360 skybox samples by).
+ *  - `uv`    — 0..1 across the canvas, origin bottom-left (shadertoy-style).
+ *  - `time`  — seconds since the effect was applied.
+ *  - `depth` — FOREGROUND ONLY. Camera-space distance in metres of whatever the
+ *              scene drew at this pixel, the far plane where it drew nothing.
+ *              Compare a particle's own distance against it and the model
+ *              occludes it; fog needs no comparison at all, its alpha simply IS
+ *              a function of distance.
  *  - `bgResolution()` — canvas size in pixels, for aspect correction.
- *  - declared params arrive as `params.<name>` (f32 or vec3f).
- *  Return display-space sRGB + alpha, 0..1. The effect is a LAYER: it is
- *  over-composited onto the base background (solid color / 360 equirect /
- *  transparent) and sits behind the scene — alpha 0 lets the base show
- *  through, so e.g. a starfield returns stars with a transparent sky. */
+ *  - declared params arrive as `params.<name>` (f32 or vec3f), shared by both.
+ *
+ *  Return display-space sRGB + alpha, 0..1. Both mounts are alpha-composited
+ *  LAYERS, so alpha is what decides how much they replace: a background effect
+ *  at alpha 1 covers the base (solid color / 360 equirect / transparent) and at
+ *  0 lets it through, which is how a starfield is stars over the user's color;
+ *  a foreground at alpha 1 covers the frame. No mode flag anywhere — the alpha
+ *  channel already says it. */
 export type CompositeEffectSource = {
-  /** User WGSL defining `background(...)` (plus any helpers it wants). */
+  /** The user's WGSL verbatim: helpers plus whichever entry points it defines. */
   wgsl: string
-  /** Codegen'd `struct BgParams {...}` + binding decl; empty when no params. */
+  /** Codegen'd `struct EffectParams {...}` + binding decl; empty when no params. */
   paramsDecl: string
+  /** Defines `fn background(...)` — mount under the scene. */
+  hasBackground: boolean
+  /** Defines `fn foreground(...)` — mount over the finished frame. */
+  hasForeground: boolean
 }
 
 const COMPOSITE_HEAD = /* wgsl */ `
@@ -39,7 +60,7 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(0) var hdrTex: texture_2d<f32>;
 @group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)
 @group(0) @binding(2) var bloomSamp: sampler;
-@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 10>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 11>;
 // Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).
 // .g = accumulated canvas alpha (what hdr.a carried before the HDR format
 // became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then
@@ -58,18 +79,63 @@ override APPLY_GAMMA: bool = true;
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
 //            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
 //            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
-//            WGSL effect is a separate LAYER over the base (viewU[6].y flag).
+//            WGSL effect is a separate LAYER over the base — no mode of its own,
+//            and no on/off uniform either: the pipeline is REBUILT per effect, so
+//            the compiled variant IS the flag.
 // viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
 // viewU[5] = (camera forward, _) — refreshed per frame while skybox/effect active.
-// viewU[6] = (time seconds, effect on/off, canvas width, canvas height).
+// viewU[6] = (time seconds, _, canvas width, canvas height).
 // viewU[7] = (grade offset.rgb, contrast);  viewU[8] = (grade power.rgb, saturation);
 // viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
+// viewU[10] = (camera world position, _) — refreshed with the basis above.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
 @group(0) @binding(6) var bgEquirect: texture_2d<f32>;
+// The scene pass's own MSAA depth buffer, bound depth-only. NOT an extra
+// render target: with neither depth of field nor a foreground effect active the
+// scene pass discards depth (TBDR tile memory never spills) and this binding is
+// never read. Either feature makes the pass store it instead, and both read
+// sample 0 — the DoF gather, and linearDepth() for the depth handed to
+// foreground().
+@group(0) @binding(8) var depthTex: texture_depth_multisampled_2d;
+// dofU[0] = (enabled, focusDistance, focusRange, aperture)
+// dofU[1] = (maxBlurRadiusPx, bladeCount, sampleCount, anamorphicRatio)
+// dofU[2] = (projA, projB, _, _) — z-buffer → camera-space depth inversion,
+//           viewZ = projB / (z - projA), rebuilt per frame because near/far
+//           track the camera radius. Cleared depth (1.0) inverts to the far
+//           plane, so empty sky reads as maximally defocused background.
+@group(0) @binding(9) var<uniform> dofU: array<vec4<f32>, 3>;
 
 // 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.
+  return clamp(dofU[2].y / (z - dofU[2].x), 0.05, 100000.0);
+}
+
+/** Signed circle of confusion in device pixels — negative in front of the
+ *  focus band, positive behind it, zero inside it. */
+fn circleOfConfusion(depth: f32) -> f32 {
+  let focus = max(dofU[0].y, 0.05);
+  let halfRange = max(dofU[0].z * 0.5, 0.01);
+  let delta = depth - focus;
+  let outside = max(abs(delta) - halfRange, 0.0);
+  let radius = min(outside / max(depth, 0.05) * dofU[0].w * dofU[1].x, dofU[1].x);
+  return select(-radius, radius, delta >= 0.0);
+}
+
+/** Premultiplied scene color (HDR + bloom) at an arbitrary pixel, for the
+ *  bokeh gather. Explicit-LOD sampling only — legal in non-uniform flow. */
+fn sceneSample(coord: vec2<i32>, fullSzI: vec2<i32>, fullSz: vec2f) -> vec4f {
+  let p = clamp(coord, vec2<i32>(0), fullSzI - vec2<i32>(1));
+  let sAlpha = textureLoad(maskTex, p, 0).g;
+  let sHdr = textureLoad(hdrTex, p, 0).rgb / max(sAlpha, 1e-6);
+  let sUv = (vec2f(p) + vec2f(0.5)) / fullSz;
+  let sBloom = textureSampleLevel(bloomTex, bloomSamp, sUv, 0.0).rgb * viewU[1].xyz * viewU[1].w;
+  return vec4f((sHdr + sBloom) * sAlpha, sAlpha);
+}
+
 fn filmic(x: f32) -> f32 {
   // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender
   // look_medium-high-contrast.spi1d): linear 0.18 → ~0.395, linear 1.0 → ~0.83.
@@ -81,9 +147,26 @@ fn filmic(x: f32) -> f32 {
   return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;
 }
 
-/** Canvas size in pixels — for user background effects (aspect correction). */
+/** Canvas size in pixels — for user effects (aspect correction). */
 fn bgResolution() -> vec2f { return viewU[6].zw; }
 
+/** The camera's world position. */
+fn bgCameraPos() -> vec3f { return viewU[10].xyz; }
+
+/** Where in the WORLD the scene drew this pixel — the depth handed to
+ *  foreground() turned into a place. Without it an effect can only think in
+ *  distances from the lens, which is no use to anything that belongs somewhere:
+ *  fog lying on the ground has to know where the ground is.
+ *
+ *  depth measures along the VIEW AXIS, not along the ray, so it is divided by
+ *  the ray's projection onto camera-forward before being walked out. At the far
+ *  plane (nothing drawn) this lands a very long way off, which is what a sky
+ *  should do to anything reading it. */
+fn bgWorldPos(ray: vec3f, depth: f32) -> vec3f {
+  let axis = max(dot(normalize(ray), viewU[5].xyz), 1e-4);
+  return bgCameraPos() + normalize(ray) * (depth / axis);
+}
+
 /** Color grading, applied to the tonemapped SCENE (not the background — see the
  *  call site). The core is ASC CDL, the film-industry interchange standard:
  *
@@ -124,7 +207,59 @@ const COMPOSITE_BODY = /* wgsl */ `
   let intensity = viewU[1].w;
   let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;
   let combined = straight + bloom;
-  let exposed = combined * exp2(viewU[0].x);
+
+  // ── Depth of field ──
+  // Single-pass golden-angle gather over a polygonal (bladed) disk, in
+  // premultiplied HDR before tonemap. Near-field taps that see focused
+  // background are heavily down-weighted so a sharp subject doesn't bleed into
+  // a blurred foreground; the reverse leak (background bokeh over the subject
+  // edge) is damped less — that soft halo is what real lenses do. Scene layer
+  // only: the composited background (solid / 360 / effect) stays sharp, which
+  // is invisible while it sits at infinity behind a far-blurred stage.
+  var scenePm = vec4f(combined * alpha, alpha);
+  if (dofU[0].x > 0.5) {
+    let centerDepth = linearDepth(coord);
+    let centerCoc = circleOfConfusion(centerDepth);
+    let radius = abs(centerCoc);
+    if (radius > 0.35) {
+      let fullSzI = vec2<i32>(fullSz);
+      let sampleCount = clamp(dofU[1].z, 6.0, 24.0);
+      let blades = clamp(dofU[1].y, 3.0, 12.0);
+      let sector = 6.28318530718 / blades;
+      var accum = scenePm;
+      var weightSum = 1.0;
+      for (var i = 0u; i < 24u; i++) {
+        if (f32(i) >= sampleCount) { break; }
+        let fi = f32(i) + 0.5;
+        let ring = sqrt(fi / sampleCount);
+        let angle = fi * 2.39996323;
+        let localAngle = (fract((angle + 3.14159265359) / sector) - 0.5) * sector;
+        let polygonRadius = cos(3.14159265359 / blades) / max(cos(localAngle), 0.01);
+        var disk = vec2f(cos(angle), sin(angle)) * ring * polygonRadius;
+        disk.x *= max(dofU[1].w, 0.25);
+        let sp = coord + vec2<i32>(round(disk * radius));
+        let cp = clamp(sp, vec2<i32>(0), fullSzI - vec2<i32>(1));
+        let sampleDepth = linearDepth(cp);
+        let sampleCoc = circleOfConfusion(sampleDepth);
+        var w = 1.0;
+        if (centerCoc < 0.0 && sampleDepth > centerDepth + dofU[0].z) {
+          w *= 0.08;
+        } else if (centerCoc > 0.0 && sampleDepth > centerDepth + dofU[0].z * 2.0) {
+          w *= 0.35;
+        }
+        // A tap only contributes where its own blur circle reaches this pixel.
+        let sampleRadius = abs(sampleCoc);
+        w *= mix(0.2, 1.0, smoothstep(ring * radius - 1.0, ring * radius + 1.0, sampleRadius));
+        accum += sceneSample(cp, fullSzI, fullSz) * w;
+        weightSum += w;
+      }
+      scenePm = mix(scenePm, accum / max(weightSum, 1e-5), smoothstep(0.35, 1.75, radius));
+    }
+  }
+  let sceneAlpha = scenePm.a;
+  let sceneStraight = scenePm.rgb / max(sceneAlpha, 1e-6);
+
+  let exposed = sceneStraight * exp2(viewU[0].x);
   let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));
   var disp = max(tm, vec3f(0.0));
   // Grade the SCENE only, before the display gamma. Deliberately not applied to
@@ -143,40 +278,54 @@ const COMPOSITE_BODY = /* wgsl */ `
   let bg = viewU[2];
   var bgA = select(0.0, 1.0, bg.w > 0.5);
   var bgPm = bg.rgb * bgA;  // premultiplied accumulator
-  let fxOn = viewU[6].y > 0.5;
-  if ((bg.w > 1.5 || fxOn) COVERAGE_GATE) {
-    // The equirect and any effect both need this pixel's world-space view ray,
-    // rebuilt from the camera basis. The dome sits at infinity (no parallax) —
-    // PhotoDome-style, display-only.
-    let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.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);
+  // This pixel's world-space view ray, rebuilt from the camera basis — what the
+  // equirect samples by, and what both effect mounts navigate by. The dome sits
+  // at infinity (no parallax): PhotoDome-style, display-only. Hoisted out of the
+  // branch below because the foreground mount is past the end of it; it is pure
+  // arithmetic on uniforms, which every backend sinks into whatever reads it.
+  let ndc = vec2f(fragCoord.x / fullSz.x * 2.0 - 1.0, 1.0 - fragCoord.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);
+  if (BACKGROUND_COND) {
     if (bg.w > 1.5) {
       // LH world (+Z forward): longitude = atan2(x, z), Babylon-PhotoDome convention.
       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;
     }
-    BG_EFFECT_CALL
+    BACKGROUND_CALL
   }
-  return vec4f(disp * alpha + bgPm * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
+  // The frame, premultiplied: scene over background. A var, not the return
+  // expression, because the foreground mount composites onto it.
+  var outRgb = disp * sceneAlpha + bgPm * (1.0 - sceneAlpha);
+  var outA = sceneAlpha + bgA * (1.0 - sceneAlpha);
+  FOREGROUND_CALL
+  return vec4f(outRgb, outA);
 }
 `
 
-// Base variant: no effect installed, the flag is never set — the ray block only
-// runs for the equirect, and there is nothing to add. (`dir` may go unused when
-// this compiles with mode<2 shaders; WGSL is fine with an unused let.)
-const NO_EFFECT_CALL = `_ = dir;`
-
 // uv flipped to bottom-left origin (shadertoy convention); clamped so a stray
 // effect can't push negatives/NaN into the premultiplied composite. Standard
-// OVER onto the base layer.
-const EFFECT_CALL = /* wgsl */ `
-    if (fxOn) {
-      let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-      let fx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
-      bgPm = fx.rgb * fx.a + bgPm * (1.0 - fx.a);
-      bgA = fx.a + bgA * (1.0 - fx.a);
-    }
+// 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);
+    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);
+  outA = fgFx.a + outA * (1.0 - fgFx.a);
 `
 
 // Derivative builtins are illegal in non-uniform control flow (WGSL uniformity
@@ -184,31 +333,41 @@ const EFFECT_CALL = /* wgsl */ `
 // effect code that doesn't use them. Checked textually at build time.
 const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/
 
-/** Skip the whole background block (equirect sample + effect) behind pixels the
- *  model fully covers — the composite multiplies the result by (1 - alpha) = 0
- *  there anyway, and on a full-screen effect that's a third or more of the frame
- *  (the cost Safari feels most). 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 gate. */
-function coverageGate(effect?: CompositeEffectSource | null): string {
-  const gated = !effect || !USES_DERIVATIVES.test(effect.wgsl)
-  return gated ? "&& alpha < 0.999" : ""
+/** The condition on the background block (equirect sample + background effect).
+ *
+ *  Two jobs. It skips the block behind pixels the model fully covers — the
+ *  composite multiplies the result by (1 - alpha) = 0 there anyway, and on a
+ *  full-screen effect that's a third or more of the frame (the cost Safari feels
+ *  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.) */
+function backgroundCondition(effect?: CompositeEffectSource | null): string {
+  // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
+  // sharp scene fully covered can end up needing background behind its blur.
+  const coverage = "sceneAlpha < 0.999"
+  if (!effect?.hasBackground) return `bg.w > 1.5 && ${coverage}`
+  return USES_DERIVATIVES.test(effect.wgsl) ? "true" : coverage
 }
 
 export function buildCompositeShader(effect?: CompositeEffectSource | null): string {
-  if (!effect)
-    return (
-      COMPOSITE_HEAD +
-      COMPOSITE_BODY.replace("BG_EFFECT_CALL", NO_EFFECT_CALL).replace("COVERAGE_GATE", coverageGate(null))
-    )
+  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
   return (
     COMPOSITE_HEAD +
-    "\n// ── user background effect (setBackgroundEffect) ──\n" +
+    "\n// ── user effect (setEffect) ──\n" +
     effect.paramsDecl +
     "\n" +
     effect.wgsl +
     "\n" +
-    COMPOSITE_BODY.replace("BG_EFFECT_CALL", EFFECT_CALL.trim()).replace("COVERAGE_GATE", coverageGate(effect))
+    body
   )
 }
 

package/dist/particles.d.ts

@@ -1,43 +0,0 @@
-import { Vec3 } from "./math";
-export interface ParticleEmitOptions {
-    /** World-space anchor points, xyz-packed (see Model.sampleSurfacePoints).
-     *  One particle spawns per point. */
-    points: Float32Array;
-    /** "burst" flies point → scattered and fades (dissolve); "converge" flies
-     *  scattered → point and vanishes on arrival (materialize). Default burst. */
-    mode?: "burst" | "converge";
-    /** Seconds the full effect lasts, staggers included (default 1.6). */
-    duration?: number;
-    /** HDR color — components above 1 glow through bloom (default warm gold). */
-    color?: Vec3;
-    /** Particle radius in world units (default 0.5). */
-    size?: number;
-    /** Scatter distance in world units at the far end of the flight (default 14). */
-    scatter?: number;
-    /** Upward drift across the flight, world units (default 6). */
-    lift?: number;
-    /** Radians the cloud winds around its centroid across the flight (default 2). */
-    swirl?: number;
-}
-export declare class ParticleSystem {
-    private readonly device;
-    private readonly pipeline;
-    private readonly bindGroupLayout;
-    private readonly cameraBuffer;
-    private readonly timeBuffer;
-    private readonly timeData;
-    private emissions;
-    constructor(device: GPUDevice, cameraBuffer: GPUBuffer, formats: {
-        hdr: GPUTextureFormat;
-        mask: GPUTextureFormat;
-        depth: GPUTextureFormat;
-        sampleCount: number;
-    });
-    /** Upload one emission. `now` is the shared clock (seconds) draw() receives. */
-    emit(opts: ParticleEmitOptions, now: number): void;
-    get active(): boolean;
-    /** Record draws into the main pass (after the transparent phase). */
-    draw(pass: GPURenderPassEncoder, now: number): void;
-    dispose(): void;
-}
-//# sourceMappingURL=particles.d.ts.map

package/dist/particles.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../src/particles.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAG7B,MAAM,WAAW,mBAAmB;IAClC;yCACqC;IACrC,MAAM,EAAE,YAAY,CAAA;IACpB;kFAC8E;IAC9E,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAaD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAW;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,SAAS,CAAiB;gBAGhC,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,SAAS,EACvB,OAAO,EAAE;QAAE,GAAG,EAAE,gBAAgB,CAAC;QAAC,IAAI,EAAE,gBAAgB,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;IAwD1G,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAoFlD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAwBnD,OAAO,IAAI,IAAI;CAQhB"}