gps-plus-slam-app-framework 1.0.0

package/dist/webxr-session-COlSrXdL.d.ts

@@ -0,0 +1,316 @@
+import { i as DepthSample, t as ARPose } from "./ar-types-B-ORgk6Z.js";
+import { i as ImageCaptureConfig, t as CapturedImage } from "./image-capture-2pKjYUS6.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-rgLMVAvd.js";
+import { n as ResetTransformData } from "./tracking-state-B9QfuZCg.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-BYUFX8iU.js";
+import { r as XRCameraLike } from "./xr-camera-texture-BbukNE79.js";
+import * as THREE from "three";
+import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
+
+//#region ../src/ar/webxr-session.d.ts
+declare function isXRCameraLike(value: unknown): value is XRCameraLike;
+/**
+ * Extract a validated XRCameraLike from an XRViewerPose.
+ *
+ * Returns null in every case where the per-frame texture acquisition must be
+ * skipped — i.e. whenever the caller should treat any previously cached
+ * texture as stale and clear it. Centralising the preconditions here makes
+ * it impossible to accidentally fall through without clearing the cache.
+ *
+ * Cases that return null:
+ *   - pose is null (tracking lost)
+ *   - pose has no views
+ *   - the first view has no `camera` property (camera-access not granted)
+ *   - the camera property is not a valid XRCameraLike (zero/NaN dimensions)
+ *
+ * @see docs/2026-02-06-bug-camera-frames-black.md
+ */
+declare function getXrCameraFromPose(pose: XRViewerPose | null): XRCameraLike | null;
+/**
+ * Decide whether the one-time camera-access grant diagnostic should fire
+ * on the current XR frame.
+ *
+ * The diagnostic is only meaningful when we actually have a valid pose:
+ * if `pose` is null (e.g. session starts with tracking lost), then the
+ * derived `xrCamera` is null regardless of permission state, and logging
+ * "NOT GRANTED" would be a false negative that permanently suppresses the
+ * correct status because `cameraAccessLoggedOnce` would latch to true.
+ *
+ * Additional conditions:
+ *   - `alreadyLogged` prevents spamming the log every frame.
+ *   - `captureActive` ensures we only care when an image capture session
+ *     is running (otherwise the diagnostic has no audience).
+ *
+ * This predicate is extracted as a pure function so the guard against the
+ * "first frame has no pose" false-negative regression is directly testable.
+ */
+declare function shouldLogCameraAccessDiagnostic(pose: XRViewerPose | null, alreadyLogged: boolean, captureActive: boolean): boolean;
+/**
+ * Reset WebXR module state - exported for testing only.
+ * @internal
+ */
+declare function resetWebXRState(): void;
+/**
+ * Extract the reset transform from an XRReferenceSpaceEvent-like object.
+ *
+ * Distinguishes three cases per OdometryTrackingRestartedPayload semantics:
+ * - Transform property missing (older browsers) → returns `undefined`
+ * - Transform property present but null (runtime can't determine delta) → returns `null`
+ * - Transform property present with data → returns `ResetTransformData`
+ *
+ * This is a pure function extracted for testability.
+ *
+ * @param event - The event object, cast to a record with an optional transform property
+ * @returns ResetTransformData, null, or undefined
+ */
+declare function extractResetTransformData(event: Record<string, unknown>): ResetTransformData | null | undefined;
+/**
+ * Extract pose data from an XRViewerPose.
+ * Returns null if pose or views are unavailable.
+ *
+ * This is a pure function extracted for testability.
+ *
+ * @param pose - The XRViewerPose from frame.getViewerPose()
+ * @returns ARPose with position and orientation, or null
+ */
+declare function extractPoseFromViewer(pose: XRViewerPose | null): ARPose | null;
+/**
+ * Get the current raw AR pose from the latest XR frame.
+ * This is updated every frame and should be called when GPS arrives
+ * to get the AR pose at that moment.
+ *
+ * IMPORTANT: This returns the RAW pose from WebXR, NOT transformed
+ * by any alignment matrix. This is what we record to the store.
+ *
+ * @returns The latest AR pose, or null if no pose available yet
+ */
+declare function getCurrentArPose(): ARPose | null;
+/**
+ * Build XR session init options.
+ * Extracted as a pure function for testability.
+ *
+ * @param rootElement - The DOM element for DOM overlay
+ * @returns XRSessionInit options
+ * @throws Error if rootElement is null
+ */
+declare function buildSessionOptions(rootElement: Element | null, isolationOptions?: Partial<ArCrashIsolationOptions>): XRSessionInit;
+/**
+ * Check if WebXR immersive-ar is supported
+ */
+declare function isWebXRSupported(): Promise<boolean>;
+/**
+ * Create the scene hierarchy with proper AR/GPS frame separation.
+ * This is a pure function for testability.
+ *
+ * Hierarchy:
+ *   scene (GPS world frame — NUE: X=North, Y=Up, Z=East)
+ *   ├── ambientLight
+ *   ├── directionalLight
+ *   └── arWorldGroup (local space = NUE; receives alignment matrix)
+ *       └── basisChangeNode ('webxr-to-nue', constant WEBXR_TO_NUE matrix)
+ *           └── arpose (Object3D — AR pose; local space = WebXR)
+ *               └── camera (PerspectiveCamera)
+ *
+ * basisChangeNode is a static scene-graph node that holds the WEBXR_TO_NUE
+ * basis-change matrix permanently (matrixAutoUpdate=false). Moving it here
+ * instead of composing it in applyAlignmentMatrix() keeps arWorldGroup's
+ * local space as NUE: objects added directly to arWorldGroup can be placed
+ * at [1,0,0]=North, [0,0,1]=East without any WebXR↔NUE conversion.
+ *
+ * - Recording: arpose stays at identity; WebXRManager writes to camera.
+ * - Replay: arpose receives recorded odomPosition/odomRotation;
+ *   camera is owned by user controls (OrbitControls / FPS).
+ *
+ * @returns Object containing scene, arWorldGroup, arpose, and camera
+ */
+declare function createSceneHierarchy(): {
+  scene: THREE.Scene;
+  arWorldGroup: THREE.Group;
+  arpose: THREE.Object3D;
+  camera: THREE.PerspectiveCamera;
+};
+/**
+ * Initialize the AR session and Three.js renderer.
+ * @param container - DOM element to host the AR canvas and CSS3D overlay.
+ */
+declare function initAR(container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>): Promise<void>;
+/**
+ * Get the current Three.js scene (for adding objects like map)
+ */
+declare function getScene(): THREE.Scene | null;
+/**
+ * Get the AR world group (for adding AR-tracked content)
+ * Content added here will be transformed by the alignment matrix.
+ */
+declare function getArWorldGroup(): THREE.Group | null;
+/**
+ * Get the current camera
+ */
+declare function getCamera(): THREE.PerspectiveCamera | null;
+/**
+ * Set the scene externally (for replay mode).
+ * Allows non-WebXR code paths to register a scene so that modules
+ * calling getScene() receive it.
+ * @see docs/2026-02-19-replay-mode.md Risk R1
+ */
+declare function setScene(s: THREE.Scene | null): void;
+/**
+ * Set the AR world group externally (for replay mode).
+ * Allows non-WebXR code paths to register an arWorldGroup so that
+ * applyAlignmentMatrix() and visualizers work correctly.
+ * @see docs/2026-02-19-replay-mode.md Risk R1
+ */
+declare function setArWorldGroup(g: THREE.Group | null): void;
+/**
+ * Set the camera externally (for replay mode).
+ * Allows non-WebXR code paths to register a camera so that modules
+ * calling getCamera() receive it.
+ * @see docs/2026-02-19-replay-mode.md Risk R1
+ */
+declare function setCamera(c: THREE.PerspectiveCamera | null): void;
+/**
+ * Get the arpose Object3D (intermediate node between arWorldGroup and camera).
+ * Returns null before scene initialization.
+ */
+declare function getArPose(): THREE.Object3D | null;
+/**
+ * Set the arpose Object3D externally (for replay mode).
+ * Allows non-WebXR code paths to register an arpose so that
+ * store subscribers can update it with recorded odom data.
+ */
+declare function setArPose(a: THREE.Object3D | null): void;
+/**
+ * Apply an alignment matrix to the AR world group.
+ *
+ * The alignment matrix maps odometry positions in NUE space
+ * to GPS world space (also NUE). It is applied directly to arWorldGroup
+ * whose local space is NUE.
+ *
+ * The WebXR→NUE basis change lives permanently in basisChangeNode (a
+ * child of arWorldGroup), so the full camera world transform is:
+ *
+ *   camera_world = arWorldGroup × basisChangeNode × arpose × camera_local
+ *               = alignment × WEBXR_TO_NUE × arpose × camera_local
+ *
+ * This is mathematically identical to the previous composition
+ * (alignment × WEBXR_TO_NUE applied directly to arWorldGroup.matrix),
+ * but arWorldGroup's local space is now NUE: objects placed as children
+ * of arWorldGroup use NUE coordinates directly ([1,0,0]=North, [0,0,1]=East).
+ *
+ * Replay note: arpose still lives in WebXR space (below basisChangeNode),
+ * so nuePositionToWebXR() is still required when setting arpose.position.
+ *
+ * @param matrix - 16-element column-major matrix (gl-matrix mat4 format)
+ */
+declare function applyAlignmentMatrix(matrix: readonly number[]): void;
+/**
+ * Convert a position from internal NUE convention (X=North, Y=Up, Z=East)
+ * to WebXR local-floor convention (X=East, Y=Up, Z=South).
+ *
+ * Delegates to the canonical library implementation (nueToWebXR).
+ * Accepts `readonly number[]` for call-site convenience.
+ *
+ * NUE [n, u, e] → WebXR [e, u, -n]
+ */
+declare function nuePositionToWebXR(nue: readonly number[]): readonly [number, number, number];
+/**
+ * Convert a quaternion from internal NUE convention to WebXR local-floor convention.
+ *
+ * Delegates to the canonical library implementation (nueQuaternionToWebXR).
+ * Accepts `readonly number[]` for call-site convenience.
+ *
+ * NUE [x, y, z, w] → WebXR [z, y, -x, w]
+ */
+declare function nueQuaternionToWebXR$1(nue: readonly number[]): readonly [number, number, number, number];
+/**
+ * End the current XR session and clean up all resources.
+ *
+ * Stops the animation loop, disposes the WebGL renderer, removes the
+ * canvas from the DOM, and tears down the CSS3D overlay. This is the
+ * production cleanup path — call it when the AR experience is finished.
+ */
+declare function endARSession(): Promise<void>;
+/**
+ * Set up image capture callbacks.
+ * Call this before starting image capture to wire up the callback handlers.
+ *
+ * @param onCaptured - Called when an image is successfully captured
+ * @param screenRotationGetter - Returns current device screen rotation (0, 90, 180, 270)
+ * @param onFailed - Optional callback for when image capture fails (e.g., low memory)
+ * @param onSuspicious - Optional callback for when a captured image appears black/empty
+ */
+declare function setImageCaptureCallback(onCaptured: (image: CapturedImage) => void, screenRotationGetter: () => number, onFailed?: () => void, onSuspicious?: (blobSize: number, frameIndex: number) => void): void;
+/**
+ * Start capturing images during recording.
+ * Must call setImageCaptureCallback first.
+ * @param config - Optional capture configuration (intervalMs, quality)
+ * @param resolutionDivisor - Resolution divisor: 1 = full, 2 = half, 4 = quarter (default: 1)
+ */
+declare function startImageCapture(config?: Partial<ImageCaptureConfig>, resolutionDivisor?: number): void;
+/**
+ * Stop capturing images.
+ */
+declare function stopImageCapture(): void;
+/**
+ * Get the current image capture frame count.
+ */
+declare function getImageCaptureFrameCount(): number;
+/**
+ * Set up tracking state callbacks.
+ * Call this BEFORE initAR() to enable tracking restart detection.
+ *
+ * @param onRestarted - Called when tracking restarts after being lost
+ */
+declare function setTrackingCallbacks(onRestarted: (payload: OdometryTrackingRestartedPayload) => void): void;
+/**
+ * Set a callback for when AR tracking is lost.
+ * Call this BEFORE initAR() to enable tracking loss notifications.
+ * Field Test Readiness Issue #3: Provide user feedback when tracking is lost.
+ *
+ * @param callback - Called when tracking is lost (pose becomes null)
+ */
+declare function setTrackingLostCallback(callback: () => void): void;
+/**
+ * Set a callback for when AR tracking recovers seamlessly (Case 1: same coordinate frame).
+ * Call this BEFORE initAR() to enable seamless recovery notifications.
+ *
+ * @param callback - Called when tracking recovers without origin reset
+ */
+declare function setTrackingRecoveredCallback(callback: () => void): void;
+/**
+ * Set up depth capture callback.
+ * Call this BEFORE initAR() to enable depth sampling.
+ *
+ * @param onCaptured - Called when a depth sample is captured
+ * @param onUnavailable - Called once if depth is unavailable after threshold
+ */
+declare function setDepthCaptureCallback(onCaptured: (sample: DepthSample) => void, onUnavailable?: () => void): void;
+/**
+ * Start depth sampling during recording.
+ * Must call setDepthCaptureCallback before initAR.
+ */
+declare function startDepthCapture(): void;
+/**
+ * Stop depth sampling.
+ */
+declare function stopDepthCapture(): void;
+/**
+ * Get the current depth sample count.
+ */
+declare function getDepthSampleCount(): number;
+/**
+ * Set a per-frame callback for custom updates.
+ * The callback is invoked every XR frame after pose updates but before render.
+ * Useful for updating elements that need to follow the camera smoothly
+ * (e.g., map overlay position).
+ *
+ * @param callback - Function to call each frame, or null to clear
+ */
+declare function setFrameCallback(callback: (() => void) | null): void;
+/**
+ * Get the CSS3D renderer manager for live AR mode.
+ * Returns null if no AR session is active or CSS3D was not created.
+ */
+declare function getLiveCss3dManager(): Css3dRendererManager | null;
+//#endregion
+export { setTrackingLostCallback as A, setArWorldGroup as C, setImageCaptureCallback as D, setFrameCallback as E, stopDepthCapture as F, stopImageCapture as I, shouldLogCameraAccessDiagnostic as M, startDepthCapture as N, setScene as O, startImageCapture as P, setArPose as S, setDepthCaptureCallback as T, isWebXRSupported as _, extractPoseFromViewer as a, nueQuaternionToWebXR$1 as b, getArWorldGroup as c, getDepthSampleCount as d, getImageCaptureFrameCount as f, initAR as g, getXrCameraFromPose as h, endARSession as i, setTrackingRecoveredCallback as j, setTrackingCallbacks as k, getCamera as l, getScene as m, buildSessionOptions as n, extractResetTransformData as o, getLiveCss3dManager as p, createSceneHierarchy as r, getArPose as s, applyAlignmentMatrix as t, getCurrentArPose as u, isXRCameraLike as v, setCamera as w, resetWebXRState as x, nuePositionToWebXR as y };

