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

package/src/builders/wireframe.ts

@@ -0,0 +1,31 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Rearranges element array for triangles into a new element array that draws a wireframe
+// Used for debugging
+export default function makeWireframeForTriangleElementData (element_data: Uint16Array | Uint32Array): Uint16Array {
+    const wireframe_data = new Uint16Array(element_data.length * 2);
+
+    // Draw triangles as lines:
+    // Make a copy of element_data, and for every group of three vertices, duplicate
+    // each vertex according to the following pattern:
+    // [1, 2, 3] => [1, 2, 2, 3, 3, 1]
+    // This takes three vertices which would have been interpreted as a triangle,
+    // and converts them into three 2-vertex line segments.
+    for (let i = 0; i < element_data.length; i += 3) {
+        wireframe_data.set(
+            [
+                element_data[i],
+                element_data[i+1],
+                element_data[i+1],
+                element_data[i+2],
+                element_data[i+2],
+                element_data[i]
+            ],
+            i * 2
+        );
+    }
+    return wireframe_data;
+}

package/src/core.d.ts

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

package/src/core.ts

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

package/src/experimental/loaders-gl-worker.ts

@@ -0,0 +1,19 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {pmtilesTileProvider} from '../procedures/pmtiles-loader';
+import {parseMltWithLoaders} from '../procedures/mlt-loaders';
+import {parseMvtWithLoaders} from '../procedures/mvt-loaders';
+import type {MvtDecoder} from '../procedures/mvt-parser';
+import type {MvtTileProviderRegistration} from '../procedures/mvt-tile-provider';
+
+type TangramWorker = typeof self & {
+    registerMvtDecoder: (name: string, decoder: MvtDecoder) => void;
+    registerMvtTileProvider: (name: string, provider: MvtTileProviderRegistration) => void;
+};
+
+const tangramWorker = self as TangramWorker;
+tangramWorker.registerMvtDecoder('loaders-mvt', parseMvtWithLoaders);
+tangramWorker.registerMvtDecoder('loaders-mlt', parseMltWithLoaders);
+tangramWorker.registerMvtTileProvider('loaders-pmtiles', pmtilesTileProvider);

package/src/experimental/projected-basemaps-worker.ts

@@ -0,0 +1,13 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {projectBasemapMesh, projectBasemapMeshWithEngine, clearProjectedMeshPreparation,
+    getProjectedMeshPreparationStatistics, getProjectedMeshWorkStatistics} from './projected-mesh';
+import type {MeshProjectionRequest} from '../procedures/mesh-projector';
+if (!('registerMeshProjector' in self) || typeof self.registerMeshProjector !== 'function') {
+    throw new Error('Projected basemap script must run inside a Tangram scene worker');
+}
+self.registerMeshProjector((request: MeshProjectionRequest) => request.projectPositions ?
+    projectBasemapMeshWithEngine(request) : projectBasemapMesh(request), clearProjectedMeshPreparation,
+    getProjectedMeshPreparationStatistics, getProjectedMeshWorkStatistics);

package/src/experimental/projected-mesh-cache.ts

