reze-engine 0.58.4 → 0.60.0

package/src/engine.ts

@@ -44,7 +44,7 @@ import {
   type SimClock,
 } from "./effect-schedule"
 import { parentKeySpan, type ModelParentKey } from "./parent-keys"
-import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades"
+import { SHADOW_CASCADES, buildShadowCascades, type ShadowBounds, type ShadowView } from "./shadow-cascades"
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera, planeFromPointNormal } from "./reflection"
 import { MIRROR_MASK_DOWNSAMPLE_WGSL, MIRROR_MAT_BYTES, mirrorShaderWgsl, mirrorShadowWgsl } from "./shaders/passes/mirror"
 import { packHalf, type HdrImage } from "./hdr"
@@ -866,8 +866,10 @@ interface ModelInstance {
   shadowDrawCalls: DrawCall[]
   shadowBindGroups: GPUBindGroup[]
   mainPerInstanceBindGroup: GPUBindGroup
-  /** Its own fill, when setModelFill gave it one. */
-  fillBuffer: GPUBuffer | null
+  /** Its own light — fill and sun — when setModelFill or setModelSun gave it
+   *  one: a 32-byte ModelLight, and the CPU copy it is written from. */
+  lightBuffer: GPUBuffer | null
+  modelLight: Float32Array | null
   pickPerInstanceBindGroup: GPUBindGroup
   pickDrawCalls: PickDrawCall[]
   /** Environment geometry added via addStage — no physics, no IK, and it
@@ -2459,7 +2461,7 @@ export class Engine {
   private depthReadView: GPUTextureView | null = null
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  // 11 × vec4f — see the viewU comment in composite.ts. The last one is the
+  // 15 × vec4f — see the viewU comment in composite.ts. The last one is the
   // camera's world position, which is what lets a foreground effect turn the
   // depth it is handed into a PLACE (bgWorldPos) rather than a distance.
   private readonly compositeUniformData = new Float32Array(60)
@@ -7307,8 +7309,8 @@ export class Engine {
     )
 
     this.noFillBuffer = this.device.createBuffer({
-      label: "model fill (none)",
-      size: 16,
+      label: "model light (none)",
+      size: 32,
       usage: GPUBufferUsage.UNIFORM,
     })
 
@@ -7422,7 +7424,7 @@ export class Engine {
           visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
           buffer: { type: "read-only-storage" },
         },
-        // The model's own fill — see setModelFill.
+        // The model's own light — see setModelFill and setModelSun.
         { binding: 1, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
       ],
     })
@@ -8018,7 +8020,7 @@ export class Engine {
     // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
     this.compositeUniformBuffer = this.device.createBuffer({
       label: "composite view uniforms",
-      // 11 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+      // 15 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
       // (time, _, canvas width, canvas height) for user effects · three grade
       // vectors (CDL offset+contrast, power+saturation, slope+flag) · camera
@@ -10753,39 +10755,66 @@ export class Engine {
    * for the models the host counts as cast.
    */
   setModelFill(name: string, fill: Vec3 | null): boolean {
+    return this.writeModelLight(name, 0, fill)
+  }
+
+  /**
+   * A model's own sun: the colour and strength the scene's sun has FOR THIS
+   * MODEL, in place of the scene's. Null gives it the scene's sun back.
+   *
+   * The other half of lighting a stage and its cast apart. A game's stage is
+   * lit by its own daylight — Aether Gazer's kitchen at twenty times white —
+   * while its characters take a key light of their own that the stage never
+   * states. So a stage carries the sun it was lit by, and the scene's sun
+   * stays the cast's. Direction and shadow are still the scene's: one sun
+   * casts, and it casts the same way on both.
+   */
+  setModelSun(name: string, sun: Vec3 | null): boolean {
+    return this.writeModelLight(name, 4, sun)
+  }
+
+  /** One half of a model's light, at `at` (0 the fill, 4 the sun) in its
+   *  ModelLight; w says whether that half is set. Both null releases the
+   *  buffer and the model takes the shared zero stand-in again. */
+  private writeModelLight(name: string, at: 0 | 4, value: Vec3 | null): boolean {
     const inst = this.modelInstances.get(name)
     if (!inst || !this.device) return false
-    if (!fill) {
-      if (!inst.fillBuffer) return true
-      const retired = inst.fillBuffer
-      inst.fillBuffer = null
+    const light = inst.modelLight ?? new Float32Array(8)
+    light.set(value ? [value.x, value.y, value.z, 1] : [0, 0, 0, 0], at)
+    const any = light[3] > 0 || light[7] > 0
+    if (!any) {
+      if (!inst.lightBuffer) return true
+      const retired = inst.lightBuffer
+      inst.lightBuffer = null
+      inst.modelLight = null
       inst.mainPerInstanceBindGroup = this.perInstanceBindGroup(name, inst.skinMatrixBuffer, null)
       this.bundlesDirty = true
       // Retired once the GPU is done with it: an encoded frame may still name it.
       void this.device.queue.onSubmittedWorkDone().then(() => retired.destroy())
       return true
     }
-    if (!inst.fillBuffer) {
-      inst.fillBuffer = this.device.createBuffer({
-        label: `${name}: fill`,
-        size: 16,
+    inst.modelLight = light
+    if (!inst.lightBuffer) {
+      inst.lightBuffer = this.device.createBuffer({
+        label: `${name}: light`,
+        size: 32,
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
       })
-      inst.mainPerInstanceBindGroup = this.perInstanceBindGroup(name, inst.skinMatrixBuffer, inst.fillBuffer)
+      inst.mainPerInstanceBindGroup = this.perInstanceBindGroup(name, inst.skinMatrixBuffer, inst.lightBuffer)
       this.bundlesDirty = true
     }
-    this.device.queue.writeBuffer(inst.fillBuffer, 0, new Float32Array([fill.x, fill.y, fill.z, 0]))
+    this.device.queue.writeBuffer(inst.lightBuffer, 0, light.buffer as ArrayBuffer)
     return true
   }
 
-  /** The per-model group: its skinning matrices and its fill, or the zero stand-in. */
-  private perInstanceBindGroup(name: string, skinMatrixBuffer: GPUBuffer, fill: GPUBuffer | null): GPUBindGroup {
+  /** The per-model group: its skinning matrices and its light, or the zero stand-in. */
+  private perInstanceBindGroup(name: string, skinMatrixBuffer: GPUBuffer, light: GPUBuffer | null): GPUBindGroup {
     return this.device.createBindGroup({
       label: `${name}: main per-instance bind group`,
       layout: this.mainPerInstanceBindGroupLayout,
       entries: [
         { binding: 0, resource: { buffer: skinMatrixBuffer } },
-        { binding: 1, resource: { buffer: fill ?? this.noFillBuffer } },
+        { binding: 1, resource: { buffer: light ?? this.noFillBuffer } },
       ],
     })
   }
@@ -10819,7 +10848,7 @@ export class Engine {
     for (const buf of inst.gpuBuffers) {
       buf.destroy()
     }
-    inst.fillBuffer?.destroy()
+    inst.lightBuffer?.destroy()
     // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
     for (const install of inst.styleGroups.values()) this.destroyInstall(install)
     this.modelInstances.delete(name)
@@ -12511,6 +12540,55 @@ export class Engine {
     }
     if (this.cullModelBuffer) this.device.queue.writeBuffer(this.cullModelBuffer, 0, data.buffer as ArrayBuffer)
     this.updateCasterSphere(data)
+    this.updateShadowSceneBounds(data, flags)
+  }
+
+  /**
+   * The box around everything visible, from the same numbers the cull reads:
+   * a rigid model's per-draw boxes through its matrix, a posed model's sphere.
+   * The shadow cascades reach along the light across it.
+   */
+  private updateShadowSceneBounds(data: Float32Array, flags: Uint32Array): void {
+    let minX = Infinity, minY = Infinity, minZ = Infinity
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity
+    for (let i = 0; i < this.cullDraws.length; i++) {
+      const f = i * 8
+      const mi = this.cullMetaU32[f + 3]
+      const o = mi * Engine.CULL_MODEL_FLOATS
+      const mf = flags[o + 20]
+      if ((mf & Engine.CULL_MODEL_VISIBLE) === 0) continue
+      if ((mf & Engine.CULL_MODEL_RIGID) !== 0) {
+        const cx = (this.cullMetaF32[f] + this.cullMetaF32[f + 4]) * 0.5
+        const cy = (this.cullMetaF32[f + 1] + this.cullMetaF32[f + 5]) * 0.5
+        const cz = (this.cullMetaF32[f + 2] + this.cullMetaF32[f + 6]) * 0.5
+        const ex = (this.cullMetaF32[f + 4] - this.cullMetaF32[f]) * 0.5
+        const ey = (this.cullMetaF32[f + 5] - this.cullMetaF32[f + 1]) * 0.5
+        const ez = (this.cullMetaF32[f + 6] - this.cullMetaF32[f + 2]) * 0.5
+        const wx = data[o] * cx + data[o + 4] * cy + data[o + 8] * cz + data[o + 12]
+        const wy = data[o + 1] * cx + data[o + 5] * cy + data[o + 9] * cz + data[o + 13]
+        const wz = data[o + 2] * cx + data[o + 6] * cy + data[o + 10] * cz + data[o + 14]
+        const gx = Math.abs(data[o]) * ex + Math.abs(data[o + 4]) * ey + Math.abs(data[o + 8]) * ez
+        const gy = Math.abs(data[o + 1]) * ex + Math.abs(data[o + 5]) * ey + Math.abs(data[o + 9]) * ez
+        const gz = Math.abs(data[o + 2]) * ex + Math.abs(data[o + 6]) * ey + Math.abs(data[o + 10]) * ez
+        minX = Math.min(minX, wx - gx); maxX = Math.max(maxX, wx + gx)
+        minY = Math.min(minY, wy - gy); maxY = Math.max(maxY, wy + gy)
+        minZ = Math.min(minZ, wz - gz); maxZ = Math.max(maxZ, wz + gz)
+      } else {
+        const r = data[o + 19]
+        if (!(r > 0)) continue
+        minX = Math.min(minX, data[o + 16] - r); maxX = Math.max(maxX, data[o + 16] + r)
+        minY = Math.min(minY, data[o + 17] - r); maxY = Math.max(maxY, data[o + 17] + r)
+        minZ = Math.min(minZ, data[o + 18] - r); maxZ = Math.max(maxZ, data[o + 18] + r)
+      }
+    }
+    if (!Number.isFinite(minX)) {
+      this.shadowSceneBounds = null
+      return
+    }
+    const b = this.shadowSceneBounds ?? { min: [0, 0, 0], max: [0, 0, 0] }
+    b.min[0] = minX; b.min[1] = minY; b.min[2] = minZ
+    b.max[0] = maxX; b.max[1] = maxY; b.max[2] = maxZ
+    this.shadowSceneBounds = b
   }
 
   /**
@@ -13364,7 +13442,8 @@ export class Engine {
       shadowDrawCalls: [],
       shadowBindGroups,
       mainPerInstanceBindGroup,
-      fillBuffer: null,
+      lightBuffer: null,
+      modelLight: null,
       pickPerInstanceBindGroup,
       pickDrawCalls: [],
       isStage,
@@ -13790,25 +13869,60 @@ export class Engine {
   /** How much shadow the sun casts — see SunOptions.shadow. Full until told. */
   private sunShadow = 1
   private shadowLightVPDirty = true
-  // Last shadow-volume center, to skip recomputes while nothing moves.
-  private readonly shadowCenter = new Vec3(0, 11, 0)
+  /** The cascades as last uploaded, to skip the upload while nothing moved:
+   *  the fit snaps to the map's texels, so a still camera fits the same box. */
+  private readonly shadowLightVPLast = new Float32Array(16 * SHADOW_CASCADES.length)
+  /** Everything drawn, in world space, as writeCullModels last saw it. The
+   *  cascades reach along the light from its nearest face to its farthest, so
+   *  a window frame behind the camera casts onto the floor in front of it. */
+  private shadowSceneBounds: ShadowBounds = null
+  private readonly shadowView: ShadowView = {
+    eye: { x: 0, y: 0, z: 0 },
+    right: { x: 1, y: 0, z: 0 },
+    up: { x: 0, y: 1, z: 0 },
+    forward: { x: 0, y: 0, z: 1 },
+    fov: 1,
+    aspect: 1,
+    near: 1,
+    far: 100,
+    focus: 10,
+  }
 
   private updateShadowLightVP() {
-    // The volumes follow the camera target so a character carried far from the
-    // origin by code-driven root motion stays inside the lit frustum. The
-    // volume MATH lives in shadow-cascades.ts, where it is testable without a
-    // GPU; this method owns only the dirty-tracking and the upload.
+    // THE CASCADES FOLLOW THE CAMERA — fitted every frame to what it sees, the
+    // way Blender's sun shadow is, with their depth fitted to the scene. The
+    // fit MATH lives in shadow-cascades.ts, where it is testable without a
+    // GPU; this method gathers the view and owns the upload.
+    const v = this.shadowView
+    const view = this.camera.getViewMatrix().values
+    const eye = this.camera.getEyePosition()
+    v.eye.x = eye.x
+    v.eye.y = eye.y
+    v.eye.z = eye.z
+    // lookAt writes the basis as the view's rows: right, up, forward.
+    v.right.x = view[0]
+    v.right.y = view[4]
+    v.right.z = view[8]
+    v.up.x = view[1]
+    v.up.y = view[5]
+    v.up.z = view[9]
+    v.forward.x = view[2]
+    v.forward.y = view[6]
+    v.forward.z = view[10]
+    v.fov = this.camera.fov
+    v.aspect = this.camera.aspect
+    v.near = this.camera.near
+    v.far = this.camera.far
     const t = this.camera.target
-    const moved =
-      Math.abs(t.x - this.shadowCenter.x) > 1e-3 ||
-      Math.abs(t.y - this.shadowCenter.y) > 1e-3 ||
-      Math.abs(t.z - this.shadowCenter.z) > 1e-3
-    if (!this.shadowLightVPDirty && !moved) return
-    this.shadowLightVPDirty = false
-    this.shadowCenter.setXYZ(t.x, t.y, t.z)
+    v.focus = Math.hypot(t.x - eye.x, t.y - eye.y, t.z - eye.z)
 
+    buildShadowCascades(v, this.sun.direction, this.shadowSceneBounds, this.shadowLightVPMatrix)
+    let same = !this.shadowLightVPDirty
+    for (let i = 0; same && i < this.shadowLightVPMatrix.length; i++) same = this.shadowLightVPMatrix[i] === this.shadowLightVPLast[i]
+    if (same) return
+    this.shadowLightVPDirty = false
+    this.shadowLightVPLast.set(this.shadowLightVPMatrix)
     for (let i = 0; i < SHADOW_CASCADES.length; i++) {
-      buildShadowVP(t, this.sun.direction, SHADOW_CASCADES[i], this.shadowLightVPMatrix, i * 16)
       this.device.queue.writeBuffer(this.shadowCascadeVPBuffers[i], 0, this.shadowLightVPMatrix, i * 16, 16)
     }
     this.device.queue.writeBuffer(this.shadowLightVPBuffer, 0, this.shadowLightVPMatrix)

package/src/graph/slots.ts

@@ -130,10 +130,10 @@ ${discard}
   let v = normalize(camera.viewPos - input.worldPos);${flip}
 ${gate}
   let l = -light.lights[0].direction.xyz;
-  let sun = light.lights[0].color.xyz * light.lights[0].color.w;
+  let sun = select(light.lights[0].color.xyz * light.lights[0].color.w, modelLight.sun.rgb, modelLight.sun.w > 0.5);
   // The world: flat colour, or the HDRI's irradiance at this normal — which
   // is what makes a loaded sky actually light her instead of only backing her.
-  let amb = rzWorldAmbient(n) + modelFill.rgb;
+  let amb = rzWorldAmbient(n) + modelLight.fill.rgb;
   let shadow = sampleShadow(input.worldPos, n);
   let tex_color = tex_s.rgb;
 

package/src/shaders/lights.ts

@@ -253,6 +253,11 @@ export function lightsApi(group: number, binding: number): string {
 @group(${group}) @binding(${binding}) var<storage, read> _rzLights: array<vec4u>;
 
 const RZ_MAX_LIGHTS: u32 = ${MAX_LIGHTS}u;
+// A lamp's bulb, in world units: the inverse square is held flat inside it,
+// so the spike beside the lamp is finite. Aether Gazer's lamps are
+// 0.1 m across (their shapeRadius, capping 1/d² at 1/0.1), which at MMD scale
+// is 2.5 units.
+const RZ_LAMP_NEAR: f32 = 2.5;
 
 /** How many positional lights the scene has. Zero is the ordinary case. */
 fn rzLightCount() -> u32 { return min(u32(bitcast<f32>(_rzLights[0].x)), RZ_MAX_LIGHTS); }
@@ -294,19 +299,16 @@ fn _rzLightCellMask(p: vec3f) -> vec4u {
 /**
  * One light's contribution at a surface point.
  *
- * FALLOFF IS RELATIVE TO THE RADIUS, and deliberately not physical.
+ * A LIGHT FALLS OFF AS THE INVERSE SQUARE, the curve Unity, Unreal, Blender and
+ * glTF all light with: intensity / max(d², RZ_LAMP_NEAR²), so its intensity is
+ * the brightness one unit away, windowed by (1 − (d/R)⁴)² so it is exactly zero
+ * at its radius and the bound the grid is built from is real.
  *
- * The first version windowed a real inverse-square, and it was unusable: 1/d²
- * is measured in world units, an MMD character is about 18 of them tall, so a
- * lamp two metres off her shoulder divided by 37 and an intensity of 4 landed
- * as 0.06 — invisible. Radius and intensity were fighting, and intensity had no
- * scale a person could learn.
- *
- * So: intensity is the brightness AT the light, radius is where it reaches
- * zero, and the curve between them is the same shape whatever the scene's
- * scale. Both dials now mean what they say, which for a composer beats being
- * right about photons. (1 - t²)² — smooth at both ends, exactly 0 at the
- * radius, so the bound the grid is built from is real.
+ * THE UNITS ARE BLENDER'S. Intensity is radiant intensity, a point light's
+ * power over 4π, and a Lambertian surface returns albedo × irradiance / π —
+ * the π the sun term already carries. So a stage exported from Blender lights
+ * here as it lit there, and a lamp's intensity is what Blender's exporter
+ * writes in candela over 683.
  */
 fn _rzLightOne(i: u32, p: vec3f, n: vec3f) -> vec3f {
   let pr = _rzLightVec(i, 0u);
@@ -322,14 +324,16 @@ fn _rzLightOne(i: u32, p: vec3f, n: vec3f) -> vec3f {
   let ndl = max(dot(n, toLight), 0.0);
   if (ndl <= 0.0) { return vec3f(0.0); }
   let t = clamp(dist / max(pr.w, 1e-4), 0.0, 1.0);
-  let falloff = 1.0 - t * t;
+  let t2 = t * t;
+  let window = 1.0 - t2 * t2;
+  let falloff = window * window / max(dist * dist, RZ_LAMP_NEAR * RZ_LAMP_NEAR);
   // How far inside the cone this point sits: 1 within the inner angle, 0 past
   // the outer one, squared for the same soft edge the falloff has. A point
   // light's (-1, -1) divides by the floor and clamps to 1, so it pays one
   // dot product and no branch.
   let cone = rzLightCone(i);
   let aim = clamp((dot(-toLight, rzLightAim(i)) - cone.x) / max(cone.y - cone.x, 1e-4), 0.0, 1.0);
-  return rzLightColor(i) * (ndl * falloff * falloff * aim * aim);
+  return rzLightColor(i) * (ndl * falloff * aim * aim);
 }
 
 /** The lamps named by one word of a cell's bits, lowest first. */
@@ -355,6 +359,10 @@ fn _rzLightWord(bits0: u32, base: u32, p: vec3f, n: vec3f) -> vec3f {
  * every material must cost nothing until someone asks for a light.
  */
 fn rzLightsDiffuse(p: vec3f, n: vec3f) -> vec3f {
+  return _rzLightsIrradiance(p, n) * (1.0 / 3.141592653589793);
+}
+
+fn _rzLightsIrradiance(p: vec3f, n: vec3f) -> vec3f {
   var acc = vec3f(0.0);
   let count = rzLightCount();
   let docs = _rzLightDocCount();

package/src/shaders/materials/common.ts

@@ -146,9 +146,13 @@ struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 @group(0) @binding(8) var worldEnvTexture: texture_2d<f32>;
 // binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
 @group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
-// Light this model receives beyond the world's — see Engine.setModelFill. Zero
-// for a model nobody gave one, which leaves its ambient exactly the world's.
-@group(1) @binding(1) var<uniform> modelFill: vec4f;
+// The light this model takes apart from the scene's — see Engine.setModelFill
+// and Engine.setModelSun. fill is added to its ambient, zero for a model
+// nobody gave one; sun replaces the scene's sun colour while its w is set,
+// which is how a stage keeps the daylight its game lit it by while the cast
+// keeps the key the scene set for them.
+struct ModelLight { fill: vec4f, sun: vec4f }
+@group(1) @binding(1) var<uniform> modelLight: ModelLight;
 @group(2) @binding(0) var diffuseTexture: texture_2d<f32>;
 @group(2) @binding(1) var<uniform> material: MaterialUniforms;
 // Reserved for future sphere/toon graph nodes; graphs that don't read them get the

package/src/shadow-cascades.ts

@@ -1,68 +1,139 @@
-// The shadow volumes, as data — a list the engine iterates rather than one
-// hardcoded box, so a second cascade is a list entry and not a rewrite.
-//
-// Pure math, its own module for the same reason param-track.ts is: the engine
-// class needs a GPU to construct, and the one thing that ever goes WRONG with a
-// shadow volume is arithmetic — a snap that stops snapping, an eye that lands
-// inside the near plane. Headless tests can hold this half to golden values.
-//
-// The arithmetic is the shipped single-volume code, operation for operation:
-// float addition is not associative, so "the same formula, reordered" is not
-// the same matrix, and cascade 0 must be BIT-IDENTICAL to the volume every
-// published scene was lit by.
-
 import { Mat4, Vec3 } from "./math"
 
-type ShadowCascade = {
-  /** World units across the ortho box, both axes. */
-  span: number
-  /** How far behind the target the light's eye sits, along -sunDir. */
-  back: number
-  /** Ortho near/far, in world units from that eye. */
-  near: number
-  far: number
+/**
+ * THE SUN'S SHADOW FOLLOWS THE CAMERA, the way Blender's does.
+ *
+ * Each cascade is fitted every frame to a slice of the view frustum: the near
+ * one to the stretch around what the camera is looking at, the far one to the
+ * whole of what it sees. Whatever is in view is in a cascade, and whatever
+ * could throw a shadow onto it is in the cascade's depth range, which is fitted
+ * to the scene's bounds along the light. A room forty metres across with its
+ * window frames behind the camera shadows its floor as the game does; a lone
+ * dancer on an empty floor keeps a crisp near map.
+ *
+ * The earlier shape was two fixed boxes around the camera target, 64 and 256
+ * units across, and a stage reached past them: the floor near the windows lay
+ * outside every box and was drawn lit, the shadows stopping at the box's edge
+ * in a straight line.
+ *
+ * INVARIANT the sampler and the cull both lean on: the outer cascade CONTAINS
+ * the inner one. The sampler falls from cascade 0 to 1 at the box edge, which
+ * is only seamless if 1 covers where 0 ends, and the cull tests the OUTERMOST
+ * frustum alone. Both hold because the outer slice is the whole frustum, of
+ * which the inner slice is a part, and both take the same depth range.
+ * tests/shadow-cascades.test.mjs pins it.
+ */
+export type ShadowCascade = {
   /** Texels per side of this cascade's map — sets the snap quantum. */
   mapSize: number
 }
 
+export const SHADOW_CASCADES: readonly ShadowCascade[] = [{ mapSize: 4096 }, { mapSize: 2048 }]
+
+/** How far past the camera's point of interest the near cascade reaches, in
+ *  world units: the dancer and the floor around her, at the near map's texel. */
+export const NEAR_REACH = 40
+
+/** The view the cascades are fitted to: the camera's eye and basis (world
+ *  space, left-handed, +Z forward as the projection is), its vertical field of
+ *  view, aspect and clip planes, and how far away the thing it looks at is. */
+export type ShadowView = {
+  eye: { x: number; y: number; z: number }
+  right: { x: number; y: number; z: number }
+  up: { x: number; y: number; z: number }
+  forward: { x: number; y: number; z: number }
+  fov: number
+  aspect: number
+  near: number
+  far: number
+  /** Distance from the eye to the camera target, along the view. */
+  focus: number
+}
+
+/** World-space box around everything drawn, or null for an empty scene. */
+export type ShadowBounds = { min: [number, number, number]; max: [number, number, number] } | null
+
+type XYZ = { x: number; y: number; z: number }
+
 /**
- * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
- * each cascade's box must CONTAIN the previous one (same snapped target, wider
- * span, deeper reach), because
- *
- *   - the sampler falls from cascade i to i+1 at the box edge, which is only
- *     seamless if i+1 covers where i ends, and
- *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
- *     each cascade to its own box. That is the same argument that made
- *     single-volume shadow culling exact: anything rejected was contributing
- *     nothing anywhere. Concentric containment is what keeps it true for a
- *     LIST. tests/shadow-cascades.test.mjs pins it.
+ * Where each cascade's slice of the view starts and ends, as distances along
+ * the view: [near, split] and [near, farFit]. The far end is where the scene
+ * ends, so an empty floor with a dancer on it keeps a short, sharp frustum
+ * rather than the camera's far plane.
  */
-export const SHADOW_CASCADES: readonly ShadowCascade[] = [
-  // The shipped volume: 64 units at 4096² ≈ 64 texels/unit — crisp contact
-  // shadows on the ground catcher (2048 read visibly blurry).
-  { span: 64, back: 72, near: 1, far: 140, mapSize: 4096 },
-  // The stage volume: 4× the span on each side, so a set piece 100 units out
-  // still throws and receives shade instead of popping lit at the near box's
-  // edge. 2048² over 256 units ≈ 8 texels/unit — soft, and read at distances
-  // where soft is what a shadow looks like anyway. 16 MB where the near map
-  // is 64. Depth reach scales with the span (same eye direction, deeper box),
-  // keeping the containment invariant checkable from the specs alone.
-  { span: 256, back: 288, near: 1, far: 560, mapSize: 2048 },
-]
+export function cascadeSlices(view: ShadowView, bounds: ShadowBounds): [number, number][] {
+  let farFit = view.near + 200
+  if (bounds) {
+    let deepest = 0
+    for (let i = 0; i < 8; i++) {
+      const cx = (i & 1 ? bounds.max : bounds.min)[0] - view.eye.x
+      const cy = (i & 2 ? bounds.max : bounds.min)[1] - view.eye.y
+      const cz = (i & 4 ? bounds.max : bounds.min)[2] - view.eye.z
+      deepest = Math.max(deepest, cx * view.forward.x + cy * view.forward.y + cz * view.forward.z)
+    }
+    farFit = deepest + 1
+  }
+  farFit = Math.min(view.far, Math.max(view.near + 1, farFit))
+  const split = Math.min(farFit, Math.max(view.near + 8, view.focus + NEAR_REACH))
+  return [
+    [view.near, split],
+    [view.near, farFit],
+  ]
+}
+
+/** The bounding sphere of a frustum slice: on the view axis, at the depth that
+ *  balances the near and far rectangles' corners. */
+function sliceSphere(view: ShadowView, n: number, f: number): { center: Vec3; radius: number } {
+  const t = Math.tan(view.fov / 2)
+  const k2 = t * t * (1 + view.aspect * view.aspect)
+  let depth: number
+  let radius: number
+  if (k2 >= (f - n) / (f + n)) {
+    depth = f
+    radius = f * Math.sqrt(k2)
+  } else {
+    depth = 0.5 * (f + n) * (1 + k2)
+    radius = 0.5 * Math.sqrt((f - n) * (f - n) + 2 * (f * f + n * n) * k2 + (f + n) * (f + n) * k2 * k2)
+  }
+  const center = new Vec3(
+    view.eye.x + view.forward.x * depth,
+    view.eye.y + view.forward.y * depth,
+    view.eye.z + view.forward.z * depth,
+  )
+  return { center, radius }
+}
+
+/** The eight corners of a slice, for tests and for the fit's own checks. */
+export function sliceCorners(view: ShadowView, n: number, f: number): XYZ[] {
+  const out: XYZ[] = []
+  for (const d of [n, f]) {
+    const h = d * Math.tan(view.fov / 2)
+    const w = h * view.aspect
+    for (const sy of [-1, 1])
+      for (const sx of [-1, 1])
+        out.push({
+          x: view.eye.x + view.forward.x * d + view.right.x * w * sx + view.up.x * h * sy,
+          y: view.eye.y + view.forward.y * d + view.right.y * w * sx + view.up.y * h * sy,
+          z: view.eye.z + view.forward.z * d + view.right.z * w * sx + view.up.z * h * sy,
+        })
+  }
+  return out
+}
 
 /**
- * One cascade's view-projection, following the camera target.
- *
- * The target is snapped to this cascade's OWN texel quantum in the light's
- * right/up plane, so a moving volume doesn't shimmer its shadow edges while
- * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ * One cascade's view-projection: an orthographic box around the slice's
+ * sphere, snapped to the map's texel grid in the light's right/up plane so a
+ * moving camera doesn't shimmer its shadow edges, and reaching along the light
+ * from the nearest thing in the scene to the farthest, so everything that
+ * could cast into the slice does.
  *
  * Writes the 16 floats into `out` at `offset` and returns `out`.
  */
-export function buildShadowVP(
-  target: { x: number; y: number; z: number },
-  sunDirection: { x: number; y: number; z: number },
+export function fitShadowVP(
+  view: ShadowView,
+  slice: [number, number],
+  sunDirection: XYZ,
+  bounds: ShadowBounds,
   cascade: ShadowCascade,
   out: Float32Array,
   offset: number,
@@ -70,28 +141,49 @@ export function buildShadowVP(
   const dir = new Vec3(sunDirection.x, sunDirection.y, sunDirection.z)
   dir.normalize()
   const up = Math.abs(dir.y) > 0.99 ? new Vec3(0, 0, -1) : new Vec3(0, 1, 0)
-
-  const t = new Vec3(target.x, target.y, target.z)
   const right = Vec3.crossInto(up, dir, new Vec3(0, 0, 0)).normalize()
   const upv = Vec3.crossInto(dir, right, new Vec3(0, 0, 0))
-  const texel = cascade.span / cascade.mapSize
-  const tr = Math.round(t.dot(right) / texel) * texel
-  const tu = Math.round(t.dot(upv) / texel) * texel
-  const td = t.dot(dir)
+
+  const { center, radius } = sliceSphere(view, slice[0], slice[1])
+  // A texel of the map, in world units; the radius is rounded up onto the
+  // grid too, so the box's size does not drift with the fov by fractions.
+  const texel = Math.max((2 * radius) / cascade.mapSize, 1e-4)
+  const half = Math.ceil(radius / texel) * texel
+  const tr = Math.round(center.dot(right) / texel) * texel
+  const tu = Math.round(center.dot(upv) / texel) * texel
+  const td = center.dot(dir)
   const snapped = new Vec3(
     right.x * tr + upv.x * tu + dir.x * td,
     right.y * tr + upv.y * tu + dir.y * td,
     right.z * tr + upv.z * tu + dir.z * td,
   )
 
-  const eye = new Vec3(snapped.x - dir.x * cascade.back, snapped.y - dir.y * cascade.back, snapped.z - dir.z * cascade.back)
-  const view = Mat4.lookAt(eye, snapped, up)
-  const half = cascade.span / 2
-  // The shadow map keeps the NON-reversed convention (orthographicLh maps z to
-  // [0,1] front-to-back) — reversing it buys nothing for an ortho box and the
-  // +2 pipeline depth bias is signed against this direction.
-  const proj = Mat4.orthographicLh(-half, half, -half, half, cascade.near, cascade.far)
-  const vp = proj.multiply(view)
-  out.set(vp.values, offset)
+  // Along the light: from the scene's nearest point to its farthest, with a
+  // margin so a caster on the box's own face is not clipped. With nothing to
+  // fit, the sphere itself.
+  let zmin = td - half
+  let zmax = td + half
+  if (bounds) {
+    for (let i = 0; i < 8; i++) {
+      const z =
+        (i & 1 ? bounds.max : bounds.min)[0] * dir.x + (i & 2 ? bounds.max : bounds.min)[1] * dir.y + (i & 4 ? bounds.max : bounds.min)[2] * dir.z
+      zmin = Math.min(zmin, z)
+      zmax = Math.max(zmax, z)
+    }
+  }
+  const margin = 2 + 0.02 * (zmax - zmin)
+  const back = td - zmin + margin
+  const far = back + (zmax - td) + margin
+  const eye = new Vec3(snapped.x - dir.x * back, snapped.y - dir.y * back, snapped.z - dir.z * back)
+  const viewM = Mat4.lookAt(eye, snapped, up)
+  const proj = Mat4.orthographicLh(-half, half, -half, half, 1, far + 1)
+  out.set(proj.multiply(viewM).values, offset)
+  return out
+}
+
+/** Every cascade's view-projection in a row, inner to outer. */
+export function buildShadowCascades(view: ShadowView, sunDirection: XYZ, bounds: ShadowBounds, out: Float32Array): Float32Array {
+  const slices = cascadeSlices(view, bounds)
+  for (let i = 0; i < SHADOW_CASCADES.length; i++) fitShadowVP(view, slices[i], sunDirection, bounds, SHADOW_CASCADES[i], out, i * 16)
   return out
 }