@woosh/meep-engine 3.19.0 → 3.21.0

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

@@ -0,0 +1,80 @@
+/**
+ * The page directory, decoded — one row per page, in page-index order.
+ *
+ * Auxiliary and fully derivable from the frames (`VGEO_FORMAT.md` §3, §9): a traversal never touches
+ * it, because every range it needs is already in the child table of a page it holds. What it is for
+ * is the tasks that are not a traversal — RAM budgeting before a fetch, resuming from a disk cache,
+ * and reaching a page the DAG does not lead to, which is exactly what a tool looking at a file wants
+ * and a runtime never does.
+ *
+ * A structure of arrays because a large asset has tens of thousands of pages and every use of this
+ * is a scan or a single indexed lookup.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoDirectory {
+    /**
+     * @type {number}
+     */
+    page_count = 0;
+
+    /**
+     * Absolute frame offsets. A double rather than a BigInt: every offset past 2^53 names a file
+     * nothing here could hold, and the ones below it are exact.
+     * @type {Float64Array}
+     */
+    frame_offset = new Float64Array(0);
+
+    /**
+     * The exact byte range to fetch each page: `[frame_offset, frame_offset + fetch_size)`.
+     * @type {Uint32Array}
+     */
+    fetch_size = new Uint32Array(0);
+
+    /**
+     * @type {Uint32Array}
+     */
+    decoded_size = new Uint32Array(0);
+
+    /**
+     * @type {Uint8Array}
+     */
+    min_level = new Uint8Array(0);
+
+    /**
+     * @type {Uint8Array}
+     */
+    max_level = new Uint8Array(0);
+
+    /**
+     * Bit 0 is `VGEO_DIRECTORY_FLAG_ROOT_PAGE`.
+     * @type {Uint16Array}
+     */
+    flags = new Uint16Array(0);
+
+    /**
+     * @type {Uint16Array}
+     */
+    group_count = new Uint16Array(0);
+
+    /**
+     * @type {Uint16Array}
+     */
+    cluster_count = new Uint16Array(0);
+
+    /**
+     * What every page of this asset costs decoded, summed — the whole resident footprint, known
+     * without decoding one.
+     * @returns {number}
+     */
+    get total_decoded_bytes() {
+        let total = 0;
+
+        for (let i = 0; i < this.page_count; i++) {
+            total += this.decoded_size[i];
+        }
+
+        return total;
+    }
+}

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

