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

package/dist/storage/ref-point-recovery.d.ts

@@ -1,28 +0,0 @@
-import { t as RefPointDefinition } from "../ref-point-loader-Pt1smgHS.js";
-
-//#region ../src/storage/ref-point-recovery.d.ts
-/**
- * Result of recovering ref point definitions from ZIP files.
- */
-interface RefPointRecoveryResult {
-  /** Merged, deduplicated RefPointDefinition objects from all ZIPs */
-  readonly definitions: RefPointDefinition[];
-  /** Number of ZIP files successfully scanned */
-  readonly zipFilesScanned: number;
-  /** Error messages from failed ZIPs or malformed ref points */
-  readonly errors: string[];
-}
-/**
- * Extract full RefPointDefinition objects from all ZIPs in a folder,
- * merge observations by ref point ID, and return the merged definitions.
- *
- * Unlike importRefPointsFromFolder() which returns simplified ImportedRefPoint[],
- * this preserves full observation data (AR poses, GPS, timestamps) needed for
- * 3D display and OPFS recovery.
- *
- * @param folderHandle - Read-only directory handle from showDirectoryPicker
- * @returns Result containing merged definitions, scan count, and errors
- */
-declare function recoverRefPointDefinitionsFromZips(folderHandle: FileSystemDirectoryHandle): Promise<RefPointRecoveryResult>;
-//#endregion
-export { RefPointRecoveryResult, recoverRefPointDefinitionsFromZips };

package/dist/storage/ref-point-recovery.js

@@ -1,159 +0,0 @@
-import { createLogger } from "../utils/logger.js";
-import { BlobReader, TextWriter, ZipReader } from "@zip.js/zip.js";
-//#region ../src/storage/ref-point-recovery.ts
-/**
-* Reference Point Recovery Module
-*
-* Extracts full RefPointDefinition objects from ZIP files in a folder and
-* merges observations by ref point ID. Unlike ref-point-importer.ts (which
-* returns simplified ImportedRefPoint with only lat/lon), this module
-* preserves complete observation data (AR poses, GPS, timestamps) needed
-* for 3D display and OPFS restoration after browser data loss.
-*
-* Used by the recovery flow: when OPFS is empty after browser data clear,
-* this module reconstructs the full scenario-level ref point state from
-* session ZIPs so the user can continue recording with prior ref points visible.
-*
-* Uses @zip.js/zip.js for ZIP reading (same library as zip-export.ts
-* and ref-point-importer.ts).
-*/
-const log = createLogger("RefPointRecovery");
-function isZipFileName(name) {
-	return name.toLowerCase().endsWith(".zip");
-}
-function isRefPointEntry(entryPath) {
-	return entryPath.startsWith("refPoints/") && entryPath.endsWith(".json") && entryPath !== "refPoints/";
-}
-/**
-* Validate parsed JSON matches RefPointDefinition shape.
-* Looser than ref-point-loader's validator: accepts empty observations
-* (schema-valid, preserves identity) and doesn't require arPose/gpsPoint
-* validation on every observation (the importer's validator already checks
-* first obs structure).
-*/
-function isValidRefPointDefinition(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const obj = value;
-	if (typeof obj.id !== "string" || typeof obj.name !== "string" || typeof obj.createdAt !== "number" || !Array.isArray(obj.observations)) return false;
-	return true;
-}
-/**
-* Extract full RefPointDefinition objects from a single ZIP file.
-*/
-async function extractDefinitionsFromZip(zipBlob, zipFileName) {
-	const definitions = [];
-	const errors = [];
-	const zipReader = new ZipReader(new BlobReader(zipBlob));
-	try {
-		const entries = await zipReader.getEntries();
-		for (const entry of entries) {
-			if (entry.directory) continue;
-			if (!isRefPointEntry(entry.filename)) continue;
-			try {
-				const textWriter = new TextWriter();
-				const jsonText = await entry.getData(textWriter);
-				let parsed;
-				try {
-					parsed = JSON.parse(jsonText);
-				} catch (parseErr) {
-					errors.push(`${zipFileName}/${entry.filename}: Invalid JSON - ${parseErr.message}`);
-					continue;
-				}
-				if (!isValidRefPointDefinition(parsed)) {
-					errors.push(`${zipFileName}/${entry.filename}: Invalid ref point schema`);
-					continue;
-				}
-				definitions.push(parsed);
-			} catch (entryErr) {
-				errors.push(`${zipFileName}/${entry.filename}: ${entryErr.message}`);
-			}
-		}
-	} finally {
-		await zipReader.close();
-	}
-	return {
-		definitions,
-		errors
-	};
-}
-/**
-* Merge observations from multiple RefPointDefinitions with the same ID.
-* Deduplicates observations by sessionId + timestamp.
-* Uses earliest createdAt and first-encountered name.
-*/
-function mergeDefinitions(allDefs) {
-	const byId = /* @__PURE__ */ new Map();
-	for (const def of allDefs) {
-		let entry = byId.get(def.id);
-		if (!entry) {
-			entry = {
-				def: {
-					id: def.id,
-					name: def.name,
-					createdAt: def.createdAt,
-					observations: []
-				},
-				seen: /* @__PURE__ */ new Set()
-			};
-			byId.set(def.id, entry);
-		} else if (def.createdAt < entry.def.createdAt) entry.def.createdAt = def.createdAt;
-		for (const obs of def.observations) {
-			const key = `${obs.sessionId}:${obs.timestamp}`;
-			if (!entry.seen.has(key)) {
-				entry.seen.add(key);
-				entry.def.observations.push(obs);
-			}
-		}
-	}
-	return Array.from(byId.values()).map((e) => e.def).sort((a, b) => a.createdAt - b.createdAt);
-}
-/**
-* Extract full RefPointDefinition objects from all ZIPs in a folder,
-* merge observations by ref point ID, and return the merged definitions.
-*
-* Unlike importRefPointsFromFolder() which returns simplified ImportedRefPoint[],
-* this preserves full observation data (AR poses, GPS, timestamps) needed for
-* 3D display and OPFS recovery.
-*
-* @param folderHandle - Read-only directory handle from showDirectoryPicker
-* @returns Result containing merged definitions, scan count, and errors
-*/
-async function recoverRefPointDefinitionsFromZips(folderHandle) {
-	const allDefinitions = [];
-	const allErrors = [];
-	let zipFilesScanned = 0;
-	log.info(`Recovery scan: ${folderHandle.name}`);
-	try {
-		for await (const entry of folderHandle.values()) {
-			if (entry.kind !== "file" || !isZipFileName(entry.name)) continue;
-			log.debug(`Processing ZIP: ${entry.name}`);
-			try {
-				const { definitions, errors } = await extractDefinitionsFromZip(await entry.getFile(), entry.name);
-				zipFilesScanned++;
-				allErrors.push(...errors);
-				allDefinitions.push(...definitions);
-			} catch (zipErr) {
-				const errorMsg = `Failed to process ${entry.name}: ${zipErr.message}`;
-				log.warn(errorMsg);
-				allErrors.push(errorMsg);
-			}
-		}
-		const merged = mergeDefinitions(allDefinitions);
-		log.info(`Recovered ${merged.length} ref points from ${zipFilesScanned} ZIP files`);
-		return {
-			definitions: merged,
-			zipFilesScanned,
-			errors: allErrors
-		};
-	} catch (err) {
-		const errorMsg = `Failed to scan folder: ${err.message}`;
-		log.error(errorMsg);
-		return {
-			definitions: mergeDefinitions(allDefinitions),
-			zipFilesScanned,
-			errors: [...allErrors, errorMsg]
-		};
-	}
-}
-//#endregion
-export { recoverRefPointDefinitionsFromZips };

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

