@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.0

package/dist/types/procedures/terrain-draping.d.ts

@@ -0,0 +1,165 @@
+import type { TerrainHeightGrid } from "../map-logic/terrain-data.js";
+import VertexLayout from "../gl/vertex_layout.js";
+import type { DrapedTerrainQueryMesh } from "../selection/draped-terrain-surface.js";
+/** Opt-in physical-height basemap displacement, independent of deck, providers and GPU ownership. */
+export interface TerrainDrapingOptions {
+    /** Non-overlapping loaded EPSG:3857 height grids; missing coverage hides geometry. */
+    grids: readonly TerrainHeightGrid[];
+    /** Previous admitted grids, sampled at the new vertices for temporal height morphing. */
+    previousGrids?: readonly TerrainHeightGrid[];
+    /** Horizontal edge target in Mercator meters; default 250, constrained by per-tile detail and vertex budgets. */
+    maxSegmentLength?: number;
+    /** Maximum additional vertices in one worker mesh; default 131072. */
+    maxAdditionalVertices?: number;
+    /** Completed interleaved vertex/index bytes per mesh; default 16 MiB. */
+    maxMeshBytes?: number;
+    /** Owned current/previous grid arrays per scene/worker, default 32 MiB. */
+    maxGridBytes?: number;
+    /** Shared height/slope interpolation duration per admitted terrain field, default 200 ms. */
+    transitionDuration?: number;
+    /** Ground style names whose exact final triangles are retained for physical queries; default empty. */
+    querySurfaceStyles?: readonly string[];
+    /** Opt-in DEM-owned ground cells per tile axis (2, 4, 8, 16, 32, 64), also conforming polygons/roads; zero keeps legacy refinement. */
+    groundMeshResolution?: number;
+    /** Previous admitted ground resolution; Renderer supplies it automatically for field replacement. */
+    previousGroundMeshResolution?: number;
+    /** Opt-in common planar refinement against previous canonical ground triangles; default false preserves arbitrary legacy previous fields. */
+    conformTransitions?: boolean;
+    /** Retained query channels per mesh, default 8 MiB; separate from completed draw bytes. */
+    maxQueryMeshBytes?: number;
+    /** Additional staged draw/query buffers across a replacement generation; default 64 MiB, excluding GPU overhead. */
+    maxStagedMeshBytes?: number;
+    /** Peak retained draw/query arrays plus estimated GPU vertex/index copies, including incumbent and staged generations; default 256 MiB. Excludes textures, driver overhead and worker scratch. */
+    maxResidentMeshBytes?: number;
+    /** Aggregate acceleration reservation for the current draped query snapshot; default 16 MiB. */
+    maxQueryIndexBytes?: number;
+    /** Retained projected picking geometry per snapshot; default 32 MiB, with exact streaming fallback. */
+    maxProjectedQueryBytes?: number;
+    /** Cooperative query-index warming target per host frame in milliseconds; default 2. */
+    queryPreparationBudgetMs?: number;
+    /** Test annotation fragments against rendered terrain and omit fully blocked collision candidates; default false. */
+    occludeAnnotations?: boolean;
+}
+/** Validated, detached physical input; typed-array contents are immutable by contract. */
+export interface TerrainDrapingSnapshot extends Required<TerrainDrapingOptions> {
+    /** Renderer-owned field epoch; unrelated scene/source rebuilds preserve this identity. */
+    transitionGeneration: number;
+    /** Exact owned height/mask array bytes; excludes structured-clone and scratch allocations. */
+    byteLength: number;
+    /** Lowest valid current/previous height for safe spherical exaggeration. */
+    minimumHeight: number;
+}
+/** Completed worker preparation cost; does not claim a total GPU/transient memory budget. */
+export interface TerrainMeshPreparation {
+    /** Original packed vertex count. */
+    inputVertices: number;
+    /** Prepared vertices, including retained originals. */
+    vertices: number;
+    /** Admitted triangle count. */
+    triangles: number;
+    /** Refined triangles conservatively removed for missing coverage. */
+    suppressedTriangles: number;
+    /** Completed interleaved vertex and index bytes. */
+    meshBytes: number;
+    /** Monotonic worker wall time for topology, sampling and mask admission. */
+    preparationMs: number;
+    /** Effective Mercator edge target; canonical ground reports its maximum admitted edge, not a certified error. */
+    edgeTarget: number;
+    /** The per-tile detail floor prevented the requested edge target. */
+    detailLimited: boolean;
+    /** Explicit source-independent ground resolution; absent on legacy polygons/ribbons/annotations. */
+    canonicalGroundResolution?: number;
+    /** Canonical cell resolution used to cut authored polygons or nominal expanded road faces. */
+    canonicalStyledResolution?: number;
+    /** Shared planar transition triangles after cutting against the previous generation's faces. */
+    transitionTriangles?: number;
+    /** View zoom whose built-in road width/offset was expanded and re-intersected in the worker. */
+    ribbonZoom?: number;
+}
+/** Resident preparation counters useful to compare detail policies on a real host. */
+export interface TerrainDrapingStatistics {
+    /** Whether displacement attributes were enabled at construction. */
+    enabled: boolean;
+    /** Owned current/previous height-array bytes per scene/worker copy. */
+    gridBytes: number;
+    /** Resident completed draped meshes, including off-screen retained tiles. */
+    meshes: number;
+    /** Resident prepared vertex count. */
+    vertices: number;
+    /** Resident admitted triangles. */
+    triangles: number;
+    /** Resident rejected no-data triangles. */
+    suppressedTriangles: number;
+    /** Resident completed worker output bytes; excludes GPU copies and scratch. */
+    meshBytes: number;
+    /** Slowest resident worker mesh preparation. */
+    maximumPreparationMs: number;
+    /** Resident meshes constrained by the per-tile detail floor. */
+    detailLimitedMeshes: number;
+    /** Retained exact ground topology and height channels, excluding lazy projected query copies. */
+    queryBytes: number;
+    /** New draw/query buffers waiting for all worker batches to complete. */
+    stagedMeshBytes: number;
+    /** Draw/query arrays plus estimated GPU vertex/index copies in both admitted and staged generations. */
+    residentMeshBytes: number;
+    /** Peak mesh-domain admission limit; source, worker scratch and driver overhead remain separate. */
+    residentMeshByteLimit: number;
+    /** Snapshot-local annotation query costs; excludes separately retained host snapshots. */
+    annotationQueries?: import("../selection/draped-terrain-surface.js").DrapedTerrainQueryStatistics;
+    /** Resident canonical road meshes, whose corners are baked at their admitted worker view zoom. */
+    ribbonMeshes?: number;
+    /** Host-driven width replacement state; failed admission preserves the last complete geometry. */
+    ribbonRefinement?: {
+        requestedZoom?: number;
+        admittedZoom?: number;
+        pending: boolean;
+        error?: string;
+    };
+}
+/** Validate and snapshot terrain before changing a scene or rebuilding workers. */
+export declare function normalizeTerrainDraping(options: TerrainDrapingOptions): TerrainDrapingSnapshot;
+/**
+ * Retain the final draw's ground channels and topology, never another DEM mesh.
+ * @param canonicalPositions - Optional exact lattice XY, avoiding source-origin reconstruction ulps at terminal bounds.
+ */
+export declare function extractDrapedTerrainQueryMesh(vertices: Uint8Array, indices: Uint16Array | Uint32Array, layout: VertexLayout, origin: readonly [number, number], tileZoom: number, byteLimit: number, canonicalPositions?: Float64Array): DrapedTerrainQueryMesh;
+/** Admit source work only where current physical heights can produce drawable geometry. */
+export declare function hasTerrainTileCoverage(grids: readonly TerrainHeightGrid[], coordinates: {
+    x: number;
+    y: number;
+    z: number;
+}): boolean;
+/** Add terrain data only after the original packed mesh has been completed. */
+export declare function getTerrainVertexLayout(original: VertexLayout): VertexLayout;
+/** Worker-side topology and samples; retains original feature/label vertex identities. */
+export declare function drapeTerrainMesh(options: {
+    /** Completed original packed vertices. */
+    vertices: Uint8Array;
+    /** Triangle topology, or an implicit non-indexed triangle list. */
+    indices: Uint16Array | Uint32Array | false;
+    /** Original layout before appending height/slope data. */
+    layout: VertexLayout;
+    /** Absolute Mercator origin of tile-local coordinates. */
+    origin: readonly [number, number];
+    /** Source tile zoom and its packed XY edge size. */
+    tileZoom: number;
+    /** Styling zoom, independent of source detail; bounds possible screen-space ribbon expansion. */
+    styleZoom?: number;
+    /** Actual host view zoom for canonical road width/offset re-intersection; defaults to style zoom. */
+    ribbonZoom?: number;
+    /** Do not refine screen-space annotation quads. */
+    annotations?: boolean;
+    /** Explicit full-tile raster ground owner; source clipping, not triangle cropping, partitions cells. */
+    ground?: boolean;
+    /** Cut polygon/line style faces against the canonical surface when groundMeshResolution is enabled. */
+    styled?: boolean;
+    /** Validated immutable current/previous heights and resource policy. */
+    terrain: TerrainDrapingSnapshot;
+}): {
+    vertices: Uint8Array;
+    indices: Uint16Array | Uint32Array;
+    byteLength: number;
+    statistics: TerrainMeshPreparation;
+    groundClip?: boolean;
+    groundPositions?: Float64Array;
+};