@@ -0,0 +1,198 @@
+/**
+ * One page, fetched, decoded, and parsed far enough to traverse.
+ *
+ * **A page owns its own bytes and its own tables.** That is the difference between a reader that can
+ * stream and one that cannot: nothing here is an index into a whole-file image, nothing is numbered
+ * against a total the reader would have to know up front, and dropping a page is dropping this
+ * object. The format is built for it — a group never spans pages, a cluster's `payload_offset` is
+ * into its own page's payload section, and `child_group` names a group inside the page the child
+ * table points at — so page-local storage is not a compromise, it is the shape the file already has.
+ *
+ * A cluster is therefore identified by a page and an index within it, and there is no global cluster
+ * id anywhere in this reader. The format has none either.
+ *
+ * Clusters are a structure of arrays rather than objects: an asset of any size has hundreds of
+ * thousands of them, a traversal reads a handful of fields from the ones it visits and nothing at
+ * all from the ones it skips, and an object per cluster would cost more than the page does.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPage {
+    /**
+     * Page index, which is also the frame ordinal.
+     * @type {number}
+     */
+    index: number;
+    /**
+     * Absolute byte offset of this page's frame in the file, and the range it was fetched from.
+     * @type {number}
+     */
+    frame_offset: number;
+    /**
+     * @type {number}
+     */
+    fetch_size: number;
+    /**
+     * The codec its frame stored it under. Informational once the page is here — it is decoded
+     * before anything reads it — and worth keeping, because it is per page and a file can carry
+     * both.
+     * @type {number}
+     */
+    codec: number;
+    /**
+     * Bytes the frame stores, before decoding. What the fetch actually cost.
+     * @type {number}
+     */
+    stored_size: number;
+    /**
+     * Bytes the page occupies decoded — `bytes.length`, and what it costs resident.
+     * @type {number}
+     */
+    decoded_size: number;
+    /**
+     * The decoded page image: page header, group table, node table, cluster records, payload.
+     * @type {Uint8Array}
+     */
+    bytes: Uint8Array;
+    /**
+     * The same bytes, addressed a word at a time. A `DataView` has no alignment requirement, which
+     * is what a payload's encoded attribute words need: their offsets are the format's, not the
+     * browser's.
+     * @type {DataView}
+     */
+    data: DataView;
+    /**
+     * @type {number}
+     */
+    min_level: number;
+    /**
+     * @type {number}
+     */
+    max_level: number;
+    /**
+     * Byte offset of this page's payload section within {@link bytes}.
+     * @type {number}
+     */
+    payload_offset: number;
+    /**
+     * @type {number}
+     */
+    payload_size: number;
+    /**
+     * @type {number}
+     */
+    node_count: number;
+    /**
+     * `child_ref -> page index`, out of the frame's plaintext child table.
+     * @type {Uint32Array}
+     */
+    child_page_index: Uint32Array;
+    /**
+     * `child_ref -> absolute frame offset`. With {@link child_fetch_size} this is the exact range to
+     * fetch a child page, which is what makes traversal self-sufficient: an installed page needs
+     * nothing but itself to reach every page one level down.
+     * @type {Float64Array}
+     */
+    child_frame_offset: Float64Array;
+    /**
+     * @type {Uint32Array}
+     */
+    child_fetch_size: Uint32Array;
+    /**
+     * What each child page costs decoded — RAM admission before the fetch is issued.
+     * @type {Uint32Array}
+     */
+    child_decoded_size: Uint32Array;
+    /**
+     * Per group: index of its first cluster within this page.
+     * @type {Uint16Array}
+     */
+    group_cluster_first: Uint16Array;
+    /**
+     * @type {Uint16Array}
+     */
+    group_cluster_count: Uint16Array;
+    /**
+     * How many clusters name this group as their child. Zero is what makes a group selectable with
+     * nothing above it — the root page's topmost groups, and only those.
+     * @type {Uint16Array}
+     */
+    group_parent_count: Uint16Array;
+    /**
+     * @type {number}
+     */
+    cluster_count: number;
+    /**
+     * `4 · cluster_count` — the LOD-metric sphere of the step that created each cluster.
+     * @type {Float32Array}
+     */
+    self_sphere: Float32Array;
+    /**
+     * @type {Float32Array}
+     */
+    self_error: Float32Array;
+    /**
+     * @type {Float32Array}
+     */
+    parent_error: Float32Array;
+    /**
+     * `4 · cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
+     * @type {Float32Array}
+     */
+    bounds_sphere: Float32Array;
+    /**
+     * Index into {@link child_page_index}, or `VGEO_SAME_PAGE`, or `VGEO_NO_CHILD` for a leaf.
+     * @type {Uint16Array}
+     */
+    child_ref: Uint16Array;
+    /**
+     * Group index within the child page — or within this one, under `VGEO_SAME_PAGE`.
+     * @type {Uint16Array}
+     */
+    child_group: Uint16Array;
+    /**
+     * @type {Uint32Array}
+     */
+    encoding_flags: Uint32Array;
+    /**
+     * Offset into this page's payload section.
+     * @type {Uint32Array}
+     */
+    cluster_payload_offset: Uint32Array;
+    /**
+     * @type {Uint8Array}
+     */
+    vertex_count: Uint8Array;
+    /**
+     * @type {Uint8Array}
+     */
+    triangle_count: Uint8Array;
+    /**
+     * Group index of each cluster, so a colour can be keyed on the residency unit.
+     * @type {Uint16Array}
+     */
+    group_of_cluster: Uint16Array;
+    /**
+     * How many of this page's clusters store a normal per vertex rather than one constant-compressed
+     * word for the whole cluster.
+     *
+     * A source carrying no normals encodes the engine default everywhere, and then a display keyed
+     * on the stored normal comes out one flat colour across the whole model. That is the file's truth
+     * and it reads exactly like a broken viewer, so it is worth counting outright.
+     *
+     * It is not a count of clusters that *have* normals: a cluster whose vertices genuinely all face
+     * the same way compresses to one word as well, and a flat surface is not a missing one.
+     *
+     * @type {number}
+     */
+    per_vertex_normal_cluster_count: number;
+    /**
+     * Absolute byte offset of a cluster's payload within {@link bytes}.
+     *
+     * @param {number} cluster index within this page
+     * @returns {number}
+     */
+    payload_at(cluster: number): number;
+}
+//# sourceMappingURL=VGeoPage.d.ts.map

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

@@ -0,0 +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;;;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;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;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;;OAEG;IACH,cAFU,UAAU,CAEa;IAEjC;;OAEG;IACH,gBAFU,UAAU,CAEe;IAEnC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;;;;;;;;OAYG;IACH,iCAFU,MAAM,CAEoB;IAEpC;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

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

