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

package/dist/state/index.js

@@ -2,6 +2,7 @@ import { buildRawGpsPoint, buildRecordGpsEventPayload, createGpsPositionHandler,
 import { clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectLastSensorOrientation, selectLastValidPose, selectLostFrameCount, selectTrackingPhase, trackingReducer } from "./tracking-slice.js";
 import { DEFAULT_RECORDING_OPTIONS, DEPTH_CONSTRAINTS, IMAGE_CONSTRAINTS, STORAGE_KEY, cloneRecordingOptions, loadRecordingOptions, resetRecordingOptions, saveRecordingOptions, validateDepthOptions, validateImageOptions, validateRecordingOptions } from "./recording-options.js";
 import { endSession, recordDepthSample, recordWriteFailure, recordingReducer, startSession } from "./recording-slice.js";
+import { DEFAULT_QR_MAX_HISTORY, clearAllQrMarkers, clearQrMarker, medianQrPosition, pruneQrDetections, qrDetectedReducer, recordQrDetection, recordQrSizeEstimate, selectDerivedQrPlacement, selectLatestQrDetection, selectQrMarker, selectQrMarkers, selectQrPoseStability, selectQrRawObservations, selectQrSize, selectResolvedQrSizeM, selectSolvedQrPose, selectStableQrPose, setQrMaxHistory } from "./qr-detected-slice.js";
 import { captureGpsAnchorSample } from "./gps-ar-pose-sampler.js";
 import { selectAlignmentMatrix, selectFrameTilesInWebXR, selectGpsPositions, selectOdometryPositions, selectOdometryRotations, selectZeroReference } from "./app-selectors.js";
 import { DEFAULT_TRACKING_QUALITY_OPTIONS, computeCompassAgreement, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeResidualConsensus, computeTrackingQualityReport, createTrackingQualityListenerMiddleware, degradedCountUpdated, firstAgreementReached, matrixDelta, reportUpdated, resetTrackingQuality, selectFirstAgreementObservationIndex, selectRecentAlignments, selectTrackingQuality, snapshotPushed, snapshotsTrimmed, trackingQualityReducer } from "./tracking-quality.js";
@@ -11,5 +12,5 @@ import { replayRecording } from "./recording-replayer.js";
 import { DEFAULT_MAX_DELAY_MS, ReplayEngine, computeInterActionDelay, extractActionTimestamp } from "./replay-engine.js";
 import { subscribeToSelector } from "./subscribe-to-selector.js";
 import { wireStoreSubscribers } from "./store-subscribers.js";
-import { a as computeOnboardingGuidance, i as setZeroPos, n as calcRelativeCoordsInMeters, o as selectOnboardingGuidance, r as recordGpsEvent, t as add2dImage } from "../state-BkIfpiyA.js";
-export { DEFAULT_MAX_DELAY_MS, DEFAULT_RECORDING_OPTIONS, DEFAULT_TRACKING_QUALITY_OPTIONS, DEPTH_CONSTRAINTS, IMAGE_CONSTRAINTS, ReplayEngine, STORAGE_KEY, add2dImage, buildRawGpsPoint, buildRecordGpsEventPayload, calcRelativeCoordsInMeters, captureGpsAnchorSample, clearLastRestartedPayload, cloneRecordingOptions, computeCompassAgreement, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeInterActionDelay, computeOnboardingGuidance, computeResidualConsensus, computeTrackingQualityReport, createGpsPositionHandler, createPersistenceMiddleware, createSlamAppStore, createTrackingQualityListenerMiddleware, degradedCountUpdated, endSession, eulerToQuaternion, extractActionTimestamp, extractOdomPosition, extractOdomRotation, firstAgreementReached, getLastDeviceOrientation, loadRecordingOptions, matrixDelta, originReset, poseLost, poseReceived, recordDepthSample, recordGpsEvent, recordWriteFailure, recordingReducer, replayRecording, reportUpdated, resetCoordinatorState, resetRecordingOptions, resetTracking, resetTrackingQuality, saveRecordingOptions, selectAlignmentMatrix, selectFirstAgreementObservationIndex, selectFrameTilesInWebXR, selectGpsPositions, selectLastRestartedPayload, selectLastSensorOrientation, selectLastValidPose, selectLostFrameCount, selectOdometryPositions, selectOdometryRotations, selectOnboardingGuidance, selectRecentAlignments, selectTrackingPhase, selectTrackingQuality, selectZeroReference, setZeroPos, slicePrefixOf, snapshotPushed, snapshotsTrimmed, startSession, subscribeToSelector, trackingQualityReducer, trackingReducer, updateDeviceOrientation, validateDepthOptions, validateImageOptions, validateRecordingOptions, wireStoreSubscribers };
+import { a as computeOnboardingGuidance, i as setZeroPos, n as calcRelativeCoordsInMeters, o as selectOnboardingGuidance, r as recordGpsEvent, t as add2dImage } from "../state-IEw0ZsBu.js";
+export { DEFAULT_MAX_DELAY_MS, DEFAULT_QR_MAX_HISTORY, DEFAULT_RECORDING_OPTIONS, DEFAULT_TRACKING_QUALITY_OPTIONS, DEPTH_CONSTRAINTS, IMAGE_CONSTRAINTS, ReplayEngine, STORAGE_KEY, add2dImage, buildRawGpsPoint, buildRecordGpsEventPayload, calcRelativeCoordsInMeters, captureGpsAnchorSample, clearAllQrMarkers, clearLastRestartedPayload, clearQrMarker, cloneRecordingOptions, computeCompassAgreement, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeInterActionDelay, computeOnboardingGuidance, computeResidualConsensus, computeTrackingQualityReport, createGpsPositionHandler, createPersistenceMiddleware, createSlamAppStore, createTrackingQualityListenerMiddleware, degradedCountUpdated, endSession, eulerToQuaternion, extractActionTimestamp, extractOdomPosition, extractOdomRotation, firstAgreementReached, getLastDeviceOrientation, loadRecordingOptions, matrixDelta, medianQrPosition, originReset, poseLost, poseReceived, pruneQrDetections, qrDetectedReducer, recordDepthSample, recordGpsEvent, recordQrDetection, recordQrSizeEstimate, recordWriteFailure, recordingReducer, replayRecording, reportUpdated, resetCoordinatorState, resetRecordingOptions, resetTracking, resetTrackingQuality, saveRecordingOptions, selectAlignmentMatrix, selectDerivedQrPlacement, selectFirstAgreementObservationIndex, selectFrameTilesInWebXR, selectGpsPositions, selectLastRestartedPayload, selectLastSensorOrientation, selectLastValidPose, selectLatestQrDetection, selectLostFrameCount, selectOdometryPositions, selectOdometryRotations, selectOnboardingGuidance, selectQrMarker, selectQrMarkers, selectQrPoseStability, selectQrRawObservations, selectQrSize, selectRecentAlignments, selectResolvedQrSizeM, selectSolvedQrPose, selectStableQrPose, selectTrackingPhase, selectTrackingQuality, selectZeroReference, setQrMaxHistory, setZeroPos, slicePrefixOf, snapshotPushed, snapshotsTrimmed, startSession, subscribeToSelector, trackingQualityReducer, trackingReducer, updateDeviceOrientation, validateDepthOptions, validateImageOptions, validateRecordingOptions, wireStoreSubscribers };

package/dist/state/persistence-middleware.d.ts

@@ -1,2 +1,2 @@
-import { n as createPersistenceMiddleware, r as slicePrefixOf, t as PersistenceMiddlewareOptions } from "../persistence-middleware-DwyzgfWr.js";
+import { n as createPersistenceMiddleware, r as slicePrefixOf, t as PersistenceMiddlewareOptions } from "../persistence-middleware-5eearhSV.js";
 export { PersistenceMiddlewareOptions, createPersistenceMiddleware, slicePrefixOf };

package/dist/state/qr-detected-slice.d.ts

@@ -0,0 +1,4 @@
+import { d as QrSizeStatus, l as QrSizeEstimate } from "../qr-size-measurer-D7739ZpB.js";
+import { a as QrPoseStability, o as QrPoseStabilityOptions, s as QrPoseStabilityStatus } from "../qr-pose-aggregation-CFlmLm6w.js";
+import { C as setQrMaxHistory, S as selectStableQrPose, _ as selectQrPoseStability, a as RootWithQrDetected, b as selectResolvedQrSizeM, c as medianQrPosition, d as recordQrDetection, f as recordQrSizeEstimate, g as selectQrMarkers, h as selectQrMarker, i as QrMarkerState, l as pruneQrDetections, m as selectLatestQrDetection, n as QrDetectedState, o as clearAllQrMarkers, p as selectDerivedQrPlacement, r as QrDetectionEntry, s as clearQrMarker, t as DEFAULT_QR_MAX_HISTORY, u as qrDetectedReducer, v as selectQrRawObservations, x as selectSolvedQrPose, y as selectQrSize } from "../qr-detected-slice-Cpv-dg82.js";
+export { DEFAULT_QR_MAX_HISTORY, QrDetectedState, QrDetectionEntry, QrMarkerState, QrPoseStability, QrPoseStabilityOptions, QrPoseStabilityStatus, QrSizeEstimate, QrSizeStatus, RootWithQrDetected, clearAllQrMarkers, clearQrMarker, medianQrPosition, pruneQrDetections, qrDetectedReducer, recordQrDetection, recordQrSizeEstimate, selectDerivedQrPlacement, selectLatestQrDetection, selectQrMarker, selectQrMarkers, selectQrPoseStability, selectQrRawObservations, selectQrSize, selectResolvedQrSizeM, selectSolvedQrPose, selectStableQrPose, setQrMaxHistory };

package/dist/state/qr-detected-slice.js

@@ -0,0 +1,311 @@
+import { deriveQrPlacement, deriveSolvedQrPose } from "../ar/qr-derived-pose.js";
+import { i as evaluateQrPoseStability } from "../qr-pose-aggregation-DXR9STHs.js";
+import { createSlice } from "@reduxjs/toolkit";
+//#region ../src/state/qr-detected-slice.ts
+/**
+* `qrDetected` Redux slice — Note 3 of the QR-tracking follow-up plan
+* (docs `2026-06-15-followup-qr-tracking-generalization-overlay-and-north.md`).
+*
+* A detection-agnostic, framework-level store of "what was detected, where, in
+* 3D" that overlay / trigger / anchor consumers subscribe to INDEPENDENTLY of
+* the GPS fusion. The QR-tracking controller dispatches into it on every lock
+* (alongside, or instead of, the synthetic GPS vote — the vote is optional, the
+* `qrDetected` emission is not). Both the QR-tracking demo and the Recorder
+* consume the SAME slice — it is not duplicated per app and does NOT live in the
+* closed-source fusion core (locked maintainer decision, 2026-06-15 interview).
+*
+* Shape (locked decision): a dictionary keyed by the decoded payload (text/URL),
+* value = a per-marker BOUNDED RING BUFFER of detections + a size-lifecycle
+* estimate. Identity is the payload itself (already unique, human-debuggable) —
+* two physically-distinct markers sharing a payload merge by design, and a
+* *moving* marker with one payload accumulates a motion path (also desired).
+* The ring buffer is bounded by {@link QrDetectedState.maxHistory} so a naive
+* consumer cannot leak; `pruneQrDetections` is the explicit custom-cleanup path.
+*
+* Detection-agnostic on purpose (Note 1): the same shape (world pose + label +
+* confidence + timestamp) generalizes to future object detection (YOLO etc.),
+* so the fields are deliberately not QR-specific beyond the payload key.
+*
+* This slice is OPT-IN: apps wire it via `createSlamAppStore({ extraReducers:
+* { qrDetected: qrDetectedReducer } })`. It is not a built-in of the store
+* factory, so framework consumers that never detect anything pay nothing.
+*
+* @see ../ar/qr-tracking-controller.ts — the producer (dispatches `recordQrDetection`).
+* @see ../ar/qr-pose.ts — `Pose` / `QrPoseSolution` (the per-detection geometry).
+*/
+/**
+* Default ring-buffer cap per marker. Bounded so an overlay that never prunes
+* still cannot leak; large enough to support a robust median over a sliding
+* window and a short motion path. Override via {@link setQrMaxHistory}.
+*/
+const DEFAULT_QR_MAX_HISTORY = 32;
+const initialSize = () => ({
+	status: "unknown",
+	estimateM: null,
+	sampleCount: 0,
+	spreadM: 0
+});
+const initialState = {
+	maxHistory: 32,
+	markers: {}
+};
+/** Trim a detection list to at most `cap`, dropping the oldest. */
+function capDetections(detections, cap) {
+	if (cap <= 0) return [];
+	return detections.length > cap ? detections.slice(detections.length - cap) : detections.slice();
+}
+const qrDetectedSlice = createSlice({
+	name: "qrDetected",
+	initialState,
+	reducers: {
+		/**
+		* Append a detection to its marker's ring buffer (creating the marker on
+		* first sight), enforcing `maxHistory`. Returns a fresh state object rather
+		* than mutating the immer draft: the entry's `Pose` carries readonly
+		* `Vector3`/`Quaternion` tuples that immer's `WritableDraft` rejects (same
+		* reason `tracking-slice.originReset` returns new state).
+		*/
+		recordQrDetection(state, action) {
+			const entry = action.payload;
+			const existing = state.markers[entry.text];
+			const detections = capDetections(existing ? [...existing.detections, entry] : [entry], state.maxHistory);
+			const marker = {
+				text: entry.text,
+				detections,
+				size: existing?.size ?? initialSize()
+			};
+			return {
+				...state,
+				markers: {
+					...state.markers,
+					[entry.text]: marker
+				}
+			};
+		},
+		/**
+		* Set a marker's size estimate (the Note 3 size lifecycle). Creates the
+		* marker with an empty history if it has no detections yet (a size can be
+		* authored before any detection).
+		*/
+		recordQrSizeEstimate(state, action) {
+			const { text, estimate } = action.payload;
+			const existing = state.markers[text];
+			const marker = {
+				text,
+				detections: existing ? existing.detections.slice() : [],
+				size: estimate
+			};
+			return {
+				...state,
+				markers: {
+					...state.markers,
+					[text]: marker
+				}
+			};
+		},
+		/**
+		* Drop the oldest `count` detections from one marker (explicit custom
+		* cleanup, beyond the automatic ring-buffer cap). No-op for an unknown
+		* marker or `count <= 0`.
+		*/
+		pruneQrDetections(state, action) {
+			const { text, count } = action.payload;
+			const existing = state.markers[text];
+			if (!existing || count <= 0) return state;
+			const marker = {
+				...existing,
+				detections: existing.detections.slice(count)
+			};
+			return {
+				...state,
+				markers: {
+					...state.markers,
+					[text]: marker
+				}
+			};
+		},
+		/** Remove one marker entirely. */
+		clearQrMarker(state, action) {
+			const { [action.payload.text]: _removed, ...rest } = state.markers;
+			return {
+				...state,
+				markers: rest
+			};
+		},
+		/** Remove every marker (e.g. on session reset). */
+		clearAllQrMarkers(state) {
+			return {
+				...state,
+				markers: {}
+			};
+		},
+		/**
+		* Change the ring-buffer cap. Existing markers are re-trimmed immediately
+		* so the invariant "no marker exceeds `maxHistory`" holds at all times.
+		*/
+		setQrMaxHistory(state, action) {
+			const next = Math.max(0, Math.floor(action.payload));
+			const markers = {};
+			for (const [key, marker] of Object.entries(state.markers)) markers[key] = {
+				...marker,
+				detections: capDetections(marker.detections, next)
+			};
+			return {
+				...state,
+				maxHistory: next,
+				markers
+			};
+		}
+	}
+});
+const { recordQrDetection, recordQrSizeEstimate, pruneQrDetections, clearQrMarker, clearAllQrMarkers, setQrMaxHistory } = qrDetectedSlice.actions;
+const qrDetectedReducer = qrDetectedSlice.reducer;
+function selectQrMarkers(state) {
+	return state.qrDetected.markers;
+}
+function selectQrMarker(state, text) {
+	return state.qrDetected.markers[text];
+}
+/**
+* The newest detection for a marker (the natural overlay-persistence source —
+* an overlay reads this and keeps the last pose across detection misses rather
+* than unmounting/flickering).
+*/
+function selectLatestQrDetection(state, text) {
+	const marker = state.qrDetected.markers[text];
+	if (!marker || marker.detections.length === 0) return void 0;
+	return marker.detections[marker.detections.length - 1];
+}
+function selectQrSize(state, text) {
+	return state.qrDetected.markers[text]?.size;
+}
+/**
+* Resolve a marker's measured size for the high-weight GPS vote
+* (framework-wiring-options Part B, Option a). Returns the running-median
+* `estimateM` ONCE the size lifecycle reports `'estimated'`, else `null` ("keep
+* scanning"). This is the bridge an app injects as the QR controller's
+* `resolveSizeM`, so a size-less-but-geo level votes the moment the slice
+* converges — **without** the `ar` controller ever importing the slice (which
+* would close the `ar → state` cycle):
+*
+* ```ts
+* resolveSizeM: (text) => selectResolvedQrSizeM(store.getState(), text),
+* ```
+*
+* Per the Note 3 decision (confirmed) a reliably-estimated *measured* size
+* drives the vote under the *same* gate as an authored size — no extra
+* size-specific bar — because the §7 occupancy + reprojection + outlier-rejection
+* backstops already bound a bad read.
+*/
+function selectResolvedQrSizeM(state, text) {
+	const size = state.qrDetected.markers[text]?.size;
+	return size?.status === "estimated" ? size.estimateM : null;
+}
+/** Per-axis median of a numeric list (returns the lower-middle for even n). */
+function medianOf(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	return sorted[Math.floor((sorted.length - 1) / 2)];
+}
+/**
+* Robust per-axis median of the world positions across a marker's detection
+* window — the "running estimate" the bounded buffer enables (Note 3). Outliers
+* in fewer than half the samples cannot move the result outside the inlier
+* range. Skips RAW-only entries that carry no solved pose (D-A); returns `null`
+* for an empty window (or one with no solved poses at all).
+*/
+function medianQrPosition(entries) {
+	const poses = entries.map((e) => e.qrPoseWorld).filter((p) => p !== void 0);
+	if (poses.length === 0) return null;
+	const xs = poses.map((p) => p.position[0]);
+	const ys = poses.map((p) => p.position[1]);
+	const zs = poses.map((p) => p.position[2]);
+	return [
+		medianOf(xs),
+		medianOf(ys),
+		medianOf(zs)
+	];
+}
+/**
+* The pose-stability lifecycle for a marker, derived from its raw detection ring
+* buffer (NOT stored separately — the detections are the source of truth, unlike
+* the depth-measured size which is accumulated outside the buffer). Mirrors the
+* size lifecycle's `unknown → measuring → stable` shape so the HUD can show
+* "converging…" vs "stable". See `ar/qr-pose-aggregation.ts`.
+*/
+function selectQrPoseStability(state, text, options) {
+	const marker = state.qrDetected.markers[text];
+	return evaluateQrPoseStability(marker ? marker.detections.map((d) => d.qrPoseWorld).filter((p) => p !== void 0) : [], options);
+}
+/**
+* The robust filtered QR world pose, exposed ONLY once the stability gate is
+* `stable` (else `null` — "keep accumulating"). This is the pose analogue of
+* {@link selectResolvedQrSizeM}: the `resolveStablePose`-style bridge an app
+* injects into the QR controller / demo so the `ar` layer never imports the
+* slice. The high-weight vote and the smooth overlay consume THIS, never the raw
+* latest pose (which stays available via {@link selectLatestQrDetection} for
+* scanning feedback / overlay persistence across misses).
+*
+* ```ts
+* resolveStablePose: (text) => selectStableQrPose(store.getState(), text),
+* ```
+*/
+function selectStableQrPose(state, text, options) {
+	const stability = selectQrPoseStability(state, text, options);
+	return stability.status === "stable" ? stability.pose : null;
+}
+/**
+* Narrow a stored entry to a {@link RawQrObservation} — i.e. one that carries
+* the full raw detector output. During the D-A-2 transition some entries may
+* still be solved-pose-only (no raw fields); those are skipped by the derive
+* selector. After WS-3 every entry is raw and this guard always holds.
+*/
+function toRawObservation(entry) {
+	if (!entry.corners || !entry.cameraPose || !entry.projectionMatrix || entry.imageWidth === void 0 || entry.imageHeight === void 0) return null;
+	return {
+		text: entry.text,
+		corners: entry.corners,
+		cameraPose: entry.cameraPose,
+		projectionMatrix: entry.projectionMatrix,
+		imageWidth: entry.imageWidth,
+		imageHeight: entry.imageHeight,
+		timestamp: entry.timestamp
+	};
+}
+/**
+* Derive the best-effort solved WORLD pose for a marker from its RAW observation
+* history (decision D-A): accumulate size over the history against the injected
+* `resolveDepthAt` as-of join, then PnP-solve the latest observation. Returns
+* `null` when the marker is unknown, has no raw observations, cannot be sized
+* yet, or PnP rejects the latest quad — the re-test-friendly replacement for the
+* once-stored solved pose. Runs identically live and on replay (only
+* `deps.resolveDepthAt` differs). See `ar/qr-derived-pose.ts`.
+*/
+function selectSolvedQrPose(state, text, deps) {
+	return deriveSolvedQrPose(text, selectQrRawObservations(state, text), deps);
+}
+/**
+* The marker's stored entries narrowed to {@link RawQrObservation}s (entries
+* carrying the full raw detector output), oldest→newest. Empty for an unknown
+* marker or one with only solved-pose-only (transitional) entries. This is the
+* shared mapping the derive-on-read selectors and the incremental deriver
+* consume — exposed so a stateful consumer (the recorder's debug controller)
+* can hand raw observations to `createIncrementalQrPlacement` without
+* re-implementing the `toRawObservation` guard.
+*/
+function selectQrRawObservations(state, text) {
+	const marker = state.qrDetected.markers[text];
+	if (!marker) return [];
+	return marker.detections.map(toRawObservation).filter((o) => o !== null);
+}
+/**
+* Derive the best-effort {@link DerivedQrPlacement} (solved pose AND the metric
+* size that solved it) for a marker from its RAW observation history. The debug
+* viz needs the size to draw the cube, so this returns both in one history pass
+* (decision D-A; see {@link deriveQrPlacement}). `null` under the same
+* conditions as {@link selectSolvedQrPose}. Runs identically live and on replay.
+*/
+function selectDerivedQrPlacement(state, text, deps) {
+	return deriveQrPlacement(text, selectQrRawObservations(state, text), deps);
+}
+//#endregion
+export { DEFAULT_QR_MAX_HISTORY, clearAllQrMarkers, clearQrMarker, medianQrPosition, pruneQrDetections, qrDetectedReducer, recordQrDetection, recordQrSizeEstimate, selectDerivedQrPlacement, selectLatestQrDetection, selectQrMarker, selectQrMarkers, selectQrPoseStability, selectQrRawObservations, selectQrSize, selectResolvedQrSizeM, selectSolvedQrPose, selectStableQrPose, setQrMaxHistory };

package/dist/state/recording-options.d.ts

@@ -1,2 +1,2 @@
-import { _ as validateRecordingOptions, a as IMAGE_CONSTRAINTS, c as RecordingOptionsInput, d as loadRecordingOptions, f as resetRecordingOptions, g as validateImageOptions, h as validateDepthOptions, i as DepthCaptureOptions, l as STORAGE_KEY, m as validateArCrashIsolationOptions, n as DEFAULT_RECORDING_OPTIONS, o as ImageCaptureOptions, p as saveRecordingOptions, r as DEPTH_CONSTRAINTS, s as RecordingOptions, t as ArCrashIsolationOptions, u as cloneRecordingOptions } from "../recording-options-DJBXuMxV.js";
-export { ArCrashIsolationOptions, DEFAULT_RECORDING_OPTIONS, DEPTH_CONSTRAINTS, DepthCaptureOptions, IMAGE_CONSTRAINTS, ImageCaptureOptions, RecordingOptions, RecordingOptionsInput, STORAGE_KEY, cloneRecordingOptions, loadRecordingOptions, resetRecordingOptions, saveRecordingOptions, validateArCrashIsolationOptions, validateDepthOptions, validateImageOptions, validateRecordingOptions };
+import { C as validateFrameTileDisplayOptions, D as validateRecordingOptions, E as validateQrOptions, O as validateVisualizationOptions, S as validateDepthOptions, T as validateOccupancyOptions, _ as cloneRecordingOptions, a as FRAME_TILE_DISPLAY_CONSTRAINTS, b as saveRecordingOptions, c as ImageCaptureOptions, d as QR_CONSTRAINTS, f as QrCaptureOptions, g as VisualizationOptions, h as STORAGE_KEY, i as DepthCaptureOptions, l as OCCUPANCY_CONSTRAINTS, m as RecordingOptionsInput, n as DEFAULT_RECORDING_OPTIONS, o as FrameTileDisplayOptions, p as RecordingOptions, r as DEPTH_CONSTRAINTS, s as IMAGE_CONSTRAINTS, t as ArCrashIsolationOptions, u as OccupancyOptions, v as loadRecordingOptions, w as validateImageOptions, x as validateArCrashIsolationOptions, y as resetRecordingOptions } from "../recording-options-D93kksJU.js";
+export { ArCrashIsolationOptions, DEFAULT_RECORDING_OPTIONS, DEPTH_CONSTRAINTS, DepthCaptureOptions, FRAME_TILE_DISPLAY_CONSTRAINTS, FrameTileDisplayOptions, IMAGE_CONSTRAINTS, ImageCaptureOptions, OCCUPANCY_CONSTRAINTS, OccupancyOptions, QR_CONSTRAINTS, QrCaptureOptions, RecordingOptions, RecordingOptionsInput, STORAGE_KEY, VisualizationOptions, cloneRecordingOptions, loadRecordingOptions, resetRecordingOptions, saveRecordingOptions, validateArCrashIsolationOptions, validateDepthOptions, validateFrameTileDisplayOptions, validateImageOptions, validateOccupancyOptions, validateQrOptions, validateRecordingOptions, validateVisualizationOptions };

package/dist/state/recording-options.js

@@ -40,6 +40,19 @@ const DEFAULT_RECORDING_OPTIONS = {
 		enableCss3dRenderer: true,
 		enableCameraTextureAcquisition: true,
 		applyChromiumProjectionLayerWorkaround: true
+	},
+	occupancy: { cellSizeM: .15 },
+	frameTileDisplay: { divisor: 2 },
+	visualization: {
+		frameTiles: true,
+		occupancyCubes: true,
+		gpsAlignmentMarkers: true,
+		compassCubes: true
+	},
+	qr: {
+		enabled: false,
+		intervalMs: 125,
+		captureSize: 1024
 	}
 };
 /** Validation constraints for depth options */