@@ -0,0 +1,137 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Immutable prepared or projected mesh owned by one worker. */
+export interface PreparedProjectedMesh {
+    /** Packed source attributes, never transferred or written into projected output. */
+    readonly vertices: Uint8Array;
+    /** Source-space refined triangle topology. */
+    readonly indices: Uint16Array | Uint32Array;
+}
+
+/** Content-addressed entry; exact byte comparison guards against hash collisions. */
+interface PreparationEntry {
+    /** Metadata and source-content lookup identity. */
+    readonly key: string;
+    /** Detached original source bytes for exact equality and mutation detection. */
+    readonly source: Uint8Array;
+    /** Detached source topology; false denotes an unindexed stream. */
+    readonly elements: Uint16Array | Uint32Array | false;
+    /** Immutable prepared geometry. */
+    readonly result: PreparedProjectedMesh;
+    /** Accounted retained typed-array bytes. */
+    readonly bytes: number;
+}
+
+/** Bounded content-addressed LRU; callers supply preparation or target/engine metadata. */
+export class ProjectedMeshPreparationCache {
+    /** Entries ordered oldest to newest, including colliding content hashes. */
+    private readonly entries: PreparationEntry[] = [];
+    /** Bytes retained in original and prepared buffers. */
+    private bytes = 0;
+    /** Number of preparations successfully reused. */
+    private hits = 0;
+    /** Number of requests requiring source preparation. */
+    private misses = 0;
+    /** Reset epoch prevents a late asynchronous preparation from repopulating a cleared cache. */
+    private epoch = 0;
+
+    /** Set worker-local limits; oversized entries are prepared but never retained. */
+    constructor(private readonly maxBytes = 16 * 1024 * 1024, private readonly maxEntries = 64) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 ||
+            !Number.isSafeInteger(maxEntries) || maxEntries < 0) {
+            throw new RangeError('Projection preparation cache requires nonnegative integer limits');
+        }
+    }
+
+    /** Reuse only byte-identical source geometry and identical refinement/layout metadata. */
+    getOrCreate(metadata: string, vertices: Uint8Array, indices: Uint16Array | Uint32Array | false,
+        prepare: () => PreparedProjectedMesh): PreparedProjectedMesh {
+        const cached = this.find(metadata, vertices, indices);
+        return cached ?? this.retain(metadata, vertices, indices, prepare());
+    }
+
+    /** Cache completed asynchronous results only; errors and replies from older epochs are not retained. */
+    async getOrCreateAsync(metadata: string, vertices: Uint8Array, indices: Uint16Array | Uint32Array | false,
+        prepare: () => Promise<PreparedProjectedMesh>): Promise<PreparedProjectedMesh> {
+        const cached = this.find(metadata, vertices, indices);
+        if (cached) return cached;
+        const epoch = this.epoch;
+        const source = vertices.slice();
+        const elements = indices === false ? false : indices.slice();
+        const result = await prepare();
+        return epoch === this.epoch ? this.retain(metadata, source, elements, result) : result;
+    }
+
+    /** Locate byte-identical inputs and update LRU/work counters. */
+    private find(metadata: string, vertices: Uint8Array, indices: Uint16Array | Uint32Array | false): PreparedProjectedMesh | undefined {
+        const key = `${metadata}:${hashBytes(vertices)}:${indices === false ? 'stream' : hashBytes(asBytes(indices))}`;
+        const index = this.entries.findIndex(entry => entry.key === key && equalBytes(entry.source, vertices) &&
+            (entry.elements === false || indices === false ? entry.elements === indices :
+                entry.elements.constructor === indices.constructor && equalBytes(asBytes(entry.elements), asBytes(indices))));
+        if (index >= 0) {
+            const [entry] = this.entries.splice(index, 1);
+            this.entries.push(entry);
+            this.hits++;
+            return entry.result;
+        }
+        this.misses++;
+        return undefined;
+    }
+
+    /** Detach retained inputs and output within the configured byte/entry limits. */
+    private retain(metadata: string, vertices: Uint8Array, indices: Uint16Array | Uint32Array | false,
+        prepared: PreparedProjectedMesh): PreparedProjectedMesh {
+        const key = `${metadata}:${hashBytes(vertices)}:${indices === false ? 'stream' : hashBytes(asBytes(indices))}`;
+        // Concurrent misses may both compute; retain only one byte-identical completed entry.
+        const existing = this.entries.find(entry => entry.key === key && equalBytes(entry.source, vertices) &&
+            (entry.elements === false || indices === false ? entry.elements === indices :
+                entry.elements.constructor === indices.constructor && equalBytes(asBytes(entry.elements), asBytes(indices))));
+        if (existing) return existing.result;
+        const bytes = vertices.byteLength + (indices === false ? 0 : indices.byteLength) +
+            prepared.vertices.byteLength + prepared.indices.byteLength;
+        if (this.maxEntries > 0 && bytes <= this.maxBytes) {
+            while (this.entries.length >= this.maxEntries || this.bytes + bytes > this.maxBytes) {
+                this.bytes -= this.entries.shift()!.bytes;
+            }
+            // Preparation can return aliases of caller input. Detach everything kept by the cache.
+            const result = {vertices: prepared.vertices.slice(), indices: prepared.indices.slice()};
+            this.entries.push({key, source: vertices.slice(), elements: indices === false ? false : indices.slice(), result, bytes});
+            this.bytes += bytes;
+            return result;
+        }
+        return prepared;
+    }
+
+    /** Snapshot diagnostics without exposing mutable cached records. */
+    getStatistics(): {entries: number; bytes: number; hits: number; misses: number} {
+        return {entries: this.entries.length, bytes: this.bytes, hits: this.hits, misses: this.misses};
+    }
+
+    /** Release worker-owned preparation at reset or teardown. */
+    clear(): void {
+        this.epoch++;
+        this.entries.length = 0;
+        this.bytes = this.hits = this.misses = 0;
+    }
+}
+
+/** View only the typed array's occupied bytes, including nonzero buffer offsets. */
+function asBytes(values: Uint16Array | Uint32Array): Uint8Array {
+    return new Uint8Array(values.buffer, values.byteOffset, values.byteLength);
+}
+
+/** Cheap lookup hash, never a substitute for exact source comparison. */
+function hashBytes(values: Uint8Array): number {
+    let hash = 2166136261;
+    for (const value of values) hash = Math.imul(hash ^ value, 16777619);
+    return hash >>> 0;
+}
+
+/** Compare detached content, not transferable buffer identity. */
+function equalBytes(first: Uint8Array, second: Uint8Array): boolean {
+    if (first.length !== second.length) return false;
+    for (let index = 0; index < first.length; index++) if (first[index] !== second[index]) return false;
+    return true;
+}

package/src/experimental/projected-mesh-domain.ts

@@ -0,0 +1,110 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {interpolatePackedVertex} from '../gl/globe_mesh';
+import type {MeshProjectionRequest, ProjectedMesh} from '../procedures/mesh-projector';
+
+/** Geographic latitude limit of the source Web Mercator tile world. */
+export const PROJECTED_TILE_LATITUDE = 85.0511287798066;
+/** Half the width of one EPSG:3857 world, in meters. */
+const WORLD_HALF_WIDTH = Math.PI * 6378137;
+
+/** World bounds for continuous projections, with the preview's explicit Albers region. */
+export function getProjectedSourceDomain(type: MeshProjectionRequest['projection']['type']): readonly [number, number, number, number] {
+    if (type === 'albers') {
+        const latitudeToMeters = (latitude: number) => 6378137 * Math.asinh(Math.tan(latitude * Math.PI / 180));
+        return [-170 / 180 * WORLD_HALF_WIDTH, latitudeToMeters(5),
+            -40 / 180 * WORLD_HALF_WIDTH, latitudeToMeters(75)];
+    }
+    return [-WORLD_HALF_WIDTH, -WORLD_HALF_WIDTH, WORLD_HALF_WIDTH, WORLD_HALF_WIDTH];
+}
+
+/** Clip triangles before nonlinear projection, retaining winding, UVs and flat feature attributes. */
+export function clipProjectedMesh(mesh: ProjectedMesh, request: MeshProjectionRequest,
+    readPosition: (vertex: DataView) => readonly [number, number], remainingVertices: number): ProjectedMesh {
+    const {layout, tile} = request;
+    const unitsPerMeter = 4096 * 2 ** tile.coords.z / (2 * WORLD_HALF_WIDTH);
+    const domain = getProjectedSourceDomain(request.projection.type);
+    const bounds = [(domain[0] - tile.min.x) * unitsPerMeter, (domain[1] - tile.min.y) * unitsPerMeter,
+        (domain[2] - tile.min.x) * unitsPerMeter, (domain[3] - tile.min.y) * unitsPerMeter];
+    const records: Uint8Array[] = [];
+    const positions: (readonly [number, number])[] = [];
+    for (let offset = 0; offset < mesh.vertices.byteLength; offset += layout.stride) {
+        const record = mesh.vertices.subarray(offset, offset + layout.stride);
+        records.push(record);
+        positions.push(readPosition(new DataView(record.buffer, record.byteOffset, record.byteLength)));
+    }
+    const originalCount = records.length;
+    const inside = (index: number) => positions[index][0] >= bounds[0] && positions[index][0] <= bounds[2] &&
+        positions[index][1] >= bounds[1] && positions[index][1] <= bounds[3];
+    if (mesh.indices.every(inside)) return mesh;
+    const intersections = new Map<string, number>();
+    const triangles: number[] = [];
+    const positionOffset = layout.dynamic_attribs.find(attribute => attribute.name === 'a_position')?.offset;
+    const height = (vertex: number) => {
+        if (positionOffset === undefined) throw new Error('Projected surface requires packed positions');
+        return new DataView(records[vertex].buffer, records[vertex].byteOffset, layout.stride).getInt16(positionOffset + 4, true);
+    };
+    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
+        let polygon = Array.from(mesh.indices.subarray(offset, offset + 3));
+        // Reject against every plane first: an early cut must not spend budget on
+        // a triangle that a later plane will discard entirely.
+        if (bounds.some((boundary, plane) => polygon.every(index =>
+            (positions[index][plane % 2] - boundary) * (plane < 2 ? 1 : -1) < 0))) continue;
+        for (let plane = 0; plane < 4 && polygon.length; plane++) {
+            const axis = plane % 2;
+            const boundary = bounds[plane];
+            const distance = (index: number) => (positions[index][axis] - boundary) * (plane < 2 ? 1 : -1);
+            const clipped: number[] = [];
+            let previous = polygon[polygon.length - 1];
+            for (const current of polygon) {
+                const previousDistance = distance(previous), currentDistance = distance(current);
+                if ((previousDistance >= 0) !== (currentDistance >= 0)) {
+                    const first = Math.min(previous, current), second = Math.max(previous, current);
+                    const key = `${plane}:${first}:${second}`;
+                    let intersection = intersections.get(key);
+                    if (intersection === undefined) {
+                        const fraction = distance(first) / (distance(first) - distance(second));
+                        if (fraction === 0 || fraction === 1) intersection = fraction === 0 ? first : second;
+                        else {
+                            if (records.length - originalCount >= remainingVertices) {
+                                throw new RangeError('CPU projection clipping vertex budget exceeded');
+                            }
+                            intersection = records.length;
+                            records.push(interpolatePackedVertex(records[first], records[second], layout, fraction));
+                            positions.push(axis === 0 ? [boundary, positions[first][1] * (1 - fraction) + positions[second][1] * fraction] :
+                                [positions[first][0] * (1 - fraction) + positions[second][0] * fraction, boundary]);
+                        }
+                        intersections.set(key, intersection);
+                    }
+                    if (clipped[clipped.length - 1] !== intersection) clipped.push(intersection);
+                }
+                if (currentDistance >= 0 && clipped[clipped.length - 1] !== current) clipped.push(current);
+                previous = current;
+            }
+            if (clipped.length > 1 && clipped[0] === clipped[clipped.length - 1]) clipped.pop();
+            polygon = clipped;
+        }
+        for (let index = 1; index < polygon.length - 1; index++) {
+            const first = positions[polygon[0]], second = positions[polygon[index]], third = positions[polygon[index + 1]];
+            const area = (second[0] - first[0]) * (third[1] - first[1]) -
+                (second[1] - first[1]) * (third[0] - first[0]);
+            // A vertical wall has no XY area. Retain its XZ/YZ area after cuts.
+            const elevated = request.projection.allowElevation && request.geometry !== 'lines' &&
+                ((second[0] - first[0]) * (height(polygon[index + 1]) - height(polygon[0])) -
+                    (height(polygon[index]) - height(polygon[0])) * (third[0] - first[0]) !== 0 ||
+                 (second[1] - first[1]) * (height(polygon[index + 1]) - height(polygon[0])) -
+                    (height(polygon[index]) - height(polygon[0])) * (third[1] - first[1]) !== 0);
+            if (area !== 0 || elevated) triangles.push(polygon[0], polygon[index], polygon[index + 1]);
+        }
+    }
+    // Drop unused/outside vertices so no invalid coordinate is submitted to the engine.
+    const remap = new Map<number, number>();
+    for (const index of triangles) if (!remap.has(index)) remap.set(index, remap.size);
+    const vertices = new Uint8Array(remap.size * layout.stride);
+    for (const [original, index] of remap) vertices.set(records[original], index * layout.stride);
+    const indices = remap.size <= 65536 ? new Uint16Array(triangles.length) : new Uint32Array(triangles.length);
+    triangles.forEach((index, offset) => {indices[offset] = remap.get(index)!;});
+    return {vertices, indices};
+}

