gps-plus-slam-app-framework 1.10.0 → 1.13.0

package/dist/{create-slam-app-store-DLv5ZwqU.js → create-slam-app-store-wYN7YkB5.js}

@@ -2,7 +2,7 @@ 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 { arElementsReducer, gpsDataReducer, gpsElementsReducer, sanitizeForDevTools, setColdStartOverrideEnabled, setCompassExperimentEnabled, setCompassRotationPriorEnabled, setCompassWebXRConsistencyEnabled, setRobustSolverComparisonEnabled, 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
@@ -77,8 +77,9 @@ function createSlamAppStoreListenerMiddleware(optIns) {
 * 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.
+* This is the framework's ONLY store factory (the legacy
+* `createRecorderStore`/`store.ts` it replaced moved out in Iter 1D); the
+* core library's license error messages point here as the remediation.
 *
 * @see docs/2026-05-03-appframework-vs-recorderapp-boundary-analysis.md — Iter 1
 */
@@ -95,7 +96,7 @@ const BUILTIN_PERSISTED_PREFIXES = [slicePrefixOf(setZeroPos.type), slicePrefixO
 * 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;
+	const { storageBackend, extraReducers, extraMiddleware, persistedExtraPrefixes, onWriteFailure, enableDevChecks = true, licenseKey = COMMUNITY_LICENSE_KEY, trackingQualityOptions, enableCompassColdStartOverride = true, enableCompassRotationPrior = false, enableCompassWebXRConsistency = false, enableCompassExperiment = false, enableRobustSolverComparison = false } = options;
 	validateLicenseKey(licenseKey);
 	const builtins = {
 		gpsData: gpsDataReducer,
@@ -127,18 +128,27 @@ function createSlamAppStore(options) {
 		isSet: (s) => s.gpsData?.compassWebXRConsistencyEnabled === true,
 		apply: (dispatch) => dispatch(setCompassWebXRConsistencyEnabled(true))
 	});
+	if (enableCompassExperiment) compassOptIns.push({
+		isSet: (s) => s.gpsData?.compassExperimentEnabled === true,
+		apply: (dispatch) => dispatch(setCompassExperimentEnabled(true))
+	});
+	if (enableRobustSolverComparison) compassOptIns.push({
+		isSet: (s) => s.gpsData?.robustSolverComparisonEnabled === true,
+		apply: (dispatch) => dispatch(setRobustSolverComparisonEnabled(true))
+	});
 	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 ? { ignoredActions: ["tracking/poseReceived"] } : false,
 			immutableCheck: enableDevChecks ? { ignoredPaths: ["tracking"] } : false
-		}).prepend(...prependedListeners).concat(createPersistenceMiddleware({
-			storageBackend,
-			onWriteFailure,
-			persistedPrefixes: [...BUILTIN_PERSISTED_PREFIXES, ...persistedExtraPrefixes ?? []]
-		}), ...extraMiddleware ?? []),
+		}).prepend(...prependedListeners).concat(persistenceMiddleware, ...extraMiddleware ?? []),
 		devTools: {
 			actionSanitizer: sanitizeForDevTools,
 			stateSanitizer: sanitizeForDevTools
@@ -149,7 +159,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-DY6zYTLx.d.ts → depth-grid-lookup-PcJTdRLL.d.ts}

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

package/dist/{depth-sampler-txG8evgQ.d.ts → depth-sampler-BcvuxgCS.d.ts}

@@ -1,4 +1,4 @@
-import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-CBafnxhE.js";
+import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-BprL3nKv.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;
   /**
@@ -114,6 +114,33 @@ declare function wrapXRDepthInfo(raw: {
     matrix?: ArrayLike<number>;
   } | null;
 }, projectionMatrix: ArrayLike<number> | undefined): DepthInfo;
+/**
+ * Recommended depth-sampling cadence for apps that RECONSTRUCT-and-render an
+ * occupancy mesh (the Recorder, the PhysicsDemo) — the depth-side counterpart
+ * of `DEFAULT_OCCUPANCY_CELL_SIZE_M`/`DEFAULT_OCCUPANCY_MIN_OBSERVATIONS`
+ * (occupancy-grid.ts): one framework-level source of truth so both apps build
+ * the mesh at the same speed (2026-07-16 field feedback: the demo relied on
+ * the conservative fallback below — 16×16 @ 1 Hz, 8× fewer points/s than the
+ * recorder — and reconstructed visibly slower).
+ *
+ * Tuning (2026-07-16 EVENING, maintainer's on-device framerate/mesh trade-off
+ * passes — supersedes the same-day sweep-derived 500 ms × 64): 200 ms × 24×24.
+ * The ground-truth density/cadence sweep
+ * (GpsPlusSlamJs_Investigation test-results/synthetic-density-cadence-sweep.txt)
+ * showed density is the more point-efficient mesh-speed lever, but its
+ * flagged open question — on-device frame-time cost — resolved against LARGE
+ * per-sample batches: 64² @ 2 Hz (8192 points/s) visibly hurt the framerate,
+ * while many SMALL samples (24² @ 5 Hz, ~2880 points/s) keep the per-frame
+ * work chunk tiny and rendering smooth at good mesh build-up. If devices get
+ * faster, the sweep says gridSize (not the interval) is the knob to raise
+ * first.
+ *
+ * Deliberately OPT-IN named constants, NOT a change to the fallback below:
+ * bumping the fallback would silently re-tune consumers that are not
+ * reconstruction apps (MinimalExample / AnchorStarter).
+ */
+declare const DEFAULT_RECONSTRUCTION_DEPTH_INTERVAL_MS = 200;
+declare const DEFAULT_RECONSTRUCTION_DEPTH_GRID_SIZE = 24;
 /**
  * Samples sparse depth points from WebXR depth sensing.
  *
@@ -208,4 +235,4 @@ declare class DepthSampler {
   hasReceivedDepth(): boolean;
 }
 //#endregion
-export { wrapXRDepthInfo as a, DepthSamplerConfig as i, DepthSampler as n, DepthSamplerCallbacks as r, DepthInfo as t };
+export { DepthSamplerCallbacks as a, DepthSampler as i, DEFAULT_RECONSTRUCTION_DEPTH_INTERVAL_MS as n, DepthSamplerConfig as o, DepthInfo as r, wrapXRDepthInfo as s, DEFAULT_RECONSTRUCTION_DEPTH_GRID_SIZE as t };

package/dist/{depth-unprojection-JKkeqJrV.d.ts → depth-unprojection-DbGipFkA.d.ts}

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

package/dist/{enable-gps-ar-BbNWyqp5.d.ts → enable-gps-ar-xjz3jNqm.d.ts}

@@ -1,7 +1,7 @@
-import { t as ArCrashIsolationOptions } from "./recording-options-Cai9D14V.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CX5b9g3s.js";
-import { n as PermissionStatus } from "./permission-checker-D1C5zvo-.js";
-import { s as SessionFeatureOptions } from "./webxr-session-CGFZ429B.js";
+import { t as ArCrashIsolationOptions } from "./ar-crash-isolation-BSFw_beO.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CC0l9lCp.js";
+import { n as PermissionStatus } from "./permission-checker-BDrCOwQF.js";
+import { a as SessionFeatureOptions, t as ArSessionCallbacks } from "./webxr-session-DurXRnl_.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-CfLTj5Ra.d.ts → file-system-utils-DE3BViuq.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-CH7E2Iv_.d.ts → frame-conversions-CzPQDYpM.d.ts}

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

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

@@ -1,4 +1,4 @@
-import { t as GpsCoord } from "./geo-types-BfDK8kJu.js";
+import { t as GpsCoord } from "./geo-types-DGe5UKgx.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-pFluGfwL.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-CAEk3osq.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-pFluGfwL.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-CAEk3osq.js";
 export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/{geodesic-angle-HXBWiXiI.js → geodesic-angle-CZ_Ow90I.js}

@@ -5,14 +5,14 @@ import { quat } from "gl-matrix";
 * 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
+* - `geodesicAngleRad` (private) in `ar/qr/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`.
+* See `GpsPlusSlamJs_Docs/docs/2026-06-23-2120-consolidate-geodesic-angle-kernel-followup.md`.
 */
 /**
 * Geodesic (shortest-arc) rotation angle in radians between two **unit**

package/dist/{gps-anchor-BaqyRsPC.d.ts → gps-anchor-Gv4NDwH4.d.ts}

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

package/dist/{gps-ar-pose-sampler-BOOV0jJk.d.ts → gps-ar-pose-sampler-DBEYDFY5.d.ts}

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

package/dist/{gps-event-coordinator-03rVh_us.d.ts → gps-event-coordinator-BKwB4RyQ.d.ts}

@@ -1,7 +1,7 @@
-import { t as ARPose } from "./ar-types-CBafnxhE.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CX5b9g3s.js";
-import { t as AbsoluteOrientationReading } from "./absolute-orientation-C_IxDR_j.js";
-import { i as SlamAppStore } from "./create-slam-app-store-CH31erpP.js";
+import { t as ARPose } from "./ar-types-BprL3nKv.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CC0l9lCp.js";
+import { t as AbsoluteOrientationReading } from "./absolute-orientation-0WIsqJnu.js";
+import { i as SlamAppStore } from "./create-slam-app-store-HNe1PBtx.js";
 import { RawAbsoluteOrientation, RawGpsPoint, RecordGpsEventPayload, eulerToQuaternion } from "gps-plus-slam-js";
 import { ReducersMapObject } from "@reduxjs/toolkit";
 

package/dist/{gps-event-markers-BsC2Ynlh.d.ts → gps-event-markers-212h7j3D.d.ts}

@@ -1,6 +1,26 @@
-import { LatLong, Vector3 } from "gps-plus-slam-js";
+import * as THREE from "three";
+import { LatLong, Vector3 as Vector3$1 } from "gps-plus-slam-js";
 
 //#region ../src/visualization/gps-event-markers.d.ts
+/**
+ * Where the visualizer resolves its scene graph from.
+ *
+ * By default markers are parented into the LIVE AR session's scene
+ * (`webxr-session.ts` getters). Non-live consumers (desktop replay, offline
+ * e2e fixtures) point the visualizer at their own scene via
+ * {@link GpsEventVisualizer.setSceneSource} instead of injecting their scene
+ * into the webxr-session singleton (the deleted replay-mode "Risk R1" setters
+ * — see the 2026-07-11 webxr-session surface-reduction plan, step 2).
+ *
+ * Both functions may return `null` (e.g. before `initAR()`); the visualizer
+ * then warns and skips the affected marker, exactly as before.
+ */
+interface GpsMarkerSceneSource {
+  /** Scene root — parents raw-GPS (yellow) and snapshot (red) markers. */
+  getScene: () => THREE.Scene | null;
+  /** AR world group — parents fused (cyan) markers so they ride the alignment. */
+  getArWorldGroup: () => THREE.Group | null;
+}
 /**
  * Optional GPS-accuracy hints used by {@link GpsEventVisualizer.addGpsEvent}
  * to render the raw-GPS marker as a non-uniform-scaled ellipsoid.
@@ -32,6 +52,20 @@ declare class GpsEventVisualizer {
    * Default `true` — the markers render exactly as before until opted out.
    */
   private markersVisible;
