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

package/dist/{h3-proximity-I1msGPgE.d.ts → h3-proximity-C-j0pw1j.d.ts}

@@ -29,6 +29,44 @@ interface KnownGeoAnchor {
  * Compute the H3 resolution-11 index for a GPS position.
  */
 declare function gpsToH3(lat: number, lng: number): string;
+/** Minimal GPS coordinate shape (Leaflet convention: `lng`, not `lon`). */
+interface LatLngLike {
+  readonly lat: number;
+  readonly lng: number;
+}
+/**
+ * Reduce a recorded GPS path to the deduplicated set of res-11 H3 cells it
+ * crossed — the per-tour "coverage index" stored in `SessionMetadata.h3Cells`.
+ *
+ * Cells are returned in first-seen (chronological) order and deduplicated, so a
+ * tour that dwells in one ~25 m cell contributes a single cell. This keeps the
+ * stored index small (see the metadata-size risk in the map-browser feedback
+ * doc, §7). Non-finite coordinates are skipped defensively — bad sensor data
+ * must not poison the index or throw inside `latLngToCell`.
+ */
+declare function gpsPathToCoverageCells(path: readonly LatLngLike[]): string[];
+/**
+ * Coarsen res-11 coverage cells to a target resolution for map zoom-clustering.
+ *
+ * Uses h3-js `cellToParent` — the ONLY correct way to coarsen an H3 cell. NEVER
+ * truncate the hex-string id: resolution is encoded in the high bits with
+ * trailing `f` padding, so slicing yields INVALID cells, not parents (verified;
+ * see the D1 gotcha in
+ * docs/2026-06-14-map-centric-recording-browser-and-h3-index-user-feedback.md).
+ *
+ * `targetRes` is clamped to `[0, H3_RESOLUTION]` because `cellToParent` throws
+ * when asked for a FINER resolution than the cell, and res 11 is the finest
+ * data stored — so the highest map zooms render the stored cells unclustered
+ * (`cellToParent(cell, 11) === cell`). A non-finite `targetRes` (e.g. a bad
+ * zoom→res mapping) degrades to unclustered output rather than throwing.
+ * Invalid input cells (corrupt/legacy metadata) are skipped defensively, as are
+ * valid cells coarser than `res` (which have no parent at the finer target res
+ * and would otherwise throw "incompatible resolutions").
+ *
+ * Output is deduplicated in first-seen order: sibling cells under one parent
+ * collapse to a single tile.
+ */
+declare function clusterCellsByZoom(cells: readonly string[], targetRes: number): string[];
 /**
  * Approximate distance in metres using equirectangular projection.
  * Accurate to < 0.1% for distances under 1 km at mid-latitudes,
@@ -60,4 +98,4 @@ declare function h3CellsMatch(h3a: string, h3b: string): boolean;
  */
 declare function isH3Index(id: string): boolean;
 //#endregion
-export { gpsToH3 as a, findNearbyGeoAnchor as i, KnownGeoAnchor as n, h3CellsMatch as o, approxDistanceMetres as r, isH3Index as s, H3_RESOLUTION as t };
+export { findNearbyGeoAnchor as a, h3CellsMatch as c, clusterCellsByZoom as i, isH3Index as l, KnownGeoAnchor as n, gpsPathToCoverageCells as o, approxDistanceMetres as r, gpsToH3 as s, H3_RESOLUTION as t };

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-qAZ5Fh5X.d.ts → image-capture-CNZDrQXG.d.ts}

@@ -1,4 +1,6 @@
-import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-Dan1MVTi.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 };