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

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

@@ -0,0 +1,33 @@
+import type { TerrainSurface, TerrainSurfaceHit, TerrainRay } from "../selection/terrain_surface.js";
+/** Read-only structural hit accepted from loaders.gl-compatible terrain providers. */
+export type TerrainQueryHit = Omit<TerrainSurfaceHit, 'position' | 'coordinate' | 'normal' | 'barycentric'> & {
+    /** Displayed XYZ in the provider's content units. */
+    readonly position: readonly [number, number, number];
+    /** Longitude/latitude degrees and unexaggerated physical source meters. */
+    readonly coordinate: readonly [number, number, number];
+    /** Unit normal following displayed winding. */
+    readonly normal: readonly [number, number, number];
+    /** Original triangle vertex order. */
+    readonly barycentric: readonly [number, number, number];
+};
+/**
+ * Structural loaders.gl terrain surface contract. No package-version, GPU, deck or
+ * HostFrame dependency is introduced. The provider owns its current displayed generation.
+ */
+export interface TerrainQuerySource {
+    /** Mercator XYZ meters or host-defined center-relative globe common units. */
+    readonly projection: TerrainSurface['projection'];
+    /** Nearest loaded hit, with distance independent of direction length; misses do not certify coverage. */
+    intersectRay(ray: TerrainRay, maxDistance?: number): TerrainQueryHit | null;
+    /** Optional conservative displayed envelope; null means empty, absence means unknown. */
+    getBounds?(): {
+        readonly minimum: readonly [number, number, number];
+        readonly maximum: readonly [number, number, number];
+    } | null;
+}
+/**
+ * Borrow a shared terrain query provider without taking disposal or index ownership.
+ * Preserve Tangram's mutable result API using detached tuples. In particular, physical
+ * coordinate altitude is not reconstructed from exaggerated displayed positions.
+ */
+export declare function adaptTerrainQuerySource(source: TerrainQuerySource): TerrainSurface;

package/dist/types/map-logic/terrain-resource-budget.d.ts

@@ -0,0 +1,51 @@
+/** Independently reported storage domains; GPU bytes are estimates, not driver allocation measurements. */
+export type TerrainResourceDomain = 'retained' | 'transient' | 'gpu';
+/** One entry in an atomically admitted allocation batch. */
+export interface TerrainResourceRequest {
+    /** Independently reported storage category. */
+    readonly domain: TerrainResourceDomain;
+    /** Exact represented allocation bytes, a non-negative safe integer. */
+    readonly bytes: number;
+    /** Optional immutable allocation identity; matching owners count once. */
+    readonly identity?: object;
+}
+/** An owned reservation. Releasing twice is safe, including cancellation racing completion. */
+export interface TerrainResourceLease {
+    /** Atomically resize a private reservation; shared immutable reservations permit only the same size. */
+    resize(bytes: number): boolean;
+    /** Release this owner's reservation. */
+    release(): void;
+}
+/** Shared admission across source, preparation and renderer owners; never takes resource disposal ownership. */
+export declare class TerrainResourceBudget {
+    /** Validated total reservation limit, in bytes. */
+    readonly byteLimit: number;
+    /** Current allocations, keyed by opaque lease identity rather than reusable tile names. */
+    private readonly allocations;
+    /** Weak allocation identities permit independent owners to retain one immutable allocation once. */
+    private readonly sharedIdentities;
+    /** Largest simultaneously reserved total since construction. */
+    private peakBytes;
+    /** Current total, updated without rescanning every owner. */
+    private bytes;
+    /** Construct a finite hard admission limit; reservations must precede the represented allocation. */
+    constructor(byteLimit: number);
+    /** Reserve before allocating; rejection leaves every incumbent owner unchanged. */
+    reserve(domain: TerrainResourceDomain, bytes: number): TerrainResourceLease | null;
+    /** Retain an immutable allocation by identity; shared leases permit only no-op resizing. */
+    reserveShared(identity: object, domain: TerrainResourceDomain, bytes: number): TerrainResourceLease | null;
+    /** Create a lease only after its complete admission has been validated. */
+    private createLease;
+    /** Admit a complete set atomically; invalid or over-budget batches allocate no leases. */
+    reserveAll(requests: readonly TerrainResourceRequest[]): TerrainResourceLease[] | null;
+    /** Detached unique allocation bytes and live owner-lease count; excludes unregistered resources and driver overhead. */
+    getStatistics(): {
+        bytes: number;
+        peakBytes: number;
+        byteLimit: number;
+        retainedBytes: number;
+        transientBytes: number;
+        gpuBytes: number;
+        leases: number;
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { TerrainGroundTopology } from "./terrain-ground-topology.js";
+/** Barycentric reference to one unchanged endpoint face. Negative indices mean absent previous coverage. */
+export interface TerrainFaceReference {
+    /** Canonical vertex indices in original winding. */
+    readonly indices: readonly [number, number, number];
+    /** Weights at the final geometric position. */
+    readonly weights: readonly [number, number, number];
+}
+/** Common planar refinement of two field generations; neither endpoint is bilinearly resampled at new cuts. */
+export interface TerrainTransitionTopology {
+    /** Complete current footprint partition, including newly covered regions. */
+    readonly topology: TerrainGroundTopology;
+    /** Current endpoint references, one per output vertex. */
+    readonly current: readonly TerrainFaceReference[];
+    /** Previous endpoint references, null outside the previous admitted footprint. */
+    readonly previous: readonly (TerrainFaceReference | null)[];
+}
+/**
+ * Split current faces along previous edges, retaining both exact planar endpoint
+ * surfaces and newly covered ground. Bounded work/vertices reject atomically.
+ * This does not claim spherical coplanarity after nonlinear globe projection.
+ */
+export declare function refineTerrainTransitionTopology(current: TerrainGroundTopology, previous: TerrainGroundTopology, maxVertices: number, maxEdgeTests?: number): TerrainTransitionTopology | null;

package/dist/types/map-logic/tile-build-queue.d.ts

@@ -0,0 +1,51 @@
+/** A single source/style generation's tile build. */
+export interface TileBuildTask {
+    /** Source-normalized tile key. */
+    readonly key: string;
+    /** Tile identity and scene generation, used to reject stale completions. */
+    readonly token: string;
+    /** Visible detail precedes pinned preload, which precedes off-screen work. */
+    priority: number;
+    /** Start worker processing; completion is reported separately. */
+    start(): void;
+    /** Release ownership when starting the task fails synchronously. */
+    fail(error: unknown): void;
+}
+/** CPU-only, callback-based stable-priority scheduling shared by all eyes and sources. */
+export default class TileBuildQueue {
+    /** Builds that have been submitted to workers. */
+    private readonly active;
+    /** Latest unsent generation for each tile key, in stable insertion order. */
+    private readonly pending;
+    /** Unlimited unless the host opts into a build limit. */
+    private limit;
+    /** Prevent synchronous completion/failure callbacks from recursively pumping. */
+    private pumping;
+    /** Nested visibility updates must install all priorities before any submission. */
+    private suspensionDepth;
+    /** Set a validated concurrency limit without cancelling active work. */
+    setLimit(limit: number | undefined): void;
+    /** Begin an atomic source/eye-union update without submitting stale queued work. */
+    suspend(): void;
+    /** Commit a batch and resume priority-based submission after the outermost update. */
+    resume(): void;
+    /** Queue the latest generation; a duplicate active task is not submitted twice. */
+    enqueue(task: TileBuildTask): void;
+    /** Update unsent work when the shared eye-union visibility changes. */
+    setPriority(key: string, priority: number): void;
+    /** Release only the matching generation; late worker replies cannot free new work. */
+    finish(key: string, token: string): boolean;
+    /** Remove a tile's queued and active ownership after the caller cancels its worker. */
+    cancel(key: string): void;
+    /** Whether any generation of a tile still owns queue state. */
+    has(key: string): boolean;
+    /** Active and unsent counts, detached from the queue's internal maps. */
+    getCounts(): {
+        activeBuilds: number;
+        queuedBuilds: number;
+    };
+    /** Submit available slots, retaining stable ordering among equal priorities. */
+    pump(): void;
+    /** Release all queue metadata during scene teardown. */
+    clear(): void;
+}

package/dist/types/map-logic/tile-cache-policy.d.ts

@@ -0,0 +1,46 @@
+/** Immutable resource metadata supplied by the host, with unique keys per snapshot. */
+export interface TileCacheRecord {
+    /** Stable content identity, including source/style generation when necessary. */
+    readonly key: string;
+    /** Non-negative finite resource bytes; the host defines which resources are counted. */
+    readonly bytes: number;
+    /** Whether visibility, loading, proxies, pins or consumers currently prevent eviction. */
+    readonly protected: boolean;
+}
+/** Already validated non-negative cache limits; protected records do not consume these budgets. */
+export interface TileCacheOptions {
+    /** Maximum evictable entries; omit for unlimited. */
+    readonly maxCachedTiles?: number;
+    /** Maximum evictable resource bytes; omit for unlimited. */
+    readonly maxCachedBytes?: number;
+}
+/** Detached accounting for a host-provided resident snapshot, not a resource allocator. */
+export interface TileCacheStatistics {
+    /** All retained records, including protected entries. */
+    residentTiles: number;
+    /** Entries eligible for eviction. */
+    cachedTiles: number;
+    /** Bytes in evictable entries. */
+    cachedBytes: number;
+    /** Entries excluded from eviction. */
+    protectedTiles: number;
+    /** Bytes in protected entries. */
+    protectedBytes: number;
+}
+/** Stable LRU policy owning recency metadata only; selection never disposes or removes content. */
+export declare class TileCachePolicy {
+    /** Logical access order, independent of clocks and resource ownership. */
+    private readonly lastUsed;
+    /** Monotonic access sequence retained across metadata resets. */
+    private tick;
+    /** Mark a key as recently used; callers decide when visibility counts as reuse. */
+    touch(key: string): void;
+    /** Release recency metadata after the host removes a record. */
+    forget(key: string): void;
+    /** Select oldest evictable keys until both budgets fit, without changing input or recency. */
+    selectEvictions(records: readonly TileCacheRecord[], options?: TileCacheOptions): string[];
+    /** Count the current snapshot without changing recency or retaining record objects. */
+    getStatistics(records: readonly TileCacheRecord[]): TileCacheStatistics;
+    /** Clear recency metadata without touching host content or resetting the logical clock. */
+    clear(): void;
+}

package/dist/types/map-logic/tile-residency.d.ts

@@ -0,0 +1,17 @@
+/** Shared-consumer residency metadata; does not own tiles, loading or disposal. */
+export declare class TileResidency<ConsumerId = symbol> {
+    /** Consumers retain independent snapshots of their selected and visible keys. */
+    private readonly consumers;
+    /** Attach a consumer with empty state, resetting it if already attached. */
+    attachConsumer(id: ConsumerId): void;
+    /** Replace a consumer's state with copied keys; unknown consumers are attached. */
+    updateConsumer(id: ConsumerId, selected: readonly string[], visible: readonly string[]): void;
+    /** Release only this consumer's protection, leaving other consumers intact. */
+    detachConsumer(id: ConsumerId): void;
+    /** Return a detached, deduplicated union in consumer and key insertion order. */
+    getSelectedTileKeys(): string[];
+    /** Whether any consumer selects or displays a key, even if its content is not loaded. */
+    isProtected(key: string): boolean;
+    /** Release all consumer metadata; no tile resources are unloaded. */
+    clear(): void;
+}

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

@@ -0,0 +1,87 @@
+/** Nearest two-sided triangle; the ray parameter retains the supplied direction scale. */
+export interface IndexedTriangleHit {
+    /** Original triangle offset, unaffected by bounds partitioning. */
+    triangleIndex: number;
+    /** Parameter along origin + direction × parameter. */
+    parameter: number;
+    /** Weights in the original index order. */
+    barycentric: [number, number, number];
+}
+/** Detached query result with deterministic work counts for conformance/performance tests. */
+export interface TriangleQueryResult {
+    /** Nearest hit in the closed forward segment, or null. */
+    hit: IndexedTriangleHit | null;
+    /** Number of tested hierarchy boxes. */
+    testedBounds: number;
+    /** Number of actual triangle intersection tests. */
+    testedTriangles: number;
+}
+/** Optional lazy hierarchy policy; the immutable geometry is always retained. */
+export interface TriangleQueryIndexOptions {
+    /** Build on the first bounds-intersecting query rather than at construction. */
+    lazy?: boolean;
+    /** Maximum hierarchy typed-array bytes; insufficient space uses exact linear queries. */
+    maxHierarchyBytes?: number;
+    /** Never build synchronously from a query; an explicit cooperative iterator warms acceleration. */
+    deferBuild?: boolean;
+}
+/** Immutable CPU triangle index; no projection, scene, DOM, GPU or source ownership. */
+export declare class TriangleQueryIndex {
+    /** Exact packed acceleration bytes for the same balanced partition used by construction. */
+    static getRequiredHierarchyBytes(triangleCount: number, leafSize?: number): number;
+    /** Original number of triangles, including degenerates. */
+    readonly triangleCount: number;
+    /** Exact retained geometry typed-array bytes, independent of lazy acceleration. */
+    readonly geometryBytes: number;
+    /** Exact required order and packed-node bytes, known before hierarchy allocation. */
+    readonly requiredHierarchyBytes: number;
+    /** Copied vertices and original topology. */
+    private readonly positions;
+    private readonly indices;
+    /** Partitioned original triangle identifiers. */
+    private order?;
+    /** Six Float64 bounds and four Uint32 topology offsets per node. */
+    private bounds?;
+    private topology?;
+    /** In-progress storage is counted but never traversed until the whole hierarchy is ready. */
+    private preparing?;
+    private readonly leafSize;
+    private readonly nodeCount;
+    private readonly hierarchyAllowed;
+    /** Host-driven warming keeps interactive queries from allocating a synchronous hierarchy. */
+    private readonly deferBuild;
+    private readonly minimum;
+    private readonly maximum;
+    /** Copy finite XYZ triangles and partition their bounds into small balanced leaves. */
+    constructor(positions: ArrayLike<number>, indices: ArrayLike<number>, leafSize?: number, options?: TriangleQueryIndexOptions);
+    /** Exact currently retained backing arrays, excluding JavaScript objects and construction scratch. */
+    get arrayBytes(): number;
+    /** Exact allocated acceleration storage, including pending warming; zero before allocation or in linear mode. */
+    get hierarchyBytes(): number;
+    /** Detached conservative geometry bounds, including unreferenced finite vertices; null for an empty vertex buffer. */
+    getBounds(): {
+        minimum: [number, number, number];
+        maximum: [number, number, number];
+    } | null;
+    /** Warm acceleration in bounded scanning/partition chunks; closing the iterator discards partial storage. */
+    prepareHierarchySteps(): Generator<void, void, void>;
+    /** Detached indexed vertex and its original identity, without exposing mutable backing arrays. */
+    getTriangleVertex(triangle: number, vertex: number): {
+        index: number;
+        position: [number, number, number];
+    };
+    /** Read one original vertex identity without allocating coordinates or exposing topology storage. */
+    getVertexIndex(triangle: number, vertex: number): number;
+    /** Two-sided math.gl queries with bounds pruning, finite clipping and stable tie-breaking. */
+    queryRay(origin: readonly [number, number, number], direction: readonly [number, number, number], maxParameter?: number, acceptHit?: (hit: IndexedTriangleHit) => boolean): TriangleQueryResult;
+    /** Preserve synchronous construction/lazy-query compatibility by consuming the same cooperative builder. */
+    private buildHierarchy;
+    /** Decode a node without retaining per-node JavaScript objects. */
+    private readNode;
+    /** Read a detached original vertex for bounds and triangle kernels. */
+    private getVertex;
+    /** Partition on the longest bounds axis; midpoint splitting bounds recursion depth. */
+    private buildNodeSteps;
+    /** In-place median selection with cooperative comparisons and no temporary full-size JavaScript order array. */
+    private partitionSteps;
+}

package/dist/types/procedures/js-yaml.d.ts

@@ -0,0 +1,15 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+declare module 'js-yaml' {
+    type SafeLoadOptions = {
+        json?: boolean;
+    };
+
+    const yaml: {
+        safeLoad(source: string, options?: SafeLoadOptions): Record<string, any>;
+    };
+
+    export default yaml;
+}

package/dist/types/procedures/mesh-projector.d.ts

@@ -0,0 +1,107 @@
+import type VertexLayout from "../gl/vertex_layout.js";
+/** Detached accounting for optional projection-independent worker preparation. */
+export interface MeshPreparationStatistics {
+    /** Number of retained source meshes. */
+    entries: number;
+    /** Retained original/prepared typed-array bytes. */
+    bytes: number;
+    /** Successful preparation reuses. */
+    hits: number;
+    /** Requests requiring a new preparation. */
+    misses: number;
+    /** Optional detached statistics for the independently bounded, opt-in projected output cache. */
+    projectedResults?: {
+        entries: number;
+        bytes: number;
+        hits: number;
+        misses: number;
+    };
+}
+/** Cumulative projection work in one worker, reset with source preparation; not resident GPU memory. */
+export interface MeshProjectionStatistics {
+    /** Meshes whose projection completed successfully. */
+    completedMeshes: number;
+    /** Requests rejected by preparation, refinement or the projection engine. */
+    failedMeshes: number;
+    /** Original packed vertices across completed requests. */
+    sourceVertices: number;
+    /** Final vertices across completed requests, including unchanged originals. */
+    outputVertices: number;
+    /** Final triangles across completed requests. */
+    outputTriangles: number;
+    /** Projector batches submitted, including samples and failed requests. */
+    projectionBatches: number;
+    /** Coordinate pairs submitted to local or host kernels. */
+    projectedPositions: number;
+    /** Successful sampled edge-refinement rounds. */
+    edgeRounds: number;
+    /** Successful sampled interior-refinement rounds. */
+    interiorRounds: number;
+}
+/** Initial CPU basemap projections; no arbitrary CRS or dynamic camera projection. */
+export type ProjectedBasemapOptions = {
+    /** Projection with fixed documented ellipsoid, origin and standard parallels. */
+    type: 'equal-earth' | 'albers' | 'equirectangular' | 'mercator' | 'web-mercator';
+    /** Maximum Mercator angular edge span before projection; defaults to four degrees. */
+    maxAngularSpan?: number;
+    /** Per-mesh additional vertex budget; defaults to 65,536. */
+    maxAdditionalVertices?: number;
+    /** Optional sampled edge/interior error in common units; ribbons use edges only. */
+    maxProjectedError?: number;
+    /** Reuse completed projected meshes; host engines require a stable worker-local cache identity. */
+    cacheProjectedMeshes?: boolean;
+    /** Opt into packed surface/annotation elevation and polygon extrusion; ground-only by default. */
+    allowElevation?: boolean;
+};
+/** Worker-local packed triangle input; the original tile coordinates must survive. */
+export interface MeshProjectionRequest {
+    /** Finalized interleaved vertex bytes. */
+    vertices: Uint8Array;
+    /** Triangle indices or an unindexed triangle stream. */
+    indices: Uint16Array | Uint32Array | false;
+    /** Layout shared by main-thread and worker polygon styles. */
+    layout: VertexLayout;
+    /** Source tile's north-west EPSG:3857 origin and actual data zoom. */
+    tile: {
+        min: {
+            x: number;
+            y: number;
+        };
+        coords: {
+            z: number;
+        };
+        overzoom2?: number;
+        style_z?: number;
+    };
+    /** Lines carry centerline positions and separate packed extrusion; other meshes are already expanded. */
+    geometry?: 'polygons' | 'raster' | 'lines' | 'points' | 'text';
+    /** Validated scene-wide projection and refinement limits. */
+    projection: ProjectedBasemapOptions;
+    /** Optional worker-local bridge to a caller-owned host engine; never serialized with the scene. */
+    projectPositions?: (coordinates: Float64Array) => Promise<Float64Array>;
+    /** Immutable host transform identity for opt-in result caching; absence bypasses host result caching. */
+    projectionCacheKey?: string;
+}
+/** Completed packed mesh, independent of projection backend ownership. */
+export type ProjectedMesh = {
+    vertices: Uint8Array;
+    indices: Uint16Array | Uint32Array;
+};
+/** Worker procedure; a host-injected backend may require an asynchronous batch round trip. */
+export type MeshProjector = (request: MeshProjectionRequest) => ProjectedMesh | Promise<ProjectedMesh>;
+/** Projected lighting currently supports ambient and common-space directional lights only. */
+export declare function validateProjectedLights(value: unknown): void;
+/** Validate fixed or strictly ordered zoom-stop distances with one unit across every stop. */
+export declare function getProjectedRoadUnit(value: unknown, positive?: boolean): 'm' | 'px';
+/** Install the optional CPU projector in this worker without importing math.gl into normal bundles. */
+export declare function registerMeshProjector(projector: MeshProjector, clear?: () => void, getStatistics?: () => MeshPreparationStatistics, getWorkStatistics?: () => MeshProjectionStatistics): void;
+/** Release optional worker preparation at reset without importing its implementation in the core. */
+export declare function clearMeshProjectorPreparation(): void;
+/** Snapshot optional preparation diagnostics without importing the projected worker in the core. */
+export declare function getMeshProjectorPreparationStatistics(): MeshPreparationStatistics | undefined;
+/** Snapshot optional projection work without importing projection kernels into renderer core. */
+export declare function getMeshProjectorWorkStatistics(): MeshProjectionStatistics | undefined;
+/** Fail explicitly when a projected scene omitted its opt-in worker script. */
+export declare function projectTileMesh(request: MeshProjectionRequest): ReturnType<MeshProjector>;
+/** Validate serialized scene options before layouts, shaders or meshes are created. */
+export declare function normalizeProjectedBasemapOptions(value: unknown): ProjectedBasemapOptions;

package/dist/types/procedures/mvt-dependencies.d.ts

@@ -0,0 +1,20 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+declare module 'pbf' {
+    export default class Pbf {
+        constructor (buffer: Uint8Array);
+    }
+}
+
+declare module '@mapbox/vector-tile' {
+    export class VectorTile {
+        layers: Record<string, unknown>;
+        constructor (pbf: unknown);
+    }
+
+    export class VectorTileFeature {
+        static types: Record<number, string>;
+    }
+}

package/dist/types/procedures/projected-coordinate-transform.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectionEngineOptions, ProjectionEngine } from "../types.js";
+import type { ProjectedBasemapOptions } from "./mesh-projector.js";
+import type { ProjectionExecutionOptions, ProjectionExecutionStatistics } from "./projection-batch-executor.js";
+/** Tangram's projected common-space units per projected meter. */
+export declare const PROJECTED_COMMON_SCALE: number;
+/** Compile the same geographic-degree to north-positive meter contract on either thread. */
+export declare function getProjectedCoordinateOptions(type: ProjectedBasemapOptions['type']): ProjectionEngineOptions;
+/** Reject transform instances and malformed factories before allocating renderer resources. */
+export declare function validateProjectionEngine(engine: ProjectionEngine | undefined): void;
+/** Scene-owned transforms; the caller owns the engine and its registrations/grids. */
+export declare class HostProjectionEngineAdapter {
+    private readonly engine;
+    /** Independent asynchronous compilation per CRS pair, shared across meshes and workers. */
+    private readonly transforms;
+    /** Prevent late worker batches from publishing after scene teardown. */
+    private disposed;
+    /** Cooperative execution and cancellation for scene-owned host requests. */
+    private readonly executor;
+    /** Retain, but never mutate or dispose, the supplied factory. */
+    constructor(engine: ProjectionEngine, options?: ProjectionExecutionOptions);
+    /** Project one packed longitude/latitude batch to common coordinates without modifying input. */
+    projectPositions(coordinates: Float64Array, type: ProjectedBasemapOptions['type'], signal?: AbortSignal): Promise<Float64Array>;
+    /** Detached host execution counters, separate from mesh and decoded-source residency. */
+    getStatistics(): ProjectionExecutionStatistics;
+    /** Release scene-owned transforms without taking ownership of the injected factory. */
+    dispose(): void;
+}

package/dist/types/procedures/projection-batch-executor.d.ts

@@ -0,0 +1,53 @@
+import type { ProjectionEngineTransform } from "../types.js";
+/** Cooperative host-side execution policy; does not limit tile loading or mesh-build capacity. */
+export interface ProjectionExecutionOptions {
+    /** Maximum coordinate pairs per synchronous kernel call, 1–65,536; defaults to 4,096. */
+    maxBatchPositions?: number;
+}
+/** Per-operation cancellation and output coordinate contract. */
+export interface ProjectionBatchRequestOptions {
+    /** Cancel this operation without cancelling shared compilation or other requests. */
+    signal?: AbortSignal;
+    /** Multiply kernel output by this finite scale; defaults to one. */
+    scale?: number;
+    /** Optional positive finite output magnitude bound, checked after scaling. */
+    maxAbsoluteValue?: number;
+    /** Preserve nonfinite inverse-domain sentinels for caller validation; defaults to false. */
+    allowNonfinite?: boolean;
+}
+/** Detached cumulative host work; counts kernel submissions, not worker/GPU memory or wall-clock time. */
+export interface ProjectionExecutionStatistics {
+    /** Requests still awaiting compilation or cooperative execution. */
+    activeRequests: number;
+    /** Requests that returned a fully validated output. */
+    completedRequests: number;
+    /** Requests rejected by compilation, kernels or invalid output. */
+    failedRequests: number;
+    /** Requests cancelled by a signal or executor teardown. */
+    cancelledRequests: number;
+    /** Coordinate pairs submitted to kernels, including requests that subsequently fail/cancel. */
+    submittedPositions: number;
+    /** Synchronous kernel calls attempted, including failed calls. */
+    batches: number;
+    /** Event-loop yields scheduled between chunks. */
+    yieldCount: number;
+    /** Configured per-call coordinate pair limit. */
+    maxBatchPositions: number;
+}
+/** Validate policy before allocating a renderer, worker endpoint or navigation helper. */
+export declare function normalizeProjectionExecutionOptions(options?: ProjectionExecutionOptions): Required<ProjectionExecutionOptions>;
+/** Run independent packed batches with detached input, cooperative yields and prompt cancellation. */
+export declare class ProjectionBatchExecutor {
+    /** Cancels pending operations without taking ownership of transforms or factories. */
+    private readonly lifetime;
+    /** Detached snapshots are returned instead of exposing these mutable counters. */
+    private readonly statistics;
+    /** Capture an immutable per-kernel-call execution policy. */
+    constructor(options?: ProjectionExecutionOptions);
+    /** Capture input before compilation; abort only this output, never a shared factory promise. */
+    execute(coordinates: Float64Array, getTransform: () => Promise<ProjectionEngineTransform>, options?: ProjectionBatchRequestOptions): Promise<Float64Array>;
+    /** Return detached counters; no factory objects, coordinate buffers or mutable references escape. */
+    getStatistics(): ProjectionExecutionStatistics;
+    /** Reject pending requests immediately; synchronous kernels cannot be interrupted mid-call. */
+    dispose(): void;
+}

package/dist/types/procedures/scene-yaml-legacy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse a Tangram scene using the renderer's established js-yaml implementation.
+ * @param {string} source YAML scene source.
+ * @returns Parsed YAML value; scene interpretation and schema validation are separate boundaries.
+ */
+export declare function parseSceneYamlLegacy(source: string): unknown;