@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -0,0 +1,236 @@
+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_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
+import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
+import { vgeo_read_page } from "./vgeo_read_page.js";
+
+/**
+ * @typedef {import("./VGeoPage.js").VGeoPage} VGeoPage
+ */
+
+const LE = true;
+
+/**
+ * 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 {
+    /**
+     * @type {boolean}
+     */
+    quarantine;
+
+    /**
+     * The last attempt's failure, in the source's own words.
+     * @type {string}
+     */
+    reason;
+
+    /**
+     * @param {string} message
+     * @param {boolean} quarantine
+     * @param {string} reason
+     */
+    constructor(message, quarantine, reason) {
+        super(message);
+
+        this.name = 'VGeoFetchError';
+        this.quarantine = quarantine;
+        this.reason = reason;
+    }
+}
+
+/**
+ * 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 {
+    /**
+     * @type {function(number, number, AbortSignal=): Promise<Uint8Array>}
+     */
+    #read;
+
+    /**
+     * @type {bigint|function(): bigint}
+     */
+    #asset_id_low64;
+
+    /**
+     * @type {boolean}
+     */
+    #verify_frames;
+
+    /**
+     * @type {number}
+     */
+    #fetch_retries;
+
+    /**
+     * @type {number}
+     */
+    #fetch_retry_backoff_ms;
+
+    /**
+     * @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 = false,
+                    fetch_retries = 2,
+                    fetch_retry_backoff_ms = 50,
+                }) {
+        assert.isFunction(read, 'read');
+        assert.isNonNegativeInteger(fetch_retries, 'fetch_retries');
+        assert.isNonNegativeInteger(fetch_retry_backoff_ms, 'fetch_retry_backoff_ms');
+
+        this.#read = read;
+        this.#asset_id_low64 = asset_id_low64;
+        this.#verify_frames = verify_frames;
+        this.#fetch_retries = fetch_retries;
+        this.#fetch_retry_backoff_ms = fetch_retry_backoff_ms;
+    }
+
+    /**
+     * @param {number} page_index
+     * @param {number} frame_offset absolute, in the container
+     * @param {number} fetch_size
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<VGeoPage>}
+     * @throws {VGeoFetchError}
+     */
+    async fetch(page_index, frame_offset, fetch_size, signal = undefined) {
+        for (let attempt = 0; ; attempt++) {
+            try {
+                return await this.#once(page_index, frame_offset, fetch_size, signal);
+            } catch (e) {
+                if (signal !== undefined && signal.aborted) {
+                    // cancelled rather than failed: nothing is wrong with this page
+                    throw new VGeoFetchError(
+                        `page ${page_index}: the fetch was cancelled`, false, String(e?.message ?? e)
+                    );
+                }
+
+                const reason = String(e?.message ?? e);
+
+                if (attempt >= this.#fetch_retries) {
+                    throw new VGeoFetchError(
+                        `page ${page_index} is quarantined after ${attempt + 1} attempt(s): ${reason}`,
+                        true,
+                        reason
+                    );
+                }
+
+                await delay(this.#fetch_retry_backoff_ms * (1 << attempt), signal);
+            }
+        }
+    }
+
+    /**
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {AbortSignal|undefined} signal
+     * @returns {Promise<VGeoPage>}
+     */
+    async #once(page_index, frame_offset, fetch_size, signal) {
+        const bytes = await this.#read(frame_offset, fetch_size, signal);
+
+        if (this.#verify_frames) {
+            this.#verify_frame(bytes, page_index);
+        }
+
+        const page = vgeo_read_page(bytes, page_index);
+
+        page.frame_offset = frame_offset;
+
+        return page;
+    }
+
+    /**
+     * The identity-seeded frame checksum, against what the frame stores.
+     *
+     * @param {Uint8Array} bytes
+     * @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 asset_id = typeof this.#asset_id_low64 === 'function'
+            ? this.#asset_id_low64()
+            : this.#asset_id_low64;
+
+        const computed = vgeo_compute_frame_checksum(
+            BinaryBuffer.fromArrayBuffer(copy), frame, asset_id
+        );
+
+        if (computed !== stored) {
+            throw new Error(
+                `page ${page_index}: its frame checksums to 0x${computed.toString(16)}`
+                + ` and stores 0x${stored.toString(16)}`
+            );
+        }
+    }
+}
+
+/**
+ * @param {number} ms
+ * @param {AbortSignal|undefined} 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 !== undefined && 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/VGeoReadOptions.d.ts

@@ -100,5 +100,19 @@ export class VGeoReadOptions {
      * @type {number}
      */
     fetch_retry_backoff_ms: number;