@@ -74,6 +87,54 @@ const IMAGE_CONSTRAINTS = {
 	}
 };
 /**
+* Validation constraints for occupancy options.
+*
+* `cellSizeM` is clamped to 1–20 cm. The floor exists because cell count (and
+* therefore the cube `InstancedMesh`, the grid `Map`, and the COLMAP
+* `points3D` row count) scales as 1/cellSize³ — sub-centimetre voxels are both
+* a memory/perf cliff on a phone and below the depth sensor's noise floor.
+* Step is 1 cm (the settings slider operates in cm).
+*/
+const OCCUPANCY_CONSTRAINTS = { cellSizeM: {
+	min: .01,
+	max: .2,
+	step: .01
+} };
+/**
+* Validation constraints for the frame-tile display-resolution divisor.
+*
+* Clamped to 1–8 (full down to one-eighth per dimension), mirroring the capture
+* `IMAGE_CONSTRAINTS.resolutionDivisor` range so the settings slider behaves the
+* same. The intended stops are 1, 2, 4, 8 (full / half / quarter / eighth); the
+* divisor is rounded to an integer so the resize target dimensions stay clean.
+*/
+const FRAME_TILE_DISPLAY_CONSTRAINTS = { divisor: {
+	min: 1,
+	max: 8,
+	step: 1
+} };
+/**
+* Validation constraints for QR-capture options.
+*
+* `intervalMs` is clamped to 50–1000 ms (20 Hz down to 1 Hz): below ~50 ms the
+* detector cannot keep up and frames just queue; above 1 s tracking feels dead.
+* `captureSize` is clamped to 256–2048 px: under 256 even a near QR loses its
+* modules; over 2048 the blit + decode cost is not worth it on a phone. Both
+* back a settings slider so a corrupt stored value can never break capture.
+*/
+const QR_CONSTRAINTS = {
+	intervalMs: {
+		min: 50,
+		max: 1e3,
+		step: 25
+	},
+	captureSize: {
+		min: 256,
+		max: 2048,
+		step: 128
+	}
+};
+/**
 * Validate and normalize AR crash isolation flags.
 * Missing or invalid values fall back to defaults.
 */
