reze-engine 0.55.16 → 0.56.1

package/src/model.ts

@@ -1024,6 +1024,22 @@ export class Model {
     return this.skeleton
   }
 
+  /**
+   * Overwrites BASE (pre-morph) positions in place — a permanent geometry
+   * edit (a bone scale's own vertex half), not a transient morph. Only the
+   * CPU copy: the caller (Engine.setVertexPositions) owns pushing the same
+   * change to whichever GPU buffer(s) actually feed the render this frame.
+   */
+  setVertexPositions(updates: readonly { index: number; position: readonly [number, number, number] }[]): void {
+    for (const { index, position } of updates) {
+      if (index < 0 || index >= this.vertexCount) continue
+      const vi = index * VERTEX_STRIDE
+      this.baseVertexData[vi] = position[0]
+      this.baseVertexData[vi + 1] = position[1]
+      this.baseVertexData[vi + 2] = position[2]
+    }
+  }
+
   // Direct bone local-transform accessors (used by interactive gizmo drag).
   // Readers return the live runtime state — callers that want a snapshot for
   // later comparison should `.clone()` the returned Quat / copy the Vec3.

package/src/overlay.ts

@@ -502,11 +502,6 @@ export const OVERLAY_STYLE = {
 
   /** 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/src/reflection.ts

@@ -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
@@ -44,20 +60,66 @@ 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: number, py: number, pz: number,
+  nx: number, ny: number, nz: number,
+  out: Float32Array,
+): Float32Array {
+  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: number): Float32Array {
-  // 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: ArrayLike<number>, out?: Float32Array): Float32Array {
+  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.
  *
@@ -69,26 +131,30 @@ export function reflectionAboutY(h: number): Float32Array {
  * view' = view × R (column-vector convention, matching `projection * view *
  * pos` in the vertex shaders); projection unchanged; eye reflected.
  */
-export function buildMirrorCamera(camera: Float32Array, planeY: number, out: Float32Array): Float32Array {
-  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]
-  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]
+export function buildMirrorCamera(
+  camera: Float32Array,
+  plane: ArrayLike<number>,
+  out: Float32Array,
+): Float32Array {
+  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] = 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/src/shaders/directives.ts

@@ -55,6 +55,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.
    *
@@ -84,6 +99,7 @@ const SPEC = {
   grid: 1,
   bloom: 0,
   dissolve: 0,
+  mirror: 0,
   duration: 1,
 } as const
 
@@ -139,6 +155,7 @@ export function parseDirectives(wgsl: string): DirectiveResult {
     grid: 0,
     bloom: false,
     dissolve: false,
+    mirror: false,
     duration: 0,
   }
   const errors: string[] = []
@@ -235,6 +252,9 @@ export function parseDirectives(wgsl: string): DirectiveResult {
       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/src/shaders/passes/ground.ts

@@ -123,6 +123,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)}
 
@@ -137,6 +157,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);
@@ -315,6 +343,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);
@@ -349,10 +382,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.
@@ -364,15 +398,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/src/shaders/passes/mirror.ts

@@ -0,0 +1,289 @@
+// The mirror surface — the one thing that consumes the reflection pass as a
+// SURFACE rather than as a layer under the floor.
+//
+// The ground has sampled the mirror target since step 7D, and it does it the
+// only way a planar reflection can be sampled correctly: project the fragment's
+// world position through the camera that rendered the reflection, and the texel
+// you land on is exactly where that fragment's reflection was drawn. No
+// screen-space ray, no guess. This file is that same projection on a quad you
+// can put anywhere, which is all a standing mirror is.
+//
+// What it deliberately does NOT do:
+//   - light. A mirror shows what it reflects; a sun term on top of that is a
+//     second surface nobody asked for.
+//   - receive shadow. The reflection already carries the shadow the reflected
+//     geometry is standing in.
+//   - carry a strength. Coverage is 1 — the tint is how a mirror falls short of
+//     perfect, the same way real glass does, and it is a colour rather than a
+//     dial that fades the surface out into nothing.
+
+import { sceneFsOutWgsl, sceneIdPadWgsl } from "./scene-contract"
+
+/** Bytes in MirrorMat below: mat4x4f + three 16-byte rows. */
+export const MIRROR_MAT_BYTES = 64 + 16 * 3
+
+export function mirrorShaderWgsl(): string {
+  return /* wgsl */ `
+struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
+// params = (projA, projB, _, _) — the depth-linearisation pair, carried beside
+// the matrix exactly as the ground reads it. Unused here (the surface takes a
+// flat blur level, not a depth-proportional one) and kept so the two consumers
+// bind one buffer rather than two shapes of the same thing.
+struct MirrorVP { viewProj: mat4x4f, params: vec4f, };
+struct MirrorMat {
+  model: mat4x4f,
+  tint: vec3f, blur: f32,
+  // frame = the band's width in WORLD units, 0 for a bare pane. World rather
+  // than a fraction of the quad so that a wide mirror and a narrow one in the
+  // same scene are framed in the same moulding.
+  frameColor: vec3f, frame: f32,
+  size: vec2f, _pad: vec2f,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var<uniform> mirrorVP: MirrorVP;
+@group(0) @binding(2) var<uniform> material: MirrorMat;
+@group(0) @binding(3) var mirrorTex: texture_2d<f32>;
+@group(0) @binding(4) var linearSampler: sampler;
+// The mirror pass's aux, resolved. .g is accumulated alpha — the reflection's
+// COVERAGE, and the only place it exists: the HDR attachment is rg11b10ufloat
+// wherever the device allows it, and that format has no alpha channel, so a
+// mirror reading the colour target's own alpha reads 1 everywhere and paints
+// the empty black of the reflection across the whole pane.
+@group(0) @binding(5) var mirrorMask: texture_2d<f32>;
+
+struct VO {
+  @builtin(position) position: vec4f,
+  @location(0) worldPos: vec3f,
+  @location(1) normal: vec3f,
+  /** Across the quad, 0..1 — what the frame is measured in. */
+  @location(2) uv: vec2f,
+};
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> VO {
+  // The quad is generated, not buffered: it is six vertices of a unit square
+  // and the model matrix carries every difference between one mirror and
+  // another, so a vertex buffer would be an allocation per mirror holding the
+  // same twelve numbers.
+  //
+  // Local XY, facing local +Z. A mirror at identity therefore faces the way the
+  // default camera looks FROM, which is the orientation someone dropping one
+  // into a scene means by "in front of her".
+  // Local Y runs 0..1 from the BASE, not -0.5..0.5 from the centre. A mirror
+  // stands on the floor: shortening it has to take the height off the top and
+  // leave the foot where it is, and turning it has to pivot on that foot. With
+  // a centred quad both of those move the whole mirror.
+  var q = array<vec2f, 6>(
+    vec2f(-0.5, 0.0), vec2f(0.5, 0.0), vec2f(0.5, 1.0),
+    vec2f(-0.5, 0.0), vec2f(0.5, 1.0), vec2f(-0.5, 1.0),
+  );
+  let local = vec4f(q[vi], 0.0, 1.0);
+  let uv = q[vi] + vec2f(0.5, 0.0);
+  let world = material.model * local;
+  var o: VO;
+  o.worldPos = world.xyz;
+  o.uv = uv;
+  // The local +Z axis through the model's rotation. Column 2 of a matrix whose
+  // scale is uniform per axis is that axis scaled — normalized here because the
+  // side test below is a sign, and a scaled normal would still give the right
+  // sign but a wrong-length one is a trap for whatever reads this next.
+  o.normal = normalize((material.model * vec4f(0.0, 0.0, 1.0, 0.0)).xyz);
+  o.position = camera.projection * camera.view * world;
+  return o;
+}
+
+${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
+  var out: FSOut;
+${sceneIdPadWgsl("out")}
+  let toEye = camera.viewPos - i.worldPos;
+  // Facing the viewer whichever side is up: the quad has one normal and two
+  // sides, and the moulding is on both.
+  let nrm = select(-i.normal, i.normal, dot(toEye, i.normal) > 0.0);
+
+  // ── The moulding ──
+  //
+  // Measured in world units off each edge, so the width means the same thing on
+  // a tall mirror as on a wide one.
+  let dx = min(i.uv.x, 1.0 - i.uv.x) * material.size.x;
+  let dy = min(i.uv.y, 1.0 - i.uv.y) * material.size.y;
+  let edge = min(dx, dy);
+  if (edge < material.frame) {
+    // A MOULDING with a cross-section, not a painted border. The band's normal
+    // rolls from facing outward at the rim to facing the viewer at the inner
+    // lip, and that roll is the whole trick: a flat rectangle of colour reads as
+    // a decal on a plane, while a normal that turns catches the view and reads
+    // as metal bent around glass.
+    let t = clamp(edge / max(material.frame, 1e-4), 0.0, 1.0);
+    // Which way this point of the band faces, in the plane. The axes come off
+    // the model matrix, so a rotated mirror's moulding rotates with it.
+    let ax = normalize(material.model[0].xyz);
+    let ay = normalize(material.model[1].xyz);
+    var outward = ax * select(-1.0, 1.0, i.uv.x > 0.5);
+    if (dy < dx) { outward = ay * select(-1.0, 1.0, i.uv.y > 0.5); }
+    let roll = cos(t * 1.5707963);
+    let n = normalize(nrm * (1.0 - roll) + outward * roll);
+    let v = normalize(toEye);
+    // Two FIXED studio lights, not the scene's. A frame lit by the scene goes
+    // black whenever the sun is behind it, and a black frame reads as a hole cut
+    // in the picture rather than as metal in shadow.
+    let l1 = normalize(vec3f(0.40, 0.80, 0.45));
+    let l2 = normalize(vec3f(-0.50, 0.20, -0.60));
+    let spec = pow(max(dot(n, normalize(l1 + v)), 0.0), 64.0) * 2.6
+             + pow(max(dot(n, normalize(l2 + v)), 0.0), 20.0) * 0.7;
+    let diff = max(dot(n, l1), 0.0) * 0.55 + max(dot(n, l2), 0.0) * 0.25;
+    // The grazing rim is what makes a metal edge read as an edge.
+    let fres = pow(1.0 - abs(dot(n, v)), 4.0);
+    // A METAL TINTS ITS OWN HIGHLIGHT. White specular on a gold frame reads as
+    // cream plastic; carrying the frame's colour into the highlight and the rim
+    // is what separates gold from a yellow-painted thing.
+    let sheen = mix(vec3f(1.0), material.frameColor, 0.65);
+    out.color = vec4f(material.frameColor * (0.45 + diff) + sheen * (spec + fres * 0.40), 1.0);
+    out.mask = vec4f(0.0, 1.0, 0.0, 1.0);
+    return out;
+  }
+
+  // Which side is being looked at. Behind a mirror there is no reflection to
+  // show — the fold puts the mirror camera on the viewer's own side and the
+  // projection returns a smear — so the back reads as what the back of a mirror
+  // is: a flat panel. Without this a mirror rotated the wrong way is not
+  // wrong-looking, it is broken-looking, and the fix is invisible from the
+  // transform panel.
+  if (dot(toEye, i.normal) <= 0.0) {
+    // The BACKING BOARD. A mirror seen from behind is a board in a frame, and
+    // it is opaque: the scene must not show through it, or the pane reads as a
+    // pane of dark glass with the cast standing inside it.
+    out.color = vec4f(material.frameColor * 0.55, 1.0);
+    out.mask = vec4f(0.0, 1.0, 0.0, 1.0);
+    return out;
+  }
+
+  // The projective sample: this fragment's world position through the mirror
+  // camera IS the texel its reflection landed on.
+  let mc = mirrorVP.viewProj * vec4f(i.worldPos, 1.0);
+  let mndc = mc.xyz / max(mc.w, 1e-6);
+  let muv = clamp(vec2f(mndc.x * 0.5 + 0.5, 0.5 - mndc.y * 0.5), vec2f(0.0), vec2f(1.0));
+  // A flat level, not the ground's depth-proportional one. That trick
+  // reconstructs how far behind the surface the reflected geometry sits by
+  // mirroring the eye through y — arithmetic that is only true for a floor.
+  // The general form belongs here eventually; a uniform frosting is the honest
+  // thing to ship before it, and blur 0 (the default) reads level 0 exactly.
+  let refl = textureSampleLevel(mirrorTex, linearSampler, muv, material.blur * 5.0);
+  // THE SAME LEVEL as the colour, and that is the whole of it. refl.rgb is
+  // premultiplied by this coverage, so the two are one quantity in two
+  // textures: blur the colour into the empty part of the reflection while
+  // reading coverage sharp, and the pane divides a spread-out colour by a
+  // coverage that never spread — which is a reflection that goes dark as the
+  // frosting comes up, exactly backwards.
+  let cov = textureSampleLevel(mirrorMask, linearSampler, muv, material.blur * 5.0).g;
+
+  // ALPHA IS COVERAGE, and it is what keeps the glass clear.
+  //
+  // The reflection target clears TRANSPARENT, so coverage is 1 exactly where
+  // the mirror pass drew something and 0 where it drew nothing. Filling the empty
+  // part with the scene's background colour is the obvious thing and it is
+  // wrong: that colour would then ride the view transform a second time (the
+  // real backdrop composites after it), and the panel comes out paler and
+  // flatter than the backdrop it sits against — a mirror that fogs.
+  //
+  // Letting it through instead costs nothing and is also what a mirror does: an
+  // empty mirror shows the room, and here the room IS the backdrop.
+  // PREMULTIPLIED, and it must not be premultiplied twice. refl.rgb came out of
+  // the HDR target, which stores colour already weighted by its own alpha, and
+  // the mirror class blends premultiplied for exactly that reason. Multiplying
+  // by cov here as well is what made the reflection a ghost.
+  //
+  // ALPHA 1, ALWAYS — the pane REPLACES what is behind it. A mirror is opaque;
+  // blending here let the real floor show through the glass beside the
+  // reflected one, which is two grids in one pane. Premultiplied over at alpha
+  // 1 is a straight overwrite, and refl.rgb is already premultiplied, so the
+  // empty sky of the reflection writes 0 rather than black-over-something.
+  out.color = vec4f(refl.rgb * material.tint, 1.0);
+  // .g is the ACCUMULATED CANVAS ALPHA the composite un-premultiplies by, and a
+  // surface that writes nothing here is a surface the composite treats as
+  // absent — the reflection then survived only where something else had already
+  // written alpha under it, which is to say only against the reflected floor.
+  // .r is the bloom gate, left at 0: the glow of a reflected ribbon is already
+  // in refl.rgb, and gating it again would bloom the one thing in the scene
+  // most likely to be over the threshold twice.
+  // COVERAGE goes here instead, and it REPLACES too (.a = 1, so the alpha-over
+  // blend takes the source whole). The composite reads .g as accumulated alpha:
+  // it un-premultiplies the colour by it and paints the scene's backdrop where
+  // it falls short. That is what puts the true sky behind the reflection at the
+  // true colour — the pane cannot paint the backdrop itself, because anything
+  // it writes here goes through the view transform a second time.
+  out.mask = vec4f(0.0, cov, 0.0, 1.0);
+  return out;
+}
+`
+}
+
+/**
+ * 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 const MIRROR_MASK_DOWNSAMPLE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var src: texture_2d<f32>;
+@group(0) @binding(1) var samp: sampler;
+
+struct VSOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f, };
+
+@vertex fn vs(@builtin(vertex_index) i: u32) -> VSOut {
+  var out: VSOut;
+  let x = f32(i32(i / 2u) * 4 - 1);
+  let y = f32(i32(i % 2u) * 4 - 1);
+  out.pos = vec4f(x, y, 0.0, 1.0);
+  out.uv = vec2f(x * 0.5 + 0.5, 0.5 - y * 0.5);
+  return out;
+}
+
+@fragment fn fs(in: VSOut) -> @location(0) vec4f {
+  return textureSampleLevel(src, samp, in.uv, 0.0);
+}
+`
+
+export function mirrorShadowWgsl(cascades: number): string {
+  return /* wgsl */ `
+struct LightVP { viewProj: array<mat4x4f, ${cascades}>, };
+struct Cascade { index: u32, _p0: u32, _p1: u32, _p2: u32, };
+struct MirrorMat {
+  model: mat4x4f,
+  tint: vec3f, blur: f32,
+  frameColor: vec3f, frame: f32,
+  size: vec2f, _pad: vec2f,
+};
+
+@group(0) @binding(0) var<uniform> lightVP: LightVP;
+@group(0) @binding(1) var<uniform> cascade: Cascade;
+@group(0) @binding(2) var<uniform> material: MirrorMat;
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  var q = array<vec2f, 6>(
+    vec2f(-0.5, 0.0), vec2f(0.5, 0.0), vec2f(0.5, 1.0),
+    vec2f(-0.5, 0.0), vec2f(0.5, 1.0), vec2f(-0.5, 1.0),
+  );
+  return lightVP.viewProj[cascade.index] * material.model * vec4f(q[vi], 0.0, 1.0);
+}
+`
+}