gps-plus-slam-app-framework 1.0.0

package/dist/ar/replay-scene.js

@@ -0,0 +1,325 @@
+import { createLogger } from "../utils/logger.js";
+import { createCss3dRendererManager } from "../visualization/css3d-renderer-manager.js";
+import { createSceneHierarchy, setArPose, setArWorldGroup, setCamera, setScene } from "./webxr-session.js";
+import { createCameraFollower } from "../visualization/camera-follower.js";
+import { createAlignmentLerper } from "../visualization/alignment-lerper.js";
+import { createGpsCompassCubes } from "../visualization/gps-compass-cubes.js";
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+//#region ../src/ar/replay-scene.ts
+/**
+* Replay Scene Module
+*
+* Sets up a standard Three.js rendering environment for desktop replay mode
+* (no WebXR). Uses createSceneHierarchy() for the scene graph, then
+* reparents the camera to the scene root (Issue 5 fix) so orbit and FPS
+* controls operate in a stable world-space frame, unaffected by the
+* alignment matrix on arWorldGroup or odom pose updates on arpose.
+*
+* Registers the scene objects with webxr-session.ts module-global getters
+* (Risk R1 fix) so existing visualizers work without modification.
+*
+* Camera modes:
+*   - orbit (default): OrbitControls — click-drag orbit + scroll zoom
+*   - fps: Drag-based mouse look + WASD — left-click-drag rotates camera,
+*     WASD moves, Space/Shift for vertical movement (Issue 6)
+*
+* @see docs/2026-02-19-replay-mode.md Issue 4, Issue 5, Risk R1, R5
+* @see docs/2026-03-12-user-feedback.md Issue 5
+*/
+const log = createLogger("ReplayScene");
+let state = null;
+/** WASD key tracking for FPS mode */
+const keysPressed = {};
+/** Movement speed in world-units per second (≈0.15 per frame × 60 fps). */
+const FPS_MOVE_SPEED = 9;
+/** Reusable scratch vectors — avoids per-frame allocations in updateFpsMovement. */
+const _direction = new THREE.Vector3();
+const _right = new THREE.Vector3();
+const MOUSE_SENSITIVITY = .002;
+const MAX_PITCH = Math.PI / 2 - .01;
+let isDragging = false;
+let lastPointerX = 0;
+let lastPointerY = 0;
+let fpsPitch = 0;
+let fpsYaw = 0;
+const _euler = new THREE.Euler(0, 0, 0, "YXZ");
+let savedTabindex = { state: "none" };
+function onKeyDown(e) {
+	keysPressed[e.code] = true;
+}
+function onKeyUp(e) {
+	keysPressed[e.code] = false;
+}
+function updateFpsMovement(dt) {
+	if (!state || state.cameraMode !== "fps") return;
+	const speed = FPS_MOVE_SPEED * dt;
+	const camera = state.camera;
+	camera.getWorldDirection(_direction);
+	_right.crossVectors(_direction, camera.up).normalize();
+	if (keysPressed["KeyW"]) camera.position.addScaledVector(_direction, speed);
+	if (keysPressed["KeyS"]) camera.position.addScaledVector(_direction, -speed);
+	if (keysPressed["KeyA"]) camera.position.addScaledVector(_right, -speed);
+	if (keysPressed["KeyD"]) camera.position.addScaledVector(_right, speed);
+	if (keysPressed["Space"]) camera.position.y += speed;
+	if (keysPressed["ShiftLeft"] || keysPressed["ShiftRight"]) camera.position.y -= speed;
+}
+/**
+* Initialize the replay scene with a standard Three.js renderer.
+*
+* - Creates the scene hierarchy via createSceneHierarchy()
+* - Reparents camera from arWorldGroup to scene root (Risk R5)
+* - Creates a WebGLRenderer WITHOUT WebXR
+* - Registers scene with module-global getters (Risk R1)
+* - Inserts canvas into the provided container
+* - Starts a requestAnimationFrame render loop
+* - Sets up OrbitControls as default camera mode
+*
+* @param container - DOM element to insert the canvas into
+* @returns Scene state object for downstream use
+* @throws If already initialized (call disposeReplayScene first)
+*/
+function initReplayScene(container) {
+	if (state) throw new Error("Replay scene already initialized. Call disposeReplayScene() first.");
+	const { scene, arWorldGroup, arpose, camera } = createSceneHierarchy();
+	scene.add(camera);
+	camera.position.set(0, 5, 10);
+	camera.lookAt(0, 0, 0);
+	const renderer = new THREE.WebGLRenderer({
+		antialias: true,
+		alpha: true
+	});
+	renderer.setPixelRatio(window.devicePixelRatio);
+	const width = container.clientWidth || window.innerWidth;
+	const height = container.clientHeight || window.innerHeight;
+	renderer.setSize(width, height);
+	renderer.xr.enabled = false;
+	container.appendChild(renderer.domElement);
+	const css3dManager = createCss3dRendererManager(container, width, height);
+	setScene(scene);
+	setArWorldGroup(arWorldGroup);
+	setArPose(arpose);
+	setCamera(camera);
+	const orbitControls = new OrbitControls(camera, renderer.domElement);
+	orbitControls.enableDamping = true;
+	orbitControls.target.set(0, 0, 0);
+	const alignmentLerper = createAlignmentLerper(arWorldGroup);
+	const cameraFollower = createCameraFollower(scene);
+	createGpsCompassCubes(cameraFollower.object3D);
+	state = {
+		scene,
+		arWorldGroup,
+		camera,
+		renderer,
+		orbitControls,
+		cameraMode: "orbit",
+		rAFId: startRenderLoop(renderer, scene, camera, orbitControls, css3dManager),
+		container,
+		cameraFollower,
+		alignmentLerper,
+		css3dManager
+	};
+	log.info("Replay scene initialized");
+	return {
+		scene,
+		arWorldGroup,
+		camera,
+		renderer
+	};
+}
+/**
+* Dispose the replay scene, cleaning up all resources.
+*
+* - Cancels the rAF render loop
+* - Disposes renderer (frees GPU resources)
+* - Disposes camera controls
+* - Removes canvas from DOM
+* - Clears module-global scene references
+*
+* Safe to call multiple times (idempotent).
+*/
+function disposeReplayScene() {
+	if (!state) return;
+	cancelAnimationFrame(state.rAFId);
+	state.alignmentLerper.dispose();
+	state.cameraFollower.dispose();
+	state.css3dManager.dispose();
+	state.orbitControls.dispose();
+	if (state.cameraMode === "fps") removeFpsListeners();
+	state.container.removeEventListener("keydown", onKeyDown);
+	state.container.removeEventListener("keyup", onKeyUp);
+	restoreTabindex();
+	if (state.renderer.domElement.parentElement) state.renderer.domElement.parentElement.removeChild(state.renderer.domElement);
+	state.renderer.dispose();
+	setScene(null);
+	setArWorldGroup(null);
+	setArPose(null);
+	setCamera(null);
+	state = null;
+	log.info("Replay scene disposed");
+}
+/**
+* Get the current replay scene state, or null if not initialized.
+*/
+function getReplayState() {
+	return state;
+}
+/** Scratch vector for orbit-target follow delta — avoids per-call allocation. */
+const _targetDelta = new THREE.Vector3();
+/**
+* Update the OrbitControls target position and translate the camera
+* by the same delta so the orbit viewing relationship is preserved.
+*
+* OrbitControls.update() does NOT automatically move the camera when
+* the target changes — it recomputes offset = camera.position - target
+* each frame, which is a no-op without user input. Without explicit
+* camera translation, the camera would sit still while the trajectory
+* moves away. Moving the camera by the target delta keeps the viewing
+* angle and distance constant as the trajectory progresses.
+*
+* Call this as new odom poses are replayed so the orbit camera
+* auto-follows the recorded trajectory.
+*
+* No-op if not initialized.
+*/
+function updateOrbitTarget(position) {
+	if (!state) return;
+	_targetDelta.copy(position).sub(state.orbitControls.target);
+	state.camera.position.add(_targetDelta);
+	state.orbitControls.target.copy(position);
+}
+/**
+* Get the current camera control mode.
+* Returns 'orbit' if not initialized.
+*/
+function getCameraMode() {
+	return state?.cameraMode ?? "orbit";
+}
+/**
+* Get the camera follower's Object3D, or null if the replay scene
+* is not initialized. Use this to attach children (e.g., map mesh)
+* that should track the camera's position but stay GPS-aligned.
+*/
+function getCameraFollower() {
+	return state?.cameraFollower.object3D ?? null;
+}
+/**
+* Get the alignment lerper, or null if not initialized.
+* Used by replay-mode to route store-subscriber alignment updates
+* through the lerper instead of applying them directly.
+*/
+function getAlignmentLerper() {
+	return state?.alignmentLerper ?? null;
+}
+/**
+* Get the CSS3D renderer manager, or null if not initialized.
+* Used for external resize handling or to verify the CSS3D layer exists.
+*/
+function getCss3dManager() {
+	return state?.css3dManager ?? null;
+}
+/**
+* Toggle between orbit and FPS camera modes.
+*
+* - orbit → fps: Disables OrbitControls, creates and enables
+*   PointerLockControls + WASD keyboard handler
+* - fps → orbit: Disables PointerLockControls, re-enables OrbitControls
+*
+* No-op if not initialized.
+*/
+function toggleCameraMode() {
+	if (!state) return;
+	if (state.cameraMode === "orbit") switchToFps();
+	else switchToOrbit();
+}
+function startRenderLoop(renderer, scene, camera, orbitControls, css3dManager) {
+	const timer = new THREE.Timer();
+	function animate() {
+		if (!state) return;
+		state.rAFId = requestAnimationFrame(animate);
+		timer.update();
+		const dt = timer.getDelta();
+		if (state.cameraMode === "orbit") orbitControls.update();
+		else updateFpsMovement(dt);
+		state.alignmentLerper.update(dt);
+		state.cameraFollower.update(state.camera, dt);
+		renderer.render(scene, camera);
+		css3dManager.render(scene, camera);
+	}
+	return requestAnimationFrame(animate);
+}
+function onPointerDown(e) {
+	if (e.button !== 0) return;
+	isDragging = true;
+	lastPointerX = e.clientX;
+	lastPointerY = e.clientY;
+}
+function onPointerMove(e) {
+	if (!isDragging || !state) return;
+	const dx = e.clientX - lastPointerX;
+	const dy = e.clientY - lastPointerY;
+	lastPointerX = e.clientX;
+	lastPointerY = e.clientY;
+	fpsYaw -= dx * MOUSE_SENSITIVITY;
+	fpsPitch -= dy * MOUSE_SENSITIVITY;
+	fpsPitch = Math.max(-MAX_PITCH, Math.min(MAX_PITCH, fpsPitch));
+	_euler.set(fpsPitch, fpsYaw, 0, "YXZ");
+	state.camera.quaternion.setFromEuler(_euler);
+}
+function onPointerUp() {
+	isDragging = false;
+}
+/** Restore the container's tabindex to its pre-FPS-mode value. */
+function restoreTabindex() {
+	if (!state || savedTabindex.state === "none") return;
+	if (savedTabindex.value === void 0) state.container.removeAttribute("tabindex");
+	else if (savedTabindex.value !== state.container.getAttribute("tabindex")) state.container.setAttribute("tabindex", savedTabindex.value);
+	savedTabindex = { state: "none" };
+}
+function addFpsListeners() {
+	if (!state) return;
+	const canvas = state.renderer.domElement;
+	canvas.addEventListener("pointerdown", onPointerDown);
+	canvas.addEventListener("pointermove", onPointerMove);
+	canvas.addEventListener("pointerup", onPointerUp);
+}
+function removeFpsListeners() {
+	if (!state) return;
+	const canvas = state.renderer.domElement;
+	canvas.removeEventListener("pointerdown", onPointerDown);
+	canvas.removeEventListener("pointermove", onPointerMove);
+	canvas.removeEventListener("pointerup", onPointerUp);
+	isDragging = false;
+}
+function switchToFps() {
+	if (!state) return;
+	state.orbitControls.enabled = false;
+	_euler.setFromQuaternion(state.camera.quaternion, "YXZ");
+	fpsYaw = _euler.y;
+	fpsPitch = _euler.x;
+	addFpsListeners();
+	const currentTabindex = state.container.hasAttribute("tabindex") ? state.container.getAttribute("tabindex") ?? "" : void 0;
+	savedTabindex = {
+		state: "saved",
+		value: currentTabindex
+	};
+	if (currentTabindex === void 0) state.container.setAttribute("tabindex", "0");
+	state.container.focus();
+	state.container.addEventListener("keydown", onKeyDown);
+	state.container.addEventListener("keyup", onKeyUp);
+	state.cameraMode = "fps";
+	log.info("Switched to FPS camera mode");
+}
+function switchToOrbit() {
+	if (!state || state.cameraMode === "orbit") return;
+	state.cameraMode = "orbit";
+	removeFpsListeners();
+	state.container.removeEventListener("keydown", onKeyDown);
+	state.container.removeEventListener("keyup", onKeyUp);
+	restoreTabindex();
+	state.orbitControls.enabled = true;
+	for (const k of Object.keys(keysPressed)) keysPressed[k] = false;
+	log.info("Switched to Orbit camera mode");
+}
+//#endregion
+export { disposeReplayScene, getAlignmentLerper, getCameraFollower, getCameraMode, getCss3dManager, getReplayState, initReplayScene, toggleCameraMode, updateOrbitTarget };

