@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -1,5 +1,6 @@
+import { GPUVirtualGeometryPool } from "../geometry/virtual/runtime/GPUVirtualGeometryPool.js";
+import { GPUVirtualGeometryRuntime } from "../geometry/virtual/runtime/GPUVirtualGeometryRuntime.js";
 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";
@@ -10,63 +11,64 @@ 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 {
+    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";
-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
+ * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
  */
 
 
 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.
+ * 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 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),
+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,
 };
 
 /**
- * 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.
+ * @type {GPURecordWriter}
  */
-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,
-};
+const ROOT_RECORD_WRITER = generate_record_writer(NODE3D_STRUCT);
 
 /**
- * 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.
+ * What a scene with no rows draws with.
+ *
+ * @type {ShadeMaterial[]}
  */
-const MESH_RECORD = {
-    geometry: 0,
-    material: 0,
-    node: NODE3D_SCENE_ID,
-    bounding_box: undefined,
-    bounding_sphere: undefined,
-};
+const NO_MATERIALS = Object.freeze([]);
 
 /**
- * Abstraction on the context of a scene, there are no hierarchies, just a collection of meshes and a geometry context
+ * 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 {
 
@@ -158,37 +160,29 @@ export class GPUSceneContext {
 
     /**
      * 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`).
+     * 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 {Uint32Array}
+     * @type {GPUSceneRows|null}
      */
-    #instance_metadata = new Uint32Array();
+    #rows = null;
 
     /**
-     * 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.
+     * Whether {@link ROOT_RECORD} has been written to row 0 — once, at the first build.
      *
-     * @type {Map<number, number>}
+     * @type {boolean}
      */
-    id_mapping = new Map();
+    #root_written = false;
 
     /**
      * Per-scene skinning state — clone-index cache today, plus
@@ -252,6 +246,57 @@ export class GPUSceneContext {
         this.#animation_manager = new GPUAnimationManager(device, `GPUSceneContext[${this.id}]/Animation`, this);
     }
 
+    /**
+     * The virtual-geometry runtime, once something has asked for one.
+     *
+     * `undefined` until {@link enable_virtual_geometry}, and every rasterization path treats that
+     * as "there is no virtual geometry in this scene" and skips the cut entirely. Opt-in rather
+     * than always-on because the pool owns real buffers — a page arena, a page table, a per-asset
+     * lookup — and a scene of ordinary meshes should not pay for them.
+     *
+     * @type {GPUVirtualGeometryRuntime|undefined}
+     */
+    #virtual_geometry;
+
+    /**
+     * @returns {GPUVirtualGeometryRuntime|undefined}
+     */
+    get virtual_geometry() {
+        return this.#virtual_geometry;
+    }
+
+    /**
+     * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
+     * draws.
+     *
+     * Sharing the pool is the whole seam on this side: a cut emits `MESHLET_DEFINITION_STRUCT`
+     * records naming rows of the same metadata buffer a static mesh's meshlets live in, so nothing
+     * downstream of the expansion has to know which kind of geometry it is looking at.
+     *
+     * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
+     *     {@link GPUVirtualGeometryRuntime}
+     * @returns {GPUVirtualGeometryRuntime}
+     */
+    enable_virtual_geometry(options = {}) {
+        if (this.#virtual_geometry !== undefined) {
+            return this.#virtual_geometry;
+        }
+
+        const pool = new GPUVirtualGeometryPool({
+            device: this.#device,
+            meshlets: this.geometries.meshlets,
+            ...options,
+        });
+
+        this.#virtual_geometry = new GPUVirtualGeometryRuntime({
+            pool,
+            device: this.#device,
+            ...options,
+        });
+
+        return this.#virtual_geometry;
+    }
+
     /**
      * @returns {GPUAnimationManager}
      */
@@ -259,9 +304,6 @@ export class GPUSceneContext {
         return this.#animation_manager;
     }
 
-    #instances_version = -1;
-
-
     /**
      * @type {GPUDevice}
      */
@@ -291,10 +333,9 @@ export class GPUSceneContext {
     }
 
     /**
-     * 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.
+     * 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
@@ -328,495 +369,106 @@ export class GPUSceneContext {
     }
 
     /**
-     * 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.
+     * Entities as rows of the scene database, at `entity + 1` in both tables.
      *
-     * @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.
+     * 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.
      *
-     * @param {Node3D} node
-     * @param {number} row
-     * @param {number} parent_row
-     * @returns {object} the module-static record, valid until the next call
+     * @returns {GPUSceneRows}
      */
-    #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;
+    get rows() {
+        return this.#obtain_rows();
     }
 
     /**
-     * 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.
+     * 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.
      *
-     * @param {Node3D} node
-     * @param {number} row
+     * @returns {GPUEntityBoundsReadback}
      */
-    #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();
+    get bounds() {
+        if (this.#bounds === null) {
+            this.#bounds = new GPUEntityBoundsReadback(this.#scene_database.readback, this.rows);
         }
 
-        // 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;
+        return this.#bounds;
     }
 
     /**
-     * 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}
+     * @type {GPUEntityBoundsReadback|null}
      */
-    #mesh_rows_version = 0;
+    #bounds = null;
 
     /**
-     * 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.
+     * 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.
      *
-     * @param {Node3D} node
-     * @returns {number}
+     * @returns {ShadeMaterial[]}
      */
-    #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;
+    get drawn_materials() {
+        return this.#rows === null ? NO_MATERIALS : this.#rows.materials;
     }
 
     /**
-     * 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}
+     * @returns {GPUSceneRows}
      */
-    #add_transform_row(node, parent_row, transforms_table) {
-        const row = transforms_table.add(EMPTY_TRANSFORM_RECORD);
-
-        this.#seed_published_global(node, row);
+    #obtain_rows() {
+        if (this.#rows === null) {
+            const dataset = this.#scene.dataset;
 
-        transforms_table.set(row, this.#write_transform_record(node, row, parent_row));
+            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');
 
-        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);
-            }
+            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,
+            });
         }
 
-        transforms_table.remove(binding.transform_row);
-
-        this.id_mapping.delete(node.id);
-        this.#bindings.delete(node);
+        return this.#rows;
     }
 
     /**
-     * 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
+     * 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.
      */
-    #sync_membership(transforms_table, meshes_table) {
-        const epoch = ++this.#epoch;
-
+    build() {
         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');
+        if (!this.#root_written) {
+            this.#scene_database.get('transforms').set_record(NODE3D_SCENE_ID, ROOT_RECORD, ROOT_RECORD_WRITER);
 
+            this.#root_written = true;
             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);
+        // 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;
         }
 
-        return written;
-    }
+        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);
 
-    /**
-     * 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.#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');
         }
 
-        written += this.#sync_transforms(transforms_table, meshes_table);
-
         if (written === 0) {
             return;
         }
@@ -825,9 +477,9 @@ export class GPUSceneContext {
         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
+        // 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`,
@@ -871,6 +523,11 @@ export class GPUSceneContext {
 
         // 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);
@@ -885,31 +542,93 @@ export class GPUSceneContext {
         // 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.
+     * 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.
      *
-     * `dt_seconds` is wall-clock seconds since the last call (the
-     * renderer's `time_delta_seconds` argument to `render()`).
+     * 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) {
-        this.#animation_manager.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();