gps-plus-slam-app-framework 1.0.0 → 1.0.7

package/dist/storage/opfs-storage.js

@@ -8,26 +8,26 @@ import { formatActionFilename, formatFrameFilename, formatTimestamp } from "./fi
 * OPFS works consistently on Desktop Chrome, Android Chrome, and iOS Safari,
 * unlike showDirectoryPicker which has write restrictions on Android.
 *
-* Directory structure:
-* /gps-recorder/
-*   └── scenarios/
-*       ├── {scenario-name}/
-*       │   ├── recording-YYYY-MM-DD_HH-MM-SSutc/
-*       │   │   ├── session.json
-*       │   │   ├── actions/
-*       │   │   │   ├── 000001.json
-*       │   │   │   └── ...
-*       │   │   └── frames/
-*       │   │       ├── frame-000001.jpg
-*       │   │       └── ...
-*       │   └── ...
+* Directory structure (flat sessions — no scenario hierarchy):
+* /gps-plus-slam/
+*   └── sessions/
+*       ├── recording-YYYY-MM-DD_HH-MM-SSutc/
+*       │   ├── session.json
+*       │   ├── actions/
+*       │   │   ├── 000001.json
+*       │   │   └── ...
+*       │   └── frames/
+*       │       ├── frame-000001.jpg
+*       │       └── ...
 *       └── ...
+*
+* Scenario grouping (scenarios/{name}/recording-…) is a recorder-only concern,
+* handled by ScenarioWrappingStorageBackend in the recorder app.
 */
 const log = createLogger("OPFS");
 let opfsRoot = null;
-let gpsRecorderDir = null;
-let scenariosDir = null;
-let currentScenarioHandle = null;
+let gpsPlusSlamDir = null;
+let sessionsDir = null;
 let currentSessionHandle = null;
 let actionsHandle = null;
 let framesHandle = null;
