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

package/dist/types/lights/light-definitions.d.ts

@@ -0,0 +1,121 @@
+import type { AmbientLight, DirectionalLight, PointLight, SpotLight } from '@luma.gl/shadertools';
+/** An RGB contribution or position, copied at the adapter boundary. */
+type Triple = readonly [number, number, number];
+/** Tangram's normalized RGB/RGBA, CSS color, or scalar lighting contribution. */
+export type TangramLightColor = number | string | Triple | readonly [number, number, number, number];
+/** Optional Tangram shading controls layered on native luma.gl light definitions. */
+export interface TangramLightExtensions {
+    /** Independent normalized ambient contribution; defaults to the native light contribution. */
+    ambient?: TangramLightColor;
+    /** Independent normalized diffuse contribution; defaults to the native light contribution. */
+    diffuse?: TangramLightColor;
+    /** Independent normalized specular contribution; defaults to the native light contribution. */
+    specular?: TangramLightColor;
+    /** Suppress this light without removing its authored definition. */
+    visible?: boolean;
+}
+/** Optional positional falloff and coordinate controls; native coefficients remain `attenuation`. */
+export interface TangramPositionalLightExtensions extends TangramLightExtensions {
+    /** Legacy exponent falloff, multiplied by the native polynomial attenuation. */
+    attenuationExponent?: number;
+    /** Legacy outer radius, or [inner, outer] radii, accepting Tangram meter/pixel units. */
+    radius?: number | string | readonly [number | string | null, number | string];
+    /** Optional legacy position interpretation; omitted means projected common-space coordinates. */
+    origin?: 'world' | 'ground' | 'camera';
+    /** Interpret native position as longitude/latitude/altitude rather than projected common coordinates. */
+    positionSpace?: 'common' | 'geographic';
+    /** Geographic spotlight orientation; defaults to ENU when positionSpace is geographic. */
+    directionSpace?: 'common' | 'enu';
+}
+/** Native ambient light with optional independent Tangram color contributions. */
+export type TangramAmbientLight = AmbientLight & TangramLightExtensions;
+/** Native directional light with optional independent Tangram color contributions. */
+export type TangramDirectionalLight = DirectionalLight & TangramLightExtensions;
+/** Native point light with optional Tangram color, falloff, and coordinate controls. */
+export type TangramPointLight = PointLight & TangramPositionalLightExtensions;
+/** Native spotlight with optional Tangram falloff inside its native radian cone. */
+export type TangramSpotLight = SpotLight & TangramPositionalLightExtensions & {
+    /** Legacy cosine falloff exponent, multiplied by the native cone transition; defaults to zero. */
+    spotExponent?: number;
+};
+/** Every native luma.gl Light is assignable; all Tangram additions are optional. */
+export type TangramLight = TangramAmbientLight | TangramDirectionalLight | TangramPointLight | TangramSpotLight;
+/** Native descriptors after defaults, vectors, attenuation and spot cones have been validated. */
+export type NormalizedTangramLight = (Omit<TangramAmbientLight, 'color' | 'intensity'> | Omit<TangramDirectionalLight, 'color' | 'intensity'> | (Omit<TangramPointLight, 'color' | 'intensity' | 'attenuation'> & {
+    attenuation: Triple;
+}) | (Omit<TangramSpotLight, 'color' | 'intensity' | 'attenuation' | 'innerConeAngle' | 'outerConeAngle'> & {
+    attenuation: Triple;
+    innerConeAngle: number;
+    outerConeAngle: number;
+})) & {
+    color: Triple;
+    intensity: number;
+};
+/** Resolved Tangram light values, after color, unit and camera conversion. */
+export interface ResolvedTangramLight {
+    /** Tangram's spotlight discriminator differs from luma.gl's `spot`. */
+    type: 'ambient' | 'directional' | 'point' | 'spotlight';
+    /** Linear RGB ambient contribution. */
+    ambient: Triple;
+    /** Linear RGB diffuse contribution. */
+    diffuse: Triple;
+    /** Linear RGB specular contribution. */
+    specular: Triple;
+    /** Position in the same eye-relative lighting space as the rendered surface. */
+    position?: Triple;
+    /** Incoming direction in the surface normal's lighting space. */
+    direction?: Triple;
+    /** Tangram's distance exponent, not luma.gl's polynomial coefficients. */
+    attenuation?: number;
+    /** Tangram's resolved inner/outer radii, in lighting-space units. */
+    radius?: readonly [number | null, number];
+    /** Tangram spotlight cutoff in degrees. */
+    angle?: number;
+    /** Tangram spotlight falloff exponent. */
+    exponent?: number;
+}
+/** A luma.gl light plus the Tangram-only data required for lossless shading. */
+export interface TangramLightMapping {
+    /** Luma.gl-compatible byte RGB and resolved coordinates, with optional Tangram controls. */
+    light: TangramLight;
+    /** Positions are resolved lighting coordinates, not geographic longitude/latitude. */
+    coordinateSpace: 'tangram-lighting';
+    /** Exact legacy contributions and falloff; consumers must not silently discard them. */
+    tangram: ResolvedTangramLight;
+}
+/** Configuration produced for Tangram's existing shader composer from a native luma.gl light. */
+export interface LumaLightConfig {
+    /** Tangram shader discriminator. */
+    type: ResolvedTangramLight['type'];
+    /** Linear ambient RGB. */
+    ambient: TangramLightColor;
+    /** Linear diffuse RGB. */
+    diffuse: TangramLightColor;
+    /** Linear specular RGB. */
+    specular: TangramLightColor;
+    /** Independent copy of the native light, used for native falloff and coordinates. */
+    lumaLight: NormalizedTangramLight;
+    /** Native common space by default, or an explicitly selected legacy position interpretation. */
+    origin: 'luma' | 'world' | 'ground' | 'camera';
+    /** Native projected position. */
+    position?: Triple;
+    /** Native incoming direction. */
+    direction?: Triple;
+    /** Tangram exponent, kept separate from the native polynomial coefficient vector. */
+    attenuation?: number;
+    /** Copied legacy radius configuration for the existing unit resolver. */
+    radius?: TangramPositionalLightExtensions['radius'];
+    /** Tangram spotlight exponent. */
+    exponent?: number;
+}
+/** Convert resolved Tangram data without pretending legacy falloff or separate colors are equivalent. */
+export declare function mapTangramLight(resolved: Omit<ResolvedTangramLight, 'ambient' | 'diffuse' | 'specular'> & {
+    ambient: readonly number[];
+    diffuse: readonly number[];
+    specular: readonly number[];
+}): TangramLightMapping;
+/** Translate a native luma.gl light while retaining its polynomial attenuation and radian cones. */
+export declare function convertLumaLight(input: TangramLight): LumaLightConfig;
+/** Wrap native arrays without validation so scene globals resolve before Light.create converts them. */
+export declare function normalizeSceneLights(lights: unknown): unknown;
+export {};

