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

package/src/procedures/mvt-legacy.ts

@@ -0,0 +1,150 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import Pbf from 'pbf';
+import {VectorTile, VectorTileFeature} from '@mapbox/vector-tile';
+import Geo from '../utils/geo';
+import {parseMvtJsonProperties} from './mvt-properties';
+
+interface MvtOptions {
+    parseJson?: boolean | readonly string[];
+}
+
+interface MvtPoint {
+    x: number;
+    y: number;
+}
+
+interface MvtFeature {
+    id?: string | number;
+    type: number;
+    properties: Record<string, unknown>;
+    loadGeometry(): MvtPoint[][];
+}
+
+interface MvtLayer {
+    extent: number;
+    length: number;
+    feature(index: number): MvtFeature;
+}
+
+/** Mapbox Vector Tile object produced by the legacy vector-tile decoder. */
+export interface MvtTile {
+    layers: Record<string, MvtLayer>;
+}
+
+interface TangramGeometry {
+    type: string;
+    coordinates: [number, number] | [number, number][] | [number, number][][] | [number, number][][][];
+}
+
+interface TangramFeature {
+    type: 'Feature';
+    geometry: TangramGeometry | null;
+    id?: string | number;
+    properties: Record<string, unknown>;
+}
+
+export interface TangramFeatureCollection {
+    type: 'FeatureCollection';
+    features: TangramFeature[];
+}
+
+/** Parse MVT bytes using Tangram's established Mapbox vector-tile implementation. */
+export function parseMvtWithLegacy(response: ArrayBuffer | ArrayLike<number>, options: MvtOptions = {}): Record<string, TangramFeatureCollection> {
+    const tile = new VectorTile(new Pbf(new Uint8Array(response))) as unknown as MvtTile;
+    return convertMvtTileWithLegacy(tile, options);
+}
+
+/** Convert a Mapbox VectorTile object to Tangram's layer-indexed GeoJSON shape. */
+export function convertMvtTileWithLegacy(tile: MvtTile, options: MvtOptions = {}): Record<string, TangramFeatureCollection> {
+    const layers: Record<string, TangramFeatureCollection> = {};
+    for (const layerName in tile.layers) {
+        const layer = tile.layers[layerName];
+        const scale = Geo.tile_scale / layer.extent;
+        const layerGeoJson: TangramFeatureCollection = {type: 'FeatureCollection', features: []};
+
+        for (let featureIndex = 0; featureIndex < layer.length; featureIndex++) {
+            const feature = layer.feature(featureIndex);
+            const featureGeoJson: TangramFeature = {
+                type: 'Feature', geometry: {type: '', coordinates: []}, id: feature.id, properties: feature.properties
+            };
+            parseMvtJsonProperties(featureGeoJson, options.parseJson);
+
+            const coordinates: [number, number][][] = feature.loadGeometry().map(ring =>
+                ring.map(point => [point.x * scale, point.y * scale])
+            );
+            let geometry = featureGeoJson.geometry;
+            if (!geometry) {
+                continue;
+            }
+            geometry.coordinates = coordinates;
+
+            if (VectorTileFeature.types[feature.type] === 'Point') {
+                if (coordinates.length === 1) {
+                    geometry.type = 'Point';
+                    geometry.coordinates = geometry.coordinates[0][0];
+                }
+                else {
+                    geometry.type = 'MultiPoint';
+                    geometry.coordinates = geometry.coordinates[0];
+                }
+            }
+            else if (VectorTileFeature.types[feature.type] === 'LineString') {
+                if (coordinates.length === 1) {
+                    geometry.type = 'LineString';
+                    geometry.coordinates = geometry.coordinates[0];
+                }
+                else {
+                    geometry.type = 'MultiLineString';
+                }
+            }
+            else if (VectorTileFeature.types[feature.type] === 'Polygon') {
+                geometry = decodeMultiPolygon(geometry);
+            }
+
+            featureGeoJson.geometry = geometry;
+            layerGeoJson.features.push(featureGeoJson);
+        }
+        layers[layerName] = layerGeoJson;
+    }
+    return layers;
+}
+
+/** Decode flattened MVT polygon rings into Polygon or MultiPolygon coordinates. */
+export function decodeMultiPolygon(geometry: TangramGeometry): TangramGeometry | null {
+    const polygons: [number, number][][][] = [];
+    let polygon: [number, number][][] = [];
+    let outerWinding: 'CW' | 'CCW' | null = null;
+    const rings = geometry.coordinates as [number, number][][];
+    for (const ring of rings) {
+        const winding = Geo.ringWinding(ring);
+        if (winding == null) {
+            continue;
+        }
+        outerWinding = outerWinding || winding;
+        if (winding === outerWinding && polygon.length > 0) {
+            polygons.push(polygon);
+            polygon = [];
+        }
+        polygon.push(ring);
+    }
+    if (polygon.length > 0) {
+        polygons.push(polygon);
+    }
+
+    if (polygons.length === 1) {
+        geometry.type = 'Polygon';
+        geometry.coordinates = polygons[0];
+    }
+    else if (polygons.length > 1) {
+        geometry.type = 'MultiPolygon';
+        geometry.coordinates = polygons;
+    }
+    else {
+        return null;
+    }
+    return geometry;
+}

