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

package/src/sources/shared_tile_source_adapter.ts

@@ -0,0 +1,117 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import DataSource from './data_source';
+import {MVTSource} from './mvt';
+import {GeoJSONTileSource} from './geojson';
+import {RasterTileSource} from './raster';
+import Utils from '../utils/utils';
+import AlignedTangramTileSource from './aligned_tile_source';
+import TangramTileSourceAdapter from './tile_source_adapter';
+import type {TileSourceContext} from './tile_source_adapter';
+import {applyTilePayload, getTileSourceRequest, updateTileSourceRequest} from './tile_source_state';
+import type {DecodedTilePayload, TileSourceRequestState} from './tile_source_state';
+import DecodedTileStore, {createTileLeaseAbortError} from './decoded_tile_store';
+import type {DecodedTileLease, DecodedTileStoreOptions} from './decoded_tile_store';
+
+/** Acquisition anchors copied from worker messages, without mesh or build ownership. */
+export interface SharedTileContext extends TileSourceContext {
+    /** Legacy diagnostic identity; never part of shared data identity. */
+    key: string;
+    /** Tile northwest in EPSG:3857 meters. */
+    min: {x: number; y: number};
+    /** Tile southeast in EPSG:3857 meters. */
+    max: {x: number; y: number};
+    /** Per-consumer detached diagnostic fields. */
+    debug?: Record<string, unknown>;
+}
+
+/** Reusable content and acquisition diagnostics, excluding live request IDs and consumer contexts. */
+interface SharedTileResult {
+    /** Original postprocessed geometry, winding, seam padding and attached rasters. */
+    readonly payload: DecodedTilePayload;
+    /** Resolved legacy provider error and URL; never ownership of a cancellation ID. */
+    readonly diagnostics: Pick<TileSourceRequestState, 'error' | 'url'>;
+    /** Detached timing fields; each consumer receives its own debug shell. */
+    readonly debug: Readonly<Record<string, unknown>>;
+}
+
+/** Only exact built-in tiled pipelines without custom hooks participate in production sharing. */
+export function supportsSharedTileAcquisition(source: unknown): source is DataSource {
+    if (!(source instanceof DataSource) || source.transform || source.preprocess || source.scripts?.length) return false;
+    if (Object.getOwnPropertyNames(source).some(name => typeof Reflect.get(source, name) === 'function')) return false;
+    if (source instanceof MVTSource && Object.getPrototypeOf(source) === MVTSource.prototype) {
+        return source.decoder === 'tangram' && !source.tile_provider &&
+            source.load === MVTSource.prototype.load && source.parseSourceData === MVTSource.prototype.parseSourceData;
+    }
+    if (source instanceof GeoJSONTileSource && Object.getPrototypeOf(source) === GeoJSONTileSource.prototype) {
+        return source.load === GeoJSONTileSource.prototype.load && source.parseSourceData === GeoJSONTileSource.prototype.parseSourceData;
+    }
+    return source instanceof RasterTileSource && Object.getPrototypeOf(source) === RasterTileSource.prototype && source.load === RasterTileSource.prototype.load;
+}
+
+/** Worker-local ownership bridge; custom sources continue through the original first-match procedure. */
+export default class SharedTileSourceAdapter<TileT extends SharedTileContext> {
+    /** No unreferenced warm cache; content stays alive only while worker tile leases need it. */
+    readonly store: DecodedTileStore<SharedTileResult>;
+    /** Worker tile identity owns its own lease, never the underlying request's cancellation ID. */
+    private leases = new WeakMap<TileT, DecodedTileLease<SharedTileResult>>();
+    /** Workers with imported external scripts cannot assume built-in prototype purity. */
+    readonly sharingEnabled: boolean;
+
+    /** Enable only known built-in pipelines; external worker scripts conservatively disable sharing. */
+    constructor(sharingEnabled = true, options: DecodedTileStoreOptions = {}) {
+        this.sharingEnabled = sharingEnabled;
+        this.store = new DecodedTileStore<SharedTileResult>(result => result.payload.byteLength, options);
+    }
+
+    /** Acquire compatible decoded content or preserve the original custom-source loading path. */
+    loadTile(tile: TileT, source: DataSource | undefined, getRetainedTiles: () => Iterable<TileT>): Promise<TileT> {
+        this.releaseTile(tile);
+        if (!this.sharingEnabled || !supportsSharedTileAcquisition(source)) {
+            return new TangramTileSourceAdapter(source, getRetainedTiles).getTileData({index: tile.coords, id: tile.key, context: tile});
+        }
+        const context: SharedTileContext = {source: tile.source, key: tile.key, coords: {...tile.coords},
+            min: {...tile.min}, max: {...tile.max}, debug: {}};
+        const lease = this.store.acquireTile({source, key: tile.coords.key, load: async signal => {
+            // The worker's traversal already applied display/bounds policy. Do not re-filter by data zoom.
+            const aligned = new AlignedTangramTileSource({load: destination => source.load(destination),
+                copyTileData: (reference, destination) => source.copyTileData(reference, destination),
+                getMetadata: () => source.getMetadata()}, {createContext: () => context, cancel: destination => {
+                const request = getTileSourceRequest(destination);
+                if (request.requestId) Utils.cancelRequest(request.requestId);
+                updateTileSourceRequest(destination, {requestId: null});
+            }});
+            const payload = await aligned.getTileData({index: context.coords, id: context.key,
+                bbox: {left: context.min.x, top: context.min.y, right: context.max.x, bottom: context.max.y}, signal});
+            if (!payload) throw new Error('Shared tile acquisition unexpectedly returned no payload');
+            const request = getTileSourceRequest(context);
+            return {payload, diagnostics: {error: request.error, url: request.url}, debug: {...context.debug}};
+        }});
+        this.leases.set(tile, lease);
+        return lease.promise.then(result => {
+            if (this.leases.get(tile) !== lease || !lease.isActive()) throw createTileLeaseAbortError();
+            applyTilePayload(tile, result.payload);
+            updateTileSourceRequest(tile, result.diagnostics);
+            tile.debug = {...tile.debug, ...result.debug};
+            return tile;
+        }).catch(error => {
+            if (this.leases.get(tile) === lease) this.releaseTile(tile);
+            throw error;
+        });
+    }
+
+    /** Release this tile's interest; the final consumer alone cancels pending acquisition. */
+    releaseTile(tile: TileT): void {
+        const lease = this.leases.get(tile);
+        this.leases.delete(tile);
+        lease?.release();
+    }
+
+    /** Invalidate one source instance while preserving unchanged sources and style-only rebuilds. */
+    invalidateSource(source: object): void { this.store.invalidateSource(source); }
+
+    /** Release all content and pending work at worker reinitialization or explicit teardown. */
+    finalize(): void { this.store.finalize(); this.leases = new WeakMap(); }
+}

