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

package/src/experimental/webxr/projection.ts

@@ -0,0 +1,371 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import {PlaneShape, SphereShape} from '@math.gl/culling';
+import {PROJECTION_CONSTANTS, unprojectGlobePosition} from '@tangram.gl/tangram-renderer/core';
+import type {
+  XRGeographicPosition,
+  XRGlobePlacement,
+  XRMapPlacement,
+  XRPlacement,
+  XRPlacementPose,
+  XRSpatialRay,
+  XRSurfaceHit,
+  XRVector3
+} from './types.ts';
+
+const TANGRAM_HALF_WORLD_METERS = 20037508.342789244;
+const GLOBE_RADIUS = PROJECTION_CONSTANTS.globeRadius;
+// Content-space queries need no shape transform: placement is inverted before picking.
+const MAP_SURFACE = new PlaneShape();
+const GLOBE_SURFACE = new SphereShape({radius: GLOBE_RADIUS});
+const MAX_MERCATOR_LATITUDE = 85.05112878;
+const DEGREES_TO_RADIANS = Math.PI / 180;
+const RADIANS_TO_DEGREES = 180 / Math.PI;
+
+/** Convert longitude and latitude to Tangram EPSG:3857 meters. */
+export function longitudeLatitudeToMeters(longitude: number, latitude: number): [number, number] {
+  const clampedLatitude = Math.max(
+    -MAX_MERCATOR_LATITUDE,
+    Math.min(MAX_MERCATOR_LATITUDE, latitude)
+  );
+  return [
+    (longitude / 180) * TANGRAM_HALF_WORLD_METERS,
+    (Math.log(Math.tan(((90 + clampedLatitude) * Math.PI) / 360)) / Math.PI) *
+      TANGRAM_HALF_WORLD_METERS
+  ];
+}
+
+/** Convert a Tangram EPSG:3857 position to longitude, latitude, and altitude. */
+export function metersToLongitudeLatitude(
+  x: number,
+  y: number,
+  altitude = 0
+): [number, number, number] {
+  return [
+    (x / TANGRAM_HALF_WORLD_METERS) * 180,
+    (Math.atan(Math.exp((y / TANGRAM_HALF_WORLD_METERS) * Math.PI)) * 360) / Math.PI - 90,
+    altitude
+  ];
+}
+
+/** Create an affine matrix from an XR-space pose. */
+export function createXRPoseMatrix(pose: XRPlacementPose = {}): Matrix4 {
+  const position = pose.position || [0, 0, 0];
+  const orientation = pose.orientation || [0, 0, 0, 1];
+  return new Matrix4()
+    .translate(position)
+    .multiplyRight(new Matrix4().fromQuaternion(orientation));
+}
+
+/** Create the world-to-reference-space placement matrix for geospatial content. */
+export function createXRPlacementMatrix(
+  placement: XRPlacement,
+  viewState: Record<string, unknown> = {}
+): Matrix4 {
+  if (placement.type === 'globe') {
+    const longitude = finiteNumber(viewState.longitude, placement.anchor[0]);
+    const latitude = finiteNumber(viewState.latitude, placement.anchor[1]);
+    const rotation = placement.rotation || 0;
+    const scale = placement.radius / GLOBE_RADIUS;
+    return createXRPoseMatrix(placement.pose)
+      // deck.gl globe coordinates have north on +Z and longitude zero on -Y.
+      // Face the anchor toward +Z in XR room space, with north toward +Y.
+      .rotateX(latitude * DEGREES_TO_RADIANS - Math.PI / 2)
+      .rotateZ(-(longitude + rotation) * DEGREES_TO_RADIANS)
+      .scale([scale, scale, scale]);
+  }
+
+  const fallbackAnchor = placement.type === 'map' ? placement.anchor : placement.origin;
+  const longitude = finiteNumber(viewState.longitude, fallbackAnchor[0]);
+  const latitude = finiteNumber(viewState.latitude, fallbackAnchor[1]);
+  const [centerX, centerY] = longitudeLatitudeToMeters(longitude, latitude);
+  const metersPerMercatorMeter = Math.cos(
+    Math.max(-MAX_MERCATOR_LATITUDE, Math.min(MAX_MERCATOR_LATITUDE, latitude)) *
+      DEGREES_TO_RADIANS
+  );
+
+  if (placement.type === 'map') {
+    const scale = 1 / placement.metersPerXRUnit;
+    return createXRPoseMatrix(placement.pose)
+      .rotateX(-Math.PI / 2)
+      .scale([scale * metersPerMercatorMeter, scale * metersPerMercatorMeter, scale])
+      .translate([-centerX, -centerY, -(placement.anchor[2] || 0)]);
+  }
+
+  const offset = placement.position || [0, 0, 0];
+  const bearing = finiteNumber(viewState.bearing, placement.bearing || 0);
+  return createXRPoseMatrix(placement.pose)
+    .rotateY(-bearing * DEGREES_TO_RADIANS)
+    .rotateX(-Math.PI / 2)
+    .translate([-offset[0], -offset[1], -offset[2]])
+    .scale([metersPerMercatorMeter, metersPerMercatorMeter, 1])
+    .translate([-centerX, -centerY, 0]);
+}
+
+/** Transform an XR-space ray back into the content coordinate system. */
+export function transformXRRayToContent(ray: XRSpatialRay, placementMatrix: readonly number[] | Float32Array | Float64Array) {
+  const inverse = new Matrix4().copy(placementMatrix).invert();
+  const origin = transformPoint(inverse, ray.origin);
+  const farPoint = transformPoint(inverse, [
+    ray.origin[0] + ray.direction[0],
+    ray.origin[1] + ray.direction[1],
+    ray.origin[2] + ray.direction[2]
+  ]);
+  return {
+    origin,
+    direction: normalizeVector([
+      farPoint[0] - origin[0],
+      farPoint[1] - origin[1],
+      farPoint[2] - origin[2]
+    ])
+  };
+}
+
+/** Intersect an XR-space ray with a placed Web Mercator map. */
+export function intersectXRMap(
+  ray: XRSpatialRay,
+  placement: XRMapPlacement,
+  viewState: Record<string, unknown> = {}
+): XRGeographicPosition | null {
+  const placementMatrix = createXRPlacementMatrix(placement, viewState);
+  const localRay = transformXRRayToContent(ray, placementMatrix);
+  return intersectContentSurface(localRay, placement, viewState)?.coordinate || null;
+}
+
+/** Shared ground/sphere intersection in the renderer's projected content space. */
+export function intersectContentSurface(
+  localRay: XRSpatialRay,
+  placement: XRPlacement,
+  viewState: Record<string, unknown> = {}
+): XRSurfaceHit | null {
+  if (!localRay.origin.every(Number.isFinite) || !localRay.direction.every(Number.isFinite) ||
+      Math.hypot(...localRay.direction) === 0) return null;
+  if (placement.type === 'globe') {
+    const distance = intersectSphereDistance(localRay.origin, localRay.direction);
+    if (distance === null) return null;
+    const point: XRVector3 = [
+      localRay.origin[0] + localRay.direction[0] * distance,
+      localRay.origin[1] + localRay.direction[1] * distance,
+      localRay.origin[2] + localRay.direction[2] * distance
+    ];
+    const coordinate = globePositionToLongitudeLatitude(point);
+    coordinate[2] = 0;
+    return {coordinate, position: point};
+  }
+  const distance = intersectPlaneDistance(localRay.origin, localRay.direction, 0);
+  if (distance === null) {
+    return null;
+  }
+  const hit: XRVector3 = [
+    localRay.origin[0] + localRay.direction[0] * distance,
+    localRay.origin[1] + localRay.direction[1] * distance,
+    0
+  ];
+  if (!isContentPointWithinMapBounds(hit, placement, viewState)) return null;
+  return {coordinate: metersToLongitudeLatitude(hit[0], hit[1]), position: hit};
+}
+
+/** Apply physical tabletop XY bounds equally to flat and terrain surface hits. */
+export function isContentPointWithinMapBounds(hit: XRVector3, placement: XRPlacement,
+  viewState: Record<string, unknown> = {}): boolean {
+  if (placement.type === 'map' && placement.surface?.type === 'bounded') {
+    const longitude = finiteNumber(viewState.longitude, placement.anchor[0]);
+    const latitude = finiteNumber(viewState.latitude, placement.anchor[1]);
+    const [centerX, centerY] = longitudeLatitudeToMeters(longitude, latitude);
+    const latitudeScale = Math.cos(
+      Math.max(-MAX_MERCATOR_LATITUDE, Math.min(MAX_MERCATOR_LATITUDE, latitude)) *
+        DEGREES_TO_RADIANS
+    );
+    const halfWidth = (placement.surface.width * placement.metersPerXRUnit) / (2 * latitudeScale);
+    const halfHeight = (placement.surface.height * placement.metersPerXRUnit) / (2 * latitudeScale);
+    if (Math.abs(hit[0] - centerX) > halfWidth || Math.abs(hit[1] - centerY) > halfHeight) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Intersect an XR-space ray with a placed deck.gl-compatible globe. */
+export function intersectXRGlobe(
+  ray: XRSpatialRay,
+  placement: XRGlobePlacement,
+  viewState: Record<string, unknown> = {}
+): XRGeographicPosition | null {
+  const placementMatrix = createXRPlacementMatrix(placement, viewState);
+  const localRay = transformXRRayToContent(ray, placementMatrix);
+  return intersectContentSurface(localRay, placement, viewState)?.coordinate || null;
+}
+
+/** Derive geographic bounds from the union of XR eye frusta intersecting a globe. */
+export function getXRGlobeVisibleBounds({
+  views,
+  placement,
+  viewState
+}: {
+  views: readonly {viewMatrix: readonly number[]; projectionMatrix: readonly number[]}[];
+  placement: XRGlobePlacement;
+  viewState?: Record<string, unknown>;
+}): [number, number, number, number] {
+  const placementMatrix = createXRPlacementMatrix(placement, viewState);
+  const coordinates: XRGeographicPosition[] = [];
+  const samples = [-1, 0, 1];
+  let crossesHorizon = false;
+  for (const view of views) {
+    const inverseClip = new Matrix4(view.projectionMatrix)
+      .multiplyRight(view.viewMatrix)
+      .multiplyRight(placementMatrix)
+      .invert();
+    for (const x of samples) {
+      for (const y of samples) {
+        const near = transformHomogeneousPoint(inverseClip, [x, y, -1]);
+        const far = transformHomogeneousPoint(inverseClip, [x, y, 1]);
+        const direction = normalizeVector([
+          far[0] - near[0],
+          far[1] - near[1],
+          far[2] - near[2]
+        ]);
+        const distance = intersectSphereDistance(near, direction);
+        if (distance !== null) {
+          coordinates.push(
+            globePositionToLongitudeLatitude([
+              near[0] + direction[0] * distance,
+              near[1] + direction[1] * distance,
+              near[2] + direction[2] * distance
+            ])
+          );
+        }
+        else crossesHorizon = true;
+      }
+    }
+  }
+  // When rays miss a room-sized globe, the visible silhouette lies between
+  // samples. Hit-only extrema are not a conservative footprint: finer tiles
+  // can omit visible ground (including the geographic anchor) entirely.
+  if (crossesHorizon && coordinates.length > 0) {
+    return getXRGlobeHorizonBounds(views, placementMatrix,
+      finiteNumber(viewState?.longitude, placement.anchor[0]));
+  }
+  if (coordinates.length === 0) {
+    return [-180, -MAX_MERCATOR_LATITUDE, 180, MAX_MERCATOR_LATITUDE];
+  }
+  const anchorLongitude = finiteNumber(viewState?.longitude, placement.anchor[0]);
+  const unwrappedLongitudes = coordinates.map(([longitude]) =>
+    unwrapLongitude(longitude, anchorLongitude)
+  );
+  const latitudes = coordinates.map((coordinate) => coordinate[1]);
+  return [
+    Math.min(...unwrappedLongitudes),
+    Math.max(-MAX_MERCATOR_LATITUDE, Math.min(...latitudes)),
+    Math.max(...unwrappedLongitudes),
+    Math.min(MAX_MERCATOR_LATITUDE, Math.max(...latitudes))
+  ];
+}
+
+/** Bound each eye's analytically visible spherical cap, independent of screen sampling density. */
+function getXRGlobeHorizonBounds(
+  views: readonly {viewMatrix: readonly number[]}[], placementMatrix: Matrix4, anchorLongitude: number
+): [number, number, number, number] {
+  let west = Infinity, south = Infinity, east = -Infinity, north = -Infinity;
+  for (const view of views) {
+    const camera = new Matrix4(view.viewMatrix).multiplyRight(placementMatrix).invert().transformAsPoint([0, 0, 0]);
+    const distance = Math.hypot(camera[0], camera[1], camera[2]);
+    if (!Number.isFinite(distance) || distance <= GLOBE_RADIUS) {
+      return [anchorLongitude - 180, -MAX_MERCATOR_LATITUDE, anchorLongitude + 180, MAX_MERCATOR_LATITUDE];
+    }
+    const [longitude, latitude] = globePositionToLongitudeLatitude([camera[0], camera[1], camera[2]]);
+    const radius = Math.acos(GLOBE_RADIUS / distance);
+    const latitudeRadians = latitude * DEGREES_TO_RADIANS;
+    const centerLongitude = unwrapLongitude(longitude, anchorLongitude);
+    const longitudeRadius = Math.abs(latitudeRadians) + radius >= Math.PI / 2 ? Math.PI :
+      Math.asin(Math.min(1, Math.sin(radius) / Math.cos(latitudeRadians)));
+    west = Math.min(west, longitudeRadius === Math.PI ? anchorLongitude - 180 : centerLongitude - longitudeRadius / DEGREES_TO_RADIANS);
+    east = Math.max(east, longitudeRadius === Math.PI ? anchorLongitude + 180 : centerLongitude + longitudeRadius / DEGREES_TO_RADIANS);
+    south = Math.min(south, latitude - radius / DEGREES_TO_RADIANS);
+    north = Math.max(north, latitude + radius / DEGREES_TO_RADIANS);
+  }
+  return [west, Math.max(-MAX_MERCATOR_LATITUDE, south), east, Math.min(MAX_MERCATOR_LATITUDE, north)];
+}
+
+/** Merge geographic bounds, preserving ranges that cross the antimeridian. */
+export function unionGeographicBounds(
+  bounds: readonly (readonly [number, number, number, number])[],
+  anchorLongitude = 0
+): [number, number, number, number] {
+  if (bounds.length === 0) {
+    return [-180, -MAX_MERCATOR_LATITUDE, 180, MAX_MERCATOR_LATITUDE];
+  }
+  const west = bounds.map((value) => unwrapLongitude(value[0], anchorLongitude));
+  const east = bounds.map((value) => unwrapLongitude(value[2], anchorLongitude));
+  return [
+    Math.min(...west),
+    Math.min(...bounds.map((value) => value[1])),
+    Math.max(...east),
+    Math.max(...bounds.map((value) => value[3]))
+  ];
+}
+
+/** Adapt Tangram's +Z ground normal to math.gl's +Y analytic plane. */
+function intersectPlaneDistance(
+  origin: XRVector3,
+  direction: XRVector3,
+  planeZ: number
+): number | null {
+  if (Math.abs(direction[2]) < 1e-8) {
+    return null;
+  }
+  return MAP_SURFACE.intersectLocalRay(
+    [origin[0], origin[2] - planeZ, origin[1]],
+    [direction[0], direction[2], direction[1]]
+  )?.distance ?? null;
+}
+
+/** Return the nearest nonnegative ray parameter, including an inside-sphere exit. */
+function intersectSphereDistance(
+  origin: XRVector3,
+  direction: XRVector3
+): number | null {
+  return GLOBE_SURFACE.intersectLocalRay(origin, direction)?.distance ?? null;
+}
+
+function globePositionToLongitudeLatitude(point: XRVector3): [number, number, number] {
+  return unprojectGlobePosition(point);
+}
+
+function transformPoint(matrix: readonly number[], point: XRVector3): XRVector3 {
+  return transformHomogeneousPoint(matrix, point);
+}
+
+function transformHomogeneousPoint(matrix: readonly number[], point: XRVector3): XRVector3 {
+  const x = point[0];
+  const y = point[1];
+  const z = point[2];
+  const w = matrix[3] * x + matrix[7] * y + matrix[11] * z + matrix[15];
+  const divisor = w || 1;
+  return [
+    (matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12]) / divisor,
+    (matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13]) / divisor,
+    (matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14]) / divisor
+  ];
+}
+
+function normalizeVector(vector: readonly number[]): XRVector3 {
+  const length = Math.hypot(vector[0], vector[1], vector[2]);
+  if (!length) {
+    return [0, 0, -1];
+  }
+  return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return Number.isFinite(value) ? (value as number) : fallback;
+}
+
+function unwrapLongitude(longitude: number, anchor: number): number {
+  let result = longitude;
+  while (result - anchor > 180) result -= 360;
+  while (result - anchor < -180) result += 360;
+  return result;
+}