package/dist/types/procedures/terrain-globe.d.ts

@@ -0,0 +1,6 @@
+/** Zero-relief globe point followed by the common-space displacement per unit exaggeration. */
+export declare function createTerrainGlobePoint(coordinate: readonly [number, number], height: number, normalized?: readonly [number, number]): Float64Array;
+/** Preserve a canonical face's affine globe plane rather than projecting a new cut back onto the sphere. */
+export declare function interpolateTerrainGlobePoints(points: readonly Float64Array[], weights: ArrayLike<number>): Float64Array;
+/** Evaluate the same current/previous affine surface as the shader, with independent authored physical altitude. */
+export declare function projectTerrainGlobeVertex(channels: ArrayLike<number>, vertex: number, blend: number, exaggeration: number, coordinate: readonly [number, number, number]): [number, number, number];

package/dist/types/procedures/terrain-styled-topology.d.ts

@@ -0,0 +1,34 @@
+import type VertexLayout from "../gl/vertex_layout.js";
+/** Styled geometry and its barycentric references to the shared physical surface. */
+export interface TerrainStyledTopology {
+    /** Packed source channels interpolated only within each original feature face. */
+    vertices: Uint8Array;
+    /** Source winding/order retained; disconnected features never weld their attributes. */
+    indices: Uint32Array;
+    /** Three canonical vertex identities per output vertex. */
+    surfaceIndices: Uint32Array;
+    /** Three surface weights at the actual packed nominal XY per output vertex. */
+    surfaceWeights: Float64Array;
+}
+/** Intersect source faces with complete DEM triangles, preserving holes, walls and feature identity.
+ * Heights are interpolated from the terrain face, not resampled from a different bilinear surface.
+ * The caller owns DEM validation, physical sampling and final draw-byte admission.
+ */
+export declare function conformTerrainStyledMesh(options: {
+    /** Floating-position authored records before terrain channels are appended. */
+    vertices: Uint8Array;
+    /** Valid source triangles in authored draw order. */
+    indices: Uint16Array | Uint32Array;
+    /** Original packed attribute interpolation semantics. */
+    layout: VertexLayout;
+    /** Canonical terrain nodes in the same tile-local coordinate system. */
+    surfacePositions: Float64Array;
+    /** Counterclockwise canonical terrain triangles. */
+    surfaceIndices: Uint32Array;
+    /** Nominal expanded corner, including road width and offset. */
+    getPosition: (record: DataView) => [number, number];
+    /** Authored elevation, used to retain vertical walls rather than discarding XY degenerates. */
+    getElevation: (record: DataView) => number;
+    /** Maximum completed output vertices; a failed admission never returns partial geometry. */
+    maxVertices: number;
+}): TerrainStyledTopology;