package/src/sources/sources.ts

@@ -0,0 +1,10 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// add all data source types
+import './geojson';
+import './topojson';
+import './mvt';
+import './raster';

package/src/sources/tile_source_adapter.ts

@@ -0,0 +1,84 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import type {TileCoordinates} from '../tile/tile_id';
+import {captureTilePayload} from './tile_source_state';
+import type {TileDataContext} from './tile_source_state';
+
+/** Worker-side request context; contains source data, never main-thread GPU meshes. */
+export interface TileSourceContext extends TileDataContext {
+    /** Scene source identity, kept distinct from data and style tile identity. */
+    source: string;
+    /** Source-normalized data coordinates; style zoom must not enter data-reuse matching. */
+    coords: TileCoordinates & {key: string};
+    /** Whether source data is available for reuse. */
+    loaded?: boolean;
+}
+
+/** Existing source procedures, preserved until individual loaders.gl switches pass conformance. */
+export interface LegacyTileDataSource<TileT extends TileSourceContext> {
+    /** Load and postprocess data into the live worker context. */
+    load(tile: TileT): Promise<TileT>;
+    /** Reuse decoded source data while preserving the destination's style/build identity. */
+    copyTileData(reference: TileT, destination: TileT): TileT;
+}
+
+/**
+ * Index/id request envelope analogous to loaders.gl's getTileData parameters.
+ * The required context is Tangram-specific: this is not yet a loaders.gl TileSource.
+ */
+export interface TangramTileDataRequest<TileT extends TileSourceContext> {
+    /** Data index, not the source/style mesh-cache key. */
+    readonly index: TileCoordinates;
+    /** Destination build identity; not used to decide decoded-data reuse. */
+    readonly id: string;
+    /** Live legacy context, retained so request IDs and cancellation stay on the worker's tile. */
+    readonly context: TileT;
+}
+
+/** Preserve the worker's legacy enumerable-property order without allocating a table snapshot. */
+export function* iterateSourceTiles<TileT>(tiles: Readonly<Record<string, TileT>>): Iterable<TileT> {
+    for (const key in tiles) yield tiles[key];
+}
+
+/**
+ * Data acquisition/reuse seam with no renderer, traversal, or GPU dependency.
+ *
+ * Keep the mutable context and resolved-versus-rejected error behavior intact.
+ * Publish a decoded payload record while retaining the legacy context facade.
+ * The separate aligned source bridge supplies metadata and AbortSignal translation.
+ */
+export default class TangramTileSourceAdapter<TileT extends TileSourceContext> {
+    /** Current legacy source; undefined preserves the missing-source worker behavior. */
+    private readonly source: LegacyTileDataSource<TileT> | undefined;
+    /** Read the current worker table at request time, never a stale registry snapshot. */
+    private readonly getRetainedTiles: () => Iterable<TileT>;
+
+    /** Bind one source to a caller-owned decoded-data registry. */
+    constructor(source: LegacyTileDataSource<TileT> | undefined, getRetainedTiles: () => Iterable<TileT>) {
+        this.source = source;
+        this.getRetainedTiles = getRetainedTiles;
+    }
+
+    /** Acquire source data using the original first-match reuse and loading procedures. */
+    getTileData({context}: TangramTileDataRequest<TileT>): Promise<TileT> {
+        if (this.source) {
+            for (const reference of this.getRetainedTiles()) {
+                if (reference.source === context.source && reference.coords.key === context.coords.key && reference.loaded) {
+                    const destination = this.source.copyTileData(reference, context);
+                    captureTilePayload(destination);
+                    return Promise.resolve(destination);
+                }
+            }
+            return this.source.load(context).then(destination => {
+                captureTilePayload(destination);
+                return destination;
+            });
+        }
+        context.source_data = {};
+        captureTilePayload(context);
+        return Promise.resolve(context);
+    }
+}

