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

package/dist/state/tracking-quality.js

@@ -1,4 +1,5 @@
-import { selectLastSensorOrientation, selectLastValidPose, selectTrackingPhase } from "./tracking-slice.js";
+import { t as geodesicAngleRad } from "../geodesic-angle-BTldfFgs.js";
+import { selectTrackingPhase } from "./tracking-slice.js";
 import { selectAlignmentMatrix, selectGpsPositions, selectOdometryPositions, selectZeroReference } from "./app-selectors.js";
 import { calcGpsCoords, distanceInMeters } from "gps-plus-slam-js";
 import { mat4, quat, vec3 } from "gl-matrix";
@@ -13,19 +14,15 @@ const DEFAULT_TRACKING_QUALITY_OPTIONS = {
 	coverageDirectionSpreadDeg: 90,
 	convergenceRotationWarnDeg: 6,
 	convergenceTranslationWarnM: 2,
-	compassWarnDeg: 15,
-	compassFailDeg: 35,
 	warmupMinObservations: 10,
 	warmupMinCoverage: .5,
 	residualConfidenceTargetM: 3,
 	gpsAccuracyFloorM: 1,
-	firstAgreementMinStreak: 3,
 	degradedHoldoff: 3,
 	convergenceEmaAlpha: .3
 };
 const initialState = {
 	recentAlignments: [],
-	firstAgreementObservationIndex: null,
 	report: null,
 	degradedConsecutiveCount: 0,
 	smoothedConvergence: null
@@ -47,11 +44,6 @@ function emaBlend(prev, raw, alpha) {
 	if (prev === null) return raw;
 	return prev + (Number.isFinite(alpha) ? alpha : 1) * (raw - prev);
 }
-function wrapToHalfCircle(deg) {
-	let d = (deg + 180) % 360 - 180;
-	if (d < -180) d += 360;
-	return d;
-}
 function bearingDeg(north, east) {
 	let deg = Math.atan2(east, north) * 180 / Math.PI;
 	if (deg < 0) deg += 360;
@@ -87,6 +79,11 @@ function rampUp(value, low, high) {
 	if (value >= high) return 1;
 	return (value - low) / (high - low);
 }
+/** True iff every element of the matrix is a finite number (no NaN/Infinity). */
+function isFiniteMatrix(m) {
+	for (let i = 0; i < m.length; i++) if (!Number.isFinite(m[i])) return false;
+	return true;
+}
 /**
 * §4.1 matrix-history convergence over the buffered snapshots.
 *
@@ -118,7 +115,15 @@ function computeConvergence(snapshots, options = {}) {
 	let sumTransM = 0;
 	let pairCount = 0;
 	for (let i = 1; i < snapshots.length; i++) {
-		const { rotationDeltaDeg, translationDeltaM } = matrixDelta(snapshots[i - 1].matrix, snapshots[i].matrix);
+		const prevM = snapshots[i - 1].matrix;
+		const currM = snapshots[i].matrix;
+		if (!isFiniteMatrix(prevM) || !isFiniteMatrix(currM)) {
+			sumRotDeg += rotFail;
+			sumTransM += transFail;
+			pairCount += 1;
+			continue;
+		}
+		const { rotationDeltaDeg, translationDeltaM } = matrixDelta(prevM, currM);
 		sumRotDeg += Math.abs(rotationDeltaDeg);
 		sumTransM += Math.abs(translationDeltaM);
 		pairCount += 1;
@@ -137,7 +142,8 @@ function computeConvergence(snapshots, options = {}) {
 * the column-major layout that gl-matrix and the framework use.
 *
 * Rotation: extract the orientation quaternion with `mat4.getRotation`
-* and compute the relative angle via `quat.getAngle` (degrees).
+* and compute the relative angle via the shared `geodesicAngleRad` kernel
+* (radians, converted to degrees here).
 * Translation: extract the origin column with `mat4.getTranslation` and
 * compute the Euclidean distance.
 *
@@ -161,15 +167,16 @@ function matrixDelta(prev, curr) {
 	mat4.getRotation(currQuat, currMat);
 	quat.normalize(prevQuat, prevQuat);
 	quat.normalize(currQuat, currQuat);
-	const angleRad = quat.getAngle(prevQuat, currQuat);
-	const rotationDeltaDeg = Number.isNaN(angleRad) ? 0 : angleRad * 180 / Math.PI;
+	const angleRad = geodesicAngleRad(prevQuat, currQuat);
+	const rotationDeltaDeg = Number.isFinite(angleRad) ? angleRad * 180 / Math.PI : 0;
 	const prevT = vec3.create();
 	const currT = vec3.create();
 	mat4.getTranslation(prevT, prevMat);
 	mat4.getTranslation(currT, currMat);
+	const rawTranslation = vec3.distance(prevT, currT);
 	return {
 		rotationDeltaDeg,
-		translationDeltaM: vec3.distance(prevT, currT)
+		translationDeltaM: Number.isFinite(rawTranslation) ? rawTranslation : 0
 	};
 }
 /**
@@ -319,56 +326,6 @@ function computeCoverage(odometryPositions, options = {}) {
 	};
 }
 /**
-* §4.3 — Compare the alignment matrix's mapping of AR-forward to ENU
-* against the device compass heading. Returns `score = null` whenever
-* the sensor's `absolute !== true` so the aggregate excludes the
-* sub-score (per Q2 in the plan).
-*
-* AR-forward in our `ARPose` convention is `(0, 0, -1)` (right-handed,
-* Y-up). We rotate that by the alignment's 3×3 rotation, take its
-* North/East components, and compare against the compass alpha.
-*/
-function computeCompassAgreement(alignmentMatrix, sensorOrientation, arPose, options = {}) {
-	const warn = options.warnDeg ?? DEFAULT_TRACKING_QUALITY_OPTIONS.compassWarnDeg;
-	const fail = options.failDeg ?? DEFAULT_TRACKING_QUALITY_OPTIONS.compassFailDeg;
-	if (!alignmentMatrix || !sensorOrientation || !arPose) return {
-		score: null,
-		headingDeltaDeg: null
-	};
-	if (sensorOrientation.absolute !== true) return {
-		score: null,
-		headingDeltaDeg: null
-	};
-	const q = arPose.orientation;
-	const fx = 0;
-	const fy = 0;
-	const fz = -1;
-	const x = q.x, y = q.y, z = q.z, w = q.w;
-	const tx = 2 * (y * fz - z * fy);
-	const ty = 2 * (z * fx - x * fz);
-	const tz = 2 * (x * fy - y * fx);
-	const arForwardLocal = [
-		fx + w * tx + (y * tz - z * ty),
-		fy + w * ty + (z * tx - x * tz),
-		fz + w * tz + (x * ty - y * tx)
-	];
-	const m = alignmentMatrix;
-	const enuN = m[0] * arForwardLocal[0] + m[4] * arForwardLocal[1] + m[8] * arForwardLocal[2];
-	m[1] * arForwardLocal[0] + m[5] * arForwardLocal[1] + m[9] * arForwardLocal[2];
-	const enuE = m[2] * arForwardLocal[0] + m[6] * arForwardLocal[1] + m[10] * arForwardLocal[2];
-	if (Math.hypot(enuN, enuE) < 1e-6) return {
-		score: null,
-		headingDeltaDeg: null
-	};
-	const alignmentHeadingDeg = bearingDeg(enuN, enuE);
-	const compassHeadingDeg = sensorOrientation.alpha;
-	const delta = Math.abs(wrapToHalfCircle(alignmentHeadingDeg - compassHeadingDeg));
-	return {
-		score: rampDown(delta, warn, fail),
-		headingDeltaDeg: delta
-	};
-}
-/**
 * §4.6 — Maximum lateral distance between raw GPS positions and the
 * positions you would predict by transforming the matching odometry
 * positions through the current alignment. Diagnostic only — never
@@ -418,9 +375,6 @@ const trackingQualitySlice = createSlice({
 		reportUpdated(state, action) {
 			state.report = action.payload;
 		},
-		firstAgreementReached(state, action) {
-			state.firstAgreementObservationIndex = action.payload;
-		},
 		/** §4.8 — update the hysteresis counter for ok → degraded holdoff. */
 		degradedCountUpdated(state, action) {
 			state.degradedConsecutiveCount = action.payload;
@@ -439,7 +393,7 @@ const trackingQualitySlice = createSlice({
 		}
 	}
 });
-const { snapshotPushed, snapshotsTrimmed, reportUpdated, firstAgreementReached, degradedCountUpdated, resetTrackingQuality } = trackingQualitySlice.actions;
+const { snapshotPushed, snapshotsTrimmed, reportUpdated, degradedCountUpdated, resetTrackingQuality } = trackingQualitySlice.actions;
 const { smoothedConvergenceUpdated } = trackingQualitySlice.actions;
 const trackingQualityReducer = trackingQualitySlice.reducer;
 function selectTrackingQuality(state) {
@@ -448,9 +402,6 @@ function selectTrackingQuality(state) {
 function selectRecentAlignments(state) {
 	return state.trackingQuality?.recentAlignments ?? EMPTY_SNAPSHOTS;
 }
-function selectFirstAgreementObservationIndex(state) {
-	return state.trackingQuality?.firstAgreementObservationIndex ?? null;
-}
 const EMPTY_SNAPSHOTS = Object.freeze([]);
 /**
 * Pure function — produces a {@link TrackingQualityReport} from a root
@@ -474,10 +425,7 @@ function computeTrackingQualityReport(rootState, options = {}) {
 	const odometryPositions = selectOdometryPositions(rootState);
 	const zeroRef = selectZeroReference(rootState);
 	const trackingPhase = selectTrackingPhase(rootState);
-	const sensorOrientation = selectLastSensorOrientation(rootState);
-	const lastPose = selectLastValidPose(rootState);
 	const snapshots = selectRecentAlignments(rootState);
-	const firstAgreementIdx = selectFirstAgreementObservationIndex(rootState);
 	const coverage = computeCoverage(odometryPositions, {
 		walkedDistanceM: opts.coverageWalkedDistanceM,
 		directionSpreadDeg: opts.coverageDirectionSpreadDeg
@@ -492,15 +440,10 @@ function computeTrackingQualityReport(rootState, options = {}) {
 		rotationWarnDeg: opts.convergenceRotationWarnDeg,
 		translationWarnM: opts.convergenceTranslationWarnM
 	});
-	const compass = computeCompassAgreement(alignmentMatrix, sensorOrientation, lastPose, {
-		warnDeg: opts.compassWarnDeg,
-		failDeg: opts.compassFailDeg
-	});
 	const gpsVsFusedMaxDivergenceM = computeGpsVsFusedDivergence(alignmentMatrix, gpsPositions, odometryPositions, zeroRef);
 	const subScores = {
 		convergence: clamp01(emaBlend(rootState.trackingQuality?.smoothedConvergence ?? null, convergence.score, opts.convergenceEmaAlpha)),
 		residualConsensus: clamp01(residual.score),
-		compassAgreement: compass.score === null ? null : clamp01(compass.score),
 		gpsAccuracy: clamp01(gpsAccuracy.score),
 		coverage: clamp01(coverage.score)
 	};
@@ -510,7 +453,6 @@ function computeTrackingQualityReport(rootState, options = {}) {
 		subScores.gpsAccuracy,
 		subScores.coverage
 	];
-	if (subScores.compassAgreement !== null) aggregateInputs.push(subScores.compassAgreement);
 	const confidence = clamp01(Math.min(...aggregateInputs));
 	const observationsSeen = gpsPositions.length;
 	let state;
@@ -529,8 +471,6 @@ function computeTrackingQualityReport(rootState, options = {}) {
 			medianRecentGpsAccuracyM: gpsAccuracy.medianM,
 			walkedDistanceM: coverage.walkedDistanceM,
 			directionSpreadDeg: coverage.directionSpreadDeg,
-			headingDeltaDeg: compass.headingDeltaDeg,
-			compassDriftDetected: firstAgreementIdx !== null && compass.headingDeltaDeg !== null && compass.headingDeltaDeg > opts.compassWarnDeg,
 			observationsSeen,
 			gpsVsFusedMaxDivergenceM
 		}
@@ -540,15 +480,14 @@ function computeTrackingQualityReport(rootState, options = {}) {
 * Per-field tolerances for the {@link reportsEqual} dispatch gate.
 *
 * Why this exists: `tracking/poseReceived` fires on *every* XR frame
-* (30–60 fps). The §4.3 compass cross-check consumes the live AR pose
-* and sensor heading, so `subScores.compassAgreement` and
-* `diagnostics.headingDeltaDeg` (and, when compass is the minimum,
-* `confidence`) jitter by imperceptible floating-point amounts on a
-* held-still device. With a strict `!==` comparison every such frame
-* produced a fresh `reportUpdated` dispatch → high Redux churn and a
-* HUD re-render at frame rate. The tolerances below quantise those
-* sub-perceptual changes so the gate only fires when the user-visible
-* quality actually moved.
+* (30–60 fps). The per-frame recompute reuses GPS/odometry windows that
+* are unchanged between pose frames, so the float sub-scores and
+* diagnostics (and `confidence`) jitter by imperceptible floating-point
+* amounts on a held-still device. With a strict `!==` comparison every
+* such frame produced a fresh `reportUpdated` dispatch → high Redux
+* churn and a HUD re-render at frame rate. The tolerances below quantise
+* those sub-perceptual changes so the gate only fires when the
+* user-visible quality actually moved.
 *
 * The gate compares the freshly computed report against the *last
 * dispatched* report (the stored `prev`), not against the previous
@@ -567,10 +506,9 @@ const REPORT_METRE_EPSILON_M = .001;
 * (both `null` ⇒ equal; exactly one `null` ⇒ different) and otherwise
 * compares with an absolute epsilon. Non-finite values are compared with
 * {@link Object.is}, so a genuine finite↔NaN/Infinity transition still
-* fires a dispatch, but a *persistently* NaN diagnostic (the only
-* unguarded path is a NaN compass `alpha` leaking into
-* `diagnostics.headingDeltaDeg`) does NOT churn the gate every frame —
-* `Object.is(NaN, NaN)` is `true` whereas `NaN === NaN` is `false`.
+* fires a dispatch, but a *persistently* NaN diagnostic does NOT churn
+* the gate every frame — `Object.is(NaN, NaN)` is `true` whereas
+* `NaN === NaN` is `false`.
 */
 function nearlyEqual(a, b, eps) {
 	if (a === null || b === null) return a === b;
@@ -585,8 +523,8 @@ function nearlyEqual(a, b, eps) {
 *
 * Float fields use the per-field tolerances above
 * ({@link REPORT_SCORE_EPSILON} et al.) so imperceptible per-frame
-* compass jitter does not churn the store — see the constants' doc
-* comment for the rationale.
+* jitter does not churn the store — see the constants' doc comment for
+* the rationale.
 */
 function reportsEqual(a, b) {
 	if (a === b) return true;
@@ -595,10 +533,10 @@ function reportsEqual(a, b) {
 	if (!nearlyEqual(a.confidence, b.confidence, REPORT_SCORE_EPSILON)) return false;
 	const sa = a.subScores;
 	const sb = b.subScores;
-	if (!nearlyEqual(sa.convergence, sb.convergence, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.residualConsensus, sb.residualConsensus, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.compassAgreement, sb.compassAgreement, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.gpsAccuracy, sb.gpsAccuracy, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.coverage, sb.coverage, REPORT_SCORE_EPSILON)) return false;
+	if (!nearlyEqual(sa.convergence, sb.convergence, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.residualConsensus, sb.residualConsensus, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.gpsAccuracy, sb.gpsAccuracy, REPORT_SCORE_EPSILON) || !nearlyEqual(sa.coverage, sb.coverage, REPORT_SCORE_EPSILON)) return false;
 	const da = a.diagnostics;
 	const db = b.diagnostics;
-	return da.compassDriftDetected === db.compassDriftDetected && da.observationsSeen === db.observationsSeen && nearlyEqual(da.recentSumRotationDeltaDeg, db.recentSumRotationDeltaDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.directionSpreadDeg, db.directionSpreadDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.headingDeltaDeg, db.headingDeltaDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.recentSumTranslationDeltaM, db.recentSumTranslationDeltaM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.medianResidualM, db.medianResidualM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.medianRecentGpsAccuracyM, db.medianRecentGpsAccuracyM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.walkedDistanceM, db.walkedDistanceM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.gpsVsFusedMaxDivergenceM, db.gpsVsFusedMaxDivergenceM, REPORT_METRE_EPSILON_M);
+	return da.observationsSeen === db.observationsSeen && nearlyEqual(da.recentSumRotationDeltaDeg, db.recentSumRotationDeltaDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.directionSpreadDeg, db.directionSpreadDeg, REPORT_ANGLE_EPSILON_DEG) && nearlyEqual(da.recentSumTranslationDeltaM, db.recentSumTranslationDeltaM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.medianResidualM, db.medianResidualM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.medianRecentGpsAccuracyM, db.medianRecentGpsAccuracyM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.walkedDistanceM, db.walkedDistanceM, REPORT_METRE_EPSILON_M) && nearlyEqual(da.gpsVsFusedMaxDivergenceM, db.gpsVsFusedMaxDivergenceM, REPORT_METRE_EPSILON_M);
 }
 function matricesNearlyEqual(a, b) {
 	if (a.length !== b.length) return false;
@@ -650,16 +588,14 @@ function createTrackingQualityListenerMiddleware(options = {}) {
 		...DEFAULT_TRACKING_QUALITY_OPTIONS,
 		...options
 	};
-	let compassStreak = 0;
 	const listenerMiddleware = createListenerMiddleware();
 	listenerMiddleware.startListening({
 		predicate: (action) => inputActionPredicate(action),
 		effect: (action, api) => {
 			const state = api.getState();
 			if (action.type === TRACKING_QUALITY_INPUT_ACTIONS.startSession || action.type === TRACKING_QUALITY_INPUT_ACTIONS.resetTracking) {
-				compassStreak = 0;
 				const tq = state.trackingQuality;
-				if (tq && (tq.recentAlignments.length > 0 || tq.firstAgreementObservationIndex !== null || tq.report !== null || tq.degradedConsecutiveCount > 0)) api.dispatch(resetTrackingQuality());
+				if (tq && (tq.recentAlignments.length > 0 || tq.report !== null || tq.degradedConsecutiveCount > 0)) api.dispatch(resetTrackingQuality());
 				return;
 			}
 			if (action.type === TRACKING_QUALITY_INPUT_ACTIONS.gpsRecorded || action.type === TRACKING_QUALITY_INPUT_ACTIONS.setZeroPos) {
@@ -678,30 +614,6 @@ function createTrackingQualityListenerMiddleware(options = {}) {
 					}
 				}
 			}
-			const midState = api.getState();
-			const midTq = midState.trackingQuality;
-			if (midTq && midTq.firstAgreementObservationIndex === null) {
-				const snapshots = selectRecentAlignments(midState);
-				if (snapshots.length >= 2) {
-					const conv = computeConvergence(snapshots, {
-						rotationWarnDeg: opts.convergenceRotationWarnDeg,
-						translationWarnM: opts.convergenceTranslationWarnM
-					});
-					const sensorOr = selectLastSensorOrientation(midState);
-					const pose = selectLastValidPose(midState);
-					const compass = computeCompassAgreement(selectAlignmentMatrix(midState), sensorOr, pose, {
-						warnDeg: opts.compassWarnDeg,
-						failDeg: opts.compassFailDeg
-					});
-					if (conv.score >= .7 && compass.headingDeltaDeg !== null && compass.headingDeltaDeg <= opts.compassWarnDeg) {
-						compassStreak += 1;
-						if (compassStreak >= opts.firstAgreementMinStreak) {
-							const obsCount = selectGpsPositions(midState).length;
-							api.dispatch(firstAgreementReached(obsCount));
-						}
-					} else compassStreak = 0;
-				}
-			}
 			const next = api.getState();
 			const report = computeTrackingQualityReport(next, opts);
 			const prev = next.trackingQuality?.report ?? null;
@@ -720,4 +632,4 @@ function createTrackingQualityListenerMiddleware(options = {}) {
 	return listenerMiddleware.middleware;
 }
 //#endregion
-export { DEFAULT_TRACKING_QUALITY_OPTIONS, computeCompassAgreement, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeResidualConsensus, computeTrackingQualityReport, createTrackingQualityListenerMiddleware, degradedCountUpdated, firstAgreementReached, matrixDelta, reportUpdated, resetTrackingQuality, selectFirstAgreementObservationIndex, selectRecentAlignments, selectTrackingQuality, snapshotPushed, snapshotsTrimmed, trackingQualityReducer };
+export { DEFAULT_TRACKING_QUALITY_OPTIONS, computeConvergence, computeCoverage, computeGpsAccuracy, computeGpsVsFusedDivergence, computeResidualConsensus, computeTrackingQualityReport, createTrackingQualityListenerMiddleware, degradedCountUpdated, matrixDelta, reportUpdated, resetTrackingQuality, 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-BuAZxXZ5.js";
 export { DeviceOrientation, PoseReceivedPayload, ResetTransformData, TrackingPhase, TrackingSliceState, clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectLastSensorOrientation, selectLastValidPose, selectLostFrameCount, selectTrackingPhase, trackingReducer };

package/dist/{state-BkIfpiyA.js → state-E51QT_-j.js}

@@ -2,11 +2,12 @@ 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";
 import "./state/persistence-middleware.js";
-import "./state/create-slam-app-store.js";
+import "./create-slam-app-store-DkCHOpvb.js";
 import "./state/recording-replayer.js";
 import "./state/store-subscribers.js";
 import { add2dImage, calcRelativeCoordsInMeters, recordGpsEvent as recordGpsEvent$1, setZeroPos as setZeroPos$1 } from "gps-plus-slam-js";

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

@@ -1,2 +1,2 @@
-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-CXIoL-DM.js";
+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-DOajnMm-.js";
 export { LEGACY_SESSION_IMAGES_DIR, SESSION_IMAGES_DIR, formatActionFilename, formatFrameFilename, formatTimestamp };

package/dist/storage/index.d.ts

@@ -1,9 +1,9 @@
-import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, h as writeSessionMetadata$1, i as createSession, l as listSessions, n as SessionMetadata, o as getSessionHandle, r as checkStorageQuota, s as getSessionsRootHandle, u as resetOpfsStorage } from "../opfs-storage-D5zAn_lx.js";
-import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-Do6YDpNo.js";
-import { a as ZipActionEntry, c as loadEntriesFromSubdir, d as loadSessionMetadataFromBlob, f as readZipEntries, i as RecordedAction, l as loadGpsPathFromBlob, n as GpsPathCoord, o as ZipSubdirEntry, r as MAX_ACTION_FILE_SIZE, s as loadActionsFromZip, t as Entry, u as loadSessionMetadata } from "../zip-reader-DSEXt7K6.js";
-import { t as NullStorageBackend } from "../null-storage-backend-uKQE8tl7.js";
-import { t as OpfsStorageBackend } from "../opfs-storage-backend-6aYMUZlJ.js";
-import { a as getCurrentScenarioHandle, c as resetForNewSession, d as startSession, f as verifyWriteAccess, h as writeSessionMetadata, i as ensureScenarioDirectory, l as resetStorageState, m as writeFrame, n as WriteAccessResult, o as initStorage, p as writeAction, s as listSessions$1, u as setCurrentScenario } from "../file-system-CwXTNHmB.js";
-import { a as formatTimestamp, i as formatFrameFilename, r as formatActionFilename } from "../file-system-utils-CXIoL-DM.js";
-import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportAndDownloadSession, r as ZipExportContributor, s as exportSessionAsZip, t as ExportSessionAsZipOptions } from "../zip-export-G14hkSPG.js";
-export { type CreateSessionResult, type Entry, type ExportSessionAsZipOptions, type GpsPathCoord, MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, type RecordedAction, type SessionMetadata, type StorageBackend, type WriteAccessResult, type ZipActionEntry, type ZipContributorAddFile, type ZipExportContributor, type ZipExportResult, type ZipSubdirEntry, checkStorageQuota, createSession, downloadZip, ensureScenarioDirectory, exportAndDownloadSession, exportSessionAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getCurrentScenarioHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, initStorage, listSessions, listSessions$1 as listSessionsFromFileSystem, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetForNewSession, resetOpfsStorage, resetSessionHandles, resetStorageState, setCurrentScenario, startSession as startStorageSession, syncToExternalZip, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata as writeSessionMeta, writeSessionMetadata$1 as writeSessionMetadata };
+import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, h as writeSessionMetadata, i as createSession, l as listSessions, n as SessionMetadata, o as getSessionHandle, r as checkStorageQuota, s as getSessionsRootHandle, u as resetOpfsStorage } from "../opfs-storage-3VZh-qH6.js";
+import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-BdVLD0dU.js";
+import { a as ZipActionEntry, c as loadEntriesFromSubdir, d as loadSessionMetadataFromBlob, f as readZipEntries, i as RecordedAction, l as loadGpsPathFromBlob, n as GpsPathCoord, o as ZipSubdirEntry, r as MAX_ACTION_FILE_SIZE, s as loadActionsFromZip, t as Entry, u as loadSessionMetadata } from "../zip-reader-D9iPQwdQ.js";
+import { t as NullStorageBackend } from "../null-storage-backend-B9rtyDfG.js";
+import { t as OpfsStorageBackend } from "../opfs-storage-backend-JJiUJo-3.js";
+import { a as formatTimestamp, i as formatFrameFilename, r as formatActionFilename } from "../file-system-utils-DOajnMm-.js";
+import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportSessionAsZip, r as ZipExportContributor, s as exportSessionHandleAsZip, t as ExportSessionAsZipOptions } from "../zip-export-ol0S_Ofd.js";
+import { t as embedCoverageInSessionJson } from "../zip-coverage-embed-DCAREVmw.js";
+export { type CreateSessionResult, type Entry, type ExportSessionAsZipOptions, type GpsPathCoord, MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, type RecordedAction, type SessionMetadata, type StorageBackend, type ZipActionEntry, type ZipContributorAddFile, type ZipExportContributor, type ZipExportResult, type ZipSubdirEntry, checkStorageQuota, createSession, downloadZip, embedCoverageInSessionJson, exportSessionAsZip, exportSessionHandleAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetOpfsStorage, resetSessionHandles, syncToExternalZip, writeSessionMetadata };

package/dist/storage/index.js

@@ -1,8 +1,8 @@
 import { MAX_ACTION_FILE_SIZE, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries } from "./zip-reader.js";
 import { formatActionFilename, formatFrameFilename, formatTimestamp } from "./file-system-utils.js";
 import { NullStorageBackend } from "./null-storage-backend.js";
-import { checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, writeSessionMetadata as writeSessionMetadata$1 } from "./opfs-storage.js";
-import { ensureScenarioDirectory, getCurrentScenarioHandle, initStorage, listSessions as listSessions$1, resetForNewSession, resetStorageState, setCurrentScenario, startSession, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata } from "./file-system.js";
+import { checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, writeSessionMetadata } from "./opfs-storage.js";
 import { OpfsStorageBackend } from "./opfs-storage-backend.js";
-import { downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip } from "./zip-export.js";
-export { MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, checkStorageQuota, createSession, downloadZip, ensureScenarioDirectory, exportAndDownloadSession, exportSessionAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getCurrentScenarioHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, initStorage, listSessions, listSessions$1 as listSessionsFromFileSystem, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetForNewSession, resetOpfsStorage, resetSessionHandles, resetStorageState, setCurrentScenario, startSession as startStorageSession, syncToExternalZip, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata as writeSessionMeta, writeSessionMetadata$1 as writeSessionMetadata };
+import { downloadZip, exportSessionAsZip, exportSessionHandleAsZip, syncToExternalZip } from "./zip-export.js";
+import { embedCoverageInSessionJson } from "./zip-coverage-embed.js";
+export { MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, checkStorageQuota, createSession, downloadZip, embedCoverageInSessionJson, exportSessionAsZip, exportSessionHandleAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetOpfsStorage, resetSessionHandles, syncToExternalZip, writeSessionMetadata };

package/dist/storage/null-storage-backend.d.ts

@@ -1,2 +1,2 @@
-import { t as NullStorageBackend } from "../null-storage-backend-uKQE8tl7.js";
+import { t as NullStorageBackend } from "../null-storage-backend-B9rtyDfG.js";
 export { NullStorageBackend };

package/dist/storage/opfs-storage-backend.d.ts

@@ -1,2 +1,2 @@
-import { t as OpfsStorageBackend } from "../opfs-storage-backend-6aYMUZlJ.js";
+import { t as OpfsStorageBackend } from "../opfs-storage-backend-JJiUJo-3.js";
 export { OpfsStorageBackend };

package/dist/storage/opfs-storage-backend.js

@@ -1,8 +1,8 @@
-import { listSessions, startSession, writeAction, writeFrame, writeSessionMetadata } from "./file-system.js";
+import { createSession, listSessions, writeAction, writeFrame, writeSessionMetadata } from "./opfs-storage.js";
 //#region ../src/storage/opfs-storage-backend.ts
 var OpfsStorageBackend = class {
-	async createSession(_timestamp, _contextTag) {
-		return { sessionName: (await startSession()).sessionPath };
+	async createSession(timestamp, _contextTag) {
+		return { sessionName: (await createSession(timestamp)).sessionName };
 	}
 	async listSessions() {
 		return listSessions();

package/dist/storage/opfs-storage.d.ts

@@ -1,2 +1,2 @@
-import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, f as setSessionHandles, h as writeSessionMetadata, i as createSession, l as listSessions, m as writeFrame, n as SessionMetadata, o as getSessionHandle, p as writeAction, r as checkStorageQuota, s as getSessionsRootHandle, t as CreateSessionResult, u as resetOpfsStorage } from "../opfs-storage-D5zAn_lx.js";
+import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, f as setSessionHandles, h as writeSessionMetadata, i as createSession, l as listSessions, m as writeFrame, n as SessionMetadata, o as getSessionHandle, p as writeAction, r as checkStorageQuota, s as getSessionsRootHandle, t as CreateSessionResult, u as resetOpfsStorage } from "../opfs-storage-3VZh-qH6.js";
 export { CreateSessionResult, SessionMetadata, checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, setSessionHandles, writeAction, writeFrame, writeSessionMetadata };

package/dist/storage/opfs-storage.js

@@ -121,10 +121,11 @@ function getSessionHandle() {
 /**
 * Set the active session handles externally.
 *
-* Used by file-system.ts's scenario-based path to reuse opfs-storage's
-* write infrastructure for sessions created outside the flat layout.
-* This is a temporary bridge until the recorder migrates to
-* ScenarioWrappingStorageBackend.
+* Lets a wrapping StorageBackend that creates sessions outside the flat layout
+* (e.g. the recorder's `ScenarioWrappingStorageBackend`, which nests sessions
+* under a named bucket) reuse opfs-storage's write infrastructure: it creates
+* the session directory itself, then hands the handles here so subsequent
+* `writeAction` / `writeFrame` / `writeSessionMetadata` calls target them.
 *
 * @internal
 */

package/dist/storage/storage-backend.d.ts

@@ -1,2 +1,2 @@
-import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-Do6YDpNo.js";
+import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-BdVLD0dU.js";
 export { CreateSessionResult, StorageBackend };

package/dist/storage/zip-coverage-embed.d.ts

@@ -0,0 +1,2 @@
+import { t as embedCoverageInSessionJson } from "../zip-coverage-embed-DCAREVmw.js";
+export { embedCoverageInSessionJson };

package/dist/storage/zip-coverage-embed.js

@@ -0,0 +1,88 @@
+import { createLogger } from "../utils/logger.js";
+import { BlobReader, BlobWriter, TextReader, TextWriter, Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.js/zip.js";
+//#region ../src/storage/zip-coverage-embed.ts
+/**
+* Zip Coverage Embed — write a recording's H3 coverage into its `session.json`.
+*
+* The map-centric browser indexes legacy recordings (those predating the
+* `h3Cells` field) by reading their full GPS path — slow, and repeated on every
+* folder open. This primitive lets a one-time "upgrade" embed the derived
+* coverage **inside the recording's own `session.json`**, so the recording
+* indexes instantly on every future open in this app *and any other reader*
+* (the portability the user asked for; O3 — in-zip rewrite).
+*
+* It is a pure transform `(zip, cells, resolution) -> zip`: it reads every entry
+* and re-emits a new zip identical to the input except that `session.json` gains
+* `h3Cells` + `h3Resolution`. It never mutates anything in place — the caller
+* (the RecorderApp backfill) owns the safe write-then-verify-then-overwrite
+* protocol around it.
+*
+* @see ./zip-coverage-embed.ts.md
+* @see GpsPlusSlamJs_Docs/docs/2026-06-14-followup-progressive-map-browser-indexing-and-backfill.md (B3)
+*/
+const log = createLogger("ZipCoverageEmbed");
+/**
+* Return a new zip blob identical to `zip` except its `session.json` gains
+* `h3Cells` + `h3Resolution`.
+*
+* **Skips (returns the input blob unchanged, by reference) when:**
+*   - the zip has no `session.json` (nothing to embed into);
+*   - `session.json` is present but unparseable (never write over a broken one);
+*   - `session.json` already carries `h3Cells` (idempotent — re-running the
+*     upgrade is a no-op, and new recordings are skipped).
+*
+* On any unexpected read/write failure it also returns the input untouched —
+* it never emits a partial zip. Callers can detect a skip via reference
+* equality (`result === zip`).
+*
+* Built on `@zip.js/zip.js` (the same library as the exporter) in store mode, so
+* every non-`session.json` entry is re-emitted with byte-identical uncompressed
+* content.
+*/
+async function embedCoverageInSessionJson(zip, h3Cells, h3Resolution) {
+	const reader = new ZipReader(new BlobReader(zip));
+	try {
+		const entries = await reader.getEntries();
+		const sessionEntry = entries.find((e) => !e.directory && e.filename.endsWith("session.json"));
+		if (!sessionEntry) {
+			log.warn("No session.json found; leaving zip untouched");
+			return zip;
+		}
+		let session;
+		try {
+			const text = await sessionEntry.getData(new TextWriter());
+			session = JSON.parse(text);
+		} catch (err) {
+			log.warn("session.json unparseable; leaving zip untouched", err);
+			return zip;
+		}
+		if (session.h3Cells !== void 0) return zip;
+		const merged = {
+			...session,
+			h3Cells,
+			h3Resolution
+		};
+		const writer = new ZipWriter(new BlobWriter("application/zip"), { level: 0 });
+		try {
+			for (const entry of entries) {
+				if (entry.directory || !entry.getData) continue;
+				if (entry === sessionEntry) await writer.add(entry.filename, new TextReader(JSON.stringify(merged)));
+				else {
+					const bytes = await entry.getData(new Uint8ArrayWriter());
+					await writer.add(entry.filename, new Uint8ArrayReader(bytes));
+				}
+			}
+			return await writer.close();
+		} catch (err) {
+			log.warn("Failed to re-emit zip; leaving original untouched", err);
+			return zip;
+		}
+	} catch (err) {
+		log.warn("Failed to read zip for coverage embed; leaving untouched", err);
+		return zip;
+	} finally {
+		await reader.close();
+	}
+}
+//#endregion
+export { embedCoverageInSessionJson };

package/dist/storage/zip-export.d.ts

@@ -1,2 +1,2 @@
-import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportAndDownloadSession, r as ZipExportContributor, s as exportSessionAsZip, t as ExportSessionAsZipOptions } from "../zip-export-G14hkSPG.js";
-export { ExportSessionAsZipOptions, ZipContributorAddFile, ZipExportContributor, ZipExportResult, downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };
+import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportSessionAsZip, r as ZipExportContributor, s as exportSessionHandleAsZip, t as ExportSessionAsZipOptions } from "../zip-export-ol0S_Ofd.js";
+export { ExportSessionAsZipOptions, ZipContributorAddFile, ZipExportContributor, ZipExportResult, downloadZip, exportSessionAsZip, exportSessionHandleAsZip, syncToExternalZip };