@woosh/meep-engine 3.32.0 → 3.34.0

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

@@ -70,9 +70,13 @@ export class GPUGeometryManager {
      * collections share the same `index` space — `__last_geometry_index`
      * advances for both.
      *
-     * @type {GPUGeometryMetadata[]}
+     * A set rather than an array, because a clone is given back by record: finding it in an
+     * array and splicing it out cost the length of the array, so a scene giving back all of its
+     * skinned clones at once paid the square of their count.
+     *
+     * @type {Set<GPUGeometryMetadata>}
      */
-    #clone_metadata = [];
+    #clone_metadata = new Set();
 
     /**
      * How to stop following a record's meshlet batch, per record that follows one. A record
@@ -343,7 +347,7 @@ export class GPUGeometryManager {
 
         this.#follow_batch(metadata);
 
-        this.#clone_metadata.push(metadata);
+        this.#clone_metadata.add(metadata);
 
         this.__needs_update = true;
 
@@ -377,14 +381,10 @@ export class GPUGeometryManager {
     remove_clone(metadata) {
         assert.defined(metadata, 'metadata');
 
-        const index = this.#clone_metadata.indexOf(metadata);
-
-        if (index === -1) {
+        if (!this.#clone_metadata.delete(metadata)) {
             return false;
         }
 
-        this.#clone_metadata.splice(index, 1);
-
         this.#unfollow_batch(metadata);
         this.#meshlets.remove_batch(metadata.meshlets);
         this.#blas.remove(metadata);
@@ -482,8 +482,7 @@ export class GPUGeometryManager {
         }
 
         this.#meshlets.destroy();
-
-        // TODO ensure BVH and others are destroyed
+        this.#blas.destroy();
 
         this.__needs_update = true;
     }

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

@@ -160,6 +160,11 @@ export class GPUGeometryBVHManager {
      * version, because that record's refit answer has changed all the same.
      */
     update(): void;
+    /**
+     * Release the arena and its tables. For the geometry manager's own teardown: nothing is
+     * obtained, uploaded or traced afterwards. Safe to call twice.
+     */
+    destroy(): void;
     #private;
 }
 export type MeshletGeometry = import("../MeshletGeometry.js").MeshletGeometry;

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;AA0CzC;;;;;;;;;;;;;;GAcG;AACH;IA8JI;;;OAGG;IACH,+BAoDC;IA9MD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IAmDD;;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;IA8RD;;;;;;;OAOG;IACH,eAOC;;CAgIJ;8BA78BY,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;AA0CzC;;;;;;;;;;;;;;GAcG;AACH;IA8JI;;;OAGG;IACH,+BAoDC;IA9MD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IAmDD;;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;IA8RD;;;;;;;OAOG;IACH,eAOC;IAiID;;;OAGG;IACH,gBAKC;;CACJ;8BAx9BY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}

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

@@ -990,4 +990,15 @@ export class GPUGeometryBVHManager {
 
         return true;
     }
+
+    /**
+     * Release the arena and its tables. For the geometry manager's own teardown: nothing is
+     * obtained, uploaded or traced afterwards. Safe to call twice.
+     */
+    destroy() {
+        this.#buffer_metadata.destroy();
+        this.#buffer_data.destroy();
+        this.#buffer_parents.destroy();
+        this.#buffer_leaf_nodes.destroy();
+    }
 }

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.d.ts

@@ -39,6 +39,11 @@ export class GPUVirtualGeometryPool {
         table_options?: any;
         page_size?: number;
     });
+    /**
+     * The device every buffer of the pool lives on, and every buffer the runtime above it makes.
+     * @returns {GPUDevice}
+     */
+    get device(): GPUDevice;
     /**
      * @returns {GPUBuffer}
      */
