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

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

@@ -1,4 +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 };
+import { i as DepthSample, t as ARPose } from "../ar-types-isPsQptb.js";
+import { t as CapturedImage } from "../image-capture-BXZUmj7j.js";
+import { A as setScene, C as resetWebXRState, D as setDepthCaptureCallback, E as setCamera, F as shouldLogCameraAccessDiagnostic, I as startDepthCapture, L as startImageCapture, M as setTrackingLostCallback, N as setTrackingRecoveredCallback, O as setFrameCallback, P as setTrackingStore, R as stopDepthCapture, S as nueQuaternionToWebXR, T as setArWorldGroup, _ as getXrCameraFromPose, a as createSceneHierarchy, b as isXRCameraLike, c as extractResetTransformData, d as getCamera, f as getCurrentArPose, g as getScene, h as getLiveCss3dManager, i as buildSessionOptions, j as setTrackingCallbacks, k as setImageCaptureCallback, l as getArPose, m as getImageCaptureFrameCount, n as TrackingSubscribableStore, o as endARSession, p as getDepthSampleCount, r as applyAlignmentMatrix, s as extractPoseFromViewer, t as SessionFeatureOptions, u as getArWorldGroup, v as initAR, w as setArPose, x as nuePositionToWebXR, y as isWebXRSupported, z as stopImageCapture } from "../webxr-session-BnArFCew.js";
+export { ARPose, CapturedImage, DepthSample, SessionFeatureOptions, TrackingSubscribableStore, 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 };

package/dist/ar/webxr-session.js

@@ -2,9 +2,13 @@ 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 { TrackingStateManager } from "./tracking-state.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";
@@ -84,6 +88,13 @@ 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
 */
@@ -100,12 +111,20 @@ function resetWebXRState() {
 	arWorldGroup = null;
 	arPoseNode = null;
 	latestArPose = null;
+	lastFrameTime = 0;
+	clearFrameUpdates();
+	clearXrFrameUpdates();
+	runSessionDisposers();
 	imageCaptureManager = null;
 	onImageCaptured = null;
 	getScreenRotation = null;
 	onCaptureFailed = null;
 	onSuspiciousImage = null;
-	trackingStateManager = null;
+	if (trackingPhaseUnsubscribe) {
+		trackingPhaseUnsubscribe();
+		trackingPhaseUnsubscribe = null;
+	}
+	trackingStore = null;
 	onTrackingRestarted = null;
 	onTrackingLost = null;
 	onTrackingRecovered = null;
@@ -163,9 +182,22 @@ let onSuspiciousImage = null;
 */
 let getScreenRotation = null;
 /**
-* Tracking state manager (created when AR session starts with tracking callbacks)
+* 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 trackingStateManager = null;
+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)
 */
@@ -323,10 +355,14 @@ function getCurrentArPose() {
 * 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 = {}) {
+function buildSessionOptions(rootElement, isolationOptions = {}, sessionFeatures = {}) {
 	if (!rootElement) throw new Error("App root element not found");
 	const normalizedOptions = validateArCrashIsolationOptions(isolationOptions);
 	const optionalFeatures = [];
@@ -343,6 +379,7 @@ function buildSessionOptions(rootElement, isolationOptions = {}) {
 		} });
 	}
 	if (normalizedOptions.enableCameraAccess) optionalFeatures.push("camera-access");
+	if (sessionFeatures.requestHitTest) optionalFeatures.push("hit-test");
 	if (optionalFeatures.length > 0) sessionOptions.optionalFeatures = optionalFeatures;
 	return sessionOptions;
 }
