@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -15,9 +15,23 @@ export class VGeoReadOptions {
      * 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.
+     * **How much overshoot is worth paying for is a measured number, and it is small.** The
+     * always-resident set of a real build is the header, the level table and a root page holding the
+     * complete topmost level — which build invariant §11.7 makes exactly one cluster. Measured on
+     * two torus builds (7.7K and 42K source triangles, 8 and 12 levels): the root page decoded to
+     * 1,732 B and 1,472 B, and the whole set came to about 2.4 KB. So a prefix is speculation about
+     * the *next* band, and at the hundreds-of-KB pages design §5 targets it buys one page. 64 KiB
+     * covers the always-resident set of any plausible asset in one request with room for that page;
+     * the 256 KiB this used to default to bought the same page and cost four times the transfer,
+     * which across a thousand open assets is 256 MB of it.
+     *
+     * Set it to {@link VGEO_HEADER_SIZE} for the strict two-round-trip start, which is what a reader
+     * measuring cold-start bytes wants — and what a runtime holding many assets at once should
+     * prefer, because the speculative page it gives up is one it can fetch when a cut asks for it.
+     *
+     * Whatever the prefix, the reader does not keep it for life: it is released the first time a
+     * read falls outside it, and {@link VGeoContainerReader.release_head} drops it on demand. See
+     * that method for why.
      *
      * @type {number}
      */
@@ -28,15 +42,13 @@ export class VGeoReadOptions {
      * **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.
+     * rather than about the view being put on screen. Measured on a 514 MiB container: one 514 MiB
+     * range and 19.4 seconds, and it is a single `ArrayBuffer`, so a multi-GB asset does not run
+     * slowly — it fails.
      *
+     * @deprecated a runtime reader must not carry a switch that reads the whole file. Call
+     *     {@link vgeo_audit_container} instead, which is a tool talking to a tool and says so, and
+     *     which refuses a file too large to audit this way rather than trying.
      * @type {boolean}
      */
     validate: boolean;
@@ -50,19 +62,43 @@ export class VGeoReadOptions {
      * 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.
+     * real cost, and a tool looking at a file it just built is not defending against the network. A
+     * reader fetching over HTTP should turn it on — it is what makes {@link fetch_retries} and the
+     * quarantine that follows them able to see corruption at all.
      *
      * @type {boolean}
      */
     verify_frames: boolean;
     /**
-     * How many page fetches may be in flight at once.
+     * How many page fetches may be in flight at once, **per reader**.
      *
      * 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.
      *
+     * This bounds one reader and nothing more: eight readers installing wants at this default were
+     * measured issuing 48 concurrent range requests, because nothing here knows about the other
+     * seven. A total across readers is a policy, and it lives in the `ConcurrencyGate` that
+     * `VGeoResidencyManager` puts in front of every reader registered with it.
+     *
      * @type {number}
      */
     max_concurrent_fetches: number;
+    /**
+     * How many times a failed page fetch is retried before the page is quarantined.
+     *
+     * §10: bounded retries with backoff, then quarantine — never a retry loop, because corruption at
+     * a content-addressed URL is deterministic. Two is the bound because the failures worth retrying
+     * are transient by definition: a dropped connection, a 503 from one edge node. A third attempt
+     * is answering the same question again.
+     *
+     * @type {number}
+     */
+    fetch_retries: number;
+    /**
+     * Milliseconds before the first retry; each further attempt doubles it.
+     *
+     * @type {number}
+     */
+    fetch_retry_backoff_ms: number;
 }
 //# sourceMappingURL=VGeoReadOptions.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"VGeoReadOptions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoReadOptions.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,mBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;OAcG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,eAFU,OAAO,CAEK;IAEtB;;;;;;;;;;;;OAYG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;;;;;;OASG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,wBAFU,MAAM,CAEY;CAC/B"}

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

@@ -17,13 +17,27 @@ export class VGeoReadOptions {
      * 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.
+     * **How much overshoot is worth paying for is a measured number, and it is small.** The
+     * always-resident set of a real build is the header, the level table and a root page holding the
+     * complete topmost level — which build invariant §11.7 makes exactly one cluster. Measured on
+     * two torus builds (7.7K and 42K source triangles, 8 and 12 levels): the root page decoded to
+     * 1,732 B and 1,472 B, and the whole set came to about 2.4 KB. So a prefix is speculation about
+     * the *next* band, and at the hundreds-of-KB pages design §5 targets it buys one page. 64 KiB
+     * covers the always-resident set of any plausible asset in one request with room for that page;
+     * the 256 KiB this used to default to bought the same page and cost four times the transfer,
+     * which across a thousand open assets is 256 MB of it.
+     *
+     * Set it to {@link VGEO_HEADER_SIZE} for the strict two-round-trip start, which is what a reader
+     * measuring cold-start bytes wants — and what a runtime holding many assets at once should
+     * prefer, because the speculative page it gives up is one it can fetch when a cut asks for it.
+     *
+     * Whatever the prefix, the reader does not keep it for life: it is released the first time a
+     * read falls outside it, and {@link VGeoContainerReader.release_head} drops it on demand. See
+     * that method for why.
      *
      * @type {number}
      */
-    head_prefix_bytes = 256 * 1024;
+    head_prefix_bytes = 64 * 1024;
 
     /**
      * Whether to run the whole-file audit when the container is opened.
@@ -31,15 +45,13 @@ export class VGeoReadOptions {
      * **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.
+     * rather than about the view being put on screen. Measured on a 514 MiB container: one 514 MiB
+     * range and 19.4 seconds, and it is a single `ArrayBuffer`, so a multi-GB asset does not run
+     * slowly — it fails.
      *
+     * @deprecated a runtime reader must not carry a switch that reads the whole file. Call
+     *     {@link vgeo_audit_container} instead, which is a tool talking to a tool and says so, and
+     *     which refuses a file too large to audit this way rather than trying.
      * @type {boolean}
      */
     validate = false;
@@ -54,19 +66,45 @@ export class VGeoReadOptions {
      * 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.
+     * real cost, and a tool looking at a file it just built is not defending against the network. A
+     * reader fetching over HTTP should turn it on — it is what makes {@link fetch_retries} and the
+     * quarantine that follows them able to see corruption at all.
      *
      * @type {boolean}
      */
     verify_frames = false;
 
     /**
-     * How many page fetches may be in flight at once.
+     * How many page fetches may be in flight at once, **per reader**.
      *
      * 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.
      *
+     * This bounds one reader and nothing more: eight readers installing wants at this default were
+     * measured issuing 48 concurrent range requests, because nothing here knows about the other
+     * seven. A total across readers is a policy, and it lives in the `ConcurrencyGate` that
+     * `VGeoResidencyManager` puts in front of every reader registered with it.
+     *
      * @type {number}
      */
     max_concurrent_fetches = 6;
+
+    /**
+     * How many times a failed page fetch is retried before the page is quarantined.
+     *
+     * §10: bounded retries with backoff, then quarantine — never a retry loop, because corruption at
+     * a content-addressed URL is deterministic. Two is the bound because the failures worth retrying
+     * are transient by definition: a dropped connection, a 503 from one edge node. A third attempt
+     * is answering the same question again.
+     *
+     * @type {number}
+     */
+    fetch_retries = 2;
+
+    /**
+     * Milliseconds before the first retry; each further attempt doubles it.
+     *
+     * @type {number}
+     */
+    fetch_retry_backoff_ms = 50;
 }

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

@@ -0,0 +1,20 @@
+/**
+ * The largest file {@link vgeo_audit_container} will read in one piece, in bytes.
+ *
+ * The audit takes the whole container as a single `ArrayBuffer`, because every invariant of
+ * `VGEO_FORMAT.md` §11 is a cross-check between two places in the file and a streaming audit would
+ * be a different program. That makes the size a hard question rather than a slow one: measured on a
+ * synthetic 514 MiB container the audit read 514 MiB in one range and took 19.4 seconds, and the
+ * next power of two up is where a browser tab stops being able to hold it at all.
+ *
+ * 1 GiB is therefore the line, and it is drawn here rather than left to the allocator so that the
+ * failure is a sentence naming the file's size instead of an out-of-memory several frames later. A
+ * caller with a reason — a build machine, a file it just wrote — passes its own limit.
+ *
+ * @type {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_MAX_AUDIT_BYTES: number;
+//# sourceMappingURL=VGEO_MAX_AUDIT_BYTES.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_MAX_AUDIT_BYTES.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/geometry/virtual/format/read/tool/VGEO_MAX_AUDIT_BYTES.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,mCALU,MAAM,CAKuC"}

package/src/shade/renderer/geometry/virtual/format/read/tool/VGEO_MAX_AUDIT_BYTES.js

@@ -0,0 +1,19 @@
+/**
+ * The largest file {@link vgeo_audit_container} will read in one piece, in bytes.
+ *
+ * The audit takes the whole container as a single `ArrayBuffer`, because every invariant of
+ * `VGEO_FORMAT.md` §11 is a cross-check between two places in the file and a streaming audit would
+ * be a different program. That makes the size a hard question rather than a slow one: measured on a
+ * synthetic 514 MiB container the audit read 514 MiB in one range and took 19.4 seconds, and the
+ * next power of two up is where a browser tab stops being able to hold it at all.
+ *
+ * 1 GiB is therefore the line, and it is drawn here rather than left to the allocator so that the
+ * failure is a sentence naming the file's size instead of an out-of-memory several frames later. A
+ * caller with a reason — a build machine, a file it just wrote — passes its own limit.
+ *
+ * @type {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_MAX_AUDIT_BYTES = 1024 * 1024 * 1024;

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

@@ -0,0 +1,27 @@
+/**
+ * The whole-file audit: every build invariant of `VGEO_FORMAT.md` §11, every checksum, and the
+ * directory against what a frame scan reconstructs.
+ *
+ * **This reads the entire file**, which is the one thing `VGeoContainerReader` exists to avoid, and
+ * that is why it lives here instead of on it. It answers a question about whoever *produced* the
+ * file; nothing about reading one depends on it having been asked, and a renderer holding a thousand
+ * open containers must not have a method within reach that turns one of them into a multi-gigabyte
+ * allocation.
+ *
+ * The size check is the point of the wrapper as much as the location is. {@link vgeo_validate_container}
+ * takes one `ArrayBuffer` because every §11 invariant is a cross-check between two places in the
+ * file, so the audit has a ceiling rather than a slope: measured, a 514 MiB container audited in
+ * 19.4 seconds, and past {@link VGEO_MAX_AUDIT_BYTES} the allocation is what fails. Refusing with
+ * the file's size in the message is better than an out-of-memory in whatever ran next.
+ *
+ * @param {VGeoContainerReader} reader an open container; only its byte source is used
+ * @param {number} [max_bytes] the ceiling to refuse above; a build machine auditing a file it just
+ *     wrote is the caller that has a reason to raise it
+ * @returns {Promise<VGeoDefect[]>} empty is the only good answer
+ * @throws {Error} when the file is larger than the audit can hold
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_audit_container(reader: VGeoContainerReader, max_bytes?: number): Promise<VGeoDefect[]>;
+//# sourceMappingURL=vgeo_audit_container.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_audit_container.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/geometry/virtual/format/read/tool/vgeo_audit_container.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8EARW,MAAM,GAEJ,QAAQ,YAAY,CAAC,CAwBjC"}

package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_audit_container.js

@@ -0,0 +1,48 @@
+import { BinaryBuffer } from "../../../../../../../core/binary/BinaryBuffer.js";
+import { vgeo_validate_container } from "../../vgeo_validate_container.js";
+import { VGEO_MAX_AUDIT_BYTES } from "./VGEO_MAX_AUDIT_BYTES.js";
+
+/**
+ * The whole-file audit: every build invariant of `VGEO_FORMAT.md` §11, every checksum, and the
+ * directory against what a frame scan reconstructs.
+ *
+ * **This reads the entire file**, which is the one thing `VGeoContainerReader` exists to avoid, and
+ * that is why it lives here instead of on it. It answers a question about whoever *produced* the
+ * file; nothing about reading one depends on it having been asked, and a renderer holding a thousand
+ * open containers must not have a method within reach that turns one of them into a multi-gigabyte
+ * allocation.
+ *
+ * The size check is the point of the wrapper as much as the location is. {@link vgeo_validate_container}
+ * takes one `ArrayBuffer` because every §11 invariant is a cross-check between two places in the
+ * file, so the audit has a ceiling rather than a slope: measured, a 514 MiB container audited in
+ * 19.4 seconds, and past {@link VGEO_MAX_AUDIT_BYTES} the allocation is what fails. Refusing with
+ * the file's size in the message is better than an out-of-memory in whatever ran next.
+ *
+ * @param {VGeoContainerReader} reader an open container; only its byte source is used
+ * @param {number} [max_bytes] the ceiling to refuse above; a build machine auditing a file it just
+ *     wrote is the caller that has a reason to raise it
+ * @returns {Promise<VGeoDefect[]>} empty is the only good answer
+ * @throws {Error} when the file is larger than the audit can hold
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function vgeo_audit_container(reader, max_bytes = VGEO_MAX_AUDIT_BYTES) {
+    const source = reader.source;
+
+    if (source.byte_length > max_bytes) {
+        throw new Error(
+            `${source.name} is ${source.byte_length} bytes and the whole-file audit reads a`
+            + ` container as one buffer, which is bounded at ${max_bytes};`
+            + ` audit it where it was built, or raise the bound deliberately`
+        );
+    }
+
+    const bytes = await source.read(0, source.byte_length);
+
+    const whole = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+        ? bytes.buffer
+        : bytes.slice().buffer;
+
+    return vgeo_validate_container(BinaryBuffer.fromArrayBuffer(whole));
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Install every page the directory lists.
+ *
+ * The opposite of what `VGeoContainerReader` is for, and exactly what a tool wants when the question
+ * is about the file rather than about a view of it — the pages no cut reaches are the ones a bug
+ * hides in.
+ *
+ * It lives here rather than on the reader because at the scale the format targets this is not a slow
+ * operation but an impossible one, and a renderer must not have it within reach of a container it is
+ * holding. Measured on a synthetic 2,000-page container of 544 KB pages: 514 MiB resident in 210 ms.
+ * The pages of one 100-million-triangle asset are several gigabytes, and there are supposed to be a
+ * thousand assets.
+ *
+ * **It goes on past a page it cannot read, and then fails.** A tool auditing a file wants the count
+ * of what could not be installed rather than the first entry on the list, and every reason is on the
+ * reader's quarantine afterwards (`VGeoContainerReader.quarantine`) whether this throws or not. The
+ * throw is what makes it a tool rather than a runtime path: the runtime's answer to a page that will
+ * not arrive is the clamped cut, and a tool's answer is to say so.
+ *
+ * @param {VGeoContainerReader} reader
+ * @param {function(number, number): void} [on_progress] called with pages attempted and total
+ * @returns {Promise<number>} how many pages are resident afterwards
+ * @throws {Error} when any page could not be installed, naming the count and the first reason
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_install_all_pages(reader: VGeoContainerReader, on_progress?: (arg0: number, arg1: number) => void): Promise<number>;
+//# sourceMappingURL=vgeo_install_all_pages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_install_all_pages.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,yFAPoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,MAAM,CAAC,CAsC3B"}

package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js

@@ -0,0 +1,60 @@
+/**
+ * Install every page the directory lists.
+ *
+ * The opposite of what `VGeoContainerReader` is for, and exactly what a tool wants when the question
+ * is about the file rather than about a view of it — the pages no cut reaches are the ones a bug
+ * hides in.
+ *
+ * It lives here rather than on the reader because at the scale the format targets this is not a slow
+ * operation but an impossible one, and a renderer must not have it within reach of a container it is
+ * holding. Measured on a synthetic 2,000-page container of 544 KB pages: 514 MiB resident in 210 ms.
+ * The pages of one 100-million-triangle asset are several gigabytes, and there are supposed to be a
+ * thousand assets.
+ *
+ * **It goes on past a page it cannot read, and then fails.** A tool auditing a file wants the count
+ * of what could not be installed rather than the first entry on the list, and every reason is on the
+ * reader's quarantine afterwards (`VGeoContainerReader.quarantine`) whether this throws or not. The
+ * throw is what makes it a tool rather than a runtime path: the runtime's answer to a page that will
+ * not arrive is the clamped cut, and a tool's answer is to say so.
+ *
+ * @param {VGeoContainerReader} reader
+ * @param {function(number, number): void} [on_progress] called with pages attempted and total
+ * @returns {Promise<number>} how many pages are resident afterwards
+ * @throws {Error} when any page could not be installed, naming the count and the first reason
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function vgeo_install_all_pages(reader, on_progress = undefined) {
+    const directory = await reader.read_directory();
+
+    const total = directory.page_count;
+
+    let failed = 0;
+    let first = '';
+
+    for (let index = 0; index < total; index++) {
+        try {
+            await reader.install(index, directory.frame_offset[index], directory.fetch_size[index]);
+        } catch (e) {
+            failed++;
+
+            if (first === '') {
+                first = String(e?.message ?? e);
+            }
+        }
+
+        if (on_progress !== undefined) {
+            on_progress(index + 1, total);
+        }
+    }
+
+    if (failed > 0) {
+        throw new Error(
+            `${failed} of ${total} pages of ${reader.source.name} could not be installed;`
+            + ` the first was: ${first}`
+        );
+    }
+
+    return reader.resident_page_count;
+}

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

@@ -11,12 +11,19 @@
  * numbers. §10 requires the response be `206` with the range that was asked for, so that is checked
  * on every read.
  *
+ * **Each range gets its own abort signal.** `init` is the whole source's — credentials, headers, and
+ * an abort that tears down every request this source will ever make — while the signal
+ * {@link VGeoByteSource.read} passes belongs to one page. A camera that moved wants to drop the
+ * fetches for the pages it stopped wanting and keep the rest, and that is only possible if the two
+ * are separate: the request is issued under both, and either one aborting it is enough.
+ *
  * 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
+ * @param {RequestInit} [init] passed to every request — credentials, headers, and an abort signal
+ *     that applies to the whole source
  * @returns {Promise<VGeoByteSource>}
  * @throws {Error} when the resource is missing, or does not serve ranges
  *

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,4CATW,MAAM,SACN,WAAW,GAET,QAAQ,cAAc,CAAC,CA8CnC;+BA1E8B,qBAAqB"}

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

@@ -13,12 +13,19 @@ import { VGeoByteSource } from "./VGeoByteSource.js";
  * numbers. §10 requires the response be `206` with the range that was asked for, so that is checked
  * on every read.
  *
+ * **Each range gets its own abort signal.** `init` is the whole source's — credentials, headers, and
+ * an abort that tears down every request this source will ever make — while the signal
+ * {@link VGeoByteSource.read} passes belongs to one page. A camera that moved wants to drop the
+ * fetches for the pages it stopped wanting and keep the rest, and that is only possible if the two
+ * are separate: the request is issued under both, and either one aborting it is enough.
+ *
  * 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
+ * @param {RequestInit} [init] passed to every request — credentials, headers, and an abort signal
+ *     that applies to the whole source
  * @returns {Promise<VGeoByteSource>}
  * @throws {Error} when the resource is missing, or does not serve ranges
  *
@@ -30,7 +37,7 @@ export async function vgeo_fetch_byte_source(url, init = {}) {
 
     return new VGeoByteSource(
         byte_length,
-        async (offset, length) => {
+        async (offset, length, signal) => {
             if (length === 0) {
                 return new Uint8Array(0);
             }
@@ -40,6 +47,7 @@ export async function vgeo_fetch_byte_source(url, init = {}) {
             const response = await fetch(url, {
                 ...init,
                 headers: { ...init.headers, Range: `bytes=${offset}-${last}` },
+                signal: either(init.signal, signal),
             });
 
             if (response.status !== 206) {
@@ -66,6 +74,28 @@ export async function vgeo_fetch_byte_source(url, init = {}) {
     );
 }
 
+/**
+ * One signal that fires when either of two does.
+ *
+ * `AbortSignal.any` is the standard answer and is what this uses when both are there; the cases
+ * where only one is are the common ones and cost nothing.
+ *
+ * @param {AbortSignal} [a]
+ * @param {AbortSignal} [b]
+ * @returns {AbortSignal|undefined}
+ */
+function either(a, b) {
+    if (a === undefined || a === null) {
+        return b ?? undefined;
+    }
+
+    if (b === undefined || b === null) {
+        return a;
+    }
+
+    return AbortSignal.any([a, b]);
+}
+
 /**
  * How long the resource is.
  *