gps-plus-slam-app-framework 1.2.0 → 1.4.0

package/dist/{webxr-session-QhcSSub5.js → webxr-session-CJF9Nijp.js}

@@ -1,19 +1,92 @@
 import { createLogger } from "./utils/logger.js";
-import { CameraBlitCapture, computeCaptureSize } from "./ar/camera-blit-capture.js";
+import { CameraBlitCapture, computeAspectFitSize, computeCaptureSize } from "./ar/camera-blit-capture.js";
 import { getLastDeviceOrientation } from "./state/gps-event-coordinator.js";
 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 { WEBXR_TO_NUE } from "./ar/webxr-nue-basis.js";
 import { DEFAULT_CAPTURE_CONFIG, ImageCaptureManager } from "./ar/image-capture.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-M-oashRH.js";
+import { n as runSessionDisposers } from "./session-disposers-D8wnO-uW.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";
 import * as THREE from "three";
 import { nueQuaternionToWebXR, nueToWebXR } from "gps-plus-slam-js";
+//#region ../src/ar/camera-frame-source.ts
+const DEFAULT_CONFIG = { intervalMs: 125 };
+/**
+* Throttled RGBA capturer. Construct with the injected `capture`/`onCapture`
+* pair, `start()`, then call `onFrame(timestamp)` once per XR frame.
+*/
+var CameraFrameSource = class {
+	callbacks;
+	config;
+	running = false;
+	captureCount = 0;
+	lastCaptureTime = -Infinity;
+	constructor(callbacks, config) {
+		this.callbacks = callbacks;
+		this.config = { ...DEFAULT_CONFIG };
+		if (config) this.updateConfig(config);
+	}
+	/** Begin throttling. Resets the cadence so the first tick captures. */
+	start() {
+		this.running = true;
+		this.captureCount = 0;
+		this.lastCaptureTime = -Infinity;
+	}
+	/** Stop capturing. `onFrame` becomes a no-op until `start()` is called again. */
+	stop() {
+		this.running = false;
+	}
+	isRunning() {
+		return this.running;
+	}
+	/** Number of frames successfully captured + delivered since `start()`. */
+	getFrameCount() {
+		return this.captureCount;
+	}
+	getConfig() {
+		return { ...this.config };
+	}
+	/**
+	* Apply partial config (e.g. the app's detection cadence). Invalid values
+	* are ignored defensively — `intervalMs` requires a finite positive number.
+	*/
+	updateConfig(config) {
+		if (typeof config.intervalMs === "number" && Number.isFinite(config.intervalMs) && config.intervalMs > 0) this.config.intervalMs = config.intervalMs;
+	}
+	/**
+	* Per-XR-frame tick. Captures + delivers a frame at most once per
+	* `intervalMs`; otherwise a cheap no-op so it is safe to call every frame.
+	*
+	* @param timestamp - monotonic frame time in ms (the XR `time` argument).
+	*/
+	onFrame(timestamp) {
+		if (!this.running) return;
+		if (timestamp - this.lastCaptureTime < this.config.intervalMs) return;
+		const image = this.captureSafely();
+		if (!image) return;
+		this.lastCaptureTime = timestamp;
+		this.captureCount++;
+		this.callbacks.onCapture(image);
+	}
+	/**
+	* Run the injected capture, guarded so a blit failure (e.g. GL context loss)
+	* can never throw out of the XR frame loop — it degrades to "no frame this
+	* tick", exactly like a missing texture.
+	*/
+	captureSafely() {
+		try {
+			return this.callbacks.capture();
+		} catch {
+			return null;
+		}
+	}
+};
+//#endregion
 //#region ../src/ar/depth-rgb-lookup.ts
 /**
 * Build an {@link RgbLookup} over an RGBA readback buffer.
@@ -159,6 +232,13 @@ function resetWebXRState() {
 		depthRgbBlit.dispose();
 		depthRgbBlit = null;
 	}
+	cameraFrameSource = null;
+	onCameraFrame = null;
+	cameraFrameCaptureSize = DEFAULT_CAMERA_FRAME_CAPTURE_SIZE;
+	if (cameraFrameBlit) {
+		cameraFrameBlit.dispose();
+		cameraFrameBlit = null;
+	}
 	onFrameCallback = null;
 	if (css3dManager) {
 		css3dManager.dispose();
@@ -285,6 +365,53 @@ const DEPTH_RGB_BLIT_CONFIG = {
 	height: 192
 };
 /**
+* Session-owned blit target for the generic camera-frame RGBA capture
+* (framework-wiring options Part A / B2) — feeds QR detection today, object
+* detection / OpenCV later. Separate from `depthRgbBlit` (256×192) on purpose:
+* CV detection needs more pixels across the target (~1024 long edge) than a
+* colour lookup, but only at the detection cadence, so the {@link CameraFrameSource}
+* throttle keeps the readback off the per-frame path. Created lazily on the
+* first capture, disposed by resetWebXRState(). The longer-edge size is
+* configurable via `startCameraFrameCapture`; the blit preserves the camera
+* aspect (see `acquireCameraFrameRgba`).
+*/
+let cameraFrameBlit = null;
+/**
+* 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
+* `?capture=` override) showed **1024** decodes a small / out-of-focus QR
+* markedly better than the prior 512 with no perceptible cadence cost on the
+* test phone; 2048 helped slightly more but risks low-end devices (4096 lagged),
+* so 1024 is the safe default. Raise per-consumer via
+* `startCameraFrameCapture({ captureSize })`.
+*
+* @see GpsPlusSlamJs_Docs/docs/2026-06-17-qr-size-accuracy-and-thin-demo-plan.md (WS-C)
+*/
+const DEFAULT_CAMERA_FRAME_CAPTURE_SIZE = 1024;
+/**
+* Longer-edge resolution of the camera-frame blit (px), default
+* {@link DEFAULT_CAMERA_FRAME_CAPTURE_SIZE}. The blit preserves the camera
+* aspect, so the actual target is e.g. 1024×768 for a 4:3 frame — see
+* `computeAspectFitSize` / `acquireCameraFrameRgba`.
+*/
+let cameraFrameCaptureSize = DEFAULT_CAMERA_FRAME_CAPTURE_SIZE;
+/**
+* Throttled camera frame source (created in initAR when `onCameraFrame` is
+* set). Blits the camera texture to RGBA at the detection cadence and hands it
+* to `onCameraFrame`. @see camera-frame-source.ts
+*
+* SINGLE consumer by design: one source, one callback, one blit. That covers
+* one CV consumer at a time (QR *or* object detection). To run two live CV
+* consumers **simultaneously** at independent cadences/resolutions, replace this
+* single-callback wiring with a small registry (e.g.
+* `registerCameraFrameConsumer({ intervalMs, captureSize, onFrame })`) holding a
+* `CameraFrameSource` per consumer — the class is already per-instance. See the
+* SCOPE note in `camera-frame-source.ts`.
+*/
+let cameraFrameSource = null;
+/** Callback for each throttled camera RGBA frame (set via setCameraFrameCallback). */
+let onCameraFrame = null;
+/**
 * Latest WebXR camera texture, updated each frame when camera-access is enabled.
 * Acquired via Three.js's renderer.xr.getCameraTexture() API (ExternalTexture).
 * @see xr-camera-texture.ts
@@ -333,6 +460,20 @@ function acquireDepthRgbLookup() {
 	return readback ? createRgbLookup(readback.pixels, readback.width, readback.height) : null;
 }
 /**
+* Capture the current XR frame as top-left RGBA for CV detection (the
+* `capture` injected into {@link CameraFrameSource}; called at most once per
+* detection interval). Returns null — no frame this tick — when camera access
+* or the texture is unavailable; the lazy blit makes a disposal elsewhere
+* self-healing. Reuses `latestCameraTexture`, exactly like the depth-RGB path.
+*/
+function acquireCameraFrameRgba() {
+	if (!renderer || !latestCameraTexture) return null;
+	const target = computeAspectFitSize(latestCameraWidth, latestCameraHeight, cameraFrameCaptureSize);
+	if (!cameraFrameBlit) cameraFrameBlit = new CameraBlitCapture(target);
+	else cameraFrameBlit.resizeIfNeeded(target.width, target.height);
+	return cameraFrameBlit.captureToRgba(renderer, latestCameraTexture);
+}
+/**
 * Extract the reset transform from an XRReferenceSpaceEvent-like object.
 *
 * Distinguishes three cases per OdometryTrackingRestartedPayload semantics:
@@ -563,6 +704,13 @@ async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
 		acquireRgbLookup: acquireDepthRgbLookup,
 		onDepthUnavailable: onDepthUnavailable ?? void 0
 	});
+	if (onCameraFrame) {
+		const deliver = onCameraFrame;
+		cameraFrameSource = new CameraFrameSource({
+			capture: acquireCameraFrameRgba,
+			onCapture: (image) => deliver(image)
+		});
+	}
 	renderer.setAnimationLoop(onXRFrame);
 	log.info("AR session started");
 }
@@ -681,6 +829,7 @@ function onXRFrame(time, frame) {
 		const depthInfo = getDepthInfoFromFrame(frame, pose);
 		depthSampler.onFrame(time, depthInfo);
 	}
+	if (cameraFrameSource) cameraFrameSource.onFrame(time);
 	if (onFrameCallback) try {
 		onFrameCallback();
 	} catch (error) {
@@ -897,14 +1046,28 @@ function startImageCapture(config) {
 	const currentRenderer = renderer;
 	const divisor = mergedConfig.resolutionDivisor;
 	callbacks.captureFrame = async (quality) => {
-		if (!blitCapture || !latestCameraTexture) return new Promise((resolve) => {
-			currentRenderer.domElement.toBlob((blob) => resolve(blob), "image/jpeg", quality);
-		});
+		const bc = blitCapture;
+		if (!bc || !latestCameraTexture) {
+			const canvas = currentRenderer.domElement;
+			return new Promise((resolve) => {
+				canvas.toBlob((blob) => resolve(blob ? {
+					blob,
+					width: canvas.width,
+					height: canvas.height
+				} : null), "image/jpeg", quality);
+			});
+		}
 		if (latestCameraWidth > 0 && latestCameraHeight > 0) {
 			const target = computeCaptureSize(latestCameraWidth, latestCameraHeight, divisor);
-			blitCapture.resizeIfNeeded(target.width, target.height);
+			bc.resizeIfNeeded(target.width, target.height);
 		}
-		return blitCapture.captureToBlob(currentRenderer, latestCameraTexture, quality);
+		const blob = await bc.captureToBlob(currentRenderer, latestCameraTexture, quality);
+		if (!blob) return null;
+		return {
+			blob,
+			width: bc.getWidth(),
+			height: bc.getHeight()
+		};
 	};
 	log.info(`Blit capture pipeline initialized (resolutionDivisor=${divisor})`);
 	imageCaptureManager = new ImageCaptureManager(renderer.domElement, callbacks, mergedConfig);
@@ -1020,6 +1183,68 @@ function getDepthSampleCount() {
 	return depthSampler?.getSampleCount() ?? 0;
 }
 /**
+* Set the per-frame camera RGBA callback (B2) — the generic CV frame feed (QR
+* detection today, object detection / OpenCV later). Call this BEFORE initAR to
+* enable in-session camera frame capture; `startCameraFrameCapture` then begins
+* delivering frames.
+*
+* The callback receives a **top-left-origin** RGBA image (no JPEG round-trip),
+* captured at the throttled detection cadence — feed it straight to a
+* `BarcodeDetector` / OpenCV front-end. Mirrors `setDepthCaptureCallback`.
+*
+* @param onFrame - Called with each throttled camera frame, or `null` to clear.
+*/
+function setCameraFrameCallback(onFrame) {
+	onCameraFrame = onFrame;
+}
+/**
+* Start camera frame capture during an AR session. Must call
+* setCameraFrameCallback before initAR (the source is created there). No-op if
+* the source was not initialized (callback not set before initAR).
+*
+* The source is the single cadence owner: drive your detection scheduler from
+* the delivered frames with its own `minIntervalMs: 0` (Option A).
+*
+* @param config - optional cadence / blit-resolution overrides.
+*/
+function startCameraFrameCapture(config) {
+	if (!cameraFrameSource) {
+		log.warn("Cannot start camera frame capture - frame source not initialized");
+		return;
+	}
+	if (typeof config?.captureSize === "number" && Number.isFinite(config.captureSize) && config.captureSize > 0) cameraFrameCaptureSize = Math.floor(config.captureSize);
+	if (config?.intervalMs !== void 0) cameraFrameSource.updateConfig({ intervalMs: config.intervalMs });
+	cameraFrameSource.start();
+	log.info(`Camera frame capture started (interval: ${cameraFrameSource.getConfig().intervalMs}ms, long edge ${cameraFrameCaptureSize}px, aspect-preserved)`);
+}
+/**
+* Stop camera frame capture. Safe to call when not running.
+*/
+function stopCameraFrameCapture() {
+	if (cameraFrameSource) {
+		const count = cameraFrameSource.getFrameCount();
+		cameraFrameSource.stop();
+		log.info(`Camera frame capture stopped (${count} frames captured)`);
+	}
+}
+/**
+* Get the number of camera frames captured since the last
+* `startCameraFrameCapture`.
+*/
+function getCameraFrameCount() {
+	return cameraFrameSource?.getFrameCount() ?? 0;
+}
+/**
+* The current longer-edge resolution (px) of the camera-frame blit — the
+* {@link DEFAULT_CAMERA_FRAME_CAPTURE_SIZE} default unless overridden via
+* `startCameraFrameCapture({ captureSize })`. Exposed for diagnostics and to
+* let tests assert the on-device-tuned default without reaching into module
+* state.
+*/
+function getCameraFrameCaptureSize() {
+	return cameraFrameCaptureSize;
+}
+/**
 * 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
@@ -1038,4 +1263,4 @@ function getLiveCss3dManager() {
 	return css3dManager;
 }
 //#endregion
-export { setTrackingLostCallback as A, setArWorldGroup as C, setImageCaptureCallback as D, setFrameCallback as E, startImageCapture as F, stopDepthCapture as I, stopImageCapture as L, setTrackingStore as M, shouldLogCameraAccessDiagnostic as N, setScene as O, startDepthCapture 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 };
+export { setFrameCallback as A, startImageCapture as B, nueQuaternionToWebXR$1 as C, setCamera as D, setArWorldGroup as E, setTrackingRecoveredCallback as F, stopDepthCapture as H, setTrackingStore as I, shouldLogCameraAccessDiagnostic as L, setScene as M, setTrackingCallbacks as N, setCameraFrameCallback as O, setTrackingLostCallback as P, startCameraFrameCapture as R, nuePositionToWebXR as S, setArPose as T, stopImageCapture as U, stopCameraFrameCapture as V, CameraFrameSource 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, startDepthCapture as z };

package/dist/{webxr-session-DtAG9srK.d.ts → webxr-session-COsOjJwn.d.ts}

@@ -1,10 +1,11 @@
-import { i as DepthSample, t as ARPose } from "./ar-types-Dan1MVTi.js";
-import { i as DepthSamplerConfig } from "./depth-sampler-Bhanfwla.js";
-import { t as ArCrashIsolationOptions } from "./recording-options-DJBXuMxV.js";
-import { i as ImageCaptureConfig, t as CapturedImage } from "./image-capture-DZ4HFRgS.js";
-import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-CdK8c-8P.js";
-import { t as Css3dRendererManager } from "./css3d-renderer-manager-ptu_t3B3.js";
-import { r as XRCameraLike } from "./xr-camera-texture-DBwCaKTd.js";
+import { i as DepthSample, t as ARPose } from "./ar-types-BckI1E-O.js";
+import { i as DepthSamplerConfig } from "./depth-sampler-DwfPYzS7.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-D93kksJU.js";
+import { a as ImageCaptureConfig, n as CapturedImage } from "./image-capture-C2Feywet.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-DJZ9qeGg.js";
+import { o as RgbaImage } from "./qr-frontend-DufZp2xS.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-m-ab19vp.js";
+import { r as XRCameraLike } from "./xr-camera-texture-BmrP7iNZ.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
 
@@ -68,6 +69,18 @@ declare function shouldLogCameraAccessDiagnostic(pose: XRViewerPose | null, alre
  * @internal
  */
 declare function resetWebXRState(): void;