+  /**
+   * Scene graph the markers are parented into. Defaults to the live AR
+   * session ({@link LIVE_SCENE_SOURCE}); replay / offline consumers override
+   * it via {@link setSceneSource}. Not reset by {@link clearAll} — the owner
+   * of the non-live scene (e.g. replay-mode's dispose) restores the default.
+   */
+  private sceneSource;
+  /**
+   * Point the visualizer at a non-live scene graph (desktop replay, offline
+   * e2e fixture). Pass `null` to restore the live-session default. The caller
+   * that overrides the source is responsible for restoring it when its scene
+   * is disposed, so a later live AR session parents markers correctly again.
+   */
+  setSceneSource(source: GpsMarkerSceneSource | null): void;
   /**
    * Set the GPS zero reference (origin for coordinate conversion).
    * Must be called before adding GPS events.
@@ -56,18 +90,18 @@ declare class GpsEventVisualizer {
    *   fixed 8 cm sphere (same defensive policy as `preview-map.ts`).
    *   Cyan fused and red snapshot markers are never affected by this argument.
    */
-  addGpsEvent(gpsCoords: Vector3, odomPosition: Vector3, accuracy?: GpsEventAccuracy): void;
+  addGpsEvent(gpsCoords: Vector3$1, odomPosition: Vector3$1, accuracy?: GpsEventAccuracy): void;
   /**
    * Add an alignment snapshot marker at the given NUE position.
    * Snapshots represent the system's best GPS estimate at each alignment update.
    * Added to scene root (GPS world space), not arWorldGroup.
    */
