@woosh/meep-engine 3.32.0 → 3.34.0

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

@@ -2,10 +2,11 @@ import { assert } from "../../../../../core/assert.js";
 import { graph_read_buffer } from "../../../buffer/graph_read_buffer.js";
 import { VGEO_CUT_STAT } from "./layout/VGEO_CUT_STAT.js";
 import { VGEO_CUT_STAT_COUNT } from "./layout/VGEO_CUT_STAT_COUNT.js";
-import { VGEO_FEEDBACK_OFFSET } from "./layout/VGEO_FEEDBACK_OFFSET.js";
+import { vgeo_feedback_slot_stats } from "./cut/vgeo_cut_feedback_layout.js";
 
 /**
  * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("./VGeoViewCut.js").VGeoViewCut} VGeoViewCut
  * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
  * @typedef {import("./VGeoResidency.js").VGeoResidency} VGeoResidency
  * @typedef {import("./cut/vgeo_cut_feedback_layout.js").vgeo_cut_feedback_layout} vgeo_cut_feedback_layout
@@ -60,7 +61,14 @@ export class VGeoFeedbackLoop {
     #read_count = 0;
 
     /**
-     * The counters of the last frame that came back — what M1's "selection cost measured" reads.
+     * Set by {@link destroy}; a reading that lands after it is dropped.
+     * @type {boolean}
+     */
+    #destroyed = false;
+
+    /**
+     * The counters of the last frame that came back, for the view that frame was rendered for —
+     * slot 0. Every view's own are on its `VGeoViewCut.stats`.
      * @type {Uint32Array}
      */
     #stats = new Uint32Array(VGEO_CUT_STAT_COUNT);
