gps-plus-slam-app-framework 1.0.0

package/dist/file-system-BsQgYCU3.d.ts

@@ -0,0 +1,128 @@
+import { n as ArPoseTuples } from "./ar-types-B-ORgk6Z.js";
+import { n as SessionMetadata } from "./opfs-storage-ChOzF_Wp.js";
+import { LatLongAlt } from "gps-plus-slam-js";
+
+//#region ../src/storage/file-system.d.ts
+/**
+ * Reset module state - exported for testing only
+ * @internal
+ */
+declare function resetStorageState(): void;
+/**
+ * Reset session-level state for a new recording.
+ *
+ * Clears scenario/session names and OPFS session handles, but preserves
+ * `storageInitialized` and the OPFS root so `initStorage()` doesn't need
+ * to be called again.
+ *
+ * Used during soft reset for new recordings (Issue 4, 2026-02-06 user feedback).
+ */
+declare function resetForNewSession(): void;
+/**
+ * Result of write access verification.
+ */
+interface WriteAccessResult {
+  /** Whether write access was successfully verified */
+  success: boolean;
+  /** Error message if write verification failed */
+  error?: string;
+}
+/**
+ * Verify that we have actual write access to a directory.
+ *
+ * This probes the directory by creating a test file, writing content,
+ * and cleaning up. This catches cases where showDirectoryPicker grants
+ * a handle but the underlying file system is read-only.
+ *
+ * User Feedback Issue #1: Even with mode: 'readwrite', Android can
+ * return a handle where getFileHandle({create: true}) succeeds but
+ * createWritable() fails with NoModificationAllowedError.
+ *
+ * @param dirHandle - Directory handle to verify
+ * @returns Success status and optional error message
+ */
+declare function verifyWriteAccess(dirHandle: FileSystemDirectoryHandle): Promise<WriteAccessResult>;
+/**
+ * Initialize storage using OPFS.
+ *
+ * This replaces the old showDirectoryPicker approach which failed on Android Chrome.
+ * OPFS is automatically available and doesn't require user folder selection.
+ *
+ * @returns List of existing scenario folder names
+ * @throws Error if OPFS is not supported
+ */
+declare function initStorage(): Promise<string[]>;
+/**
+ * Create or open a scenario folder, then create a new session folder.
+ *
+ * Now uses OPFS backend instead of showDirectoryPicker.
+ *
+ * @param scenarioName - Name of the scenario
+ */
+declare function startSession(scenarioName: string): Promise<{
+  scenarioPath: string;
+  sessionPath: string;
+}>;
+/**
+ * Write a Redux action to OPFS as a JSON file.
+ */
+declare function writeAction(action: unknown, index: number): Promise<void>;
+/**
+ * Write a captured frame image to OPFS.
+ */
+declare function writeFrame(blob: Blob, index: number): Promise<void>;
+/**
+ * Write session metadata (session.json) to OPFS.
+ * Contains timing, counts, and user agent for the recording session.
+ */
+declare function writeSessionMetadata(metadata: SessionMetadata): Promise<void>;
+/**
+ * Shape of a parsed action file for type safety
+ */
+interface ParsedRefPointAction {
+  type: string;
+  payload: {
+    id: string;
+    gpsPosition?: LatLongAlt;
+    arPose?: ArPoseTuples;
+  };
+}
+/**
+ * Type guard for reference point actions
+ * Exported for testing
+ */
+declare function isRefPointAction(action: unknown): action is ParsedRefPointAction;
+/**
+ * Load existing reference points from a scenario (across all sessions).
+ * Now uses OPFS storage backend.
+ */
+declare function loadScenarioRefPoints(scenarioName: string): Promise<RefPointRecord[]>;
+/**
+ * Get the current scenario handle (for loading prior sessions).
+ * Now delegates to OPFS storage backend.
+ */
+declare function getCurrentScenarioHandle(): FileSystemDirectoryHandle | null;
+/**
+ * Set the current scenario handle (when user selects a scenario).
+ * With OPFS, we just store the name - the actual handle is retrieved when needed.
+ */
+declare function setCurrentScenario(scenarioName: string): Promise<FileSystemDirectoryHandle | null>;
+/**
+ * Ensure a scenario directory exists in OPFS, creating it if necessary.
+ * Used during OPFS recovery when the scenario directory was lost but ZIP
+ * data is available for restoration.
+ *
+ * Unlike setCurrentScenario() which only reads, this creates on demand.
+ */
+declare function ensureScenarioDirectory(scenarioName: string): Promise<FileSystemDirectoryHandle | null>;
+/**
+ * Reference point record from prior sessions
+ */
+interface RefPointRecord {
+  id: string;
+  sessionName: string;
+  gpsPosition?: LatLongAlt;
+  arPose?: ArPoseTuples;
+}
+//#endregion
+export { initStorage as a, resetForNewSession as c, startSession as d, verifyWriteAccess as f, writeSessionMetadata as h, getCurrentScenarioHandle as i, resetStorageState as l, writeFrame as m, WriteAccessResult as n, isRefPointAction as o, writeAction as p, ensureScenarioDirectory as r, loadScenarioRefPoints as s, RefPointRecord as t, setCurrentScenario as u };

package/dist/file-system-utils-5cWO8Xyv.d.ts

@@ -0,0 +1,24 @@
+//#region ../src/storage/file-system-utils.d.ts
+/**
+ * File System Utilities - Pure Functions
+ *
+ * These are extracted from file-system.ts so they can be tested
+ * without mocking browser APIs.
+ */
+/**
+ * Format a Date as a timestamp string for folder names
+ * @example "2025-02-28_14-30-11utc"
+ */
+declare function formatTimestamp(date: Date): string;
+/**
+ * Format an action file index as a zero-padded filename
+ * @example 42 -> "000042.json"
+ */
+declare function formatActionFilename(index: number): string;
+/**
+ * Format a frame index as a zero-padded filename
+ * @example 42 -> "frame-000042.jpg"
+ */
+declare function formatFrameFilename(index: number): string;
+//#endregion
+export { formatFrameFilename as n, formatTimestamp as r, formatActionFilename as t };

package/dist/format-file-size-onGq0k1Q.d.ts

@@ -0,0 +1,24 @@
+//#region ../src/utils/format-file-size.d.ts
+/**
+ * Format File Size Utility
+ *
+ * Converts byte counts to human-readable file size strings (B, KB, MB, GB).
+ * Used by session summary to display ZIP file statistics.
+ *
+ * @see 2026-02-06 User Feedback Issue #3: ZIP stats on summary screen
+ */
+/**
+ * Format a byte count into a human-readable string.
+ *
+ * @param bytes - Number of bytes (non-negative integer expected)
+ * @returns Formatted string like "512 B", "1.5 KB", "23.4 MB", "1.0 GB"
+ *
+ * @example
+ * formatFileSize(0)          // "0 B"
+ * formatFileSize(512)        // "512 B"
+ * formatFileSize(1048576)    // "1.0 MB"
+ * formatFileSize(2500000000) // "2.3 GB"
+ */
+declare function formatFileSize(bytes: number): string;
+//#endregion
+export { formatFileSize as t };

package/dist/fused-path-DtqCSqJh.d.ts

@@ -0,0 +1,25 @@
+import { t as GpsCoord } from "./geo-types-Xx-LVcnw.js";
+import { LatLong, Matrix4, Vector3, fusedGpsFromOdom } from "gps-plus-slam-js";
+
+//#region ../src/utils/fused-path.d.ts
+/** Input data for computing the fused path */
+interface FusedPathInput {
+  /** Odometry positions in AR-local coordinates */
+  odometryPositions: ReadonlyArray<Vector3>;
+  /** Alignment matrix from the solver (null if not computed yet) */
+  alignmentMatrix: Matrix4 | null;
+  /** GPS origin for ENU conversion (null if no GPS data) */
+  zeroRef: LatLong | null;
+}
+/**
+ * Compute the fused GPS path from odometry positions using the alignment matrix.
+ *
+ * Each odometry position is transformed by the alignment matrix to get ENU
+ * coordinates (meters relative to zeroRef), then converted to GPS lat/lng.
+ *
+ * @param input - Odometry positions, alignment matrix, and GPS zero reference
+ * @returns Array of GPS coordinates suitable for Leaflet polyline
+ */
+declare function computeFusedPath(input: FusedPathInput): GpsCoord[];
+//#endregion
+export { computeFusedPath as n, fusedGpsFromOdom as r, FusedPathInput as t };