package/src/sources/tile_source_metadata.ts

@@ -0,0 +1,65 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Source metadata subset structurally compatible with loaders.gl TileSourceMetadata. */
+export interface TangramTileSourceMetadata {
+    /** Source/container format, not a promise to select a different parser. */
+    format?: string;
+    /** Encoded tile MIME type, separate from archive format and decoder selection. */
+    tileMIMEType?: string;
+    /** Human-readable source name. */
+    name?: string;
+    /** Provider credits; consumers must sanitize before rendering HTML. */
+    attributions?: string[];
+    /** Minimum advertised data level. */
+    minZoom?: number;
+    /** Maximum advertised data level. */
+    maxZoom?: number;
+    /** Geographic bounds, retaining antimeridian-crossing west/east ordering. */
+    boundingBox?: [[number, number], [number, number]];
+}
+
+/** Configuration plus discovered metadata, without depending on the DataSource implementation. */
+export interface SourceMetadataInput {
+    /** Original scene source options. */
+    config: Record<string, unknown>;
+    /** Logical scene source name. */
+    name: string;
+    /** Effective legacy data levels. */
+    zooms: readonly number[];
+    /** Effective legacy data ceiling. */
+    max_zoom: number;
+    /** Authored and discovered provider credits. */
+    getAttributions(): string[];
+}
+
+/** Normalize metadata for new consumers without changing legacy source layout or URL resolution. */
+export function createTileSourceMetadata(source: SourceMetadataInput, discovered: Record<string, unknown> = {}): TangramTileSourceMetadata {
+    const config = source.config;
+    const bounds = config.bounds ?? discovered.bounds ?? discovered.boundingBox;
+    const metadata: TangramTileSourceMetadata = {name: typeof discovered.name === 'string' ? discovered.name : source.name, attributions: source.getAttributions(),
+        minZoom: source.zooms[0], maxZoom: source.max_zoom};
+    const format = discovered.format ?? config.type;
+    if (typeof format === 'string') metadata.format = format;
+    if (typeof discovered.tileMIMEType === 'string') metadata.tileMIMEType = discovered.tileMIMEType;
+    const maximum = discovered.maxzoom ?? discovered.maxZoom;
+    const minimum = discovered.minzoom ?? discovered.minZoom;
+    if (config.zooms === undefined && config.max_zoom === undefined && validZoom(maximum)) metadata.maxZoom = maximum;
+    if (config.zooms === undefined && validZoom(minimum)) metadata.minZoom = minimum;
+    if (metadata.minZoom !== undefined && metadata.maxZoom !== undefined && metadata.minZoom > metadata.maxZoom) {
+        metadata.minZoom = source.zooms[0];
+        metadata.maxZoom = source.max_zoom;
+    }
+    const flattened = Array.isArray(bounds) && bounds.length === 2 && bounds.every(value => Array.isArray(value) && value.length === 2) ? bounds.flat() : bounds;
+    if (Array.isArray(flattened) && flattened.length === 4 && flattened.every(value => typeof value === 'number' && Number.isFinite(value)) &&
+        Math.abs(flattened[0]) <= 180 && Math.abs(flattened[2]) <= 180 && flattened[1] >= -90 && flattened[3] <= 90 && flattened[1] <= flattened[3]) {
+        metadata.boundingBox = [[flattened[0], flattened[1]], [flattened[2], flattened[3]]];
+    }
+    return metadata;
+}
+
+/** Reject unusable advertised levels rather than passing NaN or infinite values to traversal. */
+function validZoom(value: unknown): value is number {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 30;
+}