package/dist/xr-camera-texture-BbukNE79.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from "three";
+
+//#region ../src/ar/xr-camera-texture.d.ts
+/**
+ * Result from acquireCameraTexture containing the Three.js texture
+ * (ExternalTexture returned by Three.js) plus the native camera dimensions.
+ */
+interface CameraTextureResult {
+  /** Three.js ExternalTexture from renderer.xr.getCameraTexture() */
+  texture: THREE.Texture;
+  /** Native camera frame width in pixels */
+  width: number;
+  /** Native camera frame height in pixels */
+  height: number;
+}
+/**
+ * Minimal interface for XRCamera — only the properties we use.
+ */
+interface XRCameraLike {
+  width: number;
+  height: number;
+}
+/**
+ * Minimal interface for the parts of THREE.WebGLRenderer we need.
+ * Avoids importing the full renderer type in tests.
+ */
+interface RendererLike {
+  xr: {
+    getCameraTexture(xrCamera: unknown): THREE.Texture | undefined;
+  };
+}
+/**
+ * Acquire the camera texture for the current XR frame using Three.js's
+ * built-in getCameraTexture() API, paired with native camera dimensions.
+ *
+ * Three.js internally:
+ * 1. Creates XRWebGLBinding (lazy, one per session)
+ * 2. Calls glBinding.getCameraImage(camera) each frame
+ * 3. Wraps in ExternalTexture (sourceTexture = native WebGLTexture)
+ * 4. Caches per xrCamera in cameraAccessTextures map
+ *
+ * This function adds the native camera dimensions (width/height) needed
+ * for dynamic render target sizing in the blit capture pipeline.
+ *
+ * Must be called within the XR animation frame callback.
+ *
+ * @param renderer - The Three.js WebGLRenderer
+ * @param xrCamera - The XRCamera from XRView.camera, or null if unavailable
+ * @returns CameraTextureResult, or null if acquisition fails
+ */
+declare function acquireCameraTexture(renderer: RendererLike, xrCamera: XRCameraLike | null): CameraTextureResult | null;
+//#endregion
+export { acquireCameraTexture as i, RendererLike as n, XRCameraLike as r, CameraTextureResult as t };