package/src/procedures/mvt-loaders.ts

@@ -0,0 +1,53 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {MVTGeoJSONLoaderWithParser} from '@loaders.gl/mvt/mvt-geojson-loader';
+import Geo from '../utils/geo';
+import {parseMvtJsonProperties, type ParseJsonOption} from './mvt-properties';
+
+const LAYER_PROPERTY = '__tangram_layer';
+type GeoJsonGeometry = {type: string; coordinates: unknown};
+type GeoJsonFeature = {
+  type: 'Feature';
+  geometry: GeoJsonGeometry | null;
+  id?: string | number;
+  properties: Record<string, unknown>;
+};
+type GeoJsonFeatureCollection = {type: 'FeatureCollection'; features: GeoJsonFeature[]};
+
+/** Parse MVT bytes with loaders.gl and normalize them to Tangram's layer-indexed GeoJSON shape. */
+export function parseMvtWithLoaders(
+  response: ArrayBuffer | Uint8Array,
+  options: {parseJson?: ParseJsonOption} = {}
+): Record<string, GeoJsonFeatureCollection> {
+  const tileBuffer: ArrayBuffer = response instanceof Uint8Array
+    ? Uint8Array.from(response).buffer as ArrayBuffer
+    : response;
+  const parsed = MVTGeoJSONLoaderWithParser.parseSync(tileBuffer, {
+    mvt: {coordinates: 'local', layerProperty: LAYER_PROPERTY}
+  }) as GeoJsonFeatureCollection;
+
+  const layers: Record<string, GeoJsonFeatureCollection> = {};
+  for (const feature of parsed.features) {
+    const layerName = String(feature.properties[LAYER_PROPERTY]);
+    delete feature.properties[LAYER_PROPERTY];
+    if (feature.geometry) {
+      feature.geometry.coordinates = scaleCoordinates(feature.geometry.coordinates, Geo.tile_scale);
+    }
+    parseMvtJsonProperties(feature, options.parseJson);
+    layers[layerName] ||= {type: 'FeatureCollection', features: []};
+    layers[layerName].features.push(feature);
+  }
+  return layers;
+}
+
+function scaleCoordinates(coordinates: unknown, scale: number): unknown {
+  if (!Array.isArray(coordinates)) {
+    return coordinates;
+  }
+  if (coordinates.length >= 2 && coordinates.every(value => typeof value === 'number')) {
+    return coordinates.map(value => value * scale);
+  }
+  return coordinates.map(value => scaleCoordinates(value, scale));
+}

package/src/procedures/mvt-parser.ts

@@ -0,0 +1,48 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ParseJsonOption} from './mvt-properties';
+
+/** Tangram-compatible decoded MVT layers in local tile coordinates. */
+export type MvtLayers = Record<string, {
+    type: 'FeatureCollection';
+    features: unknown[];
+}>;
+
+/** Signature required of a registered MVT decoder. */
+export type MvtDecoder = (
+    response: ArrayBuffer | Uint8Array,
+    options: {parseJson?: ParseJsonOption}
+) => MvtLayers;
+
+const mvtDecoders = new Map<string, MvtDecoder>();
+
+/** Register an MVT decoder and return a function that removes that registration. */
+export function registerMvtDecoder(name: string, decoder: MvtDecoder): () => void {
+    if (!name || typeof decoder !== 'function') {
+        throw new Error('MVT decoder registration requires a name and decoder function');
+    }
+    if (mvtDecoders.has(name)) {
+        throw new Error(`MVT decoder '${name}' is already registered`);
+    }
+    mvtDecoders.set(name, decoder);
+    return () => {
+        if (mvtDecoders.get(name) === decoder) {
+            mvtDecoders.delete(name);
+        }
+    };
+}
+
+/** Decode one MVT payload with the selected registered decoder. */
+export function parseMvt(
+    name: string,
+    response: ArrayBuffer | Uint8Array,
+    options: {parseJson?: ParseJsonOption}
+): MvtLayers {
+    const decoder = mvtDecoders.get(name);
+    if (!decoder) {
+        throw new Error(`MVT decoder '${name}' is not registered in this worker`);
+    }
+    return decoder(response, options);
+}

package/src/procedures/mvt-properties.ts

@@ -0,0 +1,36 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+/** Tangram's supported `parse_json` source option. */
+export type ParseJsonOption = boolean | readonly string[] | undefined;
+
+type FeatureWithProperties = {properties: Record<string, unknown>};
+
+/** Parse JSON-encoded MVT properties according to Tangram's `parse_json` option. */
+export function parseMvtJsonProperties(
+  feature: FeatureWithProperties,
+  parseJson: ParseJsonOption
+): void {
+  if (!parseJson) {
+    return;
+  }
+
+  const properties = feature.properties;
+  const propertyNames = Array.isArray(parseJson) ? parseJson : Object.keys(properties);
+  for (const propertyName of propertyNames) {
+    const value = properties[propertyName];
+    if (typeof value !== 'string') {
+      continue;
+    }
+    if (parseJson === true && value[0] !== '{' && value[0] !== '[') {
+      continue;
+    }
+    try {
+      properties[propertyName] = JSON.parse(value);
+    } catch {
+      // Preserve the original value when it is not valid JSON.
+    }
+  }
+}

package/src/procedures/mvt-tile-provider.ts