@@ -174,6 +179,13 @@ export class GPUVirtualGeometryPool {
      * @returns {number} page row, or -1 when the tier could not make room
      */
     install(reader: VGeoContainerReader, page_index: number): number;
+    /**
+     * Pages installed into this tier since it was made — monotonic, so "has anything arrived since"
+     * is one comparison against a count taken then.
+     *
+     * @returns {number}
+     */
+    get installed_page_count(): number;
     /**
      * @param {number} page_row
      * @returns {boolean}

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUVirtualGeometryPool.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.js"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAoFI;;;;;;;;OAQG;IACH;QAP8B,MAAM;QACE,QAAQ,EAAnC,iBAAiB;QAEA,aAAa;QACb,SAAS,GAA1B,MAAM;OAyChB;IAkCD;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,mCAEC;IAED;;;OAGG;IACH,oCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,6BAEC;IAGD;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;OAKG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,oBAEC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;OAGG;IACH,gCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBALW,mBAAmB,GACjB,MAAM,CAmClB;IAED;;;;;;;;;OASG;IACH,mBAHW,mBAAmB,GACjB,OAAO,CA+CnB;IAqCD;;;OAGG;IACH,wBAHW,mBAAmB,GACjB,MAAM,CAIlB;IAED;;;;OAIG;IACH,oBAJW,mBAAmB,cACnB,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,wBAJW,mBAAmB,cACnB,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAJW,mBAAmB,cACnB,MAAM,GACJ,MAAM,CAgElB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,OAAO,CA0CnB;IAED;;;;;;;;;;;;;;OAcG;IACH,mBAHW,MAAM,GACJ;QAAC,MAAM,EAAE,mBAAmB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAIhE;IAED;;;;;OAKG;IACH,iBAFa,IAAI,CAIhB;IA2ED;;;;;;;;;OASG;IACH,SAFa,IAAI,CAMhB;IAwDD,gBAcC;;CACJ;gCAp0BY,OAAO,oCAAoC,EAAE,iBAAiB;kCAC9D,OAAO,uCAAuC,EAAE,mBAAmB;kCAL9C,wBAAwB"}
+{"version":3,"file":"GPUVirtualGeometryPool.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.js"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAoFI;;;;;;;;OAQG;IACH;QAP8B,MAAM;QACE,QAAQ,EAAnC,iBAAiB;QAEA,aAAa;QACb,SAAS,GAA1B,MAAM;OAyChB;IAkCD;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,mCAEC;IAED;;;OAGG;IACH,oCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,6BAEC;IAGD;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;OAKG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;OAEG;IACH,oBAEC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;OAGG;IACH,gCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBALW,mBAAmB,GACjB,MAAM,CAmClB;IAED;;;;;;;;;OASG;IACH,mBAHW,mBAAmB,GACjB,OAAO,CA+CnB;IAqCD;;;OAGG;IACH,wBAHW,mBAAmB,GACjB,MAAM,CAIlB;IAED;;;;OAIG;IACH,oBAJW,mBAAmB,cACnB,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,wBAJW,mBAAmB,cACnB,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAJW,mBAAmB,cACnB,MAAM,GACJ,MAAM,CAkElB;IAOD;;;;;OAKG;IACH,mCAEC;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,OAAO,CA0CnB;IAED;;;;;;;;;;;;;;OAcG;IACH,mBAHW,MAAM,GACJ;QAAC,MAAM,EAAE,mBAAmB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAIhE;IAED;;;;;OAKG;IACH,iBAFa,IAAI,CAIhB;IA2ED;;;;;;;;;OASG;IACH,SAFa,IAAI,CAMhB;IAwDD,gBAcC;;CACJ;gCA71BY,OAAO,oCAAoC,EAAE,iBAAiB;kCAC9D,OAAO,uCAAuC,EAAE,mBAAmB;kCAL9C,wBAAwB"}

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.js

@@ -239,6 +239,14 @@ export class GPUVirtualGeometryPool {
         });
     }
 
+    /**
+     * The device every buffer of the pool lives on, and every buffer the runtime above it makes.
+     * @returns {GPUDevice}
+     */
+    get device() {
+        return this.#device;
+    }
+
     /**
      * @returns {GPUBuffer}
      */
@@ -609,9 +617,26 @@ export class GPUVirtualGeometryPool {
         // flags flipped are whatever they say, not this page's alone
         this.#mark_activated();
 
+        this.#installed_page_count++;
+
         return page_row;
     }
 
+    /**
+     * @type {number}
+     */
+    #installed_page_count = 0;
+
+    /**
+     * Pages installed into this tier since it was made — monotonic, so "has anything arrived since"
+     * is one comparison against a count taken then.
+     *
+     * @returns {number}
+     */
+    get installed_page_count() {
+        return this.#installed_page_count;
+    }
+
     /**
      * @param {number} page_row
      * @returns {boolean}

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.d.ts

@@ -1,7 +1,3 @@
-/**
- * @typedef {import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool} GPUVirtualGeometryPool
- * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- */
 /**
  * What one frame of virtual geometry needs that is not a page: the threshold, the feedback buffer
  * every view writes into, and the parameters every pass reads.
@@ -12,9 +8,16 @@
  * virtual geometry is view-dependent by construction — but everything here is shared between them,
  * which is exactly what §4 means by "the setup is shared rather than the result".
  *
- * **The feedback buffer is per frame and not per invocation**, and that is what dedups a touch
- * across the buckets and passes a frame is split into. Each expansion site gets its own claim
- * bitmask (different instance sets) and writes into this one buffer.
+ * **A frame spans every graph of a render.** The renderer opens it before the shadow maps are drawn
+ * and closes it after the main view's graph is recorded, and each shadow map records into a
+ * `FrameGraph` of its own (SHADOW_PLAN_2026_09_28 §2.1). So the feedback buffer is not a transient of
+ * any one graph: it is a buffer this runtime owns, **imported** into each graph that cuts, and the
+ * first graph of a frame to import it clears it. Graphs are encoded in the order they are recorded
+ * into one encoder, which is the only ordering the frame needs between them.
+ *
+ * **Every view that cuts takes a slot** (§2.4): its own counters, its own want slice and its own
+ * stamp tag, so one view's list running out cannot silence another's, and a reading can say which
+ * view needed more wavefronts. The view the frame is opened for is slot 0.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -30,7 +33,7 @@ export class GPUVirtualGeometryRuntime {
      *     overriding the derivation below
      * @param {number} [options.queue_capacity] traversal items one wavefront may hold
      * @param {number} [options.max_iterations] wavefronts before the descent is abandoned, to start
-     *     with; the runtime raises it from what the cut reports
+     *     with; each view raises its own from what its cut reports
      * @param {number} [options.max_iteration_ceiling] as far as that raising may go
      * @param {number} [options.descent_steps] steps of the descent one traversal dispatch runs
      *     before handing back what it still holds; see the traversal kernel for why it cannot
@@ -48,6 +51,7 @@ export class GPUVirtualGeometryRuntime {
     });
     /**
      * Pixels of permitted error — the single quality/perf lever, and a runtime dial by design §4.
+     * A view cuts at this times its own {@link VGeoViewCut#tau_scale}.
      * @type {number}
      */
     tau: number;
@@ -74,60 +78,22 @@ export class GPUVirtualGeometryRuntime {
      */
     get claim_word_capacity(): number;
     /**
-     * Wavefronts the descent may run, as the runtime currently understands this scene.
-     *
-     * A **high-water mark**, not a setting: it starts where the host put it and is raised by
-     * {@link note_incomplete_descent} from what the cut reports. `graph_vgeo_expand_instances_to_meshlets`
-     * reads it while it is recording passes, so a rise lands on the next frame.
+     * Wavefronts a view's descent starts with — each view raises its own from what its cut reports
+     * (`VGeoViewCut.note_incomplete_descent`), and cuts at the larger of the two.
      *
      * @returns {number}
      */
     get max_iterations(): number;
     /**
-     * Times the bound has been raised. Zero for the whole life of almost every scene; a small
-     * number, once, for one that needed more than it was given.
+     * As far as a view's wavefront bound may be raised.
      *
      * @returns {number}
      */
-    get iteration_escalations(): number;
-    /**
-     * @returns {number}
-     */
     get iteration_ceiling(): number;
-    /**
-     * A reading saying the descent stopped with work still queued — raise the bound and keep it
-     * raised.
-     *
-     * **This is the only place the engine can learn it.** How many wavefronts a cut needs is a
-     * function of the frontier's *breadth*, which is a function of the scene, the viewpoint and the
-     * render target together; the kernel cannot know it before it runs and the host cannot know it
-     * at all. So the bound is guessed low, and the one reading that says the guess was wrong —
-     * `VGEO_CUT_STAT.QUEUE_REMAINING`, non-zero exactly when items were abandoned — pays for
-     * correcting it. It is the same shape as the rasterizer's meshlet counts, which cannot be known
-     * before the expansion runs either and are grown from what the frame reported.
-     *
-     * **Doubling, because the reading does not say how much more was needed.** A remainder is a
-     * count of *items*, and what they cost in wavefronts depends on how they spill; there is no
-     * ratio to convert one into the other. So it goes up by a factor until it drains, which is at
-     * most three steps from 8 to the ceiling.
-     *
-     * **Never lowered.** A frame that drained is evidence about that frame, not that the scene got
-     * smaller — and a bound that fell back would re-learn the same lesson every time the camera
-     * turned away and back, at a hole a time. An unused wavefront is an empty indirect dispatch,
-     * which is the cheap side of that trade.
-     *
-     * What it costs when it is wrong is bounded by the readback: the cut is capped at two readings
-     * in flight and skips frames when saturated, so the scene draws with a hole for the few frames
-     * between the first truncated descent and the reading that reports it — and then never again.
-     *
-     * @param {number} remaining items the descent still held when it was abandoned
-     * @returns {boolean} whether the bound moved
-     */
-    note_incomplete_descent(remaining: number): boolean;
     /**
      * Settable, like tau, and for the same reason: it is a quality-of-schedule dial whose right
      * value is a property of the asset's depth and the scene's breadth together rather than of the
-     * engine. `begin_frame` re-writes the params every frame, so a change lands on the next one.
+     * engine. Every view writes its params at record time, so a change lands on the next frame.
      *
      * @param {number} value
      */
@@ -139,47 +105,43 @@ export class GPUVirtualGeometryRuntime {
      */
     get descent_steps(): number;
     /**
-     * This frame's feedback resource. Every expansion site writes into it and one readback reads it.
-     * @returns {number}
+     * Whether a frame is open — whether a rasterization path recording now may cut.
+     *
+     * @returns {boolean}
      */
-    get feedback(): number;
+    get frame_open(): boolean;
     /**
-     * Hand back the version of the feedback resource that an expansion left behind.
-     *
-     * A frame is cut once per bucket per HZB pass per view, and every one of those writes into the
-     * *same* feedback buffer — which is exactly what dedups a touch across them. But a FrameGraph
-     * resource is versioned: the handle `begin_frame` created is version 0, and a second expansion
-     * that wrote version 0 again after the first had produced version 65 would be reading stale
-     * contents while claiming not to. The graph says so, loudly, and it is right to.
+     * The view the last frame was opened for, which is slot 0 of that frame's feedback.
      *
-     * So the runtime carries the *current* version and each expansion publishes what it produced.
-     * The readback then reads the last one, which is the only version that has seen every view.
+     * @returns {VGeoViewCut|undefined}
+     */
+    get frame_view(): import("./VGeoViewCut.js").VGeoViewCut;
+    /**
+     * The feedback buffer every view of a frame writes into, or null before the first frame and
+     * after {@link destroy}.
      *
-     * @param {number} handle
-     * @returns {void}
+     * @returns {GPUBuffer|null}
      */
-    publish_feedback(handle: number): void;
+    get feedback_buffer(): any;
     /**
      * @returns {ReturnType<vgeo_cut_feedback_layout>}
      */
     get feedback_layout(): {
+        slot_count: number;
         touch_bits_base: number;
-        /**
-         * @type {number}
-         */
         touch_word_count: number;
         want_base: number;
-        word_count: number; /**
-         * @type {number}
-         */
+        slot_want_capacity: number;
+        clear_word_count: number;
+        word_count: number;
     };
     /**
-     * Open a frame: publish the page tables, size the feedback buffer against what is resident, and
-     * write the parameters every pass of every view will read.
+     * Open a frame: publish the page tables, lay the feedback buffer out for the views the frame is
+     * expected to have, and take slot 0 for the view it is rendered for.
      *
-     * The sizing happens here rather than at construction because one of its terms moves with
-     * residency — one touch bit per page-table row — and a frame is the coarsest granularity at
-     * which it holds still.
+     * The sizing happens here rather than at construction because two of its terms move — one
+     * touch bit per page-table row follows residency, and the slot count follows the most views any
+     * frame has cut in — and a frame is the coarsest granularity at which they hold still.
      *
      * **The pool's frame advances here, before the flush**, and not at `end_frame`. The frame
      * number is what stamps a page row's `visible_from` — the frame whose flush publishes the
@@ -188,18 +150,72 @@ export class GPUVirtualGeometryRuntime {
      * frame's reading, exactly (RUNTIME_PLAN_2026_09_14 §2.4). It is also the clock both tiers'
      * protect windows read, and it moves whether or not a readback is scheduled this frame.
      *
-     * **A frame has no projection.** It used to take one, and wrote it into a params buffer
-     * every view then shared — so a shadow cascade cut against whichever view opened the
-     * frame. `projection_k` is a property of a render target and a camera, which is to say of
-     * a view, and it lives on {@link VGeoViewCut} with the rest of what a view owns alone.
+     * **A frame has no projection and no graph.** Each view writes its own projection
+     * ({@link VGeoViewCut}), and each graph that cuts imports the feedback buffer itself
+     * ({@link feedback_in}).
+     *
+     * Opening a frame that is already open starts it again: a render that threw before closing its
+     * frame leaves nothing behind that the next one can be confused by.
      *
      * @param {Object} options
-     * @param {FrameGraph} options.graph
-     * @returns {number} the feedback resource
+     * @param {VGeoViewCut} options.view the view the frame is rendered for
+     * @returns {void}
      */
-    begin_frame({ graph }: {
-        graph: FrameGraph;
-    }): number;
+    begin_frame({ view }: {
+        view: VGeoViewCut;
+    }): void;
+    /**
+     * This frame's slot for a view, taking the next one the first time the view cuts in the frame.
+     *
+     * A view past the slots the frame was laid out for shares the last one — never slot 0, which is
+     * the frame's own view's — and the next frame is laid out with room for it. A shared slot's
+     * counters are the sum of its views', so its reading lands on each of them but escalates none
+     * (see `VGeoFeedbackLoop`).
+     *
+     * @param {VGeoViewCut} view
+     * @returns {number}
+     */
+    slot_of(view: VGeoViewCut): number;
+    /**
+     * The tag a slot's view writes into the want stamps, unique to that view in this frame and never
+     * zero — see `VGEO_CUT_PARAMS_STRUCT.frame_tag`.
+     *
+     * @param {number} slot
+     * @returns {number}
+     */
+    frame_tag_of(slot: number): number;
+    /**
+     * This frame's views, by slot — what a reading of this frame's feedback is about. A copy, since
+     * the reading lands frames later and the table is rebuilt every frame.
+     *
+     * @returns {VGeoViewCut[][]}
+     */
+    frame_slots(): VGeoViewCut[][];
+    /**
+     * The feedback buffer as a resource of `graph`, at the version that graph last wrote.
+     *
+     * The first call for a graph imports the buffer into it; if no graph of this frame has yet, it
+     * also records the clear — the counters and the touch bits, which is everything a kernel adds
+     * to — so the first graph encoded is the one that clears, before anything of this frame writes.
+     *
+     * @param {FrameGraph} graph
+     * @returns {number} resource handle
+     */
+    feedback_in(graph: FrameGraph): number;
+    /**
+     * Hand back the version of the feedback resource a graph's expansion left behind.
+     *
+     * A FrameGraph resource is versioned: the handle an import produced is its first version, and a
+     * second expansion that wrote that version again after the first had produced a later one would
+     * be reading stale contents while claiming not to. The graph says so, loudly, and it is right to.
+     * So the runtime carries each graph's current version and each expansion publishes what it
+     * produced; the readback then reads the last one.
+     *
+     * @param {FrameGraph} graph
+     * @param {number} handle
+     * @returns {void}
+     */
+    publish_feedback(graph: FrameGraph, handle: number): void;
     /**
      * What one expansion site was handed, folded into the parameters every pass of the frame reads.
      *
@@ -208,10 +224,9 @@ export class GPUVirtualGeometryRuntime {
      * defaulted to 1 << 20 against a meshlet collection whose engine default is 2e5, so `vg_draw`
      * bounds-checked against a number five times the buffer it was writing into (REVIEW_LEDGER M6).
      *
-     * One params buffer serves the whole frame, so a frame with sites of different sizes takes the
-     * **minimum** — conservative, and the direction every other bound in the cut fails in. Written
-     * at record time, like everything else here, so the last value published before submit is what
-     * every pass of the frame executes against.
+     * A frame with sites of different sizes takes the **minimum** — conservative, and the direction
+     * every other bound in the cut fails in. Each view writes its params at record time from what
+     * has been declared so far, which is never more than its own site was handed.
      *
      * @param {Object} options
      * @param {number} options.instance_capacity records the VG instance buffer holds
@@ -231,26 +246,25 @@ export class GPUVirtualGeometryRuntime {
      */
     get meshlet_capacity(): number;
     /**
-     * The graph this frame was opened on.
-     *
-     * A cut writes into the feedback resource `begin_frame` created, and a resource handle belongs
-     * to one graph — so a rasterization path running on a *different* graph inside the same frame
-     * (a shadow view builds its own) would be naming a resource that graph has never heard of. The
-     * seam checks this and skips, which is also design §9's position: one cut per view, and shadow
-     * cuts are out of scope for v1.
+     * Close a frame. Nothing may cut until the next opens; reading it is {@link VGeoFeedbackLoop}'s,
+     * which schedules the readback while the last graph is still being recorded.
      *
-     * @returns {FrameGraph|undefined}
+     * @returns {void}
      */
-    get frame_graph(): import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    end_frame(): void;
     /**
-     * Close a frame. The feedback resource stops being valid; reading it is
-     * {@link VGeoFeedbackLoop}'s, which schedules the readback while the graph is still being built.
+     * Release the feedback buffer, which is the one device resource this makes, and close whatever
+     * frame is open so that nothing cuts into the buffer afterwards.
+     *
+     * The pool is not this runtime's to release: it was handed one, and whoever made it tears it
+     * down — after this, since a frame of this runtime writes into the pool's tables.
      *
      * @returns {void}
      */
-    end_frame(): void;
+    destroy(): void;
     #private;
 }
 export type GPUVirtualGeometryPool = import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool;
+export type VGeoViewCut = import("./VGeoViewCut.js").VGeoViewCut;
 export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
 //# sourceMappingURL=GPUVirtualGeometryRuntime.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAkFI;;;;;;;;;;;;;;;OAeG;IACH;QAd2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QAEW,qBAAqB,GAAtC,MAAM;QACW,aAAa,GAA9B,MAAM;OAkFhB;IApID;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IA6HpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;OAQG;IACH,6BAEC;IAED;;;;;OAKG;IACH,oCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,mCAHW,MAAM,GACJ,OAAO,CAanB;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;QAvUA;;WAEG;;;4BAIH;;WAEG;MAiUF;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH;QAH+B,KAAK,EAAzB,UAAU;QACR,MAAM,CA+BlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,wGAEC;IAGD;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;;CACJ;qCAteY,OAAO,6BAA6B,EAAE,sBAAsB;yBAC5D,OAAO,iEAAiE,EAAE,UAAU"}
+{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAiHI;;;;;;;;;;;;;;;OAeG;IACH;QAd2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QAEW,qBAAqB,GAAtC,MAAM;QACW,aAAa,GAA9B,MAAM;OAgFhB;IAzKD;;;;OAIG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IAiKpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;;OAIG;IACH,gCAEC;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,yDAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;OAEG;IACH;;;;;;;;MAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH;QAHgC,IAAI,EAAzB,WAAW;QACT,IAAI,CAoChB;IAwBD;;;;;;;;;;OAUG;IACH,cAHW,WAAW,GACT,MAAM,CA0BlB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,eAFa,WAAW,EAAE,EAAE,CAI3B;IAED;;;;;;;;;OASG;IACH,mBAHW,UAAU,GACR,MAAM,CAkClB;IAED;;;;;;;;;;;;OAYG;IACH,wBAJW,UAAU,UACV,MAAM,GACJ,IAAI,CAOhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;IAED;;;;;;;;OAQG;IACH,WAFa,IAAI,CAOhB;;CACJ;qCArnBY,OAAO,6BAA6B,EAAE,sBAAsB;0BAC5D,OAAO,kBAAkB,EAAE,WAAW;yBACtC,OAAO,iEAAiE,EAAE,UAAU"}