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

package/src/experimental/webxr/views.ts

@@ -0,0 +1,190 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  _GlobeController as GlobeController,
+  FirstPersonView,
+  FirstPersonController,
+  MapController,
+  MapView,
+  _GlobeView as GlobeView
+} from '@deck.gl/core';
+import type {FirstPersonViewProps, GlobeViewProps, MapViewState, GlobeViewState, WebMercatorViewport, FirstPersonViewport, _GlobeViewport as GlobeViewport} from '@deck.gl/core';
+import type {MjolnirGestureEvent} from 'mjolnir.js';
+import type {HostCamera} from '@tangram.gl/tangram-renderer/core';
+import WebMercatorViewAdapter from '../../web_mercator_view_adapter.js';
+import FirstPersonViewAdapter, {getFirstPersonFrameForCamera} from '../../first_person_view_adapter.js';
+import GlobeViewAdapter from '../../globe_view_adapter.js';
+import type {XRDeckViewport, XREyeViewportOptions, XRHostFrameFields, XRProjectionOptions} from './types.js';
+
+/** Shared conservative visibility policy for mono and actual stereo eye cameras. */
+type FirstPersonVisibilityProperties = {
+  /** Maximum local geographic east/north extent per axis, in meters. */
+  firstPersonMaxGroundExtent?: number;
+  /** Finite ordered physical height interval, in meters; defaults to ground only. */
+  firstPersonElevationRange?: readonly [number, number];
+};
+
+/**
+ * Map controller that keeps touch pinch rotation enabled while treating a
+ * two-finger trackpad gesture as a map pan.
+ *
+ * deck.gl uses the same `multiTouchDrag` option for both gesture families.
+ * The temporary mode below lets the normal controller state handle each
+ * gesture without duplicating deck.gl's pan and rotate calculations.
+ */
+export class WebXRMapController extends MapController {
+  _onMultiPanStart(event: MjolnirGestureEvent) {
+    const multiTouchDrag = this.multiTouchDrag;
+    if (event.pointerType === 'trackpad') {
+      this.multiTouchDrag = 'pan';
+    }
+    const handled = super._onMultiPanStart(event);
+    this.multiTouchDrag = multiTouchDrag;
+    return handled;
+  }
+}
+
+/** First-person controller with separate trackpad pan and touch pinch modes. */
+export class WebXRFirstPersonController extends FirstPersonController {
+  _onMultiPanStart(event: MjolnirGestureEvent) {
+    const multiTouchDrag = this.multiTouchDrag;
+    if (event.pointerType === 'trackpad') {
+      this.multiTouchDrag = 'pan';
+    }
+    const handled = super._onMultiPanStart(event);
+    this.multiTouchDrag = multiTouchDrag;
+    return handled;
+  }
+}
+
+/** Globe controller with separate trackpad pan and touch pinch modes. */
+export class WebXRGlobeController extends GlobeController {
+  _onMultiPanStart(event: MjolnirGestureEvent) {
+    const multiTouchDrag = this.multiTouchDrag;
+    if (event.pointerType === 'trackpad') {
+      this.multiTouchDrag = 'pan';
+    }
+    const handled = super._onMultiPanStart(event);
+    this.multiTouchDrag = multiTouchDrag;
+    return handled;
+  }
+}
+
+/** MapView that can derive Tangram host-frame fields and per-eye viewports. */
+export class WebXRMapView extends MapView {
+  static displayName = 'WebXRMapView';
+
+  makeEyeViewport({width, height, viewState, eyeOffset = 0}: XREyeViewportOptions<MapViewState>) {
+    const position = viewState.position || [0, 0, 0];
+    return this.makeViewport({
+      width,
+      height,
+      viewState: {...viewState, position: [position[0] + eyeOffset, position[1], position[2]]}
+    });
+  }
+
+  getHostFrame(viewport: WebMercatorViewport): XRHostFrameFields {
+    return {
+      view: {
+        longitude: viewport.longitude,
+        latitude: viewport.latitude,
+        zoom: viewport.zoom + 1
+      },
+      projection: {type: 'web-mercator'},
+      camera: WebMercatorViewAdapter.getCameraFrame(viewport),
+      tileBuffer: Math.min(
+        4,
+        Math.ceil(
+          (Math.tan((Math.abs(viewport.pitch || 0) * Math.PI) / 180) * viewport.height) / 256
+        )
+      )
+    };
+  }
+
+  getXRProjectionMatrix({projectionMatrix}: XRProjectionOptions) {
+    return projectionMatrix;
+  }
+}
+
+/** FirstPersonView that can derive Tangram host-frame fields and per-eye viewports. */
+export class WebXRFirstPersonView extends FirstPersonView {
+  static displayName = 'WebXRFirstPersonView';
+  /** Base deck view settings plus Tangram's bounded ground visibility policy. */
+  declare props: FirstPersonViewProps & FirstPersonVisibilityProperties;
+
+  /** Configure the logical first-person view and optional ground extent. */
+  constructor(props: FirstPersonViewProps & FirstPersonVisibilityProperties = {}) {
+    super(props);
+  }
+
+  makeEyeViewport({width, height, viewState, eyeOffset = 0}: XREyeViewportOptions) {
+    const position = viewState.position || [0, 0, 0];
+    return this.makeViewport({
+      width,
+      height,
+      viewState: {...viewState, position: [position[0] + eyeOffset, position[1], position[2]]}
+    });
+  }
+
+  getHostFrame(viewport: FirstPersonViewport): XRHostFrameFields {
+    const frame = FirstPersonViewAdapter.getFrame(viewport, {maxGroundExtent: this.props.firstPersonMaxGroundExtent ?? undefined,
+      elevationRange: this.props.firstPersonElevationRange});
+    return {
+      view: frame.view,
+      projection: frame.projection,
+      camera: frame.camera,
+      tileBuffer: frame.tileBuffer
+    };
+  }
+
+  /** Recomputes ground visibility after stereo or immersive camera transforms. */
+  getHostFrameForCamera(viewport: XRDeckViewport, camera: HostCamera, options: {width?: number; height?: number} = {}): XRHostFrameFields {
+    return getFirstPersonFrameForCamera(viewport, camera, {
+      ...options,
+      maxGroundExtent: this.props.firstPersonMaxGroundExtent ?? undefined,
+      elevationRange: this.props.firstPersonElevationRange
+    });
+  }
+
+  getXRProjectionMatrix({projectionMatrix}: XRProjectionOptions) {
+    return projectionMatrix;
+  }
+}
+
+/** GlobeView that can derive Tangram host-frame fields and per-eye viewports. */
+export class WebXRGlobeView extends GlobeView {
+  static displayName = 'WebXRGlobeView';
+  /** Base deck view settings plus Tangram's globe visibility policies. */
+  declare props: GlobeViewProps & {globeMaxElevation?: number; globePreloadZoom?: number};
+
+  /** Configure a globe view and its optional globally resident loading fallback. */
+  constructor(props: GlobeViewProps & {globeMaxElevation?: number; globePreloadZoom?: number} = {}) {
+    super(props);
+  }
+
+  makeEyeViewport({width, height, viewState, eyeOffset = 0}: XREyeViewportOptions<GlobeViewState>) {
+    return this.makeViewport({
+      width,
+      height,
+      viewState: {...viewState, longitude: viewState.longitude + eyeOffset * 0.06}
+    });
+  }
+
+  getHostFrame(viewport: GlobeViewport): XRHostFrameFields {
+    const frame = GlobeViewAdapter.getFrame(viewport, {maxElevation: this.props.globeMaxElevation ?? undefined,
+      preloadZoom: this.props.globePreloadZoom ?? undefined});
+    return {
+      view: frame.view,
+      projection: frame.projection,
+      camera: frame.camera,
+      tileBuffer: frame.tileBuffer,
+      globePreloadZoom: frame.globePreloadZoom
+    };
+  }
+
+  getXRProjectionMatrix({projectionMatrix, viewMatrix}: XRProjectionOptions) {
+    return projectionMatrix.clone().multiplyRight(viewMatrix);
+  }
+}

