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

package/dist/types/builders/earcut.d.ts

@@ -0,0 +1,15 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+declare module 'earcut' {
+    type EarcutResult = number[];
+
+    interface EarcutFunction {
+        (vertices: number[], holes?: number[], dimensions?: number): EarcutResult;
+        flatten(data: number[][][]): {vertices: number[]; holes: number[]; dimensions: number};
+    }
+
+    const earcut: EarcutFunction;
+    export default earcut;
+}

package/dist/types/core.d.ts

@@ -0,0 +1,29 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {ClassicWebGLRenderer as Renderer, HostFrame, LumaDeviceRenderer, WebMercatorGlobeVisibilityAdapter, WebMercatorVisibilityAdapter} from '@tangram.gl/tangram-renderer';
+export {DrapedTerrainSurfaceSnapshot} from "./selection/draped-terrain-surface.js";
+export type {TerrainDrapingOptions, TerrainDrapingStatistics} from "./procedures/terrain-draping.js";
+export type {FeatureSelectionResult, FeatureSelectionOptions} from '@tangram.gl/tangram-renderer';
+export {TerrainMeshSurface, TerrainSurfaceCollection, sampleTerrainElevation, resolveTerrainClearance, pickTerrainAt} from "./selection/terrain_surface.js";
+export type {TerrainSurface, TerrainSurfaceBounds, TerrainRay, TerrainSurfaceHit, TerrainMeshOptions, TerrainMeshStatistics, TerrainSurfaceEntry, TerrainCollectionHit, TerrainElevationProbe} from "./selection/terrain_surface.js";
+export {calculatePlanarGroundBounds, calculatePlanarVolumeBounds} from "./scene/ground_footprint.js";
+export {validateProjectedLights} from "./procedures/mesh-projector.js";
+export {normalizeProjectedBasemapOptions} from "./procedures/mesh-projector.js";
+export {getProjectedRoadUnit} from "./procedures/mesh-projector.js";
+export {countProjectedTileCoordinates, getTileGeographicBounds} from "./tile/tile_traversal_adapter.js";
+export {getProjectedCoordinateOptions, PROJECTED_COMMON_SCALE} from "./procedures/projected-coordinate-transform.js";
+export {ProjectionBatchExecutor} from './procedures/projection-batch-executor.js';
+export type {ProjectionExecutionOptions, ProjectionExecutionStatistics, ProjectionBatchRequestOptions} from './procedures/projection-batch-executor.js';
+export type {ProjectedBasemapOptions, MeshProjectionStatistics} from "./procedures/mesh-projector.js";
+export {PROJECTION_CONSTANTS, projectGeographicPosition, projectGeographicVector, unprojectGlobePosition, getGeographicProjectionProcedure} from "./scene/projection_math.js";
+export type {GeographicProjectionPosition, GeographicProjectionProcedure} from "./scene/projection_math.js";
+export {convertLumaLight, mapTangramLight} from "./lights/light-definitions.js";
+export type {ResolvedTangramLight, TangramLightMapping, TangramLight, TangramAmbientLight,
+    TangramDirectionalLight, TangramPointLight, TangramSpotLight, TangramLightExtensions,
+    TangramPositionalLightExtensions, TangramLightColor} from "./lights/light-definitions.js";
+export type {Light as LumaLight} from '@luma.gl/shadertools';
+export type {TangramTileSourceMetadata} from "./sources/tile_source_metadata.js";
+export type {HostFrameOptions, HostRenderView, HostTileLODOptions, HostTileResourceOptions, TileResourceStatistics, TileSourceStatistics, HostCamera, HostProjection, GeographicAnchor, LegacyHostFrame, RendererOptions, RenderOptions, Viewport, SceneDefinition, SceneListeners, SceneLoadOptions, VisibilityLODAdapter, GlobeVisibilityLODAdapter, VisibilityViewState, GlobeVisibilityViewState, CalculatedViewBounds} from '@tangram.gl/tangram-renderer';
+export type {ProjectionEngine, ProjectionEngineOptions, ProjectionEngineTransform} from './types.js';

package/dist/types/gl/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const gl: Record<string, number>;
+export default gl;

package/dist/types/gl/globe_mesh.d.ts

