reze-engine 0.55.16 → 0.56.0

package/dist/overlay.d.ts

@@ -120,11 +120,6 @@ export declare const OVERLAY_STYLE: {
     readonly jointSize: 0.006;
     /** Stroke for the material borders drawn over the mesh wireframe. */
     readonly seamStrokePx: 3;
-    /** Stroke for the material under the pointer — the same self-occluding reveal
-     *  a pick draws, layered over the section-wide view rather than replacing it,
-     *  and heavier than either a pick's own edges or a seam so it still pops out
-     *  of a view that already has two other things drawn in it. */
-    readonly hoverStrokePx: 4;
     /** How strongly the triangulation draws under those borders.
      *
      *  Both at full strength is one undifferentiated field of yellow — forty

package/dist/overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}

package/dist/overlay.js

@@ -405,11 +405,6 @@ export const OVERLAY_STYLE = {
     jointSize: 0.006,
     /** Stroke for the material borders drawn over the mesh wireframe. */
     seamStrokePx: 3,
-    /** Stroke for the material under the pointer — the same self-occluding reveal
-     *  a pick draws, layered over the section-wide view rather than replacing it,
-     *  and heavier than either a pick's own edges or a seam so it still pops out
-     *  of a view that already has two other things drawn in it. */
-    hoverStrokePx: 4,
     /** How strongly the triangulation draws under those borders.
      *
      *  Both at full strength is one undifferentiated field of yellow — forty

package/dist/reflection.d.ts

@@ -7,11 +7,24 @@
  */
 export declare const REFLECTION_DEBUG_WGSL = "\n@group(0) @binding(0) var t: texture_2d<f32>;\n@group(0) @binding(1) var s: sampler;\n\nstruct VSOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f, };\n\n@vertex fn vs(@builtin(vertex_index) i: u32) -> VSOut {\n  var out: VSOut;\n  let x = f32(i32(i / 2u) * 4 - 1);\n  let y = f32(i32(i % 2u) * 4 - 1);\n  out.pos = vec4f(x, y, 0.0, 1.0);\n  out.uv = vec2f(x * 0.5 + 0.5, 0.5 - y * 0.5);\n  return out;\n}\n\n@fragment fn fs(in: VSOut) -> @location(0) vec4f {\n  let c = textureSample(t, s, in.uv).rgb;\n  return vec4f(sqrt(c / (vec3f(1.0) + c)), 1.0);\n}\n";
 /**
- * Reflection about the horizontal plane y = h, column-major.
+ * A plane as the mirror wants it: 4 numbers, (nx, ny, nz, d), surface at
+ * n·p + d = 0.
  *
- *   p' = (x, 2h - y, z)
+ * Written into a caller-owned array rather than returned, because the engine
+ * holds one per mirror and rebuilds it whenever the mirror moves — which is
+ * every frame a gizmo is being dragged.
+ *
+ * `n` is normalized here rather than trusted: it arrives from a rotated quad's
+ * basis, and a scale baked into that basis would otherwise scale `d` against
+ * it and put the plane somewhere else entirely.
+ */
+export declare function planeFromPointNormal(px: number, py: number, pz: number, nx: number, ny: number, nz: number, out: Float32Array): Float32Array;
+/**
+ * The Householder reflection about (n, d), column-major.
+ *
+ *   p' = p - 2 (n·p + d) n
  */
-export declare function reflectionAboutY(h: number): Float32Array;
+export declare function reflectionAboutPlane(plane: ArrayLike<number>, out?: Float32Array): Float32Array;
 /**
  * Fill a camera-uniform block for the mirror pass from the live one.
  *
@@ -23,5 +36,5 @@ export declare function reflectionAboutY(h: number): Float32Array;
  * view' = view × R (column-vector convention, matching `projection * view *
  * pos` in the vertex shaders); projection unchanged; eye reflected.
  */
-export declare function buildMirrorCamera(camera: Float32Array, planeY: number, out: Float32Array): Float32Array;
+export declare function buildMirrorCamera(camera: Float32Array, plane: ArrayLike<number>, out: Float32Array): Float32Array;
 //# sourceMappingURL=reflection.d.ts.map

package/dist/reflection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reflection.d.ts","sourceRoot":"","sources":["../src/reflection.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,8jBAmBjC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAQxD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,YAAY,CAsBvG"}
+{"version":3,"file":"reflection.d.ts","sourceRoot":"","sources":["../src/reflection.ts"],"names":[],"mappings":"AAiCA;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,8jBAmBjC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAClC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAClC,GAAG,EAAE,YAAY,GAChB,YAAY,CAWd;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,YAAY,CAoB/F;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EACxB,GAAG,EAAE,YAAY,GAChB,YAAY,CAsBd"}

package/dist/reflection.js

@@ -2,18 +2,34 @@
 // shadow-cascades precedent.
 //
 // A planar reflection is not a second camera aimed by hand; it is the SAME
-// camera with the world reflected about the floor plane. Fold the reflection
+// camera with the world reflected about the mirror's plane. Fold the reflection
 // into the view matrix and everything downstream is untouched: world positions
 // stay TRUE world positions, so sun, shadows and positional lights evaluate at
 // the unmirrored point — which is exactly what a mirror shows, an object lit
 // as it is, seen from a mirrored eye. The only other value that must mirror is
 // the eye itself, because specular reads the view direction from it.
 //
-// Winding: a reflection has determinant -1, so triangle orientation flips.
-// Every scene-pass pipeline that draws into the mirror culls "none", which is
-// what makes this legal without a flipped-frontFace pipeline set. The OUTLINE
-// culls "back" and is therefore skipped in the mirror — its hull would face
-// the wrong way and ink over the model.
+// The plane is carried as (n, d) with n a UNIT normal and the surface at
+// n·p + d = 0 — general from the start, because a mirror standing on the floor
+// is the ordinary case and a floor is only the one plane that happens to be
+// horizontal. The ground is (0, 1, 0, 0).
+//
+// WINDING: a reflection has determinant -1, so triangle orientation flips, and
+// any pipeline that culls a face culls the WRONG one in the mirror pass.
+//
+// This note used to claim every scene-pass pipeline culls "none". That was
+// never true, and each exception cost a round of "the mirror looks broken":
+//
+//   ground   culls "back"  -> the floor vanished whole, and with it the grid
+//                             and the received shadow, since the shadow is a
+//                             layer of the ground shader
+//   outline  culls "back"  -> no ink line on the reflection at all
+//   eye      culls "front" -> the back of the eyeball kept, its front discarded
+//
+// All three now build a mirror twin with the cull answered (the ground goes to
+// "none", the outline to "front", the eye to "back"). Anything ADDED to the
+// scene pass with a cullMode must do the same — grep cullMode in engine.ts,
+// which is the whole list.
 /**
  * The debug view: the reflection target drawn over the finished frame — the
  * only way to SEE whether the mirror pass is right before anything consumes
@@ -42,19 +58,59 @@ struct VSOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f, };
 }
 `;
 /**
- * Reflection about the horizontal plane y = h, column-major.
+ * A plane as the mirror wants it: 4 numbers, (nx, ny, nz, d), surface at
+ * n·p + d = 0.
+ *
+ * Written into a caller-owned array rather than returned, because the engine
+ * holds one per mirror and rebuilds it whenever the mirror moves — which is
+ * every frame a gizmo is being dragged.
+ *
+ * `n` is normalized here rather than trusted: it arrives from a rotated quad's
+ * basis, and a scale baked into that basis would otherwise scale `d` against
+ * it and put the plane somewhere else entirely.
+ */
+export function planeFromPointNormal(px, py, pz, nx, ny, nz, out) {
+    const len = Math.hypot(nx, ny, nz) || 1;
+    const x = nx / len;
+    const y = ny / len;
+    const z = nz / len;
+    out[0] = x;
+    out[1] = y;
+    out[2] = z;
+    // d places the plane through the point: n·p + d = 0.
+    out[3] = -(x * px + y * py + z * pz);
+    return out;
+}
+/**
+ * The Householder reflection about (n, d), column-major.
  *
- *   p' = (x, 2h - y, z)
+ *   p' = p - 2 (n·p + d) n
  */
-export function reflectionAboutY(h) {
-    // prettier-ignore
-    return new Float32Array([
-        1, 0, 0, 0,
-        0, -1, 0, 0,
-        0, 0, 1, 0,
-        0, 2 * h, 0, 1,
-    ]);
+export function reflectionAboutPlane(plane, out) {
+    const nx = plane[0], ny = plane[1], nz = plane[2], d = plane[3];
+    const m = out ?? new Float32Array(16);
+    m[0] = 1 - 2 * nx * nx;
+    m[1] = -2 * ny * nx;
+    m[2] = -2 * nz * nx;
+    m[3] = 0;
+    m[4] = -2 * nx * ny;
+    m[5] = 1 - 2 * ny * ny;
+    m[6] = -2 * nz * ny;
+    m[7] = 0;
+    m[8] = -2 * nx * nz;
+    m[9] = -2 * ny * nz;
+    m[10] = 1 - 2 * nz * nz;
+    m[11] = 0;
+    m[12] = -2 * d * nx;
+    m[13] = -2 * d * ny;
+    m[14] = -2 * d * nz;
+    m[15] = 1;
+    return m;
 }
+/** Scratch for the product below — this module is called once per mirror per
+ *  frame and allocating a matrix each time is a garbage-collector visit for
+ *  nothing. */
+const R = new Float32Array(16);
 /**
  * Fill a camera-uniform block for the mirror pass from the live one.
  *
@@ -66,28 +122,27 @@ export function reflectionAboutY(h) {
  * view' = view × R (column-vector convention, matching `projection * view *
  * pos` in the vertex shaders); projection unchanged; eye reflected.
  */
-export function buildMirrorCamera(camera, planeY, out) {
-    const v = camera;
-    const h = planeY;
-    // view × R where R = reflectionAboutY(h). R only touches column 1 (scaled by
-    // -1) and adds 2h·col1 to the translation — write the product directly
-    // rather than through a generic multiply, so the arithmetic is exact and the
-    // cost is a handful of ops.
-    for (let i = 0; i < 16; i++)
-        out[i] = v[i];
-    out[4] = -v[4];
-    out[5] = -v[5];
-    out[6] = -v[6];
-    out[7] = -v[7];
-    out[12] = v[12] + 2 * h * v[4];
-    out[13] = v[13] + 2 * h * v[5];
-    out[14] = v[14] + 2 * h * v[6];
-    out[15] = v[15] + 2 * h * v[7];
+export function buildMirrorCamera(camera, plane, out) {
+    reflectionAboutPlane(plane, R);
+    // view × R, column-major: out.col_j = Σ_k view.col_k · R[j*4 + k].
+    for (let j = 0; j < 4; j++) {
+        const b0 = R[j * 4 + 0], b1 = R[j * 4 + 1], b2 = R[j * 4 + 2], b3 = R[j * 4 + 3];
+        for (let r = 0; r < 4; r++) {
+            out[j * 4 + r] =
+                camera[0 + r] * b0 + camera[4 + r] * b1 + camera[8 + r] * b2 + camera[12 + r] * b3;
+        }
+    }
     for (let i = 16; i < 32; i++)
-        out[i] = v[i];
-    out[32] = v[32];
-    out[33] = 2 * h - v[33];
-    out[34] = v[34];
-    out[35] = v[35];
+        out[i] = camera[i];
+    // The eye through the same reflection, so specular reads the mirrored view
+    // direction. Written from the plane directly rather than through R: it is one
+    // dot product, and going via the matrix would round-trip it through nine
+    // multiplies to reach the same number.
+    const nx = plane[0], ny = plane[1], nz = plane[2], d = plane[3];
+    const t = 2 * (nx * camera[32] + ny * camera[33] + nz * camera[34] + d);
+    out[32] = camera[32] - t * nx;
+    out[33] = camera[33] - t * ny;
+    out[34] = camera[34] - t * nz;
+    out[35] = camera[35];
     return out;
 }

package/dist/shaders/directives.d.ts

@@ -27,6 +27,21 @@ export type EffectDirectives = {
     bloom: boolean;
     /** This effect takes the cast apart — the host reads the timing. */
     dissolve: boolean;
+    /**
+     * This effect IS a mirror: a plane in the scene showing a true reflection of
+     * it, folded and re-rendered by the engine.
+     *
+     * A mount with no shader, and the second of them — `#lights` was the first.
+     * The reasoning is identical: a planar reflection re-renders every model from
+     * a folded camera, which is a PASS, and no mount is a pass. So the effect
+     * declares the mirror and the engine reflects, exactly as a lighting rig
+     * declares lamps and the engine shades.
+     *
+     * The plane comes from the effect's own `#param` dials, by name — see the
+     * engine's MIRROR_DIALS. That is what makes it an effect rather than a switch:
+     * it publishes, forks, schedules and fades like every other one.
+     */
+    mirror: boolean;
     /**
      * How long ONE firing of this effect lasts, in seconds. 0 = undeclared.
      *

package/dist/shaders/directives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/shaders/directives.ts"],"names":[],"mappings":"AA8BA,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE,aAAa,EAAE,OAAO,GAAG,UAAU,CAAA;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAiBD;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,QAAmC,CAAA;AAG9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAmBzD,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhF,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAqJ7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/shaders/directives.ts"],"names":[],"mappings":"AA8BA,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE,aAAa,EAAE,OAAO,GAAG,UAAU,CAAA;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAkBD;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,QAAmC,CAAA;AAG9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAmBzD,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhF,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAyJ7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/shaders/directives.js

@@ -39,6 +39,7 @@ const SPEC = {
     grid: 1,
     bloom: 0,
     dissolve: 0,
+    mirror: 0,
     duration: 1,
 };
 /** A line that declares something, and what it declares. Exported because an
@@ -88,6 +89,7 @@ export function parseDirectives(wgsl) {
         grid: 0,
         bloom: false,
         dissolve: false,
+        mirror: false,
         duration: 0,
     };
     const errors = [];
@@ -183,6 +185,9 @@ export function parseDirectives(wgsl) {
             case "dissolve":
                 d.dissolve = true;
                 return;
+            case "mirror":
+                d.mirror = true;
+                return;
             case "duration": {
                 // SECONDS, like every other time a directive states (see #dissolve).
                 // The document above works in frames and converts once; an author

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

@@ -1 +1 @@
-{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAgFA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,UAAQ,GAAG,MAAM,CA+TrD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}
+{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAgFA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,UAAQ,GAAG,MAAM,CAmWrD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}

package/dist/shaders/passes/ground.js

@@ -119,6 +119,26 @@ struct MirrorVP { viewProj: mat4x4f, params: vec4f, };
 // The frost noise, PRE-BAKED — see GROUND_NOISE_BAKE_WGSL below. Sampled with
 // the repeat sampler already at binding 10.
 @group(0) @binding(12) var noiseTex: texture_2d<f32>;
+// The mirror pass's resolved aux. .g is accumulated alpha — the reflection's
+// coverage. It lives here rather than in the colour target's own alpha because
+// the HDR format is rg11b10ufloat wherever the device allows it, and that
+// format has no alpha channel at all.
+@group(0) @binding(13) var mirrorMask: texture_2d<f32>;
+// THE MIRROR'S OWN PLANE, and whether this draw is the one inside the mirror
+// pass. A mirror shows nothing behind itself, and the floor is the geometry
+// most often behind one: stand a pane up and half the floor is behind it, lay
+// it facing UP and the whole floor is. Without this the reflection carries a
+// grid that the mirror cannot see.
+//
+// A uniform rather than a branch on some global, because the two ground bind
+// groups already differ — the camera's binds a block set to 0 and the
+// mirror's binds the live plane. No per-pass write, and nothing to get wrong
+// about which pass is running.
+// The flag is named on, not active: WGSL RESERVES active, and a reserved
+// word in a struct field fails the whole module — taking the ground
+// pipeline, and every style group and effect compiled after it, with it.
+struct MirrorClip { plane: vec4f, on: f32, _p0: f32, _p1: f32, _p2: f32, };
+@group(0) @binding(14) var<uniform> clip: MirrorClip;
 ${WORLD_AMBIENT_WGSL}
 ${lightsApi(0, 6)}
 
@@ -133,6 +153,14 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   let gp = i.worldPos.xz / material.gridSpacing;
   let gridDeriv = fwidth(gp);
 
+  // The clip, straight after the derivatives and before anything else branches.
+  // EPSILON rather than zero: a pane lying flat on the floor is coplanar with
+  // it, and a floor reflecting itself at zero distance is z-fighting, not a
+  // reflection.
+  if (clip.on > 0.5 && dot(clip.plane.xyz, i.worldPos) + clip.plane.w < 0.01) {
+    discard;
+  }
+
   var out: FSOut;
   let n = normalize(i.normal);
   let centerDist = length(i.worldPos.xz);
@@ -309,6 +337,11 @@ ${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ",
   // independence the grid won earlier. The branch is on a uniform, so the
   // whole cost vanishes for the scenes that leave it off.
   var reflShadowed = vec3f(0.0);
+  // How much of this texel the reflection pass actually covered. The target
+  // clears TRANSPARENT, so this is 1 where something reflected and 0 over the
+  // empty sky — which is what stops a floor mirror from painting the backdrop
+  // onto itself and wiping out the ground's own colour.
+  var reflA = 0.0;
   if (material.mirror > 0.0) {
     let mc = mirrorVP.viewProj * vec4f(i.worldPos, 1.0);
     let mndc = mc.xyz / max(mc.w, 1e-6);
@@ -343,10 +376,11 @@ ${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ",
       let BLUR_SPAN = 14.0;
       lod = material.mirrorBlur * 5.0 * clamp(height / BLUR_SPAN, 0.0, 1.0);
     }
-    let refl = textureSampleLevel(mirrorTex, linearSampler, muv, lod).rgb;
+    let refl = textureSampleLevel(mirrorTex, linearSampler, muv, lod);
     // Still under the received shadow: a polished floor in shade shows a dim
     // reflection, and a mirror that ignored the shadow would glow in it.
-    reflShadowed = refl * (1.0 - dark * 0.65);
+    reflShadowed = refl.rgb * (1.0 - dark * 0.65);
+    reflA = textureSampleLevel(mirrorMask, linearSampler, muv, 0.0).g;
   }
   // THREE LAYERS, composited premultiplied, bottom to top: the shadow the
   // catcher receives, the ground surface, and the grid.
@@ -358,15 +392,17 @@ ${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ",
   // alpha, and the grid is simply on or off.
   let surfA = edgeFade * material.opacity;
   let gridA = gridLine * material.gridLineOpacity * edgeFade;
-  // The mirror is opaque across the ground's extent when on — it always shows
-  // SOMETHING, because the backdrop rides in the reflection target itself.
-  let mirrA = material.mirror * edgeFade;
+  // The mirror covers only what it actually REFLECTS. The backdrop no longer
+  // rides in the reflection target — it clears transparent — so the floor keeps
+  // its own colour everywhere the cast is not standing, which is the difference
+  // between an MMD stage floor and a mirror of the sky.
+  let mirrA = material.mirror * edgeFade * reflA;
   // As opacity drops the received shadow becomes a translucent dark layer
   // (Blender's Shadow Catcher), so models still feel grounded on a photo or a
   // 360 backdrop. Colourless by construction: it darkens by covering. The
   // MIRROR subsumes it: the reflection already carries the received shadow,
   // and a catcher stacked on top would darken the same shadow twice.
-  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity) * (1.0 - material.mirror);
+  let catchA = dark * 0.65 * edgeFade * (1.0 - material.opacity) * (1.0 - mirrA);
 
   // FOUR LAYERS, premultiplied, bottom to top: reflection, received shadow,
   // ground surface, grid. Each with its own coverage, none scaling another —

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

@@ -0,0 +1,32 @@
+/** Bytes in MirrorMat below: mat4x4f + three 16-byte rows. */
+export declare const MIRROR_MAT_BYTES: number;
+export declare function mirrorShaderWgsl(): string;
+/**
+ * The mirror in the SHADOW pass — the frame throwing shade on the floor.
+ *
+ * Its own shader because the mirror has no vertex buffer and no skeleton: the
+ * quad is six generated vertices and the model matrix is the whole of it, while
+ * the ordinary shadow shader is built for skinned geometry with an alpha test.
+ *
+ * Depth only, no fragment stage. The pane is opaque across its whole rectangle
+ * — glass included, because this glass is not see-through — so there is nothing
+ * to alpha-test and nothing to colour.
+ *
+ * The cascade index arrives in its own tiny uniform rather than as a dynamic
+ * offset: the cascade matrices sit 64 bytes apart in one array, and a dynamic
+ * uniform offset has to be 256-aligned.
+ */
+/**
+ * Downsample for the reflection's COVERAGE chain.
+ *
+ * Colour and coverage are a premultiplied PAIR, and a blur has to move them
+ * together. Blurring colour alone drags it toward zero wherever it spreads into
+ * the empty part of the reflection, while a coverage still sampled sharp says
+ * "fully covered" — so the reflection simply got darker as the dial came up.
+ *
+ * One bilinear tap at the destination texel centre averages the source's 2x2
+ * exactly, which is the box filter this wants and the cheapest way to write it.
+ */
+export declare const MIRROR_MASK_DOWNSAMPLE_WGSL = "\n@group(0) @binding(0) var src: texture_2d<f32>;\n@group(0) @binding(1) var samp: sampler;\n\nstruct VSOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f, };\n\n@vertex fn vs(@builtin(vertex_index) i: u32) -> VSOut {\n  var out: VSOut;\n  let x = f32(i32(i / 2u) * 4 - 1);\n  let y = f32(i32(i % 2u) * 4 - 1);\n  out.pos = vec4f(x, y, 0.0, 1.0);\n  out.uv = vec2f(x * 0.5 + 0.5, 0.5 - y * 0.5);\n  return out;\n}\n\n@fragment fn fs(in: VSOut) -> @location(0) vec4f {\n  return textureSampleLevel(src, samp, in.uv, 0.0);\n}\n";
+export declare function mirrorShadowWgsl(cascades: number): string;
+//# sourceMappingURL=mirror.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mirror.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/mirror.ts"],"names":[],"mappings":"AAqBA,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,QAAc,CAAA;AAE3C,wBAAgB,gBAAgB,IAAI,MAAM,CAiMzC;AAED;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,2hBAkBvC,CAAA;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuBzD"}