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

package/src/map-logic/terrain-neighborhood.ts

@@ -0,0 +1,43 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {sampleTerrainHeight, type TerrainHeightGrid} from './terrain-data';
+import {TerrainHeightField} from './terrain-height-field';
+
+/** Sample touching footprints with shared-edge averaging; callers validate datum and topology. */
+export function sampleTerrainNeighborhood(grids: readonly TerrainHeightGrid[], position: readonly [number, number]): number | null {
+    let sum = 0, count = 0;
+    for (const grid of grids) {
+        const [west, south, east, north] = grid.bounds;
+        const tolerance = Math.max(east - west, north - south) * 1e-10;
+        if (position[0] < west - tolerance || position[0] > east + tolerance || position[1] < south - tolerance || position[1] > north + tolerance) continue;
+        const height = sampleTerrainHeight(grid, [Math.max(west, Math.min(east, position[0])), Math.max(south, Math.min(north, position[1]))]);
+        // A touching invalid sample is a hole, not permission to bridge it with its neighbor.
+        if (height === null) return null;
+        sum += height; count++;
+    }
+    return count ? sum / count : null;
+}
+
+/** Reconstruct explicit boundary nodes from pixel-center data and adjacent tiles. */
+export function resampleTerrainNodes(grid: TerrainHeightGrid, neighbors: readonly TerrainHeightGrid[] = []): TerrainHeightGrid {
+    const grids = [grid, ...neighbors.filter(neighbor => neighbor !== grid)];
+    const [west, south, east, north] = grid.bounds;
+    for (const neighbor of grids) {
+        if (neighbor.verticalDatum !== grid.verticalDatum || neighbor.registration !== grid.registration || neighbor.width !== grid.width || neighbor.height !== grid.height ||
+            Math.abs((neighbor.bounds[2] - neighbor.bounds[0]) / (east - west) - 1) > 1e-8 ||
+            Math.abs((neighbor.bounds[3] - neighbor.bounds[1]) / (north - south) - 1) > 1e-8) throw new Error('Terrain neighbors require matching resolution and datum');
+    }
+    const columns = grid.registration === 'pixel-center' ? grid.width : grid.width - 1;
+    const rows = grid.registration === 'pixel-center' ? grid.height : grid.height - 1;
+    const width = columns + 1, height = rows + 1;
+    const field = new TerrainHeightField(grids);
+    const heights = new Float32Array(width * height), valid = new Uint8Array(width * height);
+    for (let row = 0; row < height; row++) for (let column = 0; column < width; column++) {
+        const value = field.sampleHeight([west + column / columns * (east - west), north - row / rows * (north - south)]);
+        const index = row * width + column;
+        heights[index] = value ?? NaN; valid[index] = Number(value !== null);
+    }
+    return {width, height, heights, valid, bounds: [...grid.bounds], registration: 'grid-node', verticalDatum: grid.verticalDatum};
+}

package/src/map-logic/terrain-query.ts

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

package/src/map-logic/terrain-resource-budget.ts

