gps-plus-slam-app-framework 1.9.1 → 1.11.0

package/dist/ar/replay-scene.js

@@ -1,5 +1,5 @@
 import { createLogger } from "../utils/logger.js";
-import { A as setArWorldGroup, L as setScene, j as setCamera, k as setArPose, s as createSceneHierarchy } from "../webxr-session-BCP2XK7k.js";
+import { i as createSceneHierarchy } from "../webxr-session-OyR3YbTq.js";
 import { createCss3dRendererManager } from "../visualization/css3d-renderer-manager.js";
 import { createCameraFollower } from "../visualization/camera-follower.js";
 import { createAlignmentLerper } from "../visualization/alignment-lerper.js";
@@ -16,8 +16,15 @@ import { OrbitControls } from "three/addons/controls/OrbitControls.js";
 * 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.
+* OWNS its scene objects: the replay scene/arWorldGroup/camera/arpose are
+* exposed via initReplayScene()'s return value and getReplayState(), and are
+* NEVER injected into webxr-session.ts (the historical Risk R1
+* setScene/setArWorldGroup/setCamera/setArPose hack was removed by the
+* 2026-07-11 webxr-session surface-reduction plan, step 2). The live-session
+* getters (getScene() etc.) stay null during replay; replay consumers read
+* this module's accessors instead, and scene-reading visualizers (e.g.
+* gpsEventVisualizer.setSceneSource) are pointed at these references by the
+* replay orchestrator.
 *
 * Camera modes:
 *   - orbit (default): OrbitControls — click-drag orbit + scroll zoom
@@ -70,7 +77,8 @@ function updateFpsMovement(dt) {
 * - 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)
+* - Keeps its own scene/arWorldGroup/arpose/camera references (returned
+*   here and via getReplayState()) — nothing is written into webxr-session
 * - Inserts canvas into the provided container
 * - Starts a requestAnimationFrame render loop
 * - Sets up OrbitControls as default camera mode
@@ -96,10 +104,6 @@ function initReplayScene(container) {
 	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);
