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

package/src/tile/tile_pyramid.ts

@@ -0,0 +1,119 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import {TileID, type TileReference} from './tile_id';
+
+/** Resident proxy metadata; traversal references never acquire a live tile's methods. */
+type PyramidTile = TileReference & {key: string; loaded: boolean};
+/** Resident owner and count of retained descendants. */
+type PyramidEntry<Tile extends PyramidTile> = {tile?: Tile; descendants: number};
+
+export default class TilePyramid<Tile extends PyramidTile = PyramidTile> {
+    tiles: Record<string, PyramidEntry<Tile>>;
+    max_proxy_descendant_depth: number;
+    max_proxy_ancestor_depth: number;
+    children_cache: Record<string, Record<string, TileReference[]>>;
+
+    constructor() {
+        this.tiles = {};
+        this.max_proxy_descendant_depth = 6; // # of levels to search up/down for proxy tiles
+        this.max_proxy_ancestor_depth = 7;
+        this.children_cache = {}; // cache for children of coordinates
+    }
+
+    addTile(tile: Tile): void {
+        // Add target tile
+        this.tiles[tile.key] = this.tiles[tile.key] || { descendants: 0 };
+        this.tiles[tile.key].tile = tile;
+
+        // Add to parents
+        let reference: TileReference = tile;
+        while (reference.style_z >= 0) {
+            const parent = TileID.parent(reference);
+            if (!parent?.key) {
+                return;
+            }
+
+            reference = parent;
+            if (!this.tiles[parent.key]) {
+                this.tiles[parent.key] = { descendants: 0 };
+            }
+            this.tiles[parent.key].descendants++;
+        }
+    }
+
+    removeTile(tile: Tile): void {
+        // Remove target tile
+        if (this.tiles[tile.key]) {
+            delete this.tiles[tile.key].tile;
+
+            if (this.tiles[tile.key].descendants === 0) {
+                delete this.tiles[tile.key]; // remove whole tile in tree
+            }
+        }
+
+        // Decrement reference count up the tile pyramid
+        let reference: TileReference = tile;
+        while (reference.style_z >= 0) {
+            const parent = TileID.parent(reference);
+            if (!parent?.key) {
+                return;
+            }
+
+            reference = parent;
+            if (this.tiles[parent.key] && this.tiles[parent.key].descendants > 0) {
+                this.tiles[parent.key].descendants--;
+                if (this.tiles[parent.key].descendants === 0 && !this.tiles[parent.key].tile) {
+                    delete this.tiles[parent.key]; // remove whole tile in tree
+                }
+            }
+        }
+    }
+
+    // Find the parent tile for a given tile and style zoom level
+    getAncestor (tile: TileReference): Tile | undefined {
+        let level = 0;
+        while (level < this.max_proxy_ancestor_depth) {
+            const parent = TileID.parent(tile);
+            if (!parent?.key) {
+                return;
+            }
+
+            tile = parent;
+            const owner = this.tiles[parent.key]?.tile;
+            if (owner?.loaded) {
+                return owner;
+            }
+
+            level++;
+        }
+    }
+
+    // Find the descendant tiles for a given tile and style zoom level
+    getDescendants (tile: TileReference, level = 0): Tile[] {
+        const descendants: Tile[] = [];
+        if (level < this.max_proxy_descendant_depth) {
+            const tiles = TileID.children(tile, this.children_cache);
+            if (!tiles) {
+                return descendants;
+            }
+
+            tiles.forEach(t => {
+                if (t.key && this.tiles[t.key]) {
+                    const owner = this.tiles[t.key].tile;
+                    if (owner?.loaded) {
+                        descendants.push(owner);
+                    }
+                    else if (this.tiles[t.key].descendants > 0) { // didn't find any children, try next level
+                        descendants.push(...(this.getDescendants(t, level + 1) || []));
+                    }
+                }
+            });
+        }
+
+        return descendants;
+    }
+
+}

package/src/tile/tile_resource_cache.ts

