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

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

@@ -0,0 +1,156 @@
+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 builtins = {
+		gpsData: gpsDataReducer,
+		gpsElements: gpsElementsReducer,
+		arElements: arElementsReducer,
+		recording: recordingReducer,
+		tracking: trackingReducer,
+		trackingQuality: trackingQualityReducer
+	};
+	if (extraReducers) {
+		const collisions = Object.keys(extraReducers).filter((key) => Object.prototype.hasOwnProperty.call(builtins, key));
+		if (collisions.length > 0) throw new Error(`extraReducers must not overwrite framework-reserved slice(s): ${collisions.join(", ")}. Reserved keys: ${Object.keys(builtins).join(", ")}.`);
+	}
+	const reducer = {
+		...builtins,
+		...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/{depth-grid-lookup-vMDrGTk_.d.ts → depth-grid-lookup-D5atpNZ3.d.ts}

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

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

@@ -1,4 +1,4 @@
-import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-BckI1E-O.js";
+import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-Cc5yvBwn.js";
 import { Matrix4 } from "gps-plus-slam-js";
 
 //#region ../src/ar/depth-rgb-lookup.d.ts
@@ -66,6 +66,27 @@ interface DepthInfo {
   getDepthInMeters: (x: number, y: number) => number;
   /** Column-major projection matrix of the capturing XRView, if known. */
   projectionMatrix?: Matrix4;
+  /**
+   * Raw depth buffer (`XRCPUDepthInformation.data`) — a **live reference**
+   * valid only within the originating XR frame callback (NOT copied, unlike
+   * 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.
+   */
+  data?: ArrayBuffer;
+  /**
+   * `XRCPUDepthInformation.rawValueToMeters` — multiply a raw depth sample by
+   * this to get metres. Preserved only when a finite number. Occluder-only.
+   */
+  rawValueToMeters?: number;
+  /**
+   * The `.matrix` (column-major 16-tuple) of
+   * `XRDepthInformation.normDepthBufferFromNormView` — the screen-UV → depth-UV
+   * transform the occluder shader needs. Copied + validated like
+   * `projectionMatrix` (the UA may reuse the backing array). Occluder-only.
+   */
+  normDepthBufferFromNormView?: Matrix4;
 }
 /**
  * Wrap a raw browser XRDepthInformation object into a {@link DepthInfo}.
@@ -76,11 +97,22 @@ interface DepthInfo {
  *   the UA may reuse across frames) is defensively validated and copied into
  *   a plain serializable 16-tuple; invalid input (wrong length, non-finite
  *   entries) yields a DepthInfo without a matrix rather than an error.
+ * - The live-occluder metadata (`data`, `rawValueToMeters`,
+ *   `normDepthBufferFromNormView`) is preserved when present and valid: `data`
+ *   by live reference (no clone — see {@link DepthInfo.data}), the scale only
+ *   when finite, and the UV transform's `.matrix` copied like
+ *   `projectionMatrix`. The sparse grid sampler ignores all three; a source
+ *   lacking them (e.g. the existing test doubles) wraps exactly as before.
  */
 declare function wrapXRDepthInfo(raw: {
   width: number;
   height: number;
   getDepthInMeters: (x: number, y: number) => number;
+  data?: ArrayBuffer;
+  rawValueToMeters?: number;
+  normDepthBufferFromNormView?: {
+    matrix?: ArrayLike<number>;
+  } | null;
 }, projectionMatrix: ArrayLike<number> | undefined): DepthInfo;
 /**
  * Samples sparse depth points from WebXR depth sensing.

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

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

package/dist/{enable-gps-ar-CjZ1nEdu.d.ts → enable-gps-ar-DvGzBOrp.d.ts}

@@ -1,7 +1,7 @@
-import { t as ArCrashIsolationOptions } from "./recording-options-D93kksJU.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-C5inWeNV.js";
-import { n as PermissionStatus } from "./permission-checker-CtPtPQRq.js";
-import { r as SessionFeatureOptions } from "./webxr-session-COsOjJwn.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-vASCFzc5.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CDKDQokE.js";
+import { n as PermissionStatus } from "./permission-checker-B-VtjnBA.js";
+import { s as SessionFeatureOptions } from "./webxr-session-cRG2SYAQ.js";
 
 //#region ../src/ar/enable-gps-ar.d.ts
 /**

package/dist/{frame-conversions-D_Af8Dt3.d.ts → frame-conversions-C4bnNOEY.d.ts}

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

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

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

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-B57C6rYL.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-D0GTHQmr.js";
 export { H3_RESOLUTION, type KnownGeoAnchor, 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-C6I9NDHA.d.ts → gps-anchor-BjECcYnD.d.ts}

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

package/dist/{gps-ar-pose-sampler-DaHg2aPZ.d.ts → gps-ar-pose-sampler-DEGNk2CI.d.ts}

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

package/dist/{gps-event-coordinator-C7hwHyLA.d.ts → gps-event-coordinator-CHtIkhb7.d.ts}

@@ -1,7 +1,8 @@
-import { t as ARPose } from "./ar-types-BckI1E-O.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-C5inWeNV.js";
-import { i as SlamAppStore } from "./create-slam-app-store-Ce2FMKCp.js";
-import { Quaternion, RawGpsPoint, RecordGpsEventPayload, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
+import { t as ARPose } from "./ar-types-Cc5yvBwn.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-CDKDQokE.js";
+import { t as AbsoluteOrientationReading } from "./absolute-orientation-BAxc15J6.js";
+import { i as SlamAppStore } from "./create-slam-app-store-D3nzh9Wb.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/{image-capture-C2Feywet.d.ts → image-capture-Bp6Pd4Md.d.ts}

@@ -1,4 +1,6 @@
-import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-BckI1E-O.js";
+import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-Cc5yvBwn.js";
+import { t as MotionFilterConfig } from "./capture-motion-gate-BGoAMkmf.js";
+import { a as QualityFilterConfig } from "./image-quality-BMx2ko9-.js";
 
 //#region ../src/ar/image-capture.d.ts
 /**
@@ -26,6 +28,17 @@ interface ImageCaptureConfig {
    *  into this config so the whole user options section can flow through the
    *  capture seam as one object (see the field-drop audit, F3). */
   resolutionDivisor: number;
+  /** Motion gate: skip motion-blurred frames by deferring a due capture until
+   *  device motion settles (or `maxWaitMs` elapses). Mirrored in the persisted
+   *  `ImageCaptureOptions.motionFilter` and flowed through the same capture
+   *  seam as `resolutionDivisor`. See `capture-motion-gate.ts`. */
+  motionFilter: MotionFilterConfig;
+  /** Image-quality gate: drop a blurry/black frame (judged off-thread by the
+   *  injected `analyzeFrame` callback) and retry the next acceptable frame,
+   *  bounded by `maxWaitMs`. The increment ON TOP of the motion gate — only ever
+   *  runs on frames that already passed motion gating. Mirrored in the persisted
+   *  `ImageCaptureOptions.qualityFilter`. See `image-quality.ts`. */
+  qualityFilter: QualityFilterConfig;
 }
 /**
  * Default capture configuration
@@ -79,6 +92,18 @@ interface CapturedFrame {
   readonly width: number;
   readonly height: number;
 }
+/**
+ * Verdict returned by the injected off-thread {@link ImageCaptureCallbacks.analyzeFrame}
+ * analyzer. The manager only needs `accept`; `reason` is carried for logging/
+ * tuning. Structurally compatible with `image-quality.ts`'s `QualityVerdict`, so
+ * the recorder worker can return that type directly.
+ */
+interface FrameQualityVerdict {
+  /** `true` to save the frame, `false` to drop it and retry. */
+  readonly accept: boolean;
+  /** Optional debug reason (e.g. `'black'` | `'blurry'`); for logging only. */
+  readonly reason?: string | null;
+}
 /**
  * Callbacks for image capture integration
  */
@@ -110,6 +135,22 @@ interface ImageCaptureCallbacks {
    * @see docs/2026-02-06-bug-camera-frames-black.md
    */
   captureFrame?: (quality: number) => Promise<CapturedFrame | null>;
+  /**
+   * Optional off-thread image-quality analyzer (blur/blackness gate). When
+   * provided AND `config.qualityFilter.enabled`, a freshly-encoded blob is NOT
+   * saved immediately: it is handed to this async callback (a Web Worker
+   * round-trip in the recorder) and saved only if the verdict accepts. A reject
+   * drops the blob and re-arms capture so the next acceptable (motion-calm)
+   * frame fills the slot, bounded by `qualityFilter.maxWaitMs` (after which the
+   * next frame is saved regardless, so an interval is never silently lost).
+   *
+   * The manager itself NEVER touches pixels — the off-main-thread guarantee. The
+   * 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`.
+   */
+  analyzeFrame?: (frame: CapturedFrame) => Promise<FrameQualityVerdict>;
 }
 /**
  * Manages periodic image capture from a canvas.
@@ -129,6 +170,30 @@ declare class ImageCaptureManager {
   private frameCount;
   private captureInProgress;
   private captureTimeoutId;
+  /** True while an `analyzeFrame` verdict is in flight; blocks a second capture
+   *  for the same interval without throttling normal cadence (captureInProgress
+   *  is released after encode, NOT held across the round-trip). */
+  private awaitingVerdict;
+  /** The current interval's capture was rejected by the quality gate; bypass the
+   *  interval guard so the next acceptable frame is grabbed immediately. */
+  private retryPending;
+  /** Frame time (ms) of the FIRST quality attempt for the current interval; the
+   *  quality `maxWaitMs` fallback measures from here, independent of the motion
+   *  gate's own due clock. `null` between intervals. */
+  private qualityDeadlineBase;
+  /** Safety timeout for a hung `analyzeFrame` (fail-open). */
+  private verdictTimeoutId;
+  /** Sliding window of recent per-frame velocities for the motion gate. */
+  private readonly motionWindow;
+  /** Previous frame's pose, for the per-frame velocity delta. */
+  private prevPose;
+  /** Previous frame's timestamp (ms), for the per-frame velocity delta. */
+  private prevTime;
+  /** Whether THIS frame's velocity sample was rejected as a tracking glitch. */
+  private lastSampleWasGlitch;
+  /** When the current capture first became due (ms); null while not due. The
+   *  `maxWaitMs` fallback measures from here, not from `lastCaptureTime`. */
+  private dueTime;
   constructor(canvas: HTMLCanvasElement, callbacks: ImageCaptureCallbacks, config?: ImageCaptureConfig);
   /**
    * Start capturing images.
@@ -154,16 +219,51 @@ declare class ImageCaptureManager {
    * @param time - Frame timestamp in milliseconds (from requestAnimationFrame)
    */
   onFrame(time: number): void;
+  /**
+   * Sample per-frame device motion into the sliding window. Called every frame
+   * (even during an in-flight capture or before the interval elapses) so the
+   * window reflects truly instantaneous motion the moment a capture becomes
+   * due. A frame with no pose, or a non-positive dt (duplicate timestamp),
+   * records no sample and is treated as "not a glitch".
+   */
+  private updateMotionWindow;
+  /**
+   * Apply the motion gate to a due capture. Returns `true` to capture now,
+   * `false` to defer to a later frame.
+   *
+   * - Filter disabled → always `true` (legacy behavior).
+   * - `maxWaitMs` elapsed → always `true` (never-calm safety fallback; an
+   *   interval is never silently lost).
+   * - Current frame's sample was a tracking glitch → `false` (don't grab a
+   *   relocalization-teleport frame; the fallback still guarantees progress).
+   * - No measurable motion yet (first capture / all-glitch) → `true` (the very
+   *   first capture is never blocked; only measurable motion defers).
+   * - Otherwise → defer to {@link decideCapture} over the windowed maxima.
+   */
+  private shouldCaptureNow;
   /**
    * Clear the safety timeout for captureInProgress.
    * Called when capture completes (success or failure) before the timeout fires.
    */
   private clearCaptureTimeout;
+  /** Clear the safety timeout for a hung `analyzeFrame` verdict. */
+  private clearVerdictTimeout;
   /**
    * Common handler for captured blobs (from either canvas.toBlob or captureFrame).
-   * Handles null blobs, suspicious image detection, and dispatching onCaptured.
+   * Releases `captureInProgress` after the synchronous encode, then either saves
+   * immediately (legacy / gate-off) or runs the off-thread image-quality gate.
+   *
+   * @param time - the XR frame time the capture was dispatched at; the quality
+   *   retry-deadline clock and `lastCaptureTime` are measured from it.
    */
   private handleCapturedBlob;
+  /**
+   * Persist an accepted frame: allocate its 1-based index, run the suspicious-
+   * size belt-and-suspenders check, reset the per-interval gate clocks, and fire
+   * `onCaptured`. Called from the legacy path, the quality fallbacks, and an
+   * accepting verdict — the single place a frame becomes durable.
+   */
+  private saveCapture;
 }
 //#endregion
-export { ImageCaptureConfig as a, ImageCaptureCallbacks as i, CapturedImage as n, ImageCaptureManager as o, DEFAULT_CAPTURE_CONFIG as r, MIN_VALID_IMAGE_BYTES as s, CapturedFrame as t };
+export { ImageCaptureCallbacks as a, MIN_VALID_IMAGE_BYTES as c, FrameQualityVerdict as i, CapturedImage as n, ImageCaptureConfig as o, DEFAULT_CAPTURE_CONFIG as r, ImageCaptureManager as s, CapturedFrame as t };