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

package/dist/ar-MFpFlV7j.js

@@ -0,0 +1,382 @@
+import "./ar/camera-blit-capture.js";
+import "./ar/chromium-camera-access-workaround.js";
+import "./ar/capture-failure-tracker.js";
+import "./ar/depth-sampler.js";
+import "./ar/depth-unprojection.js";
+import "./qr-size-measurer-DLb33geH.js";
+import "./ar/qr-size-depth-context.js";
+import { buildObjectPoints, transformPoint } from "./ar/qr-pose.js";
+import "./ar/qr-derived-pose.js";
+import "./ar/webxr-nue-basis.js";
+import "./ar/qr-debug-view.js";
+import { n as createDetectionScheduler } from "./qr-detection-controller-B-tLVd-S.js";
+import "./qr-pose-aggregation-DBiaLW0O.js";
+import "./webxr-session-DG-eNfny.js";
+import "./ar/occupancy-grid.js";
+import "./ar/frame-loop.js";
+import "./ar/xr-frame-loop.js";
+import "./image-capture-B2-b6tKK.js";
+import "./ar/xr-camera-texture.js";
+import "./ar/enable-gps-ar.js";
+import "./ar/replay-scene.js";
+//#region ../src/ar/qr-level.ts
+/** Thrown when a fetched level file fails validation. */
+var QrLevelValidationError = class extends Error {
+	constructor(message) {
+		super(`qr-level: ${message}`);
+		this.name = "QrLevelValidationError";
+	}
+};
+function isFiniteNumber(v) {
+	return typeof v === "number" && Number.isFinite(v);
+}
+function isRecord(v) {
+	return typeof v === "object" && v !== null;
+}
+/**
+* Validate the optional `qr.physicalSizeM`. When present it MUST be a positive
+* number (a `0`/negative authored size is a bug, not a "measure it instead"
+* signal). Returns `undefined` when omitted.
+*/
+function parsePhysicalSize(value) {
+	if (value === void 0) return void 0;
+	if (!isFiniteNumber(value) || value <= 0) throw new QrLevelValidationError("\"qr.physicalSizeM\" must be a positive number when present");
+	return value;
+}
+/**
+* Validate the optional `qr.geo`. When present every field is validated (a
+* partial geo is a bug — it would silently place the vote wrong). Returns
+* `undefined` when omitted; heading is normalized into `[0, 360)`.
+*/
+function parseGeo(value) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) throw new QrLevelValidationError("\"qr.geo\" must be an object when present");
+	const { lat, lon, alt, headingDeg } = value;
+	if (!isFiniteNumber(lat) || lat < -90 || lat > 90) throw new QrLevelValidationError("\"qr.geo.lat\" must be a number in [-90, 90]");
+	if (!isFiniteNumber(lon) || lon < -180 || lon > 180) throw new QrLevelValidationError("\"qr.geo.lon\" must be a number in [-180, 180]");
+	if (!isFiniteNumber(alt)) throw new QrLevelValidationError("\"qr.geo.alt\" must be a finite number");
+	if (!isFiniteNumber(headingDeg)) throw new QrLevelValidationError("\"qr.geo.headingDeg\" must be a finite number");
+	return {
+		lat,
+		lon,
+		alt,
+		headingDeg: (headingDeg % 360 + 360) % 360
+	};
+}
+/**
+* Validate an already-parsed value as a {@link QrLevel}. Throws
+* {@link QrLevelValidationError} with a descriptive message on any violation.
+*/
+function parseQrLevel(data) {
+	if (!isRecord(data)) throw new QrLevelValidationError("level file must be a JSON object");
+	if (!isFiniteNumber(data.version)) throw new QrLevelValidationError("missing/invalid \"version\"");
+	if (!isRecord(data.qr)) throw new QrLevelValidationError("missing/invalid \"qr\"");
+	const physicalSizeM = parsePhysicalSize(data.qr.physicalSizeM);
+	const geo = parseGeo(data.qr.geo);
+	return {
+		version: data.version,
+		qr: {
+			...physicalSizeM !== void 0 ? { physicalSizeM } : {},
+			...geo !== void 0 ? { geo } : {}
+		},
+		content: "content" in data ? data.content : void 0
+	};
+}
+/**
+* Fetch and validate a level file from `url`. Rejects with
+* {@link QrLevelValidationError} on a non-OK response, non-JSON body, or a
+* schema violation.
+*/
+async function fetchQrLevel(url, options = {}) {
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	if (!fetchImpl) throw new QrLevelValidationError("no fetch implementation available");
+	let response;
+	try {
+		response = await fetchImpl(url, { signal: options.signal });
+	} catch (err) {
+		throw new QrLevelValidationError(`fetch failed for ${url}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!response.ok) throw new QrLevelValidationError(`fetch ${url} returned status ${response.status}`);
+	let body;
+	try {
+		body = await response.json();
+	} catch {
+		throw new QrLevelValidationError(`response for ${url} was not valid JSON`);
+	}
+	return parseQrLevel(body);
+}
+//#endregion
+//#region ../src/ar/qr-gps-vote.ts
+/** Mean meters per degree of latitude (WGS-84 average). */
+const METERS_PER_DEG_LAT = 111320;
+/**
+* `count` points evenly spaced on a circle of radius `baselineM` in the QR
+* plane (z = 0), starting at local +x. The symmetric ring's centroid is the QR
+* center, so translation stays anchored there while the wide radius stiffens
+* the rotation fit. Non-collinear for `count ≥ 3`.
+*/
+function widePlanePoints(baselineM, count) {
+	const points = [];
+	for (let i = 0; i < count; i++) {
+		const theta = 2 * Math.PI * i / count;
+		points.push([
+			baselineM * Math.cos(theta),
+			baselineM * Math.sin(theta),
+			0
+		]);
+	}
+	return points;
+}
+/**
+* Map a QR-local plane offset (meters; +x right, +y up on the printed face) to
+* an East/North/Up offset, given the QR's compass heading. Vertical-QR
+* convention: +y is world up; +x is horizontal at `headingDeg` (clockwise from
+* North), so east = x·sin(h), north = x·cos(h).
+*/
+function localPlaneToEnu(localX, localY, headingDeg) {
+	const h = headingDeg * Math.PI / 180;
+	return {
+		east: localX * Math.sin(h),
+		north: localX * Math.cos(h),
+		up: localY
+	};
+}
+/** Apply an ENU meter offset to a geo pose (equirectangular; exact enough for sub-meter QR corners). */
+function offsetGeo(center, enu) {
+	const dLat = enu.north / METERS_PER_DEG_LAT;
+	const metersPerDegLon = METERS_PER_DEG_LAT * Math.cos(center.lat * Math.PI / 180);
+	const dLon = Math.abs(metersPerDegLon) < 1e-9 ? 0 : enu.east / metersPerDegLon;
+	return {
+		latitude: center.lat + dLat,
+		longitude: center.lon + dLon,
+		altitude: center.alt + enu.up
+	};
+}
+/**
+* Build the synthetic `recordGpsEvent` payload(s) for one QR detection. Returns
+* 4 corner correspondences by default, or 1 center correspondence when
+* `multiCorrespondence` is false. Each payload pairs the corner's odom position
+* (from the solved pose) with its absolute geo position (from the level file),
+* stamped with the tiny synthetic accuracy.
+*
+* @throws RangeError on a non-positive `sizeM` or `syntheticAccuracyM`.
+*/
+function buildQrGpsVotes(input) {
+	const { qrPoseWorld, sizeM, qrGeo, syntheticAccuracyM, odomRotation = qrPoseWorld.rotation, multiCorrespondence = true, baselineM, count = 4, timestamp = Date.now(), idPrefix = "qr" } = input;
+	if (!(syntheticAccuracyM > 0) || !Number.isFinite(syntheticAccuracyM)) throw new RangeError(`qr-gps-vote: syntheticAccuracyM must be positive, got ${syntheticAccuracyM}`);
+	const useWideBaseline = baselineM !== void 0 && Number.isFinite(baselineM) && baselineM > 0;
+	if (useWideBaseline && count < 3) throw new RangeError(`qr-gps-vote: wide-baseline count must be >= 3 (collinear otherwise), got ${count}`);
+	return (useWideBaseline ? widePlanePoints(baselineM, count) : multiCorrespondence ? buildObjectPoints(sizeM) : [[
+		0,
+		0,
+		0
+	]]).map((local, i) => {
+		const odomPosition = transformPoint(local, qrPoseWorld);
+		const geo = offsetGeo(qrGeo, localPlaneToEnu(local[0], local[1], qrGeo.headingDeg));
+		return {
+			odomPosition,
+			odomRotation,
+			rawGpsPoint: {
+				id: `${idPrefix}-${timestamp}-${i}`,
+				latitude: geo.latitude,
+				longitude: geo.longitude,
+				altitude: geo.altitude,
+				latLongAccuracy: syntheticAccuracyM,
+				timestamp
+			}
+		};
+	});
+}
+//#endregion
+//#region ../src/ar/qr-tracking-controller.ts
+function createQrTrackingController(config) {
+	const { frontEnd, solvePose, fetchLevel, dispatchVotes, onDetection, resolveSizeM, resolveStablePose, getCameraPose, getIntrinsics, syntheticAccuracyM, voteBaselineM, voteCount, isPlausible, onStatus, onLocked, onError, minIntervalMs = 150, requiredLockCount = 3, now } = config;
+	const timestampNow = now ?? (() => Date.now());
+	let status = "idle";
+	const levelCache = /* @__PURE__ */ new Map();
+	let active = null;
+	function setStatus(next) {
+		if (status === next) return;
+		status = next;
+		onStatus?.(next);
+	}
+	async function ensureLevel(url) {
+		const cached = levelCache.get(url);
+		if (cached) return cached;
+		setStatus("loading-level");
+		const level = await fetchLevel(url);
+		levelCache.set(url, level);
+		return level;
+	}
+	async function detect(image) {
+		if (status === "idle" || status === "error") setStatus("scanning");
+		const detection = await frontEnd.detect(image);
+		if (!detection) {
+			active = null;
+			return null;
+		}
+		const level = await ensureLevel(detection.text);
+		const sizeM = level.qr.physicalSizeM ?? resolveSizeM?.(detection.text, level) ?? null;
+		if (sizeM === null || !(sizeM > 0) || !Number.isFinite(sizeM)) {
+			active = null;
+			if (status === "loading-level") setStatus("scanning");
+			return null;
+		}
+		const cameraPose = getCameraPose();
+		const intrinsics = getIntrinsics(image);
+		if (!cameraPose || !intrinsics) {
+			active = null;
+			return null;
+		}
+		const solution = solvePose({
+			imagePoints: detection.corners,
+			sizeM,
+			intrinsics,
+			cameraPose
+		});
+		if (!solution) {
+			active = null;
+			return null;
+		}
+		if (isPlausible && !isPlausible(solution, cameraPose)) {
+			active = null;
+			return null;
+		}
+		active = {
+			level,
+			text: detection.text,
+			sizeM
+		};
+		return solution;
+	}
+	const scheduler = createDetectionScheduler({
+		detect,
+		minIntervalMs,
+		requiredLockCount,
+		now,
+		onLocked: (solution) => {
+			const current = active;
+			if (!current) return;
+			const { level, text, sizeM } = current;
+			onDetection?.({
+				text,
+				qrPoseWorld: solution.qrPoseWorld,
+				qrPoseInCamera: solution.qrPoseInCamera,
+				reprojectionErrorPx: solution.reprojectionErrorPx,
+				timestamp: timestampNow()
+			});
+			if (level.qr.geo) {
+				const votePose = resolveStablePose ? resolveStablePose(text) : solution.qrPoseWorld;
+				if (votePose) dispatchVotes(buildQrGpsVotes({
+					qrPoseWorld: votePose,
+					sizeM,
+					qrGeo: level.qr.geo,
+					syntheticAccuracyM,
+					...voteBaselineM !== void 0 ? { baselineM: voteBaselineM } : {},
+					...voteCount !== void 0 ? { count: voteCount } : {}
+				}));
+			}
+			setStatus("tracking");
+			onLocked?.(solution, level);
+		},
+		onMiss: () => {
+			if (status === "tracking") setStatus("scanning");
+		},
+		onError: (err) => {
+			active = null;
+			setStatus("error");
+			onError?.(err);
+		}
+	});
+	return {
+		offerFrame(image) {
+			scheduler.offerFrame(image);
+		},
+		get status() {
+			return status;
+		},
+		reset() {
+			levelCache.clear();
+			active = null;
+			setStatus("idle");
+		}
+	};
+}
+//#endregion
+//#region ../src/ar/qr-occupancy-check.ts
+const DEFAULTS = {
+	surfaceToleranceCells: 1.5,
+	minObservations: 1,
+	rayCorridorCells: 1,
+	occlusionMarginCells: 2
+};
+function distance(a, b) {
+	return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+/**
+* Classify a solved QR center against the occupancy grid.
+*
+* - `no-grid` (ok): the grid has no occupied voxels — nothing to check against.
+* - `floating` (not ok): nearest occupied voxel is farther than the tolerance.
+* - `behind-surface` (not ok): an occupied voxel lies on the camera→QR ray
+*   clearly in front of the QR (the QR is inside / beyond geometry).
+* - `plausible` (ok): on a surface with empty space toward the camera.
+*
+* All positions are raw-WebXR/odom space (the same frame as `qrPoseWorld`).
+*/
+function checkQrPlausibility(qrCenterWorld, cameraPosWorld, grid, options = {}) {
+	const surfaceToleranceCells = options.surfaceToleranceCells ?? DEFAULTS.surfaceToleranceCells;
+	const minObservations = options.minObservations ?? DEFAULTS.minObservations;
+	const rayCorridorCells = options.rayCorridorCells ?? DEFAULTS.rayCorridorCells;
+	const occlusionMarginCells = options.occlusionMarginCells ?? DEFAULTS.occlusionMarginCells;
+	const cells = grid.getOccupiedCells(minObservations);
+	if (cells.length === 0) return {
+		verdict: "no-grid",
+		ok: true,
+		nearestSurfaceDistanceM: Infinity
+	};
+	const cellSizeM = grid.cellSizeM;
+	const centers = cells.map((c) => grid.getCellCenter(c));
+	let nearest = Infinity;
+	for (const center of centers) {
+		const d = distance(center, qrCenterWorld);
+		if (d < nearest) nearest = d;
+	}
+	if (nearest > surfaceToleranceCells * cellSizeM) return {
+		verdict: "floating",
+		ok: false,
+		nearestSurfaceDistanceM: nearest
+	};
+	const dir = [
+		qrCenterWorld[0] - cameraPosWorld[0],
+		qrCenterWorld[1] - cameraPosWorld[1],
+		qrCenterWorld[2] - cameraPosWorld[2]
+	];
+	const rayLength = Math.hypot(dir[0], dir[1], dir[2]);
+	if (rayLength > cellSizeM) {
+		const nx = dir[0] / rayLength;
+		const ny = dir[1] / rayLength;
+		const nz = dir[2] / rayLength;
+		const corridor = rayCorridorCells * cellSizeM;
+		const tMax = rayLength - occlusionMarginCells * cellSizeM;
+		for (const center of centers) {
+			const ox = center[0] - cameraPosWorld[0];
+			const oy = center[1] - cameraPosWorld[1];
+			const oz = center[2] - cameraPosWorld[2];
+			const t = ox * nx + oy * ny + oz * nz;
+			if (t <= cellSizeM || t >= tMax) continue;
+			if (Math.hypot(ox - t * nx, oy - t * ny, oz - t * nz) < corridor) return {
+				verdict: "behind-surface",
+				ok: false,
+				nearestSurfaceDistanceM: nearest
+			};
+		}
+	}
+	return {
+		verdict: "plausible",
+		ok: true,
+		nearestSurfaceDistanceM: nearest
+	};
+}
+//#endregion
+export { localPlaneToEnu as a, fetchQrLevel as c, buildQrGpsVotes as i, parseQrLevel as l, createQrTrackingController as n, offsetGeo as o, METERS_PER_DEG_LAT as r, QrLevelValidationError as s, checkQrPlausibility as t };

package/dist/{ar-world-group-alignment-C9lwwIyI.d.ts → ar-world-group-alignment-69fgnB39.d.ts}

@@ -1,4 +1,4 @@
-import { t as SubscribableStore } from "./subscribe-to-selector-CZ6k1NFP.js";
+import { t as SubscribableStore } from "./subscribe-to-selector-B6EUmQ3I.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/ar-world-group-alignment.d.ts

package/dist/{camera-blit-capture-CnxUDbKx.d.ts → camera-blit-capture-NKT9H5-e.d.ts}

@@ -31,6 +31,28 @@ declare function computeCaptureSize(cameraWidth: number, cameraHeight: number, d
   width: number;
   height: number;
 };
+/**
+ * Compute blit dimensions that PRESERVE the camera aspect ratio with the
+ * **longer edge fixed at `maxEdge`**. Unlike {@link computeCaptureSize} (which
+ * divides the native resolution by a user divisor), this fits the frame into a
+ * fixed pixel budget, so a 4:3 camera becomes e.g. 512×384 — NOT a stretched
+ * 512×512. Used by the QR-detection blit (B2) so the detector sees an
+ * undistorted code while the readback cost stays bounded by `maxEdge²`.
+ *
+ * @param cameraWidth  - Native camera width in pixels (from XRCamera)
+ * @param cameraHeight - Native camera height in pixels (from XRCamera)
+ * @param maxEdge      - Target length (px) of the longer output edge.
+ * @returns Integer dimensions, longer edge == `maxEdge`, aspect preserved
+ *   (within rounding), each clamped to ≥ 1. When `maxEdge` itself is invalid
+ *   (< 1 / NaN / Infinity) the longer edge falls back to
+ *   `DEFAULT_BLIT_CONFIG.width` (still aspect-preserving). When the camera
+ *   dimensions are invalid (≤ 0 / NaN / Infinity) the aspect is unknown, so it
+ *   returns a square at the (possibly defaulted) edge.
+ */
+declare function computeAspectFitSize(cameraWidth: number, cameraHeight: number, maxEdge: number): {
+  width: number;
+  height: number;
+};
 /**
  * Captures readable pixel data from WebXR opaque camera textures
  * using the intermediate render target "blit" technique.
@@ -83,6 +105,29 @@ declare class CameraBlitCapture {
     width: number;
     height: number;
   } | null;
+  /**
+   * Capture the camera texture as **top-left-origin** RGBA — the orientation
+   * QR detection (and `BarcodeDetector`) expects — returning a FRESH copy that
+   * is safe to retain beyond the next capture.
+   *
+   * This is the efficient replacement for the demo's old JPEG round-trip: blit
+   * + readback (shared with {@link captureToBlob} / {@link captureToPixels}),
+   * then the same vertical flip the JPEG encoder applies, but with no encode →
+   * decode. Unlike {@link captureToPixels} (which returns the reusable internal
+   * buffer in WebGL bottom-row-first order), this returns an owned,
+   * correctly-oriented `Uint8ClampedArray`.
+   *
+   * IMPORTANT: Must be called within the XR animation frame callback, while the
+   * camera texture is valid.
+   *
+   * @returns `{ data, width, height }` (top-left RGBA), or null on
+   *   failure/dispose.
+   */
+  captureToRgba(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture): {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+  } | null;
   /**
    * Check if a pixel buffer is entirely black (all zeros).
    * Uses sampling for performance (checks BLACK_CHECK_SAMPLE_COUNT evenly-spaced pixels).
@@ -100,13 +145,21 @@ declare class CameraBlitCapture {
    */
   private pixelsToJpegBlob;
   private getFlippedImageData;
+  /**
+   * Produce a FRESH, top-left-origin RGBA copy of the internal readback buffer.
+   * WebGL `readPixels` returns bottom-row-first; this copies (so the internal
+   * buffer stays y-flipped for a subsequent capture) and swaps rows. Shared by
+   * the JPEG encode path ({@link getFlippedImageData}) and {@link captureToRgba}.
+   */
+  private flippedPixelCopy;
   private pixelsToJpegViaOffscreenCanvas;
   private pixelsToJpegViaCanvas;
   /**
-   * Flip ImageData vertically in-place.
-   * WebGL readPixels returns bottom-row-first; canvas expects top-row-first.
+   * Flip an RGBA buffer vertically in-place (row swap).
+   * WebGL readPixels returns bottom-row-first; canvas / detectors expect
+   * top-row-first.
    */
-  private flipImageDataVertically;
+  private flipRowsVertically;
   /**
    * Resize the render target and pixel buffer to match new dimensions.
    * Call this when the camera resolution is first known or changes.
@@ -134,4 +187,4 @@ declare class CameraBlitCapture {
   dispose(): void;
 }
 //#endregion
-export { computeCaptureSize as i, CameraBlitCaptureConfig as n, DEFAULT_BLIT_CONFIG as r, CameraBlitCapture as t };
+export { computeCaptureSize as a, computeAspectFitSize as i, CameraBlitCaptureConfig as n, DEFAULT_BLIT_CONFIG as r, CameraBlitCapture as t };

package/dist/capture-motion-gate-0Yl2NpQG.d.ts

@@ -0,0 +1,24 @@
+//#region ../src/ar/capture-motion-gate.d.ts
+/**
+ * User-/consumer-facing motion-filter configuration. Shared by both config
+ * shapes that carry it — `ImageCaptureConfig` (what `ImageCaptureManager`
+ * consumes) and `ImageCaptureOptions` (the persisted recorder options) — so the
+ * one definition cannot drift between them. The window size and glitch ceilings
+ * are deliberately NOT here: they are internal tuning constants, not exposed.
+ */
+interface MotionFilterConfig {
+  /** Master switch for the motion gate. Default `true`. */
+  enabled: boolean;
+  /** Angular-velocity threshold (rad/s); at/below this a frame is "calm". */
+  maxAngularVelocity: number;
+  /** Linear-velocity threshold (m/s); at/below this a frame is "calm". */
+  maxLinearVelocity: number;
+  /**
+   * Never-calm safety fallback: once a due capture has waited this many ms it
+   * fires regardless of motion, so an interval is never silently lost. A
+   * sensible value is ~2× the capture interval.
+   */
+  maxWaitMs: number;
+}
+//#endregion
+export { MotionFilterConfig as t };

package/dist/capture-motion-gate-4EscNZCw.js

@@ -0,0 +1,94 @@
+/**
+* Angular velocity (rad/s) above which a sample is treated as a tracking glitch
+* (e.g. relocalization teleport), not real motion. A genuine hand/device turn
+* tops out well below this; a teleport is far above it. Module-internal tuning
+* constant (not exported — the gate's user surface is only the four
+* `MotionFilterConfig` fields); overridable per-instance via the `MotionWindow`
+* constructor for tests.
+*/
+const ANGULAR_GLITCH_CEILING_RAD_S = 50;
+/**
+* Linear velocity (m/s) above which a sample is treated as a tracking glitch.
+* ~20 m/s (72 km/h) is unreachable by handheld scanning but trivially exceeded
+* by a relocalization origin jump. Module-internal tuning constant (see
+* {@link ANGULAR_GLITCH_CEILING_RAD_S}).
+*/
+const LINEAR_GLITCH_CEILING_M_S = 20;
+/**
+* Default motion-filter configuration. Enabled by default (plan §1). Thresholds
+* are PLACEHOLDERS pending on-device field tuning (plan §7) — record measured
+* values in implementation-progress.md once known. `maxWaitMs` of 4000 ms is
+* 2× the default 2000 ms image interval.
+*/
+const DEFAULT_MOTION_FILTER = {
+	enabled: true,
+	maxAngularVelocity: .6,
+	maxLinearVelocity: .5,
+	maxWaitMs: 4e3
+};
+/**
+* Decide whether a due capture should fire now or defer to a later frame.
+*
+* A frame is "calm" when BOTH windowed maxima are at/below their thresholds —
+* an empty window reports `Infinity`, so it is never calm (no capture before a
+* valid sample exists). If not calm, the capture is deferred UNTIL `msSinceDue`
+* reaches `maxWaitMs`, at which point it fires regardless to guarantee an
+* interval is never silently lost (worst case: one blurry frame, not a gap).
+*/
+function decideCapture(input) {
+	if (input.windowMaxAngular <= input.maxAngularVelocity && input.windowMaxLinear <= input.maxLinearVelocity) return "capture";
+	if (input.msSinceDue >= input.maxWaitMs) return "capture";
+	return "defer";
+}
+/**
+* Fixed-size ring of the most recent VALID (non-glitch) per-frame velocities.
+*
+* `maxAngular()`/`maxLinear()` return the max over the retained samples, or
+* `Infinity` when empty so "no data yet" reads as not-calm in
+* {@link decideCapture}. A sample exceeding either glitch ceiling is rejected
+* outright (`push` returns `false`) and never stored, so a relocalization spike
+* neither pollutes the window (no spurious defer) nor is treated as motion.
+*/
+var MotionWindow = class {
+	angularGlitchCeiling;
+	linearGlitchCeiling;
+	size;
+	angular = [];
+	linear = [];
+	constructor(size = 3, angularGlitchCeiling = ANGULAR_GLITCH_CEILING_RAD_S, linearGlitchCeiling = LINEAR_GLITCH_CEILING_M_S) {
+		this.angularGlitchCeiling = angularGlitchCeiling;
+		this.linearGlitchCeiling = linearGlitchCeiling;
+		this.size = Number.isFinite(size) && size >= 1 ? Math.floor(size) : 1;
+	}
+	/**
+	* Record a per-frame velocity pair. Returns `false` (and stores nothing) when
+	* the sample exceeds either glitch ceiling, `true` otherwise.
+	*/
+	push(angularVel, linearVel) {
+		if (!Number.isFinite(angularVel) || !Number.isFinite(linearVel) || angularVel > this.angularGlitchCeiling || linearVel > this.linearGlitchCeiling) return false;
+		this.angular.push(angularVel);
+		this.linear.push(linearVel);
+		if (this.angular.length > this.size) this.angular.shift();
+		if (this.linear.length > this.size) this.linear.shift();
+		return true;
+	}
+	/** Whether the window holds at least one valid (non-glitch) sample yet. */
+	hasSamples() {
+		return this.angular.length > 0;
+	}
+	/** Max angular velocity over the retained window, or `Infinity` if empty. */
+	maxAngular() {
+		return this.angular.length === 0 ? Number.POSITIVE_INFINITY : Math.max(...this.angular);
+	}
+	/** Max linear velocity over the retained window, or `Infinity` if empty. */
+	maxLinear() {
+		return this.linear.length === 0 ? Number.POSITIVE_INFINITY : Math.max(...this.linear);
+	}
+	/** Clear all samples (e.g. on tracking loss / capture restart). */
+	reset() {
+		this.angular.length = 0;
+		this.linear.length = 0;
+	}
+};
+//#endregion
+export { MotionWindow as n, decideCapture as r, DEFAULT_MOTION_FILTER as t };

package/dist/concurrency-By0oOTZt.d.ts

@@ -0,0 +1,50 @@
+//#region ../src/utils/concurrency.d.ts
+/**
+ * Concurrency Utilities
+ *
+ * Provides helpers for limiting the number of concurrent async operations.
+ * Used to prevent excessive memory consumption when scanning many files
+ * in parallel (e.g., reading zip metadata during scenario discovery).
+ */
+/**
+ * Map over an array with a concurrency limit on the async mapper function.
+ *
+ * Behaves like `Promise.all(items.map(fn))` but limits how many mapper
+ * invocations run simultaneously. Results are returned in the same order
+ * as the input items.
+ *
+ * @param items - Array of items to process
+ * @param limit - Maximum number of concurrent mapper invocations
+ * @param mapper - Async function to apply to each item
+ * @returns Array of results in the same order as input items
+ * @throws Re-throws the first error from any mapper invocation (fail-fast)
+ */
+declare function mapWithConcurrencyLimit<T, R>(items: T[], limit: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * Run an async worker over each item with a concurrency cap, invoking the worker
+ * per item as the pool pulls it (rather than collecting results into an array).
+ *
+ * Unlike {@link mapWithConcurrencyLimit}, this returns no values — the worker is
+ * expected to produce its side effect (e.g. emit a streaming callback) itself.
+ * This is the shape progressive consumers need: each item is handled and can be
+ * reported as soon as it settles, instead of waiting for the whole batch.
+ *
+ * Completion order is **not** guaranteed (it depends on which worker finishes
+ * first). Each item's worker is invoked exactly once unless the run is aborted.
+ *
+ * When an `AbortSignal` is supplied, workers stop pulling **new** items as soon
+ * as the signal is aborted (checked before each pull). Items already in flight
+ * run to completion — the File System Access reads underneath cannot be torn
+ * mid-read — but no further items are started, so a destroyed consumer stops
+ * accumulating work. If the signal is already aborted, no work starts at all.
+ *
+ * @param items - Items to process
+ * @param limit - Maximum number of concurrent worker invocations (`>= 1`)
+ * @param worker - Async side-effecting function applied to each item
+ * @param signal - Optional abort signal that halts pulling new items
+ * @throws RangeError if `limit < 1`
+ * @throws Re-throws the first error from any worker invocation (fail-fast)
+ */
+declare function forEachWithConcurrencyLimit<T>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<void>, signal?: AbortSignal): Promise<void>;
+//#endregion
+export { mapWithConcurrencyLimit as n, forEachWithConcurrencyLimit as t };

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-import { a as LibraryRootState, c as RootState, d as calcRelativeCoordsInMeters, f as createGpsSlamStore, g as webxrToNUE, h as validateLicenseKey, i as LatLongAlt, l as Vector3, m as odometryTrackingRestarted, n as GpsPoint, o as Matrix4, p as isIdentityMatrix4, r as LatLong, s as Quaternion, t as ArImageCapture, u as calcGpsCoords } from "../index-CF05QV2m.js";
-export { ArImageCapture, GpsPoint, LatLong, LatLongAlt, LibraryRootState, Matrix4, Quaternion, RootState, Vector3, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };
+import { _ as odometryTrackingRestarted, a as LibraryRootState, c as RootState, d as bearingDeltaDeg, f as calcGpsCoords, g as magneticHeadingFromEnuQuat, h as isIdentityMatrix4, i as LatLongAlt, l as Vector3, m as createGpsSlamStore, n as GpsPoint, o as Matrix4, p as calcRelativeCoordsInMeters, r as LatLong, s as Quaternion, t as ArImageCapture, u as arNorthBearingDeg, v as validateLicenseKey, y as webxrToNUE } from "../index-_Rhgoqkh.js";
+export { ArImageCapture, GpsPoint, LatLong, LatLongAlt, LibraryRootState, Matrix4, Quaternion, RootState, Vector3, arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };

package/dist/core/index.js

@@ -1,2 +1,2 @@
-import { calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE } from "gps-plus-slam-js";
-export { calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };
+import { arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey, webxrToNUE } from "gps-plus-slam-js";
+export { arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };