@bitruvius/geo-core 0.3.1

package/dist/contracts/feature-metadata.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Normalized per-feature **metadata** — the format-agnostic target that I3S BSL/3DObject
+ * attributes, 3D-Tiles 1.0 batch tables, and glTF 1.1 `EXT_structural_metadata` property tables
+ * all decode into. It stays **CPU-side** (never uploaded — only `featureId`s go to the GPU) and
+ * powers picking + filter/style evaluation (a feature's values feed {@link PropertyGetter}).
+ *
+ * Grounded in the audited Revit/BIM field set (Category, Family, BldgLevel, Discipline,
+ * ElementType, AssemblyCode, OmniClass, IsStructural, …): I3S stores these as string/number
+ * per-node attribute blobs; 3D-Tiles stores them as property-table columns (with enums). Both
+ * normalize to {@link FeatureColumn}s consumed by {@link ColumnFeatureProperties}.
+ */
+import type { PropertyGetter } from '../style/expression';
+/** Normalized property kind (the union across I3S valueType, batch-table type, and
+ *  `EXT_structural_metadata` class-property type). */
+export type FeaturePropertyType = 'scalar' | 'string' | 'boolean' | 'enum';
+/** A named enumeration: the integer→label map an `'enum'` property resolves against. */
+export interface FeatureEnum {
+    /** The enum's name (referenced by {@link FeaturePropertyDef.enumName}). */
+    readonly name: string;
+    /** Integer value → label (e.g. `0 → 'Architectural'`). */
+    readonly values: ReadonlyMap<number, string>;
+}
+/** The definition of one feature property/column: its name, kind, and (for enums) the
+ *  enum it resolves against. */
+export interface FeaturePropertyDef {
+    /** Property/column name (the key a {@link PropertyGetter} looks up). */
+    readonly name: string;
+    /** Normalized kind of the property. */
+    readonly type: FeaturePropertyType;
+    /** Storage component type, informational (`Int32`, `Float64`, `UInt8`, `String`, …). */
+    readonly componentType?: string;
+    /** Enum name in the {@link FeatureSchema} when `type === 'enum'`. */
+    readonly enumName?: string;
+    /** Human label (I3S field alias, structural-metadata property name). */
+    readonly label?: string;
+}
+/** A feature class: a named set of property definitions (one schema entry). */
+export interface FeatureClass {
+    /** Class name. */
+    readonly name: string;
+    /** The properties of this class. */
+    readonly properties: readonly FeaturePropertyDef[];
+}
+/** Schema of feature classes + enums (I3S `fields`/`attributeStorageInfo`, or the
+ *  `EXT_structural_metadata` / batch-table-hierarchy schema). */
+export interface FeatureSchema {
+    readonly classes: ReadonlyMap<string, FeatureClass>;
+    readonly enums: ReadonlyMap<string, FeatureEnum>;
+}
+/** A resolved feature value (enum integers already mapped to their label), or `null`. */
+export type FeatureValue = number | string | boolean | null;
+/**
+ * Read-only accessor over one tile/node's per-feature property columns, addressed by
+ * `featureId` in `0..count-1`. This is what picking and filter/style evaluation read;
+ * adapt it to a {@link PropertyGetter} with {@link featureGetter}.
+ */
+export interface FeatureProperties {
+    /** Number of features (valid `featureId` range is `0..count-1`). */
+    readonly count: number;
+    /** All available property names. */
+    readonly names: readonly string[];
+    /**
+     * One property's value for a feature, with enum integers resolved to their label.
+     * @param featureId - Feature index in `0..count-1`.
+     * @param name - Property name.
+     * @returns The value, or `null` when the feature/property is absent or out of range.
+     */
+    value(featureId: number, name: string): FeatureValue;
+    /**
+     * All properties for a feature, as a plain record.
+     * @param featureId - Feature index in `0..count-1`.
+     * @returns A `name → value` record, or `null` when `featureId` is out of range.
+     */
+    record(featureId: number): Record<string, FeatureValue> | null;
+}
+/** One decoded property column: its definition plus `count` parallel values (strings
+ *  for a `'string'` property, numbers/booleans otherwise; enums stored as integers). */
+export interface FeatureColumn {
+    /** This column's {@link FeaturePropertyDef}. */
+    readonly def: FeaturePropertyDef;
+    /** The per-feature raw values (index = `featureId`). */
+    readonly values: ReadonlyArray<number | string | boolean>;
+}
+/** A structured-cloneable plain form of {@link FeatureProperties} — for handing decoded metadata
+ *  across the worker → main-thread boundary (a `ColumnFeatureProperties` is a class with `Map`s and
+ *  can't be `postMessage`d). Reconstruct with {@link materializeFeatureProperties}. */
+export interface FeaturePropertiesData {
+    /** Feature count. */
+    readonly count: number;
+    /** The decoded columns (each keyed by its `def.name`). */
+    readonly columns: readonly FeatureColumn[];
+    /** Enum definitions as plain `[value, label]` entry arrays (Maps don't clone). */
+    readonly enums?: readonly {
+        readonly name: string;
+        readonly entries: readonly (readonly [number, string])[];
+    }[];
+}
+/**
+ * In-memory {@link FeatureProperties} backed by decoded columns — built by the I3S
+ * attribute decode and the 3D-Tiles property-table / batch-table decode alike. Enum
+ * columns are resolved to labels on read, so a filter like `Discipline='Architectural'`
+ * matches regardless of the source encoding.
+ *
+ * @example
+ * ```ts
+ * const props = materializeFeatureProperties(tile.featureMetadata!); // worker → main
+ * const level = props.value(featureId, 'BldgLevel');
+ * const all = props.record(featureId); // { Category: 'Walls', BldgLevel: 3, … }
+ * ```
+ *
+ * @see {@link materializeFeatureProperties}, {@link featureGetter}
+ */
+export declare class ColumnFeatureProperties implements FeatureProperties {
+    #private;
+    /** Number of features. */
+    readonly count: number;
+    /** All available property names (the column keys). */
+    readonly names: readonly string[];
+    /**
+     * @param count - Feature count (valid `featureId` range `0..count-1`).
+     * @param columns - Decoded columns keyed by property name.
+     * @param enums - Enum definitions referenced by `'enum'` columns (default empty).
+     */
+    constructor(count: number, columns: ReadonlyMap<string, FeatureColumn>, enums?: ReadonlyMap<string, FeatureEnum>);
+    /**
+     * One property's value for a feature, enum integers resolved to their label.
+     * @param featureId - Feature index in `0..count-1`.
+     * @param name - Property name.
+     * @returns The resolved value, or `null` when out of range / absent.
+     */
+    value(featureId: number, name: string): FeatureValue;
+    /**
+     * All properties for a feature as a plain record.
+     * @param featureId - Feature index in `0..count-1`.
+     * @returns A `name → value` record, or `null` when `featureId` is out of range.
+     */
+    record(featureId: number): Record<string, FeatureValue> | null;
+    /** Plain, structured-cloneable snapshot — for the worker → main-thread hand-off. */
+    toData(): FeaturePropertiesData;
+}
+/**
+ * Rebuild a {@link ColumnFeatureProperties} from its structured-cloneable
+ * {@link FeaturePropertiesData} — the main-thread side of the worker hand-off.
+ * @param data - The plain form produced by {@link ColumnFeatureProperties.toData}.
+ * @returns A live {@link ColumnFeatureProperties}.
+ */
+export declare function materializeFeatureProperties(data: FeaturePropertiesData): ColumnFeatureProperties;
+/**
+ * Adapt one feature's properties into a {@link PropertyGetter} for the expression
+ * evaluator ({@link compileSqlFilter} / {@link compileStyleExpression}).
+ * @param props - The feature properties for the tile/node.
+ * @param featureId - The feature to bind the getter to (`0..props.count-1`).
+ * @returns A `(name) => value` getter that reads that feature's properties.
+ *
+ * @example
+ * ```ts
+ * const pass = compileSqlFilter("BldgLevel >= 3");
+ * const visible = pass(featureGetter(props, featureId));
+ * ```
+ */
+export declare function featureGetter(props: FeatureProperties, featureId: number): PropertyGetter;

package/dist/contracts/gltf-splat-decoder.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `GltfSplatDecoder` — the loose-coupling seam for 3D-Tiles gaussian-splat
+ * streaming. A 3D-Tiles tile is a `.glb` (glTF binary) whose mesh carries a
+ * `KHR_gaussian_splatting` primitive with a compressed splat buffer. This
+ * contract decodes one such `.glb` to a flat {@link GltfSplatCloud}, regardless
+ * of WHICH compression the buffer uses:
+ *
+ *   - `@bitruvius/turbo-spz` implements it for Esri/Cesium `…_compression_spz_2`.
+ *   - `@bitruvius/bvc` implements it for `…_compression_bvc` (Bitruvius BVC, the
+ *     anticipated glTF drop-in).
+ *
+ * The `@bitruvius/tiles3d` engine and the MapLibre layer depend ONLY on this
+ * interface — never on a concrete codec — so a consumer swaps decoders without
+ * touching streaming or rendering. The cloud shape matches what both wasm
+ * decoders already return (turbo-spz `SpzGaussianCloud`; the source GltfSplatCloud).
+ */
+/** A decoded gaussian-splat cloud in the tile's glb-local frame (float SoA). */
+export interface GltfSplatCloud {
+    /** Splat count. */
+    readonly numPoints: number;
+    /** Spherical-harmonics degree present (0 = DC only). */
+    readonly shDegree: number;
+    /** Column-major 4×4 glTF node transform (16). Identity if the tile declares none. */
+    readonly nodeMatrix: Float32Array;
+    /** 3·N glb-local meters. */
+    readonly positions: Float32Array;
+    /** 3·N log-scales. */
+    readonly scales: Float32Array;
+    /** 4·N quaternion (x,y,z,w). */
+    readonly rotations: Float32Array;
+    /** N opacity logit (pre-sigmoid). */
+    readonly alphas: Float32Array;
+    /** 3·N DC colour (raw SH band-0 coefficient). */
+    readonly colors: Float32Array;
+    /** N·coeffs(shDegree) SH rest coefficients, splat-major coeff-outer/RGB-inner;
+     *  band-1 = first 9 floats/splat. Empty when shDegree === 0. */
+    readonly sh: Float32Array;
+}
+/** Decodes a whole 3D-Tiles `.glb` gaussian-splat tile to a {@link GltfSplatCloud}.
+ *  Satisfied by `@bitruvius/turbo-spz` (`spz`) and `@bitruvius/bvc` (`bvc`). */
+export interface GltfSplatDecoder {
+    /** Decode one `.glb` tile (may be gzip-framed, e.g. Esri `spz_2`).
+     *  @param glb - The `.glb` tile bytes.
+     *  @returns The decoded {@link GltfSplatCloud} in the tile's glb-local frame. */
+    decode(glb: ArrayBuffer): Promise<GltfSplatCloud>;
+}
+/** Optional inverse: write a {@link GltfSplatCloud} back to a `.glb` tile. */
+export interface GltfSplatEncoder {
+    /** @param cloud - The splat cloud. @returns The encoded `.glb` bytes. */
+    encode(cloud: GltfSplatCloud): Promise<ArrayBuffer>;
+}
+/** Built-in decoder identifiers a layer/engine can resolve to a concrete impl. */
+export type GltfSplatDecoderKind = 'spz' | 'bvc';

package/dist/contracts/i3s-mesh-decoder.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The I3S **mesh** decode seam — the IntegratedMesh / 3DObject analog of
+ * `I3sPointCloudDecoder`. The engine fetches a node's geometry blob (Draco or
+ * legacy PerAttributeArray) + an optional texture blob and hands them, with the
+ * per-node reference frame, to an injected {@link I3sMeshDecoder} that produces a
+ * GPU-ready, ENU-rebased {@link PackedMeshTile} the `@bitruvius/mesh` renderer draws.
+ * Codec-agnostic: the concrete decoder lives in a codec-aware package (it injects a
+ * {@link DracoGeometryDecoder}); the i3s engine depends only on this interface.
+ */
+import type { Mat4 } from '../geo/mat4';
+import type { AlphaMode, EdgeExtractOptions, PackedMeshTile } from './mesh';
+/** The raw blobs for ONE I3S mesh node (fetched by the engine). */
+export interface I3sMeshBlobs {
+    /** `…/nodes/{resource}/geometries/{buffer}` — Draco or legacy PAA geometry. */
+    readonly geometry: ArrayBuffer;
+    /** `…/nodes/{resource}/textures/{name}` — the chosen baseColor texture, if any. */
+    readonly texture?: ArrayBuffer;
+}
+/** The unlit material params the decoder bakes into the packed tile. */
+export interface I3sDecodeMaterial {
+    readonly baseColorFactor?: readonly [number, number, number, number];
+    readonly doubleSided: boolean;
+    readonly alphaMode: AlphaMode;
+    readonly hasBaseColorTexture: boolean;
+}
+/** One member of an uncompressed PerAttributeArray (PAA) geometry buffer, in stored order
+ *  (`position`, `normal`, `uv0`, `color`, `uvRegion`/`region`, `featureId`, `faceRange`). */
+export interface I3sPaaMember {
+    readonly name: string;
+    /** I3S valueType: `Float32` | `UInt8` | `UInt16` | `UInt32` | `UInt64` | … */
+    readonly valueType: string;
+    readonly valuesPerElement: number;
+    /** `true` for the per-FEATURE section (`featureId`, `faceRange`); else per-VERTEX. */
+    readonly perFeature: boolean;
+}
+/** Binary layout of an uncompressed PAA geometry buffer — present in
+ *  {@link I3sMeshDecodeContext} when the node's chosen buffer is NOT Draco. */
+export interface I3sPaaLayout {
+    /** Leading header bytes to skip (the buffer def's `offset`; the header holds vertex/feature counts). */
+    readonly offset: number;
+    readonly members: readonly I3sPaaMember[];
+    /** Per-VERTEX element count (non-indexed: 3·faces) — from the node's `geometry.vertexCount`. */
+    readonly vertexCount: number;
+    /** Per-FEATURE element count — from the node's `geometry.featureCount`. */
+    readonly featureCount: number;
+}
+/** Everything the decoder needs to georeference + assemble one mesh node. */
+export interface I3sMeshDecodeContext {
+    /** ECEF → shared-scene ENU (meters), column-major 4×4. */
+    readonly enuFromEcef: Mat4;
+    /** node-local ENU → ECEF (the engine builds it from the node center). */
+    readonly tileTransform: Mat4;
+    /** Bake the exact per-vertex web-mercator offset at decode (kills the per-tile ENU-tangent parallax-
+     *  swim on planet-scale layers). Off ⇒ the ENU-only path, byte-identical. Set by the engine. */
+    readonly bakeMercator?: boolean;
+    /** WGS84 meters-per-degree of longitude / latitude at the node center — I3S global-mode
+     *  vertex X/Y are lng/lat DEGREE offsets; multiply to get local ENU east/north meters. */
+    readonly lngToMeters: number;
+    readonly latToMeters: number;
+    /** Geometry blob is Draco-compressed; else uncompressed PerAttributeArray (see {@link paa}). */
+    readonly draco: boolean;
+    /** Uncompressed PAA buffer layout — REQUIRED when `draco` is false (the decoder reads the blob
+     *  per this layout); absent for Draco nodes. */
+    readonly paa?: I3sPaaLayout;
+    /** Texture blob format, or null when the node carries no texture. */
+    readonly textureFormat: 'jpg' | 'png' | 'dds' | 'ktx2' | null;
+    readonly material: I3sDecodeMaterial | null;
+    /** Extract hard edges for this node ({@link PackedMeshTile.edges}). Absent ⇒ no extraction. */
+    readonly edges?: EdgeExtractOptions;
+}
+/** Decodes one I3S mesh node's blobs into a GPU-ready, ENU-rebased {@link PackedMeshTile}. */
+export interface I3sMeshDecoder {
+    /** @param blobs - The node's geometry + optional texture ({@link I3sMeshBlobs}).
+     *  @param ctx - Georeference + assembly context ({@link I3sMeshDecodeContext}).
+     *  @returns The ENU-rebased {@link PackedMeshTile}. */
+    decode(blobs: I3sMeshBlobs, ctx: I3sMeshDecodeContext): Promise<PackedMeshTile>;
+    /** Worker pool size (worker variants) — size the engine's decode concurrency to match. */
+    readonly concurrency?: number;
+    dispose?(): void;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * `I3sPointCloudDecoder` — the loose-coupling seam for Esri **I3S Point Cloud (PCSL)**
+ * streaming, the point-cloud analog of {@link GltfSplatDecoder}. An I3S node is
+ * NOT a single buffer: it is a geometry blob (`…/geometries/0`, `lepcc-xyz`) plus
+ * zero or more per-attribute blobs (`…/attributes/{key}`). This contract decodes
+ * ONE such node's blobs into a GPU-ready, ENU-rebased `PackedPointTile`,
+ * regardless of WHICH codec the blobs use:
+ *
+ *   - `@bitruvius/turbo-lepcc` implements it for native Esri LEPCC services.
+ *   - `@bitruvius/bvc` implements it for bvc-transcoded I3S nodes.
+ *
+ * The `@bitruvius/i3s` engine and the MapLibre layer depend ONLY on this
+ * interface — never on a concrete codec — so a consumer swaps `lepcc`↔`bvc`
+ * without touching streaming or rendering. Projection (geodetic→ECEF→ENU),
+ * requantization to the renderer's i32 grid, and interleaving all happen INSIDE
+ * the decoder (off the main thread for the worker variants); the engine just
+ * hands the packed tile to the renderer.
+ */
+import type { PackedPointTile } from '../geo/pack-point-enu';
+/** I3S attribute storage value type (from `attributeStorageInfo[].valueType`). */
+export type I3sValueType = 'UInt8' | 'Int8' | 'UInt16' | 'Int16' | 'UInt32' | 'Int32' | 'UInt64' | 'Int64' | 'Float32' | 'Float64';
+/** Logical attribute meaning, derived from `attributeStorageInfo[].name`. Drives
+ *  how a blob is decoded and which `PackedPointTile` channel it fills. */
+export type I3sAttributeSemantic = 'ELEVATION' | 'INTENSITY' | 'RGB' | 'CLASS_CODE' | 'FLAGS' | 'RETURNS' | 'USER_DATA' | 'POINT_SRC_ID' | 'GPS_TIME' | 'SCAN_ANGLE' | 'NEAR_INFRARED' | 'UNKNOWN';
+/** One entry of the layer's `attributeStorageInfo`, semantic-mapped. The `key` is
+ *  the per-node attribute resource id used to build the blob URL. */
+export interface I3sAttributeInfo {
+    readonly key: number;
+    /** The RAW attribute key as it appears in `attributeStorageInfo` and the resource URL
+     *  (`…/attributes/{keyName}/0`). Numeric for point layers (`'1'`), but `'f_0'`-style for
+     *  3DObject feature attributes — where {@link key} (a parsed number) is meaningless. */
+    readonly keyName?: string;
+    readonly name: string;
+    readonly semantic: I3sAttributeSemantic;
+    readonly valueType: I3sValueType;
+    readonly valuesPerElement: number;
+    /** e.g. `'lepcc-intensity'`, `'lepcc-rgb'`, `'embedded-elevation'`, or undefined (raw). */
+    readonly encoding?: string;
+}
+/** The raw blobs for ONE I3S node, fetched by the engine and handed to the decoder.
+ *  `attributes` is keyed by the I3S attribute resource id (see {@link I3sAttributeInfo.key}). */
+export interface I3sNodeBlobs {
+    /** `…/nodes/{id}/geometries/0` — the lepcc-xyz (or bvc) geometry blob. */
+    readonly geometry: ArrayBuffer;
+    /** `…/nodes/{id}/attributes/{key}` blobs the engine chose to fetch (may be empty). */
+    readonly attributes: ReadonlyMap<number, ArrayBuffer>;
+}
+/** Everything the decoder needs to georeference + requantize a node's points into
+ *  the shared scene ENU frame the renderer draws. */
+export interface I3sDecodeContext {
+    /** Node OBB center in ECEF (meters) — the per-tile requantization origin. */
+    readonly nodeCenterEcef: readonly [number, number, number];
+    /** ECEF → shared-scene local ENU (meters), column-major 4×4 (16 floats). */
+    readonly enuFromEcef: Float64Array;
+    /** Geoid undulation N (m): geometry heights are orthometric (vcsWkid 5773), so
+     *  ellipsoidal h = orthometric H + N before `geodeticToEcef`. 0 = treat as ellipsoidal. */
+    readonly geoidN: number;
+    /** Requantization step (meters) for the i32 position grid (e.g. 0.001 = 1 mm). */
+    readonly grid: number;
+    /** Layer attribute schema (semantic + valueType + encoding) for the fetched blobs. */
+    readonly attributes: readonly I3sAttributeInfo[];
+    /** Horizontal CRS wkid. 4326/4979 = geographic (decode→lng/lat/h). */
+    readonly wkid: number;
+    /** Vertical CRS wkid (5773 = EGM96 orthometric). */
+    readonly vcsWkid?: number;
+    /** Projected-CRS reprojection hook: (x,y,z) in the layer CRS → [lng°, lat°, h_m].
+     *  REQUIRED when `wkid` is a projected CRS; ignored for geographic scenes. */
+    readonly reproject?: (x: number, y: number, z: number) => [number, number, number];
+}
+/** Decodes one I3S point node's blobs into a GPU-ready, ENU-rebased point tile.
+ *  Satisfied by `@bitruvius/turbo-lepcc` (`lepcc`) and `@bitruvius/bvc` (`bvc`). */
+export interface I3sPointCloudDecoder {
+    /** Decode one node into the shared scene ENU frame.
+     *  @param blobs - The node's geometry + attribute blobs (`I3sNodeBlobs`).
+     *  @param ctx - Georeference + requantize context (`I3sDecodeContext`).
+     *  @returns The ENU-rebased, requantized `PackedPointTile`. */
+    decode(blobs: I3sNodeBlobs, ctx: I3sDecodeContext): Promise<PackedPointTile>;
+    /** Worker pool size (worker variants) — size the engine's decode concurrency to match. */
+    readonly concurrency?: number;
+    /** True when the geometry blob already carries ALL attributes (e.g. a bvc point
+     *  tile) — the engine then fetches NO separate `/attributes/{key}` blobs. Native
+     *  Esri LEPCC leaves this false (attributes are separate per-node resources). */
+    readonly selfContainedAttributes?: boolean;
+    dispose?(): void;
+}
+/** Built-in decoder identifiers a layer/engine can resolve to a concrete impl. */
+export type I3sPointCloudDecoderKind = 'lepcc' | 'bvc';
+/** Map an I3S `attributeStorageInfo[].name` to a logical {@link I3sAttributeSemantic}.
+ *  @param name - The raw attribute name. @returns The semantic, or `'UNKNOWN'`. */
+export declare function attributeSemantic(name: string): I3sAttributeSemantic;

package/dist/contracts/mesh-codecs.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Third-party-codec **seams** for the mesh/point decode path — interfaces only,
+ * no codec. The Bitruvius WASM wrapper packages implement these and are injected
+ * into the parser/decoder, keeping `@bitruvius/gltf` (and the engine) codec- and
+ * vendor-agnostic:
+ *
+ *   - `@bitruvius/draco`   → {@link DracoGeometryDecoder} (KHR_draco_mesh_compression,
+ *                             3DTILES_draco_point_compression)
+ *   - `@bitruvius/meshopt` → {@link MeshoptDecoder}       (EXT_meshopt_compression)
+ *   - `@bitruvius/ktx2`    → {@link Ktx2Transcoder}       (KHR_texture_basisu)
+ *
+ * They live in geo-core (alongside the other cross-package contracts) so a codec
+ * package depends only on `@bitruvius/geo-core`, never on the glTF parser.
+ */
+/** Any numeric typed array (decoded attribute / index storage). */
+export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
+export interface DracoDecodedAttribute {
+    readonly array: TypedArray;
+    /** Components per vertex (e.g. POSITION → 3). */
+    readonly componentCount: number;
+}
+export interface DracoDecoded {
+    /** Triangle indices, or undefined for point clouds. */
+    readonly indices: Uint32Array | undefined;
+    /** Decoded attributes keyed by the glTF/I3S attribute semantic. */
+    readonly attributes: ReadonlyMap<string, DracoDecodedAttribute>;
+    /** Vertex (or point) count. */
+    readonly count: number;
+}
+/** I3S Draco-compressed mesh geometry, decoded by NAMED attribute + Draco metadata
+ *  (I3S carries no explicit unique-id map; it uses Draco's POSITION/TEX_COORD/NORMAL
+ *  types and `i3s-scale_x/y` metadata on POSITION). Positions are RAW node-local — the
+ *  i3s-scale is returned separately in `scaleX/scaleY` (NOT pre-multiplied), so the caller
+ *  folds it into the node matrix instead of an extra full pass over every vertex.
+ *  `featureIndex` (the GENERIC per-vertex object id) is for picking. */
+export interface I3sDracoMesh {
+    /** 3·N node-local positions (Float32, RAW — i3s-scale NOT applied; see scaleX/scaleY). */
+    readonly positions: Float32Array;
+    readonly uv0?: Float32Array;
+    readonly normals?: Float32Array;
+    /** 4·N RAW RGBA bytes (0..255) — the I3S `color` vertex attribute (per-feature tint on
+     *  untextured 3DObject features). Kept as bytes; the renderer GPU-normalizes at upload. */
+    readonly color0?: Uint8Array;
+    /** 4·N RAW atlas region `(uMin,vMin,uMax,vMax)` as UInt16 (0..65535) — the I3S `uv-region`
+     *  attribute for texture-atlased 3DObject. GPU-normalized at upload; the shader wraps uv0
+     *  into the region. Absent when the node isn't atlased. */
+    readonly uvRegion?: Uint16Array;
+    readonly featureIndex?: Uint32Array;
+    /** Triangle indices — present for Draco (indexed); ABSENT for uncompressed PAA (non-indexed,
+     *  3·faces vertices drawn directly). */
+    readonly indices?: Uint32Array;
+    readonly count: number;
+    /** `i3s-scale_x/y` POSITION metadata (default 1) — fold into the node matrix's X/Y columns. */
+    readonly scaleX: number;
+    readonly scaleY: number;
+}
+/** I3S Draco-compressed POINT geometry — the modern **Point feature** profile (`layerType:
+ *  "Point"`): a Draco buffer with `position` + `feature-index` (geometryType points). Like
+ *  {@link I3sDracoMesh} but a POINT CLOUD — no faces/indices, no uv/normal/color. Positions are
+ *  RAW node-local (i3s-scale returned separately, NOT pre-multiplied); `featureIndex` is the
+ *  per-point feature ordinal for the attribute join / symbol selection / picking. */
+export interface I3sDracoPoints {
+    /** 3·N node-local positions (Float32, RAW — i3s-scale NOT applied; see scaleX/scaleY). */
+    readonly positions: Float32Array;
+    /** N per-point feature ordinals (GENERIC i3s `feature-index`); absent if the buffer omits it. */
+    readonly featureIndex?: Uint32Array;
+    readonly count: number;
+    /** `i3s-scale_x/y` POSITION metadata (default 1) — fold into the node matrix's X/Y columns. */
+    readonly scaleX: number;
+    readonly scaleY: number;
+}
+/** The Draco decode seam, satisfied by `@bitruvius/draco`. */
+export interface DracoGeometryDecoder {
+    /** Decode a Draco buffer by glTF unique-id map.
+     *  @param compressed - The Draco buffer.
+     *  @param attributeIds - Maps a semantic (`POSITION`, `NORMAL`, `TEXCOORD_0`,
+     *    `COLOR_0`, `_FEATURE_ID_0`, …) to the Draco unique-id to extract.
+     *  @returns The decoded indices + attributes ({@link DracoDecoded}). */
+    decode(compressed: Uint8Array, attributeIds: Readonly<Record<string, number>>): Promise<DracoDecoded>;
+    /** Decode an I3S Draco mesh by named attribute + metadata (no unique-id map). */
+    decodeI3sMesh?(compressed: Uint8Array): Promise<I3sDracoMesh>;
+    /** Decode I3S Draco POINT geometry (modern Point feature profile: position + feature-index). */
+    decodeI3sPoints?(compressed: Uint8Array): Promise<I3sDracoPoints>;
+    readonly concurrency?: number;
+    dispose?(): void;
+}
+export interface MeshoptDecodeRequest {
+    /** Destination buffer (written in place), sized `count * byteStride`. */
+    readonly target: Uint8Array;
+    readonly count: number;
+    readonly byteStride: number;
+    readonly source: Uint8Array;
+    /** EXT_meshopt_compression `mode`: ATTRIBUTES | TRIANGLES | INDICES. */
+    readonly mode: 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES';
+    /** Optional `filter`: NONE | OCTAHEDRAL | QUATERNION | EXPONENTIAL. */
+    readonly filter?: 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL';
+}
+/** The EXT_meshopt_compression decode seam, satisfied by `@bitruvius/meshopt`. */
+export interface MeshoptDecoder {
+    /** Decode one meshopt buffer in place into `req.target`.
+     *  @param req - The decode request ({@link MeshoptDecodeRequest}). */
+    decodeGltfBuffer(req: MeshoptDecodeRequest): Promise<void> | void;
+    dispose?(): void;
+}
+/** Backend-neutral GPU texture format the transcoder targets (the renderer picks
+ *  the best supported one per device; `rgba32` is the universal fallback). */
+export type GpuTextureFormatHint = 'rgba32' | 'bc7' | 'bc3' | 'bc1' | 'etc2' | 'astc4x4' | 'pvrtc';
+export interface TranscodedTextureLevel {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+}
+export interface TranscodedTexture {
+    readonly format: GpuTextureFormatHint;
+    readonly levels: readonly TranscodedTextureLevel[];
+}
+/**
+ * Encode a {@link GpuTextureFormatHint} as the small integer a renderer maps to a GL
+ * enum ({@link PackedTexture.compressed}.format).
+ *
+ * It is an INDEX into a fixed order, so every producer has to agree on that order or
+ * a texture uploads as the wrong format. It lives here, next to the type, because two
+ * decoders now emit transcoded textures — the glTF path and the I3S path — and a
+ * private copy in each would drift silently the first time the list grew.
+ */
+export declare function gpuFormatTag(hint: GpuTextureFormatHint): number;
+/** The KHR_texture_basisu (KTX2/Basis) transcode seam, satisfied by `@bitruvius/ktx2`. */
+export interface Ktx2Transcoder {
+    /** Transcode a KTX2/Basis texture to a GPU-native format.
+     *  @param ktx2 - The KTX2 file bytes.
+     *  @param target - The desired {@link GpuTextureFormatHint} (renderer-selected).
+     *  @returns The transcoded mip levels ({@link TranscodedTexture}). */
+    transcode(ktx2: Uint8Array, target: GpuTextureFormatHint): Promise<TranscodedTexture>;
+    dispose?(): void;
+}