gps-plus-slam-app-framework 1.0.0

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

@@ -0,0 +1,181 @@
+//#region ../src/storage/opfs-storage.d.ts
+/**
+ * OPFS Storage Module
+ *
+ * Uses the Origin Private File System (OPFS) API to persist recording data.
+ * 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
+ *       │   │       └── ...
+ *       │   └── ...
+ *       └── ...
+ */
+/**
+ * Session metadata stored in session.json.
+ */
+interface SessionMetadata {
+  /** Schema version for forward compatibility */
+  version: 1;
+  /**
+   * Odometry coordinate convention version.
+   * - Absent (era 1, old recordings): odomPosition in raw WebXR frame [xrX, xrY, xrZ],
+   *   GPS payload uses `gpsPoint` with ENU coordinates and derived fields.
+   * - 2 (era 2): odomPosition in NUE frame [-xrZ, xrY, xrX],
+   *   GPS payload uses `gpsPoint` with NUE coordinates and derived fields.
+   * - 3 (era 3): odomPosition in raw WebXR [xrX, xrY, xrZ],
+   *   GPS payload uses `gpsPoint` with NUE coordinates and derived fields.
+   * - 4 (era 4): odomPosition in raw WebXR [xrX, xrY, xrZ],
+   *   GPS payload uses `rawGpsPoint` (raw sensor fields only, no derived fields).
+   * - 5 (era 5, current): Same action format as era 4. State-side change only:
+   *   reducer now also converts quaternion rotations from WebXR to NUE.
+   * Used during replay to determine whether migration is needed.
+   */
+  odomCoordVersion?: 2 | 3 | 4 | 5;
+  /** ISO 8601 timestamp when recording started */
+  startedAt: string;
+  /** ISO 8601 timestamp when recording ended */
+  endedAt: string;
+  /** Name of the scenario this session belongs to */
+  scenarioName: string;
+  /** Total number of actions recorded */
+  actionCount: number;
+  /** Total number of frames captured */
+  frameCount: number;
+  /** Browser user agent string */
+  userAgent: string;
+  /** Build/environment info for debugging. Optional for backwards compat. */
+  build?: {
+    /** Git commit hash (short, e.g. "a1b2c3d"), or "dev" during local dev without git */commitHash: string; /** App version from package.json (e.g. "0.1.0") */
+    appVersion: string; /** Library version from gps-plus-slam-js package.json */
+    libraryVersion: string; /** Framework version from gps-plus-slam-app-framework package.json */
+    frameworkVersion: string; /** ISO 8601 timestamp of when this build was produced */
+    buildTime: string;
+  };
+  /** The page URL the recording was made from (origin + pathname only). Optional for backwards compat. */
+  pageUrl?: string;
+}
+/**
+ * Result from createSession.
+ */
+interface CreateSessionResult {
+  scenarioName: string;
+  sessionName: string;
+}
+/**
+ * Reset module state - exported for testing only.
+ * @internal
+ */
+declare function resetOpfsStorage(): void;
+/**
+ * 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).
+ */
+declare function resetSessionHandles(): void;
+/**
+ * Initialize OPFS storage by creating the required directory structure.
+ *
+ * Creates:
+ * - /gps-recorder/
+ * - /gps-recorder/scenarios/
+ *
+ * This is idempotent - calling multiple times is safe.
+ *
+ * @throws Error if OPFS is not supported
+ */
+declare function initOpfsStorage(): Promise<void>;
+/**
+ * Create a new recording session within a scenario.
+ *
+ * Creates the directory structure:
+ * - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/
+ * - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/actions/
+ * - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/frames/
+ *
+ * @param scenarioName - Name of the scenario (creates if doesn't exist)
+ * @param timestamp - Session start time (used for folder naming)
+ * @returns Session information
+ * @throws Error if storage not initialized
+ */
+declare function createSession(scenarioName: string, timestamp: Date): Promise<CreateSessionResult>;
+/**
+ * Get the current session directory handle.
+ * Useful for test assertions.
+ * @internal
+ */
+declare function getSessionHandle(): FileSystemDirectoryHandle | null;
+/**
+ * Get the current scenario directory handle.
+ */
+declare function getScenarioHandle(): FileSystemDirectoryHandle | null;
+/**
+ * Get the scenarios root directory handle.
+ * Used for loading reference points across scenarios.
+ */
+declare function getScenariosRootHandle(): FileSystemDirectoryHandle | null;
+/**
+ * Write a Redux action to the current session's actions directory.
+ *
+ * @param action - The action object to write
+ * @param index - Sequential action index (1-based)
+ * @throws Error if no active session
+ */
+declare function writeAction(action: unknown, index: number): Promise<void>;
+/**
+ * Write a frame blob to the current session's frames directory.
+ *
+ * @param blob - Image blob to write
+ * @param index - Sequential frame index (1-based)
+ * @throws Error if no active session
+ */
+declare function writeFrame(blob: Blob, index: number): Promise<void>;
+/**
+ * Write session metadata to session.json in the current session directory.
+ *
+ * @param metadata - Session metadata object
+ * @throws Error if no active session
+ */
+declare function writeSessionMetadata(metadata: SessionMetadata): Promise<void>;
+/**
+ * List all scenario names in OPFS storage.
+ *
+ * @returns Array of scenario folder names
+ */
+declare function listScenarios(): Promise<string[]>;
+/**
+ * List all session names within a scenario.
+ *
+ * @param scenarioName - Name of the scenario
+ * @returns Array of session folder names
+ */
+declare function listSessions(scenarioName: string): Promise<string[]>;
+/**
+ * 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
+ */
+declare function checkStorageQuota(): Promise<{
+  available: number;
+  used: number;
+}>;
+//#endregion
+export { getScenarioHandle as a, initOpfsStorage as c, resetOpfsStorage as d, resetSessionHandles as f, writeSessionMetadata as h, createSession as i, listScenarios as l, writeFrame as m, SessionMetadata as n, getScenariosRootHandle as o, writeAction as p, checkStorageQuota as r, getSessionHandle as s, CreateSessionResult as t, listSessions as u };

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

