gps-plus-slam-app-framework 1.3.0 → 1.7.0

package/dist/create-slam-app-store-DkCHOpvb.js

@@ -0,0 +1,149 @@
+import { trackingReducer } from "./state/tracking-slice.js";
+import { recordWriteFailure, recordingReducer } from "./state/recording-slice.js";
+import { createTrackingQualityListenerMiddleware, trackingQualityReducer } from "./state/tracking-quality.js";
+import { createPersistenceMiddleware, slicePrefixOf } from "./state/persistence-middleware.js";
+import { arElementsReducer, gpsDataReducer, gpsElementsReducer, sanitizeForDevTools, setColdStartOverrideEnabled, setCompassRotationPriorEnabled, setCompassWebXRConsistencyEnabled, setZeroPos, validateLicenseKey } from "gps-plus-slam-js";
+import { configureStore, createListenerMiddleware } from "@reduxjs/toolkit";
+import { COMMUNITY_LICENSE_KEY } from "gps-plus-slam-js/community-license-key";
+//#region ../src/state/slam-app-store-listener.ts
+/**
+* Build a listener middleware that applies the requested compass opt-ins once
+* `gpsData` exists and a flag is still unset. Register it via `.prepend(...)`
+* (so its effect dispatches *outside* the trigger's `next()` — see module doc).
+*
+* Behaviour:
+*  - **Predicate** fires whenever the `gpsData` *object reference* is new since
+*    the last apply AND at least one opt-in is still unset. Two terms, each load-
+*    bearing:
+*    - `s.gpsData !== lastApplied` makes the predicate edge-triggered on gpsData
+*      identity. A recreated `gpsData` (store swap / origin reset) is a fresh
+*      object, so it still re-triggers the apply — the re-apply semantics the
+*      2026-06-27 field bug demands are preserved. Do NOT weaken this to a
+*      `null → non-null` transition: that would drop the re-apply. The point of
+*      keying on the *reference* (not on "a flag is unset") is that it also stops
+*      the effect from re-firing for the SAME gpsData.
+*    - `optIns.some((o) => !o.isSet(s))` keeps the no-op case (all flags already
+*      set) from scheduling an effect at all.
+*    Why the reference guard matters: without it the predicate is purely level-
+*    based, so if an opt-in's `apply` dispatches but `isSet` never flips true
+*    (e.g. consumer/library **version skew** where the action type no longer
+*    matches the reducer — the packages are published independently), the
+*    condition stays true forever and every effect dispatch re-arms it: an
+*    unbounded storm that freezes the app. The per-dispatch `isSet` re-check
+*    below guards only against dispatching an *already-set* flag twice; it does
+*    nothing when the flag never sets. The reference guard is what bounds it.
+*  - **Effect** records the gpsData reference it is acting on, then dispatches
+*    every still-unset opt-in as a top-level action. `isSet` is re-read against
+*    the *current* store state immediately before each dispatch (not one snapshot
+*    at effect entry): a dispatch is synchronous, so a flag is already set by the
+*    time the next check runs, and an opt-in's own dispatch can re-enter this
+*    effect before the loop finishes. Re-checking per dispatch makes that
+*    re-entrancy idempotent — a flag is dispatched only while still unset.
+*/
+function createSlamAppStoreListenerMiddleware(optIns) {
+	const listenerMiddleware = createListenerMiddleware();
+	let lastApplied = null;
+	listenerMiddleware.startListening({
+		predicate: (_action, currentState) => {
+			const s = currentState;
+			return s.gpsData !== null && s.gpsData !== lastApplied && optIns.some((optIn) => !optIn.isSet(s));
+		},
+		effect: (_action, api) => {
+			const entry = api.getState();
+			if (entry.gpsData === null) return;
+			lastApplied = entry.gpsData;
+			for (const optIn of optIns) {
+				const s = api.getState();
+				if (s.gpsData === null) return;
+				if (!optIn.isSet(s)) optIn.apply((action) => {
+					api.dispatch(action);
+				});
+			}
+		}
+	});
+	return listenerMiddleware.middleware;
+}
+//#endregion
+//#region ../src/state/create-slam-app-store.ts
+/**
+* `createSlamAppStore` — composable Redux store factory for AR+GPS apps.
+*
+* Introduced in Iter 1 of the AppFramework/RecorderApp boundary migration.
+* Wires the three library reducers (`gpsData`, `gpsElements`, `arElements`),
+* the framework's recording lifecycle slice, and the persistence middleware.
+*
+* Recorder-only state (routing screen, ref-points, scenario) is plugged in
+* by the consumer via `extraReducers` / `extraMiddleware`. The factory itself
+* never references those concepts so apps that don't need them (POI viewers,
+* navigation arrows, …) compose freely.
+*
+* The legacy `createRecorderStore` from `store.ts` is built on top of this
+* factory and will move out of the framework in Iter 1D.
+*
+* @see docs/2026-05-03-appframework-vs-recorderapp-boundary-analysis.md — Iter 1
+*/
+/**
+* Slice prefixes the framework always persists, derived from the actual
+* library / framework action creators (never hand-typed). A rename of the
+* `gpsData` or `recording` slice therefore propagates here automatically
+* instead of silently dropping that slice's actions from recordings.
+*/
+const BUILTIN_PERSISTED_PREFIXES = [slicePrefixOf(setZeroPos.type), slicePrefixOf(recordWriteFailure.type)];
+/**
+* Build a Redux store wired with library + recording slices, persistence
+* middleware, and any caller-supplied extras. See module docstring for the
+* design rationale.
+*/
+function createSlamAppStore(options) {
+	const { storageBackend, extraReducers, extraMiddleware, persistedExtraPrefixes, onWriteFailure, enableDevChecks = true, licenseKey = COMMUNITY_LICENSE_KEY, trackingQualityOptions, enableCompassColdStartOverride = true, enableCompassRotationPrior = false, enableCompassWebXRConsistency = false } = options;
+	validateLicenseKey(licenseKey);
+	const reducer = {
+		gpsData: gpsDataReducer,
+		gpsElements: gpsElementsReducer,
+		arElements: arElementsReducer,
+		recording: recordingReducer,
+		tracking: trackingReducer,
+		trackingQuality: trackingQualityReducer,
+		...extraReducers ?? {}
+	};
+	const trackingQualityMiddleware = createTrackingQualityListenerMiddleware(trackingQualityOptions);
+	const compassOptIns = [];
+	if (enableCompassColdStartOverride) compassOptIns.push({
+		isSet: (s) => s.gpsData?.coldStartOverrideEnabled === true,
+		apply: (dispatch) => dispatch(setColdStartOverrideEnabled(true))
+	});
+	if (enableCompassRotationPrior) compassOptIns.push({
+		isSet: (s) => s.gpsData?.compassRotationPriorEnabled === true,
+		apply: (dispatch) => dispatch(setCompassRotationPriorEnabled(true))
+	});
+	if (enableCompassWebXRConsistency) compassOptIns.push({
+		isSet: (s) => s.gpsData?.compassWebXRConsistencyEnabled === true,
+		apply: (dispatch) => dispatch(setCompassWebXRConsistencyEnabled(true))
+	});
+	const prependedListeners = [trackingQualityMiddleware];
+	if (compassOptIns.length > 0) prependedListeners.push(createSlamAppStoreListenerMiddleware(compassOptIns));
+	const store = configureStore({
+		reducer,
+		middleware: (getDefaultMiddleware) => getDefaultMiddleware({
+			serializableCheck: enableDevChecks,
+			immutableCheck: enableDevChecks
+		}).prepend(...prependedListeners).concat(createPersistenceMiddleware({
+			storageBackend,
+			onWriteFailure,
+			persistedPrefixes: [...BUILTIN_PERSISTED_PREFIXES, ...persistedExtraPrefixes ?? []]
+		}), ...extraMiddleware ?? []),
+		devTools: {
+			actionSanitizer: sanitizeForDevTools,
+			stateSanitizer: sanitizeForDevTools
+		}
+	});
+	return {
+		getState: () => store.getState(),
+		dispatch: store.dispatch,
+		subscribe: (listener) => store.subscribe(listener),
+		writeFrame: (blob, index) => storageBackend.writeFrame(blob, index),
+		writeSessionMetadata: (metadata) => storageBackend.writeSessionMetadata(metadata)
+	};
+}
+//#endregion
+export { createSlamAppStore as t };