@@ -1,20 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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/visualization/reference-points.d.ts

@@ -1,2 +0,0 @@
-import { n as refPointVisualizer, t as RefPointVisualizer } from "../reference-points-CFWy8_wj.js";
-export { RefPointVisualizer, refPointVisualizer };

package/dist/visualization/reference-points.js

@@ -1,160 +0,0 @@
-import { createLogger } from "../utils/logger.js";
-import { disposeMeshArray } from "./three-dispose.js";
-import { getScene } from "../ar/webxr-session.js";
-import { VIS_COLORS } from "./vis-colors.js";
-import * as THREE from "three";
-import { calcRelativeCoordsInMeters } from "gps-plus-slam-js";
-//#region ../src/visualization/reference-points.ts
-/**
-* Reference Point Visualizer
-*
-* Creates and manages Three.js meshes for visualizing reference points
-* in GPS-aligned 3D space.
-*
-* ARCHITECTURE NOTE:
-* - Prior reference points (green) are added to scene root (GPS world space)
-* - Current session points (red) are also in GPS world space
-* - Spheres stay in GPS coordinates, independent of alignment matrix
-*/
-const log = createLogger("RefPointVisualizer");
-/** Sphere radius in meters (10cm) */
-const REF_POINT_RADIUS = .1;
-/**
-* Manager for reference point visualization
-*/
-var RefPointVisualizer = class {
-	priorRefMeshes = [];
-	currentRefMeshes = [];
-	zeroRef = null;
-	/** Shared geometry for prior-session ref point meshes (lazy-created) */
-	priorRefGeometry = null;
-	/** Shared material for prior-session ref point meshes (lazy-created) */
-	priorRefMaterial = null;
-	/** Shared geometry for current-session ref point meshes (lazy-created) */
-	currentRefGeometry = null;
-	/**
-	* Set the GPS zero reference (origin for coordinate conversion).
-	* Must be called before displaying reference points.
-	*
-	* @param zero - GPS coordinates of the origin
-	*/
-	setZeroRef(zero) {
-		this.zeroRef = zero;
-	}
-	/**
-	* Get the current zero reference
-	*/
-	getZeroRef() {
-		return this.zeroRef;
-	}
-	/**
-	* Display reference points from prior sessions.
-	* Clears any existing prior ref points first.
-	*
-	* @param refPoints - Array of reference point marks to visualize
-	*/
-	displayPriorRefPoints(refPoints) {
-		if (!this.zeroRef) {
-			log.warn("No zero reference set");
-			return;
-		}
-		const scene = getScene();
-		if (!scene) {
-			log.warn("Scene not available");
-			return;
-		}
-		this.clearPriorRefPoints();
-		const geometry = this.priorRefGeometry ??= new THREE.SphereGeometry(REF_POINT_RADIUS, 16, 16);
-		const material = this.priorRefMaterial ??= new THREE.MeshBasicMaterial({ color: VIS_COLORS.PRIOR_REF_POINT.hex });
-		let visibleCount = 0;
-		for (const refPoint of refPoints) {
-			if (!refPoint.gpsPosition) continue;
-			const coords = calcRelativeCoordsInMeters(this.zeroRef, {
-				lat: refPoint.gpsPosition.lat,
-				lon: refPoint.gpsPosition.lon
-			}, refPoint.gpsPosition.altitude ?? 0, 0);
-			const mesh = new THREE.Mesh(geometry, material);
-			mesh.position.set(coords[0], coords[1], coords[2]);
-			mesh.name = `prior-ref-${refPoint.id}`;
-			scene.add(mesh);
-			this.priorRefMeshes.push(mesh);
-			visibleCount++;
-		}
-		log.info(`Displayed ${visibleCount}/${refPoints.length} prior reference points`);
-	}
-	/**
-	* Add a reference point from the current session.
-	*
-	* @param refPoint - Reference point mark to visualize
-	*/
-	addCurrentRefPoint(refPoint) {
-		if (!this.zeroRef || !refPoint.gpsPosition) {
-			log.warn("Cannot add current ref point - missing zero ref or GPS position");
-			return;
-		}
-		const scene = getScene();
-		if (!scene) {
-			log.warn("Scene not available");
-			return;
-		}
-		const coords = calcRelativeCoordsInMeters(this.zeroRef, {
-			lat: refPoint.gpsPosition.lat,
-			lon: refPoint.gpsPosition.lon
-		}, refPoint.gpsPosition.altitude ?? 0, 0);
-		const geometry = this.currentRefGeometry ??= new THREE.SphereGeometry(REF_POINT_RADIUS, 16, 16);
-		const material = new THREE.MeshBasicMaterial({ color: VIS_COLORS.CURRENT_REF_POINT.hex });
-		const mesh = new THREE.Mesh(geometry, material);
-		mesh.position.set(coords[0], coords[1], coords[2]);
-		mesh.name = `current-ref-${refPoint.id}`;
-		scene.add(mesh);
-		this.currentRefMeshes.push(mesh);
-		log.info(`Added current ref point: ${refPoint.id}`);
-	}
-	/**
-	* Clear all prior reference point meshes from the scene.
-	*/
-	clearPriorRefPoints() {
-		const scene = getScene();
-		disposeMeshArray(this.priorRefMeshes, scene, {
-			skipGeometry: true,
-			skipMaterial: true
-		});
-		this.priorRefGeometry?.dispose();
-		this.priorRefGeometry = null;
-		this.priorRefMaterial?.dispose();
-		this.priorRefMaterial = null;
-	}
-	/**
-	* Clear current session reference point meshes from the scene.
-	*/
-	clearCurrentRefPoints() {
-		const scene = getScene();
-		disposeMeshArray(this.currentRefMeshes, scene, { skipGeometry: true });
-		this.currentRefGeometry?.dispose();
-		this.currentRefGeometry = null;
-	}
-	/**
-	* Clear all visualizations and reset state.
-	*/
-	clearAll() {
-		this.clearPriorRefPoints();
-		this.clearCurrentRefPoints();
-		this.zeroRef = null;
-	}
-	/**
-	* Get count of visible reference points.
-	*/
-	getCounts() {
-		return {
-			prior: this.priorRefMeshes.length,
-			current: this.currentRefMeshes.length
-		};
-	}
-};
-/**
-* Singleton instance for global use.
-* Import this to visualize reference points.
-*/
-const refPointVisualizer = new RefPointVisualizer();
-//#endregion
-export { RefPointVisualizer, refPointVisualizer };