package/src/first_person_view_adapter.ts

@@ -0,0 +1,107 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import {calculatePlanarVolumeBounds, type HostCamera, type LegacyHostFrame} from '@tangram.gl/tangram-renderer/core';
+import WebMercatorViewAdapter from './web_mercator_view_adapter.js';
+import type {FirstPersonViewport} from './view_adapter_types.js';
+
+const DECK_WORLD_SIZE = 512;
+const HALF_WORLD_METERS = 20037508.342789244;
+const TILE_SIZE = 256;
+const MAX_MERCATOR_LATITUDE = 85.05112878;
+const DEFAULT_GROUND_EXTENT = 20000;
+
+/** Rendering dimensions and bounded first-person ground visibility policy. */
+export type FirstPersonViewAdapterOptions = {
+  /** Target width in CSS pixels; defaults to viewport width. */
+  width?: number;
+  /** Target height in CSS pixels; defaults to viewport height. */
+  height?: number;
+  /** Maximum east/north extent from the eye in local geographic meters, per axis. Defaults to 20 km. */
+  maxGroundExtent?: number;
+  /** Conservative minimum/maximum physical heights in meters; defaults to ground only, [0, 0]. */
+  elevationRange?: readonly [number, number];
+};
+
+/** Typed bounded ground-footprint boundary for deck.gl FirstPersonView. */
+export default class FirstPersonViewAdapter {
+  /** Converts the finite frustum/ground intersection without changing camera matrices. */
+  static getFrame = getFrame;
+}
+
+/**
+ * Derives geographic tile visibility from the full finite camera frustum.
+ * Near/far planes and an eye-centered square limit bound horizon intersections.
+ * Looking entirely away from ground supplies explicit empty visibility instead
+ * of an error. An optional elevation slab includes elevated-only geometry;
+ * it is a conservative footprint, not a terrain intersection or occlusion test.
+ */
+function getFrame(viewport: FirstPersonViewport, options: FirstPersonViewAdapterOptions = {}): LegacyHostFrame {
+  return getFirstPersonFrameForCamera(viewport, WebMercatorViewAdapter.getCameraFrame(viewport), options);
+}
+
+/** Derives flat-ground visibility from the actual mono or per-eye EPSG:3857 camera. */
+export function getFirstPersonFrameForCamera(
+  viewport: FirstPersonViewport,
+  camera: HostCamera,
+  options: FirstPersonViewAdapterOptions = {}
+): LegacyHostFrame {
+  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_SIZE / (HALF_WORLD_METERS * 2);
+  const toGeographic = (x: number, y: number) => unprojectFlat.call(viewport, [
+    x * xyScale + DECK_WORLD_SIZE / 2, y * xyScale + DECK_WORLD_SIZE / 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: [number, number, number, number] | null = null;
+  if (bounds) {
+    const southwest = toGeographic(bounds.sw.x, bounds.sw.y);
+    const northeast = toGeographic(bounds.ne.x, bounds.ne.y);
+    // Keep the longitude interval unwrapped; the renderer's tile wrapping owns world copies.
+    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
+  };
+}

package/src/globe_view_adapter.ts

@@ -0,0 +1,103 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LegacyHostFrame} from '@tangram.gl/tangram-renderer/core';
+import type {GlobeViewport} from './view_adapter_types.js';
+const DECK_TO_TANGRAM_ZOOM_OFFSET = 1;
+
+/** Scene visibility declarations, independent of the host camera's altitude. */
+export type GlobeViewAdapterOptions = {
+  /** Conservative maximum rendered height in geographic meters; omit if unknown. */
+  maxElevation?: number;
+  /** Optional host-supplied footprint enclosing ground AND elevated content. */
+  visibleBounds?: readonly [number, number, number, number];
+  /** Globally resident loading fallback level, integer 0–3; omit to disable. */
+  preloadZoom?: number;
+};
+
+/** Typed globe projection and visibility boundary for deck.gl. */
+export default class GlobeViewAdapter {
+    /** Converts globe common-space matrices and visible geographic bounds. */
+    static getFrame = getFrame;
+}
+
+/**
+ * Converts a deck.gl GlobeViewport into Tangram's host-frame contract.
+ *
+ * Globe matrices consume deck common-space coordinates directly. Tangram's
+ * renderer converts its EPSG:3857 tile vertices to deck's radius-256 globe in
+ * the vertex shader before applying these matrices.
+ * GlobeViewport already compensates its camera scale for latitude. The local
+ * Mercator-to-sphere derivative cancels that compensation, so data/style zoom
+ * needs only the same 512-to-256 tile-size offset as MapView, not another
+ * latitude adjustment. Source tile_size and zoom_offset are applied later.
+ *
+ * @param {object} viewport deck.gl GlobeViewport.
+ * @param options Explicit scene height and conservative geographic footprint.
+ * @returns {object} Tangram HostFrame fields for a globe render view.
+ */
+function getFrame(viewport: GlobeViewport, options: GlobeViewAdapterOptions = {}): LegacyHostFrame {
+  if (options.maxElevation !== undefined &&
+    (!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_OFFSET)
+    },
+    projection: {
+      type: 'globe', visibleBounds: [visibleBounds[0], visibleBounds[1], visibleBounds[2], visibleBounds[3]],
+      ...(options.maxElevation === undefined ? {} : {maxElevation: options.maxElevation})
+    },
+    camera: {
+      view: new Float64Array(viewport.viewMatrix),
+      projection: new Float32Array(
+        multiplyMatrices(viewport.projectionMatrix, viewport.viewMatrix)
+      ),
+      position: [viewport.cameraPosition[0], viewport.cameraPosition[1], viewport.cameraPosition[2]]
+    },
+    tileBuffer: 0,
+    globePreloadZoom: options.preloadZoom
+  };
+}
+
+function multiplyMatrices(left: ArrayLike<number>, right: ArrayLike<number>): Float64Array {
+  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;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Layer} from '@deck.gl/core';
+import {Renderer as ClassicWebGLRenderer} from '@tangram.gl/tangram-renderer/core';
+import createTangramLayerClass, {
+  getExternalCameraFrame,
+  getFirstPersonViewFrame,
+  getGlobeViewFrame,
+  injectNextzenApiKey
+} from './tangram-layer.js';
+import type {TangramLayerProps} from './tangram-layer.js';
+
+const BaseTangramLayer = createTangramLayerClass({Layer, ClassicWebGLRenderer, Renderer: undefined});
+
+/**
+ * A deck.gl basemap layer that renders a Tangram scene into deck's active
+ * luma.gl device and render pass.
+ */
+class TangramLayer extends BaseTangramLayer {
+  /** Preserve deck.gl's complete public context rather than only the bridge capabilities. */
+  declare context: Layer<TangramLayerProps>['context'];
+  /** Public layer properties retain deck's resolved defaults. */
+  declare props: Layer<TangramLayerProps>['props'];
+  /** Preserve deck's state update signature through the injected base class. */
+  declare setState: Layer<TangramLayerProps>['setState'];
+  /** Keep deck's public state surface while the internal adapter checks its own record. */
+  declare state: Layer<TangramLayerProps>['state'];
+  /** Stable deck.gl metadata for the typed public subclass. */
+  static componentName = 'TangramLayer';
+  /** Compatibility name for integrations using deck.gl's historical metadata. */
+  static layerName = 'TangramLayer';
+  /** Preserve deck.gl's public initialization signature through the injected superclass. */
+  initializeState(_context: Layer<TangramLayerProps>['context']): void {super.initializeState();}
+  /** Forward the standard deck.gl property/state change contract. */
+  updateState(parameters: Parameters<Layer<TangramLayerProps>['updateState']>[0]): void {super.updateState(parameters);}
+  /** Release the scene using the standard deck.gl finalization signature. */
+  finalizeState(_context: Layer<TangramLayerProps>['context']): void {super.finalizeState();}
+  /** Forward deck's complete draw options to the existing render-pass bridge. */
+  draw(options: Parameters<Layer<TangramLayerProps>['draw']>[0]): void {super.draw(options);}
+}
+
+/** deck.gl fields inherited through the dependency-injected runtime superclass. */
+interface TangramLayer extends Layer<TangramLayerProps> {}
+
+export {
+  TangramLayer,
+  createTangramLayerClass,
+  getExternalCameraFrame,
+  getFirstPersonViewFrame,
+  getGlobeViewFrame,
+  injectNextzenApiKey
+};
+
+export default TangramLayer;
+export type {TangramLayerProps} from './tangram-layer.js';
+
+export {default as WebMercatorViewAdapter} from './web_mercator_view_adapter.js';
+export {default as FirstPersonViewAdapter} from './first_person_view_adapter.js';
+export type {FirstPersonViewAdapterOptions} from './first_person_view_adapter.js';
+export {default as GlobeViewAdapter} from './globe_view_adapter.js';
+export type {GlobeViewAdapterOptions} from './globe_view_adapter.js';
+export type {FirstPersonViewport, GlobeViewport, PlanarCameraViewport} from './view_adapter_types.js';