package/dist/types/procedures/web-mercator-legacy.d.ts

@@ -0,0 +1,4 @@
+/** Project longitude/latitude degrees to Web Mercator meters using Tangram's established formula. */
+export declare function projectLngLatToMetersLegacy(coordinates: readonly [number, number]): [number, number];
+/** Unproject Web Mercator meters to longitude/latitude degrees using Tangram's established formula. */
+export declare function unprojectMetersToLngLatLegacy(coordinates: readonly [number, number]): [number, number];

package/dist/types/procedures/web-mercator-math.d.ts

@@ -0,0 +1,4 @@
+/** Project longitude/latitude degrees to Tangram Web Mercator meters using math.gl. */
+export declare function projectLngLatToMetersWithMath(coordinates: readonly [number, number]): [number, number];
+/** Unproject Tangram Web Mercator meters to longitude/latitude degrees using math.gl. */
+export declare function unprojectMetersToLngLatWithMath(coordinates: readonly [number, number]): [number, number];

package/dist/types/scene/globals.d.ts

@@ -0,0 +1,11 @@
+/** Authored globals may contain scalars, functions, arrays, or opaque application values. */
+type GlobalObject = Record<string, unknown>;
+/** Identify URL/global-reference strings while retaining omitted resource values. */
+export declare function isGlobalReference(val: string | null | undefined): boolean;
+/** Inspect substitution provenance for a named property or nested object/array path. */
+export declare function isGlobalSubstitution(object: object, prop_or_path: string | (string | number)[]): boolean;
+/** Flatten global records without discarding their original nested values. */
+export declare function flattenGlobalProperties(obj: GlobalObject, prefix?: string | null, globals?: GlobalObject): GlobalObject;
+/** Reapply globals using hidden provenance, retaining the input object's identity and type. */
+export declare function applyGlobalProperties<Value>(globals: GlobalObject, obj: Value, target?: object, key?: string | number): Value;
+export {};

