@woosh/meep-engine 3.20.0 → 3.22.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"}

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

@@ -0,0 +1,72 @@
+import { VGEO_HEADER_SIZE } from "../header/VGEO_HEADER_SIZE.js";
+
+/**
+ * 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 = 256 * 1024;
+
+    /**
+     * 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 = false;
+
+    /**
+     * 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 = false;
+
+    /**
+     * 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 = 6;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * A {@link VGeoByteSource} over an HTTP URL, served by range requests.
+ *
+ * This is the source the format was designed against: `VGEO_FORMAT.md` §10 asks a reader to fetch
+ * `[0, 256)`, then the always-resident head, then one exact range per page it decides it wants, and
+ * every one of those is a `Range` header away.
+ *
+ * **A `200` is a failure, not a slower success.** A server that ignores `Range` answers with the
+ * whole file under a `200`, and a reader that took the first `length` bytes of it would read the
+ * head of the file where it asked for the middle of a frame — silently, and with entirely plausible
+ * numbers. §10 requires the response be `206` with the range that was asked for, so that is checked
+ * on every read.
+ *
+ * The length comes from a `HEAD`, falling back to a one-byte ranged `GET` when the server declines
+ * one — `Content-Range` names the total either way, and a CDN that refuses `HEAD` is common enough
+ * to be worth the fallback rather than an error.
+ *
+ * @param {string} url
+ * @param {RequestInit} [init] passed to every request — credentials, an abort signal, headers
+ * @returns {Promise<VGeoByteSource>}
+ * @throws {Error} when the resource is missing, or does not serve ranges
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_fetch_byte_source(url: string, init?: RequestInit): Promise<VGeoByteSource>;
+import { VGeoByteSource } from "./VGeoByteSource.js";
+//# sourceMappingURL=vgeo_fetch_byte_source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_fetch_byte_source.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_fetch_byte_source.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,4CARW,MAAM,SACN,WAAW,GACT,QAAQ,cAAc,CAAC,CA6CnC;+BAlE8B,qBAAqB"}

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

@@ -0,0 +1,108 @@
+import { VGeoByteSource } from "./VGeoByteSource.js";
+
+/**
+ * A {@link VGeoByteSource} over an HTTP URL, served by range requests.
+ *
+ * This is the source the format was designed against: `VGEO_FORMAT.md` §10 asks a reader to fetch
+ * `[0, 256)`, then the always-resident head, then one exact range per page it decides it wants, and
+ * every one of those is a `Range` header away.
+ *
+ * **A `200` is a failure, not a slower success.** A server that ignores `Range` answers with the
+ * whole file under a `200`, and a reader that took the first `length` bytes of it would read the
+ * head of the file where it asked for the middle of a frame — silently, and with entirely plausible
+ * numbers. §10 requires the response be `206` with the range that was asked for, so that is checked
+ * on every read.
+ *
+ * The length comes from a `HEAD`, falling back to a one-byte ranged `GET` when the server declines
+ * one — `Content-Range` names the total either way, and a CDN that refuses `HEAD` is common enough
+ * to be worth the fallback rather than an error.
+ *
+ * @param {string} url
+ * @param {RequestInit} [init] passed to every request — credentials, an abort signal, headers
+ * @returns {Promise<VGeoByteSource>}
+ * @throws {Error} when the resource is missing, or does not serve ranges
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function vgeo_fetch_byte_source(url, init = {}) {
+    const byte_length = await probe_length(url, init);
+
+    return new VGeoByteSource(
+        byte_length,
+        async (offset, length) => {
+            if (length === 0) {
+                return new Uint8Array(0);
+            }
+
+            const last = offset + length - 1;
+
+            const response = await fetch(url, {
+                ...init,
+                headers: { ...init.headers, Range: `bytes=${offset}-${last}` },
+            });
+
+            if (response.status !== 206) {
+                throw new Error(
+                    `${url} answered HTTP ${response.status} to a range request for`
+                    + ` bytes ${offset}-${last};`
+                    + ` a reader needs 206, and a 200 means the range was ignored`
+                );
+            }
+
+            const range = response.headers.get('Content-Range');
+
+            // The status alone is not enough: a proxy can answer 206 with a different range than the
+            // one asked for, and every offset below this line is the format's rather than a guess.
+            if (range !== null && !range.startsWith(`bytes ${offset}-${last}/`)) {
+                throw new Error(
+                    `${url} answered "${range}" to a range request for bytes ${offset}-${last}`
+                );
+            }
+
+            return new Uint8Array(await response.arrayBuffer());
+        },
+        url
+    );
+}
+
+/**
+ * How long the resource is.
+ *
+ * @param {string} url
+ * @param {RequestInit} init
+ * @returns {Promise<number>}
+ */
+async function probe_length(url, init) {
+    const head = await fetch(url, { ...init, method: 'HEAD' });
+
+    if (head.ok) {
+        const length = head.headers.get('Content-Length');
+
+        if (length !== null && head.headers.get('Accept-Ranges') !== 'none') {
+            return Number(length);
+        }
+    }
+
+    // Either the server has no HEAD, or it declined to say how long the body is. One byte under a
+    // range request answers both questions at once — the total is the tail of `Content-Range`, and
+    // getting a 206 at all is the range support this source needs.
+    const probe = await fetch(url, { ...init, headers: { ...init.headers, Range: 'bytes=0-0' } });
+
+    if (probe.status !== 206) {
+        throw new Error(
+            `${url} answered HTTP ${probe.status} to a range request;`
+            + ` this reader needs a server that serves ranges`
+        );
+    }
+
+    const range = probe.headers.get('Content-Range');
+
+    const total = range === null ? NaN : Number(range.slice(range.indexOf('/') + 1));
+
+    if (!Number.isFinite(total)) {
+        throw new Error(`${url} served a range without a usable Content-Range ("${range}")`);
+    }
+
+    return total;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Read the page directory out of the bytes at `directory_offset`.
+ *
+ * Record `i` describes page `i` and lives at exactly `32·i`, so a reader that wants one page's row
+ * fetches 32 bytes; this reads a whole slice because the whole directory of even a very large asset
+ * is a few hundred kilobytes, and everything that reads it at all reads most of it.
+ *
+ * The block checksums (§9) are not verified here. They are `asset_id_high64`-seeded, one per 128
+ * records, and verifying them is the same optional audit everything else in this reader treats as
+ * optional — with the same reason: the directory is derived data, and a reader that mistrusts it can
+ * reconstruct every field by scanning frames instead.
+ *
+ * @param {Uint8Array} bytes the directory region, from its first byte
+ * @param {number} page_count `total_pages` from the header
+ * @returns {VGeoDirectory}
+ * @throws {Error} when the bytes are shorter than the records the header says are there
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_read_directory(bytes: Uint8Array, page_count: number): VGeoDirectory;
+import { VGeoDirectory } from "./VGeoDirectory.js";
+//# sourceMappingURL=vgeo_read_directory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_read_directory.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_directory.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2CARW,UAAU,cACV,MAAM,GACJ,aAAa,CA4CzB;8BAjF6B,oBAAoB"}

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

@@ -0,0 +1,83 @@
+import { VGEO_DIRECTORY_RECORD_SIZE } from "../directory/VGEO_DIRECTORY_RECORD_SIZE.js";
+import { VGeoDirectory } from "./VGeoDirectory.js";
+
+/**
+ * Everything in the container is little-endian (`VGEO_FORMAT.md` §2).
+ * @type {boolean}
+ */
+const LE = true;
+
+/**
+ * Byte offsets within one 32-byte directory record (§9).
+ * @enum {number}
+ */
+const RECORD = {
+    FRAME_OFFSET: 0,
+    FETCH_SIZE: 8,
+    DECODED_SIZE: 12,
+    MIN_LEVEL: 16,
+    MAX_LEVEL: 17,
+    FLAGS: 18,
+    GROUP_COUNT: 20,
+    CLUSTER_COUNT: 22,
+};
+
+/**
+ * Read the page directory out of the bytes at `directory_offset`.
+ *
+ * Record `i` describes page `i` and lives at exactly `32·i`, so a reader that wants one page's row
+ * fetches 32 bytes; this reads a whole slice because the whole directory of even a very large asset
+ * is a few hundred kilobytes, and everything that reads it at all reads most of it.
+ *
+ * The block checksums (§9) are not verified here. They are `asset_id_high64`-seeded, one per 128
+ * records, and verifying them is the same optional audit everything else in this reader treats as
+ * optional — with the same reason: the directory is derived data, and a reader that mistrusts it can
+ * reconstruct every field by scanning frames instead.
+ *
+ * @param {Uint8Array} bytes the directory region, from its first byte
+ * @param {number} page_count `total_pages` from the header
+ * @returns {VGeoDirectory}
+ * @throws {Error} when the bytes are shorter than the records the header says are there
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_read_directory(bytes, page_count) {
+    const needed = page_count * VGEO_DIRECTORY_RECORD_SIZE;
+
+    if (bytes.byteLength < needed) {
+        throw new Error(
+            `the directory of ${page_count} pages needs ${needed} bytes and ${bytes.byteLength}`
+            + ` were given`
+        );
+    }
+
+    const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+    const result = new VGeoDirectory();
+
+    result.page_count = page_count;
+    result.frame_offset = new Float64Array(page_count);
+    result.fetch_size = new Uint32Array(page_count);
+    result.decoded_size = new Uint32Array(page_count);
+    result.min_level = new Uint8Array(page_count);
+    result.max_level = new Uint8Array(page_count);
+    result.flags = new Uint16Array(page_count);
+    result.group_count = new Uint16Array(page_count);
+    result.cluster_count = new Uint16Array(page_count);
+
+    for (let i = 0; i < page_count; i++) {
+        const record = i * VGEO_DIRECTORY_RECORD_SIZE;
+
+        result.frame_offset[i] = Number(data.getBigUint64(record + RECORD.FRAME_OFFSET, LE));
+        result.fetch_size[i] = data.getUint32(record + RECORD.FETCH_SIZE, LE);
+        result.decoded_size[i] = data.getUint32(record + RECORD.DECODED_SIZE, LE);
+        result.min_level[i] = data.getUint8(record + RECORD.MIN_LEVEL);
+        result.max_level[i] = data.getUint8(record + RECORD.MAX_LEVEL);
+        result.flags[i] = data.getUint16(record + RECORD.FLAGS, LE);
+        result.group_count[i] = data.getUint16(record + RECORD.GROUP_COUNT, LE);
+        result.cluster_count[i] = data.getUint16(record + RECORD.CLUSTER_COUNT, LE);
+    }
+
+    return result;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Read a file's header and level table.
+ *
+ * The reject rules here are the ones `VGEO_FORMAT.md` §4 and §10 make mandatory for *every* reader,
+ * and they are deliberately not part of the optional whole-file audit: a file whose magic, reader
+ * version, payload encoding or hash algorithm is not one this build understands must be refused
+ * outright, because misreading it produces plausible geometry rather than an error. Everything
+ * softer than that — checksums, cross-table agreement, build invariants — is
+ * {@link vgeo_validate_container}'s, needs the whole file, and is nobody's precondition for reading.
+ *
+ * Note what is *not* checked: `header_checksum`. It covers only bytes 0–255, so it is cheap and
+ * available from a head prefix, but a reader that verifies it and nothing else has bought very
+ * little — the frame checksums are what stand between a traversal and a corrupt page, and those
+ * arrive with their pages. It belongs to validation.
+ *
+ * @param {Uint8Array} bytes a head prefix, at least {@link VGEO_MIN_HEAD_BYTES} long, and at least
+ *     {@link vgeo_head_size} long to carry the whole level table
+ * @returns {VGeoContainerHeader}
+ * @throws {Error} when the bytes are not a `.vgeo` this build can read, or the prefix is too short
+ *     to hold the table the header describes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_read_header(bytes: Uint8Array): VGeoContainerHeader;
+/**
+ * How long a head prefix has to be to carry the whole always-resident set — the header, the level
+ * table, and the root page's frame (§10) — read from the fixed header alone.
+ *
+ * The three are contiguous and in that order, and both numbers that bound them sit in the first 256
+ * bytes, which is what lets a cold start be two requests: read the header, then read the rest of the
+ * set in one range. Nothing here has to guess a prefix, and nothing is fetched twice.
+ *
+ * The magic is checked, because the value this returns is about to size a fetch and reading a u64
+ * out of bytes that are not a `.vgeo` would size it out of noise. The rest of §4's reject rules stay
+ * with {@link vgeo_read_header}, which is what runs once the set is in hand.
+ *
+ * @param {Uint8Array} bytes at least {@link VGEO_MIN_HEAD_BYTES}
+ * @returns {number}
+ * @throws {Error} when the bytes are not a `.vgeo` at all
+ */
+export function vgeo_resident_head_size(bytes: Uint8Array): number;
+/**
+ * How many bytes of head {@link vgeo_read_header} needs before it can be called at all.
+ *
+ * The level table's size is a header field, so a reader that has only this much learns how much more
+ * to ask for; {@link vgeo_head_size} is what turns the one into the other.
+ *
+ * @type {number}
+ */
+export const VGEO_MIN_HEAD_BYTES: number;
+import { VGeoContainerHeader } from "./VGeoContainerHeader.js";
+//# sourceMappingURL=vgeo_read_header.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_read_header.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_header.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCATW,UAAU,GAER,mBAAmB,CA4G/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,UAAU,GACR,MAAM,CA4BlB;AAlLD;;;;;;;GAOG;AACH,kCAFU,MAAM,CAEoC;oCAjBhB,0BAA0B"}

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

@@ -0,0 +1,211 @@
+import { VGEO_HASH_ALGO_XXH3 } from "../header/VGEO_HASH_ALGO_XXH3.js";
+import { VGEO_HEADER_OFFSET } from "../header/VGEO_HEADER_OFFSET.js";
+import { VGEO_HEADER_SIZE } from "../header/VGEO_HEADER_SIZE.js";
+import { VGEO_LEVEL_OFFSET } from "../header/VGEO_LEVEL_OFFSET.js";
+import { VGEO_LEVEL_RECORD_SIZE } from "../header/VGEO_LEVEL_RECORD_SIZE.js";
+import { VGEO_MAGIC } from "../header/VGEO_MAGIC.js";
+import { VGEO_MIN_READER_VERSION } from "../header/VGEO_MIN_READER_VERSION.js";
+import { VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1 } from "../header/VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1.js";
+import { VGeoContainerHeader } from "./VGeoContainerHeader.js";
+import { VGeoLevelRecord } from "../header/VGeoLevelRecord.js";
+
+/**
+ * Everything in the container is little-endian (`VGEO_FORMAT.md` §2).
+ * @type {boolean}
+ */
+const LE = true;
+
+/**
+ * How many bytes of head {@link vgeo_read_header} needs before it can be called at all.
+ *
+ * The level table's size is a header field, so a reader that has only this much learns how much more
+ * to ask for; {@link vgeo_head_size} is what turns the one into the other.
+ *
+ * @type {number}
+ */
+export const VGEO_MIN_HEAD_BYTES = VGEO_HEADER_SIZE;
+
+/**
+ * Read a file's header and level table.
+ *
+ * The reject rules here are the ones `VGEO_FORMAT.md` §4 and §10 make mandatory for *every* reader,
+ * and they are deliberately not part of the optional whole-file audit: a file whose magic, reader
+ * version, payload encoding or hash algorithm is not one this build understands must be refused
+ * outright, because misreading it produces plausible geometry rather than an error. Everything
+ * softer than that — checksums, cross-table agreement, build invariants — is
+ * {@link vgeo_validate_container}'s, needs the whole file, and is nobody's precondition for reading.
+ *
+ * Note what is *not* checked: `header_checksum`. It covers only bytes 0–255, so it is cheap and
+ * available from a head prefix, but a reader that verifies it and nothing else has bought very
+ * little — the frame checksums are what stand between a traversal and a corrupt page, and those
+ * arrive with their pages. It belongs to validation.
+ *
+ * @param {Uint8Array} bytes a head prefix, at least {@link VGEO_MIN_HEAD_BYTES} long, and at least
+ *     {@link vgeo_head_size} long to carry the whole level table
+ * @returns {VGeoContainerHeader}
+ * @throws {Error} when the bytes are not a `.vgeo` this build can read, or the prefix is too short
+ *     to hold the table the header describes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_read_header(bytes) {
+    if (bytes.byteLength < VGEO_HEADER_SIZE) {
+        throw new Error(`the head is ${bytes.byteLength} bytes, shorter than the header`);
+    }
+
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+    const magic = view.getUint32(VGEO_HEADER_OFFSET.MAGIC, LE);
+
+    if (magic !== VGEO_MAGIC) {
+        throw new Error(
+            `not a .vgeo file: magic is 0x${magic.toString(16)}, expected 0x${VGEO_MAGIC.toString(16)}`
+        );
+    }
+
+    const result = new VGeoContainerHeader();
+
+    result.format_version = view.getUint16(VGEO_HEADER_OFFSET.FORMAT_VERSION, LE);
+    result.min_reader_version = view.getUint16(VGEO_HEADER_OFFSET.MIN_READER_VERSION, LE);
+
+    if (result.min_reader_version > VGEO_MIN_READER_VERSION) {
+        throw new Error(
+            `the file wants a reader of version ${result.min_reader_version};`
+            + ` this one is ${VGEO_MIN_READER_VERSION}`
+        );
+    }
+
+    const hash_algo = view.getUint8(VGEO_HEADER_OFFSET.HASH_ALGO);
+
+    if (hash_algo !== VGEO_HASH_ALGO_XXH3) {
+        throw new Error(`hash algorithm ${hash_algo} is not one this reader knows`);
+    }
+
+    const required = view.getUint32(VGEO_HEADER_OFFSET.FEATURE_FLAGS_REQUIRED, LE);
+
+    if (required !== 0) {
+        // Every bit here is unknown by construction — no feature flag is defined yet — and §4 says
+        // a reader must refuse any set bit it does not understand rather than ignore it.
+        throw new Error(`the file requires feature flags 0x${required.toString(16)}`);
+    }
+
+    result.payload_encoding = view.getUint32(VGEO_HEADER_OFFSET.PAYLOAD_ENCODING, LE);
+
+    if (result.payload_encoding !== VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1) {
+        throw new Error(
+            `payload encoding ${result.payload_encoding} is not one this reader decodes`
+            + ` (${VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1} is SHADE_MESHLET_V1)`
+        );
+    }
+
+    result.asset_id = read_asset_id(view, VGEO_HEADER_OFFSET.ASSET_ID);
+    result.asset_id_low64 = view.getBigUint64(VGEO_HEADER_OFFSET.ASSET_ID, LE);
+    result.vertex_attribute_mask = view.getUint32(VGEO_HEADER_OFFSET.VERTEX_ATTRIBUTE_MASK, LE);
+    result.total_pages = view.getUint32(VGEO_HEADER_OFFSET.TOTAL_PAGES, LE);
+    result.total_clusters = Number(view.getBigUint64(VGEO_HEADER_OFFSET.TOTAL_CLUSTERS, LE));
+    result.total_groups = Number(view.getBigUint64(VGEO_HEADER_OFFSET.TOTAL_GROUPS, LE));
+    result.root_page_offset = Number(view.getBigUint64(VGEO_HEADER_OFFSET.ROOT_PAGE_OFFSET, LE));
+    result.root_page_fetch_size = view.getUint32(VGEO_HEADER_OFFSET.ROOT_PAGE_FETCH_SIZE, LE);
+    result.root_page_decoded_size = view.getUint32(VGEO_HEADER_OFFSET.ROOT_PAGE_DECODED_SIZE, LE);
+    result.directory_offset = Number(view.getBigUint64(VGEO_HEADER_OFFSET.DIRECTORY_OFFSET, LE));
+    result.dir_block_checksums_offset =
+        Number(view.getBigUint64(VGEO_HEADER_OFFSET.DIR_BLOCK_CHECKSUMS_OFFSET, LE));
+    result.nominal_page_size = view.getUint32(VGEO_HEADER_OFFSET.NOMINAL_PAGE_SIZE, LE);
+    result.source_vertex_count = Number(view.getBigUint64(VGEO_HEADER_OFFSET.SOURCE_VERTEX_COUNT, LE));
+    result.source_face_count = Number(view.getBigUint64(VGEO_HEADER_OFFSET.SOURCE_FACE_COUNT, LE));
+
+    for (let i = 0; i < 4; i++) {
+        result.object_sphere[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_SPHERE + i * 4, LE);
+    }
+
+    for (let i = 0; i < 6; i++) {
+        result.object_bounds[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_BOUNDS + i * 4, LE);
+    }
+
+    const level_count = view.getUint8(VGEO_HEADER_OFFSET.LEVEL_COUNT);
+
+    const table_end = VGEO_HEADER_SIZE + level_count * VGEO_LEVEL_RECORD_SIZE;
+
+    if (bytes.byteLength < table_end) {
+        throw new Error(
+            `the head is ${bytes.byteLength} bytes and the level table of ${level_count} levels`
+            + ` ends at ${table_end}`
+        );
+    }
+
+    for (let i = 0; i < level_count; i++) {
+        const at = VGEO_HEADER_SIZE + i * VGEO_LEVEL_RECORD_SIZE;
+
+        const level = new VGeoLevelRecord();
+
+        level.min_error = view.getFloat32(at + VGEO_LEVEL_OFFSET.MIN_ERROR, LE);
+        level.max_error = view.getFloat32(at + VGEO_LEVEL_OFFSET.MAX_ERROR, LE);
+        level.max_sphere_radius = view.getFloat32(at + VGEO_LEVEL_OFFSET.MAX_SPHERE_RADIUS, LE);
+        level.cluster_count = view.getUint32(at + VGEO_LEVEL_OFFSET.CLUSTER_COUNT, LE);
+        level.group_count = view.getUint32(at + VGEO_LEVEL_OFFSET.GROUP_COUNT, LE);
+        level.triangle_count = view.getUint32(at + VGEO_LEVEL_OFFSET.TRIANGLE_COUNT, LE);
+
+        result.levels.push(level);
+    }
+
+    return result;
+}
+
+/**
+ * How long a head prefix has to be to carry the whole always-resident set — the header, the level
+ * table, and the root page's frame (§10) — read from the fixed header alone.
+ *
+ * The three are contiguous and in that order, and both numbers that bound them sit in the first 256
+ * bytes, which is what lets a cold start be two requests: read the header, then read the rest of the
+ * set in one range. Nothing here has to guess a prefix, and nothing is fetched twice.
+ *
+ * The magic is checked, because the value this returns is about to size a fetch and reading a u64
+ * out of bytes that are not a `.vgeo` would size it out of noise. The rest of §4's reject rules stay
+ * with {@link vgeo_read_header}, which is what runs once the set is in hand.
+ *
+ * @param {Uint8Array} bytes at least {@link VGEO_MIN_HEAD_BYTES}
+ * @returns {number}
+ * @throws {Error} when the bytes are not a `.vgeo` at all
+ */
+export function vgeo_resident_head_size(bytes) {
+    if (bytes.byteLength < VGEO_HEADER_SIZE) {
+        throw new Error(`the head is ${bytes.byteLength} bytes, shorter than the header`);
+    }
+
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+    const magic = view.getUint32(VGEO_HEADER_OFFSET.MAGIC, LE);
+
+    if (magic !== VGEO_MAGIC) {
+        throw new Error(
+            `not a .vgeo file: magic is 0x${magic.toString(16)}, expected 0x${VGEO_MAGIC.toString(16)}`
+        );
+    }
+
+    const table_end =
+        VGEO_HEADER_SIZE + view.getUint8(VGEO_HEADER_OFFSET.LEVEL_COUNT) * VGEO_LEVEL_RECORD_SIZE;
+
+    const root_end = Number(view.getBigUint64(VGEO_HEADER_OFFSET.ROOT_PAGE_OFFSET, LE))
+        + view.getUint32(VGEO_HEADER_OFFSET.ROOT_PAGE_FETCH_SIZE, LE);
+
+    // The root frame begins where the level table ends, so `root_end` covers both — unless the
+    // header is lying about one of them, in which case the table is still what has to be read for
+    // the reject rules to run at all.
+    return Math.max(table_end, root_end);
+}
+
+/**
+ * @param {DataView} view
+ * @param {number} offset
+ * @returns {string} 16 bytes as hex
+ */
+function read_asset_id(view, offset) {
+    let out = '';
+
+    for (let i = 0; i < 16; i++) {
+        out += view.getUint8(offset + i).toString(16).padStart(2, '0');
+    }
+
+    return out;
+}