@bitruvius/geo-core 0.3.1

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,133 @@
+<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/geo-core
+
+**The contracts and geospatial math every Bitruvius package shares, in pure TypeScript with no GPU, wasm or DOM.**
+
+> **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
+
+The SDK is assembled from packages that must not know about each other. A codec must not
+depend on a streaming engine. An engine must not depend on a codec. A renderer must not
+depend on a viewer. Each of those boundaries is an interface, and an interface has to live
+somewhere both sides can import it from without importing each other. That is this package.
+
+The seams are real, not theoretical:
+
+- `@bitruvius/turbo-lepcc` and `@bitruvius/bvc` both implement `I3sPointCloudDecoder`.
+  The `@bitruvius/i3s` engine imports the interface and never a codec, so you swap LEPCC for
+  BVC without touching streaming or rendering.
+- `@bitruvius/draco`, `@bitruvius/meshopt` and `@bitruvius/ktx2` implement
+  `DracoGeometryDecoder`, `MeshoptDecoder` and `Ktx2Transcoder`. They are injected into
+  `@bitruvius/gltf`, which is why a codec package depends on geo-core and never on the parser.
+- The renderers (`splats`, `ptcloud`, `mesh`, `point-symbols`, `raster`) are driven entirely
+  through `ViewerAdapter` and `FrameState`. They do not know MapLibre exists. A new host is
+  one adapter file, not a renderer fork.
+
+The second reason is purity. Nothing here touches WebGL, wasm or the DOM, so the same code
+runs on the main thread, inside a decode worker, and under `bun test` with no browser. That
+is a requirement, not a preference: the worker packs a tile into the shared ENU grid, the
+shader expands it back, and the tests prove the two agree. Both sides have to be reading
+the same arithmetic from the same file.
+
+Twenty other packages in this repository depend on geo-core. It depends on one thing,
+[`@bitruvius/foundation`](https://www.npmjs.com/package/@bitruvius/foundation).
+
+## What is in it
+
+**Contracts.** `Decoder` and `DecoderFactory`, `Renderer` and `TileHandle`, `ViewerAdapter`
+and `FrameState`, plus the per-format decode seams: `GltfSplatDecoder`,
+`I3sPointCloudDecoder`, `I3sMeshDecoder`, `CesiumPointDecoder`, `MeshTileDecoder`.
+
+**The decoded model.** `DecodedSplatTile`, `DecodedPointTile` and `ContainerMeta` carry
+quantized structure-of-arrays straight out of the decoder, because dequantization is
+deferred to the render shaders. `PackedPointTile` and `PackedMeshTile` are the ENU-rebased,
+GPU-ready forms the renderers upload. No floating-point geometry crosses this boundary.
+
+**Geospatial math.** WGS84 geodetic to ECEF and back (Bowring closed form), ECEF to ENU,
+and Web Mercator implemented from the public definition to match MapLibre's
+`MercatorCoordinate` exactly, so this math is interchangeable with the viewer's own.
+Column-major `mat4`/`mat3` and planes for frustum culling and clipping.
+
+**Measurement.** What the SDK's measure tools are built on: slope and horizontal
+distance, bearing, polyline length, polygon area and perimeter, the sampling grid behind
+cut-and-fill volume, and contour extraction. These solve in the ENU tangent plane at the
+feature being measured rather than on the ellipsoid, which is exact at city scale and
+starts to drift past roughly 50 km; `haversineDistance` on the mean sphere is the
+long-range cross-check and the axis measure for elevation profiles.
+
+**Packing.** `packPointTileEnu`, `packI3sPointsEnu`, `packGltfPointsEnu` and `packMeshEnu`
+rebase a decoded tile into the shared ENU meters frame and requantize it onto the
+renderer's integer grid, so coordinates stay f32-exact however far the dataset sits from
+the scene anchor. `extractHardEdges` derives the lines a person would draw if asked to
+sketch a building, since no I3S or 3D Tiles service ships edge geometry.
+
+**Placement.** `ModelPlacement` is the vocabulary the single-model layers expose: `upAxis`
+preset, `heading`/`pitch`/`roll` in degrees, `scale`, `anchorPoint`. `placementBasis` and
+`modelPlacementMatrix` compose the correct basis, including the mercator Y-flip that users
+must never see. `QuantBoundsAccumulator` derives source-space bounds from streamed
+quantized tiles, with robust percentiles, because splat captures arrive wrapped in a halo
+of far-field background outliers that would otherwise hold the bounding box hostage.
+
+**Style and metadata.** `compileSqlFilter` (Esri Building Scene Layer `filterExpression`)
+and `compileStyleExpression` (3D Tiles declarative styling) compile to one AST and one
+closure, evaluated per feature against a `PropertyGetter`. Hand-written tokenizer and
+recursive-descent parser, no `eval`. I3S attributes, 3D Tiles batch tables and glTF
+`EXT_structural_metadata` property tables all normalize into the same feature columns.
+
+**Dequant reference.** The canonical inverse-quantization formulas. The GLSL shaders port
+these functions, and this module is the parity oracle they are tested against.
+
+Because geo-core re-exports `@bitruvius/foundation`, importing it also gives you the
+domain-agnostic base: `TaskQueue`, `WorkerPool`, `detectCapabilities`,
+`recommendDecodeBackend`, SDK config and `BitruviusError`.
+
+```ts
+import { placementMatrix, toFloat32 } from '@bitruvius/geo-core';
+
+const model = placementMatrix({ lng: -73.99, lat: 40.75, altitude: 0 });
+gl.uniformMatrix4fv(uModel, false, toFloat32(model));
+```
+
+## Should you depend on it directly
+
+Usually not. Install [`@bitruvius/sdk-maplibre`](https://www.npmjs.com/package/@bitruvius/sdk-maplibre)
+and you get this package as a transitive dependency.
+
+Depend on it directly when you are implementing one of its seams: a decoder for your own
+container format that an SDK engine should stream, or a `ViewerAdapter` for a host the SDK
+does not ship. Those are the cases where you want the interface and nothing else.
+
+It is published for that purpose, not as a general-purpose geospatial math library. The API
+tracks what the SDK needs and moves with SDK releases.
+
+```sh
+npm i @bitruvius/geo-core
+```
+
+## Trademarks
+
+Esri, ArcGIS, I3S and LEPCC are trademarks of Environmental Systems Research Institute, Inc.
+Cesium and 3D Tiles are trademarks of Cesium GS, Inc. Khronos, glTF and KTX are trademarks
+of The Khronos Group Inc. Google and Draco are trademarks of Google LLC. Niantic and SPZ are
+trademarks of Niantic, Inc. 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
+
+Proprietary. The full terms ship as `LICENSE` inside this package, and are readable
+before installing at [cdn.bitruvius.com/legal/sdk-license-v1.txt](https://cdn.bitruvius.com/legal/sdk-license-v1.txt).
+
+© Bitruvius, Inc.

package/dist/contracts/cesium-point-decoder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `CesiumPointDecoder` — the loose-coupling seam for OGC 3D-Tiles **point cloud**
+ * (`.pnts` / glTF-1.1 POINTS) streaming, the Cesium analog of `I3sPointCloudDecoder`.
+ * It decodes one tile buffer into a GPU-ready, ENU-rebased `PackedPointTile`
+ * (the same shape the `@bitruvius/ptcloud` renderer already consumes), regardless
+ * of whether the geometry is uncompressed or Draco-compressed.
+ *
+ * The engine and the MapLibre layer depend ONLY on this interface — never on a
+ * concrete codec — so the uncompressed reader and the Draco-seam variant are
+ * interchangeable.
+ */
+import type { Mat4 } from '../geo/mat4';
+import type { PackedPointTile } from '../geo/pack-point-enu';
+export interface CesiumPointDecodeContext {
+    /** ECEF → shared-scene ENU (meters), column-major 4×4. */
+    readonly enuFromEcef: Mat4;
+    /** Cumulative tile transform: tile-local → ECEF. */
+    readonly tileTransformEcef: Mat4;
+    /** Requantization step (meters) for the i32 position grid. */
+    readonly grid: number;
+}
+/** Decodes one OGC 3D-Tiles point-cloud tile (`.pnts` / glTF-1.1 POINTS) into a
+ *  GPU-ready, ENU-rebased `PackedPointTile`. */
+export interface CesiumPointDecoder {
+    /** @param buffer - The tile bytes (`.pnts` or `.glb`).
+     *  @param ctx - Georeference + requantize context (`CesiumPointDecodeContext`).
+     *  @returns The ENU-rebased `PackedPointTile`. */
+    decode(buffer: ArrayBuffer, ctx: CesiumPointDecodeContext): Promise<PackedPointTile>;
+    /** Worker-pool size (worker variants) — size the engine's decode concurrency to match. */
+    readonly concurrency?: number;
+    dispose?(): void;
+}
+/** Built-in point-decoder identifiers a layer/engine can resolve to an impl. */
+export type CesiumPointDecoderKind = 'pnts';

package/dist/contracts/decoder.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Decoder contract + the normalized decoded model.
+ *
+ * The model the SDK passes around is the **quantized** structure-of-
+ * arrays straight from the wasm decoder, plus the container metadata
+ * needed to dequantize. Dequant itself is deferred to the render
+ * shaders (upload compact bytes, expand on the GPU), so nothing here is
+ * floating-point geometry.
+ */
+import type { DecodeBackend } from '@bitruvius/foundation';
+/** Which decoded model a container holds: a gaussian `splat` cloud or a `pointcloud`. */
+export type ModelProfile = 'splat' | 'pointcloud';
+/** Splat-container dequant metadata — the constants the render shader needs to expand
+ *  the quantized {@link DecodedSplatTile} arrays back to meters/colors. */
+export interface SplatContainerMeta {
+    /** Discriminant. */
+    readonly kind: 'splat';
+    /** Position grid divisor exponent: `meters = q / 2^fractionalBits`. */
+    readonly fractionalBits: number;
+    /** Container SH-degree hint (0..3). A per-tile degree may also be present. */
+    readonly shDegree: number;
+}
+/** Point-cloud-container dequant metadata: the per-axis affine that maps the quantized
+ *  i32 grid back to world coordinates. */
+export interface PointContainerMeta {
+    /** Discriminant. */
+    readonly kind: 'pointcloud';
+    /** Per-axis dequant scale (world = `q * scale + offset`). f64 — full precision. */
+    readonly scale: readonly [number, number, number];
+    /** Per-axis dequant offset (world = `q * scale + offset`). f64. */
+    readonly offset: readonly [number, number, number];
+}
+/** The container-level dequant metadata, discriminated by `kind`. */
+export type ContainerMeta = SplatContainerMeta | PointContainerMeta;
+/** One decoded gaussian-splat tile: quantized structure-of-arrays straight from the
+ *  wasm decoder (dequant deferred to the render shader). All arrays have `count`
+ *  elements unless noted; SH bands are present per `shDegree`. */
+export interface DecodedSplatTile {
+    /** Discriminant. */
+    readonly kind: 'splat';
+    /** Splat count in this tile. */
+    readonly count: number;
+    /** Quantized position grid, X axis (`meters = q / 2^fractionalBits`). */
+    readonly x: Int32Array;
+    /** Quantized position grid, Y axis. */
+    readonly y: Int32Array;
+    /** Quantized position grid, Z axis. */
+    readonly z: Int32Array;
+    /** Opacity byte in the rendered (post-sigmoid) domain. */
+    readonly opacity: Uint8Array;
+    /** Log-quantized scale, X axis (see {@link splatScale}). */
+    readonly scaleX: Uint8Array;
+    /** Log-quantized scale, Y axis. */
+    readonly scaleY: Uint8Array;
+    /** Log-quantized scale, Z axis. */
+    readonly scaleZ: Uint8Array;
+    /** Smallest-three rotation: slot index of the omitted (largest `|component|`). */
+    readonly rotIdx: Uint8Array;
+    /** Smallest-three rotation component A (see {@link decodeSmallestThree}). */
+    readonly rotA: Int16Array;
+    /** Smallest-three rotation component B. */
+    readonly rotB: Int16Array;
+    /** Smallest-three rotation component C. */
+    readonly rotC: Int16Array;
+    /** SH degree-0 DC byte, red channel. */
+    readonly colorR: Uint8Array;
+    /** SH degree-0 DC byte, green channel. */
+    readonly colorG: Uint8Array;
+    /** SH degree-0 DC byte, blue channel. */
+    readonly colorB: Uint8Array;
+    /** This tile's SH degree (0..3). */
+    readonly shDegree: number;
+    /** Band-1 SH rest coefficients (`count*9` bytes); present when `shDegree >= 1`. */
+    readonly sh1?: Uint8Array;
+    /** Band-2 SH rest coefficients (`count*15` bytes); present when `shDegree >= 2`. */
+    readonly sh2?: Uint8Array;
+    /** Band-3 SH rest coefficients (`count*21` bytes); present when `shDegree === 3`. */
+    readonly sh3?: Uint8Array;
+}
+/** One decoded point-cloud tile: quantized i32 positions plus the present per-point
+ *  attribute planes (all of length `count`). Dequant deferred to the render shader. */
+export interface DecodedPointTile {
+    /** Discriminant. */
+    readonly kind: 'pointcloud';
+    /** Point count in this tile. */
+    readonly count: number;
+    /** Quantized position grid, X axis (`world = q * scale + offset`). */
+    readonly x: Int32Array;
+    /** Quantized position grid, Y axis. */
+    readonly y: Int32Array;
+    /** Quantized position grid, Z axis. */
+    readonly z: Int32Array;
+    /** Red channel (full-range u16), if colored. */
+    readonly r?: Uint16Array;
+    /** Green channel (full-range u16), if colored. */
+    readonly g?: Uint16Array;
+    /** Blue channel (full-range u16), if colored. */
+    readonly b?: Uint16Array;
+    /** LAS intensity (full-range u16), if present. */
+    readonly intensity?: Uint16Array;
+    /** LAS classification code, if present. */
+    readonly classification?: Uint8Array;
+    /** GPS time low 32 bits — reassemble as `lo + hi * 2^32`. */
+    readonly gpsLo?: Uint32Array;
+    /** GPS time high 32 bits. */
+    readonly gpsHi?: Uint32Array;
+}
+/** One decoded tile, discriminated by `kind`: a {@link DecodedSplatTile} or a
+ *  {@link DecodedPointTile}. */
+export type DecodedTile = DecodedSplatTile | DecodedPointTile;
+/** Result of `Decoder.open` — the cheap header parse: which profile the
+ *  container is, its dequant metadata, and how many tiles it holds. */
+export interface DecodedModel {
+    /** `'splat'` or `'pointcloud'`. */
+    readonly profile: ModelProfile;
+    /** Container-level dequant metadata ({@link ContainerMeta}). */
+    readonly meta: ContainerMeta;
+    /** Number of tiles {@link Decoder.decodeTiles} will yield. */
+    readonly tileCount: number;
+}
+/** Options for {@link Decoder.decodeTiles}. */
+export interface DecodeOptions {
+    /** Decode backend to use; omit to auto-select (see {@link recommendDecodeBackend}). */
+    readonly backend?: DecodeBackend;
+    /** Abort signal — aborting stops the stream and rejects in-flight work. */
+    readonly signal?: AbortSignal;
+    /** Streaming hook called as each tile finishes decoding.
+     *  @param tile - The freshly decoded tile.
+     *  @param index - Its 0-based index within the container. */
+    readonly onTile?: (tile: DecodedTile, index: number) => void;
+}
+/**
+ * The decode seam a codec satisfies and the streaming engines consume. Obtain one from
+ * a {@link DecoderFactory.create}; `open` the bytes to read the header, then
+ * `decodeTiles` to stream the quantized tiles.
+ */
+export interface Decoder {
+    /** The backend this decoder is actually running. */
+    readonly backend: DecodeBackend;
+    /**
+     * Parse the container header (cheap — no per-tile decode).
+     * @param bytes - The full container bytes.
+     * @returns The `DecodedModel` (profile + dequant meta + tile count).
+     * @throws BitruviusError `BVX_DECODE_FAILED` on bad magic / truncation / unsupported version.
+     */
+    open(bytes: Uint8Array): Promise<DecodedModel>;
+    /**
+     * Stream-decode every tile. Each yielded tile's typed arrays are transferred from the
+     * worker (zero-copy), so do not reuse a tile's arrays after the next iteration.
+     * @param model - The `DecodedModel` from `open`.
+     * @param bytes - The full container bytes (same buffer passed to `open`).
+     * @param opts - Optional `DecodeOptions` (backend / abort / `onTile`).
+     * @returns An async iterable of `DecodedTile`s in container order.
+     * @throws BitruviusError `BVX_DECODE_FAILED` on a corrupt tile; `BVX_WORKER_SPAWN_BLOCKED`
+     *   when a worker backend cannot start.
+     */
+    decodeTiles(model: DecodedModel, bytes: Uint8Array, opts?: DecodeOptions): AsyncIterable<DecodedTile>;
+    /** Release the decoder's resources (worker pool, wasm instance). */
+    dispose(): void;
+}
+/**
+ * The factory every codec package exports (one per format: `bvc`, `turbolzp`, …). The
+ * loose-coupling seam between a streaming engine and a concrete codec.
+ *
+ * @example
+ * ```ts
+ * const decoder = await factory.create({ poolSize: 4 });
+ * const model = await decoder.open(bytes);
+ * for await (const tile of decoder.decodeTiles(model, bytes)) {
+ *   // upload `tile` to the GPU
+ * }
+ * decoder.dispose();
+ * ```
+ */
+export interface DecoderFactory {
+    /** Stable codec id (e.g. `'bvc'`). */
+    readonly id: string;
+    /** The backends this codec can run on this build. */
+    readonly supportedBackends: readonly DecodeBackend[];
+    /**
+     * Construct a {@link Decoder}.
+     * @param opts - Optional backend override and worker `poolSize`.
+     * @returns A ready {@link Decoder}.
+     * @throws BitruviusError `BVX_NO_BACKEND` when no requested/available backend is usable;
+     *   `BVX_WASM_LOAD_FAILED` when the codec wasm cannot load.
+     */
+    create(opts?: {
+        backend?: DecodeBackend;
+        poolSize?: number;
+    }): Promise<Decoder>;
+}