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

package/src/experimental/projected-basemaps.ts

@@ -0,0 +1,301 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Layer} from '@deck.gl/core';
+import {Matrix4} from '@math.gl/core';
+import {HostFrame, Renderer, normalizeProjectedBasemapOptions, countProjectedTileCoordinates, getProjectedRoadUnit, validateProjectedLights} from '@tangram.gl/tangram-renderer/core';
+import type {HostFrameOptions, HostTileResourceOptions, ProjectedBasemapOptions} from '@tangram.gl/tangram-renderer/core';
+import createTangramLayerClass from '../tangram-layer.js';
+
+export {ProjectedBasemapNavigation, getProjectedGeographicBounds} from './projected-navigation';
+export type {ProjectedNavigationViewport, ProjectedBasemapType, ProjectedGeographicBounds,
+    ProjectedGeographicPosition, ProjectedFitOptions, ProjectedFitViewState,
+    ProjectedCameraCoverage, ProjectedFocusTransition, ProjectedNavigationRequestOptions} from './projected-navigation';
+export {selectProjectedTileDetail} from './projected-detail';
+export type {ProjectedTileDetailOptions, ProjectedTileDetail} from './projected-detail';
+
+/** The public, non-geospatial OrthographicViewport camera consumed by the adapter. */
+export interface ProjectedViewport {
+    /** Viewports must use Cartesian common-space positions, not automatic Mercator offsets. */
+    isGeospatial: boolean;
+    /** Viewport width in CSS pixels. */
+    width: number;
+    /** Viewport height in CSS pixels. */
+    height: number;
+    /** World-to-camera matrix supplied by deck.gl. */
+    viewMatrix: ArrayLike<number>;
+    /** Camera-to-clip matrix supplied by deck.gl. */
+    projectionMatrix: ArrayLike<number>;
+    /** Explicit deck.gl orthographic contract; perspective viewports are rejected. */
+    constructor: {displayName?: string; name?: string};
+}
+
+/** Explicit geographic coverage and source detail; viewport zoom is not geographic style zoom. */
+export interface ProjectedViewOptions {
+    /** Must match the scene's worker projection; Albers initially uses a North American footprint. */
+    projection: ProjectedBasemapOptions;
+    /** Single-world west/south/east/north degrees; no poles or arbitrary-cut meridians. */
+    visibleBounds: readonly [number, number, number, number];
+    /** Source data detail in [0, 6], deliberately independent of OrthographicView zoom. */
+    tileZoom: number;
+    /** Styling level in [0, 22], no lower than data detail; defaults to tileZoom. */
+    styleZoom?: number;
+    /** Optional positive per-source candidate limit checked before any tile allocation. */
+    maxTiles?: number;
+    /** Shared worker concurrency and completed off-screen mesh cache limits. */
+    tileResources?: HostTileResourceOptions;
+}
+
+/** Supply a common-space orthographic camera without claiming its matrices contain EPSG:3857 meters. */
+export function getProjectedViewFrame(viewport: ProjectedViewport, options: ProjectedViewOptions,
+    dimensions = {width: viewport.width, height: viewport.height}): HostFrameOptions {
+    if (viewport.isGeospatial !== false ||
+        (viewport.constructor.displayName !== 'OrthographicViewport' && viewport.constructor.name !== 'OrthographicViewport')) {
+        throw new Error('CPU-projected basemaps require deck.gl OrthographicView');
+    }
+    const cameraProjection = new Matrix4(Array.from(viewport.projectionMatrix)).multiplyRight(Array.from(viewport.viewMatrix));
+    const [west, south, east, north] = options.visibleBounds;
+    const projection = normalizeProjectedBasemapOptions(options.projection);
+    const styleZoom = options.styleZoom ?? options.tileZoom;
+    if (!Number.isSafeInteger(styleZoom) || styleZoom < 0 || styleZoom > 22) {
+        throw new Error('Projected styleZoom must be an integer in [0, 22]');
+    }
+    if (options.maxTiles !== undefined && (!Number.isSafeInteger(options.maxTiles) || options.maxTiles < 1)) {
+        throw new Error('Projected maxTiles must be a positive safe integer');
+    }
+    if (projection.type === 'albers' && (west < -170 || east > -40 || south < 5 || north > 75)) {
+        throw new Error('Initial Albers coverage must remain within [-170, 5, -40, 75] degrees');
+    }
+    const frame: HostFrameOptions = {
+        viewport: dimensions,
+        projection: {type: 'projected', visibleBounds: options.visibleBounds},
+        geographicAnchor: {longitude: (west + east) / 2, latitude: (south + north) / 2, zoom: styleZoom},
+        tileZoom: options.tileZoom,
+        tileBuffer: 0,
+        ...(options.tileResources === undefined ? {} : {tileResources: options.tileResources}),
+        renderViews: [{id: 'projected', camera: {view: new Float64Array(new Matrix4()),
+            projection: new Float64Array(cameraProjection), position: [0, 0, 1]}}]
+    };
+    // Validate before any renderer frame or tile state is modified.
+    new HostFrame(frame);
+    if (options.maxTiles !== undefined) {
+        const count = countProjectedTileCoordinates(options.visibleBounds, options.tileZoom);
+        if (count > options.maxTiles) {
+            throw new Error(`Projected footprint requires ${count} tiles per source, exceeding maxTiles ${options.maxTiles}`);
+        }
+    }
+    return frame;
+}
+
+/** Add the isolated projection worker to an inline scene without mutating its sources or style definitions. */
+export function createProjectedBasemapScene(scene: Record<string, unknown>, projection: ProjectedBasemapOptions,
+    workerUrl: string): Record<string, unknown> {
+    const options = normalizeProjectedBasemapOptions(projection);
+    validateProjectedLights(scene.lights);
+    const url = new URL(workerUrl);
+    if (!['http:', 'https:', 'blob:'].includes(url.protocol)) throw new Error('Projection worker requires an HTTP(S) or Blob URL');
+    if (scene.import !== undefined) throw new Error('Initial projected basemaps require a self-contained inline scene');
+    const styles = readRecord(scene.styles ?? {}, 'styles');
+    for (const value of Object.values(styles)) {
+        const style = readRecord(value, 'style');
+        if (!['polygons', 'raster', 'lines', 'points', 'text'].includes(String(style.base)) || style.mix !== undefined ||
+            style.shaders !== undefined || (style.lighting !== undefined && style.lighting !== false &&
+                (!['polygons', 'raster'].includes(String(style.base)) || !['vertex', 'fragment'].includes(String(style.lighting))))) {
+            throw new Error('Projected styles require ground/annotation bases or vertex/fragment-lit surfaces without mixins or shaders');
+        }
+        if (style.material !== undefined) {
+            const material = readRecord(style.material, 'material');
+            if (material.normal !== undefined || (material.specular !== undefined && material.specular !== 0)) {
+                throw new Error('Projected lighting supports diffuse materials without normal maps or specular terms');
+            }
+        }
+        if (style.draw !== undefined) validateFlatDraw(readRecord(style.draw, 'style draw defaults'),
+            Boolean(options.allowElevation && ['polygons', 'raster', 'points', 'text'].includes(String(style.base))));
+        if (style.draw !== undefined && ['points', 'text'].includes(String(style.base))) {
+            validateAnnotationDraw(readRecord(style.draw, 'annotation defaults'));
+        }
+        if (style.base === 'raster' && style.draw !== undefined && readRecord(style.draw, 'raster defaults').interactive === true) {
+            throw new Error('Raster imagery does not expose selectable source features');
+        }
+        if (style.base === 'lines') {
+            validateRoadDraw(style, false);
+            if (style.draw !== undefined) validateRoadDraw(readRecord(style.draw, 'style draw defaults'), false);
+        }
+    }
+    for (const layer of Object.values(readRecord(scene.layers ?? {}, 'layers'))) {
+        validateProjectedDraws(readRecord(layer, 'root layer'), styles, {}, Boolean(options.allowElevation));
+    }
+    const settings = scene.scene;
+    if (settings !== undefined && (!settings || typeof settings !== 'object' || Array.isArray(settings))) {
+        throw new Error('Projected scene settings must be an object');
+    }
+    const scripts = settings && 'scripts' in settings ? settings.scripts : [];
+    if (!Array.isArray(scripts) || !scripts.every(script => typeof script === 'string')) {
+        throw new Error('Projected scene scripts must be an array of URLs');
+    }
+    return {...scene, scene: {...settings, scripts: [...new Set([...scripts, url.href])], cpu_projection: options}};
+}
+
+/** Reject unsupported authored features before any worker starts or a partial map can appear. */
+function validateProjectedDraws(node: Record<string, unknown>, styles: Record<string, unknown>,
+    inheritedDraws: Record<string, Record<string, unknown>> = {}, allowElevation = false): void {
+    const effectiveDraws = {...inheritedDraws};
+    if (node.draw !== undefined) {
+        for (const [name, value] of Object.entries(readRecord(node.draw, 'draw'))) {
+            const draw = mergeAnnotationDraws(effectiveDraws[name] ?? {}, readRecord(value, 'draw style'));
+            effectiveDraws[name] = draw;
+            const styleName = String(draw.style ?? name);
+            const style = styleName in styles ? readRecord(styles[styleName], 'draw style definition') : {base: styleName};
+            if (!['polygons', 'raster', 'lines', 'points', 'text'].includes(String(style.base))) {
+                throw new Error('Projected basemaps require supported surface, road or annotation bases');
+            }
+            validateFlatDraw(draw, allowElevation && ['polygons', 'raster', 'points', 'text'].includes(String(style.base)));
+            if (style.base === 'raster' && draw.interactive === true) throw new Error('Raster imagery does not expose selectable source features');
+            if (style.base === 'points' || style.base === 'text') {
+                const defaults = style.draw === undefined ? {} : readRecord(style.draw, 'annotation defaults');
+                const annotation = mergeAnnotationDraws(defaults, draw);
+                validateFlatDraw(annotation, allowElevation);
+                validateAnnotationDraw(annotation);
+                if (annotation.collide !== undefined && typeof annotation.collide !== 'boolean') throw new Error('Projected collide must be boolean');
+                if (annotation.text !== undefined) {
+                    const text = readRecord(annotation.text, 'attached text');
+                    if (text.collide !== undefined && typeof text.collide !== 'boolean') throw new Error('Projected collide must be boolean');
+                    validateFlatDraw(text);
+                }
+            }
+            if (style.base === 'lines') {
+                const defaults = style.draw === undefined ? {} : readRecord(style.draw, 'style draw defaults');
+                validateRoadDraw({...defaults, ...draw}, true);
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(node)) {
+        // Match Tangram layer parsing: configuration records are not child layers.
+        if (!['filter', 'draw', 'visible', 'enabled', 'data', 'exclusive', 'priority'].includes(key) &&
+            value && typeof value === 'object' && !Array.isArray(value)) {
+            validateProjectedDraws(readRecord(value, 'layer'), styles, effectiveDraws, allowElevation);
+        }
+    }
+}
+
+/** Preserve nested attached-text settings when applying style defaults or child-layer overrides. */
+function mergeAnnotationDraws(defaults: Record<string, unknown>, draw: Record<string, unknown>): Record<string, unknown> {
+    const merged = {...defaults, ...draw};
+    if (defaults.text && typeof defaults.text === 'object' && !Array.isArray(defaults.text) &&
+        draw.text && typeof draw.text === 'object' && !Array.isArray(draw.text)) {
+        merged.text = {...readRecord(defaults.text, 'attached text defaults'), ...readRecord(draw.text, 'attached text')};
+    }
+    return merged;
+}
+
+/** Apply height opt-in to layer draws and inherited style defaults; interactive draws opt into selection. */
+function validateFlatDraw(draw: Record<string, unknown>, allowElevation = false): void {
+    if (!allowElevation && ((draw.extrude !== undefined && draw.extrude !== false) || draw.z !== undefined)) {
+        throw new Error('Projected basemaps require flat draws unless allowElevation is enabled');
+    }
+}
+
+/** Billboards may have altitude, not extrusion; attached text inherits its point's anchor height. */
+function validateAnnotationDraw(draw: Record<string, unknown>): void {
+    if (draw.extrude !== undefined && draw.extrude !== false) throw new Error('Projected annotations do not support extrusion');
+    if (draw.text !== undefined && draw.text !== false) validateFlatDraw(readRecord(draw.text, 'attached text'));
+}
+
+/** Copy validated object records without accepting arrays or prototype properties as configuration. */
+function readRecord(value: unknown, label: string): Record<string, unknown> {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Projected ${label} must be an object`);
+    return Object.fromEntries(Object.entries(value));
+}
+
+/** Fixed and zoom-stop meter/pixel roads share the builder; reject functions and mixed-unit offsets/outlines. */
+function validateRoadDraw(draw: Record<string, unknown>, requireWidth: boolean): void {
+    if (draw.outline !== undefined) readRecord(draw.outline, 'road outline');
+    if (['next_width', 'next_offset', 'texture'].some(key => draw[key] !== undefined)) {
+        throw new Error('Projected roads require static ribbons without dynamic widths or external textures');
+    }
+    if (draw.width !== undefined || requireWidth) {
+        const unit = getProjectedRoadUnit(draw.width);
+        if (draw.offset !== undefined && getProjectedRoadUnit(draw.offset, false) !== unit) throw new Error('Projected road offsets must use the width unit');
+        if (draw.outline !== undefined) {
+            const outline = readRecord(draw.outline, 'road outline');
+            validateFlatDraw(outline);
+            if (outline.style !== undefined) throw new Error('Projected road outlines must use the parent line style');
+            if (getProjectedRoadUnit(outline.width) !== unit) throw new Error('Projected road outlines must use the width unit');
+            validateRoadDraw(outline, true);
+        }
+    }
+    if (draw.animated !== undefined && typeof draw.animated !== 'boolean') throw new Error('Projected road animated must be boolean');
+    if (draw.dash !== undefined && (!Array.isArray(draw.dash) || draw.dash.length === 0 ||
+        !draw.dash.every(value => typeof value === 'number' && Number.isFinite(value) && value > 0))) {
+        throw new Error('Projected road dash must contain positive finite lengths');
+    }
+}
+
+/** Opt-in deck.gl basemap layer; the ordinary package root still uses its existing view adapters. */
+const BaseProjectedBasemapLayer = createTangramLayerClass({Layer, ClassicWebGLRenderer: Renderer,
+    Renderer: undefined}, {
+        getFrame(viewport: ProjectedViewport, properties: {scene: unknown; projectedVisibleBounds?: ProjectedViewOptions['visibleBounds'];
+            projectedTileZoom?: number; projectedProjection?: ProjectedBasemapOptions;
+            projectedStyleZoom?: number | null; projectedMaxTiles?: number | null;
+            tileResources?: HostTileResourceOptions | null}, dimensions: {width: number; height: number}) {
+            const scene = readRecord(properties.scene, 'scene');
+            const settings = readRecord(scene.scene, 'scene settings');
+            const projection = normalizeProjectedBasemapOptions(properties.projectedProjection ?? settings.cpu_projection);
+            return getProjectedViewFrame(viewport, {
+                projection,
+                visibleBounds: properties.projectedVisibleBounds ?? (projection.type === 'albers' ? [-170, 5, -40, 75] :
+                    [-180, -85.0511287798066, 180, 85.0511287798066]),
+                tileZoom: properties.projectedTileZoom ?? 2,
+                ...(properties.projectedStyleZoom == null ? {} : {styleZoom: properties.projectedStyleZoom}),
+                ...(properties.projectedMaxTiles == null ? {} : {maxTiles: properties.projectedMaxTiles}),
+                ...(properties.tileResources == null ? {} : {tileResources: properties.tileResources})
+            }, dimensions);
+        }
+    });
+
+/** Opt-in projection changes rebuild meshes on the existing renderer instead of reloading the scene. */
+export class ProjectedBasemapLayer extends BaseProjectedBasemapLayer {
+    /**
+     * Query interactive Tangram geometry asynchronously in viewport-local CSS pixels.
+     * This is not deck.gl's synchronous picking API. The host must keep rendering
+     * until the selection pass and worker lookup finish; the layer requests a redraw.
+     */
+    getFeatureAt(pixel: {x: number; y: number}, options: import('@tangram.gl/tangram-renderer/core').FeatureSelectionOptions = {}): Promise<import('@tangram.gl/tangram-renderer/core').FeatureSelectionResult | undefined> {
+        return super.getFeatureAt(pixel, options);
+    }
+    /** deck.gl's stable layer identity for state transfer between property updates. */
+    static layerName = 'ProjectedBasemapLayer';
+    /** Optional projection override and completion notification, independent of source scene identity. */
+    static defaultProps = {...BaseProjectedBasemapLayer.defaultProps,
+        projectedVisibleBounds: null, projectedTileZoom: 2, projectedProjection: null,
+        projectedStyleZoom: null, projectedMaxTiles: null,
+        onProjectionChange: {type: 'function', value: () => {}}};
+
+    /** Keep the ordinary scene lifecycle, then queue an opt-in projection-only update after loading. */
+    updateState(parameters: {props: Partial<import('../tangram-layer').TangramLayerProps>}): void {
+        super.updateState(parameters);
+        const record = this.state.tangramRecord;
+        if (!record) return;
+        const settings = readRecord(readRecord(record.sceneSource, 'scene').scene, 'scene settings');
+        const projection = normalizeProjectedBasemapOptions(parameters.props.projectedProjection ?? settings.cpu_projection);
+        const key = JSON.stringify(projection);
+        if (record.projectedProjectionKey === key) return;
+        record.projectedProjectionKey = key;
+        Promise.resolve(record.loadPromise).then(async () => {
+            if (record.disposed || record.loadFailed || record.projectedProjectionKey !== key) return;
+            await record.renderer.setProjectedBasemapProjection(projection);
+            if (!record.disposed && record.projectedProjectionKey === key) {
+                record.owner.props.onProjectionChange!(projection);
+                record.owner.setNeedsRedraw();
+            }
+        }).catch(error => {
+            if (!record.disposed && record.projectedProjectionKey === key) {
+                record.projectedProjectionKey = null;
+                record.owner._reportSceneError(record, error);
+            }
+        });
+    }
+}
+
+export type {ProjectedBasemapOptions};

package/src/experimental/projected-detail.ts

@@ -0,0 +1,116 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {countProjectedTileCoordinates, WebMercatorVisibilityAdapter, projectGeographicPosition,
+    getTileGeographicBounds} from '@tangram.gl/tangram-renderer/core';
+import {validateProjectedGeographicBounds, validateProjectedNavigationViewport} from './projected-navigation';
+import type {ProjectedBasemapNavigation, ProjectedBasemapType, ProjectedGeographicBounds,
+    ProjectedNavigationViewport} from './projected-navigation';
+
+/** Explicit opt-in uniform source detail policy, independent of geographic style zoom. */
+export interface ProjectedTileDetailOptions {
+    /** Fixed geographic loading region; this policy does not infer visible geographic bounds. */
+    visibleBounds: ProjectedGeographicBounds;
+    /** Lowest permissible data level in [0, 6]; defaults to 0. */
+    minZoom?: number;
+    /** Highest permissible data level in [0, 6]; defaults to 6. */
+    maxZoom?: number;
+    /** Desired maximum sampled tile span in CSS pixels; defaults to 256. */
+    targetTilePixels?: number;
+    /** Positive per-source candidate limit; defaults to 256. */
+    maxTiles?: number;
+    /** Previous level, used only if it remains in range and within budget. */
+    currentTileZoom?: number;
+    /** Fractional hysteresis around adjacent-level thresholds in [0, 0.5); defaults to 0.15. */
+    hysteresis?: number;
+}
+
+/** Diagnostic result; exhausting resource/detail bounds is explicit rather than hidden. */
+export interface ProjectedTileDetail {
+    /** Selected source detail, suitable for projectedTileZoom. */
+    tileZoom: number;
+    /** Actual single-world logical candidates per source at that detail. */
+    candidateCount: number;
+    /** Maximum screen span of the sampled, domain-clipped tile footprints. */
+    estimatedTilePixels: number;
+    /** Whether a finer level was unavailable because it exceeds maxTiles. */
+    budgetLimited: boolean;
+    /** Whether the maximum configured detail still cannot reach the target pixel span. */
+    detailLimited: boolean;
+}
+
+/** Choose uniform XYZ detail from projected tile samples, camera scale, hysteresis and candidate limits. */
+export async function selectProjectedTileDetail(navigation: ProjectedBasemapNavigation, viewport: ProjectedNavigationViewport,
+    type: ProjectedBasemapType, options: ProjectedTileDetailOptions): Promise<ProjectedTileDetail> {
+    validateProjectedNavigationViewport(viewport);
+    const {visibleBounds, minZoom = 0, maxZoom = 6, targetTilePixels = 256, maxTiles = 256, currentTileZoom,
+        hysteresis = 0.15} = options;
+    validateProjectedGeographicBounds(visibleBounds, type);
+    if (![minZoom, maxZoom].every(value => Number.isSafeInteger(value) && value >= 0 && value <= 6) || minZoom > maxZoom ||
+        !Number.isFinite(targetTilePixels) || targetTilePixels <= 0 || !Number.isSafeInteger(maxTiles) || maxTiles < 1 ||
+        !Number.isFinite(hysteresis) || hysteresis < 0 || hysteresis >= 0.5 ||
+        (currentTileZoom !== undefined && (!Number.isSafeInteger(currentTileZoom) || currentTileZoom < 0 || currentTileZoom > 6))) {
+        throw new Error('Projected tile detail requires ordered levels 0–6, positive pixel/candidate limits and finite hysteresis');
+    }
+    const candidates: {zoom: number; count: number}[] = [];
+    for (let zoom = minZoom; zoom <= maxZoom; zoom++) {
+        const count = countProjectedTileCoordinates(visibleBounds, zoom);
+        if (count > maxTiles) break;
+        candidates.push({zoom, count});
+    }
+    if (!candidates.length) throw new Error('Projected minimum tile detail exceeds the candidate budget');
+    const southwest = projectGeographicPosition([visibleBounds[0], visibleBounds[1], 0], 'web-mercator');
+    const northeast = projectGeographicPosition([visibleBounds[2], visibleBounds[3], 0], 'web-mercator');
+    const traversal = new WebMercatorVisibilityAdapter();
+    const measurements = new Map<number, number>();
+    const measure = async (zoom: number) => {
+        const cached = measurements.get(zoom);
+        if (cached !== undefined) return cached;
+        const tiles = traversal.findVisibleTileCoordinates({center: {lng: 0, lat: 0}, zoom, tile_zoom: zoom,
+            size: {css: {width: viewport.width, height: viewport.height}}, buffer: 0, wrap: false,
+            bounds: {sw: {x: southwest[0], y: southwest[1]}, ne: {x: northeast[0], y: northeast[1]}}});
+        const coordinates: number[] = [];
+        for (const tile of tiles) {
+            const bounds = getTileGeographicBounds(tile);
+            const west = Math.max(visibleBounds[0], bounds.west), south = Math.max(visibleBounds[1], bounds.south);
+            const east = Math.min(visibleBounds[2], bounds.east), north = Math.min(visibleBounds[3], bounds.north);
+            // Nine samples per clipped candidate; interior samples capture bowed regional projections.
+            for (let column = 0; column <= 2; column++) for (let row = 0; row <= 2; row++) {
+                coordinates.push(west + (east - west) * column / 2, south + (north - south) * row / 2);
+            }
+        }
+        const positions = await navigation.projectPositions(new Float64Array(coordinates), type);
+        let maximum = 0;
+        for (let offset = 0; offset < positions.length; offset += 18) {
+            let west = Infinity, south = Infinity, east = -Infinity, north = -Infinity;
+            for (let index = offset; index < offset + 18; index += 2) {
+                const screen = viewport.project([positions[index], positions[index + 1], 0]);
+                if (![screen[0], screen[1]].every(Number.isFinite)) throw new Error('Projected tile detail produced nonfinite screen positions');
+                west = Math.min(west, screen[0]); east = Math.max(east, screen[0]);
+                south = Math.min(south, screen[1]); north = Math.max(north, screen[1]);
+            }
+            maximum = Math.max(maximum, east - west, north - south);
+        }
+        measurements.set(zoom, maximum);
+        return maximum;
+    };
+    let selected = candidates[candidates.length - 1];
+    const current = candidates.find(candidate => candidate.zoom === currentTileZoom);
+    if (current) {
+        const pixels = await measure(current.zoom);
+        const coarser = candidates.find(candidate => candidate.zoom === current.zoom - 1);
+        if (pixels <= targetTilePixels * (1 + hysteresis) &&
+            (!coarser || await measure(coarser.zoom) > targetTilePixels * (1 - hysteresis))) selected = current;
+        else {
+            for (const candidate of candidates) if (await measure(candidate.zoom) <= targetTilePixels) {selected = candidate; break;}
+        }
+    } else {
+        for (const candidate of candidates) if (await measure(candidate.zoom) <= targetTilePixels) {selected = candidate; break;}
+    }
+    const estimatedTilePixels = await measure(selected.zoom);
+    const unmet = estimatedTilePixels > targetTilePixels * (1 + hysteresis);
+    return {tileZoom: selected.zoom, candidateCount: selected.count, estimatedTilePixels,
+        budgetLimited: unmet && candidates[candidates.length - 1].zoom < maxZoom,
+        detailLimited: unmet && selected.zoom === maxZoom};
+}