package/src/experimental/webxr/types.ts

@@ -0,0 +1,221 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {HostFrameOptions, HostRenderView} from '@tangram.gl/tangram-renderer';
+import type {TerrainSurface, TerrainSurfaceHit} from '@tangram.gl/tangram-renderer/core';
+import type {Controller, FirstPersonViewState, MapViewState, View, Viewport} from '@deck.gl/core';
+import type {Matrix4} from '@math.gl/core';
+
+/** Shared geographic navigation state, independent of the rendered eye. */
+export type XRViewState = Omit<MapViewState, 'zoom'> & FirstPersonViewState & {zoom?: number};
+
+/** Canvas dimensions used to create a logical or per-eye viewport. */
+export type XRViewportSize = {width: number; height: number};
+
+/** Parameters used to derive an eye from the shared logical navigation state. */
+export type XREyeViewportOptions<State = XRViewState> = XRViewportSize & {viewState: State; eyeOffset?: number};
+
+/** Matrices supplied to a view-specific projection adapter. */
+export type XRProjectionOptions = {projectionMatrix: Matrix4; viewMatrix: Matrix4};
+
+/** Three-dimensional coordinate expressed in meters unless documented otherwise. */
+export type XRVector3 = readonly [number, number, number];
+
+/** Quaternion in `[x, y, z, w]` order. */
+export type XRQuaternion = readonly [number, number, number, number];
+
+/** Geographic coordinate in `[longitude, latitude, altitude]` order. */
+export type XRGeographicPosition = readonly [number, number, number?];
+
+/** Placement pose in an XR reference space. */
+export type XRPlacementPose = {
+  position?: XRVector3;
+  orientation?: XRQuaternion;
+};
+
+/** Finite tabletop dimensions in physical XR meters. */
+export type XRBoundedMapSurface = {
+  type: 'bounded';
+  width: number;
+  height: number;
+};
+
+/** Map plane without a finite interaction boundary. */
+export type XRUnboundedMapSurface = {type: 'unbounded'};
+
+/** Placement of a Web Mercator map in an XR reference space. */
+export type XRMapPlacement = {
+  type: 'map';
+  anchor: XRGeographicPosition;
+  pose?: XRPlacementPose;
+  /** Geographic meters represented by one physical XR meter. */
+  metersPerXRUnit: number;
+  surface?: XRBoundedMapSurface | XRUnboundedMapSurface;
+};
+
+/** Placement of a globe in an XR reference space. */
+export type XRGlobePlacement = {
+  type: 'globe';
+  anchor: XRGeographicPosition;
+  pose?: XRPlacementPose;
+  /** Physical globe radius in XR meters. */
+  radius: number;
+  /** Additional rotation around the globe's polar axis, in degrees. */
+  rotation?: number;
+};
+
+/** One-to-one local tangent placement for immersive first-person navigation. */
+export type XRFirstPersonPlacement = {
+  type: 'first-person';
+  origin: XRGeographicPosition;
+  pose?: XRPlacementPose;
+  /** East, north, and up locomotion offset in geographic meters. */
+  position?: XRVector3;
+  /** Body heading in degrees. Head pitch and roll remain owned by WebXR. */
+  bearing?: number;
+};
+
+/** Supported geospatial content placements. */
+export type XRPlacement = XRMapPlacement | XRGlobePlacement | XRFirstPersonPlacement;
+
+/** Runtime presentation mode. */
+export type XRPresentationMode = 'auto' | 'mono' | 'stereo-preview' | 'immersive-vr';
+
+/** Minimal luma.gl WebXR view state consumed by the presentation. */
+export type XRFrameView = {
+  eye?: string;
+  index: number;
+  viewport: readonly [number, number, number, number];
+  viewMatrix: readonly number[];
+  projectionMatrix: readonly number[];
+  framebuffer?: unknown;
+};
+
+/** Minimal luma.gl WebXR frame state consumed by the presentation. */
+export type XRFrameState = {
+  views: readonly XRFrameView[];
+  framebuffer?: unknown;
+};
+
+/** Deck view contract required by {@link WebXRPresentation}. */
+export type XRDeckView = {
+  id: string;
+  constructor: Function & {displayName?: string};
+  controller: View['controller'];
+  makeViewport: View['makeViewport'];
+  makeEyeViewport(options: XREyeViewportOptions<Parameters<View['makeViewport']>[0]['viewState']>): XRDeckViewport | null;
+  getHostFrame(viewport: XRDeckViewport): XRHostFrameFields;
+  /** Optional visibility recalculation after actual per-eye camera transforms. */
+  getHostFrameForCamera?(viewport: XRDeckViewport, camera: HostRenderView['camera'],
+    options?: {width?: number; height?: number}): XRHostFrameFields;
+  getXRProjectionMatrix(options: XRProjectionOptions): Matrix4;
+};
+
+/** Deck viewport surface used by the package without importing private deck internals. */
+export type XRDeckViewport = Viewport & {longitude?: number; latitude?: number; pitch?: number; bearing?: number};
+
+/** Deck controller methods used by the shared logical view. */
+export type XRDeckController = Pick<Controller<never>, 'setProps' | 'finalize' | 'updateTransition'>;
+
+/** Host-frame fields derived from one logical deck viewport. */
+export type XRHostFrameFields = {
+  view: {
+    longitude: number;
+    latitude: number;
+    altitude?: number;
+    zoom: number;
+  };
+  projection?: HostFrameOptions['projection'];
+  camera: HostRenderView['camera'];
+  tileBuffer?: number;
+  /** Optional globally resident coarse globe fallback level. */
+  globePreloadZoom?: number;
+};
+
+/** One rendered eye or mono view and its corresponding deck viewport. */
+export type XRPresentationRenderView = HostRenderView & {
+  id: string;
+  /** Eye rectangle is always defined by a prepared presentation. */
+  viewport: HostFrameOptions['viewport'];
+  hostFrame?: XRHostFrameFields;
+  deckViewport: XRDeckViewport;
+  xrView?: XRFrameView;
+  /** Logical view attached to native XR eyes for host integration. */
+  view?: XRDeckView;
+  /** Shared navigation snapshot attached to native XR eyes. */
+  viewState?: XRViewState;
+};
+
+/** Result of preparing one mono, stereo-preview, or immersive frame. */
+export type XRPresentationFrame = {
+  mode: Exclude<XRPresentationMode, 'auto'>;
+  logicalViewport: XRDeckViewport;
+  renderViews: readonly XRPresentationRenderView[];
+  hostFrame: HostFrameOptions;
+};
+
+/** Ray expressed in the active XR reference space. */
+export type XRSpatialRay = {
+  origin: XRVector3;
+  direction: XRVector3;
+  handedness?: string;
+};
+
+/** Top-origin canvas pointer in frame viewport units: CSS pixels for desktop, framebuffer pixels for XR. */
+export type XRScreenPointer = {
+  x: number;
+  y: number;
+  eye?: 'left' | 'right' | 'center';
+};
+
+/** Geographic analytic or explicit terrain surface hit, not a rendered feature selection. */
+export type XRSurfaceHit = {
+  /** Longitude/latitude degrees; zero altitude by default, physical terrain altitude when supplied. */
+  coordinate: readonly [number, number, number];
+  /** EPSG:3857 meters for planar content, or radius-256 globe common coordinates. */
+  position: XRVector3;
+  /** Rendered eye used by a screen pointer; absent for room rays and logical center-eye picks. */
+  renderViewId?: string;
+  /** Triangle and normal metadata when the explicit terrain surface was intersected. */
+  terrain?: Pick<TerrainSurfaceHit, 'triangleIndex' | 'normal' | 'barycentric'>;
+};
+
+/** Snapshot used to resolve a screen pointer or XR reference-space ray. */
+export type XRSurfacePickingOptions = {
+  /** Host-owned mesh in content coordinates; a miss never falls back to the zero-height surface. */
+  terrain?: TerrainSurface;
+  /** Top-origin canvas pointer in frame viewport units, or reference-space ray. */
+  pointer: XRScreenPointer | XRSpatialRay;
+  /** Content placement and optional finite map interaction boundary. */
+  placement: XRPlacement;
+  /** Actual rendered frame; required for screen pointers. */
+  frame?: XRPresentationFrame;
+  /** Logical geographic state at the time the frame was rendered. */
+  viewState?: Record<string, unknown>;
+  /** Actual room placement matrix, including application animation; used only for room rays. */
+  placementMatrix?: HostRenderView['camera']['view'];
+};
+
+/** Input-independent navigation, pointing, and signal contract. */
+export type XRInteractionIntent =
+  | {
+      type: 'navigate';
+      action: 'pan' | 'zoom' | 'rotate' | 'pitch' | 'move' | 'turn';
+      delta: readonly number[];
+      handedness?: string;
+    }
+  | {
+      type: 'point';
+      pointer: XRSpatialRay | XRScreenPointer;
+      action?: 'hover' | 'select' | 'grab' | 'release' | 'cancel';
+      /** Stable controller/pointer owner during a gesture; omitted for single-pointer clients. */
+      inputId?: string;
+      /** Activation source, so select release cannot end an independent squeeze grab. */
+      button?: 'select' | 'squeeze';
+    }
+  | {
+      type: 'signal';
+      action: string;
+      data?: unknown;
+    };