package/dist/types/map-logic/draped-terrain-bounds.d.ts

@@ -0,0 +1,41 @@
+/** Immutable worker query channels; no scene, GPU, provider or query-index ownership. */
+interface DrapedTerrainBoundsInput {
+    /** Absolute Mercator XYZ, with authored offsets in meters. */
+    positions: Float64Array;
+    /** Current/previous physical DEM heights, interleaved per vertex. */
+    heights: Float32Array;
+    /** Optional current/previous affine globe bases and relief vectors, twelve channels per vertex. */
+    globeBasis?: Float32Array;
+    /** Actual rendered triangle indices. */
+    indices: Uint16Array | Uint32Array;
+    /** Optional trusted worker summary of these exact immutable channels. */
+    boundsSummary?: DrapedTerrainBoundsSummary;
+}
+/** Independent channel extrema enclose every convex rendered triangle throughout its height morph. */
+export interface DrapedTerrainBoundsSummary {
+    /** Radius-one globe directions of indexed vertices, not geographic rectangle corners. */
+    directions: {
+        minimum: [number, number, number];
+        maximum: [number, number, number];
+    };
+    /** Authored meter offsets, independent of relief exaggeration. */
+    offsets: readonly [number, number];
+    /** Physical current/previous DEM endpoints, conservatively enclosing all morph fractions. */
+    heights: readonly [number, number];
+    /** Affine globe channels enclose canonical face cuts without projecting them back onto the sphere. */
+    globe?: {
+        /** Zero-relief common-space endpoint extrema. */
+        base: {
+            minimum: number[];
+            maximum: number[];
+        };
+        /** Common-space displacement per unit exaggeration. */
+        relief: {
+            minimum: number[];
+            maximum: number[];
+        };
+    };
+}
+/** Compute bounds from the actual indexed vertices so long globe chords and unwrapped tiles remain enclosed. */
+export declare function summarizeDrapedTerrainBounds(mesh: DrapedTerrainBoundsInput): DrapedTerrainBoundsSummary;
+export {};

package/dist/types/map-logic/globe-terrain-preparation.d.ts