package/dist/geo-types-Xx-LVcnw.d.ts

@@ -0,0 +1,29 @@
+//#region ../src/types/geo-types.d.ts
+/**
+ * Shared Geo Types
+ *
+ * Canonical definitions for Leaflet-convention GPS coordinate types
+ * (uses `lng`, NOT `lon`). Consolidates formerly duplicated interfaces
+ * from fused-path.ts and summary-map.ts, and replaces inline
+ * `{ lat: number; lng: number }` shapes across the codebase.
+ *
+ * NOTE: The library (`gps-plus-slam-js`) exports `LatLong` which uses
+ * `lon` (not `lng`). These two types are intentionally distinct —
+ * `GpsCoord` uses Leaflet's `lng` convention for UI/map code.
+ *
+ * @see 2026-03-03-code-review-inline-type-duplication.md Finding #3
+ */
+/** A GPS coordinate using the Leaflet convention (lat/lng). */
+interface GpsCoord {
+  readonly lat: number;
+  readonly lng: number;
+}
+/**
+ * A reference point with GPS location and a human-readable name.
+ * Extends GpsCoord so it is usable wherever GpsCoord is expected.
+ */
+interface RefPointMarker extends GpsCoord {
+  readonly name: string;
+}
+//#endregion
+export { RefPointMarker as n, GpsCoord as t };

package/dist/gps-Ddzr2KlX.d.ts

@@ -0,0 +1,54 @@
+//#region ../src/sensors/gps.d.ts
+/**
+ * GPS Module
+ *
+ * Handles Geolocation API access and device orientation/compass.
+ */
+interface GpsPosition {
+  readonly lat: number;
+  readonly lon: number;
+  readonly altitude: number | null;
+  readonly accuracy: number;
+  readonly altitudeAccuracy: number | null;
+  readonly heading: number | null;
+  readonly speed: number | null;
+  readonly timestamp: number;
+}
+/**
+ * Raw device orientation from the browser's DeviceOrientationEvent API.
+ * Fields are nullable because sensors may be unavailable on some devices.
+ * See also: DeviceOrientation in ar/tracking-state.ts (resolved, non-nullable).
+ */
+interface RawDeviceOrientation {
+  alpha: number | null;
+  beta: number | null;
+  gamma: number | null;
+  absolute: boolean;
+}
+type GpsCallback = (position: GpsPosition) => void;
+type OrientationCallback = (orientation: RawDeviceOrientation) => void;
+/**
+ * Start watching GPS position.
+ * Idempotent: clears any existing watch before starting a new one
+ * (Issue 4, 2026-02-27 user feedback — prevents watch leaks when
+ * transitioning from warm-up to recording watch).
+ */
+declare function startGpsWatch(onPosition: GpsCallback, onError?: (error: GeolocationPositionError) => void): void;
+/**
+ * Stop watching GPS position
+ */
+declare function stopGpsWatch(): void;
+/**
+ * Start listening for device orientation (compass)
+ */
+declare function startOrientationWatch(onOrientation: OrientationCallback): void;
+/**
+ * Stop listening for device orientation
+ */
+declare function stopOrientationWatch(): void;
+/**
+ * Request permission for device orientation (required on iOS 13+)
+ */
+declare function requestOrientationPermission(): Promise<boolean>;
+//#endregion
+export { startOrientationWatch as a, startGpsWatch as i, RawDeviceOrientation as n, stopGpsWatch as o, requestOrientationPermission as r, stopOrientationWatch as s, GpsPosition as t };

package/dist/gps-compass-cubes-C-6JEnpR.d.ts

@@ -0,0 +1,22 @@
+import * as THREE from "three";
+
+//#region ../src/visualization/gps-compass-cubes.d.ts
+/** Side length of each compass cube in metres. */
+declare const COMPASS_CUBE_SIZE = 0.1;
+/** Distance from origin to each compass cube in metres. */
+declare const COMPASS_CUBE_DISTANCE = 1;
+interface GpsCompassCubes {
+  /** The container Group — add this (or its parent) to the scene. */
+  readonly group: THREE.Group;
+  /** Remove the group from its parent and dispose resources. */
+  dispose(): void;
+}
+/**
+ * Create compass cubes and attach them to a parent Object3D.
+ *
+ * @param parent The Object3D to anchor the compass group to
+ *               (typically the CameraFollower).
+ */
+declare function createGpsCompassCubes(parent: THREE.Object3D): GpsCompassCubes;
+//#endregion
+export { createGpsCompassCubes as i, COMPASS_CUBE_SIZE as n, GpsCompassCubes as r, COMPASS_CUBE_DISTANCE as t };

