@woosh/meep-engine 3.13.0 → 3.14.0

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

@@ -113,6 +113,19 @@ export class Shadowmap {
      * @type {boolean}
      */
     metadata_changed: boolean;
+    /**
+     * Which reconciliation pass last saw this map's light in the scene. Owned entirely by
+     * {@link ShadowmapRegistry} — nothing else should read or write it.
+     *
+     * Lives on the map rather than in a side table because the reclamation pass tests it once per
+     * map per frame, and a hash lookup there costs more than the whole rest of the pass. A
+     * `WeakMap` keyed by map measured at about twice the total reconciliation time at 32 lights.
+     *
+     * 0 means "never marked", which is what a map reads as before its first reconciliation. The
+     * registry marks from 1 upward, so an unmarked map is correctly treated as stale.
+     * @type {number}
+     */
+    _reconcile_mark: number;
     /**
      *
      * @param {Camera} main_camera

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

@@ -1 +1 @@
-{"version":3,"file":"Shadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/Shadowmap.js"],"names":[],"mappings":"AAAA;IACI,WAAO;IAEP;;OAEG;IACH,aAAK;IAEL;;;;OAIG;IACH,QAFU,OAAO,CAEL;IAEZ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAFU,OAAO,GAAG,IAAI,CAEF;IAEtB;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,0BAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,yBAFU,MAAM,CAEa;IAE7B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAFU,OAAO,CAEC;IAElB;;;;;;;;OAQG;IACH,aAFU,OAAO,CAEG;IAEpB;;;;;;;;;;;;;;OAcG;IACH,kBAFU,OAAO,CAEO;IAExB;;;;OAIG;IACH,8DAEC;IAED;;;;;;;OAOG;IACH,mBAEC;IAED,gBAEC;CACJ"}
+{"version":3,"file":"Shadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/Shadowmap.js"],"names":[],"mappings":"AAAA;IACI,WAAO;IAEP;;OAEG;IACH,aAAK;IAEL;;;;OAIG;IACH,QAFU,OAAO,CAEL;IAEZ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAFU,OAAO,GAAG,IAAI,CAEF;IAEtB;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,0BAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,yBAFU,MAAM,CAEa;IAE7B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAFU,OAAO,CAEC;IAElB;;;;;;;;OAQG;IACH,aAFU,OAAO,CAEG;IAEpB;;;;;;;;;;;;;;OAcG;IACH,kBAFU,OAAO,CAEO;IAExB;;;;;;;;;;;OAWG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,8DAEC;IAED;;;;;;;OAOG;IACH,mBAEC;IAED,gBAEC;CACJ"}

package/src/shade/renderer/shadow/map/Shadowmap.js

@@ -124,6 +124,20 @@ export class Shadowmap {
      */
     metadata_changed = true;
 
+    /**
+     * Which reconciliation pass last saw this map's light in the scene. Owned entirely by
+     * {@link ShadowmapRegistry} — nothing else should read or write it.
+     *
+     * Lives on the map rather than in a side table because the reclamation pass tests it once per
+     * map per frame, and a hash lookup there costs more than the whole rest of the pass. A
+     * `WeakMap` keyed by map measured at about twice the total reconciliation time at 32 lights.
+     *
+     * 0 means "never marked", which is what a map reads as before its first reconciliation. The
+     * registry marks from 1 upward, so an unmarked map is correctly treated as stale.
+     * @type {number}
+     */
+    _reconcile_mark = 0;
+
     /**
      *
      * @param {Camera} main_camera

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

@@ -0,0 +1,79 @@
+/**
+ * Picks which shadowmaps get rasterized this frame, given a view budget.
+ *
+ * This is the score-and-select half of {@link GPUSceneShadowmapContext.select_for_draw}, split out
+ * so it can be measured without a GPU device — the scoring is arithmetic over plain fields, and
+ * the only reason it used to need a renderer was that it lived on the class that owns the atlas.
+ *
+ * **Why a heap and not a sort.** The budget is a handful of views and a scene can hold hundreds of
+ * candidates, so a full ordering is thrown away almost entirely: it sorts N to consume ~K. Popping
+ * a max-heap K times is O(N + K log N) against the sort's O(N log N), and skips the N `{map,
+ * score}` objects the sorted version allocated every frame. Measured at 512 lights: 30us per frame
+ * for the sort, 2.6us for the heap. Removing just the allocation and keeping the sort gets 8.3us,
+ * so roughly a third of the win is the allocation and the rest is not ordering the tail. See
+ * benchmark/select.spec.js.
+ *
+ * **Ordering is load-bearing, so the heap is drained in score order rather than partitioned.**
+ * A map that has never been drawn must refresh whether or not the budget can cover it, but WHEN it
+ * charges its views against the pool decides whether a lower-priority map still fits. Settling all
+ * the must-draws up front would be cheaper and would change which maps draw, so they compete in
+ * the same ordered drain as everything else.
+ *
+ * **Ties resolve differently than a sort.** `Array.sort` is stable, so equal scores kept array
+ * order; a heap has no such guarantee, and it compares float32 where the sort compared float64.
+ * Maps with equal scores are interchangeable by construction — the scorer is the definition of
+ * which map deserves the slot, and it rated them the same — so what the benchmark asserts is that
+ * the selection is equally good (same view spend, same carry-over signal, same multiset of
+ * selected scores), not that it is the same maps. Ties are common rather than exotic here: every
+ * light the camera sits inside reports the full viewport as its projected area.
+ */
+export class ShadowmapDrawSelector {
+    /**
+     * Maps chosen by the most recent {@link select}, in the order they were selected. Reused
+     * across frames — read it before the next call, don't retain it.
+     * @type {Shadowmap[]}
+     */
+    selected: Shadowmap[];
+    /**
+     * Views the most recent {@link select} committed, counting must-draws that bypassed the
+     * budget. Can exceed the budget it was given.
+     * @type {number}
+     */
+    views_spent: number;
+    /**
+     * True when the most recent {@link select} left at least one in-view candidate unrefreshed
+     * because the pool could not cover its view cost. Drives the caller's carry-over: unused
+     * budget is only worth carrying forward when there was demand it could not meet.
+     * @type {boolean}
+     */
+    had_unfit_candidates: boolean;
+    /**
+     * Score every shadowmap and mark the winners with `should_draw`.
+     *
+     * Categories, in the order the drain encounters them:
+     *
+     *   - **Directional** — always refreshes. Scores Infinity, so it would head the ordering
+     *     anyway; it is settled during the scoring pass instead of being pushed onto the heap
+     *     because the outcome cannot depend on where it lands. Its view cost is still charged, so
+     *     local lights see a reduced pool.
+     *   - **Local, off-screen** (`projected_area_px <= 0`) — skipped entirely. Not demand, and not
+     *     carry-over fuel: the map keeps its flags and springs back when it returns to view.
+     *   - **Local, in-view, invalid** — must draw. `is_invalid` means the committed layout has
+     *     never held valid depth, so sampling it would show garbage. Bypasses the budget but is
+     *     visited in score order, because its charge against the pool is what decides whether the
+     *     candidates below it still fit.
+     *   - **Local, in-view, valid** — competes for what is left, highest score first.
+     *
+     * Results land on {@link selected}, {@link views_spent} and {@link had_unfit_candidates}.
+     * `map.update()` is deliberately NOT called here — that needs the camera and the scene, and
+     * keeping it out is what keeps this side GPU-free. The caller walks {@link selected}.
+     *
+     * @param {Shadowmap[]} shadowmaps every map in the scene; `projected_area_px` must already be
+     *        current for this frame
+     * @param {number} frame_index monotonically increasing frame counter, used for staleness
+     * @param {number} budget_total views available this frame, including any carry-over
+     */
+    select(shadowmaps: Shadowmap[], frame_index: number, budget_total: number): void;
+    #private;
+}
+//# sourceMappingURL=ShadowmapDrawSelector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShadowmapDrawSelector.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowmapDrawSelector.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACI;;;;OAIG;IACH,UAFU,WAAW,CAEP;IAEd;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,sBAFU,OAAO,CAEY;IAsC7B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,mBALW,WAAW,eAEX,MAAM,gBACN,MAAM,QA+EhB;;CACJ"}

package/src/shade/renderer/shadow/map/ShadowmapDrawSelector.js

@@ -0,0 +1,196 @@
+import { IndexedFloatMaxHeap } from "../../../../core/collection/heap/IndexedFloatMaxHeap.js";
+import { compute_shadowmap_update_score } from "./shadowmap_update_score.js";
+
+/**
+ * Picks which shadowmaps get rasterized this frame, given a view budget.
+ *
+ * This is the score-and-select half of {@link GPUSceneShadowmapContext.select_for_draw}, split out
+ * so it can be measured without a GPU device — the scoring is arithmetic over plain fields, and
+ * the only reason it used to need a renderer was that it lived on the class that owns the atlas.
+ *
+ * **Why a heap and not a sort.** The budget is a handful of views and a scene can hold hundreds of
+ * candidates, so a full ordering is thrown away almost entirely: it sorts N to consume ~K. Popping
+ * a max-heap K times is O(N + K log N) against the sort's O(N log N), and skips the N `{map,
+ * score}` objects the sorted version allocated every frame. Measured at 512 lights: 30us per frame
+ * for the sort, 2.6us for the heap. Removing just the allocation and keeping the sort gets 8.3us,
+ * so roughly a third of the win is the allocation and the rest is not ordering the tail. See
+ * benchmark/select.spec.js.
+ *
+ * **Ordering is load-bearing, so the heap is drained in score order rather than partitioned.**
+ * A map that has never been drawn must refresh whether or not the budget can cover it, but WHEN it
+ * charges its views against the pool decides whether a lower-priority map still fits. Settling all
+ * the must-draws up front would be cheaper and would change which maps draw, so they compete in
+ * the same ordered drain as everything else.
+ *
+ * **Ties resolve differently than a sort.** `Array.sort` is stable, so equal scores kept array
+ * order; a heap has no such guarantee, and it compares float32 where the sort compared float64.
+ * Maps with equal scores are interchangeable by construction — the scorer is the definition of
+ * which map deserves the slot, and it rated them the same — so what the benchmark asserts is that
+ * the selection is equally good (same view spend, same carry-over signal, same multiset of
+ * selected scores), not that it is the same maps. Ties are common rather than exotic here: every
+ * light the camera sits inside reports the full viewport as its projected area.
+ */
+export class ShadowmapDrawSelector {
+    /**
+     * Maps chosen by the most recent {@link select}, in the order they were selected. Reused
+     * across frames — read it before the next call, don't retain it.
+     * @type {Shadowmap[]}
+     */
+    selected = [];
+
+    /**
+     * Views the most recent {@link select} committed, counting must-draws that bypassed the
+     * budget. Can exceed the budget it was given.
+     * @type {number}
+     */
+    views_spent = 0;
+
+    /**
+     * True when the most recent {@link select} left at least one in-view candidate unrefreshed
+     * because the pool could not cover its view cost. Drives the caller's carry-over: unused
+     * budget is only worth carrying forward when there was demand it could not meet.
+     * @type {boolean}
+     */
+    had_unfit_candidates = false;
+
+    /**
+     * Heap of budget candidates, keyed by index into the shadowmap array the current
+     * {@link select} was handed. Held across frames so the id table and slot storage are
+     * allocated once rather than per frame.
+     * @type {IndexedFloatMaxHeap}
+     */
+    #heap = new IndexedFloatMaxHeap(0);
+
+    /**
+     * Id capacity of {@link #heap}. Ids are shadowmap array indices, so this has to cover the
+     * largest map count seen so far.
+     * @type {number}
+     */
+    #heap_capacity = 0;
+
+    /**
+     * Resize the heap to hold ids up to `count`. IndexedFloatMaxHeap sizes its id table at
+     * construction, so growing means a new heap — safe here because the heap is empty between
+     * frames and carries nothing worth migrating.
+     *
+     * Rounded up to a power of two so a scene that gains lights one at a time reallocates a
+     * handful of times rather than every frame.
+     *
+     * @param {number} count
+     */
+    #ensure_capacity(count) {
+        if (count <= this.#heap_capacity) {
+            return;
+        }
+
+        const capacity = Math.max(64, 1 << (32 - Math.clz32(count - 1)));
+
+        this.#heap = new IndexedFloatMaxHeap(capacity);
+        this.#heap_capacity = capacity;
+    }
+
+    /**
+     * Score every shadowmap and mark the winners with `should_draw`.
+     *
+     * Categories, in the order the drain encounters them:
+     *
+     *   - **Directional** — always refreshes. Scores Infinity, so it would head the ordering
+     *     anyway; it is settled during the scoring pass instead of being pushed onto the heap
+     *     because the outcome cannot depend on where it lands. Its view cost is still charged, so
+     *     local lights see a reduced pool.
+     *   - **Local, off-screen** (`projected_area_px <= 0`) — skipped entirely. Not demand, and not
+     *     carry-over fuel: the map keeps its flags and springs back when it returns to view.
+     *   - **Local, in-view, invalid** — must draw. `is_invalid` means the committed layout has
+     *     never held valid depth, so sampling it would show garbage. Bypasses the budget but is
+     *     visited in score order, because its charge against the pool is what decides whether the
+     *     candidates below it still fit.
+     *   - **Local, in-view, valid** — competes for what is left, highest score first.
+     *
+     * Results land on {@link selected}, {@link views_spent} and {@link had_unfit_candidates}.
+     * `map.update()` is deliberately NOT called here — that needs the camera and the scene, and
+     * keeping it out is what keeps this side GPU-free. The caller walks {@link selected}.
+     *
+     * @param {Shadowmap[]} shadowmaps every map in the scene; `projected_area_px` must already be
+     *        current for this frame
+     * @param {number} frame_index monotonically increasing frame counter, used for staleness
+     * @param {number} budget_total views available this frame, including any carry-over
+     */
+    select(shadowmaps, frame_index, budget_total) {
+        const n = shadowmaps.length;
+
+        const selected = this.selected;
+        selected.length = 0;
+
+        let views_spent = 0;
+        let had_unfit_candidates = false;
+
+        this.#ensure_capacity(n);
+
+        const heap = this.#heap;
+        heap.clear();
+
+        // Number of must-draw maps still in the heap. Tracked rather than looked for, because it
+        // is the only thing that can stop the drain from exiting early — see below.
+        let invalid_in_heap = 0;
+
+        for (let i = 0; i < n; i++) {
+            const map = shadowmaps[i];
+
+            map.should_draw = false;
+
+            if (map.light.isDirectionalLight) {
+                map.should_draw = true;
+                selected.push(map);
+                views_spent += map.views.length;
+                continue;
+            }
+
+            if (map.projected_area_px <= 0) {
+                continue;
+            }
+
+            if (map.is_invalid) {
+                invalid_in_heap++;
+            }
+
+            heap.insert(i, compute_shadowmap_update_score(map, frame_index));
+        }
+
+        while (heap.size > 0) {
+            // Every map costs at least one view, so once the pool is gone nothing left can fit and
+            // the remainder are unfit by definition — provided none of them is a must-draw, which
+            // would have to be visited regardless. In steady state there are none (`is_invalid` is
+            // cleared by the first successful raster) and this fires after about `budget_total`
+            // pops, which is what bounds K. During a cold start it degrades to a full drain, i.e.
+            // to a heapsort, still ahead of the comparator sort it replaced.
+            if (views_spent >= budget_total && invalid_in_heap === 0) {
+                had_unfit_candidates = true;
+                break;
+            }
+
+            const map = shadowmaps[heap.pop_max()];
+            const cost = map.views.length;
+
+            if (map.is_invalid) {
+                invalid_in_heap--;
+                map.should_draw = true;
+                selected.push(map);
+                views_spent += cost;
+                continue;
+            }
+
+            if (views_spent + cost <= budget_total) {
+                map.should_draw = true;
+                selected.push(map);
+                views_spent += cost;
+            } else {
+                // Wanted to refresh but the pool could not cover its view cost. Keep going — a
+                // cheaper candidate further down may still fit.
+                had_unfit_candidates = true;
+            }
+        }
+
+        this.views_spent = views_spent;
+        this.had_unfit_candidates = had_unfit_candidates;
+    }
+}

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