package/src/sources/tile_source_state.ts

@@ -0,0 +1,112 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Legacy compatibility envelope; network bookkeeping is not reusable decoded content. */
+export interface TileSourceData {
+    /** Postprocessed source layers, shared by the existing overzoom path. */
+    layers?: Record<string, unknown>;
+    /** Legacy cancellation identity. */
+    request_id?: string | null;
+    /** Resolved provider error, retained for the legacy warn-and-continue path. */
+    error?: string | null;
+    /** Resolved source URL. */
+    url?: string;
+}
+
+/** Worker-side structural surface; no scene, styles or GPU content. */
+export interface TileDataContext {
+    /** Temporary legacy data facade used by existing parsers and transforms. */
+    source_data?: TileSourceData;
+    /** Attached raster identities. */
+    rasters?: string[];
+    /** Seam padding already applied during postprocessing. */
+    pad_scale?: number;
+    /** Source polygon winding after postprocessing. */
+    default_winding?: string | null;
+}
+
+/** Reusable decoded content, deliberately excluding URLs, errors and cancellation IDs. */
+export interface DecodedTilePayload {
+    /** Tangram-local layer references (4096-unit tiles, negative local Y); not geographic GeoJSON. */
+    readonly layers?: Record<string, unknown>;
+    /** Detached list of attached raster sources. */
+    readonly rasters: readonly string[];
+    /** Seam padding retained when rebinding content to a style/build tile. */
+    readonly padScale?: number;
+    /** Polygon winding retained when rebinding content. */
+    readonly defaultWinding?: string | null;
+    /** Optional decoded-content allocation estimate supplied by an owning adapter, never encoded response bytes. */
+    readonly byteLength?: number;
+}
+
+/** Per-request mutable state, never shared with an overzoom payload. */
+export interface TileSourceRequestState {
+    /** Source-owned cancellation hook for providers that do not use legacy XHR request IDs. */
+    cancel?: () => void;
+    /** Legacy cancellation identity, when a provider exposes one. */
+    requestId?: string | null;
+    /** Resolved provider error, distinct from a thrown/rejected load. */
+    error?: string | null;
+    /** Resolved source URL. */
+    url?: string;
+}
+
+/** Request records follow context lifetime without entering worker messages. */
+const requestStates = new WeakMap<TileDataContext, TileSourceRequestState>();
+/** Decoded records follow context lifetime without retaining evicted worker tiles. */
+const payloads = new WeakMap<TileDataContext, DecodedTilePayload>();
+/** Aborted aligned requests can cancel IDs assigned after asynchronous URL resolution. */
+const cancellationListeners = new WeakMap<TileDataContext, () => void>();
+
+/** Read request state, including writes by an unmodified custom legacy source. */
+export function getTileSourceRequest(context: TileDataContext): TileSourceRequestState {
+    const state = requestStates.get(context) ?? {};
+    const legacy = context.source_data;
+    state.requestId = legacy?.request_id;
+    state.error = legacy?.error;
+    state.url = legacy?.url;
+    requestStates.set(context, state);
+    return state;
+}
+
+/** Write separated request state and preserve the legacy parser/cancellation facade. */
+export function updateTileSourceRequest(context: TileDataContext, changes: Partial<TileSourceRequestState>): void {
+    const state = getTileSourceRequest(context);
+    Object.assign(state, changes);
+    const legacy = context.source_data ??= {};
+    if ('requestId' in changes) legacy.request_id = changes.requestId;
+    if ('error' in changes) legacy.error = changes.error;
+    if ('url' in changes) legacy.url = changes.url;
+    if (changes.requestId || changes.cancel) cancellationListeners.get(context)?.();
+}
+
+/** Keep a cancellation hook attached until the legacy load settles, including late request IDs. */
+export function bindTileSourceCancellation(context: TileDataContext, cancel: () => void): () => void {
+    cancellationListeners.set(context, cancel);
+    return () => { if (cancellationListeners.get(context) === cancel) cancellationListeners.delete(context); };
+}
+
+/** Publish postprocessed content without cloning or freezing legacy feature objects. */
+export function captureTilePayload(context: TileDataContext): DecodedTilePayload {
+    const payload: DecodedTilePayload = {layers: context.source_data?.layers,
+        rasters: [...(context.rasters ?? [])], padScale: context.pad_scale, defaultWinding: context.default_winding};
+    getTileSourceRequest(context);
+    payloads.set(context, payload);
+    return payload;
+}
+
+/** Retrieve the last decoded publication, without retaining request/build state in the payload. */
+export function getTilePayload(context: TileDataContext): DecodedTilePayload | undefined {
+    return payloads.get(context);
+}
+
+/** Bind reusable content to a new build context with fresh request state. */
+export function applyTilePayload(context: TileDataContext, payload: DecodedTilePayload): void {
+    context.source_data = {layers: payload.layers};
+    context.rasters = [...payload.rasters];
+    context.pad_scale = payload.padScale;
+    context.default_winding = payload.defaultWinding;
+    requestStates.set(context, {});
+    payloads.set(context, payload);
+}

package/src/sources/topojson.ts

@@ -0,0 +1,90 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import DataSource from './data_source';
+import {GeoJSONSource, GeoJSONTileSource} from './geojson';
+
+import * as topojson from 'topojson-client';
+
+type SourceConfig = Record<string, any>;
+
+/**
+ TopoJSON standalone (non-tiled) source
+ Uses geojson-vt split into tiles client-side
+*/
+
+export class TopoJSONSource extends GeoJSONSource {
+
+    parseSourceData (tile?: any, source?: any, response?: any): void {
+        if (!tile || !source) {
+            throw new Error('TopoJSON source parsing requires a tile and source data');
+        }
+        let data = typeof response === 'string' ? JSON.parse(response) : response;
+        data = this.toGeoJSON(data);
+
+        let layers = this.getLayers(data);
+        super.preprocessLayers(layers, tile);
+        source.layers = layers;
+    }
+
+    toGeoJSON (data: any): any {
+        // Single layer
+        if (data.objects &&
+            Object.keys(data.objects).length === 1) {
+            let layer = Object.keys(data.objects)[0];
+            data = getTopoJSONFeature(data, data.objects[layer]);
+        }
+        // Multiple layers
+        else {
+            let layers: Record<string, any> = {};
+            for (let key in data.objects) {
+                layers[key] = getTopoJSONFeature(data, data.objects[key]);
+            }
+            data = layers;
+        }
+        return data;
+    }
+
+}
+
+function getTopoJSONFeature (topology: any, object: any): any {
+    let feature = topojson.feature(topology, object);
+
+    // Convert single feature to a feature collection
+    if (feature.type === 'Feature') {
+        feature = {
+            type: 'FeatureCollection',
+            features: [feature]
+        };
+    }
+    return feature;
+}
+
+
+/**
+ TopoJSON vector tiles
+ @class TopoJSONTileSource
+*/
+export class TopoJSONTileSource extends GeoJSONTileSource {
+
+    constructor(source: SourceConfig, sources?: Record<string, unknown>) {
+        super(source, sources);
+    }
+
+    parseSourceData (tile?: any, source?: any, response?: any): void {
+        if (!tile || !source) {
+            throw new Error('TopoJSON tile parsing requires a tile and source data');
+        }
+        let data = typeof response === 'string' ? JSON.parse(response) : response;
+        data = TopoJSONSource.prototype.toGeoJSON(data);
+        this.prepareGeoJSON(data, tile, source);
+    }
+
+}
+
+// Check for URL tile pattern, if not found, treat as standalone GeoJSON/TopoJSON object
+DataSource.register('TopoJSON', (source: SourceConfig) => {
+    return TopoJSONTileSource.urlHasTilePattern(source.url) ? TopoJSONTileSource : TopoJSONSource;
+});

package/src/styles/feature_annotations.ts

@@ -0,0 +1,16 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Shared feature visibility keeps the legacy aggregate-generation semantics without mutating content. */
+const renderedGenerations = new WeakMap<object, number>();
+
+/** Mark successful built-in geometry generation in sidecar state, never on decoded features. */
+export function markFeatureRendered(feature: object, generation: number): void {
+    renderedGenerations.set(feature, generation);
+}
+
+/** Read built-in sidecar visibility, falling back to annotations supplied by legacy custom code. */
+export function getFeatureRenderedGeneration(feature: object): unknown {
+    return renderedGenerations.get(feature) ?? ('generation' in feature ? feature.generation : undefined);
+}