gps-plus-slam-app-framework 1.10.0 → 1.13.0

package/README.md

@@ -262,19 +262,19 @@ that guard's `APP_OVERLAY_CONTRACTS` list.
 
 WebXR session lifecycle, Three.js renderer setup, image/depth capture, replay scene management.
 
-| Export                                         | Description                                                                                                                                                                                                                                                             |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `initAR(container, isolation?, features?)`     | Start a WebXR AR session with Three.js rendering. `features.requestHitTest` opts the session into the WebXR `hit-test` feature                                                                                                                                          |
-| `endARSession()`                               | End the active XR session                                                                                                                                                                                                                                               |
-| `createEnableGpsArController()`                | Headless "Enable GPS AR" orchestration (support check + permission bundling + sensor watches + `initAR`) with observable state; the app renders its own button over it                                                                                                  |
-| `registerXrFrameUpdate(cb)`                    | Per-frame access to the live `XRFrame` + reference space + session (valid only synchronously inside the callback). Enables app-side hit-test / other WebXR features                                                                                                     |
-| `isFullySupported(s)` / `capabilityMessage(s)` | WebXR + geolocation capability gating + a user-facing message                                                                                                                                                                                                           |
-| `startImageCapture()` / `stopImageCapture()`   | Toggle camera frame capture                                                                                                                                                                                                                                             |
-| `ImageCaptureManager`                          | Configurable camera frame capture pipeline                                                                                                                                                                                                                              |
-| `DepthSampler`                                 | Depth buffer sampling with configurable grids                                                                                                                                                                                                                           |
-| `CameraBlitCapture`                            | GPU blit-based camera capture                                                                                                                                                                                                                                           |
-| `initReplayScene(container)`                   | Create a 3D replay scene with orbit/FPS controls                                                                                                                                                                                                                        |
-| `applyChromiumProjectionLayerWorkaround`       | Chromium camera-access tab-crash workaround. Always deletes projection-layer hooks (forces `XRWebGLLayer`; required on every affected build incl. Chrome 150) and additionally persists `baseLayer` only on the affected Chrome window (148.0.7778.12 up to 149.0.7821) |
+| Export                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initAR(container, isolation?, features?, callbacks?)` | Start a WebXR AR session with Three.js rendering. `features.requestHitTest` opts the session into the WebXR `hit-test` feature. `callbacks` (`ArSessionCallbacks`) carries ALL per-session host callbacks — `imageCapture`, `tracking` (store + callbacks together), `depth`, `cameraFrame`, `onFrame`, `onSessionEnd` — replacing the former pre-init setter exports; re-pass it with each session (cleared at session end). `rebindTrackingStore(store)` remains for the one mid-session need (swapping the tracking store per recording) |
+| `endARSession()`                                       | End the active XR session                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `createEnableGpsArController()`                        | Headless "Enable GPS AR" orchestration (support check + permission bundling + sensor watches + `initAR`) with observable state; the app renders its own button over it                                                                                                                                                                                                                                                                                                                                                                      |
+| `registerXrFrameUpdate(cb)`                            | Per-frame access to the live `XRFrame` + reference space + session (valid only synchronously inside the callback). Enables app-side hit-test / other WebXR features                                                                                                                                                                                                                                                                                                                                                                         |
+| `isFullySupported(s)` / `capabilityMessage(s)`         | WebXR + geolocation capability gating + a user-facing message                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `startImageCapture()` / `stopImageCapture()`           | Toggle camera frame capture                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `ImageCaptureManager`                                  | Configurable camera frame capture pipeline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `DepthSampler`                                         | Depth buffer sampling with configurable grids                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `CameraBlitCapture`                                    | GPU blit-based camera capture                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `initReplayScene(container)`                           | Create a 3D replay scene with orbit/FPS controls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `applyChromiumProjectionLayerWorkaround`               | Chromium camera-access tab-crash workaround. Always deletes projection-layer hooks (forces `XRWebGLLayer`; required on every affected build incl. Chrome 150) and additionally persists `baseLayer` only on the affected Chrome window (148.0.7778.12 up to 149.0.7821)                                                                                                                                                                                                                                                                     |
 
 ### `sensors/` — GPS & Permissions
 
@@ -291,19 +291,18 @@ WebXR session lifecycle, Three.js renderer setup, image/depth capture, replay sc
 
 ### `state/` — Store & Recording
 
-| Export                                              | Description                                                    |
-| --------------------------------------------------- | -------------------------------------------------------------- |
-| `createSlamAppStore(options)`                       | Composable store factory (see options table above).            |
-| `recordingReducer`                                  | Recording lifecycle slice (built into the factory).            |
-| `startSession()` / `endSession()`                   | Recording lifecycle actions.                                   |
-| `recordGpsEvent(payload)`                           | Record a paired AR+GPS observation.                            |
-| `createGpsPositionHandler(config)`                  | Factory that adapts `GeolocationPosition` to a store dispatch. |
-| `captureGpsAnchorSample(options)`                   | Sample a paired AR pose + GPS point for anchoring.             |
-| `loadRecordingOptions()` / `saveRecordingOptions()` | Persist user-controlled recording settings.                    |
-| `replayRecording(store, blob)`                      | Replay a ZIP recording into a store.                           |
-| `ReplayEngine`                                      | Lower-level timed action playback with pause/resume/speed.     |
-| `createPersistenceMiddleware(options)`              | Middleware factory used internally by `createSlamAppStore`.    |
-| `wireStoreSubscribers(store, deps)`                 | Bridge store state → visualization updates.                    |
+| Export                                 | Description                                                    |
+| -------------------------------------- | -------------------------------------------------------------- |
+| `createSlamAppStore(options)`          | Composable store factory (see options table above).            |
+| `recordingReducer`                     | Recording lifecycle slice (built into the factory).            |
+| `startSession()` / `endSession()`      | Recording lifecycle actions.                                   |
+| `recordGpsEvent(payload)`              | Record a paired AR+GPS observation.                            |
+| `createGpsPositionHandler(config)`     | Factory that adapts `GeolocationPosition` to a store dispatch. |
+| `captureGpsAnchorSample(options)`      | Sample a paired AR pose + GPS point for anchoring.             |
+| `replayRecording(store, blob)`         | Replay a ZIP recording into a store.                           |
+| `ReplayEngine`                         | Lower-level timed action playback with pause/resume/speed.     |
+| `createPersistenceMiddleware(options)` | Middleware factory used internally by `createSlamAppStore`.    |
+| `wireStoreSubscribers(store, deps)`    | Bridge store state → visualization updates.                    |
 
 ### `storage/` — OPFS, ZIP, File System
 
@@ -312,7 +311,7 @@ WebXR session lifecycle, Three.js renderer setup, image/depth capture, replay sc
 | `StorageBackend`                               | Abstract storage interface (implement your own).        |
 | `OpfsStorageBackend`                           | OPFS-based `StorageBackend`.                            |
 | `NullStorageBackend`                           | No-op backend for tests and replay.                     |
-| `initOpfsStorage()` / `initStorage(backend)`   | Initialize the file-system layer.                       |
+| `initOpfsStorage()`                            | Initialize the OPFS file-system layer.                  |
 | `createSession()` / `listSessions()`           | Session lifecycle on disk.                              |
 | `exportSessionAsZip(handle, { contributors })` | Export a recording session as a ZIP blob.               |
 | `ZipExportContributor`                         | Hook for adding your own ZIP subdirectories on export.  |
@@ -341,7 +340,6 @@ H3-based proximity matching for GPS-anchored points (renamed from `ref-points/`
 | Export                         | Description                                            |
 | ------------------------------ | ------------------------------------------------------ |
 | `LeafletMapOverlay`            | 2D Leaflet map integrated via CSS3D into a 3D scene.   |
-| `MapOverlay`                   | Tile-based 3D map overlay (no Leaflet dependency).     |
 | `GpsEventVisualizer`           | Three.js spheres for GPS event positions.              |
 | `createAlignmentLerper()`      | Smooth alignment matrix interpolation.                 |
 | `createCameraFollower()`       | Camera that tracks a moving target.                    |
@@ -392,6 +390,7 @@ pnpm run build     # build with tsdown
 ```
 src/
 ├── ar/             # WebXR session, capture, replay scene
+│   └── qr/         # QR detection, pose (planar PnP), size-from-depth, GPS vote
 ├── sensors/        # GPS, orientation, permissions
 ├── state/          # createSlamAppStore, recording, replay, persistence middleware
 ├── storage/        # OPFS, ZIP export/import, StorageBackend

package/dist/{absolute-orientation-C_IxDR_j.d.ts → absolute-orientation-0WIsqJnu.d.ts}

@@ -3,7 +3,7 @@
  * AbsoluteOrientationSensor capture (Generic Sensor API).
  *
  * Phase 1 of the AbsoluteOrientationSensor plan
- * (GpsPlusSlamJs_Docs/docs/2026-06-25-absolute-orientation-sensor-plan.md §5.1):
+ * (GpsPlusSlamJs_Docs/docs/2026-06-25-0543-absolute-orientation-sensor-plan.md §5.1):
  * passive instrumentation that fuses accelerometer + gyroscope + magnetometer
  * into an Earth-referenced (ENU) quaternion, captured per GPS event as an
  * independent north reference. No production behaviour change.

package/dist/{accuracy-circles-BE7tbvYV.d.ts → accuracy-circles-CFnKGfsD.d.ts}

@@ -16,7 +16,7 @@ import L from "leaflet";
  * @deprecated Stroke-only since 2026-06-28 (Finding 1) — accuracy circles no
  * longer render a fill, so this opacity is unused. Retained as an exported
  * constant only to preserve the published API surface; do not pass it to