@@ -0,0 +1,124 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Independently reported storage domains; GPU bytes are estimates, not driver allocation measurements. */
+export type TerrainResourceDomain = 'retained' | 'transient' | 'gpu';
+
+/** One entry in an atomically admitted allocation batch. */
+export interface TerrainResourceRequest {
+    /** Independently reported storage category. */
+    readonly domain: TerrainResourceDomain;
+    /** Exact represented allocation bytes, a non-negative safe integer. */
+    readonly bytes: number;
+    /** Optional immutable allocation identity; matching owners count once. */
+    readonly identity?: object;
+}
+
+/** An owned reservation. Releasing twice is safe, including cancellation racing completion. */
+export interface TerrainResourceLease {
+    /** Atomically resize a private reservation; shared immutable reservations permit only the same size. */
+    resize(bytes: number): boolean;
+    /** Release this owner's reservation. */
+    release(): void;
+}
+
+/** Shared admission across source, preparation and renderer owners; never takes resource disposal ownership. */
+export class TerrainResourceBudget {
+    /** Validated total reservation limit, in bytes. */
+    readonly byteLimit: number;
+    /** Current allocations, keyed by opaque lease identity rather than reusable tile names. */
+    private readonly allocations = new Map<object, {domain: TerrainResourceDomain; bytes: number; references: number}>();
+    /** Weak allocation identities permit independent owners to retain one immutable allocation once. */
+    private readonly sharedIdentities = new WeakMap<object, object>();
+    /** Largest simultaneously reserved total since construction. */
+    private peakBytes = 0;
+    /** Current total, updated without rescanning every owner. */
+    private bytes = 0;
+
+    /** Construct a finite hard admission limit; reservations must precede the represented allocation. */
+    constructor(byteLimit: number) {
+        validateBytes(byteLimit);
+        this.byteLimit = byteLimit;
+    }
+
+    /** Reserve before allocating; rejection leaves every incumbent owner unchanged. */
+    reserve(domain: TerrainResourceDomain, bytes: number): TerrainResourceLease | null {
+        return this.reserveAll([{domain, bytes}])?.[0] ?? null;
+    }
+
+    /** Retain an immutable allocation by identity; shared leases permit only no-op resizing. */
+    reserveShared(identity: object, domain: TerrainResourceDomain, bytes: number): TerrainResourceLease | null {
+        return this.reserveAll([{identity, domain, bytes}])?.[0] ?? null;
+    }
+
+    /** Create a lease only after its complete admission has been validated. */
+    private createLease(domain: TerrainResourceDomain, bytes: number, shared?: object): TerrainResourceLease {
+        const identity = (shared ? this.sharedIdentities.get(shared) : undefined) ?? {};
+        let allocation = this.allocations.get(identity);
+        if (allocation) allocation.references++;
+        else {
+            allocation = {domain, bytes, references: 1};
+            this.allocations.set(identity, allocation);
+            if (shared) this.sharedIdentities.set(shared, identity);
+            this.bytes += bytes; this.peakBytes = Math.max(this.peakBytes, this.bytes);
+        }
+        const allocationIdentity = identity;
+        const owned = allocation;
+        let active = true;
+        return {
+            resize: next => {
+                validateBytes(next);
+                if (!active || shared && next !== owned.bytes || next - owned.bytes > this.byteLimit - this.bytes) return false;
+                this.bytes += next - owned.bytes;
+                owned.bytes = next; this.peakBytes = Math.max(this.peakBytes, this.bytes);
+                return true;
+            },
+            release: () => {
+                if (!active) return;
+                active = false; owned.references--;
+                if (!owned.references) {this.bytes -= owned.bytes; this.allocations.delete(allocationIdentity);}
+            }
+        };
+    }
+
+    /** Admit a complete set atomically; invalid or over-budget batches allocate no leases. */
+    reserveAll(requests: readonly TerrainResourceRequest[]): TerrainResourceLease[] | null {
+        const entries = requests.map(({domain, bytes, identity}) => ({domain, bytes, identity}));
+        let total = 0;
+        const planned = new Map<object, {domain: TerrainResourceDomain; bytes: number}>();
+        for (const request of entries) {
+            validateBytes(request.bytes);
+            if (!['retained', 'transient', 'gpu'].includes(request.domain)) throw new Error('Invalid terrain resource domain');
+            if (request.identity !== undefined) {
+                if (request.identity === null || typeof request.identity !== 'object') throw new Error('Invalid shared terrain resource identity');
+                const identity = this.sharedIdentities.get(request.identity);
+                const allocation = identity ? this.allocations.get(identity) : undefined;
+                const previous = allocation ?? planned.get(request.identity);
+                if (previous) {
+                    if (previous.domain !== request.domain || previous.bytes !== request.bytes) throw new Error('Shared terrain resource metadata must match');
+                    continue;
+                }
+                planned.set(request.identity, request);
+            }
+            if (request.bytes > Number.MAX_SAFE_INTEGER - total) throw new Error('Invalid terrain resource byte reservation');
+            total += request.bytes;
+        }
+        if (total > this.byteLimit - this.bytes) return null;
+        return entries.map(request => this.createLease(request.domain, request.bytes, request.identity));
+    }
+
+    /** Detached unique allocation bytes and live owner-lease count; excludes unregistered resources and driver overhead. */
+    getStatistics(): {bytes: number; peakBytes: number; byteLimit: number; retainedBytes: number; transientBytes: number; gpuBytes: number; leases: number} {
+        const totals = {retained: 0, transient: 0, gpu: 0};
+        let leases = 0;
+        for (const allocation of this.allocations.values()) {totals[allocation.domain] += allocation.bytes; leases += allocation.references;}
+        return {bytes: this.bytes, peakBytes: this.peakBytes, byteLimit: this.byteLimit,
+            retainedBytes: totals.retained, transientBytes: totals.transient, gpuBytes: totals.gpu, leases};
+    }
+}
+
+/** Reject overflow and fractional reservations before changing an owner. */
+function validateBytes(bytes: number): void {
+    if (!Number.isSafeInteger(bytes) || bytes < 0) throw new Error('Invalid terrain resource byte reservation');
+}

