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

package/src/scene/host_frame.ts

@@ -0,0 +1,326 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GeographicAnchor, HostCamera, HostFrameOptions, HostProjection, HostTileLODOptions, HostTileResourceOptions, Viewport, FeatureSelectionOptions} from '../types';
+
+/** Validated per-eye state; optional visibility overrides never change scene/style state. */
+export interface NormalizedRenderView {
+    readonly id: string;
+    readonly viewport: Required<Viewport>;
+    readonly camera: HostCamera;
+    readonly geographicAnchor?: Required<GeographicAnchor>;
+    readonly projection?: HostProjection;
+}
+
+/** Host-owned logical frame, shared tile visibility, and independently drawable eyes. */
+export default class HostFrame {
+    /** Resolve a full-target or view-local CSS pixel without changing the active camera. */
+    resolveSelectionPoint(pixel: {x: number; y: number}, options: FeatureSelectionOptions = {},
+        activeViewId = this.activeRenderViewId): {view: NormalizedRenderView; pixel: {x: number; y: number}} | null {
+        if (![pixel.x, pixel.y].every(Number.isFinite)) throw new Error('Selection coordinates must be finite');
+        if (options.coordinateSpace !== undefined && !['view', 'canvas'].includes(options.coordinateSpace)) {
+            throw new Error('Selection coordinateSpace must be view or canvas');
+        }
+        const contains = (view: NormalizedRenderView) => pixel.x >= view.viewport.x && pixel.y >= view.viewport.y &&
+            pixel.x < view.viewport.x + view.viewport.width && pixel.y < view.viewport.y + view.viewport.height;
+        const view = options.renderViewId !== undefined ? this.getRenderView(options.renderViewId) :
+            options.coordinateSpace === 'canvas' ? [...this.renderViews].reverse().find(contains) : this.getRenderView(activeViewId);
+        if (!view) return null;
+        const local = options.coordinateSpace === 'canvas' ? {x: pixel.x - view.viewport.x, y: pixel.y - view.viewport.y} : {...pixel};
+        if (local.x < 0 || local.y < 0 || local.x >= view.viewport.width || local.y >= view.viewport.height) return null;
+        return {view, pixel: local};
+    }
+    /** Full target dimensions in CSS pixels; origins are top-left. */
+    readonly viewport: Required<Viewport>;
+    /** Shared geographic/style anchor in degrees, altitude meters, and Tangram zoom. */
+    readonly geographicAnchor: Required<GeographicAnchor>;
+    /** Shared geographic projection. */
+    readonly projection: HostProjection;
+    /** Per-eye camera and footprint state. */
+    readonly renderViews: readonly NormalizedRenderView[];
+    /** Default eye to draw. */
+    readonly activeRenderViewId: string;
+    /** Conservative neighboring tile buffer. */
+    readonly tileBuffer: number;
+    /** Shared data-tile level, independent of scene/style zoom, when supplied. */
+    readonly tileZoom?: number;
+    /** Validated projected-scale LOD settings, when enabled. */
+    readonly tileLOD?: Readonly<Required<HostTileLODOptions>>;
+    /** Shared opt-in worker and completed off-screen mesh cache limits. */
+    readonly tileResources?: Readonly<HostTileResourceOptions>;
+    /** Optional globally resident globe fallback level, capped at 64 coordinates per source. */
+    readonly globePreloadZoom?: number;
+    /** Shared elapsed scene animation time in seconds, when supplied. */
+    readonly animationTime?: number;
+
+    /** Copies and validates a host frame without retaining caller matrix arrays. */
+    constructor(options: HostFrameOptions) {
+        const record = requireRecord(options, 'HostFrame');
+        this.viewport = normalizeViewport(record.viewport, 'HostFrame viewport');
+        this.geographicAnchor = normalizeAnchor(record.geographicAnchor);
+        this.projection = normalizeProjection(record.projection);
+        this.tileBuffer = normalizeNonNegative(record.tileBuffer ?? 0, 'tileBuffer');
+        this.tileZoom = normalizeTileZoom(record.tileZoom, this.geographicAnchor.zoom);
+        this.tileLOD = normalizeTileLOD(record.tileLOD);
+        if (this.projection.type === 'projected' && (this.tileLOD || this.tileZoom === undefined || this.tileZoom > 6)) {
+            throw new Error('HostFrame CPU projection requires explicit tileZoom <= 6 and does not support automatic LOD');
+        }
+        this.tileResources = normalizeTileResources(record.tileResources);
+        this.globePreloadZoom = normalizeGlobePreloadZoom(record.globePreloadZoom);
+        if (this.globePreloadZoom !== undefined && this.projection.type !== 'globe') {
+            throw new Error('HostFrame globePreloadZoom requires a globe projection');
+        }
+        if (this.tileZoom !== undefined && this.tileLOD !== undefined) {
+            throw new Error('HostFrame tileZoom and tileLOD are mutually exclusive');
+        }
+        this.animationTime = record.animationTime === undefined ? undefined :
+            normalizeNonNegative(record.animationTime, 'animationTime');
+        if (!Array.isArray(record.renderViews) || record.renderViews.length === 0) {
+            throw new Error('HostFrame requires at least one render view');
+        }
+        const ids = new Set<string>();
+        this.renderViews = record.renderViews.map((value: unknown, index: number) => {
+            const view = requireRecord(value, `HostFrame render view ${index}`);
+            const id = typeof view.id === 'string' && view.id ? view.id : index === 0 ? 'default' : `view-${index}`;
+            if (ids.has(id)) {
+                throw new Error(`HostFrame render view id '${id}' is duplicated`);
+            }
+            ids.add(id);
+            const projection = view.projection === undefined ? undefined : normalizeProjection(view.projection);
+            if (projection && projection.type !== this.projection.type) {
+                throw new Error('HostFrame render views must share a projection type');
+            }
+            if (projection?.type === 'globe' && this.projection.type === 'globe' &&
+                this.projection.maxElevation !== undefined) {
+                if (projection.maxElevation === undefined) {
+                    projection.maxElevation = this.projection.maxElevation;
+                }
+                else if (projection.maxElevation < this.projection.maxElevation) {
+                    throw new Error('HostFrame render-view maxElevation cannot lower the shared scene bound');
+                }
+            }
+            return {
+                id,
+                viewport: normalizeViewport(view.viewport ?? this.viewport, `HostFrame render view '${id}' viewport`),
+                camera: normalizeCamera(view.camera, id),
+                geographicAnchor: view.geographicAnchor === undefined ? undefined : normalizeAnchor(view.geographicAnchor),
+                projection
+            };
+        });
+        this.activeRenderViewId = typeof record.activeRenderViewId === 'string' && record.activeRenderViewId ||
+            this.renderViews[0].id;
+        this.getRenderView();
+    }
+
+    /** Validates untrusted application input, including the original single-view shape. */
+    static from(frame: unknown): HostFrame {
+        if (frame instanceof HostFrame) {
+            return frame;
+        }
+        const record = requireRecord(frame, 'HostFrame');
+        // Normalize unknown inputs before constructing the typed frame.
+        if (record.renderViews !== undefined || record.geographicAnchor !== undefined) {
+            return HostFrame.createValidated(record);
+        }
+        return HostFrame.fromLegacy(record);
+    }
+
+    /** Converts the original viewport/view/camera contract. */
+    static fromLegacy(frame: unknown): HostFrame {
+        const record = requireRecord(frame, 'HostFrame');
+        return HostFrame.createValidated({
+            ...record,
+            geographicAnchor: record.view,
+            renderViews: [{id: 'default', viewport: record.viewport, camera: record.camera}]
+        });
+    }
+
+    /** Returns the selected eye or throws before any scene state is modified. */
+    getRenderView(id = this.activeRenderViewId): NormalizedRenderView {
+        const view = this.renderViews.find(candidate => candidate.id === id);
+        if (!view) {
+            throw new Error(`HostFrame render view '${id}' was not found`);
+        }
+        return view;
+    }
+
+    private static createValidated(record: Record<string, unknown>): HostFrame {
+        const viewport = normalizeViewport(record.viewport, 'HostFrame viewport');
+        if (!Array.isArray(record.renderViews) || record.renderViews.length === 0) {
+            throw new Error('HostFrame requires at least one render view');
+        }
+        return new HostFrame({
+            viewport,
+            geographicAnchor: normalizeAnchor(record.geographicAnchor),
+            projection: normalizeProjection(record.projection),
+            renderViews: record.renderViews.map((value: unknown, index: number) => {
+                const view = requireRecord(value, `HostFrame render view ${index}`);
+                return {
+                    id: typeof view.id === 'string' ? view.id : undefined,
+                    viewport: normalizeViewport(view.viewport ?? viewport, 'HostFrame render view viewport'),
+                    camera: normalizeCamera(view.camera, String(index)),
+                    geographicAnchor: view.geographicAnchor === undefined ? undefined : normalizeAnchor(view.geographicAnchor),
+                    projection: view.projection === undefined ? undefined : normalizeProjection(view.projection)
+                };
+            }),
+            activeRenderViewId: typeof record.activeRenderViewId === 'string' ? record.activeRenderViewId : undefined,
+            tileBuffer: normalizeNonNegative(record.tileBuffer ?? 0, 'tileBuffer'),
+            tileZoom: normalizeTileZoom(record.tileZoom, normalizeAnchor(record.geographicAnchor).zoom),
+            tileLOD: normalizeTileLOD(record.tileLOD),
+            tileResources: normalizeTileResources(record.tileResources),
+            globePreloadZoom: normalizeGlobePreloadZoom(record.globePreloadZoom),
+            animationTime: record.animationTime === undefined ? undefined : normalizeNonNegative(record.animationTime, 'animationTime')
+        });
+    }
+}
+
+/** Reject unsafe limits before any camera or worker state is modified. */
+function normalizeTileResources(value: unknown): HostTileResourceOptions | undefined {
+    if (value === undefined) return undefined;
+    const record = requireRecord(value, 'HostFrame tileResources');
+    const result: HostTileResourceOptions = {};
+    for (const name of ['maxConcurrentBuilds', 'maxCachedTiles', 'maxCachedMeshBytes'] as const) {
+        const limit = record[name];
+        if (limit === undefined) continue;
+        if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < (name === 'maxConcurrentBuilds' ? 1 : 0)) {
+            throw new Error(`HostFrame tileResources ${name} must be a ${name === 'maxConcurrentBuilds' ? 'positive' : 'non-negative'} safe integer`);
+        }
+        result[name] = limit;
+    }
+    return Object.freeze(result);
+}
+
+/** Bound global residency before any tile enumeration or scene mutation. */
+function normalizeGlobePreloadZoom(value: unknown): number | undefined {
+    if (value === undefined) return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 3) {
+        throw new Error('HostFrame globePreloadZoom must be an integer from 0 to 3');
+    }
+    return value;
+}
+
+/** Copy and validate all policy inputs before camera or scene state is touched. */
+function normalizeTileLOD(value: unknown): Required<HostTileLODOptions> | undefined {
+    if (value === undefined) return undefined;
+    const record = requireRecord(value, 'HostFrame tileLOD');
+    const targetTilePixels = record.targetTilePixels ?? 512;
+    const pixelRatio = record.pixelRatio ?? 1;
+    const maxTiles = record.maxTiles ?? 256;
+    const hysteresis = record.hysteresis ?? 0.2;
+    if (!isFiniteNumber(targetTilePixels) || targetTilePixels <= 0 ||
+        !isFiniteNumber(pixelRatio) || pixelRatio <= 0 ||
+        !isFiniteNumber(maxTiles) || !Number.isSafeInteger(maxTiles) || maxTiles < 1 ||
+        !isFiniteNumber(hysteresis) || hysteresis < 0 || hysteresis >= 1) {
+        throw new Error('HostFrame tileLOD requires positive pixel scales, a positive integer maxTiles, and hysteresis in [0, 1)');
+    }
+    return {targetTilePixels, pixelRatio, maxTiles, hysteresis};
+}
+
+/** Validate coarsening without introducing unsupported geometry underzoom. */
+function normalizeTileZoom(value: unknown, styleZoom: number): number | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 22 ||
+        value > Math.floor(styleZoom)) {
+        throw new Error('HostFrame tileZoom must be an integer from 0 to 22, no higher than the shared style zoom');
+    }
+    return value;
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} requires an object`);
+    }
+    return Object.fromEntries(Object.entries(value));
+}
+
+function normalizeViewport(value: unknown, label: string): Required<Viewport> {
+    const record = value && typeof value === 'object' ? requireRecord(value, label) : {};
+    if (!isFiniteNumber(record.width) || record.width <= 0 ||
+        !isFiniteNumber(record.height) || record.height <= 0) {
+        throw new Error(`${label} requires positive width and height`);
+    }
+    return {x: finiteOr(record.x, 0), y: finiteOr(record.y, 0), width: record.width, height: record.height};
+}
+
+function normalizeAnchor(value: unknown): Required<GeographicAnchor> {
+    const record = value && typeof value === 'object' ? requireRecord(value, 'HostFrame geographic anchor') : {};
+    if (!isFiniteNumber(record.longitude) || !isFiniteNumber(record.latitude) || !isFiniteNumber(record.zoom)) {
+        throw new Error('HostFrame geographic anchor requires finite longitude, latitude, and zoom');
+    }
+    return {longitude: record.longitude, latitude: record.latitude, zoom: record.zoom, altitude: finiteOr(record.altitude, 0)};
+}
+
+function normalizeProjection(value: unknown): HostProjection {
+    const record = value === undefined ? {} : requireRecord(value, 'HostFrame projection');
+    const type = value === undefined ? 'web-mercator' : record.type;
+    if (type === 'web-mercator' || type === 'projected') {
+        if (type === 'projected' && (record.visibleBounds === undefined || record.visibleBounds === null)) {
+            throw new Error('HostFrame CPU projection requires an explicit geographic footprint');
+        }
+        if (type === 'web-mercator' && record.visibleBounds === undefined) return {type};
+        if (type === 'web-mercator' && record.visibleBounds === null) return {type, visibleBounds: null};
+        const bounds = record.visibleBounds;
+        if (!Array.isArray(bounds) || bounds.length !== 4 || !bounds.every(isFiniteNumber) ||
+            bounds[0] > bounds[2] || bounds[1] > bounds[3] || bounds[1] <= -90 || bounds[3] >= 90) {
+            throw new Error('HostFrame planar projection requires finite ordered visibleBounds with latitudes strictly between -90 and 90');
+        }
+        if (type === 'projected' && (bounds[0] < -180 || bounds[2] > 180 || bounds[1] < -85.0511287798066 || bounds[3] > 85.0511287798066)) {
+            throw new Error('HostFrame CPU projection footprint must stay inside the finite single-world tile domain');
+        }
+        return {type, visibleBounds: [bounds[0], bounds[1], bounds[2], bounds[3]]};
+    }
+    if (type !== 'globe') {
+        throw new Error(`HostFrame projection type '${String(type)}' is invalid`);
+    }
+    const bounds = record.visibleBounds;
+    if (!Array.isArray(bounds) || bounds.length !== 4 || !bounds.every(isFiniteNumber)) {
+        throw new Error('HostFrame globe projection requires finite visibleBounds');
+    }
+    return {
+        type, visibleBounds: [bounds[0], bounds[1], bounds[2], bounds[3]],
+        ...(record.maxElevation === undefined ? {} : {
+            maxElevation: normalizeNonNegative(record.maxElevation, 'maxElevation')
+        })
+    };
+}
+
+function normalizeCamera(value: unknown, id: string): HostCamera {
+    const record = value && typeof value === 'object' ? requireRecord(value, 'HostFrame camera') : {};
+    const view = readFiniteArray(record.view, 16);
+    const projection = readFiniteArray(record.projection, 16);
+    const position = readFiniteArray(record.position, 3);
+    if (!view || !projection || !position) {
+        throw new Error(`HostFrame render view '${id}' requires finite camera matrices and position`);
+    }
+    const projectionMatrix = new Float32Array(projection);
+    if (!projectionMatrix.every(Number.isFinite)) {
+        throw new Error(`HostFrame render view '${id}' requires finite camera matrices and position`);
+    }
+    return {view: new Float64Array(view), projection: projectionMatrix, position: [position[0], position[1], position[2]]};
+}
+
+function readFiniteArray(value: unknown, length: number): number[] | null {
+    if (!Array.isArray(value) && !(value instanceof Float32Array) && !(value instanceof Float64Array)) {
+        return null;
+    }
+    const values: unknown[] = Array.from(value);
+    return values.length === length && values.every(isFiniteNumber) ? values : null;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+
+function finiteOr(value: unknown, fallback: number): number {
+    return isFiniteNumber(value) ? value : fallback;
+}
+
+function normalizeNonNegative(value: unknown, label: string): number {
+    if (!isFiniteNumber(value) || value < 0) {
+        throw new Error(`HostFrame ${label} must be a finite non-negative number`);
+    }
+    return value;
+}

package/src/scene/projected_tile_lod.ts

@@ -0,0 +1,125 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import Geo, {type Bounds} from '../utils/geo';
+import type {HostCamera, HostProjection, Viewport} from '../types';
+import type HostFrame from './host_frame';
+import {getProjectionSurface} from './projection_math';
+
+/** One eye's surface footprint and projection, independent of the embedding library. */
+export interface ProjectedLODEye {
+    /** Matrices in the renderer's planar/globe host convention. */
+    readonly camera: HostCamera;
+    /** Geographic projection of the surface. */
+    readonly projection: HostProjection;
+    /** Eye viewport in CSS pixels. */
+    readonly viewport: Required<Viewport>;
+    /** Unwrapped Mercator-meter footprint, or null when no surface is visible. */
+    readonly bounds: Bounds | null;
+}
+
+/** Stateful, opt-in uniform surface-scale LOD; never changes scene/style zoom. */
+export default class ProjectedTileLOD {
+    private previousZoom?: number;
+    private policyKey = '';
+
+    /** Selects one level for every eye before allocating candidates or installing a frame. */
+    select(frame: HostFrame, eyes: readonly ProjectedLODEye[], countCandidates: (zoom: number) => number): number | undefined {
+        const options = frame.tileLOD;
+        if (!options) {
+            this.previousZoom = undefined;
+            this.policyKey = '';
+            return frame.tileZoom;
+        }
+        const key = JSON.stringify([options, frame.projection.type]);
+        const maximumZoom = Math.min(22, Math.max(0, Math.floor(frame.geographicAnchor.zoom)));
+        let scale = 0;
+        for (const eye of eyes) {
+            scale = Math.max(scale, getProjectedScale(eye, options.pixelRatio));
+        }
+        // Missing visible samples are not evidence that coarse data is sufficient.
+        const desiredZoom = scale > 0
+            ? Math.log2(Geo.circumference_meters * scale / options.targetTilePixels)
+            : maximumZoom;
+        let zoom = Math.min(maximumZoom, Math.max(0, Math.ceil(desiredZoom)));
+        const previous = key === this.policyKey ? this.previousZoom : undefined;
+        if (previous !== undefined && previous <= maximumZoom &&
+            desiredZoom >= previous - 1 - options.hysteresis && desiredZoom <= previous + options.hysteresis) {
+            zoom = previous;
+        }
+        for (;;) {
+            const count = countCandidates(zoom);
+            if (!Number.isFinite(count) || count < 0) {
+                throw new Error('Automatic tile LOD requires a finite non-negative candidate count');
+            }
+            if (count <= options.maxTiles) break;
+            if (zoom === 0) {
+                throw new Error('HostFrame tileLOD maxTiles cannot fit the buffered eye footprints, even at zoom 0');
+            }
+            zoom--;
+        }
+        // Failed budget checks must not affect the next successful frame's hysteresis.
+        this.previousZoom = zoom;
+        this.policyKey = key;
+        return zoom;
+    }
+}
+
+/** Estimates the strongest local surface magnification at a deterministic 3x3 footprint grid. */
+function getProjectedScale(eye: ProjectedLODEye, pixelRatio: number): number {
+    if (!eye.bounds) return 0;
+    const matrix = new Matrix4().copy(eye.camera.projection);
+    if (eye.projection.type === 'web-mercator') matrix.multiplyRight(eye.camera.view);
+    const {sw, ne} = eye.bounds;
+    let scale = 0;
+    for (const horizontal of [0, 0.5, 1]) {
+        for (const vertical of [0, 0.5, 1]) {
+            const x = sw.x + (ne.x - sw.x) * horizontal;
+            const y = sw.y + (ne.y - sw.y) * vertical;
+            const surface = getSurface(x, y, eye.projection);
+            const clip = transform(matrix, surface.position, 1);
+            if (!clip.every(Number.isFinite) || clip[3] <= 0 ||
+                Math.abs(clip[0]) > clip[3] * 1.001 || Math.abs(clip[1]) > clip[3] * 1.001 ||
+                Math.abs(clip[2]) > clip[3] * 1.001) continue;
+            const derivativeX = transform(matrix, surface.derivativeX, 0);
+            const derivativeY = transform(matrix, surface.derivativeY, 0);
+            const width = eye.viewport.width * pixelRatio / 2;
+            const height = eye.viewport.height * pixelRatio / 2;
+            const horizontalX = projectedDerivative(clip, derivativeX, 0) * width;
+            const horizontalY = projectedDerivative(clip, derivativeY, 0) * width;
+            const verticalX = projectedDerivative(clip, derivativeX, 1) * height;
+            const verticalY = projectedDerivative(clip, derivativeY, 1) * height;
+            const diagonalX = horizontalX ** 2 + verticalX ** 2;
+            const diagonalY = horizontalY ** 2 + verticalY ** 2;
+            const offDiagonal = horizontalX * horizontalY + verticalX * verticalY;
+            const largestEigenvalue = (diagonalX + diagonalY +
+                Math.hypot(diagonalX - diagonalY, 2 * offDiagonal)) / 2;
+            const candidate = Math.sqrt(largestEigenvalue);
+            if (Number.isFinite(candidate)) scale = Math.max(scale, candidate);
+        }
+    }
+    return scale;
+}
+
+/** Differential of normalized-device coordinates, including perspective division. */
+function projectedDerivative(clip: number[], derivative: number[], axis: number): number {
+    return (derivative[axis] * clip[3] - clip[axis] * derivative[3]) / (clip[3] ** 2);
+}
+
+/** Column-major homogeneous transform; derivatives use w=0, positions use w=1. */
+function transform(matrix: ArrayLike<number>, vector: number[], homogeneous: number): number[] {
+    return [0, 1, 2, 3].map(row => matrix[row] * vector[0] + matrix[row + 4] * vector[1] +
+        matrix[row + 8] * vector[2] + matrix[row + 12] * homogeneous);
+}
+
+/** Surface position and derivatives per EPSG:3857 meter, matching the globe shaders. */
+function getSurface(x: number, y: number, projection: HostProjection): {
+    position: number[]; derivativeX: number[]; derivativeY: number[];
+} {
+    if (projection.type === 'web-mercator') {
+        return {position: [x, y, 0], derivativeX: [1, 0, 0], derivativeY: [0, 1, 0]};
+    }
+    return getProjectionSurface(x, y, projection.type);
+}

package/src/scene/projection_math.ts

@@ -0,0 +1,142 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {HostProjection} from '../types';
+import {unprojectMetersToLngLatLegacy} from '../procedures/web-mercator-legacy';
+
+/** Neutral units shared by CPU geometry, lighting, shader generation and host adapters. */
+export const PROJECTION_CONSTANTS = Object.freeze({
+    /** EPSG:3857 spherical radius in meters; not the geographic altitude radius. */
+    mercatorRadius: 6378137,
+    /** Geographic altitude scale matching deck.gl's public GlobeViewport. */
+    earthRadius: 6370972,
+    /** Globe common-space radius; north is +Z and longitude zero is -Y. */
+    globeRadius: 256,
+    /** Tangram's reference tile size, distinct from deck's 512-unit world. */
+    tileSize: 256,
+    /** Mercator's finite square-world latitude cutoff in degrees. */
+    maxMercatorLatitude: 85.0511287798066
+});
+
+/** Longitude/latitude in degrees and geographic altitude in meters. */
+export type GeographicProjectionPosition = readonly [number, number, number];
+
+/** Renderer-owned geographic boundary; cameras and tile-row conversion are separate. */
+export interface GeographicProjectionProcedure {
+    /** Existing HostFrame projection discriminator; this is not a CRS identifier. */
+    readonly type: HostProjection['type'];
+    /** Absolute position units before the host's view/placement matrices. */
+    readonly positionUnits: 'meters' | 'globe-common-units';
+    /** Maximum represented latitude in degrees, after Mercator clamping. */
+    readonly latitudeLimit: number;
+    /** Whether longitude selects a nearest anchored world copy or repeats around a sphere. */
+    readonly longitudePolicy: 'nearest-anchor-or-unwrapped' | 'periodic';
+    /** Project finite degree/degree/meter positions; an anchor affects only Mercator longitude. */
+    readonly project: (position: GeographicProjectionPosition, anchorLongitude?: number) => [number, number, number];
+    /** Invert an absolute position; globe center is undefined and longitude becomes canonical. */
+    readonly unproject: (position: readonly [number, number, number]) => [number, number, number];
+    /** Rotate an ENU direction without converting its length to common-space units. */
+    readonly projectVector: (position: GeographicProjectionPosition, direction: readonly [number, number, number]) => [number, number, number];
+}
+
+/** Project geography to absolute Mercator meters or globe common coordinates, never eye space. */
+export function projectGeographicPosition(position: GeographicProjectionPosition, projection: HostProjection['type'], anchorLongitude?: number): [number, number, number] {
+    let [longitude, latitude, altitude] = position;
+    if (projection === 'projected') throw new Error('CPU-projected basemaps require the experimental worker procedure');
+    if (!position.every(Number.isFinite) || Math.abs(latitude) > 90) throw new Error('Projection requires finite geographic coordinates and latitude within +/-90 degrees');
+    if (projection === 'globe') {
+        longitude *= Math.PI / 180; latitude *= Math.PI / 180;
+        const radius = PROJECTION_CONSTANTS.globeRadius * (1 + altitude / PROJECTION_CONSTANTS.earthRadius);
+        return [Math.sin(longitude) * Math.cos(latitude) * radius,
+            -Math.cos(longitude) * Math.cos(latitude) * radius, Math.sin(latitude) * radius];
+    }
+    if (anchorLongitude != null && Number.isFinite(anchorLongitude)) longitude += Math.round((anchorLongitude - longitude) / 360) * 360;
+    latitude = Math.max(-PROJECTION_CONSTANTS.maxMercatorLatitude, Math.min(PROJECTION_CONSTANTS.maxMercatorLatitude, latitude));
+    return [PROJECTION_CONSTANTS.mercatorRadius * longitude * Math.PI / 180,
+        PROJECTION_CONSTANTS.mercatorRadius * Math.log(Math.tan(Math.PI / 4 + latitude * Math.PI / 360)), altitude];
+}
+
+/** Rotate an ENU direction into globe axes without camera transforms or changing its length. */
+export function projectGeographicVector(position: GeographicProjectionPosition, direction: readonly [number, number, number], projection: HostProjection['type']): [number, number, number] {
+    if (projection === 'projected') throw new Error('CPU-projected basemaps do not support geographic lighting');
+    const [east, north, up] = direction;
+    if (projection === 'web-mercator') return [east, north, up];
+    const longitude = position[0] * Math.PI / 180, latitude = position[1] * Math.PI / 180;
+    return [east * Math.cos(longitude) - north * Math.sin(longitude) * Math.sin(latitude) + up * Math.sin(longitude) * Math.cos(latitude),
+        east * Math.sin(longitude) + north * Math.cos(longitude) * Math.sin(latitude) - up * Math.cos(longitude) * Math.cos(latitude),
+        north * Math.cos(latitude) + up * Math.sin(latitude)];
+}
+
+/** Invert globe common coordinates for spatial picking, rejecting the undefined sphere center. */
+export function unprojectGlobePosition(position: readonly [number, number, number]): [number, number, number] {
+    const radius = Math.hypot(...position);
+    if (!position.every(Number.isFinite) || radius === 0) throw new Error('Globe position must be finite and non-zero');
+    return [Math.atan2(position[0], -position[1]) * 180 / Math.PI,
+        Math.asin(Math.max(-1, Math.min(1, position[2] / radius))) * 180 / Math.PI,
+        (radius / PROJECTION_CONSTANTS.globeRadius - 1) * PROJECTION_CONSTANTS.earthRadius];
+}
+
+/** Style pixels in the zoom-zero Mercator convention, not perspective screen-pixel error. */
+export function getMercatorMetersPerPixel(zoom: number): number {
+    return 2 * Math.PI * PROJECTION_CONSTANTS.mercatorRadius / PROJECTION_CONSTANTS.tileSize / Math.pow(2, zoom);
+}
+
+/** Surface differential per EPSG:3857 meter for projected LOD; elevation is intentionally zero. */
+export function getProjectionSurface(x: number, y: number, projection: HostProjection['type']): {
+    /** Common-space ground position. */
+    position: number[];
+    /** Change in position per eastward Mercator meter. */
+    derivativeX: number[];
+    /** Change in position per northward Mercator meter. */
+    derivativeY: number[];
+} {
+    if (projection === 'projected') throw new Error('CPU-projected basemaps require explicit LOD');
+    if (projection === 'web-mercator') return {position: [x, y, 0], derivativeX: [1, 0, 0], derivativeY: [0, 1, 0]};
+    const longitude = x / PROJECTION_CONSTANTS.mercatorRadius;
+    const latitude = Math.atan(Math.sinh(y / PROJECTION_CONSTANTS.mercatorRadius));
+    const cosine = Math.cos(latitude), sine = Math.sin(latitude);
+    const sineLongitude = Math.sin(longitude), cosineLongitude = Math.cos(longitude);
+    const radius = PROJECTION_CONSTANTS.globeRadius, derivativeScale = radius / PROJECTION_CONSTANTS.mercatorRadius;
+    return {position: [radius * sineLongitude * cosine, -radius * cosineLongitude * cosine, radius * sine],
+        derivativeX: [derivativeScale * cosineLongitude * cosine, derivativeScale * sineLongitude * cosine, 0],
+        derivativeY: [-derivativeScale * sineLongitude * sine * cosine,
+            derivativeScale * cosineLongitude * sine * cosine, derivativeScale * cosine ** 2]};
+}
+
+/** Invert finite absolute Mercator meters without wrapping longitude or discarding altitude. */
+function unprojectMercatorPosition(position: readonly [number, number, number]): [number, number, number] {
+    if (!position.every(Number.isFinite)) throw new Error('Mercator position must be finite');
+    const [longitude, latitude] = unprojectMetersToLngLatLegacy([position[0], position[1]]);
+    return [longitude, latitude, position[2]];
+}
+
+/** Immutable procedures delegate to existing formulas; no runtime math.gl candidate switch. */
+const PROJECTION_PROCEDURES: Readonly<Record<'web-mercator' | 'globe', GeographicProjectionProcedure>> = Object.freeze({
+    'web-mercator': Object.freeze({
+        type: 'web-mercator',
+        positionUnits: 'meters',
+        latitudeLimit: PROJECTION_CONSTANTS.maxMercatorLatitude,
+        longitudePolicy: 'nearest-anchor-or-unwrapped',
+        project: (position: GeographicProjectionPosition, anchorLongitude?: number) => projectGeographicPosition(position, 'web-mercator', anchorLongitude),
+        unproject: unprojectMercatorPosition,
+        projectVector: (position: GeographicProjectionPosition, direction: readonly [number, number, number]) => projectGeographicVector(position, direction, 'web-mercator')
+    }),
+    globe: Object.freeze({
+        type: 'globe',
+        positionUnits: 'globe-common-units',
+        latitudeLimit: 90,
+        longitudePolicy: 'periodic',
+        project: (position: GeographicProjectionPosition) => projectGeographicPosition(position, 'globe'),
+        unproject: unprojectGlobePosition,
+        projectVector: (position: GeographicProjectionPosition, direction: readonly [number, number, number]) => projectGeographicVector(position, direction, 'globe')
+    })
+});
+
+/** Select the existing renderer's CPU procedure and conventions for a supported HostFrame projection. */
+export function getGeographicProjectionProcedure(projection: HostProjection['type']): GeographicProjectionProcedure {
+    if (projection !== 'web-mercator' && projection !== 'globe') {
+        throw new Error('Unsupported geographic projection; expected web-mercator or globe');
+    }
+    return PROJECTION_PROCEDURES[projection];
+}