@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/extension/RenderExtensionRegistry.d.ts

@@ -2,9 +2,9 @@
  * The extensions an outside caller has put into a frame, kept per {@link FramePhase} in the order
  * their declarations resolve to.
  *
- * Device-free on purpose: this is the part of the mechanism with rules — ordering, cycles, removal,
- * what a recording scope is around — and keeping it out of the renderer means those rules can be
- * stated and tested without standing up a GPU.
+ * Device-free on purpose: this is the part of the mechanism with rules — ordering, removal, what a
+ * recording scope is around — and keeping it out of the renderer means those rules can be stated
+ * and tested without standing up a GPU.
  *
  * **The graph does not order extensions; this does.** `FrameGraph.execute` iterates its passes in
  * insertion order and does not sort, and `validate()` checks only that such an order is
@@ -15,8 +15,8 @@ export class RenderExtensionRegistry {
     /**
      * Register `extension` to record when its phase comes round.
      *
-     * The resolved order is computed here, so a cycle in the declarations fails at the registration
-     * that closed it, naming what it is made of. Registration order itself decides nothing.
+     * `relative_order` is read here, once. Moving an extension after it is registered means taking
+     * it out and putting it back.
      *
      * @param {RenderExtension} extension
      * @returns {RenderExtension} `extension`, so a caller can hold it for {@link remove} without

package/src/shade/renderer/extension/RenderExtensionRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderExtensionRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/RenderExtensionRegistry.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH;IA6BI;;;;;;;;;OASG;IACH,iDAiBC;IAED;;;;;;OAMG;IACH,oCAFa,OAAO,CAsBnB;IAED;;;OAGG;IACH,aAHW,UAAU,GACR,MAAM,CAOlB;IAED;;;;;;;;;OASG;IACH,+BA0CC;;CACJ;2BA3K4C,iBAAiB"}
+{"version":3,"file":"RenderExtensionRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/RenderExtensionRegistry.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH;IAqBI;;;;;;;;;OASG;IACH,iDAcC;IAED;;;;;;OAMG;IACH,oCAFa,OAAO,CAsBnB;IAED;;;OAGG;IACH,aAHW,UAAU,GACR,MAAM,CAOlB;IAED;;;;;;;;;OASG;IACH,+BA0CC;;CACJ;2BAhK4C,iBAAiB"}

package/src/shade/renderer/extension/RenderExtensionRegistry.js

@@ -10,9 +10,9 @@ const PHASE_COUNT = Object.keys(FramePhase).length;
  * The extensions an outside caller has put into a frame, kept per {@link FramePhase} in the order
  * their declarations resolve to.
  *
- * Device-free on purpose: this is the part of the mechanism with rules — ordering, cycles, removal,
- * what a recording scope is around — and keeping it out of the renderer means those rules can be
- * stated and tested without standing up a GPU.
+ * Device-free on purpose: this is the part of the mechanism with rules — ordering, removal, what a
+ * recording scope is around — and keeping it out of the renderer means those rules can be stated
+ * and tested without standing up a GPU.
  *
  * **The graph does not order extensions; this does.** `FrameGraph.execute` iterates its passes in
  * insertion order and does not sort, and `validate()` checks only that such an order is
@@ -21,16 +21,9 @@ const PHASE_COUNT = Object.keys(FramePhase).length;
  */
 export class RenderExtensionRegistry {
     /**
-     * Registered extensions per phase, in registration order. The order things run in is
-     * {@link #resolved}; this is what that is computed from.
-     *
-     * @type {Array<RenderExtension[]>}
-     */
-    #registered = [];
-
-    /**
-     * Registration order run through the declarations, recomputed whenever the set changes rather
-     * than per frame.
+     * Registered extensions per phase, kept in the order they record in. Resolved whenever the set
+     * changes rather than per frame; registration order is not kept beside it because nothing is
+     * computed from it.
      *
      * @type {Array<RenderExtension[]>}
      */
@@ -43,7 +36,6 @@ export class RenderExtensionRegistry {
 
     constructor() {
         for (let i = 0; i < PHASE_COUNT; i++) {
-            this.#registered.push([]);
             this.#resolved.push([]);
         }
     }
@@ -51,8 +43,8 @@ export class RenderExtensionRegistry {
     /**
      * Register `extension` to record when its phase comes round.
      *
-     * The resolved order is computed here, so a cycle in the declarations fails at the registration
-     * that closed it, naming what it is made of. Registration order itself decides nothing.
+     * `relative_order` is read here, once. Moving an extension after it is registered means taking
+     * it out and putting it back.
      *
      * @param {RenderExtension} extension
      * @returns {RenderExtension} `extension`, so a caller can hold it for {@link remove} without
@@ -63,16 +55,13 @@ export class RenderExtensionRegistry {
         assert.isString(extension.name, 'extension.name');
         assert.isNonNegativeInteger(extension.phase, 'extension.phase');
         assert.lessThan(extension.phase, PHASE_COUNT, 'extension.phase');
+        assert.isNumber(extension.relative_order, 'extension.relative_order');
+        assert.isFinite(extension.relative_order, 'extension.relative_order');
         assert.equal(this.#recording, false, 'an extension cannot be registered while the registry is recording a frame');
 
         const phase = extension.phase;
-        const candidates = this.#registered[phase].concat(extension);
 
-        // resolved before anything is kept, so a cycle leaves the registry exactly as it was
-        const resolved = resolve_order(candidates, phase);
-
-        this.#registered[phase] = candidates;
-        this.#resolved[phase] = resolved;
+        this.#resolved[phase] = resolve_order(this.#resolved[phase].concat(extension));
 
         return extension;
     }
@@ -89,19 +78,19 @@ export class RenderExtensionRegistry {
         assert.equal(this.#recording, false, 'an extension cannot be removed while the registry is recording a frame');
 
         const phase = extension.phase;
-        const registered = this.#registered[phase];
-        const index = registered.indexOf(extension);
+        const resolved = this.#resolved[phase];
+        const index = resolved.indexOf(extension);
 
         if (index === -1) {
             return false;
         }
 
-        const candidates = registered.slice();
+        // taking one out cannot reorder the rest, so the remainder is still resolved
+        const remaining = resolved.slice();
 
-        candidates.splice(index, 1);
+        remaining.splice(index, 1);
 
-        this.#registered[phase] = candidates;
-        this.#resolved[phase] = resolve_order(candidates, phase);
+        this.#resolved[phase] = remaining;
 
         return true;
     }
@@ -114,7 +103,7 @@ export class RenderExtensionRegistry {
         assert.isNonNegativeInteger(phase, 'phase');
         assert.lessThan(phase, PHASE_COUNT, 'phase');
 
-        return this.#registered[phase].length;
+        return this.#resolved[phase].length;
     }
 
     /**
@@ -173,147 +162,21 @@ export class RenderExtensionRegistry {
 }
 
 /**
- * Put `extensions` into the order their `after` / `before` declarations ask for, breaking
- * everything they leave open by name, ascending.
+ * Put `extensions` into the order they record in: by `relative_order`, ascending, and by name
+ * within one value.
+ *
+ * Both keys are the extensions' own, so registration order does not reach the result — two sharing
+ * both keys are the one exception, and they keep theirs.
  *
  * @param {RenderExtension[]} extensions
- * @param {FramePhase} phase
  * @returns {RenderExtension[]}
  */
-function resolve_order(extensions, phase) {
-    const count = extensions.length;
-
-    // name order is the base, so the result is the same whatever order registration happened in
-    const nodes = extensions.slice().sort((a, b) => a.name < b.name ? -1 : (a.name > b.name ? 1 : 0));
-
-    /**
-     * `successors[i]` are the extensions that must record after `nodes[i]`.
-     *
-     * @type {Array<number[]>}
-     */
-    const successors = [];
-    const incoming = new Int32Array(count);
-
-    for (let i = 0; i < count; i++) {
-        successors.push([]);
-    }
-
-    for (let i = 0; i < count; i++) {
-        const node = nodes[i];
-
-        for (let j = 0; j < count; j++) {
-            if (i === j) {
-                continue;
-            }
-
-            const other = nodes[j];
-
-            // `i` records after `j` when either side says so; a class nobody registered on this
-            // phase names nothing and is therefore not a constraint
-            const constrained = declares(node.after, other) || declares(other.before, node);
-
-            if (constrained) {
-                successors[j].push(i);
-                incoming[i]++;
-            }
-        }
-    }
-
-    const order = [];
-    const ready = [];
-
-    for (let i = 0; i < count; i++) {
-        if (incoming[i] === 0) {
-            ready.push(i);
+function resolve_order(extensions) {
+    return extensions.slice().sort((a, b) => {
+        if (a.relative_order !== b.relative_order) {
+            return a.relative_order - b.relative_order;
         }
-    }
-
-    while (ready.length > 0) {
-        // `nodes` is in name order, so taking the lowest index available is taking the lowest name
-        // among everything currently unblocked
-        let pick = 0;
-
-        for (let i = 1; i < ready.length; i++) {
-            if (ready[i] < ready[pick]) {
-                pick = i;
-            }
-        }
-
-        const index = ready[pick];
-
-        ready.splice(pick, 1);
-        order.push(nodes[index]);
-
-        for (const successor of successors[index]) {
-            incoming[successor]--;
-
-            if (incoming[successor] === 0) {
-                ready.push(successor);
-            }
-        }
-    }
-
-    if (order.length !== count) {
-        throw new Error(`Render extensions on ${frame_phase_name(phase)} declare an ordering cycle: ${describe_cycle(nodes, successors, incoming)}. A cycle has no order, so there is nothing to resolve it to.`);
-    }
-
-    return order;
-}
-
-/**
- * Whether `declarations` names the class `extension` is an instance of.
- *
- * @param {Function[]} declarations
- * @param {RenderExtension} extension
- * @returns {boolean}
- */
-function declares(declarations, extension) {
-    for (let i = 0; i < declarations.length; i++) {
-        if (extension instanceof declarations[i]) {
-            return true;
-        }
-    }
-
-    return false;
-}
-
-/**
- * One cycle out of what is left unresolved, as names, so the message says what to go and look at.
- *
- * @param {RenderExtension[]} nodes
- * @param {Array<number[]>} successors
- * @param {Int32Array} incoming
- * @returns {string}
- */
-function describe_cycle(nodes, successors, incoming) {
-    const remaining = [];
-
-    for (let i = 0; i < nodes.length; i++) {
-        if (incoming[i] > 0) {
-            remaining.push(i);
-        }
-    }
-
-    const path = [];
-    const seen = new Set();
-
-    let current = remaining[0];
-
-    while (!seen.has(current)) {
-        seen.add(current);
-        path.push(current);
-
-        const next = successors[current].find(index => incoming[index] > 0);
-
-        if (next === undefined) {
-            break;
-        }
-
-        current = next;
-    }
-
-    const start = path.indexOf(current);
-    const cycle = start === -1 ? path : path.slice(start);
 
-    return cycle.concat(cycle[0]).map(index => `'${nodes[index].name}'`).join(" -> ");
+        return a.name < b.name ? -1 : (a.name > b.name ? 1 : 0);
+    });
 }

package/src/shade/renderer/geometry/GPUGeometryManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryManager.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH;IAqJI;;;OAGG;IACH,+BAUC;IA7JD;;;OAGG;IACH,iBAFU,YAAU,IAAI,CAED;IA0CvB;;;OAGG;IACH,4GAEC;IAED;;;;OAIG;IACH,8BAA0B;IAE1B;;;;OAIG;IACH,uBAAsB;IAOtB;;;OAGG;IACH,kCAEC;IAwBD;;;OAGG;IACH,kCAEC;IAGD;;;OAGG;IACH,0EAEC;IAED;;;OAGG;IACH,+BAiBC;IAkBD;;;;OAIG;IACH,qBAHW,mBAAmB,GAClB,MAAM,CAMjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAIlB;IAGD;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CA+EnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,2BAPW,eAAe,GACb,mBAAmB,CAiC/B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAHW,mBAAmB,GACjB,OAAO,CAqBnB;IAED;;;;;;;OAOG;IACH,uBAHW,eAAe,GACb,mBAAmB,GAAC,SAAS,CAIzC;IAED;;;;OAIG;IACH,iBAHW,eAAe,GACb,OAAO,CAsCnB;IAyBD,gBAWC;IAED;;;;;;OAMG;IACH,qBANW,sBAAsB,QAuChC;IAmDD,cAmCC;IAED,0CAWC;;CAqCJ;qCAzoBY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,sBAAsB,EAAE,eAAe;oCAC9C,OAAO,gCAAgC,EAAE,qBAAqB;oCANvC,0BAA0B;kCAC5B,gCAAgC;sCAH5B,gCAAgC"}
+{"version":3,"file":"GPUGeometryManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryManager.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH;IA6JI;;;OAGG;IACH,+BAUC;IArKD;;;OAGG;IACH,iBAFU,YAAU,IAAI,CAED;IAkDvB;;;OAGG;IACH,4GAEC;IAED;;;;OAIG;IACH,8BAA0B;IAE1B;;;;OAIG;IACH,uBAAsB;IAOtB;;;OAGG;IACH,kCAEC;IAwBD;;;OAGG;IACH,kCAEC;IAGD;;;OAGG;IACH,0EAEC;IAED;;;OAGG;IACH,+BAiBC;IAkBD;;;;OAIG;IACH,qBAHW,mBAAmB,GAClB,MAAM,CAMjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAIlB;IAGD;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAwEnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,2BAPW,eAAe,GACb,mBAAmB,CAmC/B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAHW,mBAAmB,GACjB,OAAO,CAsBnB;IAED;;;;;;;OAOG;IACH,uBAHW,eAAe,GACb,mBAAmB,GAAC,SAAS,CAIzC;IAED;;;;OAIG;IACH,iBAHW,eAAe,GACb,OAAO,CAuCnB;IAyBD,gBAWC;IAED;;;;;;OAMG;IACH,qBANW,sBAAsB,QAuChC;IAmDD,cAqCC;IAED,0CAWC;;CAuFJ;qCAlsBY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,sBAAsB,EAAE,eAAe;oCAC9C,OAAO,gCAAgC,EAAE,qBAAqB;oCANvC,0BAA0B;kCAC5B,gCAAgC;sCAH5B,gCAAgC"}

package/src/shade/renderer/geometry/GPUGeometryManager.js

@@ -74,6 +74,14 @@ export class GPUGeometryManager {
      */
     #clone_metadata = [];
 
+    /**
+     * How to stop following a record's meshlet batch, per record that follows one. A record
+     * that has been released must not go on rewriting a row that is no longer its own.
+     *
+     * @type {Map<GPUGeometryMetadata, function(): void>}
+     */
+    #batch_listeners = new Map();
+
     /**
      * Do not modify. The data is managed by this class, access in read-only mode.
      * @return {Map<Readonly<MeshletGeometry>, Readonly<GPUGeometryMetadata>>}
@@ -267,14 +275,7 @@ export class GPUGeometryManager {
 
             metadata.meshlets = this.#meshlets.add_batch(meshlets);
 
-            // watch for data migration
-            metadata.meshlets.changed.add(() => {
-
-                // TODO need to handle this properly
-
-                console.warn('Meshlet GPU address changed.')
-
-            });
+            this.#follow_batch(metadata);
         }
 
         this.#geometries.set(geometry, metadata);
@@ -340,6 +341,8 @@ export class GPUGeometryManager {
         metadata.index = this.__last_geometry_index++;
         metadata.meshlets = clone_meshlets;
 
+        this.#follow_batch(metadata);
+
         this.#clone_metadata.push(metadata);
 
         this.__needs_update = true;
@@ -382,6 +385,7 @@ export class GPUGeometryManager {
 
         this.#clone_metadata.splice(index, 1);
 
+        this.#unfollow_batch(metadata);
         this.#meshlets.remove_batch(metadata.meshlets);
         this.#blas.remove(metadata);
 
@@ -432,6 +436,7 @@ export class GPUGeometryManager {
         // slices so other geometries are unaffected, and the rebuild drops this geometry's
         // metadata row so nothing references the freed ranges afterward.
         if (metadata.meshlets !== undefined) {
+            this.#unfollow_batch(metadata);
             this.#meshlets.remove_batch(metadata.meshlets);
         }
         this.#blas.remove(metadata);
@@ -605,7 +610,9 @@ export class GPUGeometryManager {
 
         // write metadata
         for (let i = 0; i < all_metadata.length; i++) {
-            this.#write_geometry_metadata(all_metadata[i], metadata);
+            const g_meta = all_metadata[i];
+
+            this.#write_geometry_metadata(g_meta, metadata.buffer, g_meta.index * GEOMETRY_METADATA_STRUCT.size);
         }
 
         this.buffer_metadata.unmap();
@@ -632,15 +639,12 @@ export class GPUGeometryManager {
      * own GPU allocation when this is a clone.
      *
      * @param {GPUGeometryMetadata} g_meta
-     * @param {DataView} metadata
+     * @param {ArrayBuffer} target
+     * @param {number} offset byte offset of the row in `target`
      */
-    #write_geometry_metadata(g_meta, metadata) {
+    #write_geometry_metadata(g_meta, target, offset) {
         const geometry = g_meta.geometry;
 
-        const idx = g_meta.index;
-
-        const offset = idx * GEOMETRY_METADATA_STRUCT.size;
-
         // TODO fix this, assumes triangles currently
         const indexCount = geometry.primitive_count * 3;
 
@@ -656,7 +660,60 @@ export class GPUGeometryManager {
             meshlets_address: g_meta.meshlets?.metadata.offset ?? 0,
             meshlets_count: g_meta.meshlets?.meshlet_count ?? 0,
             vg_row: g_meta.vg_row,
-        }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
+        }, GEOMETRY_METADATA_STRUCT, target, offset);
 
     }
+
+    /**
+     * Follow a record's meshlet batch: when the pool moves it, the record's row on the device is
+     * re-addressed then and there.
+     *
+     * The pool announces a move through the batch record's `changed` (a rebuild, or a sweep step
+     * once it sweeps — COMPACTION_PLAN_2026_09_16 §5). The row is written from inside the handler
+     * with `queue.writeBuffer`, which the queue orders ahead of whatever command buffer carries
+     * the move, rather than being deferred to this manager's own {@link update}: the skinning
+     * context drives the pool's flush directly, and nothing runs an update of this table after
+     * it in the frame, so a deferred patch would leave the row wrong for every pass of that
+     * frame. When a rebuild of the whole table is already pending it writes every row, and a row
+     * past the buffer is one that rebuild has yet to create.
+     *
+     * @param {GPUGeometryMetadata} metadata
+     */
+    #follow_batch(metadata) {
+        const listener = () => {
+            if (this.__needs_update) {
+                return;
+            }
+
+            const buffer = this.buffer_metadata;
+            const offset = metadata.index * GEOMETRY_METADATA_STRUCT.size;
+
+            if (offset + GEOMETRY_METADATA_STRUCT.size > buffer.size) {
+                return;
+            }
+
+            const row = new ArrayBuffer(GEOMETRY_METADATA_STRUCT.size);
+
+            this.#write_geometry_metadata(metadata, row, 0);
+
+            this.#device.queue.writeBuffer(buffer, offset, row);
+        };
+
+        metadata.meshlets.changed.add(listener);
+
+        this.#batch_listeners.set(metadata, () => metadata.meshlets.changed.remove(listener));
+    }
+
+    /**
+     * @param {GPUGeometryMetadata} metadata
+     */
+    #unfollow_batch(metadata) {
+        const unfollow = this.#batch_listeners.get(metadata);
+
+        if (unfollow !== undefined) {
+            unfollow();
+
+            this.#batch_listeners.delete(metadata);
+        }
+    }
 }

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH;;;;;GAKG;AACH,gDAGG;AAEH;;;;;;;;;;;GAWG;AACH,sCAFU,MAAM,CAEyB;AAoBzC;;;;;;;;;;;;;;GAcG;AACH;IA0II;;;OAGG;IACH,+BAoDC;IA1LD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IA+BD;;OAEG;IACH,gCAEC;IA6ED;;;;OAIG;IACH,iCAEC;IAED,+BAoBC;IAED;;;;;;;;;OASG;IACH,wCAIC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,UACN,eAAe,GAEb,sBAAsB,CAalC;IA8DD;;;;;;;;;;;;OAYG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAqB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,OAAO,CA8BnB;IA4LD;;;;;;;OAOG;IACH,eAOC;;CAgIJ;8BAj0BY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}
+{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH;;;;;GAKG;AACH,gDAGG;AAEH;;;;;;;;;;;GAWG;AACH,sCAFU,MAAM,CAEyB;AAmCzC;;;;;;;;;;;;;;GAcG;AACH;IA0II;;;OAGG;IACH,+BAoDC;IA1LD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IA+BD;;OAEG;IACH,gCAEC;IA6ED;;;;OAIG;IACH,iCAEC;IAED,+BAoBC;IAED;;;;;;;;;OASG;IACH,wCAIC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,UACN,eAAe,GAEb,sBAAsB,CAalC;IA8DD;;;;;;;;;;;;OAYG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAqB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,OAAO,CA8BnB;IA4LD;;;;;;;OAOG;IACH,eAOC;;CAgIJ;8BAh1BY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js

@@ -54,13 +54,28 @@ const DATA_GROWTH_MULTIPLIER = 1.2;
 
 /**
  * Regions the node arena's allocator can describe at once — live trees plus the free gaps
- * between them. A scene's live trees are one per geometry plus one per skinned instance, so
- * this is thousands of instances of headroom.
+ * between them. A scene's live trees are one per geometry plus one per skinned instance.
  *
  * A ceiling rather than a starting point: {@link OffsetAllocator#grow} enlarges the arena but
  * deliberately does not raise this, so it is picked once here.
+ *
+ * **32,768 was the figure, and a real map disproved the assumption under it.** That number was
+ * chosen as "thousands of instances of headroom", which is a statement about how many *distinct
+ * geometries* a scene has rather than about how big they are — and the scene it was sized for is one
+ * an artist built. A converted production map is not: Caldera's `map_capital` alone places 116,512
+ * distinct geometries and the whole map has 478,006, so the arena refused its 32,769th tree partway
+ * through loading one district out of forty-five. The refusal is loud, which is the one good thing
+ * about it: `#allocate_nodes` asserts rather than silently drawing without a BLAS.
+ *
+ * The cost of the ceiling is paid at construction whether a scene reaches it or not — the allocator
+ * eagerly allocates its node table — and it is **0.93 MiB at 32,768 regions against 29.0 MiB at
+ * 1,048,576**, measured. 28 MiB of host memory is the price of a scene of half a million geometries
+ * being possible at all, and it buys the whole of Caldera; a host that would rather have the 28 MiB
+ * back than draw a map of that size can put the old figure back here, and nothing else changes.
+ *
+ * @see src/shade/playground/caldera/README.md — where this was found and what it took to pass it
  */
-const NODE_ALLOCATION_LIMIT = 32 * 1024;
+const NODE_ALLOCATION_LIMIT = 1024 * 1024;
 
 const endianness = platform_compute_endianness();