package/dist/gps-error-handler-VPuNOuf8.d.ts

@@ -0,0 +1,40 @@
+//#region ../src/sensors/gps-error-handler.d.ts
+/**
+ * GPS Error Handler
+ *
+ * Provides user-facing error messages for GPS failures.
+ * Separates error handling logic from GPS module for testability.
+ */
+/**
+ * GPS error codes from the Geolocation API.
+ * Duplicated here to avoid depending on browser types in tests.
+ */
+declare const GPS_ERROR_CODES: {
+  readonly PERMISSION_DENIED: 1;
+  readonly POSITION_UNAVAILABLE: 2;
+  readonly TIMEOUT: 3;
+};
+/**
+ * User-friendly error messages for each GPS error type.
+ */
+declare const GPS_ERROR_MESSAGES: Record<number, string>;
+/**
+ * Default message for unknown error codes.
+ */
+declare const GPS_ERROR_MESSAGE_UNKNOWN = "GPS error. Check your device settings.";
+/**
+ * Get a user-friendly error message for a GPS error.
+ *
+ * @param error - The GeolocationPositionError from the browser API
+ * @returns A user-friendly error message
+ */
+declare function getGpsErrorMessage(error: GeolocationPositionError): string;
+/**
+ * Create a GPS error handler that logs and shows user-facing errors.
+ *
+ * @param showError - Function to display error to user (e.g., from hud.ts)
+ * @returns A function suitable for use as startGpsWatch's onError callback
+ */
+declare function createGpsErrorHandler(showError: (message: string) => void): (error: GeolocationPositionError) => void;
+//#endregion
+export { getGpsErrorMessage as a, createGpsErrorHandler as i, GPS_ERROR_MESSAGES as n, GPS_ERROR_MESSAGE_UNKNOWN as r, GPS_ERROR_CODES as t };

package/dist/gps-event-markers-DpEy2qRd.d.ts

