@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -1,928 +1,594 @@
-import { assert } from "../../../core/assert.js";
-import { typed_array_copy } from "../../../core/collection/array/typed/typed_array_copy.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
-import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
-import { Brick4LightMap } from "../global_illumination/brick4/Brick4LightMap.js";
-import { GPULightProbeVolume } from "../global_illumination/lpv/GPULightProbeVolume.js";
-import { GPULightCollection } from "../light/GPULightCollection.js";
-import { GPUSceneVolumetrics } from "../volumetrics/GPUSceneVolumetrics.js";
-import { Scene } from "./Scene.js";
-import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
-import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";
-import { NODE3D_SCENE_ID } from "./NODE3D_STRUCT.js";
-import { SCENE_DATABASE_SPEC } from "./SCENE_DATABASE_SPEC.js";
-import { SceneNodeBinding } from "./SceneNodeBinding.js";
-import { TransformAuthority } from "./TransformAuthority.js";
-
-/**
- * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
- * @typedef {import("../geometry/GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
- * @typedef {import("../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
- * @typedef {import("./Node3D.js").Node3D} Node3D
- */
-
-
-let id_counter = 0;
-
-/**
- * Staging for one `transforms` row. Reused across every write — the table serializes it into its
- * page shadow synchronously, so nothing outlives the call.
- */
-const TRANSFORM_RECORD = {
-    local_translation: new Float32Array(3),
-    local_rotation: new Float32Array(4),
-    local_scale: new Float32Array(3),
-    global: new Float32Array(16),
-    prev_global: new Float32Array(16),
-    parent: NODE3D_SCENE_ID,
-};
-
-/**
- * Placeholder for claiming a row before its contents are known — {@link GPUTypedTable.add} chooses
- * the row, and the record has to name it. Overwritten in the same breath, and the table's upload
- * de-duplication collapses the pair into a single record.
- */
-const EMPTY_TRANSFORM_RECORD = {
-    local_translation: new Float32Array(3),
-    local_rotation: new Float32Array(4),
-    local_scale: new Float32Array(3),
-    global: new Float32Array(16),
-    prev_global: new Float32Array(16),
-    parent: NODE3D_SCENE_ID,
-};
-
-/**
- * Staging for one `meshes` row, on the same terms as {@link TRANSFORM_RECORD}. The two bounds
- * fields are references to the mesh's own arrays rather than copies — the table reads them before
- * the next call replaces them.
- */
-const MESH_RECORD = {
-    geometry: 0,
-    material: 0,
-    node: NODE3D_SCENE_ID,
-    bounding_box: undefined,
-    bounding_sphere: undefined,
-};
-
-/**
- * Abstraction on the context of a scene, there are no hierarchies, just a collection of meshes and a geometry context
- */
-export class GPUSceneContext {
-
-    /**
-     * @readonly
-     * @type {number}
-     */
-    id = id_counter++;
-
-    /**
-     * @type {GPUGeometryManager}
-     */
-    geometries;
-
-    /**
-     * @type {GPUMaterialManager}
-     */
-    materials;
-
-
-    /**
-     * @type {Brick4LightMap}
-     */
-    volumetric_light_map;
-
-
-    /**
-     *
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     *
-     * @return {Scene}
-     */
-    get scene() {
-        return this.#scene;
-    }
-
-    /**
-     * @type {GPUSceneVolumetrics}
-     */
-    #volumetrics;
-
-    get volumetrics() {
-        return this.#volumetrics;
-    }
-
-    /**
-     * @type {GPULightCollection}
-     */
-    #lights;
-
-
-    /**
-     *
-     * @returns {GPULightCollection}
-     */
-    get lights() {
-        return this.#lights;
-    }
-
-    /**
-     * @type {GPULightProbeVolume}
-     */
-    #light_probe_volume;
-
-    /**
-     *
-     * @returns {GPULightProbeVolume}
-     */
-    get light_probe_volume() {
-        return this.#light_probe_volume;
-    }
-
-    /**
-     * @type {GPUInstancesAccelerationStructure}
-     */
-    #tlas
-
-    /**
-     *
-     * @returns {GPUInstancesAccelerationStructure}
-     */
-    get tlas() {
-        return this.#tlas;
-    }
-
-    /**
-     * GPU-resident scene database — mesh metadata in the `meshes` table,
-     * scene-graph nodes (transforms) in the `transforms` table. Replaces
-     * the old flat `instance_buffer`. Consumers bind `scene_database.buffer`
-     * as `array<u32>` and read records via `scene_read_mesh` /
-     * `scene_read_node` (see `chunk_scene_database_access`).
-     *
-     * @type {GPUDatabase}
-     */
-    #scene_database;
-
-    /**
-     *
-     * @type {Uint32Array}
-     */
-    #instance_metadata = new Uint32Array();
-
-    /**
-     * Mesh → instance index. Rebuilt each frame in {@link build}. The
-     * Lookup from a node's stable JS-side {@link Node3D.id} to its row
-     * in the scene database's `transforms` table. Built during
-     * {@link build} as each node is allocated via
-     * {@link GPUTypedTable.add}; the table itself owns the row
-     * allocation, this map just bridges between Node3D handles and the
-     * GPU rows they live at.
-     *
-     * Public so external code can do partial updates: looking up a
-     * single node's row lets a system patch one `transforms_table`
-     * entry instead of re-uploading the whole scene.
-     *
-     * @type {Map<number, number>}
-     */
-    id_mapping = new Map();
-
-    /**
-     * Per-scene skinning state — clone-index cache today, plus
-     * Skin-bindings and the per-frame skinning compute dispatch in
-     * later phases. Lazily constructed because it depends on
-     * {@link geometries}, which {@link SceneManager#create} assigns
-     * externally after this constructor runs. See {@link skinning} for
-     * access.
-     *
-     * @type {GPUMeshSkinningContext|null}
-     */
-    #skinning = null;
-
-    /**
-     * Per-scene animation system — clips, tracks, curves, skins, and
-     * the skin-matrix scratch buffer. Owned here (rather than passed
-     * in) so that consumers fetching `gpu_scene.animation_manager`
-     * always see the same instance, and so per-frame database flush
-     * can be wired into {@link update} alongside the rest of the
-     * scene's bookkeeping.
-     *
-     * @type {GPUAnimationManager}
-     */
-    #animation_manager;
-
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics, scene) {
-        assert.defined(scene, 'scene');
-        assert.isObject(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        const device = graphics.device;
-
-        this.#scene = scene;
-        this.#device = device;
-        this.#graphics = graphics;
-
-        this.#tlas = new GPUInstancesAccelerationStructure(graphics);
-
-        // Pass `this` so the light collection (and its child shadow context) can use
-        // this scene's GPUSceneContext when building its own ViewManager — avoids
-        // threading the renderer-level ViewManager / SceneManager through every layer.
-        this.#lights = new GPULightCollection(graphics, this);
-
-        this.#scene_database = new GPUDatabase({
-            device,
-            definition: SCENE_DATABASE_SPEC,
-            label: "GPUSceneContext/Database",
-        });
-
-        this.#light_probe_volume = new GPULightProbeVolume(device, scene.light_probe_volume);
-
-        this.volumetric_light_map = new Brick4LightMap(device);
-
-        this.#volumetrics = new GPUSceneVolumetrics(device, scene.volumetrics);
-
-        this.#animation_manager = new GPUAnimationManager(device, `GPUSceneContext[${this.id}]/Animation`, this);
-    }
-
-    /**
-     * @returns {GPUAnimationManager}
-     */
-    get animation_manager() {
-        return this.#animation_manager;
-    }
-
-    #instances_version = -1;
-
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics;
-
-    /**
-     *
-     * @returns {GPUDatabase}
-     */
-    get scene_database() {
-        return this.#scene_database;
-    }
-
-    /**
-     * The underlying buffer that backs {@link scene_database} — bind this
-     * as `array<u32>` in shaders that read mesh / transform records.
-     *
-     * @returns {GPUBuffer}
-     */
-    get scene_database_buffer() {
-        return this.#scene_database.buffer;
-    }
-
-    /**
-     * Per-scene skinning subsystem. Routes {@link SkinnedMesh}
-     * instances through per-instance geometry clones; later phases
-     * grow Skin-binding management and the per-frame skinning compute
-     * onto it.
-     *
-     * Lazy because it depends on {@link geometries}, which is assigned
-     * externally after this object's constructor returns
-     * (see {@link SceneManager}). The first access happens during
-     * {@link build}, which runs well after that assignment.
-     *
-     * @returns {GPUMeshSkinningContext}
-     */
-    get skinning() {
-        if (this.#skinning === null) {
-            this.#skinning = new GPUMeshSkinningContext({
-                geometries: this.geometries,
-                animation_manager: this.#animation_manager,
-                scene_context: this,
-                device: this.#device,
-            });
-        }
-        return this.#skinning;
-    }
-
-    get gpu_memory_usage(){
-        let r = 0;
-
-        r+= this.#scene_database.gpu_memory_usage;
-
-        r += this.#lights.gpu_memory_usage;
-        r += this.#light_probe_volume.gpu_memory_usage;
-        r += this.volumetric_light_map.gpu_memory_usage;
-
-        return r;
-    }
-
-    /**
-     * Grow the per-row mesh metadata to cover `size` rows. Never shrinks: rows are addresses, and a
-     * table that has held N rows can hand any of them out again.
-     *
-     * @param {number} size
-     */
-    #allocate_instances(size) {
-        const required = 2 * size;
-
-        if (this.#instance_metadata.length >= required) {
-            return;
-        }
-
-        const previous = this.#instance_metadata;
-
-        this.#instance_metadata = new Uint32Array(required);
-
-        typed_array_copy(previous, this.#instance_metadata);
-    }
-
-    /**
-     * World matrix last published for each `transforms` row, 16 floats at `row * 16`.
-     *
-     * The GPU hierarchy pass takes whatever is in a row's `global` at the start of the frame and
-     * moves it to `prev_global` before composing the new one, so what the CPU puts in `global` is
-     * only ever read as *last* frame's world matrix. Handing it the current one collapses the
-     * per-object velocity that motion vectors are derived from, which is why this cache exists
-     * rather than reading `node.transform_global` twice.
-     *
-     * @type {Float32Array}
-     */
-    #published_globals = new Float32Array();
-
-    /**
-     * Rows this context owns, by node. Also the answer to "is this node already in the database".
-     *
-     * @type {Map<Node3D, SceneNodeBinding>}
-     */
-    #bindings = new Map();
-
-    /**
-     * @type {number}
-     */
-    #epoch = 0;
-
-    /**
-     * @param {number} row
-     */
-    #reserve_published_global(row) {
-        const required = (row + 1) * 16;
-
-        if (this.#published_globals.length >= required) {
-            return;
-        }
-
-        const grown = new Float32Array(Math.max(required, this.#published_globals.length * 2));
-
-        typed_array_copy(this.#published_globals, grown);
-
-        this.#published_globals = grown;
-    }
-
-    /**
-     * Fill the shared record with `node`'s local TRS, the parent row, and the world matrix last
-     * published for `row` — see {@link #published_globals} for why that is the previous one and not
-     * the current one. Leaves `#published_globals` holding the node's current world matrix.
-     *
-     * @param {Node3D} node
-     * @param {number} row
-     * @param {number} parent_row
-     * @returns {object} the module-static record, valid until the next call
-     */
-    #write_transform_record(node, row, parent_row) {
-        // read through the scalar accessors: the `translation` / `rotation` / `scale` properties are
-        // live views, freshly allocated on every access, and this runs once per changed row per frame
-        const tl = node.transform_local;
-
-        TRANSFORM_RECORD.local_translation[0] = tl.translation_x;
-        TRANSFORM_RECORD.local_translation[1] = tl.translation_y;
-        TRANSFORM_RECORD.local_translation[2] = tl.translation_z;
-
-        TRANSFORM_RECORD.local_rotation[0] = tl.rotation_x;
-        TRANSFORM_RECORD.local_rotation[1] = tl.rotation_y;
-        TRANSFORM_RECORD.local_rotation[2] = tl.rotation_z;
-        TRANSFORM_RECORD.local_rotation[3] = tl.rotation_w;
-
-        TRANSFORM_RECORD.local_scale[0] = tl.scale_x;
-        TRANSFORM_RECORD.local_scale[1] = tl.scale_y;
-        TRANSFORM_RECORD.local_scale[2] = tl.scale_z;
-
-        this.#reserve_published_global(row);
-
-        const published = this.#published_globals;
-        const base = row * 16;
-
-        for (let i = 0; i < 16; i++) {
-            const previous = published[base + i];
-
-            TRANSFORM_RECORD.global[i] = previous;
-            TRANSFORM_RECORD.prev_global[i] = previous;
-        }
-
-        const current = node.transform_global;
-
-        for (let i = 0; i < 16; i++) {
-            published[base + i] = current[i];
-        }
-
-        TRANSFORM_RECORD.parent = parent_row;
-
-        return TRANSFORM_RECORD;
-    }
-
-    /**
-     * Seed a row's published world matrix with the node's current one, so the row's first write
-     * reports zero velocity instead of motion away from the origin.
-     *
-     * @param {Node3D} node
-     * @param {number} row
-     */
-    #seed_published_global(node, row) {
-        this.#reserve_published_global(row);
-
-        const current = node.transform_global;
-        const base = row * 16;
-
-        for (let i = 0; i < 16; i++) {
-            this.#published_globals[base + i] = current[i];
-        }
-    }
-
-    /**
-     * @param {Mesh} mesh
-     * @param {number} transform_row
-     * @returns {object} the module-static record, valid until the next call
-     */
-    #write_mesh_record(mesh, transform_row) {
-        // A skinned mesh's world bounds are a property of its *skeleton*, and the skeleton is not
-        // in the mesh's own subtree — Michelle's joint root is the mesh node's next sibling, which
-        // is the shape every glTF character has. `Node3D.updateMatrices` walks pre-order, so when
-        // the mesh's own bounds pass ran the joints it reads had not been visited yet and it
-        // described where the character stood before the move; a second walk would catch up, and
-        // nothing calls one. Re-deriving here costs a matrix per joint on a mesh that just moved,
-        // and here every walk is over — which is the only point at which the answer is knowable.
-        if (mesh.isSkinnedMesh === true) {
-            mesh.updateBoundsBasic();
-        }
-
-        // SkinnedMesh routes to its per-instance clone (allocated + cached by the skinning
-        // context); regular meshes get the source's id. obtain_geometry_index handles both,
-        // idempotent.
-        MESH_RECORD.geometry = this.skinning.obtain_geometry_index(mesh);
-        MESH_RECORD.material = mesh.material.id;
-        MESH_RECORD.node = transform_row;
-        MESH_RECORD.bounding_box = mesh.bounding_box;
-        MESH_RECORD.bounding_sphere = mesh.bounding_sphere;
-
-        return MESH_RECORD;
-    }
-
-    /**
-     * Which row of the `meshes` table a node occupies — **the value the visibility buffer writes
-     * for every pixel that node covers**, which is what makes it worth reading from outside.
-     *
-     * `id_mapping` is not this. That map goes from a node's id to its row in the `transforms`
-     * table, which is a different table with different rows; a caller that used it to index the
-     * visibility buffer would be reading somebody else's mesh.
-     *
-     * @param {Node3D} node
-     * @returns {number} the row, or `-1` for a node that is not in this scene or carries no geometry
-     */
-    mesh_row_of(node) {
-        const binding = this.#bindings.get(node);
-
-        return binding === undefined ? -1 : binding.mesh_row;
-    }
-
-    /**
-     * Bumped every time the `meshes` table gains or loses a row. **Rows are reused** — the table
-     * hands out the lowest free one — so a row read through {@link mesh_row_of} and kept is only
-     * valid while this number is unchanged. Anything holding one compares against its own copy and
-     * re-reads when they differ.
-     *
-     * @returns {number}
-     */
-    get mesh_rows_version() {
-        return this.#mesh_rows_version;
-    }
-
-    /**
-     * @see mesh_rows_version
-     * @type {number}
-     */
-    #mesh_rows_version = 0;
-
-    /**
-     * Parent's row if the parent is already in the database, the scene root otherwise. The fallback
-     * covers top-level nodes and parents that are not in this scene at all; a parent that is in the
-     * scene but not yet added is handled by the caller, which revisits the node once the sweep has
-     * placed everyone.
-     *
-     * @param {Node3D} node
-     * @returns {number}
-     */
-    #resolve_parent_row(node) {
-        const parent = node.parent;
-
-        if (parent === null) {
-            return NODE3D_SCENE_ID;
-        }
-
-        const row = this.id_mapping.get(parent.id);
-
-        return row !== undefined ? row : NODE3D_SCENE_ID;
-    }
-
-    /**
-     * Give a node rows in the database — one in `transforms`, plus one in `meshes` when it carries
-     * geometry.
-     *
-     * @param {Node3D} node
-     * @param {GPUTypedTable} transforms_table
-     * @param {GPUTypedTable} meshes_table
-     * @returns {SceneNodeBinding}
-     */
-    #add_node(node, transforms_table, meshes_table) {
-        const binding = new SceneNodeBinding();
-
-        const transform_row = this.#add_transform_row(node, this.#resolve_parent_row(node), transforms_table);
-
-        binding.transform_row = transform_row;
-        binding.version = node.version;
-        // Seeding a row is the CPU's job whoever owns it afterwards — the row has to exist and hold
-        // a starting pose before the GPU has written anything into it.
-        binding.authority = node.transform_authority;
-
-        this.id_mapping.set(node.id, transform_row);
-
-        if (node.isMesh === true) {
-            this.materials.obtain(node.material);
-
-            const mesh_row = meshes_table.add(this.#write_mesh_record(node, transform_row));
-
-            binding.mesh_row = mesh_row;
-
-            this.#mesh_rows_version++;
-
-            this.#allocate_instances(meshes_table.element_capacity);
-
-            this.#instance_metadata[mesh_row * 2] = node.id;
-            this.#instance_metadata[mesh_row * 2 + 1] = node.version;
-
-            this.#tlas.instance_add(mesh_row, node);
-        }
-
-        this.#bindings.set(node, binding);
-
-        return binding;
-    }
-
-    /**
-     * Allocate a `transforms` row for a node. The row is not known until the table hands one back,
-     * and the record has to carry that row's published world matrix — so the row is claimed first
-     * with a placeholder and written properly immediately after.
-     *
-     * @param {Node3D} node
-     * @param {number} parent_row
-     * @param {GPUTypedTable} transforms_table
-     * @returns {number}
-     */
-    #add_transform_row(node, parent_row, transforms_table) {
-        const row = transforms_table.add(EMPTY_TRANSFORM_RECORD);
-
-        this.#seed_published_global(node, row);
-
-        transforms_table.set(row, this.#write_transform_record(node, row, parent_row));
-
-        return row;
-    }
-
-    /**
-     * Take a node's rows back. The rows are freed, not reassigned — see {@link SceneNodeBinding}.
-     *
-     * @param {Node3D} node
-     * @param {SceneNodeBinding} binding
-     * @param {GPUTypedTable} transforms_table
-     * @param {GPUTypedTable} meshes_table
-     */
-    #remove_node(node, binding, transforms_table, meshes_table) {
-        if (node.isMesh === true) {
-            const mesh_row = binding.mesh_row;
-
-            meshes_table.remove(mesh_row);
-            this.#tlas.instance_remove(mesh_row);
-
-            this.#mesh_rows_version++;
-
-            this.#instance_metadata[mesh_row * 2] = 0;
-            this.#instance_metadata[mesh_row * 2 + 1] = 0;
-
-            // A skinned mesh renders a per-instance copy of its geometry, and the row just
-            // given back was the only thing naming it. This is where that copy — its vertex
-            // region, its BLAS and its prev-position slice — goes back too; nothing else in
-            // the engine sees a mesh leave, and unbinding deliberately does not free it.
-            if (node.isSkinnedMesh === true) {
-                this.skinning.release_clone(node);
-            }
-        }
-
-        transforms_table.remove(binding.transform_row);
-
-        this.id_mapping.delete(node.id);
-        this.#bindings.delete(node);
-    }
-
-    /**
-     * Bring the database's membership in line with the scene's: nodes that arrived get rows, nodes
-     * that left give theirs back. Runs only when the batch reports a change, so the per-frame path
-     * never pays for it.
-     *
-     * @param {GPUTypedTable} transforms_table
-     * @param {GPUTypedTable} meshes_table
-     * @returns {number} rows written
-     */
-    #sync_membership(transforms_table, meshes_table) {
-        const epoch = ++this.#epoch;
-
-        let written = 0;
-
-        const scene = this.#scene;
-
-        // The scene root must land at row 0 — it is both the hierarchy walk's terminator and the
-        // natural value of any zero-initialised buffer.
-        let scene_binding = this.#bindings.get(scene);
-
-        if (scene_binding === undefined) {
-            scene_binding = this.#add_node(scene, transforms_table, meshes_table);
-
-            assert.equal(scene_binding.transform_row, NODE3D_SCENE_ID, 'scene must land at transforms table row 0');
-
-            written++;
-        }
-
-        scene_binding.epoch = epoch;
-
-        const nodes = this.#scene.instances.nodes;
-        const node_count = nodes.length;
-
-        // Nodes whose parent had not been placed when they were. `Scene.add` walks parents before
-        // children, so this is empty unless a caller added a child to the scene ahead of its
-        // parent.
-        const orphaned = [];
-
-        for (let i = 0; i < node_count; i++) {
-            const node = nodes[i];
-
-            let binding = this.#bindings.get(node);
-
-            if (binding === undefined) {
-                binding = this.#add_node(node, transforms_table, meshes_table);
-
-                written++;
-
-                if (node.parent !== null && this.id_mapping.get(node.parent.id) === undefined) {
-                    orphaned.push(node);
-                }
-            }
-
-            binding.epoch = epoch;
-        }
-
-        for (let i = 0; i < orphaned.length; i++) {
-            const node = orphaned[i];
-            const parent_row = this.id_mapping.get(node.parent.id);
-
-            if (parent_row === undefined) {
-                // the parent really is not in this scene — the scene root stands
-                continue;
-            }
-
-            const binding = this.#bindings.get(node);
-
-            transforms_table.set(
-                binding.transform_row,
-                this.#write_transform_record(node, binding.transform_row, parent_row)
-            );
-        }
-
-        for (const [node, binding] of this.#bindings) {
-            if (binding.epoch !== epoch) {
-                this.#remove_node(node, binding, transforms_table, meshes_table);
-
-                written++;
-            }
-        }
-
-        return written;
-    }
-
-    /**
-     * Push every node that has moved since its row was last written, and nothing else.
-     *
-     * Rows the GPU owns are left alone entirely — see {@link TransformAuthority}. Their nodes still
-     * report movement (a CPU-driven parent recursing through `updateMatrices` is enough to mark
-     * every joint under it), and acting on that report is exactly the collision authority exists to
-     * prevent.
-     *
-     * @param {GPUTypedTable} transforms_table
-     * @param {GPUTypedTable} meshes_table
-     * @returns {number} rows written
-     */
-    #sync_transforms(transforms_table, meshes_table) {
-        let written = 0;
-
-        for (const [node, binding] of this.#bindings) {
-            const authority = node.transform_authority;
-            const handed_back = authority !== binding.authority && authority === TransformAuthority.CPU;
-
-            binding.authority = authority;
-
-            if (authority === TransformAuthority.GPU) {
-                continue;
-            }
-
-            const version = node.version;
-
-            // A row just handed back has to be written whatever the version says: nothing moved it
-            // while the GPU held it, so there is no change to notice, and the row it is taking over
-            // holds a pose the CPU never wrote.
-            if (version === binding.version && !handed_back) {
-                continue;
-            }
-
-            if (handed_back) {
-                // Taking over from an unknown pose — seed the published matrix the way a fresh row
-                // is seeded, so the first frame back reports no velocity rather than a jump.
-                this.#seed_published_global(node, binding.transform_row);
-            }
-
-            binding.version = version;
-            written++;
-
-            const transform_row = binding.transform_row;
-
-            transforms_table.set(
-                transform_row,
-                this.#write_transform_record(node, transform_row, this.#resolve_parent_row(node))
-            );
-
-            if (node.isMesh !== true) {
-                continue;
-            }
-
-            // World-space bounds moved with the node, and culling reads them off the mesh row.
-            const mesh_row = binding.mesh_row;
-
-            meshes_table.set(mesh_row, this.#write_mesh_record(node, transform_row));
-
-            this.#instance_metadata[mesh_row * 2 + 1] = version;
-
-            this.#tlas.instance_update(mesh_row, node);
-        }
-
-        return written;
-    }
-
-    /**
-     * Bring the GPU scene database in line with the scene, writing only the rows that changed.
-     *
-     * Membership is reconciled when the batch says it moved; transforms are checked every frame,
-     * because a node moving does not touch the batch. Both walk the scene once and write nothing
-     * for a node that has not changed.
-     */
-    build() {
-
-        const batch = this.#scene.instances;
-
-        const meshes_table = this.#scene_database.get('meshes');
-        const transforms_table = this.#scene_database.get('transforms');
-
-        let written = 0;
-
-        if (this.#instances_version !== batch.version) {
-            written += this.#sync_membership(transforms_table, meshes_table);
-
-            this.#instances_version = batch.version;
-        }
-
-        written += this.#sync_transforms(transforms_table, meshes_table);
-
-        if (written === 0) {
-            return;
-        }
-
-        // Flush the scene database — only the rows that changed carry an upload record.
-        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/database-build');
-
-        // Also flush the global geometry manager. The first time a scene
-        // sees a new mesh, scene.build's `obtain_geometry_index` calls
-        // `geometries.add(...)` which registers the source MeshletGeometry
-        // and flips `geometries.__needs_update = true`. The next per-frame
-        // `graphics.update()` would normally rebuild
-        // `geometries.buffer_metadata` to reflect those new entries — but
-        // `graphics.update()` runs at the *head* of `Renderer.#begin_frame`,
-        // *before* this scene.build, so the buffer_metadata stays whatever
-        // it was at the start of the frame (often the zero-record placeholder
-        // from the renderer's startup build, when the scene's geometries
-        // hadn't been registered yet).
-        //
-        // Any pass reading `geometries[mesh.geometry]` later in the frame
-        // (rasterization meshlet expansion, `shader_refresh_all_mesh_bounds`,
-        // etc.) sees zeros — `meshlets_count = 0` produces no triangles and
-        // `bounding_box = (0,0,0)-(0,0,0)` collapses world bounds to a
-        // single point in `shader_refresh_all_mesh_bounds`, which then writes
-        // those collapsed bounds back into `meshes_table`. Subsequent frames
-        // get a correct `buffer_metadata` from the next `graphics.update()`,
-        // but the `meshes_table` bounds stay collapsed until refresh_all
-        // overwrites them again — and frustum cull on the collapsed bounds
-        // can drop meshes whose collapsed point sits outside the frustum.
-        //
-        // Symptom: stress test rendered ground (whose collapsed point at the
-        // origin survives the cull) but dropped most trees (whose collapsed
-        // points scattered across the grid trigger cull edge cases).
-        //
-        // Calling `geometries.update(cmd)` here ensures the new buffer is in
-        // place before any pass in the same frame reads it. Idempotent / no-op
-        // when nothing's queued, so the per-frame `graphics.update` head call
-        // and this build-time call together leave the buffer in the right
-        // state under both lifetimes.
-        this.geometries.update(cmd);
-
-        this.#scene_database.update(cmd);
-        cmd.finish();
-    }
-
-    /**
-     *
-     * @param {GraphicsContext} ctx
-     */
-    update(ctx) {
-        assert.defined(ctx, 'ctx');
-
-        // TODO add a fast update check, so that calling this multiple times per frame can be fast.
-
-        this.#light_probe_volume.update();
-        this.#lights.update(ctx);
-        this.#volumetrics.update(ctx, 0);
-
-        // Per-frame animation database flush — picks up any new clips,
-        // tracks, skins, or per-frame `set_time` writes queued since
-        // last frame. Idempotent / cheap when nothing's queued.
-        const animation_cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/animation-flush');
-        this.#animation_manager.update(animation_cmd);
-        animation_cmd.finish();
-
-        // TODO update SDF
-
-        this.build();
-
-        // After the build, which is what feeds the TLAS this frame's arrivals, departures and moves —
-        // and, for the GPU build, writes the world AABBs it reads out of the `meshes` table.
-        this.#tlas.update(this.scene_database_buffer);
-    }
-
-    /**
-     * Per-frame animation tick — drains pending registrations,
-     * advances `clip.time` on the GPU, runs apply → resolve →
-     * hierarchy propagate → skin-matrix prep → skinning. Thin
-     * passthrough to {@link GPUAnimationManager#tick}; lives here
-     * so the renderer can call it on every scene it renders without
-     * reaching past `GPUSceneContext` for an internal manager.
-     *
-     * `dt_seconds` is wall-clock seconds since the last call (the
-     * renderer's `time_delta_seconds` argument to `render()`).
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     * @param {number} dt_seconds wall-clock seconds since last call
-     */
-    tick(cmd_ctx, dt_seconds) {
-        this.#animation_manager.tick(cmd_ctx, dt_seconds);
-    }
-
-    destroy() {
-        this.#scene_database.destroy();
-        this.#lights.destroy();
-        this.#light_probe_volume.destroy();
-        this.#animation_manager.destroy();
-        if (this.#skinning !== null) {
-            this.#skinning.destroy();
-        }
-    }
-
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-GPUSceneContext.prototype.isGPUSceneContext = true;
+import { assert } from "../../../core/assert.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import { Brick4LightMap } from "../global_illumination/brick4/Brick4LightMap.js";
+import { GPULightProbeVolume } from "../global_illumination/lpv/GPULightProbeVolume.js";
+import { GPULightCollection } from "../light/GPULightCollection.js";
+import { GPUSceneVolumetrics } from "../volumetrics/GPUSceneVolumetrics.js";
+import { Scene } from "./Scene.js";
+import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
+import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";
+import {
+    shader_refresh_all_mesh_bounds,
+    WORKGROUP_SIZE as REFRESH_ALL_MESH_BOUNDS_WORKGROUP_SIZE
+} from "../object_property/shader_refresh_all_mesh_bounds.js";
+import { GPUEntityBoundsReadback } from "./rows/GPUEntityBoundsReadback.js";
+import { GPUSceneRows } from "./rows/GPUSceneRows.js";
+import { generate_record_writer } from "../buffer/table/serde/generate_record_writer.js";
+import { NODE3D_SCENE_ID, NODE3D_STRUCT } from "./NODE3D_STRUCT.js";
+import { SCENE_DATABASE_SPEC } from "./SCENE_DATABASE_SPEC.js";
+
+/**
+ * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../geometry/GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
+ * @typedef {import("../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
+ * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
+ */
+
+
+let id_counter = 0;
+
+/**
+ * Row 0 of the `transforms` table: the scene root. Identity, and its own parent — which is what the
+ * hierarchy pass takes as "no further ancestor" — so an entity whose attachment names no entity
+ * with a row is posed under it in world space, and the composition is exact. Written once, at the
+ * first {@link GPUSceneContext.build}, so it goes up with the first rows rather than being left to
+ * whatever the buffer held.
+ */
+const ROOT_RECORD = {
+    local_translation: new Float32Array([0, 0, 0]),
+    local_rotation: new Float32Array([0, 0, 0, 1]),
+    local_scale: new Float32Array([1, 1, 1]),
+    global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+    prev_global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+    parent: NODE3D_SCENE_ID,
+};
+
+/**
+ * @type {GPURecordWriter}
+ */
+const ROOT_RECORD_WRITER = generate_record_writer(NODE3D_STRUCT);
+
+/**
+ * What a scene with no rows draws with.
+ *
+ * @type {ShadeMaterial[]}
+ */
+const NO_MATERIALS = Object.freeze([]);
+
+/**
+ * The GPU side of one {@link Scene}: its database — the `transforms` and `meshes` tables, one row
+ * per entity that is drawn or posed, at `entity + 1` — and what is built over that database each
+ * frame: the lights' records, the probe volume, the volumetrics, the animation, the TLAS.
+ *
+ * Nothing here holds a hierarchy of its own. An entity's row names its parent's row and the GPU
+ * composes the chain each frame, derives every mesh row's bounds under the composed matrix and
+ * builds the tree over them — see {@link tick}. What the CPU writes is what it owns: an entity's
+ * local TRS and the row of its parent, through {@link rows}.
+ */
+export class GPUSceneContext {
+
+    /**
+     * @readonly
+     * @type {number}
+     */
+    id = id_counter++;
+
+    /**
+     * @type {GPUGeometryManager}
+     */
+    geometries;
+
+    /**
+     * @type {GPUMaterialManager}
+     */
+    materials;
+
+
+    /**
+     * @type {Brick4LightMap}
+     */
+    volumetric_light_map;
+
+
+    /**
+     *
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     *
+     * @return {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    /**
+     * @type {GPUSceneVolumetrics}
+     */
+    #volumetrics;
+
+    get volumetrics() {
+        return this.#volumetrics;
+    }
+
+    /**
+     * @type {GPULightCollection}
+     */
+    #lights;
+
+
+    /**
+     *
+     * @returns {GPULightCollection}
+     */
+    get lights() {
+        return this.#lights;
+    }
+
+    /**
+     * @type {GPULightProbeVolume}
+     */
+    #light_probe_volume;
+
+    /**
+     *
+     * @returns {GPULightProbeVolume}
+     */
+    get light_probe_volume() {
+        return this.#light_probe_volume;
+    }
+
+    /**
+     * @type {GPUInstancesAccelerationStructure}
+     */
+    #tlas
+
+    /**
+     *
+     * @returns {GPUInstancesAccelerationStructure}
+     */
+    get tlas() {
+        return this.#tlas;
+    }
+
+    /**
+     * GPU-resident scene database — mesh metadata in the `meshes` table,
+     * transforms in the `transforms` table, one row per entity in each.
+     * Consumers bind `scene_database.buffer` as `array<u32>` and read
+     * records via `scene_read_mesh` / `scene_read_node` (see
+     * `chunk_scene_database_access`).
+     *
+     * @type {GPUDatabase}
+     */
+    #scene_database;
+
+    /**
+     * Entities as rows of {@link scene_database} — see {@link rows}. Built the first time it is
+     * asked for, which needs the scene to name its dataset by then.
+     *
+     * @type {GPUSceneRows|null}
+     */
+    #rows = null;
+
+    /**
+     * Whether {@link ROOT_RECORD} has been written to row 0 — once, at the first build.
+     *
+     * @type {boolean}
+     */
+    #root_written = false;
+
+    /**
+     * Per-scene skinning state — clone-index cache today, plus
+     * Skin-bindings and the per-frame skinning compute dispatch in
+     * later phases. Lazily constructed because it depends on
+     * {@link geometries}, which {@link SceneManager#create} assigns
+     * externally after this constructor runs. See {@link skinning} for
+     * access.
+     *
+     * @type {GPUMeshSkinningContext|null}
+     */
+    #skinning = null;
+
+    /**
+     * Per-scene animation system — clips, tracks, curves, skins, and
+     * the skin-matrix scratch buffer. Owned here (rather than passed
+     * in) so that consumers fetching `gpu_scene.animation_manager`
+     * always see the same instance, and so per-frame database flush
+     * can be wired into {@link update} alongside the rest of the
+     * scene's bookkeeping.
+     *
+     * @type {GPUAnimationManager}
+     */
+    #animation_manager;
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        assert.defined(scene, 'scene');
+        assert.isObject(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        const device = graphics.device;
+
+        this.#scene = scene;
+        this.#device = device;
+        this.#graphics = graphics;
+
+        this.#tlas = new GPUInstancesAccelerationStructure(graphics);
+
+        // Pass `this` so the light collection (and its child shadow context) can use
+        // this scene's GPUSceneContext when building its own ViewManager — avoids
+        // threading the renderer-level ViewManager / SceneManager through every layer.
+        this.#lights = new GPULightCollection(graphics, this);
+
+        this.#scene_database = new GPUDatabase({
+            device,
+            definition: SCENE_DATABASE_SPEC,
+            label: "GPUSceneContext/Database",
+        });
+
+        this.#light_probe_volume = new GPULightProbeVolume(device, scene.light_probe_volume);
+
+        this.volumetric_light_map = new Brick4LightMap(device);
+
+        this.#volumetrics = new GPUSceneVolumetrics(device, scene.volumetrics);
+
+        this.#animation_manager = new GPUAnimationManager(device, `GPUSceneContext[${this.id}]/Animation`, this);
+    }
+
+    /**
+     * @returns {GPUAnimationManager}
+     */
+    get animation_manager() {
+        return this.#animation_manager;
+    }
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     *
+     * @returns {GPUDatabase}
+     */
+    get scene_database() {
+        return this.#scene_database;
+    }
+
+    /**
+     * The underlying buffer that backs {@link scene_database} — bind this
+     * as `array<u32>` in shaders that read mesh / transform records.
+     *
+     * @returns {GPUBuffer}
+     */
+    get scene_database_buffer() {
+        return this.#scene_database.buffer;
+    }
+
+    /**
+     * Per-scene skinning subsystem. Routes skinned rows through
+     * per-instance geometry clones; later phases grow Skin-binding
+     * management and the per-frame skinning compute onto it.
+     *
+     * Lazy because it depends on {@link geometries}, which is assigned
+     * externally after this object's constructor returns
+     * (see {@link SceneManager}). The first access happens during
+     * {@link build}, which runs well after that assignment.
+     *
+     * @returns {GPUMeshSkinningContext}
+     */
+    get skinning() {
+        if (this.#skinning === null) {
+            this.#skinning = new GPUMeshSkinningContext({
+                geometries: this.geometries,
+                animation_manager: this.#animation_manager,
+                scene_context: this,
+                device: this.#device,
+            });
+        }
+        return this.#skinning;
+    }
+
+    get gpu_memory_usage(){
+        let r = 0;
+
+        r+= this.#scene_database.gpu_memory_usage;
+
+        r += this.#lights.gpu_memory_usage;
+        r += this.#light_probe_volume.gpu_memory_usage;
+        r += this.volumetric_light_map.gpu_memory_usage;
+
+        return r;
+    }
+
+    /**
+     * Entities as rows of the scene database, at `entity + 1` in both tables.
+     *
+     * A system that places an entity acquires its row here and marks it on the dataset's change
+     * events; a scene with no systems places through `prefab_place` and `place_primitive`, which
+     * do the same by hand; and {@link build} flushes what was marked. The scene has to name its
+     * dataset ({@link Scene.dataset}) before this is first asked for, because the rows are written
+     * from that dataset's components.
+     *
+     * @returns {GPUSceneRows}
+     */
+    get rows() {
+        return this.#obtain_rows();
+    }
+
+    /**
+     * An entity's world bounds as the GPU holds them, read back — what a consumer that wants the
+     * box that is drawn asks, a frame or two behind the device. Built on demand, over the rows.
+     *
+     * @returns {GPUEntityBoundsReadback}
+     */
+    get bounds() {
+        if (this.#bounds === null) {
+            this.#bounds = new GPUEntityBoundsReadback(this.#scene_database.readback, this.rows);
+        }
+
+        return this.#bounds;
+    }
+
+    /**
+     * @type {GPUEntityBoundsReadback|null}
+     */
+    #bounds = null;
+
+    /**
+     * Every material something in the scene draws with, each once — the rows' own list, kept
+     * current as meshes attach and detach. What the rasterizers iterate to decide which buckets
+     * and pipelines a frame needs. The array is reused until the set changes; a scene with no
+     * rows draws with nothing.
+     *
+     * @returns {ShadeMaterial[]}
+     */
+    get drawn_materials() {
+        return this.#rows === null ? NO_MATERIALS : this.#rows.materials;
+    }
+
+    /**
+     * @returns {GPUSceneRows}
+     */
+    #obtain_rows() {
+        if (this.#rows === null) {
+            const dataset = this.#scene.dataset;
+
+            assert.notNull(dataset, 'the scene names no dataset — set Scene.dataset before asking for its rows');
+            assert.defined(dataset, 'the scene names no dataset — set Scene.dataset before asking for its rows');
+
+            this.#rows = new GPUSceneRows({
+                dataset,
+                transforms: this.#scene_database.get('transforms'),
+                meshes: this.#scene_database.get('meshes'),
+                geometries: this.geometries,
+                materials: this.materials,
+                tlas: this.#tlas,
+                skinning: () => this.skinning,
+            });
+        }
+
+        return this.#rows;
+    }
+
+    /**
+     * Bring the GPU scene database in line with the scene, writing only the rows that changed:
+     * the scene root's, once; a light's, as it arrives; and every entity's row that a system
+     * marked since the last build. Nothing is walked — the rows keep what was marked.
+     */
+    build() {
+        let written = 0;
+
+        if (!this.#root_written) {
+            this.#scene_database.get('transforms').set_record(NODE3D_SCENE_ID, ROOT_RECORD, ROOT_RECORD_WRITER);
+
+            this.#root_written = true;
+            written++;
+        }
+
+        // Entities are rows — marked by the systems that place them, written here. Built on demand
+        // because the scene may name its dataset after this context was made.
+        if (this.#rows === null && this.#scene.dataset !== null && this.#scene.dataset !== undefined) {
+            this.rows;
+        }
+
+        if (this.#rows !== null) {
+            // A light is an entity's row, held here on the light collection's behalf — before the
+            // flush, so a light that arrived this frame is written this frame.
+            this.#lights.sync_rows(this.#rows);
+
+            written += this.#rows.flush();
+        } else {
+            assert.equal(this.#scene.lights.elements.length, 0, 'the scene has lights and names no dataset; a light is an entity of one');
+        }
+
+        if (written === 0) {
+            return;
+        }
+
+        // Flush the scene database — only the rows that changed carry an upload record.
+        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/database-build');
+
+        // Also flush the global geometry manager. The first time a scene
+        // sees a new mesh, the rows' flush calls `geometries.add(...)`,
+        // which registers the source MeshletGeometry and flips
+        // `geometries.__needs_update = true`. The next per-frame
+        // `graphics.update()` would normally rebuild
+        // `geometries.buffer_metadata` to reflect those new entries — but
+        // `graphics.update()` runs at the *head* of `Renderer.#begin_frame`,
+        // *before* this scene.build, so the buffer_metadata stays whatever
+        // it was at the start of the frame (often the zero-record placeholder
+        // from the renderer's startup build, when the scene's geometries
+        // hadn't been registered yet).
+        //
+        // Any pass reading `geometries[mesh.geometry]` later in the frame
+        // (rasterization meshlet expansion, `shader_refresh_all_mesh_bounds`,
+        // etc.) sees zeros — `meshlets_count = 0` produces no triangles and
+        // `bounding_box = (0,0,0)-(0,0,0)` collapses world bounds to a
+        // single point in `shader_refresh_all_mesh_bounds`, which then writes
+        // those collapsed bounds back into `meshes_table`. Subsequent frames
+        // get a correct `buffer_metadata` from the next `graphics.update()`,
+        // but the `meshes_table` bounds stay collapsed until refresh_all
+        // overwrites them again — and frustum cull on the collapsed bounds
+        // can drop meshes whose collapsed point sits outside the frustum.
+        //
+        // Symptom: stress test rendered ground (whose collapsed point at the
+        // origin survives the cull) but dropped most trees (whose collapsed
+        // points scattered across the grid trigger cull edge cases).
+        //
+        // Calling `geometries.update(cmd)` here ensures the new buffer is in
+        // place before any pass in the same frame reads it. Idempotent / no-op
+        // when nothing's queued, so the per-frame `graphics.update` head call
+        // and this build-time call together leave the buffer in the right
+        // state under both lifetimes.
+        this.geometries.update(cmd);
+
+        this.#scene_database.update(cmd);
+        cmd.finish();
+    }
+
+    /**
+     *
+     * @param {GraphicsContext} ctx
+     */
+    update(ctx) {
+        assert.defined(ctx, 'ctx');
+
+        // TODO add a fast update check, so that calling this multiple times per frame can be fast.
+
+        // The apply point of the scene database's readback: whatever the device has answered since
+        // — an entity's drawn bounds, asked for through {@link bounds} — is delivered before
+        // anything this frame reads it, and never mid-update.
+        this.#scene_database.readback.apply();
+
+        this.#light_probe_volume.update();
+        this.#lights.update(ctx);
+        this.#volumetrics.update(ctx, 0);
+
+        // Per-frame animation database flush — picks up any new clips,
+        // tracks, skins, or per-frame `set_time` writes queued since
+        // last frame. Idempotent / cheap when nothing's queued.
+        const animation_cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/animation-flush');
+        this.#animation_manager.update(animation_cmd);
+        animation_cmd.finish();
+
+        // TODO update SDF
+
+        this.build();
+    }
+
+    /**
+     * Per-frame GPU-side scene update, once per scene per frame, after every view's {@link update}
+     * has flushed what the CPU changed:
+     *
+     * 1. the animation tick — pending registrations drained, `clip.time` advanced, apply → resolve
+     *    → hierarchy propagate → skin-matrix prep → skinning, through {@link GPUAnimationManager#tick};
+     * 2. render bounds — every mesh row's world box and sphere, derived from its geometry under
+     *    the `global` the hierarchy pass just composed, because the CPU does not hold that matrix
+     *    for a subtree the GPU drives;
+     * 3. light poses — every light record's position and direction, from its entity's row, for
+     *    the same reason;
+     * 4. the TLAS — rebuilt from those bounds when anything moved, on either side.
+     *
+     * All four into `cmd_ctx`, in that order, so the tree the frame's ray passes traverse is built
+     * over this frame's bounds rather than last frame's, and what lights the frame is where it is
+     * this frame.
+     *
+     * `dt_seconds` is wall-clock seconds since the last call (the renderer's `time_delta_seconds`
+     * argument to `render()`).
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     * @param {number} dt_seconds wall-clock seconds since last call
+     */
+    tick(cmd_ctx, dt_seconds) {
+        const animated = this.#animation_manager.tick(cmd_ctx, dt_seconds);
+
+        this.#refresh_mesh_bounds(cmd_ctx);
+
+        this.#lights.refresh_poses(cmd_ctx, this.scene_database_buffer);
+
+        if (animated) {
+            // Rows moved on the GPU, where no version was bumped: a clip resolved into a TRS, a
+            // skinning pass moved a clone's vertices. The bounds pass just re-derived their boxes,
+            // and the tree is built over boxes.
+            this.#tlas.invalidate();
+        }
+
+        this.#tlas.update(this.scene_database_buffer, cmd_ctx);
+
+        // What was asked of the scene database this frame is copied out at the tail of the
+        // database's own update when rows were written this frame, and here — after the bounds
+        // pass — when none were; either way what lands, at the head of a later frame's update, is
+        // the box the GPU held when the copy ran.
+        this.#scene_database.readback.encode(cmd_ctx);
+    }
+
+    /**
+     * Recompute every mesh row's world bounds from its geometry under its composed `global`.
+     * Skipped when there is no mesh row; otherwise one thread per slot of the `meshes` table's
+     * pages, occupancy-masked.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    #refresh_mesh_bounds(cmd_ctx) {
+        const meshes_table = this.#scene_database.get('meshes');
+
+        const group_count = meshes_table.dispatch_group_count(REFRESH_ALL_MESH_BOUNDS_WORKGROUP_SIZE);
+
+        if (group_count === 0) {
+            return;
+        }
+
+        const geometries = this.geometries.buffer_metadata;
+
+        if (geometries === null) {
+            // a mesh row names a geometry, and a geometry is registered before its row is written
+            // — so this is a scene whose first frame has not flushed the geometry manager yet
+            return;
+        }
+
+        shader_refresh_all_mesh_bounds.dispatch({
+            encoder: cmd_ctx,
+            group_count_x: group_count,
+            bindings: {
+                scene_database: this.scene_database_buffer,
+                geometries,
+            },
+        });
+    }
+
+    destroy() {
+        if (this.#rows !== null) {
+            this.#rows.destroy();
+        }
+
+        this.#scene_database.destroy();
+        this.#lights.destroy();
+        this.#light_probe_volume.destroy();
+        this.#animation_manager.destroy();
+        if (this.#skinning !== null) {
+            this.#skinning.destroy();
+        }
+    }
+
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+GPUSceneContext.prototype.isGPUSceneContext = true;