+    /**
+     * Whether the reader keeps its own selectability — the RAM tier's answer to design §6's
+     * activation rule, a live-reference counter per resident group with a pending index for pages
+     * not yet here — as pages are installed and evicted.
+     *
+     * On for a tool or a viewer that cuts on the CPU, which is what `is_selectable` serves. Off for
+     * a reader a `VGeoResidency` owns: the runtime answers activation in the VRAM arena and never
+     * asks the reader, and at fifty thousand resident pages the counters and the pending index are
+     * tens of megabytes of nested maps nobody reads (RUNTIME_PLAN_2026_09_14 §4.6). With it off,
+     * `is_selectable` answers false for every group.
+     *
+     * @type {boolean}
+     */
+    track_selectability: boolean;
 }
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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;IAE5B;;;;;;;;;;;;OAYG;IACH,qBAFU,OAAO,CAEU;CAC9B"}

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

@@ -107,4 +107,19 @@ export class VGeoReadOptions {
      * @type {number}
      */
     fetch_retry_backoff_ms = 50;
+
+    /**
+     * Whether the reader keeps its own selectability — the RAM tier's answer to design §6's
+     * activation rule, a live-reference counter per resident group with a pending index for pages
+     * not yet here — as pages are installed and evicted.
+     *
+     * On for a tool or a viewer that cuts on the CPU, which is what `is_selectable` serves. Off for
+     * a reader a `VGeoResidency` owns: the runtime answers activation in the VRAM arena and never
+     * asks the reader, and at fifty thousand resident pages the counters and the pending index are
+     * tens of megabytes of nested maps nobody reads (RUNTIME_PLAN_2026_09_14 §4.6). With it off,
+     * `is_selectable` answers false for every group.
+     *
+     * @type {boolean}
+     */
+    track_selectability = true;
 }

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

