@bitruvius/foundation 0.3.0

package/LICENSE

@@ -0,0 +1,167 @@
+Bitruvius SDK License Agreement
+
+Copyright (c) 2026 Bitruvius, Inc. All rights reserved.
+
+This Bitruvius SDK License Agreement (the "Agreement") is between you and
+Bitruvius, Inc., a Delaware corporation ("Bitruvius"), and governs the use of
+the Bitruvius SDK, including all @bitruvius npm packages, browser bundles,
+WebAssembly binaries, documentation, and related materials distributed with
+this notice (collectively, the "SDK").
+
+1. LICENSE GRANT
+
+Subject to the terms of this Agreement, Bitruvius grants you a worldwide,
+royalty-free, non-exclusive, non-transferable, revocable license to:
+
+  (a) use the SDK, in unmodified form, in any application, website, or
+      service you develop, whether commercial or non-commercial (an
+      "Application"); and
+  (b) reproduce and distribute the SDK solely as embedded in or bundled
+      with an Application (for example, as part of a compiled or bundled
+      build of the Application), provided the SDK is not distributed on a
+      standalone basis and remains subject to this Agreement.
+
+2. RESTRICTIONS
+
+Except as expressly permitted in Section 1 or by applicable law
+notwithstanding this limitation, you may not, and may not permit or assist
+any third party to:
+
+  (a) modify, adapt, translate, or create derivative works of the SDK;
+  (b) redistribute, publish, sublicense, sell, rent, lease, or otherwise
+      make the SDK available on a standalone basis, including republishing
+      the SDK or any portion of it to any package registry or content
+      delivery network;
+  (c) reverse engineer, decompile, disassemble, decode, or otherwise
+      attempt to derive or reconstruct the source code, underlying ideas,
+      algorithms, file formats, or non-public APIs of the SDK, including
+      the WebAssembly binaries contained in the SDK;
+  (d) use the SDK, or any output or knowledge derived from it, to develop,
+      train, or improve a product or service that competes with the SDK or
+      with Bitruvius codec technology, including implementing or
+      reimplementing encoders or decoders for Bitruvius codec formats;
+  (e) remove, obscure, or alter any copyright, license, or attribution
+      notices contained in the SDK.
+
+THIRD-PARTY COMPONENTS. Nothing in this Section 2 limits any right granted to
+you directly by a third party under the license covering a third-party
+component distributed with the SDK. Those components and their licenses are
+identified in the NOTICES files distributed alongside them, together with a
+copy of each license. Where this Agreement conflicts with such a license as
+applied to that component, the third-party license governs that component.
+
+THIRD-PARTY DATA AND SERVICES. The SDK is able to connect to data, imagery,
+tilesets, and services operated by third parties, some of which require
+credentials that you obtain in your own name. This Agreement grants you no
+right, title, or license in or to any such data or service. Your access to and
+use of them is governed solely by your agreement with the relevant provider,
+including any obligation to display attribution or to restrict redistribution.
+Bitruvius does not supply, endorse, or warrant any third-party data or service,
+is not a party to your agreement with any provider, and bears no responsibility
+for its availability, accuracy, terms, or charges.
+
+3. OWNERSHIP
+
+The SDK is licensed, not sold. Bitruvius and its licensors retain all
+right, title, and interest in and to the SDK, including all intellectual
+property rights. No rights are granted except as expressly set out in this
+Agreement.
+
+4. PRERELEASE VERSIONS
+
+Versions of the SDK identified as alpha or beta (including any 0.x or
+prerelease-tagged versions) are provided for evaluation and testing,
+may change or be discontinued at any time without notice, and are provided
+without any commitment of support or backward compatibility.
+
+5. NO WARRANTY
+
+THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, OR
+NON-INFRINGEMENT. BITRUVIUS DOES NOT WARRANT THAT THE SDK WILL BE
+UNINTERRUPTED, ERROR-FREE, OR SECURE.
+
+6. LIMITATION OF LIABILITY
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT WILL BITRUVIUS BE
+LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY
+DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, OR GOODWILL, ARISING
+OUT OF OR RELATING TO THIS AGREEMENT OR THE SDK, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES. BITRUVIUS'S TOTAL AGGREGATE LIABILITY ARISING
+OUT OF OR RELATING TO THIS AGREEMENT WILL NOT EXCEED ONE HUNDRED (100) US
+DOLLARS.
+
+7. INDEMNIFICATION
+
+You will defend, indemnify, and hold harmless Bitruvius and its officers,
+directors, employees, and agents from and against any third-party claim,
+demand, suit, or proceeding, and any resulting losses, damages, liabilities,
+settlements, costs, and reasonable attorneys' fees, arising out of or
+relating to: (a) your Applications or any product or service you build with
+or distribute using the SDK; (b) your data, content, or the services you
+direct the SDK to access; (c) your use of the SDK in violation of this
+Agreement or of any applicable law; or (d) your infringement or
+misappropriation of any third party's rights. Bitruvius will notify you of
+any such claim, allow you to control the defense (except that any settlement
+requiring an admission or payment by Bitruvius requires its consent, not to
+be unreasonably withheld), and provide reasonable cooperation at your
+expense.
+
+BITRUVIUS PROVIDES NO INDEMNITY OF ANY KIND UNDER THIS AGREEMENT, INCLUDING
+NO DEFENSE OR INDEMNITY AGAINST ANY CLAIM THAT THE SDK INFRINGES OR
+MISAPPROPRIATES ANY PATENT, COPYRIGHT, TRADEMARK, TRADE SECRET, OR OTHER
+INTELLECTUAL PROPERTY RIGHT. THE SDK IS LICENSED AT NO CHARGE AND IS
+PROVIDED WITHOUT SUCH PROTECTION. If you require an intellectual property
+indemnity, contact legal@bitruvius.com about a commercial license; any such
+indemnity applies only if expressly agreed in a signed written agreement.
+
+8. TERMINATION
+
+This Agreement is effective until terminated. It terminates automatically,
+without notice, if you breach any of its terms. Upon termination you must
+cease all use of the SDK and destroy all copies in your possession or
+control, except that Applications already distributed to end users with the
+SDK embedded may continue to be used. Sections 2, 3, 5, 6, 7, 8, and 9
+survive termination.
+
+9. GENERAL
+
+This Agreement constitutes the entire agreement between you and Bitruvius
+concerning the SDK and supersedes any prior agreements. Bitruvius may
+publish updated or supplemental terms for future SDK versions at
+https://bitruvius.com/eula; the terms accompanying a given SDK version
+govern that version. If any provision of this Agreement is held
+unenforceable, the remaining provisions remain in full force.
+
+GOVERNING LAW AND VENUE. This Agreement is governed by and construed in
+accordance with the laws of the State of Georgia and the applicable federal
+law of the United States, without regard to conflict-of-law provisions, and
+excluding the United Nations Convention on Contracts for the International
+Sale of Goods. The exclusive venue for any dispute arising out of or
+relating to this Agreement or the SDK is the state or federal courts located
+in Cobb County, Georgia, and each party consents to personal jurisdiction
+and venue in those courts.
+
+ASSIGNMENT. You may not assign or transfer this Agreement, in whole or in
+part, without Bitruvius's prior written consent, and any attempted
+assignment without that consent is void. Bitruvius may assign this
+Agreement freely, including in connection with a merger, acquisition, or
+sale of assets. This Agreement binds and benefits the parties' permitted
+successors and assigns.
+
+EXPORT COMPLIANCE. The SDK may be subject to export control laws,
+including the U.S. Export Administration Regulations and applicable
+sanctions programs. You represent that you are not located in, and will
+not use or export the SDK in or to, any country or to any person or entity
+subject to such restrictions, and that you will comply with all applicable
+export and import laws.
+
+U.S. GOVERNMENT END USERS. The SDK is "commercial computer software" and
+"commercial computer software documentation" as those terms are used in
+48 C.F.R. 12.212 and 48 C.F.R. 227.7202. Any use, duplication, or
+disclosure by or on behalf of the U.S. Government is governed solely by
+the terms of this Agreement.
+
+For commercial licensing of Bitruvius encoder technology, or any questions
+about this Agreement, contact: legal@bitruvius.com

package/README.md

@@ -0,0 +1,76 @@
+<p align="center">
+  <a href="https://bitruvius.com"><img src="https://cdn.bitruvius.com/brand/bitruvius-logo.png" width="360" alt="Bitruvius"></a>
+</p>
+
+# @bitruvius/foundation
+
+**The dependency root of the Bitruvius SDK: scheduling, capability detection, transport authorization, configuration and errors, with nothing underneath it.**
+
+> **Internal building block.** This package exists so that
+> [`@bitruvius/sdk-maplibre`](https://www.npmjs.com/package/@bitruvius/sdk-maplibre) and the
+> Bitruvius codecs can resolve their dependencies on npm. It has no standalone product story.
+> Unless you are deliberately building against it, install the SDK instead.
+
+## Why it is a separate package
+
+Bitruvius ships as many small packages: a codec per format, a geospatial layer, an auth adapter, a renderer SDK. They all need the same worker pool, the same error type and the same configuration store, and none of them may depend on each other. A raster codec cannot depend on the geospatial layer, and the geospatial layer cannot depend on a raster codec.
+
+So the shared pieces moved down to the one package with nothing beneath it. This package has zero runtime dependencies and touches no WebGL, DOM, wasm or geospatial code. That is what lets `@bitruvius/ript`, a scientific raster codec with no interest in maps, take the same worker pool as `@bitruvius/sdk-maplibre`. The geospatial layer is `@bitruvius/geo-core`, which builds on this.
+
+Two more things force a single low-level home:
+
+**Configuration has to be shared across copies of the SDK.** `configure()` writes to a namespaced key on `globalThis`, not to a module-scoped variable. A page can load several per-package CDN bundles, each carrying its own copy of the SDK, and they must still see one `wasmBaseUrl` and one signed-in ArcGIS session.
+
+**Errors have to survive duplicate bundles.** `BitruviusError.is()` duck-types on shape instead of using `instanceof`, for the same reason: two copies of the SDK on one page each throw errors that fail the other's `instanceof`. The stable `BVX_*` code set is defined exactly once, here, so every package throws identifiers you can still branch on after minification.
+
+## What is in it
+
+**Scheduling.** `WorkerPool` is a transferable Web Worker pool with per-task `AbortSignal` handling, a warm-up handshake, `broadcast`, and self-healing respawn under a budget, so a broken worker module or wasm URL fails the pool loudly rather than hanging every tile. `TaskQueue` bounds concurrency. `createCdnWorkerTrampoline` solves the cross-origin worker problem: `new Worker(crossOriginUrl)` throws a synchronous `SecurityError` before any network request is made, so a CDN-hosted SDK fetches its worker chunk's text and spawns it from a same-origin `blob:` URL instead. `reportWorkerDegradation` makes the main-thread fallback audible once per label, because a layer that renders slowly and a layer that renders nothing were both shipping silently.
+
+**Capability detection.** `detectCapabilities()` probes WebGL2, WebGPU, Workers, transferables and WebAssembly SIMD. SIMD is a hard gate rather than a preference: the codec wasm is compiled with `+simd128` and there is no non-SIMD build, so `recommendDecodeBackend()` throws instead of pretending. `DecodeBackend` names the execution model a decoder will use.
+
+**Transport.** `RequestAuthorizer` is a drop-in replacement for `fetch`, scoped to one streaming session. It is a `fetch` override rather than an `authorize()` callback because every call site already calls `fetch`, and because only the override holds the `Response`, which is what lets `@bitruvius/esri-auth` detect the ArcGIS challenge that arrives as HTTP 200 with `{ error: { code: 498 } }` in the body.
+
+`publicAuthorizer()` also enforces a credential trust boundary. A tileset is a third-party document that names further URLs, and the streaming engines fetch every one of them. Without the boundary, a tileset naming `https://attacker.example/tile.glb` harvests a Cesium ion token or a Google API key, both reusable and both billable, delivered by our own transport. Credentials go to the origin they were minted for and to nowhere else; other hosts get the request without them, and are warned once. A tile that fails to load is recoverable in a way that a leaked key is not.
+
+`fetchBinaryAsset()` fails on the transport problem instead of handing a wrong-typed body to a codec. A missing file that 404s to an HTML fallback page otherwise surfaces as a bad magic number of `1868833084`, which is the ASCII `<!do` of `<!doctype html>`, and sends you off to debug a decoder that is working correctly.
+
+**Configuration.** `configure`, `getConfig`, `configuredWasmUrl` and `resolveAuth`. One call points every codec at a wasm folder; an explicit per-decoder `wasmUrl` or `wasmBytes` still wins over it.
+
+**Errors.** `BitruviusError`, `BvxCode`, `BVX_CODES` and `asBitruviusError`, plus `abortError` and `isAbortError`, which follow the WHATWG cancellation convention with a plain `Error` named `AbortError` rather than a `DOMException`, since that is not constructible in every worker or test realm.
+
+## Depending on it directly
+
+Inside the SDK, `@bitruvius/geo-core`, `@bitruvius/codec-runtime`, `@bitruvius/esri-auth`, `@bitruvius/sdk-maplibre` and the codec packages all depend on it, which is why it is published at all.
+
+Outside the SDK, reach for it in two cases: you are writing a custom `RequestAuthorizer`, or you are catching SDK errors and want the error type and code list at their source. Both are re-exported by `@bitruvius/sdk-maplibre`, so installing this package on its own is rarely the answer.
+
+```sh
+npm i @bitruvius/foundation
+```
+
+```ts
+import { BitruviusError, configure } from '@bitruvius/foundation';
+
+// Serve every codec's .wasm from one folder (note the trailing slash).
+configure({ wasmBaseUrl: 'https://my.app/assets/bitruvius/' });
+
+try {
+  await layer.load();
+} catch (e) {
+  if (BitruviusError.is(e, 'BVX_GL_UNAVAILABLE')) showWebGl2Warning();
+  else throw e;
+}
+```
+
+## Trademarks
+
+Esri and ArcGIS are trademarks of Environmental Systems Research Institute, Inc. Cesium is a trademark of Cesium GS, Inc. Google is a trademark of Google LLC. MapLibre is a trademark of the MapLibre organization. All other marks are the property of their respective owners.
+
+These names are used solely to describe the data formats this software interoperates with. WebGL is a trademark of The Khronos Group Inc.
+
+Bitruvius is not affiliated with, sponsored by, or endorsed by any of them, and no such relationship is implied.
+
+## License
+
+See [LICENSE](./LICENSE). © Bitruvius, Inc.

package/dist/capability/detect.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime capability detection + decode-backend recommendation.
+ *
+ * The vendored BVC wasm is compiled with `+simd128`, so it can only run
+ * where WASM SIMD is available — `wasmSimd` is therefore a hard
+ * requirement, not a nice-to-have. The renderer needs WebGL2.
+ */
+/**
+ * How the bytes→arrays decode work is performed. P1 ships `cpu-wasm-workers`;
+ * the rest are reserved for fast-follow backends. This is a decode-**execution**
+ * concern, so it lives in the runtime base (not the geospatial layer).
+ */
+export type DecodeBackend = 'auto' | 'cpu-wasm-workers' | 'webgl2-unpack' | 'webgpu-compute' | 'cpu-wasm';
+/** The runtime features the SDK probes via {@link detectCapabilities}. */
+export interface Capabilities {
+    /** WebGL2 is available (required to render). */
+    readonly webgl2: boolean;
+    /** WebGPU is available (reserved for future GPU-decode backends). */
+    readonly webgpu: boolean;
+    /** Web Workers are available (enables off-main-thread decode). */
+    readonly workers: boolean;
+    /** Transferable objects (`MessageChannel`) are available (zero-copy worker handoff). */
+    readonly transferable: boolean;
+    /** WebAssembly fixed-width SIMD is available (REQUIRED — the codecs are `+simd128`). */
+    readonly wasmSimd: boolean;
+}
+/** The subset of globals {@link detectCapabilities} probes; pass a partial object in
+ *  tests to inject a deterministic environment. Defaults to `globalThis`. */
+export interface DetectEnv {
+    /** The `Worker` constructor, if present. */
+    Worker?: unknown;
+    /** The `MessageChannel` constructor, if present. */
+    MessageChannel?: unknown;
+    /** The `WebGL2RenderingContext` global, if present. */
+    WebGL2RenderingContext?: unknown;
+    /** `navigator`, probed for `navigator.gpu`. */
+    navigator?: {
+        gpu?: unknown;
+    };
+}
+/** Probe whether the runtime supports WebAssembly fixed-width SIMD (validates a tiny
+ *  `v128` module). @returns `true` when SIMD is supported. */
+export declare function isWasmSimdSupported(): boolean;
+/** Detect the SDK-relevant runtime {@link Capabilities}.
+ *  @param env - Globals to probe (default `globalThis`; override in tests).
+ *  @returns The detected {@link Capabilities}.
+ *
+ * @example
+ * ```ts
+ * const caps = detectCapabilities();
+ * if (!caps.webgl2 || !caps.wasmSimd) showUnsupportedBrowserNotice();
+ * ```
+ */
+export declare function detectCapabilities(env?: DetectEnv): Capabilities;
+/**
+ * Recommend the P1 {@link DecodeBackend} for the given capabilities.
+ * @param caps - At least `workers` and `wasmSimd` from {@link detectCapabilities}.
+ * @returns `'cpu-wasm-workers'` when Workers are available, else `'cpu-wasm'`.
+ * @throws Error when `wasmSimd` is `false` — there is no non-SIMD wasm build, so decode
+ *   cannot proceed in that runtime.
+ */
+export declare function recommendDecodeBackend(caps: Pick<Capabilities, 'workers' | 'wasmSimd'>): DecodeBackend;

package/dist/errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The stable set of Bitruvius error codes. Append-only and never renamed, so it is the
+ * one dependable error API across the SDK: branch on a {@link BitruviusError.code},
+ * not on message text or class names (shipped JS is minified).
+ *
+ * @remarks
+ * Each entry is a `BVX_*` string; the union of them is {@link BvxCode}. Use
+ * {@link BitruviusError.is} to test a caught value against one of these.
+ *
+ * @example
+ * ```ts
+ * import { BitruviusError } from '@bitruvius/foundation';
+ *
+ * try {
+ *   await decoder.decode(bytes);
+ * } catch (e) {
+ *   if (BitruviusError.is(e, 'BVX_WASM_LOAD_FAILED')) {
+ *     // CSP / MIME / network: fall back to a configured wasm URL, or surface a hint.
+ *   } else {
+ *     throw e;
+ *   }
+ * }
+ * ```
+ */
+export declare const BVX_CODES: readonly ["BVX_WASM_LOAD_FAILED", "BVX_DECODE_FAILED", "BVX_NO_BACKEND", "BVX_WORKER_SPAWN_BLOCKED", "BVX_GL_UNAVAILABLE", "BVX_BAD_INPUT", "BVX_ASSET_FETCH_FAILED"];
+/** One of the {@link BVX_CODES} — the stable, minification-proof error identifier. */
+export type BvxCode = (typeof BVX_CODES)[number];
+/**
+ * The SDK's error type. Every error the SDK throws on purpose is a `BitruviusError`
+ * carrying a stable {@link BvxCode}; consumers branch on `err.code` and support triages
+ * from it. The `message` is `"<code>: <detail>"`.
+ *
+ * @remarks
+ * Prefer the {@link BitruviusError.is} type-guard over `instanceof` — it is
+ * cross-realm / duplicate-bundle safe (two SDK copies on one page can each throw a
+ * `BitruviusError` that fails the other's `instanceof`).
+ *
+ * @example
+ * ```ts
+ * import { BitruviusError } from '@bitruvius/foundation';
+ *
+ * try {
+ *   await layer.load();
+ * } catch (e) {
+ *   if (BitruviusError.is(e, 'BVX_GL_UNAVAILABLE')) showWebGl2Warning();
+ *   else throw e;
+ * }
+ * ```
+ */
+export declare class BitruviusError extends Error {
+    readonly name = "BitruviusError";
+    /** The stable {@link BvxCode} for this error — the value to branch on. */
+    readonly code: BvxCode;
+    /**
+     * @param code - The stable {@link BvxCode} for this failure.
+     * @param message - Human-readable detail; prefixed with `<code>: ` in `.message`.
+     * @param options - Standard error options; `cause` preserves the underlying error.
+     */
+    constructor(code: BvxCode, message: string, options?: {
+        cause?: unknown;
+    });
+    /**
+     * Type-guard: is `err` a {@link BitruviusError} (optionally with a specific
+     * {@link BvxCode})? Duck-types on shape (not `instanceof`), so it is safe across
+     * realms and duplicate SDK bundles.
+     *
+     * @param err - The caught value to test.
+     * @param code - When given, also require `err.code === code`.
+     * @returns `true` (narrowing `err` to {@link BitruviusError}) when `err` is a
+     *   Bitruvius error and, if `code` was passed, carries that exact code.
+     */
+    static is(err: unknown, code?: BvxCode): err is BitruviusError;
+}
+/**
+ * Wrap an unknown thrown value as a {@link BitruviusError}, preserving the cause. If
+ * `cause` is already a `BitruviusError` it is returned unchanged (the original code is
+ * kept), so re-wrapping at multiple layers never loses the first/most-specific code.
+ *
+ * @param code - The {@link BvxCode} to use when `cause` is not already a `BitruviusError`.
+ * @param message - Human-readable detail for the wrapping error.
+ * @param cause - The original thrown value, preserved as `.cause`.
+ * @returns A {@link BitruviusError} — `cause` itself when it already was one.
+ */
+export declare function asBitruviusError(code: BvxCode, message: string, cause: unknown): BitruviusError;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @bitruvius/foundation — the domain-agnostic foundation shared by every Bitruvius SDK.
+ *
+ * Pure-TS, geo-free building blocks: off-main-thread scheduling, runtime capability
+ * detection (+ the `DecodeBackend` execution model), the request-authorization seam,
+ * SDK configuration (e.g. the wasm base URL), and the shared error type. No WebGL, DOM,
+ * wasm, or geospatial concerns live here — the geospatial layer is `@bitruvius/geo-core`,
+ * which builds on this package.
+ */
+export * from './capability/detect';
+export * from './scheduling/abort-error';
+export * from './scheduling/task-queue';
+export * from './scheduling/worker-pool';
+export * from './scheduling/cdn-worker-trampoline';
+export * from './scheduling/worker-degradation';
+export * from './transport/authorizer';
+export * from './transport/fetch-asset';
+export * from './sdk-config';
+export * from './errors';

package/dist/index.js

@@ -0,0 +1 @@
+var A=new Uint8Array([0,97,115,109,1,0,0,0,1,5,1,96,0,1,123,3,2,1,0,10,10,1,8,0,65,0,253,15,253,98,11]);function L(){try{return typeof WebAssembly<"u"&&WebAssembly.validate(A)}catch{return!1}}function k(G=globalThis){return{webgl2:typeof G.WebGL2RenderingContext<"u",webgpu:!!G.navigator&&"gpu"in G.navigator&&G.navigator.gpu!=null,workers:typeof G.Worker<"u",transferable:typeof G.MessageChannel<"u",wasmSimd:L()}}function m(G){if(!G.wasmSimd)throw Error("BVC decode requires WebAssembly SIMD (the vendored wasm is built with +simd128); this runtime lacks it.");return G.workers?"cpu-wasm-workers":"cpu-wasm"}function W(G){let J=G instanceof Error?G.message:G!==void 0?String(G):"The operation was aborted",Q=Error(J);return Q.name="AbortError",Q}function p(G){return(G instanceof Error||typeof DOMException<"u"&&G instanceof DOMException)&&G.name==="AbortError"}class U{concurrency;active=0;pending=[];idleWaiters=[];constructor(G){this.concurrency=G;if(G<1)throw Error("TaskQueue concurrency must be >= 1")}get size(){return this.active+this.pending.length}run(G){return new Promise((J,Q)=>{let Z=()=>{this.active++,G().then(J,Q).finally(()=>this.afterTask())};if(this.active<this.concurrency)Z();else this.pending.push(Z)})}onIdle(){if(this.size===0)return Promise.resolve();return new Promise((G)=>this.idleWaiters.push(G))}afterTask(){this.active--;let G=this.pending.shift();if(G)G();else if(this.size===0){let J=this.idleWaiters.splice(0);for(let Q of J)Q()}}}class _{workers=[];idle=[];queue=[];inflight=new Map;byWorker=new Map;broadcasts=new Map;nextId=1;disposed=!1;spawn;targetSize;respawns=0;broken=null;warmup;onDiscard;warmPending=0;warmWaiters=[];constructor(G){if(G.size<1)throw Error("WorkerPool size must be >= 1");if(this.spawn=G.spawn,this.targetSize=G.size,G.warmup)this.warmup=G.warmup;if(G.onDiscard)this.onDiscard=G.onDiscard;for(let J=0;J<G.size;J++)this.addWorker()}addWorker(){let G=this.spawn();if(G.onmessage=($)=>this.onMessage(G,$),G.onerror=($)=>this.onError(G,$),this.workers.push(G),!this.warmup){this.idle.push(G);return}let J;try{J=this.warmup()}catch{this.replaceWorker(G);return}this.warmPending++;let Q=this.nextId++,Z={request:J.request,transfer:J.transfer??[],resolve:()=>this.noteWarm(),reject:()=>{if(this.workers.includes(G))this.replaceWorker(G);this.noteWarm()}};this.inflight.set(Q,{job:Z,worker:G}),this.byWorker.set(G,Q);try{G.postMessage({__id:Q,request:J.request},J.transfer??[])}catch($){this.inflight.delete(Q),this.byWorker.delete(G),this.rejectJob(Z,$)}}noteWarm(){if(--this.warmPending>0)return;this.warmPending=0;let G=this.warmWaiters.splice(0);for(let J of G)J()}whenWarm(){if(this.warmPending===0)return Promise.resolve();return new Promise((G)=>this.warmWaiters.push(G))}get size(){return this.queue.length+this.inflight.size}get queueLength(){return this.queue.length}get inflightCount(){return this.inflight.size}run(G,J=[],Q){if(this.disposed)return Promise.reject(Error("WorkerPool disposed"));if(this.broken)return Promise.reject(this.broken);let Z=Q?.signal;if(Z?.aborted)return Promise.reject(W(Z.reason));return new Promise(($,V)=>{let z={request:G,transfer:J,resolve:$,reject:V};if(Z)z.signal=Z,z.onAbort=()=>{let X=this.queue.indexOf(z);if(X>=0)this.queue.splice(X,1);this.rejectJob(z,W(Z.reason))},Z.addEventListener("abort",z.onAbort,{once:!0});this.queue.push(z),this.pump()})}broadcast(G,J=[]){if(this.disposed)return Promise.reject(Error("WorkerPool disposed"));if(this.broken)return Promise.reject(this.broken);return Promise.all([...this.workers].map((Q)=>new Promise((Z,$)=>{let V=this.nextId++;this.broadcasts.set(V,{worker:Q,resolve:Z,reject:$});try{Q.postMessage({__id:V,request:G},J)}catch(z){this.broadcasts.delete(V),$(z)}})))}dispose(){this.disposed=!0;for(let J of this.workers)J.terminate();let G=Error("WorkerPool disposed");for(let{job:J}of this.inflight.values())this.rejectJob(J,G);for(let J of this.queue)this.rejectJob(J,G);for(let J of this.broadcasts.values())J.reject(G);this.broadcasts.clear(),this.inflight.clear(),this.byWorker.clear(),this.queue.length=0,this.idle.length=0,this.workers.length=0}resolveJob(G,J){if(G.settled)return;G.settled=!0,this.detachAbort(G),G.resolve(J)}rejectJob(G,J){if(G.settled)return;G.settled=!0,this.detachAbort(G),G.reject(J)}detachAbort(G){if(G.signal&&G.onAbort)G.signal.removeEventListener("abort",G.onAbort)}pump(){while(this.idle.length>0&&this.queue.length>0){let G=this.idle.pop(),J=this.queue.shift(),Q=this.nextId++;this.inflight.set(Q,{job:J,worker:G}),this.byWorker.set(G,Q);try{G.postMessage({__id:Q,request:J.request},J.transfer)}catch(Z){this.inflight.delete(Q),this.byWorker.delete(G),this.idle.push(G),this.rejectJob(J,Z)}}}onMessage(G,J){let{__id:Q,result:Z,error:$}=J.data,V=this.broadcasts.get(Q);if(V){if(this.broadcasts.delete(Q),$!==void 0)V.reject(Error($));else V.resolve(Z);return}let z=this.inflight.get(Q);if(!z)return;if(this.inflight.delete(Q),this.byWorker.delete(G),this.idle.push(G),z.job.settled){if($===void 0&&this.onDiscard)this.onDiscard(Z)}else if($!==void 0)this.rejectJob(z.job,Error($));else this.resolveJob(z.job,Z);this.pump()}onError(G,J){if(!this.workers.includes(G))return;let Q=this.byWorker.get(G),Z=Q!==void 0?this.inflight.get(Q):void 0;if(Q!==void 0)this.inflight.delete(Q);let $=Error(J.message||"worker error");for(let[V,z]of this.broadcasts)if(z.worker===G)this.broadcasts.delete(V),z.reject($);if(this.replaceWorker(G),Z)this.rejectJob(Z.job,$);this.pump()}replaceWorker(G){let J=Error("worker replaced before broadcast reply");for(let[$,V]of this.broadcasts)if(V.worker===G)this.broadcasts.delete($),V.reject(J);this.byWorker.delete(G);let Q=this.idle.indexOf(G);if(Q>=0)this.idle.splice(Q,1);let Z=this.workers.indexOf(G);if(Z>=0)this.workers.splice(Z,1);try{G.terminate()}catch{}if(this.disposed||this.broken)return;if(++this.respawns>this.targetSize*3+2){this.fail(Error("WorkerPool: workers repeatedly faulted (check the worker module + wasm URL)"));return}try{this.addWorker()}catch{if(this.workers.length===0)this.fail(Error("WorkerPool: failed to spawn a replacement worker"))}}fail(G){this.broken=G;for(let J of this.queue)this.rejectJob(J,G);this.queue.length=0}}function l(G){let J=null,Q=null;return{set(Z){J=Z},has(){return J!==null},wasmUrl(){return J?.wasmUrl},source(){if(!J)return Promise.reject(Error(`${G}: no CDN runtime registered`));let{workerUrl:Z}=J;return Q??=fetch(Z).then(($)=>{if(!$.ok)throw Q=null,Error(`${G}: worker chunk fetch ${$.status} for ${Z}`);return $.text()}),Q},spawnFromSource(Z){let $=URL.createObjectURL(new Blob([Z],{type:"text/javascript"}));try{return new Worker($)}catch(V){throw Error(`${G}: blob worker construction failed — page CSP likely lacks \`worker-src blob:\`; pass \`spawn\` with a self-hosted worker script`,{cause:V})}finally{URL.revokeObjectURL($)}}}}var B=["BVX_WASM_LOAD_FAILED","BVX_DECODE_FAILED","BVX_NO_BACKEND","BVX_WORKER_SPAWN_BLOCKED","BVX_GL_UNAVAILABLE","BVX_BAD_INPUT","BVX_ASSET_FETCH_FAILED"];class H extends Error{name="BitruviusError";code;constructor(G,J,Q){super(`${G}: ${J}`,Q);this.code=G}static is(G,J){let Q=G;return G instanceof Error&&typeof Q?.code==="string"&&B.includes(Q.code)&&(J===void 0||Q.code===J)}}function n(G,J,Q){if(H.is(Q))return Q;return new H(G,J,{cause:Q})}var F=new Set;function s(){F.clear()}function t(G){let{label:J,cause:Q,fallback:Z,chunk:$,disableOption:V,onDegraded:z}=G,X=Q instanceof Error?Q.message:String(Q),Y=["serve the SDK same-origin","allow `worker-src blob:` in your CSP",...$?[`self-host \`${$}\` and pass \`spawn\``]:[],...V?[`or pass \`${V}\` to choose this path deliberately`]:[]].join(", "),K=new H("BVX_WORKER_SPAWN_BLOCKED",`${J}: worker pool unavailable — falling back to ${Z}, which is MUCH slower and runs on the render thread. ${X}. Fixes: ${Y}.`,{cause:Q});if(!F.has(J))F.add(J),console.warn(K.message);return z?.(K),K}function O(G){if(!G)return{};if(G instanceof Headers){let J={};return G.forEach((Q,Z)=>{J[Z]=Q}),J}if(Array.isArray(G))return Object.fromEntries(G);return{...G}}function P(G,J){if(!G)return J??{};if(!J)return G;let Q={...G,...J};if(G.headers||J.headers)Q.headers={...O(G.headers),...O(J.headers)};return Q}var T=new Set(["authorization","proxy-authorization","cookie","x-goog-api-key","x-api-key","x-esri-authorization"]),y=["cesium.com","googleapis.com"],I="https://relative.invalid/",E="relative.invalid";function C(G){let J;try{J=new URL(G,I)}catch{return}if(J.hostname===E)return;return{host:J.hostname.toLowerCase(),protocol:J.protocol}}function f(G,J){return J.some((Q)=>G===Q||G.endsWith(`.${Q}`))}function j(G){if(!G)return G;let J=O(G.headers),Q=Object.keys(J).filter((V)=>T.has(V.toLowerCase())),Z=G.credentials==="include";if(Q.length===0&&!Z)return G;let $={...G};if(Q.length>0){for(let V of Q)delete J[V];$.headers=J}if(Z)$.credentials="same-origin";return $}function N(G,J={}){let Q=j(G);if(Q===G)return{fetch:(z,X)=>globalThis.fetch(z,P(G,X))};let Z;if(J.credentialOrigin!==void 0){if(Z=C(J.credentialOrigin),Z===void 0||Z.host==="")throw Error(`publicAuthorizer: credentialOrigin must be an absolute URL naming the origin the credential was minted for (e.g. "https://tiles.example.com/tileset.json"); received ${JSON.stringify(J.credentialOrigin)}.`)}let $=[...y,...J.trustedHosts??[]].map((z)=>z.toLowerCase()),V=new Set;return{fetch(z,X){let Y=C(z);if(Y===void 0)return globalThis.fetch(z,P(G,X));let{host:K,protocol:M}=Y;if(Z===void 0&&K!=="")Z=Y;let R=M==="https:"||M===Z?.protocol,x=K!==""&&(K===Z?.host||f(K,$));if(x&&R)return globalThis.fetch(z,P(G,X));if(!V.has(K)){V.add(K);let S=x?`${M}//${K} is a cleartext url, so the request was sent without this session's credential. A header sent over http is readable by anything on the path; serve it over https.`:K===""?`a ${M} url names no host, so the request was sent without this session's credential.`:`${K} is not the origin this session's credential was issued for (${Z?.host??"unknown"}), so the request was sent without it. If you own that host, pass it on the layer: auth: publicAuthorizer(requestInit, { trustedHosts: ['${K}'] }).`;console.warn(`[bitruvius] ${S}`)}return globalThis.fetch(z,P(Q,X))}}}var v=/^\s*(?:text\/|application\/(?:json|xml|xhtml\+xml)\b)/i,g=[[60,33],[60,104],[60,63]];async function GG(G,J={}){let{label:Q,...Z}=J,$=Q?`${Q}: `:"",V=await fetch(G,Z);if(!V.ok)throw new H("BVX_ASSET_FETCH_FAILED",`${$}${G} returned HTTP ${V.status}${V.statusText?` ${V.statusText}`:""} — expected a binary asset.`);let z=V.headers.get("content-type")??"";if(v.test(z))throw new H("BVX_ASSET_FETCH_FAILED",`${$}${G} served "${z.split(";")[0].trim()}", not a binary asset — the file is probably `+"missing and the server returned a fallback page. Check the URL and that the asset is deployed.");let X=new Uint8Array(await V.arrayBuffer());if(!z&&g.some(([Y,K])=>X[0]===Y&&X[1]===K))throw new H("BVX_ASSET_FETCH_FAILED",`${$}${G} returned a markup document, not a binary asset — the file is probably missing and the `+"server returned a fallback page. Check the URL and that the asset is deployed.");return X}var q="__BITRUVIUS_CONFIG__";function ZG(G){let J=globalThis;J[q]={...J[q],...G}}function D(){return globalThis[q]??{}}function $G(G,J,Q){if(G)return G;let Z=D().esriAuth;if(Z)return Z;return N(J,Q)}function VG(G){let J=D().wasmBaseUrl;if(J===void 0)return;return new URL(G,J instanceof URL?J:new URL(J,globalThis.location?.href))}export{$G as resolveAuth,t as reportWorkerDegradation,m as recommendDecodeBackend,N as publicAuthorizer,P as mergeInit,L as isWasmSimdSupported,p as isAbortError,D as getConfig,GG as fetchBinaryAsset,k as detectCapabilities,l as createCdnWorkerTrampoline,VG as configuredWasmUrl,ZG as configure,n as asBitruviusError,W as abortError,s as __resetWorkerDegradationLog,_ as WorkerPool,U as TaskQueue,y as DEFAULT_TRUSTED_CREDENTIAL_HOSTS,H as BitruviusError,B as BVX_CODES};

package/dist/scheduling/abort-error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The WHATWG abort convention without `DOMException` (not constructible in
+ * every worker/test realm): an `Error` whose `name` is `'AbortError'`.
+ * Consumers that dispatch on cancellation (MapLibre's `isAbortError`, our
+ * loaders) check exactly that name.
+ */
+/**
+ * Build an abort rejection.
+ *
+ * @param reason - Optional `AbortSignal.reason` to carry in the message.
+ * @returns An `Error` named `'AbortError'`.
+ */
+export declare function abortError(reason?: unknown): Error;
+/**
+ * Whether a rejection is a cancellation (ours or a native fetch abort).
+ *
+ * @param err - The caught value.
+ * @returns `true` for any `Error`/`DOMException` named `'AbortError'`.
+ */
+export declare function isAbortError(err: unknown): boolean;

package/dist/scheduling/cdn-worker-trampoline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The cross-origin Web Worker **blob trampoline** — one mechanism, instantiated once per
+ * published worker chunk.
+ *
+ * `new Worker(crossOriginUrl, { type: 'module' })` throws a SYNCHRONOUS `SecurityError`
+ * in the constructor: worker scripts must be same-origin (or `blob:`/`data:`). The check
+ * runs BEFORE any network request, so publishing the missing chunk cannot fix it — a page
+ * that loads the SDK from a CDN simply cannot spawn the SDK's worker chunks directly.
+ *
+ * The fix: fetch the published, self-contained worker chunk's TEXT (a plain CORS GET the
+ * CDN serves happily) and spawn it from a same-origin `blob:` URL, which inherits the
+ * page's origin. Blob workers can't resolve relative imports (`blob:https://host/uuid` is
+ * not hierarchical, so every specifier fails), so the published chunk must be a fully
+ * self-contained CLASSIC script — see the `*-decode-worker.iife.min.js` steps in
+ * `scripts/build-cdn.ts`. Codec wasm is resolved on the MAIN thread and forwarded by URL
+ * or bytes, never resolved by the worker against its blob base.
+ *
+ * `set()` is called by the generated CDN bundle entry at module init. npm/bundler
+ * consumers never register anything, so `has()` stays false and their decoder keeps
+ * spawning the same-origin module worker their bundler emitted — same-origin behaviour is
+ * unchanged by construction.
+ *
+ * CSP note: blob workers need `worker-src blob:`. Locked-down consumers host the published
+ * chunk themselves and pass `spawn: () => new Worker('/their/path.js')`.
+ */
+/** What the CDN bundle entry registers for one published worker chunk. */
+export interface CdnWorkerRuntime {
+    /** Absolute URL of this build's published, self-contained classic worker chunk. */
+    readonly workerUrl: string;
+    /**
+     * Absolute URL of the codec wasm this worker needs, when the worker's own package-relative
+     * resolution can't survive a blob base (wasm-bindgen glue resolves its `_bg.wasm` against
+     * `import.meta.url`). Resolved at BUILD time against the published tree, so the decoder can
+     * forward it on the main thread. Omit for workers handed their wasm URL another way.
+     */
+    readonly wasmUrl?: string;
+}
+/** One published worker chunk's trampoline. Created once per chunk at module scope. */
+export interface CdnWorkerTrampoline {
+    /** @internal Register this build's chunk — called by the generated CDN bundle entry. */
+    set(rt: CdnWorkerRuntime): void;
+    /** True once a CDN bundle registered a chunk (i.e. take the blob path, not `new Worker(url)`). */
+    has(): boolean;
+    /** The registered wasm URL, if the build published one. */
+    wasmUrl(): string | undefined;
+    /** Fetch (once, cached across the whole pool) the chunk's source text. */
+    source(): Promise<string>;
+    /** Spawn a classic worker from already-fetched source via a same-origin Blob URL. */
+    spawnFromSource(source: string): Worker;
+}
+/**
+ * Create the trampoline for one published worker chunk.
+ *
+ * @param label - Package/worker name used in error messages (e.g. `'tiles3d-mesh'`).
+ * @returns The per-chunk trampoline; keep it at module scope so the source fetch is
+ * shared by every worker in the pool.
+ */
+export declare function createCdnWorkerTrampoline(label: string): CdnWorkerTrampoline;