package/dist/types/scene/ground_footprint.d.ts

@@ -0,0 +1,16 @@
+import type { HostCamera } from "../types.js";
+import type { Bounds } from "../utils/geo.js";
+/**
+ * Intersects all twelve edges of a finite host frustum with EPSG:3857 ground.
+ * Optional meter-space limits clip the resulting convex polygon before bounds
+ * are calculated. Null means no ground area, not an unknown footprint.
+ * Matrices use column-major OpenGL clip coordinates, also on the WebGPU path.
+ */
+export declare function calculatePlanarGroundBounds(camera: HostCamera, limits?: Bounds): Bounds | null;
+/**
+ * Bounds the finite frustum intersected with a closed elevation slab. Heights
+ * are physical meters; XY uses EPSG:3857 meters. This conservative candidate
+ * footprint includes elevated-only geometry, not terrain surface intersections.
+ * Optional horizontal limits clip the convex footprint, not its bounding box.
+ */
+export declare function calculatePlanarVolumeBounds(camera: HostCamera, elevationRange: readonly [number, number], limits?: Bounds): Bounds | null;

package/dist/types/scene/host_frame.d.ts

@@ -0,0 +1,54 @@
+import type { GeographicAnchor, HostCamera, HostFrameOptions, HostProjection, HostTileLODOptions, HostTileResourceOptions, Viewport, FeatureSelectionOptions } from "../types.js";
+/** Validated per-eye state; optional visibility overrides never change scene/style state. */
+export interface NormalizedRenderView {
+    readonly id: string;
+    readonly viewport: Required<Viewport>;
+    readonly camera: HostCamera;
+    readonly geographicAnchor?: Required<GeographicAnchor>;
+    readonly projection?: HostProjection;
+}
+/** Host-owned logical frame, shared tile visibility, and independently drawable eyes. */
+export default class HostFrame {
+    /** Resolve a full-target or view-local CSS pixel without changing the active camera. */
+    resolveSelectionPoint(pixel: {
+        x: number;
+        y: number;
+    }, options?: FeatureSelectionOptions, activeViewId?: string): {
+        view: NormalizedRenderView;
+        pixel: {
+            x: number;
+            y: number;
+        };
+    } | null;
+    /** Full target dimensions in CSS pixels; origins are top-left. */
+    readonly viewport: Required<Viewport>;
+    /** Shared geographic/style anchor in degrees, altitude meters, and Tangram zoom. */
+    readonly geographicAnchor: Required<GeographicAnchor>;
+    /** Shared geographic projection. */
+    readonly projection: HostProjection;
+    /** Per-eye camera and footprint state. */
+    readonly renderViews: readonly NormalizedRenderView[];
+    /** Default eye to draw. */
+    readonly activeRenderViewId: string;
+    /** Conservative neighboring tile buffer. */
+    readonly tileBuffer: number;
+    /** Shared data-tile level, independent of scene/style zoom, when supplied. */
+    readonly tileZoom?: number;
+    /** Validated projected-scale LOD settings, when enabled. */
+    readonly tileLOD?: Readonly<Required<HostTileLODOptions>>;
+    /** Shared opt-in worker and completed off-screen mesh cache limits. */
+    readonly tileResources?: Readonly<HostTileResourceOptions>;
+    /** Optional globally resident globe fallback level, capped at 64 coordinates per source. */
+    readonly globePreloadZoom?: number;
+    /** Shared elapsed scene animation time in seconds, when supplied. */
+    readonly animationTime?: number;
+    /** Copies and validates a host frame without retaining caller matrix arrays. */
+    constructor(options: HostFrameOptions);
+    /** Validates untrusted application input, including the original single-view shape. */
+    static from(frame: unknown): HostFrame;
+    /** Converts the original viewport/view/camera contract. */
+    static fromLegacy(frame: unknown): HostFrame;
+    /** Returns the selected eye or throws before any scene state is modified. */
+    getRenderView(id?: string): NormalizedRenderView;
+    private static createValidated;
+}