package/src/map-logic/terrain-transition-topology.ts

@@ -0,0 +1,164 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TerrainGroundTopology} from './terrain-ground-topology';
+
+/** Barycentric reference to one unchanged endpoint face. Negative indices mean absent previous coverage. */
+export interface TerrainFaceReference {
+    /** Canonical vertex indices in original winding. */
+    readonly indices: readonly [number, number, number];
+    /** Weights at the final geometric position. */
+    readonly weights: readonly [number, number, number];
+}
+
+/** Common planar refinement of two field generations; neither endpoint is bilinearly resampled at new cuts. */
+export interface TerrainTransitionTopology {
+    /** Complete current footprint partition, including newly covered regions. */
+    readonly topology: TerrainGroundTopology;
+    /** Current endpoint references, one per output vertex. */
+    readonly current: readonly TerrainFaceReference[];
+    /** Previous endpoint references, null outside the previous admitted footprint. */
+    readonly previous: readonly (TerrainFaceReference | null)[];
+}
+
+/** Closed face envelope used by the temporary sweep broad phase. */
+interface Face {
+    /** Canonical face identity. */
+    indices: [number, number, number];
+    /** Exact sample-domain corners. */
+    points: [number, number][];
+    /** Closed bounds. */
+    bounds: [number, number, number, number];
+}
+
+/** Temporary binary broad phase; no retained index escapes preparation. */
+interface FaceNode {
+    /** Closed descendant envelope. */
+    bounds: [number, number, number, number];
+    /** Small original-order leaf. */
+    faces?: Face[];
+    /** Median split children. */
+    children?: [FaceNode, FaceNode];
+}
+
+/** Bound edge work to overlapping old faces rather than the product of both meshes. */
+function buildNode(faces: Face[]): FaceNode | null {
+    if (!faces.length) return null;
+    const bounds: FaceNode['bounds'] = [Infinity, Infinity, -Infinity, -Infinity];
+    for (const face of faces) for (let axis = 0; axis < 2; axis++) {
+        bounds[axis] = Math.min(bounds[axis], face.bounds[axis]); bounds[axis + 2] = Math.max(bounds[axis + 2], face.bounds[axis + 2]);
+    }
+    if (faces.length <= 8) return {bounds, faces};
+    const axis = bounds[2] - bounds[0] > bounds[3] - bounds[1] ? 0 : 1;
+    faces.sort((first, second) => first.bounds[axis] + first.bounds[axis + 2] - second.bounds[axis] - second.bounds[axis + 2]);
+    const middle = Math.floor(faces.length / 2);
+    return {bounds, children: [buildNode(faces.slice(0, middle))!, buildNode(faces.slice(middle))!]};
+}
+
+/** Signed twice-area, preserving the canonical world-XY winding. */
+function cross(first: readonly number[], second: readonly number[], point: readonly number[]): number {
+    return (second[0] - first[0]) * (point[1] - first[1]) - (second[1] - first[1]) * (point[0] - first[0]);
+}
+
+/** Classify collinearity within world-coordinate representation error, not a fixed geometric epsilon. */
+function signedDistance(first: readonly number[], second: readonly number[], point: readonly number[]): number {
+    const distance = cross(first, second, point);
+    const tolerance = Number.EPSILON * Math.max(1, ...first.map(Math.abs), ...second.map(Math.abs), ...point.map(Math.abs)) *
+        (Math.abs(second[0] - first[0]) + Math.abs(second[1] - first[1])) * 16;
+    return Math.abs(distance) <= tolerance ? 0 : distance;
+}
+
+/** Reference coordinates without changing the existing face's diagonal or endpoint samples. */
+function reference(face: Face, point: readonly number[]): TerrainFaceReference {
+    const denominator = cross(face.points[0], face.points[1], face.points[2]);
+    const first = cross(face.points[1], face.points[2], point) / denominator;
+    const second = cross(face.points[2], face.points[0], point) / denominator;
+    return {indices: face.indices, weights: [first, second, 1 - first - second]};
+}
+
+/** Snapshot an immutable topology's faces; temporary arrays never survive the worker preparation. */
+function faces(topology: TerrainGroundTopology): Face[] {
+    const result: Face[] = [];
+    for (let offset = 0; offset < topology.indices.length; offset += 3) {
+        const indices: [number, number, number] = [topology.indices[offset], topology.indices[offset + 1], topology.indices[offset + 2]];
+        const points = indices.map((index): [number, number] => [topology.samplePositions[index * 2], topology.samplePositions[index * 2 + 1]]);
+        result.push({indices, points, bounds: [Math.min(...points.map(point => point[0])), Math.min(...points.map(point => point[1])),
+            Math.max(...points.map(point => point[0])), Math.max(...points.map(point => point[1]))]});
+    }
+    return result;
+}
+
+/**
+ * Split current faces along previous edges, retaining both exact planar endpoint
+ * surfaces and newly covered ground. Bounded work/vertices reject atomically.
+ * This does not claim spherical coplanarity after nonlinear globe projection.
+ */
+export function refineTerrainTransitionTopology(current: TerrainGroundTopology, previous: TerrainGroundTopology, maxVertices: number,
+    maxEdgeTests = 1048576): TerrainTransitionTopology | null {
+    if (!Number.isSafeInteger(maxVertices) || maxVertices < 0 || !Number.isSafeInteger(maxEdgeTests) || maxEdgeTests < 0 || current.sampleOffset !== previous.sampleOffset) throw new Error('Invalid terrain transition budget or sampling world');
+    if (current.samplePositions.length === previous.samplePositions.length && current.indices.length === previous.indices.length &&
+        current.samplePositions.every((value, index) => value === previous.samplePositions[index]) && current.indices.every((value, index) => value === previous.indices[index])) return null;
+    const root = buildNode(faces(previous));
+    const positions: number[] = [], samplePositions: number[] = [], normalizedPositions: number[] = [], indices: number[] = [];
+    const currentReferences: TerrainFaceReference[] = [], previousReferences: (TerrainFaceReference | null)[] = [];
+    let tests = 0;
+    for (const face of faces(current)) {
+        const candidates: Face[] = [];
+        const pending = root ? [root] : [];
+        while (pending.length) {
+            const node = pending.pop()!;
+            if (++tests > maxEdgeTests) throw new Error('Terrain transition edge-work budget exceeded');
+            if (node.bounds[0] >= face.bounds[2] || node.bounds[2] <= face.bounds[0] || node.bounds[1] >= face.bounds[3] || node.bounds[3] <= face.bounds[1]) continue;
+            if (node.faces) for (const candidate of node.faces) {
+                if (candidate.bounds[0] < face.bounds[2] && candidate.bounds[2] > face.bounds[0] && candidate.bounds[1] < face.bounds[3] && candidate.bounds[3] > face.bounds[1]) candidates.push(candidate);
+            }
+            else pending.push(...node.children!);
+        }
+        let polygons = [face.points];
+        const edges = new Set<string>();
+        for (const candidate of candidates) for (let edge = 0; edge < 3; edge++) {
+            let start = candidate.points[edge], end = candidate.points[(edge + 1) % 3];
+            if (start[0] > end[0] || start[0] === end[0] && start[1] > end[1]) [start, end] = [end, start];
+            const key = `${start.join(',')}/${end.join(',')}`;
+            if (edges.has(key)) continue;
+            edges.add(key);
+            const next: [number, number][][] = [];
+            for (const polygon of polygons) {
+                if (++tests > maxEdgeTests) throw new Error('Terrain transition edge-work budget exceeded');
+                const distances = polygon.map(point => signedDistance(start, end, point));
+                if (!distances.some(value => value < 0) || !distances.some(value => value > 0)) {next.push(polygon); continue;}
+                const positive: [number, number][] = [], negative: [number, number][] = [];
+                polygon.forEach((point, index) => {
+                    const distance = distances[index], following = polygon[(index + 1) % polygon.length], followingDistance = distances[(index + 1) % polygon.length];
+                    if (distance >= 0) positive.push(point);
+                    if (distance <= 0) negative.push(point);
+                    if (distance * followingDistance < 0) {
+                        const fraction = distance / (distance - followingDistance);
+                        const intersection: [number, number] = [point[0] + (following[0] - point[0]) * fraction, point[1] + (following[1] - point[1]) * fraction];
+                        positive.push(intersection); negative.push(intersection);
+                    }
+                });
+                next.push(positive, negative);
+                if (next.length * 3 > maxVertices) throw new Error('Terrain transition vertex budget exceeded');
+            }
+            polygons = next;
+        }
+        for (const polygon of polygons) {
+            if (samplePositions.length / 2 + polygon.length > maxVertices) throw new Error('Terrain transition vertex budget exceeded');
+            const center = polygon.reduce(([x, y], point) => [x + point[0] / polygon.length, y + point[1] / polygon.length], [0, 0]);
+            const oldFace = candidates.find(candidate => candidate.points.every((point, index) => signedDistance(point, candidate.points[(index + 1) % 3], center) >= 0));
+            const base = samplePositions.length / 2;
+            for (const point of polygon) {
+                const currentReference = reference(face, point);
+                currentReferences.push(currentReference); previousReferences.push(oldFace ? reference(oldFace, point) : null);
+                samplePositions.push(...point); positions.push(point[0] + current.sampleOffset, point[1]);
+                for (let axis = 0; axis < 2; axis++) normalizedPositions.push(currentReference.indices.reduce((sum, index, corner) =>
+                    sum + current.normalizedPositions[index * 2 + axis] * currentReference.weights[corner], 0));
+            }
+            for (let index = 1; index + 1 < polygon.length; index++) if (cross(polygon[0], polygon[index], polygon[index + 1]) !== 0) indices.push(base, base + index, base + index + 1);
+        }
+    }
+    return {topology: {positions: Float64Array.from(positions), samplePositions: Float64Array.from(samplePositions), normalizedPositions: Float64Array.from(normalizedPositions),
+        indices: Uint32Array.from(indices), sampleOffset: current.sampleOffset}, current: currentReferences, previous: previousReferences};
+}