@@ -0,0 +1,91 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {HostTileResourceOptions, TileResourceStatistics} from '../types';
+import {TileCachePolicy} from '../map-logic/tile-cache-policy';
+
+/** The byte-accounting surface shared by planar, globe, and pending-label meshes. */
+interface ResourceMesh {
+    /** Vertex and index allocation size, excluding textures and driver overhead. */
+    buffer_size?: number;
+    /** Independently allocated projection-specific mesh. */
+    globe_mesh?: ResourceMesh | null;
+}
+
+/** Minimal lifecycle state used by the resource policy; no GPU or host dependency. */
+export interface ResourceTile {
+    /** Source/style-normalized key. */
+    key: string;
+    /** Eye-union and fallback visibility. */
+    visible: boolean;
+    /** Worker processing is still incomplete. */
+    loading: boolean;
+    /** All mesh batches have arrived. */
+    built: boolean;
+    /** Current drawable meshes by style. */
+    meshes: Record<string, ResourceMesh[]>;
+    /** Label mesh batches waiting for collision layout. */
+    pending_label_meshes?: Record<string, ResourceMesh[]> | null;
+    /** Proxy tiles remain protected even if not explicitly visible. */
+    isProxy(): boolean;
+}
+
+/** Mesh bytes currently owned by a tile, deduplicating shared mesh references. */
+export function getTileMeshBytes(tile: ResourceTile): number {
+    const seen = new Set<ResourceMesh>();
+    let bytes = 0;
+    const addMesh = (mesh: ResourceMesh): void => {
+        if (seen.has(mesh)) return;
+        seen.add(mesh);
+        if (typeof mesh.buffer_size === 'number' && Number.isFinite(mesh.buffer_size) && mesh.buffer_size > 0) {
+            bytes += mesh.buffer_size;
+        }
+        if (mesh.globe_mesh) addMesh(mesh.globe_mesh);
+    };
+    for (const collection of [tile.meshes, tile.pending_label_meshes]) {
+        for (const meshes of Object.values(collection ?? {})) for (const mesh of meshes) addMesh(mesh);
+    }
+    return bytes;
+}
+
+/** LRU limits apply only to completed, unneeded tiles, never visible/proxy/preload work. */
+export default class TileResourceCache {
+    /** Neutral metadata policy; renderer mesh accounting stays in this adapter. */
+    private readonly policy = new TileCachePolicy();
+
+    /** Mark newly retained or currently protected tiles as recently used. */
+    touch(key: string): void { this.policy.touch(key); }
+
+    /** Remove metadata with the tile's worker and GPU resources. */
+    forget(key: string): void { this.policy.forget(key); }
+
+    /** Choose oldest completed cache entries until both opt-in limits are satisfied. */
+    selectEvictions(tiles: readonly ResourceTile[], options: HostTileResourceOptions | undefined,
+        isPreloaded: (key: string) => boolean): string[] {
+        if (options?.maxCachedTiles === undefined && options?.maxCachedMeshBytes === undefined) return [];
+        // As before, only walk mesh allocations for evictable tiles when a budget is enabled.
+        const records = tiles.filter(tile => !this.isProtected(tile, isPreloaded))
+            .map(tile => ({key: tile.key, bytes: getTileMeshBytes(tile), protected: false}));
+        return this.policy.selectEvictions(records, {maxCachedTiles: options?.maxCachedTiles,
+            maxCachedBytes: options?.maxCachedMeshBytes});
+    }
+
+    /** Detached accounting for protected residency and evictable cache separately. */
+    getStatistics(tiles: readonly ResourceTile[], isPreloaded: (key: string) => boolean,
+        builds: {activeBuilds: number; queuedBuilds: number}): TileResourceStatistics {
+        const statistics = this.policy.getStatistics(tiles.map(tile => ({key: tile.key,
+            protected: this.isProtected(tile, isPreloaded), bytes: getTileMeshBytes(tile)})));
+        return {...builds, residentTiles: statistics.residentTiles, cachedTiles: statistics.cachedTiles,
+            cachedMeshBytes: statistics.cachedBytes, protectedTiles: statistics.protectedTiles,
+            protectedMeshBytes: statistics.protectedBytes};
+    }
+
+    /** Visible union, loading work, proxy ancestors and pinned coarse tiles are never cache victims. */
+    isProtected(tile: ResourceTile, isPreloaded: (key: string) => boolean): boolean {
+        return tile.visible || tile.loading || !tile.built || tile.isProxy() || isPreloaded(tile.key);
+    }
+
+    /** Clear residency metadata on renderer teardown. */
+    clear(): void { this.policy.clear(); }
+}