@@ -0,0 +1,91 @@
+/**
+ * The set of shadowmaps a scene currently holds, indexed by the light each one belongs to.
+ *
+ * Exists to make {@link GPUSceneShadowmapContext.process_lights} cheap. That pass runs every
+ * frame for every scene, and its job is to answer two questions per element: "does this light
+ * already have a map" (once per light) and "is this map's light still in the scene" (once per
+ * map). Answering the first by scanning the map array made the pass O(lights x maps) — 148us per
+ * frame at 512 lights, 554us at 1024, against 24us and 57us with the index. See
+ * benchmark/reconcile.spec.js.
+ *
+ * The second question is answered by MARKING rather than by a per-frame `new Set(lights)`. A
+ * reconciliation stamps every light's map with the current pass's mark as it walks the light
+ * array; anything still carrying an older mark afterwards belongs to a light that has left. That
+ * folds the liveness check into the lookup that was happening anyway, so the pass builds no
+ * per-frame collection at all.
+ *
+ * Deliberately GPU-free — it owns array and index bookkeeping and nothing else. Allocating an
+ * atlas rect, creating views and cameras, and releasing them again all stay in
+ * {@link GPUSceneShadowmapContext}, which is what lets this be measured without a device.
+ *
+ * Invariant: a light has at most one map. {@link add} asserts it.
+ */
+export class ShadowmapRegistry {
+    /**
+     * The live map array, in allocation order. Callers iterate this directly — the draw pass, the
+     * record writer and the resolution policy all walk it every frame and none of them should pay
+     * for a copy.
+     *
+     * Mutate it only through this class, or the light index silently stops matching it.
+     * @returns {Shadowmap[]}
+     */
+    get maps(): Shadowmap[];
+    /**
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * @param {Light} light
+     * @returns {Shadowmap|undefined}
+     */
+    get(light: Light): Shadowmap | undefined;
+    /**
+     * Open a reconciliation pass. Every map that should survive it must be handed to
+     * {@link mark_live} before {@link is_marked} is consulted.
+     */
+    begin_reconcile(): void;
+    /**
+     * Look up `light`'s map and, if it has one, mark it as belonging to a light that is still in
+     * the scene. The lookup and the liveness marking are the same operation on purpose — that is
+     * the whole point of the mark, and splitting them would put the hash probe back.
+     *
+     * @param {Light} light
+     * @returns {Shadowmap|undefined} undefined when the light has no map yet, i.e. it is new
+     */
+    mark_live(light: Light): Shadowmap | undefined;
+    /**
+     * @param {Shadowmap} map
+     * @returns {boolean} true when the map was marked during the current reconciliation pass
+     */
+    is_marked(map: Shadowmap): boolean;
+    /**
+     * @param {number} index
+     * @returns {Shadowmap}
+     */
+    get_at(index: number): Shadowmap;
+    /**
+     * Take ownership of a newly created map. Marked live immediately — a map created during a
+     * reconciliation pass must survive that same pass's reclamation.
+     *
+     * @param {Shadowmap} map with `light` already assigned
+     */
+    add(map: Shadowmap): void;
+    /**
+     * Drop the map at `index`. The caller is responsible for releasing its GPU-side resources
+     * first — this only unhooks it from the array and the index.
+     *
+     * Order of the remaining maps is preserved, because the per-type shadow ids assigned at the
+     * end of reconciliation are positional and the records they point at are re-published only
+     * when an id actually moves.
+     *
+     * @param {number} index
+     */
+    remove_at(index: number): void;
+    /**
+     * Drop every map. Same caveat as {@link remove_at} — GPU-side resources are the caller's to
+     * release before calling this.
+     */
+    clear(): void;
+    #private;
+}
+//# sourceMappingURL=ShadowmapRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShadowmapRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowmapRegistry.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAuBI;;;;;;;OAOG;IACH,wBAEC;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,mBAFa,YAAU,SAAS,CAI/B;IAED;;;OAGG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,yBAFa,YAAU,SAAS,CAU/B;IAED;;;OAGG;IACH,2BAFa,OAAO,CAInB;IAED;;;OAGG;IACH,cAHW,MAAM,aAKhB;IAED;;;;;OAKG;IACH,0BAMC;IAED;;;;;;;;;OASG;IACH,iBAFW,MAAM,QAOhB;IAED;;;OAGG;IACH,cAGC;;CACJ"}

package/src/shade/renderer/shadow/map/ShadowmapRegistry.js

@@ -0,0 +1,156 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * The set of shadowmaps a scene currently holds, indexed by the light each one belongs to.
+ *
+ * Exists to make {@link GPUSceneShadowmapContext.process_lights} cheap. That pass runs every
+ * frame for every scene, and its job is to answer two questions per element: "does this light
+ * already have a map" (once per light) and "is this map's light still in the scene" (once per
+ * map). Answering the first by scanning the map array made the pass O(lights x maps) — 148us per
+ * frame at 512 lights, 554us at 1024, against 24us and 57us with the index. See
+ * benchmark/reconcile.spec.js.
+ *
+ * The second question is answered by MARKING rather than by a per-frame `new Set(lights)`. A
+ * reconciliation stamps every light's map with the current pass's mark as it walks the light
+ * array; anything still carrying an older mark afterwards belongs to a light that has left. That
+ * folds the liveness check into the lookup that was happening anyway, so the pass builds no
+ * per-frame collection at all.
+ *
+ * Deliberately GPU-free — it owns array and index bookkeeping and nothing else. Allocating an
+ * atlas rect, creating views and cameras, and releasing them again all stay in
+ * {@link GPUSceneShadowmapContext}, which is what lets this be measured without a device.
+ *
+ * Invariant: a light has at most one map. {@link add} asserts it.
+ */
+export class ShadowmapRegistry {
+    /**
+     * @type {Shadowmap[]}
+     */
+    #maps = [];
+
+    /**
+     * @type {Map<Light, Shadowmap>}
+     */
+    #by_light = new Map();
+
+    /**
+     * Monotonically increasing reconciliation counter. Compared against
+     * {@link Shadowmap._reconcile_mark} to tell a map whose light is still in the scene from one
+     * whose light has left. Starts at 0 and is pre-incremented by {@link begin_reconcile}, so the
+     * first pass marks with 1 and a never-marked map (whose field is 0) reads as stale.
+     *
+     * Increments once per frame. A double stays exact to 2^53, which at 1000 frames per second is
+     * longer than the hardware will last, so there is no wraparound to handle.
+     * @type {number}
+     */
+    #mark = 0;
+
+    /**
+     * The live map array, in allocation order. Callers iterate this directly — the draw pass, the
+     * record writer and the resolution policy all walk it every frame and none of them should pay
+     * for a copy.
+     *
+     * Mutate it only through this class, or the light index silently stops matching it.
+     * @returns {Shadowmap[]}
+     */
+    get maps() {
+        return this.#maps;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get size() {
+        return this.#maps.length;
+    }
+
+    /**
+     * @param {Light} light
+     * @returns {Shadowmap|undefined}
+     */
+    get(light) {
+        return this.#by_light.get(light);
+    }
+
+    /**
+     * Open a reconciliation pass. Every map that should survive it must be handed to
+     * {@link mark_live} before {@link is_marked} is consulted.
+     */
+    begin_reconcile() {
+        this.#mark++;
+    }
+
+    /**
+     * Look up `light`'s map and, if it has one, mark it as belonging to a light that is still in
+     * the scene. The lookup and the liveness marking are the same operation on purpose — that is
+     * the whole point of the mark, and splitting them would put the hash probe back.
+     *
+     * @param {Light} light
+     * @returns {Shadowmap|undefined} undefined when the light has no map yet, i.e. it is new
+     */
+    mark_live(light) {
+        const map = this.#by_light.get(light);
+
+        if (map !== undefined) {
+            map._reconcile_mark = this.#mark;
+        }
+
+        return map;
+    }
+
+    /**
+     * @param {Shadowmap} map
+     * @returns {boolean} true when the map was marked during the current reconciliation pass
+     */
+    is_marked(map) {
+        return map._reconcile_mark === this.#mark;
+    }
+
+    /**
+     * @param {number} index
+     * @returns {Shadowmap}
+     */
+    get_at(index) {
+        return this.#maps[index];
+    }
+
+    /**
+     * Take ownership of a newly created map. Marked live immediately — a map created during a
+     * reconciliation pass must survive that same pass's reclamation.
+     *
+     * @param {Shadowmap} map with `light` already assigned
+     */
+    add(map) {
+        assert.equal(this.#by_light.has(map.light), false, 'light already has a shadowmap');
+
+        map._reconcile_mark = this.#mark;
+        this.#maps.push(map);
+        this.#by_light.set(map.light, map);
+    }
+
+    /**
+     * Drop the map at `index`. The caller is responsible for releasing its GPU-side resources
+     * first — this only unhooks it from the array and the index.
+     *
+     * Order of the remaining maps is preserved, because the per-type shadow ids assigned at the
+     * end of reconciliation are positional and the records they point at are re-published only
+     * when an id actually moves.
+     *
+     * @param {number} index
+     */
+    remove_at(index) {
+        const map = this.#maps[index];
+
+        this.#by_light.delete(map.light);
+        this.#maps.splice(index, 1);
+    }
+
+    /**
+     * Drop every map. Same caveat as {@link remove_at} — GPU-side resources are the caller's to
+     * release before calling this.
+     */
+    clear() {
+        this.#maps.length = 0;
+        this.#by_light.clear();
+    }
+}

package/src/engine/graphics/ecs/highlight/plugin/HighlightRenderElementSource.d.ts

@@ -1,9 +0,0 @@
-export class HighlightRenderElementSource {
-    /**
-     *
-     * @param {ObjectPoolFactory<HighlightRenderElement>} pool
-     * @param {HighlightRenderGroup} group
-     */
-    collect(pool: ObjectPoolFactory<HighlightRenderElement>, group: HighlightRenderGroup): void;
-}
-//# sourceMappingURL=HighlightRenderElementSource.d.ts.map

package/src/engine/graphics/ecs/highlight/plugin/HighlightRenderElementSource.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"HighlightRenderElementSource.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/highlight/plugin/HighlightRenderElementSource.js"],"names":[],"mappings":"AAAA;IAGI;;;;OAIG;IACH,4FAEC;CACJ"}

package/src/engine/graphics/ecs/highlight/plugin/HighlightRenderElementSource.js

@@ -1,12 +0,0 @@
-export class HighlightRenderElementSource {
-
-
-    /**
-     *
-     * @param {ObjectPoolFactory<HighlightRenderElement>} pool
-     * @param {HighlightRenderGroup} group
-     */
-    collect(pool, group) {
-
-    }
-}

package/src/engine/graphics/ecs/highlight/renderer/HighlightRenderElement.d.ts

@@ -1,16 +0,0 @@
-export class HighlightRenderElement {
-    /**
-     *
-     * @type {Object3D}
-     */
-    object: Object3D;
-    /**
-     * TODO some definitions may be merged, such as those with the same {@link HighlightDefinition.thickness}, this would allow for less work in the shader
-     * @type {HighlightDefinition[]}
-     */
-    definitions: HighlightDefinition[];
-    merged: HighlightDefinition;
-    merge(): void;
-}
-import { HighlightDefinition } from "../HighlightDefinition.js";
-//# sourceMappingURL=HighlightRenderElement.d.ts.map

package/src/engine/graphics/ecs/highlight/renderer/HighlightRenderElement.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"HighlightRenderElement.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/highlight/renderer/HighlightRenderElement.js"],"names":[],"mappings":"AAGA;IACI;;;OAGG;IACH,iBAAc;IAEd;;;OAGG;IACH,aAFU,mBAAmB,EAAE,CAEd;IAEjB,4BAAmC;IAEnC,cAwBC;CACJ;oCA1CmC,2BAA2B"}

package/src/engine/graphics/ecs/highlight/renderer/HighlightRenderElement.js

@@ -1,44 +0,0 @@
-import { lerp } from "../../../../../core/math/lerp.js";
-import { HighlightDefinition } from "../HighlightDefinition.js";
-
-export class HighlightRenderElement {
-    /**
-     *
-     * @type {Object3D}
-     */
-    object = null;
-
-    /**
-     * TODO some definitions may be merged, such as those with the same {@link HighlightDefinition.thickness}, this would allow for less work in the shader
-     * @type {HighlightDefinition[]}
-     */
-    definitions = [];
-
-    merged = new HighlightDefinition();
-
-    merge() {
-        const definitions = this.definitions;
-        const n = definitions.length;
-
-        let outputR = 0;
-        let outputG = 0;
-        let outputB = 0;
-        let outputA = 0;
-
-        for (let i = 0; i < n; i++) {
-            const definition = definitions[i];
-
-            const color = definition.color;
-            const opacity = definition.opacity;
-
-            outputR = lerp(outputR, color.r, opacity);
-            outputG = lerp(outputG, color.g, opacity);
-            outputB = lerp(outputB, color.b, opacity);
-
-            outputA = (outputA * (1 - opacity)) + opacity;
-        }
-
-        this.merged.color.setRGB(outputR, outputG, outputB);
-        this.merged.opacity = outputA;
-    }
-}