@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../header/VGeoLevelRecord.js").VGeoLevelRecord} VGeoLevelRecord
+ */
 /**
  * A `.vgeo` file's header and level table, decoded — the first 256 bytes plus `32 · level_count`
  * after them, and nothing else.
@@ -130,4 +133,5 @@ export class VGeoContainerHeader {
      */
     get head_size(): number;
 }
+export type VGeoLevelRecord = import("../header/VGeoLevelRecord.js").VGeoLevelRecord;
 //# sourceMappingURL=VGeoContainerHeader.d.ts.map

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoContainerHeader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH;IACI;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;OAEG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,sBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;OAEG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;;OAIG;IACH,wBAEC;CACJ"}
+{"version":3,"file":"VGeoContainerHeader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH;IACI;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;OAEG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,sBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;OAEG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;OAIG;IACH,wBAEC;CACJ;8BA7JY,OAAO,8BAA8B,EAAE,eAAe"}

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../header/VGeoLevelRecord.js").VGeoLevelRecord} VGeoLevelRecord
+ */
+
 /**
  * A `.vgeo` file's header and level table, decoded — the first 256 bytes plus `32 · level_count`
  * after them, and nothing else.

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.d.ts

@@ -69,7 +69,7 @@ export class VGeoContainerReader {
     /**
      * @returns {VGeoByteSource}
      */
-    get source(): VGeoByteSource;
+    get source(): import("./VGeoByteSource.js").VGeoByteSource;
     /**
      * @returns {VGeoReadOptions}
      */
@@ -133,7 +133,7 @@ export class VGeoContainerReader {
      *
      * @returns {VGeoPage}
      */
-    get root(): VGeoPage;
+    get root(): import("./VGeoPage.js").VGeoPage;
     /**
      * Every resident page, sorted by page index.
      *
@@ -144,7 +144,7 @@ export class VGeoContainerReader {
      *
      * @returns {VGeoPage[]}
      */
-    get pages(): VGeoPage[];
+    get pages(): import("./VGeoPage.js").VGeoPage[];
     /**
      * Every resident page, in arrival order, allocating nothing.
      *
@@ -277,6 +277,26 @@ export class VGeoContainerReader {
      * @returns {number} how many were abandoned
      */
     cancel_all(): number;
+    /**
+     * Take a page decoded elsewhere — on a worker, by `VGeoPageFetcher` — as resident.
+     *
+     * The one door into the page map for a page this reader did not fetch itself, and the same
+     * door its own fetches use. Idempotent: a page already here is returned rather than replaced,
+     * because residency is the accounting and two arrivals must cost one page.
+     *
+     * @param {VGeoPage} page
+     * @returns {VGeoPage} the resident page, which is the one given unless one was already here
+     */
+    adopt(page: VGeoPage): VGeoPage;
+    /**
+     * Record that a page will not arrive from this source, so that it is not asked for again
+     * until {@link clear_quarantine}. What a fetch that ran elsewhere reports back.
+     *
+     * @param {number} page_index
+     * @param {string} reason
+     * @returns {void}
+     */
+    quarantine_page(page_index: number, reason: string): void;
     /**
      * Install the page a want names.
      *
@@ -371,5 +391,11 @@ export class VGeoContainerReader {
     release_head(): number;
     #private;
 }
+export type VGeoByteSource = import("./VGeoByteSource.js").VGeoByteSource;
+export type VGeoContainerHeader = import("./VGeoContainerHeader.js").VGeoContainerHeader;
+export type VGeoDefect = import("../VGeoDefect.js").VGeoDefect;
+export type VGeoDirectory = import("./VGeoDirectory.js").VGeoDirectory;
+export type VGeoPage = import("./VGeoPage.js").VGeoPage;
+export type VGeoPageWant = import("./VGeoPageWant.js").VGeoPageWant;
 import { VGeoReadOptions } from "./VGeoReadOptions.js";
 //# sourceMappingURL=VGeoContainerReader.d.ts.map

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAwPI;;;;;;;;OAQG;IACH,8CALW,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IAhJD;;;OAGG;IACH,8CAFW,eAAe,EAOzB;IA/HD;;OAEG;IACH,4BAAmB;IAEnB;;;;OAIG;IACH,WAFU,gBAAc,SAAS,CAEX;IAuHtB;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;OAaG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,2CAEC;IAED;;;;;OAKG;IACH,yBAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;;;;;;;;;;;OAYG;IACH,qBAEC;IAED;;;;;;;;;OASG;IACH,wBAEC;IAED;;;;OAIG;IACH,kBAFa,0BAA0B,CAItC;IA0FD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,WAAS,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,iCAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB;IAoOD;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;OASG;IACH,8BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,cAFa,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAI9C;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAPW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,iBAAiB,CAoC7B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHW,MAAM,GACJ,OAAO,CAYnB;IAED;;;OAGG;IACH,cAFa,MAAM,CAYlB;IA0ED;;;;;OAKG;IACH,kCAFa,iBAAiB,CAI7B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,qBANW,cAAc,UACd,MAAM,WAEN,WAAW,GACT,QAAQ,UAAU,CAAC,CA+D/B;IAED;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,OAAO,CAoDnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,sBAAsB,CAkBlC;IAED;;;;;;;;OAQG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAMzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,YAAY,CAAC,CAYjC;IAiCD;;;;;;;;;OASG;IACH,gBAFa,MAAM,CAQlB;;CA8DJ;gCA9vC+B,sBAAsB"}
+{"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IA8PI;;;;;;;;OAQG;IACH,oBANW,cAAc,YACd,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IAhJD;;;OAGG;IACH,oBAHW,cAAc,YACd,eAAe,EAOzB;IArID;;OAEG;IACH,QAFU,mBAAmB,CAEV;IAEnB;;;;OAIG;IACH,WAFU,aAAa,GAAC,SAAS,CAEX;IA6HtB;;OAEG;IACH,2DAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;OAaG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,2CAEC;IAED;;;;;OAKG;IACH,yBAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;;;;;;;;;;;OAYG;IACH,6CAEC;IAED;;;;;;;;;OASG;IACH,gDAEC;IAED;;;;OAIG;IACH,kBAFa,iBAAiB,QAAQ,CAAC,CAItC;IA0FD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,QAAQ,GAAC,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,iCAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB;IAoOD;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;OASG;IACH,8BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,cAFa,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAI9C;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAPW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,QAAQ,QAAQ,CAAC,CAoC7B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHW,MAAM,GACJ,OAAO,CAYnB;IAED;;;OAGG;IACH,cAFa,MAAM,CAYlB;IA6CD;;;;;;;;;OASG;IACH,YAHW,QAAQ,GACN,QAAQ,CAqBpB;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,IAAI,CAMhB;IACD;;;;;OAKG;IACH,mBAHW,YAAY,GACV,QAAQ,QAAQ,CAAC,CAI7B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,qBANW,YAAY,EAAE,UACd,MAAM,WAEN,WAAW,GACT,QAAQ,QAAQ,EAAE,CAAC,CA+D/B;IAED;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,OAAO,CAsDnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,QAAQ,aAAa,CAAC,CAkBlC;IAED;;;;;;;;OAQG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAMzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,UAAU,EAAE,CAAC,CAYjC;IAiCD;;;;;;;;;OASG;IACH,gBAFa,MAAM,CAQlB;;CA6BJ;6BAvvCY,OAAO,qBAAqB,EAAE,cAAc;kCAC5C,OAAO,0BAA0B,EAAE,mBAAmB;yBACtD,OAAO,kBAAkB,EAAE,UAAU;4BACrC,OAAO,oBAAoB,EAAE,aAAa;uBAC1C,OAAO,eAAe,EAAE,QAAQ;2BAChC,OAAO,mBAAmB,EAAE,YAAY;gCAXrB,sBAAsB"}

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js

@@ -1,15 +1,22 @@
 import { assert } from "../../../../../../core/assert.js";
-import { BinaryBuffer } from "../../../../../../core/binary/BinaryBuffer.js";
-import { vgeo_compute_frame_checksum } from "../checksum/vgeo_compute_frame_checksum.js";
 import { VGEO_NO_CHILD } from "../cluster/VGEO_NO_CHILD.js";
 import { VGEO_SAME_PAGE } from "../cluster/VGEO_SAME_PAGE.js";
-import { VGEO_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
 import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
+import { VGeoPageFetcherCore } from "./VGeoPageFetcherCore.js";
 import { VGeoReadOptions } from "./VGeoReadOptions.js";
 import { vgeo_read_directory } from "./vgeo_read_directory.js";
 import { vgeo_read_header, vgeo_resident_head_size, VGEO_MIN_HEAD_BYTES } from "./vgeo_read_header.js";
 import { vgeo_read_page } from "./vgeo_read_page.js";
 
+/**
+ * @typedef {import("./VGeoByteSource.js").VGeoByteSource} VGeoByteSource
+ * @typedef {import("./VGeoContainerHeader.js").VGeoContainerHeader} VGeoContainerHeader
+ * @typedef {import("../VGeoDefect.js").VGeoDefect} VGeoDefect
+ * @typedef {import("./VGeoDirectory.js").VGeoDirectory} VGeoDirectory
+ * @typedef {import("./VGeoPage.js").VGeoPage} VGeoPage
+ * @typedef {import("./VGeoPageWant.js").VGeoPageWant} VGeoPageWant
+ */
+
 /**
  * Everything in the container is little-endian (`VGEO_FORMAT.md` §2).
  * @type {boolean}
@@ -121,6 +128,12 @@ export class VGeoContainerReader {
      */
     #quarantined = new Map();
 
+    /**
+     * Built on first fetch; see {@link #fetcher_core}.
+     * @type {VGeoPageFetcherCore|undefined}
+     */
+    #core;
+
     /**
      * The speculative head prefix, while it is still paying for itself.
      *
@@ -861,6 +874,26 @@ export class VGeoContainerReader {
         return cancelled;
     }
 
+    /**
+     * The fetch, verify and decode logic, over this reader's head-aware read — the same object a
+     * worker runs over a byte source of its own.
+     *
+     * @returns {VGeoPageFetcherCore}
+     */
+    #fetcher_core() {
+        if (this.#core === undefined) {
+            this.#core = new VGeoPageFetcherCore({
+                read: (offset, length, signal) => this.#read(offset, length, signal),
+                asset_id_low64: () => this.header.asset_id_low64,
+                verify_frames: this.#options.verify_frames,
+                fetch_retries: this.#options.fetch_retries,
+                fetch_retry_backoff_ms: this.#options.fetch_retry_backoff_ms,
+            });
+        }
+
+        return this.#core;
+    }
+
     /**
      * One page, retried a bounded number of times and then quarantined — §10.
      *
@@ -871,68 +904,63 @@ export class VGeoContainerReader {
      * @returns {Promise<VGeoPage>}
      */
     async #fetch_page(page_index, frame_offset, fetch_size, signal) {
-        const retries = this.#options.fetch_retries;
-
-        for (let attempt = 0; ; attempt++) {
-            try {
-                return await this.#read_page(page_index, frame_offset, fetch_size, signal);
-            } catch (e) {
-                if (signal.aborted) {
-                    // cancelled rather than failed: nothing is wrong with this page
-                    throw signal.reason ?? e;
-                }
-
-                const reason = String(e?.message ?? e);
-
-                if (attempt >= retries) {
-                    this.#quarantined.set(page_index, reason);
-
-                    throw new Error(
-                        `page ${page_index} is quarantined after ${attempt + 1} attempt(s): ${reason}`
-                    );
-                }
+        try {
+            const page = await this.#fetcher_core().fetch(page_index, frame_offset, fetch_size, signal);
 
-                await delay(this.#options.fetch_retry_backoff_ms * (1 << attempt), signal);
+            return this.adopt(page);
+        } catch (e) {
+            if (e?.quarantine === true) {
+                this.#quarantined.set(page_index, e.reason);
             }
+
+            throw e;
         }
     }
 
     /**
-     * One attempt: the bytes, the checks, the decode, and the residency it becomes.
+     * Take a page decoded elsewhere — on a worker, by `VGeoPageFetcher` — as resident.
      *
-     * @param {number} page_index
-     * @param {number} frame_offset
-     * @param {number} fetch_size
-     * @param {AbortSignal} signal
-     * @returns {Promise<VGeoPage>}
+     * The one door into the page map for a page this reader did not fetch itself, and the same
+     * door its own fetches use. Idempotent: a page already here is returned rather than replaced,
+     * because residency is the accounting and two arrivals must cost one page.
+     *
+     * @param {VGeoPage} page
+     * @returns {VGeoPage} the resident page, which is the one given unless one was already here
      */
-    async #read_page(page_index, frame_offset, fetch_size, signal) {
-        const bytes = await this.#read(frame_offset, fetch_size, signal);
-
-        if (this.#options.verify_frames) {
-            this.#verify_frame(bytes, page_index);
-        }
+    adopt(page) {
+        assert.defined(page, 'page');
 
-        const page = vgeo_read_page(bytes, page_index);
+        const existing = this.#pages.get(page.index);
 
-        page.frame_offset = frame_offset;
-
-        // Two callers can reach here for one page only if the second started before the first
-        // resolved, which `#pending` already prevents — but residency is the accounting, so it is
-        // read here rather than assumed.
-        if (!this.#pages.has(page_index)) {
-            this.#pages.set(page_index, page);
+        if (existing !== undefined) {
+            return existing;
+        }
 
-            this.#resident_bytes += page.decoded_size;
+        this.#pages.set(page.index, page);
+        this.#resident_bytes += page.decoded_size;
 
-            // after the page is resident, because the cascade reads residency to decide whether a
-            // reference lands on a counter or waits in the pending index — including this page's own
+        // after the page is resident, because the cascade reads residency to decide whether a
+        // reference lands on a counter or waits in the pending index — including this page's own
+        if (this.#options.track_selectability) {
             this.#activate_page(page);
         }
 
-        return this.#pages.get(page_index);
+        return page;
     }
 
+    /**
+     * Record that a page will not arrive from this source, so that it is not asked for again
+     * until {@link clear_quarantine}. What a fetch that ran elsewhere reports back.
+     *
+     * @param {number} page_index
+     * @param {string} reason
+     * @returns {void}
+     */
+    quarantine_page(page_index, reason) {
+        assert.isNonNegativeInteger(page_index, 'page_index');
+
+        this.#quarantined.set(page_index, String(reason));
+    }
     /**
      * Install the page a want names.
      *
@@ -1058,8 +1086,10 @@ export class VGeoContainerReader {
         */
         const selectable = this.#selectable.get(page_index);
 
-        for (let group = 0; group < selectable.length; group++) {
-            this.#cascade_deactivate(page_index, group);
+        if (selectable !== undefined) {
+            for (let group = 0; group < selectable.length; group++) {
+                this.#cascade_deactivate(page_index, group);
+            }
         }
 
         /*
@@ -1067,7 +1097,7 @@ export class VGeoContainerReader {
          that are still here and still selectable — so they move back to the pending index, and a
          re-install starts its counters where they left off rather than at zero.
         */
-        const live = this.#live_refs.get(page_index);
+        const live = this.#live_refs.get(page_index) ?? new Uint16Array(0);
 
         const held = new Map();
 
@@ -1250,75 +1280,4 @@ export class VGeoContainerReader {
 
         this.#head = grown;
     }
-
-    /**
-     * Check a frame against its identity-seeded checksum before anything decodes it.
-     *
-     * The seed is `asset_id_low64 XOR page_index`, so this catches a well-formed frame of the wrong
-     * page or the wrong asset as well as corruption — which is the case a traversal can actually
-     * produce, by following a child-table entry whose offset is wrong.
-     *
-     * @param {Uint8Array} bytes the fetched frame
-     * @param {number} page_index
-     */
-    #verify_frame(bytes, page_index) {
-        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-
-        const frame = vgeo_read_frame_extent(view, 0, page_index);
-
-        const stored = view.getBigUint64(VGEO_FRAME_OFFSET.CHECKSUM, LE);
-
-        const copy = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
-            ? bytes.buffer
-            : bytes.slice().buffer;
-
-        const computed = vgeo_compute_frame_checksum(
-            BinaryBuffer.fromArrayBuffer(copy), frame, this.header.asset_id_low64
-        );
-
-        if (computed !== stored) {
-            throw new Error(
-                `page ${page_index}: its frame checksums to 0x${computed.toString(16)}`
-                + ` and stores 0x${stored.toString(16)}`
-            );
-        }
-    }
-}
-
-/**
- * Wait, unless the caller stops wanting to.
- *
- * The timer is cleared on abort rather than left to fire, because a backoff between retries of a
- * page nobody wants any more is exactly the wait a cancelled fetch should not sit through.
- *
- * @param {number} ms
- * @param {AbortSignal} signal
- * @returns {Promise<void>}
- */
-function delay(ms, signal) {
-    if (ms <= 0) {
-        return Promise.resolve();
-    }
-
-    // Checked rather than relied on: `addEventListener` on a signal that has already aborted never
-    // fires, so a wait started on one would run to term with nobody left who wanted it.
-    if (signal.aborted) {
-        return Promise.reject(signal.reason ?? new Error('the wait was cancelled'));
-    }
-
-    return new Promise((resolve, reject) => {
-        const on_abort = () => {
-            clearTimeout(timer);
-
-            reject(signal.reason ?? new Error('the wait was cancelled'));
-        };
-
-        const timer = setTimeout(() => {
-            signal.removeEventListener('abort', on_abort);
-
-            resolve();
-        }, ms);
-
-        signal.addEventListener('abort', on_abort, { once: true });
-    });
 }

package/src/shade/renderer/geometry/virtual/format/read/VGeoPage.d.ts

@@ -141,6 +141,46 @@ export class VGeoPage {
      * @type {Uint16Array}
      */
     group_parent_count: Uint16Array;
+    /**
+     * Per group: where its run in {@link parent_ref}/{@link parent_cluster} starts. The run is
+     * {@link group_parent_count} long, and the groups tile the table in order.
+     *
+     * Empty on a container written before `format_version` 4, which carries no upward edge at all.
+     * The absence is the header's `parent_table_offset` reading zero rather than a version test,
+     * so a reader that wants to walk up asks whether these arrays are populated.
+     *
+     * @type {Uint32Array}
+     */
+    group_parent_first: Uint32Array;
+    /**
+     * Index into {@link parent_page_index}, or `VGEO_SAME_PAGE`, for each entry of the
+     * group-parent table.
+     *
+     * The table is the format's only upward edge (§6.3). A cluster names one child group, so every
+     * entry here mirrors exactly one `child_ref`/`child_group` pair somewhere, and format §11.16
+     * holds the two to each other — which is what lets a cut that has descended to a group find the
+     * clusters that would stand in for it if the camera pulled back, without re-descending from the
+     * root to discover them.
+     *
+     * @type {Uint16Array}
+     */
+    parent_ref: Uint16Array;
+    /**
+     * Cluster index within the page {@link parent_ref} names.
+     * @type {Uint16Array}
+     */
+    parent_cluster: Uint16Array;
+    /**
+     * `parent_ref -> page index`, deduplicated and ascending.
+     *
+     * No fetch range, unlike {@link child_page_index}, and the asymmetry is the point: a child may
+     * be absent and the decision to fetch it is made before it arrives, while a parent of a group in
+     * the cut is resident already — `VGEO_GROUP_FLAG_SELECTABLE` is exactly "every parent reference
+     * is live". So a parent reference has nothing to decide and says only where.
+     *
+     * @type {Uint32Array}
+     */
+    parent_page_index: Uint32Array;
     /**
      * @type {number}
      */

package/src/shade/renderer/geometry/virtual/format/read/VGeoPage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoPage.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPage.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,OAFU,UAAU,CAEM;IAE1B;;;;;OAKG;IACH,MAFU,QAAQ,CAEsB;IAExC;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;OAKG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;OAEG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;;;;OAYG;IACH,qBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,6BAFU,YAAY,CAE4B;IAElD;;OAEG;IACH,+BAFU,YAAY,CAE8B;IAEpD;;;OAGG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;OAEG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,oBAFU,WAAW,CAEmB;IAExC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,YAAY,CAEY;IAElC;;OAEG;IACH,YAFU,YAAY,CAEW;IAEjC;;OAEG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;;;;;;OASG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;;;;;;OAQG;IACH,MAFU,YAAY,CAEK;IAE3B;;;OAGG;IACH,WAFU,WAAW,CAEU;IAE/B;;;OAGG;IACH,aAFU,WAAW,CAEY;IAEjC;;OAEG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,wBAFU,WAAW,CAEuB;IAE5C;;;;OAIG;IACH,sBAFU,WAAW,CAEqB;IAE1C;;OAEG;IACH,cAFU,UAAU,CAEa;IAEjC;;OAEG;IACH,gBAFU,UAAU,CAEe;IAEnC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;;;;;;OAUG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,qBAFU,YAAY,CAEoB;IAE1C;;;;;;;;OAQG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,YAFU,WAAW,CAEW;IAEhC;;;;;;;OAOG;IACH,QAFU,YAAY,CAEO;IAE7B;;;;;;;;;;;;OAYG;IACH,iCAFU,MAAM,CAEoB;IAEpC;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"VGeoPage.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPage.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,OAFU,UAAU,CAEM;IAE1B;;;;;OAKG;IACH,MAFU,QAAQ,CAEsB;IAExC;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;OAKG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;OAEG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;;;;OAYG;IACH,qBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,6BAFU,YAAY,CAE4B;IAElD;;OAEG;IACH,+BAFU,YAAY,CAE8B;IAEpD;;;OAGG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;OAEG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;OASG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;;;OAWG;IACH,YAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;;;;;;;OASG;IACH,mBAFU,WAAW,CAEkB;IAEvC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,YAAY,CAEY;IAElC;;OAEG;IACH,YAFU,YAAY,CAEW;IAEjC;;OAEG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;;;;;;OASG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;;;;;;OAQG;IACH,MAFU,YAAY,CAEK;IAE3B;;;OAGG;IACH,WAFU,WAAW,CAEU;IAE/B;;;OAGG;IACH,aAFU,WAAW,CAEY;IAEjC;;OAEG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,wBAFU,WAAW,CAEuB;IAE5C;;;;OAIG;IACH,sBAFU,WAAW,CAEqB;IAE1C;;OAEG;IACH,cAFU,UAAU,CAEa;IAEjC;;OAEG;IACH,gBAFU,UAAU,CAEe;IAEnC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;;;;;;OAUG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,qBAFU,YAAY,CAEoB;IAE1C;;;;;;;;OAQG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,YAFU,WAAW,CAEW;IAEhC;;;;;;;OAOG;IACH,QAFU,YAAY,CAEO;IAE7B;;;;;;;;;;;;OAYG;IACH,iCAFU,MAAM,CAEoB;IAEpC;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

package/src/shade/renderer/geometry/virtual/format/read/VGeoPage.js

@@ -164,6 +164,50 @@ export class VGeoPage {
      */
     group_parent_count = new Uint16Array(0);
 
+    /**
+     * Per group: where its run in {@link parent_ref}/{@link parent_cluster} starts. The run is
+     * {@link group_parent_count} long, and the groups tile the table in order.
+     *
+     * Empty on a container written before `format_version` 4, which carries no upward edge at all.
+     * The absence is the header's `parent_table_offset` reading zero rather than a version test,
+     * so a reader that wants to walk up asks whether these arrays are populated.
+     *
+     * @type {Uint32Array}
+     */
+    group_parent_first = new Uint32Array(0);
+
+    /**
+     * Index into {@link parent_page_index}, or `VGEO_SAME_PAGE`, for each entry of the
+     * group-parent table.
+     *
+     * The table is the format's only upward edge (§6.3). A cluster names one child group, so every
+     * entry here mirrors exactly one `child_ref`/`child_group` pair somewhere, and format §11.16
+     * holds the two to each other — which is what lets a cut that has descended to a group find the
+     * clusters that would stand in for it if the camera pulled back, without re-descending from the
+     * root to discover them.
+     *
+     * @type {Uint16Array}
+     */
+    parent_ref = new Uint16Array(0);
+
+    /**
+     * Cluster index within the page {@link parent_ref} names.
+     * @type {Uint16Array}
+     */
+    parent_cluster = new Uint16Array(0);
+
+    /**
+     * `parent_ref -> page index`, deduplicated and ascending.
+     *
+     * No fetch range, unlike {@link child_page_index}, and the asymmetry is the point: a child may
+     * be absent and the decision to fetch it is made before it arrives, while a parent of a group in
+     * the cut is resident already — `VGEO_GROUP_FLAG_SELECTABLE` is exactly "every parent reference
+     * is live". So a parent reference has nothing to decide and says only where.
+     *
+     * @type {Uint32Array}
+     */
+    parent_page_index = new Uint32Array(0);
+
     /**
      * @type {number}
      */

package/src/shade/renderer/geometry/virtual/format/read/VGeoPageFetcherCore.d.ts

@@ -0,0 +1,69 @@
+/**
+ * How a fetch ends when it does not end in a page.
+ *
+ * `quarantine` is the verdict the reader acts on: `true` means the page will not arrive from this
+ * source — every attempt failed the same way — and asking again is a storm; `false` means the
+ * fetch was cancelled, nothing is wrong with the page, and the next cut may ask again.
+ */
+export class VGeoFetchError extends Error {
+    /**
+     * @param {string} message
+     * @param {boolean} quarantine
+     * @param {string} reason
+     */
+    constructor(message: string, quarantine: boolean, reason: string);
+    /**
+     * @type {boolean}
+     */
+    quarantine: boolean;
+    /**
+     * The last attempt's failure, in the source's own words.
+     * @type {string}
+     */
+    reason: string;
+}
+/**
+ * One page from bytes: read the range, retry with backoff, verify the frame against the asset's
+ * identity, decode.
+ *
+ * Pure logic over a `read` function, so that it runs anywhere — on the main thread inside
+ * `VGeoContainerReader`, whose `install` has always done exactly this, or in a worker, which is
+ * where a runtime wants it. Measured on the Zorah bdf6f961 container, the checksum is 1.0 ms a
+ * page and the decode 0.08 ms; at thirty-two pages a reading that is a frame of main-thread time
+ * for what is, on a worker, the residency cost of thirty-two arrivals
+ * (RUNTIME_PLAN_2026_09_14 §0, §4.6).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPageFetcherCore {
+    /**
+     * @param {Object} options
+     * @param {function(number, number, AbortSignal=): Promise<Uint8Array>} options.read bytes of a
+     *     range of the container
+     * @param {bigint|function(): bigint} options.asset_id_low64 what frames are checksummed against;
+     *     a function when the header is read after construction
+     * @param {boolean} [options.verify_frames]
+     * @param {number} [options.fetch_retries] attempts after the first
+     * @param {number} [options.fetch_retry_backoff_ms] doubled per attempt
+     */
+    constructor({ read, asset_id_low64, verify_frames, fetch_retries, fetch_retry_backoff_ms, }: {
+        read: (arg0: number, arg1: number, arg2: AbortSignal | undefined) => Promise<Uint8Array>;
+        asset_id_low64: bigint | (() => bigint);
+        verify_frames?: boolean;
+        fetch_retries?: number;
+        fetch_retry_backoff_ms?: number;
+    });
+    /**
+     * @param {number} page_index
+     * @param {number} frame_offset absolute, in the container
+     * @param {number} fetch_size
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<VGeoPage>}
+     * @throws {VGeoFetchError}
+     */
+    fetch(page_index: number, frame_offset: number, fetch_size: number, signal?: AbortSignal): Promise<VGeoPage>;
+    #private;
+}
+export type VGeoPage = import("./VGeoPage.js").VGeoPage;
+//# sourceMappingURL=VGeoPageFetcherCore.d.ts.map

package/src/shade/renderer/geometry/virtual/format/read/VGeoPageFetcherCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoPageFetcherCore.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPageFetcherCore.js"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH;IAYI;;;;OAIG;IACH,qBAJW,MAAM,cACN,OAAO,UACP,MAAM,EAQhB;IAtBD;;OAEG;IACH,YAFU,OAAO,CAEN;IAEX;;;OAGG;IACH,QAFU,MAAM,CAET;CAcV;AAED;;;;;;;;;;;;;GAaG;AACH;IA0BI;;;;;;;;;OASG;IACH;QARgF,IAAI,SAAhE,MAAM,QAAE,MAAM,QAAE,WAAW,iBAAI,QAAQ,UAAU,CAAC;QAExB,cAAc,EAAjD,MAAM,UAAa,MAAM,CAAA;QAEP,aAAa,GAA/B,OAAO;QACU,aAAa,GAA9B,MAAM;QACW,sBAAsB,GAAvC,MAAM;OAkBhB;IAED;;;;;;;OAOG;IACH,kBAPW,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CA4B7B;;CAuDJ;uBAlMY,OAAO,eAAe,EAAE,QAAQ"}