@@ -109,6 +113,7 @@ function initReplayScene(container) {
 	state = {
 		scene,
 		arWorldGroup,
+		arpose,
 		camera,
 		renderer,
 		orbitControls,
@@ -123,6 +128,7 @@ function initReplayScene(container) {
 	return {
 		scene,
 		arWorldGroup,
+		arpose,
 		camera,
 		renderer
 	};
@@ -134,7 +140,7 @@ function initReplayScene(container) {
 * - Disposes renderer (frees GPU resources)
 * - Disposes camera controls
 * - Removes canvas from DOM
-* - Clears module-global scene references
+* - Clears this module's state (getReplayState() returns null afterwards)
 *
 * Safe to call multiple times (idempotent).
 */
@@ -151,10 +157,6 @@ function disposeReplayScene() {
 	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");
 }

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

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

package/dist/ar/webxr-nue-basis.d.ts

@@ -1,2 +1,2 @@
-import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-CaCnYxuq.js";
+import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-C3vTqkE2.js";
 export { WEBXR_TO_NUE };

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

@@ -1,4 +1,4 @@
-import { i as DepthSample, t as ARPose } from "../ar-types-Cc5yvBwn.js";
-import { n as CapturedImage } from "../image-capture-Bp6Pd4Md.js";
-import { $ as stopImageCapture, A as nuePositionToWebXR, B as setImageQualityAnalyzer, C as getImageCaptureFrameCount, D as initAR, E as getXrCameraFromPose, F as setCamera, G as setTrackingRecoveredCallback, H as setSessionEndCallback, I as setCameraFrameCallback, J as startCameraFrameCapture, K as setTrackingStore, L as setDepthCaptureCallback, M as resetWebXRState, N as setArPose, O as isWebXRSupported, P as setArWorldGroup, Q as stopDepthCapture, R as setFrameCallback, S as getDepthSampleCount, T as getScene, U as setTrackingCallbacks, V as setScene, W as setTrackingLostCallback, X as startImageCapture, Y as startDepthCapture, Z as stopCameraFrameCapture, _ as getCamera, a as DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, b as getCurrentArPose, c as TrackingSubscribableStore, d as createSceneHierarchy, f as endARSession, g as getArWorldGroup, h as getArPose, i as CameraFrameCaptureConfig, j as nueQuaternionToWebXR, k as isXRCameraLike, l as applyAlignmentMatrix, m as extractResetTransformData, n as AR_CAMERA_FOV, o as SessionEndInfo, p as extractPoseFromViewer, q as shouldLogCameraAccessDiagnostic, r as AR_CAMERA_NEAR, s as SessionFeatureOptions, t as AR_CAMERA_FAR, u as buildSessionOptions, v as getCameraFrameCaptureSize, w as getLiveCss3dManager, x as getDepthInfoFromFrame, y as getCameraFrameCount, z as setImageCaptureCallback } from "../webxr-session-BWCpGd-2.js";
-export { ARPose, AR_CAMERA_FAR, AR_CAMERA_FOV, AR_CAMERA_NEAR, CameraFrameCaptureConfig, CapturedImage, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, DepthSample, SessionEndInfo, SessionFeatureOptions, TrackingSubscribableStore, applyAlignmentMatrix, buildSessionOptions, createSceneHierarchy, endARSession, extractPoseFromViewer, extractResetTransformData, getArPose, getArWorldGroup, getCamera, getCameraFrameCaptureSize, getCameraFrameCount, getCurrentArPose, getDepthInfoFromFrame, getDepthSampleCount, getImageCaptureFrameCount, getLiveCss3dManager, getScene, getXrCameraFromPose, initAR, isWebXRSupported, isXRCameraLike, nuePositionToWebXR, nueQuaternionToWebXR, resetWebXRState, setArPose, setArWorldGroup, setCamera, setCameraFrameCallback, setDepthCaptureCallback, setFrameCallback, setImageCaptureCallback, setImageQualityAnalyzer, setScene, setSessionEndCallback, setTrackingCallbacks, setTrackingLostCallback, setTrackingRecoveredCallback, setTrackingStore, shouldLogCameraAccessDiagnostic, startCameraFrameCapture, startDepthCapture, startImageCapture, stopCameraFrameCapture, stopDepthCapture, stopImageCapture };
+import { i as DepthSample, t as ARPose } from "../ar-types-D6PYS4bc.js";
+import { n as CapturedImage } from "../image-capture-BevgKpoO.js";
+import { A as startCameraFrameCapture, C as isWebXRSupported, D as rebindTrackingStore, E as nueQuaternionToWebXR, F as stopImageCapture, M as startImageCapture, N as stopCameraFrameCapture, O as resetWebXRState, P as stopDepthCapture, S as initAR, T as nuePositionToWebXR, _ as getDepthInfoFromFrame, a as SessionFeatureOptions, b as getScene, c as buildSessionOptions, d as extractPoseFromViewer, f as extractResetTransformData, g as getCurrentArPose, h as getCameraFrameCount, i as SessionEndInfo, j as startDepthCapture, k as shouldLogCameraAccessDiagnostic, l as createSceneHierarchy, m as getCamera, n as CameraFrameCaptureConfig, o as TrackingSubscribableStore, p as getArWorldGroup, r as DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, s as applyAlignmentMatrix, t as ArSessionCallbacks, u as endARSession, v as getDepthSampleCount, w as isXRCameraLike, x as getXrCameraFromPose, y as getImageCaptureFrameCount } from "../webxr-session-DefwObIu.js";
+export { ARPose, ArSessionCallbacks, CameraFrameCaptureConfig, CapturedImage, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, DepthSample, SessionEndInfo, SessionFeatureOptions, TrackingSubscribableStore, applyAlignmentMatrix, buildSessionOptions, createSceneHierarchy, endARSession, extractPoseFromViewer, extractResetTransformData, getArWorldGroup, getCamera, getCameraFrameCount, getCurrentArPose, getDepthInfoFromFrame, getDepthSampleCount, getImageCaptureFrameCount, getScene, getXrCameraFromPose, initAR, isWebXRSupported, isXRCameraLike, nuePositionToWebXR, nueQuaternionToWebXR, rebindTrackingStore, resetWebXRState, shouldLogCameraAccessDiagnostic, startCameraFrameCapture, startDepthCapture, startImageCapture, stopCameraFrameCapture, stopDepthCapture, stopImageCapture };

package/dist/ar/webxr-session.js

@@ -1,2 +1,2 @@
-import { A as setArWorldGroup, B as setTrackingLostCallback, C as initAR, D as nueQuaternionToWebXR, E as nuePositionToWebXR, F as setImageCaptureCallback, G as startDepthCapture, H as setTrackingStore, I as setImageQualityAnalyzer, J as stopDepthCapture, K as startImageCapture, L as setScene, M as setCameraFrameCallback, N as setDepthCaptureCallback, O as resetWebXRState, P as setFrameCallback, R as setSessionEndCallback, S as getXrCameraFromPose, T as isXRCameraLike, U as shouldLogCameraAccessDiagnostic, V as setTrackingRecoveredCallback, W as startCameraFrameCapture, Y as stopImageCapture, _ as getDepthInfoFromFrame, a as applyAlignmentMatrix, b as getLiveCss3dManager, c as endARSession, d as getArPose, f as getArWorldGroup, g as getCurrentArPose, h as getCameraFrameCount, i as DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, j as setCamera, k as setArPose, l as extractPoseFromViewer, m as getCameraFrameCaptureSize, n as AR_CAMERA_FOV, o as buildSessionOptions, p as getCamera, q as stopCameraFrameCapture, r as AR_CAMERA_NEAR, s as createSceneHierarchy, t as AR_CAMERA_FAR, u as extractResetTransformData, v as getDepthSampleCount, w as isWebXRSupported, x as getScene, y as getImageCaptureFrameCount, z as setTrackingCallbacks } from "../webxr-session-BCP2XK7k.js";
-export { AR_CAMERA_FAR, AR_CAMERA_FOV, AR_CAMERA_NEAR, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, applyAlignmentMatrix, buildSessionOptions, createSceneHierarchy, endARSession, extractPoseFromViewer, extractResetTransformData, getArPose, getArWorldGroup, getCamera, getCameraFrameCaptureSize, getCameraFrameCount, getCurrentArPose, getDepthInfoFromFrame, getDepthSampleCount, getImageCaptureFrameCount, getLiveCss3dManager, getScene, getXrCameraFromPose, initAR, isWebXRSupported, isXRCameraLike, nuePositionToWebXR, nueQuaternionToWebXR, resetWebXRState, setArPose, setArWorldGroup, setCamera, setCameraFrameCallback, setDepthCaptureCallback, setFrameCallback, setImageCaptureCallback, setImageQualityAnalyzer, setScene, setSessionEndCallback, setTrackingCallbacks, setTrackingLostCallback, setTrackingRecoveredCallback, setTrackingStore, shouldLogCameraAccessDiagnostic, startCameraFrameCapture, startDepthCapture, startImageCapture, stopCameraFrameCapture, stopDepthCapture, stopImageCapture };
+import { A as stopImageCapture, C as resetWebXRState, D as startImageCapture, E as startDepthCapture, O as stopCameraFrameCapture, S as rebindTrackingStore, T as startCameraFrameCapture, _ as initAR, a as endARSession, b as nuePositionToWebXR, c as getArWorldGroup, d as getCurrentArPose, f as getDepthInfoFromFrame, g as getXrCameraFromPose, h as getScene, i as createSceneHierarchy, k as stopDepthCapture, l as getCamera, m as getImageCaptureFrameCount, n as applyAlignmentMatrix, o as extractPoseFromViewer, p as getDepthSampleCount, r as buildSessionOptions, s as extractResetTransformData, t as DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, u as getCameraFrameCount, v as isWebXRSupported, w as shouldLogCameraAccessDiagnostic, x as nueQuaternionToWebXR, y as isXRCameraLike } from "../webxr-session-OyR3YbTq.js";
+export { DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, applyAlignmentMatrix, buildSessionOptions, createSceneHierarchy, endARSession, extractPoseFromViewer, extractResetTransformData, getArWorldGroup, getCamera, getCameraFrameCount, getCurrentArPose, getDepthInfoFromFrame, getDepthSampleCount, getImageCaptureFrameCount, getScene, getXrCameraFromPose, initAR, isWebXRSupported, isXRCameraLike, nuePositionToWebXR, nueQuaternionToWebXR, rebindTrackingStore, resetWebXRState, shouldLogCameraAccessDiagnostic, startCameraFrameCapture, startDepthCapture, startImageCapture, stopCameraFrameCapture, stopDepthCapture, stopImageCapture };

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-uVGDu9IX.js";
+import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-D9y5r8ok.js";
 export { XR_ERROR_MESSAGES, XR_ERROR_MESSAGE_UNKNOWN, getXrErrorMessage };

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

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

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

@@ -18,7 +18,7 @@ import { createLogger } from "../utils/logger.js";
 * 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`
+* See `2026-06-03-0553-threejs-arbutton-minimal-ar-example-user-feedback.md`
 * §6.2/§6.3 (option H-A2) for the design rationale.
 */
 const log = createLogger("XrFrameLoop");

package/dist/ar-crash-isolation-DlXCGzMf.d.ts

@@ -0,0 +1,52 @@
+//#region ../src/ar/ar-crash-isolation.d.ts
+/**
+ * AR crash isolation flags — diagnostic gates for XR session negotiation.
+ *
+ * Moved out of the recorder settings catalog (2026-07-11 G-1 move,
+ * `2026-07-11-1445-recording-options-altitude-move-plan.md`): the framework itself
+ * consumes these flags in `webxr-session.ts` (session feature requests, frame
+ * loop) and on `enable-gps-ar.ts`'s public param, so the type + defaults +
+ * validator live framework-side. The recorder embeds the group in its own
+ * `RecordingOptions` catalog and re-exports the type.
+ */
+/**
+ * Diagnostic flags for isolating pre-recording AR startup crashes.
+ * These gates affect XR session negotiation and frame-loop behavior,
+ * independently of recording-time image/depth capture.
+ */
+interface ArCrashIsolationOptions {
+  enableDomOverlay: boolean;
+  enableCameraAccess: boolean;
+  enableDepthSensingFeature: boolean;
+  enableCss3dRenderer: boolean;
+  enableCameraTextureAcquisition: boolean;
+  /**
+   * Apply the Chromium WebXR camera-access tab-crash workaround at app
+   * bootstrap. The workaround always deletes
+   * `XRWebGLBinding.prototype.createProjectionLayer` /
+   * `XRRenderState.prototype.layers` (forcing `XRWebGLLayer`) — required on
+   * every affected Chrome build observed on-device, including Chrome 150 — and
+   * additionally persists the `baseLayer` across
+   * `XRSession.prototype.updateRenderState` only for Chrome builds inside the
+   * affected window (148.0.7778.12 up to 149.0.7821).
+   *
+   * Default `true`. Opt-out is offered because forcing `XRWebGLLayer` may break
+   * WebXR on unaffected (e.g. Quest) devices.
+   *
+   * @see GpsPlusSlamJs_AppFramework/src/ar/chromium-camera-access-workaround.ts
+   * @see https://github.com/mrdoob/three.js/issues/33404
+   */
+  applyChromiumProjectionLayerWorkaround: boolean;
+}
+/** Default AR-crash-isolation flags (all features enabled). */
+declare const DEFAULT_AR_CRASH_ISOLATION: ArCrashIsolationOptions;
+/**
+ * Validate and normalize AR crash isolation flags.
+ * Missing or invalid values fall back to defaults. The container itself is as
+ * untrusted as its fields (persisted blobs may lack the key entirely or hold
+ * `null`), so a nullish container yields the full defaults instead of
+ * throwing.
+ */
+declare function validateArCrashIsolationOptions(rawOptions?: Partial<ArCrashIsolationOptions> | null): ArCrashIsolationOptions;
+//#endregion
+export { DEFAULT_AR_CRASH_ISOLATION as n, validateArCrashIsolationOptions as r, ArCrashIsolationOptions as t };

package/dist/{ar-types-Cc5yvBwn.d.ts → ar-types-D6PYS4bc.d.ts}

@@ -43,6 +43,21 @@ interface ARPose {
   readonly position: WebXRVec3;
   readonly orientation: WebXRQuaternion;
 }
+/**
+ * Extract the raw odometry position tuple from an {@link ARPose}.
+ *
+ * Returns the raw WebXR position without coordinate conversion — the reducer
+ * applies the WebXR→NUE transform when storing into state (raw-storage
+ * pattern, see docs/2026-04-09-raw-storage-convert-on-read.md).
+ * WebXR local-floor frame: X=East, Y=Up, Z=South (toward viewer / backward).
+ *
+ * Lives next to the type (quality-review G-8 — it used to sit in
+ * `state/gps-event-coordinator.ts`, forcing an ar→state import in
+ * `ar/depth-sampler.ts`).
+ */
+declare function extractOdomPosition(arPose: ARPose): Vector3;
+/** Extract the raw odometry rotation tuple from an {@link ARPose}. */
+declare function extractOdomRotation(arPose: ARPose): Quaternion;
 /**
  * An sRGB color triple, 0–255 integers per channel. Kept as plain ints so
  * persisted JSON stays compact (~3 bytes/point in practice).
@@ -102,4 +117,4 @@ interface DepthSample {
   readonly projectionMatrix?: Matrix4;
 }
 //#endregion
-export { RgbTuple as a, DepthSample as i, ArPoseTuples as n, WebXRQuaternion as o, DepthPoint as r, WebXRVec3 as s, ARPose as t };
+export { RgbTuple as a, extractOdomPosition as c, DepthSample as i, extractOdomRotation as l, ArPoseTuples as n, WebXRQuaternion as o, DepthPoint as r, WebXRVec3 as s, ARPose as t };

package/dist/{ar-world-group-alignment-Cfg0trC3.d.ts → ar-world-group-alignment-BdS_h8Nf.d.ts}

@@ -1,4 +1,4 @@
-import { t as SubscribableStore } from "./subscribe-to-selector-dQV8SpsO.js";
+import { t as SubscribableStore } from "./subscribe-to-selector-j-eOYybQ.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/ar-world-group-alignment.d.ts
@@ -32,7 +32,7 @@ interface ArWorldGroupAlignmentHandle {
  * 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.
+ * gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-08-2149-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

package/dist/{capability-checker-BTTpygvZ.d.ts → capability-checker-BZ3_x1YL.d.ts}

@@ -8,7 +8,7 @@
  * 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.
+ * See `2026-06-03-0553-threejs-arbutton-minimal-ar-example-user-feedback.md` §6.4.
  */
 /** The two capabilities every GPS+AR demo requires to run. */
 interface CapabilitySupport {

package/dist/capture-motion-gate-CPwLekNf.d.ts

@@ -0,0 +1,120 @@
+//#region ../src/ar/capture-motion-gate.d.ts
+/**
+ * Capture motion gate — the policy that decides whether a *due* capture should
+ * fire on the current frame or be deferred until the device settles.
+ *
+ * Two cohesive pieces, both pure/deterministic and unit-testable in isolation
+ * from `ImageCaptureManager`:
+ *  - {@link decideCapture} — the stateless capture-vs-defer decision over the
+ *    windowed motion maxima, the thresholds, and the time since the capture
+ *    became due (the never-calm safety fallback).
+ *  - {@link MotionWindow} — a tiny fixed-size ring of recent per-frame
+ *    velocities with glitch rejection, so the decision judges "max over the
+ *    last N frames" rather than one lucky-calm sample.
+ *
+ * The window size and glitch ceilings are INTERNAL constants, deliberately not
+ * user-facing config: the user-facing surface is only enabled / maxAngular /
+ * maxLinear / maxWaitMs (plan §5.1). Keeping the stateful policy here (not in a
+ * speculative framework-wide service) matches the plan's §4.1 scope note.
+ *
+ * @see GpsPlusSlamJs_Docs/docs/2026-06-23-2105-blurry-frame-motion-gating-plan.md §4.2-4.4
+ */
+/** Default number of recent frames the gate judges motion over (~50 ms @ 60fps). */
+declare const DEFAULT_MOTION_WINDOW_SIZE = 3;
+/**
+ * User-/consumer-facing motion-filter configuration. Shared by both config
+ * shapes that carry it — `ImageCaptureConfig` (what `ImageCaptureManager`
+ * consumes) and `ImageCaptureOptions` (the persisted recorder options) — so the
+ * one definition cannot drift between them. The window size and glitch ceilings
+ * are deliberately NOT here: they are internal tuning constants, not exposed.
+ */
+interface MotionFilterConfig {
+  /** Master switch for the motion gate. Default `true`. */
+  enabled: boolean;
+  /** Angular-velocity threshold (rad/s); at/below this a frame is "calm". */
+  maxAngularVelocity: number;
+  /** Linear-velocity threshold (m/s); at/below this a frame is "calm". */
+  maxLinearVelocity: number;
+  /**
+   * Never-calm safety fallback: once a due capture has waited this many ms it
+   * fires regardless of motion, so an interval is never silently lost. A
+   * sensible value is ~2× the capture interval.
+   */
+  maxWaitMs: number;
+}
+/**
+ * Default motion-filter configuration. Enabled by default (plan §1).
+ *
+ * `maxLinearVelocity` was raised `0.5 → 2.5` m/s on 2026-07-02 after a
+ * 5-recording field analysis: at 0.5 m/s (~⅓ of a ~1.4 m/s walking pace) the
+ * gate deferred ~90 % of captures to the never-calm `maxWaitMs` fallback,
+ * collapsing the walking capture rate from the configured 0.5 Hz to ~0.17 Hz.
+ * Measured 1 Hz-averaged walking speed was a tight band (median 1.38, max
+ * 1.73 m/s); allowing for higher instantaneous per-frame stride peaks, 2.5 m/s
+ * clears steady and brisk walking while still deferring genuine lunges/jogging
+ * — demoting the (weak-at-scanning-distance) linear signal to a gross-motion
+ * safety net and letting the well-behaved angular gate be the primary blur
+ * selector. See
+ * `GpsPlusSlamJs_Docs/docs/2026-07-02-0117-image-capture-rate-motion-gate-finding.md`.
+ *
+ * `maxAngularVelocity` remains a PLACEHOLDER pending on-device field tuning
+ * (plan §7). `maxWaitMs` of 4000 ms is 2× the default 2000 ms image interval.
+ */
+declare const DEFAULT_MOTION_FILTER: MotionFilterConfig;
+/** Inputs to the stateless capture decision. */
+interface CaptureDecisionInput {
+  /** Max angular velocity (rad/s) over the recent window. `Infinity` if empty. */
+  windowMaxAngular: number;
+  /** Max linear velocity (m/s) over the recent window. `Infinity` if empty. */
+  windowMaxLinear: number;
+  /** Angular-velocity threshold (rad/s); at/below this is "calm". */
+  maxAngularVelocity: number;
+  /** Linear-velocity threshold (m/s); at/below this is "calm". */
+  maxLinearVelocity: number;
+  /** Milliseconds since the capture first became due (interval elapsed). */
+  msSinceDue: number;
+  /** Safety fallback: capture regardless once this many ms have passed. */
+  maxWaitMs: number;
+}
+/**
+ * Decide whether a due capture should fire now or defer to a later frame.
+ *
+ * A frame is "calm" when BOTH windowed maxima are at/below their thresholds —
+ * an empty window reports `Infinity`, so it is never calm (no capture before a
+ * valid sample exists). If not calm, the capture is deferred UNTIL `msSinceDue`
+ * reaches `maxWaitMs`, at which point it fires regardless to guarantee an
+ * interval is never silently lost (worst case: one blurry frame, not a gap).
+ */
+declare function decideCapture(input: CaptureDecisionInput): 'capture' | 'defer';
+/**
+ * Fixed-size ring of the most recent VALID (non-glitch) per-frame velocities.
+ *
+ * `maxAngular()`/`maxLinear()` return the max over the retained samples, or
+ * `Infinity` when empty so "no data yet" reads as not-calm in
+ * {@link decideCapture}. A sample exceeding either glitch ceiling is rejected
+ * outright (`push` returns `false`) and never stored, so a relocalization spike
+ * neither pollutes the window (no spurious defer) nor is treated as motion.
+ */
+declare class MotionWindow {
+  private readonly angularGlitchCeiling;
+  private readonly linearGlitchCeiling;
+  private readonly size;
+  private readonly angular;
+  private readonly linear;
+  constructor(size?: number, angularGlitchCeiling?: number, linearGlitchCeiling?: number);
+  /**
+   * Record a per-frame velocity pair. Returns `false` (and stores nothing) when
+   * the sample exceeds either glitch ceiling, `true` otherwise.
+   */
+  push(angularVel: number, linearVel: number): boolean;
+  /** Whether the window holds at least one valid (non-glitch) sample yet. */
+  hasSamples(): boolean;
+  /** Max angular velocity over the retained window, or `Infinity` if empty. */
+  maxAngular(): number;
+  /** Max linear velocity over the retained window, or `Infinity` if empty. */
+  maxLinear(): number;
+  /** Clear all samples (e.g. on tracking loss / capture restart). */
+  reset(): void;
+}
+//#endregion
+export { MotionWindow as a, MotionFilterConfig as i, DEFAULT_MOTION_FILTER as n, decideCapture as o, DEFAULT_MOTION_WINDOW_SIZE as r, CaptureDecisionInput as t };

package/dist/{chromium-camera-access-workaround-C6yJLXz9.d.ts → chromium-camera-access-workaround-BHR4clTE.d.ts}

@@ -10,7 +10,7 @@
  * added — i.e. it is not specific to this app's session setup. See:
  *
  *   - GpsPlusSlamJs_Docs/docs/2026-04-22-camera-access-reproducer-plan.md
- *   - GpsPlusSlamJs_Docs/docs/2026-06-04-camera-access-crash-regression-chrome-148.md
+ *   - GpsPlusSlamJs_Docs/docs/2026-06-04-0458-camera-access-crash-regression-chrome-148.md
  *   - https://github.com/mrdoob/three.js/issues/33404
  *   - https://issues.chromium.org/issues/507508099 (root-cause, marked Fixed)
  *

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-import { S as webxrToNUE, _ as createLoopClosureHandler, a as LibraryRootState, b as odometryTrackingRestarted, c as Matrix4, d as Vector3, f as arNorthBearingDeg, g as createGpsSlamStore, h as calcRelativeCoordsInMeters, i as LatLongAlt, l as Quaternion, m as calcGpsCoords, n as GpsPoint, o as LoopClosureHandler, p as bearingDeltaDeg, r as LatLong, s as LoopClosureHandlerConfig, t as ArImageCapture, u as RootState, v as isIdentityMatrix4, x as validateLicenseKey, y as magneticHeadingFromEnuQuat } from "../index-DXPVzOpP.js";
+import { S as webxrToNUE, _ as createLoopClosureHandler, a as LibraryRootState, b as odometryTrackingRestarted, c as Matrix4, d as Vector3, f as arNorthBearingDeg, g as createGpsSlamStore, h as calcRelativeCoordsInMeters, i as LatLongAlt, l as Quaternion, m as calcGpsCoords, n as GpsPoint, o as LoopClosureHandler, p as bearingDeltaDeg, r as LatLong, s as LoopClosureHandlerConfig, t as ArImageCapture, u as RootState, v as isIdentityMatrix4, x as validateLicenseKey, y as magneticHeadingFromEnuQuat } from "../index-CjxbDm8W.js";
 export { ArImageCapture, GpsPoint, LatLong, LatLongAlt, LibraryRootState, LoopClosureHandler, LoopClosureHandlerConfig, Matrix4, Quaternion, RootState, Vector3, arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, createLoopClosureHandler, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };

package/dist/{create-slam-app-store-D1QSMuKu.d.ts → create-slam-app-store-DFm5K9Ob.d.ts}

@@ -1,10 +1,11 @@
-import { a as TrackingSliceState } from "./tracking-slice-DMkHlbny.js";
-import { t as RecordingState } from "./recording-slice-BW8SiLo1.js";
-import { n as SessionMetadata } from "./opfs-storage-CTkxvxN4.js";
-import { n as StorageBackend } from "./storage-backend-sEtmM4yW.js";
+import { a as TrackingSliceState } from "./tracking-slice-BAbcZK-Y.js";
+import { t as RecordingState } from "./recording-slice-DXw5-UvO.js";
+import { n as SessionMetadata } from "./opfs-storage-S_odkCk1.js";
+import { n as StorageBackend } from "./storage-backend-BX7egQKi.js";
 import { GpsPoint, LatLong, Matrix4, RootState, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 import { Middleware, Reducer, ReducersMapObject, configureStore } from "@reduxjs/toolkit";
+import * as _$redux from "redux";
 
 //#region ../src/state/combined-root-state.d.ts
 type CombinedRootState = SlamAppCombinedState;
@@ -205,7 +206,7 @@ declare function computeGpsVsFusedDivergence(alignmentMatrix: Matrix4 | null, gp
 declare const snapshotPushed: _$_reduxjs_toolkit0.ActionCreatorWithPayload<AlignmentSnapshot, "trackingQuality/snapshotPushed">, snapshotsTrimmed: _$_reduxjs_toolkit0.ActionCreatorWithPayload<{
     size: number;
   }, "trackingQuality/snapshotsTrimmed">, reportUpdated: _$_reduxjs_toolkit0.ActionCreatorWithPayload<TrackingQualityReport | null, "trackingQuality/reportUpdated">, degradedCountUpdated: _$_reduxjs_toolkit0.ActionCreatorWithPayload<number, "trackingQuality/degradedCountUpdated">, resetTrackingQuality: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"trackingQuality/resetTrackingQuality">;
-declare const trackingQualityReducer: _$_reduxjs_toolkit0.Reducer<TrackingQualitySliceState>;
+declare const trackingQualityReducer: _$redux.Reducer<TrackingQualitySliceState>;
 interface RootWithTrackingQuality {
   trackingQuality?: TrackingQualitySliceState;
 }
@@ -329,7 +330,7 @@ interface SlamAppStoreOptions<ExtraReducers extends ReducersMapObject = Record<s
    * override on. **For Stage-A/§6a field-calibration recordings, turn this OFF**
    * (recorder settings) so the captured compass behaviour is unmodified.
    *
-   * @see GpsPlusSlamJs_Docs/docs/2026-06-26-stage0-field-collection-and-enablement.md
+   * @see GpsPlusSlamJs_Docs/docs/2026-06-26-0701-stage0-field-collection-and-enablement.md
    */
   enableCompassColdStartOverride?: boolean;
   /**
@@ -369,6 +370,14 @@ interface SlamAppStore<ExtraReducers extends ReducersMapObject = Record<string,
   writeFrame: (blob: Blob, index: number) => Promise<void>;
   /** Persist session metadata (`session.json`) via the configured backend. */
   writeSessionMetadata: (metadata: SessionMetadata) => Promise<void>;
+  /**
+   * Resolves once every action write queued by the persistence middleware
+   * has settled. The stop flow MUST await this before anything reads the
+   * session's `actions/` (final sync, ZIP export) — the write queue is
+   * async, so an action dispatched moments before Stop could otherwise
+   * land after the export enumerated the directory and miss the zip.
+   */
+  flushPendingActionWrites: () => Promise<void>;
 }
 /**
  * Build a Redux store wired with library + recording slices, persistence

package/dist/{create-slam-app-store-DXiAnJwR.js → create-slam-app-store-oK9bnqyI.js}

@@ -129,16 +129,17 @@ function createSlamAppStore(options) {
 	});
 	const prependedListeners = [trackingQualityMiddleware];
 	if (compassOptIns.length > 0) prependedListeners.push(createSlamAppStoreListenerMiddleware(compassOptIns));
+	const persistenceMiddleware = createPersistenceMiddleware({
+		storageBackend,
+		onWriteFailure,
+		persistedPrefixes: [...BUILTIN_PERSISTED_PREFIXES, ...persistedExtraPrefixes ?? []]
+	});
 	const store = configureStore({
 		reducer,
 		middleware: (getDefaultMiddleware) => getDefaultMiddleware({
-			serializableCheck: enableDevChecks,
-			immutableCheck: enableDevChecks
-		}).prepend(...prependedListeners).concat(createPersistenceMiddleware({
-			storageBackend,
-			onWriteFailure,
-			persistedPrefixes: [...BUILTIN_PERSISTED_PREFIXES, ...persistedExtraPrefixes ?? []]
-		}), ...extraMiddleware ?? []),
+			serializableCheck: enableDevChecks ? { ignoredActions: ["tracking/poseReceived"] } : false,
+			immutableCheck: enableDevChecks ? { ignoredPaths: ["tracking"] } : false
+		}).prepend(...prependedListeners).concat(persistenceMiddleware, ...extraMiddleware ?? []),
 		devTools: {
 			actionSanitizer: sanitizeForDevTools,
 			stateSanitizer: sanitizeForDevTools
@@ -149,7 +150,8 @@ function createSlamAppStore(options) {
 		dispatch: store.dispatch,
 		subscribe: (listener) => store.subscribe(listener),
 		writeFrame: (blob, index) => storageBackend.writeFrame(blob, index),
-		writeSessionMetadata: (metadata) => storageBackend.writeSessionMetadata(metadata)
+		writeSessionMetadata: (metadata) => storageBackend.writeSessionMetadata(metadata),
+		flushPendingActionWrites: () => persistenceMiddleware.flushPendingWrites()
 	};
 }
 //#endregion

package/dist/{depth-grid-lookup-D5atpNZ3.d.ts → depth-grid-lookup-CCuzlqUo.d.ts}

@@ -1,4 +1,4 @@
-import { r as DepthPoint } from "./ar-types-Cc5yvBwn.js";
+import { r as DepthPoint } from "./ar-types-D6PYS4bc.js";
 
 //#region ../src/ar/depth-grid-lookup.d.ts
 interface DepthGridLookup {

package/dist/{depth-sampler-CwObAwEA.d.ts → depth-sampler-CS2jAFw4.d.ts}

@@ -1,4 +1,4 @@
-import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-Cc5yvBwn.js";
+import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-D6PYS4bc.js";
 import { Matrix4 } from "gps-plus-slam-js";
 
 //#region ../src/ar/depth-rgb-lookup.d.ts
@@ -72,7 +72,7 @@ interface DepthInfo {
    * the matrices: the per-frame buffer is too large to clone and the live
    * depth occluder uploads it synchronously). Absent when the source carries
    * no `data` (e.g. the sparse-only path). Plumbed for the live depth occluder
-   * (2026-06-14-webxr-depth-occlusion-plan.md §2); the sparse sampler ignores it.
+   * (2026-06-14-0009-webxr-depth-occlusion-plan.md §2); the sparse sampler ignores it.
    */
   data?: ArrayBuffer;
   /**
@@ -169,12 +169,22 @@ declare class DepthSampler {
    */
   updateConfig(config: Partial<DepthSamplerConfig>): void;
   /**
-   * Called each frame with depth information.
+   * Called each frame with a LAZY depth provider (quality-review E-4: the
+   * caller used to acquire + wrap the depth info every frame while this
+   * method threw ~59 of 60 acquisitions away at the interval check — the
+   * provider is now invoked only when a sample is due).
+   *
+   * Unavailability detection is preserved by construction:
+   * `lastSampleTime` only advances when a sample is EMITTED, so while depth
+   * is unavailable the sampler stays "due" and probes the provider every
+   * frame — exactly the cadence the old per-frame acquisition gave
+   * `checkDepthUnavailability` (Field Test Readiness Issue #8).
    *
    * @param timestamp - Current frame timestamp in milliseconds
-   * @param depthInfo - WebXR depth information, or null if unavailable
+   * @param acquireDepthInfo - Returns the frame's depth info, or null if
+   *   unavailable. Only invoked when a sample is due.
    */
-  onFrame(timestamp: number, depthInfo: DepthInfo | null): void;
+  onFrame(timestamp: number, acquireDepthInfo: () => DepthInfo | null): void;
   /**
    * Acquire the per-sample RGB lookup, gated by `config.rgb` and guarded so
    * a failing acquisition (e.g. GL context loss during the blit) can never

package/dist/{depth-unprojection-DRdBU90S.d.ts → depth-unprojection-ET3Gwedf.d.ts}

@@ -1,4 +1,4 @@
-import { r as DepthPoint } from "./ar-types-Cc5yvBwn.js";
+import { r as DepthPoint } from "./ar-types-D6PYS4bc.js";
 import { Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/ar/depth-unprojection.d.ts

package/dist/device-orientation-cache-j-kLP8he.js

@@ -0,0 +1,20 @@
+//#region ../src/sensors/device-orientation-cache.ts
+let lastDeviceOrientation = null;
+/**
+* Update the cached device orientation.
+* Called by the host's orientation watch; read when a GPS event arrives and
+* by the XR frame loop's orientation snapshot.
+*/
+function updateDeviceOrientation(orientation) {
+	lastDeviceOrientation = orientation;
+}
+/** Get the current cached device orientation (null before the first reading). */
+function getLastDeviceOrientation() {
+	return lastDeviceOrientation;
+}
+/** Clear the cache (testing / session reset). */
+function resetDeviceOrientationCache() {
+	lastDeviceOrientation = null;
+}
+//#endregion
+export { resetDeviceOrientationCache as n, updateDeviceOrientation as r, getLastDeviceOrientation as t };

package/dist/{enable-gps-ar-BBtRO2FJ.d.ts → enable-gps-ar-D_xEHzh5.d.ts}

@@ -1,7 +1,7 @@
-import { t as ArCrashIsolationOptions } from "./recording-options-DYKWVI93.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CDKDQokE.js";
+import { t as ArCrashIsolationOptions } from "./ar-crash-isolation-DlXCGzMf.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CnhYrJCa.js";
 import { n as PermissionStatus } from "./permission-checker-B-VtjnBA.js";
-import { s as SessionFeatureOptions } from "./webxr-session-BWCpGd-2.js";
+import { a as SessionFeatureOptions, t as ArSessionCallbacks } from "./webxr-session-DefwObIu.js";
 
 //#region ../src/ar/enable-gps-ar.d.ts
 /**
@@ -37,6 +37,11 @@ interface EnableGpsArConfig {
   requestHitTest?: boolean;
   /** Crash-isolation diagnostic flags forwarded verbatim to `initAR`. */
   isolationOptions?: Partial<ArCrashIsolationOptions>;
+  /**
+   * Per-session AR callbacks (tracking store, depth, image capture, …)
+   * forwarded verbatim to `initAR` — see {@link ArSessionCallbacks}.
+   */
+  callbacks?: ArSessionCallbacks;
   /** Receives every GPS fix from the started watch. */
   onGpsPosition?: (position: GpsPosition) => void;
   /** Receives every device-orientation sample from the started watch. */
@@ -56,7 +61,7 @@ interface EnableGpsArDeps {
   requestWebXRWithDepthPermission: () => Promise<PermissionStatus>;
   startGpsWatch: (onPosition: (position: GpsPosition) => void, onError?: (error: GeolocationPositionError) => void) => void;
   startOrientationWatch: (onOrientation: (orientation: RawDeviceOrientation) => void) => void;
-  initAR: (container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions) => Promise<void>;
+  initAR: (container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions, callbacks?: ArSessionCallbacks) => Promise<void>;
   stopGpsWatch: () => void;
   stopOrientationWatch: () => void;
   endARSession: () => Promise<void>;

package/dist/{file-system-utils-DueXHxo9.d.ts → file-system-utils-BHI0rXr9.d.ts}

@@ -26,7 +26,7 @@ declare function formatFrameFilename(index: number): string;
  * is a textbook COLMAP tree (`images/frame-NNNNNN.jpg` next to `sparse/0/`).
  * Both the OPFS write path and the recorder's persisted `imageFile` value must
  * use THIS constant so a recording stays self-consistent (COLMAP export plan
- * Q5, gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-13-colmap-export-plan.md).
+ * Q5, gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-13-1205-colmap-export-plan.md).
  */
 declare const SESSION_IMAGES_DIR = "images";
 /**

package/dist/{frame-conversions-DDcNHkTb.d.ts → frame-conversions-CH7E2Iv_.d.ts}

@@ -1,4 +1,4 @@
-import { i as LatLongAlt, r as LatLong } from "./index-DXPVzOpP.js";
+import { i as LatLongAlt, r as LatLong } from "./index-CjxbDm8W.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/frame-conversions.d.ts

package/dist/{fused-path-C5pp0PJU.d.ts → fused-path-DOKzVMiO.d.ts}

@@ -1,4 +1,4 @@
-import { t as GpsCoord } from "./geo-types-DrGVu8nS.js";
+import { t as GpsCoord } from "./geo-types-BfDK8kJu.js";
 import { LatLong, Matrix4, Vector3, fusedGpsFromOdom } from "gps-plus-slam-js";
 
 //#region ../src/utils/fused-path.d.ts

package/dist/geo/h3-proximity.d.ts

@@ -1,2 +1,2 @@
-import { a as findNearbyGeoAnchor, c as h3CellsMatch, i as clusterCellsByZoom, l as isH3Index, n as KnownGeoAnchor, o as gpsPathToCoverageCells, r as approxDistanceMetres, s as gpsToH3, t as H3_RESOLUTION } from "../h3-proximity-D0GTHQmr.js";
+import { a as findNearbyGeoAnchor, c as h3CellsMatch, i as clusterCellsByZoom, l as isH3Index, n as KnownGeoAnchor, o as gpsPathToCoverageCells, r as approxDistanceMetres, s as gpsToH3, t as H3_RESOLUTION } from "../h3-proximity-BaAulrnM.js";
 export { H3_RESOLUTION, KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/h3-proximity.js

@@ -51,7 +51,7 @@ function gpsPathToCoverageCells(path) {
 * truncate the hex-string id: resolution is encoded in the high bits with
 * trailing `f` padding, so slicing yields INVALID cells, not parents (verified;
 * see the D1 gotcha in
-* docs/2026-06-14-map-centric-recording-browser-and-h3-index-user-feedback.md).
+* docs/2026-06-14-1048-map-centric-recording-browser-and-h3-index-user-feedback.md).
 *
 * `targetRes` is clamped to `[0, H3_RESOLUTION]` because `cellToParent` throws
 * when asked for a FINER resolution than the cell, and res 11 is the finest

package/dist/geo/index.d.ts

@@ -1,2 +1,2 @@
-import { a as findNearbyGeoAnchor, c as h3CellsMatch, i as clusterCellsByZoom, l as isH3Index, n as KnownGeoAnchor, o as gpsPathToCoverageCells, r as approxDistanceMetres, s as gpsToH3, t as H3_RESOLUTION } from "../h3-proximity-D0GTHQmr.js";
+import { a as findNearbyGeoAnchor, c as h3CellsMatch, i as clusterCellsByZoom, l as isH3Index, n as KnownGeoAnchor, o as gpsPathToCoverageCells, r as approxDistanceMetres, s as gpsToH3, t as H3_RESOLUTION } from "../h3-proximity-BaAulrnM.js";
 export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };