@woosh/meep-engine 3.13.0 → 3.14.0

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

@@ -1,1322 +1,1342 @@
-import { assert } from "../../../../core/assert.js";
-import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
-import { MaxRectanglesPacker } from "../../../../core/geom/packing/max-rect/MaxRectanglesPacker.js";
-import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
-import { CameraManager } from "../../camera/CameraManager.js";
-import { OrthographicCamera } from "../../camera/OrthographicCamera.js";
-import { PerspectiveCamera } from "../../camera/PerspectiveCamera.js";
-import { CullPolicy } from "../../rasterize/bucket/construct_primitive_state.js";
-import { graph_mesh_sphere_cull } from "../../rasterize/compute/graph_mesh_sphere_cull.js";
-import { execute_rasterization_jobs } from "../../rasterize/execute_rasterization_jobs.js";
-import {
-    shadow_rasterization_alpha_tested_pass_descriptor
-} from "../../rasterize/native/depth/shadow_rasterization_alpha_tested_pass_descriptor.js";
-import {
-    shadow_rasterization_pass_descriptor
-} from "../../rasterize/native/depth/shadow_rasterization_pass_descriptor.js";
-import { RasterizationJob, RasterizationPipelineType } from "../../rasterize/RasterizationJob.js";
-import { graph_rasterize_scene_fast_raw } from "../../rasterize/fast/graph_rasterize_scene_fast.js";
-import { graph_create_texture, graph_import_texture } from "../../shader/graph/graph_import_texture.js";
-import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
-import { RenderTarget } from "../../texture/RenderTarget.js";
-import { View } from "../../view/View.js";
-import { ViewManager } from "../../view/ViewManager.js";
-import { SHADOWMAP_CSM_CASCADE_COUNT } from "./csm/SHADOWMAP_CSM_CASCADE_COUNT.js";
-import { DirectionalLightShadowmap } from "./DirectionalLightShadowmap.js";
-import { POINT_SHADOW_CUBE_COLS, POINT_SHADOW_CUBE_ROWS } from "./POINT_SHADOW_CUBE_LAYOUT.js";
-import {
-    POINT_SHADOW_TETRA_COLS,
-    POINT_SHADOW_TETRA_FACE_COUNT,
-    POINT_SHADOW_TETRA_MAPPING_RESOLUTION_SCALE,
-    POINT_SHADOW_TETRA_ROWS,
-} from "./POINT_SHADOW_TETRAHEDRON_LAYOUT.js";
-import { PointLightShadowmap } from "./PointLightShadowmap.js";
-import {
-    shader_shadowmap_remap_cube_to_octahedral
-} from "./shader/shader_shadowmap_remap_cube_to_octahedral.js";
-import {
-    POINT_SHADOW_TETRA_REMAP_SETTINGS,
-    shader_shadowmap_remap_tetrahedron_to_octahedral
-} from "./shader/shader_shadowmap_remap_tetrahedron_to_octahedral.js";
-import { SHADOWMAP_ATLAS_BORDER } from "./SHADOWMAP_ATLAS_BORDER.js";
-import { TetrahedronPointLightShadowmap } from "./TetrahedronPointLightShadowmap.js";
-import { compute_light_projected_area_px, compute_shadowmap_update_score } from "./shadowmap_update_score.js";
-import { ShadowmapResolutionPolicy } from "./ShadowmapResolutionPolicy.js";
-import { SpotLightShadowmap } from "./SpotLightShadowmap.js";
-
-const DEFAULT_SHADOWMAP_ATLAS_RESOLUTION = 4096 * 2;
-
-/**
- * Resolution by cascade.
- * If the number of cascades is greater than the array length, the last resolution is used.
- * @type {number[]}
- */
-const DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION = [
-    1740, // first cascade
-    1440,
-];
-
-/**
- * Placeholder resolution for local-light shadowmaps (spot/point).
- * A proper implementation will project the light's bounding volume into screen space to derive this at runtime.
- * @type {number}
- */
-const DEFAULT_SHADOWMAP_LOCAL_RESOLUTION = 128;
-
-/**
- * Per-frame shadow refresh budget, measured in **views** (one cube face counts as one view,
- * one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
- * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
- * keeps the cost of the refresh step roughly proportional to how much work we're asking the
- * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
- * equivalent work to 6 spot lights.
- *
- * Directional lights are always refreshed unconditionally (they drive the whole scene) and
- * their view cost is charged against the budget, so they effectively reduce the pool available
- * for local lights that frame.
- *
- * Unused budget is carried over between frames when demand exceeds supply — see
- * {@link GPUSceneShadowmapContext.#budget_carry_over}. This lets a light that's too expensive
- * to fit in a single frame (e.g. a point needing 6 views when only 2 are free) eventually get
- * its turn without permanently starving other lights.
- * @type {number}
- */
-const SHADOWMAP_UPDATE_BUDGET = 8;
-
-/**
- * Shadows for a single scene
- */
-export class GPUSceneShadowmapContext {
-    atlas = new MaxRectanglesPacker(DEFAULT_SHADOWMAP_ATLAS_RESOLUTION, DEFAULT_SHADOWMAP_ATLAS_RESOLUTION);
-
-    /**
-     * Depth texture atlas used for shadowmaps.
-     * @type {GPUTextureContext}
-     */
-    texture;
-
-
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics;
-
-    /**
-     * Dedicated ViewManager for the cube/cascade/perspective shadow views this context
-     * creates and rasterizes into the atlas. Decoupled from the renderer-level ViewManager
-     * so the ownership chain stays self-contained — the shadow context creates the views,
-     * caches their GPU contexts, and disposes them with itself. The shared SceneManager
-     * lookup is short-circuited with a tiny object that always returns our owning
-     * GPUSceneContext (every shadow view here is for the same scene by construction).
-     * @type {ViewManager}
-     */
-    shadow_view_manager;
-
-    /**
-     * Internal CameraManager backing {@link shadow_view_manager}. Shadow cameras are
-     * created locally in {@link process_lights} and only referenced by this context, so
-     * they don't need to share the renderer-level CameraManager.
-     * @type {CameraManager}
-     */
-    #cameras;
-
-    /**
-     * @type {RenderTarget}
-     */
-    #render_target;
-
-
-    /**
-     *
-     * @type {Shadowmap[]}
-     */
-    #maps = [];
-
-    /**
-     * Master kill switch for shadows on this scene. Defaults true; the renderer sets it from
-     * its own `feature_shadows_enabled` flag before each frame's light update. When false,
-     * {@link process_lights} evicts all maps so the next light-record build clears
-     * CASTS_SHADOW_BIT on every light. {@link select_for_draw} and {@link draw} are still
-     * gated externally by the renderer; this flag exists to keep the GPU light records in
-     * sync with that gating without needing to thread the renderer's flag down further.
-     * @type {boolean}
-     */
-    enabled = true;
-
-    /**
-     * Selects the tetrahedral point-light shadow generator (4 face frusta) over the default
-     * cube generator (6 faces). The renderer pushes this from its
-     * `feature_tetrahedron_point_shadows` flag before each light update, alongside {@link enabled}.
-     *
-     * Only affects how a point light's shadow is GENERATED — both paths remap into the same
-     * octahedral atlas encoding, so the sampler is identical and this can be toggled at runtime.
-     * A flip is picked up in {@link process_lights}: existing point maps whose generator no longer
-     * matches this flag are evicted and rebuilt with the correct face count on the same pass.
-     * @type {boolean}
-     */
-    use_tetrahedron_point_shadows = false;
-
-    /**
-     * Frame index of the most recent {@link select_for_draw} call. Passed to {@link draw} via
-     * this field so we don't have to thread it through the call again — draw() stamps
-     * `map.last_updated_frame_index` with this value after each successful rasterization.
-     * @type {number}
-     */
-    #current_frame_index = -1;
-
-    /**
-     * View-budget surplus carried forward from prior frames. Accumulates whenever we had
-     * non-directional candidates that couldn't fit in the per-frame budget (i.e. a point light
-     * wanted 6 views but only 2 were free after directionals + earlier locals consumed their
-     * share). Resets to 0 on any frame where the full demand was satisfied, so the carryover
-     * doesn't grow unboundedly when the scene is quiet.
-     * @type {number}
-     */
-    #budget_carry_over = 0;
-
-    /**
-     * Adjusts per-map atlas footprints each frame based on projected on-screen area. Lazily
-     * tied to {@link atlas} in the constructor.
-     * @type {ShadowmapResolutionPolicy}
-     */
-    #resolution_policy;
-
-    /**
-     * Number of shadowmaps actually rasterized by the most recent {@link draw} call. Reset at
-     * the start of draw(), incremented once per map that went through the raster path. Exposed
-     * for debugging scheduling behaviour — a persistently oscillating value (e.g. 36/20/15
-     * repeating) indicates some maps are being invalidated every frame and forcing a redraw,
-     * which usually means the resolution policy or selector is churning.
-     * @type {number}
-     */
-    #debug_render_count = 0;
-
-    /**
-     * @returns {number} number of shadowmaps rasterized in the most recent draw pass
-     */
-    get debug_render_count() {
-        return this.#debug_render_count;
-    }
-
-    /**
-     * Most recently measured atlas occupancy (placed area / total area, including pending
-     * reservations), in [0, 1]. Forwards from the resolution policy. Useful for the debug
-     * overlay alongside {@link debug_drop_size_scale} — together they show whether the global
-     * shrink/grow feedback has converged or is still chasing the target band.
-     * @returns {number}
-     */
-    get debug_atlas_occupancy() {
-        return this.#resolution_policy.last_occupancy;
-    }
-
-    /**
-     * Current value of the global drop-size scale applied by the resolution policy. 1 means no
-     * shrink; values below 1 mean atlas pressure has trimmed every light's target size
-     * proportionally. Forwarded from the resolution policy for debug overlays.
-     * @returns {number}
-     */
-    get debug_drop_size_scale() {
-        return this.#resolution_policy.drop_size_scale;
-    }
-
-
-    /**
-     * Per-type counts of shadow records written to the GPU database in the previous
-     * {@link draw} pass. Used to identify trailing slots that must be zeroed when the
-     * map count for a given type shrinks (e.g. a shadow-casting light is removed),
-     * mirroring the bookkeeping in {@link GPULightCollection.#build}.
-     */
-    #prev_point_count = 0;
-    #prev_spot_count = 0;
-    #prev_directional_count = 0;
-
-    /**
-     * The Scene this context manages shadows for. Captured at construction so
-     * {@link process_lights} doesn't need it threaded back through every frame.
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * Owning light collection — gives us access to the GPU database where shadow
-     * records live and to the source LightCollection. Set in the constructor.
-     * @type {GPULightCollection}
-     */
-    #owner;
-
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     * @param {GPUSceneContext} scene_ctx the GPU-side context for the Scene we manage
-     *        shadows for. Used as the (single) destination of {@link shadow_view_manager}'s
-     *        scene lookup — every shadow view is for this scene, so the lookup short-circuits.
-     * @param {GPULightCollection} owner the parent light collection — gives us back-access
-     *        to the GPU database we publish records into during {@link draw}.
-     */
-    constructor(
-        graphics,
-        scene_ctx,
-        owner,
-    ) {
-        assert.defined(graphics, 'graphics');
-        assert.defined(scene_ctx, 'scene_ctx');
-        assert.equal(scene_ctx.isGPUSceneContext, true, 'scene_ctx.isGPUSceneContext !== true');
-        assert.defined(owner, 'owner');
-
-
-        const initial_atlas_resolution = Math.min(
-            graphics.device.limits.maxTextureDimension2D,
-            DEFAULT_SHADOWMAP_ATLAS_RESOLUTION,
-        );
-
-        {
-            const t = this.texture = new GPUTextureContext(graphics.device);
-
-
-            const descriptor = t.descriptor;
-
-            descriptor.format = "depth32float";
-            descriptor.dimension = "2d";
-            descriptor.label = "Shadowmap atlas";
-            descriptor.usage = GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC;
-
-            t.resize(
-                initial_atlas_resolution,
-                initial_atlas_resolution
-            );
-
-            // ensure atlas size matches
-            this.atlas.resize(
-                initial_atlas_resolution,
-                initial_atlas_resolution
-            );
-        }
-
-        this.#graphics = graphics;
-        this.#scene = scene_ctx.scene;
-        this.#owner = owner;
-
-        // Local CameraManager + ViewManager dedicated to shadow rasterization. We don't
-        // share with the renderer-level managers because the cameras and views here are
-        // owned by this context and only referenced from inside it. The "scenes" lookup
-        // is a stub that always returns the owning scene context — every shadow view is
-        // for `this.#scene` by construction.
-        this.#cameras = new CameraManager(graphics.device);
-        this.shadow_view_manager = new ViewManager(graphics, this.#cameras, {
-            obtain: () => scene_ctx,
-        });
-
-        this.#render_target = RenderTarget.from({
-            depth: this.texture,
-        });
-
-        this.#resolution_policy = new ShadowmapResolutionPolicy(this.atlas);
-    }
-
-    /**
-     *
-     * @param {Light} light
-     * @returns {Shadowmap|undefined}
-     */
-    get_map(light) {
-        return this.#maps.find(map => map.light === light);
-    }
-
-    /**
-     * Decide which shadowmaps should be rasterized this frame.
-     *
-     * 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.
-     *  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.
-     *  3. **Reserve pending atlas footprints.** {@link ShadowmapResolutionPolicy.adjust} may
-     *     attach a `pending_layout` to maps whose projected area has shifted enough to warrant a
-     *     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:
-     *        - **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
-     *          has never held valid depth (freshly created map); sampling it would display
-     *          garbage, so we bypass the budget. Resizes no longer invalidate under the dual-
-     *          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.
-     *
-     * 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.
-     *
-     * @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()`
-     * @param {GPUSceneContext} scene
-     * @param {number} frame_index monotonically increasing frame counter, used for staleness
-     * @param {ArrayLike<number>} view_resolution [width, height] of the main view in pixels; used
-     *        to convert projected sphere extents into a pixel-area score
-     */
-    select_for_draw(main_camera, scene, frame_index, view_resolution) {
-        assert.defined(main_camera, 'main_camera');
-        assert.isObject(main_camera, 'main_camera');
-        assert.equal(scene.isGPUSceneContext, true, 'scene.isGPUSceneContext !== true');
-        assert.isNumber(frame_index, 'frame_index');
-        assert.defined(view_resolution, 'view_resolution');
-
-        // make sure the camera is updated — both our scoring (projected area) and any downstream
-        // map.update() reads depend on view/projection matrices being current
-        main_camera.update();
-
-        this.#current_frame_index = frame_index;
-
-        const shadowmaps = this.#maps;
-        const n = shadowmaps.length;
-
-        // Step 1: clear per-frame flags so a stale signal from a prior frame can't fire now.
-        for (let i = 0; i < n; i++) {
-            shadowmaps[i].should_draw = false;
-        }
-
-        // Step 2: recompute projected areas. Writing onto the map so the policy + scorer can
-        // just read `map.projected_area_px` without threading a parallel array through.
-        for (let i = 0; i < n; i++) {
-            const m = shadowmaps[i];
-            m.projected_area_px = compute_light_projected_area_px(m.light, main_camera, view_resolution);
-        }
-
-        // Step 3: policy reserves pending resize footprints alongside committed layouts. It
-        // never mutates layout and never invalidates — sampling continues against the old
-        // region until draw() commits the pending during a normal raster pass. Directionals and
-        // off-screen locals are skipped (off-screen locals also get any stale pending released
-        // so an idle reservation can't tie up atlas space).
-        this.#resolution_policy.adjust(shadowmaps, frame_index);
-
-        // Step 4: score every map. Directionals return Infinity; off-screen locals return 0.
-        const scored = new Array(n);
-        for (let i = 0; i < n; i++) {
-            scored[i] = {
-                map: shadowmaps[i],
-                score: compute_shadowmap_update_score(shadowmaps[i], frame_index),
-            };
-        }
-        scored.sort((a, b) => b.score - a.score);
-
-        // Step 5: greedy-fill the view-budget in score order.
-        const budget_total = SHADOWMAP_UPDATE_BUDGET + this.#budget_carry_over;
-        let views_spent = 0;
-        let had_unfit_candidates = false;
-
-        for (let i = 0; i < n; i++) {
-            const map = scored[i].map;
-            const cost = map.views.length;
-            const light = map.light;
-
-            if (light.isDirectionalLight) {
-                // Phase A: directionals always refresh. Infinite score puts them at the front of
-                // the sorted list; their view cost still counts against the pool, so local lights
-                // see a reduced budget this frame.
-                map.should_draw = true;
-                map.update(main_camera, scene);
-                views_spent += cost;
-                continue;
-            }
-
-            // Phase B: local lights (spot/point).
-            if (map.projected_area_px <= 0) {
-                // Off-screen. Not demand, not carryover fuel. Leave is_invalid / should_draw
-                // alone so the map springs back to life the moment it returns to view.
-                continue;
-            }
-
-            if (map.is_invalid) {
-                // Phase B-override: invalid + in-view is a MUST-draw. Sampling garbage depth on
-                // a visible light would be user-visible corruption, so we bypass the budget.
-                // The view cost still counts so normal-priority locals see the deficit.
-                map.should_draw = true;
-                map.update(main_camera, scene);
-                views_spent += cost;
-                continue;
-            }
-
-            // Phase B normal: score-ordered greedy fill.
-            if (views_spent + cost <= budget_total) {
-                map.should_draw = true;
-                map.update(main_camera, scene);
-                views_spent += cost;
-            } else {
-                // wanted to refresh but the pool couldn't cover its view cost; flag so we carry
-                // unused budget forward for next frame's attempt
-                had_unfit_candidates = true;
-            }
-            // Skipped maps keep their prior metadata + atlas contents — a never-refreshed map
-            // samples the initial depth-cleared rect, which reads as "fully lit" under the
-            // reverse-Z greater compare. Acceptable behavior until the map eventually wins a slot.
-        }
-
-        // Carry over the unused pool only when there was demand we couldn't meet. When the whole
-        // scene's demand was satisfied, reset to 0 so idle frames don't inflate the pool. If
-        // must-draw bypasses over-spent the pool (views_spent > budget_total), clamp at zero —
-        // we can't owe future frames for past over-spend, that way lies runaway starvation.
-        if (had_unfit_candidates) {
-            this.#budget_carry_over = Math.max(0, budget_total - views_spent);
-        } else {
-            this.#budget_carry_over = 0;
-        }
-    }
-
-    /**
-     * Publish per-shadowmap records into the scene's GPU database. Each map writes its record
-     * into the type-specific shadow_* table at the slot identified by `light._gpu_shadowmap_id`
-     * (which is itself the per-type index, set by {@link process_lights}). Trailing slots from
-     * previous frames are zeroed when the map count for a type shrinks, so stale entries don't
-     * linger.
-     *
-     * Only maps with `metadata_changed === true` are re-uploaded; the flag is cleared after
-     * the slot is queued so unchanged maps don't pay for an upload they don't need. Trim writes
-     * always run regardless of the flag — they zero slots that no longer correspond to any map.
-     *
-     * The type-bucket order here MUST match the per-type id assignment in {@link process_lights}
-     * (Point → Spot → Directional) so the shadow_id stamped onto each light record points at the
-     * slot we write here.
-     *
-     * Caller must invoke `database.update(cmd)` afterwards to upload the writes — that is done
-     * by {@link draw} once for both the new records and any zeroed trailing slots.
-     *
-     * @param {GPUDatabase} database
-     */
-    #write_shadow_records(database) {
-        const t_point = database.get('shadow_point');
-        const t_spot = database.get('shadow_spot');
-        const t_directional = database.get('shadow_directional');
-
-        const maps = this.#maps;
-        let pc = 0;
-        let sc = 0;
-        let dc = 0;
-
-        for (let i = 0; i < maps.length; i++) {
-            const map = maps[i];
-            const light = map.light;
-
-            let table;
-            let slot;
-            if (light.isPointLight) {
-                table = t_point;
-                slot = pc++;
-            } else if (light.isSpotLight) {
-                table = t_spot;
-                slot = sc++;
-            } else if (light.isDirectionalLight) {
-                table = t_directional;
-                slot = dc++;
-            } else {
-                continue;
-            }
-
-            if (map.metadata_changed) {
-                table.set(slot, map.make_record());
-                map.metadata_changed = false;
-            }
-        }
-
-        // trim trailing slots from previous frames so disused entries don't leak
-        for (let i = pc; i < this.#prev_point_count; i++) {
-            t_point.remove(i);
-        }
-        for (let i = sc; i < this.#prev_spot_count; i++) {
-            t_spot.remove(i);
-        }
-        for (let i = dc; i < this.#prev_directional_count; i++) {
-            t_directional.remove(i);
-        }
-
-        this.#prev_point_count = pc;
-        this.#prev_spot_count = sc;
-        this.#prev_directional_count = dc;
-    }
-
-    /**
-     * Rasterize every shadowmap flagged by {@link select_for_draw} for a refresh this frame,
-     * committing any pending resize reservations in the process, then publish per-shadow
-     * metadata into the scene's GPU database.
-     *
-     * For each map with `should_draw` set:
-     *
-     *   1. If the map has a {@link Shadowmap.pending_layout} reservation, swap it into place
-     *      BEFORE rasterization so the draw targets the new region. The old committed rects
-     *      are remembered for step 3.
-     *   2. Dispatch to the type-specific raster path:
-     *        - **Directional / spot**: direct raster into the atlas's sub-rects (one job per
-     *          cascade for directionals, one job per spot).
-     *        - **Point**: 6 cube-face depth passes into a shared intermediate texture, then
-     *          cube→octahedral remap into the atlas. Point lights are serialised so they can
-     *          reuse the intermediate texture.
-     *   3. If a commit happened in step 1, release the old committed rects from the atlas now
-     *      that the new region holds valid depth.
-     *   4. Clear per-frame flags (`should_draw`, `is_invalid`) and stamp
-     *      `last_updated_frame_index` with the current frame.
-     *
-     * After the loop, each map's metadata record is written into the corresponding
-     * `shadow_point` / `shadow_spot` / `shadow_directional` table on the owning light
-     * collection's database, then the database is uploaded — this is where the committed
-     * swaps become visible to the lighting shader. `#debug_render_count` is reset at entry
-     * and incremented per map to expose scheduling behaviour to the debug overlay.
-     *
-     * No external job list: every path batches its own work internally via
-     * {@link execute_rasterization_jobs}. Callers just pass a command context.
-     *
-     * @param {ShadeGPUCommandContext} command_ctx
-     */
-    draw(command_ctx) {
-        assert.defined(command_ctx, 'command_ctx');
-
-
-        this.#debug_render_count = 0;
-
-        const frame_index = this.#current_frame_index;
-        const maps = this.#maps;
-
-        for (let i = 0; i < maps.length; i++) {
-            const map = maps[i];
-            if (!map.should_draw) {
-                continue;
-            }
-
-            // Step 1: commit any pending-layout reservation before rasterizing. The draw helpers
-            // read `map.layout` directly, so swapping here makes the raster target the new
-            // region. We stash the old rect(s) locally for step 3's atlas release — once the
-            // raster commands are enqueued, the old region's contents will no longer be sampled
-            // (the next shadow-record write publishes the new layout), so returning that atlas
-            // space to the packer is safe.
-            let retired_rects = null;
-            if (map.pending_layout !== null) {
-                retired_rects = map.layout;
-                map.layout = map.pending_layout;
-                map.pending_layout = null;
-                map.metadata_changed = true;
-            }
-
-            const light = map.light;
-
-            if (light.isDirectionalLight || light.isSpotLight) {
-                this.#draw_direct(map, command_ctx);
-            } else if (light.isPointLight) {
-                if (map.isTetrahedron) {
-                    this.#draw_point_tetrahedron(map, command_ctx);
-                } else {
-                    this.#draw_point(map, command_ctx);
-                }
-            } else {
-                throw new Error(`Unsupported light type ${light.constructor.name}`);
-            }
-
-            // Step 3: release the retired rects from the atlas. Must happen AFTER the raster
-            // helpers finish reading map.layout (they may close over retired_rects as scratch
-            // memory or view references in some paths; safest order is raster-first).
-            if (retired_rects !== null) {
-                for (let j = 0; j < retired_rects.length; j++) {
-                    this.atlas.remove(retired_rects[j]);
-                }
-            }
-
-            // Step 4: atlas contents are now current. Clear per-frame flags and stamp the frame
-            // index so the next frame's scorer computes staleness correctly.
-            map.should_draw = false;
-            map.is_invalid = false;
-            map.last_updated_frame_index = frame_index;
-            this.#debug_render_count++;
-        }
-
-
-        // Publish metadata AFTER all commits so the lighting shader sees atlas coordinates that
-        // match the regions we just rasterised into. Never-drawn maps carry stale-but-valid
-        // projection + layout; off-screen maps and skipped candidates publish their prior state.
-        const database = this.#owner.database;
-        this.#write_shadow_records(database);
-        database.update(command_ctx);
-
-
-        // finalize rendered views
-        for (const map of this.#maps) {
-            if (map.last_updated_frame_index !== frame_index) {
-                // skip
-                continue;
-            }
-
-            for (const view of map.views) {
-                const view_ctx = this.shadow_view_manager.obtain(view);
-                view_ctx.finish_frame(command_ctx);
-            }
-        }
-    }
-
-    /**
-     * Rasterize a directional or spot shadowmap directly into its atlas rects. One job per
-     * `map.views[i]` / `map.layout[i]` pair — directionals have N cascades, spots have one.
-     *
-     * @param {Shadowmap} map
-     * @param {ShadeGPUCommandContext} command_ctx
-     */
-    #draw_direct(map, command_ctx) {
-        // TODO pre-cull mesh set by sphere-casting the light volume against the main View Frustum
-        //      see ref: https://www.reddit.com/r/Unity3D/comments/1foe8qi/added_a_way_to_perform_frustum_culling_and_take
-
-        const graph = new FrameGraph("shadows");
-
-        const shadow_views = map.views;
-        const jobs = new Array(shadow_views.length);
-
-        for (let i = 0; i < shadow_views.length; i++) {
-            const view = shadow_views[i];
-            const view_ctx = this.shadow_view_manager.obtain(view);
-
-            view_ctx.update(this.#graphics);
-
-            const atlas_aabb = map.layout[i];
-            view_ctx.setViewportSize(atlas_aabb.width, atlas_aabb.height);
-
-            const job = new RasterizationJob();
-            job.opaque_pass = shadow_rasterization_pass_descriptor;
-            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
-            job.cull_policy = CullPolicy.Reversed;
-            job.render_target = this.#render_target;
-            job.view_ctx = view_ctx;
-            job.viewport = [atlas_aabb.x0, atlas_aabb.y0, atlas_aabb.width, atlas_aabb.height];
-
-
-            jobs[i] = job;
-
-            // TODO reproject current scene view into shadow map for better occlusion culling,
-            //  see Assassin's Creed Unity talk on GPU-driven rendering,
-            //  see "RE ENGINE Meshlet Rendering Pipeline" https://youtu.be/nWgPtCDXlPc?t=2055
-
-            // TODO need to linearize depth(?)
-            // can linearize together with reprojection (TAA)
-        }
-
-        execute_rasterization_jobs({
-            jobs,
-            limits: this.#graphics.collection_limits,
-            command_ctx,
-            graph,
-        });
-
-        command_ctx.encodeGraph(graph);
-    }
-
-    /**
-     * Rasterize a point light's 6 cube faces into the shared intermediate texture, then run the
-     * cube→octahedral remap shader to write the encoded depth into this light's atlas rect.
-     *
-     * Sequencing matters: each point light fully completes (6 cube rasters + remap) before the
-     * next one starts, so the intermediate texture can be reused across point lights without
-     * cross-contamination.
-     *
-     * @param {PointLightShadowmap} map
-     * @param {ShadeGPUCommandContext} command_ctx
-     */
-    #draw_point(
-        map,
-        command_ctx,
-    ) {
-
-        const graph = new FrameGraph("shadows");
-
-        const gr_atlas_texture = graph_import_texture(graph, this.texture);
-
-        const atlas_rect = map.layout[0];
-
-        const octahedral_resolution = atlas_rect.width;
-
-        /**
-         * Controls the relationship between octahedral resolution and the cube map used during rendering
-         * If this is larger - we get better quality at the cost of rendering more pixels.
-         *
-         * Solving for solid angle coverage, using the formula `N=POW(1 - SQRT(E/3), 3/2)` we get:
-         *
-         * 0% error -> 1
-         * 1% error -> 0.915
-         * 5% error -> 0.81299
-         * 10% error -> 0.739
-         * 20% error -> 0.639
-         * 30% error -> 0.565
-         * 40% error -> 0.506
-         * 50% error -> 0.455
-         *
-         * @type {number}
-         */
-        const CUBE_MAPPING_RESOLUTION_SCALE = 1;
-
-        const cube_face_resolution = Math.ceil(octahedral_resolution * CUBE_MAPPING_RESOLUTION_SCALE);
-
-        // reserve texture
-        let cube_packed_texture = graph_create_texture(graph, TextureResourceDescriptor.from({
-            resolution: [
-                cube_face_resolution * POINT_SHADOW_CUBE_COLS,
-                cube_face_resolution * POINT_SHADOW_CUBE_ROWS,
-            ],
-            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-            format: 'depth32float',
-            enableMips: false,
-        }));
-
-        /**
-         *
-         * @type {PointLight}
-         */
-        const light = map.light;
-
-        const scene_ctx = this.shadow_view_manager.obtain(map.views[0]).scene;
-
-        /**
-         * Sphere-culled meshes from the scene.
-         * We could do per-face culling, but most point lights are local, and there's already meshlet culling happening later in the pipeline.
-         * Good enough.
-         * @type {number}
-         */
-        const input_meshes = graph_mesh_sphere_cull({
-            graph,
-            sphere: [...light.position, light.distance],
-            scene: scene_ctx,
-            limits: this.#graphics.collection_limits,
-        });
-
-        for (let face = 0; face < 6; face++) {
-            const view = map.views[face];
-            const view_ctx = this.shadow_view_manager.obtain(view);
-
-            view_ctx.update(this.#graphics);
-            view_ctx.setViewportSize(cube_face_resolution, cube_face_resolution);
-
-            const col = face % POINT_SHADOW_CUBE_COLS;
-            const row = Math.floor(face / POINT_SHADOW_CUBE_COLS);
-
-            const job = new RasterizationJob();
-
-            job.pipeline_type = RasterizationPipelineType.Fast;
-            job.opaque_pass = shadow_rasterization_pass_descriptor;
-            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
-            job.cull_policy = CullPolicy.Reversed;
-            job.render_target = null;
-            job.view_ctx = view_ctx;
-            job.viewport = [
-                col * cube_face_resolution,
-                row * cube_face_resolution,
-                cube_face_resolution,
-                cube_face_resolution,
-            ];
-
-            cube_packed_texture = graph_rasterize_scene_fast_raw({
-                graph,
-                meshes: input_meshes,
-                limits: this.#graphics.collection_limits,
-                target_depth: cube_packed_texture,
-                job,
-            }).target_depth;
-        }
-
-        /**
-         *
-         * @param data
-         * @param {FramePassResources} resources
-         * @param {GraphicsExecutionContext} context
-         */
-        function remap_to_atlas(data, resources, context) {
-            const atlas = resources.get(data.atlas);
-            const cube_texture = resources.get(data.cube_texture);
-
-            const settings = {
-                atlas_offset: [
-                    atlas_rect.x0 + SHADOWMAP_ATLAS_BORDER,
-                    atlas_rect.y0 + SHADOWMAP_ATLAS_BORDER,
-                    atlas_rect.width - 2 * SHADOWMAP_ATLAS_BORDER,
-                    atlas_rect.height - 2 * SHADOWMAP_ATLAS_BORDER,
-                ],
-                light_params: [
-                    map.light.distance,
-                    map.cube_near,
-                    0,
-                    0,
-                ]
-            };
-
-            shader_shadowmap_remap_cube_to_octahedral.draw({
-                encoder: context.encoder,
-                bindings: {
-                    settings: settings,
-                    cube_faces: cube_texture.obtainView(),
-                },
-                depthStencilAttachment: {
-                    view: atlas.obtainView(),
-                    depthLoadOp: "load",
-                    depthStoreOp: "store",
-                },
-                viewport: [
-                    atlas_rect.x0,
-                    atlas_rect.y0,
-                    atlas_rect.width,
-                    atlas_rect.height,
-                ]
-            })
-        }
-
-        const remap_data = {};
-
-        const remap_pass = graph.add("remap to atals", remap_data, remap_to_atlas);
-
-        remap_data.atlas = remap_pass.write(gr_atlas_texture);
-        remap_data.cube_texture = remap_pass.read(cube_packed_texture);
-
-
-        command_ctx.encodeGraph(graph);
-    }
-
-    /**
-     * Rasterize a point light's 4 tetrahedron faces into a shared intermediate texture, then run
-     * the tetrahedron→octahedral remap to write the encoded depth into this light's atlas rect.
-     * The tetrahedral parallel to {@link #draw_point} — same shape, 4 faces in a 2x2 grid instead
-     * of 6 in a 3x2 grid, and the remap is handed each face's view-projection matrix so it can
-     * select faces and project directions in exact agreement with how the depth was rasterized.
-     *
-     * @param {TetrahedronPointLightShadowmap} map
-     * @param {ShadeGPUCommandContext} command_ctx
-     */
-    #draw_point_tetrahedron(
-        map,
-        command_ctx,
-    ) {
-
-        const graph = new FrameGraph("shadows");
-
-        const gr_atlas_texture = graph_import_texture(graph, this.texture);
-
-        const atlas_rect = map.layout[0];
-
-        const octahedral_resolution = atlas_rect.width;
-
-        // Wider face fov than the cube path (see POINT_SHADOW_TETRA_FOV_DEGREES) needs a larger
-        // per-face resolution to hold comparable on-axis density — the analogue of the cube
-        // path's CUBE_MAPPING_RESOLUTION_SCALE.
-        const face_resolution = Math.ceil(octahedral_resolution * POINT_SHADOW_TETRA_MAPPING_RESOLUTION_SCALE);
-
-        // reserve intermediate depth texture — 2x2 grid of faces
-        let tetra_packed_texture = graph_create_texture(graph, TextureResourceDescriptor.from({
-            resolution: [
-                face_resolution * POINT_SHADOW_TETRA_COLS,
-                face_resolution * POINT_SHADOW_TETRA_ROWS,
-            ],
-            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-            format: 'depth32float',
-            enableMips: false,
-        }));
-
-        /**
-         *
-         * @type {PointLight}
-         */
-        const light = map.light;
-
-        const scene_ctx = this.shadow_view_manager.obtain(map.views[0]).scene;
-
-        // One sphere cull for all 4 faces — most point lights are local and meshlet culling
-        // refines later; per-face culling isn't worth it. Same trade as the cube path.
-        const input_meshes = graph_mesh_sphere_cull({
-            graph,
-            sphere: [...light.position, light.distance],
-            scene: scene_ctx,
-            limits: this.#graphics.collection_limits,
-        });
-
-        for (let face = 0; face < POINT_SHADOW_TETRA_FACE_COUNT; face++) {
-            const view = map.views[face];
-            const view_ctx = this.shadow_view_manager.obtain(view);
-
-            view_ctx.update(this.#graphics);
-            view_ctx.setViewportSize(face_resolution, face_resolution);
-
-            const col = face % POINT_SHADOW_TETRA_COLS;
-            const row = Math.floor(face / POINT_SHADOW_TETRA_COLS);
-
-            const job = new RasterizationJob();
-
-            job.pipeline_type = RasterizationPipelineType.Fast;
-            job.opaque_pass = shadow_rasterization_pass_descriptor;
-            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
-            job.cull_policy = CullPolicy.Reversed;
-            job.render_target = null;
-            job.view_ctx = view_ctx;
-            job.viewport = [
-                col * face_resolution,
-                row * face_resolution,
-                face_resolution,
-                face_resolution,
-            ];
-
-            tetra_packed_texture = graph_rasterize_scene_fast_raw({
-                graph,
-                meshes: input_meshes,
-                limits: this.#graphics.collection_limits,
-                target_depth: tetra_packed_texture,
-                job,
-            }).target_depth;
-        }
-
-        const views = map.views;
-        const tetra_near = map.tetra_near;
-        const light_max_distance = map.light.distance;
-
-        /**
-         *
-         * @param data
-         * @param {FramePassResources} resources
-         * @param {GraphicsExecutionContext} context
-         */
-        function remap_to_atlas(data, resources, context) {
-            const atlas = resources.get(data.atlas);
-            const tetra_texture = resources.get(data.tetra_texture);
-
-            // Read each face camera's view-projection at encode time — set in map.update() and
-            // untouched since, and it is exactly the matrix the rasterizer used above.
-            const face_view_proj = new Array(POINT_SHADOW_TETRA_FACE_COUNT);
-            for (let f = 0; f < POINT_SHADOW_TETRA_FACE_COUNT; f++) {
-                face_view_proj[f] = views[f].camera.view_projection_matrix;
-            }
-
-            const settings = context.encoder.allocateTransientValueBuffer(
-                POINT_SHADOW_TETRA_REMAP_SETTINGS,
-                {
-                    atlas_offset: [
-                        atlas_rect.x0 + SHADOWMAP_ATLAS_BORDER,
-                        atlas_rect.y0 + SHADOWMAP_ATLAS_BORDER,
-                        atlas_rect.width - 2 * SHADOWMAP_ATLAS_BORDER,
-                        atlas_rect.height - 2 * SHADOWMAP_ATLAS_BORDER,
-                    ],
-                    light_params: [
-                        light_max_distance,
-                        tetra_near,
-                        0,
-                        0,
-                    ],
-                    face_view_proj,
-                }
-            );
-
-            shader_shadowmap_remap_tetrahedron_to_octahedral.draw({
-                encoder: context.encoder,
-                bindings: {
-                    settings: settings,
-                    tetra_faces: tetra_texture.obtainView(),
-                },
-                depthStencilAttachment: {
-                    view: atlas.obtainView(),
-                    depthLoadOp: "load",
-                    depthStoreOp: "store",
-                },
-                viewport: [
-                    atlas_rect.x0,
-                    atlas_rect.y0,
-                    atlas_rect.width,
-                    atlas_rect.height,
-                ]
-            })
-        }
-
-        const remap_data = {};
-
-        const remap_pass = graph.add("remap tetra to atlas", remap_data, remap_to_atlas);
-
-        remap_data.atlas = remap_pass.write(gr_atlas_texture);
-        remap_data.tetra_texture = remap_pass.read(tetra_packed_texture);
-
-
-        command_ctx.encodeGraph(graph);
-    }
-
-    /**
-     * Release the per-face GPU contexts (each view's uniform/HZB/volumetrics buffers + its camera
-     * uniform) backing a map. The dedicated {@link shadow_view_manager} / {@link #cameras} caches
-     * key on the View/Camera objects and have no GC path, so a map's contexts must be released
-     * explicitly here or their GPU buffers leak for the context's lifetime. Most visible when the
-     * point-shadow generator toggle rebuilds every point map (fresh Views each time), but it also
-     * closes the ordinary eviction leak (light removed / stops casting / shadows disabled).
-     *
-     * In this context Views and Cameras are 1:1 per map (each map creates its own), so releasing a
-     * view's camera alongside it can't strand a still-referenced camera.
-     *
-     * @param {Shadowmap} map
-     */
-    #release_map_gpu_contexts(map) {
-        const views = map.views;
-        for (let j = 0; j < views.length; j++) {
-            const view = views[j];
-            this.shadow_view_manager.release(view);
-            this.#cameras.release(view.camera);
-        }
-    }
-
-    /**
-     * Release a map's atlas rects + GPU side-resources. Caller is responsible for splicing it
-     * out of {@link #maps}.
-     *
-     * @param {Shadowmap} map
-     */
-    #evict_map(map) {
-        for (let j = 0; j < map.layout.length; j++) {
-            this.atlas.remove(map.layout[j]);
-        }
-        if (map.pending_layout !== null) {
-            for (let j = 0; j < map.pending_layout.length; j++) {
-                this.atlas.remove(map.pending_layout[j]);
-            }
-            map.pending_layout = null;
-        }
-
-        // free the per-view/-camera GPU contexts — without this an evicted map's buffers leak
-        this.#release_map_gpu_contexts(map);
-
-        map.light._gpu_shadowmap_id = -1;
-    }
-
-    /**
-     * Reconcile shadow allocations against the current scene state. Evicts maps for lights
-     * that no longer cast shadows or have left the scene, allocates maps for new shadow-
-     * casting lights, and reassigns per-type `_gpu_shadowmap_id` when the map ordering
-     * shifts.
-     *
-     * Called from {@link GPULightCollection.update} every frame, including frames where
-     * {@link LightCollection.version} hasn't moved — `light.casts_shadow` flips are not
-     * tracked by version and are detected here.
-     *
-     * @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
-     *          have shifted).
-     */
-    process_lights() {
-        // When the renderer has shadows disabled, treat every map as evictable so the next
-        // build clears CASTS_SHADOW_BIT on every light. Re-enabling reconstructs everything
-        // from scratch on the following frame — that's a one-frame catch-up cost, considered
-        // an acceptable trade for the simpler invariant ("disabled" = no maps held).
-        if (!this.enabled) {
-            const had_maps = this.#maps.length > 0;
-            for (let i = this.#maps.length - 1; i >= 0; i--) {
-                this.#evict_map(this.#maps[i]);
-            }
-            this.#maps.length = 0;
-            return had_maps;
-        }
-
-        const scene = this.#scene;
-        const lights = scene.lights.elements;
-        let changed = false;
-
-        // Reclamation: drop maps whose lights left the scene or stopped casting shadows so a
-        // removed light's atlas rect doesn't stay pinned forever. Walk in reverse so splice
-        // indices stay stable.
-        const live_lights = new Set(lights);
-        for (let i = this.#maps.length - 1; i >= 0; i--) {
-            const map = this.#maps[i];
-            const light = map.light;
-
-            // A point map built by the other generator (cube vs tetra) must be rebuilt when the
-            // flag flips — its face count and draw path no longer match. Dropping it here lets
-            // add_light re-create it with the current generator later in this same pass.
-            const generator_mismatch = light.isPointLight
-                && Boolean(map.isTetrahedron) !== this.use_tetrahedron_point_shadows;
-
-            if (live_lights.has(light) && light.casts_shadow && !generator_mismatch) {
-                continue;
-            }
-            this.#evict_map(map);
-            this.#maps.splice(i, 1);
-            changed = true;
-        }
-
-        const add_directional = (light) => {
-            const map = new DirectionalLightShadowmap();
-            map.light = light;
-
-            const bound = [];
-            try {
-                for (let j = 0; j < SHADOWMAP_CSM_CASCADE_COUNT; j++) {
-                    const resolution_index = Math.min(j, DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION.length - 1);
-                    const resolution = DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION[resolution_index];
-
-                    const rect = this.bind(resolution);
-                    bound.push(rect);
-                    map.layout[j] = rect;
-
-                    const camera = new OrthographicCamera();
-                    camera.update();
-
-                    const view = new View(camera, scene);
-                    view.label = `Shadow Cascade ${j}`;
-
-                    map.views[j] = view;
-                }
-            } catch (e) {
-                // Partial bind: roll back any cascade rects already inserted so the atlas isn't
-                // left holding orphans for a map that never got pushed to #maps.
-                for (let j = 0; j < bound.length; j++) {
-                    this.atlas.remove(bound[j]);
-                }
-                throw e;
-            }
-
-            this.#maps.push(map);
-        };
-
-        const add_spot = (light) => {
-            const map = new SpotLightShadowmap();
-            map.light = light;
-
-            const rect = this.bind(DEFAULT_SHADOWMAP_LOCAL_RESOLUTION);
-            map.layout[0] = rect;
-
-            try {
-                const camera = new PerspectiveCamera();
-                camera.update();
-
-                const view = new View(camera, scene);
-                view.label = `Spot Shadow`;
-
-                map.views[0] = view;
-            } catch (e) {
-                this.atlas.remove(rect);
-                throw e;
-            }
-
-            this.#maps.push(map);
-        };
-
-        const add_point = (light) => {
-
-            // Generator chosen by the current flag; both remap into one octahedral slot, they
-            // only differ in how many face frusta feed that remap (tetra 4, cube 6).
-            const use_tetra = this.use_tetrahedron_point_shadows;
-
-            const map = use_tetra ? new TetrahedronPointLightShadowmap() : new PointLightShadowmap();
-            map.light = light;
-
-            // single atlas rect holds the octahedral-encoded depth for all faces
-            const rect = this.bind(DEFAULT_SHADOWMAP_LOCAL_RESOLUTION);
-            map.layout[0] = rect;
-
-            const face_count = use_tetra ? POINT_SHADOW_TETRA_FACE_COUNT : 6;
-
-            for (let j = 0; j < face_count; j++) {
-                const camera = new PerspectiveCamera();
-                camera.update();
-
-                const view = new View(camera, scene);
-                view.label = use_tetra ? `Point Shadow (tetra) face ${j}` : `Point Shadow face ${j}`;
-
-                map.views[j] = view;
-            }
-
-            this.#maps.push(map);
-        };
-
-        const add_light = (light) => {
-            if (!light.casts_shadow) {
-                return;
-            }
-
-            if (this.get_map(light) !== undefined) {
-                return;
-            }
-
-            if (light.isDirectionalLight) {
-                add_directional(light);
-                changed = true;
-            } else if (light.isSpotLight) {
-                add_spot(light);
-                changed = true;
-            } else if (light.isPointLight) {
-                add_point(light);
-                changed = true;
-            }
-        };
-
-        for (let i = 0; i < lights.length; i++) {
-            const light = lights[i];
-
-            try {
-                add_light(light);
-            } catch (e) {
-                console.error(e);
-            }
-        }
-
-        // Publish per-type shadowmap ids back onto the lights. Each shadow_* table is indexed
-        // independently, so a point light's shadow_id points into shadow_point, a spot's into
-        // shadow_spot, etc. Type-bucket order MUST match {@link #write_shadow_records} so each
-        // light record's stored shadow_id lines up with the slot we'll write into the table.
-        // When a map's slot index actually changes (eviction shifted neighbours up the array),
-        // mark its record dirty so the next #write_shadow_records re-publishes it into the new
-        // slot, and report `changed` so the caller re-publishes the light records too.
-        let pc = 0;
-        let sc = 0;
-        let dc = 0;
-        for (let i = 0; i < this.#maps.length; i++) {
-            const map = this.#maps[i];
-            const light = map.light;
-
-            let new_id;
-            if (light.isPointLight) {
-                new_id = pc++;
-            } else if (light.isSpotLight) {
-                new_id = sc++;
-            } else if (light.isDirectionalLight) {
-                new_id = dc++;
-            } else {
-                continue;
-            }
-
-            if (light._gpu_shadowmap_id !== new_id) {
-                light._gpu_shadowmap_id = new_id;
-                map.metadata_changed = true;
-                changed = true;
-            }
-        }
-
-        return changed;
-    }
-
-    /**
-     *
-     * @param {number} resolution
-     * @returns {AABB2}
-     */
-    bind(resolution) {
-
-        const rect = new AABB2(0, 0, resolution, resolution);
-
-        if (!this.atlas.add(rect)) {
-            throw new Error(`Failed to add shadowmap to atlas`);
-        }
-
-        return rect;
-    }
-
-    destroy() {
-        this.texture.destroy();
-
-        for (let i = 0; i < this.#maps.length; i++) {
-            const map = this.#maps[i];
-            // release the per-view/-camera GPU contexts too — map.destroy() alone doesn't (the
-            // buffers live in the view/camera manager caches, not on the map)
-            this.#release_map_gpu_contexts(map);
-            map.destroy();
-        }
-        this.#maps.length = 0;
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
+import { MaxRectanglesPacker } from "../../../../core/geom/packing/max-rect/MaxRectanglesPacker.js";
+import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import { CameraManager } from "../../camera/CameraManager.js";
+import { OrthographicCamera } from "../../camera/OrthographicCamera.js";
+import { PerspectiveCamera } from "../../camera/PerspectiveCamera.js";
+import { CullPolicy } from "../../rasterize/bucket/construct_primitive_state.js";
+import { graph_mesh_sphere_cull } from "../../rasterize/compute/graph_mesh_sphere_cull.js";
+import { execute_rasterization_jobs } from "../../rasterize/execute_rasterization_jobs.js";
+import {
+    shadow_rasterization_alpha_tested_pass_descriptor
+} from "../../rasterize/native/depth/shadow_rasterization_alpha_tested_pass_descriptor.js";
+import {
+    shadow_rasterization_pass_descriptor
+} from "../../rasterize/native/depth/shadow_rasterization_pass_descriptor.js";
+import { RasterizationJob, RasterizationPipelineType } from "../../rasterize/RasterizationJob.js";
+import { graph_rasterize_scene_fast_raw } from "../../rasterize/fast/graph_rasterize_scene_fast.js";
+import { graph_create_texture, graph_import_texture } from "../../shader/graph/graph_import_texture.js";
+import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
+import { RenderTarget } from "../../texture/RenderTarget.js";
+import { View } from "../../view/View.js";
+import { ViewManager } from "../../view/ViewManager.js";
+import { SHADOWMAP_CSM_CASCADE_COUNT } from "./csm/SHADOWMAP_CSM_CASCADE_COUNT.js";
+import { DirectionalLightShadowmap } from "./DirectionalLightShadowmap.js";
+import { POINT_SHADOW_CUBE_COLS, POINT_SHADOW_CUBE_ROWS } from "./POINT_SHADOW_CUBE_LAYOUT.js";
+import {
+    POINT_SHADOW_TETRA_COLS,
+    POINT_SHADOW_TETRA_FACE_COUNT,
+    POINT_SHADOW_TETRA_MAPPING_RESOLUTION_SCALE,
+    POINT_SHADOW_TETRA_ROWS,
+} from "./POINT_SHADOW_TETRAHEDRON_LAYOUT.js";
+import { PointLightShadowmap } from "./PointLightShadowmap.js";
+import {
+    shader_shadowmap_remap_cube_to_octahedral
+} from "./shader/shader_shadowmap_remap_cube_to_octahedral.js";
+import {
+    POINT_SHADOW_TETRA_REMAP_SETTINGS,
+    shader_shadowmap_remap_tetrahedron_to_octahedral
+} from "./shader/shader_shadowmap_remap_tetrahedron_to_octahedral.js";
+import { SHADOWMAP_ATLAS_BORDER } from "./SHADOWMAP_ATLAS_BORDER.js";
+import { TetrahedronPointLightShadowmap } from "./TetrahedronPointLightShadowmap.js";
+import { compute_light_projected_area_px } from "./shadowmap_update_score.js";
+import { ShadowmapDrawSelector } from "./ShadowmapDrawSelector.js";
+import { ShadowmapRegistry } from "./ShadowmapRegistry.js";
+import { ShadowmapResolutionPolicy } from "./ShadowmapResolutionPolicy.js";
+import { SpotLightShadowmap } from "./SpotLightShadowmap.js";
+
+const DEFAULT_SHADOWMAP_ATLAS_RESOLUTION = 4096 * 2;
+
+/**
+ * Resolution by cascade.
+ * If the number of cascades is greater than the array length, the last resolution is used.
+ * @type {number[]}
+ */
+const DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION = [
+    1740, // first cascade
+    1440,
+];
+
+/**
+ * Placeholder resolution for local-light shadowmaps (spot/point).
+ * A proper implementation will project the light's bounding volume into screen space to derive this at runtime.
+ * @type {number}
+ */
+const DEFAULT_SHADOWMAP_LOCAL_RESOLUTION = 128;
+
+/**
+ * Per-frame shadow refresh budget, measured in **views** (one cube face counts as one view,
+ * one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
+ * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
+ * keeps the cost of the refresh step roughly proportional to how much work we're asking the
+ * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
+ * equivalent work to 6 spot lights.
+ *
+ * Directional lights are always refreshed unconditionally (they drive the whole scene) and
+ * their view cost is charged against the budget, so they effectively reduce the pool available
+ * for local lights that frame.
+ *
+ * Unused budget is carried over between frames when demand exceeds supply — see
+ * {@link GPUSceneShadowmapContext.#budget_carry_over}. This lets a light that's too expensive
+ * to fit in a single frame (e.g. a point needing 6 views when only 2 are free) eventually get
+ * its turn without permanently starving other lights.
+ * @type {number}
+ */
+const SHADOWMAP_UPDATE_BUDGET = 8;
+
+/**
+ * Shadows for a single scene
+ */
+export class GPUSceneShadowmapContext {
+    atlas = new MaxRectanglesPacker(DEFAULT_SHADOWMAP_ATLAS_RESOLUTION, DEFAULT_SHADOWMAP_ATLAS_RESOLUTION);
+
+    /**
+     * Depth texture atlas used for shadowmaps.
+     * @type {GPUTextureContext}
+     */
+    texture;
+
+
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     * Dedicated ViewManager for the cube/cascade/perspective shadow views this context
+     * creates and rasterizes into the atlas. Decoupled from the renderer-level ViewManager
+     * so the ownership chain stays self-contained — the shadow context creates the views,
+     * caches their GPU contexts, and disposes them with itself. The shared SceneManager
+     * lookup is short-circuited with a tiny object that always returns our owning
+     * GPUSceneContext (every shadow view here is for the same scene by construction).
+     * @type {ViewManager}
+     */
+    shadow_view_manager;
+
+    /**
+     * Internal CameraManager backing {@link shadow_view_manager}. Shadow cameras are
+     * created locally in {@link process_lights} and only referenced by this context, so
+     * they don't need to share the renderer-level CameraManager.
+     * @type {CameraManager}
+     */
+    #cameras;
+
+    /**
+     * @type {RenderTarget}
+     */
+    #render_target;
+
+
+    /**
+     * Every shadowmap this scene holds, plus the light -> map index and the reconciliation marks
+     * that make {@link process_lights} O(lights + maps) instead of O(lights x maps).
+     * @type {ShadowmapRegistry}
+     */
+    #registry = new ShadowmapRegistry();
+
+    /**
+     * Scores and picks the maps to refresh each frame. Holds the heap it selects with across
+     * frames, so the per-frame scoring allocates nothing.
+     * @type {ShadowmapDrawSelector}
+     */
+    #selector = new ShadowmapDrawSelector();
+
+    /**
+     * Scratch list of lights that need a shadowmap allocated, handed from pass 1 of
+     * {@link process_lights} to pass 3. Held across frames rather than allocated per call — it is
+     * empty on every frame where the light set didn't move, which is nearly all of them.
+     * @type {Light[]}
+     */
+    #reconcile_newcomers = [];
+
+    /**
+     * Master kill switch for shadows on this scene. Defaults true; the renderer sets it from
+     * its own `feature_shadows_enabled` flag before each frame's light update. When false,
+     * {@link process_lights} evicts all maps so the next light-record build clears
+     * CASTS_SHADOW_BIT on every light. {@link select_for_draw} and {@link draw} are still
+     * gated externally by the renderer; this flag exists to keep the GPU light records in
+     * sync with that gating without needing to thread the renderer's flag down further.
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * Selects the tetrahedral point-light shadow generator (4 face frusta) over the default
+     * cube generator (6 faces). The renderer pushes this from its
+     * `feature_tetrahedron_point_shadows` flag before each light update, alongside {@link enabled}.
+     *
+     * Only affects how a point light's shadow is GENERATED — both paths remap into the same
+     * octahedral atlas encoding, so the sampler is identical and this can be toggled at runtime.
+     * A flip is picked up in {@link process_lights}: existing point maps whose generator no longer
+     * matches this flag are evicted and rebuilt with the correct face count on the same pass.
+     * @type {boolean}
+     */
+    use_tetrahedron_point_shadows = false;
+
+    /**
+     * Frame index of the most recent {@link select_for_draw} call. Passed to {@link draw} via
+     * this field so we don't have to thread it through the call again — draw() stamps
+     * `map.last_updated_frame_index` with this value after each successful rasterization.
+     * @type {number}
+     */
+    #current_frame_index = -1;
+
+    /**
+     * View-budget surplus carried forward from prior frames. Accumulates whenever we had
+     * non-directional candidates that couldn't fit in the per-frame budget (i.e. a point light
+     * wanted 6 views but only 2 were free after directionals + earlier locals consumed their
+     * share). Resets to 0 on any frame where the full demand was satisfied, so the carryover
+     * doesn't grow unboundedly when the scene is quiet.
+     * @type {number}
+     */
+    #budget_carry_over = 0;
+
+    /**
+     * Adjusts per-map atlas footprints each frame based on projected on-screen area. Lazily
+     * tied to {@link atlas} in the constructor.
+     * @type {ShadowmapResolutionPolicy}
+     */
+    #resolution_policy;
+
+    /**
+     * Number of shadowmaps actually rasterized by the most recent {@link draw} call. Reset at
+     * the start of draw(), incremented once per map that went through the raster path. Exposed
+     * for debugging scheduling behaviour — a persistently oscillating value (e.g. 36/20/15
+     * repeating) indicates some maps are being invalidated every frame and forcing a redraw,
+     * which usually means the resolution policy or selector is churning.
+     * @type {number}
+     */
+    #debug_render_count = 0;
+
+    /**
+     * @returns {number} number of shadowmaps rasterized in the most recent draw pass
+     */
+    get debug_render_count() {
+        return this.#debug_render_count;
+    }
+
+    /**
+     * Most recently measured atlas occupancy (placed area / total area, including pending
+     * reservations), in [0, 1]. Forwards from the resolution policy. Useful for the debug
+     * overlay alongside {@link debug_drop_size_scale} — together they show whether the global
+     * shrink/grow feedback has converged or is still chasing the target band.
+     * @returns {number}
+     */
+    get debug_atlas_occupancy() {
+        return this.#resolution_policy.last_occupancy;
+    }
+
+    /**
+     * Current value of the global drop-size scale applied by the resolution policy. 1 means no
+     * shrink; values below 1 mean atlas pressure has trimmed every light's target size
+     * proportionally. Forwarded from the resolution policy for debug overlays.
+     * @returns {number}
+     */
+    get debug_drop_size_scale() {
+        return this.#resolution_policy.drop_size_scale;
+    }
+
+
+    /**
+     * Per-type counts of shadow records written to the GPU database in the previous
+     * {@link draw} pass. Used to identify trailing slots that must be zeroed when the
+     * map count for a given type shrinks (e.g. a shadow-casting light is removed),
+     * mirroring the bookkeeping in {@link GPULightCollection.#build}.
+     */
+    #prev_point_count = 0;
+    #prev_spot_count = 0;
+    #prev_directional_count = 0;
+
+    /**
+     * The Scene this context manages shadows for. Captured at construction so
+     * {@link process_lights} doesn't need it threaded back through every frame.
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * Owning light collection — gives us access to the GPU database where shadow
+     * records live and to the source LightCollection. Set in the constructor.
+     * @type {GPULightCollection}
+     */
+    #owner;
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     * @param {GPUSceneContext} scene_ctx the GPU-side context for the Scene we manage
+     *        shadows for. Used as the (single) destination of {@link shadow_view_manager}'s
+     *        scene lookup — every shadow view is for this scene, so the lookup short-circuits.
+     * @param {GPULightCollection} owner the parent light collection — gives us back-access
+     *        to the GPU database we publish records into during {@link draw}.
+     */
+    constructor(
+        graphics,
+        scene_ctx,
+        owner,
+    ) {
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene_ctx, 'scene_ctx');
+        assert.equal(scene_ctx.isGPUSceneContext, true, 'scene_ctx.isGPUSceneContext !== true');
+        assert.defined(owner, 'owner');
+
+
+        const initial_atlas_resolution = Math.min(
+            graphics.device.limits.maxTextureDimension2D,
+            DEFAULT_SHADOWMAP_ATLAS_RESOLUTION,
+        );
+
+        {
+            const t = this.texture = new GPUTextureContext(graphics.device);
+
+
+            const descriptor = t.descriptor;
+
+            descriptor.format = "depth32float";
+            descriptor.dimension = "2d";
+            descriptor.label = "Shadowmap atlas";
+            descriptor.usage = GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC;
+
+            t.resize(
+                initial_atlas_resolution,
+                initial_atlas_resolution
+            );
+
+            // ensure atlas size matches
+            this.atlas.resize(
+                initial_atlas_resolution,
+                initial_atlas_resolution
+            );
+        }
+
+        this.#graphics = graphics;
+        this.#scene = scene_ctx.scene;
+        this.#owner = owner;
+
+        // Local CameraManager + ViewManager dedicated to shadow rasterization. We don't
+        // share with the renderer-level managers because the cameras and views here are
+        // owned by this context and only referenced from inside it. The "scenes" lookup
+        // is a stub that always returns the owning scene context — every shadow view is
+        // for `this.#scene` by construction.
+        this.#cameras = new CameraManager(graphics.device);
+        this.shadow_view_manager = new ViewManager(graphics, this.#cameras, {
+            obtain: () => scene_ctx,
+        });
+
+        this.#render_target = RenderTarget.from({
+            depth: this.texture,
+        });
+
+        this.#resolution_policy = new ShadowmapResolutionPolicy(this.atlas);
+    }
+
+    /**
+     *
+     * @param {Light} light
+     * @returns {Shadowmap|undefined}
+     */
+    get_map(light) {
+        return this.#registry.get(light);
+    }
+
+    /**
+     * Decide which shadowmaps should be rasterized this frame.
+     *
+     * 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. 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.
+     *  3. **Reserve pending atlas footprints.** {@link ShadowmapResolutionPolicy.adjust} may
+     *     attach a `pending_layout` to maps whose projected area has shifted enough to warrant a
+     *     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.** 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
+     *          has never held valid depth (freshly created map); sampling it would display
+     *          garbage, so we bypass the budget. Resizes no longer invalidate under the dual-
+     *          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. **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, 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()`
+     * @param {GPUSceneContext} scene
+     * @param {number} frame_index monotonically increasing frame counter, used for staleness
+     * @param {ArrayLike<number>} view_resolution [width, height] of the main view in pixels; used
+     *        to convert projected sphere extents into a pixel-area score
+     */
+    select_for_draw(main_camera, scene, frame_index, view_resolution) {
+        assert.defined(main_camera, 'main_camera');
+        assert.isObject(main_camera, 'main_camera');
+        assert.equal(scene.isGPUSceneContext, true, 'scene.isGPUSceneContext !== true');
+        assert.isNumber(frame_index, 'frame_index');
+        assert.defined(view_resolution, 'view_resolution');
+
+        // make sure the camera is updated — both our scoring (projected area) and any downstream
+        // map.update() reads depend on view/projection matrices being current
+        main_camera.update();
+
+        this.#current_frame_index = frame_index;
+
+        const shadowmaps = this.#registry.maps;
+        const n = shadowmaps.length;
+
+        // Step 1 (clearing the stale per-frame `should_draw`) happens inside the selector's own
+        // scoring pass, so there is no separate walk for it here.
+
+        // Step 2: recompute projected areas. Writing onto the map so the policy + scorer can
+        // just read `map.projected_area_px` without threading a parallel array through.
+        for (let i = 0; i < n; i++) {
+            const m = shadowmaps[i];
+            m.projected_area_px = compute_light_projected_area_px(m.light, main_camera, view_resolution);
+        }
+
+        // Step 3: policy reserves pending resize footprints alongside committed layouts. It
+        // never mutates layout and never invalidates — sampling continues against the old
+        // region until draw() commits the pending during a normal raster pass. Directionals and
+        // off-screen locals are skipped (off-screen locals also get any stale pending released
+        // so an idle reservation can't tie up atlas space).
+        this.#resolution_policy.adjust(shadowmaps, frame_index);
+
+        // Steps 4 and 5: score every map and greedy-fill the view budget in score order. See
+        // ShadowmapDrawSelector for why this is a heap drain rather than a sort — the budget
+        // consumes a handful of winners out of however many candidates the scene has.
+        const budget_total = SHADOWMAP_UPDATE_BUDGET + this.#budget_carry_over;
+        const selector = this.#selector;
+
+        selector.select(shadowmaps, frame_index, budget_total);
+
+        // Fit the winners' projections to the current frame. Kept out of the selector because it
+        // needs the camera and the scene, and the selector is deliberately free of both.
+        //
+        // Maps that lost keep their prior metadata + atlas contents — a never-refreshed map
+        // samples the initial depth-cleared rect, which reads as "fully lit" under the reverse-Z
+        // greater compare. Acceptable behavior until the map eventually wins a slot.
+        const selected = selector.selected;
+        for (let i = 0; i < selected.length; i++) {
+            selected[i].update(main_camera, scene);
+        }
+
+        // Carry over the unused pool only when there was demand we couldn't meet. When the whole
+        // scene's demand was satisfied, reset to 0 so idle frames don't inflate the pool. If
+        // must-draw bypasses over-spent the pool (views_spent > budget_total), clamp at zero —
+        // we can't owe future frames for past over-spend, that way lies runaway starvation.
+        if (selector.had_unfit_candidates) {
+            this.#budget_carry_over = Math.max(0, budget_total - selector.views_spent);
+        } else {
+            this.#budget_carry_over = 0;
+        }
+    }
+
+    /**
+     * Publish per-shadowmap records into the scene's GPU database. Each map writes its record
+     * into the type-specific shadow_* table at the slot identified by `light._gpu_shadowmap_id`
+     * (which is itself the per-type index, set by {@link process_lights}). Trailing slots from
+     * previous frames are zeroed when the map count for a type shrinks, so stale entries don't
+     * linger.
+     *
+     * Only maps with `metadata_changed === true` are re-uploaded; the flag is cleared after
+     * the slot is queued so unchanged maps don't pay for an upload they don't need. Trim writes
+     * always run regardless of the flag — they zero slots that no longer correspond to any map.
+     *
+     * The type-bucket order here MUST match the per-type id assignment in {@link process_lights}
+     * (Point → Spot → Directional) so the shadow_id stamped onto each light record points at the
+     * slot we write here.
+     *
+     * Caller must invoke `database.update(cmd)` afterwards to upload the writes — that is done
+     * by {@link draw} once for both the new records and any zeroed trailing slots.
+     *
+     * @param {GPUDatabase} database
+     */
+    #write_shadow_records(database) {
+        const t_point = database.get('shadow_point');
+        const t_spot = database.get('shadow_spot');
+        const t_directional = database.get('shadow_directional');
+
+        const maps = this.#registry.maps;
+        let pc = 0;
+        let sc = 0;
+        let dc = 0;
+
+        for (let i = 0; i < maps.length; i++) {
+            const map = maps[i];
+            const light = map.light;
+
+            let table;
+            let slot;
+            if (light.isPointLight) {
+                table = t_point;
+                slot = pc++;
+            } else if (light.isSpotLight) {
+                table = t_spot;
+                slot = sc++;
+            } else if (light.isDirectionalLight) {
+                table = t_directional;
+                slot = dc++;
+            } else {
+                continue;
+            }
+
+            if (map.metadata_changed) {
+                table.set(slot, map.make_record());
+                map.metadata_changed = false;
+            }
+        }
+
+        // trim trailing slots from previous frames so disused entries don't leak
+        for (let i = pc; i < this.#prev_point_count; i++) {
+            t_point.remove(i);
+        }
+        for (let i = sc; i < this.#prev_spot_count; i++) {
+            t_spot.remove(i);
+        }
+        for (let i = dc; i < this.#prev_directional_count; i++) {
+            t_directional.remove(i);
+        }
+
+        this.#prev_point_count = pc;
+        this.#prev_spot_count = sc;
+        this.#prev_directional_count = dc;
+    }
+
+    /**
+     * Rasterize every shadowmap flagged by {@link select_for_draw} for a refresh this frame,
+     * committing any pending resize reservations in the process, then publish per-shadow
+     * metadata into the scene's GPU database.
+     *
+     * For each map with `should_draw` set:
+     *
+     *   1. If the map has a {@link Shadowmap.pending_layout} reservation, swap it into place
+     *      BEFORE rasterization so the draw targets the new region. The old committed rects
+     *      are remembered for step 3.
+     *   2. Dispatch to the type-specific raster path:
+     *        - **Directional / spot**: direct raster into the atlas's sub-rects (one job per
+     *          cascade for directionals, one job per spot).
+     *        - **Point**: 6 cube-face depth passes into a shared intermediate texture, then
+     *          cube→octahedral remap into the atlas. Point lights are serialised so they can
+     *          reuse the intermediate texture.
+     *   3. If a commit happened in step 1, release the old committed rects from the atlas now
+     *      that the new region holds valid depth.
+     *   4. Clear per-frame flags (`should_draw`, `is_invalid`) and stamp
+     *      `last_updated_frame_index` with the current frame.
+     *
+     * After the loop, each map's metadata record is written into the corresponding
+     * `shadow_point` / `shadow_spot` / `shadow_directional` table on the owning light
+     * collection's database, then the database is uploaded — this is where the committed
+     * swaps become visible to the lighting shader. `#debug_render_count` is reset at entry
+     * and incremented per map to expose scheduling behaviour to the debug overlay.
+     *
+     * No external job list: every path batches its own work internally via
+     * {@link execute_rasterization_jobs}. Callers just pass a command context.
+     *
+     * @param {ShadeGPUCommandContext} command_ctx
+     */
+    draw(command_ctx) {
+        assert.defined(command_ctx, 'command_ctx');
+
+
+        this.#debug_render_count = 0;
+
+        const frame_index = this.#current_frame_index;
+        const maps = this.#registry.maps;
+
+        for (let i = 0; i < maps.length; i++) {
+            const map = maps[i];
+            if (!map.should_draw) {
+                continue;
+            }
+
+            // Step 1: commit any pending-layout reservation before rasterizing. The draw helpers
+            // read `map.layout` directly, so swapping here makes the raster target the new
+            // region. We stash the old rect(s) locally for step 3's atlas release — once the
+            // raster commands are enqueued, the old region's contents will no longer be sampled
+            // (the next shadow-record write publishes the new layout), so returning that atlas
+            // space to the packer is safe.
+            let retired_rects = null;
+            if (map.pending_layout !== null) {
+                retired_rects = map.layout;
+                map.layout = map.pending_layout;
+                map.pending_layout = null;
+                map.metadata_changed = true;
+            }
+
+            const light = map.light;
+
+            if (light.isDirectionalLight || light.isSpotLight) {
+                this.#draw_direct(map, command_ctx);
+            } else if (light.isPointLight) {
+                if (map.isTetrahedron) {
+                    this.#draw_point_tetrahedron(map, command_ctx);
+                } else {
+                    this.#draw_point(map, command_ctx);
+                }
+            } else {
+                throw new Error(`Unsupported light type ${light.constructor.name}`);
+            }
+
+            // Step 3: release the retired rects from the atlas. Must happen AFTER the raster
+            // helpers finish reading map.layout (they may close over retired_rects as scratch
+            // memory or view references in some paths; safest order is raster-first).
+            if (retired_rects !== null) {
+                for (let j = 0; j < retired_rects.length; j++) {
+                    this.atlas.remove(retired_rects[j]);
+                }
+            }
+
+            // Step 4: atlas contents are now current. Clear per-frame flags and stamp the frame
+            // index so the next frame's scorer computes staleness correctly.
+            map.should_draw = false;
+            map.is_invalid = false;
+            map.last_updated_frame_index = frame_index;
+            this.#debug_render_count++;
+        }
+
+
+        // Publish metadata AFTER all commits so the lighting shader sees atlas coordinates that
+        // match the regions we just rasterised into. Never-drawn maps carry stale-but-valid
+        // projection + layout; off-screen maps and skipped candidates publish their prior state.
+        const database = this.#owner.database;
+        this.#write_shadow_records(database);
+        database.update(command_ctx);
+
+
+        // finalize rendered views
+        for (const map of this.#registry.maps) {
+            if (map.last_updated_frame_index !== frame_index) {
+                // skip
+                continue;
+            }
+
+            for (const view of map.views) {
+                const view_ctx = this.shadow_view_manager.obtain(view);
+                view_ctx.finish_frame(command_ctx);
+            }
+        }
+    }
+
+    /**
+     * Rasterize a directional or spot shadowmap directly into its atlas rects. One job per
+     * `map.views[i]` / `map.layout[i]` pair — directionals have N cascades, spots have one.
+     *
+     * @param {Shadowmap} map
+     * @param {ShadeGPUCommandContext} command_ctx
+     */
+    #draw_direct(map, command_ctx) {
+        // TODO pre-cull mesh set by sphere-casting the light volume against the main View Frustum
+        //      see ref: https://www.reddit.com/r/Unity3D/comments/1foe8qi/added_a_way_to_perform_frustum_culling_and_take
+
+        const graph = new FrameGraph("shadows");
+
+        const shadow_views = map.views;
+        const jobs = new Array(shadow_views.length);
+
+        for (let i = 0; i < shadow_views.length; i++) {
+            const view = shadow_views[i];
+            const view_ctx = this.shadow_view_manager.obtain(view);
+
+            view_ctx.update(this.#graphics);
+
+            const atlas_aabb = map.layout[i];
+            view_ctx.setViewportSize(atlas_aabb.width, atlas_aabb.height);
+
+            const job = new RasterizationJob();
+            job.opaque_pass = shadow_rasterization_pass_descriptor;
+            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
+            job.cull_policy = CullPolicy.Reversed;
+            job.render_target = this.#render_target;
+            job.view_ctx = view_ctx;
+            job.viewport = [atlas_aabb.x0, atlas_aabb.y0, atlas_aabb.width, atlas_aabb.height];
+
+
+            jobs[i] = job;
+
+            // TODO reproject current scene view into shadow map for better occlusion culling,
+            //  see Assassin's Creed Unity talk on GPU-driven rendering,
+            //  see "RE ENGINE Meshlet Rendering Pipeline" https://youtu.be/nWgPtCDXlPc?t=2055
+
+            // TODO need to linearize depth(?)
+            // can linearize together with reprojection (TAA)
+        }
+
+        execute_rasterization_jobs({
+            jobs,
+            limits: this.#graphics.collection_limits,
+            command_ctx,
+            graph,
+        });
+
+        command_ctx.encodeGraph(graph);
+    }
+
+    /**
+     * Rasterize a point light's 6 cube faces into the shared intermediate texture, then run the
+     * cube→octahedral remap shader to write the encoded depth into this light's atlas rect.
+     *
+     * Sequencing matters: each point light fully completes (6 cube rasters + remap) before the
+     * next one starts, so the intermediate texture can be reused across point lights without
+     * cross-contamination.
+     *
+     * @param {PointLightShadowmap} map
+     * @param {ShadeGPUCommandContext} command_ctx
+     */
+    #draw_point(
+        map,
+        command_ctx,
+    ) {
+
+        const graph = new FrameGraph("shadows");
+
+        const gr_atlas_texture = graph_import_texture(graph, this.texture);
+
+        const atlas_rect = map.layout[0];
+
+        const octahedral_resolution = atlas_rect.width;
+
+        /**
+         * Controls the relationship between octahedral resolution and the cube map used during rendering
+         * If this is larger - we get better quality at the cost of rendering more pixels.
+         *
+         * Solving for solid angle coverage, using the formula `N=POW(1 - SQRT(E/3), 3/2)` we get:
+         *
+         * 0% error -> 1
+         * 1% error -> 0.915
+         * 5% error -> 0.81299
+         * 10% error -> 0.739
+         * 20% error -> 0.639
+         * 30% error -> 0.565
+         * 40% error -> 0.506
+         * 50% error -> 0.455
+         *
+         * @type {number}
+         */
+        const CUBE_MAPPING_RESOLUTION_SCALE = 1;
+
+        const cube_face_resolution = Math.ceil(octahedral_resolution * CUBE_MAPPING_RESOLUTION_SCALE);
+
+        // reserve texture
+        let cube_packed_texture = graph_create_texture(graph, TextureResourceDescriptor.from({
+            resolution: [
+                cube_face_resolution * POINT_SHADOW_CUBE_COLS,
+                cube_face_resolution * POINT_SHADOW_CUBE_ROWS,
+            ],
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            format: 'depth32float',
+            enableMips: false,
+        }));
+
+        /**
+         *
+         * @type {PointLight}
+         */
+        const light = map.light;
+
+        const scene_ctx = this.shadow_view_manager.obtain(map.views[0]).scene;
+
+        /**
+         * Sphere-culled meshes from the scene.
+         * We could do per-face culling, but most point lights are local, and there's already meshlet culling happening later in the pipeline.
+         * Good enough.
+         * @type {number}
+         */
+        const input_meshes = graph_mesh_sphere_cull({
+            graph,
+            sphere: [...light.position, light.distance],
+            scene: scene_ctx,
+            limits: this.#graphics.collection_limits,
+        });
+
+        for (let face = 0; face < 6; face++) {
+            const view = map.views[face];
+            const view_ctx = this.shadow_view_manager.obtain(view);
+
+            view_ctx.update(this.#graphics);
+            view_ctx.setViewportSize(cube_face_resolution, cube_face_resolution);
+
+            const col = face % POINT_SHADOW_CUBE_COLS;
+            const row = Math.floor(face / POINT_SHADOW_CUBE_COLS);
+
+            const job = new RasterizationJob();
+
+            job.pipeline_type = RasterizationPipelineType.Fast;
+            job.opaque_pass = shadow_rasterization_pass_descriptor;
+            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
+            job.cull_policy = CullPolicy.Reversed;
+            job.render_target = null;
+            job.view_ctx = view_ctx;
+            job.viewport = [
+                col * cube_face_resolution,
+                row * cube_face_resolution,
+                cube_face_resolution,
+                cube_face_resolution,
+            ];
+
+            cube_packed_texture = graph_rasterize_scene_fast_raw({
+                graph,
+                meshes: input_meshes,
+                limits: this.#graphics.collection_limits,
+                target_depth: cube_packed_texture,
+                job,
+            }).target_depth;
+        }
+
+        /**
+         *
+         * @param data
+         * @param {FramePassResources} resources
+         * @param {GraphicsExecutionContext} context
+         */
+        function remap_to_atlas(data, resources, context) {
+            const atlas = resources.get(data.atlas);
+            const cube_texture = resources.get(data.cube_texture);
+
+            const settings = {
+                atlas_offset: [
+                    atlas_rect.x0 + SHADOWMAP_ATLAS_BORDER,
+                    atlas_rect.y0 + SHADOWMAP_ATLAS_BORDER,
+                    atlas_rect.width - 2 * SHADOWMAP_ATLAS_BORDER,
+                    atlas_rect.height - 2 * SHADOWMAP_ATLAS_BORDER,
+                ],
+                light_params: [
+                    map.light.distance,
+                    map.cube_near,
+                    0,
+                    0,
+                ]
+            };
+
+            shader_shadowmap_remap_cube_to_octahedral.draw({
+                encoder: context.encoder,
+                bindings: {
+                    settings: settings,
+                    cube_faces: cube_texture.obtainView(),
+                },
+                depthStencilAttachment: {
+                    view: atlas.obtainView(),
+                    depthLoadOp: "load",
+                    depthStoreOp: "store",
+                },
+                viewport: [
+                    atlas_rect.x0,
+                    atlas_rect.y0,
+                    atlas_rect.width,
+                    atlas_rect.height,
+                ]
+            })
+        }
+
+        const remap_data = {};
+
+        const remap_pass = graph.add("remap to atals", remap_data, remap_to_atlas);
+
+        remap_data.atlas = remap_pass.write(gr_atlas_texture);
+        remap_data.cube_texture = remap_pass.read(cube_packed_texture);
+
+
+        command_ctx.encodeGraph(graph);
+    }
+
+    /**
+     * Rasterize a point light's 4 tetrahedron faces into a shared intermediate texture, then run
+     * the tetrahedron→octahedral remap to write the encoded depth into this light's atlas rect.
+     * The tetrahedral parallel to {@link #draw_point} — same shape, 4 faces in a 2x2 grid instead
+     * of 6 in a 3x2 grid, and the remap is handed each face's view-projection matrix so it can
+     * select faces and project directions in exact agreement with how the depth was rasterized.
+     *
+     * @param {TetrahedronPointLightShadowmap} map
+     * @param {ShadeGPUCommandContext} command_ctx
+     */
+    #draw_point_tetrahedron(
+        map,
+        command_ctx,
+    ) {
+
+        const graph = new FrameGraph("shadows");
+
+        const gr_atlas_texture = graph_import_texture(graph, this.texture);
+
+        const atlas_rect = map.layout[0];
+
+        const octahedral_resolution = atlas_rect.width;
+
+        // Wider face fov than the cube path (see POINT_SHADOW_TETRA_FOV_DEGREES) needs a larger
+        // per-face resolution to hold comparable on-axis density — the analogue of the cube
+        // path's CUBE_MAPPING_RESOLUTION_SCALE.
+        const face_resolution = Math.ceil(octahedral_resolution * POINT_SHADOW_TETRA_MAPPING_RESOLUTION_SCALE);
+
+        // reserve intermediate depth texture — 2x2 grid of faces
+        let tetra_packed_texture = graph_create_texture(graph, TextureResourceDescriptor.from({
+            resolution: [
+                face_resolution * POINT_SHADOW_TETRA_COLS,
+                face_resolution * POINT_SHADOW_TETRA_ROWS,
+            ],
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            format: 'depth32float',
+            enableMips: false,
+        }));
+
+        /**
+         *
+         * @type {PointLight}
+         */
+        const light = map.light;
+
+        const scene_ctx = this.shadow_view_manager.obtain(map.views[0]).scene;
+
+        // One sphere cull for all 4 faces — most point lights are local and meshlet culling
+        // refines later; per-face culling isn't worth it. Same trade as the cube path.
+        const input_meshes = graph_mesh_sphere_cull({
+            graph,
+            sphere: [...light.position, light.distance],
+            scene: scene_ctx,
+            limits: this.#graphics.collection_limits,
+        });
+
+        for (let face = 0; face < POINT_SHADOW_TETRA_FACE_COUNT; face++) {
+            const view = map.views[face];
+            const view_ctx = this.shadow_view_manager.obtain(view);
+
+            view_ctx.update(this.#graphics);
+            view_ctx.setViewportSize(face_resolution, face_resolution);
+
+            const col = face % POINT_SHADOW_TETRA_COLS;
+            const row = Math.floor(face / POINT_SHADOW_TETRA_COLS);
+
+            const job = new RasterizationJob();
+
+            job.pipeline_type = RasterizationPipelineType.Fast;
+            job.opaque_pass = shadow_rasterization_pass_descriptor;
+            job.alpha_tested_pass = shadow_rasterization_alpha_tested_pass_descriptor;
+            job.cull_policy = CullPolicy.Reversed;
+            job.render_target = null;
+            job.view_ctx = view_ctx;
+            job.viewport = [
+                col * face_resolution,
+                row * face_resolution,
+                face_resolution,
+                face_resolution,
+            ];
+
+            tetra_packed_texture = graph_rasterize_scene_fast_raw({
+                graph,
+                meshes: input_meshes,
+                limits: this.#graphics.collection_limits,
+                target_depth: tetra_packed_texture,
+                job,
+            }).target_depth;
+        }
+
+        const views = map.views;
+        const tetra_near = map.tetra_near;
+        const light_max_distance = map.light.distance;
+
+        /**
+         *
+         * @param data
+         * @param {FramePassResources} resources
+         * @param {GraphicsExecutionContext} context
+         */
+        function remap_to_atlas(data, resources, context) {
+            const atlas = resources.get(data.atlas);
+            const tetra_texture = resources.get(data.tetra_texture);
+
+            // Read each face camera's view-projection at encode time — set in map.update() and
+            // untouched since, and it is exactly the matrix the rasterizer used above.
+            const face_view_proj = new Array(POINT_SHADOW_TETRA_FACE_COUNT);
+            for (let f = 0; f < POINT_SHADOW_TETRA_FACE_COUNT; f++) {
+                face_view_proj[f] = views[f].camera.view_projection_matrix;
+            }
+
+            const settings = context.encoder.allocateTransientValueBuffer(
+                POINT_SHADOW_TETRA_REMAP_SETTINGS,
+                {
+                    atlas_offset: [
+                        atlas_rect.x0 + SHADOWMAP_ATLAS_BORDER,
+                        atlas_rect.y0 + SHADOWMAP_ATLAS_BORDER,
+                        atlas_rect.width - 2 * SHADOWMAP_ATLAS_BORDER,
+                        atlas_rect.height - 2 * SHADOWMAP_ATLAS_BORDER,
+                    ],
+                    light_params: [
+                        light_max_distance,
+                        tetra_near,
+                        0,
+                        0,
+                    ],
+                    face_view_proj,
+                }
+            );
+
+            shader_shadowmap_remap_tetrahedron_to_octahedral.draw({
+                encoder: context.encoder,
+                bindings: {
+                    settings: settings,
+                    tetra_faces: tetra_texture.obtainView(),
+                },
+                depthStencilAttachment: {
+                    view: atlas.obtainView(),
+                    depthLoadOp: "load",
+                    depthStoreOp: "store",
+                },
+                viewport: [
+                    atlas_rect.x0,
+                    atlas_rect.y0,
+                    atlas_rect.width,
+                    atlas_rect.height,
+                ]
+            })
+        }
+
+        const remap_data = {};
+
+        const remap_pass = graph.add("remap tetra to atlas", remap_data, remap_to_atlas);
+
+        remap_data.atlas = remap_pass.write(gr_atlas_texture);
+        remap_data.tetra_texture = remap_pass.read(tetra_packed_texture);
+
+
+        command_ctx.encodeGraph(graph);
+    }
+
+    /**
+     * Release the per-face GPU contexts (each view's uniform/HZB/volumetrics buffers + its camera
+     * uniform) backing a map. The dedicated {@link shadow_view_manager} / {@link #cameras} caches
+     * key on the View/Camera objects and have no GC path, so a map's contexts must be released
+     * explicitly here or their GPU buffers leak for the context's lifetime. Most visible when the
+     * point-shadow generator toggle rebuilds every point map (fresh Views each time), but it also
+     * closes the ordinary eviction leak (light removed / stops casting / shadows disabled).
+     *
+     * In this context Views and Cameras are 1:1 per map (each map creates its own), so releasing a
+     * view's camera alongside it can't strand a still-referenced camera.
+     *
+     * @param {Shadowmap} map
+     */
+    #release_map_gpu_contexts(map) {
+        const views = map.views;
+        for (let j = 0; j < views.length; j++) {
+            const view = views[j];
+            this.shadow_view_manager.release(view);
+            this.#cameras.release(view.camera);
+        }
+    }
+
+    /**
+     * Release a map's atlas rects + GPU side-resources. Caller is responsible for splicing it
+     * out of {@link #registry}.
+     *
+     * @param {Shadowmap} map
+     */
+    #evict_map(map) {
+        for (let j = 0; j < map.layout.length; j++) {
+            this.atlas.remove(map.layout[j]);
+        }
+        if (map.pending_layout !== null) {
+            for (let j = 0; j < map.pending_layout.length; j++) {
+                this.atlas.remove(map.pending_layout[j]);
+            }
+            map.pending_layout = null;
+        }
+
+        // free the per-view/-camera GPU contexts — without this an evicted map's buffers leak
+        this.#release_map_gpu_contexts(map);
+
+        map.light._gpu_shadowmap_id = -1;
+    }
+
+    /**
+     * Reconcile shadow allocations against the current scene state. Evicts maps for lights
+     * that no longer cast shadows or have left the scene, allocates maps for new shadow-
+     * casting lights, and reassigns per-type `_gpu_shadowmap_id` when the map ordering
+     * shifts.
+     *
+     * Called from {@link GPULightCollection.update} every frame, including frames where
+     * {@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
+     *          have shifted).
+     */
+    process_lights() {
+        const registry = this.#registry;
+        const shadowmaps = registry.maps;
+
+        // When the renderer has shadows disabled, treat every map as evictable so the next
+        // build clears CASTS_SHADOW_BIT on every light. Re-enabling reconstructs everything
+        // from scratch on the following frame — that's a one-frame catch-up cost, considered
+        // an acceptable trade for the simpler invariant ("disabled" = no maps held).
+        if (!this.enabled) {
+            const had_maps = shadowmaps.length > 0;
+            for (let i = shadowmaps.length - 1; i >= 0; i--) {
+                this.#evict_map(shadowmaps[i]);
+            }
+            registry.clear();
+            return had_maps;
+        }
+
+        const scene = this.#scene;
+        const lights = scene.lights.elements;
+        let changed = false;
+
+        const use_tetra = this.use_tetrahedron_point_shadows;
+        const newcomers = this.#reconcile_newcomers;
+
+        registry.begin_reconcile();
+        newcomers.length = 0;
+
+        // Pass 1 — mark. One index lookup per light both answers "does this light already have a
+        // map" and stamps that map as belonging to a light still in the scene, which is what lets
+        // the reclamation below run without building a set of live lights first.
+        //
+        // A light that stopped casting is simply not marked; its map falls out in pass 2 on the
+        // strength of the stale mark alone.
+        for (let i = 0; i < lights.length; i++) {
+            const light = lights[i];
+
+            if (!light.casts_shadow) {
+                continue;
+            }
+
+            const map = registry.mark_live(light);
+
+            if (map === undefined) {
+                newcomers.push(light);
+                continue;
+            }
+
+            // A point map built by the other generator (cube vs tetra) must be rebuilt when the
+            // flag flips — its face count and draw path no longer match. Pass 2 drops it on the
+            // same test; queueing the rebuild here lands it in this pass rather than the next.
+            if (light.isPointLight && Boolean(map.isTetrahedron) !== use_tetra) {
+                newcomers.push(light);
+            }
+        }
+
+        // Pass 2 — reclaim. Anything not marked belongs to a light that left the scene or stopped
+        // casting, and its atlas rect would otherwise stay pinned forever. Walk in reverse so
+        // splice indices stay stable.
+        for (let i = shadowmaps.length - 1; i >= 0; i--) {
+            const map = shadowmaps[i];
+            const light = map.light;
+
+            const generator_mismatch = light.isPointLight
+                && Boolean(map.isTetrahedron) !== use_tetra;
+
+            if (registry.is_marked(map) && !generator_mismatch) {
+                continue;
+            }
+            this.#evict_map(map);
+            registry.remove_at(i);
+            changed = true;
+        }
+
+        const add_directional = (light) => {
+            const map = new DirectionalLightShadowmap();
+            map.light = light;
+
+            const bound = [];
+            try {
+                for (let j = 0; j < SHADOWMAP_CSM_CASCADE_COUNT; j++) {
+                    const resolution_index = Math.min(j, DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION.length - 1);
+                    const resolution = DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION[resolution_index];
+
+                    const rect = this.bind(resolution);
+                    bound.push(rect);
+                    map.layout[j] = rect;
+
+                    const camera = new OrthographicCamera();
+                    camera.update();
+
+                    const view = new View(camera, scene);
+                    view.label = `Shadow Cascade ${j}`;
+
+                    map.views[j] = view;
+                }
+            } catch (e) {
+                // Partial bind: roll back any cascade rects already inserted so the atlas isn't
+                // left holding orphans for a map that never got registered.
+                for (let j = 0; j < bound.length; j++) {
+                    this.atlas.remove(bound[j]);
+                }
+                throw e;
+            }
+
+            registry.add(map);
+        };
+
+        const add_spot = (light) => {
+            const map = new SpotLightShadowmap();
+            map.light = light;
+
+            const rect = this.bind(DEFAULT_SHADOWMAP_LOCAL_RESOLUTION);
+            map.layout[0] = rect;
+
+            try {
+                const camera = new PerspectiveCamera();
+                camera.update();
+
+                const view = new View(camera, scene);
+                view.label = `Spot Shadow`;
+
+                map.views[0] = view;
+            } catch (e) {
+                this.atlas.remove(rect);
+                throw e;
+            }
+
+            registry.add(map);
+        };
+
+        const add_point = (light) => {
+
+            // Generator picked by `use_tetra` above; both remap into one octahedral slot, they
+            // only differ in how many face frusta feed that remap (tetra 4, cube 6).
+            const map = use_tetra ? new TetrahedronPointLightShadowmap() : new PointLightShadowmap();
+            map.light = light;
+
+            // single atlas rect holds the octahedral-encoded depth for all faces
+            const rect = this.bind(DEFAULT_SHADOWMAP_LOCAL_RESOLUTION);
+            map.layout[0] = rect;
+
+            const face_count = use_tetra ? POINT_SHADOW_TETRA_FACE_COUNT : 6;
+
+            for (let j = 0; j < face_count; j++) {
+                const camera = new PerspectiveCamera();
+                camera.update();
+
+                const view = new View(camera, scene);
+                view.label = use_tetra ? `Point Shadow (tetra) face ${j}` : `Point Shadow face ${j}`;
+
+                map.views[j] = view;
+            }
+
+            registry.add(map);
+        };
+
+        const add_light = (light) => {
+            // A light present twice in the scene's light array gets queued twice by pass 1, since
+            // neither occurrence finds a map. LightCollection.add doesn't dedupe, so re-check here
+            // rather than letting the registry's one-map-per-light assert fire every frame. Free
+            // in the normal case — this loop only runs over lights that actually need a map.
+            if (registry.get(light) !== undefined) {
+                return;
+            }
+
+            if (light.isDirectionalLight) {
+                add_directional(light);
+                changed = true;
+            } else if (light.isSpotLight) {
+                add_spot(light);
+                changed = true;
+            } else if (light.isPointLight) {
+                add_point(light);
+                changed = true;
+            }
+        };
+
+        // Pass 3 — allocate. Only the lights pass 1 flagged, so on the overwhelming majority of
+        // frames (nothing arrived, nothing left) this loop does not run at all. The old version
+        // walked every light here and re-tested casts_shadow on each; pass 1 already answered that.
+        for (let i = 0; i < newcomers.length; i++) {
+            try {
+                add_light(newcomers[i]);
+            } catch (e) {
+                console.error(e);
+            }
+        }
+
+        // Drop the references rather than leaving them until the next call — a light that gets
+        // removed from the scene right after being added here would otherwise stay reachable from
+        // this scratch array for a frame.
+        newcomers.length = 0;
+
+        // Publish per-type shadowmap ids back onto the lights. Each shadow_* table is indexed
+        // independently, so a point light's shadow_id points into shadow_point, a spot's into
+        // shadow_spot, etc. Type-bucket order MUST match {@link #write_shadow_records} so each
+        // light record's stored shadow_id lines up with the slot we'll write into the table.
+        // When a map's slot index actually changes (eviction shifted neighbours up the array),
+        // mark its record dirty so the next #write_shadow_records re-publishes it into the new
+        // slot, and report `changed` so the caller re-publishes the light records too.
+        let pc = 0;
+        let sc = 0;
+        let dc = 0;
+        for (let i = 0; i < shadowmaps.length; i++) {
+            const map = shadowmaps[i];
+            const light = map.light;
+
+            let new_id;
+            if (light.isPointLight) {
+                new_id = pc++;
+            } else if (light.isSpotLight) {
+                new_id = sc++;
+            } else if (light.isDirectionalLight) {
+                new_id = dc++;
+            } else {
+                continue;
+            }
+
+            if (light._gpu_shadowmap_id !== new_id) {
+                light._gpu_shadowmap_id = new_id;
+                map.metadata_changed = true;
+                changed = true;
+            }
+        }
+
+        return changed;
+    }
+
+    /**
+     *
+     * @param {number} resolution
+     * @returns {AABB2}
+     */
+    bind(resolution) {
+
+        const rect = new AABB2(0, 0, resolution, resolution);
+
+        if (!this.atlas.add(rect)) {
+            throw new Error(`Failed to add shadowmap to atlas`);
+        }
+
+        return rect;
+    }
+
+    destroy() {
+        this.texture.destroy();
+
+        const maps = this.#registry.maps;
+        for (let i = 0; i < maps.length; i++) {
+            const map = maps[i];
+            // release the per-view/-camera GPU contexts too — map.destroy() alone doesn't (the
+            // buffers live in the view/camera manager caches, not on the map)
+            this.#release_map_gpu_contexts(map);
+            map.destroy();
+        }
+        this.#registry.clear();
+    }
+}