@@ -145,9 +153,7 @@ export class VGeoFeedbackLoop {
     read(graph) {
         assert.defined(graph, 'graph');
 
-        const feedback = this.#runtime.feedback;
-
-        if (feedback === -1) {
+        if (this.#destroyed || !this.#runtime.frame_open) {
             return false;
         }
 
@@ -174,17 +180,36 @@ export class VGeoFeedbackLoop {
          */
         const reading_frame = this.#runtime.pool.frame;
 
+        /*
+         And which views it is about, by slot. The table is rebuilt every frame and the set of views
+         changes — a point light's faces are in the shadow budget one frame and out the next — so a
+         reading that asked for "the" table when it landed would hand one view's counters to another.
+        */
+        const slots = this.#runtime.frame_slots();
+
+        const feedback = this.#runtime.feedback_in(graph);
+
         this.#in_flight++;
 
         graph_read_buffer({ graph, buffer: feedback, offset: 0, size: layout.word_count * 4 })
             .then(reference => {
                 try {
-                    this.#apply(new Uint32Array(reference.getValue()), layout, reading_frame);
+                    // about a scene torn down since: its views and its residency are gone
+                    if (!this.#destroyed) {
+                        this.#apply(
+                            new Uint32Array(reference.getValue()), layout, reading_frame, slots
+                        );
+                    }
                 } finally {
                     reference.release();
                 }
             })
             .catch(error => {
+                if (this.#destroyed) {
+                    // the teardown destroyed the buffer the mapping waited on; nothing failed
+                    return;
+                }
+
                 // a timed-out or failed mapping costs a frame of feedback, not a frame of rendering
                 console.warn('vgeo: feedback readback failed', error);
             })
@@ -201,20 +226,40 @@ export class VGeoFeedbackLoop {
      * @param {Uint32Array} words
      * @param {ReturnType<vgeo_cut_feedback_layout>} layout the frame's own, not the current one
      * @param {number} reading_frame the frame this reading is about
+     * @param {VGeoViewCut[][]} slots the frame's views, by slot
      */
-    #apply(words, layout, reading_frame) {
-        for (let i = 0; i < VGEO_CUT_STAT_COUNT; i++) {
-            this.#stats[i] = words[VGEO_FEEDBACK_OFFSET.STATS + i];
+    #apply(words, layout, reading_frame, slots) {
+        for (let slot = 0; slot < slots.length; slot++) {
+            const base = vgeo_feedback_slot_stats(slot);
+
+            /*
+             A slot two views shared — they were past the frame's layout — holds the sum of their
+             counters, so a remainder in it says one of them ran out and not which. Escalating both
+             would raise a bound that was never binding, for good; each has a slot of its own next
+             frame, and escalates from that.
+            */
+            const remaining = slots[slot].length === 1 ? words[base + VGEO_CUT_STAT.QUEUE_REMAINING] : 0;
+
+            for (const view of slots[slot]) {
+                for (let i = 0; i < VGEO_CUT_STAT_COUNT; i++) {
+                    view.stats[i] = words[base + i];
+                }
+
+                /*
+                 One counter is not a statistic, it is an instruction. `QUEUE_REMAINING` is non-zero
+                 exactly when the descent ran out of wavefronts and abandoned subtrees it had not
+                 expanded — a hole in the picture rather than a coarser surface — and this is the only
+                 moment anything on the host learns it. The view owns what to do about it; the loop's
+                 job here is the same as with a want, which is to carry the reading to whoever it is
+                 about.
+                */
+                view.note_incomplete_descent(remaining, this.#runtime);
+            }
         }
 
-        /*
-         One counter is not a statistic, it is an instruction. `QUEUE_REMAINING` is non-zero exactly
-         when the descent ran out of wavefronts and abandoned subtrees it had not expanded — a hole
-         in the picture rather than a coarser surface — and this is the only moment anything on the
-         host learns it. The runtime owns what to do about it; the loop's job here is the same as
-         with a want, which is to carry the reading to whoever it is about.
-        */
-        this.#runtime.note_incomplete_descent(this.#stats[VGEO_CUT_STAT.QUEUE_REMAINING]);
+        for (let i = 0; i < VGEO_CUT_STAT_COUNT; i++) {
+            this.#stats[i] = words[vgeo_feedback_slot_stats(0) + i];
+        }
 
         this.#residency.apply(words, layout, reading_frame);
     }
@@ -229,14 +274,18 @@ export class VGeoFeedbackLoop {
     }
 
     /**
-     * Give up on this loop: the same as {@link abort}, under the name a host tears things down by.
+     * Give up on this loop: {@link abort}, and drop every reading still in flight.
      *
      * The loop owns no device resource, so there is nothing else to release — what it owns is
-     * outstanding *work*.
+     * outstanding *work*, and a reading is some: it lands frames after its cut, by which time the
+     * views it is about and the residency it feeds may be torn down, and the mapping it waits on may
+     * have been aborted by that teardown. A destroyed loop schedules nothing more.
      *
      * @returns {void}
      */
     destroy() {
+        this.#destroyed = true;
+
         this.abort();
     }
 }

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

@@ -72,7 +72,8 @@ export class VGeoPageFetcher {
      */
     cancel(reader: VGeoContainerReader): number;
     /**
-     * Terminate the workers and reject what they were doing.
+     * Terminate the workers and reject what they were doing, and refuse every fetch after — for
+     * good, because a pool spawned again after this is one nothing will terminate.
      *
      * @returns {void}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoPageFetcher.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IA0EI;;;;;;OAMG;IACH;QAL4B,YAAY,GAA7B,MAAM;QACuB,WAAW,SAA5B,MAAM;OAS5B;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;;;OAOG;IACH,cAPW,mBAAmB,cACnB,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CAc7B;IAED;;;;;;OAMG;IACH,eAHW,mBAAmB,GACjB,MAAM,CAkClB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAoBhB;;CAgOJ;kCAzcY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ"}
+{"version":3,"file":"VGeoPageFetcher.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAgFI;;;;;;OAMG;IACH;QAL4B,YAAY,GAA7B,MAAM;QACuB,WAAW,SAA5B,MAAM;OAS5B;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;;;OAOG;IACH,cAPW,mBAAmB,cACnB,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CAqB7B;IAED;;;;;;OAMG;IACH,eAHW,mBAAmB,GACjB,MAAM,CAkClB;IAED;;;;;OAKG;IACH,WAFa,IAAI,CAsBhB;;CAgOJ;kCAzdY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ"}

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

@@ -57,6 +57,12 @@ export class VGeoPageFetcher {
      */
     #no_workers = false;
 
+    /**
+     * Set by {@link destroy}; every fetch after it is refused.
+     * @type {boolean}
+     */
+    #destroyed = false;
+
     /**
      * @type {number}
      */
@@ -161,6 +167,13 @@ export class VGeoPageFetcher {
     fetch(reader, page_index, frame_offset, fetch_size, signal = undefined) {
         assert.defined(reader, 'reader');
 
+        if (this.#destroyed) {
+            // the pool was terminated; an empty pool is otherwise what spawns one
+            return Promise.reject(
+                new VGeoFetchError(`page ${page_index}: the fetcher was destroyed`, false, 'destroyed')
+            );
+        }
+
         if (this.#worker_count > 0 && !this.#no_workers && reader.source.descriptor !== undefined) {
             const worker = this.#worker_for();
 
@@ -214,11 +227,14 @@ export class VGeoPageFetcher {
     }
 
     /**
-     * Terminate the workers and reject what they were doing.
+     * Terminate the workers and reject what they were doing, and refuse every fetch after — for
+     * good, because a pool spawned again after this is one nothing will terminate.
      *
      * @returns {void}
      */
     destroy() {
+        this.#destroyed = true;
+
         for (const entry of this.#pending.values()) {
             // the in-process ones are still reading; terminating a worker is what stops the others
             entry.controller?.abort();

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

@@ -176,6 +176,10 @@ export class VGeoResidency {
     /**
      * Stop every fetch every registered container has on the wire.
      *
+     * Only those: a fetch still waiting in the gate for a slot is not on the wire, and it starts
+     * when a slot comes free, because its container is still registered. {@link unregister} and
+     * {@link destroy} are what stop those too.
+     *
      * @returns {void}
      */
     abort(): void;

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoResidency.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoResidency.js"],"names":[],"mappings":"AA2GA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAiKI;;;;;;;OAOG;IACH;QAN2C,IAAI,EAApC,sBAAsB;QACS,OAAO,GAAtC,oBAAoB;QACM,IAAI,GAA9B,eAAe;QACW,OAAO,GAAjC,eAAe;OA8BzB;IAID;;OAEG;IACH,oCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,oBAEC;IAED;;;;OAIG;IACH,gCAGC;IAED,+BAEC;IAED,iCAEC;IAED,6BAEC;IAED,2BAEC;IAED,iCAEC;IAED,gCAEC;IAED;;;;OAIG;IACH,oCAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;OAGG;IACH,iCAEC;IAED,gCAEC;IAED,+BAEC;IAED,8BAEC;IAED;;OAEG;IACH,qCAQC;IAID;;;;;;;;;;OAUG;IACH,iBAHW,mBAAmB,GACjB,MAAM,CA8ClB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,OAAO,CAgBnB;IAED;;;OAGG;IACH,sBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,cAJW,mBAAmB,cACnB,MAAM,GACJ,QAAQ,GAAC,UAAU,GAAC,aAAa,GAAC,KAAK,GAAC,MAAM,GAAC,cAAc,CAqBzE;IA6CD;;;;OAIG;IACH,SAFa,IAAI,CAOhB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAUhB;IAED;;;;OAIG;IACH,qBAFa,MAAM,CAkBlB;IAID;;;;;;;;;OASG;IACH,aANW,WAAW,UACX;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAChF,UAAgB,EAAE,MAAM,CAAA;KAAC,iBACf,MAAM,GACJ,IAAI,CA6HhB;IA2FD;;;;;;OAMG;IACH,yBAHW,MAAM,GACJ,OAAO,CAgBnB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,OAAO,CAoCnB;;CAqXJ;kCAl2CY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ;qCAC7C,OAAO,6BAA6B,EAAE,sBAAsB;qCALpC,2BAA2B;gCALhC,gDAAgD;gCAIhD,sBAAsB"}
+{"version":3,"file":"VGeoResidency.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoResidency.js"],"names":[],"mappings":"AA4GA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAiKI;;;;;;;OAOG;IACH;QAN2C,IAAI,EAApC,sBAAsB;QACS,OAAO,GAAtC,oBAAoB;QACM,IAAI,GAA9B,eAAe;QACW,OAAO,GAAjC,eAAe;OA8BzB;IAID;;OAEG;IACH,oCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,oBAEC;IAED;;;;OAIG;IACH,gCAGC;IAED,+BAEC;IAED,iCAEC;IAED,6BAEC;IAED,2BAEC;IAED,iCAEC;IAED,gCAEC;IAED;;;;OAIG;IACH,oCAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;OAGG;IACH,iCAEC;IAED,gCAEC;IAED,+BAEC;IAED,8BAEC;IAED;;OAEG;IACH,qCAQC;IAID;;;;;;;;;;OAUG;IACH,iBAHW,mBAAmB,GACjB,MAAM,CA8ClB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,OAAO,CAgBnB;IAED;;;OAGG;IACH,sBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,cAJW,mBAAmB,cACnB,MAAM,GACJ,QAAQ,GAAC,UAAU,GAAC,aAAa,GAAC,KAAK,GAAC,MAAM,GAAC,cAAc,CAqBzE;IA6CD;;;;;;;;OAQG;IACH,SAFa,IAAI,CAOhB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAUhB;IAED;;;;OAIG;IACH,qBAFa,MAAM,CAkBlB;IAID;;;;;;;;;OASG;IACH,aANW,WAAW,UACX;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAChF,UAAgB,EAAE,MAAM,CAAA;KAAC,iBACf,MAAM,GACJ,IAAI,CA6HhB;IAyGD;;;;;;OAMG;IACH,yBAHW,MAAM,GACJ,OAAO,CAgBnB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,OAAO,CAoCnB;;CAgYJ;kCA/3CY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ;qCAC7C,OAAO,6BAA6B,EAAE,sBAAsB;qCALpC,2BAA2B;gCANhC,gDAAgD;gCAKhD,sBAAsB"}

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

@@ -1,6 +1,7 @@
 import { assert } from "../../../../../core/assert.js";
 import { ConcurrencyGate } from "../../../../../core/process/ConcurrencyGate.js";
-import { VGEO_FEEDBACK_OFFSET } from "./layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGeoFetchError } from "../format/read/VGeoPageFetcherCore.js";
+import { vgeo_feedback_slot_want_count } from "./cut/vgeo_cut_feedback_layout.js";
 import { VGEO_PAGE_ROW_OFFSET } from "./layout/VGEO_PAGE_ROW_OFFSET.js";
 import { VGEO_WANT_WORDS } from "./layout/VGEO_WANT_WORDS.js";
 import { VGeoPageFetcher } from "./VGeoPageFetcher.js";
@@ -675,6 +676,10 @@ export class VGeoResidency {
     /**
      * Stop every fetch every registered container has on the wire.
      *
+     * Only those: a fetch still waiting in the gate for a slot is not on the wire, and it starts
+     * when a slot comes free, because its container is still registered. {@link unregister} and
+     * {@link destroy} are what stop those too.
+     *
      * @returns {void}
      */
     abort() {
@@ -913,7 +918,13 @@ export class VGeoResidency {
     }
 
     /**
-     * Order this reading's want records by priority, highest first.
+     * Order this reading's want records by priority, highest first — every view's, on one scale.
+     *
+     * Each view wrote its own slice, and a record's priority is its error over that view's own
+     * threshold, so a shadow view's wants and the main view's rank against each other on what they
+     * are worth rather than on which view recorded first (SHADOW_PLAN_2026_09_28 §2.4). A page two
+     * views both want appears twice; the second is collapsed in {@link apply}, which finds it pending
+     * or resident by then.
      *
      * A sort of at most `want_capacity` indices. It is not on the GPU, deliberately: the list is
      * capped, a sort of two thousand numbers is microseconds, and a device sort is a dozen dispatches
@@ -924,21 +935,29 @@ export class VGeoResidency {
      * @returns {number} records
      */
     #rank_wants(words, layout) {
-        const capacity = Math.floor((layout.word_count - layout.want_base) / VGEO_WANT_WORDS);
-
-        // clamped: the count is an atomicAdd that ran past the capacity the kernel refused to write at
-        const count = Math.min(words[VGEO_FEEDBACK_OFFSET.WANT_COUNT], capacity);
+        const order = this.#order;
 
-        this.#last_want_count = count;
+        order.length = 0;
 
-        const order = this.#order;
+        for (let slot = 0; slot < layout.slot_count; slot++) {
+            // clamped: the count is an atomicAdd that ran past the capacity the kernel refused to
+            // write at
+            const count = Math.min(
+                words[vgeo_feedback_slot_want_count(slot)], layout.slot_want_capacity
+            );
 
-        order.length = count;
+            // records are numbered across the whole want region, slice after slice
+            const first = slot * layout.slot_want_capacity;
 
-        for (let i = 0; i < count; i++) {
-            order[i] = i;
+            for (let i = 0; i < count; i++) {
+                order.push(first + i);
+            }
         }
 
+        const count = order.length;
+
+        this.#last_want_count = count;
+
         const priority = i => decode_float(words[layout.want_base + i * VGEO_WANT_WORDS + 3]);
 
         order.sort((a, b) => priority(b) - priority(a));
@@ -1307,7 +1326,18 @@ export class VGeoResidency {
 
         this.#gate.submit(
             priority,
-            () => this.#fetcher.fetch(reader, page_index, frame_offset, fetch_size)
+            /*
+             Whether the container is still here is asked when the slot comes free, not only when
+             the fetch was queued: the gate cannot drop a closure, and `unregister` cancels only
+             what the fetcher has already been handed — so a fetch still waiting here started
+             anyway, reading a container nobody held and, behind a destroyed fetcher, spawning its
+             worker pool again.
+            */
+            () => this.#geometries.get(reader) === geometry
+                ? this.#fetcher.fetch(reader, page_index, frame_offset, fetch_size)
+                : Promise.reject(new VGeoFetchError(
+                    `page ${page_index}: the container left before its fetch started`, false, 'cancelled'
+                ))
         )
             .then(
                 page => {

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

@@ -10,8 +10,9 @@
  *
  * ## Why the params are here and not on the runtime
  *
- * `projection_k` is `screen_height / (2·tan(fov_y/2))`: a property of a render target and a camera,
- * which is to say of a view. One buffer on the runtime meant one value for the frame, written from
+ * `projection_k` is pixels per unit — `screen_height / (2·tan(fov_y/2))` for a perspective view:
+ * a property of a render target and a camera, which is to say of a view. One buffer on the runtime
+ * meant one value for the frame, written from
  * whichever view opened it — so a shadow cascade cut against the main view's projection and
  * selected a level for a screen it is not drawn to. That is a live defect independent of anything
  * a kept cut needs, and the fix is that each view writes its own.
@@ -33,6 +34,21 @@ export class VGeoViewCut {
         device: GPUDevice;
         label?: string;
     });
+    /**
+     * How much coarser than the runtime's threshold this view cuts: its τ is `runtime.tau ×
+     * tau_scale`. A scale rather than a τ of its own, so the runtime's τ stays the one lever — a
+     * view set to twice the error stays twice it wherever the lever goes. Nothing in the runtime
+     * knows what kind of view this is; whoever owns the view may set it.
+     *
+     * @type {number}
+     */
+    tau_scale: number;
+    /**
+     * What the last reading of this view's slot said, indexed by `VGEO_CUT_STAT`.
+     *
+     * @type {Uint32Array}
+     */
+    stats: Uint32Array;
     /**
      * The uniform every pass of this view's cut reads.
      *
@@ -43,6 +59,10 @@ export class VGeoViewCut {
      * @returns {number}
      */
     get projection_k(): number;
+    /**
+     * @returns {number}
+     */
+    get distance_weight(): number;
     /**
      * Where this view's last cut stood, as one bit per page row.
      *
@@ -83,31 +103,92 @@ export class VGeoViewCut {
      */
     resize_frontier(page_row_capacity: number): void;
     /**
-     * Take this view's projection from the target it draws to and the camera it draws with.
+     * Take this view's projection from the target it draws to and the matrix it draws with.
+     *
+     * **From the matrix, not from the camera's kind.** `P[0]` and `P[5]` are clip units per view
+     * unit on each axis for a perspective and an orthographic projection alike, so half of pixels
+     * times either is pixels per unit: `height / (2·tan(fov_y/2))` for this engine's infinite
+     * reverse-Z perspective, and `height / (top − bottom)` for its reverse-Z orthographic. The finer
+     * of the two axes is taken, which is the one a cascade needs — its rect is square and its
+     * extent is not — and which for a perspective view whose aspect matches its target is the
+     * same number either way. `−P[11]` is 1 for perspective, whose clip w is the view depth, and 0
+     * for orthographic, whose is not; that is the weight distance divides the error by.
+     *
+     * Anything else is refused: an oblique or otherwise unusual projection has no single pixels per
+     * unit, and a cut selected against a guess at one draws a level for a screen nobody has.
      *
      * @param {Object} options
-     * @param {number} options.screen_height pixels of the render target
-     * @param {number} options.fov_y radians
+     * @param {number} options.width pixels of the render target
+     * @param {number} options.height pixels of the render target
+     * @param {ArrayLike<number>} options.projection_matrix column-major, as `Camera.projection_matrix`
      * @returns {void}
      */
-    set_projection({ screen_height, fov_y }: {
-        screen_height: number;
-        fov_y: number;
+    set_projection({ width, height, projection_matrix }: {
+        width: number;
+        height: number;
+        projection_matrix: ArrayLike<number>;
     }): void;
+    /**
+     * Wavefronts this view's descent may run in a frame of `runtime`: the runtime's starting bound,
+     * or what this view's own readings have raised it to.
+     *
+     * @param {GPUVirtualGeometryRuntime} runtime
+     * @returns {number}
+     */
+    iterations_under(runtime: GPUVirtualGeometryRuntime): number;
+    /**
+     * Times this view's bound has been raised. Zero for the life of almost every view.
+     *
+     * @returns {number}
+     */
+    get iteration_escalations(): number;
+    /**
+     * A reading of this view's slot saying its descent stopped with work still queued — raise this
+     * view's 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.
+     *
+     * **Per view.** One bound for the frame let one hungry view — a far cascade, a point face in the
+     * shadow budget for one frame — double every site's ladder for the life of the scene
+     * (SHADOW_PLAN_2026_09_28 §2.4).
+     *
+     * **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.
+     *
+     * @param {number} remaining items the descent still held when it was abandoned
+     * @param {GPUVirtualGeometryRuntime} runtime whose starting bound and ceiling apply
+     * @returns {boolean} whether the bound moved
+     */
+    note_incomplete_descent(remaining: number, runtime: GPUVirtualGeometryRuntime): boolean;
     /**
      * Publish the frame's shared settings and this view's own, as one uniform.
      *
-     * Everything but `projection_k` and `flags` is a property of the runtime or the frame, so it is
-     * read from the runtime at write time rather than mirrored here — a second copy of `tau` is a
-     * second thing to forget to update.
+     * Everything but the projection, the threshold's scale, the slot and `flags` is a property of the
+     * runtime or the frame, so it is read from the runtime at write time rather than mirrored here —
+     * a second copy of `tau` is a second thing to forget to update.
      *
      * @param {Object} options
      * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+     * @param {number} options.slot this view's slot in the frame's feedback
      * @param {boolean} [options.coarsen] whether this view's cut may walk up
      * @returns {void}
      */
-    write_params({ runtime, coarsen }: {
+    write_params({ runtime, slot, coarsen }: {
         runtime: GPUVirtualGeometryRuntime;
+        slot: number;
         coarsen?: boolean;
     }): void;
     destroy(): void;

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoViewCut.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoViewCut.js"],"names":[],"mappings":"AAgBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAwCI;;;;OAIG;IACH;QAH8B,MAAM;QACR,KAAK,GAAtB,MAAM;OAehB;IAED;;;;OAIG;IACH,+BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,2BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAFa,IAAI,CAchB;IAED;;;;;;;;;;OAUG;IACH,mCAHW,MAAM,GACJ,IAAI,CAkBhB;IAED;;;;;;;OAOG;IACH;QAJ2B,aAAa,EAA7B,MAAM;QACU,KAAK,EAArB,MAAM;QACJ,IAAI,CAShB;IAED;;;;;;;;;;;OAWG;IACH;QAJ8C,OAAO,EAA1C,yBAAyB;QACP,OAAO,GAAzB,OAAO;QACL,IAAI,CA8BhB;IAED,gBAIC;;CACJ;wCAhPY,OAAO,gCAAgC,EAAE,yBAAyB"}
+{"version":3,"file":"VGeoViewCut.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoViewCut.js"],"names":[],"mappings":"AAsBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA6EI;;;;OAIG;IACH;QAH8B,MAAM;QACR,KAAK,GAAtB,MAAM;OAehB;IAhDD;;;;;;;OAOG;IACH,WAFU,MAAM,CAEF;IAed;;;;OAIG;IACH,OAFU,WAAW,CAEwB;IAsB7C;;;;OAIG;IACH,+BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,8BAEC;IAED;;;;OAIG;IACH,2BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAFa,IAAI,CAchB;IAED;;;;;;;;;;OAUG;IACH,mCAHW,MAAM,GACJ,IAAI,CAkBhB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;QAL2B,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACqB,iBAAiB,EAA5C,UAAU,MAAM,CAAC;QACf,IAAI,CAmBhB;IAED;;;;;;OAMG;IACH,0BAHW,yBAAyB,GACvB,MAAM,CAIlB;IAED;;;;OAIG;IACH,oCAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,mCAJW,MAAM,WACN,yBAAyB,GACvB,OAAO,CAgBnB;IAED;;;;;;;;;;;;OAYG;IACH;QAL8C,OAAO,EAA1C,yBAAyB;QACT,IAAI,EAApB,MAAM;QACY,OAAO,GAAzB,OAAO;QACL,IAAI,CAmChB;IAED,gBAIC;;CACJ;wCA5XY,OAAO,gCAAgC,EAAE,yBAAyB"}