@@ -0,0 +1,31 @@
+/**
+ * A byte source rebuilt from what another thread said about it.
+ *
+ * A `VGeoByteSource` is a closure and cannot cross a worker boundary; its `descriptor` can. The
+ * three forms the engine makes carry one: a URL with the length already probed, so a worker opens
+ * it with no `HEAD`; a `Blob`, which structured clone carries by reference; and bytes in memory,
+ * which are copied once per worker. A source built by hand has no descriptor and stays on the
+ * thread that built it.
+ *
+ * @param {{kind: 'url', url: string, byte_length: number, init?: object}
+ *     | {kind: 'blob', blob: Blob}
+ *     | {kind: 'memory', bytes: Uint8Array}} descriptor
+ * @returns {VGeoByteSource}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_byte_source_from_descriptor(descriptor: {
+    kind: 'url';
+    url: string;
+    byte_length: number;
+    init?: object;
+} | {
+    kind: 'blob';
+    blob: Blob;
+} | {
+    kind: 'memory';
+    bytes: Uint8Array;
+}): VGeoByteSource;
+import { VGeoByteSource } from "./VGeoByteSource.js";
+//# sourceMappingURL=vgeo_byte_source_from_descriptor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_byte_source_from_descriptor.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_byte_source_from_descriptor.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,6DARW;IAAC,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAC,GAChE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAC,GAC1B;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAC,GAC/B,cAAc,CAgB1B;+BA/B8B,qBAAqB"}

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

@@ -0,0 +1,32 @@
+import { VGeoByteSource } from "./VGeoByteSource.js";
+import { vgeo_byte_source_over_url } from "./vgeo_fetch_byte_source.js";
+
+/**
+ * A byte source rebuilt from what another thread said about it.
+ *
+ * A `VGeoByteSource` is a closure and cannot cross a worker boundary; its `descriptor` can. The
+ * three forms the engine makes carry one: a URL with the length already probed, so a worker opens
+ * it with no `HEAD`; a `Blob`, which structured clone carries by reference; and bytes in memory,
+ * which are copied once per worker. A source built by hand has no descriptor and stays on the
+ * thread that built it.
+ *
+ * @param {{kind: 'url', url: string, byte_length: number, init?: object}
+ *     | {kind: 'blob', blob: Blob}
+ *     | {kind: 'memory', bytes: Uint8Array}} descriptor
+ * @returns {VGeoByteSource}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_byte_source_from_descriptor(descriptor) {
+    switch (descriptor?.kind) {
+        case 'url':
+            return vgeo_byte_source_over_url(descriptor.url, descriptor.byte_length, descriptor.init ?? {});
+        case 'blob':
+            return VGeoByteSource.from_blob(descriptor.blob);
+        case 'memory':
+            return VGeoByteSource.of(descriptor.bytes);
+        default:
+            throw new Error(`not a byte source descriptor: ${JSON.stringify(descriptor?.kind)}`);
+    }
+}

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

@@ -31,5 +31,15 @@
  * @copyright Company Named Limited (c) 2026
  */
 export function vgeo_fetch_byte_source(url: string, init?: RequestInit): Promise<VGeoByteSource>;
+/**
+ * The source over a URL whose length is already known — what a worker rebuilds from a
+ * descriptor without a second `HEAD`.
+ *
+ * @param {string} url
+ * @param {number} byte_length
+ * @param {RequestInit} [init]
+ * @returns {VGeoByteSource}
+ */
+export function vgeo_byte_source_over_url(url: string, byte_length: number, init?: RequestInit): 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

@@ -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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,4CATW,MAAM,SACN,WAAW,GAET,QAAQ,cAAc,CAAC,CA8CnC;+BA1E8B,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,CAUnC;AAED;;;;;;;;GAQG;AACH,+CALW,MAAM,eACN,MAAM,SACN,WAAW,GACT,cAAc,CA+C1B;+BA9F8B,qBAAqB"}

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

