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

package/dist/ar/webxr-session.js

@@ -1,970 +1,2 @@
-import { createLogger } from "../utils/logger.js";
-import { CameraBlitCapture, computeCaptureSize } from "./camera-blit-capture.js";
-import { getLastDeviceOrientation } from "../state/gps-event-coordinator.js";
-import { DepthSampler } from "./depth-sampler.js";
-import { clearFrameUpdates, runFrameUpdates } from "./frame-loop.js";
-import { clearXrFrameUpdates, runXrFrameUpdates } from "./xr-frame-loop.js";
-import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-BbdqhqY6.js";
-import { DEFAULT_CAPTURE_CONFIG, ImageCaptureManager } from "./image-capture.js";
-import { clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectTrackingPhase } from "../state/tracking-slice.js";
-import { acquireCameraTexture } from "./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 "./scene-node-names.js";
-import { createCss3dRendererManager } from "../visualization/css3d-renderer-manager.js";
-import * as THREE from "three";
-import { nueQuaternionToWebXR as nueQuaternionToWebXR$1, nueToWebXR } from "gps-plus-slam-js";
-//#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;
-	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;
-/**
-* 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;
-}
-/**
-* 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,
-		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) {
-	if (!pose || !pose.views[0]) return null;
-	const xrFrame = frame;
-	if (typeof xrFrame.getDepthInformation !== "function") return null;
-	try {
-		return xrFrame.getDepthInformation(pose.views[0]) ?? null;
-	} 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(nue) {
-	return nueQuaternionToWebXR$1(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 (intervalMs, quality)
-* @param resolutionDivisor - Resolution divisor: 1 = full, 2 = half, 4 = quarter (default: 1)
-*/
-function startImageCapture(config, resolutionDivisor = 1) {
-	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
-	};
-	blitCapture = new CameraBlitCapture();
-	const currentRenderer = renderer;
-	const divisor = resolutionDivisor;
-	callbacks.captureFrame = async (quality) => {
-		if (!blitCapture || !latestCameraTexture) return new Promise((resolve) => {
-			currentRenderer.domElement.toBlob((blob) => resolve(blob), "image/jpeg", quality);
-		});
-		if (latestCameraWidth > 0 && latestCameraHeight > 0) {
-			const target = computeCaptureSize(latestCameraWidth, latestCameraHeight, divisor);
-			blitCapture.resizeIfNeeded(target.width, target.height);
-		}
-		return blitCapture.captureToBlob(currentRenderer, latestCameraTexture, quality);
-	};
-	log.info(`Blit capture pipeline initialized (resolutionDivisor=${divisor})`);
-	const mergedConfig = {
-		...DEFAULT_CAPTURE_CONFIG,
-		...config
-	};
-	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.
-*/
-function startDepthCapture() {
-	if (!depthSampler) {
-		log.warn("Cannot start depth capture - sampler not initialized");
-		return;
-	}
-	depthSampler.start();
-	log.info("Depth capture started");
-}
-/**
-* 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
+import { A as setTrackingLostCallback, C as setArWorldGroup, D as setImageCaptureCallback, E as setFrameCallback, F as startImageCapture, I as stopDepthCapture, L as stopImageCapture, M as setTrackingStore, N as shouldLogCameraAccessDiagnostic, O as setScene, P as startDepthCapture, S as setArPose, T as setDepthCaptureCallback, _ as isWebXRSupported, a as extractPoseFromViewer, b as nueQuaternionToWebXR, c as getArWorldGroup, d as getDepthSampleCount, f as getImageCaptureFrameCount, g as initAR, h as getXrCameraFromPose, i as endARSession, j as setTrackingRecoveredCallback, k as setTrackingCallbacks, l as getCamera, m as getScene, n as buildSessionOptions, o as extractResetTransformData, p as getLiveCss3dManager, r as createSceneHierarchy, s as getArPose, t as applyAlignmentMatrix, u as getCurrentArPose, v as isXRCameraLike, w as setCamera, x as resetWebXRState, y as nuePositionToWebXR } from "../webxr-session-QhcSSub5.js";
 export { applyAlignmentMatrix, buildSessionOptions, createSceneHierarchy, endARSession, extractPoseFromViewer, extractResetTransformData, getArPose, getArWorldGroup, getCamera, getCurrentArPose, getDepthSampleCount, getImageCaptureFrameCount, getLiveCss3dManager, getScene, getXrCameraFromPose, initAR, isWebXRSupported, isXRCameraLike, nuePositionToWebXR, nueQuaternionToWebXR, resetWebXRState, setArPose, setArWorldGroup, setCamera, setDepthCaptureCallback, setFrameCallback, setImageCaptureCallback, setScene, setTrackingCallbacks, setTrackingLostCallback, setTrackingRecoveredCallback, setTrackingStore, shouldLogCameraAccessDiagnostic, startDepthCapture, startImageCapture, stopDepthCapture, stopImageCapture };