@@ -0,0 +1,232 @@
+/**
+ * One page, fetched, decoded, and parsed far enough to traverse.
+ *
+ * **A page owns its own bytes and its own tables.** That is the difference between a reader that can
+ * stream and one that cannot: nothing here is an index into a whole-file image, nothing is numbered
+ * against a total the reader would have to know up front, and dropping a page is dropping this
+ * object. The format is built for it — a group never spans pages, a cluster's `payload_offset` is
+ * into its own page's payload section, and `child_group` names a group inside the page the child
+ * table points at — so page-local storage is not a compromise, it is the shape the file already has.
+ *
+ * A cluster is therefore identified by a page and an index within it, and there is no global cluster
+ * id anywhere in this reader. The format has none either.
+ *
+ * Clusters are a structure of arrays rather than objects: an asset of any size has hundreds of
+ * thousands of them, a traversal reads a handful of fields from the ones it visits and nothing at
+ * all from the ones it skips, and an object per cluster would cost more than the page does.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPage {
+    /**
+     * Page index, which is also the frame ordinal.
+     * @type {number}
+     */
+    index = 0;
+
+    /**
+     * Absolute byte offset of this page's frame in the file, and the range it was fetched from.
+     * @type {number}
+     */
+    frame_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    fetch_size = 0;
+
+    /**
+     * The codec its frame stored it under. Informational once the page is here — it is decoded
+     * before anything reads it — and worth keeping, because it is per page and a file can carry
+     * both.
+     * @type {number}
+     */
+    codec = 0;
+
+    /**
+     * Bytes the frame stores, before decoding. What the fetch actually cost.
+     * @type {number}
+     */
+    stored_size = 0;
+
+    /**
+     * Bytes the page occupies decoded — `bytes.length`, and what it costs resident.
+     * @type {number}
+     */
+    decoded_size = 0;
+
+    /**
+     * The decoded page image: page header, group table, node table, cluster records, payload.
+     * @type {Uint8Array}
+     */
+    bytes = new Uint8Array(0);
+
+    /**
+     * The same bytes, addressed a word at a time. A `DataView` has no alignment requirement, which
+     * is what a payload's encoded attribute words need: their offsets are the format's, not the
+     * browser's.
+     * @type {DataView}
+     */
+    data = new DataView(new ArrayBuffer(0));
+
+    /**
+     * @type {number}
+     */
+    min_level = 0;
+
+    /**
+     * @type {number}
+     */
+    max_level = 0;
+
+    /**
+     * Byte offset of this page's payload section within {@link bytes}.
+     * @type {number}
+     */
+    payload_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    payload_size = 0;
+
+    /**
+     * @type {number}
+     */
+    node_count = 0;
+
+    /**
+     * `child_ref -> page index`, out of the frame's plaintext child table.
+     * @type {Uint32Array}
+     */
+    child_page_index = new Uint32Array(0);
+
+    /**
+     * `child_ref -> absolute frame offset`. With {@link child_fetch_size} this is the exact range to
+     * fetch a child page, which is what makes traversal self-sufficient: an installed page needs
+     * nothing but itself to reach every page one level down.
+     * @type {Float64Array}
+     */
+    child_frame_offset = new Float64Array(0);
+
+    /**
+     * @type {Uint32Array}
+     */
+    child_fetch_size = new Uint32Array(0);
+
+    /**
+     * What each child page costs decoded — RAM admission before the fetch is issued.
+     * @type {Uint32Array}
+     */
+    child_decoded_size = new Uint32Array(0);
+
+    /**
+     * Per group: index of its first cluster within this page.
+     * @type {Uint16Array}
+     */
+    group_cluster_first = new Uint16Array(0);
+
+    /**
+     * @type {Uint16Array}
+     */
+    group_cluster_count = new Uint16Array(0);
+
+    /**
+     * How many clusters name this group as their child. Zero is what makes a group selectable with
+     * nothing above it — the root page's topmost groups, and only those.
+     * @type {Uint16Array}
+     */
+    group_parent_count = new Uint16Array(0);
+
+    /**
+     * @type {number}
+     */
+    cluster_count = 0;
+
+    /**
+     * `4 · cluster_count` — the LOD-metric sphere of the step that created each cluster.
+     * @type {Float32Array}
+     */
+    self_sphere = new Float32Array(0);
+
+    /**
+     * @type {Float32Array}
+     */
+    self_error = new Float32Array(0);
+
+    /**
+     * @type {Float32Array}
+     */
+    parent_error = new Float32Array(0);
+
+    /**
+     * `4 · cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
+     * @type {Float32Array}
+     */
+    bounds_sphere = new Float32Array(0);
+
+    /**
+     * Index into {@link child_page_index}, or `VGEO_SAME_PAGE`, or `VGEO_NO_CHILD` for a leaf.
+     * @type {Uint16Array}
+     */
+    child_ref = new Uint16Array(0);
+
+    /**
+     * Group index within the child page — or within this one, under `VGEO_SAME_PAGE`.
+     * @type {Uint16Array}
+     */
+    child_group = new Uint16Array(0);
+
+    /**
+     * @type {Uint32Array}
+     */
+    encoding_flags = new Uint32Array(0);
+
+    /**
+     * Offset into this page's payload section.
+     * @type {Uint32Array}
+     */
+    cluster_payload_offset = new Uint32Array(0);
+
+    /**
+     * @type {Uint8Array}
+     */
+    vertex_count = new Uint8Array(0);
+
+    /**
+     * @type {Uint8Array}
+     */
+    triangle_count = new Uint8Array(0);
+
+    /**
+     * Group index of each cluster, so a colour can be keyed on the residency unit.
+     * @type {Uint16Array}
+     */
+    group_of_cluster = new Uint16Array(0);
+
+    /**
+     * How many of this page's clusters store a normal per vertex rather than one constant-compressed
+     * word for the whole cluster.
+     *
+     * A source carrying no normals encodes the engine default everywhere, and then a display keyed
+     * on the stored normal comes out one flat colour across the whole model. That is the file's truth
+     * and it reads exactly like a broken viewer, so it is worth counting outright.
+     *
+     * It is not a count of clusters that *have* normals: a cluster whose vertices genuinely all face
+     * the same way compresses to one word as well, and a flat surface is not a missing one.
+     *
+     * @type {number}
+     */
+    per_vertex_normal_cluster_count = 0;
+
+    /**
+     * Absolute byte offset of a cluster's payload within {@link bytes}.
+     *
+     * @param {number} cluster index within this page
+     * @returns {number}
+     */
+    payload_at(cluster) {
+        return this.payload_offset + this.cluster_payload_offset[cluster];
+    }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * A page a traversal wanted and did not have.
+ *
+ * Everything needed to fetch it is here, because everything needed to fetch it was in the child
+ * table of a page that *is* resident (`VGEO_FORMAT.md` §5): the exact byte range, and what it will
+ * cost decoded. No metadata request, no directory lookup, no second round trip — one range, and the
+ * page installs.
+ *
+ * A want is not an error and not a stall. The cut that produced it is a correct, watertight,
+ * coarser surface — the clamp §10 describes — so a reader is free to fetch wants in whatever order
+ * and at whatever rate it likes, or to ignore them entirely and keep drawing what it has.
+ * {@link priority} is what makes the order worth choosing: it is how far past the pixel threshold
+ * the clamped cluster projected, so the page that would fix the most visible coarseness sorts first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPageWant {
+    /**
+     * @type {number}
+     */
+    page_index: number;
+    /**
+     * Absolute offset of the page's frame.
+     * @type {number}
+     */
+    frame_offset: number;
+    /**
+     * Bytes to fetch from {@link frame_offset} — the whole frame, aligned.
+     * @type {number}
+     */
+    fetch_size: number;
+    /**
+     * What the page will cost resident, known before it is asked for.
+     * @type {number}
+     */
+    decoded_size: number;
+    /**
+     * Pixels of error the clamped cluster projected. The threshold it failed is τ, so anything here
+     * is above it, and the excess is how much refining this page would buy.
+     * @type {number}
+     */
+    priority: number;
+    /**
+     * How many clusters of the current cut are waiting on this page. A page wanted by many clamped
+     * clusters is one whose absence is spread over more of the surface.
+     * @type {number}
+     */
+    reference_count: number;
+}
+//# sourceMappingURL=VGeoPageWant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoPageWant.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPageWant.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH;IACI;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,UAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,iBAFU,MAAM,CAEI;CACvB"}

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