+/**
+ * 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
+ * `?capture=` override) showed **1024** decodes a small / out-of-focus QR
+ * markedly better than the prior 512 with no perceptible cadence cost on the
+ * test phone; 2048 helped slightly more but risks low-end devices (4096 lagged),
+ * so 1024 is the safe default. Raise per-consumer via
+ * `startCameraFrameCapture({ captureSize })`.
+ *
+ * @see GpsPlusSlamJs_Docs/docs/2026-06-17-qr-size-accuracy-and-thin-demo-plan.md (WS-C)
+ */
+declare const DEFAULT_CAMERA_FRAME_CAPTURE_SIZE = 1024;
 /**
  * Extract the reset transform from an XRReferenceSpaceEvent-like object.
  *
@@ -371,6 +384,61 @@ declare function stopDepthCapture(): void;
  * Get the current depth sample count.
  */
 declare function getDepthSampleCount(): number;
+/** Optional tuning for {@link startCameraFrameCapture}. */
+interface CameraFrameCaptureConfig {
+  /** Detection cadence (ms between captures). Default 125 (~8 Hz). */
+  intervalMs?: number;
+  /**
+   * Longer-edge resolution (px) of the camera-frame blit. Default
+   * {@link DEFAULT_CAMERA_FRAME_CAPTURE_SIZE} (1024). The blit preserves the
+   * camera ASPECT with its longer edge at this value (e.g. 1024 → 1024×768 for a
+   * 4:3 camera), so the target reaches the detector undistorted. A QR needs ~3–5
+   * px per module; the on-device sweep settled on 1024 (512 made small QRs decode
+   * only at very close range). Applied before the first capture.
+   */
+  captureSize?: number;
+}
+/**
+ * Set the per-frame camera RGBA callback (B2) — the generic CV frame feed (QR
+ * detection today, object detection / OpenCV later). Call this BEFORE initAR to
+ * enable in-session camera frame capture; `startCameraFrameCapture` then begins
+ * delivering frames.
+ *
+ * The callback receives a **top-left-origin** RGBA image (no JPEG round-trip),
+ * captured at the throttled detection cadence — feed it straight to a
+ * `BarcodeDetector` / OpenCV front-end. Mirrors `setDepthCaptureCallback`.
+ *
+ * @param onFrame - Called with each throttled camera frame, or `null` to clear.
+ */
+declare function setCameraFrameCallback(onFrame: ((image: RgbaImage) => void) | null): void;
+/**
+ * Start camera frame capture during an AR session. Must call
+ * setCameraFrameCallback before initAR (the source is created there). No-op if
+ * the source was not initialized (callback not set before initAR).
+ *
+ * The source is the single cadence owner: drive your detection scheduler from
+ * the delivered frames with its own `minIntervalMs: 0` (Option A).
+ *
+ * @param config - optional cadence / blit-resolution overrides.
+ */
+declare function startCameraFrameCapture(config?: CameraFrameCaptureConfig): void;
+/**
+ * Stop camera frame capture. Safe to call when not running.
+ */
+declare function stopCameraFrameCapture(): void;
+/**
+ * Get the number of camera frames captured since the last
+ * `startCameraFrameCapture`.
+ */
+declare function getCameraFrameCount(): number;
+/**
+ * The current longer-edge resolution (px) of the camera-frame blit — the
+ * {@link DEFAULT_CAMERA_FRAME_CAPTURE_SIZE} default unless overridden via
+ * `startCameraFrameCapture({ captureSize })`. Exposed for diagnostics and to
+ * let tests assert the on-device-tuned default without reaching into module
+ * state.
+ */
+declare function getCameraFrameCaptureSize(): number;
 /**
  * Set a per-frame callback for custom updates.
  * The callback is invoked every XR frame after pose updates but before render.
@@ -386,4 +454,4 @@ declare function setFrameCallback(callback: (() => void) | null): void;
  */
 declare function getLiveCss3dManager(): Css3dRendererManager | null;
 //#endregion