@@ -0,0 +1,48 @@
+import type VertexLayout from "./vertex_layout.js";
+type VertexAttribute = VertexLayout['dynamic_attribs'][number];
+/** Packed triangle data after projection-aware refinement. */
+export type GlobeMeshData = {
+    /** Interleaved vertices, with the original vertices retained at their original indices. */
+    vertices: Uint8Array;
+    /** Triangle indices, promoted to 32 bits when necessary. */
+    indices: Uint16Array | Uint32Array;
+};
+/** Limits for globe refinement in Tangram tile-local coordinates. */
+export type GlobeMeshOptions = {
+    /** Actual source tile zoom, not the style zoom. */
+    tileZoom: number;
+    /** Tile-local units per tile edge. */
+    tileScale?: number;
+    /** Maximum Mercator angular edge span; conservatively bounds spherical span. */
+    maxAngularSpan?: number;
+    /** Maximum additional vertices; additional triangles are limited to twice this budget. */
+    maxAdditionalVertices?: number;
+    /** Optional expanded tile-space position for packed ribbons; never changes the preserved attributes. */
+    getPosition?: (vertex: DataView) => [number, number];
+    /** Optional packed height for topology checks on elevated surfaces; curvature still uses XY. */
+    getElevation?: (vertex: DataView) => number;
+    /** Optional additional edge decision; callers must use the same criterion across adjacent meshes. */
+    shouldSplitEdge?: (first: DataView, second: DataView) => boolean;
+    /** Fan partial-edge refinements around an interior vertex instead of introducing a long diagonal. */
+    splitRemainderInterior?: boolean;
+    /** Choose the shorter green-refinement diagonal; useful for floating terrain ribbons and thin MVT faces. */
+    splitRemainderShortest?: boolean;
+};
+/**
+ * Split long triangle edges before spherical projection. Shared indexed edges share
+ * midpoints; independent tile edges use the same quantized midpoint rule. Selection
+ * IDs and layer order remain flat. Unknown varying attributes are rejected rather
+ * than guessing their interpolation semantics. Camera state is deliberately absent.
+ */
+export declare function refineGlobeMesh(vertices: Uint8Array, indices: Uint16Array | Uint32Array | false, layout: {
+    stride: number;
+    dynamic_attribs: VertexAttribute[];
+}, options: GlobeMeshOptions): GlobeMeshData;
+/** Choose the dominant source-space plane so vertical walls retain the same packed-precision checks as roofs. */
+export declare function selectTrianglePlane(points: readonly (readonly [number, number, number])[]): readonly [0 | 1 | 2, 0 | 1 | 2];
+/** Preserve Tangram's packed interpolation and flat IDs at refinement or clipping intersections. */
+export declare function interpolatePackedVertex(first: Uint8Array, second: Uint8Array, layout: {
+    stride: number;
+    dynamic_attribs: VertexAttribute[];
+}, fraction: number): Uint8Array;
+export {};

package/dist/types/gl/glsl.d.ts

@@ -0,0 +1,17 @@
+type UniformValue = number | string | boolean | number[] | string[] | number[][];
+type ParsedUniform = {
+    type: string;
+    method: string;
+    name: string;
+    value: UniformValue;
+    path: (string | number)[];
+};
+interface GLSLNamespace {
+    parseUniforms(uniforms?: Record<string, unknown>): ParsedUniform[];
+    defineVariable(name: string, value: unknown): string | undefined;
+    defineUniform(name: string, value: unknown): string | undefined;
+    expandVec3(value: UniformValue, z?: number): number[] | undefined;
+    expandVec4(value: UniformValue, w?: number): number[] | undefined;
+}
+declare const GLSL: GLSLNamespace;
+export default GLSL;

package/dist/types/gl/vertex-constants.d.ts

@@ -0,0 +1,4 @@
+/** Packed signed-short height units per physical meter, shared by builders and optional projection workers. */
+export declare const PACKED_HEIGHT_SCALE = 16;
+/** Validate physical annotation meters before signed-short storage can silently wrap. */
+export declare function packProjectedAnnotationHeight(height: unknown, allowElevation?: boolean): number;

package/dist/types/gl/vertex-types.d.ts

@@ -0,0 +1,34 @@
+import type { BufferLayout, VertexFormat } from '@luma.gl/core';
+/** Numeric views used to pack Tangram's heterogeneous interleaved vertex data. */
+export type VertexArray = Float32Array | Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array;
+/** Views of the same backing allocation indexed by legacy GL component type. */
+export type VertexBufferViews = Record<number, VertexArray>;
+/** Generated writer preserving component offsets and packed conversion semantics. */
+export type AddVertexFunction = (vertex: number[], views: VertexBufferViews, offset: number) => void;
+/** Authored attribute plus the offsets populated by VertexLayout construction. */
+export interface VertexAttribute {
+    name: string;
+    size: number;
+    type: number;
+    normalized?: boolean;
+    static?: number | number[] | null;
+    offset?: number;
+    byte_size?: number;
+    method?: `vertexAttrib${1 | 2 | 3 | 4}fv`;
+}
+/** Portable layout returned after all dynamic attribute offsets are assigned. */
+export type VertexBufferLayout = BufferLayout & {
+    attributes: {
+        attribute: string;
+        format: VertexFormat;
+        byteOffset: number;
+    }[];
+};
+/** Shader-side attribute lookup consumed by the classic binding path. */
+export interface VertexAttributeProgram {
+    attribute(name: string): {
+        location: number;
+    } | undefined;
+}
+/** Classic WebGL operations consumed by layouts; portable devices bypass this surface. */
+export type VertexAttributeContext = Pick<WebGLRenderingContext, 'enableVertexAttribArray' | 'disableVertexAttribArray' | 'vertexAttribPointer'> & Partial<Record<`vertexAttrib${1 | 2 | 3 | 4}fv`, (location: number, value: number[]) => void>>;

package/dist/types/gl/vertex_data.d.ts

@@ -0,0 +1,32 @@
+import VertexElements from "./vertex_elements.js";
+import type { VertexAttribute, AddVertexFunction, VertexBufferViews } from "./vertex-types.js";
+type VertexLayoutLike = {
+    stride: number;
+    index: Record<string, number>;
+    dynamic_attribs: VertexAttribute[];
+    getAddVertexFunction(): AddVertexFunction;
+};
+export default class VertexData {
+    static array_pool: Uint8Array[];
+    vertex_layout: VertexLayoutLike;
+    vertex_elements: VertexElements;
+    stride: number;
+    vertex_buffer: Uint8Array;
+    element_buffer: Uint16Array | Uint32Array | false;
+    byte_length: number;
+    size: number;
+    offset: number;
+    vertex_count: number;
+    realloc_count: number;
+    views: VertexBufferViews;
+    vertexLayoutAddVertex: AddVertexFunction;
+    constructor(vertex_layout: VertexLayoutLike, { prealloc }?: {
+        prealloc?: number;
+    });
+    setBufferViews(): void;
+    checkBufferSize(): void;
+    setAddVertexFunction(): void;
+    addVertex(vertex: number[]): void;
+    end(): this;
+}
+export {};

package/dist/types/gl/vertex_elements.d.ts

@@ -0,0 +1,8 @@
+export default class VertexElements {
+    static setElementIndexUint: (flag: boolean) => void;
+    array: number[];
+    has_overflown: boolean;
+    constructor();
+    push(value: number): void;
+    end(): Uint16Array | Uint32Array | false;
+}

package/dist/types/gl/vertex_layout.d.ts

@@ -0,0 +1,32 @@
+import VertexData from "./vertex_data.js";
+import type { VertexAttribute, AddVertexFunction, VertexAttributeProgram, VertexAttributeContext, VertexBufferLayout } from "./vertex-types.js";
+type VertexComponent = {
+    type: number;
+    shift: number;
+    offset: number;
+    index: number;
+};
+export default class VertexLayout {
+    static enabled_attribs: Record<string, VertexAttributeProgram>;
+    static add_vertex_funcs: Record<number, AddVertexFunction>;
+    attribs: VertexAttribute[];
+    dynamic_attribs: VertexAttribute[];
+    static_attribs: VertexAttribute[];
+    components: VertexComponent[];
+    index: Record<string, number>;
+    offset: Record<string, number>;
+    stride: number;
+    addVertex?: AddVertexFunction;
+    constructor(attribs: VertexAttribute[]);
+    enableDynamicAttributes(gl: VertexAttributeContext, program: VertexAttributeProgram): void;
+    enableStaticAttributes(gl: VertexAttributeContext, program: VertexAttributeProgram): void;
+    createVertexData(): VertexData;
+    getBufferLayout(name?: string): VertexBufferLayout;
+    getStaticAttributes(): {
+        attribute: string;
+        value: number[];
+    }[];
+    getAddVertexFunction(): AddVertexFunction;
+    createAddVertexFunction(): void;
+}
+export {};

package/dist/types/glsl.d.ts

