@woosh/meep-engine 3.13.0 → 3.13.1

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.13.0",
+  "version": "3.13.1",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/shape/ConvexHullShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA8CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IA1DD;;;;OAIG;IACH,UAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;OAMG;IACH,cAFU,WAAW,CAEa;IAElC,0BAA0B;IAC1B,YADW,WAAW,CACU;IAEhC;;;;;;OAMG;IACH,iBAA+B;IAE/B,oCAAoC;IACpC,eAA6B;IAE7B,8BAA8B;IAC9B,iBAAa;IAEb,8BAA8B;IAC9B,uBAAmB;IAkBnB;;;OAGG;IACH,kBA8EC;IAKD,wCAIC;IAED;;;;;OAKG;IACH,qGAwCC;IAED;;;;;;;;OAQG;IACH,yCAEC;IAED;;;;OAIG;IACH,wCAEC;IAED,qCAkBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAiBC;IAED,mEAEC;IAED,4DAoBC;IAGD;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAvX+B,sBAAsB"}
+{"version":3,"file":"ConvexHullShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/ConvexHullShape3D.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA8CI;;;;;;;OAOG;IACH,sBAJW,YAAY,WACZ,WAAW,GACT,iBAAiB,CAQ7B;IA1DD;;;;OAIG;IACH,UAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;OAMG;IACH,cAFU,WAAW,CAEa;IAElC,0BAA0B;IAC1B,YADW,WAAW,CACU;IAEhC;;;;;;OAMG;IACH,iBAA+B;IAE/B,oCAAoC;IACpC,eAA6B;IAE7B,8BAA8B;IAC9B,iBAAa;IAEb,8BAA8B;IAC9B,uBAAmB;IAkBnB;;;OAGG;IACH,kBAkFC;IAUD,wCAQC;IAED;;;;;OAKG;IACH,qGAwCC;IAED;;;;;;;;OAQG;IACH,yCAEC;IAED;;;;OAIG;IACH,wCAEC;IAED,qCAkBC;IAED;;;OAGG;IACH,oCAgBC;IAED;;;OAGG;IACH,6CAiBC;IAED,mEAEC;IAED,4DAwBC;IAGD;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAanB;IAcL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;CAP9C;gCAtY+B,sBAAsB"}

package/src/core/geom/3d/shape/ConvexHullShape3D.js

@@ -1,10 +1,10 @@
 import { hash_mix2 } from "../../../math/hash/hash_mix2.js";
 import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { aabb3_from_v3_array } from "../aabb/aabb3_from_v3_array.js";
+import { convex_polyhedron3_raycast } from "../polyhedron/convex_polyhedron3_raycast.js";
 import { tri3_closest_point } from "../triangle/tri3_closest_point.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