package/dist/xr-error-handler-DTHfmvrl.d.ts

@@ -0,0 +1,24 @@
+//#region ../src/ar/xr-error-handler.d.ts
+/**
+ * WebXR Error Handler
+ *
+ * Provides user-facing error messages for WebXR session failures.
+ * Separates error handling logic from AR module for testability.
+ */
+/**
+ * Known WebXR error types and their user-friendly messages.
+ */
+declare const XR_ERROR_MESSAGES: Record<string, string>;
+/**
+ * Default message for unknown error types.
+ */
+declare const XR_ERROR_MESSAGE_UNKNOWN = "Failed to start AR session. Check device compatibility and permissions.";
+/**
+ * Get a user-friendly error message from a WebXR session error.
+ *
+ * @param error - The error thrown by navigator.xr.requestSession
+ * @returns A user-friendly error message
+ */
+declare function getXrErrorMessage(error: unknown): string;
+//#endregion
+export { XR_ERROR_MESSAGE_UNKNOWN as n, getXrErrorMessage as r, XR_ERROR_MESSAGES as t };

package/dist/zip-export-Rtpi75JJ.d.ts

@@ -0,0 +1,87 @@
+//#region ../src/storage/zip-export.d.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
+ */
+/**
+ * Result of a ZIP export operation.
+ * Provides the blob and metadata for share + summary display.
+ *
+ * @see 2026-02-06 User Feedback Issue #2 (Share) and Issue #3 (ZIP Stats)
+ */
+interface ZipExportResult {
+  /** The ZIP blob ready for download or sharing */
+  readonly blob: Blob;
+  /** Number of files packaged in the ZIP */
+  readonly fileCount: number;
+}
+/**
+ * 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
+ */
+declare function exportSessionAsZip(scenarioName: string, sessionName: string): Promise<ZipExportResult>;
+/**
+ * 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
+ */
+declare function syncToExternalZip(fileHandle: FileSystemFileHandle, scenarioName: string, sessionName: string): Promise<ZipExportResult>;
+/**
+ * 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
+ */
+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 { syncToExternalZip as a, exportSessionAsZip as i, downloadZip as n, exportAndDownloadSession as r, ZipExportResult as t };

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