-export { setScene as A, resetWebXRState as C, setDepthCaptureCallback as D, setCamera as E, shouldLogCameraAccessDiagnostic as F, startDepthCapture as I, startImageCapture as L, setTrackingLostCallback as M, setTrackingRecoveredCallback as N, setFrameCallback as O, setTrackingStore as P, stopDepthCapture as R, nueQuaternionToWebXR$1 as S, setArWorldGroup as T, getXrCameraFromPose as _, createSceneHierarchy as a, isXRCameraLike as b, extractResetTransformData as c, getCamera as d, getCurrentArPose as f, getScene as g, getLiveCss3dManager as h, buildSessionOptions as i, setTrackingCallbacks as j, setImageCaptureCallback as k, getArPose as l, getImageCaptureFrameCount as m, TrackingSubscribableStore as n, endARSession as o, getDepthSampleCount as p, applyAlignmentMatrix as r, extractPoseFromViewer as s, SessionFeatureOptions as t, getArWorldGroup as u, initAR as v, setArPose as w, nuePositionToWebXR as x, isWebXRSupported as y, stopImageCapture as z };
+export { setCamera as A, shouldLogCameraAccessDiagnostic as B, isWebXRSupported as C, resetWebXRState as D, nueQuaternionToWebXR$1 as E, setScene as F, stopDepthCapture as G, startDepthCapture as H, setTrackingCallbacks as I, stopImageCapture as K, setTrackingLostCallback as L, setDepthCaptureCallback as M, setFrameCallback as N, setArPose as O, setImageCaptureCallback as P, setTrackingRecoveredCallback as R, initAR as S, nuePositionToWebXR as T, startImageCapture as U, startCameraFrameCapture as V, stopCameraFrameCapture 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, SessionFeatureOptions as r, createSceneHierarchy as s, CameraFrameCaptureConfig as t, extractResetTransformData as u, getImageCaptureFrameCount as v, isXRCameraLike as w, getXrCameraFromPose as x, getLiveCss3dManager as y, setTrackingStore as z };