@@ -89,12 +150,43 @@ function validateArCrashIsolationOptions(options) {
 	};
 }
 /**
+* Validate and normalize the live debug-overlay visibility toggles.
+* Each field is boolean-or-default (same policy as the AR-crash-isolation
+* flags): a missing, corrupted, or pre-feature persisted value falls back to
+* the ON default so an overlay is never silently disabled by bad input.
+*/
+function validateVisualizationOptions(options) {
+	const defaults = DEFAULT_RECORDING_OPTIONS.visualization;
+	return {
+		frameTiles: typeof options.frameTiles === "boolean" ? options.frameTiles : defaults.frameTiles,
+		occupancyCubes: typeof options.occupancyCubes === "boolean" ? options.occupancyCubes : defaults.occupancyCubes,
+		gpsAlignmentMarkers: typeof options.gpsAlignmentMarkers === "boolean" ? options.gpsAlignmentMarkers : defaults.gpsAlignmentMarkers,
+		compassCubes: typeof options.compassCubes === "boolean" ? options.compassCubes : defaults.compassCubes
+	};
+}
+/**
 * Clamp a value to the specified constraints.
 */
 function clamp(value, min, max) {
 	return Math.max(min, Math.min(max, value));
 }
 /**
+* Validate and normalize QR-capture options. `enabled` is boolean-or-default
+* (a corrupt/pre-feature value falls back to the OFF default so QR never
+* silently turns ON); `intervalMs`/`captureSize` are clamped to
+* {@link QR_CONSTRAINTS}, with a `Number.isFinite` guard so a stored `NaN`
+* (which is `typeof 'number'` and survives `clamp`) falls back to the default
+* rather than breaking the camera-frame source.
+*/
+function validateQrOptions(options) {
+	const defaults = DEFAULT_RECORDING_OPTIONS.qr;
+	return {
+		enabled: typeof options.enabled === "boolean" ? options.enabled : defaults.enabled,
+		intervalMs: clamp(typeof options.intervalMs === "number" && Number.isFinite(options.intervalMs) ? options.intervalMs : defaults.intervalMs, QR_CONSTRAINTS.intervalMs.min, QR_CONSTRAINTS.intervalMs.max),
+		captureSize: clamp(typeof options.captureSize === "number" && Number.isFinite(options.captureSize) ? options.captureSize : defaults.captureSize, QR_CONSTRAINTS.captureSize.min, QR_CONSTRAINTS.captureSize.max)
+	};
+}
+/**
 * Validate and normalize depth options.
 * Invalid values are clamped to valid ranges.
 */