@@ -0,0 +1,97 @@
+import { Entry, Entry as Entry$1 } from "@zip.js/zip.js";
+
+//#region ../src/storage/zip-reader.d.ts
+/**
+ * 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.
+ */
+declare const MAX_ACTION_FILE_SIZE = 1048576;
+/** Shape of a single recorded Redux action (type + optional payload). */
+type RecordedAction = {
+  type: string;
+  payload?: unknown;
+};
+/**
+ * A parsed action entry from a recording zip file.
+ */
+interface ZipActionEntry {
+  /** 1-based index extracted from the filename (e.g., 1 from "000001.json") */
+  index: number;
+  /** Original filename within the zip (e.g., "actions/000001.json") */
+  filename: string;
+  /** Parsed Redux action with type and optional payload */
+  action: RecordedAction;
+}
+/**
+ * Read all entries from a zip file.
+ *
+ * @param data - The zip file content as a Uint8Array
+ * @returns Array of zip entries (directories and files)
+ */
+declare function readZipEntries(data: Uint8Array): Promise<Entry[]>;
+/**
+ * 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
+ */
+declare function loadActionsFromZip(data: Uint8Array, maxFileSize?: number): Promise<ZipActionEntry[]>;
+/**
+ * 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
+ */
+declare function loadSessionMetadata(data: Uint8Array, maxFileSize?: number): Promise<Record<string, unknown> | null>;
+/**
+ * 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
+ */
+declare function loadSessionMetadataFromBlob(blob: Blob, maxFileSize?: number): Promise<Record<string, unknown> | null>;
+/** A lightweight GPS coordinate pair (Leaflet convention: lat/lng). */
+interface GpsPathCoord {
+  readonly lat: number;
+  readonly lng: number;
+}
+/**
+ * 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
+ */
+declare function loadGpsPathFromBlob(blob: Blob, maxFileSize?: number): Promise<GpsPathCoord[]>;
+//#endregion
+export { ZipActionEntry as a, loadSessionMetadata as c, RecordedAction as i, loadSessionMetadataFromBlob as l, GpsPathCoord as n, loadActionsFromZip as o, MAX_ACTION_FILE_SIZE as r, loadGpsPathFromBlob as s, Entry$1 as t, readZipEntries as u };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "gps-plus-slam-app-framework",
+  "version": "1.0.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": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./ar": "./dist/ar/index.js",
+    "./ar/*": "./dist/ar/*.js",
+    "./sensors": "./dist/sensors/index.js",
+    "./sensors/*": "./dist/sensors/*.js",
+    "./state": "./dist/state/index.js",
+    "./state/*": "./dist/state/*.js",
+    "./storage": "./dist/storage/index.js",
+    "./storage/*": "./dist/storage/*.js",
+    "./ref-points": "./dist/ref-points/index.js",
+    "./ref-points/*": "./dist/ref-points/*.js",
+    "./visualization": "./dist/visualization/index.js",
+    "./visualization/*": "./dist/visualization/*.js",
+    "./utils": "./dist/utils/index.js",
+    "./utils/*": "./dist/utils/*.js",
+    "./types": "./dist/types/index.js",
+    "./types/*": "./dist/types/*.js",
+    "./licensing": "./dist/licensing/index.js",
+    "./licensing/*": "./dist/licensing/*.js",
+    "./test-utils/*": "./dist/test-utils/*.js"
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "@reduxjs/toolkit": "^2.11.2",
+    "gl-matrix": "3.4.4",
+    "gps-plus-slam-js": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@sentry/browser": ">=10.0.0",
+    "@zip.js/zip.js": ">=2.7.0",
+    "h3-js": ">=4.0.0",
+    "leaflet": ">=1.9.0",
+    "three": ">=0.170.0"
+  },
+  "peerDependenciesMeta": {
+    "leaflet": {
+      "optional": true
+    },
+    "@sentry/browser": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@sentry/browser": "^10.49.0",
+    "@types/leaflet": "^1.9.21",
+    "@types/node": "^25.6.0",
+    "@types/three": "^0.184.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/eslint-plugin": "^1.6.16",
+    "@zip.js/zip.js": "^2.8.26",
+    "dpdm": "^4.0.1",
+    "eslint": "^10.2.1",
+    "eslint-config-prettier": "^10.1.8",
+    "fast-check": "^4.7.0",
+    "globals": "^17.5.0",
+    "h3-js": "^4.4.0",
+    "jsdom": "^29.0.2",
+    "leaflet": "^1.9.4",
+    "prettier": "^3.8.3",
+    "three": "^0.184.0",
+    "tsdown": "^0.21.9",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^4.1.5"
+  },
+  "keywords": [
+    "ar",
+    "gps",
+    "slam",
+    "webxr",
+    "three.js",
+    "framework"
+  ],
+  "author": "cs-util-com",
+  "license": "Apache-2.0",
+  "scripts": {
+    "test": "pnpm run test:core",
+    "test:core": "pnpm run format && pnpm run lint && pnpm run typecheck && pnpm run typecheck:tests && pnpm run test:unit",
+    "format": "prettier --log-level warn --write --ignore-unknown --no-error-on-unmatched-pattern \"src\" \"config\" package.json README.md",
+    "format:check": "prettier --check --ignore-unknown .",
+    "build": "tsdown --config config/tsdown.config.ts",
+    "verify:pack": "pnpm pack --dry-run",
+    "test:unit": "vitest run --coverage --config config/vitest.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.vitest.json --noEmit",
+    "lint": "eslint . --config config/eslint.config.mjs",
+    "test:watch": "vitest --config config/vitest.config.ts",
+    "check:cycles": "dpdm -T --exit-code circular:1 --no-warning --no-tree ./src/index.ts",
+    "setup": "bash ./scripts/setup.sh"
+  }
+}