package/src/map-logic/tile-build-queue.ts

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

package/src/map-logic/tile-cache-policy.ts

@@ -0,0 +1,89 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Immutable resource metadata supplied by the host, with unique keys per snapshot. */
+export interface TileCacheRecord {
+    /** Stable content identity, including source/style generation when necessary. */
+    readonly key: string;
+    /** Non-negative finite resource bytes; the host defines which resources are counted. */
+    readonly bytes: number;
+    /** Whether visibility, loading, proxies, pins or consumers currently prevent eviction. */
+    readonly protected: boolean;
+}
+
+/** Already validated non-negative cache limits; protected records do not consume these budgets. */
+export interface TileCacheOptions {
+    /** Maximum evictable entries; omit for unlimited. */
+    readonly maxCachedTiles?: number;
+    /** Maximum evictable resource bytes; omit for unlimited. */
+    readonly maxCachedBytes?: number;
+}
+
+/** Detached accounting for a host-provided resident snapshot, not a resource allocator. */
+export interface TileCacheStatistics {
+    /** All retained records, including protected entries. */
+    residentTiles: number;
+    /** Entries eligible for eviction. */
+    cachedTiles: number;
+    /** Bytes in evictable entries. */
+    cachedBytes: number;
+    /** Entries excluded from eviction. */
+    protectedTiles: number;
+    /** Bytes in protected entries. */
+    protectedBytes: number;
+}
+
+/** Stable LRU policy owning recency metadata only; selection never disposes or removes content. */
+export class TileCachePolicy {
+    /** Logical access order, independent of clocks and resource ownership. */
+    private readonly lastUsed = new Map<string, number>();
+    /** Monotonic access sequence retained across metadata resets. */
+    private tick = 0;
+
+    /** Mark a key as recently used; callers decide when visibility counts as reuse. */
+    touch(key: string): void {
+        this.lastUsed.set(key, ++this.tick);
+    }
+
+    /** Release recency metadata after the host removes a record. */
+    forget(key: string): void {
+        this.lastUsed.delete(key);
+    }
+
+    /** Select oldest evictable keys until both budgets fit, without changing input or recency. */
+    selectEvictions(records: readonly TileCacheRecord[], options?: TileCacheOptions): string[] {
+        if (options?.maxCachedTiles === undefined && options?.maxCachedBytes === undefined) return [];
+        const cached = records.filter(record => !record.protected);
+        cached.sort((first, second) => (this.lastUsed.get(first.key) ?? 0) - (this.lastUsed.get(second.key) ?? 0));
+        let count = cached.length;
+        let bytes = cached.reduce((total, record) => total + record.bytes, 0);
+        const evictions: string[] = [];
+        for (const record of cached) {
+            if (count <= (options?.maxCachedTiles ?? Infinity) && bytes <= (options?.maxCachedBytes ?? Infinity)) break;
+            evictions.push(record.key);
+            count--;
+            bytes -= record.bytes;
+        }
+        return evictions;
+    }
+
+    /** Count the current snapshot without changing recency or retaining record objects. */
+    getStatistics(records: readonly TileCacheRecord[]): TileCacheStatistics {
+        let cachedTiles = 0, cachedBytes = 0, protectedBytes = 0;
+        for (const record of records) {
+            if (record.protected) protectedBytes += record.bytes;
+            else {
+                cachedTiles++;
+                cachedBytes += record.bytes;
+            }
+        }
+        return {residentTiles: records.length, cachedTiles, cachedBytes,
+            protectedTiles: records.length - cachedTiles, protectedBytes};
+    }
+
+    /** Clear recency metadata without touching host content or resetting the logical clock. */
+    clear(): void {
+        this.lastUsed.clear();
+    }
+}

