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

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

@@ -1,4 +1,4 @@
-import { t as GpsCoord } from "./geo-types-DqiBzPO9.js";
+import { t as GpsCoord } from "./geo-types-3Ip1NzVR.js";
 import { LatLong, Matrix4, Vector3, fusedGpsFromOdom } from "gps-plus-slam-js";
 
 //#region ../src/utils/fused-path.d.ts

package/dist/geo/h3-proximity.d.ts

@@ -1,2 +1,2 @@
-import { a as 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-C-j0pw1j.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-C-j0pw1j.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-BeFO2RYa.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-_Rhgoqkh.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-DHMZmYAc.d.ts}

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

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

package/dist/image-capture-B2-b6tKK.js

@@ -0,0 +1,374 @@
+import { createLogger } from "./utils/logger.js";
+import { t as geodesicAngleRad } from "./geodesic-angle-BTldfFgs.js";
+import { n as MotionWindow, r as decideCapture, t as DEFAULT_MOTION_FILTER } from "./capture-motion-gate-4EscNZCw.js";
+import { DEFAULT_QUALITY_FILTER } from "./ar/image-quality.js";
+import { quat } from "gl-matrix";
+//#region ../src/ar/pose-motion.ts
+/**
+* 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)
+* 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.
+*
+* This module holds ONLY the pure, stateless math (angle ÷ dt, distance ÷ dt).
+* The stateful policy (sliding window, glitch rejection, the capture decision)
+* lives in `ImageCaptureManager` and `capture-motion-gate.ts` — keeping the
+* reusable atom separate from the capture-specific policy (plan §4.1 "Scope").
+*
+* Angular velocity reuses the shared `geodesicAngleRad` kernel rather than a
+* fresh `acos` (CLAUDE.md: search first, prefer refactor over re-implementation).
+*/
+/**
+* Convert a WebXR object-form quaternion to a normalized gl-matrix quaternion.
+* Normalizing defends against slightly non-unit inputs (the gate must not throw
+* on imperfect tracking data).
+*/
+function toGlQuat(q) {
+	const g = quat.fromValues(q.x, q.y, q.z, q.w);
+	return quat.normalize(g, g);
+}
+/**
+* Angular velocity in radians/second between two orientations.
+*
+* @param qPrev - orientation at the previous frame.
+* @param qCur - orientation at the current frame.
+* @param dtSeconds - elapsed time in seconds (must be > 0).
+* @returns geodesic angle between the orientations divided by `dtSeconds`.
+*   Returns `0` when `dtSeconds <= 0` (degenerate/duplicate frame timestamp) so
+*   a bad delta can never produce `Infinity`/`NaN` and spuriously flip the
+*   motion gate. Double-cover safe (`q` ≡ `−q`) via the shared kernel.
+*/
+function angularVelocity(qPrev, qCur, dtSeconds) {
+	if (!(dtSeconds > 0)) return 0;
+	return geodesicAngleRad(toGlQuat(qPrev), toGlQuat(qCur)) / dtSeconds;
+}
+/**
+* Linear velocity in metres/second between two positions.
+*
+* @param pPrev - position at the previous frame.
+* @param pCur - position at the current frame.
+* @param dtSeconds - elapsed time in seconds (must be > 0).
+* @returns straight-line distance divided by `dtSeconds`. Returns `0` when
+*   `dtSeconds <= 0` (same guard rationale as {@link angularVelocity}).
+*/
+function linearVelocity(pPrev, pCur, dtSeconds) {
+	if (!(dtSeconds > 0)) return 0;
+	const dx = pCur.x - pPrev.x;
+	const dy = pCur.y - pPrev.y;
+	const dz = pCur.z - pPrev.z;
+	return Math.sqrt(dx * dx + dy * dy + dz * dz) / dtSeconds;
+}
+//#endregion
+//#region ../src/ar/image-capture.ts
+/**
+* Image Capture Module
+*
+* Captures periodic JPEG screenshots from the WebGL canvas during AR recording.
+* Uses async toBlob() for better performance (non-blocking).
+*
+* Includes validation to detect suspiciously small images (likely black/empty)
+* which can occur on mobile devices when the WebGL context hasn't composited yet.
+*/
+const log = createLogger("ImageCapture");
+/**
+* Minimum expected blob size in bytes for a valid JPEG image.
+* A black/empty 1920x1080 JPEG still compresses to ~2-3KB due to headers.
+* A real camera frame at 0.7 quality should be 50KB+.
+* We use a conservative threshold to catch obviously broken captures.
+*/
+const MIN_VALID_IMAGE_BYTES = 5e3;
+/**
+* Default capture configuration
+*/
+const DEFAULT_CAPTURE_CONFIG = {
+	intervalMs: 2e3,
+	quality: .7,
+	captureTimeoutMs: 5e3,
+	resolutionDivisor: 1,
+	motionFilter: DEFAULT_MOTION_FILTER,
+	qualityFilter: DEFAULT_QUALITY_FILTER
+};
+/**
+* Manages periodic image capture from a canvas.
+*
+* Usage:
+* 1. Create with canvas and callbacks
+* 2. Call start() when recording begins
+* 3. Call onFrame(time) each XR frame
+* 4. Call stop() when recording ends
+*/
+var ImageCaptureManager = class {
+	canvas;
+	callbacks;
+	config;
+	capturing = false;
+	lastCaptureTime = 0;
+	frameCount = 0;
+	captureInProgress = false;
+	captureTimeoutId = null;
+	/** 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). */
+	awaitingVerdict = false;
+	/** The current interval's capture was rejected by the quality gate; bypass the
+	*  interval guard so the next acceptable frame is grabbed immediately. */
+	retryPending = false;
+	/** 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. */
+	qualityDeadlineBase = null;
+	/** Safety timeout for a hung `analyzeFrame` (fail-open). */
+	verdictTimeoutId = null;
+	/** Sliding window of recent per-frame velocities for the motion gate. */
+	motionWindow = new MotionWindow();
+	/** Previous frame's pose, for the per-frame velocity delta. */
+	prevPose = null;
+	/** Previous frame's timestamp (ms), for the per-frame velocity delta. */
+	prevTime = 0;
+	/** Whether THIS frame's velocity sample was rejected as a tracking glitch. */
+	lastSampleWasGlitch = false;
+	/** When the current capture first became due (ms); null while not due. The
+	*  `maxWaitMs` fallback measures from here, not from `lastCaptureTime`. */
+	dueTime = null;
+	constructor(canvas, callbacks, config = DEFAULT_CAPTURE_CONFIG) {
+		this.canvas = canvas;
+		this.callbacks = callbacks;
+		this.config = config;
+	}
+	/**
+	* Start capturing images.
+	* Resets frame counter and last capture time.
+	*/
+	start() {
+		this.capturing = true;
+		this.lastCaptureTime = 0;
+		this.frameCount = 0;
+		this.motionWindow.reset();
+		this.prevPose = null;
+		this.prevTime = 0;
+		this.lastSampleWasGlitch = false;
+		this.dueTime = null;
+		this.clearVerdictTimeout();
+		this.awaitingVerdict = false;
+		this.retryPending = false;
+		this.qualityDeadlineBase = null;
+	}
+	/**
+	* Stop capturing images.
+	* Clears any pending safety timeout and resets in-flight capture state.
+	*/
+	stop() {
+		this.capturing = false;
+		this.clearCaptureTimeout();
+		this.captureInProgress = false;
+		this.clearVerdictTimeout();
+		this.awaitingVerdict = false;
+		this.retryPending = false;
+		this.qualityDeadlineBase = null;
+	}
+	/**
+	* Check if capture manager is active.
+	*/
+	isCapturing() {
+		return this.capturing;
+	}
+	/**
+	* Get the current frame count.
+	*/
+	getFrameCount() {
+		return this.frameCount;
+	}
+	/**
+	* Called each XR frame to check if a capture is needed.
+	*
+	* @param time - Frame timestamp in milliseconds (from requestAnimationFrame)
+	*/
+	onFrame(time) {
+		if (!this.capturing) return;
+		const pose = this.callbacks.getCurrentPose();
+		this.updateMotionWindow(time, pose);
+		if (this.captureInProgress || this.awaitingVerdict) return;
+		const elapsed = time - this.lastCaptureTime;
+		if (!this.retryPending && this.lastCaptureTime > 0 && elapsed < this.config.intervalMs) {
+			this.dueTime = null;
+			return;
+		}
+		if (!pose) return;
+		if (this.dueTime === null) this.dueTime = time;
+		if (!this.shouldCaptureNow(time)) return;
+		this.captureInProgress = true;
+		this.lastCaptureTime = time;
+		this.dueTime = null;
+		const timestamp = performance.timeOrigin + time;
+		const screenRotation = this.callbacks.getScreenRotation();
+		this.captureTimeoutId = setTimeout(() => {
+			if (this.captureInProgress) {
+				log.error(`Capture timeout after ${this.config.captureTimeoutMs}ms — force-resetting captureInProgress`);
+				this.captureInProgress = false;
+				this.captureTimeoutId = null;
+			}
+		}, this.config.captureTimeoutMs);
+		if (this.callbacks.captureFrame) this.callbacks.captureFrame(this.config.quality).then((frame) => {
+			this.handleCapturedBlob(frame?.blob ?? null, frame?.width, frame?.height, timestamp, time, pose, screenRotation);
+		}).catch(() => {
+			this.clearCaptureTimeout();
+			this.captureInProgress = false;
+			this.callbacks.onCaptureFailed?.();
+		});
+		else this.canvas.toBlob((blob) => {
+			this.handleCapturedBlob(blob, this.canvas.width, this.canvas.height, timestamp, time, pose, screenRotation);
+		}, "image/jpeg", this.config.quality);
+	}
+	/**
+	* 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".
+	*/
+	updateMotionWindow(time, pose) {
+		if (!pose) {
+			this.lastSampleWasGlitch = false;
+			this.motionWindow.reset();
+			this.prevPose = null;
+			this.prevTime = 0;
+			this.retryPending = false;
+			this.qualityDeadlineBase = null;
+			return;
+		}
+		if (this.prevPose && this.prevTime > 0) {
+			const dt = (time - this.prevTime) / 1e3;
+			if (dt > 0) {
+				const angVel = angularVelocity(this.prevPose.orientation, pose.orientation, dt);
+				const linVel = linearVelocity(this.prevPose.position, pose.position, dt);
+				this.lastSampleWasGlitch = !this.motionWindow.push(angVel, linVel);
+			} else this.lastSampleWasGlitch = false;
+		} else this.lastSampleWasGlitch = false;
+		this.prevPose = pose;
+		this.prevTime = time;
+	}
+	/**
+	* 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.
+	*/
+	shouldCaptureNow(time) {
+		const mf = this.config.motionFilter;
+		if (!mf || !mf.enabled) return true;
+		const msSinceDue = this.dueTime === null ? 0 : time - this.dueTime;
+		if (msSinceDue >= mf.maxWaitMs) return true;
+		if (this.lastSampleWasGlitch) return false;
+		if (!this.motionWindow.hasSamples()) return true;
+		return decideCapture({
+			windowMaxAngular: this.motionWindow.maxAngular(),
+			windowMaxLinear: this.motionWindow.maxLinear(),
+			maxAngularVelocity: mf.maxAngularVelocity,
+			maxLinearVelocity: mf.maxLinearVelocity,
+			msSinceDue,
+			maxWaitMs: mf.maxWaitMs
+		}) === "capture";
+	}
+	/**
+	* Clear the safety timeout for captureInProgress.
+	* Called when capture completes (success or failure) before the timeout fires.
+	*/
+	clearCaptureTimeout() {
+		if (this.captureTimeoutId !== null) {
+			clearTimeout(this.captureTimeoutId);
+			this.captureTimeoutId = null;
+		}
+	}
+	/** Clear the safety timeout for a hung `analyzeFrame` verdict. */
+	clearVerdictTimeout() {
+		if (this.verdictTimeoutId !== null) {
+			clearTimeout(this.verdictTimeoutId);
+			this.verdictTimeoutId = null;
+		}
+	}
+	/**
+	* Common handler for captured blobs (from either canvas.toBlob or captureFrame).
+	* 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.
+	*/
+	handleCapturedBlob(blob, width, height, timestamp, time, pose, screenRotation) {
+		this.clearCaptureTimeout();
+		this.captureInProgress = false;
+		if (!blob) {
+			this.callbacks.onCaptureFailed?.();
+			return;
+		}
+		const qf = this.config.qualityFilter;
+		const analyze = this.callbacks.analyzeFrame;
+		if (!analyze || !qf || !qf.enabled) {
+			this.saveCapture(blob, width, height, timestamp, pose, screenRotation);
+			return;
+		}
+		if (this.qualityDeadlineBase === null) this.qualityDeadlineBase = time;
+		if (time - this.qualityDeadlineBase >= qf.maxWaitMs) {
+			this.saveCapture(blob, width, height, timestamp, pose, screenRotation);
+			return;
+		}
+		this.awaitingVerdict = true;
+		let settled = false;
+		const finish = (accept, viaTimeout) => {
+			if (settled || !this.capturing) return;
+			settled = true;
+			this.clearVerdictTimeout();
+			this.awaitingVerdict = false;
+			if (viaTimeout) log.error("analyzeFrame verdict timed out — saving frame fail-open to keep the pipeline live");
+			if (accept) this.saveCapture(blob, width, height, timestamp, pose, screenRotation);
+			else this.retryPending = true;
+		};
+		this.verdictTimeoutId = setTimeout(() => finish(true, true), this.config.captureTimeoutMs);
+		analyze({
+			blob,
+			width: width ?? 0,
+			height: height ?? 0
+		}).then((verdict) => finish(verdict.accept, false)).catch((err) => {
+			log.error("analyzeFrame failed — saving frame without quality gate", err);
+			finish(true, false);
+		});
+	}
+	/**
+	* 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.
+	*/
+	saveCapture(blob, width, height, timestamp, pose, screenRotation) {
+		if (!this.capturing) return;
+		this.retryPending = false;
+		this.qualityDeadlineBase = null;
+		const frameIndex = ++this.frameCount;
+		if (blob.size < 5e3) {
+			log.error(`Suspicious image at frame ${frameIndex}: blob size ${blob.size} bytes is below minimum ${MIN_VALID_IMAGE_BYTES} bytes. Image may be black/empty.`);
+			this.callbacks.onSuspiciousImage?.(blob.size, frameIndex);
+		}
+		this.callbacks.onCaptured({
+			blob,
+			timestamp,
+			frameIndex,
+			position: pose.position,
+			rotation: pose.orientation,
+			screenRotation,
+			...width && width > 0 ? { width } : {},
+			...height && height > 0 ? { height } : {}
+		});
+	}
+};
+//#endregion
+export { ImageCaptureManager as n, MIN_VALID_IMAGE_BYTES as r, DEFAULT_CAPTURE_CONFIG as t };

package/dist/{image-capture-C2Feywet.d.ts → image-capture-CNZDrQXG.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-BFX2r1wk.js";
+import { t as MotionFilterConfig } from "./capture-motion-gate-0Yl2NpQG.js";
+import { a as QualityFilterConfig } from "./image-quality-smCBoFj1.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 };