@@ -0,0 +1,85 @@
+import { type GlobeTerrainMeshTemplate } from "./globe-terrain.js";
+import type { TerrainHeightGrid } from "./terrain-data.js";
+import type { TerrainResourceBudget } from "./terrain-resource-budget.js";
+/** Complete, immutable neighborhood generation; only library-produced handles can resolve templates. */
+export interface GlobeTerrainPreparationSnapshot {
+    /** Ordered immutable source identities; applications must not mutate their samples. */
+    readonly grids: readonly TerrainHeightGrid[];
+    /** Uniform curved-cell resolution for all stitched tiles. */
+    readonly resolution: number;
+    /** Owned prepared typed arrays, excluding source, display/query buffers and GPU allocations. */
+    readonly byteLength: number;
+}
+/** Validate library ownership, including empty snapshots whose templates cannot be looked up. */
+export declare function assertGlobeTerrainPreparationSnapshot(snapshot: GlobeTerrainPreparationSnapshot): void;
+/** Resolve only a source identity belonging to a completed preparation generation. */
+export declare function getPreparedGlobeTerrainTemplate(snapshot: GlobeTerrainPreparationSnapshot, grid: TerrainHeightGrid): GlobeTerrainMeshTemplate;
+/** Detached cooperative-work diagnostics, not a frame-time or whole-process memory measurement. */
+export interface GlobeTerrainPreparationStatistics {
+    /** Tiles still awaiting preparation in the latest request. */
+    pending: number;
+    /** Unique current and staged template storage; shared templates count once. */
+    retainedBytes: number;
+    /** Maximum retained template bytes permitted by this owner. */
+    byteLimit: number;
+    /** Fully published generations. */
+    committed: number;
+    /** Requests replaced before completion. */
+    cancelled: number;
+    /** New templates admitted by the latest generation. */
+    prepared: number;
+    /** Templates reused by the latest generation. */
+    reused: number;
+    /** Cooperative CPU slices in the latest generation. */
+    slices: number;
+    /** Last slice's elapsed time; an indivisible step may exceed its target. */
+    lastSliceMs: number;
+    /** Largest observed slice in the latest generation. */
+    maxSliceMs: number;
+    /** CPU slice elapsed sum, excluding time yielded back to the host. */
+    workMs: number;
+    /** Largest current-plus-candidate typed-template requirement observed before allocation. */
+    requiredPeakBytes: number;
+    /** Last preparation/admission failure; retry is explicit. */
+    error?: string;
+}
+/** Latest-request-wins preparation driven by the host, with atomic stitched snapshots and bounded retention. */
+export declare class GlobeTerrainPreparation {
+    private current?;
+    private target?;
+    private iterator?;
+    private staged;
+    private disposed;
+    private readonly statistics;
+    /** Leases cover this owner's current/staged templates, not external snapshots or scratch. */
+    private readonly leases;
+    /** Optional shared admission with sources, display preparation and renderer owners. */
+    private readonly resourceBudget?;
+    /** Retention includes the currently displayed and partially prepared generations, but not transient scratch arrays. */
+    constructor(maxRetainedBytes?: number, options?: {
+        /** Shared registered-allocation budget; independent local limits still apply. */
+        resourceBudget?: TerrainResourceBudget;
+    });
+    /** Replace obsolete staged work; unchanged requests and failed generations do not restart automatically. */
+    request(grids: readonly TerrainHeightGrid[], resolution?: number): boolean;
+    /** Run at least one bounded step, then yield after the elapsed target; true means a complete generation was committed. */
+    advance(budgetMs?: number, now?: () => number): boolean;
+    /** Retry a failed immutable request without resetting the displayed snapshot. */
+    retry(): boolean;
+    /** Completed snapshot only; partial generations are never exposed for rendering or picking. */
+    getSnapshot(): GlobeTerrainPreparationSnapshot | undefined;
+    /** Detached diagnostic snapshot, including unique current/staged template backing storage. */
+    getStatistics(): GlobeTerrainPreparationStatistics;
+    /** True until the latest generation commits, fails or is cancelled by teardown. */
+    isPending(): boolean;
+    /** Cancel pending work and release its reservations without discarding the displayed snapshot. */
+    cancel(): boolean;
+    /** Release references to current, staged and source data; safe to repeat. */
+    destroy(): void;
+    /** Count shared template handles once across visible and candidate generations. */
+    private getRetainedBytes;
+    /** Release only templates no longer retained by this owner; external snapshot ownership is separate. */
+    private releaseUnusedLeases;
+    /** Preserve unaffected immutable neighborhoods; commit every stitched tile together only after admission succeeds. */
+    private prepare;
+}

package/dist/types/map-logic/globe-terrain.d.ts