@@ -0,0 +1,14 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+declare module '*.glsl' {
+    const source: string;
+    export default source;
+}
+
+/** Vite raw shader assets used by the real-device conformance tests. */
+declare module '*.glsl?raw' {
+    const source: string;
+    export default source;
+}

package/dist/types/gpu/luma_device_renderer.d.ts

@@ -0,0 +1,66 @@
+import { Buffer, Texture } from '@luma.gl/core';
+import type { Device, RenderPipeline, RenderPipelineParameters, RenderPass, VertexArray } from '@luma.gl/core';
+import type { TangramDrawableMesh, TangramDrawableProgram, TangramGPUBackend, TangramGPUSceneOptions, TangramMeshBufferOptions, TangramMeshDrawDescriptor, TangramMeshDrawOptions, TangramRenderStateOptions, TangramShaderOptions, TangramShaderProgramOptions, TangramTextureOptions, TangramUniformBufferOptions } from "./tangram_gpu_backend.js";
+/**
+ * Portable Tangram GPU backend implemented exclusively with the luma.gl Device API.
+ *
+ * This class deliberately never reads `device.handle`. It owns resources and draw
+ * submission while Tangram continues to own tile building and scene traversal.
+ *
+ * @implements {import('./tangram_gpu_backend').TangramGPUBackend}
+ */
+export default class LumaDeviceRenderer implements TangramGPUBackend {
+    readonly device: Device;
+    /** Shader/layout/state cache; keys do not keep scene programs alive. */
+    private pipeline_cache;
+    /** Mesh/pipeline vertex-array cache. */
+    private mesh_resource_cache;
+    /** Live program generations; released on recompilation/destruction or backend teardown. */
+    private program_resources;
+    /** Live mesh resources; released on tile eviction or backend teardown. */
+    private mesh_resources;
+    /** A destroyed backend cannot reuse cached or host resources. */
+    private destroyed;
+    /** Restore native types at the capability-only wrapper boundary, without asserting a resource facade. */
+    private readonly bindingResources;
+    constructor(device: Device);
+    /** Shader language selected by the host device. */
+    get shaderLanguage(): "glsl" | "wgsl";
+    /** Maximum supported two-dimensional texture dimension. */
+    get maxTextureSize(): number;
+    /**
+     * Returns the resource factories consumed by Tangram Scene and Style objects.
+     */
+    getSceneOptions(): TangramGPUSceneOptions;
+    /** Creates a luma.gl uniform buffer. */
+    createUniformBuffer(options: TangramUniformBufferOptions): Buffer;
+    /** Creates a shader in the language supported by the active device. */
+    createShader(options: TangramShaderOptions): import("@luma.gl/core").Shader;
+    /** Validates a device-owned shader pair when the backend supports layout-free linking. */
+    validateShaderProgram({ id, vertexShader, fragmentShader }: TangramShaderProgramOptions): void;
+    /** Creates a luma.gl vertex or index buffer. */
+    createMeshBuffer(options: TangramMeshBufferOptions): Buffer;
+    /** Creates and initializes a luma.gl texture. */
+    createTexture(options: TangramTextureOptions): Texture;
+    /** Translates normalized Tangram state into luma.gl pipeline parameters. */
+    getRenderPipelineParameters({ depthTest, depthWrite, cullFace, blend }: TangramRenderStateOptions): RenderPipelineParameters;
+    /** Draws one Tangram mesh into a host-provided luma.gl RenderPass. */
+    drawMesh({ mesh, program, renderPass, renderState, visibleTime }: TangramMeshDrawOptions): boolean;
+    /** Destroys cached pipelines, vertex arrays and uniform snapshots, not the host device. */
+    destroy(): void;
+    /** Copies mutable uniform blocks into storage unique to the encoded mesh draw. */
+    snapshotMeshUniformBindings(mesh: TangramDrawableMesh, program: TangramDrawableProgram, bindings: Record<string, object>): void;
+    /** Cache pipelines by geometry, render state and the active pass's attachment formats. */
+    getPipeline(program: TangramDrawableProgram, vertex_layout: object, descriptor: TangramMeshDrawDescriptor, render_state?: RenderPipelineParameters, renderPass?: RenderPass): RenderPipeline;
+    getVertexArray(mesh: TangramDrawableMesh, pipeline: RenderPipeline, descriptor: TangramMeshDrawDescriptor): VertexArray;
+    /** Create one cleanup generation per program without retaining the owner in a callback. */
+    private getProgramResources;
+    /** Reuse live mesh storage, and observe only the resources belonging to that mesh. */
+    private getMeshResources;
+    /** Release a mesh's cached draw resources, leaving shared program pipelines alive. */
+    private disposeMeshResources;
+    /** Invalidate dependent vertex arrays before retiring one program generation's pipelines. */
+    private disposeProgramResources;
+    /** Prevent draw-time reuse after final backend teardown. */
+    private assertAlive;
+}