@@ -0,0 +1,55 @@
+/**
+ * A page a traversal wanted and did not have.
+ *
+ * Everything needed to fetch it is here, because everything needed to fetch it was in the child
+ * table of a page that *is* resident (`VGEO_FORMAT.md` §5): the exact byte range, and what it will
+ * cost decoded. No metadata request, no directory lookup, no second round trip — one range, and the
+ * page installs.
+ *
+ * A want is not an error and not a stall. The cut that produced it is a correct, watertight,
+ * coarser surface — the clamp §10 describes — so a reader is free to fetch wants in whatever order
+ * and at whatever rate it likes, or to ignore them entirely and keep drawing what it has.
+ * {@link priority} is what makes the order worth choosing: it is how far past the pixel threshold
+ * the clamped cluster projected, so the page that would fix the most visible coarseness sorts first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPageWant {
+    /**
+     * @type {number}
+     */
+    page_index = 0;
+
+    /**
+     * Absolute offset of the page's frame.
+     * @type {number}
+     */
+    frame_offset = 0;
+
+    /**
+     * Bytes to fetch from {@link frame_offset} — the whole frame, aligned.
+     * @type {number}
+     */
+    fetch_size = 0;
+
+    /**
+     * What the page will cost resident, known before it is asked for.
+     * @type {number}
+     */
+    decoded_size = 0;
+
+    /**
+     * Pixels of error the clamped cluster projected. The threshold it failed is τ, so anything here
+     * is above it, and the excess is how much refining this page would buy.
+     * @type {number}
+     */
+    priority = 0;
+
+    /**
+     * How many clusters of the current cut are waiting on this page. A page wanted by many clamped
+     * clusters is one whose absence is spread over more of the surface.
+     * @type {number}
+     */
+    reference_count = 0;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * How a {@link VGeoContainerReader} opens and grows.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoReadOptions {
+    /**
+     * How many bytes to ask for on the first read.
+     *
+     * `VGEO_FORMAT.md` §10 offers two cold starts: fetch the 256-byte header, then the level table
+     * and root frame the header located — two round trips, exactly the bytes needed — or fetch one
+     * speculative head prefix and get all three at once. The second is the default here because the
+     * layout is coarse-first: every byte of a prefix belongs to something the reader is about to
+     * want anyway, so a prefix that overshoots the root frame has bought the next pages rather than
+     * wasted a fetch.
+     *
+     * 256 KB is one nominal page plus the head, so it covers the root frame of a default build
+     * whole. Set it to {@link VGEO_HEADER_SIZE} for the strict two-round-trip start, which is what a
+     * reader measuring cold-start bytes wants.
+     *
+     * @type {number}
+     */
+    head_prefix_bytes: number;
+    /**
+     * Whether to run the whole-file audit when the container is opened.
+     *
+     * **Off, and it is the right default.** {@link vgeo_validate_container} reads every byte of the
+     * file — every frame, every checksum, the directory against a full frame scan — which is the
+     * one thing an incremental reader exists to avoid, and it answers a question about the *writer*
+     * rather than about the view being put on screen. Turning it on costs the whole file and the
+     * whole audit, on a file that may be gigabytes.
+     *
+     * What is *not* optional, and does not live here: the reject rules of §4 and §10 that
+     * {@link vgeo_read_header} and {@link vgeo_read_page} apply unconditionally — magic, reader
+     * version, payload encoding, hash algorithm, unknown required feature bits, unknown codecs, and
+     * a `decoded_size` outside what the stored bytes could produce. Those are not validation; they
+     * are the difference between refusing a file and misreading it.
+     *
+     * @type {boolean}
+     */
+    validate: boolean;
+    /**
+     * Whether each frame's identity-seeded checksum is verified before its page is decoded.
+     *
+     * Separate from {@link validate} because it is affordable where the audit is not: a frame's
+     * checksum covers only that frame, so it is verified from bytes the reader has just fetched
+     * anyway, with no extra request and no whole-file pass. §10 requires it of a *runtime* reader,
+     * where corruption at a content-addressed URL is deterministic and a quarantined page is the
+     * difference between a coarse stand-in and a wrong surface.
+     *
+     * Off by default here for the same reason {@link validate} is: hashing every installed byte is a
+     * real cost, and a tool looking at a file it just built is not defending against the network.
+     *
+     * @type {boolean}
+     */
+    verify_frames: boolean;
+    /**
+     * How many page fetches may be in flight at once.
+     *
+     * Enough to keep a connection busy, few enough that a traversal's whole want list does not
+     * become one burst — the wants are ranked, and issuing them all at once discards the ranking.
+     *
+     * @type {number}
+     */
+    max_concurrent_fetches: number;
+}
+//# sourceMappingURL=VGeoReadOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoReadOptions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoReadOptions.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;OAeG;IACH,mBAFU,MAAM,CAEe;IAE/B;;;;;;;;;;;;;;;;OAgBG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;;;;;;;OAaG;IACH,eAFU,OAAO,CAEK;IAEtB;;;;;;;OAOG;IACH,wBAFU,MAAM,CAEW;CAC9B"}