package/dist/types/scene/projection_math.d.ts

@@ -0,0 +1,52 @@
+import type { HostProjection } from "../types.js";
+/** Neutral units shared by CPU geometry, lighting, shader generation and host adapters. */
+export declare const PROJECTION_CONSTANTS: Readonly<{
+    /** EPSG:3857 spherical radius in meters; not the geographic altitude radius. */
+    mercatorRadius: 6378137;
+    /** Geographic altitude scale matching deck.gl's public GlobeViewport. */
+    earthRadius: 6370972;
+    /** Globe common-space radius; north is +Z and longitude zero is -Y. */
+    globeRadius: 256;
+    /** Tangram's reference tile size, distinct from deck's 512-unit world. */
+    tileSize: 256;
+    /** Mercator's finite square-world latitude cutoff in degrees. */
+    maxMercatorLatitude: 85.0511287798066;
+}>;
+/** Longitude/latitude in degrees and geographic altitude in meters. */
+export type GeographicProjectionPosition = readonly [number, number, number];
+/** Renderer-owned geographic boundary; cameras and tile-row conversion are separate. */
+export interface GeographicProjectionProcedure {
+    /** Existing HostFrame projection discriminator; this is not a CRS identifier. */
+    readonly type: HostProjection['type'];
+    /** Absolute position units before the host's view/placement matrices. */
+    readonly positionUnits: 'meters' | 'globe-common-units';
+    /** Maximum represented latitude in degrees, after Mercator clamping. */
+    readonly latitudeLimit: number;
+    /** Whether longitude selects a nearest anchored world copy or repeats around a sphere. */
+    readonly longitudePolicy: 'nearest-anchor-or-unwrapped' | 'periodic';
+    /** Project finite degree/degree/meter positions; an anchor affects only Mercator longitude. */
+    readonly project: (position: GeographicProjectionPosition, anchorLongitude?: number) => [number, number, number];
+    /** Invert an absolute position; globe center is undefined and longitude becomes canonical. */
+    readonly unproject: (position: readonly [number, number, number]) => [number, number, number];
+    /** Rotate an ENU direction without converting its length to common-space units. */
+    readonly projectVector: (position: GeographicProjectionPosition, direction: readonly [number, number, number]) => [number, number, number];
+}
+/** Project geography to absolute Mercator meters or globe common coordinates, never eye space. */
+export declare function projectGeographicPosition(position: GeographicProjectionPosition, projection: HostProjection['type'], anchorLongitude?: number): [number, number, number];
+/** Rotate an ENU direction into globe axes without camera transforms or changing its length. */
+export declare function projectGeographicVector(position: GeographicProjectionPosition, direction: readonly [number, number, number], projection: HostProjection['type']): [number, number, number];
+/** Invert globe common coordinates for spatial picking, rejecting the undefined sphere center. */
+export declare function unprojectGlobePosition(position: readonly [number, number, number]): [number, number, number];
+/** Style pixels in the zoom-zero Mercator convention, not perspective screen-pixel error. */
+export declare function getMercatorMetersPerPixel(zoom: number): number;
+/** Surface differential per EPSG:3857 meter for projected LOD; elevation is intentionally zero. */
+export declare function getProjectionSurface(x: number, y: number, projection: HostProjection['type']): {
+    /** Common-space ground position. */
+    position: number[];
+    /** Change in position per eastward Mercator meter. */
+    derivativeX: number[];
+    /** Change in position per northward Mercator meter. */
+    derivativeY: number[];
+};
+/** Select the existing renderer's CPU procedure and conventions for a supported HostFrame projection. */
+export declare function getGeographicProjectionProcedure(projection: HostProjection['type']): GeographicProjectionProcedure;