package/dist/scheduling/fixtures/echo.worker.d.ts

@@ -0,0 +1,5 @@
+/** Test-only worker: doubles numbers, echoes a transferred buffer, or errors. */
+declare const ctx: {
+    onmessage: ((e: MessageEvent) => void) | null;
+    postMessage: (msg: unknown, transfer?: Transferable[]) => void;
+};

package/dist/scheduling/task-queue.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A minimal concurrency-limited async task runner. Used to bound how many
+ * decode/work jobs run at once (e.g. the worker-pool fan-out), without
+ * pulling in a dependency. Pure — no DOM/worker deps.
+ *
+ * @internal
+ */
+export declare class TaskQueue {
+    private readonly concurrency;
+    private active;
+    private readonly pending;
+    private readonly idleWaiters;
+    constructor(concurrency: number);
+    /** Total tasks not yet settled (queued + running). */
+    get size(): number;
+    /** Queue `fn`; resolves/rejects with its result once it has run. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Resolves when there are no queued or running tasks. */
+    onIdle(): Promise<void>;
+    private afterTask;
+}

package/dist/scheduling/worker-degradation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One-time, LOUD reporting of a worker-pool degradation.
+ *
+ * When a decode worker pool cannot be spawned, every decoder in the SDK can still decode
+ * on the calling thread — so the picture the consumer sees is a layer that renders, just
+ * far slower, or (worse) a layer that silently renders nothing while `console.warn` scrolls
+ * eight lines past. Both failure modes were shipping: a cross-origin CDN page got an empty
+ * mesh layer with no catchable error, and Esri terrain rendered a perfectly flat planet
+ * with no output at all.
+ *
+ * This helper is the single place that decides what a degradation says. It:
+ *  - builds a `BitruviusError('BVX_WORKER_SPAWN_BLOCKED')` the caller memoises, so the
+ *    pool is attempted ONCE rather than re-thrown per tile (the spawn storm);
+ *  - warns exactly once per label, naming the real cost and every escape hatch;
+ *  - hands the error to the layer's `onError` so a consumer can react in code.
+ */
+import { BitruviusError } from '../errors';
+/** How one worker path degrades; see {@link reportWorkerDegradation}. */
+export interface WorkerDegradationReport {
+    /** Package/worker name, used as the log prefix and the once-per-label key. */
+    readonly label: string;
+    /** The underlying failure (usually a `SecurityError` from the `Worker` constructor). */
+    readonly cause: unknown;
+    /** What the SDK does instead — e.g. `'main-thread decode'`. */
+    readonly fallback: string;
+    /** Published chunk filename for the self-host escape hatch, when there is one. */
+    readonly chunk?: string;
+    /** Layer/decoder option that selects the fallback deliberately, e.g. `'workers: false'`. */
+    readonly disableOption?: string;
+    /** Layer `onError` (or any consumer sink) — always called, even after the log is deduped. */
+    readonly onDegraded?: (err: BitruviusError) => void;
+}
+/**
+ * Reset the once-per-label log dedupe.
+ *
+ * @remarks Test seam only — production code never un-warns.
+ * @internal
+ */
+export declare function __resetWorkerDegradationLog(): void;
+/**
+ * Build (and, once per label, log) the error describing a worker-pool degradation.
+ *
+ * @param report - What degraded and how; see {@link WorkerDegradationReport}.
+ * @returns The `BitruviusError` to memoise on the decoder — its presence is what stops
+ * the caller re-attempting the spawn on every subsequent decode.
+ */
+export declare function reportWorkerDegradation(report: WorkerDegradationReport): BitruviusError;

package/dist/scheduling/worker-pool.d.ts

@@ -0,0 +1,97 @@
+/** Options for {@link WorkerPool}. @internal */
+export interface WorkerPoolOptions<TReq = unknown> {
+    /** Number of workers to spawn. */
+    size: number;
+    /** Create a fresh module worker. */
+    spawn: () => Worker;
+    /**
+     * Optional init request posted to EACH worker (including self-heal
+     * replacements) before it accepts jobs — e.g. wasm instantiation, so the
+     * first real task doesn't pay the compile. The worker must ack through the
+     * normal reply protocol; an error reply pulls the worker via the budgeted
+     * respawn path (a broken wasm URL fails the pool loudly, not silently).
+     * Called once per worker, so per-worker payloads (cloned bytes) are safe.
+     */
+    warmup?: () => {
+        request: TReq;
+        transfer?: Transferable[];
+    };
+    /**
+     * Called with a result whose task was abandoned (aborted in flight, so the
+     * worker's late reply has no consumer) — release resources the reply carries
+     * (e.g. `ImageBitmap.close()`) instead of waiting on GC.
+     */
+    onDiscard?: (result: unknown) => void;
+}
+/** Per-call options for {@link WorkerPool.run}. @internal */
+export interface WorkerPoolRunOptions {
+    /** Abort the task: queued → dropped before dispatch; in-flight → caller
+     *  rejected now, late worker reply discarded. Rejections carry
+     *  `name === 'AbortError'`. */
+    readonly signal?: AbortSignal;
+}
+/** @internal */
+export declare class WorkerPool<TReq = unknown, TRes = unknown> {
+    private readonly workers;
+    private readonly idle;
+    private readonly queue;
+    private readonly inflight;
+    private readonly byWorker;
+    private readonly broadcasts;
+    private nextId;
+    private disposed;
+    private readonly spawn;
+    private readonly targetSize;
+    private respawns;
+    private broken;
+    private readonly warmup?;
+    private readonly onDiscard?;
+    private warmPending;
+    private readonly warmWaiters;
+    constructor(opts: WorkerPoolOptions<TReq>);
+    private addWorker;
+    private noteWarm;
+    /**
+     * Resolves once every currently-spawned worker has acked its warm-up (or the
+     * pool gave up on it). Immediately resolved when no `warmup` option is set.
+     */
+    whenWarm(): Promise<void>;
+    /** Queued + in-flight task count. */
+    get size(): number;
+    /** Tasks waiting for a worker (not yet dispatched). */
+    get queueLength(): number;
+    /** Tasks currently running on a worker (abandoned-but-running included). */
+    get inflightCount(): number;
+    /**
+     * Run one task; resolves with the worker's `result` (or rejects on error /
+     * abort — see {@link WorkerPoolRunOptions}).
+     */
+    run(request: TReq, transfer?: Transferable[], opts?: WorkerPoolRunOptions): Promise<TRes>;
+    /**
+     * Send one request to EVERY worker (busy or idle) and resolve with one
+     * result per worker (rejects if any worker errors or faults). Replies are
+     * correlated by the same `__id` wire mechanism as {@link run}, but
+     * broadcast replies never touch the idle/dispatch state — a broadcast
+     * coexists with the normal queue (workers drain messages in order).
+     *
+     * NOTE on `transfer`: a Transferable is detached by the FIRST post, so a
+     * transfer list is only safe with a single-worker pool. SharedArrayBuffers
+     * don't need (and can't be in) a transfer list — they share zero-copy.
+     */
+    broadcast(request: TReq, transfer?: Transferable[]): Promise<TRes[]>;
+    /** Terminate all workers and reject any outstanding work. */
+    dispose(): void;
+    /** Settle helpers: at-most-once + abort-listener hygiene. */
+    private resolveJob;
+    private rejectJob;
+    private detachAbort;
+    private pump;
+    private onMessage;
+    private onError;
+    /** Remove a faulted worker from rotation, terminate it, and (within a respawn
+     *  budget) spawn a fresh replacement. If workers keep faulting — a broken worker
+     *  module/wasm URL — fail the pool loudly instead of spinning or hanging. */
+    private replaceWorker;
+    /** Mark the pool broken and reject all queued (and future) work. */
+    private fail;
+}