package/dist/zip-coverage-embed-tFohI2J4.d.ts

@@ -0,0 +1,41 @@
+//#region ../src/storage/zip-coverage-embed.d.ts
+/**
+ * Zip Coverage Embed — write a recording's H3 coverage into its `session.json`.
+ *
+ * The map-centric browser indexes legacy recordings (those predating the
+ * `h3Cells` field) by reading their full GPS path — slow, and repeated on every
+ * folder open. This primitive lets a one-time "upgrade" embed the derived
+ * coverage **inside the recording's own `session.json`**, so the recording
+ * indexes instantly on every future open in this app *and any other reader*
+ * (the portability the user asked for; O3 — in-zip rewrite).
+ *
+ * It is a pure transform `(zip, cells, resolution) -> zip`: it reads every entry
+ * and re-emits a new zip identical to the input except that `session.json` gains
+ * `h3Cells` + `h3Resolution`. It never mutates anything in place — the caller
+ * (the RecorderApp backfill) owns the safe write-then-verify-then-overwrite
+ * protocol around it.
+ *
+ * @see ./zip-coverage-embed.ts.md
+ * @see GpsPlusSlamJs_Docs/docs/2026-06-14-followup-progressive-map-browser-indexing-and-backfill.md (B3)
+ */
+/**
+ * Return a new zip blob identical to `zip` except its `session.json` gains
+ * `h3Cells` + `h3Resolution`.
+ *
+ * **Skips (returns the input blob unchanged, by reference) when:**
+ *   - the zip has no `session.json` (nothing to embed into);
+ *   - `session.json` is present but unparseable (never write over a broken one);
+ *   - `session.json` already carries `h3Cells` (idempotent — re-running the
+ *     upgrade is a no-op, and new recordings are skipped).
+ *
+ * On any unexpected read/write failure it also returns the input untouched —
+ * it never emits a partial zip. Callers can detect a skip via reference
+ * equality (`result === zip`).
+ *
+ * Built on `@zip.js/zip.js` (the same library as the exporter) in store mode, so
+ * every non-`session.json` entry is re-emitted with byte-identical uncompressed
+ * content.
+ */
+declare function embedCoverageInSessionJson(zip: Blob, h3Cells: string[], h3Resolution: number): Promise<Blob>;
+//#endregion
+export { embedCoverageInSessionJson as t };

package/dist/{zip-export-D_5HAvFz.d.ts → zip-export-DDWXInTR.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, ...
- * - frames/frame-000001.jpg, frames/frame-000002.jpg, ...
- * - refPoints/{h3}.json (only observations from this session, scenario layout only)
+ * - images/frame-000001.jpg, images/frame-000002.jpg, ... (legacy: frames/)
  *
- * 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.2.0",
+  "version": "1.4.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.0.7"
+    "gps-plus-slam-js": "^1.4.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 };