gps-plus-slam-app-framework 1.3.0 → 1.7.0

package/dist/{zip-export-G14hkSPG.d.ts → zip-export-ol0S_Ofd.d.ts}

@@ -78,24 +78,38 @@ interface ExportSessionAsZipOptions {
   readonly contributors?: readonly ZipExportContributor[];
 }
 /**
- * Export a session from OPFS as a ZIP blob.
+ * Export a flat-layout 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, ...
  * - images/frame-000001.jpg, images/frame-000002.jpg, ... (legacy: frames/)
- * - refPoints/{h3}.json (only observations from this session, scenario layout only)
  *
- * Uses "store" mode (compression level 0) for fast packaging.
- *
- * Supports both flat and scenario-based layouts:
- * - `exportSessionAsZip(sessionName)` — flat layout (sessions/)
- * - `exportSessionAsZip(scenarioName, sessionName)` — scenario layout (scenarios/{name}/)
+ * Uses "store" mode (compression level 0) for fast packaging. Consumers with a
+ * different on-disk layout (one that nests sessions under a named bucket)
+ * resolve their own session handle and call {@link exportSessionHandleAsZip}.
  *
+ * @param sessionName - Name of the session folder under `sessions/`.
  * @returns ZIP export result with blob and file count
- * @throws Error if session not found
+ * @throws Error if the session is not found
+ */
+declare function exportSessionAsZip(sessionName: string, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
+/**
+ * Stream an already-resolved session directory handle to a ZIP blob, running
+ * any caller-supplied extension {@link ZipExportContributor}s after the
+ * framework-owned files.
+ *
+ * This is the layout-agnostic core of {@link exportSessionAsZip}: consumers
+ * that resolve a session directory handle themselves (e.g. an app that nests
+ * sessions under its own grouping layer) call this directly so the framework's
+ * ZIP schema stays the single source of truth without the framework needing to
+ * know how the handle was located.
+ *
+ * @param sessionHandle - The session directory to package (must contain the
+ *   framework-owned `session.json` / `actions/` / `images/` tree).
+ * @returns ZIP export result with blob and file count.
  */
-declare function exportSessionAsZip(scenarioNameOrSessionName: string, sessionName?: string, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
+declare function exportSessionHandleAsZip(sessionHandle: FileSystemDirectoryHandle, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
 /**
  * Sync current OPFS session data to an external file handle.
  *
@@ -109,12 +123,11 @@ declare function exportSessionAsZip(scenarioNameOrSessionName: string, sessionNa
  * 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
+ * @param sessionName - Name of the session folder under `sessions/`
  * @returns ZIP export result with blob and file count
- * @throws Error if scenario or session not found
+ * @throws Error if the session is not found
  */
-declare function syncToExternalZip(fileHandle: FileSystemFileHandle, scenarioName: string, sessionName: string, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
+declare function syncToExternalZip(fileHandle: FileSystemFileHandle, sessionName: string, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
 /**
  * Trigger a file download in the browser.
  *
@@ -125,14 +138,5 @@ declare function syncToExternalZip(fileHandle: FileSystemFileHandle, scenarioNam
  * @param filename - Suggested filename
  */
 declare function downloadZip(blob: Blob, filename: string): Promise<void>;
-/**
- * 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
- */
-declare function exportAndDownloadSession(scenarioName: string, sessionName: string): Promise<void>;
 //#endregion
-export { downloadZip as a, syncToExternalZip as c, ZipExportResult as i, ZipContributorAddFile as n, exportAndDownloadSession as o, ZipExportContributor as r, exportSessionAsZip as s, ExportSessionAsZipOptions as t };
+export { downloadZip as a, syncToExternalZip as c, ZipExportResult as i, ZipContributorAddFile as n, exportSessionAsZip as o, ZipExportContributor as r, exportSessionHandleAsZip as s, ExportSessionAsZipOptions as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gps-plus-slam-app-framework",
-  "version": "1.3.0",
+  "version": "1.7.0",
   "description": "Reusable AR+GPS app framework layer — WebXR session management, Three.js visualization, GPS sensors, storage abstractions, replay engine, and store wiring for gps-plus-slam-js.",
   "type": "module",
   "files": [
@@ -36,7 +36,7 @@
   "dependencies": {
     "@reduxjs/toolkit": "^2.11.2",
     "gl-matrix": "3.4.4",
-    "gps-plus-slam-js": "^1.3.0"
+    "gps-plus-slam-js": "^1.7.0"
   },
   "peerDependencies": {
     "@sentry/browser": ">=10.0.0",

package/dist/concurrency-CO1FQvs3.d.ts

@@ -1,24 +0,0 @@
-//#region ../src/utils/concurrency.d.ts
-/**
- * Concurrency Utilities
- *
- * Provides helpers for limiting the number of concurrent async operations.
- * Used to prevent excessive memory consumption when scanning many files
- * in parallel (e.g., reading zip metadata during scenario discovery).
- */
-/**
- * Map over an array with a concurrency limit on the async mapper function.
- *
- * Behaves like `Promise.all(items.map(fn))` but limits how many mapper
- * invocations run simultaneously. Results are returned in the same order
- * as the input items.
- *
- * @param items - Array of items to process
- * @param limit - Maximum number of concurrent mapper invocations
- * @param mapper - Async function to apply to each item
- * @returns Array of results in the same order as input items
- * @throws Re-throws the first error from any mapper invocation (fail-fast)
- */
-declare function mapWithConcurrencyLimit<T, R>(items: T[], limit: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;
-//#endregion
-export { mapWithConcurrencyLimit as t };

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

@@ -1,114 +0,0 @@
-import { n as SessionMetadata } from "./opfs-storage-D5zAn_lx.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.
- */
-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.
- */
-declare function verifyWriteAccess(dirHandle: FileSystemDirectoryHandle): Promise<WriteAccessResult>;
-/**
- * Initialize storage using OPFS.
- *
- * @returns List of existing scenario folder names
- * @throws Error if OPFS is not supported
- */
-declare function initStorage(): Promise<string[]>;
-/**
- * Create a new session folder.
- *
- * When scenarioName is provided, creates under the scenario directory
- * (legacy scenario layout for the recorder). When omitted, creates under
- * the flat sessions/ directory.
- *
- * @param scenarioName - Optional name of the scenario (omit for flat layout)
- */
-declare function startSession(scenarioName?: string): Promise<{
-  scenarioPath: string;
-  sessionPath: string;
-}>;
-/**
- * List all session names.
- * When scenarioName is provided, lists sessions under that scenario.
- * Otherwise lists flat sessions.
- */
-declare function listSessions(scenarioName?: string): Promise<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.
- */
-declare function writeSessionMetadata(metadata: SessionMetadata): Promise<void>;
-/**
- * Get the current scenario handle (for loading prior sessions).
- * Legacy: uses scenario directory layout.
- */
-declare function getCurrentScenarioHandle(): FileSystemDirectoryHandle | null;
-/**
- * Set the current scenario handle (when user selects a scenario).
- * Legacy: uses scenario directory layout.
- */
-declare function setCurrentScenario(scenarioName: string): Promise<FileSystemDirectoryHandle | null>;
-/**
- * Ensure a scenario directory exists in OPFS, creating it if necessary.
- * Legacy: used during OPFS recovery.
- */
-declare function ensureScenarioDirectory(scenarioName: string): Promise<FileSystemDirectoryHandle | null>;
-/**
- * Result of clearing the reference-point cache across all scenarios.
- */
-interface ClearRefPointsCacheResult {
-  /** Number of scenarios whose `refPoints/` directory was deleted. */
-  readonly scenariosCleared: number;
-  /** Total number of scenarios scanned (including ones with no cache). */
-  readonly scenariosScanned: number;
-  /** Names of scenarios that failed to clear, with reason. */
-  readonly errors: {
-    scenarioName: string;
-    reason: string;
-  }[];
-}
-/**
- * Clear the cached `refPoints/` directory for every scenario in OPFS.
- *
- * Used by the "Clear Reference Point Cache" maintenance action so that the
- * next scenario load re-imports ref points from the read folder's `*.zip`
- * recordings (see ref-point-recovery in the recorder app).
- *
- * Failures for individual scenarios are collected in `errors` rather than
- * aborting the whole operation — partial progress is still useful.
- *
- * @throws Error if OPFS storage is unavailable (e.g. `initStorage()` not yet
- *   called, or browser does not support OPFS). Surfacing this loudly avoids
- *   reporting a silent "0 scenarios cleared" success that would mask the
- *   real failure to the user.
- */
-declare function clearRefPointsCacheForAllScenarios(): Promise<ClearRefPointsCacheResult>;
-//#endregion
-export { getCurrentScenarioHandle as a, resetForNewSession as c, startSession as d, verifyWriteAccess as f, writeSessionMetadata as h, ensureScenarioDirectory as i, resetStorageState as l, writeFrame as m, WriteAccessResult as n, initStorage as o, writeAction as p, clearRefPointsCacheForAllScenarios as r, listSessions as s, ClearRefPointsCacheResult as t, setCurrentScenario as u };

package/dist/index-CF05QV2m.d.ts

@@ -1,2 +0,0 @@
-import { ArImageCapture as ArImageCapture$1, GpsPoint as GpsPoint$1, LatLong as LatLong$1, LatLongAlt, Matrix4 as Matrix4$1, Quaternion as Quaternion$1, RootState as LibraryRootState, RootState as RootState$1, Vector3 as Vector3$1, calcGpsCoords as calcGpsCoords$1, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey as validateLicenseKey$1, webxrToNUE } from "gps-plus-slam-js";
-export { LibraryRootState as a, RootState$1 as c, calcRelativeCoordsInMeters as d, createGpsSlamStore as f, webxrToNUE as g, validateLicenseKey$1 as h, LatLongAlt as i, Vector3$1 as l, odometryTrackingRestarted as m, GpsPoint$1 as n, Matrix4$1 as o, isIdentityMatrix4 as p, LatLong$1 as r, Quaternion$1 as s, ArImageCapture$1 as t, calcGpsCoords$1 as u };

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

@@ -1,182 +0,0 @@
-//#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. The workaround always deletes
-   * `XRWebGLBinding.prototype.createProjectionLayer` /
-   * `XRRenderState.prototype.layers` (forcing `XRWebGLLayer`) — required on
-   * every affected Chrome build observed on-device, including Chrome 150 — and
-   * additionally persists the `baseLayer` across
-   * `XRSession.prototype.updateRenderState` only for Chrome builds inside the
-   * affected window (148.0.7778.12 up to 149.0.7821).
-   *
-   * Default `true`. Opt-out is offered because forcing `XRWebGLLayer` may break
-   * WebXR on unaffected (e.g. Quest) 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: 16 — dense enough to
-   * populate the AR-space occupancy grid (2026-06-11 port plan §1).
-   */
-  gridSize: number;
-  /**
-   * Whether to enrich each depth point with the camera color at its view
-   * coordinates (RGB voxel coloring, occupancy-grid port plan Iter 8).
-   * Costs one small GPU blit+readback per sample (~1 Hz); when off, the
-   * occupancy cubes keep the height-based coloring. Default: true.
-   */
-  rgb: boolean;
-}
-/**
- * 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: 32;
-    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-slice-89O07ebs.d.ts

@@ -1,36 +0,0 @@
-import { i as DepthSample } from "./ar-types-Dan1MVTi.js";
-import { s as RecordingOptions } from "./recording-options-DJBXuMxV.js";
-import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
-
-//#region ../src/state/recording-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 RecordingState {
-  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;
-  /**
-   * The most recent depth sample, kept ONLY so subscribers can observe new
-   * samples via reference comparison (the AR-space occupancy grid is fed
-   * this way — see the 2026-06-11 occupancy-grid port plan). The persisted
-   * action stream remains the source of truth; no history is kept here.
-   * The payload stays in raw WebXR coordinates — conversion-free.
-   */
-  latestDepthSample: DepthSample | null;
-}
-declare const startSession: _$_reduxjs_toolkit0.ActionCreatorWithPayload<SessionMetadata, "recording/startSession">, endSession: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"recording/endSession">, recordDepthSample: _$_reduxjs_toolkit0.ActionCreatorWithPayload<DepthSample, "recording/recordDepthSample">, recordWriteFailure: _$_reduxjs_toolkit0.ActionCreatorWithPayload<string, "recording/recordWriteFailure">;
-declare const recordingReducer: _$_reduxjs_toolkit0.Reducer<RecordingState>;
-//#endregion
-export { recordWriteFailure as a, recordDepthSample as i, SessionMetadata as n, recordingReducer as o, endSession as r, startSession as s, RecordingState as t };

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

@@ -1,2 +0,0 @@
-import { a as getCurrentScenarioHandle, c as resetForNewSession, d as startSession, f as verifyWriteAccess, h as writeSessionMetadata, i as ensureScenarioDirectory, l as resetStorageState, m as writeFrame, n as WriteAccessResult, o as initStorage, p as writeAction, r as clearRefPointsCacheForAllScenarios, s as listSessions, t as ClearRefPointsCacheResult, u as setCurrentScenario } from "../file-system-CwXTNHmB.js";
-export { ClearRefPointsCacheResult, WriteAccessResult, clearRefPointsCacheForAllScenarios, ensureScenarioDirectory, getCurrentScenarioHandle, initStorage, listSessions, resetForNewSession, resetStorageState, setCurrentScenario, startSession, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata };