gps-plus-slam-app-framework 1.0.0

package/dist/storage/zip-export.js

@@ -0,0 +1,214 @@
+import { createLogger } from "../utils/logger.js";
+import { BlobReader, BlobWriter, ZipWriter } from "@zip.js/zip.js";
+//#region ../src/storage/zip-export.ts
+/**
+* ZIP Export Module
+*
+* Exports OPFS session data as ZIP files for download.
+* Uses @zip.js/zip.js library for streaming ZIP creation and reading.
+*
+* The ZIP uses "store" mode (no compression) because:
+* 1. Images are already compressed (JPEG)
+* 2. Faster packaging
+* 3. Simpler implementation
+*
+* @zip.js/zip.js was chosen over fflate because:
+* - Supports streaming reads and writes (needed for periodic sync to external file)
+* - Can append to existing ZIP files via prependZip
+* - Actively maintained with good TypeScript support
+* - Built-in Web Worker support for non-blocking compression
+*/
+const log = createLogger("ZipExport");
+/**
+* Get the OPFS scenarios directory handle.
+* Re-acquires from navigator.storage to avoid holding stale references.
+*/
+async function getScenariosHandle() {
+	return (await (await navigator.storage.getDirectory()).getDirectoryHandle("gps-recorder")).getDirectoryHandle("scenarios");
+}
+/**
+* Stream all files from a directory recursively into a ZipWriter.
+* Files are read one at a time and immediately added to the ZIP,
+* keeping memory usage proportional to a single file (not the total).
+*
+* @returns Number of files added
+*/
+async function streamDirectoryToZip(dirHandle, zipWriter, basePath = "") {
+	let count = 0;
+	for await (const entry of dirHandle.values()) {
+		const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+		if (entry.kind === "file") {
+			const file = await (await dirHandle.getFileHandle(entry.name)).getFile();
+			await zipWriter.add(relativePath, new BlobReader(file));
+			count++;
+		} else if (entry.kind === "directory") {
+			const subDirHandle = await dirHandle.getDirectoryHandle(entry.name);
+			count += await streamDirectoryToZip(subDirHandle, zipWriter, relativePath);
+		}
+	}
+	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)
+*
+* Uses "store" mode (compression level 0) for fast packaging.
+*
+* @param scenarioName - Name of the scenario
+* @param sessionName - Name of the session folder
+* @returns ZIP export result with blob and file count
+* @throws Error if scenario or 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`);
+	}
+	let sessionHandle;
+	try {
+		sessionHandle = await scenarioHandle.getDirectoryHandle(sessionName);
+	} catch {
+		throw new Error(`Session "${sessionName}" not found in scenario "${scenarioName}"`);
+	}
+	const zipWriter = new ZipWriter(new BlobWriter("application/zip"), { level: 0 });
+	let fileCount = await streamDirectoryToZip(sessionHandle, zipWriter);
+	fileCount += await streamSessionRefPointsToZip(scenarioHandle, sessionName, zipWriter);
+	const blob = await zipWriter.close();
+	log.info(`ZIP created: ${blob.size} bytes, ${fileCount} files`);
+	return {
+		blob,
+		fileCount
+	};
+}
+/**
+* Sync current OPFS session data to an external file handle.
+*
+* This is used for periodic sync during recording to save data to the user's
+* chosen location (obtained via showSaveFilePicker). The function:
+* 1. Reads all current session data from OPFS
+* 2. Creates a ZIP in memory
+* 3. Writes the ZIP to the external file handle
+*
+* This provides crash safety combined with OPFS - even if the app crashes,
+* the last synced ZIP contains all data up to that point.
+*
+* @param fileHandle - File handle from showSaveFilePicker
+* @param scenarioName - Name of the scenario
+* @param sessionName - Name of the session folder
+* @returns ZIP export result with blob and file count
+* @throws Error if scenario or session not found
+*/
+async function syncToExternalZip(fileHandle, scenarioName, sessionName) {
+	log.info(`Syncing to external ZIP: ${scenarioName}/${sessionName}`);
+	const result = await exportSessionAsZip(scenarioName, sessionName);
+	const writable = await fileHandle.createWritable();
+	await writable.write(result.blob);
+	await writable.close();
+	log.info(`Synced ${result.blob.size} bytes to external file`);
+	return result;
+}
+/**
+* Trigger a file download in the browser.
+*
+* Uses showSaveFilePicker if available (for better UX on desktop),
+* falls back to <a download> for broader compatibility.
+*
+* @param blob - The blob to download
+* @param filename - Suggested filename
+*/
+async function downloadZip(blob, filename) {
+	if ("showSaveFilePicker" in window && window.showSaveFilePicker) try {
+		const writable = await (await window.showSaveFilePicker({
+			suggestedName: filename,
+			types: [{
+				description: "ZIP Archive",
+				accept: { "application/zip": [".zip"] }
+			}]
+		})).createWritable();
+		await writable.write(blob);
+		await writable.close();
+		log.info(`Saved via File System Access API: ${filename}`);
+		return;
+	} catch (err) {
+		const error = err;
+		if (error.name === "AbortError") {
+			log.info("User cancelled save dialog");
+			return;
+		}
+		log.warn("showSaveFilePicker failed, using fallback:", error.message);
+	}
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = filename;
+	link.style.display = "none";
+	document.body.appendChild(link);
+	link.click();
+	document.body.removeChild(link);
+	setTimeout(() => URL.revokeObjectURL(url), 1e3);
+	log.info(`Download triggered via <a download>: ${filename}`);
+}
+/**
+* Export and download a session in one step.
+*
+* Convenience function combining exportSessionAsZip and downloadZip.
+*
+* @param scenarioName - Name of the scenario
+* @param sessionName - Name of the session folder
+*/
+async function exportAndDownloadSession(scenarioName, sessionName) {
+	const { blob } = await exportSessionAsZip(scenarioName, sessionName);
+	await downloadZip(blob, `${scenarioName}-${sessionName}.zip`);
+}
+//#endregion
+export { downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };

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

@@ -0,0 +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 };

package/dist/storage/zip-reader.js

@@ -0,0 +1,190 @@
+import { createLogger } from "../utils/logger.js";
+import { BlobReader, TextWriter, Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
+//#region ../src/storage/zip-reader.ts
+/**
+* Zip Reader — utilities for reading recording session zip files.
+*
+* Provides production-ready functions to enumerate zip entries, extract
+* recorded Redux actions, and load session metadata from exported recording
+* zip files. Works with both Node.js (Uint8Array from fs) and browser
+* (Uint8Array from fetch/FileReader) environments.
+*
+* The recording zip format:
+*   actions/000001.json  — Redux action JSON files (1-based, zero-padded)
+*   actions/000002.json
+*   ...
+*   frames/frame-000001.jpg  — captured image frames (optional)
+*   session.json             — session metadata (optional, see F1 bug)
+*/
+const log = createLogger("ZipReader");
+/**
+* Maximum allowed uncompressed size (in bytes) for a single action or
+* metadata JSON file inside a recording zip. Entries exceeding this limit
+* are rejected before decompression to prevent out-of-memory conditions
+* from malicious or corrupted zip files.
+*
+* 1 MB — generous for Redux action JSON; typical actions are a few KB.
+*/
+const MAX_ACTION_FILE_SIZE = 1048576;
+/**
+* Read all entries from a zip file.
+*
+* @param data - The zip file content as a Uint8Array
+* @returns Array of zip entries (directories and files)
+*/
+async function readZipEntries(data) {
+	const reader = new ZipReader(new Uint8ArrayReader(data));
+	try {
+		return await reader.getEntries();
+	} finally {
+		await reader.close();
+	}
+}
+/**
+* Extract the numeric index from an action filename.
+* Filenames are zero-padded like "000001.json" or "actions/000001.json".
+*
+* @param filename - The entry filename from the zip
+* @returns The numeric index, or NaN if the filename doesn't match the pattern
+*/
+function extractActionIndex(filename) {
+	const match = /(\d+)\.json$/.exec(filename);
+	return match ? parseInt(match[1], 10) : NaN;
+}
+/**
+* Load all recorded Redux actions from a zip file.
+*
+* Filters for JSON files in the actions/ directory, parses them, and returns
+* them sorted by their filename index (chronological order for replay).
+*
+* @param data - The zip file content as a Uint8Array
+* @param maxFileSize - Maximum allowed uncompressed size per entry (defaults to MAX_ACTION_FILE_SIZE)
+* @returns Array of action entries sorted by index
+*/
+async function loadActionsFromZip(data, maxFileSize = MAX_ACTION_FILE_SIZE) {
+	const actionEntries = (await readZipEntries(data)).filter((e) => !e.directory && e.filename.includes("actions/") && e.filename.endsWith(".json")).sort((a, b) => a.filename.localeCompare(b.filename));
+	const results = [];
+	for (const entry of actionEntries) if (!entry.directory) {
+		if (entry.uncompressedSize > maxFileSize) throw new Error(`Action file "${entry.filename}" (${entry.uncompressedSize} bytes) exceeds maximum allowed size of ${maxFileSize} bytes`);
+		const index = extractActionIndex(entry.filename);
+		if (Number.isNaN(index)) log.warn(`Unexpected non-numeric action filename: "${entry.filename}". Expected pattern like "actions/000001.json". The file will still be processed.`);
+		const text = await entry.getData(new TextWriter());
+		let action;
+		try {
+			const parsed = JSON.parse(text);
+			if (typeof parsed !== "object" || parsed === null || typeof parsed.type !== "string") {
+				log.warn(`Skipping "${entry.filename}": parsed JSON is not a valid action (missing "type" string)`);
+				continue;
+			}
+			action = parsed;
+		} catch {
+			log.warn(`Skipping malformed JSON in "${entry.filename}": parse failed`);
+			continue;
+		}
+		results.push({
+			index,
+			filename: entry.filename,
+			action
+		});
+	}
+	return results;
+}
+/**
+* Extract session metadata from an already-constructed ZipReader.
+*
+* Finds the `session.json` entry, validates its size, extracts and parses it.
+* The reader is always closed in `finally`, so callers must not reuse it.
+*
+* @param reader - An open ZipReader (Uint8ArrayReader or BlobReader based)
+* @param maxFileSize - Maximum allowed uncompressed size for session.json
+* @returns Parsed metadata object, or null if session.json is absent
+*/
+async function extractSessionMetadataFromReader(reader, maxFileSize) {
+	try {
+		const sessionEntry = (await reader.getEntries()).find((e) => !e.directory && e.filename.endsWith("session.json"));
+		if (!sessionEntry) return null;
+		if (sessionEntry.uncompressedSize > maxFileSize) throw new Error(`Session file "${sessionEntry.filename}" (${sessionEntry.uncompressedSize} bytes) exceeds maximum allowed size of ${maxFileSize} bytes`);
+		const text = await sessionEntry.getData(new TextWriter());
+		return JSON.parse(text);
+	} finally {
+		await reader.close();
+	}
+}
+/**
+* Load session metadata from session.json in the zip file.
+*
+* Returns null if session.json is absent (graceful degradation for
+* recordings created before the metadata writing bug was fixed).
+*
+* @param data - The zip file content as a Uint8Array
+* @param maxFileSize - Maximum allowed uncompressed size per entry (defaults to MAX_ACTION_FILE_SIZE)
+* @returns Parsed session metadata, or null if not found
+*/
+async function loadSessionMetadata(data, maxFileSize = MAX_ACTION_FILE_SIZE) {
+	return extractSessionMetadataFromReader(new ZipReader(new Uint8ArrayReader(data)), maxFileSize);
+}
+/**
+* Load session metadata from session.json in a zip file provided as a Blob.
+*
+* Unlike `loadSessionMetadata(Uint8Array)`, this variant uses zip.js's
+* BlobReader which reads only the central directory and the target entry
+* from the Blob — not the entire file contents. This is critical for
+* memory-efficient scanning of many large recording zips (e.g., during
+* `discoverScenariosFromZipMetadata`).
+*
+* Since `File` extends `Blob`, this works directly with file handles:
+*   const file = await handle.getFile();
+*   const meta = await loadSessionMetadataFromBlob(file);
+*
+* @param blob - A Blob or File containing the zip data
+* @param maxFileSize - Maximum allowed uncompressed size per entry (defaults to MAX_ACTION_FILE_SIZE)
+* @returns Parsed session metadata, or null if session.json is not found
+*/
+async function loadSessionMetadataFromBlob(blob, maxFileSize = MAX_ACTION_FILE_SIZE) {
+	return extractSessionMetadataFromReader(new ZipReader(new BlobReader(blob)), maxFileSize);
+}
+/**
+* Extract GPS coordinates from a recording zip provided as a Blob.
+*
+* Uses BlobReader for memory-efficient reading. Reads all action JSON files,
+* identifies `gpsData/recordGpsEvent` actions, and returns only the lightweight
+* `{ lat, lng }` pairs — all other action data is discarded immediately.
+*
+* Returns coordinates in chronological order (sorted by action filename).
+* Returns an empty array if the zip is invalid or contains no GPS actions.
+*
+* @param blob - A Blob or File containing the zip data
+* @param maxFileSize - Maximum allowed uncompressed size per action entry
+* @returns Array of GPS coordinates in chronological order
+*/
+async function loadGpsPathFromBlob(blob, maxFileSize = MAX_ACTION_FILE_SIZE) {
+	const reader = new ZipReader(new BlobReader(blob));
+	try {
+		const actionEntries = (await reader.getEntries()).filter((e) => !e.directory && e.filename.includes("actions/") && e.filename.endsWith(".json")).sort((a, b) => a.filename.localeCompare(b.filename));
+		const coords = [];
+		for (const entry of actionEntries) {
+			if (entry.uncompressedSize > maxFileSize) continue;
+			const text = await entry.getData(new TextWriter());
+			let action;
+			try {
+				action = JSON.parse(text);
+			} catch {
+				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
+			});
+		}
+		return coords;
+	} catch {
+		return [];
+	} finally {
+		try {
+			await reader.close();
+		} catch {}
+	}
+}
+//#endregion
+export { MAX_ACTION_FILE_SIZE, loadActionsFromZip, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries };

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

@@ -0,0 +1,20 @@
+import { n as SessionMetadata } from "./opfs-storage-ChOzF_Wp.js";
+
+//#region ../src/storage/storage-backend.d.ts
+/**
+ * Contract for persisting recording data during a session.
+ *
+ * Implementations:
+ * - OpfsStorageBackend: production — delegates to OPFS via file-system.ts
+ * - NullStorageBackend: tests/replay — silent no-ops
+ */
+interface StorageBackend {
+  /** 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 t };

package/dist/store-C7PKOj8S.d.ts

@@ -0,0 +1,96 @@
+import { n as SessionMetadata } from "./opfs-storage-ChOzF_Wp.js";
+import { t as StorageBackend } from "./storage-backend-BcEItnFr.js";
+import { t as RecorderState } from "./recorder-slice-fcwAXrsh.js";
+import { t as RefPointsState } from "./ref-points-slice-tC-Wd6XJ.js";
+import { n as RoutingState } from "./routing-slice-BlHTM8eh.js";
+import { configureStore } from "@reduxjs/toolkit";
+import { GpsPoint as GpsPoint$1, LatLong as LatLong$1, MarkReferencePointPayload, RawDeviceOrientation, RawGpsPoint as RawGpsPoint$1, RecordGpsEventPayload, RootState, add2dImage, calcRelativeCoordsInMeters as calcRelativeCoordsInMeters$1, markReferencePoint, recordGpsEvent, setZeroPos } from "gps-plus-slam-js";
+
+//#region ../src/state/store.d.ts
+/**
+ * Combined root state: library state + app-level state.
+ * All 6 reducers (3 library + 3 app) are managed by a single configureStore.
+ */
+interface CombinedRootState extends RootState {
+  recorder: RecorderState;
+  refPoints: RefPointsState;
+  routing: RoutingState;
+}
+/**
+ * Store interface for the recorder app.
+ *
+ * Wraps the Redux Toolkit store and adds storage delegation methods
+ * (writeFrame, writeSessionMetadata) that route through the injected
+ * StorageBackend abstraction.
+ */
+interface RecorderStore {
+  /** Get combined state (library + app) */
+  getState: () => CombinedRootState;
+  /** Dispatch actions to the unified store */
+  dispatch: ReturnType<typeof configureStore>['dispatch'];
+  /** Subscribe to state changes */
+  subscribe: (listener: () => void) => () => void;
+  /**
+   * Persist a captured camera frame via the StorageBackend.
+   * A1 fix: routes through the abstraction so NullStorageBackend suppresses
+   * writes during replay/testing.
+   */
+  writeFrame: (blob: Blob, index: number) => Promise<void>;
+  /**
+   * Persist session metadata (session.json) via the StorageBackend.
+   * A1 fix: routes through the abstraction so NullStorageBackend suppresses
+   * writes during replay/testing.
+   */
+  writeSessionMetadata: (metadata: SessionMetadata) => Promise<void>;
+}
+/**
+ * Options for creating the recorder store.
+ */
+interface RecorderStoreOptions {
+  /**
+   * Callback invoked when a write operation fails during persistence.
+   * User Feedback Issue #1 Part B: Used to show toast notifications.
+   */
+  onWriteFailure?: (error: Error) => void;
+  /**
+   * StorageBackend to use for action persistence.
+   * Defaults to OpfsStorageBackend (production OPFS).
+   * Pass NullStorageBackend for tests or replay mode.
+   *
+   * Finding F2: Decouples the store from the concrete OPFS dependency.
+   */
+  storageBackend?: StorageBackend;
+  /**
+   * When false, disables expensive Redux dev-only middleware
+   * (SerializableStateInvariantMiddleware, ImmutableStateInvariantMiddleware).
+   * Set to false in high-throughput replay scenarios such as investigation tests
+   * to avoid excessive per-dispatch overhead.
+   * Default: true (dev checks enabled).
+   */
+  enableDevChecks?: boolean;
+  /**
+   * License key for the core library.
+   * Validated via Ed25519 signature verification and expiry check.
+   *
+   * Defaults to the bundled `COMMUNITY_LICENSE_KEY` so example apps work out
+   * of the box. Pass a paid license to override. The library is never usable
+   * without a valid key — invalid, empty, or expired keys throw.
+   *
+   * @see EULA.md §3 — License Key
+   */
+  licenseKey?: string;
+}
+/**
+ * Create the recorder store using Redux Toolkit's configureStore.
+ *
+ * Combines all 6 reducers (3 library: gpsData, gpsElements, arElements;
+ * 3 app: recorder, refPoints, routing) into a single store with the
+ * persistence middleware for action recording.
+ *
+ * @param options - Optional configuration including callbacks
+ */
+declare function createRecorderStore(options?: RecorderStoreOptions): RecorderStore;
+type RootState$1 = CombinedRootState;
+type AppDispatch = RecorderStore['dispatch'];
+//#endregion
+export { setZeroPos as _, MarkReferencePointPayload as a, RecordGpsEventPayload as c, RootState$1 as d, add2dImage as f, recordGpsEvent as g, markReferencePoint as h, LatLong$1 as i, RecorderStore as l, createRecorderStore as m, CombinedRootState as n, RawDeviceOrientation as o, calcRelativeCoordsInMeters$1 as p, GpsPoint$1 as r, RawGpsPoint$1 as s, AppDispatch as t, RecorderStoreOptions as u };

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

@@ -0,0 +1,77 @@
+import { t as SubscribableStore } from "./subscribe-to-selector-UTZ0KkAc.js";
+import { LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/state/store-subscribers.d.ts
+/**
+ * Dependencies injected into wireStoreSubscribers.
+ * Uses minimal interfaces — callers pass the real singletons or test mocks.
+ */
+interface StoreSubscriberDeps {
+  /** Apply alignment matrix to the AR world group (from webxr-session.ts). */
+  applyAlignmentMatrix: (matrix: Matrix4) => void;
+  /** GPS event visualizer — adds raw + fused marker spheres. */
+  gpsEventVisualizer: {
+    getZeroRef: () => LatLong | null;
+    setZeroRef: (zero: LatLong) => void;
+    addGpsEvent: (gpsCoords: Vector3, odomPosition: Vector3) => void;
+    addAlignmentSnapshot: (nuePosition: Vector3) => void;
+  };
+  /** Map overlay — updates the 2D map position. Nullable (not present in all modes). */
+  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;
+  } | null;
+  /**
+   * Optional callback invoked with the GPS world-space coordinates of each
+   * newly visualized GPS event. Used in replay mode to auto-follow the orbit
+   * camera target to the latest position (Risk R9 fix).
+   *
+   * Not provided in live recording mode (camera is XR-controlled).
+   */
+  onNewGpsPosition?: (coords: Vector3) => void;
+  /**
+   * Optional callback invoked with the odom position and rotation of each
+   * newly dispatched GPS event. Used in replay mode to update the arpose
+   * Object3D so the camera follows the recorded AR trajectory.
+   *
+   * Not provided in live recording mode (arpose stays at identity).
+   */
+  onNewOdomPose?: (odomPosition: Vector3, odomRotation: Quaternion) => void;
+  /**
+   * Optional callback invoked with the transformed NUE position each time
+   * an alignment snapshot is captured. Used in replay mode to update the
+   * orbit camera target to the snapshot position (Issue #3).
+   */
+  onAlignmentSnapshot?: (nuePosition: Vector3) => void;
+  /**
+   * Optional callback invoked with raw lat/lng of each newly processed GPS
+   * event. Used in live recording to drive ref-point proximity detection
+   * for dynamic button label updates.
+   */
+  onNewGpsLatLng?: (lat: number, lng: number) => void;
+}
+/**
+ * Wire store state-change subscriptions to visualization dependencies.
+ *
+ * Uses subscribeToSelector to decompose the monolithic subscriber into
+ * focused, change-gated callbacks:
+ * 1. Alignment matrix changes → apply matrix + capture snapshots
+ * 2. GPS position changes → incremental event visualization + map overlay
+ * 3. Reference point changes → forward to map overlay
+ *
+ * Each subscription uses reference equality to detect changes — callbacks
+ * only fire when the selector output actually differs between dispatches.
+ *
+ * Each call creates **fresh subscriptions** — no manual reset needed between
+ * sessions. Call the returned unsubscribe function to tear down all.
+ *
+ * @param store — any object satisfying SubscribableStore (RecorderStore, replay store, mock)
+ * @param deps  — visualization dependencies (real singletons or test mocks)
+ * @returns An unsubscribe function that removes all listeners from the store.
+ */
+declare function wireStoreSubscribers(store: SubscribableStore, deps: StoreSubscriberDeps): () => void;
+//#endregion
+export { wireStoreSubscribers as n, StoreSubscriberDeps as t };

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

@@ -0,0 +1,26 @@
+import { n as CombinedRootState } from "./store-C7PKOj8S.js";
+
+//#region ../src/state/subscribe-to-selector.d.ts
+/**
+ * Minimal store interface for selector subscriptions.
+ * Both RecorderStore (live) and replay stores satisfy this.
+ */
+interface SubscribableStore {
+  getState: () => CombinedRootState;
+  subscribe: (listener: () => void) => () => void;
+}
+/**
+ * Subscribe to a specific derived value from the store, invoking `onChange`
+ * only when the selector result changes by strict reference equality (`!==`).
+ *
+ * This replaces the `let lastX = …; if (current !== lastX) { … }` pattern
+ * previously used in store-subscribers.ts.
+ *
+ * @param store    — subscribable store instance
+ * @param selector — pure function extracting a value from state
+ * @param onChange — callback receiving (current, previous) when the value changes
+ * @returns unsubscribe function
+ */
+declare function subscribeToSelector<T>(store: SubscribableStore, selector: (state: CombinedRootState) => T, onChange: (current: T, previous: T | undefined) => void): () => void;
+//#endregion
+export { subscribeToSelector as n, SubscribableStore as t };