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

package/dist/{webxr-session-DG-eNfny.js → webxr-session-BCP2XK7k.js}

@@ -5,10 +5,10 @@ import { DepthSampler, wrapXRDepthInfo } from "./ar/depth-sampler.js";
 import { WEBXR_TO_NUE } from "./ar/webxr-nue-basis.js";
 import { clearFrameUpdates, runFrameUpdates } from "./ar/frame-loop.js";
 import { clearXrFrameUpdates, runXrFrameUpdates } from "./ar/xr-frame-loop.js";
-import { n as ImageCaptureManager, t as DEFAULT_CAPTURE_CONFIG } from "./image-capture-B2-b6tKK.js";
+import { n as ImageCaptureManager, t as DEFAULT_CAPTURE_CONFIG } from "./image-capture-DVcuqMtX.js";
 import { clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectTrackingPhase } from "./state/tracking-slice.js";
 import { acquireCameraTexture } from "./ar/xr-camera-texture.js";
-import { n as runSessionDisposers } from "./session-disposers-zv9OGXPB.js";
+import { n as runSessionDisposers } from "./session-disposers-BPrMplIC.js";
 import { DEFAULT_RECORDING_OPTIONS, validateArCrashIsolationOptions } from "./state/recording-options.js";
 import { SCENE_NODE } from "./ar/scene-node-names.js";
 import { createCss3dRendererManager } from "./visualization/css3d-renderer-manager.js";