@@ -373,8 +410,18 @@ async function isWebXRSupported() {
 * 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 as NUE: objects added directly to arWorldGroup can be placed
-* at [1,0,0]=North, [0,0,1]=East without any WebXR↔NUE conversion.
+* 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;
@@ -412,9 +459,13 @@ function createSceneHierarchy() {
 /**
 * 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 = {}) {
+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,
@@ -430,44 +481,23 @@ async function initAR(container, isolationOptions = {}) {
 	arWorldGroup = hierarchy.arWorldGroup;
 	arPoseNode = hierarchy.arpose;
 	camera = hierarchy.camera;
-	const sessionOptions = buildSessionOptions(container, currentArCrashIsolationOptions);
+	const sessionOptions = buildSessionOptions(container, currentArCrashIsolationOptions, sessionFeatures);
 	xrSession = await navigator.xr.requestSession("immersive-ar", sessionOptions);
 	xrSession.addEventListener("end", () => {
 		log.info("Session ended");
-		if (trackingStateManager) trackingStateManager.reset();
+		if (trackingStore) trackingStore.dispatch(resetTracking());
 		xrSession = null;
 		latestArPose = null;
 	});
 	await renderer.xr.setSession(xrSession);
-	if (onTrackingRestarted) {
-		trackingStateManager = new TrackingStateManager({
-			onTrackingLost: () => {
-				log.warn("Tracking lost");
-				latestArPose = null;
-				onTrackingLost?.();
-			},
-			onTrackingRestarted: (payload) => {
-				log.info("Tracking restarted (origin reset)");
-				onTrackingRestarted?.(payload);
-			},
-			onTrackingRecovered: () => {
-				log.info("Tracking recovered (same coordinate frame)");
-				onTrackingRecovered?.();
-			},
-			getDeviceOrientation: () => {
-				const orientation = getLastDeviceOrientation();
-				return {
-					alpha: orientation?.alpha ?? 0,
-					beta: orientation?.beta ?? 0,
-					gamma: orientation?.gamma ?? 0,
-					absolute: orientation?.absolute ?? false
-				};
-			}
-		});
+	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);
-			trackingStateManager?.markOriginReset(transformData);
+			store.dispatch(originReset(transformData));
 			log.warn("XR reference space reset detected", transformData ? "(transform available)" : "(no transform)");
 		});
 	}
@@ -480,12 +510,72 @@ async function initAR(container, isolationOptions = {}) {
 	log.info("AR session started");
 }
 /**
-* Update tracking state manager with current pose state.
+* 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 (!trackingStateManager) return;
-	if (arPose) trackingStateManager.onPoseReceived(arPose);
-	else trackingStateManager.onPoseLost();
+	if (!trackingStore || !onTrackingRestarted) return;
+	if (arPose) trackingStore.dispatch(poseReceived({
+		pose: arPose,
+		sensorOrientation: snapshotDeviceOrientation()
+	}));
+	else trackingStore.dispatch(poseLost());
 }
 /**
 * Called each XR frame
@@ -497,6 +587,17 @@ function onXRFrame(time, frame) {
 	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) {
@@ -607,41 +708,6 @@ function setArPose(a) {
 	arPoseNode = a;
 }
 /**
-* Constant matrix converting WebXR local-floor coordinates to the internal
-* NUE (North-Up-East) convention.
-*
-* WebXR: X=East, Y=Up, Z=South (right-handed, toward viewer)
-* NUE:   X=North, Y=Up, Z=East (right-handed)
-*
-* Mapping:  NUE_X = -WebXR_Z,  NUE_Y = WebXR_Y,  NUE_Z = WebXR_X
-*
-* Row-major:
-*   [ 0  0 -1  0 ]
-*   [ 0  1  0  0 ]
-*   [ 1  0  0  0 ]
-*   [ 0  0  0  1 ]
-*
-* Stored column-major (Three.js / gl-matrix convention).
-*/
-const WEBXR_TO_NUE = new THREE.Matrix4().fromArray([
-	0,
-	0,
-	1,
-	0,
-	0,
-	1,
-	0,
-	0,
-	-1,
-	0,
-	0,
-	0,
-	0,
-	0,
-	0,
-	1
-]);
-/**
 * Apply an alignment matrix to the AR world group.
 *
 * The alignment matrix maps odometry positions in NUE space
@@ -703,27 +769,20 @@ function nueQuaternionToWebXR(nue) {
 /**
 * End the current XR session and clean up all resources.
 *
-* Stops the animation loop, disposes the WebGL renderer, removes the
-* canvas from the DOM, and tears down the CSS3D overlay. This is the
-* production cleanup path — call it when the AR experience is finished.
+* 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);
-	if (xrSession) {
-		await xrSession.end();
-		xrSession = null;
-	}
-	latestArPose = null;
-	if (css3dManager) {
-		css3dManager.dispose();
-		css3dManager = null;
-	}
-	if (renderer) {
-		if (renderer.domElement.parentElement) renderer.domElement.parentElement.removeChild(renderer.domElement);
-		renderer.dispose();
-		renderer = null;
+	try {
+		if (xrSession) await xrSession.end();
+	} finally {
+		resetWebXRState();
 	}
-	cleanupBlitResources();
 }
 /**
 * Set up image capture callbacks.
@@ -755,6 +814,10 @@ function startImageCapture(config, resolutionDivisor = 1) {
 		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,
@@ -802,6 +865,23 @@ 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.
 *
@@ -887,4 +967,4 @@ function getLiveCss3dManager() {
 	return css3dManager;
 }
 //#endregion
-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, shouldLogCameraAccessDiagnostic, startDepthCapture, startImageCapture, stopDepthCapture, stopImageCapture };
+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 };

package/dist/ar/xr-camera-texture.d.ts

@@ -1,2 +1,2 @@
-import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-BbukNE79.js";
+import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-BU5YvKAM.js";
 export { CameraTextureResult, RendererLike, XRCameraLike, acquireCameraTexture };

package/dist/ar/xr-error-handler.d.ts

@@ -1,2 +1,2 @@
-import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-DTHfmvrl.js";
+import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-DcUFshNF.js";
 export { XR_ERROR_MESSAGES, XR_ERROR_MESSAGE_UNKNOWN, getXrErrorMessage };

package/dist/ar/xr-frame-loop.d.ts

@@ -0,0 +1,2 @@
+import { a as runXrFrameUpdates, i as registerXrFrameUpdate, n as XrFrameUpdate, r as clearXrFrameUpdates, t as XrFrameContext } from "../xr-frame-loop-BKckC7xC.js";
+export { XrFrameContext, XrFrameUpdate, clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

package/dist/ar/xr-frame-loop.js

@@ -0,0 +1,69 @@
+import { createLogger } from "../utils/logger.js";
+//#region ../src/ar/xr-frame-loop.ts
+/**
+* Per-frame **XR-access** callback registry — the safe seam that lets app
+* code run standard WebXR work (hit-test, light estimation, depth, the WebXR
+* Anchors API, …) without the framework wrapping each capability.
+*
+* The framework owns the single `renderer.setAnimationLoop(onXRFrame)` hook,
+* and the live `XRFrame` never leaves `onXRFrame`. The plain `FrameUpdate`
+* registry (`frame-loop.ts`) only passes `(dt, elapsed)`, which is enough for
+* pose-free ticks but cannot drive hit-test. This registry additionally hands
+* the callback the live `frame`, `referenceSpace`, and `session`.
+*
+* SAFETY CONTRACT (non-negotiable): `frame` / `referenceSpace` / `session` are
+* valid **only synchronously inside the callback**. The `XRFrame` is
+* use-after-frame-unsafe — storing it and reading it on a later tick throws or
+* crashes. Passing them as arguments (never a stashable `getXrFrame()` getter)
+* makes correct use the easy path and stashing the awkward one. Do NOT retain
+* `ctx` or its fields beyond the callback's synchronous execution.
+*
+* See `2026-06-03-threejs-arbutton-minimal-ar-example-user-feedback.md`
+* §6.2/§6.3 (option H-A2) for the design rationale.
+*/
+const log = createLogger("XrFrameLoop");
+const updates = /* @__PURE__ */ new Set();
+/**
+* Register a per-frame XR-access callback. Returns an unregister function.
+*
+* Registration is idempotent — registering the same `fn` twice is a no-op
+* (it remains a single entry in the underlying `Set`).
+*/
+function registerXrFrameUpdate(fn) {
+	updates.add(fn);
+	return () => {
+		updates.delete(fn);
+	};
+}
+/**
+* Invoke all registered XR-access callbacks. Called by the WebXR session's
+* `onXRFrame` once per frame, only when a live `frame` / `referenceSpace` /
+* `session` are all available.
+*
+* The set is snapshotted before iterating so that
+* `registerXrFrameUpdate` / unregister calls made by a handler during the
+* same frame are deferred to the next tick — mirroring `runFrameUpdates`.
+*
+* Each callback is invoked in its own `try/catch`: this registry is the public
+* app seam, so a bug in one app-registered callback (which throws every frame)
+* must not abort the remaining callbacks nor propagate up through `onXRFrame`
+* and kill the scene render for the whole session. Failures are logged and the
+* loop continues — mirroring `runFrameUpdates`.
+*/
+function runXrFrameUpdates(ctx) {
+	const snapshot = Array.from(updates);
+	for (const fn of snapshot) try {
+		fn(ctx);
+	} catch (error) {
+		log.error("A registered XrFrameUpdate threw; continuing the loop", error);
+	}
+}
+/**
+* Clear all registrations. Called from `resetWebXRState()` so a fresh
+* session starts with an empty registry.
+*/
+function clearXrFrameUpdates() {
+	updates.clear();
+}
+//#endregion
+export { clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

package/dist/ar-world-group-alignment-Dn4rQk_c.d.ts

@@ -0,0 +1,43 @@
+import { t as SubscribableStore } from "./subscribe-to-selector--KQpgLXG.js";
+import * as THREE from "three";
+
+//#region ../src/visualization/ar-world-group-alignment.d.ts
+interface ArWorldGroupAlignmentOptions {
+  /** The store whose alignment selector drives the lerper. */
+  readonly store: SubscribableStore;
+  /** The AR world group whose `.matrix` is lerped toward each alignment. */
+  readonly arWorldGroup: THREE.Object3D;
+  /**
+   * Lerp speed multiplier forwarded to {@link createAlignmentLerper}
+   * (default matches the lerper's own `DEFAULT_LERP_RATE`).
+   */
+  readonly lerpRate?: number;
+}
+interface ArWorldGroupAlignmentHandle {
+  /** Stop the subscription and the per-frame update. */
+  dispose(): void;
+}
+/**
+ * Begin applying the store's (lerped) alignment to `arWorldGroup`. Returns a
+ * handle whose `dispose()` removes both the store subscription and the
+ * per-frame update.
+ *
+ * Disposal is tied to the AR session lifecycle: the binding registers itself
+ * with the session-disposer registry that `resetWebXRState()` flushes on
+ * teardown, so a caller can `enableArWorldGroupAlignment(...)` once and never
+ * hold the handle — the binding cannot outlive the session (which is what two
+ * apps independently leaked: the store subscription survives a teardown because
+ * `clearFrameUpdates` only drops the per-frame tick). Because `initAR()` throws
+ * while a prior session is live, every restart passes through that flush. The
+ * handle is still returned for callers that want to stop alignment mid-session,
+ * and is idempotent + self-deregistering so a manual `dispose()` and the
+ * teardown flush never double-run. See
+ * gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-08-arworldgroup-alignment-session-scoped-disposal.md.
+ *
+ * Double-drive is still the caller's concern: the recorder owns its own lerper
+ * and must NOT also call this (it would double-lerp the same group). It does not
+ * call this helper, so flushing the registry on teardown never affects it.
+ */
+declare function enableArWorldGroupAlignment(options: ArWorldGroupAlignmentOptions): ArWorldGroupAlignmentHandle;
+//#endregion
+export { ArWorldGroupAlignmentOptions as n, enableArWorldGroupAlignment as r, ArWorldGroupAlignmentHandle as t };

package/dist/capability-checker-BTCmZRL4.d.ts

@@ -0,0 +1,43 @@
+//#region ../src/ar/capability-checker.d.ts
+/**
+ * Pure capability-gating helpers, promoted from the AnchorStarter app so the
+ * minimal AR example and AnchorStarter share the *decision* and *message*
+ * without sharing app-specific copy.
+ *
+ * The async feature probing (`isWebXRSupported()` / geolocation availability)
+ * stays in each app's `main.ts`; only the browser-free decision and the
+ * user-facing message live here so they can be unit-tested without a browser.
+ *
+ * See `2026-06-03-threejs-arbutton-minimal-ar-example-user-feedback.md` §6.4.
+ */
+/** The two capabilities every GPS+AR demo requires to run. */
+interface CapabilitySupport {
+  /** Browser supports a WebXR `immersive-ar` session. */
+  readonly webxr: boolean;
+  /** Geolocation API is available. */
+  readonly geolocation: boolean;
+}
+/** Options that let an app flavour the otherwise-neutral gating message. */
+interface CapabilityMessageOptions {
+  /**
+   * App-specific "what this demo lets you do" phrase, appended as
+   * `…outdoors, to try ${contextLabel}.`. Omit for a neutral message that
+   * ends at `…outdoors.`. Example: `'the persistent-anchor flow'`.
+   */
+  readonly contextLabel?: string;
+}
+/** True only when both AR and GPS are available — the demo can run. */
+declare function isFullySupported(support: CapabilitySupport): boolean;
+/**
+ * Build the capability-gated message shown when the demo cannot run. Names
+ * exactly which capabilities are missing so the user understands *why*, and
+ * always points them at the supported environment (an AR phone, outdoors).
+ * Returns `null` when everything is supported (no message needed).
+ *
+ * The trailing "to try …" clause is app-specific and supplied via
+ * `options.contextLabel`; without it the message ends neutrally at
+ * "…outdoors.".
+ */
+declare function capabilityMessage(support: CapabilitySupport, options?: CapabilityMessageOptions): string | null;
+//#endregion
+export { isFullySupported as i, CapabilitySupport as n, capabilityMessage as r, CapabilityMessageOptions as t };