-  addAlignmentSnapshot(nuePosition: Vector3): void;
+  addAlignmentSnapshot(nuePosition: Vector3$1): void;
   /**
    * Get the NUE positions of all alignment snapshot markers.
    * Used at session end to convert to GPS coordinates for the summary map.
    */
-  getAlignmentSnapshotPositions(): Vector3[];
+  getAlignmentSnapshotPositions(): Vector3$1[];
   /**
    * Create a sphere marker mesh with the given color and name.
    */
@@ -118,4 +152,4 @@ declare class GpsEventVisualizer {
  */
 declare const gpsEventVisualizer: GpsEventVisualizer;
 //#endregion
-export { GpsEventVisualizer as n, gpsEventVisualizer as r, GpsEventAccuracy as t };
+export { gpsEventVisualizer as i, GpsEventVisualizer as n, GpsMarkerSceneSource as r, GpsEventAccuracy as t };

package/dist/{h3-proximity-pFluGfwL.d.ts → h3-proximity-CAEk3osq.d.ts}

@@ -52,7 +52,7 @@ declare function gpsPathToCoverageCells(path: readonly LatLngLike[]): string[];
  * 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/hit-test-reticle-driver-CfKiDgsa.d.ts

@@ -0,0 +1,40 @@
+import { Object3D, Vector3 } from "three";
+
+//#region ../src/ar/hit-test-reticle-driver.d.ts
+/** Live-reticle handle returned by {@link startHitTestReticle}. */
+interface HitTestReticleHandle {
+  /** Is a surface currently under the screen-centre reticle? */
+  isVisible(): boolean;
+  /**
+   * Write the reticle's current world position into `out` and return it. Only
+   * meaningful while `isVisible()` is true; the value is the GPS-world (NUE)
+   * pose once `arWorldGroup` carries the alignment.
+   */
+  getWorldPosition(out: Vector3): Vector3;
+  /** Remove the reticle mesh and unregister the frame loop (idempotent). */
+  dispose(): void;
+}
+/** Arguments for {@link startHitTestReticle}. */
+interface HitTestReticleArgs {
+  /**
+   * Parent for the reticle mesh — pass `getArWorldGroup()` so the reticle
+   * rides the GPS alignment and its world pose is GPS-world (NUE).
+   */
+  arWorldGroup: Object3D;
+  /**
+   * Optional tap handler, fired on EVERY WebXR `select` — with the reticle's
+   * current world position when a surface is present, or `null` when not.
+   * Surface-less taps are reported too so the app can react (GPS gating,
+   * "point at the floor" hints); the placement decision stays app-side.
+   * When omitted, no `select` listener is registered at all.
+   */
+  onSelect?: (worldPosition: Vector3 | null) => void;
+}
+/**
+ * Install the hit-test reticle under `arWorldGroup` and start driving it from
+ * the XR frame loop. Returns a handle the app reads at placement time (or
+ * ignores entirely when it placed via `onSelect`).
+ */
+declare function startHitTestReticle(args: HitTestReticleArgs): HitTestReticleHandle;
+//#endregion
+export { HitTestReticleHandle as n, startHitTestReticle as r, HitTestReticleArgs as t };

package/dist/{image-capture-Cr_rljeV.d.ts → image-capture-BXmx1YvD.d.ts}

@@ -1,6 +1,6 @@
-import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-CBafnxhE.js";
-import { t as MotionFilterConfig } from "./capture-motion-gate-BmjiWUJv.js";
-import { a as QualityFilterConfig } from "./image-quality-BjBLoTec.js";
+import { i as MotionFilterConfig } from "./capture-motion-gate-C60Qrilh.js";
+import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-BprL3nKv.js";
+import { s as QualityFilterConfig } from "./image-quality-G7_qT4aj.js";
 
 //#region ../src/ar/image-capture.d.ts
 /**
@@ -51,7 +51,7 @@ declare const DEFAULT_CAPTURE_CONFIG: ImageCaptureConfig;
  * action by the RecorderApp's `handleImageCaptured`, which rebuilds the
  * payload field-by-field. A new field added here is therefore NOT persisted
  * until it is threaded through that handler — see
- * `2026-06-12-payload-rebuild-field-drop-audit.md` (F1/F2) and the forwarding
+ * `2026-06-12-1130-payload-rebuild-field-drop-audit.md` (F1/F2) and the forwarding
  * test in `main.occupancy-cubes-wiring.test.ts`.
  */
 interface CapturedImage {
@@ -83,7 +83,7 @@ interface CapturedImage {
  * A captured frame blob together with the pixel dimensions it was encoded at.
  * Returned by the optional `captureFrame` (blit) callback so the pose-invariant
  * image size can be persisted as first-class metadata (frame-tile aspect-ratio
- * fix, D1 of 2026-06-13-frame-tile-rendering-bugs-user-feedback.md). The
+ * fix, D1 of 2026-06-13-1311-frame-tile-rendering-bugs-user-feedback.md). The
  * dimensions are the blit render-target size — identical to the JPEG's own
  * width/height — so no decode is needed to learn the aspect ratio.
  */
@@ -148,7 +148,7 @@ interface ImageCaptureCallbacks {
    * callback MUST settle its promise; if it rejects, or does not settle within
    * `captureTimeoutMs`, the manager fails open (saves the frame) so a hung
    * analyzer cannot deadlock the pipeline. See `image-quality.ts` and
-   * `GpsPlusSlamJs_Docs/docs/2026-06-24-image-quality-gate-plan.md`.
+   * `GpsPlusSlamJs_Docs/docs/2026-06-24-1057-image-quality-gate-plan.md`.
    */
   analyzeFrame?: (frame: CapturedFrame) => Promise<FrameQualityVerdict>;
 }

package/dist/{image-capture-BUqqsOi3.js → image-capture-Dn8uLIP2.js}

@@ -1,6 +1,6 @@
 import { createLogger } from "./utils/logger.js";
-import { t as geodesicAngleRad } from "./geodesic-angle-HXBWiXiI.js";
-import { n as MotionWindow, r as decideCapture, t as DEFAULT_MOTION_FILTER } from "./capture-motion-gate-D1eyGC_o.js";
+import { t as geodesicAngleRad } from "./geodesic-angle-CZ_Ow90I.js";
+import { DEFAULT_MOTION_FILTER, MotionWindow, decideCapture } from "./ar/capture-motion-gate.js";
 import { DEFAULT_QUALITY_FILTER } from "./ar/image-quality.js";
 import { quat } from "gl-matrix";
 //#region ../src/ar/pose-motion.ts
@@ -8,7 +8,7 @@ import { quat } from "gl-matrix";
 * Pose-motion helpers — stateless angular/linear velocity from two AR poses.
 *
 * The capture motion gate (blurry-frame skipping, see
-* `GpsPlusSlamJs_Docs/docs/2026-06-23-blurry-frame-motion-gating-plan.md` §4.1)
+* `GpsPlusSlamJs_Docs/docs/2026-06-23-2105-blurry-frame-motion-gating-plan.md` §4.1)
 * rejects frames whose device motion is too fast to yield a sharp image. Motion
 * is derived from consecutive WebXR poses — cheaper than any image-content
 * metric because it needs no GPU readback.

package/dist/{image-quality-BjBLoTec.d.ts → image-quality-G7_qT4aj.d.ts}

@@ -21,10 +21,23 @@
  *    black/empty frame; an absolute cutoff is safe because "black is black"
  *    regardless of scene texture (§5).
  *
- * @see GpsPlusSlamJs_Docs/docs/2026-06-24-image-quality-gate-plan.md
+ * @see GpsPlusSlamJs_Docs/docs/2026-06-24-1057-image-quality-gate-plan.md
  * @see ./capture-motion-gate.ts — the motion gate this builds on (same shape:
  *   a shared config type + a small stateful window + a pure decision).
  */
+/**
+ * Selectable sharpness metrics for the gate's blur check. Both are pure
+ * grayscale scorers with identical defensive contracts; the gate's RELATIVE
+ * rule (`score < k · median(recent)`) is metric-agnostic, so the same
+ * `blurRelativeThreshold` slider drives either. Benchmarked against the
+ * hand-labeled recording 2026-07-11 (variance-of-Laplacian best at "clearly
+ * blurry vs rest", the energy ratio best at "sharp vs degraded") — see
+ * GpsPlusSlamJs_Docs/docs/2026-07-12-0823-blur-metric-toggle-plan.md.
+ */
+type BlurMetricId = 'variance-of-laplacian' | 'high-frequency-energy-ratio';
+/** All valid {@link BlurMetricId} values, the default (VoL) first — for
+ *  consumer-side validation of persisted configs. */
+declare const BLUR_METRIC_IDS: readonly BlurMetricId[];
 /**
  * User-/consumer-facing configuration for the image-quality gate. Shared by both
  * config shapes that carry it — `ImageCaptureConfig` (what `ImageCaptureManager`
@@ -57,6 +70,14 @@ interface QualityFilterConfig {
    * motion gate's `maxWaitMs`). A sensible value is ~2× the capture interval.
    */
   maxWaitMs: number;
+  /**
+   * Which sharpness metric the blur check scores frames with. **Optional**
+   * for backward compatibility with configs persisted before the toggle
+   * existed: `undefined` means `'variance-of-laplacian'` (the original
+   * behavior) — resolve via {@link blurMetricScorer}, never by reading this
+   * field directly.
+   */
+  blurMetric?: BlurMetricId;
 }
 /**
  * Default image-quality configuration. **Disabled by default** (plan §10): the
@@ -108,6 +129,27 @@ declare function rgbaToGrayscale(rgba: Uint8Array | Uint8ClampedArray): Uint8Cla
  * an empty buffer.
  */
 declare function meanLuminance(rgba: Uint8Array | Uint8ClampedArray): number;
+/**
+ * Frequency-domain focus measure: the fraction of non-DC spectral energy at
+ * normalized radial frequency ≥ `cutoff` (default 0.3), computed by FFT over
+ * the centered largest power-of-two crop (needs ≥ 8×8, else returns 0).
+ * In [0, 1]; higher ⇒ sharper. Unlike {@link sharpnessScore} it is invariant
+ * to brightness shift AND contrast scale (it is a ratio). Ported from the
+ * investigation benchmark (2026-07-12 toggle plan) where it won the
+ * "sharp vs degraded" boundary (AUC 0.838 vs 0.750).
+ *
+ * Defensive contract identical to {@link sharpnessScore}: non-integer or
+ * < 3×3 dims, or a buffer shorter than `width·height`, return 0.
+ */
+declare function highFrequencyEnergyRatio(gray: Uint8Array | Uint8ClampedArray | readonly number[], width: number, height: number, cutoff?: number): number;
+/**
+ * Resolve a {@link BlurMetricId} to its scoring function. `undefined` or an
+ * unknown id (e.g. from a persisted config written by a newer/older app
+ * version) resolves to {@link sharpnessScore} — the pre-toggle behavior.
+ * The (untestable) recorder worker calls this so the mapping stays here,
+ * where tests can pin it.
+ */
+declare function blurMetricScorer(metric: BlurMetricId | undefined): (gray: Uint8Array | Uint8ClampedArray | readonly number[], width: number, height: number) => number;
 /** Reason a frame was rejected by the quality gate, or `null` when accepted. */
 type QualityRejectReason = 'black' | 'blurry';
 /** Outcome of evaluating one frame against the quality gate. */
@@ -155,4 +197,4 @@ declare class ImageQualityGate {
   reset(): void;
 }
 //#endregion
-export { QualityFilterConfig as a, meanLuminance as c, ImageQualityGate as i, rgbaToGrayscale as l, DEFAULT_SHARPNESS_HISTORY_SIZE as n, QualityRejectReason as o, DEFAULT_SHARPNESS_MIN_SAMPLES as r, QualityVerdict as s, DEFAULT_QUALITY_FILTER as t, sharpnessScore as u };
+export { DEFAULT_SHARPNESS_MIN_SAMPLES as a, QualityRejectReason as c, highFrequencyEnergyRatio as d, meanLuminance as f, DEFAULT_SHARPNESS_HISTORY_SIZE as i, QualityVerdict as l, sharpnessScore as m, BlurMetricId as n, ImageQualityGate as o, rgbaToGrayscale as p, DEFAULT_QUALITY_FILTER as r, QualityFilterConfig as s, BLUR_METRIC_IDS as t, blurMetricScorer as u };

package/dist/index-DVmgFIgm.d.ts

@@ -0,0 +1,64 @@
+import { o as RgbaImage } from "./qr-frontend-BnLlVjKu.js";
+//#region ../src/ar/camera-frame-source.d.ts
+/** Tuning for the camera frame source. */
+interface CameraFrameSourceConfig {
+  /**
+   * Minimum interval between captures in milliseconds. Default 125 ms (≈ 8 Hz),
+   * the plan §9 5–10 Hz detection target. The capture (and therefore the blit)
+   * fires at most once per `intervalMs`.
+   */
+  intervalMs: number;
+}
+/** Injected I/O for the camera frame source. */
+interface CameraFrameSourceCallbacks {
+  /**
+   * Capture the current XR frame as top-left-origin RGBA, or `null` when no
+   * frame is available (no camera texture yet, GL failure). This is the GPU
+   * blit + readback; the source only invokes it at the throttled cadence so
+   * the cost is bounded. A `null` return does NOT consume the interval slot —
+   * the next frame retries immediately (a missing texture is transient).
+   */
+  capture: () => RgbaImage | null;
+  /** Receive a throttled, successfully-captured frame. */
+  onCapture: (image: RgbaImage) => void;
+}
+/**
+ * Throttled RGBA capturer. Construct with the injected `capture`/`onCapture`
+ * pair, `start()`, then call `onFrame(timestamp)` once per XR frame.
+ */
+declare class CameraFrameSource {
+  private readonly callbacks;
+  private readonly config;
+  private running;
+  private captureCount;
+  private lastCaptureTime;
+  constructor(callbacks: CameraFrameSourceCallbacks, config?: Partial<CameraFrameSourceConfig>);
+  /** Begin throttling. Resets the cadence so the first tick captures. */
+  start(): void;
+  /** Stop capturing. `onFrame` becomes a no-op until `start()` is called again. */
+  stop(): void;
+  isRunning(): boolean;
+  /** Number of frames successfully captured + delivered since `start()`. */
+  getFrameCount(): number;
+  getConfig(): CameraFrameSourceConfig;
+  /**
+   * Apply partial config (e.g. the app's detection cadence). Invalid values
+   * are ignored defensively — `intervalMs` requires a finite positive number.
+   */
+  updateConfig(config: Partial<CameraFrameSourceConfig>): void;
+  /**
+   * Per-XR-frame tick. Captures + delivers a frame at most once per
+   * `intervalMs`; otherwise a cheap no-op so it is safe to call every frame.
+   *
+   * @param timestamp - monotonic frame time in ms (the XR `time` argument).
+   */
+  onFrame(timestamp: number): void;
+  /**
+   * Run the injected capture, guarded so a blit failure (e.g. GL context loss)
+   * can never throw out of the XR frame loop — it degrades to "no frame this
+   * tick", exactly like a missing texture.
+   */
+  private captureSafely;
+}
+//#endregion
+export { CameraFrameSourceCallbacks as n, CameraFrameSourceConfig as r, CameraFrameSource as t };