@@ -225,6 +225,8 @@ function resetWebXRState() {
 	onTrackingRestarted = null;
 	onTrackingLost = null;
 	onTrackingRecovered = null;
+	onSessionEnd = null;
+	endRequestedByApp = false;
 	depthSampler = null;
 	onDepthCaptured = null;
 	onDepthUnavailable = null;
@@ -329,6 +331,20 @@ let onTrackingLost = null;
 */
 let onTrackingRecovered = null;
 /**
+* Host callback fired exactly once whenever the XRSession ends — on BOTH the
+* app-initiated and the system-initiated path (set via setSessionEndCallback).
+* Cleared by resetWebXRState() like every other module-level callback.
+*/
+let onSessionEnd = null;
+/**
+* Set by endARSession() immediately before its `xrSession.end()` so the
+* shared 'end' listener can tell the two trigger paths apart (the app's own
+* end() fires the same 'end' event the system path does). Consumed (reset to
+* false) by handleSessionEnded(); also cleared defensively in
+* resetWebXRState() in case end() rejects without the event ever firing.
+*/
+let endRequestedByApp = false;
+/**
 * Depth sampler instance (created when AR session starts with depth callbacks)
 */
 let depthSampler = null;
@@ -563,7 +579,7 @@ function getCurrentArPose() {
 * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
 *   depth-sensing, camera-access)
 * @param sessionFeatures - Opt-in standard WebXR features that are independent
-*   of crash isolation (currently `requestHitTest`)
+*   of crash isolation (`requestHitTest`, `requestDepthOcclusion`)
 * @returns XRSessionInit options
 * @throws Error if rootElement is null
 */
@@ -576,7 +592,7 @@ function buildSessionOptions(rootElement, isolationOptions = {}, sessionFeatures
 		optionalFeatures.push("dom-overlay");
 		sessionOptions.domOverlay = { root: rootElement };
 	}
-	if (normalizedOptions.enableDepthSensingFeature) {
+	if (normalizedOptions.enableDepthSensingFeature || sessionFeatures.requestDepthOcclusion) {
 		optionalFeatures.push("depth-sensing");
 		Object.assign(sessionOptions, { depthSensing: {
 			usagePreference: ["cpu-optimized"],
@@ -600,6 +616,23 @@ async function isWebXRSupported() {
 	}
 }
 /**
+* AR camera frustum constants — the single source of truth for live AR and
+* replay (both build their camera via {@link createSceneHierarchy}).
+*
+* F2 (2026-07-04 user feedback): far raised 100 → 200 m so objects in the
+* reported 100–200 m range are no longer frustum-culled. The far-plane
+* distance itself is essentially free at this app's object counts; the real
+* constraint is depth precision — far/near = 2×10⁴ is comfortable for a
+* 24-bit depth buffer. Revisit the ratio if AR_CAMERA_NEAR ever shrinks.
+*
+* Note: these apply to WebGL content only. The CSS3D minimap is composited by
+* the browser from the camera fov alone — near/far do not clip it (F1 in the
+* same feedback doc).
+*/
+const AR_CAMERA_FOV = 70;
+const AR_CAMERA_NEAR = .01;
+const AR_CAMERA_FAR = 200;
+/**
 * Create the scene hierarchy with proper AR/GPS frame separation.
 * This is a pure function for testability.
 *
@@ -647,7 +680,7 @@ function createSceneHierarchy() {
 	const newArPose = new THREE.Object3D();
 	newArPose.name = "ar-pose";
 	newBasisChangeNode.add(newArPose);
-	const newCamera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, .01, 100);
+	const newCamera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, AR_CAMERA_NEAR, 200);
 	newArPose.add(newCamera);
 	const ambientLight = new THREE.AmbientLight(16777215, .5);
 	newScene.add(ambientLight);
@@ -689,10 +722,7 @@ async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
 	const sessionOptions = buildSessionOptions(container, currentArCrashIsolationOptions, sessionFeatures);
 	xrSession = await navigator.xr.requestSession("immersive-ar", sessionOptions);
 	xrSession.addEventListener("end", () => {
-		log.info("Session ended");
-		if (trackingStore) trackingStore.dispatch(resetTracking());
-		xrSession = null;
-		latestArPose = null;
+		handleSessionEnded();
 	});
 	await renderer.xr.setSession(xrSession);
 	if (onTrackingRestarted && trackingStore) {
@@ -847,8 +877,15 @@ function onXRFrame(time, frame) {
 	if (currentArCrashIsolationOptions.enableCss3dRenderer && css3dManager) css3dManager.render(scene, camera);
 }
 /**
-* Extract depth information from an XR frame.
-* Returns null if depth sensing is not available.
+* Extract depth information from an XR frame. Returns `null` if depth sensing is
+* not available (no pose/view, no `getDepthInformation`, or the call throws).
+*
+* Exported so a consumer can feed the **live depth occluder** from a
+* `registerXrFrameUpdate` callback — the callback has the live `frame` +
+* `referenceSpace`, computes `pose = frame.getViewerPose(referenceSpace)`, and
+* passes both here to obtain the per-frame {@link DepthInfo} (with the widened
+* `data` / `rawValueToMeters` / `normDepthBufferFromNormView` / `projectionMatrix`
+* the occluder needs). The same wrapped depth the sparse grid sampler consumes.
 */
 function getDepthInfoFromFrame(frame, pose) {
 	const view = pose?.views[0];
@@ -984,6 +1021,41 @@ function nueQuaternionToWebXR$1(nue) {
 	return nueQuaternionToWebXR(nue);
 }
 /**
+* Register a host callback fired exactly once whenever the XRSession ends —
+* app-initiated ({@link endARSession}) AND system-initiated (e.g. the Android
+* back gesture, which ends an immersive session directly and uncancelably).
+* `info.requestedByApp` discriminates the two. Fired AFTER the full teardown,
+* so the host can immediately start a fresh session from inside the callback.
+*
+* Cleared by resetWebXRState() (i.e. after every session end) like the other
+* module-level callbacks — re-register before/with each new session.
+* Pass `null` to unregister. F3, 2026-07-04 user feedback.
+*/
+function setSessionEndCallback(cb) {
+	onSessionEnd = cb;
+}
+/**
+* The ONE teardown for a session that has ended, shared by both trigger
+* paths via the XRSession 'end' listener. Before F3 the system-initiated
+* path (back gesture) only nulled `xrSession`/`latestArPose`, leaving the
+* renderer compositing the 3D scene over a black camera background and the
+* host app never notified — the "haunted scene" from
+* docs/2026-02-15-lifecycle-orphans.md §1.
+*/
+function handleSessionEnded() {
+	log.info("Session ended");
+	const callback = onSessionEnd;
+	const requestedByApp = endRequestedByApp;
+	endRequestedByApp = false;
+	if (trackingStore) trackingStore.dispatch(resetTracking());
+	resetWebXRState();
+	if (callback) try {
+		callback({ requestedByApp });
+	} catch (err) {
+		log.error("Session-end callback threw:", err);
+	}
+}
+/**
 * End the current XR session and clean up all resources.
 *
 * Stops the animation loop, ends the XR session, then delegates the full
@@ -996,7 +1068,10 @@ function nueQuaternionToWebXR$1(nue) {
 async function endARSession() {
 	if (renderer) renderer.setAnimationLoop(null);
 	try {
-		if (xrSession) await xrSession.end();
+		if (xrSession) {
+			endRequestedByApp = true;
+			await xrSession.end();
+		}
 	} finally {
 		resetWebXRState();
 	}
@@ -1284,4 +1359,4 @@ function getLiveCss3dManager() {
 	return css3dManager;
 }
 //#endregion
-export { setFrameCallback as A, startDepthCapture as B, nueQuaternionToWebXR$1 as C, setCamera as D, setArWorldGroup as E, setTrackingLostCallback as F, CameraFrameSource as G, stopCameraFrameCapture as H, setTrackingRecoveredCallback as I, setTrackingStore as L, setImageQualityAnalyzer as M, setScene as N, setCameraFrameCallback as O, setTrackingCallbacks as P, shouldLogCameraAccessDiagnostic as R, nuePositionToWebXR as S, setArPose as T, stopDepthCapture as U, startImageCapture as V, stopImageCapture as W, getScene as _, endARSession as a, isWebXRSupported as b, getArPose as c, getCameraFrameCaptureSize as d, getCameraFrameCount as f, getLiveCss3dManager as g, getImageCaptureFrameCount as h, createSceneHierarchy as i, setImageCaptureCallback as j, setDepthCaptureCallback as k, getArWorldGroup as l, getDepthSampleCount as m, applyAlignmentMatrix as n, extractPoseFromViewer as o, getCurrentArPose as p, buildSessionOptions as r, extractResetTransformData as s, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as t, getCamera as u, getXrCameraFromPose as v, resetWebXRState as w, isXRCameraLike as x, initAR as y, startCameraFrameCapture as z };
+export { setArWorldGroup as A, setTrackingLostCallback as B, initAR as C, nueQuaternionToWebXR$1 as D, nuePositionToWebXR as E, setImageCaptureCallback as F, startDepthCapture as G, setTrackingStore as H, setImageQualityAnalyzer as I, stopDepthCapture as J, startImageCapture as K, setScene as L, setCameraFrameCallback as M, setDepthCaptureCallback as N, resetWebXRState as O, setFrameCallback as P, setSessionEndCallback as R, getXrCameraFromPose as S, isXRCameraLike as T, shouldLogCameraAccessDiagnostic as U, setTrackingRecoveredCallback as V, startCameraFrameCapture as W, CameraFrameSource as X, stopImageCapture as Y, getDepthInfoFromFrame as _, applyAlignmentMatrix as a, getLiveCss3dManager as b, endARSession as c, getArPose as d, getArWorldGroup as f, getCurrentArPose as g, getCameraFrameCount as h, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as i, setCamera as j, setArPose as k, extractPoseFromViewer as l, getCameraFrameCaptureSize as m, AR_CAMERA_FOV as n, buildSessionOptions as o, getCamera as p, stopCameraFrameCapture as q, AR_CAMERA_NEAR as r, createSceneHierarchy as s, AR_CAMERA_FAR as t, extractResetTransformData as u, getDepthSampleCount as v, isWebXRSupported as w, getScene as x, getImageCaptureFrameCount as y, setTrackingCallbacks as z };

package/dist/{webxr-session-Do5L6G3B.d.ts → webxr-session-BWCpGd-2.d.ts}

@@ -1,11 +1,11 @@
-import { i as DepthSample, t as ARPose } from "./ar-types-BFX2r1wk.js";
-import { i as DepthSamplerConfig } from "./depth-sampler-asc8exHt.js";
-import { t as ArCrashIsolationOptions } from "./recording-options-BPCpMHLK.js";
-import { i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, t as CapturedFrame } from "./image-capture-CNZDrQXG.js";
-import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-BuAZxXZ5.js";
-import { o as RgbaImage } from "./qr-frontend--fFX25mV.js";
-import { t as Css3dRendererManager } from "./css3d-renderer-manager-B3kGNtcn.js";
-import { r as XRCameraLike } from "./xr-camera-texture-Cva1q3Qj.js";
+import { i as DepthSample, t as ARPose } from "./ar-types-Cc5yvBwn.js";
+import { i as DepthSamplerConfig, t as DepthInfo } from "./depth-sampler-CwObAwEA.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-DYKWVI93.js";
+import { i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, t as CapturedFrame } from "./image-capture-Bp6Pd4Md.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-DMkHlbny.js";
+import { o as RgbaImage } from "./qr-frontend-BPURlh3S.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-CPpVtvgs.js";
+import { r as XRCameraLike } from "./xr-camera-texture-q0eIDSRg.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
 
@@ -69,6 +69,16 @@ declare function shouldLogCameraAccessDiagnostic(pose: XRViewerPose | null, alre
  * @internal
  */
 declare function resetWebXRState(): void;
+/**
+ * Info passed to the session-end callback (F3, 2026-07-04 user feedback).
+ * `requestedByApp` discriminates the app's own `endARSession()` from a
+ * system-initiated end (e.g. the Android back gesture, which ends an
+ * immersive XRSession directly — no popstate, no beforeunload, not
+ * cancelable).
+ */
+interface SessionEndInfo {
+  requestedByApp: boolean;
+}
 /**
  * Default longer-edge resolution (px) for the camera-frame blit the QR / CV
  * detector sees. The on-device capture-resolution sweep (2026-06-17, via the
@@ -129,6 +139,18 @@ interface SessionFeatureOptions {
    * existing recorder/anchor sessions are unaffected.
    */
   requestHitTest?: boolean;
+  /**
+   * Request `depth-sensing` (cpu-optimized) for the **live depth occluder**
+   * even when crash-isolation's `enableDepthSensingFeature` is off. Consumer
+   * apps (AnchorStarter / MinimalExample) want occlusion without the recorder's
+   * depth-capture wiring, so the occluder owns its own session-feature switch.
+   * Both flags resolve the **same** cpu-optimized usage — setting both is valid
+   * (no conflict, no throw): the grid sampler and the occluder are two consumers
+   * of one depth read. Default `false`.
+   *
+   * @see GpsPlusSlamJs_Docs/docs/2026-06-14-webxr-depth-occlusion-plan.md §6/§8
+   */
+  requestDepthOcclusion?: boolean;
 }
 /**
  * Build XR session init options.
@@ -138,7 +160,7 @@ interface SessionFeatureOptions {
  * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
  *   depth-sensing, camera-access)
  * @param sessionFeatures - Opt-in standard WebXR features that are independent
- *   of crash isolation (currently `requestHitTest`)
+ *   of crash isolation (`requestHitTest`, `requestDepthOcclusion`)
  * @returns XRSessionInit options
  * @throws Error if rootElement is null
  */
@@ -147,6 +169,23 @@ declare function buildSessionOptions(rootElement: Element | null, isolationOptio
  * Check if WebXR immersive-ar is supported
  */
 declare function isWebXRSupported(): Promise<boolean>;
+/**
+ * AR camera frustum constants — the single source of truth for live AR and
+ * replay (both build their camera via {@link createSceneHierarchy}).
+ *
+ * F2 (2026-07-04 user feedback): far raised 100 → 200 m so objects in the
+ * reported 100–200 m range are no longer frustum-culled. The far-plane
+ * distance itself is essentially free at this app's object counts; the real
+ * constraint is depth precision — far/near = 2×10⁴ is comfortable for a
+ * 24-bit depth buffer. Revisit the ratio if AR_CAMERA_NEAR ever shrinks.
+ *
+ * Note: these apply to WebGL content only. The CSS3D minimap is composited by
+ * the browser from the camera fov alone — near/far do not clip it (F1 in the
+ * same feedback doc).
+ */
+declare const AR_CAMERA_FOV = 70;
+declare const AR_CAMERA_NEAR = 0.01;
+declare const AR_CAMERA_FAR = 200;
 /**
  * Create the scene hierarchy with proper AR/GPS frame separation.
  * This is a pure function for testability.
@@ -196,6 +235,18 @@ declare function createSceneHierarchy(): {
  *   `requestHitTest`) forwarded to the session negotiation.
  */
 declare function initAR(container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions): Promise<void>;
+/**
+ * Extract depth information from an XR frame. Returns `null` if depth sensing is
+ * not available (no pose/view, no `getDepthInformation`, or the call throws).
+ *
+ * Exported so a consumer can feed the **live depth occluder** from a
+ * `registerXrFrameUpdate` callback — the callback has the live `frame` +
+ * `referenceSpace`, computes `pose = frame.getViewerPose(referenceSpace)`, and
+ * passes both here to obtain the per-frame {@link DepthInfo} (with the widened
+ * `data` / `rawValueToMeters` / `normDepthBufferFromNormView` / `projectionMatrix`
+ * the occluder needs). The same wrapped depth the sparse grid sampler consumes.
+ */
+declare function getDepthInfoFromFrame(frame: XRFrame, pose: XRViewerPose | null): DepthInfo | null;
 /**
  * Get the current Three.js scene (for adding objects like map)
  */
@@ -284,6 +335,18 @@ declare function nuePositionToWebXR(nue: readonly number[]): readonly [number, n
  * NUE [x, y, z, w] → WebXR [z, y, -x, w]
  */
 declare function nueQuaternionToWebXR$1(nue: readonly number[]): readonly [number, number, number, number];
+/**
+ * Register a host callback fired exactly once whenever the XRSession ends —
+ * app-initiated ({@link endARSession}) AND system-initiated (e.g. the Android
+ * back gesture, which ends an immersive session directly and uncancelably).
+ * `info.requestedByApp` discriminates the two. Fired AFTER the full teardown,
+ * so the host can immediately start a fresh session from inside the callback.
+ *
+ * Cleared by resetWebXRState() (i.e. after every session end) like the other
+ * module-level callbacks — re-register before/with each new session.
+ * Pass `null` to unregister. F3, 2026-07-04 user feedback.
+ */
+declare function setSessionEndCallback(cb: ((info: SessionEndInfo) => void) | null): void;
 /**
  * End the current XR session and clean up all resources.
  *
@@ -464,4 +527,4 @@ declare function setFrameCallback(callback: (() => void) | null): void;
  */
 declare function getLiveCss3dManager(): Css3dRendererManager | null;
 //#endregion
-export { setCamera as A, setTrackingStore as B, isWebXRSupported as C, resetWebXRState as D, nueQuaternionToWebXR$1 as E, setImageQualityAnalyzer as F, stopCameraFrameCapture as G, startCameraFrameCapture as H, setScene as I, stopDepthCapture as K, setTrackingCallbacks as L, setDepthCaptureCallback as M, setFrameCallback as N, setArPose as O, setImageCaptureCallback as P, setTrackingLostCallback as R, initAR as S, nuePositionToWebXR as T, startDepthCapture as U, shouldLogCameraAccessDiagnostic as V, startImageCapture as W, getDepthSampleCount as _, applyAlignmentMatrix as a, getScene as b, endARSession as c, getArPose as d, getArWorldGroup as f, getCurrentArPose as g, getCameraFrameCount as h, TrackingSubscribableStore as i, setCameraFrameCallback as j, setArWorldGroup as k, extractPoseFromViewer as l, getCameraFrameCaptureSize as m, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as n, buildSessionOptions as o, getCamera as p, stopImageCapture as q, SessionFeatureOptions as r, createSceneHierarchy as s, CameraFrameCaptureConfig as t, extractResetTransformData as u, getImageCaptureFrameCount as v, isXRCameraLike as w, getXrCameraFromPose as x, getLiveCss3dManager as y, setTrackingRecoveredCallback as z };
+export { stopImageCapture as $, nuePositionToWebXR as A, setImageQualityAnalyzer as B, getImageCaptureFrameCount as C, initAR as D, getXrCameraFromPose as E, setCamera as F, setTrackingRecoveredCallback as G, setSessionEndCallback as H, setCameraFrameCallback as I, startCameraFrameCapture as J, setTrackingStore as K, setDepthCaptureCallback as L, resetWebXRState as M, setArPose as N, isWebXRSupported as O, setArWorldGroup as P, stopDepthCapture as Q, setFrameCallback as R, getDepthSampleCount as S, getScene as T, setTrackingCallbacks as U, setScene as V, setTrackingLostCallback as W, startImageCapture as X, startDepthCapture as Y, stopCameraFrameCapture as Z, getCamera as _, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as a, getCurrentArPose as b, TrackingSubscribableStore as c, createSceneHierarchy as d, endARSession as f, getArWorldGroup as g, getArPose as h, CameraFrameCaptureConfig as i, nueQuaternionToWebXR$1 as j, isXRCameraLike as k, applyAlignmentMatrix as l, extractResetTransformData as m, AR_CAMERA_FOV as n, SessionEndInfo as o, extractPoseFromViewer as p, shouldLogCameraAccessDiagnostic as q, AR_CAMERA_NEAR as r, SessionFeatureOptions as s, AR_CAMERA_FAR as t, buildSessionOptions as u, getCameraFrameCaptureSize as v, getLiveCss3dManager as w, getDepthInfoFromFrame as x, getCameraFrameCount as y, setImageCaptureCallback as z };

package/dist/{zip-reader-D9iPQwdQ.d.ts → zip-reader-BzENzMH6.d.ts}

@@ -1,6 +1,32 @@
-import { Entry, Entry as Entry$1 } from "@zip.js/zip.js";
+import { Entry, Entry as Entry$1, Reader, ZipReader } from "@zip.js/zip.js";
 
 //#region ../src/storage/zip-reader.d.ts
+/**
+ * Input accepted by the zip-reading helpers: either the full zip bytes
+ * (the original behavior) or any zip.js {@link Reader} — e.g. a ranged
+ * reader over a file descriptor — so callers scanning many large archives
+ * can read only the central directory + the entries they open instead of
+ * loading whole files into memory.
+ *
+ * Reader contract: a single Reader instance may back several helper calls
+ * concurrently (see `loadRecording` in gps-plus-slam-recorder, which fans
+ * out over three helpers via Promise.all), so `init()` must be idempotent
+ * and `readUint8Array(index, length)` must support interleaved ranged reads.
+ * The caller owns the underlying resource lifecycle (helpers close their
+ * ZipReader wrappers, never the Reader's resource).
+ */
+type ZipSource = Uint8Array | Reader<unknown>;
+/**
+ * Wrap a {@link ZipSource} in a fresh zip.js ZipReader.
+ *
+ * Exported deliberately: consumers outside this workspace resolve this
+ * module from the published dist at runtime and probe
+ * `typeof toZipReader === 'function'` as the capability marker for lazy
+ * Reader support before passing anything other than Uint8Array (older
+ * published versions accept only Uint8Array). Do not rename or remove
+ * without treating it as a breaking API change.
+ */
+declare function toZipReader(source: ZipSource): ZipReader<unknown>;
 /**
  * Maximum allowed uncompressed size (in bytes) for a single action or
  * metadata JSON file inside a recording zip. Entries exceeding this limit
@@ -29,32 +55,32 @@ interface ZipActionEntry {
 /**
  * Read all entries from a zip file.
  *
- * @param data - The zip file content as a Uint8Array
+ * @param data - The zip content as a Uint8Array, or a zip.js Reader for lazy access
  * @returns Array of zip entries (directories and files)
  */
-declare function readZipEntries(data: Uint8Array): Promise<Entry[]>;
+declare function readZipEntries(data: ZipSource): 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 data - The zip content as a Uint8Array, or a zip.js Reader for lazy access
  * @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[]>;
+declare function loadActionsFromZip(data: ZipSource, 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 data - The zip content as a Uint8Array, or a zip.js Reader for lazy access
  * @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>;
+declare function loadSessionMetadata(data: ZipSource, maxFileSize?: number): Promise<Record<string, unknown> | null>;
 /**
  * Load session metadata from session.json in a zip file provided as a Blob.
  *
@@ -126,9 +152,9 @@ interface ZipSubdirEntry {
  * `relativePath` for deterministic iteration. Returns an empty array when
  * the subdir is absent (graceful degradation for older zips).
  *
- * @param data - The zip file content as a Uint8Array
+ * @param data - The zip content as a Uint8Array, or a zip.js Reader for lazy access
  * @param subdir - Top-level subdir to scan (no leading or trailing `/`)
  */
-declare function loadEntriesFromSubdir(data: Uint8Array, subdir: string): Promise<ZipSubdirEntry[]>;
+declare function loadEntriesFromSubdir(data: ZipSource, subdir: string): Promise<ZipSubdirEntry[]>;
 //#endregion
-export { ZipActionEntry as a, loadEntriesFromSubdir as c, loadSessionMetadataFromBlob as d, readZipEntries as f, RecordedAction as i, loadGpsPathFromBlob as l, GpsPathCoord as n, ZipSubdirEntry as o, MAX_ACTION_FILE_SIZE as r, loadActionsFromZip as s, Entry$1 as t, loadSessionMetadata as u };
+export { ZipActionEntry as a, loadActionsFromZip as c, loadSessionMetadata as d, loadSessionMetadataFromBlob as f, RecordedAction as i, loadEntriesFromSubdir as l, toZipReader as m, GpsPathCoord as n, ZipSource as o, readZipEntries as p, MAX_ACTION_FILE_SIZE as r, ZipSubdirEntry as s, Entry$1 as t, loadGpsPathFromBlob as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gps-plus-slam-app-framework",
-  "version": "1.7.0",
+  "version": "1.9.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": [
@@ -31,12 +31,12 @@
   },
   "types": "./dist/index.d.ts",
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22"
   },
   "dependencies": {
     "@reduxjs/toolkit": "^2.11.2",
     "gl-matrix": "3.4.4",
-    "gps-plus-slam-js": "^1.7.0"
+    "gps-plus-slam-js": "^1.9.0"
   },
   "peerDependencies": {
     "@sentry/browser": ">=10.0.0",
@@ -58,6 +58,7 @@
     "@sentry/browser": "^10.53.1",
     "@types/leaflet": "^1.9.21",
     "@types/node": "^25.7.0",
+    "@types/qrcode": "^1.5.6",
     "@types/three": "^0.184.1",
     "@vitest/coverage-v8": "^4.1.6",
     "@vitest/eslint-plugin": "^1.6.17",
@@ -71,6 +72,7 @@
     "jsdom": "^29.1.1",
     "leaflet": "^1.9.4",
     "prettier": "^3.8.3",
+    "qrcode": "^1.5.4",
     "three": "^0.184.0",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
@@ -104,11 +106,13 @@
     "build": "tsdown --config config/tsdown.config.ts",
     "verify:pack": "pnpm pack --dry-run",
     "verify:community-key-lifetime": "node scripts/verify-community-key-lifetime.mjs",
-    "test:unit": "vitest run --coverage --config config/vitest.config.ts",
+    "test:unit": "node ../scripts/run-vitest-scoped.mjs run --coverage --config=config/vitest.config.ts",
     "typecheck": "tsc -p tsconfig.app.json --noEmit",
     "typecheck:tests": "tsc -p tsconfig.vitest.json --noEmit",
-    "lint": "eslint . --config config/eslint.config.mjs",
+    "lint": "eslint . --config config/eslint.config.mjs --max-warnings 37",
     "test:watch": "vitest --config config/vitest.config.ts",
+    "bench": "vitest bench --run --config config/vitest.bench.config.ts",
+    "bench:watch": "vitest bench --config config/vitest.bench.config.ts",
     "check:cycles": "dpdm -T --exit-code circular:1 --no-warning --no-tree ./src/index.ts",
     "setup": "bash ./scripts/setup.sh"
   }

package/dist/index-_Rhgoqkh.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, arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords as calcGpsCoords$1, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey as validateLicenseKey$1, webxrToNUE } from "gps-plus-slam-js";
-export { odometryTrackingRestarted as _, LibraryRootState as a, RootState$1 as c, bearingDeltaDeg as d, calcGpsCoords$1 as f, magneticHeadingFromEnuQuat as g, isIdentityMatrix4 as h, LatLongAlt as i, Vector3$1 as l, createGpsSlamStore as m, GpsPoint$1 as n, Matrix4$1 as o, calcRelativeCoordsInMeters as p, LatLong$1 as r, Quaternion$1 as s, ArImageCapture$1 as t, arNorthBearingDeg as u, validateLicenseKey$1 as v, webxrToNUE as y };

package/dist/lerp-utils-BLmHhkVe.d.ts

@@ -1,20 +0,0 @@
-//#region ../src/visualization/lerp-utils.d.ts
-/**
- * Shared lerp utilities for visualization modules.
- *
- * Both alignment-lerper and camera-follower need the same smoothing
- * rate constant and clamped-alpha formula. Centralised here (R3) to
- * keep the two modules in sync.
- */
-/** Default speed multiplier — ~90 % convergence in ~0.3 s at 60 fps. */
-declare const DEFAULT_LERP_RATE = 8;
-/**
- * Compute a frame-rate-independent lerp/slerp factor clamped to [0, 1].
- *
- * @param lerpRate Speed multiplier (higher = faster convergence).
- * @param dt       Delta time in seconds since last frame.
- * @returns The interpolation alpha, guaranteed ≤ 1.0.
- */
-declare function clampedAlpha(lerpRate: number, dt: number): number;
-//#endregion
-export { clampedAlpha as n, DEFAULT_LERP_RATE as t };

package/dist/map-data-B4oEehUh.d.ts

@@ -1,49 +0,0 @@
-import { n as RawGpsSample, t as GpsCoord } from "./geo-types-3Ip1NzVR.js";
-import { LatLong, Matrix4, Vector3 } from "gps-plus-slam-js";
-
-//#region ../src/visualization/map-data.d.ts
-/** Fully-resolved trajectory data ready to be drawn onto a Leaflet map. */
-interface MapData {
-  /** Latest user GPS position (blue dot), or null when unknown. */
-  userPosition: GpsCoord | null;
-  /** Raw GPS samples (yellow polyline + per-event accuracy circles). */
-  rawGpsPath: RawGpsSample[];
-  /** Fused SLAM+GPS positions (cyan polyline), recomputed from latest matrix. */
-  fusedPath: GpsCoord[];
-  /** Alignment-snapshot GPS positions (red). */
-  alignmentSnapshots: GpsCoord[];
-}
-/**
- * Inputs to {@link buildMapData}, all optional so callers can supply only the
- * slices they have. Array inputs are read-only and defensively copied.
- */
-interface MapDataInput {
-  /** Raw GPS samples in chronological order. */
-  rawGpsPath?: readonly RawGpsSample[];
-  /** Odometry positions (AR-local) used to derive the fused path. */
-  odometryPositions?: ReadonlyArray<Vector3>;
-  /** Latest alignment matrix from the solver (null until first solve). */
-  alignmentMatrix?: Matrix4 | null;
-  /** GPS origin for ENU→GPS conversion (null when no GPS yet). */
-  zeroRef?: LatLong | null;
-  /** Alignment-snapshot GPS positions. */
-  alignmentSnapshots?: readonly GpsCoord[];
-  /**
-   * Explicit user position. When omitted, defaults to the last entry of
-   * `rawGpsPath` (or null when there is none).
-   */
-  userPosition?: GpsCoord | null;
-}
-/**
- * Build a {@link MapData} snapshot from store-derived inputs.
- *
- * Pure and free of Leaflet/Three dependencies. The fused path is always
- * derived via {@link computeFusedPath} (D2); when the matrix or zero reference
- * is missing it is an empty array.
- *
- * @param input - Optional trajectory slices (see {@link MapDataInput}).
- * @returns A fully-resolved {@link MapData} with all arrays defensively copied.
- */
-declare function buildMapData(input: MapDataInput): MapData;
-//#endregion
-export { MapDataInput as n, buildMapData as r, MapData as t };

package/dist/occupancy-grid-DnOc-6PU.d.ts

@@ -1,82 +0,0 @@
-import { t as GridCell } from "./bresenham3d-CU1Gv2W4.js";
-import { a as RgbTuple, i as DepthSample } from "./ar-types-BFX2r1wk.js";
-import { Vector3 } from "gps-plus-slam-js";
-
-//#region ../src/ar/occupancy-grid.d.ts
-interface OccupancyGridOptions {
-  /** Edge length of a cubic grid cell in meters. Default 0.15 (Unity parity). */
-  readonly cellSizeM?: number;
-  /**
-   * Dominant-axis steps before a ray's endpoint at which free-space
-   * carving stops, to respect depth noise. Default 2 (Unity parity).
-   */
-  readonly carveStopCells?: number;
-}
-declare class OccupancyGrid {
-  readonly cellSizeM: number;
-  readonly carveStopCells: number;
-  private readonly cells;
-  constructor(options?: OccupancyGridOptions);
-  /** Number of occupied cells. */
-  get size(): number;
-  /**
-   * Fold one depth sample into the grid: unproject each point, carve free
-   * space from the camera cell to the point cell, then count the point's
-   * cell as occupied. Points that cannot be unprojected (no
-   * projectionMatrix on old recordings, invalid depth/coords) are skipped.
-   *
-   * Carving and incrementing run as two separate passes over the sample's
-   * points: all rays are carved first, then every endpoint is incremented.
-   * A single interleaved pass would be order-dependent — a deeper point's
-   * carve could erase the endpoint a nearer point added earlier in the same
-   * sample. Splitting the passes makes the result deterministic and lets an
-   * endpoint observed within a sample survive other rays in that same
-   * sample. (Deeper-carves-nearer still applies ACROSS samples: a later
-   * sample's ray carves an earlier sample's endpoint as before.)
-   *
-   * @returns the number of points actually added.
-   */
-  addSample(sample: DepthSample): number;
-  /** Occupied cells observed at least `minObservations` times (default 1). */
-  getOccupiedCells(minObservations?: number): GridCell[];
-  /** Quantize a raw-WebXR position to its grid cell (round per axis). */
-  cellForPosition(pos: Vector3): GridCell;
-  /** Center of a cell in raw WebXR space (round-consistent: cell · cellSizeM). */
-  getCellCenter(cell: GridCell): Vector3;
-  /**
-   * Running-average of the EXACT unprojected surface points observed in this
-   * cell (raw WebXR space), or null for an unknown cell. Unlike
-   * {@link getCellCenter} (the geometric 15 cm-lattice center) this hugs the
-   * real measured surface and noise-averages across viewpoints — used by the
-   * COLMAP `points3D` export and the debug cubes (follow-up Item A). Being a
-   * centroid of points that fell in the cell, it always lies within
-   * `cellSizeM/2` of the cell center per axis.
-   */
-  getCellPoint(cell: GridCell): Vector3 | null;
-  /**
-   * Running-average color of the cell's colored observations (Iter 8), or
-   * null when the cell is unknown or was only ever observed without color
-   * (rgb option off / pre-Iter-8 recordings) — consumers fall back to
-   * height-based coloring. Channels are rounded and clamped to 0–255.
-   */
-  getCellColor(cell: GridCell): RgbTuple | null;
-  /**
-   * Walk the grid from `startPos` to `endPos` and return the center of the
-   * first cell occupied at least `minObservations` times, or null.
-   * Port of Unity's `TryRaycast` (hook for cursor/floor-detection parity).
-   */
-  raycast(startPos: Vector3, endPos: Vector3, minObservations?: number): Vector3 | null;
-  /** Remove all occupied cells (e.g. on store swap / new session). */
-  clear(): void;
-  /**
-   * Delete occupied cells along the camera→point ray (the space was seen
-   * through, so it must be free), stopping `carveStopCells` dominant-axis
-   * steps before the endpoint. The endpoint cell itself is additionally
-   * protected so a current observation is never erased (relevant for
-   * carveStopCells = 0 and for the unconditional start-cell visit).
-   */
-  private carve;
-  private increment;
-}
-//#endregion
-export { OccupancyGridOptions as n, OccupancyGrid as t };