gps-plus-slam-app-framework 1.1.0 → 1.3.0

package/dist/webxr-session-TIaD883f.js

@@ -0,0 +1,1054 @@
+import { createLogger } from "./utils/logger.js";
+import { CameraBlitCapture, computeCaptureSize } from "./ar/camera-blit-capture.js";
+import { getLastDeviceOrientation } from "./state/gps-event-coordinator.js";
+import { DepthSampler, wrapXRDepthInfo } from "./ar/depth-sampler.js";
+import { clearFrameUpdates, runFrameUpdates } from "./ar/frame-loop.js";
+import { clearXrFrameUpdates, runXrFrameUpdates } from "./ar/xr-frame-loop.js";
+import { WEBXR_TO_NUE } from "./ar/webxr-nue-basis.js";
+import { DEFAULT_CAPTURE_CONFIG, ImageCaptureManager } from "./ar/image-capture.js";
+import { clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectTrackingPhase } from "./state/tracking-slice.js";
+import { acquireCameraTexture } from "./ar/xr-camera-texture.js";
+import { n as runSessionDisposers } from "./session-disposers-M-oashRH.js";
+import { DEFAULT_RECORDING_OPTIONS, validateArCrashIsolationOptions } from "./state/recording-options.js";
+import { SCENE_NODE } from "./ar/scene-node-names.js";
+import { createCss3dRendererManager } from "./visualization/css3d-renderer-manager.js";
+import * as THREE from "three";
+import { nueQuaternionToWebXR, nueToWebXR } from "gps-plus-slam-js";
+//#region ../src/ar/depth-rgb-lookup.ts
+/**
+* Build an {@link RgbLookup} over an RGBA readback buffer.
+*
+* Defensive boundary: returns `null` (no lookup) when the dimensions are
+* not positive integers or the buffer length does not match
+* `width × height × 4` — callers then simply emit color-less points
+* rather than crashing the capture path.
+*/
+function createRgbLookup(pixels, width, height) {
+	if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || pixels.length !== width * height * 4) return null;
+	return (screenX, screenY) => {
+		if (!Number.isFinite(screenX) || !Number.isFinite(screenY) || screenX < 0 || screenX > 1 || screenY < 0 || screenY > 1) return null;
+		const col = Math.min(width - 1, Math.floor(screenX * width));
+		const rowFromTop = Math.min(height - 1, Math.floor(screenY * height));
+		const i = ((height - 1 - rowFromTop) * width + col) * 4;
+		return [
+			pixels[i],
+			pixels[i + 1],
+			pixels[i + 2]
+		];
+	};
+}
+//#endregion
+//#region ../src/ar/webxr-session.ts
+/**
+* WebXR Session Module
+*
+* Handles WebXR AR session initialization and frame loop.
+*
+* ARCHITECTURE NOTE: See docs/architecture-ar-gps-pose-separation.md
+*
+* Scene Hierarchy:
+*   scene (GPS world frame — NUE: X=North, Y=Up, Z=East)
+*   └── arWorldGroup (local space = NUE; receives alignment matrix)
+*       └── basisChangeNode ('webxr-to-nue', constant WEBXR_TO_NUE matrix)
+*           └── arpose (local space = WebXR)
+*               └── camera (raw AR pose from WebXR)
+*
+* The arWorldGroup is transformed by the GpsPlusSlamJs alignment matrix.
+* The camera's LOCAL transform is the raw AR pose from WebXR.
+* The camera's WORLD transform is the GPS-aligned world pose.
+*/
+const log = createLogger("WebXR");
+function isXRCameraLike(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const camera = value;
+	return typeof camera.width === "number" && Number.isFinite(camera.width) && camera.width > 0 && typeof camera.height === "number" && Number.isFinite(camera.height) && camera.height > 0;
+}
+/**
+* Extract a validated XRCameraLike from an XRViewerPose.
+*
+* Returns null in every case where the per-frame texture acquisition must be
+* skipped — i.e. whenever the caller should treat any previously cached
+* texture as stale and clear it. Centralising the preconditions here makes
+* it impossible to accidentally fall through without clearing the cache.
+*
+* Cases that return null:
+*   - pose is null (tracking lost)
+*   - pose has no views
+*   - the first view has no `camera` property (camera-access not granted)
+*   - the camera property is not a valid XRCameraLike (zero/NaN dimensions)
+*
+* @see docs/2026-02-06-bug-camera-frames-black.md
+*/
+function getXrCameraFromPose(pose) {
+	if (!pose) return null;
+	const view = pose.views[0];
+	if (!view) return null;
+	const candidate = view.camera;
+	return isXRCameraLike(candidate) ? candidate : null;
+}
+/**
+* Decide whether the one-time camera-access grant diagnostic should fire
+* on the current XR frame.
+*
+* The diagnostic is only meaningful when we actually have a valid pose:
+* if `pose` is null (e.g. session starts with tracking lost), then the
+* derived `xrCamera` is null regardless of permission state, and logging
+* "NOT GRANTED" would be a false negative that permanently suppresses the
+* correct status because `cameraAccessLoggedOnce` would latch to true.
+*
+* Additional conditions:
+*   - `alreadyLogged` prevents spamming the log every frame.
+*   - `captureActive` ensures we only care when an image capture session
+*     is running (otherwise the diagnostic has no audience).
+*
+* This predicate is extracted as a pure function so the guard against the
+* "first frame has no pose" false-negative regression is directly testable.
+*/
+function shouldLogCameraAccessDiagnostic(pose, alreadyLogged, captureActive) {
+	return pose !== null && !alreadyLogged && captureActive;
+}
+let renderer = null;
+let scene = null;
+let camera = null;
+let xrSession = null;
+/**
+* Monotonic time of the previous XR frame, in milliseconds (XR `time`
+* argument). Reset to 0 by `resetWebXRState()` so the first frame of a
+* new session sees `dt = 0` rather than a stale delta from the prior
+* session.
+*/
+let lastFrameTime = 0;
+/**
+* Reset WebXR module state - exported for testing only.
+* @internal
+*/
+function resetWebXRState() {
+	if (renderer) {
+		renderer.setAnimationLoop(null);
+		if (renderer.domElement.parentElement) renderer.domElement.parentElement.removeChild(renderer.domElement);
+		renderer.dispose();
+	}
+	renderer = null;
+	scene = null;
+	camera = null;
+	xrSession = null;
+	arWorldGroup = null;
+	arPoseNode = null;
+	latestArPose = null;
+	lastFrameTime = 0;
+	clearFrameUpdates();
+	clearXrFrameUpdates();
+	runSessionDisposers();
+	imageCaptureManager = null;
+	onImageCaptured = null;
+	getScreenRotation = null;
+	onCaptureFailed = null;
+	onSuspiciousImage = null;
+	if (trackingPhaseUnsubscribe) {
+		trackingPhaseUnsubscribe();
+		trackingPhaseUnsubscribe = null;
+	}
+	trackingStore = null;
+	onTrackingRestarted = null;
+	onTrackingLost = null;
+	onTrackingRecovered = null;
+	depthSampler = null;
+	onDepthCaptured = null;
+	onDepthUnavailable = null;
+	if (depthRgbBlit) {
+		depthRgbBlit.dispose();
+		depthRgbBlit = null;
+	}
+	onFrameCallback = null;
+	if (css3dManager) {
+		css3dManager.dispose();
+		css3dManager = null;
+	}
+	cameraAccessLoggedOnce = false;
+	getCameraTextureNullCount = 0;
+	latestCameraWidth = 0;
+	latestCameraHeight = 0;
+	currentArCrashIsolationOptions = { ...DEFAULT_RECORDING_OPTIONS.arCrashIsolation };
+	cleanupBlitResources();
+}
+/**
+* The AR world group - parent of camera and all AR-tracked content.
+* This group's transform = the alignment matrix from GpsPlusSlamJs.
+* When the library computes a new alignment, apply it to this group.
+*/
+let arWorldGroup = null;
+/**
+* The arpose Object3D — intermediate node between arWorldGroup and camera.
+* During recording it stays at identity; during replay it receives recorded
+* odomPosition/odomRotation from the store subscriber.
+*/
+let arPoseNode = null;
+/**
+* Stores the latest raw AR pose from WebXR (updated every frame).
+* This is read by the GPS callback to create paired GPS+AR events.
+*/
+let latestArPose = null;
+/**
+* Image capture manager instance (created when AR session starts)
+*/
+let imageCaptureManager = null;
+/**
+* Callback for when an image is captured (set via setImageCaptureCallback)
+*/
+let onImageCaptured = null;
+/**
+* Callback for when image capture fails (set via setImageCaptureCallback)
+*/
+let onCaptureFailed = null;
+/**
+* Callback for when a captured image appears suspicious/black
+* (set via setImageCaptureCallback)
+*/
+let onSuspiciousImage = null;
+/**
+* Screen rotation getter (set via setImageCaptureCallback)
+*/
+let getScreenRotation = null;
+/**
+* Redux store injected by the host (`setTrackingStore`). When present
+* together with `onTrackingRestarted`, `onXRFrame` dispatches
+* `poseReceived`/`poseLost`, the XR reference-space reset listener
+* dispatches `originReset`, and a `subscribeToSelector` translation
+* surface translates phase transitions back into the existing
+* `onTrackingLost` / `onTrackingRestarted` / `onTrackingRecovered`
+* callbacks. When the store is absent the tracking pipeline simply
+* no-ops.
+*/
+let trackingStore = null;
+/**
+* Unsubscribe handle returned by the phase subscription set up in
+* `initAR`. Cleared in `resetWebXRState` and on session-end so we never
+* leave dangling listeners on a stale store.
+*/
+let trackingPhaseUnsubscribe = null;
+/**
+* Callback for when tracking restarts (set via setTrackingCallbacks)
+*/
+let onTrackingRestarted = null;
+/**
+* Callback for when tracking is lost (set via setTrackingLostCallback)
+* Field Test Readiness Issue #3: Provide user feedback when tracking is lost
+*/
+let onTrackingLost = null;
+/**
+* Callback for when tracking recovers seamlessly without origin reset (Case 1).
+* Set via setTrackingRecoveredCallback.
+*/
+let onTrackingRecovered = null;
+/**
+* Depth sampler instance (created when AR session starts with depth callbacks)
+*/
+let depthSampler = null;
+/**
+* Callback for when a depth sample is captured (set via setDepthCaptureCallback)
+*/
+let onDepthCaptured = null;
+/**
+* Callback for when depth sensing is determined to be unavailable.
+* Field Test Readiness Issue #8: Notify user if depth was requested but not granted.
+*/
+let onDepthUnavailable = null;
+/**
+* Per-frame callback for custom updates (e.g., map overlay position).
+* Called every XR frame after pose updates but before render.
+*/
+let onFrameCallback = null;
+/**
+* CSS3D renderer manager for rendering DOM-based 3D objects (e.g., Leaflet map)
+* alongside the WebGL render. Created in initAR(), disposed in resetWebXRState().
+*/
+let css3dManager = null;
+/**
+* Camera blit capture instance for reading WebXR opaque camera textures.
+* Created when image capture starts, disposed when it stops.
+* @see docs/2026-02-06-bug-camera-frames-black.md
+*/
+let blitCapture = null;
+/**
+* Dedicated small blit target for per-depth-sample RGB lookups
+* (occupancy-grid port plan Iter 8). Separate from `blitCapture`: the JPEG
+* path resizes to (camera resolution ÷ divisor) while this one stays tiny —
+* only ≤ gridSize² positions are ever read from it, so 256×192 suffices and
+* keeps the 1 Hz readback stall negligible. Created lazily on the first
+* sample that needs it (no GPU allocation when the rgb option is off),
+* disposed by resetWebXRState().
+*/
+let depthRgbBlit = null;
+/** Readback size for the depth-RGB blit (plan §5: "e.g. 256×192 suffices"). */
+const DEPTH_RGB_BLIT_CONFIG = {
+	width: 256,
+	height: 192
+};
+/**
+* Latest WebXR camera texture, updated each frame when camera-access is enabled.
+* Acquired via Three.js's renderer.xr.getCameraTexture() API (ExternalTexture).
+* @see xr-camera-texture.ts
+*/
+let latestCameraTexture = null;
+/**
+* Latest camera frame dimensions from XRCamera (native resolution).
+* Used to dynamically resize the blit render target for full-quality captures.
+*/
+let latestCameraWidth = 0;
+let latestCameraHeight = 0;
+/**
+* Track whether camera-access diagnostic status has been logged.
+* Reset on each new session via resetWebXRState().
+*/
+let cameraAccessLoggedOnce = false;
+/**
+* Counter for throttled getCameraTexture diagnostic logging.
+* Only logs the first few null returns to avoid log spam.
+*/
+let getCameraTextureNullCount = 0;
+const GET_CAMERA_TEXTURE_LOG_THRESHOLD = 5;
+let currentArCrashIsolationOptions = { ...DEFAULT_RECORDING_OPTIONS.arCrashIsolation };
+/**
+* Dispose blit capture resources and clear the cached camera texture.
+* Shared by resetWebXRState() and stopImageCapture() to avoid duplication.
+*/
+function cleanupBlitResources() {
+	if (blitCapture) {
+		blitCapture.dispose();
+		blitCapture = null;
+	}
+	latestCameraTexture = null;
+}
+/**
+* Acquire a camera-color lookup for the current XR frame (passed to the
+* DepthSampler as `acquireRgbLookup`; called at most once per emitted
+* sample). Returns null — color-less points — when camera access or the
+* readback is unavailable; the blit instance lazily (re)creates itself so
+* a disposal elsewhere is self-healing.
+*/
+function acquireDepthRgbLookup() {
+	if (!renderer || !latestCameraTexture) return null;
+	depthRgbBlit ??= new CameraBlitCapture(DEPTH_RGB_BLIT_CONFIG);
+	const readback = depthRgbBlit.captureToPixels(renderer, latestCameraTexture);
+	return readback ? createRgbLookup(readback.pixels, readback.width, readback.height) : null;
+}
+/**
+* Extract the reset transform from an XRReferenceSpaceEvent-like object.
+*
+* Distinguishes three cases per OdometryTrackingRestartedPayload semantics:
+* - Transform property missing (older browsers) → returns `undefined`
+* - Transform property present but null (runtime can't determine delta) → returns `null`
+* - Transform property present with data → returns `ResetTransformData`
+*
+* This is a pure function extracted for testability.
+*
+* @param event - The event object, cast to a record with an optional transform property
+* @returns ResetTransformData, null, or undefined
+*/
+function extractResetTransformData(event) {
+	if (!("transform" in event)) return;
+	const transform = event.transform;
+	if (!transform) return null;
+	const pos = transform.position;
+	const ori = transform.orientation;
+	return {
+		position: [
+			pos.x,
+			pos.y,
+			pos.z
+		],
+		orientation: [
+			ori.x,
+			ori.y,
+			ori.z,
+			ori.w
+		]
+	};
+}
+/**
+* Extract pose data from an XRViewerPose.
+* Returns null if pose or views are unavailable.
+*
+* This is a pure function extracted for testability.
+*
+* @param pose - The XRViewerPose from frame.getViewerPose()
+* @returns ARPose with position and orientation, or null
+*/
+function extractPoseFromViewer(pose) {
+	if (!pose) return null;
+	const view = pose.views[0];
+	if (!view) return null;
+	const { position, orientation } = view.transform;
+	return {
+		position: {
+			x: position.x,
+			y: position.y,
+			z: position.z
+		},
+		orientation: {
+			x: orientation.x,
+			y: orientation.y,
+			z: orientation.z,
+			w: orientation.w
+		}
+	};
+}
+/**
+* Get the current raw AR pose from the latest XR frame.
+* This is updated every frame and should be called when GPS arrives
+* to get the AR pose at that moment.
+*
+* IMPORTANT: This returns the RAW pose from WebXR, NOT transformed
+* by any alignment matrix. This is what we record to the store.
+*
+* @returns The latest AR pose, or null if no pose available yet
+*/
+function getCurrentArPose() {
+	return latestArPose;
+}
+/**
+* Build XR session init options.
+* Extracted as a pure function for testability.
+*
+* @param rootElement - The DOM element for DOM overlay
+* @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
+*   depth-sensing, camera-access)
+* @param sessionFeatures - Opt-in standard WebXR features that are independent
+*   of crash isolation (currently `requestHitTest`)
+* @returns XRSessionInit options
+* @throws Error if rootElement is null
+*/
+function buildSessionOptions(rootElement, isolationOptions = {}, sessionFeatures = {}) {
+	if (!rootElement) throw new Error("App root element not found");
+	const normalizedOptions = validateArCrashIsolationOptions(isolationOptions);
+	const optionalFeatures = [];
+	const sessionOptions = { requiredFeatures: ["local-floor"] };
+	if (normalizedOptions.enableDomOverlay) {
+		optionalFeatures.push("dom-overlay");
+		sessionOptions.domOverlay = { root: rootElement };
+	}
+	if (normalizedOptions.enableDepthSensingFeature) {
+		optionalFeatures.push("depth-sensing");
+		Object.assign(sessionOptions, { depthSensing: {
+			usagePreference: ["cpu-optimized"],
+			dataFormatPreference: ["luminance-alpha", "float32"]
+		} });
+	}
+	if (normalizedOptions.enableCameraAccess) optionalFeatures.push("camera-access");
+	if (sessionFeatures.requestHitTest) optionalFeatures.push("hit-test");
+	if (optionalFeatures.length > 0) sessionOptions.optionalFeatures = optionalFeatures;
+	return sessionOptions;
+}
+/**
+* Check if WebXR immersive-ar is supported
+*/
+async function isWebXRSupported() {
+	if (!navigator.xr) return false;
+	try {
+		return await navigator.xr.isSessionSupported("immersive-ar");
+	} catch {
+		return false;
+	}
+}
+/**
+* Create the scene hierarchy with proper AR/GPS frame separation.
+* This is a pure function for testability.
+*
+* Hierarchy:
+*   scene (GPS world frame — NUE: X=North, Y=Up, Z=East)
+*   ├── ambientLight
+*   ├── directionalLight
+*   └── arWorldGroup (local space = NUE; receives alignment matrix)
+*       └── basisChangeNode ('webxr-to-nue', constant WEBXR_TO_NUE matrix)
+*           └── arpose (Object3D — AR pose; local space = WebXR)
+*               └── camera (PerspectiveCamera)
+*
+* basisChangeNode is a static scene-graph node that holds the WEBXR_TO_NUE
+* basis-change matrix permanently (matrixAutoUpdate=false). Moving it here
+* instead of composing it in applyAlignmentMatrix() keeps arWorldGroup's
+* local space in the **NUE axis convention** (X=North, Y=Up, Z=East), so no
+* WebXR↔NUE swizzle is needed for children.
+*
+* CAUTION — two NUE frames: arWorldGroup's local space is the *AR-odometry*
+* NUE frame, i.e. the **domain** of the alignment matrix, NOT the GPS-world
+* NUE frame of the scene root. Only content authored in AR-odometry
+* coordinates (e.g. the camera subtree) may be placed with raw local values.
+* GPS-world content (a lat/lon → NUE point) is expressed in the scene-root
+* frame and must be pre-multiplied by alignment⁻¹ before being used as a
+* local position under arWorldGroup — see createGpsAnchor and the
+* alignment-frame bug doc
+* (GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md).
+*
+* - Recording: arpose stays at identity; WebXRManager writes to camera.
+* - Replay: arpose receives recorded odomPosition/odomRotation;
+*   camera is owned by user controls (OrbitControls / FPS).
+*
+* @returns Object containing scene, arWorldGroup, arpose, and camera
+*/
+function createSceneHierarchy() {
+	const newScene = new THREE.Scene();
+	const newArWorldGroup = new THREE.Group();
+	newArWorldGroup.name = "ar-world";
+	newScene.add(newArWorldGroup);
+	const newBasisChangeNode = new THREE.Group();
+	newBasisChangeNode.name = SCENE_NODE.BASIS_CHANGE;
+	newBasisChangeNode.matrix.copy(WEBXR_TO_NUE);
+	newBasisChangeNode.matrixAutoUpdate = false;
+	newArWorldGroup.add(newBasisChangeNode);
+	const newArPose = new THREE.Object3D();
+	newArPose.name = "ar-pose";
+	newBasisChangeNode.add(newArPose);
+	const newCamera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, .01, 100);
+	newArPose.add(newCamera);
+	const ambientLight = new THREE.AmbientLight(16777215, .5);
+	newScene.add(ambientLight);
+	const directionalLight = new THREE.DirectionalLight(16777215, .8);
+	directionalLight.position.set(0, 10, 5);
+	newScene.add(directionalLight);
+	return {
+		scene: newScene,
+		arWorldGroup: newArWorldGroup,
+		arpose: newArPose,
+		camera: newCamera
+	};
+}
+/**
+* Initialize the AR session and Three.js renderer.
+* @param container - DOM element to host the AR canvas and CSS3D overlay.
+* @param isolationOptions - Crash-isolation diagnostic flags.
+* @param sessionFeatures - Opt-in standard WebXR features (e.g.
+*   `requestHitTest`) forwarded to the session negotiation.
+*/
+async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
+	if (!navigator.xr) throw new Error("WebXR not available");
+	if (renderer || xrSession) throw new Error("AR session already initialized — call endARSession() before initAR() again");
+	currentArCrashIsolationOptions = validateArCrashIsolationOptions(isolationOptions);
+	renderer = new THREE.WebGLRenderer({
+		antialias: true,
+		alpha: true
+	});
+	renderer.setPixelRatio(window.devicePixelRatio);
+	renderer.setSize(window.innerWidth, window.innerHeight);
+	renderer.xr.enabled = true;
+	container.insertBefore(renderer.domElement, container.firstChild);
+	if (currentArCrashIsolationOptions.enableCss3dRenderer) css3dManager = createCss3dRendererManager(container, window.innerWidth, window.innerHeight);
+	const hierarchy = createSceneHierarchy();
+	scene = hierarchy.scene;
+	arWorldGroup = hierarchy.arWorldGroup;
+	arPoseNode = hierarchy.arpose;
+	camera = hierarchy.camera;
+	const sessionOptions = buildSessionOptions(container, currentArCrashIsolationOptions, sessionFeatures);
+	xrSession = await navigator.xr.requestSession("immersive-ar", sessionOptions);
+	xrSession.addEventListener("end", () => {
+		log.info("Session ended");
+		if (trackingStore) trackingStore.dispatch(resetTracking());
+		xrSession = null;
+		latestArPose = null;
+	});
+	await renderer.xr.setSession(xrSession);
+	if (onTrackingRestarted && trackingStore) {
+		const store = trackingStore;
+		store.dispatch(resetTracking());
+		trackingPhaseUnsubscribe = subscribeToTrackingPhase(store);
+		const referenceSpace = renderer.xr.getReferenceSpace();
+		if (referenceSpace) referenceSpace.addEventListener("reset", (event) => {
+			const transformData = extractResetTransformData(event);
+			store.dispatch(originReset(transformData));
+			log.warn("XR reference space reset detected", transformData ? "(transform available)" : "(no transform)");
+		});
+	}
+	if (onDepthCaptured) depthSampler = new DepthSampler({
+		onSampleCaptured: onDepthCaptured,
+		getCurrentPose: getCurrentArPose,
+		acquireRgbLookup: acquireDepthRgbLookup,
+		onDepthUnavailable: onDepthUnavailable ?? void 0
+	});
+	renderer.setAnimationLoop(onXRFrame);
+	log.info("AR session started");
+}
+/**
+* Snapshot the current `DeviceOrientation` (with documented fallback
+* defaults) for inclusion in `poseReceived` payloads.
+*/
+function snapshotDeviceOrientation() {
+	const orientation = getLastDeviceOrientation();
+	return {
+		alpha: orientation?.alpha ?? 0,
+		beta: orientation?.beta ?? 0,
+		gamma: orientation?.gamma ?? 0,
+		absolute: orientation?.absolute ?? false
+	};
+}
+/**
+* Wire the tracking-slice → host-callbacks translation. The subscriber
+* runs synchronously inside each `dispatch`, so the host callbacks fire
+* in the same order as a direct invocation would.
+*
+* Translation rules (locked in by tracking-slice tests):
+*   - `tracking → lost`: clear `latestArPose` (drops in-flight GPS events)
+*     and call `onTrackingLost?.()`.
+*   - `lost → tracking` with `lastRestartedPayload !== null` (Case 2):
+*     call `onTrackingRestarted?.(payload)` then dispatch
+*     `clearLastRestartedPayload` so a subsequent loss cycle starts clean.
+*   - `lost → tracking` with payload null (Case 1: seamless recovery):
+*     call `onTrackingRecovered?.()`.
+*   - `initializing → tracking`: no callback (initial acquisition is not
+*     a restart — same behaviour as the manager).
+*/
+function subscribeToTrackingPhase(store) {
+	let prev = "initializing";
+	return store.subscribe(() => {
+		const next = selectTrackingPhase(store.getState());
+		if (next === prev) return;
+		const previous = prev;
+		prev = next;
+		if (previous === "tracking" && next === "lost") {
+			log.warn("Tracking lost");
+			latestArPose = null;
+			onTrackingLost?.();
+			return;
+		}
+		if (previous === "lost" && next === "tracking") {
+			const payload = selectLastRestartedPayload(store.getState());
+			if (payload !== null) {
+				log.info("Tracking restarted (origin reset)");
+				onTrackingRestarted?.(payload);
+				store.dispatch(clearLastRestartedPayload());
+			} else {
+				log.info("Tracking recovered (same coordinate frame)");
+				onTrackingRecovered?.();
+			}
+		}
+	});
+}
+/**
+* Dispatch the per-frame `poseReceived` / `poseLost` action into the
+* tracking slice. No-op when no store is bound or when tracking wiring
+* was not requested.
+*/
+function updateTrackingState(arPose) {
+	if (!trackingStore || !onTrackingRestarted) return;
+	if (arPose) trackingStore.dispatch(poseReceived({
+		pose: arPose,
+		sensorOrientation: snapshotDeviceOrientation()
+	}));
+	else trackingStore.dispatch(poseLost());
+}
+/**
+* Called each XR frame
+*/
+function onXRFrame(time, frame) {
+	if (!renderer || !scene || !camera || !frame) return;
+	const referenceSpace = renderer.xr.getReferenceSpace();
+	if (!referenceSpace) return;
+	const pose = frame.getViewerPose(referenceSpace);
+	const arPose = extractPoseFromViewer(pose);
+	updateTrackingState(arPose);
+	const dt = lastFrameTime === 0 ? 0 : (time - lastFrameTime) / 1e3;
+	const elapsed = time / 1e3;
+	lastFrameTime = time;
+	runFrameUpdates(dt, elapsed);
+	if (xrSession) runXrFrameUpdates({
+		frame,
+		referenceSpace,
+		session: xrSession,
+		dt,
+		elapsed
+	});
+	if (arPose) latestArPose = arPose;
+	latestCameraTexture = null;
+	if (currentArCrashIsolationOptions.enableCameraTextureAcquisition) {
+		const xrCamera = getXrCameraFromPose(pose);
+		if (shouldLogCameraAccessDiagnostic(pose, cameraAccessLoggedOnce, imageCaptureManager !== null)) {
+			cameraAccessLoggedOnce = true;
+			if (xrCamera) log.info("camera-access GRANTED — XRView.camera is available for blit capture");
+			else log.warn("camera-access NOT GRANTED — XRView.camera is undefined. Image capture will fall back to canvas.toBlob() which may produce black/empty frames in WebXR.");
+		}
+		if (xrCamera) {
+			const result = acquireCameraTexture(renderer, xrCamera);
+			if (result) {
+				latestCameraTexture = result.texture;
+				latestCameraWidth = result.width;
+				latestCameraHeight = result.height;
+			} else {
+				getCameraTextureNullCount++;
+				if (getCameraTextureNullCount <= GET_CAMERA_TEXTURE_LOG_THRESHOLD) log.warn(`getCameraTexture() returned null (occurrence ${getCameraTextureNullCount}/${GET_CAMERA_TEXTURE_LOG_THRESHOLD}). camera-access is granted but Three.js did not provide a texture.`);
+			}
+		}
+	}
+	if (imageCaptureManager) imageCaptureManager.onFrame(time);
+	if (depthSampler) {
+		const depthInfo = getDepthInfoFromFrame(frame, pose);
+		depthSampler.onFrame(time, depthInfo);
+	}
+	if (onFrameCallback) try {
+		onFrameCallback();
+	} catch (error) {
+		log.error("Error in onFrameCallback:", error);
+	}
+	renderer.render(scene, camera);
+	if (currentArCrashIsolationOptions.enableCss3dRenderer && css3dManager) css3dManager.render(scene, camera);
+}
+/**
+* Extract depth information from an XR frame.
+* Returns null if depth sensing is not available.
+*/
+function getDepthInfoFromFrame(frame, pose) {
+	const view = pose?.views[0];
+	if (!view) return null;
+	const xrFrame = frame;
+	if (typeof xrFrame.getDepthInformation !== "function") return null;
+	try {
+		const result = xrFrame.getDepthInformation(view);
+		if (!result) return null;
+		return wrapXRDepthInfo(result, view.projectionMatrix);
+	} catch {
+		return null;
+	}
+}
+/**
+* Get the current Three.js scene (for adding objects like map)
+*/
+function getScene() {
+	return scene;
+}
+/**
+* Get the AR world group (for adding AR-tracked content)
+* Content added here will be transformed by the alignment matrix.
+*/
+function getArWorldGroup() {
+	return arWorldGroup;
+}
+/**
+* Get the current camera
+*/
+function getCamera() {
+	return camera;
+}
+/**
+* Set the scene externally (for replay mode).
+* Allows non-WebXR code paths to register a scene so that modules
+* calling getScene() receive it.
+* @see docs/2026-02-19-replay-mode.md Risk R1
+*/
+function setScene(s) {
+	scene = s;
+}
+/**
+* Set the AR world group externally (for replay mode).
+* Allows non-WebXR code paths to register an arWorldGroup so that
+* applyAlignmentMatrix() and visualizers work correctly.
+* @see docs/2026-02-19-replay-mode.md Risk R1
+*/
+function setArWorldGroup(g) {
+	arWorldGroup = g;
+}
+/**
+* Set the camera externally (for replay mode).
+* Allows non-WebXR code paths to register a camera so that modules
+* calling getCamera() receive it.
+* @see docs/2026-02-19-replay-mode.md Risk R1
+*/
+function setCamera(c) {
+	camera = c;
+}
+/**
+* Get the arpose Object3D (intermediate node between arWorldGroup and camera).
+* Returns null before scene initialization.
+*/
+function getArPose() {
+	return arPoseNode;
+}
+/**
+* Set the arpose Object3D externally (for replay mode).
+* Allows non-WebXR code paths to register an arpose so that
+* store subscribers can update it with recorded odom data.
+*/
+function setArPose(a) {
+	arPoseNode = a;
+}
+/**
+* Apply an alignment matrix to the AR world group.
+*
+* The alignment matrix maps odometry positions in NUE space
+* to GPS world space (also NUE). It is applied directly to arWorldGroup
+* whose local space is NUE.
+*
+* The WebXR→NUE basis change lives permanently in basisChangeNode (a
+* child of arWorldGroup), so the full camera world transform is:
+*
+*   camera_world = arWorldGroup × basisChangeNode × arpose × camera_local
+*               = alignment × WEBXR_TO_NUE × arpose × camera_local
+*
+* This is mathematically identical to the previous composition
+* (alignment × WEBXR_TO_NUE applied directly to arWorldGroup.matrix),
+* but arWorldGroup's local space is now NUE: objects placed as children
+* of arWorldGroup use NUE coordinates directly ([1,0,0]=North, [0,0,1]=East).
+*
+* Replay note: arpose still lives in WebXR space (below basisChangeNode),
+* so nuePositionToWebXR() is still required when setting arpose.position.
+*
+* @param matrix - 16-element column-major matrix (gl-matrix mat4 format)
+*/
+function applyAlignmentMatrix(matrix) {
+	if (!arWorldGroup) {
+		log.warn("Cannot apply alignment - arWorldGroup not initialized");
+		return;
+	}
+	if (matrix.length !== 16) {
+		log.error("Invalid alignment matrix - expected 16 elements");
+		return;
+	}
+	arWorldGroup.matrix.fromArray(matrix);
+	arWorldGroup.matrixAutoUpdate = false;
+	arWorldGroup.updateMatrixWorld(true);
+}
+/**
+* Convert a position from internal NUE convention (X=North, Y=Up, Z=East)
+* to WebXR local-floor convention (X=East, Y=Up, Z=South).
+*
+* Delegates to the canonical library implementation (nueToWebXR).
+* Accepts `readonly number[]` for call-site convenience.
+*
+* NUE [n, u, e] → WebXR [e, u, -n]
+*/
+function nuePositionToWebXR(nue) {
+	return nueToWebXR(nue);
+}
+/**
+* Convert a quaternion from internal NUE convention to WebXR local-floor convention.
+*
+* Delegates to the canonical library implementation (nueQuaternionToWebXR).
+* Accepts `readonly number[]` for call-site convenience.
+*
+* NUE [x, y, z, w] → WebXR [z, y, -x, w]
+*/
+function nueQuaternionToWebXR$1(nue) {
+	return nueQuaternionToWebXR(nue);
+}
+/**
+* End the current XR session and clean up all resources.
+*
+* Stops the animation loop, ends the XR session, then delegates the full
+* teardown to {@link resetWebXRState} so every module-level reference is
+* cleared (renderer/scene/camera, image-capture, depth, the tracking-phase
+* subscription, the frame-update registry, diagnostics, blit resources).
+* This is the production cleanup path — call it when the AR experience is
+* finished.
+*/
+async function endARSession() {
+	if (renderer) renderer.setAnimationLoop(null);
+	try {
+		if (xrSession) await xrSession.end();
+	} finally {
+		resetWebXRState();
+	}
+}
+/**
+* Set up image capture callbacks.
+* Call this before starting image capture to wire up the callback handlers.
+*
+* @param onCaptured - Called when an image is successfully captured
+* @param screenRotationGetter - Returns current device screen rotation (0, 90, 180, 270)
+* @param onFailed - Optional callback for when image capture fails (e.g., low memory)
+* @param onSuspicious - Optional callback for when a captured image appears black/empty
+*/
+function setImageCaptureCallback(onCaptured, screenRotationGetter, onFailed, onSuspicious) {
+	onImageCaptured = onCaptured;
+	getScreenRotation = screenRotationGetter;
+	onCaptureFailed = onFailed ?? null;
+	onSuspiciousImage = onSuspicious ?? null;
+}
+/**
+* Start capturing images during recording.
+* Must call setImageCaptureCallback first.
+*
+* @param config - Optional capture configuration. Accepts the whole user
+*   image-options section (`intervalMs`, `quality`, `resolutionDivisor`; any
+*   extra keys such as `enabled` are ignored). Passing the section as one
+*   object means a newly-added option flows through without editing this seam
+*   — see `2026-06-12-payload-rebuild-field-drop-audit.md` (F3).
+*/
+function startImageCapture(config) {
+	if (!renderer) {
+		log.warn("Cannot start image capture - renderer not initialized");
+		return;
+	}
+	if (!onImageCaptured || !getScreenRotation) {
+		log.warn("Cannot start image capture - callbacks not set");
+		return;
+	}
+	if (imageCaptureManager || blitCapture) {
+		log.warn("Image capture already running - stopping previous session");
+		stopImageCapture();
+	}
+	const callbacks = {
+		getCurrentPose: getCurrentArPose,
+		getScreenRotation,
+		onCaptured: onImageCaptured,
+		onCaptureFailed: onCaptureFailed ?? void 0,
+		onSuspiciousImage: onSuspiciousImage ?? void 0
+	};
+	const mergedConfig = {
+		...DEFAULT_CAPTURE_CONFIG,
+		...config
+	};
+	blitCapture = new CameraBlitCapture();
+	const currentRenderer = renderer;
+	const divisor = mergedConfig.resolutionDivisor;
+	callbacks.captureFrame = async (quality) => {
+		if (!blitCapture || !latestCameraTexture) {
+			const canvas = currentRenderer.domElement;
+			return new Promise((resolve) => {
+				canvas.toBlob((blob) => resolve(blob ? {
+					blob,
+					width: canvas.width,
+					height: canvas.height
+				} : null), "image/jpeg", quality);
+			});
+		}
+		if (latestCameraWidth > 0 && latestCameraHeight > 0) {
+			const target = computeCaptureSize(latestCameraWidth, latestCameraHeight, divisor);
+			blitCapture.resizeIfNeeded(target.width, target.height);
+		}
+		const blob = await blitCapture.captureToBlob(currentRenderer, latestCameraTexture, quality);
+		if (!blob) return null;
+		return {
+			blob,
+			width: blitCapture.getWidth(),
+			height: blitCapture.getHeight()
+		};
+	};
+	log.info(`Blit capture pipeline initialized (resolutionDivisor=${divisor})`);
+	imageCaptureManager = new ImageCaptureManager(renderer.domElement, callbacks, mergedConfig);
+	imageCaptureManager.start();
+	log.info("Image capture started");
+}
+/**
+* Stop capturing images.
+*/
+function stopImageCapture() {
+	if (imageCaptureManager) {
+		imageCaptureManager.stop();
+		log.info(`Image capture stopped (${imageCaptureManager.getFrameCount()} frames captured)`);
+		imageCaptureManager = null;
+	}
+	cleanupBlitResources();
+}
+/**
+* Get the current image capture frame count.
+*/
+function getImageCaptureFrameCount() {
+	return imageCaptureManager?.getFrameCount() ?? 0;
+}
+/**
+* Inject the Redux store used by the tracking-state slice pipeline.
+*
+* MUST be called before `initAR()` whenever the host also wires tracking
+* callbacks via `setTrackingCallbacks`. Without a store the tracking
+* pipeline silently no-ops.
+*
+* @param store — any store satisfying {@link TrackingSubscribableStore}.
+*   `null` clears the binding (useful for teardown in tests).
+*/
+function setTrackingStore(store) {
+	if (trackingPhaseUnsubscribe) {
+		trackingPhaseUnsubscribe();
+		trackingPhaseUnsubscribe = null;
+	}
+	trackingStore = store;
+}
+/**
+* Set up tracking state callbacks.
+* Call this BEFORE initAR() to enable tracking restart detection.
+*
+* @param onRestarted - Called when tracking restarts after being lost
+*/
+function setTrackingCallbacks(onRestarted) {
+	onTrackingRestarted = onRestarted;
+}
+/**
+* Set a callback for when AR tracking is lost.
+* Call this BEFORE initAR() to enable tracking loss notifications.
+* Field Test Readiness Issue #3: Provide user feedback when tracking is lost.
+*
+* @param callback - Called when tracking is lost (pose becomes null)
+*/
+function setTrackingLostCallback(callback) {
+	onTrackingLost = callback;
+}
+/**
+* Set a callback for when AR tracking recovers seamlessly (Case 1: same coordinate frame).
+* Call this BEFORE initAR() to enable seamless recovery notifications.
+*
+* @param callback - Called when tracking recovers without origin reset
+*/
+function setTrackingRecoveredCallback(callback) {
+	onTrackingRecovered = callback;
+}
+/**
+* Set up depth capture callback.
+* Call this BEFORE initAR() to enable depth sampling.
+*
+* @param onCaptured - Called when a depth sample is captured
+* @param onUnavailable - Called once if depth is unavailable after threshold
+*/
+function setDepthCaptureCallback(onCaptured, onUnavailable) {
+	onDepthCaptured = onCaptured;
+	onDepthUnavailable = onUnavailable ?? null;
+}
+/**
+* Start depth sampling during recording.
+* Must call setDepthCaptureCallback before initAR.
+*
+* @param config - optional sampler overrides (typically the user's
+*   `depth.intervalMs`/`depth.gridSize` recording options); applied via
+*   `DepthSampler.updateConfig` before sampling starts. Without this the
+*   sampler's own defaults apply — the settings knobs were dead before
+*   this parameter existed (occupancy-grid port plan, Iter 6).
+*/
+function startDepthCapture(config) {
+	if (!depthSampler) {
+		log.warn("Cannot start depth capture - sampler not initialized");
+		return;
+	}
+	if (config) depthSampler.updateConfig(config);
+	depthSampler.start();
+	log.info(`Depth capture started (interval: ${depthSampler.getConfig().intervalMs}ms, grid: ${depthSampler.getConfig().gridSize}×${depthSampler.getConfig().gridSize})`);
+}
+/**
+* Stop depth sampling.
+*/
+function stopDepthCapture() {
+	if (depthSampler) {
+		const count = depthSampler.getSampleCount();
+		depthSampler.stop();
+		log.info(`Depth capture stopped (${count} samples captured)`);
+	}
+}
+/**
+* Get the current depth sample count.
+*/
+function getDepthSampleCount() {
+	return depthSampler?.getSampleCount() ?? 0;
+}
+/**
+* Set a per-frame callback for custom updates.
+* The callback is invoked every XR frame after pose updates but before render.
+* Useful for updating elements that need to follow the camera smoothly
+* (e.g., map overlay position).
+*
+* @param callback - Function to call each frame, or null to clear
+*/
+function setFrameCallback(callback) {
+	onFrameCallback = callback;
+}
+/**
+* Get the CSS3D renderer manager for live AR mode.
+* Returns null if no AR session is active or CSS3D was not created.
+*/
+function getLiveCss3dManager() {
+	return css3dManager;
+}
+//#endregion
+export { setTrackingLostCallback as A, setArWorldGroup as C, setImageCaptureCallback as D, setFrameCallback as E, startImageCapture as F, stopDepthCapture as I, stopImageCapture as L, setTrackingStore as M, shouldLogCameraAccessDiagnostic as N, setScene as O, startDepthCapture as P, setArPose as S, setDepthCaptureCallback as T, isWebXRSupported as _, extractPoseFromViewer as a, nueQuaternionToWebXR$1 as b, getArWorldGroup as c, getDepthSampleCount as d, getImageCaptureFrameCount as f, initAR as g, getXrCameraFromPose as h, endARSession as i, setTrackingRecoveredCallback as j, setTrackingCallbacks as k, getCamera as l, getScene as m, buildSessionOptions as n, extractResetTransformData as o, getLiveCss3dManager as p, createSceneHierarchy as r, getArPose as s, applyAlignmentMatrix as t, getCurrentArPose as u, isXRCameraLike as v, setCamera as w, resetWebXRState as x, nuePositionToWebXR as y };