package/src/tile/tile_traversal_adapter.ts

@@ -0,0 +1,132 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import Geo from '../utils/geo';
+import type {HostProjection} from '../types';
+import type {TileCoordinate, TileCoordinates} from './tile_id';
+import type {GlobeVisibilityLODAdapter, VisibilityLODAdapter, VisibilityViewState} from '../scene/visibility_adapter';
+import {WebMercatorVisibilityAdapter} from '../scene/visibility_adapter';
+
+/** Count a finite CPU-projected footprint at data detail 0–6 without allocating tile coordinates.
+ * Uses the same XYZ endpoint and single-world clamping rules as actual traversal.
+ * This is a per-source candidate count, not a total across multiple sources.
+ */
+export function countProjectedTileCoordinates(bounds: readonly [number, number, number, number], tileZoom: number): number {
+    if (!Array.isArray(bounds) || bounds.length !== 4 || !Array.from(bounds).every(Number.isFinite) || bounds[0] < -180 || bounds[2] > 180 ||
+        bounds[0] > bounds[2] || bounds[1] > bounds[3] || bounds[1] < -85.0511287798066 || bounds[3] > 85.0511287798066 ||
+        !Number.isSafeInteger(tileZoom) || tileZoom < 0 || tileZoom > 6) {
+        throw new Error('Projected tile count requires finite single-world bounds and integer detail 0–6');
+    }
+    const southwest = Geo.latLngToMeters([bounds[0], bounds[1]]);
+    const northeast = Geo.latLngToMeters([bounds[2], bounds[3]]);
+    return new WebMercatorVisibilityAdapter().countTileCoordinates({
+        center: {lng: 0, lat: 0}, zoom: tileZoom, tile_zoom: tileZoom,
+        size: {css: {width: 1, height: 1}}, buffer: 0, wrap: false,
+        bounds: {sw: {x: southwest[0], y: southwest[1]}, ne: {x: northeast[0], y: northeast[1]}}
+    });
+}
+
+/** Geographic XYZ tile bounds; an unwrapped world copy retains its longitude offset. */
+export interface GeographicTileBounds {
+    /** Western longitude in degrees. */
+    west: number;
+    /** Southern latitude in degrees. */
+    south: number;
+    /** Eastern longitude in degrees. */
+    east: number;
+    /** Northern latitude in degrees. */
+    north: number;
+}
+
+/** One host eye's traversal inputs, independent of deck.gl viewport classes. */
+export interface TangramTraversalEye {
+    /** Geographic view state with style and data zoom kept distinct. */
+    readonly view: VisibilityViewState;
+    /** Projection and footprint policy. */
+    readonly projection: HostProjection;
+    /** Optional globe/common-space camera position. */
+    readonly position?: ArrayLike<number>;
+    /** Host eyes need independent bounds; classic views already have calculated bounds. */
+    readonly calculateBounds?: boolean;
+    /** Projected LOD overrides per-eye automatic detail, never style zoom. */
+    readonly dataZoom?: number;
+}
+
+/** Shared logical traversal state; stereo consumers contribute an eye union. */
+export interface TangramTraversalState {
+    /** Empty until the view is ready. */
+    readonly eyes: readonly TangramTraversalEye[];
+    /** Host render-view collections deduplicate even a single eye; classic ordering remains unchanged. */
+    readonly union?: boolean;
+}
+
+/** Structured geographic bounds suitable for both Tangram and loaders.gl adapters. */
+export function getTileGeographicBounds(index: TileCoordinates): GeographicTileBounds {
+    const northwest = Geo.metersForTile(index);
+    const southeast = Geo.metersForTile({x: index.x + 1, y: index.y + 1, z: index.z});
+    const [west, north] = Geo.metersToLatLng([northwest.x, northwest.y]);
+    const [east, south] = Geo.metersToLatLng([southeast.x, southeast.y]);
+    return {west, south, east, north};
+}
+
+/**
+ * Traversal seam structurally compatible with loaders.gl Tileset2DAdapter.
+ * Tangram owns footprint/LOD inputs; source normalization and fallback pinning remain separate.
+ */
+export default class TangramTileTraversalAdapter {
+    /** Existing planar/FirstPerson visibility implementation. */
+    private readonly planar: VisibilityLODAdapter;
+    /** Existing curved globe/horizon visibility implementation. */
+    private readonly globe: GlobeVisibilityLODAdapter;
+
+    /** Bind the unchanged projection-specific selection procedures. */
+    constructor(planar: VisibilityLODAdapter, globe: GlobeVisibilityLODAdapter) {
+        this.planar = planar;
+        this.globe = globe;
+    }
+
+    /** Select the same logical data tiles before source sparse-zoom/overzoom normalization. */
+    getTileIndices({viewState}: {viewState: TangramTraversalState}): TileCoordinate[] {
+        if (viewState.eyes.length === 1 && !viewState.union) return this.selectEye(viewState.eyes[0]);
+        const coordinates = new Map<string, TileCoordinate>();
+        for (const eye of viewState.eyes) for (const coordinate of this.selectEye(eye)) {
+            coordinates.set(coordinate.key ?? `${coordinate.x}/${coordinate.y}/${coordinate.z}`, coordinate);
+        }
+        return Array.from(coordinates.values());
+    }
+
+    /** Geographic tile metadata, with XYZ's north-down Y convention preserved. */
+    getTileBoundingBox(_context: {viewState: TangramTraversalState}, index: TileCoordinates): GeographicTileBounds {
+        return getTileGeographicBounds(index);
+    }
+
+    /** Original per-eye projection dispatch and explicit footprint handling. */
+    private selectEye(eye: TangramTraversalEye): TileCoordinate[] {
+        let state = eye.view;
+        if (eye.calculateBounds) {
+            const bounds = this.planar.calculateBounds(state);
+            state = {...state, bounds: bounds.bounds, tile_zoom: eye.dataZoom ?? bounds.tileZoom};
+        }
+        const projection = eye.projection;
+        if (projection.type === 'globe') {
+            return this.globe.findVisibleTileCoordinates({tile_zoom: state.tile_zoom, buffer: state.buffer,
+                visibleBounds: projection.visibleBounds,
+                ...(projection.maxElevation === undefined ? {} : {maxElevation: projection.maxElevation}),
+                cameraPosition: eye.position ? [eye.position[0], eye.position[1], eye.position[2]] : undefined});
+        }
+        if (projection.visibleBounds !== undefined) {
+            const bounds = projection.visibleBounds;
+            if (bounds === null) return [];
+            const southwest = Geo.latLngToMeters([bounds[0], bounds[1]]);
+            const northeast = Geo.latLngToMeters([bounds[2], bounds[3]]);
+            if (!southwest.every(Number.isFinite) || !northeast.every(Number.isFinite)) {
+                throw new Error('HostFrame planar visibleBounds must project to finite meters');
+            }
+            state = {...state, bounds: {sw: {x: southwest[0], y: southwest[1]}, ne: {x: northeast[0], y: northeast[1]}}};
+        }
+        // CPU-projected scenes represent one finite tile world, never wrapped copies.
+        return this.planar.findVisibleTileCoordinates(projection.type === 'projected' ? {...state, wrap: false} : state);
+    }
+}