package/dist/sdk-config.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Global SDK configuration — one call wires wasm asset resolution (and a shared
+ * ESRI sign-in) for every codec, instead of passing wasm options per decoder.
+ *
+ * @remarks
+ * The configuration store lives on `globalThis` under a namespaced key, so
+ * independently loaded copies of the SDK (e.g. two per-package CDN bundles on one
+ * page) share ONE configuration.
+ *
+ * **wasm asset precedence (applies to every codec's `ensureWasm`, documented once
+ * here).** When a decoder needs its `.wasm`, it resolves the bytes/URL in this order,
+ * highest first:
+ *   1. an explicit `wasmBytes` (raw `Uint8Array`) or `wasmUrl` passed to that decoder;
+ *   2. {@link configure}`({ wasmBaseUrl })` joined with the codec's wasm filename
+ *      (see `configuredWasmUrl`);
+ *   3. the build's default (a bundler-resolved sibling file on npm; a baked,
+ *      content-hashed URL in CDN bundles).
+ *
+ * @see {@link configure} to set it, {@link getConfig} to read it,
+ *      `configuredWasmUrl` for the per-codec wasm URL resolution.
+ */
+import { type PublicAuthorizerOptions, type RequestAuthorizer } from './transport/authorizer';
+/**
+ * Global configuration shape merged by {@link configure} and read by
+ * {@link getConfig}. Every field is optional; an unset field falls through to the
+ * documented per-decoder / build default.
+ */
+export interface BitruviusConfig {
+    /**
+     * Base URL the codec `.wasm` files are served from. Resolved per codec as
+     * `new URL(<wasmFileName>, wasmBaseUrl)` (see `configuredWasmUrl`) — include a
+     * trailing slash. This is step 2 of the wasm precedence documented on
+     * {@link BitruviusConfig}; an explicit per-decoder `wasmUrl`/`wasmBytes` overrides it.
+     */
+    readonly wasmBaseUrl?: string | URL;
+    /**
+     * Default request authorizer applied to every ESRI/ArcGIS layer fetch that does
+     * not set its own `auth`. Wired by `configureEsriAuth()` in `@bitruvius/esri-auth`,
+     * which calls `configure({ esriAuth })` here so one sign-in is shared across all
+     * layers (and across independently loaded per-package CDN bundles). Layers consume
+     * it via {@link resolveAuth}; absent ⇒ public-first unauthenticated fetches.
+     */
+    readonly esriAuth?: RequestAuthorizer;
+}
+/**
+ * Set (merge) the global SDK configuration. This is the first call most
+ * applications make: it wires wasm asset resolution (and, via `@bitruvius/esri-auth`,
+ * a shared sign-in) for every codec/layer at once.
+ *
+ * @remarks
+ * Each call MERGES field-wise over the previous configuration — later calls override
+ * only the fields they set. The store is shared across independently loaded SDK
+ * bundles on one page (see {@link BitruviusConfig}).
+ *
+ * @param config - The fields to set/override. See {@link BitruviusConfig}.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@bitruvius/foundation';
+ *
+ * // Serve every codec's .wasm from one CDN folder (note the trailing slash).
+ * configure({ wasmBaseUrl: 'https://my.app/assets/bitruvius/' });
+ * ```
+ *
+ * @see {@link getConfig}, `configuredWasmUrl`, {@link BitruviusConfig.wasmBaseUrl}
+ */
+export declare function configure(config: BitruviusConfig): void;
+/**
+ * Read the current global SDK configuration set by {@link configure}.
+ *
+ * @returns The merged {@link BitruviusConfig}; an empty object when {@link configure}
+ *   has never been called.
+ */
+export declare function getConfig(): BitruviusConfig;
+/**
+ * Resolve the {@link RequestAuthorizer} a layer fetch should use. Always returns a
+ * usable authorizer, so every call site has ONE code path.
+ *
+ * @remarks
+ * Precedence, highest first:
+ *   1. the layer's own `auth` option (`perLayer`);
+ *   2. the global {@link configure}`({ esriAuth })` session;
+ *   3. a no-op {@link publicAuthorizer} wrapping the layer's static `staticInit`.
+ *
+ * `auth` (per-layer or global) and `requestInit` are alternatives: when a real
+ * authorizer is present it owns header attachment, so `staticInit` is applied ONLY by
+ * the public fallback.
+ *
+ * @param perLayer - The layer's own authorizer, if any.
+ * @param staticInit - Static `RequestInit` (headers etc.) the layer supplied; used
+ *   only by the public-fallback path.
+ * @returns A {@link RequestAuthorizer} that is always safe to call.
+ * @see {@link BitruviusConfig.esriAuth}, {@link publicAuthorizer}
+ */
+export declare function resolveAuth(perLayer?: RequestAuthorizer, staticInit?: RequestInit, options?: PublicAuthorizerOptions): RequestAuthorizer;
+/**
+ * Resolve a codec's wasm filename against the {@link configure}`({ wasmBaseUrl })`
+ * base URL — step 2 of the wasm precedence documented on {@link BitruviusConfig}.
+ * Used by every codec's `ensureWasm`.
+ *
+ * @remarks
+ * Resolved as `new URL(wasmFileName, wasmBaseUrl)`, so `wasmBaseUrl` should end with a
+ * trailing slash. A string base is itself resolved against `location.href` first (so a
+ * relative base works in the browser).
+ *
+ * @param wasmFileName - The codec's bare wasm filename (e.g. `'bvc_wasm_bg.wasm'`).
+ * @returns The absolute wasm {@link URL}, or `undefined` when no `wasmBaseUrl` is
+ *   configured (the caller then falls through to the build default).
+ * @see {@link configure}, {@link BitruviusConfig.wasmBaseUrl}
+ */
+export declare function configuredWasmUrl(wasmFileName: string): URL | undefined;