@@ -0,0 +1,72 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Tile coordinates passed to a registered MVT tile provider. */
+export type MvtTileIndex = {x: number; y: number; z: number};
+
+/** Loads encoded vector-tile bytes for a Tangram source URL and tile index. */
+export type MvtTileProvider = (
+    url: string,
+    tileIndex: MvtTileIndex
+) => Promise<ArrayBuffer | Uint8Array | null> | ArrayBuffer | Uint8Array | null;
+
+/** Metadata supplied by TileJSON or an archive without depending on a renderer. */
+export interface MvtProviderMetadata {
+    /** Container format, distinct from the encoded tile MIME type. */
+    format?: string;
+    /** Encoded tile MIME type, when known. */
+    tileMIMEType?: string;
+    /** Provider's human-readable name. */
+    name?: string;
+    /** Required provider credits, never interpreted as trusted HTML. */
+    attributions?: readonly string[];
+    /** Lowest advertised tile level. */
+    minZoom?: number;
+    /** Highest advertised tile level. */
+    maxZoom?: number;
+    /** Geographic extent, including west greater than east at the antimeridian. */
+    boundingBox?: readonly [readonly [number, number], readonly [number, number]];
+}
+
+/** Source-owned handle for archive metadata, cancellable requests and explicit teardown. */
+export interface MvtTileProviderSource {
+    /** Acquire encoded bytes; a canceled request must not publish a decoded tile. */
+    getTile(index: MvtTileIndex, signal?: AbortSignal): Promise<ArrayBuffer | Uint8Array | null>;
+    /** Resolve source capabilities and credits without fetching tile payloads. */
+    getMetadata?(): Promise<MvtProviderMetadata>;
+    /** Cancel pending transport work and release this source's archive/cache references. */
+    dispose(): void;
+}
+
+/** Factory isolates archive ownership by Tangram source instance rather than global URL. */
+export interface MvtTileProviderFactory {
+    /** Create a handle for the resolved URL and optional authenticated request headers. */
+    createSource(url: string, options: {headers?: Record<string, string>}): MvtTileProviderSource;
+}
+
+/** Existing stateless functions remain valid; factories add optional lifecycle capabilities. */
+export type MvtTileProviderRegistration = MvtTileProvider | MvtTileProviderFactory;
+
+const mvtTileProviders = new Map<string, MvtTileProviderRegistration>();
+
+/** Register an MVT tile provider and return a function that removes that registration. */
+export function registerMvtTileProvider(name: string, provider: MvtTileProviderRegistration): () => void {
+    if (!name || !(typeof provider === 'function' || provider && typeof provider.createSource === 'function')) {
+        throw new Error('MVT tile provider registration requires a name and provider function or source factory');
+    }
+    if (mvtTileProviders.has(name)) {
+        throw new Error(`MVT tile provider '${name}' is already registered`);
+    }
+    mvtTileProviders.set(name, provider);
+    return () => {
+        if (mvtTileProviders.get(name) === provider) {
+            mvtTileProviders.delete(name);
+        }
+    };
+}
+
+/** Find a registered MVT tile provider by name. */
+export function getMvtTileProvider(name: string): MvtTileProviderRegistration | undefined {
+    return mvtTileProviders.get(name);
+}

package/src/procedures/pmtiles-loader.ts

@@ -0,0 +1,75 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {PMTilesSourceLoader} from '@loaders.gl/pmtiles';
+import type {MvtProviderMetadata, MvtTileProviderFactory, MvtTileProviderSource} from './mvt-tile-provider';
+
+type PMTilesTileSource = ReturnType<typeof PMTilesSourceLoader.createDataSource>;
+
+/** PMTiles transport factory; every Tangram source owns exactly one archive handle. */
+export const pmtilesTileProvider: MvtTileProviderFactory = {createSource: createPMTilesSource};
+
+/** Acquire archive metadata and raw tile bytes without a global URL cache or a decoder switch. */
+export function createPMTilesSource(url: string, options: {headers?: Record<string, string>} = {}): MvtTileProviderSource {
+    const lifetime = new AbortController();
+    let source: PMTilesTileSource | undefined = PMTilesSourceLoader.createDataSource(url, {
+        core: {fetch: async (requestUrl: string, requestOptions: RequestInit = {}) => {
+            const controller = new AbortController();
+            const abort = (): void => controller.abort();
+            const requestSignal = requestOptions.signal;
+            if (lifetime.signal.aborted || requestSignal?.aborted) controller.abort();
+            lifetime.signal.addEventListener('abort', abort, {once: true});
+            requestSignal?.addEventListener('abort', abort, {once: true});
+            try {
+                const headers = new Headers(requestOptions.headers);
+                for (const [name, value] of Object.entries(options.headers ?? {})) headers.set(name, value);
+                const response = await fetch(requestUrl, {...requestOptions, headers, signal: controller.signal});
+                // Range transports consume the body after fetch resolves. Keep the
+                // lifetime signal bound until that body finishes, not just headers.
+                const bytes = await response.arrayBuffer();
+                return new Response(bytes, {status: response.status, statusText: response.statusText, headers: response.headers});
+            } finally {
+                lifetime.signal.removeEventListener('abort', abort);
+                requestSignal?.removeEventListener('abort', abort);
+            }
+        }}
+    });
+    // loaders.gl starts metadata eagerly; retain the rejection for getMetadata(),
+    // but do not emit an unhandled rejection when a source is disposed before use.
+    const metadata = source.metadata;
+    void metadata.catch(() => {});
+    let capabilities: Promise<MvtProviderMetadata> | undefined;
+    return {
+        async getTile(index, signal) {
+            if (!source || signal?.aborted) throw createAbortError();
+            const bytes = await source.getTile({...index, signal});
+            if (!source || signal?.aborted) throw createAbortError();
+            return bytes;
+        },
+        async getMetadata() {
+            if (!source) throw createAbortError();
+            if (!capabilities) {
+                // alpha.8 drops credits in both normalized metadata surfaces.
+                // Keep the raw archive JSON as well, without changing its parser.
+                capabilities = Promise.all([metadata, source.pmtiles.getMetadata()]).then(([value, raw]) => {
+                    const rawAttribution = raw && typeof raw === 'object' && 'attribution' in raw ? raw.attribution : undefined;
+                    const nestedAttribution = value.tilejson?.htmlAttribution;
+                    return {...value, attributions: [...new Set([...(value.attributions ?? []),
+                        ...[nestedAttribution, rawAttribution].filter((credit): credit is string => typeof credit === 'string')])]};
+                });
+            }
+            const value = await capabilities;
+            if (!source) throw createAbortError();
+            return value;
+        },
+        dispose() { lifetime.abort(); source = undefined; }
+    };
+}
+
+/** Cancellation stays distinguishable from missing archive content. */
+function createAbortError(): Error {
+    const error = new Error('PMTiles source request aborted');
+    error.name = 'AbortError';
+    return error;
+}