@@ -103,7 +195,7 @@ function validateDepthOptions(options) {
 	return {
 		enabled: typeof options.enabled === "boolean" ? options.enabled : defaults.enabled,
 		intervalMs: clamp(typeof options.intervalMs === "number" ? options.intervalMs : defaults.intervalMs, DEPTH_CONSTRAINTS.intervalMs.min, DEPTH_CONSTRAINTS.intervalMs.max),
-		gridSize: clamp(typeof options.gridSize === "number" ? options.gridSize : defaults.gridSize, DEPTH_CONSTRAINTS.gridSize.min, DEPTH_CONSTRAINTS.gridSize.max),
+		gridSize: clamp(typeof options.gridSize === "number" && Number.isFinite(options.gridSize) ? Math.round(options.gridSize) : defaults.gridSize, DEPTH_CONSTRAINTS.gridSize.min, DEPTH_CONSTRAINTS.gridSize.max),
 		rgb: typeof options.rgb === "boolean" ? options.rgb : defaults.rgb
 	};
 }
@@ -121,6 +213,30 @@ function validateImageOptions(options) {
 	};
 }
 /**
+* Validate and normalize occupancy options.
+* Invalid values are clamped to valid ranges.
+*
+* Note the explicit `Number.isFinite` guard: `OccupancyGrid` throws a
+* `RangeError` on a non-finite cell size, and `clamp(NaN, …)` would otherwise
+* pass `NaN` straight through (it is `typeof 'number'`). Falling back to the
+* default keeps a corrupted stored value from crashing grid construction.
+*/
+function validateOccupancyOptions(options) {
+	const defaults = DEFAULT_RECORDING_OPTIONS.occupancy;
+	return { cellSizeM: clamp(typeof options.cellSizeM === "number" && Number.isFinite(options.cellSizeM) ? options.cellSizeM : defaults.cellSizeM, OCCUPANCY_CONSTRAINTS.cellSizeM.min, OCCUPANCY_CONSTRAINTS.cellSizeM.max) };
+}
+/**
+* Validate and normalize frame-tile display options. `divisor` is clamped to
+* {@link FRAME_TILE_DISPLAY_CONSTRAINTS} and rounded to an integer, with a
+* `Number.isFinite` guard so a stored `NaN` (which is `typeof 'number'` and
+* survives `clamp`) falls back to the default rather than producing a broken
+* resize target.
+*/
+function validateFrameTileDisplayOptions(options) {
+	const defaults = DEFAULT_RECORDING_OPTIONS.frameTileDisplay;
+	return { divisor: clamp(typeof options.divisor === "number" && Number.isFinite(options.divisor) ? Math.round(options.divisor) : defaults.divisor, FRAME_TILE_DISPLAY_CONSTRAINTS.divisor.min, FRAME_TILE_DISPLAY_CONSTRAINTS.divisor.max) };
+}
+/**
 * Validate and normalize a full RecordingOptions object.
 * Merges with defaults and clamps invalid values.
 */