@@ -0,0 +1,11 @@
+import { n as SessionMetadata } from "./opfs-storage-ChOzF_Wp.js";
+import { t as StorageBackend } from "./storage-backend-BcEItnFr.js";
+
+//#region ../src/storage/opfs-storage-backend.d.ts
+declare class OpfsStorageBackend implements StorageBackend {
+  writeAction(action: unknown, index: number): Promise<void>;
+  writeFrame(blob: Blob, index: number): Promise<void>;
+  writeSessionMetadata(metadata: SessionMetadata): Promise<void>;
+}
+//#endregion
+export { OpfsStorageBackend as t };

package/dist/permission-checker-jO2ziCWC.d.ts

@@ -0,0 +1,146 @@
+//#region ../src/sensors/permission-checker.d.ts
+/**
+ * Permission Checker Module
+ *
+ * Provides utilities to check and verify mandatory device permissions
+ * required for AR+GPS tracking: WebXR (immersive-ar), Camera, and Geolocation.
+ *
+ * This module is used by the setup modal to verify permissions BEFORE
+ * the user enters AR mode, providing clear feedback on what's missing.
+ */
+/**
+ * Individual permission status for a single capability.
+ */
+interface PermissionStatus {
+  /** Whether the permission/feature is supported by the browser/device */
+  supported: boolean;
+  /** Whether permission has been granted (null if not yet requested) */
+  granted: boolean | null;
+  /** Human-readable error message if not supported or denied */
+  error?: string;
+}
+/**
+ * Aggregated status of all mandatory permissions.
+ */
+interface PermissionCheckResult {
+  /** WebXR immersive-ar session support */
+  webxr: PermissionStatus;
+  /** Geolocation API access */
+  geolocation: PermissionStatus;
+  /** Camera access (via getUserMedia) */
+  camera: PermissionStatus;
+  /** Device orientation (compass) - optional but recommended */
+  orientation: PermissionStatus;
+  /** File system access for saving recordings */
+  fileSystem: PermissionStatus;
+  /** Whether all mandatory permissions are ready */
+  allMandatoryReady: boolean;
+}
+/**
+ * Internal state for file system permission tracking.
+ * This tracks whether a folder has been selected and write access verified.
+ */
+interface FileSystemState {
+  folderSelected: boolean;
+  writeVerified: boolean;
+  writeError?: string;
+}
+/**
+ * Reset file system permission state.
+ * Exported for testing purposes.
+ * @internal
+ */
+declare function resetFileSystemState(): void;
+/**
+ * Set file system permission state.
+ * Used by the storage module after folder selection and write verification.
+ * @internal
+ */
+declare function setFileSystemState(state: Partial<FileSystemState>): void;
+/**
+ * Check file system access permission status.
+ *
+ * User Feedback Issue #1: File system access is critical for recording.
+ * This function checks:
+ * 1. If OPFS (Origin Private File System) is available
+ * 2. If storage has been initialized
+ * 3. If write access has been verified
+ *
+ * Note: We now use OPFS instead of showDirectoryPicker because it works
+ * consistently on Android Chrome, iOS Safari, and Desktop browsers.
+ *
+ * @returns Permission status for file system access
+ */
+declare function checkFileSystemPermission(): PermissionStatus;
+/**
+ * Check if WebXR immersive-ar mode is supported.
+ * Does not request a session, only checks support.
+ */
+declare function checkWebXRSupport(): Promise<PermissionStatus>;
+/**
+ * Check geolocation permission status without triggering a prompt.
+ * Uses the Permissions API if available, otherwise returns unknown state.
+ */
+declare function checkGeolocationPermission(): Promise<PermissionStatus>;
+/**
+ * Request geolocation permission by triggering a position request.
+ * This will show the browser's permission prompt if not already granted.
+ *
+ * @param timeoutMs - Maximum time to wait for position (default 10s)
+ * @returns Updated permission status after request
+ */
+declare function requestGeolocationPermission(timeoutMs?: number): Promise<PermissionStatus>;
+/**
+ * Check camera permission status without triggering a prompt.
+ * Uses the Permissions API if available.
+ */
+declare function checkCameraPermission(): Promise<PermissionStatus>;
+/**
+ * Request camera permission by triggering getUserMedia.
+ * This will show the browser's permission prompt if not already granted.
+ *
+ * @returns Updated permission status after request
+ */
+declare function requestCameraPermission(): Promise<PermissionStatus>;
+/**
+ * Check device orientation permission status.
+ * On iOS 13+, this requires explicit permission request.
+ */
+declare function checkOrientationPermission(): Promise<PermissionStatus>;
+/**
+ * Request device orientation permission (iOS 13+).
+ * On other platforms, this is a no-op that returns granted.
+ */
+declare function requestOrientationPermission(): Promise<PermissionStatus>;
+/**
+ * Check all permissions without triggering any prompts.
+ * Returns current known state of each permission.
+ */
+declare function checkAllPermissions(): Promise<PermissionCheckResult>;
+/**
+ * Request all mandatory permissions that haven't been granted yet.
+ * Shows browser prompts for each permission that needs requesting.
+ *
+ * This now includes the WebXR+Depth probe to trigger the "3D map" permission
+ * upfront, rather than surprising users with a second prompt after "Enter AR".
+ *
+ * @returns Updated permission check result after requests
+ */
+declare function requestAllPermissions(): Promise<PermissionCheckResult>;
+/**
+ * Request WebXR permission with depth-sensing by starting a probe session.
+ *
+ * The depth-sensing permission (ARCore's "3D map of surroundings") is only
+ * triggered when an XR session is actually started with depth-sensing options.
+ * This function starts a minimal probe session to trigger the permission prompt,
+ * then immediately ends it.
+ *
+ * This allows the app to request all AR permissions upfront during the
+ * setup flow, rather than surprising users with a second prompt when
+ * they click "Enter AR".
+ *
+ * @returns Permission status indicating if AR+depth access was granted
+ */
+declare function requestWebXRWithDepthPermission(): Promise<PermissionStatus>;
+//#endregion
+export { checkFileSystemPermission as a, checkWebXRSupport as c, requestGeolocationPermission as d, requestOrientationPermission as f, setFileSystemState as h, checkCameraPermission as i, requestAllPermissions as l, resetFileSystemState as m, PermissionStatus as n, checkGeolocationPermission as o, requestWebXRWithDepthPermission as p, checkAllPermissions as r, checkOrientationPermission as s, PermissionCheckResult as t, requestCameraPermission as u };