-import { aabb3_from_v3_array } from "../aabb/aabb3_from_v3_array.js";
-import { convex_polyhedron3_raycast } from "../polyhedron/convex_polyhedron3_raycast.js";
 
 /**
  * Convex polyhedron collider.
@@ -161,9 +161,13 @@ export class ConvexHullShape3D extends AbstractShape3D {
             //   Σ a·n === Σ (a − o)·n over a closed surface, since Σ n = 0.
             vol6 += (ax - ox) * nx + (ay - oy) * ny + (az - oz) * nz;
 
-            nx /= len; ny /= len; nz /= len;
+            nx /= len;
+            ny /= len;
+            nz /= len;
             const o = f * 4;
-            planes[o] = nx; planes[o + 1] = ny; planes[o + 2] = nz;
+            planes[o] = nx;
+            planes[o + 1] = ny;
+            planes[o + 2] = nz;
             planes[o + 3] = nx * ax + ny * ay + nz * az;
         }
         this.__planes = planes;
@@ -178,13 +182,22 @@ export class ConvexHullShape3D extends AbstractShape3D {
         this.face_loops = idx;
     }
 
-    get volume() { return this.__volume; }
-    get surface_area() { return this.__surface_area; }
+    get volume() {
+        return this.__volume;
+    }
+
+    get surface_area() {
+        return this.__surface_area;
+    }
 
     compute_bounding_box(result) {
         const b = this.__bbox;
-        result[0] = b[0]; result[1] = b[1]; result[2] = b[2];
-        result[3] = b[3]; result[4] = b[4]; result[5] = b[5];
+        result[0] = b[0];
+        result[1] = b[1];
+        result[2] = b[2];
+        result[3] = b[3];
+        result[4] = b[4];
+        result[5] = b[5];
     }
 
     /**
@@ -201,9 +214,9 @@ export class ConvexHullShape3D extends AbstractShape3D {
     ) {
 
         const v = this.vertices;
-        const vc = v.length / 3;
+        const vertex_array_length = v.length;
 
-        if (vc === 0) {
+        if (vertex_array_length === 0) {
 
             result[result_offset] = 0;
             result[result_offset + 1] = 0;
@@ -212,27 +225,27 @@ export class ConvexHullShape3D extends AbstractShape3D {
             return;
         }
 
-        let best = -Infinity;
-        let bi = 0;
+        let best_distance = -Infinity;
+        let best_offset = 0;
 
-        for (let i = 0; i < vc; i++) {
+        for (let offset = 0; offset < vertex_array_length; offset += 3) {
 
-            const v_x = v[i * 3];
-            const v_y = v[i * 3 + 1];
-            const v_z = v[i * 3 + 2];
+            const v_x = v[offset];
+            const v_y = v[offset + 1];
+            const v_z = v[offset + 2];
 
             const d = direction_x * v_x + direction_y * v_y + direction_z * v_z;
 
-            if (d > best) {
-                best = d;
-                bi = i;
+            if (d > best_distance) {
+                best_distance = d;
+                best_offset = offset;
             }
 
         }
 
-        result[result_offset] = v[bi * 3];
-        result[result_offset + 1] = v[bi * 3 + 1];
-        result[result_offset + 2] = v[bi * 3 + 2];
+        result[result_offset] = v[best_offset];
+        result[result_offset + 1] = v[best_offset + 1];
+        result[result_offset + 2] = v[best_offset + 2];
     }
 
     /**
@@ -342,10 +355,14 @@ export class ConvexHullShape3D extends AbstractShape3D {
             const d2 = tri3_closest_point(scratch_closest, 0, px, py, pz, ax, ay, az, bx, by, bz, cx, cy, cz);
             if (d2 < best_d2) {
                 best_d2 = d2;
-                bx_ = scratch_closest[0]; by_ = scratch_closest[1]; bz_ = scratch_closest[2];
+                bx_ = scratch_closest[0];
+                by_ = scratch_closest[1];
+                bz_ = scratch_closest[2];
             }
         }
-        result[0] = bx_; result[1] = by_; result[2] = bz_;
+        result[0] = bx_;
+        result[1] = by_;
+        result[2] = bz_;
     }
 
 
@@ -387,4 +404,3 @@ ConvexHullShape3D.prototype.isConvexHullShape3D = true;
 
 // closest-point-on-triangle output for the surface-scan query helpers
 const scratch_closest = new Float64Array(3);
-const scratch_point = new Float64Array(3);

package/src/core/geom/3d/shape/PosedShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAoED,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAlL+B,sBAAsB"}
+{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAyED,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAvL+B,sBAAsB"}

package/src/core/geom/3d/shape/PosedShape3D.js

@@ -86,7 +86,10 @@ export class PosedShape3D extends AbstractShape3D {
         // inline here at the cost of ~7 extra lines per direction.
         // See core/geom/vec3/v3_quat3_apply.js for the canonical form
         // — this is a literal expansion of it.
-        const qx = this.qx, qy = this.qy, qz = this.qz, qw = this.qw;
+        const qx = this.qx;
+        const qy = this.qy;
+        const qz = this.qz;
+        const qw = this.qw;
 
         // Rotate world direction into body frame via the conjugate
         // quaternion: v_local = q* · v_world · q.  Conjugate xyz are
@@ -105,7 +108,9 @@ export class PosedShape3D extends AbstractShape3D {
 
         // Rotate the body-local support point back to world: v_world =
         // q · v_local · q*.
-        const lsx = scratch_local[0], lsy = scratch_local[1], lsz = scratch_local[2];
+        const lsx = scratch_local[0];
+        const lsy = scratch_local[1];
+        const lsz = scratch_local[2];
 
         const tsx =  qw * lsx + qy * lsz - qz * lsy;
         const tsy =  qw * lsy + qz * lsx - qx * lsz;

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#360@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#362@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#360@#clear_field"(fluid: FluidComponent): void;
+    static "__#362@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#360@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#362@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#360@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#362@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/device/PASS_ENCODER_PROPOSAL_2026_08_31.md

@@ -12,6 +12,10 @@
 > **Revision 3** records what shipped. The §9 decisions were taken (§9), the error-carrying
 > `workgroup_size_error` of revision 2 was rejected in favour of throwing at construction (§3.5),
 > and the code landed in three commits (§10).
+>
+> **Revision 4** rewrites §3.2, which was wrong and shipped a renderer that could not draw. Revision
+> 2 identified `setBindGroup` as the one forward that could be actively wrong and then guarded the
+> wrong end of it. §8.9 is the post-mortem; §3.2 is now the rule that replaced it.
 
 ---
 
@@ -228,9 +232,7 @@ export class ShadeGPUComputePassEncoder {
 
     setBindGroupRange(index, bind_group, data, data_start, data_length) { /* §3.2 */ }
 
