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

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

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

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

@@ -129,16 +129,17 @@ function createSlamAppStore(options) {
 	});
 	const prependedListeners = [trackingQualityMiddleware];
 	if (compassOptIns.length > 0) prependedListeners.push(createSlamAppStoreListenerMiddleware(compassOptIns));
+	const persistenceMiddleware = createPersistenceMiddleware({
+		storageBackend,
+		onWriteFailure,
+		persistedPrefixes: [...BUILTIN_PERSISTED_PREFIXES, ...persistedExtraPrefixes ?? []]
+	});
 	const store = configureStore({
 		reducer,
 		middleware: (getDefaultMiddleware) => getDefaultMiddleware({
 			serializableCheck: enableDevChecks ? { 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 +150,8 @@ function createSlamAppStore(options) {
 		dispatch: store.dispatch,
 		subscribe: (listener) => store.subscribe(listener),
 		writeFrame: (blob, index) => storageBackend.writeFrame(blob, index),
-		writeSessionMetadata: (metadata) => storageBackend.writeSessionMetadata(metadata)
+		writeSessionMetadata: (metadata) => storageBackend.writeSessionMetadata(metadata),
+		flushPendingActionWrites: () => persistenceMiddleware.flushPendingWrites()
 	};
 }
 //#endregion

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

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

package/dist/{depth-sampler-txG8evgQ.d.ts → depth-sampler-CS2jAFw4.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-D6PYS4bc.js";
 import { Matrix4 } from "gps-plus-slam-js";
 
 //#region ../src/ar/depth-rgb-lookup.d.ts
@@ -72,7 +72,7 @@ interface DepthInfo {
    * the matrices: the per-frame buffer is too large to clone and the live
    * depth occluder uploads it synchronously). Absent when the source carries
    * no `data` (e.g. the sparse-only path). Plumbed for the live depth occluder
-   * (2026-06-14-webxr-depth-occlusion-plan.md §2); the sparse sampler ignores it.
+   * (2026-06-14-0009-webxr-depth-occlusion-plan.md §2); the sparse sampler ignores it.
    */
   data?: ArrayBuffer;
   /**

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

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

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

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

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

package/dist/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-BaAulrnM.js";
 export { H3_RESOLUTION, KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/h3-proximity.js

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

package/dist/geo/index.d.ts

@@ -1,2 +1,2 @@
-import { a as findNearbyGeoAnchor, c as h3CellsMatch, i as clusterCellsByZoom, l as isH3Index, n as KnownGeoAnchor, o as gpsPathToCoverageCells, r as approxDistanceMetres, s as gpsToH3, t as H3_RESOLUTION } from "../h3-proximity-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-BaAulrnM.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-ar-pose-sampler-BOOV0jJk.d.ts → gps-ar-pose-sampler-BuuUuK-D.d.ts}

@@ -1,4 +1,4 @@
-import { t as ARPose } from "./ar-types-CBafnxhE.js";
+import { t as ARPose } from "./ar-types-D6PYS4bc.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-Cruoe5I-.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-D6PYS4bc.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CnhYrJCa.js";
+import { t as AbsoluteOrientationReading } from "./absolute-orientation-Dj1One3y.js";
+import { i as SlamAppStore } from "./create-slam-app-store-DFm5K9Ob.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-y2b2aVl6.d.ts}

@@ -1,6 +1,26 @@
+import * as THREE from "three";
 import { LatLong, Vector3 } 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.
@@ -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-BaAulrnM.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/{image-capture-Cr_rljeV.d.ts → image-capture-BevgKpoO.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-CPwLekNf.js";
+import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-D6PYS4bc.js";
+import { s as QualityFilterConfig } from "./image-quality--HLuyJ2r.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-C4DwxC10.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--HLuyJ2r.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-C2Bo0buN.d.ts → index-BWVwd9Zw.d.ts}

@@ -1,9 +1,9 @@
 import { t as GridCell } from "./bresenham3d-D-t9i_b5.js";
-import { a as QrPoseSolution, i as Pose, r as Point2, t as CameraIntrinsics } from "./qr-pose-CCTF1PP0.js";
-import { a as QrFrontEnd, o as RgbaImage } from "./qr-frontend-61SKPSyU.js";
+import { a as QrPoseSolution, i as Pose, r as Point2, t as CameraIntrinsics } from "./qr-pose-21fRDcFO.js";
+import { a as QrFrontEnd, o as RgbaImage } from "./qr-frontend-QzKZSqB-.js";
 import { Quaternion, RecordGpsEventPayload, Vector3 } from "gps-plus-slam-js";
 
-//#region ../src/ar/qr-gps-vote.d.ts
+//#region ../src/ar/qr/qr-gps-vote.d.ts
 /** Absolute geo pose of the printed QR, from the level file. */
 interface QrGeoPose {
   lat: number;
@@ -97,7 +97,7 @@ declare function offsetGeo(center: QrGeoPose, enu: Enu): {
  */
 declare function buildQrGpsVotes(input: QrGpsVoteInput): RecordGpsEventPayload[];
 //#endregion
-//#region ../src/ar/qr-level.d.ts
+//#region ../src/ar/qr/qr-level.d.ts
 /**
  * A validated QR level file.
  *
@@ -150,7 +150,7 @@ interface FetchQrLevelOptions {
  */
 declare function fetchQrLevel(url: string, options?: FetchQrLevelOptions): Promise<QrLevel>;
 //#endregion
-//#region ../src/ar/qr-tracking-controller.d.ts
+//#region ../src/ar/qr/qr-tracking-controller.d.ts
 type QrTrackingStatus = 'idle' | 'scanning' | 'loading-level' | 'tracking' | 'error';
 /** Inputs to the injected pose solve (so the controller doesn't import OpenCV). */
 interface QrSolvePoseInput {
@@ -163,7 +163,7 @@ interface QrSolvePoseInput {
  * Emitted on every lock, INDEPENDENTLY of the GPS vote (Note 3). The app maps
  * this onto `recordQrDetection` of the `qrDetected` slice. Kept structural (no
  * import of the state slice) so the `ar` layer never depends on `state` — that
- * would close a cycle (`state/qr-detected-slice` already imports `ar/qr-pose`).
+ * would close a cycle (`state/qr-detected-slice` already imports `ar/qr/qr-pose`).
  */
 interface QrDetectionEvent {
   /** Decoded payload (text/URL) — the marker key. */
@@ -247,69 +247,7 @@ interface QrTrackingController {
 }
 declare function createQrTrackingController(config: QrTrackingControllerConfig): QrTrackingController;
 //#endregion
-//#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
-//#region ../src/ar/detection-scheduler.d.ts
+//#region ../src/ar/qr/detection-scheduler.d.ts
 interface DetectionSchedulerConfig<TResult, TImage = RgbaImage> {
   /** The full detect→solve step; resolves to a result or `null` (no hit / rejected). */
   detect: (image: TImage) => Promise<TResult | null>;
@@ -344,7 +282,7 @@ type QrDetectionScheduler = DetectionScheduler<RgbaImage>;
 /** The QR path: a detection scheduler whose result is a {@link QrPoseSolution}. */
 declare function createQrDetectionScheduler(config: QrDetectionSchedulerConfig): QrDetectionScheduler;
 //#endregion
-//#region ../src/ar/qr-occupancy-check.d.ts
+//#region ../src/ar/qr/qr-occupancy-check.d.ts
 /**
  * The slice of `OccupancyGrid` this check needs. Declared structurally so the
  * real grid satisfies it and tests can pass a tiny synthetic stand-in.
@@ -394,4 +332,4 @@ interface QrPlausibilityOptions {
  */
 declare function checkQrPlausibility(qrCenterWorld: Vector3, cameraPosWorld: Vector3, grid: OccupancySurface, options?: QrPlausibilityOptions): QrPlausibility;
 //#endregion
-export { buildQrGpsVotes as A, QrLevel as C, Enu as D, parseQrLevel as E, offsetGeo as M, QrGeoPose as O, FetchQrLevelOptions as S, fetchQrLevel as T, QrTrackingController as _, checkQrPlausibility as a, createQrTrackingController as b, QrDetectionScheduler as c, createQrDetectionScheduler as d, CameraFrameSource as f, QrSolvePoseInput as g, QrDetectionEvent as h, QrPlausibilityVerdict as i, localPlaneToEnu as j, QrGpsVoteInput as k, QrDetectionSchedulerConfig as l, CameraFrameSourceConfig as m, QrPlausibility as n, DetectionScheduler as o, CameraFrameSourceCallbacks as p, QrPlausibilityOptions as r, DetectionSchedulerConfig as s, OccupancySurface as t, createDetectionScheduler as u, QrTrackingControllerConfig as v, QrLevelValidationError as w, FetchLike as x, QrTrackingStatus as y };
+export { parseQrLevel as C, buildQrGpsVotes as D, QrGpsVoteInput as E, localPlaneToEnu as O, fetchQrLevel as S, QrGeoPose as T, createQrTrackingController as _, checkQrPlausibility as a, QrLevel as b, QrDetectionScheduler as c, createQrDetectionScheduler as d, QrDetectionEvent as f, QrTrackingStatus as g, QrTrackingControllerConfig as h, QrPlausibilityVerdict as i, offsetGeo as k, QrDetectionSchedulerConfig as l, QrTrackingController as m, QrPlausibility as n, DetectionScheduler as o, QrSolvePoseInput as p, QrPlausibilityOptions as r, DetectionSchedulerConfig as s, OccupancySurface as t, createDetectionScheduler as u, FetchLike as v, Enu as w, QrLevelValidationError as x, FetchQrLevelOptions as y };

package/dist/{index-CuHaGY0F.d.ts → index-ClmnNJ6-.d.ts}

@@ -1,4 +1,4 @@
-import { N as CombinedRootState, m as TrackingQualityReport } from "./create-slam-app-store-CH31erpP.js";
+import { N as CombinedRootState, m as TrackingQualityReport } from "./create-slam-app-store-DFm5K9Ob.js";
 import { Add2dImagePayload, GpsPoint as GpsPoint$1, LatLong as LatLong$1, RawDeviceOrientation, RawGpsPoint as RawGpsPoint$1, RecordGpsEventPayload as RecordGpsEventPayload$1, add2dImage, calcRelativeCoordsInMeters, recordGpsEvent as recordGpsEvent$1, setZeroPos as setZeroPos$1 } from "gps-plus-slam-js";
 
 //#region ../src/state/onboarding-guidance.d.ts

package/dist/index-Dxb6ATNK.d.ts

@@ -0,0 +1,64 @@
+import { o as RgbaImage } from "./qr-frontend-QzKZSqB-.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 };