package/dist/{create-slam-app-store-BljusOua.d.ts → create-slam-app-store-n_VF63D5.d.ts}

@@ -1,8 +1,7 @@
-import { t as ARPose } from "./ar-types-Dan1MVTi.js";
-import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-CdK8c-8P.js";
-import { t as RecordingState } from "./recording-slice-89O07ebs.js";
-import { n as SessionMetadata } from "./opfs-storage-D5zAn_lx.js";
-import { n as StorageBackend } from "./storage-backend-Do6YDpNo.js";
+import { a as TrackingSliceState } from "./tracking-slice-BuAZxXZ5.js";
+import { t as RecordingState } from "./recording-slice-DaxHZvNu.js";
+import { n as SessionMetadata } from "./opfs-storage-3VZh-qH6.js";
+import { n as StorageBackend } from "./storage-backend-BdVLD0dU.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 };

package/dist/depth-grid-lookup-DQ-IYhO3.d.ts

@@ -0,0 +1,21 @@
+import { r as DepthPoint } from "./ar-types-BFX2r1wk.js";
+
+//#region ../src/ar/depth-grid-lookup.d.ts
+interface DepthGridLookup {
+  /**
+   * Bilinearly-interpolated depth (m) at a normalized screen point (top-left
+   * origin), or `null` when the point is outside the node grid or any of the
+   * four surrounding nodes has no valid (finite, positive) depth.
+   */
+  depthAt(screenX: number, screenY: number): number | null;
+}
+/**
+ * Build a bilinear lookup over a depth-sampler grid.
+ *
+ * @param points - the grid `DepthPoint`s (row-major, `row·g + col`).
+ * @param gridSize - points-per-side; inferred as `round(√points.length)` when
+ *   omitted (the sampler always emits a full `g²` grid).
+ */
+declare function createDepthGridLookup(points: readonly DepthPoint[], gridSize?: number): DepthGridLookup;
+//#endregion
+export { createDepthGridLookup as n, DepthGridLookup as t };