-    setImmediates(range_offset, data, data_offset, data_size) {
-        this.#pass.setImmediates(range_offset, data, data_offset, data_size);
-    }
+    setImmediates(...args) { /* §3.2, shape 1 */ }
 
     // --- GPUDebugCommandsMixin ------------------------------------------------
 
@@ -662,6 +664,16 @@ call it out. This is the single most likely place for this change to introduce a
 - **"Both classes ~120 lines."** Now ~130 with the `label` setter and the split `setBindGroup`.
   Immaterial, but the earlier number was a guess presented as a measurement.
 
+### 8.8 Residual risks, accepted
+
+- **A WebGPU method Chrome ships that Shade has not modelled** is now a hard failure rather than a
+  silent forward. That is the intended trade (§8.2), but it means the browser check is load-bearing
+  and needs to actually run in CI or a pre-release checklist, not just exist.
+- **`executeBundles` work is uncounted** (§3.3). Pre-existing, documented, nothing uses bundles.
+- **99 call sites change type.** No reflection over pass objects exists anywhere in the tree
+  (`typeof pass.x`, `Object.keys(pass)`, spread, `instanceof` — all checked, all absent), so the
+  surface is method calls only. If one is missed it throws at that call; it cannot silently misbehave.
+
 ### 8.9 It shipped broken anyway — the arity bug *(found in a browser, after landing)*
 
 `setBindGroup(0, bind_group)` forwarded `setBindGroup(0, bind_group, undefined)`, and the renderer
@@ -702,16 +714,6 @@ rather than claiming a mechanism it cannot demonstrate.
 three tiers in §6 are blind to the mock/browser boundary by construction, and this change has now
 been wrong at that boundary twice.
 
-### 8.8 Residual risks, accepted
-
-- **A WebGPU method Chrome ships that Shade has not modelled** is now a hard failure rather than a
-  silent forward. That is the intended trade (§8.2), but it means the browser check is load-bearing
-  and needs to actually run in CI or a pre-release checklist, not just exist.
-- **`executeBundles` work is uncounted** (§3.3). Pre-existing, documented, nothing uses bundles.
-- **99 call sites change type.** No reflection over pass objects exists anywhere in the tree
-  (`typeof pass.x`, `Object.keys(pass)`, spread, `instanceof` — all checked, all absent), so the
-  surface is method calls only. If one is missed it throws at that call; it cannot silently misbehave.
-
 ---
 
 ## 9. Decisions taken
@@ -745,6 +747,9 @@ Still open, and deliberately not done here:
 2. `refactor(shade): pass encoders become explicit decorator classes` — §§3.1–3.4 and 3.6, plus the
    BVH verification tool moved onto a `GPUFrameRecorder`.
 3. `refactor(shade): remove the debug-timer path, the profiler is the only one` — §4.
+4. `fix(shade): pass encoders forward the arity they received` — §3.2, after the renderer failed on
+   its first bind group in a browser. §8.9.
 
 Revision 2 ordered these decorators-first; that was wrong (§8.4) and the workgroup size went first
-instead. Full suite green after each: 15,012 tests.
+instead. Full suite green after each: 15,014 tests — which, per §8.9, was never going to be enough
+on its own.

package/src/shade/renderer/scene/Mesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Mesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Mesh.js"],"names":[],"mappings":"AAYA;IA2HI;;;;;;OAMG;IACH,mFAFY,IAAI,CAoBf;IAnJD;;OAEG;IACH,0BAAS;IAET;;OAEG;IACH,wBAAS;IAET;;;OAGG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,iBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,SAFa,IAAI,CAQhB;IAED;;;OAGG;IACH,YAFW,IAAI,QAiBd;IAED;;;;OAIG;IACH,cAHW,IAAI,GACF,OAAO,CAQnB;IAQD,0BAOC;IAED,0BAqCC;IA+BL,gBAAqB;CAHpB;uBAvJsB,aAAa"}
+{"version":3,"file":"Mesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/Mesh.js"],"names":[],"mappings":"AAUA;IA2HI;;;;;;OAMG;IACH,mFAFY,IAAI,CAoBf;IAnJD;;OAEG;IACH,0BAAS;IAET;;OAEG;IACH,wBAAS;IAET;;;OAGG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,iBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,SAFa,IAAI,CAQhB;IAED;;;OAGG;IACH,YAFW,IAAI,QAiBd;IAED;;;;OAIG;IACH,cAHW,IAAI,GACF,OAAO,CAQnB;IAQD,0BAOC;IAED,0BAqCC;IA+BL,gBAAqB;CAHpB;uBAvJsB,aAAa"}

package/src/shade/renderer/scene/Mesh.js

@@ -1,10 +1,8 @@
 import { assert } from "../../../core/assert.js";
 import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
-import {
-    aabb3_from_v3_array_transformed
-} from "../../../core/geom/3d/aabb/aabb3_from_v3_array_transformed.js";
+import { aabb3_from_v3_array_transformed } from "../../../core/geom/3d/aabb/aabb3_from_v3_array_transformed.js";
 import { aabb3_matrix4_project } from "../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
-import { sphere_matrix4_project } from "../../../core/geom/3d/sphere/sphere_matrix4_transform.js";
+import { sphere_matrix4_transform } from "../../../core/geom/3d/sphere/sphere_matrix4_transform.js";
 import { epsilonEquals } from "../../../core/math/epsilonEquals.js";
 import { optional_equality } from "../../descriptor/util/optional_equality.js";
 import { StandardAttributes } from "../geometry/StandardAttributes.js";
@@ -91,7 +89,7 @@ export class Mesh extends Node3D {
         const m = this.transform_global;
 
         aabb3_matrix4_project(this.bounding_box, this.geometry.bounding_box, m);
-        sphere_matrix4_project(this.bounding_sphere, this.geometry.bounding_sphere, m);
+        sphere_matrix4_transform(this.bounding_sphere, this.geometry.bounding_sphere, m);
     }
 
     updateBoundsTight() {
@@ -128,7 +126,7 @@ export class Mesh extends Node3D {
 
             {
                 // todo do a tight sphere bounds
-                sphere_matrix4_project(this.bounding_sphere, this.geometry.bounding_sphere, this.transform_global);
+                sphere_matrix4_transform(this.bounding_sphere, this.geometry.bounding_sphere, this.transform_global);
             }
         }
     }

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.d.ts