@@ -37,9 +37,8 @@ let framesHandle = null;
 */
 function resetOpfsStorage() {
 	opfsRoot = null;
-	gpsRecorderDir = null;
-	scenariosDir = null;
-	currentScenarioHandle = null;
+	gpsPlusSlamDir = null;
+	sessionsDir = null;
 	currentSessionHandle = null;
 	actionsHandle = null;
 	framesHandle = null;
@@ -47,14 +46,11 @@ function resetOpfsStorage() {
 /**
 * Reset session-level handles only.
 *
-* Preserves opfsRoot/gpsRecorderDir/scenariosDir (OPFS stays initialized)
-* but clears current scenario/session/actions/frames handles so a new
-* session can be started fresh.
-*
-* Used during soft reset for new recordings (Issue 4, 2026-02-06 user feedback).
+* Preserves opfsRoot/gpsPlusSlamDir/sessionsDir (OPFS stays initialized)
+* but clears current session/actions/frames handles so a new session can
+* be started fresh.
 */
 function resetSessionHandles() {
-	currentScenarioHandle = null;
 	currentSessionHandle = null;
 	actionsHandle = null;
 	framesHandle = null;
@@ -63,8 +59,8 @@ function resetSessionHandles() {
 * Initialize OPFS storage by creating the required directory structure.
 *
 * Creates:
-* - /gps-recorder/
-* - /gps-recorder/scenarios/
+* - /gps-plus-slam/
+* - /gps-plus-slam/sessions/
 *
 * This is idempotent - calling multiple times is safe.
 *
@@ -74,65 +70,74 @@ async function initOpfsStorage() {
 	if (typeof navigator === "undefined" || !navigator.storage || typeof navigator.storage.getDirectory !== "function") throw new Error("OPFS (Origin Private File System) is not supported in this browser. Please use Chrome 86+, Safari 15.2+, or Firefox 111+.");
 	opfsRoot = await navigator.storage.getDirectory();
 	log.info("OPFS root obtained");
-	gpsRecorderDir = await opfsRoot.getDirectoryHandle("gps-recorder", { create: true });
-	scenariosDir = await gpsRecorderDir.getDirectoryHandle("scenarios", { create: true });
+	gpsPlusSlamDir = await opfsRoot.getDirectoryHandle("gps-plus-slam", { create: true });
+	sessionsDir = await gpsPlusSlamDir.getDirectoryHandle("sessions", { create: true });
 	log.info("OPFS storage initialized");
 }
 /**
-* Create a new recording session within a scenario.
+* Get the sessions root directory handle.
+* Used by consumers that need direct OPFS access (e.g. ZIP export).
+*/
+function getSessionsRootHandle() {
+	return sessionsDir;
+}
+/**
+* Get the app root directory handle (gps-plus-slam/).
+* Used by consumers that need to create additional directories alongside sessions/.
+*/
+function getAppRootHandle() {
+	return gpsPlusSlamDir;
+}
+/**
+* Create a new recording session.
 *
 * Creates the directory structure:
-* - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/
-* - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/actions/
-* - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/frames/
+* - /gps-plus-slam/sessions/recording-{timestamp}/
+* - /gps-plus-slam/sessions/recording-{timestamp}/actions/
+* - /gps-plus-slam/sessions/recording-{timestamp}/frames/
 *
-* @param scenarioName - Name of the scenario (creates if doesn't exist)
 * @param timestamp - Session start time (used for folder naming)
+* @param _contextTag - Opaque tag; not used by the flat layout but accepted
+*   for interface compatibility with wrapping backends
 * @returns Session information
 * @throws Error if storage not initialized
 */
-async function createSession(scenarioName, timestamp) {
-	if (!scenariosDir) throw new Error("OPFS storage not initialized. Call initOpfsStorage first.");
-	currentScenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName, { create: true });
+async function createSession(timestamp, _contextTag) {
+	if (!sessionsDir) throw new Error("OPFS storage not initialized. Call initOpfsStorage first.");
 	const sessionName = `recording-${formatTimestamp(timestamp)}`;
-	currentSessionHandle = await currentScenarioHandle.getDirectoryHandle(sessionName, { create: true });
+	currentSessionHandle = await sessionsDir.getDirectoryHandle(sessionName, { create: true });
 	actionsHandle = await currentSessionHandle.getDirectoryHandle("actions", { create: true });
 	framesHandle = await currentSessionHandle.getDirectoryHandle("frames", { create: true });
-	log.info("Session created:", `${scenarioName}/${sessionName}`);
-	return {
-		scenarioName,
-		sessionName
-	};
+	log.info("Session created:", sessionName);
+	return { sessionName };
 }
 /**
 * Get the current session directory handle.
-* Useful for test assertions.
 * @internal
 */
 function getSessionHandle() {
 	return currentSessionHandle;
 }
 /**
-* Get the current scenario directory handle.
-*/
-function getScenarioHandle() {
-	return currentScenarioHandle;
-}
-/**
-* Get the scenarios root directory handle.
-* Used for loading reference points across scenarios.
+* 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.
+*
+* @internal
 */
-function getScenariosRootHandle() {
-	return scenariosDir;
+function setSessionHandles(session, actions, frames) {
+	currentSessionHandle = session;
+	actionsHandle = actions;
+	framesHandle = frames;
 }
 /**
 * Safely write data to a file handle with proper cleanup.
 *
 * Uses try/finally to ensure the writable stream is always cleaned up,
 * calling abort() on errors to prevent resource leaks and file locks.
-*
-* @param fileHandle - The file handle to write to
-* @param data - The data to write (string or Blob)
 */
 async function safeWriteToFile(fileHandle, data) {
 	const writable = await fileHandle.createWritable();
@@ -188,40 +193,19 @@ async function writeSessionMetadata(metadata) {
 	log.info("Session metadata written");
 }
 /**
-* List all scenario names in OPFS storage.
-*
-* @returns Array of scenario folder names
-*/
-async function listScenarios() {
-	if (!scenariosDir) return [];
-	const scenarios = [];
-	for await (const entry of scenariosDir.values()) if (entry.kind === "directory") scenarios.push(entry.name);
-	return scenarios;
-}
-/**
-* List all session names within a scenario.
+* List all session names in OPFS storage.
 *
-* @param scenarioName - Name of the scenario
 * @returns Array of session folder names
 */
-async function listSessions(scenarioName) {
-	if (!scenariosDir) return [];
-	try {
-		const scenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName);
-		const sessions = [];
-		for await (const entry of scenarioHandle.values()) if (entry.kind === "directory") sessions.push(entry.name);
-		return sessions;
-	} catch {
-		return [];
-	}
+async function listSessions() {
+	if (!sessionsDir) return [];
+	const sessions = [];
+	for await (const entry of sessionsDir.values()) if (entry.kind === "directory") sessions.push(entry.name);
+	return sessions;
 }
 /**
 * Check storage quota.
 *
-* Note: Prefer calling `initOpfsStorage()` before this function to ensure
-* the Storage API is available. If the Storage Manager API is not supported,
-* returns a safe default of `{ available: 0, used: 0 }`.
-*
 * @returns Available and used storage in bytes
 */
 async function checkStorageQuota() {
@@ -239,4 +223,4 @@ async function checkStorageQuota() {
 	};
 }
 //#endregion
-export { checkStorageQuota, createSession, getScenarioHandle, getScenariosRootHandle, getSessionHandle, initOpfsStorage, listScenarios, listSessions, resetOpfsStorage, resetSessionHandles, writeAction, writeFrame, writeSessionMetadata };
+export { checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, setSessionHandles, writeAction, writeFrame, writeSessionMetadata };

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

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

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

@@ -1,2 +1,2 @@
-import { a as syncToExternalZip, i as exportSessionAsZip, n as downloadZip, r as exportAndDownloadSession, t as ZipExportResult } from "../zip-export-Rtpi75JJ.js";
-export { ZipExportResult, downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };
+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-QO4iLIi7.js";
+export { ExportSessionAsZipOptions, ZipContributorAddFile, ZipExportContributor, ZipExportResult, downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };

package/dist/storage/zip-export.js

@@ -22,9 +22,16 @@ const log = createLogger("ZipExport");
 /**
 * Get the OPFS scenarios directory handle.
 * Re-acquires from navigator.storage to avoid holding stale references.
+* Creates on demand so it works even when initOpfsStorage only creates sessions/.
 */
 async function getScenariosHandle() {
-	return (await (await navigator.storage.getDirectory()).getDirectoryHandle("gps-recorder")).getDirectoryHandle("scenarios");
+	return (await (await navigator.storage.getDirectory()).getDirectoryHandle("gps-plus-slam")).getDirectoryHandle("scenarios", { create: true });
+}
+/**
+* Get the OPFS sessions directory handle (flat layout).
+*/
+async function getSessionsHandle() {
+	return (await (await navigator.storage.getDirectory()).getDirectoryHandle("gps-plus-slam")).getDirectoryHandle("sessions");
 }
 /**
 * Stream all files from a directory recursively into a ZipWriter.
@@ -49,80 +56,66 @@ async function streamDirectoryToZip(dirHandle, zipWriter, basePath = "") {
 	return count;
 }
 /**
-* Filter and stream per-session ref point observations into a ZipWriter.
-*
-* Reads each ref point JSON from the scenario-level refPoints/ directory,
-* keeps only observations where `sessionId` matches `sessionName`, and writes
-* the filtered definition into the ZIP under `refPoints/{h3}.json`.
-*
-* Ref points with no observations for the current session are skipped entirely.
-* If the refPoints/ directory doesn't exist yet (new scenario), returns 0.
-*
-* @returns Number of ref point files added
-*/
-async function streamSessionRefPointsToZip(scenarioHandle, sessionName, zipWriter) {
-	let count = 0;
-	let refPointsHandle;
-	try {
-		refPointsHandle = await scenarioHandle.getDirectoryHandle("refPoints");
-	} catch {
-		return 0;
-	}
-	for await (const [name, handle] of refPointsHandle.entries()) {
-		if (handle.kind !== "file" || !name.endsWith(".json")) continue;
-		try {
-			const text = await (await handle.getFile()).text();
-			const def = JSON.parse(text);
-			if (!Array.isArray(def.observations)) continue;
-			const sessionObs = def.observations.filter((o) => o.sessionId === sessionName);
-			if (sessionObs.length === 0) continue;
-			const filtered = {
-				...def,
-				observations: sessionObs
-			};
-			const blob = new Blob([JSON.stringify(filtered, null, 2)], { type: "application/json" });
-			await zipWriter.add(`refPoints/${name}`, new BlobReader(blob));
-			count++;
-		} catch (err) {
-			log.warn(`Failed to process ref point ${name}:`, err);
-		}
-	}
-	return count;
-}
-/**
 * Export a session from OPFS as a ZIP blob.
 *
 * The ZIP structure mirrors the OPFS session structure:
 * - session.json (at root)
 * - actions/000001.json, actions/000002.json, ...
 * - frames/frame-000001.jpg, frames/frame-000002.jpg, ...
-* - refPoints/{h3}.json (only observations from this session)
+* - refPoints/{h3}.json (only observations from this session, scenario layout only)
 *
 * Uses "store" mode (compression level 0) for fast packaging.
 *
-* @param scenarioName - Name of the scenario
-* @param sessionName - Name of the session folder
+* Supports both flat and scenario-based layouts:
+* - `exportSessionAsZip(sessionName)` — flat layout (sessions/)
+* - `exportSessionAsZip(scenarioName, sessionName)` — scenario layout (scenarios/{name}/)
+*
 * @returns ZIP export result with blob and file count
-* @throws Error if scenario or session not found
+* @throws Error if session not found
 */
-async function exportSessionAsZip(scenarioName, sessionName) {
-	log.info(`Exporting session: ${scenarioName}/${sessionName}`);
-	const scenariosDir = await getScenariosHandle();
-	let scenarioHandle;
-	try {
-		scenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName);
-	} catch {
-		throw new Error(`Scenario "${scenarioName}" not found in OPFS storage`);
-	}
+async function exportSessionAsZip(scenarioNameOrSessionName, sessionName, options) {
 	let sessionHandle;
-	try {
-		sessionHandle = await scenarioHandle.getDirectoryHandle(sessionName);
-	} catch {
-		throw new Error(`Session "${sessionName}" not found in scenario "${scenarioName}"`);
+	if (sessionName) {
+		const scenarioName = scenarioNameOrSessionName;
+		log.info(`Exporting session: ${scenarioName}/${sessionName}`);
+		const scenariosDir = await getScenariosHandle();
+		let scenarioHandle;
+		try {
+			scenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName);
+		} catch {
+			throw new Error(`Scenario "${scenarioName}" not found in OPFS storage`);
+		}
+		try {
+			sessionHandle = await scenarioHandle.getDirectoryHandle(sessionName);
+		} catch {
+			throw new Error(`Session "${sessionName}" not found in scenario "${scenarioName}"`);
+		}
+	} else {
+		log.info(`Exporting session: ${scenarioNameOrSessionName}`);
+		const sessionsDir = await getSessionsHandle();
+		try {
+			sessionHandle = await sessionsDir.getDirectoryHandle(scenarioNameOrSessionName);
+		} catch {
+			throw new Error(`Session "${scenarioNameOrSessionName}" not found in OPFS storage`);
+		}
 	}
 	const zipWriter = new ZipWriter(new BlobWriter("application/zip"), { level: 0 });
 	let fileCount = await streamDirectoryToZip(sessionHandle, zipWriter);
-	fileCount += await streamSessionRefPointsToZip(scenarioHandle, sessionName, zipWriter);
+	const contributors = options?.contributors ?? [];
+	const seenSubdirs = /* @__PURE__ */ new Set();
+	for (const contributor of contributors) {
+		const subdir = contributor.subdir;
+		if (!subdir || subdir.includes("/") || subdir.startsWith(".")) throw new Error(`ZipExportContributor.subdir must be a non-empty single path segment, got: ${JSON.stringify(subdir)}`);
+		if (seenSubdirs.has(subdir)) throw new Error(`Duplicate ZipExportContributor.subdir registered: ${subdir}`);
+		seenSubdirs.add(subdir);
+		const addFile = async (relativePath, blob) => {
+			if (relativePath.startsWith("/")) throw new Error(`ZipExportContributor relative path must not start with '/' (got ${relativePath})`);
+			if (relativePath.includes("\\")) throw new Error(`ZipExportContributor relative path must not contain '\\' (got ${relativePath})`);
+			if (relativePath.split("/").some((s) => s === ".." || s === ".")) throw new Error(`ZipExportContributor relative path must not contain '.' or '..' segments (got ${relativePath})`);
+			await zipWriter.add(`${subdir}/${relativePath}`, new BlobReader(blob));
+		};
+		fileCount += await contributor.contribute(addFile);
+	}
 	const blob = await zipWriter.close();
 	log.info(`ZIP created: ${blob.size} bytes, ${fileCount} files`);
 	return {
@@ -148,9 +141,9 @@ async function exportSessionAsZip(scenarioName, sessionName) {
 * @returns ZIP export result with blob and file count
 * @throws Error if scenario or session not found
 */
-async function syncToExternalZip(fileHandle, scenarioName, sessionName) {
+async function syncToExternalZip(fileHandle, scenarioName, sessionName, options) {
 	log.info(`Syncing to external ZIP: ${scenarioName}/${sessionName}`);
-	const result = await exportSessionAsZip(scenarioName, sessionName);
+	const result = await exportSessionAsZip(scenarioName, sessionName, options);
 	const writable = await fileHandle.createWritable();
 	await writable.write(result.blob);
 	await writable.close();

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

@@ -1,2 +1,2 @@
-import { a as ZipActionEntry, c as loadSessionMetadata, i as RecordedAction, l as loadSessionMetadataFromBlob, n as GpsPathCoord, o as loadActionsFromZip, r as MAX_ACTION_FILE_SIZE, s as loadGpsPathFromBlob, t as Entry, u as readZipEntries } from "../zip-reader-D7pkpX8K.js";
-export { Entry, GpsPathCoord, MAX_ACTION_FILE_SIZE, RecordedAction, ZipActionEntry, loadActionsFromZip, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries };
+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-D1105idz.js";
+export { Entry, GpsPathCoord, MAX_ACTION_FILE_SIZE, RecordedAction, ZipActionEntry, ZipSubdirEntry, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries };

package/dist/storage/zip-reader.js

@@ -172,10 +172,14 @@ async function loadGpsPathFromBlob(blob, maxFileSize = MAX_ACTION_FILE_SIZE) {
 				continue;
 			}
 			const gps = action.payload?.rawGpsPoint ?? action.payload?.gpsPoint;
-			if (action.type === "gpsData/recordGpsEvent" && gps && typeof gps.latitude === "number" && typeof gps.longitude === "number") coords.push({
-				lat: gps.latitude,
-				lng: gps.longitude
-			});
+			if (action.type === "gpsData/recordGpsEvent" && gps && typeof gps.latitude === "number" && typeof gps.longitude === "number") {
+				const accuracy = typeof gps.latLongAccuracy === "number" && gps.latLongAccuracy > 0 ? gps.latLongAccuracy : void 0;
+				coords.push({
+					lat: gps.latitude,
+					lng: gps.longitude,
+					...accuracy !== void 0 ? { accuracy } : {}
+				});
+			}
 		}
 		return coords;
 	} catch {
@@ -186,5 +190,28 @@ async function loadGpsPathFromBlob(blob, maxFileSize = MAX_ACTION_FILE_SIZE) {
 		} catch {}
 	}
 }
+/**
+* Enumerate every file under a single top-level subdirectory of a recording
+* zip. Mirrors the writer-side {@link ZipExportContributor} seam so consumers
+* (typically the recorder) can read back what they wrote without
+* re-implementing zip enumeration.
+*
+* Skips directory entries and files outside `subdir`. Sorts entries by
+* `relativePath` for deterministic iteration. Returns an empty array when
+* the subdir is absent (graceful degradation for older zips).
+*
+* @param data - The zip file content as a Uint8Array
+* @param subdir - Top-level subdir to scan (no leading or trailing `/`)
+*/
+async function loadEntriesFromSubdir(data, subdir) {
+	if (!subdir || subdir.includes("/") || subdir.startsWith(".")) throw new Error(`subdir must be a non-empty single path segment, got: ${JSON.stringify(subdir)}`);
+	const prefix = `${subdir}/`;
+	return (await readZipEntries(data)).filter((e) => !e.directory && e.filename.startsWith(prefix) && e.filename !== prefix).sort((a, b) => a.filename.localeCompare(b.filename)).map((entry) => ({
+		relativePath: entry.filename.slice(prefix.length),
+		fullPath: entry.filename,
+		uncompressedSize: entry.uncompressedSize,
+		getText: () => entry.getData(new TextWriter())
+	}));
+}
 //#endregion
-export { MAX_ACTION_FILE_SIZE, loadActionsFromZip, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries };
+export { MAX_ACTION_FILE_SIZE, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries };

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

@@ -0,0 +1,28 @@
+import { n as SessionMetadata } from "./opfs-storage-DOPkzgeT.js";
+
+//#region ../src/storage/storage-backend.d.ts
+interface CreateSessionResult {
+  sessionName: string;
+}
+/**
+ * Contract for session lifecycle and recording persistence.
+ *
+ * Implementations:
+ * - OpfsStorageBackend: production — flat sessions under OPFS
+ * - NullStorageBackend: tests/replay — silent no-ops
+ * - ScenarioWrappingStorageBackend (recorder): layers scenario hierarchy on top
+ */
+interface StorageBackend {
+  /** Create a new recording session. Returns the session name for reference. */
+  createSession(timestamp: Date, contextTag?: string): Promise<CreateSessionResult>;
+  /** List all session names managed by this backend. */
+  listSessions(): Promise<string[]>;
+  /** Persist a Redux action as a numbered JSON file. */
+  writeAction(action: unknown, index: number): Promise<void>;
+  /** Persist a captured camera frame as a numbered JPEG. */
+  writeFrame(blob: Blob, index: number): Promise<void>;
+  /** Persist session metadata (session.json). */
+  writeSessionMetadata(metadata: SessionMetadata): Promise<void>;
+}
+//#endregion
+export { StorageBackend as n, CreateSessionResult as t };

package/dist/{store-subscribers-CuoIzB5T.d.ts → store-subscribers-Dce_CoJF.d.ts}

@@ -1,4 +1,5 @@
-import { t as SubscribableStore } from "./subscribe-to-selector-UTZ0KkAc.js";
+import { t as MapData } from "./map-data-sih4g64v.js";
+import { t as SubscribableStore } from "./subscribe-to-selector-DIHm3BRZ.js";
 import { LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/state/store-subscribers.d.ts
@@ -13,16 +14,28 @@ interface StoreSubscriberDeps {
   gpsEventVisualizer: {
     getZeroRef: () => LatLong | null;
     setZeroRef: (zero: LatLong) => void;
-    addGpsEvent: (gpsCoords: Vector3, odomPosition: Vector3) => void;
+    addGpsEvent: (gpsCoords: Vector3, odomPosition: Vector3, accuracy?: {
+      horizontal?: number;
+      vertical?: number;
+    }) => void;
     addAlignmentSnapshot: (nuePosition: Vector3) => void;
   };
-  /** Map overlay — updates the 2D map position. Nullable (not present in all modes). */
+  /**
+   * Map overlay — renders the shared trajectory snapshot. Nullable (not
+   * present in all modes).
+   *
+   * `setGpsPosition` centers the map on the latest fix; `render` draws the
+   * full {@link MapData} snapshot (raw GPS + accuracy circles, fused path,
+   * alignment snapshots, user dot) via the shared `drawMapData` routine — the
+   * SAME one the 2D session-summary map uses, so the live and summary maps
+   * stay identical (unified-trajectory-map Phase 3). The previous incremental
+   * `addRawGpsPoint` / `addFusedPoint` / `addAlignmentSnapshot` API is gone:
+   * the fused path now recomputes from the latest matrix on every rebuild
+   * (D2), so the live polyline "snaps" as alignment improves.
+   */
   mapOverlay?: {
     setGpsPosition: (lat: number, lon: number) => void;
-    addRawGpsPoint?: (lat: number, lon: number) => void;
-    addFusedPoint?: (lat: number, lon: number) => void;
-    addAlignmentSnapshot?: (lat: number, lon: number) => void;
-    addRefPoint?: (lat: number, lon: number, name: string) => void;
+    render?: (data: MapData) => void;
   } | null;
   /**
    * Optional callback invoked with the GPS world-space coordinates of each
@@ -52,6 +65,17 @@ interface StoreSubscriberDeps {
    * for dynamic button label updates.
    */
   onNewGpsLatLng?: (lat: number, lng: number) => void;
+  /**
+   * When `true`, the recorded GPS 1σ accuracies (`latLongAccuracy`,
+   * `altitudeAccuracy`) on each `GpsPoint` are forwarded to `addGpsEvent`
+   * so the raw-GPS marker renders as a non-uniform-scaled ellipsoid (see
+   * `gps-event-markers.ts` §3). When `false` (the default) the accuracies
+   * are dropped and the legacy fixed 8 cm sphere is used.
+   *
+   * Live recording leaves this `false` (large ellipsoids would distract the
+   * operator). Replay mode sets it to `true` so the diagnostic is visible.
+   */
+  showAccuracySpheres?: boolean;
 }
 /**
  * Wire store state-change subscriptions to visualization dependencies.

package/dist/{subscribe-to-selector-UTZ0KkAc.d.ts → subscribe-to-selector-DIHm3BRZ.d.ts}

@@ -1,4 +1,4 @@
-import { n as CombinedRootState } from "./store-C7PKOj8S.js";
+import { L as CombinedRootState } from "./create-slam-app-store-CNsZ3rcX.js";
 
 //#region ../src/state/subscribe-to-selector.d.ts
 /**

package/dist/test-utils/browser-mocks.d.ts

@@ -1,4 +1,4 @@
-import { a as WebXRQuaternion, o as WebXRVec3 } from "../ar-types-B-ORgk6Z.js";
+import { a as WebXRQuaternion, o as WebXRVec3 } from "../ar-types-Ck8LEq8k.js";
 import { Mock } from "vitest";
 
 //#region ../src/test-utils/browser-mocks.d.ts

package/dist/test-utils/zip-round-trip-helpers.d.ts

@@ -1,4 +1,4 @@
-import { i as RecordedAction } from "../zip-reader-D7pkpX8K.js";
+import { i as RecordedAction } from "../zip-reader-D1105idz.js";
 import { LatLong } from "gps-plus-slam-js";
 
 //#region ../src/test-utils/zip-round-trip-helpers.d.ts
@@ -12,6 +12,12 @@ interface ProduceTestZipOptions {
   frameCount: number;
   deviceInfo: string;
   zeroPos: LatLong;
+  /**
+   * Optional horizontal accuracy (meters) stamped onto every produced
+   * `recordGpsEvent` action's `rawGpsPoint.latLongAccuracy`. When omitted,
+   * the field is left off — matching pre-accuracy recordings.
+   */
+  gpsAccuracy?: number;
 }
 /** Result of producing a test zip, with all metadata needed for assertions. */
 interface TestZipResult {

package/dist/test-utils/zip-round-trip-helpers.js

@@ -65,7 +65,7 @@ async function produceTestZip(opts) {
 	const { cleanup } = installOPFSMocks();
 	try {
 		await initOpfsStorage();
-		const { scenarioName, sessionName } = await createSession(options.scenarioName, options.sessionTimestamp);
+		const { sessionName } = await createSession(options.sessionTimestamp, options.scenarioName);
 		const allActions = [];
 		let actionIndex = 0;
 		/** Increment index, persist to OPFS, and record for later assertions. */
@@ -75,7 +75,7 @@ async function produceTestZip(opts) {
 			allActions.push(action);
 		};
 		await writeAndRecordAction({
-			type: "recorder/startSession",
+			type: "recording/startSession",
 			payload: {
 				scenarioName: options.scenarioName,
 				sessionName,
@@ -131,7 +131,8 @@ async function produceTestZip(opts) {
 						id: `gps-event-${i + 1}`,
 						latitude: options.zeroPos.lat + (i + 1) * 1e-4,
 						longitude: options.zeroPos.lon + (i + 1) * 1e-4,
-						timestamp: t
+						timestamp: t,
+						...typeof options.gpsAccuracy === "number" ? { latLongAccuracy: options.gpsAccuracy } : {}
 					}
 				}
 			});
@@ -174,12 +175,12 @@ async function produceTestZip(opts) {
 			version: 1,
 			startedAt: options.sessionTimestamp.toISOString(),
 			endedAt: new Date(options.sessionTimestamp.getTime() + actionIndex * 1e3 + 5e3).toISOString(),
-			scenarioName: options.scenarioName,
+			contextTag: options.scenarioName,
 			actionCount: actionIndex,
 			frameCount: options.frameCount,
 			userAgent: options.deviceInfo
 		});
-		const { blob } = await exportSessionAsZip(scenarioName, sessionName);
+		const { blob } = await exportSessionAsZip(sessionName);
 		return {
 			zipData: new Uint8Array(await blob.arrayBuffer()),
 			totalActionCount: actionIndex,