@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,901 +1,901 @@
-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";
-
-
-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(device);
-
-        // 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) {
-        // 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;
-        }
-
-        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.
-        this.#tlas.update();
-    }
-
-    /**
-     * 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 { 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";
+
+
+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(device);
+
+        // 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) {
+        // 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;
+        }
+
+        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.
+        this.#tlas.update();
+    }
+
+    /**
+     * 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;