gps-plus-slam-app-framework 1.4.0 → 1.8.0

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

@@ -1,2 +1,2 @@
-import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-CW1wsbm6.js";
+import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-CaCnYxuq.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-BckI1E-O.js";
-import { n as CapturedImage } from "../image-capture-C2Feywet.js";
-import { A as setCamera, B as shouldLogCameraAccessDiagnostic, C as isWebXRSupported, D as resetWebXRState, E as nueQuaternionToWebXR, F as setScene, G as stopDepthCapture, H as startDepthCapture, I as setTrackingCallbacks, K as stopImageCapture, L as setTrackingLostCallback, M as setDepthCaptureCallback, N as setFrameCallback, O as setArPose, P as setImageCaptureCallback, R as setTrackingRecoveredCallback, S as initAR, T as nuePositionToWebXR, U as startImageCapture, V as startCameraFrameCapture, W as stopCameraFrameCapture, _ as getDepthSampleCount, a as applyAlignmentMatrix, b as getScene, c as endARSession, d as getArPose, f as getArWorldGroup, g as getCurrentArPose, h as getCameraFrameCount, i as TrackingSubscribableStore, j as setCameraFrameCallback, k as setArWorldGroup, l as extractPoseFromViewer, m as getCameraFrameCaptureSize, n as DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, o as buildSessionOptions, p as getCamera, r as SessionFeatureOptions, s as createSceneHierarchy, t as CameraFrameCaptureConfig, u as extractResetTransformData, v as getImageCaptureFrameCount, w as isXRCameraLike, x as getXrCameraFromPose, y as getLiveCss3dManager, z as setTrackingStore } from "../webxr-session-COsOjJwn.js";
-export { ARPose, CameraFrameCaptureConfig, CapturedImage, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE, DepthSample, SessionFeatureOptions, TrackingSubscribableStore, applyAlignmentMatrix, buildSessionOptions, createSceneHierarchy, endARSession, extractPoseFromViewer, extractResetTransformData, getArPose, getArWorldGroup, getCamera, getCameraFrameCaptureSize, getCameraFrameCount, getCurrentArPose, getDepthSampleCount, getImageCaptureFrameCount, getLiveCss3dManager, getScene, getXrCameraFromPose, initAR, isWebXRSupported, isXRCameraLike, nuePositionToWebXR, nueQuaternionToWebXR, resetWebXRState, setArPose, setArWorldGroup, setCamera, setCameraFrameCallback, setDepthCaptureCallback, setFrameCallback, setImageCaptureCallback, setScene, setTrackingCallbacks, setTrackingLostCallback, setTrackingRecoveredCallback, setTrackingStore, shouldLogCameraAccessDiagnostic, startCameraFrameCapture, startDepthCapture, startImageCapture, stopCameraFrameCapture, stopDepthCapture, stopImageCapture };
+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-cRG2SYAQ.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 };