@@ -0,0 +1,54 @@
+import type { TerrainHeightGrid } from "./terrain-data.js";
+/** Detached render/query buffers; original height grids are never exaggerated or modified. */
+export interface GlobeTerrainMesh {
+    /** Longitude/latitude degrees and displayed elevation meters for deck.gl projection. */
+    geographicPositions: Float32Array;
+    /** Radius-256 spherical XYZ matching those packed geographic vertices. */
+    positions: Float64Array;
+    /** Physical source elevation per vertex, independent of exaggeration and chord error. */
+    physicalHeights: Float32Array;
+    /** Outward triangle topology; cells touching no-data samples are omitted. */
+    indices: Uint32Array;
+    /** RGB relief colors with baked common-space lighting, independent of backend. */
+    colors: Float32Array;
+}
+/** Opaque immutable sampling/topology snapshot; keep it to rescale without reading source grids again. */
+export interface GlobeTerrainMeshTemplate {
+    /** Number of regular and stitched vertices in this snapshot. */
+    readonly vertexCount: number;
+    /** Number of outward triangles, excluding no-data cells. */
+    readonly triangleCount: number;
+    /** Owned typed-array backing storage; excludes source grids and temporary JavaScript arrays. */
+    readonly byteLength: number;
+}
+/** Attenuate exaggerated relief to flat after one diameter doubling; explicit physical/subphysical settings stay fixed. */
+export declare function getGlobeTerrainExaggeration(globeScreenRatio: number, maximum?: number): number;
+/** Resample a Mercator DEM onto curved triangles; neighbors reconcile matching tile edges. */
+export declare function buildGlobeTerrainMesh(grid: TerrainHeightGrid, options?: {
+    /** Effective display multiplier, not the zoom-independent maximum. */
+    exaggeration?: number;
+    /** Cells along each tile axis, bounded to keep allocations predictable; defaults to 64. */
+    resolution?: number;
+    /** Same-datum, non-overlapping neighbors with balanced 2:1 edges and the same cell resolution. */
+    neighbors?: readonly TerrainHeightGrid[];
+}): GlobeTerrainMesh;
+/** Snapshot source sampling, no-data, edge stitching and physical slopes once per immutable neighborhood. */
+export declare function prepareGlobeTerrainMesh(grid: TerrainHeightGrid, options?: {
+    /** Uniform cells per tile axis, integer [2, 256]; defaults to 64. */
+    resolution?: number;
+    /** Same-datum non-overlapping neighbors with balanced 2:1 edges. */
+    neighbors?: readonly TerrainHeightGrid[];
+}): GlobeTerrainMeshTemplate;
+/** Cooperatively prepare identical topology; each yield releases control between bounded sampling chunks. */
+export declare function prepareGlobeTerrainMeshSteps(grid: TerrainHeightGrid, options?: {
+    /** Uniform cells per tile axis, integer [2, 256]; defaults to 64. */
+    resolution?: number;
+    /** Same-datum non-overlapping neighbors with balanced 2:1 edges. */
+    neighbors?: readonly TerrainHeightGrid[];
+    /** Exact final typed-array admission fence; scratch is excluded. The identity is not a usable template until completion. */
+    onAllocate?: (bytes: number, allocation: GlobeTerrainMeshTemplate) => void;
+}): Generator<void, GlobeTerrainMeshTemplate, void>;
+/** Rebuild detached display/query buffers without resampling or restitching the immutable template. */
+export declare function scaleGlobeTerrainMesh(template: GlobeTerrainMeshTemplate, exaggeration?: number): GlobeTerrainMesh;
+/** Cooperatively rescale identical packed vertices/lighting; yields every 128 vertices without resampling. */
+export declare function scaleGlobeTerrainMeshSteps(template: GlobeTerrainMeshTemplate, exaggeration?: number): Generator<void, GlobeTerrainMesh, void>;

package/dist/types/map-logic/index.d.ts

@@ -0,0 +1,33 @@
+export { resolveLabelPlacement } from "./label-placement.js";
+export type { ScreenLabelCandidate, LabelPlacementOptions } from "./label-placement.js";
+export { areGeographicLabelCopies } from "./label-identity.js";
+export type { GeographicLabelAnchor, GeographicLabelIdentityOptions } from "./label-identity.js";
+export { intersectsScreenBounds, unionScreenBounds, getScreenBoundsCells } from "./screen-bounds.js";
+export type { ScreenBounds, LabelViewport } from "./screen-bounds.js";
+export { default as TileBuildQueue } from "./tile-build-queue.js";
+export type { TileBuildTask } from "./tile-build-queue.js";
+export { TileResidency } from "./tile-residency.js";
+export { TileCachePolicy } from "./tile-cache-policy.js";
+export type { TileCacheRecord, TileCacheOptions, TileCacheStatistics } from "./tile-cache-policy.js";
+export { TERRARIUM_DECODER, TERRAIN_RGB_DECODER, decodeTerrainHeightGrid, sampleTerrainHeight } from "./terrain-data.js";
+export { sampleTerrainNeighborhood, resampleTerrainNodes } from "./terrain-neighborhood.js";
+export { TerrainHeightField } from "./terrain-height-field.js";
+export { TerrainResourceBudget } from "./terrain-resource-budget.js";
+export type { TerrainResourceDomain, TerrainResourceLease, TerrainResourceRequest } from "./terrain-resource-budget.js";
+export { measureTerrainError, boundTerrainMeshError, selectTerrainMeshResolution, boundProjectedDisplacement } from "./terrain-error.js";
+export type { TerrainErrorEnvelope } from "./terrain-error.js";
+export { guardTerrainMotion } from "./terrain-navigation.js";
+export type { TerrainMotionResult } from "./terrain-navigation.js";
+export type { TerrainFieldBounds, TerrainHeightFieldOptions, TerrainHeightFieldStatistics } from "./terrain-height-field.js";
+export { createTerrainGroundTopology } from "./terrain-ground-topology.js";
+export type { TerrainGroundTopology } from "./terrain-ground-topology.js";
+export type { ElevationDecoder, TerrainGridOptions, TerrainHeightGrid } from "./terrain-data.js";
+export { TriangleQueryIndex } from "./triangle-query-index.js";
+export { adaptTerrainQuerySource } from "./terrain-query.js";
+export type { TerrainQuerySource, TerrainQueryHit } from "./terrain-query.js";
+export type { TerrainSurface, TerrainSurfaceBounds, TerrainRay, TerrainSurfaceHit } from "../selection/terrain_surface.js";
+export type { IndexedTriangleHit, TriangleQueryResult, TriangleQueryIndexOptions } from "./triangle-query-index.js";
+export { buildGlobeTerrainMesh, prepareGlobeTerrainMesh, prepareGlobeTerrainMeshSteps, scaleGlobeTerrainMesh, scaleGlobeTerrainMeshSteps, getGlobeTerrainExaggeration } from "./globe-terrain.js";
+export type { GlobeTerrainMesh, GlobeTerrainMeshTemplate } from "./globe-terrain.js";
+export { GlobeTerrainPreparation, getPreparedGlobeTerrainTemplate, assertGlobeTerrainPreparationSnapshot } from "./globe-terrain-preparation.js";
+export type { GlobeTerrainPreparationSnapshot, GlobeTerrainPreparationStatistics } from "./globe-terrain-preparation.js";

package/dist/types/map-logic/label-identity.d.ts

@@ -0,0 +1,22 @@
+/** Geographic identity retained independently of rendered geometry and cameras. */
+export interface GeographicLabelAnchor {
+    /** Source/style/feature/text identity; absent identities cannot deduplicate. */
+    readonly identity?: string;
+    /** Tile identity; multiple mesh parts of the same tile are not buffered copies. */
+    readonly sourceTileIdentity: object | string;
+    /** Absolute projected XY in the same units as the world width. */
+    readonly anchor: readonly [number, number];
+    /** Quantized physical elevation; distinct elevations remain separate labels. */
+    readonly height: number;
+    /** Source detail used for coordinate quantization, independent of style zoom. */
+    readonly sourceZoom: number;
+}
+/** Explicit coordinate conventions; no renderer projection or Earth radius is assumed. */
+export interface GeographicLabelIdentityOptions {
+    /** Width of a complete projected world in anchor units. */
+    readonly worldWidth: number;
+    /** Treat horizontally wrapped copies as the same surface, as on a globe. */
+    readonly wrapHorizontal: boolean;
+}
+/** Match buffered copies within two 4096-unit source-tile quantization steps. */
+export declare function areGeographicLabelCopies(candidate: GeographicLabelAnchor, previous: GeographicLabelAnchor, options: GeographicLabelIdentityOptions): boolean;

package/dist/types/map-logic/label-placement.d.ts

@@ -0,0 +1,32 @@
+import type { ScreenBounds, LabelViewport } from "./screen-bounds.js";
+/** Renderer-independent candidate, already projected and ordered by the caller. */
+export interface ScreenLabelCandidate {
+    /** Unique ID within this invocation; also identifies linked candidates. */
+    readonly id: string;
+    /** Visible, padded local CSS-pixel bounds per named view. Empty means hidden. */
+    readonly boxes: ReadonlyMap<string, ScreenBounds>;
+    /** False skips overlap rejection but retains repeat and identity rules. */
+    readonly collide?: boolean;
+    /** Optional dependency; reciprocal links form an atomic pair. */
+    readonly linkedId?: string;
+    /** Key used to compare candidate copies via the supplied identity policy. */
+    readonly identity?: string;
+    /** Optional repeat group shared by labels representing the same content. */
+    readonly repeatGroup?: string;
+    /** Minimum CSS-pixel separation between box centers in every shared view. */
+    readonly repeatDistance?: number;
+}
+/** Geometry and identity policy supplied by the host, not owned by this algorithm. */
+export interface LabelPlacementOptions<Candidate extends ScreenLabelCandidate> {
+    /** Dimensions for every view named by candidate bounds. */
+    readonly viewports: ReadonlyMap<string, LabelViewport>;
+    /** Optional buffered-copy policy; called only within matching identity groups. */
+    readonly isDuplicate?: (candidate: Candidate, previous: Candidate) => boolean;
+}
+/**
+ * Resolve one visibility mask across all views in caller-supplied priority order.
+ * Inputs must have unique IDs and finite, ordered, already clipped/padded bounds.
+ * No input mutation, global state, camera, tile, worker, DOM or GPU dependency.
+ * Reciprocal links are placed atomically; optional children may overlap their parent.
+ */
+export declare function resolveLabelPlacement<Candidate extends ScreenLabelCandidate>(ordered: readonly Candidate[], options: LabelPlacementOptions<Candidate>): ReadonlyMap<Candidate, boolean>;