package/dist/types/gpu/resource_lifecycle.d.ts

@@ -0,0 +1,4 @@
+/** Register cache cleanup for a mesh retirement or shader-resource replacement. */
+export declare function observeGPUResourceDisposal(owner: object, dispose: () => void): () => void;
+/** Drain a generation's observers, even if one fails or registers a new generation. */
+export declare function notifyGPUResourceDisposal(owner: object): void;

package/dist/types/gpu/tangram_gpu_backend.d.ts

@@ -0,0 +1,151 @@
+import type { Buffer, BufferLayout, Device, ExternalImage, RenderPass, RenderPipelineParameters, PrimitiveTopology, Shader, Texture, UniformValue } from '@luma.gl/core';
+/** Shader languages supported by Tangram's portable GPU backend. */
+export type TangramShaderLanguage = 'glsl' | 'wgsl';
+/** Options used to allocate a Tangram uniform buffer. */
+export type TangramUniformBufferOptions = {
+    id: string;
+    usage: 'uniform';
+    byteLength: number;
+};
+/** Options used to allocate a Tangram vertex or index buffer. */
+export type TangramMeshBufferOptions = {
+    id: string;
+    usage: 'vertex' | 'index';
+    data: ArrayBuffer | ArrayBufferView;
+    indexType?: 'uint16' | 'uint32';
+};
+/** Options used to compile one stage of a Tangram shader program. */
+export type TangramShaderOptions = {
+    id: string;
+    language?: TangramShaderLanguage;
+    stage: 'vertex' | 'fragment';
+    source: string;
+    entryPoint?: string;
+};
+/** Options used to validate a linked Tangram shader pair. */
+export type TangramShaderProgramOptions = {
+    id: string;
+    vertexShader: Shader;
+    fragmentShader: Shader;
+};
+/** Options used to allocate and initialize a Tangram texture. */
+export type TangramTextureOptions = {
+    id: string;
+    width: number;
+    height: number;
+    data?: ArrayBuffer | ArrayBufferView | ExternalImage;
+    filtering?: 'nearest' | 'linear' | 'mipmap';
+    repeat?: boolean;
+    flipY?: boolean;
+    premultipliedAlpha?: boolean;
+};
+/** Portable mesh submission passed from Tangram scene traversal to a GPU backend. */
+export type TangramMeshDrawOptions = {
+    mesh: TangramDrawableMesh;
+    program: TangramDrawableProgram;
+    renderPass: RenderPass;
+    renderState?: RenderPipelineParameters;
+    visibleTime: number;
+};
+/** GPU resources and layout needed to submit one portable mesh. */
+export type TangramMeshDrawDescriptor = {
+    topology: PrimitiveTopology;
+    vertexCount: number;
+    indexCount: number;
+    vertexBuffer: Buffer | null;
+    indexBuffer: Buffer | null;
+    bufferLayout: BufferLayout & {
+        attributes: NonNullable<BufferLayout['attributes']>;
+    };
+    staticAttributes: {
+        attribute: string;
+        value: readonly number[];
+    }[];
+};
+/** Scene-owned mesh state consumed by the device backend. */
+export type TangramDrawableMesh = {
+    id: string | number;
+    vertex_layout: object;
+    uniforms?: Record<string, unknown>;
+    getDrawDescriptor(): TangramMeshDrawDescriptor;
+};
+/** Mutable uniform block whose contents can be snapshotted per encoded draw. */
+export type TangramDrawableUniformBlock = {
+    snapshot_per_mesh: boolean;
+    data: ArrayBuffer | null;
+    byteLength: number;
+};
+/** Shader and uniform operations required by the device submission path. */
+export type TangramDrawableProgram = {
+    id: string | number;
+    name?: string;
+    vertex_shader_resource: Shader | null | undefined;
+    fragment_shader_resource: Shader | null | undefined;
+    uniform_blocks?: Record<string, TangramDrawableUniformBlock>;
+    saveUniforms(uniforms: Record<string, unknown>): void;
+    setUniforms(uniforms: Record<string, unknown>, resetTextureUnit: boolean): void;
+    restoreUniforms(uniforms: Record<string, unknown>): void;
+    uniform(method: string, name: string, value: number): void;
+    getBindings(): Record<string, object>;
+    getUniformValues(): Record<string, UniformValue>;
+};
+/** Tangram blend modes accepted by the portable renderer. */
+export type TangramBlendMode = false | 'opaque' | 'overlay' | 'inlay' | 'translucent' | 'add' | 'multiply';
+/** Normalized Tangram state used to create a luma.gl render pipeline. */
+export type TangramRenderStateOptions = {
+    depthTest: boolean;
+    depthWrite: boolean;
+    cullFace: boolean;
+    blend: TangramBlendMode;
+};
+/**
+ * Scene integration hooks supplied by a portable Tangram GPU backend.
+ *
+ * This compatibility shape keeps the current Scene and Style internals isolated
+ * while their individual resource wrappers are migrated to the backend contract.
+ */
+export type TangramGPUSceneOptions = {
+    enableUniformBuffers: true;
+    deviceShaderCompilation: true;
+    shaderLanguage: TangramShaderLanguage;
+    uniformBufferFactory: (options: TangramUniformBufferOptions) => Buffer;
+    shaderFactory: (options: TangramShaderOptions) => Shader;
+    shaderProgramValidator: (options: TangramShaderProgramOptions) => void;
+    meshBufferFactory: (options: TangramMeshBufferOptions) => Buffer;
+    textureFactory: (options: TangramTextureOptions) => Texture;
+    maxTextureSize?: number;
+    meshRenderer: TangramGPUBackend;
+};
+/**
+ * Renderer-independent boundary for Tangram GPU resource ownership and drawing.
+ *
+ * `LumaDeviceRenderer` is the current and only implementation. It owns the
+ * resources it creates but does not own the host device or render pass. The
+ * interface intentionally contains no deck.gl types.
+ */
+export interface TangramGPUBackend {
+    /** Host-owned luma.gl device used by this backend. */
+    readonly device: Device;
+    /** Shader language compiled by this backend. */
+    readonly shaderLanguage: TangramShaderLanguage;
+    /** Maximum supported two-dimensional texture dimension, when known. */
+    readonly maxTextureSize?: number;
+    /** Returns the compatibility hooks consumed by current Scene internals. */
+    getSceneOptions(): TangramGPUSceneOptions;
+    /** Allocates a uniform buffer. */
+    createUniformBuffer(options: TangramUniformBufferOptions): Buffer;
+    /** Allocates a vertex or index buffer. */
+    createMeshBuffer(options: TangramMeshBufferOptions): Buffer;
+    /** Compiles a shader stage. */
+    createShader(options: TangramShaderOptions): Shader;
+    /** Validates a linked shader pair. */
+    validateShaderProgram(options: TangramShaderProgramOptions): void;
+    /** Allocates and initializes a texture. */
+    createTexture(options: TangramTextureOptions): Texture;
+    /** Submits one mesh to a host-owned render pass. */
+    drawMesh(options: TangramMeshDrawOptions): boolean;
+    /** Translates Tangram state into luma.gl render-pipeline parameters. */
+    getRenderPipelineParameters(options: TangramRenderStateOptions): RenderPipelineParameters;
+    /** Releases resources owned by this backend. */
+    destroy(): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,155 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  HostFrameOptions,
+  HostRenderView,
+  LegacyHostFrame,
+  RendererOptions,
+  RenderOptions,
+  SceneDataSource,
+  SceneDefinition,
+  SceneListeners,
+  SceneLoadOptions,
+  SceneQueryOptions,
+  SceneScreenshot,
+  SceneFeature,
+  SceneUpdateOptions,
+  Viewport
+} from './types.js';
+export type {FeatureSelectionResult, FeatureSelectionOptions} from './types.js';
+export {DrapedTerrainSurfaceSnapshot} from "./selection/draped-terrain-surface.js";
+export {TerrainMeshSurface, TerrainSurfaceCollection, sampleTerrainElevation, resolveTerrainClearance, pickTerrainAt} from "./selection/terrain_surface.js";
+export type {TerrainSurface, TerrainSurfaceBounds, TerrainRay, TerrainSurfaceHit, TerrainMeshOptions, TerrainMeshStatistics, TerrainSurfaceEntry, TerrainCollectionHit, TerrainElevationProbe} from "./selection/terrain_surface.js";
+export type {
+  TangramGPUBackend,
+  TangramGPUSceneOptions,
+  TangramMeshBufferOptions,
+  TangramMeshDrawOptions,
+  TangramMeshDrawDescriptor,
+  TangramDrawableMesh,
+  TangramDrawableProgram,
+  TangramDrawableUniformBlock,
+  TangramRenderStateOptions,
+  TangramShaderLanguage,
+  TangramShaderOptions,
+  TangramShaderProgramOptions,
+  TangramTextureOptions,
+  TangramUniformBufferOptions
+} from './gpu/tangram_gpu_backend.js';
+
+export type {Matrix4, Vector3, SceneDefinition, Viewport, GeographicAnchor, HostProjection, HostCamera, HostRenderView, HostTileLODOptions, HostTileResourceOptions, TileResourceStatistics, TileSourceStatistics, HostFrameOptions, LegacyHostFrame, RendererOptions, SceneLoadOptions, SceneUpdateOptions, SceneDataSource, SceneFeature, SceneQueryOptions, SceneScreenshot, RenderOptions, SceneConfigEvent, SceneErrorEvent, SceneEventMap, SceneListener, SceneListeners, WorkerRequest, WorkerResponse, WorkerBrokerMessage} from './types.js';
+export {
+  WebMercatorGlobeVisibilityAdapter,
+  WebMercatorVisibilityAdapter
+} from './scene/visibility_adapter.js';
+export type {
+  CalculatedViewBounds,
+  GlobeVisibilityLODAdapter,
+  GlobeVisibilityViewState,
+  VisibilityLODAdapter,
+  VisibilityViewState
+} from './scene/visibility_adapter.js';
+
+import HostFrame from "./scene/host_frame.js";
+import LumaDeviceRenderer from './gpu/luma_device_renderer.js';
+export {HostFrame};
+export {LumaDeviceRenderer};
+export {calculatePlanarGroundBounds, calculatePlanarVolumeBounds} from "./scene/ground_footprint.js";
+export {convertLumaLight, mapTangramLight} from "./lights/light-definitions.js";
+export type {ResolvedTangramLight, TangramLightMapping, TangramLight, TangramAmbientLight,
+    TangramDirectionalLight, TangramPointLight, TangramSpotLight, TangramLightExtensions,
+    TangramPositionalLightExtensions, TangramLightColor, NormalizedTangramLight} from "./lights/light-definitions.js";
+export type {Light as LumaLight} from '@luma.gl/shadertools';
+export type {TangramTileSourceMetadata} from "./sources/tile_source_metadata.js";
+export type {MeshProjectionStatistics} from "./procedures/mesh-projector.js";
+export type {ProjectionExecutionOptions, ProjectionExecutionStatistics} from './procedures/projection-batch-executor.js';
+
+export declare class Scene {
+  /** Normalized animation policy read by host-driven layer integrations. */
+  config: {scene?: {animated?: boolean}} | null;
+  /** Run a synchronous operation inside the renderer's existing shared WebGL state scope. */
+  withWebGLContext<Value>(operation: () => Value): Value;
+  static create(config: SceneDefinition, options?: RendererOptions): Scene;
+  subscribe(listeners: SceneListeners): void;
+  unsubscribe(listeners: SceneListeners): void;
+  load(config?: SceneDefinition | null, options?: SceneLoadOptions): Promise<unknown>;
+  updateConfig(options?: SceneUpdateOptions): Promise<void>;
+  /** Deduplicated source/TileJSON credits; HTML must be sanitized by the displaying host. */
+  getAttributions(): Promise<string[]>;
+  /** Normalized TileJSON/archive capabilities, preserving authored source overrides. */
+  getSourceMetadata(): Promise<Record<string, import("./sources/tile_source_metadata.js").TangramTileSourceMetadata>>;
+  /** Detached decoded acquisition diagnostics from each current worker. */
+  getTileSourceStatistics(): Promise<import("./types.js").TileSourceStatistics[]>;
+  /** Detached cooperative host execution counters; absent for worker-local kernels. */
+  getProjectionEngineStatistics(): import('./procedures/projection-batch-executor.js').ProjectionExecutionStatistics | undefined;
+  /** Current-eye luma.gl definitions with exact Tangram-only shading extensions. */
+  getLumaLightDefinitions(): import("./lights/light-definitions.js").TangramLightMapping[];
+  setDataSource(name: string, config: SceneDataSource): Promise<unknown> | undefined;
+  queryFeatures(
+    options?: SceneQueryOptions
+  ): Promise<SceneFeature[] | Record<string, SceneFeature[]>>;
+  screenshot(options?: {background?: string}): Promise<SceneScreenshot>;
+  destroy(): unknown;
+}
+
+export declare class ClassicWebGLRenderer {
+  /** Synchronous nearest hit on an explicit host-owned terrain mesh, in the selected eye. */
+  getTerrainAt(pixel: {x: number; y: number}, surface?: import("./selection/terrain_surface.js").TerrainSurface,
+    options?: import("./types.js").FeatureSelectionOptions): import("./selection/terrain_surface.js").TerrainSurfaceHit | null;
+  /** Async interactive-draw selection in active-view CSS pixels; host rendering must continue. */
+  getFeatureAt(pixel: {x: number; y: number}, options?: import("./types.js").FeatureSelectionOptions): Promise<import("./types.js").FeatureSelectionResult | undefined>;
+  /** Reproject loaded meshes without replacing workers; rejects failed builds and permits subsequent recovery. */
+  setProjectedBasemapProjection(projection: import("./procedures/mesh-projector.js").ProjectedBasemapOptions): Promise<void>;
+  /** Rebuild worker terrain geometry while preserving vector source caches. */
+  setTerrain(options: import("./procedures/terrain-draping.js").TerrainDrapingOptions): Promise<void>;
+  /** Adjust visual relief without resampling or rebuilding worker geometry. */
+  setTerrainExaggeration(value: number): void;
+  /** Exact admitted ground draw topology, temporal blend and physical query channels. */
+  getDrapedTerrainSurface(): import("./selection/draped-terrain-surface.js").DrapedTerrainSurfaceSnapshot | null;
+    /** Resident worker preparation cost, excluding GPU and transient copies. */
+    getTerrainDrapingStatistics(): import("./procedures/terrain-draping.js").TerrainDrapingStatistics;
+  constructor(config: SceneDefinition, options?: RendererOptions);
+  static create(config: SceneDefinition, options?: RendererOptions): ClassicWebGLRenderer;
+  readonly scene: Scene;
+  readonly gpuBackend: LumaDeviceRenderer | null;
+  setFrame(
+    frame: HostFrame | HostFrameOptions | LegacyHostFrame,
+    options?: {renderViewId?: string}
+  ): HostFrame;
+  render(options?: RenderOptions): boolean;
+  load(config?: SceneDefinition | null, options?: SceneLoadOptions): Promise<unknown>;
+  /** Current source/TileJSON credits for the host's attribution UI. */
+  getAttributions(): Promise<string[]>;
+  /** Current source capabilities without exposing worker/archive ownership. */
+  getSourceMetadata(): Promise<Record<string, import("./sources/tile_source_metadata.js").TangramTileSourceMetadata>>;
+  /** Per-worker built-in source-procedure slots; separate from renderer mesh-build accounting. */
+  getTileSourceStatistics(): Promise<import("./types.js").TileSourceStatistics[]>;
+  /** Detached cooperative host execution counters; absent for worker-local kernels. */
+  getProjectionEngineStatistics(): import('./procedures/projection-batch-executor.js').ProjectionExecutionStatistics | undefined;
+  /** Current-eye luma.gl definitions with exact Tangram-only shading extensions. */
+  getLumaLightDefinitions(): import("./lights/light-definitions.js").TangramLightMapping[];
+  subscribe(listeners: SceneListeners): void;
+  /** Shared worker queue and completed-cache mesh bytes; excludes texture/CPU/driver memory. */
+  getTileResourceStatistics(): import('./types.js').TileResourceStatistics;
+  destroy(): unknown;
+}
+
+export declare const Renderer: typeof ClassicWebGLRenderer;
+export declare const debug: Record<string, unknown>;
+export declare const version: string;
+
+declare const Tangram: {
+  Scene: typeof Scene;
+  ClassicWebGLRenderer: typeof ClassicWebGLRenderer;
+  Renderer: typeof ClassicWebGLRenderer;
+  HostFrame: typeof HostFrame;
+  LumaDeviceRenderer: typeof LumaDeviceRenderer;
+  debug: typeof debug;
+  version: string;
+};
+
+export default Tangram;
+export type {TerrainDrapingOptions, TerrainDrapingStatistics} from "./procedures/terrain-draping.js";
+export type {ProjectionEngine, ProjectionEngineOptions, ProjectionEngineTransform} from './types.js';