package/dist/ar/webxr-session.js

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

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-BmrP7iNZ.js";
+import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-q0eIDSRg.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-BEjRgZjt.js";
+import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-uVGDu9IX.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-K8ebdjLw.js";
+import { a as runXrFrameUpdates, i as registerXrFrameUpdate, n as XrFrameUpdate, r as clearXrFrameUpdates, t as XrFrameContext } from "../xr-frame-loop-DX3JPpAU.js";
 export { XrFrameContext, XrFrameUpdate, clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

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

@@ -24,6 +24,13 @@ import { createLogger } from "../utils/logger.js";
 const log = createLogger("XrFrameLoop");
 const updates = /* @__PURE__ */ new Set();
 /**
+* Cached iteration snapshot of {@link updates}, invalidated on every registry
+* mutation. The snapshot SEMANTICS (a register/unregister during a tick defers
+* to the next frame) are unchanged — caching only avoids re-allocating an
+* identical array at 60–90 Hz between (rare) registry changes (PR #67 review).
+*/
+let snapshot = null;
+/**
 * Register a per-frame XR-access callback. Returns an unregister function.
 *
 * Registration is idempotent — registering the same `fn` twice is a no-op
@@ -31,8 +38,10 @@ const updates = /* @__PURE__ */ new Set();
 */
 function registerXrFrameUpdate(fn) {
 	updates.add(fn);
+	snapshot = null;
 	return () => {
 		updates.delete(fn);
+		snapshot = null;
 	};
 }
 /**
@@ -51,8 +60,8 @@ function registerXrFrameUpdate(fn) {
 * loop continues — mirroring `runFrameUpdates`.
 */
 function runXrFrameUpdates(ctx) {
-	const snapshot = Array.from(updates);
-	for (const fn of snapshot) try {
+	const fns = snapshot ?? (snapshot = Array.from(updates));
+	for (const fn of fns) try {
 		fn(ctx);
 	} catch (error) {
 		log.error("A registered XrFrameUpdate threw; continuing the loop", error);
@@ -64,6 +73,7 @@ function runXrFrameUpdates(ctx) {
 */
 function clearXrFrameUpdates() {
 	updates.clear();
+	snapshot = null;
 }
 //#endregion
 export { clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

package/dist/{ar-Dc72Ksiu.js → ar-BqCudtqE.js}

@@ -10,12 +10,13 @@ import "./ar/qr-derived-pose.js";
 import "./ar/webxr-nue-basis.js";
 import "./ar/qr-debug-view.js";
 import { n as createDetectionScheduler } from "./qr-detection-controller-B-tLVd-S.js";
-import "./qr-pose-aggregation-DXR9STHs.js";
-import "./webxr-session-CJF9Nijp.js";
+import "./qr-pose-aggregation-DBiaLW0O.js";
+import "./webxr-session-BCP2XK7k.js";
 import "./ar/occupancy-grid.js";
+import "./ar/occupancy-mesher.js";
 import "./ar/frame-loop.js";
 import "./ar/xr-frame-loop.js";
-import "./ar/image-capture.js";
+import "./image-capture-DVcuqMtX.js";
 import "./ar/xr-camera-texture.js";
 import "./ar/enable-gps-ar.js";
 import "./ar/replay-scene.js";

package/dist/{ar-world-group-alignment-DDLkgNf_.d.ts → ar-world-group-alignment-BlvGcIAk.d.ts}

@@ -1,4 +1,4 @@
-import { t as SubscribableStore } from "./subscribe-to-selector-Bp3sLx8L.js";
+import { t as SubscribableStore } from "./subscribe-to-selector-B9ylM5Oh.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/ar-world-group-alignment.d.ts

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

@@ -0,0 +1,24 @@
+//#region ../src/ar/capture-motion-gate.d.ts
+/**
+ * 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;
+}
+//#endregion
+export { MotionFilterConfig as t };

package/dist/capture-motion-gate-_NdTSwKi.js

@@ -0,0 +1,106 @@
+/**
+* Angular velocity (rad/s) above which a sample is treated as a tracking glitch
+* (e.g. relocalization teleport), not real motion. A genuine hand/device turn
+* tops out well below this; a teleport is far above it. Module-internal tuning
+* constant (not exported — the gate's user surface is only the four
+* `MotionFilterConfig` fields); overridable per-instance via the `MotionWindow`
+* constructor for tests.
+*/
+const ANGULAR_GLITCH_CEILING_RAD_S = 50;
+/**
+* Linear velocity (m/s) above which a sample is treated as a tracking glitch.
+* ~20 m/s (72 km/h) is unreachable by handheld scanning but trivially exceeded
+* by a relocalization origin jump. Module-internal tuning constant (see
+* {@link ANGULAR_GLITCH_CEILING_RAD_S}).
+*/
+const LINEAR_GLITCH_CEILING_M_S = 20;
+/**
+* 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-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.
+*/
+const DEFAULT_MOTION_FILTER = {
+	enabled: true,
+	maxAngularVelocity: .6,
+	maxLinearVelocity: 2.5,
+	maxWaitMs: 4e3
+};
+/**
+* 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).
+*/
+function decideCapture(input) {
+	if (input.windowMaxAngular <= input.maxAngularVelocity && input.windowMaxLinear <= input.maxLinearVelocity) return "capture";
+	if (input.msSinceDue >= input.maxWaitMs) return "capture";
+	return "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.
+*/
+var MotionWindow = class {
+	angularGlitchCeiling;
+	linearGlitchCeiling;
+	size;
+	angular = [];
+	linear = [];
+	constructor(size = 3, angularGlitchCeiling = ANGULAR_GLITCH_CEILING_RAD_S, linearGlitchCeiling = LINEAR_GLITCH_CEILING_M_S) {
+		this.angularGlitchCeiling = angularGlitchCeiling;
+		this.linearGlitchCeiling = linearGlitchCeiling;
+		this.size = Number.isFinite(size) && size >= 1 ? Math.floor(size) : 1;
+	}
+	/**
+	* Record a per-frame velocity pair. Returns `false` (and stores nothing) when
+	* the sample exceeds either glitch ceiling, `true` otherwise.
+	*/
+	push(angularVel, linearVel) {
+		if (!Number.isFinite(angularVel) || !Number.isFinite(linearVel) || angularVel > this.angularGlitchCeiling || linearVel > this.linearGlitchCeiling) return false;
+		this.angular.push(angularVel);
+		this.linear.push(linearVel);
+		if (this.angular.length > this.size) this.angular.shift();
+		if (this.linear.length > this.size) this.linear.shift();
+		return true;
+	}
+	/** Whether the window holds at least one valid (non-glitch) sample yet. */
+	hasSamples() {
+		return this.angular.length > 0;
+	}
+	/** Max angular velocity over the retained window, or `Infinity` if empty. */
+	maxAngular() {
+		return this.angular.length === 0 ? Number.POSITIVE_INFINITY : Math.max(...this.angular);
+	}
+	/** Max linear velocity over the retained window, or `Infinity` if empty. */
+	maxLinear() {
+		return this.linear.length === 0 ? Number.POSITIVE_INFINITY : Math.max(...this.linear);
+	}
+	/** Clear all samples (e.g. on tracking loss / capture restart). */
+	reset() {
+		this.angular.length = 0;
+		this.linear.length = 0;
+	}
+};
+//#endregion
+export { MotionWindow as n, decideCapture as r, DEFAULT_MOTION_FILTER as t };

package/dist/cell-key-DIB4rOTV.js

@@ -0,0 +1,51 @@
+//#region ../src/ar/cell-key.ts
+/** Full-field envelope: direct cell keys are collision-free for `|c| ≤` this. */
+const CELL_KEY_LIMIT = 65535;
+/**
+* Mesher-tier envelope: leaves headroom for the derived half-lattice
+* (`2·coord ± 1`) and neighbour (`±1`) keys the meshers build from a cell.
+*/
+const HALF_LATTICE_CELL_KEY_LIMIT = 32767;
+const KEY_OFFSET = 65536;
+const KEY_FIELD = 131072;
+const KEY_FIELD_SQ = KEY_FIELD * KEY_FIELD;
+/**
+* Pack three integer coordinates into the numeric key. Collision-free only
+* within the caller's envelope (see the module header); scalar form so hot
+* loops need no tuple.
+*/
+function packCellKey(x, y, z) {
+	return (x + KEY_OFFSET) * KEY_FIELD_SQ + (y + KEY_OFFSET) * KEY_FIELD + (z + KEY_OFFSET);
+}
+/** Tuple convenience over {@link packCellKey}. */
+function cellKey(cell) {
+	return packCellKey(cell[0], cell[1], cell[2]);
+}
+/** One axis of {@link unpackCellKey} without allocating the tuple (hot paths). */
+function unpackCellCoord(key, axis) {
+	if (axis === 0) return Math.floor(key / KEY_FIELD_SQ) - KEY_OFFSET;
+	if (axis === 1) return Math.floor(key / KEY_FIELD) % KEY_FIELD - KEY_OFFSET;
+	return key % KEY_FIELD - KEY_OFFSET;
+}
+/**
+* Exact inverse of {@link cellKey} over the ±{@link CELL_KEY_LIMIT} envelope
+* (property-tested). Consumers that no longer store coordinate tuples recover
+* them from the key through this function.
+*/
+function unpackCellKey(key) {
+	return [
+		unpackCellCoord(key, 0),
+		unpackCellCoord(key, 1),
+		unpackCellCoord(key, 2)
+	];
+}
+/**
+* True iff every coordinate is within ±`limit` — the aliasing guard callers
+* must apply before keying untrusted coordinates. Defaults to the full-field
+* {@link CELL_KEY_LIMIT}; the meshers pass {@link HALF_LATTICE_CELL_KEY_LIMIT}.
+*/
+function cellCoordsInKeyRange(cell, limit = CELL_KEY_LIMIT) {
+	return Math.abs(cell[0]) <= limit && Math.abs(cell[1]) <= limit && Math.abs(cell[2]) <= limit;
+}
+//#endregion
+export { packCellKey as a, cellKey as i, HALF_LATTICE_CELL_KEY_LIMIT as n, unpackCellCoord as o, cellCoordsInKeyRange as r, unpackCellKey as s, CELL_KEY_LIMIT as t };

package/dist/core/index.d.ts

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

package/dist/core/index.js

@@ -1,2 +1,2 @@
-import { calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE } from "gps-plus-slam-js";
-export { calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };
+import { arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey, webxrToNUE } from "gps-plus-slam-js";
+export { arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };

package/dist/{create-slam-app-store-Ce2FMKCp.d.ts → create-slam-app-store-D3nzh9Wb.d.ts}

@@ -1,8 +1,7 @@
-import { t as ARPose } from "./ar-types-BckI1E-O.js";
-import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-DJZ9qeGg.js";
-import { t as RecordingState } from "./recording-slice-B-uCgGoh.js";
-import { n as SessionMetadata } from "./opfs-storage-DMtlt57S.js";
-import { n as StorageBackend } from "./storage-backend-CTJHNdMp.js";
+import { a as TrackingSliceState } from "./tracking-slice-DMkHlbny.js";
+import { t as RecordingState } from "./recording-slice-DTUtSVgd.js";
+import { n as SessionMetadata } from "./opfs-storage-CTkxvxN4.js";
+import { n as StorageBackend } from "./storage-backend-sEtmM4yW.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";
@@ -18,8 +17,7 @@ interface TrackingQualityReport {
   confidence: number;
   subScores: {
     convergence: number;
-    residualConsensus: number; /** `null` when the device cannot supply an absolute compass heading. */
-    compassAgreement: number | null;
+    residualConsensus: number;
     gpsAccuracy: number;
     coverage: number;
   };
@@ -37,9 +35,7 @@ interface TrackingQualityReport {
     medianResidualM: number;
     medianRecentGpsAccuracyM: number;
     walkedDistanceM: number;
-    directionSpreadDeg: number; /** `null` when §4.3 is unavailable (no absolute compass). */
-    headingDeltaDeg: number | null;
-    compassDriftDetected: boolean;
+    directionSpreadDeg: number;
     observationsSeen: number; /** §4.6 — diagnostic only, never feeds the aggregate. */
     gpsVsFusedMaxDivergenceM: number;
   };
@@ -61,10 +57,6 @@ interface TrackingQualityOptions {
   convergenceRotationWarnDeg?: number;
   /** §4.1 ΣΔtranslation (m) at/below which convergence scores 1.0. Fail ramp ends at 4×. */
   convergenceTranslationWarnM?: number;
-  /** §4.3 EMA threshold (deg) below which compass scores 1.0. */
-  compassWarnDeg?: number;
-  /** §4.3 EMA threshold (deg) above which compass scores 0.0. */
-  compassFailDeg?: number;
   /** Minimum GPS observations before leaving `warming-up`. */
   warmupMinObservations?: number;
   /** Minimum coverage score before leaving `warming-up`. */
@@ -73,8 +65,6 @@ interface TrackingQualityOptions {
   residualConfidenceTargetM?: number;
   /** §4.4 GPS-accuracy floor used to normalise residuals (m). */
   gpsAccuracyFloorM?: number;
-  /** §4.3 consecutive compass-agreeing observations for first agreement. */
-  firstAgreementMinStreak?: number;
   /** §4.8 consecutive sub-threshold observations before ok → degraded. */
   degradedHoldoff?: number;
   /**
@@ -97,7 +87,6 @@ interface AlignmentSnapshot {
 }
 interface TrackingQualitySliceState {
   recentAlignments: AlignmentSnapshot[];
-  firstAgreementObservationIndex: number | null;
   report: TrackingQualityReport | null;
   /** §4.8 — consecutive observations with raw confidence < degradedThreshold. */
   degradedConsecutiveCount: number;
@@ -143,7 +132,8 @@ declare function computeConvergence(snapshots: readonly AlignmentSnapshot[], opt
  * the column-major layout that gl-matrix and the framework use.
  *
  * Rotation: extract the orientation quaternion with `mat4.getRotation`
- * and compute the relative angle via `quat.getAngle` (degrees).
+ * and compute the relative angle via the shared `geodesicAngleRad` kernel
+ * (radians, converted to degrees here).
  * Translation: extract the origin column with `mat4.getTranslation` and
  * compute the Euclidean distance.
  *
@@ -206,25 +196,6 @@ declare function computeCoverage(odometryPositions: readonly Vector3[], options?
   walkedDistanceM?: number;
   directionSpreadDeg?: number;
 }): CoverageResult;
-interface CompassAgreementResult {
-  /** `null` when `absolute !== true` on the sensor orientation. */
-  score: number | null;
-  headingDeltaDeg: number | null;
-}
-/**
- * §4.3 — Compare the alignment matrix's mapping of AR-forward to ENU
- * against the device compass heading. Returns `score = null` whenever
- * the sensor's `absolute !== true` so the aggregate excludes the
- * sub-score (per Q2 in the plan).
- *
- * AR-forward in our `ARPose` convention is `(0, 0, -1)` (right-handed,
- * Y-up). We rotate that by the alignment's 3×3 rotation, take its
- * North/East components, and compare against the compass alpha.
- */
-declare function computeCompassAgreement(alignmentMatrix: Matrix4 | null, sensorOrientation: DeviceOrientation | null, arPose: ARPose | null, options?: {
-  warnDeg?: number;
-  failDeg?: number;
-}): CompassAgreementResult;
 /**
  * §4.6 — Maximum lateral distance between raw GPS positions and the
  * positions you would predict by transforming the matching odometry
@@ -234,14 +205,13 @@ declare function computeCompassAgreement(alignmentMatrix: Matrix4 | null, sensor
 declare function computeGpsVsFusedDivergence(alignmentMatrix: Matrix4 | null, gpsPositions: readonly GpsPoint[], odometryPositions: readonly Vector3[], zeroRef: LatLong | null, windowSize?: number): number;
 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">, firstAgreementReached: _$_reduxjs_toolkit0.ActionCreatorWithPayload<number, "trackingQuality/firstAgreementReached">, degradedCountUpdated: _$_reduxjs_toolkit0.ActionCreatorWithPayload<number, "trackingQuality/degradedCountUpdated">, resetTrackingQuality: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"trackingQuality/resetTrackingQuality">;
+  }, "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>;
 interface RootWithTrackingQuality {
   trackingQuality?: TrackingQualitySliceState;
 }
 declare function selectTrackingQuality(state: RootWithTrackingQuality): TrackingQualityReport | null;
 declare function selectRecentAlignments(state: RootWithTrackingQuality): readonly AlignmentSnapshot[];
-declare function selectFirstAgreementObservationIndex(state: RootWithTrackingQuality): number | null;
 /**
  * Pure function — produces a {@link TrackingQualityReport} from a root
  * state and options. The Investigation harness imports this directly to
@@ -339,6 +309,46 @@ interface SlamAppStoreOptions<ExtraReducers extends ReducersMapObject = Record<s
    * @see docs/2026-05-16-tracking-quality-metrics-plan.md
    */
   trackingQualityOptions?: Partial<TrackingQualityOptions>;
+  /**
+   * Enable the library's Phase-4 **Stage-0** cold-start compass yaw override.
+   * **Default `true`** — Stage 0 is a field-validated, default-on feature: at
+   * cold start the GPS-derived yaw is unobservable (clustered fixes ⇒ a yaw set
+   * by noise that flips as the user looks around), so the compass heading gives
+   * a roughly-correct, stable orientation immediately ("open app, stand still,
+   * look around" works). It is an observability-gated handover — once a walked
+   * baseline conditions the GPS yaw, the solve hands back to GPS — so it does no
+   * harm once GPS is observable. Pass `false` to opt out (the recorder exposes
+   * this as a settings toggle).
+   *
+   * When enabled the factory dispatches `setColdStartOverrideEnabled(true)` the
+   * first time `gpsData` becomes non-null (right after the first `setZeroPos`,
+   * since the flag lives on that slice and cannot be set before it exists).
+   *
+   * Replay/determinism: the library's `DefaultAlignmentConfig` stays OFF, so
+   * historical recordings replay unchanged; default-on lives here as a recorded
+   * `gpsData` action. A recording made with this on therefore replays with the
+   * 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
+   */
+  enableCompassColdStartOverride?: boolean;
+  /**
+   * **Debug/experiment flag** — enable the library's Phase-4 **Stage-C**
+   * trust-gated compass rotation prior (keeps a steady compass vote once GPS yaw
+   * is observable + the compass is trusted; supersedes Stage 0). Dispatches
+   * `setCompassRotationPriorEnabled(true)` once `gpsData` exists. Default `false`
+   * ⇒ byte-identical. Like the Stage-0 flag, the action persists into recordings.
+   */
+  enableCompassRotationPrior?: boolean;
+  /**
+   * **Debug/experiment flag** — enable the library's GPS-free compass↔WebXR
+   * consistency gate. When on, the compass override (Stage 0 / Stage C) abstains
+   * unless the compass is rotating in lock-step with the WebXR pose. Dispatches
+   * `setCompassWebXRConsistencyEnabled(true)` once `gpsData` exists. Default
+   * `false` ⇒ byte-identical. The action persists into recordings.
+   */
+  enableCompassWebXRConsistency?: boolean;
 }
 /**
  * Combined root state: the framework's base state plus any caller-supplied
@@ -368,4 +378,4 @@ interface SlamAppStore<ExtraReducers extends ReducersMapObject = Record<string,
  */
 declare function createSlamAppStore<ExtraReducers extends ReducersMapObject = Record<string, never>>(options: SlamAppStoreOptions<ExtraReducers>): SlamAppStore<ExtraReducers>;
 //#endregion
-export { resetTrackingQuality as A, computeResidualConsensus as C, firstAgreementReached as D, degradedCountUpdated as E, snapshotsTrimmed as F, trackingQualityReducer as I, CombinedRootState as L, selectRecentAlignments as M, selectTrackingQuality as N, matrixDelta as O, snapshotPushed as P, computeGpsVsFusedDivergence as S, createTrackingQualityListenerMiddleware as T, TrackingQualityState as _, SlamAppStoreOptions as a, computeCoverage as b, CompassAgreementResult as c, DEFAULT_TRACKING_QUALITY_OPTIONS as d, GpsAccuracyResult as f, TrackingQualitySliceState as g, TrackingQualityReport as h, SlamAppStore as i, selectFirstAgreementObservationIndex as j, reportUpdated as k, ConvergenceResult as l, TrackingQualityOptions as m, SlamAppMiddleware as n, createSlamAppStore as o, ResidualConsensusResult as p, SlamAppRootState as r, AlignmentSnapshot as s, SlamAppCombinedState as t, CoverageResult as u, computeCompassAgreement as v, computeTrackingQualityReport as w, computeGpsAccuracy as x, computeConvergence as y };
+export { snapshotPushed as A, createTrackingQualityListenerMiddleware as C, resetTrackingQuality as D, reportUpdated as E, trackingQualityReducer as M, CombinedRootState as N, selectRecentAlignments as O, computeTrackingQualityReport as S, matrixDelta as T, computeConvergence as _, SlamAppStoreOptions as a, computeGpsVsFusedDivergence as b, ConvergenceResult as c, GpsAccuracyResult as d, ResidualConsensusResult as f, TrackingQualityState as g, TrackingQualitySliceState as h, SlamAppStore as i, snapshotsTrimmed as j, selectTrackingQuality as k, CoverageResult as l, TrackingQualityReport as m, SlamAppMiddleware as n, createSlamAppStore as o, TrackingQualityOptions as p, SlamAppRootState as r, AlignmentSnapshot as s, SlamAppCombinedState as t, DEFAULT_TRACKING_QUALITY_OPTIONS as u, computeCoverage as v, degradedCountUpdated as w, computeResidualConsensus as x, computeGpsAccuracy as y };