package/src/procedures/projected-coordinate-transform.ts

@@ -0,0 +1,79 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ProjectionEngineOptions, ProjectionEngine, ProjectionEngineTransform} from '../types';
+import {normalizeProjectedBasemapOptions} from './mesh-projector';
+import type {ProjectedBasemapOptions} from './mesh-projector';
+import {ProjectionBatchExecutor} from './projection-batch-executor';
+import type {ProjectionExecutionOptions, ProjectionExecutionStatistics} from './projection-batch-executor';
+
+/** Tangram's projected common-space units per projected meter. */
+export const PROJECTED_COMMON_SCALE = 256 / 6378137;
+
+/** Compile the same geographic-degree to north-positive meter contract on either thread. */
+export function getProjectedCoordinateOptions(type: ProjectedBasemapOptions['type']): ProjectionEngineOptions {
+    normalizeProjectedBasemapOptions({type});
+    const parameters = type === 'equal-earth' ? '+proj=eqearth +lon_0=0' :
+        type === 'albers' ? '+proj=aea +lon_0=-96 +lat_0=37.5 +lat_1=29.5 +lat_2=45.5' :
+            type === 'mercator' || type === 'web-mercator' ? '+proj=merc +lon_0=0 +k_0=1 +over' :
+                '+proj=eqc +lon_0=0 +lat_0=0 +lat_ts=0';
+    const geometry = type === 'mercator' ? '+ellps=WGS84' : '+R=6378137';
+    return {from: `+proj=longlat ${geometry}`, to: `${parameters} ${geometry} +units=m`};
+}
+
+/** Reject transform instances and malformed factories before allocating renderer resources. */
+export function validateProjectionEngine(engine: ProjectionEngine | undefined): void {
+    if (engine !== undefined && (!engine || typeof engine.createProjection !== 'function' ||
+        typeof engine.createProjectionAsync !== 'function')) {
+        throw new Error('projectionEngine must implement the math.gl ProjectionEngine factory contract');
+    }
+}
+
+/** Scene-owned transforms; the caller owns the engine and its registrations/grids. */
+export class HostProjectionEngineAdapter {
+    /** Independent asynchronous compilation per CRS pair, shared across meshes and workers. */
+    private readonly transforms = new Map<ProjectedBasemapOptions['type'], Promise<ProjectionEngineTransform>>();
+    /** Prevent late worker batches from publishing after scene teardown. */
+    private disposed = false;
+    /** Cooperative execution and cancellation for scene-owned host requests. */
+    private readonly executor: ProjectionBatchExecutor;
+
+    /** Retain, but never mutate or dispose, the supplied factory. */
+    constructor(private readonly engine: ProjectionEngine, options: ProjectionExecutionOptions = {}) {
+        validateProjectionEngine(engine);
+        this.executor = new ProjectionBatchExecutor(options);
+    }
+
+    /** Project one packed longitude/latitude batch to common coordinates without modifying input. */
+    async projectPositions(coordinates: Float64Array, type: ProjectedBasemapOptions['type'], signal?: AbortSignal): Promise<Float64Array> {
+        if (this.disposed) throw new Error('Projection engine adapter is disposed');
+        const options = getProjectedCoordinateOptions(type);
+        if (!(coordinates instanceof Float64Array) || coordinates.length % 2 !== 0 ||
+            !coordinates.every((value, index) => Number.isFinite(value) && Math.abs(value) <=
+                (index % 2 === 0 ? 180 : 85.0511287798066))) {
+            throw new Error('Projection engine requires packed finite geographic degrees within the tile domain');
+        }
+        return this.executor.execute(coordinates, () => {
+            let pending = this.transforms.get(type);
+            if (!pending) {
+                pending = Promise.resolve().then(() => this.engine.createProjectionAsync(options));
+                this.transforms.set(type, pending);
+                pending.catch(() => {if (this.transforms.get(type) === pending) this.transforms.delete(type);});
+            }
+            return pending;
+        }, {signal, scale: PROJECTED_COMMON_SCALE, maxAbsoluteValue: 3.4028234663852886e38});
+    }
+
+    /** Detached host execution counters, separate from mesh and decoded-source residency. */
+    getStatistics(): ProjectionExecutionStatistics {
+        return this.executor.getStatistics();
+    }
+
+    /** Release scene-owned transforms without taking ownership of the injected factory. */
+    dispose(): void {
+        this.disposed = true;
+        this.executor.dispose();
+        this.transforms.clear();
+    }
+}