package/dist/types/scene/scene-resource-types.d.ts

@@ -0,0 +1,177 @@
+import type GLSL from "../gl/glsl.js";
+import type { SceneBundle } from "./scene_bundle.js";
+import type { SubscriptionMethods } from "../utils/subscribe.js";
+/** URL-backed or in-memory scene input, including class-backed editor definitions. */
+export type SceneInput = string | object;
+/** A URL-bearing resource; omitted URLs remain omitted during normalization. */
+export interface SceneResourceDefinition extends Record<string, unknown> {
+    /** Relative, absolute, blob, or global-reference URL. */
+    url?: string;
+}
+/** Source fields whose paths are normalized by the scene loader. */
+export interface SceneSourceDefinition extends SceneResourceDefinition {
+    /** Optional TileJSON metadata URL. */
+    tilejson?: string | Record<string, unknown>;
+    /** Legacy raster composite resources. */
+    composite?: SceneResourceDefinition[];
+    /** Named external scripts, or the legacy list form. */
+    scripts?: string[] | Record<string, string | undefined>;
+}
+/** A CSS-provided font, one URL face, or multiple URL faces. */
+export type SceneFontDefinition = 'external' | SceneResourceDefinition | SceneResourceDefinition[];
+/** Material channels may contain an inline texture URL or a named texture reference. */
+export type SceneMaterialChannel = number | string | number[] | {
+    texture?: string;
+    [key: string]: unknown;
+};
+/** Style fields used by resource discovery, without restricting custom shader blocks. */
+export interface SceneStyleDefinition extends Record<string, unknown> {
+    /** Named texture or inline texture URL. */
+    texture?: string;
+    /** Material channels understood by Tangram's texture collector. */
+    material?: Record<string, SceneMaterialChannel | null>;
+    /** Custom shader configuration; other shader block fields are retained. */
+    shaders?: {
+        uniforms?: Parameters<typeof GLSL.parseUniforms>[0];
+        [key: string]: unknown;
+    };
+}
+/** Draw-group fields relevant to texture discovery. */
+export interface SceneDrawDefinition extends Record<string, unknown> {
+    /** Named texture or inline texture URL. */
+    texture?: string;
+    /** Optional outline texture. */
+    outline?: SceneDrawDefinition;
+}
+/** Recursive layers combine sublayers with reserved metadata and draw groups. */
+export interface SceneLayerDefinition {
+    /** Style-named draw groups at this level. */
+    draw?: Record<string, SceneDrawDefinition>;
+    /** Sublayers and reserved fields are interpreted separately by the loader. */
+    [key: string]: unknown;
+}
+/** Loader-owned fields of an authored scene; extensions stay explicitly unknown. */
+export interface SceneDefinition extends Record<string, unknown> {
+    /** One import or an authored-order list of imports. */
+    import?: SceneInput | SceneInput[];
+    /** Data sources normalized relative to their declaring bundle. */
+    sources?: Record<string, SceneSourceDefinition>;
+    /** Fonts normalized relative to their declaring bundle. */
+    fonts?: Record<string, SceneFontDefinition>;
+    /** Named textures normalized relative to their declaring bundle. */
+    textures?: Record<string, SceneResourceDefinition>;
+    /** Custom and built-in style definitions. */
+    styles?: Record<string, SceneStyleDefinition>;
+    /** Hierarchical drawing rules. */
+    layers?: SceneLayerDefinition;
+    /** Authored globals; their values may include functions and opaque objects. */
+    global?: Record<string, unknown>;
+    /** Scene-wide settings, including explicit lighting mode. */
+    scene?: Record<string, unknown>;
+    /** Classic camera definitions; host-driven scenes retain but do not synthesize them. */
+    cameras?: Record<string, Record<string, unknown>>;
+    /** Legacy singular classic camera definition. */
+    camera?: Record<string, unknown>;
+    /** Legacy named or native luma.gl light definitions, normalized separately. */
+    lights?: SceneNamedLights | unknown[];
+}
+/** Light data stays unresolved until globals and the native-light adapter have run. */
+export type SceneNamedLights = Record<string, {
+    visible?: boolean | string;
+    type?: string;
+    [key: string]: unknown;
+}>;
+/** Settings guaranteed by scene-wide finalization, including empty native-light arrays. */
+export interface FinalizedSceneDefinition extends SceneDefinition {
+    /** Always present global registry. */
+    global: Record<string, unknown>;
+    /** Always present scene-wide settings. */
+    scene: Record<string, unknown>;
+    /** Always present camera registry, possibly empty for host cameras. */
+    cameras: Record<string, Record<string, unknown>>;
+    /** Native arrays have become named wrappers; conversion remains deferred. */
+    lights: SceneNamedLights;
+    /** Always present style registry. */
+    styles: Record<string, SceneStyleDefinition>;
+    /** Always present layer hierarchy. */
+    layers: SceneLayerDefinition;
+}
+/** Input descriptor passed between recursive scene loads. */
+export interface SceneResourceDescriptor {
+    /** Resource to load; missing archive members have no URL. */
+    url?: SceneInput;
+    /** Original resource directory, before archive URLs become blob URLs. */
+    path?: string | null;
+    /** Explicit or inferred bundle format. */
+    type?: string | null;
+}
+/** Texture provenance tracked before global substitution and hoisting. */
+export type SceneTextureNodes = Record<string, {
+    path: (string | number)[];
+    bundle: SceneBundle;
+}>;
+/** Successful load with normalized local resources and authored texture provenance. */
+export interface LoadedScene {
+    /** Merged scene data. */
+    config: SceneDefinition;
+    /** Root resource resolver. */
+    bundle: SceneBundle;
+    /** Original declaring bundle for every inline texture property. */
+    texture_nodes?: SceneTextureNodes;
+}
+/** A rejected subtree contributes no config, bundle, or texture provenance. */
+export type SceneLoadResult = LoadedScene | {
+    config?: never;
+    bundle?: never;
+    texture_nodes?: never;
+};
+/** Scene import failure with its authored URL or object attached. */
+export type SceneImportError = Error & {
+    url?: SceneInput;
+};
+/** Options shared by root loading and final camera normalization. */
+export interface SceneLoadOptions {
+    /** Override the root resource directory, such as for an edited scene. */
+    path?: string | null;
+    /** Explicit root bundle format. */
+    type?: string | null;
+    /** Leave camera ownership to Tangram or its host. */
+    cameraMode?: 'scene' | 'external';
+}
+/** Typed loader operations shared by scene startup, editor reloads, and resource tests. */
+export interface SceneLoaderAPI extends SubscriptionMethods {
+    /** Load a root scene, report failed imports, and return successful merged data. */
+    loadScene(url: SceneInput, options?: SceneLoadOptions): Promise<LoadedScene & {
+        texture_nodes: SceneTextureNodes;
+    }>;
+    /** Load an import subtree without rejecting valid sibling imports. */
+    loadSceneRecursive(resource: SceneResourceDescriptor, parent: SceneBundle | null, nodes?: SceneTextureNodes, errors?: SceneImportError[]): Promise<SceneLoadResult>;
+    /** Normalize one declaring scene before merging it with other scenes. */
+    normalize(config: SceneDefinition, bundle: SceneBundle, nodes?: SceneTextureNodes): LoadedScene;
+    /** Resolve source resource paths. */
+    normalizeDataSources(config: SceneDefinition, bundle: SceneBundle): SceneDefinition;
+    /** Resolve one source's data, metadata, composite, and script paths. */
+    normalizeDataSource(source: SceneSourceDefinition, bundle: SceneBundle): SceneSourceDefinition;
+    /** Resolve URL font faces, preserving CSS-provided fonts. */
+    normalizeFonts(config: SceneDefinition, bundle: SceneBundle): SceneDefinition;
+    /** Resolve named texture definitions. */
+    normalizeTextures(config: SceneDefinition, bundle: SceneBundle): void;
+    /** Collect inline texture provenance after named textures have been normalized. */
+    collectTextures(config: SceneDefinition, bundle: SceneBundle, nodes: SceneTextureNodes): void;
+    /** Record the declaring bundle for a nested texture property. */
+    addTextureNode(path: (string | number)[], bundle: SceneBundle, nodes: SceneTextureNodes): void;
+    /** Hoist inline texture URLs after global substitution; named textures must exist. */
+    hoistTextureNodes(config: SceneDefinition, bundle: SceneBundle, nodes?: SceneTextureNodes): void;
+    /** Substitute authored globals in merged scene data. */
+    applyGlobalProperties<Config extends SceneDefinition>(config: Config): Config;
+    /** Apply scene-wide defaults without synthesizing host-owned cameras. */
+    finalize<Bundle>(scene: {
+        config: SceneDefinition;
+        bundle: Bundle;
+    }, options?: SceneLoadOptions): {
+        config: FinalizedSceneDefinition;
+        bundle: Bundle;
+    };
+    /** Failed subtrees have no finalizable scene data. */
+    finalize(scene: SceneLoadResult, options?: SceneLoadOptions): SceneLoadResult;
+}