package/dist/persistence-middleware-DrptY02i.d.ts

@@ -0,0 +1,31 @@
+import { t as StorageBackend } from "./storage-backend-BcEItnFr.js";
+import { Middleware } from "@reduxjs/toolkit";
+
+//#region ../src/state/persistence-middleware.d.ts
+interface PersistenceMiddlewareOptions {
+  /**
+   * StorageBackend to use for action persistence.
+   */
+  storageBackend: StorageBackend;
+  /**
+   * Callback invoked when a write operation fails during persistence.
+   * User Feedback Issue #1 Part B: Used to show toast notifications.
+   */
+  onWriteFailure?: (error: Error) => void;
+}
+/**
+ * Create a Redux middleware that persists qualifying actions to storage
+ * during active recording sessions.
+ *
+ * Persistence rules:
+ * - Only persists when `state.recorder.isRecording` is true (checked AFTER
+ *   the action is reduced, so `startSession` itself is included).
+ * - Persists `gpsData/*` and `recorder/*` actions.
+ * - Excludes `recorder/recordWriteFailure` to prevent recursive persistence.
+ * - Excludes `routing/*`, `refPoints/*`, and any other non-recording actions.
+ * - Uses 1-based indexing for action files (000001.json, 000002.json, …).
+ * - Each middleware instance maintains its own action index (Bug 10 fix).
+ */
+declare function createPersistenceMiddleware(options: PersistenceMiddlewareOptions): Middleware;
+//#endregion
+export { createPersistenceMiddleware as n, PersistenceMiddlewareOptions as t };