package/src/experimental/projected-mesh-refinement.ts

@@ -0,0 +1,193 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {interpolatePackedVertex, refineGlobeMesh, selectTrianglePlane} from '../gl/globe_mesh';
+import type {MeshProjectionRequest, ProjectedMesh} from '../procedures/mesh-projector';
+
+/** Per-request refinement work, separate from cached source preparation. */
+export interface ProjectedRefinementWork {
+    /** Rounds that subdivide curved edges. */
+    edgeRounds: number;
+    /** Rounds that add strictly interior triangle vertices. */
+    interiorRounds: number;
+}
+
+const INTERIOR_WEIGHTS = [[1 / 3, 1 / 3, 1 / 3], [0.5, 0.25, 0.25],
+    [0.25, 0.5, 0.25], [0.25, 0.25, 0.5]] as const;
+
+/** Batch projection samples per refinement round; local and caller-owned kernels use identical topology decisions.
+ * Edge and barycentric interior probes are sampled estimates, not certified bounds for arbitrary kernels.
+ * Indexed neighbors share decisions. Independent source tiles use identical packed midpoint rules and tolerance.
+ */
+export function* refineProjectedMesh(mesh: ProjectedMesh, request: MeshProjectionRequest,
+    geographicPosition: (vertex: DataView, displacement?: readonly [number, number]) => readonly [number, number],
+    readPosition: (vertex: DataView) => [number, number],
+    work: ProjectedRefinementWork = {edgeRounds: 0, interiorRounds: 0}): Generator<Float64Array, ProjectedMesh, Float64Array> {
+    const tolerance = request.projection.maxProjectedError;
+    if (tolerance === undefined || mesh.indices.length === 0) return mesh;
+    const {layout} = request;
+    const originalCount = request.vertices.byteLength / layout.stride;
+    const budget = request.projection.maxAdditionalVertices ?? 65536;
+    let result = mesh;
+    const key = (vertex: DataView): string => Array.from(new Uint8Array(vertex.buffer, vertex.byteOffset, vertex.byteLength)).join(',');
+    const edgeKey = (first: DataView, second: DataView): string => {
+        const firstKey = key(first), secondKey = key(second);
+        return firstKey < secondKey ? `${firstKey}:${secondKey}` : `${secondKey}:${firstKey}`;
+    };
+    for (let iteration = 0; iteration < 32; iteration++) {
+        const edges = new Map<string, [Uint8Array, Uint8Array]>();
+        for (let index = 0; index < result.indices.length; index += 3) for (let edge = 0; edge < 3; edge++) {
+            const first = result.vertices.subarray(result.indices[index + edge] * layout.stride,
+                (result.indices[index + edge] + 1) * layout.stride);
+            const secondIndex = result.indices[index + (edge + 1) % 3];
+            const second = result.vertices.subarray(secondIndex * layout.stride, (secondIndex + 1) * layout.stride);
+            edges.set(edgeKey(new DataView(first.buffer, first.byteOffset, first.byteLength),
+                new DataView(second.buffer, second.byteOffset, second.byteLength)), [first, second]);
+        }
+        const coordinates: number[] = [];
+        for (const [first, second] of edges.values()) {
+            const start = readPosition(new DataView(first.buffer, first.byteOffset, first.byteLength));
+            const end = readPosition(new DataView(second.buffer, second.byteOffset, second.byteLength));
+            for (const fraction of [0, 0.25, 0.5, 0.75, 1]) {
+                const sample = fraction === 0 ? first : fraction === 1 ? second : interpolatePackedVertex(first, second, layout, fraction);
+                const view = new DataView(sample.buffer, sample.byteOffset, sample.byteLength);
+                const packed = readPosition(view);
+                // Test the exact source chord, not off-chord integer rounding of
+                // its probes. Generated vertices still retain the packed rules.
+                coordinates.push(...geographicPosition(view, [start[0] * (1 - fraction) + end[0] * fraction - packed[0],
+                    start[1] * (1 - fraction) + end[1] * fraction - packed[1]]));
+            }
+        }
+        const edgeCoordinateCount = coordinates.length;
+        // Ribbons are parameterized around centerlines; their pixel-width/fan
+        // reconstruction is not a geographic surface interpolant.
+        const inspectInteriors = request.geometry !== 'lines';
+        if (inspectInteriors) for (let index = 0; index < result.indices.length; index += 3) {
+            const corners = [0, 1, 2].map(component => result.vertices.subarray(
+                result.indices[index + component] * layout.stride, (result.indices[index + component] + 1) * layout.stride));
+            const points = corners.map(record => readPosition(new DataView(record.buffer, record.byteOffset, layout.stride)));
+            for (const corner of corners) coordinates.push(...geographicPosition(new DataView(corner.buffer, corner.byteOffset, layout.stride)));
+            for (const weights of INTERIOR_WEIGHTS) {
+                const sample = interpolateTriangle(corners, request, weights);
+                const view = new DataView(sample.buffer, sample.byteOffset, layout.stride);
+                const packed = readPosition(view);
+                coordinates.push(...geographicPosition(view, [
+                    points.reduce((sum, point, component) => sum + point[0] * weights[component], 0) - packed[0],
+                    points.reduce((sum, point, component) => sum + point[1] * weights[component], 0) - packed[1]]));
+            }
+        }
+        const projected = yield new Float64Array(coordinates);
+        if (!(projected instanceof Float64Array) || projected.length !== coordinates.length || !projected.every(Number.isFinite)) {
+            throw new Error('Projection refinement returned an invalid common-position batch');
+        }
+        const split = new Set<string>();
+        let offset = 0;
+        for (const edge of edges.keys()) {
+            const differenceX = projected[offset + 8] - projected[offset];
+            const differenceY = projected[offset + 9] - projected[offset + 1];
+            const lengthSquared = differenceX ** 2 + differenceY ** 2;
+            for (let sample = 1; sample < 4; sample++) {
+                // Packed samples round to the source grid. Movement along a straight
+                // chord is not curvature, even when it no longer equals sample / 4.
+                const fraction = request.geometry !== 'lines' ? sample / 4 : lengthSquared === 0 ? 0 : Math.max(0, Math.min(1,
+                    ((projected[offset + sample * 2] - projected[offset]) * differenceX +
+                    (projected[offset + sample * 2 + 1] - projected[offset + 1]) * differenceY) / lengthSquared));
+                // Surfaces need parameterized interpolation accuracy for raster
+                // UVs, not just perpendicular silhouette error. Exact source
+                // probes above keep packed rounding out of this measurement.
+                const error = Math.hypot(projected[offset + sample * 2] -
+                    (projected[offset] * (1 - fraction) + projected[offset + 8] * fraction),
+                projected[offset + sample * 2 + 1] -
+                    (projected[offset + 1] * (1 - fraction) + projected[offset + 9] * fraction));
+                if (error > tolerance) split.add(edge);
+            }
+            offset += 10;
+        }
+        if (split.size === 0) {
+            const interiors = new Set<number>();
+            offset = edgeCoordinateCount;
+            if (inspectInteriors) for (let index = 0; index < result.indices.length; index += 3) {
+                for (const [sample, weights] of INTERIOR_WEIGHTS.entries()) {
+                    const expected = [0, 1].map(component => weights.reduce((sum, weight, corner) =>
+                        sum + weight * projected[offset + corner * 2 + component], 0));
+                    const actual = offset + 6 + sample * 2;
+                    if (Math.hypot(projected[actual] - expected[0], projected[actual + 1] - expected[1]) > tolerance) {
+                        interiors.add(index);
+                    }
+                }
+                offset += 14;
+            }
+            if (interiors.size === 0) return result;
+            result = splitTriangleInteriors(result, request, interiors, readPosition,
+                budget - (result.vertices.byteLength / layout.stride - originalCount));
+            work.interiorRounds++;
+            continue;
+        }
+        const refined = refineGlobeMesh(result.vertices, result.indices, layout, {tileZoom: request.tile.coords.z,
+            maxAngularSpan: 180, maxAdditionalVertices: budget - (result.vertices.byteLength / layout.stride - originalCount),
+            splitRemainderInterior: inspectInteriors,
+            getElevation: getPackedElevationReader(request),
+            getPosition: readPosition, shouldSplitEdge: (first, second) => split.has(edgeKey(first, second))});
+        if (refined.vertices.byteLength === result.vertices.byteLength) {
+            throw new RangeError('Projected error tolerance exceeds packed coordinate precision');
+        }
+        result = refined;
+        work.edgeRounds++;
+    }
+    throw new RangeError('Projected refinement iteration budget exceeded');
+}
+
+/** Interpolate all supported varying attributes while retaining flat feature provenance. */
+function interpolateTriangle(corners: Uint8Array[], request: MeshProjectionRequest, weights: readonly number[]): Uint8Array {
+    return interpolatePackedVertex(interpolatePackedVertex(corners[0], corners[1], request.layout,
+        weights[1] / (weights[0] + weights[1])), corners[2], request.layout, weights[2]);
+}
+
+/** Insert strictly interior packed centers without changing any shared edge or its neighbors. */
+function splitTriangleInteriors(mesh: ProjectedMesh, request: MeshProjectionRequest, selected: Set<number>,
+    readPosition: (vertex: DataView) => [number, number], remainingBudget: number): ProjectedMesh {
+    if (selected.size > remainingBudget) throw new RangeError('Projected interior refinement vertex budget exceeded');
+    const {stride} = request.layout;
+    const vertexCount = mesh.vertices.byteLength / stride;
+    const vertices = new Uint8Array(mesh.vertices.byteLength + selected.size * stride);
+    vertices.set(mesh.vertices);
+    const indices: number[] = [];
+    let inserted = 0;
+    for (let index = 0; index < mesh.indices.length; index += 3) {
+        const triangle = [mesh.indices[index], mesh.indices[index + 1], mesh.indices[index + 2]];
+        if (!selected.has(index)) {indices.push(...triangle); continue;}
+        const corners = triangle.map(vertex => mesh.vertices.subarray(vertex * stride, (vertex + 1) * stride));
+        const center = interpolateTriangle(corners, request, INTERIOR_WEIGHTS[0]);
+        const readElevation = getPackedElevationReader(request);
+        const topologyPosition = (vertex: Uint8Array): [number, number, number] => {
+            const view = new DataView(vertex.buffer, vertex.byteOffset, stride);
+            return [...readPosition(view), readElevation?.(view) ?? 0];
+        };
+        const corners3D = corners.map(topologyPosition);
+        const axes = selectTrianglePlane(corners3D);
+        const flatten = (position: readonly [number, number, number]): [number, number] => [position[axes[0]], position[axes[1]]];
+        const point = flatten(topologyPosition(center));
+        const points = corners3D.map(flatten);
+        const cross = (first: number[], second: number[], third: number[]) =>
+            (second[0] - first[0]) * (third[1] - first[1]) - (second[1] - first[1]) * (third[0] - first[0]);
+        const orientation = cross(points[0], points[1], points[2]);
+        if (points.some((start, edge) => cross(start, points[(edge + 1) % 3], point) * orientation <= 0)) {
+            throw new RangeError('Projected interior tolerance exceeds packed coordinate precision');
+        }
+        const centerIndex = vertexCount + inserted++;
+        vertices.set(center, centerIndex * stride);
+        indices.push(triangle[0], triangle[1], centerIndex, triangle[1], triangle[2], centerIndex,
+            triangle[2], triangle[0], centerIndex);
+    }
+    return {vertices, indices: vertexCount + selected.size <= 65536 ? new Uint16Array(indices) : new Uint32Array(indices)};
+}
+
+/** Read the original packed height only for opted-in surface topology checks. */
+function getPackedElevationReader(request: MeshProjectionRequest): ((vertex: DataView) => number) | undefined {
+    if (!request.projection.allowElevation || request.geometry === 'lines') return undefined;
+    const position = request.layout.dynamic_attribs.find(attribute => attribute.name === 'a_position');
+    if (!position || position.offset === undefined || position.size < 3) throw new Error('Projected elevation requires a position layout');
+    const offset = position.offset;
+    return vertex => vertex.getInt16(offset + 4, true);
+}