@@ -35,7 +35,20 @@ import { VGeoByteSource } from "./VGeoByteSource.js";
 export async function vgeo_fetch_byte_source(url, init = {}) {
     const byte_length = await probe_length(url, init);
 
-    return new VGeoByteSource(
+    return vgeo_byte_source_over_url(url, byte_length, init);
+}
+
+/**
+ * The source over a URL whose length is already known — what a worker rebuilds from a
+ * descriptor without a second `HEAD`.
+ *
+ * @param {string} url
+ * @param {number} byte_length
+ * @param {RequestInit} [init]
+ * @returns {VGeoByteSource}
+ */
+export function vgeo_byte_source_over_url(url, byte_length, init = {}) {
+    const source = new VGeoByteSource(
         byte_length,
         async (offset, length, signal) => {
             if (length === 0) {
@@ -72,6 +85,13 @@ export async function vgeo_fetch_byte_source(url, init = {}) {
         },
         url
     );
+
+    // a signal cannot cross a worker boundary and belongs to this thread's fetches anyway
+    const { signal, ...cloneable } = init;
+
+    source.descriptor = { kind: 'url', url, byte_length, init: cloneable };
+
+    return source;
 }
 
 /**

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

@@ -0,0 +1,15 @@
+/**
+ * @param {VGeoPage} page
+ * @returns {{record: object, buffers: ArrayBuffer[]}} the record to post, and the buffers to transfer
+ */
+export function vgeo_page_transferable(page: VGeoPage): {
+    record: object;
+    buffers: ArrayBuffer[];
+};
+/**
+ * @param {object} record as {@link vgeo_page_transferable} made it
+ * @returns {VGeoPage}
+ */
+export function vgeo_page_from_transfer(record: object): VGeoPage;
+import { VGeoPage } from "./VGeoPage.js";
+//# sourceMappingURL=vgeo_page_transfer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_page_transfer.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_page_transfer.js"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,6CAHW,QAAQ,GACN;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,EAAE,CAAA;CAAC,CA4BpD;AAED;;;GAGG;AACH,gDAHW,MAAM,GACJ,QAAQ,CAsBpB;yBAnFwB,eAAe"}

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

@@ -0,0 +1,84 @@
+import { VGeoPage } from "./VGeoPage.js";
+
+/**
+ * A decoded page across a worker boundary, in both directions.
+ *
+ * `vgeo_read_page` decodes into a `VGeoPage` of some thirty typed arrays, each over its own buffer.
+ * Structured clone would copy every one and drop the class; this records each view's kind, offset
+ * and length beside its buffer, hands every distinct buffer to the transfer list, and rebuilds the
+ * class on the other side — so a page costs a few dozen small allocations to cross and no copy of
+ * its bytes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const VIEW_CONSTRUCTORS = {
+    Uint8Array,
+    Uint16Array,
+    Uint32Array,
+    Int8Array,
+    Int16Array,
+    Int32Array,
+    Float32Array,
+    Float64Array,
+    DataView,
+};
+
+/**
+ * @param {VGeoPage} page
+ * @returns {{record: object, buffers: ArrayBuffer[]}} the record to post, and the buffers to transfer
+ */
+export function vgeo_page_transferable(page) {
+    const record = {};
+
+    /**
+     * @type {Set<ArrayBuffer>}
+     */
+    const buffers = new Set();
+
+    for (const key of Object.keys(page)) {
+        const value = page[key];
+
+        if (ArrayBuffer.isView(value)) {
+            record[key] = {
+                view: value.constructor.name,
+                buffer: value.buffer,
+                offset: value.byteOffset,
+                length: value instanceof DataView ? value.byteLength : value.length,
+            };
+
+            buffers.add(value.buffer);
+        } else {
+            record[key] = value;
+        }
+    }
+
+    return { record, buffers: Array.from(buffers) };
+}
+
+/**
+ * @param {object} record as {@link vgeo_page_transferable} made it
+ * @returns {VGeoPage}
+ */
+export function vgeo_page_from_transfer(record) {
+    const page = new VGeoPage();
+
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+
+        if (value !== null && typeof value === 'object' && typeof value.view === 'string') {
+            const constructor = VIEW_CONSTRUCTORS[value.view];
+
+            if (constructor === undefined) {
+                throw new Error(`a page came back with a ${value.view} in ${key}`);
+            }
+
+            page[key] = new constructor(value.buffer, value.offset, value.length);
+        } else {
+            page[key] = value;
+        }
+    }
+
+    return page;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * The worker side of {@link VGeoPageFetcher}'s protocol, over any port shaped like a worker's
+ * global — `onmessage` in, `postMessage(message, transfer)` out — so a spec can serve it over a
+ * loopback in-process and the worker entry serves it over `self`.
+ *
+ * Requests: `{id, source_id, descriptor?, asset_id_low64, verify_frames, fetch_retries,
+ * fetch_retry_backoff_ms, page_index, frame_offset, fetch_size}` — the descriptor comes with the
+ * first request naming a source and is remembered after; `{cancel: id}` aborts one in flight.
+ * Replies: `{id, page}` with the page's buffers transferred, or `{id, error: {message, quarantine,
+ * reason}}`.
+ *
+ * @param {{onmessage: function|null, postMessage: function(object, ArrayBuffer[]=): void}} port
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_page_worker_serve(port: {
+    onmessage: Function | null;
+    postMessage: (arg0: object, arg1: ArrayBuffer[] | undefined) => void;
+}): void;
+//# sourceMappingURL=vgeo_page_worker_serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_page_worker_serve.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_page_worker_serve.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW;IAAC,SAAS,EAAE,WAAS,IAAI,CAAC;IAAC,WAAW,SAAW,MAAM,QAAE,WAAW,EAAE,iBAAI,IAAI,CAAA;CAAC,GAC7E,IAAI,CA+EhB"}

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

@@ -0,0 +1,96 @@
+import { VGeoPageFetcherCore } from "./VGeoPageFetcherCore.js";
+import { vgeo_byte_source_from_descriptor } from "./vgeo_byte_source_from_descriptor.js";
+import { vgeo_page_transferable } from "./vgeo_page_transfer.js";
+
+/**
+ * The worker side of {@link VGeoPageFetcher}'s protocol, over any port shaped like a worker's
+ * global — `onmessage` in, `postMessage(message, transfer)` out — so a spec can serve it over a
+ * loopback in-process and the worker entry serves it over `self`.
+ *
+ * Requests: `{id, source_id, descriptor?, asset_id_low64, verify_frames, fetch_retries,
+ * fetch_retry_backoff_ms, page_index, frame_offset, fetch_size}` — the descriptor comes with the
+ * first request naming a source and is remembered after; `{cancel: id}` aborts one in flight.
+ * Replies: `{id, page}` with the page's buffers transferred, or `{id, error: {message, quarantine,
+ * reason}}`.
+ *
+ * @param {{onmessage: function|null, postMessage: function(object, ArrayBuffer[]=): void}} port
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_page_worker_serve(port) {
+    /**
+     * @type {Map<number, VGeoPageFetcherCore>}
+     */
+    const cores = new Map();
+
+    /**
+     * @type {Map<number, AbortController>}
+     */
+    const controllers = new Map();
+
+    port.onmessage = async event => {
+        const data = event.data;
+
+        if (data.cancel !== undefined) {
+            controllers.get(data.cancel)?.abort(new Error('cancelled'));
+
+            return;
+        }
+
+        const { id, source_id, page_index, frame_offset, fetch_size } = data;
+
+        let core = cores.get(source_id);
+
+        if (core === undefined) {
+            if (data.descriptor === undefined) {
+                port.postMessage({
+                    id,
+                    error: {
+                        message: `page ${page_index}: the worker does not know source ${source_id}`,
+                        quarantine: false,
+                        reason: 'no descriptor',
+                    },
+                });
+
+                return;
+            }
+
+            const source = vgeo_byte_source_from_descriptor(data.descriptor);
+
+            core = new VGeoPageFetcherCore({
+                read: (offset, length, signal) => source.read(offset, length, signal),
+                asset_id_low64: data.asset_id_low64,
+                verify_frames: data.verify_frames,
+                fetch_retries: data.fetch_retries,
+                fetch_retry_backoff_ms: data.fetch_retry_backoff_ms,
+            });
+
+            cores.set(source_id, core);
+        }
+
+        const controller = new AbortController();
+
+        controllers.set(id, controller);
+
+        try {
+            const page = await core.fetch(page_index, frame_offset, fetch_size, controller.signal);
+
+            const { record, buffers } = vgeo_page_transferable(page);
+
+            port.postMessage({ id, page: record }, buffers);
+        } catch (e) {
+            port.postMessage({
+                id,
+                error: {
+                    message: String(e?.message ?? e),
+                    quarantine: e?.quarantine === true,
+                    reason: e?.reason ?? String(e?.message ?? e),
+                },
+            });
+        } finally {
+            controllers.delete(id);
+        }
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CAgFpB;yBA/GwB,eAAe"}
+{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CAiFpB;yBAhHwB,eAAe"}