package/dist/{depth-sampler-Bhanfwla.d.ts → depth-sampler-asc8exHt.d.ts}

@@ -1,4 +1,4 @@
-import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-BFX2r1wk.js";
 import { Matrix4 } from "gps-plus-slam-js";
 
 //#region ../src/ar/depth-rgb-lookup.d.ts

package/dist/{depth-unprojection-Y6i_mJuT.d.ts → depth-unprojection-DjsbJW9L.d.ts}

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

package/dist/{enable-gps-ar-BfUJOgpW.d.ts → enable-gps-ar-DkNhFv4Y.d.ts}

@@ -1,7 +1,7 @@
-import { t as ArCrashIsolationOptions } from "./recording-options-DJBXuMxV.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-VuezJWK3.js";
-import { n as PermissionStatus } from "./permission-checker-GpAiSCwd.js";
-import { t as SessionFeatureOptions } from "./webxr-session-GjZ2BIpS.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-BPCpMHLK.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-BBO3hKfT.js";
+import { n as PermissionStatus } from "./permission-checker-CDuI8BwC.js";
+import { r as SessionFeatureOptions } from "./webxr-session-Do5L6G3B.js";
 
 //#region ../src/ar/enable-gps-ar.d.ts
 /**

package/dist/{frame-conversions-BfsafGWR.d.ts → frame-conversions-DObhj8Wf.d.ts}

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

package/dist/{fused-path-DJoVu98b.d.ts → fused-path-v6eOmLl3.d.ts}

@@ -1,4 +1,4 @@
-import { t as GpsCoord } from "./geo-types-SaPnIEUM.js";
+import { t as GpsCoord } from "./geo-types-3Ip1NzVR.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 gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-I1msGPgE.js";
-export { H3_RESOLUTION, KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+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-C-j0pw1j.js";
+export { H3_RESOLUTION, KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/h3-proximity.js

@@ -1,4 +1,4 @@
-import { gridDisk, latLngToCell } from "h3-js";
+import { cellToParent, getResolution, gridDisk, isValidCell, latLngToCell } from "h3-js";
 //#region ../src/geo/h3-proximity.ts
 /**
 * H3 Geo-Anchor Proximity Matching
@@ -22,6 +22,65 @@ function gpsToH3(lat, lng) {
 	return latLngToCell(lat, lng, 11);
 }
 /**
+* Reduce a recorded GPS path to the deduplicated set of res-11 H3 cells it
+* crossed — the per-tour "coverage index" stored in `SessionMetadata.h3Cells`.
+*
+* Cells are returned in first-seen (chronological) order and deduplicated, so a
+* tour that dwells in one ~25 m cell contributes a single cell. This keeps the
+* stored index small (see the metadata-size risk in the map-browser feedback
+* doc, §7). Non-finite coordinates are skipped defensively — bad sensor data
+* must not poison the index or throw inside `latLngToCell`.
+*/
+function gpsPathToCoverageCells(path) {
+	const seen = /* @__PURE__ */ new Set();
+	const cells = [];
+	for (const p of path) {
+		if (!Number.isFinite(p.lat) || !Number.isFinite(p.lng)) continue;
+		const cell = gpsToH3(p.lat, p.lng);
+		if (!seen.has(cell)) {
+			seen.add(cell);
+			cells.push(cell);
+		}
+	}
+	return cells;
+}
+/**
+* Coarsen res-11 coverage cells to a target resolution for map zoom-clustering.
+*
+* Uses h3-js `cellToParent` — the ONLY correct way to coarsen an H3 cell. NEVER
+* 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).
+*
+* `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
+* data stored — so the highest map zooms render the stored cells unclustered
+* (`cellToParent(cell, 11) === cell`). A non-finite `targetRes` (e.g. a bad
+* zoom→res mapping) degrades to unclustered output rather than throwing.
+* Invalid input cells (corrupt/legacy metadata) are skipped defensively, as are
+* valid cells coarser than `res` (which have no parent at the finer target res
+* and would otherwise throw "incompatible resolutions").
+*
+* Output is deduplicated in first-seen order: sibling cells under one parent
+* collapse to a single tile.
+*/
+function clusterCellsByZoom(cells, targetRes) {
+	const res = Number.isFinite(targetRes) ? Math.max(0, Math.min(11, Math.floor(targetRes))) : 11;
+	const seen = /* @__PURE__ */ new Set();
+	const parents = [];
+	for (const cell of cells) {
+		if (!isValidCell(cell)) continue;
+		if (getResolution(cell) < res) continue;
+		const parent = cellToParent(cell, res);
+		if (!seen.has(parent)) {
+			seen.add(parent);
+			parents.push(parent);
+		}
+	}
+	return parents;
+}
+/**
 * Approximate distance in metres using equirectangular projection.
 * Accurate to < 0.1% for distances under 1 km at mid-latitudes,
 * which is sufficient for ranking ref point candidates within a
@@ -75,4 +134,4 @@ function isH3Index(id) {
 	return H3_INDEX_PATTERN.test(id);
 }
 //#endregion
-export { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+export { H3_RESOLUTION, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/index.d.ts

@@ -1,2 +1,2 @@
-import { a as gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-I1msGPgE.js";
-export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+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-C-j0pw1j.js";
+export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/index.js

@@ -1,2 +1,2 @@
-import { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index } from "./h3-proximity.js";
-export { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+import { H3_RESOLUTION, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index } from "./h3-proximity.js";
+export { H3_RESOLUTION, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geodesic-angle-BTldfFgs.js

@@ -0,0 +1,39 @@
+import { quat } from "gl-matrix";
+//#region ../src/utils/geodesic-angle.ts
+/**
+* Geodesic-angle kernel — the single shared definition of the shortest-arc
+* rotation angle between two unit quaternions.
+*
+* This used to be hand-rolled in (at least) two places:
+* - `geodesicAngleRad` (private) in `ar/qr-pose-aggregation.ts`, and
+* - `quat.getAngle(...)` + a NaN guard inside `state/tracking-quality.ts`'s
+*   `matrixDelta`.
+*
+* Both compute the same number — `acos(2·dot² − 1)` — so they are consolidated
+* here so a third consumer (the capture motion gate's angular-velocity helper,
+* `ar/pose-motion.ts`) reuses one definition instead of adding a fourth copy.
+* See `GpsPlusSlamJs_Docs/docs/2026-06-23-followup-consolidate-geodesic-angle-kernel.md`.
+*/
+/**
+* Geodesic (shortest-arc) rotation angle in radians between two **unit**
+* quaternions.
+*
+* Uses `cos θ = 2·dot² − 1`, which is invariant to the sign of either input
+* (`q` ≡ `−q`, the quaternion double cover) because it depends only on `dot²`.
+* The argument is clamped to `[-1, 1]` before `acos` so float error on a
+* near-identical pair (where `2·dot² − 1` can drift slightly above 1) returns
+* `0` rather than `NaN` — this is the guard `matrixDelta` previously applied
+* explicitly around the raw `quat.getAngle`.
+*
+* Precondition: both inputs are (approximately) unit length. Callers that hold
+* un-normalized quaternions must normalize first (gl-matrix `quat.normalize`).
+*
+* @returns angle in radians, in `[0, π]`. Never `NaN` for finite unit inputs.
+*/
+function geodesicAngleRad(a, b) {
+	const d = quat.dot(a, b);
+	const c = Math.min(1, Math.max(-1, 2 * d * d - 1));
+	return Math.acos(c);
+}
+//#endregion
+export { geodesicAngleRad as t };