package/dist/ar/scene-node-names.d.ts

@@ -0,0 +1,2 @@
+import { t as SCENE_NODE } from "../scene-node-names-DPsaE2z3.js";
+export { SCENE_NODE };

package/dist/ar/scene-node-names.js

@@ -0,0 +1,16 @@
+//#region ../src/ar/scene-node-names.ts
+/**
+* Scene-graph node name constants.
+*
+* Used in .name assignments and getObjectByName() lookups.
+* Centralised here (R4) so a rename is a single-point change
+* with compile-time safety instead of grep-and-replace.
+*/
+const SCENE_NODE = {
+	/** Basis-change node (WebXR → NUE coordinate system) */
+	BASIS_CHANGE: "webxr-to-nue",
+	/** Camera follower node (GPS-world-aligned, tracks camera position) */
+	CAMERA_FOLLOWER: "camera-follower"
+};
+//#endregion
+export { SCENE_NODE };

package/dist/ar/tracking-state.d.ts

@@ -0,0 +1,2 @@
+import { a as TrackingStateManager, i as TrackingStateCallbacks, n as ResetTransformData, r as TrackingState, t as DeviceOrientation } from "../tracking-state-B9QfuZCg.js";
+export { DeviceOrientation, ResetTransformData, TrackingState, TrackingStateCallbacks, TrackingStateManager };

package/dist/ar/tracking-state.js

@@ -0,0 +1,164 @@
+import { createLogger } from "../utils/logger.js";
+import { extractOdomPosition } from "../state/recording-coordinator.js";
+//#region ../src/ar/tracking-state.ts
+/**
+* Tracking State Manager
+*
+* Detects AR tracking loss and restart events, maintaining state
+* about the last valid odometry pose for alignment correction.
+*
+* ARCHITECTURE NOTE: See docs/architecture-ar-gps-pose-separation.md
+*
+* When WebXR tracking is lost and restarted, the odometry frame resets
+* to a new origin. To maintain GPS+AR alignment, we need to:
+* 1. Store the last valid pose before tracking was lost
+* 2. Detect when tracking resumes with a new pose
+* 3. Dispatch odometryTrackingRestarted with both poses for offset calculation
+*/
+const log = createLogger("TrackingState");
+/**
+* Possible tracking states
+*/
+let TrackingState = /* @__PURE__ */ function(TrackingState) {
+	/** AR session started but no pose received yet */
+	TrackingState["INITIALIZING"] = "initializing";
+	/** Actively receiving valid poses */
+	TrackingState["TRACKING"] = "tracking";
+	/** Pose became unavailable (tracking lost) */
+	TrackingState["LOST"] = "lost";
+	return TrackingState;
+}({});
+/**
+* Manages AR tracking state and detects loss/restart events.
+*/
+var TrackingStateManager = class {
+	state = "initializing";
+	lastValidPose = null;
+	lastSensorOrientation = null;
+	lostFrameCount = 0;
+	originResetDuringLoss = false;
+	resetTransform = void 0;
+	callbacks;
+	constructor(callbacks) {
+		this.callbacks = callbacks;
+	}
+	/**
+	* Get current tracking state.
+	*/
+	getState() {
+		return this.state;
+	}
+	/**
+	* Get the last valid AR pose (before tracking was lost).
+	*/
+	getLastValidPose() {
+		return this.lastValidPose;
+	}
+	/**
+	* Get count of consecutive frames without pose (during LOST state).
+	*/
+	getLostFrameCount() {
+		return this.lostFrameCount;
+	}
+	/**
+	* Flag that an XRReferenceSpace reset event occurred during tracking loss.
+	* Only meaningful while in LOST state — ignored otherwise.
+	*
+	* @param transform — Serialized XRReferenceSpaceEvent.transform (post-reset
+	*   origin in pre-reset coordinates).  Pass `null` when the event's
+	*   transform property is null (runtime can't determine delta).
+	*   Omit entirely for backwards-compat with callers that don't have it.
+	*/
+	markOriginReset(transform) {
+		if (this.state === "lost") {
+			this.originResetDuringLoss = true;
+			this.resetTransform = transform;
+		}
+	}
+	/**
+	* Called when a valid pose is received from WebXR.
+	*/
+	onPoseReceived(pose) {
+		if (this.state === "lost") this.handleTrackingRestarted(pose);
+		this.state = "tracking";
+		this.lastValidPose = pose;
+		this.lastSensorOrientation = this.callbacks.getDeviceOrientation();
+		this.lostFrameCount = 0;
+	}
+	/**
+	* Called when pose is null/unavailable from WebXR.
+	*/
+	onPoseLost() {
+		this.lostFrameCount++;
+		if (this.state === "tracking") {
+			this.state = "lost";
+			this.callbacks.onTrackingLost();
+			log.warn("AR tracking lost");
+		}
+	}
+	/**
+	* Reset the manager to initial state.
+	* Call this when starting a new session.
+	*/
+	reset() {
+		this.state = "initializing";
+		this.lastValidPose = null;
+		this.lastSensorOrientation = null;
+		this.lostFrameCount = 0;
+		this.originResetDuringLoss = false;
+		this.resetTransform = void 0;
+	}
+	/**
+	* Handle the transition from LOST to TRACKING (restart detected).
+	*/
+	handleTrackingRestarted(newPose) {
+		const hadReset = this.originResetDuringLoss;
+		const savedResetTransform = this.resetTransform;
+		this.originResetDuringLoss = false;
+		this.resetTransform = void 0;
+		if (!hadReset) {
+			log.info("AR tracking recovered (same coordinate frame)");
+			this.callbacks.onTrackingRecovered?.();
+			return;
+		}
+		if (!this.lastValidPose) {
+			log.warn("Tracking restarted but no previous pose available");
+			return;
+		}
+		const currentSensorOrientation = this.callbacks.getDeviceOrientation();
+		const lastOrientation = this.lastSensorOrientation ?? currentSensorOrientation;
+		const payload = {
+			lastValidOdomPos: extractOdomPosition(this.lastValidPose),
+			lastValidOdomRot: [
+				this.lastValidPose.orientation.x,
+				this.lastValidPose.orientation.y,
+				this.lastValidPose.orientation.z,
+				this.lastValidPose.orientation.w
+			],
+			lastSensorOrientation: {
+				alpha: lastOrientation.alpha,
+				beta: lastOrientation.beta,
+				gamma: lastOrientation.gamma,
+				absolute: lastOrientation.absolute
+			},
+			newOdomRot: [
+				newPose.orientation.x,
+				newPose.orientation.y,
+				newPose.orientation.z,
+				newPose.orientation.w
+			],
+			newSensorOrientation: {
+				alpha: currentSensorOrientation.alpha,
+				beta: currentSensorOrientation.beta,
+				gamma: currentSensorOrientation.gamma,
+				absolute: currentSensorOrientation.absolute
+			},
+			newOdomPos: extractOdomPosition(newPose),
+			resetTransform: savedResetTransform
+		};
+		log.info("AR tracking restarted (origin reset), dispatching alignment correction");
+		this.callbacks.onTrackingRestarted(payload);
+	}
+};
+//#endregion
+export { TrackingState, TrackingStateManager };

package/dist/ar/webxr-session.d.ts

@@ -0,0 +1,4 @@
+import { i as DepthSample, t as ARPose } from "../ar-types-B-ORgk6Z.js";
+import { t as CapturedImage } from "../image-capture-2pKjYUS6.js";
+import { A as setTrackingLostCallback, C as setArWorldGroup, D as setImageCaptureCallback, E as setFrameCallback, F as stopDepthCapture, I as stopImageCapture, M as shouldLogCameraAccessDiagnostic, N as startDepthCapture, O as setScene, P as startImageCapture, 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-COlSrXdL.js";
+export { ARPose, CapturedImage, DepthSample, 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, shouldLogCameraAccessDiagnostic, startDepthCapture, startImageCapture, stopDepthCapture, stopImageCapture };