package/dist/types/map-logic/screen-bounds.d.ts

@@ -0,0 +1,15 @@
+/** Axis-aligned CSS-pixel bounds: minimum X/Y followed by maximum X/Y. */
+export type ScreenBounds = readonly [number, number, number, number];
+/** Local viewport dimensions; bounds do not include a canvas/eye origin. */
+export interface LabelViewport {
+    /** Local CSS-pixel width. */
+    readonly width: number;
+    /** Local CSS-pixel height. */
+    readonly height: number;
+}
+/** Strict rectangle overlap; touching padded edges do not collide. */
+export declare function intersectsScreenBounds(left: ScreenBounds, right: ScreenBounds): boolean;
+/** Combine parts of one annotation without modifying either input. */
+export declare function unionScreenBounds(left: ScreenBounds | undefined, right: ScreenBounds): ScreenBounds;
+/** Enumerate 64-pixel spatial-index cells, clipped to the visible viewport. */
+export declare function getScreenBoundsCells(box: ScreenBounds, viewport: LabelViewport): Generator<string>;

package/dist/types/map-logic/terrain-data.d.ts

@@ -0,0 +1,55 @@
+/** Affine coefficients applied to byte-valued linear RGB, with output in meters. */
+export interface ElevationDecoder {
+    /** Red channel multiplier. */
+    readonly rScaler: number;
+    /** Green channel multiplier. */
+    readonly gScaler: number;
+    /** Blue channel multiplier. */
+    readonly bScaler: number;
+    /** Meter offset after channel scaling. */
+    readonly offset: number;
+}
+/** Terrarium encoding used by Mapterhorn; compatible with loaders.gl terrain options. */
+export declare const TERRARIUM_DECODER: ElevationDecoder;
+/** Mapbox Terrain-RGB encoding, independent of the tile service. */
+export declare const TERRAIN_RGB_DECODER: ElevationDecoder;
+/** Explicit raster georeferencing; row zero is north and column zero is west. */
+export interface TerrainGridOptions {
+    /** Number of columns, at least two. */
+    width: number;
+    /** Number of rows, at least two. */
+    height: number;
+    /** Interleaved RGBA bytes, not sRGB-converted samples. */
+    pixels: Uint8Array | Uint8ClampedArray;
+    /** Decoder shared with loaders.gl. */
+    decoder: ElevationDecoder;
+    /** [west, south, east, north] in absolute EPSG:3857 meters. */
+    bounds: readonly [number, number, number, number];
+    /** Explicit vertical reference; do not infer a datum from the provider name. */
+    verticalDatum: 'ellipsoidal' | 'orthometric' | 'unknown';
+    /** Pixel-aligned validity mask; zero means no data. Alpha is not implicitly interpreted. */
+    valid?: Uint8Array;
+    /** Raster pixel centers, or samples including both grid edges. */
+    registration: 'pixel-center' | 'grid-node';
+}
+/** Detached decoded elevation data; meters are physical heights, never exaggerated. */
+export interface TerrainHeightGrid {
+    /** Number of columns. */
+    readonly width: number;
+    /** Number of rows. */
+    readonly height: number;
+    /** North-to-south, west-to-east row-major elevation values in meters. */
+    readonly heights: Float32Array;
+    /** Detached validity mask; invalid heights are NaN. */
+    readonly valid: Uint8Array;
+    /** Absolute Mercator footprint in meters. */
+    readonly bounds: readonly [number, number, number, number];
+    /** Vertical reference, without implicit conversions. */
+    readonly verticalDatum: TerrainGridOptions['verticalDatum'];
+    /** Sampling convention of the decoded pixels. */
+    readonly registration: TerrainGridOptions['registration'];
+}
+/** Decode identical byte coefficients to loaders.gl; preserve no-data explicitly. */
+export declare function decodeTerrainHeightGrid(options: TerrainGridOptions): TerrainHeightGrid;
+/** Bilinear height lookup; outside footprints and no-data neighborhoods return null. */
+export declare function sampleTerrainHeight(grid: TerrainHeightGrid, position: readonly [number, number]): number | null;

package/dist/types/map-logic/terrain-error.d.ts

