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

package/dist/state/persistence-middleware.js

@@ -77,27 +77,38 @@ function createPersistenceMiddleware(options) {
 	const excludedActionType = recordWriteFailure.type;
 	let actionIndex = 0;
 	const writeQueue = new WriteQueue();
+	let dispatchDepth = 0;
+	let hasWarnedReentrant = false;
 	const middleware = (store) => (next) => (action) => {
-		const typedAction = action;
-		const actionType = typeof typedAction.type === "string" ? typedAction.type : null;
-		const wasRecording = readIsRecording(store.getState());
-		const result = next(action);
-		if (!actionType) return result;
-		if (actionType === startSession.type) actionIndex = 0;
-		if (!isInPersistableSession(wasRecording, readIsRecording(store.getState()), actionType)) return result;
-		if (!(actionType !== excludedActionType && normalizedPrefixes.some((prefix) => actionType.startsWith(prefix)))) return result;
-		const index = ++actionIndex;
-		writeQueue.enqueue(async () => {
-			try {
-				await storageBackend.writeAction(typedAction, index);
-			} catch (err) {
-				const normalized = err instanceof Error ? err : new Error(String(err));
-				log.error("Failed to persist action:", normalized);
-				store.dispatch(recordWriteFailure(normalized.message));
-				if (onWriteFailure) onWriteFailure(normalized);
+		dispatchDepth += 1;
+		try {
+			const typedAction = action;
+			const actionType = typeof typedAction.type === "string" ? typedAction.type : null;
+			const wasRecording = readIsRecording(store.getState());
+			const result = next(action);
+			if (!actionType) return result;
+			if (actionType === startSession.type) actionIndex = 0;
+			if (!isInPersistableSession(wasRecording, readIsRecording(store.getState()), actionType)) return result;
+			if (!(actionType !== excludedActionType && normalizedPrefixes.some((prefix) => actionType.startsWith(prefix)))) return result;
+			const index = ++actionIndex;
+			if (dispatchDepth > 1 && !hasWarnedReentrant) {
+				hasWarnedReentrant = true;
+				log.warn(`Persisted action "${actionType}" was dispatched re-entrantly (inside another dispatch's next()). Its recorded order can invert on replay — react to actions via a prepended listener middleware, not a synchronous store.subscribe dispatch. See 2026-06-28-subscriber-dispatch-persistence-ordering-review.md.`);
 			}
-		});
-		return result;
+			writeQueue.enqueue(async () => {
+				try {
+					await storageBackend.writeAction(typedAction, index);
+				} catch (err) {
+					const normalized = err instanceof Error ? err : new Error(String(err));
+					log.error("Failed to persist action:", normalized);
+					store.dispatch(recordWriteFailure(normalized.message));
+					if (onWriteFailure) onWriteFailure(normalized);
+				}
+			});
+			return result;
+		} finally {
+			dispatchDepth -= 1;
+		}
 	};
 	return middleware;
 }

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

@@ -0,0 +1,4 @@
+import { d as QrSizeStatus, l as QrSizeEstimate } from "../qr-size-measurer-DQdAsid1.js";
+import { a as QrPoseStability, o as QrPoseStabilityOptions, s as QrPoseStabilityStatus } from "../qr-pose-aggregation-B7tWJq7j.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-VQssZmQJ.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-DBiaLW0O.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 { A as validateOccupancyOptions, C as saveRecordingOptions, D as validateFrameTileDisplayOptions, E as validateDepthOptions, M as validateQualityFilterOptions, N as validateRecordingOptions, O as validateImageOptions, P as validateVisualizationOptions, S as resetRecordingOptions, T as validateCompassDebugOptions, _ as RecordingOptionsInput, a as DepthCaptureOptions, b as cloneRecordingOptions, c as IMAGE_CONSTRAINTS, d as OCCUPANCY_CONSTRAINTS, f as OccupancyOptions, g as RecordingOptions, h as QrCaptureOptions, i as DEPTH_CONSTRAINTS, j as validateQrOptions, k as validateMotionFilterOptions, l as ImageCaptureOptions, m as QUALITY_FILTER_CONSTRAINTS, n as CompassDebugOptions, o as FRAME_TILE_DISPLAY_CONSTRAINTS, p as QR_CONSTRAINTS, r as DEFAULT_RECORDING_OPTIONS, s as FrameTileDisplayOptions, t as ArCrashIsolationOptions, u as MOTION_FILTER_CONSTRAINTS, v as STORAGE_KEY, w as validateArCrashIsolationOptions, x as loadRecordingOptions, y as VisualizationOptions } from "../recording-options-BPCpMHLK.js";
+export { ArCrashIsolationOptions, CompassDebugOptions, DEFAULT_RECORDING_OPTIONS, DEPTH_CONSTRAINTS, DepthCaptureOptions, FRAME_TILE_DISPLAY_CONSTRAINTS, FrameTileDisplayOptions, IMAGE_CONSTRAINTS, ImageCaptureOptions, MOTION_FILTER_CONSTRAINTS, OCCUPANCY_CONSTRAINTS, OccupancyOptions, QR_CONSTRAINTS, QUALITY_FILTER_CONSTRAINTS, QrCaptureOptions, RecordingOptions, RecordingOptionsInput, STORAGE_KEY, VisualizationOptions, cloneRecordingOptions, loadRecordingOptions, resetRecordingOptions, saveRecordingOptions, validateArCrashIsolationOptions, validateCompassDebugOptions, validateDepthOptions, validateFrameTileDisplayOptions, validateImageOptions, validateMotionFilterOptions, validateOccupancyOptions, validateQrOptions, validateQualityFilterOptions, validateRecordingOptions, validateVisualizationOptions };