package/dist/types/scene/scene_bundle.d.ts

@@ -0,0 +1,69 @@
+import JSZip from 'jszip';
+import type { SceneDefinition, SceneInput, SceneResourceDescriptor } from "./scene-resource-types.js";
+/** Extracted archive member and its lazily created browser URL. */
+type SceneBundleFile = {
+    data: ArrayBuffer;
+    type: string | undefined;
+    depth: number;
+    url?: string;
+};
+type SceneBundleParent = SceneBundle | ZipSceneBundle | null;
+/** Resolve resources relative to an authored scene, including nested archive imports. */
+export declare class SceneBundle {
+    /** Scene URL or reusable in-memory definition. */
+    url: SceneInput;
+    /** Resource directory for this scene. */
+    path: string;
+    /** Authored directory used to resolve within an ancestor archive. */
+    path_for_parent: string;
+    /** Importing scene, if present. */
+    parent: SceneBundleParent;
+    /** Archive ancestor responsible for relative resources. */
+    container: SceneBundle | ZipSceneBundle | null;
+    /** Create a resource resolver without loading or validating its scene. */
+    constructor(url: SceneInput, path?: string | null, parent?: SceneBundleParent);
+    /** Load and parse URL data, or snapshot reusable object scene data. */
+    load(): Promise<SceneDefinition>;
+    /** Return the network/blob URL and authored directory/format for an import. */
+    resourceFor(url: string): SceneResourceDescriptor;
+    /** Resolve a resource URL, retaining globals and omitted URLs. */
+    urlFor(url: string | undefined): string | undefined;
+    /** Return the authored directory before archive resolution changes the URL. */
+    pathFor(url: string): string;
+    /** Infer the resource format from its authored extension. */
+    typeFor(url: string): string | undefined;
+    /** Ordinary scene files do not own an archive of resources. */
+    isContainer(): boolean;
+}
+/** ZIP scene with one root YAML member and lazy blob URLs for its resources. */
+export declare class ZipSceneBundle extends SceneBundle {
+    /** Archive parser, initialized only when loading starts. */
+    zip: JSZip | null;
+    /** Non-directory members indexed by authored archive path. */
+    files: Record<string, SceneBundleFile>;
+    /** Root YAML path selected after archive inspection. */
+    root: string | null;
+    /** Create an archive resolver; loading remains explicit. */
+    constructor(url: SceneInput, path?: string | null, parent?: SceneBundleParent);
+    /** Archive scenes own their relative resources. */
+    isContainer(): boolean;
+    /** Extract an URL-backed archive, retaining the legacy object-input fallback. */
+    load(): Promise<SceneDefinition>;
+    /** Resolve relative resources within the archive, or delegate external URLs. */
+    urlFor(url: string | undefined): string | undefined;
+    /** Infer an archive member's format without opening its blob URL. */
+    typeFor(url: string): string | undefined;
+    /** Load the unique root YAML file selected by findRoot. */
+    loadRoot(): Promise<SceneDefinition>;
+    /** Select the unique root YAML file, rejecting missing or ambiguous roots. */
+    findRoot(): void;
+    /** Extract non-directory members while retaining depth and format metadata. */
+    parseZipFiles(): Promise<void>;
+    /** Create or reuse a member's blob URL; missing members return undefined. */
+    urlForZipFile(file: string): string | undefined;
+    /** Return a member's format, or undefined when the member is absent. */
+    typeForZipFile(file: string): string | undefined;
+}
+/** Create a scene or zip bundle, inferring its path and parent when omitted. */
+export declare function createSceneBundle(url: SceneInput, path?: string | null, parent?: SceneBundleParent, type?: string | null): SceneBundle | ZipSceneBundle;
+export {};