package/src/types.ts

@@ -0,0 +1,332 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device, RenderPass} from '@luma.gl/core';
+import type {DecodedTileStatistics} from './sources/decoded_tile_store';
+import type {
+  GlobeVisibilityLODAdapter,
+  VisibilityLODAdapter
+} from './scene/visibility_adapter.js';
+
+export type Matrix4 = readonly number[] | Float32Array | Float64Array;
+export type Vector3 = readonly [number, number, number];
+export type SceneDefinition = string | Record<string, unknown> | readonly SceneDefinition[];
+
+/** Minimal CRS options accepted by a caller-owned math.gl-compatible projection factory. */
+export interface ProjectionEngineOptions {
+  /** Source CRS, supplied by Tangram as geographic degrees. */
+  from?: string;
+  /** Destination CRS, supplied by Tangram as north-positive projected meters. */
+  to?: string;
+}
+
+/** Compiled projection surface used for packed worker mesh coordinates. */
+export interface ProjectionEngineTransform {
+  /** Project packed coordinates in place, preserving their typed-array representation. */
+  projectFlatSync(coordinates: Float64Array, dimension?: number): Float64Array;
+}
+
+/** Structural subset of math.gl's factory; ordinary consumers need not install the optional peer. */
+export interface ProjectionEngine {
+  /** Compile an independent transform synchronously. */
+  createProjection(options?: ProjectionEngineOptions): ProjectionEngineTransform;
+  /** Compile a transform after loading any registered lazy projection implementations. */
+  createProjectionAsync(options?: ProjectionEngineOptions): Promise<ProjectionEngineTransform>;
+}
+
+export type Viewport = {
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+};
+
+export type GeographicAnchor = {
+  longitude: number;
+  latitude: number;
+  altitude?: number;
+  zoom: number;
+};
+
+/** Geographic projection used by host-provided positions and camera matrices. */
+export type HostProjection =
+    | {
+      /** Worker-projected flat common coordinates; requires an explicit geographic footprint. */
+      type: 'projected';
+      /** Ordered unwrapped footprint in degrees; tile selection remains Web Mercator XYZ. */
+      visibleBounds: readonly [number, number, number, number];
+    }
+  | {
+      type: 'web-mercator';
+      /** Explicit unwrapped geographic footprint; null means no visible ground, omitted uses camera/legacy bounds. */
+      visibleBounds?: readonly [number, number, number, number] | null;
+    }
+  | {
+      type: 'globe';
+      /** Conservative footprint enclosing ground and elevated content: west, south, east, north. */
+      visibleBounds: readonly [number, number, number, number];
+      /**
+       * Conservative maximum rendered elevation in geographic meters above the reference sphere.
+       * Zero declares a surface-only scene. Omitted means unknown and disables horizon rejection.
+       * Includes terrain, extrusion, offsets and shader displacement; never inferred from camera altitude.
+       */
+      maxElevation?: number;
+    };
+
+export type HostCamera = {
+  view: Matrix4;
+  projection: Matrix4;
+  position: Vector3;
+};
+
+export type HostRenderView = {
+  id?: string;
+  viewport?: Viewport;
+  camera: HostCamera;
+  /** Optional per-eye footprint anchor; scene/style state still uses the shared anchor. */
+  geographicAnchor?: GeographicAnchor;
+  /** Optional per-eye geographic bounds for union visibility. */
+  projection?: HostProjection;
+};
+
+/** Opt-in uniform data LOD estimated from projected surface scale across all eyes. */
+export type HostTileLODOptions = {
+  /** Target projected tile edge in device pixels; defaults to 512. */
+  targetTilePixels?: number;
+  /** Device pixels per viewport CSS pixel; defaults to 1. */
+  pixelRatio?: number;
+  /** Buffered candidate visits across eyes, before deduplication; defaults to 256. */
+  maxTiles?: number;
+  /** Zoom-level dead band around transitions; defaults to 0.2. */
+  hysteresis?: number;
+};
+
+/** Opt-in worker scheduling and completed off-screen mesh cache limits, shared by all eyes. */
+export type HostTileResourceOptions = {
+  /** Maximum concurrently submitted tile builds across sources; positive integer, omitted is unlimited. */
+  maxConcurrentBuilds?: number;
+  /** Maximum completed off-screen cache entries; non-negative integer, omitted is unlimited. */
+  maxCachedTiles?: number;
+  /** Cached vertex/index bytes, including globe variants and pending labels; non-negative integer. */
+  maxCachedMeshBytes?: number;
+};
+
+/** Detached renderer resource accounting; textures, CPU data and driver overhead are not included. */
+export type TileResourceStatistics = {
+  /** Tile builds submitted to workers, not individual network requests. */
+  activeBuilds: number;
+  /** Source/style tile builds waiting for a scheduling slot. */
+  queuedBuilds: number;
+  /** All retained tiles, including visible/proxy/preload and incomplete builds. */
+  residentTiles: number;
+  /** Completed tiles eligible for cache eviction. */
+  cachedTiles: number;
+  /** Vertex/index bytes owned by evictable tiles. */
+  cachedMeshBytes: number;
+  /** Tiles protected from resource-policy eviction. */
+  protectedTiles: number;
+  /** Vertex/index bytes owned by protected tiles. */
+  protectedMeshBytes: number;
+};
+
+/** Worker-local decoded acquisition accounting, separate from scene-wide mesh-build statistics. */
+export type TileSourceStatistics = DecodedTileStatistics & {
+  /** Index of the worker in the scene's current worker pool. */
+  workerId: number;
+  /** False for workers with external source scripts; custom pipelines always bypass sharing. */
+  sharingEnabled: boolean;
+  /** Present only for the opt-in projected worker; separate from decoded-source and GPU residency. */
+  projectionPreparation?: import('./procedures/mesh-projector').MeshPreparationStatistics;
+  /** Optional cumulative CPU projection/refinement work, reset when the worker source lifecycle resets. */
+  projectionWork?: import('./procedures/mesh-projector').MeshProjectionStatistics;
+};
+
+/** CSS-pixel query coordinates and view routing for asynchronous feature selection. */
+export interface FeatureSelectionOptions {
+  /** Non-negative CSS-pixel search radius. */
+  radius?: number;
+  /** Explicit eye/view identity; omitted canvas queries choose the last overlapping view. */
+  renderViewId?: string;
+  /** Default view-local pixels, or full-target top-origin CSS pixels for stereo routing. */
+  coordinateSpace?: 'view' | 'canvas';
+}
+
+/** Asynchronous selection of a built-in worker feature or an application-defined payload. */
+export type FeatureSelectionResult = {
+  /** Cloneable metadata from the worker; null/undefined means no hit. */
+  feature?: unknown;
+  /** Whether the selected feature differs from the previous completed query. */
+  changed?: boolean;
+  /** Caller-requested top-origin CSS pixel, in the selected coordinate space. */
+  pixel?: {x: number; y: number};
+  /** View/eye used for the query; pixel remains in the caller's requested coordinate space. */
+  renderViewId?: string;
+  /** Readback, cancellation or worker failure, preserving Scene's result contract. */
+  error?: unknown;
+};
+
+export type HostFrameOptions = {
+  viewport: Viewport;
+  geographicAnchor: GeographicAnchor;
+  projection?: HostProjection;
+  renderViews: readonly HostRenderView[];
+  activeRenderViewId?: string;
+  tileBuffer?: number;
+  /** Optional shared data-tile zoom (integer 0–22, no higher than the shared style zoom). */
+  tileZoom?: number;
+  /** Automatic shared data LOD; mutually exclusive with tileZoom. */
+  tileLOD?: HostTileLODOptions;
+  /** Opt-in scheduling/cache policy shared by every render view and source. */
+  tileResources?: HostTileResourceOptions;
+  /** Retain a global coarse level for globe loading gaps; integer 0–3, omitted disables preloading. */
+  globePreloadZoom?: number;
+  /** Shared elapsed scene animation time in seconds. */
+  animationTime?: number;
+};
+
+export type LegacyHostFrame = {
+  viewport: Viewport;
+  view: GeographicAnchor;
+  projection?: HostProjection;
+  camera: HostCamera;
+  tileBuffer?: number;
+  /** Optional shared data-tile zoom; omission preserves zoom-driven selection. */
+  tileZoom?: number;
+  /** Opt-in projected-scale data LOD. */
+  tileLOD?: HostTileLODOptions;
+  /** Opt-in scheduling/cache policy; omission restores unlimited scheduling/cache defaults. */
+  tileResources?: HostTileResourceOptions;
+  /** Optional bounded global globe fallback level, integer 0–3. */
+  globePreloadZoom?: number;
+  /** Shared elapsed scene animation time in seconds. */
+  animationTime?: number;
+};
+
+export type RendererOptions = {
+  /** Opt-in worker-side physical terrain displacement; provider loading remains host-owned. */
+  terrain?: import('./procedures/terrain-draping').TerrainDrapingOptions;
+  /** Optional application-owned admission pool shared with terrain source/preparation owners. Captured at creation; never sent to workers. */
+  terrainResourceBudget?: import('./map-logic/terrain-resource-budget').TerrainResourceBudget;
+  /** Optional caller-owned CRS factory for CPU-projected basemaps; ordinary Mercator/globe cameras are unchanged. */
+  projectionEngine?: ProjectionEngine;
+  /** Host kernel chunking policy; captured at renderer creation and independent of worker/build budgets. */
+  projectionEngineExecution?: import('./procedures/projection-batch-executor').ProjectionExecutionOptions;
+  device?: Device;
+  /** Optional worker script URL; otherwise the package uses its embedded worker. */
+  workerURL?: string;
+  /** Renderer-owned policy for viewport bounds and tile visibility/LOD. */
+  visibilityAdapter?: VisibilityLODAdapter;
+  /** Renderer-owned policy for selecting tiles for globe projection bounds. */
+  globeVisibilityAdapter?: GlobeVisibilityLODAdapter;
+  canvas?: HTMLCanvasElement | OffscreenCanvas;
+  requestRedraw?: () => void;
+  numWorkers?: number;
+  /** Positive safe integer limit for shared built-in tile loads in each worker; omitted is unlimited. */
+  maxConcurrentTileLoadsPerWorker?: number;
+  logLevel?: import('./utils/log').LogLevel;
+  highDensityDisplay?: boolean;
+  introspection?: boolean;
+  [option: string]: unknown;
+};
+
+export type SceneLoadOptions = {
+  base_path?: string;
+  file_type?: string;
+  blocking?: boolean;
+  [option: string]: unknown;
+};
+
+export type SceneUpdateOptions = {
+  loading?: boolean;
+  rebuild?: boolean | Record<string, unknown>;
+  serialize_funcs?: boolean;
+  texture_nodes?: import('./scene/scene-resource-types').SceneTextureNodes;
+  normalize?: boolean;
+  fade_in?: boolean;
+};
+
+export type SceneDataSource = {
+  type: string;
+  /** Required provider credit HTML for the host to display safely. */
+  attribution?: string;
+  url?: string;
+  tilejson?: string | Record<string, unknown>;
+  data?: unknown;
+  [property: string]: unknown;
+};
+
+export type SceneFeature = {
+  id?: string | number;
+  properties: Record<string, unknown>;
+  geometry?: Record<string, unknown>;
+  [property: string]: unknown;
+};
+
+export type SceneQueryOptions = {
+  filter?: unknown;
+  unique?: boolean | string | readonly string[];
+  group_by?: string | readonly string[] | null;
+  visible?: boolean | null;
+  geometry?: boolean;
+};
+
+export type SceneScreenshot = {
+  url: string;
+  blob: Blob;
+  type: 'png';
+};
+
+export type RenderOptions = {
+  frame?: HostFrameOptions | LegacyHostFrame;
+  renderPass?: RenderPass | null;
+  renderViewId?: string;
+  force?: boolean;
+};
+
+export type SceneConfigEvent = {config: Record<string, unknown>};
+export type SceneErrorEvent = {
+  type?: string;
+  message?: string;
+  error?: unknown;
+  [property: string]: unknown;
+};
+
+export type SceneEventMap = {
+  load: [event: SceneConfigEvent];
+  update: [event: SceneConfigEvent];
+  pre_update: [willRender: boolean];
+  post_update: [willRender: boolean];
+  view_complete: [event: {first: boolean}];
+  error: [event: SceneErrorEvent];
+  warning: [event: SceneErrorEvent];
+  move: [];
+};
+
+export type SceneListener<EventName extends keyof SceneEventMap = keyof SceneEventMap> = (
+  ...arguments_: SceneEventMap[EventName]
+) => void;
+
+export type SceneListeners = {
+  [EventName in keyof SceneEventMap]?: SceneListener<EventName>;
+} & {
+  [event: string]: ((...arguments_: never[]) => void) | undefined;
+};
+
+export type WorkerRequest<Message = unknown> = {
+  type: 'main_send' | 'worker_send';
+  message_id: number;
+  method: string;
+  message: Message;
+};
+
+export type WorkerResponse<Message = unknown> = {
+  type: 'main_reply' | 'worker_reply';
+  message_id: number;
+  message?: Message;
+  error?: string;
+};
+
+export type WorkerBrokerMessage<Message = unknown> =
+  | WorkerRequest<Message>
+  | WorkerResponse<Message>;