@@ -81,7 +81,8 @@ export class GPUSceneShadowmapContext {
      * Runs at the top of every frame, before {@link draw}. Responsibilities:
      *
      *  1. **Reset per-frame signals.** `should_draw` is cleared on every map so a stale "yes"
-     *     from a prior frame can never cause a spurious extra raster.
+     *     from a prior frame can never cause a spurious extra raster. Folded into the selector's
+     *     scoring pass, which walks every map anyway.
      *  2. **Measure on-screen presence.** `projected_area_px` is computed once per map and stored
      *     on the map itself — consumed by the resolution policy, the scorer, and the selector,
      *     and exposed for debug tooling.
@@ -90,7 +91,8 @@ export class GPUSceneShadowmapContext {
      *     resize. The committed `layout` is left untouched so sampling remains valid; the
      *     pending is consumed later by {@link draw} when the scheduler naturally picks this map
      *     up (no forced redraw).
-     *  4. **Score + select.** For each map:
+     *  4. **Score + select.** Delegated to {@link ShadowmapDrawSelector}, which sets `should_draw`
+     *     on the winners and reports the view spend and whether any candidate went unmet:
      *        - **Directional** → always selected (infinite score); view cost still charged.
      *        - **Local, off-screen** (`projected_area_px <= 0`) → skipped entirely.
      *        - **Local, in-view, invalid** → MUST draw. `is_invalid` means the committed layout
@@ -99,15 +101,16 @@ export class GPUSceneShadowmapContext {
      *          layout model — this flag fires only on first-draw.
      *        - **Local, in-view, valid** → compete for the remaining budget by score. Ordering
      *          is descending score so the most important (largest-on-screen, stalest) maps win.
-     *  5. **Commit selection.** On each winner we set `should_draw = true` and call
-     *     `map.update()` so its projection matrices reflect the current frame. The
-     *     `last_updated_frame_index` stamp is deferred to {@link draw} — it records when the
-     *     atlas contents become current, not when the projection is fitted.
+     *  5. **Fit the winners.** `map.update()` on each selected map, so its projection matrices
+     *     reflect the current frame. The `last_updated_frame_index` stamp is deferred to
+     *     {@link draw} — it records when the atlas contents become current, not when the
+     *     projection is fitted.
      *
      * Shadow records are NOT written here; they're written at the end of {@link draw} so the
      * shader reads slots that reflect any just-committed pending swaps within the same frame.
      *
-     * See {@link compute_shadowmap_update_score} for the scoring formula and rationale.
+     * See {@link compute_shadowmap_update_score} for the scoring formula and rationale, and
+     * {@link ShadowmapDrawSelector} for why the ordering is a heap drain rather than a sort.
      *
      * @param {Camera} main_camera used both for rendering the final frame and for projected-area
      *        computation and directional CSM fit; must be callable for `.update()`
@@ -160,6 +163,12 @@ export class GPUSceneShadowmapContext {
      * {@link LightCollection.version} hasn't moved — `light.casts_shadow` flips are not
      * tracked by version and are detected here.
      *
+     * Runs as three linear passes — mark, reclaim, allocate — over {@link #registry}, which owns
+     * the light -> map index and the marks. It used to scan the map array once per light to find
+     * out whether that light already had one, which made the pass quadratic: 148us per frame at
+     * 512 lights against 19us now, and 554us against 45us at 1024. See
+     * benchmark/reconcile.spec.js.
+     *
      * @returns {boolean} true when at least one map was added/evicted or at least one light's
      *          per-type shadow_id moved. The caller uses this to decide whether the light
      *          records need to be re-published (their `shadow_id` and CASTS_SHADOW_BIT may

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAsFA;;GAEG;AACH;IA8JI;;;;;;;;OAQG;IACH,8FA0DC;IAhOD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsBpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IAqCtC;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAgGD;;;;OAIG;IACH,uBAFa,YAAU,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,0EAJW,MAAM,mBACN,UAAU,MAAM,CAAC,QA6G3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,gDAiFC;IA6aD;;;;;;;;;;;;;;OAcG;IACH,kBALa,OAAO,CAkMnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAWC;;CACJ;oCAvyCmC,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}
+{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAwFA;;GAEG;AACH;IA8KI;;;;;;;;OAQG;IACH,8FA0DC;IAhPD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IAqCtC;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAgGD;;;;OAIG;IACH,uBAFa,YAAU,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,0EAJW,MAAM,mBACN,UAAU,MAAM,CAAC,QAgE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,gDAiFC;IA6aD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAuOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAYC;;CACJ;oCA3zCmC,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}