package/dist/transport/authorizer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Transport authorization seam — a drop-in replacement for the global `fetch`,
+ * scoped to one streaming session.
+ *
+ * Every streaming engine (3D-Tiles, I3S, elevation) routes its network requests
+ * through a {@link RequestAuthorizer.fetch}. The default {@link publicAuthorizer}
+ * adds nothing and never retries, so a public URL does EXACTLY ONE unauthenticated
+ * request — byte-identical to the pre-auth behavior, no perf regression. A real
+ * implementation (e.g. the ESRI identity manager in `@bitruvius/esri-auth`)
+ * attaches per-host auth (a header or a `?token=` query param) and transparently
+ * refreshes + retries ONCE on an auth challenge.
+ *
+ * Why a `fetch`-override and not an `authorize()`/`onChallenge()` pair:
+ *  - every call site already calls `fetch`, so this is a literal drop-in; and
+ *  - only the override holds the `Response`, so it can detect ArcGIS's `f=json`
+ *    challenge — HTTP **200** with a body of `{ error: { code: 498 | 499 } }` —
+ *    which binary endpoints instead signal as HTTP 401/403/498/499.
+ */
+/**
+ * A drop-in replacement for the global `fetch`, scoped to one streaming session. Pass a
+ * custom implementation as a layer's `auth` option (or globally via
+ * {@link configure}`({ esriAuth })`) to attach per-host credentials and transparently
+ * refresh + retry on an auth challenge; the default is {@link publicAuthorizer}.
+ *
+ * @example
+ * ```ts
+ * const auth: RequestAuthorizer = {
+ *   async fetch(url, init) {
+ *     const token = await getToken();
+ *     return fetch(url, mergeInit(init, { headers: { Authorization: `Bearer ${token}` } }));
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link publicAuthorizer}, {@link resolveAuth}, {@link BitruviusConfig.esriAuth}
+ */
+export interface RequestAuthorizer {
+    /**
+     * Issue an authorized request and resolve the FINAL {@link Response} (after any
+     * internal token acquisition / refresh + single retry).
+     * @param input - The request URL.
+     * @param init - Standard `RequestInit`. If `init.signal` is present (the streaming
+     *   engines pass the tile's abort + a hard timeout) it MUST be honored.
+     * @returns The final `Response`.
+     */
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Merge two `RequestInit`s into one — useful when writing a {@link RequestAuthorizer}
+ * that layers credentials over the caller's init.
+ * @param a - The base init (lower precedence).
+ * @param b - The override init (wins on top-level conflicts; its headers win field-wise).
+ * @returns A new merged `RequestInit` (`headers` combined field-wise). Either side may
+ *   be `undefined`.
+ */
+export declare function mergeInit(a?: RequestInit, b?: RequestInit): RequestInit;
+/**
+ * Hosts that receive a session credential without the caller naming them: the service
+ * domains whose credentials this SDK mints (Cesium ion, Google Map Tiles). Anything
+ * else — a customer's own tile server, a sibling CDN — is trusted only because it IS
+ * the origin the credential was minted for, or because the caller listed it in
+ * {@link PublicAuthorizerOptions.trustedHosts}.
+ */
+export declare const DEFAULT_TRUSTED_CREDENTIAL_HOSTS: readonly string[];
+/** Options for {@link publicAuthorizer}'s credential trust boundary. */
+export interface PublicAuthorizerOptions {
+    /**
+     * Absolute URL (or origin) the credential in `staticInit` was minted for — normally
+     * the tileset document's own URL. Requests to any other host are sent WITHOUT the
+     * credential. Omit and the credential pins to the host of the first request instead;
+     * naming it is strictly better, because the first request's host comes from a url the
+     * third-party tileset chose, so the fallback anchor is attacker-influenced.
+     *
+     * Must name a host: `file:///…` and `data:` URLs are rejected rather than accepted as
+     * an anchor that matches nothing.
+     */
+    readonly credentialOrigin?: string;
+    /**
+     * Extra hosts allowed to receive the credential — the legitimate case of content URLs
+     * on a sibling CDN host of the same service. Matched on a dot boundary, so
+     * `acme.com` covers `cdn.acme.com` but never `notacme.com`.
+     */
+    readonly trustedHosts?: readonly string[];
+}
+/**
+ * The default no-op / public {@link RequestAuthorizer}: merges `staticInit` UNDER each
+ * call's init and delegates to the global `fetch`. A public URL does EXACTLY ONE
+ * unauthenticated request with no retry — byte-identical to plain `fetch`.
+ *
+ * @remarks
+ * When `staticInit` carries a credential (see {@link CREDENTIAL_HEADERS} —
+ * a Cesium ion `Bearer`, a Google `X-Goog-Api-Key`, cookies) that credential is sent
+ * ONLY to the origin it was minted for, plus {@link DEFAULT_TRUSTED_CREDENTIAL_HOSTS}
+ * and any {@link PublicAuthorizerOptions.trustedHosts}. Every other host gets the
+ * request without it, and is warned about once.
+ *
+ * A tileset is a document fetched from a third party that lists further URLs, and the
+ * streaming engines fetch every URL it names through this authorizer. Without the
+ * boundary, a tileset that names `https://attacker.example/tile.glb` harvests the ion
+ * token or the API key — both reusable, both billable to the user — delivered by our own
+ * transport, with the response body proving to the attacker that the credential works.
+ * A credential minted for host A does not become valid for host B because A's JSON said
+ * so, so a cross-origin URL is fetched public instead of authenticated: the tile fails
+ * to load, which is recoverable, rather than the key leaking, which is not.
+ *
+ * @param staticInit - Optional static `RequestInit` (e.g. headers) applied beneath each
+ *   request's own init.
+ * @param options - Credential trust boundary; see {@link PublicAuthorizerOptions}. Ignored
+ *   when `staticInit` carries no credential.
+ * @returns A {@link RequestAuthorizer} backed by the global `fetch`.
+ * @throws Error when `options.credentialOrigin` is not a parseable absolute URL.
+ * @see {@link resolveAuth}
+ */
+export declare function publicAuthorizer(staticInit?: RequestInit, options?: PublicAuthorizerOptions): RequestAuthorizer;

package/dist/transport/fetch-asset.d.ts

@@ -0,0 +1,39 @@
+/** Options for {@link fetchBinaryAsset}. */
+export interface FetchBinaryAssetOptions extends RequestInit {
+    /**
+     * Label for the thing being fetched, used in the error message (e.g. the
+     * layer or codec name). Defaults to no prefix.
+     */
+    readonly label?: string;
+}
+/**
+ * Fetch `url` and return its bytes, rejecting anything that is plainly not a
+ * binary asset.
+ *
+ * @remarks
+ * Codecs identify their input by a magic number, so when a URL 404s to an HTML
+ * fallback the decoder reports a *bad magic number* — for HTML it was never
+ * meant to read. That error names the codec, not the missing file, and reliably
+ * sends the reader off to debug a decoder that is working correctly. (A real
+ * example: `BadMagic { found: 1868833084 }` — which is the ASCII `<!do` of
+ * `<!doctype html>`.)
+ *
+ * This checks the response status, then the content type, then sniffs the
+ * leading bytes when the server sent no usable type — so the failure names the
+ * URL and what came back instead.
+ *
+ * @param url - The asset URL.
+ * @param opts - Standard `RequestInit` (pass `signal` to make it abortable), plus an optional `label`.
+ * @returns The response body as bytes.
+ * @throws BitruviusError `BVX_ASSET_FETCH_FAILED` when the response is an HTTP
+ * error, or is textual rather than binary.
+ *
+ * @example
+ * ```ts
+ * import { fetchBinaryAsset } from '@bitruvius/foundation';
+ *
+ * const bytes = await fetchBinaryAsset('/assets/scene.bvc', { signal, label: 'BvcMapLibreLayer' });
+ * const model = await decoder.open(bytes);
+ * ```
+ */
+export declare function fetchBinaryAsset(url: string, opts?: FetchBinaryAssetOptions): Promise<Uint8Array>;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bitruvius/foundation",
+  "version": "0.3.0",
+  "description": "Bitruvius SDK foundation: the domain-agnostic, geo-free base every Bitruvius SDK builds on (task/worker scheduling, runtime capability detection, request authorization, SDK config, and error types).",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "bugs": {
+    "url": "https://github.com/bitruvius/support"
+  },
+  "homepage": "https://dev.bitruvius.com/sdks/js/",
+  "keywords": [
+    "bitruvius",
+    "sdk",
+    "foundation",
+    "scheduling",
+    "worker-pool"
+  ],
+  "sideEffects": [
+    "./src/index.ts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --format esm --target browser --minify && tsc --emitDeclarationOnly",
+    "test": "bun test"
+  }
+}