package/src/map-logic/tile-residency.ts

@@ -0,0 +1,50 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Private, copied selection metadata for one logical view or resource consumer. */
+interface TileConsumerState {
+    /** Requested keys, including not-yet-loaded content. */
+    selected: Set<string>;
+    /** Drawable fallback and refinement keys. */
+    visible: Set<string>;
+}
+
+/** Shared-consumer residency metadata; does not own tiles, loading or disposal. */
+export class TileResidency<ConsumerId = symbol> {
+    /** Consumers retain independent snapshots of their selected and visible keys. */
+    private readonly consumers = new Map<ConsumerId, TileConsumerState>();
+
+    /** Attach a consumer with empty state, resetting it if already attached. */
+    attachConsumer(id: ConsumerId): void {
+        this.updateConsumer(id, [], []);
+    }
+
+    /** Replace a consumer's state with copied keys; unknown consumers are attached. */
+    updateConsumer(id: ConsumerId, selected: readonly string[], visible: readonly string[]): void {
+        this.consumers.set(id, {selected: new Set(selected), visible: new Set(visible)});
+    }
+
+    /** Release only this consumer's protection, leaving other consumers intact. */
+    detachConsumer(id: ConsumerId): void {
+        this.consumers.delete(id);
+    }
+
+    /** Return a detached, deduplicated union in consumer and key insertion order. */
+    getSelectedTileKeys(): string[] {
+        return [...new Set([...this.consumers.values()].flatMap(consumer => [...consumer.selected]))];
+    }
+
+    /** Whether any consumer selects or displays a key, even if its content is not loaded. */
+    isProtected(key: string): boolean {
+        for (const consumer of this.consumers.values()) {
+            if (consumer.selected.has(key) || consumer.visible.has(key)) return true;
+        }
+        return false;
+    }
+
+    /** Release all consumer metadata; no tile resources are unloaded. */
+    clear(): void {
+        this.consumers.clear();
+    }
+}