package/src/tangram-layer-lifecycle.ts

@@ -0,0 +1,130 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device, RenderPass} from '@luma.gl/core';
+import type {Scene} from '@tangram.gl/tangram-renderer';
+import type {Renderer, RendererOptions, SceneDefinition, SceneListeners, SceneLoadOptions, RenderOptions} from '@tangram.gl/tangram-renderer/core';
+import type {TangramLayerProps} from './tangram-layer';
+import type {FirstPersonViewport} from './view_adapter_types';
+
+/** Geographic viewport capabilities read by the existing view dispatch. */
+export interface TangramLayerViewport extends FirstPersonViewport {
+    /** Camera bearing in degrees. */
+    bearing?: number;
+    /** Class metadata used by deck.gl's existing experimental globe/first-person adapters. */
+    constructor: Function & {displayName?: string};
+    /** Optional globe eye and visible-boundary capabilities. */
+    cameraPosition?: ArrayLike<number>;
+    getBounds?: (options: {z: number}) => unknown;
+}
+
+/** Device state tracked only on the WebGL branch of the bridge. */
+export interface TangramBridgeDevice extends Device {
+    /** Optional WebGL state stack, validated before constructing a WebGL record. */
+    pushState?: () => void;
+    popState?: () => void;
+}
+
+/** Renderer scene capabilities needed by the bridge, without exposing scene implementation state. */
+export interface TangramBridgeScene {
+    /** Normalized animation policy, absent before loading. */
+    config?: {scene?: {animated?: boolean}} | null;
+    /** Main-thread context ownership used only for WebGL submission. */
+    withWebGLContext?<Value>(operation: () => Value): Value;
+}
+
+/** Narrow injected renderer API; GPU resources and workers remain renderer-owned. */
+export interface TangramBridgeRenderer extends Pick<Renderer,
+    'setFrame' | 'setTerrain' | 'setTerrainExaggeration' | 'getFeatureAt' | 'getTerrainAt' |
+    'getDrapedTerrainSurface' | 'getTerrainDrapingStatistics' | 'getAttributions' | 'destroy' | 'setProjectedBasemapProjection'> {
+    /** Scene owned by this renderer instance. */
+    scene: Scene;
+    /** Scene event registration. */
+    subscribe(listeners: SceneListeners): unknown;
+    /** Asynchronous scene load; synchronous legacy returns remain supported. */
+    load(scene: SceneDefinition, options: SceneLoadOptions): unknown;
+    /** Submit one host frame through the caller's active render pass. */
+    render(options: RenderOptions): boolean;
+}
+
+/** Factory injection preserves both the current and legacy renderer argument names. */
+export interface TangramRendererFactory {
+    /** Construct one independently owned renderer; missing factories still fail through the existing catch path. */
+    create?: (scene: SceneDefinition, options: RendererOptions & {requestRedraw: () => void}) => TangramBridgeRenderer;
+}
+
+/** deck lifecycle capabilities inherited from the injected superclass. */
+export interface TangramLayerOwner {
+    /** Resolved deck properties, including callback defaults. */
+    props: Partial<TangramLayerProps>;
+    /** Notify deck that asynchronous scene work needs another frame. */
+    setNeedsRedraw(): void;
+    /** Forward existing error reporting to deck. */
+    raiseError(error: Error, message: string): void;
+    /** Existing error callback used by the opt-in projected subclass. */
+    _reportSceneError(record: TangramRecord, error: Error, isFatal?: boolean): void;
+}
+
+/** Scene ownership shared by callbacks when deck replaces its layer instance. */
+export interface TangramRecord {
+    /** Latest layer instance holding the logical scene. */
+    owner: TangramLayerOwner;
+    /** Assigned renderer and scene, after successful factory construction. */
+    renderer: TangramBridgeRenderer;
+    scene: Scene;
+    /** Device and optional native WebGL context. */
+    device: TangramBridgeDevice;
+    gl: (WebGLRenderingContext & {lumaState?: {program?: WebGLProgram | null}}) | null;
+    /** Host canvas never replaced by Tangram. */
+    deckCanvas: HTMLCanvasElement;
+    /** Immutable constructor input identities. */
+    sceneSource: SceneDefinition;
+    sceneBasePath?: string | null;
+    apiKey?: string | null;
+    projectionEngine?: TangramLayerProps['projectionEngine'];
+    projectionEngineExecution?: TangramLayerProps['projectionEngineExecution'];
+    maxConcurrentTileLoadsPerWorker?: number;
+    /** Current asynchronous terrain request and latest relief policy. */
+    terrain?: TangramLayerProps['terrain'];
+    /** Immutable borrowed admission-pool identity. */
+    terrainResourceBudget?: TangramLayerProps['terrainResourceBudget'];
+    terrainRevision?: number;
+    terrainPendingRevision: number;
+    /** Current canvas CSS size, assigned during view synchronization. */
+    canvasWidth: number | null;
+    canvasHeight: number | null;
+    /** Disposal waits for an in-flight load, and releases the renderer once. */
+    disposed: boolean;
+    destroyed: boolean;
+    loadSettled: boolean;
+    loadFailed: boolean;
+    loaded: boolean;
+    loadPromise: Promise<unknown> | null;
+    /** Deduplicated scene/viewport errors and attribution request generation. */
+    lastSceneError: string | null;
+    lastViewportError: string | null;
+    reportedViewportError: string | null;
+    attributionGeneration?: number;
+    /** Latest opt-in projected mesh generation requested by the projected subclass. */
+    projectedProjectionKey?: string | null;
+    /** Reentrant WebGL state-scope depth. */
+    webglScopeDepth: number;
+}
+
+/** Record initialization happens before the factory is called so redraw callbacks can close over it. */
+export type PendingTangramRecord = Omit<TangramRecord, 'renderer' | 'scene'> & {
+    renderer: TangramBridgeRenderer | null;
+    scene: TangramBridgeScene | null;
+};
+
+/** Required host context capabilities, with no dependency on a concrete deck.gl subclass. */
+export interface TangramLayerContext {
+    /** Host device validated by the existing creation path. */
+    device: TangramBridgeDevice;
+    /** Current viewport plus the complete view inventory. */
+    viewport: TangramLayerViewport;
+    deck?: {getCanvas(): HTMLCanvasElement | null; getViewports?(): readonly TangramLayerViewport[]};
+    /** Caller-owned pass; undefined keeps the existing renderer fallback. */
+    renderPass?: RenderPass;
+}