package/src/procedures/projection-batch-executor.ts

@@ -0,0 +1,140 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ProjectionEngineTransform} from '../types';
+
+/** 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 function normalizeProjectionExecutionOptions(options: ProjectionExecutionOptions = {}): Required<ProjectionExecutionOptions> {
+    const maxBatchPositions = options.maxBatchPositions === undefined ? 4096 : options.maxBatchPositions;
+    if (!Number.isSafeInteger(maxBatchPositions) || maxBatchPositions < 1 || maxBatchPositions > 65536) {
+        throw new Error('Projection execution requires maxBatchPositions in [1, 65536]');
+    }
+    return {maxBatchPositions};
+}
+
+/** Run independent packed batches with detached input, cooperative yields and prompt cancellation. */
+export class ProjectionBatchExecutor {
+    /** Cancels pending operations without taking ownership of transforms or factories. */
+    private readonly lifetime = new AbortController();
+    /** Detached snapshots are returned instead of exposing these mutable counters. */
+    private readonly statistics: ProjectionExecutionStatistics;
+
+    /** Capture an immutable per-kernel-call execution policy. */
+    constructor(options: ProjectionExecutionOptions = {}) {
+        this.statistics = {...normalizeProjectionExecutionOptions(options), activeRequests: 0,
+            completedRequests: 0, failedRequests: 0, cancelledRequests: 0, submittedPositions: 0,
+            batches: 0, yieldCount: 0};
+    }
+
+    /** Capture input before compilation; abort only this output, never a shared factory promise. */
+    async execute(coordinates: Float64Array, getTransform: () => Promise<ProjectionEngineTransform>,
+        options: ProjectionBatchRequestOptions = {}): Promise<Float64Array> {
+        const scale = options.scale ?? 1;
+        const maximum = options.maxAbsoluteValue ?? Infinity;
+        const allowNonfinite = options.allowNonfinite ?? false;
+        if (!(coordinates instanceof Float64Array) || coordinates.length % 2 !== 0 ||
+            !coordinates.every(Number.isFinite) || !Number.isFinite(scale) ||
+            maximum <= 0 || (options.maxAbsoluteValue !== undefined && !Number.isFinite(maximum))) {
+            throw new Error('Projection batches require finite coordinate pairs, scale and output bounds');
+        }
+        const signals = [this.lifetime.signal, ...(options.signal ? [options.signal] : [])];
+        const cancelled = () => signals.some(signal => signal.aborted);
+        const abortError = () => {const error = new Error(this.lifetime.signal.aborted ? 'Projection operation disposed' : 'Projection operation aborted'); error.name = 'AbortError'; return error;};
+        if (cancelled()) throw abortError();
+        const result = coordinates.slice();
+        let rejectCancellation: (error: Error) => void = () => {};
+        const cancellation = new Promise<never>((_resolve, reject) => {rejectCancellation = reject;});
+        const onAbort = () => rejectCancellation(abortError());
+        for (const signal of signals) signal.addEventListener('abort', onAbort, {once: true});
+        this.statistics.activeRequests++;
+        try {
+            const work = async () => {
+                // Stop awaiting a caller-owned compilation on abort; do not retain this
+                // request's coordinate snapshot until an unrelated factory settles.
+                const transform = await Promise.race([getTransform(), cancellation]);
+                if (cancelled()) throw abortError();
+                const stride = this.statistics.maxBatchPositions * 2;
+                for (let offset = 0; offset < result.length; offset += stride) {
+                    if (cancelled()) throw abortError();
+                    const chunk = result.subarray(offset, Math.min(result.length, offset + stride));
+                    this.statistics.batches++;
+                    this.statistics.submittedPositions += chunk.length / 2;
+                    transform.projectFlatSync(chunk, 2);
+                    for (let index = 0; index < chunk.length; index++) {
+                        chunk[index] *= scale;
+                        if ((!allowNonfinite && !Number.isFinite(chunk[index])) || Math.abs(chunk[index]) > maximum) {
+                            throw new Error(maximum === Infinity ?
+                                'Projection engine produced nonfinite output coordinates' : 'Projection engine produced an invalid Float32 common position');
+                        }
+                    }
+                    if (offset + stride < result.length) {
+                        this.statistics.yieldCount++;
+                        await new Promise<void>(resolve => setTimeout(resolve, 0));
+                    }
+                }
+                if (cancelled()) throw abortError();
+                return result;
+            };
+            const output = await Promise.race([work(), cancellation]);
+            if (cancelled()) throw abortError();
+            this.statistics.completedRequests++;
+            return output;
+        } catch (error) {
+            if (cancelled()) this.statistics.cancelledRequests++;
+            else this.statistics.failedRequests++;
+            throw error;
+        } finally {
+            this.statistics.activeRequests--;
+            for (const signal of signals) signal.removeEventListener('abort', onAbort);
+        }
+    }
+
+    /** Return detached counters; no factory objects, coordinate buffers or mutable references escape. */
+    getStatistics(): ProjectionExecutionStatistics {
+        return {...this.statistics};
+    }
+
+    /** Reject pending requests immediately; synchronous kernels cannot be interrupted mid-call. */
+    dispose(): void {
+        this.lifetime.abort();
+    }
+}

package/src/procedures/scene-yaml-legacy.ts

@@ -0,0 +1,16 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import yaml from 'js-yaml';
+
+/**
+ * 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 function parseSceneYamlLegacy(source: string): unknown {
+    // Existing Tangram behavior allows duplicate keys despite the YAML specification.
+    return yaml.safeLoad(source, { json: true });
+}