@@ -128,7 +244,11 @@ function validateRecordingOptions(options) {
 	return {
 		depth: validateDepthOptions(options.depth ?? {}),
 		images: validateImageOptions(options.images ?? {}),
-		arCrashIsolation: validateArCrashIsolationOptions(options.arCrashIsolation ?? {})
+		arCrashIsolation: validateArCrashIsolationOptions(options.arCrashIsolation ?? {}),
+		occupancy: validateOccupancyOptions(options.occupancy ?? {}),
+		frameTileDisplay: validateFrameTileDisplayOptions(options.frameTileDisplay ?? {}),
+		visualization: validateVisualizationOptions(options.visualization ?? {}),
+		qr: validateQrOptions(options.qr ?? {})
 	};
 }
 /**
@@ -187,8 +307,12 @@ function cloneRecordingOptions(options) {
 	return {
 		depth: { ...options.depth },
 		images: { ...options.images },
-		arCrashIsolation: { ...options.arCrashIsolation }
+		arCrashIsolation: { ...options.arCrashIsolation },
+		occupancy: { ...options.occupancy },
+		frameTileDisplay: { ...options.frameTileDisplay },
+		visualization: { ...options.visualization },
+		qr: { ...options.qr }
 	};
 }
 //#endregion
-export { DEFAULT_RECORDING_OPTIONS, DEPTH_CONSTRAINTS, IMAGE_CONSTRAINTS, STORAGE_KEY, cloneRecordingOptions, loadRecordingOptions, resetRecordingOptions, saveRecordingOptions, validateArCrashIsolationOptions, validateDepthOptions, validateImageOptions, validateRecordingOptions };
+export { DEFAULT_RECORDING_OPTIONS, DEPTH_CONSTRAINTS, FRAME_TILE_DISPLAY_CONSTRAINTS, IMAGE_CONSTRAINTS, OCCUPANCY_CONSTRAINTS, QR_CONSTRAINTS, STORAGE_KEY, cloneRecordingOptions, loadRecordingOptions, resetRecordingOptions, saveRecordingOptions, validateArCrashIsolationOptions, validateDepthOptions, validateFrameTileDisplayOptions, validateImageOptions, validateOccupancyOptions, validateQrOptions, validateRecordingOptions, validateVisualizationOptions };

package/dist/state/recording-replayer.d.ts

@@ -1,3 +1,3 @@
-import { L as CombinedRootState } from "../create-slam-app-store-qNXQ-tq5.js";
-import { n as replayRecording, t as ReplayRecordingOptions } from "../recording-replayer-BL-x-7k0.js";
+import { L as CombinedRootState } from "../create-slam-app-store-Ce2FMKCp.js";
+import { n as replayRecording, t as ReplayRecordingOptions } from "../recording-replayer-CUEK82tM.js";
 export { CombinedRootState, ReplayRecordingOptions, replayRecording };

package/dist/state/recording-slice.d.ts

@@ -1,2 +1,2 @@
-import { a as recordWriteFailure, i as recordDepthSample, n as SessionMetadata, o as recordingReducer, r as endSession, s as startSession, t as RecordingState } from "../recording-slice-89O07ebs.js";
+import { a as recordWriteFailure, i as recordDepthSample, n as SessionMetadata, o as recordingReducer, r as endSession, s as startSession, t as RecordingState } from "../recording-slice-B-uCgGoh.js";
 export { RecordingState, SessionMetadata, endSession, recordDepthSample, recordWriteFailure, recordingReducer, startSession };

package/dist/state/recording-slice.js

@@ -11,8 +11,12 @@ const recordingSlice = createSlice({
 	},
 	reducers: {
 		startSession(state, action) {
+			const { scenarioName, contextTag, ...rest } = action.payload;
 			state.isRecording = true;
-			state.sessionMetadata = action.payload;
+			state.sessionMetadata = {
+				...rest,
+				contextTag: contextTag ?? scenarioName ?? ""
+			};
 			state.actionCount = 0;
 			state.failedWriteCount = 0;
 			state.latestDepthSample = null;

package/dist/state/replay-engine.d.ts

@@ -1,2 +1,2 @@
-import { a as ReplayAction, c as computeInterActionDelay, i as ProgressCallback, l as extractActionTimestamp, n as DEFAULT_MAX_DELAY_MS, o as ReplayEngine, r as ErrorCallback, s as ReplayState, t as CompleteCallback } from "../replay-engine-BRqszuQ9.js";
+import { a as ReplayAction, c as computeInterActionDelay, i as ProgressCallback, l as extractActionTimestamp, n as DEFAULT_MAX_DELAY_MS, o as ReplayEngine, r as ErrorCallback, s as ReplayState, t as CompleteCallback } from "../replay-engine-BSVd7Zzb.js";
 export { CompleteCallback, DEFAULT_MAX_DELAY_MS, ErrorCallback, ProgressCallback, ReplayAction, ReplayEngine, ReplayState, computeInterActionDelay, extractActionTimestamp };

package/dist/state/replay-engine.js

@@ -7,9 +7,12 @@ const MAX_CONSECUTIVE_ERRORS = 10;
 * Extract an absolute epoch-ms timestamp from a Redux action, or null
 * if the action type doesn't carry one.
 *
-* IMPORTANT: depthSample uses performance.now() (relative to page load),
-* NOT epoch ms. Returning it here would mix clock domains and produce
-* garbage delays. It must return null. (Risk R4)
+* IMPORTANT: the high-frequency sensor streams (depthSample, qrDetected) return
+* null here ON PURPOSE — they are NOT used to pace replay delays (they anchor to
+* the GPS/image/session timeline by recorded ORDER instead). Their payload
+* `timestamp` IS epoch ms (`performance.timeOrigin + frameTs`, see
+* `ar/depth-sampler.ts`); the QR size as-of join reads those payload timestamps
+* directly, independently of this pacing function. (Risk R4)
 *
 * @param action - A Redux action with type and optional payload
 * @returns Epoch milliseconds, or null if unavailable/unreliable
@@ -37,6 +40,7 @@ function extractActionTimestamp(action) {
 			return null;
 		}
 		case "recording/recordDepthSample": return null;
+		case "qrDetected/recordQrDetection": return null;
 		case "recording/endSession": return null;
 		default: return null;
 	}

package/dist/state/store-subscribers.d.ts

@@ -1,3 +1,3 @@
-import { t as SubscribableStore } from "../subscribe-to-selector-CP3BKSbF.js";
-import { n as wireStoreSubscribers, t as StoreSubscriberDeps } from "../store-subscribers-rrkLkFTt.js";
+import { t as SubscribableStore } from "../subscribe-to-selector-Bp3sLx8L.js";
+import { n as wireStoreSubscribers, t as StoreSubscriberDeps } from "../store-subscribers-BZP81hjh.js";
 export { StoreSubscriberDeps, SubscribableStore, wireStoreSubscribers };

package/dist/state/subscribe-to-selector.d.ts

@@ -1,2 +1,2 @@
-import { n as subscribeToSelector, t as SubscribableStore } from "../subscribe-to-selector-CP3BKSbF.js";
+import { n as subscribeToSelector, t as SubscribableStore } from "../subscribe-to-selector-Bp3sLx8L.js";
 export { SubscribableStore, subscribeToSelector };

package/dist/state/tracking-quality.d.ts

@@ -1,2 +1,2 @@
-import { A as resetTrackingQuality, C as computeResidualConsensus, D as firstAgreementReached, E as degradedCountUpdated, F as snapshotsTrimmed, I as trackingQualityReducer, M as selectRecentAlignments, N as selectTrackingQuality, O as matrixDelta, P as snapshotPushed, S as computeGpsVsFusedDivergence, T as createTrackingQualityListenerMiddleware, _ as TrackingQualityState, b as computeCoverage, c as CompassAgreementResult, d as DEFAULT_TRACKING_QUALITY_OPTIONS, f as GpsAccuracyResult, g as TrackingQualitySliceState, h as TrackingQualityReport, j as selectFirstAgreementObservationIndex, k as reportUpdated, l as ConvergenceResult, m as TrackingQualityOptions, p as ResidualConsensusResult, s as AlignmentSnapshot, u as CoverageResult, v as computeCompassAgreement, w as computeTrackingQualityReport, x as computeGpsAccuracy, y as computeConvergence } from "../create-slam-app-store-qNXQ-tq5.js";
+import { A as resetTrackingQuality, C as computeResidualConsensus, D as firstAgreementReached, E as degradedCountUpdated, F as snapshotsTrimmed, I as trackingQualityReducer, M as selectRecentAlignments, N as selectTrackingQuality, O as matrixDelta, P as snapshotPushed, S as computeGpsVsFusedDivergence, T as createTrackingQualityListenerMiddleware, _ as TrackingQualityState, b as computeCoverage, c as CompassAgreementResult, d as DEFAULT_TRACKING_QUALITY_OPTIONS, f as GpsAccuracyResult, g as TrackingQualitySliceState, h as TrackingQualityReport, j as selectFirstAgreementObservationIndex, k as reportUpdated, l as ConvergenceResult, m as TrackingQualityOptions, p as ResidualConsensusResult, s as AlignmentSnapshot, u as CoverageResult, v as computeCompassAgreement, w as computeTrackingQualityReport, x as computeGpsAccuracy, y as computeConvergence } from "../create-slam-app-store-Ce2FMKCp.js";
 export { AlignmentSnapshot, CompassAgreementResult, ConvergenceResult, CoverageResult, DEFAULT_TRACKING_QUALITY_OPTIONS, GpsAccuracyResult, ResidualConsensusResult, TrackingQualityOptions, TrackingQualityReport, TrackingQualitySliceState, TrackingQualityState, computeCompassAgreement, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeResidualConsensus, computeTrackingQualityReport, createTrackingQualityListenerMiddleware, degradedCountUpdated, firstAgreementReached, matrixDelta, reportUpdated, resetTrackingQuality, selectFirstAgreementObservationIndex, selectRecentAlignments, selectTrackingQuality, snapshotPushed, snapshotsTrimmed, trackingQualityReducer };

package/dist/state/tracking-slice.d.ts

@@ -1,2 +1,2 @@
-import { a as TrackingSliceState, c as poseLost, d as selectLastRestartedPayload, f as selectLastSensorOrientation, g as trackingReducer, h as selectTrackingPhase, i as TrackingPhase, l as poseReceived, m as selectLostFrameCount, n as PoseReceivedPayload, o as clearLastRestartedPayload, p as selectLastValidPose, r as ResetTransformData, s as originReset, t as DeviceOrientation, u as resetTracking } from "../tracking-slice-CdK8c-8P.js";
+import { a as TrackingSliceState, c as poseLost, d as selectLastRestartedPayload, f as selectLastSensorOrientation, g as trackingReducer, h as selectTrackingPhase, i as TrackingPhase, l as poseReceived, m as selectLostFrameCount, n as PoseReceivedPayload, o as clearLastRestartedPayload, p as selectLastValidPose, r as ResetTransformData, s as originReset, t as DeviceOrientation, u as resetTracking } from "../tracking-slice-DJZ9qeGg.js";
 export { DeviceOrientation, PoseReceivedPayload, ResetTransformData, TrackingPhase, TrackingSliceState, clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectLastSensorOrientation, selectLastValidPose, selectLostFrameCount, selectTrackingPhase, trackingReducer };

package/dist/{state-BkIfpiyA.js → state-IEw0ZsBu.js}

@@ -2,6 +2,7 @@ import "./state/gps-event-coordinator.js";
 import "./state/tracking-slice.js";
 import "./state/recording-options.js";
 import "./state/recording-slice.js";
+import "./state/qr-detected-slice.js";
 import "./state/gps-ar-pose-sampler.js";
 import "./state/app-selectors.js";
 import { selectTrackingQuality } from "./state/tracking-quality.js";

package/dist/storage/file-system-utils.d.ts

@@ -1,2 +1,2 @@
-import { n as formatFrameFilename, r as formatTimestamp, t as formatActionFilename } from "../file-system-utils-DyAmcuvX.js";
-export { formatActionFilename, formatFrameFilename, formatTimestamp };
+import { a as formatTimestamp, i as formatFrameFilename, n as SESSION_IMAGES_DIR, r as formatActionFilename, t as LEGACY_SESSION_IMAGES_DIR } from "../file-system-utils-Bs7lpeVP.js";
+export { LEGACY_SESSION_IMAGES_DIR, SESSION_IMAGES_DIR, formatActionFilename, formatFrameFilename, formatTimestamp };