package/dist/recorder-slice-fcwAXrsh.d.ts

@@ -0,0 +1,35 @@
+import { i as DepthSample } from "./ar-types-B-ORgk6Z.js";
+import { s as RecordingOptions } from "./recording-options-BYUFX8iU.js";
+import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
+
+//#region ../src/state/recorder-slice.d.ts
+interface SessionMetadata {
+  scenarioName: string;
+  sessionName: string;
+  startTime: number;
+  deviceInfo?: string;
+  notes?: string;
+  /** Recording options used for this session (for replay context) */
+  recordingOptions?: RecordingOptions;
+}
+interface RecorderState {
+  isRecording: boolean;
+  sessionMetadata: SessionMetadata | null;
+  actionCount: number;
+  /**
+   * Count of failed file write operations during this session.
+   * User Feedback Issue #1 Part B: Track write failures for visibility.
+   */
+  failedWriteCount: number;
+  /**
+   * Currently selected scenario name.
+   * Replaces the closure variable in folder-manager.ts so any module
+   * can read it via store.getState().recorder.currentScenarioName.
+   * @see docs/2026-03-26-state-management-audit.md §9.4 Priority 2
+   */
+  currentScenarioName: string;
+}
+declare const startSession: _$_reduxjs_toolkit0.ActionCreatorWithPayload<SessionMetadata, "recorder/startSession">, endSession: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"recorder/endSession">, recordDepthSample: _$_reduxjs_toolkit0.ActionCreatorWithPayload<DepthSample, "recorder/recordDepthSample">, recordWriteFailure: _$_reduxjs_toolkit0.ActionCreatorWithPayload<string, "recorder/recordWriteFailure">, setCurrentScenarioName: _$_reduxjs_toolkit0.ActionCreatorWithPayload<string, "recorder/setCurrentScenarioName">;
+declare const recorderReducer: _$_reduxjs_toolkit0.Reducer<RecorderState>;
+//#endregion
+export { recordWriteFailure as a, startSession as c, recordDepthSample as i, SessionMetadata as n, recorderReducer as o, endSession as r, setCurrentScenarioName as s, RecorderState as t };

package/dist/recording-coordinator-DzflP07_.d.ts

