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

package/dist/experimental/projected-basemaps.js

@@ -0,0 +1,1310 @@
+// src/experimental/projected-basemaps.ts
+import { Layer } from "@deck.gl/core";
+import { Matrix4 as Matrix42 } from "@math.gl/core";
+import { HostFrame, Renderer, normalizeProjectedBasemapOptions as normalizeProjectedBasemapOptions2, countProjectedTileCoordinates as countProjectedTileCoordinates3, getProjectedRoadUnit, validateProjectedLights } from "@tangram.gl/tangram-renderer/core";
+
+// src/web_mercator_view_adapter.ts
+import { PROJECTION_CONSTANTS } from "@tangram.gl/tangram-renderer/core";
+var DECK_TO_TANGRAM_ZOOM_OFFSET = 1;
+var DECK_WORLD_SIZE = 512;
+var TANGRAM_HALF_WORLD_METERS = Math.PI * PROJECTION_CONSTANTS.mercatorRadius;
+var WebMercatorViewAdapter = class _WebMercatorViewAdapter {
+  /**
+   * Checks that a deck viewport provides the public Web Mercator contract used
+   * by TangramLayer.
+   * @param viewport deck.gl viewport.
+   * @returns Validation error, or null when supported.
+   */
+  static validateViewport(viewport) {
+    if (viewport?.isGeospatial === false) {
+      return new Error("a Web Mercator viewport is required");
+    }
+    if (_WebMercatorViewAdapter.validateGeographicAnchor(viewport, "Web Mercator viewport")) {
+      return new Error("a Web Mercator viewport is required");
+    }
+    return null;
+  }
+  /**
+   * Validates the geographic anchor shared by all deck.gl view adapters.
+   * @param viewport deck.gl viewport.
+   * @param viewportName View name used in the error message.
+   * @returns Validation error, or null when the anchor is finite.
+   */
+  static validateGeographicAnchor(viewport, viewportName = "viewport") {
+    if (!Number.isFinite(viewport?.longitude) || !Number.isFinite(viewport?.latitude) || !Number.isFinite(viewport?.zoom)) {
+      return new Error(`${viewportName} requires finite longitude, latitude, and zoom`);
+    }
+    return null;
+  }
+  /**
+   * Converts deck.gl camera matrices to Tangram camera matrices.
+   *
+   * Tangram tile models use absolute EPSG:3857 meters while deck matrices
+   * consume zoom-zero common coordinates. Altitude uses deck's
+   * latitude-dependent distance scale.
+   * @param viewport deck.gl WebMercatorViewport.
+   * @returns Tangram camera matrices and eye position.
+   */
+  static getCameraFrame(viewport) {
+    const distanceScales = typeof viewport.getDistanceScales === "function" ? viewport.getDistanceScales() : viewport.distanceScales;
+    const unitsPerMeter = distanceScales && distanceScales.unitsPerMeter;
+    const viewMatrix = viewport.viewMatrix;
+    const projectionMatrix = viewport.projectionMatrix;
+    if (!viewMatrix || viewMatrix.length !== 16 || !projectionMatrix || projectionMatrix.length !== 16 || !unitsPerMeter || !Number.isFinite(unitsPerMeter[2])) {
+      throw new Error("deck viewport camera matrices and distance scales are required");
+    }
+    const xyScale = DECK_WORLD_SIZE / (TANGRAM_HALF_WORLD_METERS * 2);
+    const metersToCommon = new Float64Array(16);
+    metersToCommon[0] = xyScale;
+    metersToCommon[5] = xyScale;
+    metersToCommon[10] = unitsPerMeter[2];
+    metersToCommon[12] = DECK_WORLD_SIZE / 2;
+    metersToCommon[13] = DECK_WORLD_SIZE / 2;
+    metersToCommon[15] = 1;
+    return {
+      view: multiplyMatrices(viewMatrix, metersToCommon),
+      projection: new Float32Array(projectionMatrix),
+      // The view matrix places the camera at the origin in eye coordinates.
+      position: [0, 0, 0]
+    };
+  }
+  /**
+   * Builds Tangram's external-camera frame for a deck.gl MapView.
+   * @param viewport deck.gl WebMercatorViewport.
+   * @param dimensions Render-target size.
+   * @returns Tangram HostFrame legacy shape.
+   */
+  static getFrame(viewport, { width, height }) {
+    const longitude = viewport.longitude;
+    const latitude = viewport.latitude;
+    const zoom = viewport.zoom;
+    if (typeof longitude !== "number" || !Number.isFinite(longitude) || typeof latitude !== "number" || !Number.isFinite(latitude) || typeof zoom !== "number" || !Number.isFinite(zoom)) {
+      throw new Error("a Web Mercator viewport is required");
+    }
+    const pitch = Math.abs(viewport.pitch || 0) * Math.PI / 180;
+    return {
+      viewport: { width, height },
+      view: {
+        longitude,
+        latitude,
+        zoom: zoom + DECK_TO_TANGRAM_ZOOM_OFFSET
+      },
+      projection: { type: "web-mercator" },
+      camera: _WebMercatorViewAdapter.getCameraFrame(viewport),
+      tileBuffer: Math.min(4, Math.ceil(Math.tan(pitch) * (viewport.height || height) / 256))
+    };
+  }
+};
+function multiplyMatrices(left, right) {
+  const result = new Float64Array(16);
+  for (let column = 0; column < 4; column++) {
+    for (let row = 0; row < 4; row++) {
+      let value = 0;
+      for (let index = 0; index < 4; index++) {
+        value += left[index * 4 + row] * right[column * 4 + index];
+      }
+      result[column * 4 + row] = value;
+    }
+  }
+  return result;
+}
+
+// src/first_person_view_adapter.ts
+import { Matrix4 } from "@math.gl/core";
+import { calculatePlanarVolumeBounds } from "@tangram.gl/tangram-renderer/core";
+var DECK_WORLD_SIZE2 = 512;
+var HALF_WORLD_METERS = 20037508342789244e-9;
+var TILE_SIZE = 256;
+var MAX_MERCATOR_LATITUDE = 85.05112878;
+var DEFAULT_GROUND_EXTENT = 2e4;
+var FirstPersonViewAdapter = class {
+  /** Converts the finite frustum/ground intersection without changing camera matrices. */
+  static getFrame = getFrame;
+};
+function getFrame(viewport, options = {}) {
+  return getFirstPersonFrameForCamera(viewport, WebMercatorViewAdapter.getCameraFrame(viewport), options);
+}
+function getFirstPersonFrameForCamera(viewport, camera, options = {}) {
+  const width = options.width ?? viewport.width;
+  const height = options.height ?? viewport.height;
+  const maxGroundExtent = options.maxGroundExtent ?? DEFAULT_GROUND_EXTENT;
+  if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+    throw new Error("FirstPersonViewport requires positive width and height");
+  }
+  if (!Number.isFinite(maxGroundExtent) || maxGroundExtent <= 0) {
+    throw new Error("FirstPersonViewport maxGroundExtent must be finite and positive");
+  }
+  const { longitude, latitude } = viewport;
+  const unprojectFlat = viewport.unprojectFlat;
+  if (typeof longitude !== "number" || !Number.isFinite(longitude) || typeof latitude !== "number" || !Number.isFinite(latitude) || typeof unprojectFlat !== "function") {
+    throw new Error("FirstPersonViewport geographic center and ground projection method are required");
+  }
+  const inverseView = new Matrix4().copy(camera.view);
+  if (!Number.isFinite(inverseView.determinant()) || inverseView.determinant() === 0) {
+    throw new Error("FirstPersonViewport camera is singular");
+  }
+  const eye = inverseView.invert().transformAsPoint([0, 0, 0]);
+  if (!eye.every(Number.isFinite)) throw new Error("FirstPersonViewport eye position is invalid");
+  const latitudeScale = Math.cos(Math.max(
+    -MAX_MERCATOR_LATITUDE,
+    Math.min(MAX_MERCATOR_LATITUDE, latitude)
+  ) * Math.PI / 180);
+  const extent = maxGroundExtent / latitudeScale;
+  const bounds = calculatePlanarVolumeBounds(camera, options.elevationRange ?? [0, 0], {
+    sw: { x: eye[0] - extent, y: eye[1] - extent },
+    ne: { x: eye[0] + extent, y: eye[1] + extent }
+  });
+  const xyScale = DECK_WORLD_SIZE2 / (HALF_WORLD_METERS * 2);
+  const toGeographic = (x, y) => unprojectFlat.call(viewport, [
+    x * xyScale + DECK_WORLD_SIZE2 / 2,
+    y * xyScale + DECK_WORLD_SIZE2 / 2
+  ]);
+  const center = bounds ? toGeographic(
+    (bounds.sw.x + bounds.ne.x) / 2,
+    (bounds.sw.y + bounds.ne.y) / 2
+  ) : [longitude, latitude];
+  const metersPerPixel = bounds ? Math.max(
+    (bounds.ne.x - bounds.sw.x) / width,
+    (bounds.ne.y - bounds.sw.y) / height
+  ) : extent * 2 / Math.min(width, height);
+  let visibleBounds = null;
+  if (bounds) {
+    const southwest = toGeographic(bounds.sw.x, bounds.sw.y);
+    const northeast = toGeographic(bounds.ne.x, bounds.ne.y);
+    visibleBounds = [southwest[0], southwest[1], northeast[0], northeast[1]];
+  }
+  if (!center.every(Number.isFinite) || !Number.isFinite(metersPerPixel) || metersPerPixel <= 0 || visibleBounds && !visibleBounds.every(Number.isFinite)) {
+    throw new Error("FirstPersonViewport ground footprint is invalid");
+  }
+  return {
+    viewport: { width, height },
+    view: {
+      longitude: center[0],
+      latitude: center[1],
+      altitude: eye[2],
+      zoom: Math.max(0, Math.log2(HALF_WORLD_METERS * 2 / (TILE_SIZE * metersPerPixel)))
+    },
+    projection: { type: "web-mercator", visibleBounds },
+    camera,
+    tileBuffer: 1
+  };
+}
+
+// src/globe_view_adapter.ts
+var DECK_TO_TANGRAM_ZOOM_OFFSET2 = 1;
+var GlobeViewAdapter = class {
+  /** Converts globe common-space matrices and visible geographic bounds. */
+  static getFrame = getFrame2;
+};
+function getFrame2(viewport, options = {}) {
+  if (options.maxElevation !== void 0 && (!Number.isFinite(options.maxElevation) || options.maxElevation < 0)) {
+    throw new Error("GlobeView maxElevation must be a finite non-negative number");
+  }
+  if (!viewport || !Number.isFinite(viewport.width) || !Number.isFinite(viewport.height) || !viewport.viewMatrix || viewport.viewMatrix.length !== 16 || !viewport.projectionMatrix || viewport.projectionMatrix.length !== 16 || !viewport.cameraPosition || viewport.cameraPosition.length !== 3 || !Array.from(viewport.cameraPosition).every(Number.isFinite) || typeof viewport.getBounds !== "function") {
+    throw new Error("deck GlobeViewport matrices, camera position, size, and visible bounds are required");
+  }
+  const visibleBounds = options.visibleBounds ?? viewport.getBounds({ z: 0 });
+  if (!Array.isArray(visibleBounds) || visibleBounds.length !== 4 || visibleBounds.some((value) => !Number.isFinite(value))) {
+    throw new Error("deck GlobeViewport must provide finite geographic bounds");
+  }
+  return {
+    viewport: { width: viewport.width, height: viewport.height },
+    view: {
+      longitude: viewport.longitude,
+      latitude: viewport.latitude,
+      zoom: Math.max(0, viewport.zoom + DECK_TO_TANGRAM_ZOOM_OFFSET2)
+    },
+    projection: {
+      type: "globe",
+      visibleBounds: [visibleBounds[0], visibleBounds[1], visibleBounds[2], visibleBounds[3]],
+      ...options.maxElevation === void 0 ? {} : { maxElevation: options.maxElevation }
+    },
+    camera: {
+      view: new Float64Array(viewport.viewMatrix),
+      projection: new Float32Array(
+        multiplyMatrices2(viewport.projectionMatrix, viewport.viewMatrix)
+      ),
+      position: [viewport.cameraPosition[0], viewport.cameraPosition[1], viewport.cameraPosition[2]]
+    },
+    tileBuffer: 0,
+    globePreloadZoom: options.preloadZoom
+  };
+}
+function multiplyMatrices2(left, right) {
+  const result = new Float64Array(16);
+  for (let column = 0; column < 4; column++) {
+    for (let row = 0; row < 4; row++) {
+      let value = 0;
+      for (let index = 0; index < 4; index++) {
+        value += left[index * 4 + row] * right[column * 4 + index];
+      }
+      result[column * 4 + row] = value;
+    }
+  }
+  return result;
+}
+
+// src/tangram-layer.ts
+var VIEW_EPSILON = 1e-7;
+function injectNextzenApiKey(config, apiKey) {
+  if (!apiKey || !config || !config.sources) {
+    return false;
+  }
+  let updated = false;
+  for (const source of Object.values(config.sources)) {
+    if (source && typeof source.url === "string" && source.url.includes("nextzen.org")) {
+      source.url_params = source.url_params || {};
+      source.url_params.api_key = apiKey;
+      updated = true;
+    }
+  }
+  return updated;
+}
+function getFirstPersonViewFrame(viewport, options = {}) {
+  return FirstPersonViewAdapter.getFrame(viewport, options);
+}
+function getGlobeViewFrame(viewport, options = {}) {
+  return GlobeViewAdapter.getFrame(viewport, options);
+}
+function createTangramLayerClass({ Layer: Layer2, ClassicWebGLRenderer, Renderer: Renderer2 }, viewAdapter) {
+  const rendererClass = ClassicWebGLRenderer || Renderer2;
+  if (!Layer2 || !rendererClass) {
+    throw new Error("createTangramLayerClass requires Layer and ClassicWebGLRenderer");
+  }
+  class TangramLayer extends Layer2 {
+    /** Forward deck.gl's property objects without changing its constructor semantics. */
+    constructor(...properties) {
+      super(...properties);
+    }
+    initializeState(_context) {
+      this.setState({ tangramRecord: null });
+    }
+    updateState({ props }) {
+      let record = this.state.tangramRecord;
+      const shouldCreateScene = !record || record.sceneSource !== props.scene || record.sceneBasePath !== props.sceneBasePath || record.apiKey !== props.apiKey || record.projectionEngine !== (props.projectionEngine ?? void 0) || record.projectionEngineExecution !== (props.projectionEngineExecution ?? void 0) || Boolean(record.terrain) !== Boolean(props.terrain) || record.terrainResourceBudget !== (props.terrainResourceBudget ?? void 0) || record.maxConcurrentTileLoadsPerWorker !== (props.maxConcurrentTileLoadsPerWorker ?? void 0);
+      if (shouldCreateScene) {
+        this._disposeTangramRecord(record);
+        record = this._createTangramRecord(props);
+        this.setState({ tangramRecord: record });
+      }
+      if (record) {
+        record.owner = this;
+        if (record.terrain !== props.terrain) {
+          record.terrain = props.terrain;
+          const terrain = props.terrain;
+          const revision = record.terrainRevision = (record.terrainRevision || 0) + 1;
+          record.terrainPendingRevision = revision;
+          Promise.resolve(record.loadPromise).then(async () => {
+            try {
+              if (!record.disposed && revision === record.terrainRevision && terrain) {
+                await record.renderer.setTerrain(terrain);
+                if (!record.disposed && revision === record.terrainRevision) {
+                  record.terrainPendingRevision = 0;
+                  record.renderer.setTerrainExaggeration(record.owner.props.terrainExaggeration ?? 1);
+                }
+              }
+            } finally {
+              if (record.terrainPendingRevision === revision) record.terrainPendingRevision = 0;
+            }
+          }).catch((error) => {
+            if (!record.disposed && revision === record.terrainRevision) this._raiseBridgeError(normalizeError(error));
+          });
+        }
+        if (props.terrain && !record.terrainPendingRevision) {
+          try {
+            record.renderer.setTerrainExaggeration(props.terrainExaggeration ?? 1);
+          } catch (error) {
+            this._raiseBridgeError(normalizeError(error));
+          }
+        }
+      }
+    }
+    draw({ renderPass } = {}) {
+      const record = this.state.tangramRecord;
+      if (!record || record.disposed) {
+        return;
+      }
+      record.owner = this;
+      this._synchronizeTangramScene(record);
+      if (!this._canRender(record, this.props)) {
+        return;
+      }
+      const renderTangram = () => {
+        const update_options = { force: true };
+        renderPass = renderPass || this.context.renderPass;
+        if (renderPass) {
+          update_options.renderPass = renderPass;
+        }
+        const rendered = record.renderer.render(update_options);
+        if (record.scene.config && record.scene.config.scene && record.scene.config.scene.animated === true) {
+          this.setNeedsRedraw();
+        }
+        if (rendered && record.gl) {
+          record.gl.depthMask(true);
+          record.gl.clear(record.gl.DEPTH_BUFFER_BIT | record.gl.STENCIL_BUFFER_BIT);
+        }
+      };
+      if (record.device.type === "webgl") {
+        record.scene.withWebGLContext(renderTangram);
+      } else {
+        renderTangram();
+      }
+    }
+    finalizeState(_context) {
+      this._disposeTangramRecord(this.state && this.state.tangramRecord);
+    }
+    /** Asynchronously query a view-local or canvas CSS pixel; the host must keep drawing. */
+    getFeatureAt(pixel, options = {}) {
+      const record = this.state.tangramRecord;
+      if (!record || record.disposed || record.loadFailed) return Promise.resolve(void 0);
+      const pending = record.renderer.getFeatureAt(pixel, options);
+      record.owner.setNeedsRedraw();
+      return pending;
+    }
+    /** Intersect the actual rendered eye with a host-owned terrain mesh in content coordinates. */
+    getTerrainAt(pixel, surface, options = {}) {
+      const record = this.state && this.state.tangramRecord;
+      if (!record || record.disposed || record.loadFailed || !record.loaded) return null;
+      return record.renderer.getTerrainAt(pixel, surface, options);
+    }
+    /** Exact admitted ground triangles at the last frame, including temporal relief and globe projection. */
+    getDrapedTerrainSurface() {
+      const record = this.state?.tangramRecord;
+      return record && !record.disposed && record.loaded && !record.loadFailed ? record.renderer.getDrapedTerrainSurface() : null;
+    }
+    /** Resident worker preparation costs; GPU, source and scratch allocations are separate. */
+    getTerrainDrapingStatistics() {
+      const record = this.state?.tangramRecord;
+      return record && !record.disposed ? record.renderer.getTerrainDrapingStatistics() : void 0;
+    }
+    get isLoaded() {
+      const record = this.state && this.state.tangramRecord;
+      return Boolean(record && record.loaded && !record.loadFailed && !record.disposed);
+    }
+    _createTangramRecord(props) {
+      if (!props.scene) {
+        this._raiseBridgeError(new Error("scene is required"));
+        return null;
+      }
+      const deckCanvas = this.context.deck && this.context.deck.getCanvas();
+      const device = this.context.device;
+      if (!deckCanvas) {
+        this._raiseBridgeError(new Error("deck canvas is required"));
+        return null;
+      }
+      if (!device || device.type !== "webgl" && device.type !== "webgpu" || typeof device.createBuffer !== "function" || typeof device.createShader !== "function" || typeof device.createTexture !== "function" || typeof device.createRenderPipeline !== "function" || typeof device.createVertexArray !== "function") {
+        this._raiseBridgeError(new Error("a deck.gl luma.gl Device is required"));
+        return null;
+      }
+      let gl = null;
+      if (device.type === "webgl") {
+        gl = device.handle;
+        if (!gl || typeof device.pushState !== "function" || typeof device.popState !== "function") {
+          this._raiseBridgeError(new Error("a deck.gl WebGLDevice is required"));
+          return null;
+        }
+        if (gl.canvas !== deckCanvas) {
+          this._raiseBridgeError(
+            new Error("deck canvas and WebGLDevice handle must share a context")
+          );
+          return null;
+        }
+      }
+      const record = {
+        owner: this,
+        renderer: null,
+        scene: null,
+        device,
+        gl,
+        deckCanvas,
+        sceneSource: props.scene,
+        sceneBasePath: props.sceneBasePath,
+        apiKey: props.apiKey,
+        projectionEngine: props.projectionEngine ?? void 0,
+        terrain: props.terrain,
+        terrainResourceBudget: props.terrainResourceBudget ?? void 0,
+        terrainPendingRevision: 0,
+        projectionEngineExecution: props.projectionEngineExecution ?? void 0,
+        maxConcurrentTileLoadsPerWorker: props.maxConcurrentTileLoadsPerWorker ?? void 0,
+        canvasWidth: null,
+        canvasHeight: null,
+        disposed: false,
+        destroyed: false,
+        loadSettled: false,
+        loadFailed: false,
+        loaded: false,
+        lastSceneError: null,
+        lastViewportError: null,
+        reportedViewportError: null,
+        loadPromise: null,
+        webglScopeDepth: 0
+      };
+      let renderer;
+      try {
+        const renderer_options = {
+          device,
+          canvas: deckCanvas,
+          projectionEngine: record.projectionEngine,
+          terrain: record.terrain,
+          terrainResourceBudget: record.terrainResourceBudget,
+          projectionEngineExecution: record.projectionEngineExecution,
+          maxConcurrentTileLoadsPerWorker: record.maxConcurrentTileLoadsPerWorker,
+          requestRedraw: () => {
+            if (!record.disposed && record.owner.setNeedsRedraw) {
+              record.owner.setNeedsRedraw();
+            }
+          },
+          continuousZoom: true,
+          highDensityDisplay: true,
+          logLevel: "warn"
+        };
+        if (gl) {
+          renderer_options.webGLContext = gl;
+          renderer_options.webGLContextScope = (callback) => this._withDeviceState(record, callback);
+        }
+        renderer = rendererClass.create(props.scene, renderer_options);
+      } catch (error) {
+        this._raiseBridgeError(normalizeError(error));
+        return null;
+      }
+      record.renderer = renderer;
+      record.scene = renderer.scene;
+      const liveRecord = record;
+      renderer.subscribe({
+        load: (message) => {
+          injectNextzenApiKey(message.config, record.apiKey);
+        },
+        update: () => this._updateAttributions(liveRecord),
+        error: (message) => this._reportSceneError(liveRecord, normalizeError(message), message.type !== "scene_import")
+      });
+      this._synchronizeTangramScene(liveRecord);
+      record.loadPromise = Promise.resolve().then(() => {
+        if (record.disposed) {
+          return null;
+        }
+        return renderer.load(props.scene, {
+          // Creation already rejected missing scene input; this closure preserves that identity.
+          base_path: props.sceneBasePath,
+          blocking: false
+        });
+      }).then((result) => {
+        if (!record.disposed) {
+          record.loaded = true;
+          record.owner.setNeedsRedraw && record.owner.setNeedsRedraw();
+          record.owner.props.onSceneLoad(liveRecord.scene);
+          this._updateAttributions(liveRecord);
+        }
+        return result;
+      }).catch((error) => {
+        if (!record.disposed) {
+          record.loadFailed = true;
+          this._reportSceneError(liveRecord, normalizeError(error));
+        }
+      }).finally(() => {
+        record.loadSettled = true;
+        if (record.disposed) {
+          this._destroyTangramRecord(liveRecord);
+        }
+      });
+      return liveRecord;
+    }
+    /** Refresh credits after source recreation; ignore stale metadata and disposed layers. */
+    _updateAttributions(record) {
+      if (record.disposed || typeof record.renderer.getAttributions !== "function") return;
+      const generation = record.attributionGeneration = (record.attributionGeneration || 0) + 1;
+      Promise.resolve().then(() => record.disposed ? void 0 : record.renderer.getAttributions()).then((credits) => {
+        if (credits && !record.disposed && generation === record.attributionGeneration) {
+          record.owner.props.onAttributionChange?.(credits, record.scene);
+        }
+      }).catch((error) => {
+        if (!record.disposed && generation === record.attributionGeneration) {
+          this._reportSceneError(record, normalizeError(error), false);
+        }
+      });
+    }
+    _synchronizeTangramScene(record) {
+      const viewport = this.context.viewport;
+      const viewports = this.context.deck.getViewports ? this.context.deck.getViewports() : [viewport];
+      if (viewAdapter) {
+        try {
+          if (viewports.length !== 1) throw new Error("only one deck.gl viewport is supported");
+          const width2 = record.deckCanvas.clientWidth || viewport.width;
+          const height2 = record.deckCanvas.clientHeight || viewport.height;
+          const frame2 = viewAdapter.getFrame(viewport, this.props, { width: width2, height: height2 });
+          record.renderer.setFrame({ ...frame2, tileResources: this.props.tileResources ?? void 0 });
+          record.lastViewportError = null;
+          record.reportedViewportError = null;
+        } catch (error) {
+          record.lastViewportError = error.message;
+          this._raiseViewportError(record, normalizeError(error));
+        }
+        return;
+      }
+      const globeOptions = {
+        maxElevation: this.props.globeMaxElevation ?? void 0,
+        visibleBounds: this.props.globeVisibleBounds ?? void 0,
+        preloadZoom: this.props.globePreloadZoom ?? void 0
+      };
+      const firstPersonOptions = {
+        maxGroundExtent: this.props.firstPersonMaxGroundExtent ?? void 0,
+        elevationRange: this.props.firstPersonElevationRange ?? void 0
+      };
+      const viewportError = validateViewport(viewport, viewports, globeOptions, firstPersonOptions);
+      if (viewportError) {
+        record.lastViewportError = viewportError.message;
+        this._raiseViewportError(record, viewportError);
+        return;
+      }
+      record.lastViewportError = null;
+      record.reportedViewportError = null;
+      const width = record.deckCanvas.clientWidth || viewport.width;
+      const height = record.deckCanvas.clientHeight || viewport.height;
+      record.canvasWidth = width;
+      record.canvasHeight = height;
+      const frame = isGlobeViewport(viewport) ? { ...getGlobeViewFrame(viewport, globeOptions), viewport: { width, height } } : isFirstPersonViewport(viewport) ? getFirstPersonViewFrame(viewport, { width, height, ...firstPersonOptions }) : getMapViewFrame(viewport, { width, height });
+      record.renderer.setFrame({ ...frame, tileResources: this.props.tileResources ?? void 0 });
+    }
+    _canRender(record, props) {
+      return props.visible !== false && props.opacity !== 0 && record.loaded && !record.loadFailed && !record.lastViewportError;
+    }
+    _raiseViewportError(record, error) {
+      if (record.reportedViewportError === error.message) {
+        return;
+      }
+      record.reportedViewportError = error.message;
+      this._raiseBridgeError(error);
+    }
+    _reportSceneError(record, error, isFatal = true) {
+      if (record.disposed || record.lastSceneError === error.message) {
+        return;
+      }
+      record.lastSceneError = error.message;
+      if (isFatal) {
+        record.loadFailed = true;
+      }
+      record.owner.props.onSceneError(error, record.scene);
+      record.owner.raiseError(error, "TangramLayer scene");
+    }
+    _raiseBridgeError(error) {
+      this.raiseError(error, "TangramLayer bridge");
+    }
+    _disposeTangramRecord(record) {
+      if (!record || record.disposed) {
+        return;
+      }
+      record.disposed = true;
+      if (!record.loadPromise || record.loadSettled) {
+        this._destroyTangramRecord(record);
+      }
+    }
+    _destroyTangramRecord(record) {
+      if (!record.destroyed) {
+        record.destroyed = true;
+        record.renderer.destroy();
+      }
+    }
+    _withDeviceState(record, callback) {
+      if (record.webglScopeDepth > 0) {
+        return callback();
+      }
+      const { device, gl } = record;
+      const lumaState = gl.lumaState;
+      const hasTrackedProgram = Boolean(lumaState && "program" in lumaState);
+      const previousProgram = hasTrackedProgram ? lumaState.program : gl.getParameter(gl.CURRENT_PROGRAM);
+      record.webglScopeDepth++;
+      device.pushState();
+      try {
+        return callback();
+      } finally {
+        try {
+          device.popState();
+          gl.useProgram(previousProgram);
+        } finally {
+          record.webglScopeDepth--;
+        }
+      }
+    }
+  }
+  TangramLayer.layerName = "TangramLayer";
+  TangramLayer.defaultProps = {
+    projectionEngine: null,
+    projectionEngineExecution: null,
+    scene: null,
+    sceneBasePath: null,
+    apiKey: null,
+    globeMaxElevation: null,
+    globeVisibleBounds: null,
+    globePreloadZoom: null,
+    tileResources: null,
+    maxConcurrentTileLoadsPerWorker: null,
+    firstPersonMaxGroundExtent: 2e4,
+    terrain: { type: "object", value: null, compare: false },
+    terrainResourceBudget: { type: "object", value: null, compare: false },
+    terrainExaggeration: { type: "number", value: 1, min: 0, max: 1e3 },
+    firstPersonElevationRange: { type: "array", value: [0, 0], compare: true },
+    onSceneLoad: () => {
+    },
+    onAttributionChange: () => {
+    },
+    onSceneError: () => {
+    }
+  };
+  return TangramLayer;
+}
+function validateViewport(viewport, viewports, globeOptions = {}, firstPersonOptions = {}) {
+  if (viewports.length !== 1) {
+    return new Error("only one deck.gl viewport is supported");
+  }
+  const globe = isGlobeViewport(viewport);
+  const firstPerson = isFirstPersonViewport(viewport);
+  const geographicAnchorError = WebMercatorViewAdapter.validateGeographicAnchor(
+    viewport,
+    globe ? "GlobeViewport" : "Web Mercator viewport"
+  );
+  if (geographicAnchorError) {
+    return globe ? geographicAnchorError : new Error("a Web Mercator viewport is required");
+  }
+  if (!globe) {
+    const webMercatorError = WebMercatorViewAdapter.validateViewport(viewport);
+    if (webMercatorError) {
+      return webMercatorError;
+    }
+  }
+  if (!Number.isFinite(viewport.bearing || 0) || !Number.isFinite(viewport.pitch || 0) || (viewport.pitch || 0) < (firstPerson ? -90 : -VIEW_EPSILON) || (firstPerson ? (viewport.pitch || 0) > 90 : (viewport.pitch || 0) >= 90)) {
+    return new Error("bearing and pitch must describe a finite deck.gl camera");
+  }
+  try {
+    if (globe) {
+      getGlobeViewFrame(viewport, globeOptions);
+    } else if (isFirstPersonViewport(viewport)) {
+      getFirstPersonViewFrame(viewport, firstPersonOptions);
+    } else {
+      WebMercatorViewAdapter.getCameraFrame(viewport);
+    }
+  } catch (error) {
+    return error;
+  }
+  return null;
+}
+function getMapViewFrame(viewport, { width, height }) {
+  return WebMercatorViewAdapter.getFrame(viewport, { width, height });
+}
+function isFirstPersonViewport(viewport) {
+  return Boolean(
+    viewport && viewport.constructor && viewport.constructor.displayName === "FirstPersonViewport"
+  );
+}
+function isGlobeViewport(viewport) {
+  return Boolean(
+    viewport && (viewport.constructor?.displayName === "GlobeViewport" || viewport.constructor?.name === "GlobeViewport")
+  );
+}
+function normalizeError(value) {
+  const fields = value;
+  if (value instanceof Error) {
+    return value;
+  }
+  if (value && fields.error instanceof Error) {
+    return fields.error;
+  }
+  if (value && fields.message) {
+    return new Error(fields.message);
+  }
+  return new Error(String(value));
+}
+var tangram_layer_default = createTangramLayerClass;
+
+// src/experimental/projected-navigation.ts
+import {
+  getProjectedCoordinateOptions,
+  PROJECTED_COMMON_SCALE,
+  countProjectedTileCoordinates,
+  normalizeProjectedBasemapOptions,
+  ProjectionBatchExecutor
+} from "@tangram.gl/tangram-renderer/core";
+function getProjectedGeographicBounds(type) {
+  normalizeProjectedBasemapOptions({ type });
+  return type === "albers" ? [-170, 5, -40, 75] : [-180, -85.0511287798066, 180, 85.0511287798066];
+}
+function validateProjectedNavigationViewport(viewport) {
+  if (viewport.isGeospatial !== false || viewport.constructor.displayName !== "OrthographicViewport" && viewport.constructor.name !== "OrthographicViewport" || ![viewport.width, viewport.height].every((value) => Number.isFinite(value) && value > 0)) {
+    throw new Error("Projected navigation requires a finite deck.gl OrthographicViewport");
+  }
+}
+function validateProjectedGeographicBounds(bounds, type) {
+  countProjectedTileCoordinates(bounds, 0);
+  const domain = getProjectedGeographicBounds(type);
+  if (bounds[0] < domain[0] || bounds[1] < domain[1] || bounds[2] > domain[2] || bounds[3] > domain[3]) {
+    throw new Error("Projected navigation bounds must remain within the projection domain");
+  }
+}
+var ProjectedBasemapNavigation = class {
+  /** Retain a factory without taking ownership of its registrations, grids or lifetime. */
+  constructor(engine, options = {}) {
+    this.engine = engine;
+    if (!engine || typeof engine.createProjection !== "function" || typeof engine.createProjectionAsync !== "function") {
+      throw new Error("Projected navigation requires a ProjectionEngine factory");
+    }
+    this.executor = new ProjectionBatchExecutor(options);
+  }
+  engine;
+  /** Independent compiled forward/reverse CRS pairs, including lazy factory initialization. */
+  transforms = /* @__PURE__ */ new Map();
+  /** Prevent late asynchronous work from publishing after example teardown. */
+  disposed = false;
+  /** Bounded host kernel calls shared by forward and reverse requests. */
+  executor;
+  /** Project a detached longitude/latitude batch into north-positive common coordinates. */
+  async projectPositions(coordinates, type, options = {}) {
+    const domain = getProjectedGeographicBounds(type);
+    if (!(coordinates instanceof Float64Array) || coordinates.length % 2 !== 0) {
+      throw new Error("Projected navigation requires finite geographic pairs inside the projection domain");
+    }
+    if (!coordinates.every((value, index) => Number.isFinite(value) && value >= domain[index % 2] && value <= domain[index % 2 + 2])) {
+      throw new Error("Projected navigation requires finite geographic pairs inside the projection domain");
+    }
+    return this.executor.execute(
+      coordinates,
+      () => this.getTransform(type, false),
+      { signal: options.signal, scale: PROJECTED_COMMON_SCALE }
+    );
+  }
+  /** Project a geographic focus point without mutating the supplied pair. */
+  async projectPosition(position, type, options = {}) {
+    if (position.length !== 2) throw new Error("Projected focus requires a longitude/latitude pair");
+    const result = await this.projectPositions(new Float64Array(position), type, options);
+    return [result[0], result[1], 0];
+  }
+  /** Invert ground; finite outside-domain/folded results return null. Engine errors propagate. */
+  async unprojectPosition(position, type, options = {}) {
+    if (position.length !== 2 || !position.every(Number.isFinite)) throw new Error("Projected inverse requires a finite common pair");
+    const point = [position[0], position[1]];
+    const requestOptions = { signal: options.signal };
+    const result = await this.executor.execute(
+      new Float64Array(point.map((value) => value / PROJECTED_COMMON_SCALE)),
+      () => this.getTransform(type, true),
+      { ...requestOptions, allowNonfinite: true }
+    );
+    const domain = getProjectedGeographicBounds(type);
+    if (!result.every((value, index) => Number.isFinite(value) && value >= domain[index] - 1e-7 && value <= domain[index + 2] + 1e-7)) return null;
+    const geographic = [
+      Math.max(domain[0], Math.min(domain[2], result[0])),
+      Math.max(domain[1], Math.min(domain[3], result[1]))
+    ];
+    const restored = await this.projectPosition(geographic, type, requestOptions);
+    if (Math.hypot(restored[0] - point[0], restored[1] - point[1]) <= 1e-5) return geographic;
+    if (domain[0] === -180 && domain[2] === 180 && Math.abs(Math.abs(geographic[0]) - 180) <= 1e-7) {
+      const opposite = [geographic[0] < 0 ? 180 : -180, geographic[1]];
+      const alternative = await this.projectPosition(opposite, type, requestOptions);
+      if (Math.hypot(alternative[0] - point[0], alternative[1] - point[1]) <= 1e-5) return opposite;
+    }
+    return null;
+  }
+  /** Probe geographic coordinates on ground, not a rendered feature or depth/picking buffer. */
+  async unprojectScreenPosition(viewport, pixel, type, options = {}) {
+    validateProjectedNavigationViewport(viewport);
+    if (pixel.length !== 2 || !pixel.every(Number.isFinite)) throw new Error("Projected probe requires a finite screen pair");
+    if (pixel[0] < 0 || pixel[1] < 0 || pixel[0] > viewport.width || pixel[1] > viewport.height) return null;
+    const position = viewport.unproject([...pixel], { targetZ: 0 });
+    return this.unprojectPosition([position[0], position[1]], type, options);
+  }
+  /** Bound the viewport's ground rectangle using the fixed projections' separable latitude and longitude scales.
+   * Equal Earth's longitude factor decreases with absolute latitude, so both latitude endpoints bound its envelope.
+   * Albers uses radial/angular interval bounds about the conic apex, not sparse inverse samples.
+   * This does not support wrapped worlds or arbitrary custom projection kernels.
+   */
+  async getCameraCoverage(viewport, type, sourceBounds = getProjectedGeographicBounds(type)) {
+    if (this.disposed) throw new Error("Projected navigation is disposed");
+    validateProjectedNavigationViewport(viewport);
+    validateProjectedGeographicBounds(sourceBounds, type);
+    const region = [...sourceBounds];
+    const corners = [[0, 0], [viewport.width, 0], [0, viewport.height], [viewport.width, viewport.height]].map((pixel) => viewport.unproject(pixel, { targetZ: 0 }));
+    if (!corners.every((point) => point.length >= 2 && point.slice(0, 2).every(Number.isFinite))) {
+      throw new Error("Projected coverage requires finite ground corners");
+    }
+    if (type === "albers") return this.getAlbersCoverage(corners, region);
+    const minimumX = Math.min(...corners.map((point) => point[0]));
+    const maximumX = Math.max(...corners.map((point) => point[0]));
+    const minimumY = Math.min(...corners.map((point) => point[1]));
+    const maximumY = Math.max(...corners.map((point) => point[1]));
+    const southernEdge = await this.projectPosition([0, region[1]], type);
+    const northernEdge = await this.projectPosition([0, region[3]], type);
+    if (maximumY < southernEdge[1] || minimumY > northernEdge[1]) return { bounds: null, domainFallback: false };
+    const south = await this.unprojectPosition([0, Math.max(minimumY, southernEdge[1])], type);
+    const north = await this.unprojectPosition([0, Math.min(maximumY, northernEdge[1])], type);
+    if (!south || !north) throw new Error("Projection engine could not invert the bounded latitude envelope");
+    const southernScale = (await this.projectPosition([180, south[1]], type))[0] / 180;
+    const northernScale = (await this.projectPosition([180, north[1]], type))[0] / 180;
+    if (![southernScale, northernScale].every((value) => Number.isFinite(value) && value > 0)) {
+      throw new Error("Projected coverage requires a positive longitude scale");
+    }
+    const scales = [southernScale, northernScale];
+    if (south[1] < 0 && north[1] > 0) scales.push((await this.projectPosition([180, 0], type))[0] / 180);
+    const west = Math.max(region[0], Math.min(...scales.map((scale) => minimumX / scale)));
+    const east = Math.min(region[2], Math.max(...scales.map((scale) => maximumX / scale)));
+    if (west > east) return { bounds: null, domainFallback: false };
+    const margin = 1e-7;
+    return { bounds: [
+      Math.max(region[0], west - margin),
+      Math.max(region[1], south[1] - margin),
+      Math.min(region[2], east + margin),
+      Math.min(region[3], north[1] + margin)
+    ], domainFallback: false };
+  }
+  /** Bound the fixed northern Albers cone: radius decreases with latitude, angle increases with longitude. */
+  async getAlbersCoverage(corners, region) {
+    const reference = await this.projectPositions(new Float64Array([-96, 5, -86, 5, -96, 75]), "albers");
+    const apex = (reference[2] ** 2 + reference[3] ** 2 - reference[1] ** 2) / (2 * (reference[3] - reference[1]));
+    const cone = (Math.sin(29.5 * Math.PI / 180) + Math.sin(45.5 * Math.PI / 180)) / 2;
+    if (!Number.isFinite(apex) || apex <= reference[5]) throw new Error("Projected coverage requires a northern Albers cone");
+    const south = await this.projectPosition([-96, region[1]], "albers");
+    const north = await this.projectPosition([-96, region[3]], "albers");
+    const minimumRadius = apex - north[1], maximumRadius = apex - south[1];
+    const firstAngle = (region[0] + 96) * Math.PI / 180 * cone;
+    const lastAngle = (region[2] + 96) * Math.PI / 180 * cone;
+    const angles = [firstAngle, lastAngle];
+    if (firstAngle <= 0 && lastAngle >= 0) angles.push(0);
+    const minimumCosine = Math.min(...angles.map(Math.cos));
+    const maximumCosine = Math.max(...angles.map(Math.cos));
+    const x = [Math.min(...corners.map((point) => point[0])), Math.max(...corners.map((point) => point[0]))];
+    const down = [
+      Math.max(minimumRadius * minimumCosine, apex - Math.max(...corners.map((point) => point[1]))),
+      Math.min(maximumRadius * maximumCosine, apex - Math.min(...corners.map((point) => point[1])))
+    ];
+    if (down[0] > down[1]) return { bounds: null, domainFallback: false };
+    const closestX = Math.max(x[0], Math.min(x[1], 0));
+    const nearRadius = Math.max(minimumRadius, Math.hypot(closestX, down[0]));
+    const farRadius = Math.min(maximumRadius, Math.max(...x.map((value) => Math.hypot(value, down[1]))));
+    const longitude = x.flatMap((value) => down.map((distance) => Math.atan2(value, distance) / cone * 180 / Math.PI - 96));
+    const west = Math.max(region[0], Math.min(...longitude)), east = Math.min(region[2], Math.max(...longitude));
+    if (nearRadius > farRadius || west > east) return { bounds: null, domainFallback: false };
+    const southern = await this.unprojectPosition([0, apex - farRadius], "albers");
+    const northern = await this.unprojectPosition([0, apex - nearRadius], "albers");
+    if (!southern || !northern) throw new Error("Projection engine could not invert the Albers radius envelope");
+    const margin = 1e-7;
+    return { bounds: [
+      Math.max(region[0], west - margin),
+      Math.max(region[1], southern[1] - margin),
+      Math.min(region[2], east + margin),
+      Math.min(region[3], northern[1] + margin)
+    ], domainFallback: false };
+  }
+  /** Preserve geographic focus and numeric zoom; clamp to a smaller destination domain, never mutate the input.
+   * A finite outside-domain target falls back to the destination domain center. Engine errors still propagate.
+   * Keeping zoom does not imply preserving local ground scale across differently distorted projections.
+   */
+  async reprojectViewState(state, from, to) {
+    if (state.target.length !== 3 || ![...state.target, state.zoom].every(Number.isFinite)) {
+      throw new Error("Projection transition requires a finite target and zoom");
+    }
+    const point = [state.target[0], state.target[1]];
+    const zoom = state.zoom;
+    const domain = getProjectedGeographicBounds(to);
+    const previous = await this.unprojectPosition(point, from);
+    const focus = previous ? [
+      Math.max(domain[0], Math.min(domain[2], previous[0])),
+      Math.max(domain[1], Math.min(domain[3], previous[1]))
+    ] : [(domain[0] + domain[2]) / 2, (domain[1] + domain[3]) / 2];
+    return {
+      viewState: { target: await this.projectPosition(focus, to), zoom },
+      focus,
+      clamped: Boolean(previous && (focus[0] !== previous[0] || focus[1] !== previous[1])),
+      domainFallback: previous === null
+    };
+  }
+  /** Fit a sampled geographic extent; this is navigation, not a conservative visibility proof. */
+  async fitBounds(bounds, dimensions, type, options = {}) {
+    validateProjectedGeographicBounds(bounds, type);
+    const { padding = 24, minZoom = -10, maxZoom = 10 } = options;
+    if (![dimensions.width, dimensions.height, padding, minZoom, maxZoom].every(Number.isFinite) || padding < 0 || dimensions.width <= 2 * padding || dimensions.height <= 2 * padding || minZoom > maxZoom) {
+      throw new Error("Projected fit requires usable CSS dimensions, padding and an ordered zoom range");
+    }
+    const coordinates = [];
+    for (let column = 0; column <= 32; column++) for (let row = 0; row <= 32; row++) {
+      coordinates.push(
+        bounds[0] + (bounds[2] - bounds[0]) * column / 32,
+        bounds[1] + (bounds[3] - bounds[1]) * row / 32
+      );
+    }
+    const positions = await this.projectPositions(new Float64Array(coordinates), type);
+    let west = Infinity, south = Infinity, east = -Infinity, north = -Infinity;
+    for (let index = 0; index < positions.length; index += 2) {
+      west = Math.min(west, positions[index]);
+      east = Math.max(east, positions[index]);
+      south = Math.min(south, positions[index + 1]);
+      north = Math.max(north, positions[index + 1]);
+    }
+    const zoom = Math.log2(Math.min(
+      (dimensions.width - 2 * padding) / Math.max(east - west, 1e-9),
+      (dimensions.height - 2 * padding) / Math.max(north - south, 1e-9)
+    ));
+    return { target: [(west + east) / 2, (south + north) / 2, 0], zoom: Math.max(minZoom, Math.min(maxZoom, zoom)) };
+  }
+  /** Release navigation-owned caches; leave the shared engine usable by the renderer. */
+  dispose() {
+    this.disposed = true;
+    this.executor.dispose();
+    this.transforms.clear();
+  }
+  /** Detached host execution work, independent of decoded/GPU cache residency. */
+  getExecutionStatistics() {
+    return this.executor.getStatistics();
+  }
+  /** Share concurrent compilation, allow retry after failure and reject late results on teardown. */
+  async getTransform(type, reverse) {
+    if (this.disposed) throw new Error("Projected navigation is disposed");
+    const options = getProjectedCoordinateOptions(type);
+    const key = `${type}:${reverse}`;
+    let pending = this.transforms.get(key);
+    if (!pending) {
+      pending = Promise.resolve().then(() => this.engine.createProjectionAsync(reverse ? { from: options.to, to: options.from } : options));
+      this.transforms.set(key, pending);
+      pending.catch(() => {
+        if (this.transforms.get(key) === pending) this.transforms.delete(key);
+      });
+    }
+    const transform = await pending;
+    if (this.disposed) throw new Error("Projected navigation is disposed");
+    return transform;
+  }
+};
+
+// src/experimental/projected-detail.ts
+import {
+  countProjectedTileCoordinates as countProjectedTileCoordinates2,
+  WebMercatorVisibilityAdapter,
+  projectGeographicPosition,
+  getTileGeographicBounds
+} from "@tangram.gl/tangram-renderer/core";
+async function selectProjectedTileDetail(navigation, viewport, type, options) {
+  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 !== void 0 && (!Number.isSafeInteger(currentTileZoom) || currentTileZoom < 0 || currentTileZoom > 6)) {
+    throw new Error("Projected tile detail requires ordered levels 0\u20136, positive pixel/candidate limits and finite hysteresis");
+  }
+  const candidates = [];
+  for (let zoom = minZoom; zoom <= maxZoom; zoom++) {
+    const count = countProjectedTileCoordinates2(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 = /* @__PURE__ */ new Map();
+  const measure = async (zoom) => {
+    const cached = measurements.get(zoom);
+    if (cached !== void 0) 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 = [];
+    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);
+      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
+  };
+}
+
+// src/experimental/projected-basemaps.ts
+function getProjectedViewFrame(viewport, options, dimensions = { width: viewport.width, height: viewport.height }) {
+  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 Matrix42(Array.from(viewport.projectionMatrix)).multiplyRight(Array.from(viewport.viewMatrix));
+  const [west, south, east, north] = options.visibleBounds;
+  const projection = normalizeProjectedBasemapOptions2(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 !== void 0 && (!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 = {
+    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 === void 0 ? {} : { tileResources: options.tileResources },
+    renderViews: [{ id: "projected", camera: {
+      view: new Float64Array(new Matrix42()),
+      projection: new Float64Array(cameraProjection),
+      position: [0, 0, 1]
+    } }]
+  };
+  new HostFrame(frame);
+  if (options.maxTiles !== void 0) {
+    const count = countProjectedTileCoordinates3(options.visibleBounds, options.tileZoom);
+    if (count > options.maxTiles) {
+      throw new Error(`Projected footprint requires ${count} tiles per source, exceeding maxTiles ${options.maxTiles}`);
+    }
+  }
+  return frame;
+}
+function createProjectedBasemapScene(scene, projection, workerUrl) {
+  const options = normalizeProjectedBasemapOptions2(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 !== void 0) 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 !== void 0 || style.shaders !== void 0 || style.lighting !== void 0 && 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 !== void 0) {
+      const material = readRecord(style.material, "material");
+      if (material.normal !== void 0 || material.specular !== void 0 && material.specular !== 0) {
+        throw new Error("Projected lighting supports diffuse materials without normal maps or specular terms");
+      }
+    }
+    if (style.draw !== void 0) validateFlatDraw(
+      readRecord(style.draw, "style draw defaults"),
+      Boolean(options.allowElevation && ["polygons", "raster", "points", "text"].includes(String(style.base)))
+    );
+    if (style.draw !== void 0 && ["points", "text"].includes(String(style.base))) {
+      validateAnnotationDraw(readRecord(style.draw, "annotation defaults"));
+    }
+    if (style.base === "raster" && style.draw !== void 0 && 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 !== void 0) 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 !== void 0 && (!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: [.../* @__PURE__ */ new Set([...scripts, url.href])], cpu_projection: options } };
+}
+function validateProjectedDraws(node, styles, inheritedDraws = {}, allowElevation = false) {
+  const effectiveDraws = { ...inheritedDraws };
+  if (node.draw !== void 0) {
+    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 === void 0 ? {} : readRecord(style.draw, "annotation defaults");
+        const annotation = mergeAnnotationDraws(defaults, draw);
+        validateFlatDraw(annotation, allowElevation);
+        validateAnnotationDraw(annotation);
+        if (annotation.collide !== void 0 && typeof annotation.collide !== "boolean") throw new Error("Projected collide must be boolean");
+        if (annotation.text !== void 0) {
+          const text = readRecord(annotation.text, "attached text");
+          if (text.collide !== void 0 && typeof text.collide !== "boolean") throw new Error("Projected collide must be boolean");
+          validateFlatDraw(text);
+        }
+      }
+      if (style.base === "lines") {
+        const defaults = style.draw === void 0 ? {} : readRecord(style.draw, "style draw defaults");
+        validateRoadDraw({ ...defaults, ...draw }, true);
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (!["filter", "draw", "visible", "enabled", "data", "exclusive", "priority"].includes(key) && value && typeof value === "object" && !Array.isArray(value)) {
+      validateProjectedDraws(readRecord(value, "layer"), styles, effectiveDraws, allowElevation);
+    }
+  }
+}
+function mergeAnnotationDraws(defaults, draw) {
+  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;
+}
+function validateFlatDraw(draw, allowElevation = false) {
+  if (!allowElevation && (draw.extrude !== void 0 && draw.extrude !== false || draw.z !== void 0)) {
+    throw new Error("Projected basemaps require flat draws unless allowElevation is enabled");
+  }
+}
+function validateAnnotationDraw(draw) {
+  if (draw.extrude !== void 0 && draw.extrude !== false) throw new Error("Projected annotations do not support extrusion");
+  if (draw.text !== void 0 && draw.text !== false) validateFlatDraw(readRecord(draw.text, "attached text"));
+}
+function readRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Projected ${label} must be an object`);
+  return Object.fromEntries(Object.entries(value));
+}
+function validateRoadDraw(draw, requireWidth) {
+  if (draw.outline !== void 0) readRecord(draw.outline, "road outline");
+  if (["next_width", "next_offset", "texture"].some((key) => draw[key] !== void 0)) {
+    throw new Error("Projected roads require static ribbons without dynamic widths or external textures");
+  }
+  if (draw.width !== void 0 || requireWidth) {
+    const unit = getProjectedRoadUnit(draw.width);
+    if (draw.offset !== void 0 && getProjectedRoadUnit(draw.offset, false) !== unit) throw new Error("Projected road offsets must use the width unit");
+    if (draw.outline !== void 0) {
+      const outline = readRecord(draw.outline, "road outline");
+      validateFlatDraw(outline);
+      if (outline.style !== void 0) 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 !== void 0 && typeof draw.animated !== "boolean") throw new Error("Projected road animated must be boolean");
+  if (draw.dash !== void 0 && (!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");
+  }
+}
+var BaseProjectedBasemapLayer = tangram_layer_default({
+  Layer,
+  ClassicWebGLRenderer: Renderer,
+  Renderer: void 0
+}, {
+  getFrame(viewport, properties, dimensions) {
+    const scene = readRecord(properties.scene, "scene");
+    const settings = readRecord(scene.scene, "scene settings");
+    const projection = normalizeProjectedBasemapOptions2(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);
+  }
+});
+var ProjectedBasemapLayer = class 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, options = {}) {
+    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) {
+    super.updateState(parameters);
+    const record = this.state.tangramRecord;
+    if (!record) return;
+    const settings = readRecord(readRecord(record.sceneSource, "scene").scene, "scene settings");
+    const projection = normalizeProjectedBasemapOptions2(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 {
+  ProjectedBasemapLayer,
+  ProjectedBasemapNavigation,
+  createProjectedBasemapScene,
+  getProjectedGeographicBounds,
+  getProjectedViewFrame,
+  selectProjectedTileDetail
+};
+//# sourceMappingURL=projected-basemaps.js.map