- * `L.circle`. See `2026-06-28-map-rings-transparency-and-view-direction-user-feedback.md`.
+ * `L.circle`. See `2026-06-28-1822-map-rings-transparency-and-view-direction-user-feedback.md`.
  */
 declare const ACCURACY_CIRCLE_FILL_OPACITY = 0.12;
 declare const ACCURACY_CIRCLE_STROKE_OPACITY = 0.5;

package/dist/{app-selectors-CV7ggGoo.d.ts → app-selectors-QM0ZpNA4.d.ts}

@@ -1,4 +1,4 @@
-import { N as CombinedRootState } from "./create-slam-app-store-CH31erpP.js";
+import { N as CombinedRootState } from "./create-slam-app-store-HNe1PBtx.js";
 import * as _$gps_plus_slam_js0 from "gps-plus-slam-js";
 import { ArImageCapture, GpsPoint, LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";

package/dist/ar/ar-crash-isolation.d.ts

@@ -0,0 +1,2 @@
+import { n as DEFAULT_AR_CRASH_ISOLATION, r as validateArCrashIsolationOptions, t as ArCrashIsolationOptions } from "../ar-crash-isolation-BSFw_beO.js";
+export { ArCrashIsolationOptions, DEFAULT_AR_CRASH_ISOLATION, validateArCrashIsolationOptions };

package/dist/ar/ar-crash-isolation.js

@@ -0,0 +1,40 @@
+//#region ../src/ar/ar-crash-isolation.ts
+/** Default AR-crash-isolation flags (all features enabled). */
+const DEFAULT_AR_CRASH_ISOLATION = {
+	enableDomOverlay: true,
+	enableCameraAccess: true,
+	enableDepthSensingFeature: true,
+	enableCss3dRenderer: true,
+	enableCameraTextureAcquisition: true,
+	applyChromiumProjectionLayerWorkaround: true
+};
+/**
+* Boolean-or-default (quality-review C-1): persisted/external values are
+* untrusted, so anything that is not a real boolean falls back to the
+* default. Local copy of the recorder catalog's helper — the validator must
+* stay dependency-free so the framework owns the whole group.
+*/
+function boolOr(value, fallback) {
+	return typeof value === "boolean" ? value : fallback;
+}
+/**
+* Validate and normalize AR crash isolation flags.
+* Missing or invalid values fall back to defaults. The container itself is as
+* untrusted as its fields (persisted blobs may lack the key entirely or hold
+* `null`), so a nullish container yields the full defaults instead of
+* throwing.
+*/
+function validateArCrashIsolationOptions(rawOptions) {
+	const options = rawOptions ?? {};
+	const defaults = DEFAULT_AR_CRASH_ISOLATION;
+	return {
+		enableDomOverlay: boolOr(options.enableDomOverlay, defaults.enableDomOverlay),
+		enableCameraAccess: boolOr(options.enableCameraAccess, defaults.enableCameraAccess),
+		enableDepthSensingFeature: boolOr(options.enableDepthSensingFeature, defaults.enableDepthSensingFeature),
+		enableCss3dRenderer: boolOr(options.enableCss3dRenderer, defaults.enableCss3dRenderer),
+		enableCameraTextureAcquisition: boolOr(options.enableCameraTextureAcquisition, defaults.enableCameraTextureAcquisition),
+		applyChromiumProjectionLayerWorkaround: boolOr(options.applyChromiumProjectionLayerWorkaround, defaults.applyChromiumProjectionLayerWorkaround)
+	};
+}
+//#endregion
+export { DEFAULT_AR_CRASH_ISOLATION, validateArCrashIsolationOptions };

package/dist/ar/bresenham3d.d.ts

@@ -1,2 +1,2 @@
-import { n as MAX_TRACE_STEPS, r as bresenham3d, t as GridCell } from "../bresenham3d-D-t9i_b5.js";
+import { n as MAX_TRACE_STEPS, r as bresenham3d, t as GridCell } from "../bresenham3d-bt61R-Qa.js";
 export { GridCell, MAX_TRACE_STEPS, bresenham3d };

package/dist/ar/camera-blit-capture.d.ts

@@ -1,2 +1,2 @@
-import { a as computeCaptureSize, i as computeAspectFitSize, n as CameraBlitCaptureConfig, r as DEFAULT_BLIT_CONFIG, t as CameraBlitCapture } from "../camera-blit-capture-BlC-arRb.js";
+import { a as computeCaptureSize, i as computeAspectFitSize, n as CameraBlitCaptureConfig, r as DEFAULT_BLIT_CONFIG, t as CameraBlitCapture } from "../camera-blit-capture-CgNJ9grH.js";
 export { CameraBlitCapture, CameraBlitCaptureConfig, DEFAULT_BLIT_CONFIG, computeAspectFitSize, computeCaptureSize };

package/dist/ar/capability-checker.d.ts

@@ -1,2 +1,2 @@
-import { i as isFullySupported, n as CapabilitySupport, r as capabilityMessage, t as CapabilityMessageOptions } from "../capability-checker-DEo-ktWI.js";
+import { i as isFullySupported, n as CapabilitySupport, r as capabilityMessage, t as CapabilityMessageOptions } from "../capability-checker-DrWimJ_t.js";
 export { CapabilityMessageOptions, CapabilitySupport, capabilityMessage, isFullySupported };

package/dist/ar/capture-failure-tracker.d.ts

@@ -1,2 +1,2 @@
-import { a as createCaptureFailureTracker, i as DEFAULT_CAPTURE_TRACKER_CONFIG, n as CaptureFailureTracker, r as CaptureFailureTrackerConfig, t as CAPTURE_FAILURE_WARNING } from "../capture-failure-tracker-BAUKjtXU.js";
+import { a as createCaptureFailureTracker, i as DEFAULT_CAPTURE_TRACKER_CONFIG, n as CaptureFailureTracker, r as CaptureFailureTrackerConfig, t as CAPTURE_FAILURE_WARNING } from "../capture-failure-tracker-bUXJeMvQ.js";
 export { CAPTURE_FAILURE_WARNING, CaptureFailureTracker, CaptureFailureTrackerConfig, DEFAULT_CAPTURE_TRACKER_CONFIG, createCaptureFailureTracker };

package/dist/ar/capture-motion-gate.d.ts

@@ -0,0 +1,2 @@
+import { a as MotionWindow, i as MotionFilterConfig, n as DEFAULT_MOTION_FILTER, o as decideCapture, r as DEFAULT_MOTION_WINDOW_SIZE, t as CaptureDecisionInput } from "../capture-motion-gate-C60Qrilh.js";
+export { CaptureDecisionInput, DEFAULT_MOTION_FILTER, DEFAULT_MOTION_WINDOW_SIZE, MotionFilterConfig, MotionWindow, decideCapture };

package/dist/{capture-motion-gate-D1eyGC_o.js → ar/capture-motion-gate.js}

@@ -1,3 +1,26 @@
+//#region ../src/ar/capture-motion-gate.ts
+/**
+* Capture motion gate — the policy that decides whether a *due* capture should
+* fire on the current frame or be deferred until the device settles.
+*
+* Two cohesive pieces, both pure/deterministic and unit-testable in isolation
+* from `ImageCaptureManager`:
+*  - {@link decideCapture} — the stateless capture-vs-defer decision over the
+*    windowed motion maxima, the thresholds, and the time since the capture
+*    became due (the never-calm safety fallback).
+*  - {@link MotionWindow} — a tiny fixed-size ring of recent per-frame
+*    velocities with glitch rejection, so the decision judges "max over the
+*    last N frames" rather than one lucky-calm sample.
+*
+* The window size and glitch ceilings are INTERNAL constants, deliberately not
+* user-facing config: the user-facing surface is only enabled / maxAngular /
+* maxLinear / maxWaitMs (plan §5.1). Keeping the stateful policy here (not in a
+* speculative framework-wide service) matches the plan's §4.1 scope note.
+*
+* @see GpsPlusSlamJs_Docs/docs/2026-06-23-2105-blurry-frame-motion-gating-plan.md §4.2-4.4
+*/
+/** Default number of recent frames the gate judges motion over (~50 ms @ 60fps). */
+const DEFAULT_MOTION_WINDOW_SIZE = 3;
 /**
 * Angular velocity (rad/s) above which a sample is treated as a tracking glitch
 * (e.g. relocalization teleport), not real motion. A genuine hand/device turn
@@ -27,7 +50,7 @@ const LINEAR_GLITCH_CEILING_M_S = 20;
 * — demoting the (weak-at-scanning-distance) linear signal to a gross-motion
 * safety net and letting the well-behaved angular gate be the primary blur
 * selector. See
-* `GpsPlusSlamJs_Docs/docs/2026-07-02-image-capture-rate-motion-gate-finding.md`.
+* `GpsPlusSlamJs_Docs/docs/2026-07-02-0117-image-capture-rate-motion-gate-finding.md`.
 *
 * `maxAngularVelocity` remains a PLACEHOLDER pending on-device field tuning
 * (plan §7). `maxWaitMs` of 4000 ms is 2× the default 2000 ms image interval.
@@ -103,4 +126,4 @@ var MotionWindow = class {
 	}
 };
 //#endregion
-export { MotionWindow as n, decideCapture as r, DEFAULT_MOTION_FILTER as t };
+export { DEFAULT_MOTION_FILTER, DEFAULT_MOTION_WINDOW_SIZE, MotionWindow, decideCapture };

package/dist/ar/chromium-camera-access-workaround.d.ts

@@ -1,2 +1,2 @@
-import { a as applyChromiumProjectionLayerWorkaround, i as ChromiumProjectionLayerWorkaroundResult, n as BASELAYER_WINDOW_MIN, o as needsBaseLayerPersistence, r as ChromeVersion, s as parseChromeVersion, t as BASELAYER_WINDOW_MAX } from "../chromium-camera-access-workaround-DCd8SP2N.js";
+import { a as applyChromiumProjectionLayerWorkaround, i as ChromiumProjectionLayerWorkaroundResult, n as BASELAYER_WINDOW_MIN, o as needsBaseLayerPersistence, r as ChromeVersion, s as parseChromeVersion, t as BASELAYER_WINDOW_MAX } from "../chromium-camera-access-workaround-BRs6gkI4.js";
 export { BASELAYER_WINDOW_MAX, BASELAYER_WINDOW_MIN, ChromeVersion, ChromiumProjectionLayerWorkaroundResult, applyChromiumProjectionLayerWorkaround, needsBaseLayerPersistence, parseChromeVersion };

package/dist/ar/chromium-camera-access-workaround.js

@@ -11,7 +11,7 @@ import { createLogger } from "../utils/logger.js";
 * added — i.e. it is not specific to this app's session setup. See:
 *
 *   - GpsPlusSlamJs_Docs/docs/2026-04-22-camera-access-reproducer-plan.md
-*   - GpsPlusSlamJs_Docs/docs/2026-06-04-camera-access-crash-regression-chrome-148.md
+*   - GpsPlusSlamJs_Docs/docs/2026-06-04-0458-camera-access-crash-regression-chrome-148.md
 *   - https://github.com/mrdoob/three.js/issues/33404
 *   - https://issues.chromium.org/issues/507508099 (root-cause, marked Fixed)
 *

package/dist/ar/depth-grid-lookup.d.ts

@@ -1,2 +1,2 @@
-import { n as createDepthGridLookup, t as DepthGridLookup } from "../depth-grid-lookup-DY6zYTLx.js";
+import { n as createDepthGridLookup, t as DepthGridLookup } from "../depth-grid-lookup-PcJTdRLL.js";
 export { DepthGridLookup, createDepthGridLookup };

package/dist/ar/depth-occluder.d.ts

@@ -1,4 +1,4 @@
-import { t as DepthInfo } from "../depth-sampler-txG8evgQ.js";
+import { r as DepthInfo } from "../depth-sampler-BcvuxgCS.js";
 import * as THREE from "three";
 
 //#region ../src/ar/depth-occluder.d.ts

package/dist/ar/depth-occluder.js

@@ -10,7 +10,7 @@ import * as THREE from "three";
 * occludes per-pixel against the surface currently in view (sharp, registration-
 * free, no memory). They **compose** — both depth-only under `arWorldGroup`, the
 * live occluder wins where this frame has depth, the mesh fills out-of-view / depth
-* holes (2026-06-14-webxr-depth-occlusion-plan.md §5).
+* holes (2026-06-14-0009-webxr-depth-occlusion-plan.md §5).
 *
 * **Two layers, two confidence levels:**
 *  - The **pure occlusion math** (this file's exported functions) is the CI-tested

package/dist/ar/depth-sampler.d.ts

@@ -1,3 +1,3 @@
-import { i as DepthSample } from "../ar-types-CBafnxhE.js";
-import { a as wrapXRDepthInfo, i as DepthSamplerConfig, n as DepthSampler, r as DepthSamplerCallbacks, t as DepthInfo } from "../depth-sampler-txG8evgQ.js";
-export { DepthInfo, DepthSample, DepthSampler, DepthSamplerCallbacks, DepthSamplerConfig, wrapXRDepthInfo };
+import { i as DepthSample } from "../ar-types-BprL3nKv.js";
+import { a as DepthSamplerCallbacks, i as DepthSampler, n as DEFAULT_RECONSTRUCTION_DEPTH_INTERVAL_MS, o as DepthSamplerConfig, r as DepthInfo, s as wrapXRDepthInfo, t as DEFAULT_RECONSTRUCTION_DEPTH_GRID_SIZE } from "../depth-sampler-BcvuxgCS.js";
+export { DEFAULT_RECONSTRUCTION_DEPTH_GRID_SIZE, DEFAULT_RECONSTRUCTION_DEPTH_INTERVAL_MS, DepthInfo, DepthSample, DepthSampler, DepthSamplerCallbacks, DepthSamplerConfig, wrapXRDepthInfo };

package/dist/ar/depth-sampler.js

@@ -42,6 +42,33 @@ function wrapXRDepthInfo(raw, projectionMatrix) {
 	if (uvTransform) wrapped.normDepthBufferFromNormView = uvTransform;
 	return wrapped;
 }
+/**
+* Recommended depth-sampling cadence for apps that RECONSTRUCT-and-render an
+* occupancy mesh (the Recorder, the PhysicsDemo) — the depth-side counterpart
+* of `DEFAULT_OCCUPANCY_CELL_SIZE_M`/`DEFAULT_OCCUPANCY_MIN_OBSERVATIONS`
+* (occupancy-grid.ts): one framework-level source of truth so both apps build
+* the mesh at the same speed (2026-07-16 field feedback: the demo relied on
+* the conservative fallback below — 16×16 @ 1 Hz, 8× fewer points/s than the
+* recorder — and reconstructed visibly slower).
+*
+* Tuning (2026-07-16 EVENING, maintainer's on-device framerate/mesh trade-off
+* passes — supersedes the same-day sweep-derived 500 ms × 64): 200 ms × 24×24.
+* The ground-truth density/cadence sweep
+* (GpsPlusSlamJs_Investigation test-results/synthetic-density-cadence-sweep.txt)
+* showed density is the more point-efficient mesh-speed lever, but its
+* flagged open question — on-device frame-time cost — resolved against LARGE
+* per-sample batches: 64² @ 2 Hz (8192 points/s) visibly hurt the framerate,
+* while many SMALL samples (24² @ 5 Hz, ~2880 points/s) keep the per-frame
+* work chunk tiny and rendering smooth at good mesh build-up. If devices get
+* faster, the sweep says gridSize (not the interval) is the knob to raise
+* first.
+*
+* Deliberately OPT-IN named constants, NOT a change to the fallback below:
+* bumping the fallback would silently re-tune consumers that are not
+* reconstruction apps (MinimalExample / AnchorStarter).
+*/
+const DEFAULT_RECONSTRUCTION_DEPTH_INTERVAL_MS = 200;
+const DEFAULT_RECONSTRUCTION_DEPTH_GRID_SIZE = 24;
 const DEFAULT_CONFIG = {
 	intervalMs: 1e3,
 	gridSize: 16,
@@ -228,4 +255,4 @@ function isFinitePositive(value) {
 	return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
 //#endregion
-export { DepthSampler, wrapXRDepthInfo };
+export { DEFAULT_RECONSTRUCTION_DEPTH_GRID_SIZE, DEFAULT_RECONSTRUCTION_DEPTH_INTERVAL_MS, DepthSampler, wrapXRDepthInfo };

package/dist/ar/depth-unprojection.d.ts

@@ -1,2 +1,2 @@
-import { n as createDepthUnprojector, r as unprojectDepthPoint, t as DepthUnprojector } from "../depth-unprojection-JKkeqJrV.js";
+import { n as createDepthUnprojector, r as unprojectDepthPoint, t as DepthUnprojector } from "../depth-unprojection-DbGipFkA.js";
 export { DepthUnprojector, createDepthUnprojector, unprojectDepthPoint };

package/dist/ar/enable-gps-ar.d.ts

@@ -1,2 +1,2 @@
-import { a as EnableGpsArState, i as EnableGpsArResult, n as EnableGpsArController, o as EnableGpsArStatus, r as EnableGpsArDeps, s as createEnableGpsArController, t as EnableGpsArConfig } from "../enable-gps-ar-BbNWyqp5.js";
+import { a as EnableGpsArState, i as EnableGpsArResult, n as EnableGpsArController, o as EnableGpsArStatus, r as EnableGpsArDeps, s as createEnableGpsArController, t as EnableGpsArConfig } from "../enable-gps-ar-xjz3jNqm.js";
 export { EnableGpsArConfig, EnableGpsArController, EnableGpsArDeps, EnableGpsArResult, EnableGpsArState, EnableGpsArStatus, createEnableGpsArController };

package/dist/ar/enable-gps-ar.js

@@ -1,5 +1,5 @@
 import { createLogger } from "../utils/logger.js";
-import { C as initAR, c as endARSession, w as isWebXRSupported } from "../webxr-session-DWKUsCN9.js";
+import { _ as initAR, a as endARSession, v as isWebXRSupported } from "../webxr-session-BBlgzrqY.js";
 import { requestGeolocationPermission, requestOrientationPermission, requestWebXRWithDepthPermission } from "../sensors/permission-checker.js";
 import { startGpsWatch, startOrientationWatch, stopGpsWatch, stopOrientationWatch } from "../sensors/gps.js";
 //#region ../src/ar/enable-gps-ar.ts
@@ -74,11 +74,22 @@ function createEnableGpsArController(deps = {}) {
 			error: "AR is already starting, running or stopping."
 		};
 		setState({ status: "starting" });
+		const appCallbacks = config.callbacks;
+		const callbacks = {
+			...appCallbacks,
+			onSessionEnd: (info) => {
+				if (state.status === "running") {
+					stopWatches();
+					setState({ status: "ready" });
+				}
+				appCallbacks?.onSessionEnd?.(info);
+			}
+		};
 		let sessionStarted = false;
 		try {
 			const permissionError = await requestPermissions(config);
 			if (permissionError !== null) return fail(permissionError);
-			await resolved.initAR(config.container, config.isolationOptions, { requestHitTest: config.requestHitTest });
+			await resolved.initAR(config.container, config.isolationOptions, { requestHitTest: config.requestHitTest }, callbacks);
 			sessionStarted = true;
 			if (config.onGpsPosition) {
 				resolved.startGpsWatch(config.onGpsPosition);
@@ -127,9 +138,8 @@ function createEnableGpsArController(deps = {}) {
 			error
 		};
 	}
-	async function disable() {
-		if (state.status !== "running") return;
-		setState({ status: "stopping" });
+	/** Stop whichever sensor watches this controller started (idempotent). */
+	function stopWatches() {
 		if (gpsWatchActive) {
 			resolved.stopGpsWatch();
 			gpsWatchActive = false;
@@ -138,6 +148,11 @@ function createEnableGpsArController(deps = {}) {
 			resolved.stopOrientationWatch();
 			orientationWatchActive = false;
 		}
+	}
+	async function disable() {
+		if (state.status !== "running") return;
+		setState({ status: "stopping" });
+		stopWatches();
 		try {
 			await resolved.endARSession();
 		} catch (err) {

package/dist/ar/frame-loop.d.ts

@@ -1,2 +1,2 @@
-import { i as runFrameUpdates, n as clearFrameUpdates, r as registerFrameUpdate, t as FrameUpdate } from "../frame-loop-7HigCj7m.js";
+import { i as runFrameUpdates, n as clearFrameUpdates, r as registerFrameUpdate, t as FrameUpdate } from "../frame-loop-CUEIdlhS.js";
 export { FrameUpdate, clearFrameUpdates, registerFrameUpdate, runFrameUpdates };

package/dist/ar/hit-test-reticle-driver.d.ts

@@ -0,0 +1,2 @@
+import { n as HitTestReticleHandle, r as startHitTestReticle, t as HitTestReticleArgs } from "../hit-test-reticle-driver-CfKiDgsa.js";
+export { HitTestReticleArgs, HitTestReticleHandle, startHitTestReticle };

package/dist/ar/hit-test-reticle-driver.js

@@ -0,0 +1,122 @@
+import { registerXrFrameUpdate } from "./xr-frame-loop.js";
+import { createReticleMesh, updateReticle } from "../visualization/hit-test-reticle.js";
+import { Vector3 } from "three";
+//#region ../src/ar/hit-test-reticle-driver.ts
+/**
+* Hit-test reticle driver — the per-frame WebXR plumbing that drives the
+* screen-centre hit-test reticle whose pure view-model lives in
+* `visualization/hit-test-reticle.ts` (`createReticleMesh` / `updateReticle`).
+*
+* Promoted from the consumer apps (2026-07-18): MinimalExample,
+* WayfindingHudDemo and AnchorStarter each hand-rolled this loop, and the
+* copies had already drifted in their session-end handling. AnchorStarter's
+* copy (the most careful one) is the reference implementation.
+*
+* Responsibilities, all subtle and previously copy-pasted per app:
+* - Request the hit-test source once per session (`requestReferenceSpace
+*   ('viewer')` → `requestHitTestSource`), retrying on transient failure.
+* - Guard the "request still in flight while we shut down" races: a source
+*   that resolves after `dispose()` — or after the session that issued the
+*   request has ended — is cancelled, never adopted.
+* - Register the session `'end'` (and optional `'select'`) listeners exactly
+*   once per session, outside the request-retry path.
+* - Reset per-session state on `'end'` so a fresh session re-requests its own
+*   source with its own listeners.
+*
+* Lifecycle: the handle is torn down only by `dispose()`. In the framework's
+* standard flow `resetWebXRState()` clears the XR frame registry at every
+* session end, so a handle is typically created once per AR session entry and
+* disposed from the app's session-teardown path; the per-session reset logic
+* additionally keeps the handle correct when frames are delivered outside that
+* flow (tests, custom loops).
+*/
+/**
+* Request a screen-centre hit-test source from the live session. Returns
+* `null` when the runtime does not expose `requestHitTestSource` (older WebXR
+* builds); the caller keeps the reticle hidden in that case.
+*/
+async function requestHitTestSource(session) {
+	const viewerSpace = await session.requestReferenceSpace("viewer");
+	return await session.requestHitTestSource?.({ space: viewerSpace }) ?? null;
+}
+/**
+* Cancel a hit-test source, tolerating a dead session. `cancel()` can throw
+* once the source's session has ended (e.g. the app's teardown path calls
+* `dispose()` before this driver's own `'end'` listener has run) — and a
+* dead session has already stopped the hit-test, so there is nothing left to
+* clean up.
+*/
+function cancelSource(source) {
+	try {
+		source?.cancel();
+	} catch {}
+}
+/**
+* Install the hit-test reticle under `arWorldGroup` and start driving it from
+* the XR frame loop. Returns a handle the app reads at placement time (or
+* ignores entirely when it placed via `onSelect`).
+*/
+function startHitTestReticle(args) {
+	const reticle = createReticleMesh();
+	args.arWorldGroup.add(reticle);
+	let hitTestSource = null;
+	let hitTestSourceRequested = false;
+	let disposed = false;
+	let removeSessionListeners = null;
+	let sessionGeneration = 0;
+	const handleSelect = () => {
+		args.onSelect?.(reticle.visible ? reticle.getWorldPosition(new Vector3()) : null);
+	};
+	const handleSessionEnd = () => {
+		sessionGeneration += 1;
+		hitTestSource = null;
+		hitTestSourceRequested = false;
+		removeSessionListeners = null;
+	};
+	const unregister = registerXrFrameUpdate(({ frame, referenceSpace, session }) => {
+		if (!removeSessionListeners) {
+			session.addEventListener("end", handleSessionEnd);
+			if (args.onSelect) session.addEventListener("select", handleSelect);
+			removeSessionListeners = () => {
+				session.removeEventListener("end", handleSessionEnd);
+				if (args.onSelect) session.removeEventListener("select", handleSelect);
+			};
+		}
+		if (!hitTestSourceRequested) {
+			hitTestSourceRequested = true;
+			const requestGeneration = sessionGeneration;
+			requestHitTestSource(session).then((source) => {
+				if (disposed || requestGeneration !== sessionGeneration) {
+					cancelSource(source);
+					return;
+				}
+				hitTestSource = source;
+			}).catch(() => {
+				if (requestGeneration === sessionGeneration) hitTestSourceRequested = false;
+			});
+		}
+		if (!hitTestSource) {
+			updateReticle(reticle, null);
+			return;
+		}
+		const [hit] = frame.getHitTestResults(hitTestSource);
+		const pose = hit?.getPose(referenceSpace);
+		updateReticle(reticle, pose ? pose.transform.matrix : null);
+	});
+	return {
+		isVisible: () => reticle.visible,
+		getWorldPosition: (out) => reticle.getWorldPosition(out),
+		dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			unregister();
+			removeSessionListeners?.();
+			removeSessionListeners = null;
+			cancelSource(hitTestSource);
+			hitTestSource = null;
+			args.arWorldGroup.remove(reticle);
+		}
+	};
+}
+//#endregion
+export { startHitTestReticle };

package/dist/ar/image-capture.d.ts

@@ -1,2 +1,2 @@
-import { a as ImageCaptureCallbacks, c as MIN_VALID_IMAGE_BYTES, i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, r as DEFAULT_CAPTURE_CONFIG, s as ImageCaptureManager, t as CapturedFrame } from "../image-capture-Cr_rljeV.js";
+import { a as ImageCaptureCallbacks, c as MIN_VALID_IMAGE_BYTES, i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, r as DEFAULT_CAPTURE_CONFIG, s as ImageCaptureManager, t as CapturedFrame } from "../image-capture-BXmx1YvD.js";
 export { CapturedFrame, CapturedImage, DEFAULT_CAPTURE_CONFIG, FrameQualityVerdict, ImageCaptureCallbacks, ImageCaptureConfig, ImageCaptureManager, MIN_VALID_IMAGE_BYTES };

package/dist/ar/image-capture.js

@@ -1,2 +1,2 @@
-import { n as ImageCaptureManager, r as MIN_VALID_IMAGE_BYTES, t as DEFAULT_CAPTURE_CONFIG } from "../image-capture-BUqqsOi3.js";
+import { n as ImageCaptureManager, r as MIN_VALID_IMAGE_BYTES, t as DEFAULT_CAPTURE_CONFIG } from "../image-capture-Dn8uLIP2.js";
 export { DEFAULT_CAPTURE_CONFIG, ImageCaptureManager, MIN_VALID_IMAGE_BYTES };

package/dist/ar/image-quality.d.ts

@@ -1,2 +1,2 @@
-import { a as QualityFilterConfig, c as meanLuminance, i as ImageQualityGate, l as rgbaToGrayscale, n as DEFAULT_SHARPNESS_HISTORY_SIZE, o as QualityRejectReason, r as DEFAULT_SHARPNESS_MIN_SAMPLES, s as QualityVerdict, t as DEFAULT_QUALITY_FILTER, u as sharpnessScore } from "../image-quality-BjBLoTec.js";
-export { DEFAULT_QUALITY_FILTER, DEFAULT_SHARPNESS_HISTORY_SIZE, DEFAULT_SHARPNESS_MIN_SAMPLES, ImageQualityGate, QualityFilterConfig, QualityRejectReason, QualityVerdict, meanLuminance, rgbaToGrayscale, sharpnessScore };
+import { a as DEFAULT_SHARPNESS_MIN_SAMPLES, c as QualityRejectReason, d as highFrequencyEnergyRatio, f as meanLuminance, i as DEFAULT_SHARPNESS_HISTORY_SIZE, l as QualityVerdict, m as sharpnessScore, n as BlurMetricId, o as ImageQualityGate, p as rgbaToGrayscale, r as DEFAULT_QUALITY_FILTER, s as QualityFilterConfig, t as BLUR_METRIC_IDS, u as blurMetricScorer } from "../image-quality-G7_qT4aj.js";
+export { BLUR_METRIC_IDS, BlurMetricId, DEFAULT_QUALITY_FILTER, DEFAULT_SHARPNESS_HISTORY_SIZE, DEFAULT_SHARPNESS_MIN_SAMPLES, ImageQualityGate, QualityFilterConfig, QualityRejectReason, QualityVerdict, blurMetricScorer, highFrequencyEnergyRatio, meanLuminance, rgbaToGrayscale, sharpnessScore };