@@ -0,0 +1,67 @@
+import { LatLong, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/visualization/gps-event-markers.d.ts
+/**
+ * Manager for GPS event visualization
+ */
+declare class GpsEventVisualizer {
+  private rawGpsMarkers;
+  private fusedMarkers;
+  private snapshotMarkers;
+  private zeroRef;
+  private eventCounter;
+  private snapshotCounter;
+  /**
+   * Set the GPS zero reference (origin for coordinate conversion).
+   * Must be called before adding GPS events.
+   *
+   * @param zero - GPS coordinates of the origin
+   */
+  setZeroRef(zero: LatLong): void;
+  /**
+   * Get the current zero reference
+   */
+  getZeroRef(): LatLong | null;
+  /**
+   * Add a GPS event to the visualization.
+   * Creates both a raw GPS marker and a fused alignment marker.
+   *
+   * @param gpsCoords - GPS position as [x, y, z] meters from zero reference
+   * @param odomPosition - AR odometry position at the time of GPS reading
+   */
+  addGpsEvent(gpsCoords: Vector3, odomPosition: Vector3): void;
+  /**
+   * Add an alignment snapshot marker at the given NUE position.
+   * Snapshots represent the system's best GPS estimate at each alignment update.
+   * Added to scene root (GPS world space), not arWorldGroup.
+   */
+  addAlignmentSnapshot(nuePosition: Vector3): void;
+  /**
+   * Get the NUE positions of all alignment snapshot markers.
+   * Used at session end to convert to GPS coordinates for the summary map.
+   */
+  getAlignmentSnapshotPositions(): Vector3[];
+  /**
+   * Create a sphere marker mesh with the given color and name.
+   */
+  private createMarkerMesh;
+  /**
+   * Clear all markers from the scene and reset state.
+   */
+  clearAll(): void;
+  /**
+   * Get count of visible markers.
+   */
+  getCounts(): {
+    raw: number;
+    fused: number;
+    snapshots: number;
+  };
+}
+/**
+ * Singleton instance for global use.
+ * Import this to visualize GPS events.
+ */
+declare const gpsEventVisualizer: GpsEventVisualizer;
+//#endregion
+export { gpsEventVisualizer as n, GpsEventVisualizer as t };

package/dist/h3-ref-point-CFhayNSZ.d.ts

@@ -0,0 +1,59 @@
+//#region ../src/ref-points/h3-ref-point.d.ts
+/**
+ * H3 Reference Point Matching
+ *
+ * Utility for matching GPS positions to known reference points using
+ * H3 hexagonal grid indices. Uses gridDisk(cell, 1) to create a ~65m
+ * safe zone that absorbs GPS jitter of 3-10m.
+ *
+ * @see docs/2026-03-08-ref-point-naming-investigation.md §6
+ */
+/** H3 resolution 11: ~25m edge, ~65m gridDisk safe zone */
+declare const H3_RESOLUTION = 11;
+/**
+ * A known reference point with its H3 cell index and GPS coordinates,
+ * used for proximity matching. GPS coordinates are needed to rank
+ * multiple candidates by distance when their gridDisk zones overlap.
+ */
+interface KnownRefPoint {
+  readonly h3Index: string;
+  readonly displayName?: string;
+  readonly lat: number;
+  readonly lon: number;
+}
+/**
+ * Compute the H3 resolution-11 index for a GPS position.
+ */
+declare function gpsToH3(lat: number, lng: number): string;
+/**
+ * Approximate distance in metres using equirectangular projection.
+ * Accurate to < 0.1% for distances under 1 km at mid-latitudes,
+ * which is sufficient for ranking ref point candidates within a
+ * gridDisk safe zone (~65–130 m).
+ */
+declare function approxDistanceMetres(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Find the known reference point closest to the given GPS position,
+ * provided it falls within the gridDisk safe zone.
+ *
+ * The safe zone is the center cell plus its 6 neighbors (~65m radius),
+ * which absorbs GPS jitter of 3-10m while keeping ref points >130m apart
+ * distinguishable.
+ *
+ * When multiple ref points have overlapping safe zones (65–130 m apart),
+ * the closest one by equirectangular distance is returned.
+ */
+declare function findNearbyRefPoint(lat: number, lng: number, knownRefPoints: readonly KnownRefPoint[]): KnownRefPoint | undefined;
+/**
+ * Check whether two H3 indices refer to the same physical location
+ * (i.e., one falls within the other's gridDisk safe zone).
+ * This is the canonical cross-session matching check.
+ */
+declare function h3RefsMatch(h3a: string, h3b: string): boolean;
+/**
+ * Check whether a string looks like a valid H3 resolution-11 index.
+ * Used to distinguish H3 IDs from legacy user-typed string IDs.
+ */
+declare function isH3Index(id: string): boolean;
+//#endregion
+export { gpsToH3 as a, findNearbyRefPoint as i, KnownRefPoint as n, h3RefsMatch as o, approxDistanceMetres as r, isH3Index as s, H3_RESOLUTION as t };

package/dist/image-capture-2pKjYUS6.d.ts

@@ -0,0 +1,130 @@
+import { a as WebXRQuaternion, o as WebXRVec3, t as ARPose } from "./ar-types-B-ORgk6Z.js";
+
+//#region ../src/ar/image-capture.d.ts
+/**
+ * Minimum expected blob size in bytes for a valid JPEG image.
+ * A black/empty 1920x1080 JPEG still compresses to ~2-3KB due to headers.
+ * A real camera frame at 0.7 quality should be 50KB+.
+ * We use a conservative threshold to catch obviously broken captures.
+ */
+declare const MIN_VALID_IMAGE_BYTES = 5000;
+/**
+ * Configuration for image capture timing and quality
+ */
+interface ImageCaptureConfig {
+  /** Minimum interval between captures in milliseconds (default: 2000) */
+  intervalMs: number;
+  /** JPEG quality 0.0-1.0 (default: 0.7) */
+  quality: number;
+  /** Safety timeout for captureInProgress flag in milliseconds (default: 5000).
+   *  If a capture promise doesn't resolve within this duration, the flag is
+   *  force-reset to prevent permanent pipeline deadlock. */
+  captureTimeoutMs: number;
+}
+/**
+ * Default capture configuration
+ */
+declare const DEFAULT_CAPTURE_CONFIG: ImageCaptureConfig;
+/**
+ * Data returned when an image is captured
+ */
+interface CapturedImage {
+  /** The captured image as a Blob */
+  readonly blob: Blob;
+  /** Epoch milliseconds when captured */
+  readonly timestamp: number;
+  /** Frame index (0-based, increments each capture) */
+  readonly frameIndex: number;
+  /** Camera position when captured */
+  readonly position: WebXRVec3;
+  /** Camera rotation when captured */
+  readonly rotation: WebXRQuaternion;
+  /** Device screen orientation (0, 90, 180, 270) */
+  readonly screenRotation: number;
+}
+/**
+ * Callbacks for image capture integration
+ */
+interface ImageCaptureCallbacks {
+  /** Get current AR pose (position + orientation) */
+  getCurrentPose: () => ARPose | null;
+  /** Get device screen rotation (0, 90, 180, 270) */
+  getScreenRotation: () => number;
+  /** Called when an image is successfully captured */
+  onCaptured: (image: CapturedImage) => void;
+  /** Called when image capture fails (e.g., toBlob returns null on low memory) */
+  onCaptureFailed?: () => void;
+  /**
+   * Called when a captured image appears suspicious (likely black/empty).
+   * This can happen on mobile devices when WebGL hasn't composited the frame yet.
+   * The image is still saved (for debugging) but this callback allows logging.
+   */
+  onSuspiciousImage?: (blobSize: number, frameIndex: number) => void;
+  /**
+   * Optional custom frame capture function.
+   * When provided, this is used instead of canvas.toBlob() for capturing frames.
+   * This enables the "blit" technique for WebXR opaque textures that cannot
+   * be read directly via canvas.toBlob() (which returns black pixels).
+   *
+   * @param quality - JPEG quality 0.0-1.0
+   * @returns Promise resolving to a JPEG Blob, or null if capture fails
+   * @see docs/2026-02-06-bug-camera-frames-black.md
+   */
+  captureFrame?: (quality: number) => Promise<Blob | null>;
+}
+/**
+ * Manages periodic image capture from a canvas.
+ *
+ * Usage:
+ * 1. Create with canvas and callbacks
+ * 2. Call start() when recording begins
+ * 3. Call onFrame(time) each XR frame
+ * 4. Call stop() when recording ends
+ */
+declare class ImageCaptureManager {
+  private canvas;
+  private callbacks;
+  private config;
+  private capturing;
+  private lastCaptureTime;
+  private frameCount;
+  private captureInProgress;
+  private captureTimeoutId;
+  constructor(canvas: HTMLCanvasElement, callbacks: ImageCaptureCallbacks, config?: ImageCaptureConfig);
+  /**
+   * Start capturing images.
+   * Resets frame counter and last capture time.
+   */
+  start(): void;
+  /**
+   * Stop capturing images.
+   * Clears any pending safety timeout and resets in-flight capture state.
+   */
+  stop(): void;
+  /**
+   * Check if capture manager is active.
+   */
+  isCapturing(): boolean;
+  /**
+   * Get the current frame count.
+   */
+  getFrameCount(): number;
+  /**
+   * Called each XR frame to check if a capture is needed.
+   *
+   * @param time - Frame timestamp in milliseconds (from requestAnimationFrame)
+   */
+  onFrame(time: number): void;
+  /**
+   * Clear the safety timeout for captureInProgress.
+   * Called when capture completes (success or failure) before the timeout fires.
+   */
+  private clearCaptureTimeout;
+  /**
+   * Common handler for captured blobs (from either canvas.toBlob or captureFrame).
+   * Handles null blobs, suspicious image detection, and dispatching onCaptured.
+   */
+  private handleCapturedBlob;
+}
+//#endregion
+export { ImageCaptureManager as a, ImageCaptureConfig as i, DEFAULT_CAPTURE_CONFIG as n, MIN_VALID_IMAGE_BYTES as o, ImageCaptureCallbacks as r, CapturedImage as t };