package/dist/{gps-anchor-dYeCvvp5.d.ts → gps-anchor-BeFO2RYa.d.ts}

@@ -1,4 +1,4 @@
-import { i as LatLongAlt, r as LatLong } from "./index-CF05QV2m.js";
+import { i as LatLongAlt, r as LatLong } from "./index-_Rhgoqkh.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/gps-anchor.d.ts

package/dist/{gps-ar-pose-sampler-DVb96iOy.d.ts → gps-ar-pose-sampler-DHMZmYAc.d.ts}

@@ -1,4 +1,4 @@
-import { t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { t as ARPose } from "./ar-types-BFX2r1wk.js";
 import { Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/state/gps-ar-pose-sampler.d.ts

package/dist/{gps-event-coordinator-CWIDOk4U.d.ts → gps-event-coordinator-CjWW636x.d.ts}

@@ -1,7 +1,8 @@
-import { t as ARPose } from "./ar-types-Dan1MVTi.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-VuezJWK3.js";
-import { i as SlamAppStore } from "./create-slam-app-store-BljusOua.js";
-import { Quaternion, RawGpsPoint, RecordGpsEventPayload, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
+import { t as ARPose } from "./ar-types-BFX2r1wk.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-BBO3hKfT.js";
+import { t as AbsoluteOrientationReading } from "./absolute-orientation-CAEh840t.js";
+import { i as SlamAppStore } from "./create-slam-app-store-n_VF63D5.js";
+import { Quaternion, RawAbsoluteOrientation, RawGpsPoint, RecordGpsEventPayload, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
 import { ReducersMapObject } from "@reduxjs/toolkit";
 
 //#region ../src/state/gps-event-coordinator.d.ts
@@ -44,28 +45,37 @@ declare function extractOdomRotation(arPose: ARPose): Quaternion;
 /**
  * Build a RawGpsPoint from GPS position data.
  * Returns only raw sensor fields — no derived fields (coordinates, weight,
- * zeroRef, deviceRotation). Derived fields are computed by the library
- * reducer when the action is dispatched (raw-storage pattern).
+ * zeroRef). Derived fields are computed by the library reducer when the
+ * action is dispatched (raw-storage pattern).
  *
  * @param gpsPosition - GPS position from Geolocation API
- * @param deviceOrientation - Optional device orientation from sensors
+ * @param deviceOrientation - Accepted for signature stability; no longer
+ *   read (the legacy `compassAbsolute` field it fed is no longer recorded)
  * @returns RawGpsPoint ready for the action payload
  */
 declare function buildRawGpsPoint(gpsPosition: GpsPosition, deviceOrientation: RawDeviceOrientation | null): RawGpsPoint;
+/**
+ * Map a capture-module {@link AbsoluteOrientationReading} to the library's
+ * {@link RawAbsoluteOrientation} payload shape (the only difference is the
+ * timestamp field name: capture `timestamp` → payload `sampleTimestamp`).
+ * Returns `undefined` when the sensor produced no reading (most non-Chrome).
+ */
+declare function toRawAbsoluteOrientation(reading: AbsoluteOrientationReading | null): RawAbsoluteOrientation | undefined;
 /**
  * Build a RecordGpsEventPayload from GPS position and AR pose.
  * This is a pure function for testability.
  *
  * Stores only raw sensor data in the payload. The library reducer
- * computes derived fields (coordinates, weight, deviceRotation)
- * when the action is processed (raw-storage pattern).
+ * computes derived fields (coordinates, weight) when the action is
+ * processed (raw-storage pattern).
  *
  * @param gpsPosition - GPS position from Geolocation API
  * @param arPose - AR pose from WebXR
  * @param deviceOrientation - Optional device orientation from sensors
+ * @param absoluteOrientation - Optional AbsoluteOrientationSensor reading
  * @returns RecordGpsEventPayload ready for dispatch
  */
-declare function buildRecordGpsEventPayload(gpsPosition: GpsPosition, arPose: ARPose, deviceOrientation: RawDeviceOrientation | null): RecordGpsEventPayload;
+declare function buildRecordGpsEventPayload(gpsPosition: GpsPosition, arPose: ARPose, deviceOrientation: RawDeviceOrientation | null, absoluteOrientation?: AbsoluteOrientationReading | null): RecordGpsEventPayload;
 /**
  * Create a GPS position handler that dispatches combined GPS+AR events.
  *
@@ -79,4 +89,4 @@ declare function buildRecordGpsEventPayload(gpsPosition: GpsPosition, arPose: AR
  */
 declare function createGpsPositionHandler(config: RecordingCoordinatorConfig): (position: GpsPosition) => void;
 //#endregion
-export { eulerToQuaternion as a, getLastDeviceOrientation as c, createGpsPositionHandler as i, resetCoordinatorState as l, buildRawGpsPoint as n, extractOdomPosition as o, buildRecordGpsEventPayload as r, extractOdomRotation as s, RecordingCoordinatorConfig as t, updateDeviceOrientation as u };
+export { eulerToQuaternion as a, getLastDeviceOrientation as c, updateDeviceOrientation as d, createGpsPositionHandler as i, resetCoordinatorState as l, buildRawGpsPoint as n, extractOdomPosition as o, buildRecordGpsEventPayload as r, extractOdomRotation as s, RecordingCoordinatorConfig as t, toRawAbsoluteOrientation as u };

package/dist/{gps-event-markers-Dc9FT-q1.d.ts → gps-event-markers-Cz9RMA2k.d.ts}

@@ -24,6 +24,14 @@ declare class GpsEventVisualizer {
   private zeroRef;
   private eventCounter;
   private snapshotCounter;
+  /**
+   * Whether the debug markers are drawn. Toggled by {@link setVisible} for the
+   * recorder's `visualization.gpsAlignmentMarkers` opt-out (Finding B). Applied
+   * to every marker at creation so events spawned later by the live
+   * store-subscriber inherit the current state instead of popping into view.
+   * Default `true` — the markers render exactly as before until opted out.
+   */
+  private markersVisible;
   /**
    * Set the GPS zero reference (origin for coordinate conversion).
    * Must be called before adding GPS events.
@@ -64,6 +72,16 @@ declare class GpsEventVisualizer {
    * Create a sphere marker mesh with the given color and name.
    */
   private createMarkerMesh;
+  /**
+   * Show or hide ALL debug markers — raw GPS (yellow), fused (cyan), and
+   * alignment-snapshot (red) — and remember the state so markers added later
+   * inherit it. Used by the recorder's `visualization.gpsAlignmentMarkers`
+   * opt-out, read once at Enter-AR (live only; replay keeps markers visible).
+   *
+   * This only changes rendering: capture, GPS-event recording, counts, and the
+   * snapshot positions read back at session end are all unaffected.
+   */
+  setVisible(visible: boolean): void;
   /**
    * Clear all markers from the scene and reset state.
    */