@@ -0,0 +1,51 @@
+import type { TerrainHeightGrid } from "./terrain-data.js";
+/** Immutable DEM-derived envelope; it says nothing about unloaded finer source detail. */
+export interface TerrainErrorEnvelope {
+    /** Lowest and highest valid physical source elevations. */
+    readonly minimumHeight: number;
+    readonly maximumHeight: number;
+    /** Conservative directional bilinear gradient bounds per Mercator meter. */
+    readonly eastSlope: number;
+    readonly northSlope: number;
+    /** Mercator footprint width and height. */
+    readonly width: number;
+    readonly height: number;
+    /** Invalid samples prevent certification of the complete footprint. */
+    readonly complete: boolean;
+}
+/**
+ * Conservative CSS-pixel Lipschitz bound for a projective transform over an
+ * absolute XYZ box. Null means the box crosses the eye plane: never substitute
+ * a center-only derivative and call it a bounded screen error.
+ */
+export declare function boundProjectedDisplacement(matrix: readonly number[], minimum: readonly [number, number, number], maximum: readonly [number, number, number], viewport: {
+    width: number;
+    height: number;
+}): number | null;
+/** Measure source extrema and adjacent gradients once, retaining no additional sample arrays. */
+export declare function measureTerrainError(grid: TerrainHeightGrid): TerrainErrorEnvelope;
+/**
+ * Bound vertical interpolation error by the bilinear field's Lipschitz envelope.
+ * Deliberately conservative on ramps: this is not a fitted/sample-only RMSE.
+ * A separate spherical sagitta covers surface curvature, in globe-radius units.
+ */
+export declare function boundTerrainMeshError(envelope: TerrainErrorEnvelope, resolution: number): {
+    heightError: number;
+    globeCurvatureError: number;
+};
+/** Select a dyadic resolution with hysteresis from a caller's conservative pixels-per-unit bounds. */
+export declare function selectTerrainMeshResolution(grids: readonly TerrainHeightGrid[], options: {
+    /** Maximum acceptable interpolation-plus-curvature error, CSS pixels; default 2. */
+    targetPixels?: number;
+    /** Upper bound on projected displacement per physical vertical meter, including exaggeration. */
+    pixelsPerMeter: number;
+    /** Upper bound on projected displacement per radius-256 globe unit; zero for a planar view. */
+    pixelsPerGlobeUnit?: number;
+    /** Prior dyadic resolution supplies a 20% coarsening deadband. */
+    previousResolution?: number;
+}): {
+    resolution: number;
+    projectedError: number;
+    limited: boolean;
+    complete: boolean;
+};

package/dist/types/map-logic/terrain-ground-topology.d.ts

@@ -0,0 +1,26 @@
+import type { TerrainHeightGrid } from "./terrain-data.js";
+import type { TerrainFieldBounds } from "./terrain-height-field.js";
+/** Source-independent triangles; tile ownership is clipped after projection, never by moving boundary nodes. */
+export interface TerrainGroundTopology {
+    /** Absolute unwrapped EPSG:3857 XY, two components per vertex. */
+    positions: Float64Array;
+    /** Exact dyadic world fractions: X from the western world edge, Y southward from the northern edge. */
+    normalizedPositions: Float64Array;
+    /** Exact periodic sampling XY before whole-world translation; may share the positions array in world zero. */
+    samplePositions: Float64Array;
+    /** Counterclockwise top triangles, including conforming coarse/fine edge nodes. */
+    indices: Uint32Array;
+    /** Subtract this whole-world X offset before sampling the periodic DEM neighborhood. */
+    sampleOffset: number;
+}
+/** Include every touching neighbor's edge knots on a patch boundary, preserving traversal order. */
+export declare function getTerrainEdgeNodes(bounds: TerrainFieldBounds, neighbors: readonly TerrainFieldBounds[], resolution: number, start: readonly [number, number], end: readonly [number, number]): [number, number][];
+/** Quadtree copies shift to the sampling world; optional generic previous fields retain their absolute domain. */
+export declare function wrapTerrainGroundGrids(grids: readonly TerrainHeightGrid[], requireQuadtree?: boolean, samplingWorldOffset?: number): TerrainHeightGrid[];
+/**
+ * Build complete DEM-owned cells intersecting a source tile. Do not clip triangles
+ * at source/fallback edges: both owners must submit the same curved triangle there.
+ * Fragment/query half-open clips select ownership. Current fields must have balanced
+ * 2:1 quadtree edges; unsupported fields and exhausted budgets reject, never truncate.
+ */
+export declare function createTerrainGroundTopology(grids: readonly TerrainHeightGrid[], bounds: TerrainFieldBounds, resolution?: number, maxVertices?: number): TerrainGroundTopology;

package/dist/types/map-logic/terrain-height-field.d.ts

@@ -0,0 +1,59 @@
+import { type TerrainHeightGrid } from "./terrain-data.js";
+/** Absolute EPSG:3857 [west, south, east, north], including zero-width probe bounds. */
+export type TerrainFieldBounds = readonly [number, number, number, number];
+/** Retained mask admission; geometry, source arrays and JavaScript metadata are separate. */
+export interface TerrainHeightFieldOptions {
+    /** Maximum retained summed-area mask bytes; default 8 MiB. Zero uses exact sample scans. */
+    maxMaskBytes?: number;
+}
+/** Detached operation counts, suitable for deterministic performance tests rather than FPS estimates. */
+export interface TerrainHeightFieldStatistics {
+    /** Number of retained immutable source references. */
+    grids: number;
+    /** Retained summed-area mask bytes, excluding source arrays and tree metadata. */
+    maskBytes: number;
+    /** Admitted mask constructions, each built at most once per grid. */
+    maskBuilds: number;
+    /** Validity samples read during mask construction or exact fallback scans. */
+    maskSamples: number;
+    /** Spatial tree envelopes tested by sampling and coverage queries. */
+    boundsTests: number;
+    /** Candidate grid footprints visited after tree pruning. */
+    candidateGrids: number;
+}
+/**
+ * Immutable-source physical height sampling and conservative footprint admission.
+ * Snapshots membership/bounds, not height arrays: do not mutate shared grids.
+ * No provider, worker, deck view, GPU resource or implicit longitude wrapping is owned.
+ */
+export declare class TerrainHeightField {
+    /** Original order for small-field direct sampling, avoiding tree/sort overhead. */
+    private readonly entries;
+    /** Immutable spatial tree built once per admitted field. */
+    private readonly root;
+    /** Fixed retained summed-area mask admission limit. */
+    private readonly maxMaskBytes;
+    /** Mutable counters never exposed by reference. */
+    private readonly statistics;
+    /** Retain structurally valid decoded grids with one datum; overlaps preserve ordered sample averaging. */
+    constructor(grids: readonly TerrainHeightGrid[], options?: TerrainHeightFieldOptions);
+    /** Same ordered bilinear arithmetic, touching-edge tolerance and no-data rule as sampleTerrainNeighborhood. */
+    sampleHeight(position: readonly [number, number]): number | null;
+    /** Require complete rectangular footprint coverage and no invalid bilinear-support sample; not an exact triangle mask. */
+    coversBounds(bounds: TerrainFieldBounds): boolean;
+    /** Scalar counters only; callers cannot mutate cache ownership through diagnostics. */
+    getStatistics(): TerrainHeightFieldStatistics;
+    /**
+     * Physical extrema over bilinear cell rectangles in a fully covered probe.
+     * A missing footprint or invalid sample returns null, not a clearance
+     * certificate. Overlapping grids use a conservative per-grid envelope.
+     */
+    getHeightRange(bounds: TerrainFieldBounds): {
+        minimum: number;
+        maximum: number;
+    } | null;
+    /** Traverse closed envelopes, then preserve original source order for floating-point accumulation. */
+    private findEntries;
+    /** Admit a lazy reusable prefix or scan the same support rectangle exactly when it does not fit. */
+    private hasMissingSamples;
+}

package/dist/types/map-logic/terrain-navigation.d.ts

@@ -0,0 +1,27 @@
+import type { TerrainHeightField } from "./terrain-height-field.js";
+/** Conservative swept square-footprint guard; it is not a rigid-body physics solver. */
+export interface TerrainMotionResult {
+    /** True only when every admitted path rectangle has valid source coverage. */
+    readonly available: boolean;
+    /** No translation should be published when true; orientation can still change. */
+    readonly blocked: boolean;
+    /** Explicit distinction between an obstacle, no-data and a bounded-work refusal. */
+    readonly reason: 'clear' | 'terrain' | 'missing' | 'budget';
+    /** Exact rectangle queries performed, useful for deterministic work-budget tests. */
+    readonly probes: number;
+}
+/**
+ * Guard all intermediate XY coverage and the entire body footprint, not just
+ * endpoint/centerline rays. XY and radius are EPSG:3857 meters; Z/clearance are
+ * physical vertical meters. A square conservatively contains a circular avatar.
+ */
+export declare function guardTerrainMotion(field: TerrainHeightField, start: readonly [number, number, number], end: readonly [number, number, number], options: {
+    /** Half-width of the conservative horizontal footprint in Mercator meters. */
+    radius: number;
+    /** Required physical eye-to-ground distance. */
+    clearance: number;
+    /** Maximum horizontal travel per query rectangle, default 2 Mercator meters. */
+    maxStep?: number;
+    /** Hard rectangle-query cap, default 128. Excessive movement holds translation. */
+    maxProbes?: number;
+}): TerrainMotionResult;

package/dist/types/map-logic/terrain-neighborhood.d.ts

@@ -0,0 +1,5 @@
+import { type TerrainHeightGrid } from "./terrain-data.js";
+/** Sample touching footprints with shared-edge averaging; callers validate datum and topology. */
+export declare function sampleTerrainNeighborhood(grids: readonly TerrainHeightGrid[], position: readonly [number, number]): number | null;
+/** Reconstruct explicit boundary nodes from pixel-center data and adjacent tiles. */
+export declare function resampleTerrainNodes(grid: TerrainHeightGrid, neighbors?: readonly TerrainHeightGrid[]): TerrainHeightGrid;