@@ -0,0 +1,81 @@
+import { t as ARPose } from "./ar-types-B-ORgk6Z.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-Ddzr2KlX.js";
+import { c as RecordGpsEventPayload, l as RecorderStore } from "./store-C7PKOj8S.js";
+import { Quaternion, RawGpsPoint, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
+
+//#region ../src/state/recording-coordinator.d.ts
+/**
+ * Configuration for the recording coordinator
+ */
+interface RecordingCoordinatorConfig {
+  /** Redux store to dispatch actions to */
+  store: RecorderStore;
+  /** Function to get current AR pose (from WebXR module) */
+  getArPose: () => ARPose | null;
+}
+/**
+ * Update the cached device orientation.
+ * Called by orientation watch, used when GPS event arrives.
+ */
+declare function updateDeviceOrientation(orientation: RawDeviceOrientation): void;
+/**
+ * Get the current cached device orientation.
+ */
+declare function getLastDeviceOrientation(): RawDeviceOrientation | null;
+/**
+ * Clear cached state (for testing or session reset)
+ */
+declare function resetCoordinatorState(): void;
+/**
+ * Extract raw odometry position tuple from ARPose.
+ *
+ * Returns the raw WebXR position without coordinate conversion.
+ * The reducer applies the WebXR→NUE transform when storing into state
+ * (raw-storage pattern, see docs/2026-04-09-raw-storage-convert-on-read.md).
+ *
+ * WebXR local-floor frame: X=East, Y=Up, Z=South (toward viewer / backward).
+ */
+declare function extractOdomPosition(arPose: ARPose): Vector3;
+/**
+ * Extract odometry rotation tuple from ARPose.
+ */
+declare function extractOdomRotation(arPose: ARPose): Quaternion;
+/**
+ * Build a RawGpsPoint from GPS position data.
+ * Returns only raw sensor fields — no derived fields (coordinates, weight,
+ * zeroRef, deviceRotation). Derived fields are computed by the library
+ * reducer when the action is dispatched (raw-storage pattern).
+ *
+ * @param gpsPosition - GPS position from Geolocation API
+ * @param deviceOrientation - Optional device orientation from sensors
+ * @returns RawGpsPoint ready for the action payload
+ */
+declare function buildRawGpsPoint(gpsPosition: GpsPosition, deviceOrientation: RawDeviceOrientation | null): RawGpsPoint;
+/**
+ * Build a RecordGpsEventPayload from GPS position and AR pose.
+ * This is a pure function for testability.
+ *
+ * Stores only raw sensor data in the payload. The library reducer
+ * computes derived fields (coordinates, weight, deviceRotation)
+ * when the action is processed (raw-storage pattern).
+ *
+ * @param gpsPosition - GPS position from Geolocation API
+ * @param arPose - AR pose from WebXR
+ * @param deviceOrientation - Optional device orientation from sensors
+ * @returns RecordGpsEventPayload ready for dispatch
+ */
+declare function buildRecordGpsEventPayload(gpsPosition: GpsPosition, arPose: ARPose, deviceOrientation: RawDeviceOrientation | null): RecordGpsEventPayload;
+/**
+ * Create a GPS position handler that dispatches combined GPS+AR events.
+ *
+ * This is the CRITICAL function that implements the correct architecture:
+ * - Called when GPS arrives
+ * - Reads current AR pose
+ * - Dispatches single combined action
+ *
+ * @param config - Configuration with store and getArPose function
+ * @returns Callback function for GPS watch
+ */
+declare function createGpsPositionHandler(config: RecordingCoordinatorConfig): (position: GpsPosition) => void;
+//#endregion
+export { eulerToQuaternion as a, getLastDeviceOrientation as c, createGpsPositionHandler as i, resetCoordinatorState as l, buildRawGpsPoint as n, extractOdomPosition as o, buildRecordGpsEventPayload as r, extractOdomRotation as s, RecordingCoordinatorConfig as t, updateDeviceOrientation as u };

package/dist/recording-options-BYUFX8iU.d.ts

@@ -0,0 +1,166 @@
+//#region ../src/state/recording-options.d.ts
+/**
+ * Recording Options - User-configurable settings for data capture.
+ *
+ * Allows users to disable/configure high-frequency data streams
+ * (depth sampling, image capture) to improve performance on lower-end devices.
+ *
+ * Options persist in localStorage across sessions.
+ */
+/**
+ * Input type for validateRecordingOptions allowing partial nested objects.
+ * This allows passing incomplete objects that will be merged with defaults.
+ */
+interface RecordingOptionsInput {
+  depth?: Partial<DepthCaptureOptions>;
+  images?: Partial<ImageCaptureOptions>;
+  arCrashIsolation?: Partial<ArCrashIsolationOptions>;
+}
+/**
+ * Diagnostic flags for isolating pre-recording AR startup crashes.
+ * These gates affect XR session negotiation and frame-loop behavior,
+ * independently of recording-time image/depth capture.
+ */
+interface ArCrashIsolationOptions {
+  enableDomOverlay: boolean;
+  enableCameraAccess: boolean;
+  enableDepthSensingFeature: boolean;
+  enableCss3dRenderer: boolean;
+  enableCameraTextureAcquisition: boolean;
+  /**
+   * Apply the Chromium WebXR camera-access tab-crash workaround at app
+   * bootstrap (deletes `XRWebGLBinding.prototype.createProjectionLayer` and
+   * `XRRenderState.prototype.layers` so three.js falls back to
+   * `XRWebGLLayer`). Opt-in because the upstream issue thread warns it may
+   * break WebXR on unaffected devices.
+   *
+   * @see GpsPlusSlamJs_AppFramework/src/ar/chromium-camera-access-workaround.ts
+   * @see https://github.com/mrdoob/three.js/issues/33404
+   */
+  applyChromiumProjectionLayerWorkaround: boolean;
+}
+/**
+ * Configuration for depth sampling during recording.
+ */
+interface DepthCaptureOptions {
+  /** Whether to capture depth samples. Default: true */
+  enabled: boolean;
+  /** Interval between samples in milliseconds. Default: 1000 */
+  intervalMs: number;
+  /** Grid size (N×N points per sample). Default: 3 */
+  gridSize: number;
+}
+/**
+ * Configuration for image capture during recording.
+ */
+interface ImageCaptureOptions {
+  /** Whether to capture images. Default: true */
+  enabled: boolean;
+  /** Interval between captures in milliseconds. Default: 2000 */
+  intervalMs: number;
+  /** JPEG quality (0.0 - 1.0). Default: 0.7 */
+  quality: number;
+  /** Resolution divisor: 1 = full native resolution, 2 = half, 4 = quarter. Default: 1 */
+  resolutionDivisor: number;
+}
+/**
+ * User-configurable recording options.
+ * Persisted to localStorage for cross-session consistency.
+ */
+interface RecordingOptions {
+  /** Depth sampling configuration */
+  depth: DepthCaptureOptions;
+  /** Image capture configuration */
+  images: ImageCaptureOptions;
+  /** Diagnostic flags for pre-recording AR crash isolation */
+  arCrashIsolation: ArCrashIsolationOptions;
+}
+/**
+ * localStorage key for persisted options.
+ *
+ * **Multi-tab caveat:** All tabs/instances sharing the same origin will
+ * read and write this key. In multi-tab or embedded scenarios, concurrent
+ * saves can silently overwrite each other. Use a custom `storageKey`
+ * parameter in `loadRecordingOptions` / `saveRecordingOptions` to isolate
+ * instances when needed.
+ */
+declare const STORAGE_KEY = "gps-plus-slam-recorder-options";
+/** Default recording options (all streams enabled) */
+declare const DEFAULT_RECORDING_OPTIONS: RecordingOptions;
+/** Validation constraints for depth options */
+declare const DEPTH_CONSTRAINTS: {
+  readonly intervalMs: {
+    readonly min: 500;
+    readonly max: 5000;
+    readonly step: 100;
+  };
+  readonly gridSize: {
+    readonly min: 2;
+    readonly max: 10;
+    readonly step: 1;
+  };
+};
+/** Validation constraints for image options */
+declare const IMAGE_CONSTRAINTS: {
+  readonly intervalMs: {
+    readonly min: 1000;
+    readonly max: 10000;
+    readonly step: 500;
+  };
+  readonly quality: {
+    readonly min: 0.3;
+    readonly max: 1;
+    readonly step: 0.1;
+  };
+  readonly resolutionDivisor: {
+    readonly min: 1;
+    readonly max: 8;
+    readonly step: 1;
+  };
+};
+/**
+ * Validate and normalize AR crash isolation flags.
+ * Missing or invalid values fall back to defaults.
+ */
+declare function validateArCrashIsolationOptions(options: Partial<ArCrashIsolationOptions>): ArCrashIsolationOptions;
+/**
+ * Validate and normalize depth options.
+ * Invalid values are clamped to valid ranges.
+ */
+declare function validateDepthOptions(options: Partial<DepthCaptureOptions>): DepthCaptureOptions;
+/**
+ * Validate and normalize image options.
+ * Invalid values are clamped to valid ranges.
+ */
+declare function validateImageOptions(options: Partial<ImageCaptureOptions>): ImageCaptureOptions;
+/**
+ * Validate and normalize a full RecordingOptions object.
+ * Merges with defaults and clamps invalid values.
+ */
+declare function validateRecordingOptions(options: RecordingOptionsInput): RecordingOptions;
+/**
+ * Load recording options from localStorage.
+ * Returns defaults if no saved options exist or parsing fails.
+ * Validates and merges with defaults to handle schema evolution.
+ * @param storageKey - Optional custom localStorage key (defaults to STORAGE_KEY).
+ */
+declare function loadRecordingOptions(storageKey?: string): RecordingOptions;
+/**
+ * Save recording options to localStorage.
+ * Options are validated before saving.
+ * @param storageKey - Optional custom localStorage key (defaults to STORAGE_KEY).
+ */
+declare function saveRecordingOptions(options: RecordingOptions, storageKey?: string): void;
+/**
+ * Reset recording options to defaults.
+ * Clears localStorage and returns default options.
+ * @param storageKey - Optional custom localStorage key (defaults to STORAGE_KEY).
+ */
+declare function resetRecordingOptions(storageKey?: string): RecordingOptions;
+/**
+ * Create a deep copy of recording options.
+ * Useful for creating mutable copies of the frozen defaults.
+ */
+declare function cloneRecordingOptions(options: RecordingOptions): RecordingOptions;
+//#endregion
+export { validateRecordingOptions as _, IMAGE_CONSTRAINTS as a, RecordingOptionsInput as c, loadRecordingOptions as d, resetRecordingOptions as f, validateImageOptions as g, validateDepthOptions as h, DepthCaptureOptions as i, STORAGE_KEY as l, validateArCrashIsolationOptions as m, DEFAULT_RECORDING_OPTIONS as n, ImageCaptureOptions as o, saveRecordingOptions as p, DEPTH_CONSTRAINTS as r, RecordingOptions as s, ArCrashIsolationOptions as t, cloneRecordingOptions as u };

package/dist/recording-replayer-oOzPITrd.d.ts

@@ -0,0 +1,32 @@
+import { n as CombinedRootState } from "./store-C7PKOj8S.js";
+import { i as RecordedAction } from "./zip-reader-D7pkpX8K.js";
+
+//#region ../src/state/recording-replayer.d.ts
+/**
+ * Options for replaying a recording.
+ */
+interface ReplayRecordingOptions {
+  /**
+   * Optional migration function to transform raw actions from the ZIP before
+   * dispatching. Use this to handle older recording formats (e.g., era 1–3
+   * recordings that use `gpsPoint` instead of `rawGpsPoint`).
+   *
+   * When not provided, actions are dispatched as-is from the ZIP.
+   */
+  readonly migrateActions?: (actions: RecordedAction[]) => RecordedAction[];
+}
+/**
+ * Replay a recording session from zip data, returning the final state.
+ *
+ * Loads all actions from the zip, creates a store with no persistence,
+ * optionally migrates old-format actions, dispatches in order, and returns
+ * the resulting state.
+ *
+ * @param zipData - The zip file content as a Uint8Array
+ * @param options - Optional replay configuration (e.g., action migration)
+ * @returns The fully-replayed combined state (library + recorder)
+ * @throws If the zip cannot be parsed or contains invalid data
+ */
+declare function replayRecording(zipData: Uint8Array, options?: ReplayRecordingOptions): Promise<CombinedRootState>;
+//#endregion
+export { replayRecording as n, ReplayRecordingOptions as t };