gps-plus-slam-app-framework 1.0.6 → 1.1.0

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

@@ -0,0 +1,137 @@
+//#region ../src/ar/chromium-camera-access-workaround.d.ts
+/**
+ * Chromium WebXR camera-access tab-crash workaround.
+ *
+ * Background:
+ * Requesting `camera-access` as an optional WebXR feature on Android Chrome
+ * 147+ causes a fatal renderer-process crash (`CrRendererMain`) 1–2 seconds
+ * after entering AR. The crash reproduces in the upstream three.js
+ * `webxr_ar_hittest.html` example with `optionalFeatures: ['camera-access']`
+ * 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
+ *   - https://github.com/mrdoob/three.js/issues/33404
+ *   - https://issues.chromium.org/issues/507508099 (root-cause, marked Fixed)
+ *
+ * There is NOT a single crash here — the Chromium tracker notes the crash on
+ * Chrome 147 is different from the crash on 148+, and the simple workaround
+ * below only helped on a subset of versions. The empirically-verified
+ * (on-device) timeline is:
+ *
+ *   - 147 : deleting `createProjectionLayer` / `layers` forces three.js onto
+ *       `XRWebGLLayer` and sidesteps the crash (deletes-only is sufficient).
+ *   - 148.0.7778.12 .. 149.0.7821 : the delete-only trick is NOT sufficient on
+ *       its own. An ADDITIONAL patch is needed: persist the `baseLayer`
+ *       reference across `XRSession.prototype.updateRenderState` so three.js's
+ *       later `depthNear`/`depthFar` update does not drop the active
+ *       `glBaseLayer`. (Confirmed on-device on `148.0.7778.215`: BOTH the
+ *       deletes and the baseLayer patch are required for the page not to
+ *       crash. Earlier 148 builds (`< .7778.12`) are below the window per the
+ *       tracker, which reported delete-only worked there.)
+ *   - > 149.0.7821 (incl. Chrome 150) : the delete-only path is STILL required
+ *       (confirmed on-device: Chrome 150 only stops crashing when the deletes
+ *       are applied), but the extra baseLayer-persistence patch is NOT needed.
+ *       The earlier assumption that Chromium fully fixed this on patched
+ *       builds did not hold on real devices, so we no longer skip the
+ *       workaround on "patched" Chrome.
+ *
+ * Resulting policy (see {@link applyChromiumProjectionLayerWorkaround}):
+ *   - ALWAYS apply the deletes (every Chrome build, and unknown/non-Chromium
+ *     environments — restoring the original always-on behavior).
+ *   - Apply the baseLayer-persistence patch ONLY when a detected Chrome build
+ *     falls inside the affected window
+ *     [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}].
+ *
+ * Caveats:
+ * - This is a Chromium-specific hack and the upstream comment explicitly
+ *   warns it "might break webxr on other devices" — keep it opt-in.
+ * - Must run BEFORE any WebXR session setup. Three.js reads these prototype
+ *   members lazily when the first session starts, so calling this at app
+ *   bootstrap (before `initAR()`) is sufficient.
+ * - Idempotent: safe to call repeatedly. Safe on environments where the
+ *   prototypes do not exist (e.g. desktop browsers, jsdom).
+ */
+/**
+ * Parsed Chrome version as `[major, minor, build, patch]`.
+ */
+type ChromeVersion = [number, number, number, number];
+/**
+ * Inclusive lower bound of the Chrome window that additionally needs the
+ * `baseLayer`-persistence patch (on top of the deletes).
+ *
+ * Set to `148.0.7778.12`, the issue tracker's figure for when the delete-only
+ * trick stopped being sufficient. On-device confirmation: `148.0.7778.215`
+ * (well inside this window) crashes with deletes-only and needs BOTH patches.
+ * Earlier 148 builds (`< .7778.12`) and all of Chrome 147 stay below this
+ * bound (deletes-only) per the documented timeline — we have no on-device
+ * evidence that they need the baseLayer patch, so we do not apply it there.
+ */
+declare const BASELAYER_WINDOW_MIN: ChromeVersion;
+/**
+ * Inclusive upper bound of the Chrome window that additionally needs the
+ * `baseLayer`-persistence patch. The crash is fixed after `149.0.7819.0` and
+ * the camera image is correctly populated after `149.0.7821.0`; above this
+ * build the extra patch is no longer required (the deletes still are — see
+ * the module header and the on-device matrix for Chrome 150).
+ *
+ * @see https://github.com/mrdoob/three.js/issues/33404
+ */
+declare const BASELAYER_WINDOW_MAX: ChromeVersion;
+/**
+ * Result of {@link applyChromiumProjectionLayerWorkaround}.
+ * Useful for logging and tests.
+ */
+interface ChromiumProjectionLayerWorkaroundResult {
+  /** True if `XRWebGLBinding.prototype.createProjectionLayer` was deleted on this call. */
+  deletedCreateProjectionLayer: boolean;
+  /** True if `XRRenderState.prototype.layers` was deleted on this call. */
+  deletedRenderStateLayers: boolean;
+  /** True if `XRSession.prototype.updateRenderState` was wrapped on this call. */
+  patchedUpdateRenderState: boolean;
+  /** The detected Chrome version (`"major.minor.build.patch"`), or null. */
+  detectedChromeVersion: string | null;
+}
+/**
+ * Parse a Chrome/Chromium version from a user-agent string.
+ *
+ * Matches the `Chrome/<major>.<minor>.<build>.<patch>` token (and the iOS
+ * `CriOS/...` variant). Returns null for non-Chromium user agents.
+ */
+declare function parseChromeVersion(userAgent: string): ChromeVersion | null;
+/**
+ * True when the detected Chrome build falls inside the affected window
+ * [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}] (inclusive)
+ * and therefore additionally needs the `baseLayer`-persistence patch. Outside
+ * the window (including non-Chromium user agents) returns false — only the
+ * deletes are needed there.
+ */
+declare function needsBaseLayerPersistence(userAgent: string): boolean;
+/**
+ * Apply the Chromium camera-access tab-crash workaround.
+ *
+ * Policy (derived from on-device testing — see the module header):
+ *
+ *  - ALWAYS removes `XRWebGLBinding.prototype.createProjectionLayer`
+ *    (three.js r184) and `XRRenderState.prototype.layers` (three.js r158) so
+ *    three.js falls back to `XRWebGLLayer`. This is required on every affected
+ *    Chrome build observed so far, including Chrome 150, and is also applied
+ *    on unknown/non-Chromium environments (restoring the original always-on
+ *    behavior).
+ *  - ADDITIONALLY persists the `baseLayer` across
+ *    `XRSession.prototype.updateRenderState`, but ONLY when a detected Chrome
+ *    build falls inside the affected window
+ *    [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}]. Outside
+ *    that window the extra patch is unnecessary (and is skipped on unknown
+ *    environments to avoid touching projection-layer devices like Quest).
+ *
+ * Call once during bootstrap, before any `requestSession()` call.
+ *
+ * @param options.userAgent override the detected user agent (for testing).
+ * @returns which prototype members were actually changed on this call.
+ */
+declare function applyChromiumProjectionLayerWorkaround(options?: {
+  userAgent?: string;
+}): ChromiumProjectionLayerWorkaroundResult;
+//#endregion
+export { applyChromiumProjectionLayerWorkaround as a, ChromiumProjectionLayerWorkaroundResult as i, BASELAYER_WINDOW_MIN as n, needsBaseLayerPersistence as o, ChromeVersion as r, parseChromeVersion as s, BASELAYER_WINDOW_MAX as t };

package/dist/core/index.d.ts

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

package/dist/core/index.js

@@ -1,2 +1,2 @@
-import { calcGpsCoords, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE } from "gps-plus-slam-js";
-export { calcGpsCoords, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };
+import { calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE } from "gps-plus-slam-js";
+export { calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };

package/dist/create-slam-app-store-B76AGaI0.d.ts

@@ -0,0 +1,371 @@
+import { t as ARPose } from "./ar-types-isPsQptb.js";
+import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-CDREeoZ_.js";
+import { t as RecordingState } from "./recording-slice-Cb888P6d.js";
+import { n as SessionMetadata } from "./opfs-storage-LsLY6VZV.js";
+import { n as StorageBackend } from "./storage-backend-yDSKafAQ.js";
+import { GpsPoint, LatLong, Matrix4, RootState, Vector3 } from "gps-plus-slam-js";
+import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
+import { Middleware, Reducer, ReducersMapObject, configureStore } from "@reduxjs/toolkit";
+
+//#region ../src/state/combined-root-state.d.ts
+type CombinedRootState = SlamAppCombinedState;
+//#endregion
+//#region ../src/state/tracking-quality.d.ts
+type TrackingQualityState = 'warming-up' | 'ar-lost' | 'degraded' | 'ok';
+interface TrackingQualityReport {
+  state: TrackingQualityState;
+  /** 0..1, monotonically combined from {@link subScores}. */
+  confidence: number;
+  subScores: {
+    convergence: number;
+    residualConsensus: number; /** `null` when the device cannot supply an absolute compass heading. */
+    compassAgreement: number | null;
+    gpsAccuracy: number;
+    coverage: number;
+  };
+  diagnostics: {
+    /**
+     * §4.1 (Finding 6): **sum of |Δrotation|** across the last
+     * `matrixHistorySize - 1` consecutive snapshot pairs in the ring
+     * buffer, in degrees. Replaced the per-pair `recentMaxRotationDeltaDeg`
+     * on 2026-05-23 — see
+     * `GpsPlusSlamJs_Docs/docs/2026-05-23-tracking-quality-hud-user-feedback.md`
+     * (Finding 6). Surfaced in the recorder HUD as `ΣΔrot:`.
+     */
+    recentSumRotationDeltaDeg: number; /** §4.1 (Finding 6): sum of |Δtranslation| across the same window, in metres. Surfaced as `ΣΔpos:`. */
+    recentSumTranslationDeltaM: number;
+    medianResidualM: number;
+    medianRecentGpsAccuracyM: number;
+    walkedDistanceM: number;
+    directionSpreadDeg: number; /** `null` when §4.3 is unavailable (no absolute compass). */
+    headingDeltaDeg: number | null;
+    compassDriftDetected: boolean;
+    observationsSeen: number; /** §4.6 — diagnostic only, never feeds the aggregate. */
+    gpsVsFusedMaxDivergenceM: number;
+  };
+}
+interface TrackingQualityOptions {
+  /** §4.1 ring-buffer length. Seed default; corpus-tuned in §6.1. */
+  matrixHistorySize?: number;
+  /** §4.2 GPS-window length. Seed default; corpus-tuned in §6.1. */
+  residualWindowSize?: number;
+  /** Confidence threshold below which `state` reports `'degraded'`. */
+  degradedThreshold?: number;
+  /** §4.4 window length for GPS-accuracy budget. */
+  gpsAccuracyWindowSize?: number;
+  /** §4.5 walked-distance threshold for coverage = 1.0. */
+  coverageWalkedDistanceM?: number;
+  /** §4.5 direction-spread threshold for coverage = 1.0. */
+  coverageDirectionSpreadDeg?: number;
+  /** §4.1 ΣΔrotation (deg) at/below which convergence scores 1.0. Fail ramp ends at 4×. */
+  convergenceRotationWarnDeg?: number;
+  /** §4.1 ΣΔtranslation (m) at/below which convergence scores 1.0. Fail ramp ends at 4×. */
+  convergenceTranslationWarnM?: number;
+  /** §4.3 EMA threshold (deg) below which compass scores 1.0. */
+  compassWarnDeg?: number;
+  /** §4.3 EMA threshold (deg) above which compass scores 0.0. */
+  compassFailDeg?: number;
+  /** Minimum GPS observations before leaving `warming-up`. */
+  warmupMinObservations?: number;
+  /** Minimum coverage score before leaving `warming-up`. */
+  warmupMinCoverage?: number;
+  /** §4.2 residual saturation target (m). */
+  residualConfidenceTargetM?: number;
+  /** §4.4 GPS-accuracy floor used to normalise residuals (m). */
+  gpsAccuracyFloorM?: number;
+  /** §4.3 consecutive compass-agreeing observations for first agreement. */
+  firstAgreementMinStreak?: number;
+  /** §4.8 consecutive sub-threshold observations before ok → degraded. */
+  degradedHoldoff?: number;
+  /**
+   * §4.8b (Finding 4) — EMA blend factor applied to `subScores.convergence`.
+   * `1.0` disables smoothing (raw value). `0 < α < 1` blends as
+   * `smoothed = prevSmoothed + α * (raw - prevSmoothed)`. First observation
+   * (no prior smoothed value) is seeded to the raw value.
+   */
+  convergenceEmaAlpha?: number;
+}
+declare const DEFAULT_TRACKING_QUALITY_OPTIONS: Required<TrackingQualityOptions>;
+/**
+ * Single buffered alignment matrix snapshot. `matrix` is stored as a
+ * plain `number[]` (length 16, row-major) so it stays serializable for
+ * RTK's `SerializableStateInvariantMiddleware` and for action logs.
+ */
+interface AlignmentSnapshot {
+  observationIndex: number;
+  matrix: number[];
+}
+interface TrackingQualitySliceState {
+  recentAlignments: AlignmentSnapshot[];
+  firstAgreementObservationIndex: number | null;
+  report: TrackingQualityReport | null;
+  /** §4.8 — consecutive observations with raw confidence < degradedThreshold. */
+  degradedConsecutiveCount: number;
+  /**
+   * §4.8b (Finding 4) — last EMA-smoothed convergence sub-score. `null`
+   * means "no prior observation" and the next aggregator run will seed
+   * the value with the raw convergence score. Reset on
+   * `resetTrackingQuality`.
+   */
+  smoothedConvergence: number | null;
+}
+interface ConvergenceResult {
+  score: number;
+  /** §4.1 (Finding 6): sum of |Δrotation| across the last N-1 pairs. */
+  recentSumRotationDeltaDeg: number;
+  /** §4.1 (Finding 6): sum of |Δtranslation| across the last N-1 pairs. */
+  recentSumTranslationDeltaM: number;
+  /** Pair count used (≥ 2 snapshots ⇒ ≥ 1 pair, else 0). */
+  pairCount: number;
+}
+/**
+ * §4.1 matrix-history convergence over the buffered snapshots.
+ *
+ * Reuses the same kernel idea as `computeStabilityDelta` from the
+ * Investigation helpers (rotation + translation delta between two 4×4
+ * matrices). With 0 or 1 snapshot we return score 0 — convergence is
+ * undefined until at least one consecutive pair exists.
+ *
+ * Finding 6 (2026-05-23 field test): the per-pair `max` aggregation was
+ * replaced with a **sum** across the window. `max` is a burst detector
+ * — dominated by one bad pair, blind to slow drift; `sum` answers
+ * "how much alignment motion accumulated over the window?" and exposes
+ * slow creeping drift in user-readable units (°, m). The HUD now shows
+ * the raw sums (`ΣΔrot:`, `ΣΔpos:`) alongside the EMA-smoothed `Conv:`
+ * sub-score (Finding 4) so the user can debug an unstable reading.
+ */
+declare function computeConvergence(snapshots: readonly AlignmentSnapshot[], options?: {
+  rotationWarnDeg?: number;
+  translationWarnM?: number;
+}): ConvergenceResult;
+/**
+ * Rotation and translation delta between two 4×4 alignment matrices in
+ * the column-major layout that gl-matrix and the framework use.
+ *
+ * Rotation: extract the orientation quaternion with `mat4.getRotation`
+ * and compute the relative angle via `quat.getAngle` (degrees).
+ * Translation: extract the origin column with `mat4.getTranslation` and
+ * compute the Euclidean distance.
+ *
+ * This is the **single shared kernel** for the AppFramework reporter and
+ * the Investigation harness (see §11 (a) of the tracking-quality plan).
+ * `GpsPlusSlamJs_Investigation/src/investigation-helpers.ts` re-exports
+ * `computeStabilityDelta` as a thin wrapper around this function so the
+ * §6.1 corpus sweep and the runtime convergence score share one numeric
+ * definition.
+ */
+declare function matrixDelta(prev: readonly number[], curr: readonly number[]): {
+  rotationDeltaDeg: number;
+  translationDeltaM: number;
+};
+interface ResidualConsensusResult {
+  score: number;
+  medianResidualM: number;
+  count: number;
+}
+/**
+ * §4.2 — Median residual between the last `K` GPS observations and the
+ * positions you would have predicted by transforming the matching
+ * odometry positions through the current alignment matrix.
+ *
+ * Returns `score = 0`, `medianResidualM = 0` when we have fewer than
+ * 2 paired observations or when the alignment matrix / zero ref is
+ * not yet set.
+ */
+declare function computeResidualConsensus(alignmentMatrix: Matrix4 | null, gpsPositions: readonly GpsPoint[], odometryPositions: readonly Vector3[], zeroRef: LatLong | null, options?: Pick<Required<TrackingQualityOptions>, 'residualWindowSize' | 'residualConfidenceTargetM' | 'gpsAccuracyFloorM'>): ResidualConsensusResult;
+interface GpsAccuracyResult {
+  score: number;
+  medianM: number;
+  countAccurate: number;
+  countTotal: number;
+}
+/**
+ * §4.4 — Median `latLongAccuracy` of the last `K` GPS points, with
+ * an "accurate-fix count" diagnostic. Cheap, always available.
+ *
+ * `score` ramps from 1.0 at median ≤ 3 m to 0.0 at median ≥ 25 m
+ * (linear), matching the plan's "≤ 5 m is good" heuristic with a
+ * generous fail tail.
+ */
+declare function computeGpsAccuracy(gpsPositions: readonly GpsPoint[], options?: {
+  windowSize?: number;
+  goodMedianM?: number;
+  badMedianM?: number;
+}): GpsAccuracyResult;
+interface CoverageResult {
+  score: number;
+  walkedDistanceM: number;
+  directionSpreadDeg: number;
+}
+/**
+ * §4.5 — Coverage = how far the user has walked AND how diverse the
+ * walking direction has been. Both required: a long but unidirectional
+ * walk leaves the rotation about the walking axis under-determined.
+ */
+declare function computeCoverage(odometryPositions: readonly Vector3[], options?: {
+  walkedDistanceM?: number;
+  directionSpreadDeg?: number;
+}): CoverageResult;
+interface CompassAgreementResult {
+  /** `null` when `absolute !== true` on the sensor orientation. */
+  score: number | null;
+  headingDeltaDeg: number | null;
+}
+/**
+ * §4.3 — Compare the alignment matrix's mapping of AR-forward to ENU
+ * against the device compass heading. Returns `score = null` whenever
+ * the sensor's `absolute !== true` so the aggregate excludes the
+ * sub-score (per Q2 in the plan).
+ *
+ * AR-forward in our `ARPose` convention is `(0, 0, -1)` (right-handed,
+ * Y-up). We rotate that by the alignment's 3×3 rotation, take its
+ * North/East components, and compare against the compass alpha.
+ */
+declare function computeCompassAgreement(alignmentMatrix: Matrix4 | null, sensorOrientation: DeviceOrientation | null, arPose: ARPose | null, options?: {
+  warnDeg?: number;
+  failDeg?: number;
+}): CompassAgreementResult;
+/**
+ * §4.6 — Maximum lateral distance between raw GPS positions and the
+ * positions you would predict by transforming the matching odometry
+ * positions through the current alignment. Diagnostic only — never
+ * feeds the aggregate confidence per the plan.
+ */
+declare function computeGpsVsFusedDivergence(alignmentMatrix: Matrix4 | null, gpsPositions: readonly GpsPoint[], odometryPositions: readonly Vector3[], zeroRef: LatLong | null, windowSize?: number): number;
+declare const snapshotPushed: _$_reduxjs_toolkit0.ActionCreatorWithPayload<AlignmentSnapshot, "trackingQuality/snapshotPushed">, snapshotsTrimmed: _$_reduxjs_toolkit0.ActionCreatorWithPayload<{
+    size: number;
+  }, "trackingQuality/snapshotsTrimmed">, reportUpdated: _$_reduxjs_toolkit0.ActionCreatorWithPayload<TrackingQualityReport | null, "trackingQuality/reportUpdated">, firstAgreementReached: _$_reduxjs_toolkit0.ActionCreatorWithPayload<number, "trackingQuality/firstAgreementReached">, degradedCountUpdated: _$_reduxjs_toolkit0.ActionCreatorWithPayload<number, "trackingQuality/degradedCountUpdated">, resetTrackingQuality: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"trackingQuality/resetTrackingQuality">;
+declare const trackingQualityReducer: _$_reduxjs_toolkit0.Reducer<TrackingQualitySliceState>;
+interface RootWithTrackingQuality {
+  trackingQuality?: TrackingQualitySliceState;
+}
+declare function selectTrackingQuality(state: RootWithTrackingQuality): TrackingQualityReport | null;
+declare function selectRecentAlignments(state: RootWithTrackingQuality): readonly AlignmentSnapshot[];
+declare function selectFirstAgreementObservationIndex(state: RootWithTrackingQuality): number | null;
+/**
+ * Pure function — produces a {@link TrackingQualityReport} from a root
+ * state and options. The Investigation harness imports this directly to
+ * sweep `(N, K)` without going through the Redux listener middleware.
+ *
+ * The report's `state` enum follows §5 of the plan:
+ *   - `ar-lost` whenever `tracking.phase !== 'tracking'`
+ *   - `warming-up` until `coverage ≥ warmupMinCoverage` AND
+ *     `observationsSeen ≥ warmupMinObservations`
+ *   - then `ok` / `degraded` from `min(subScores)` vs.
+ *     `degradedThreshold`.
+ */
+declare function computeTrackingQualityReport(rootState: CombinedRootState, options?: TrackingQualityOptions): TrackingQualityReport;
+/**
+ * Build the listener middleware that drives the `trackingQuality`
+ * slice. Register the returned middleware in `createSlamAppStore`.
+ *
+ * Behaviour:
+ *  - On `gpsData/recordGpsEvent` and `gpsData/setZeroPos`: if the
+ *    alignment matrix changed, dispatch `snapshotPushed` +
+ *    `snapshotsTrimmed`. Then recompute the report and dispatch
+ *    `reportUpdated` if it changed.
+ *  - On `recording/startSession` and `tracking/resetTracking`:
+ *    dispatch `resetTrackingQuality` and recompute the report.
+ *  - On `tracking/poseReceived` and `tracking/poseLost`: only
+ *    recompute the report (no buffer change).
+ *  - All dispatches are idempotency-gated so quiet motion does not
+ *    churn the store.
+ */
+declare function createTrackingQualityListenerMiddleware(options?: TrackingQualityOptions): Middleware;
+//#endregion
+//#region ../src/state/create-slam-app-store.d.ts
+/**
+ * Base shape produced by `createSlamAppStore` with no `extraReducers`.
+ *
+ * Library state (`gpsData` / `gpsElements` / `arElements`) plus the
+ * framework recording slice (`recording`).
+ */
+interface SlamAppRootState extends RootState {
+  recording: RecordingState;
+  tracking: TrackingSliceState;
+  trackingQuality: TrackingQualitySliceState;
+}
+/** A bare-minimum middleware signature compatible with RTK's middleware list. */
+type SlamAppMiddleware = Middleware<any, any, any>;
+/**
+ * Options for {@link createSlamAppStore}.
+ */
+interface SlamAppStoreOptions<ExtraReducers extends ReducersMapObject = Record<string, never>> {
+  /**
+   * Persistence backend used to bridge Redux actions to durable storage.
+   * Tests / replay paths should pass `NullStorageBackend`.
+   */
+  storageBackend: StorageBackend;
+  /**
+   * Caller-supplied reducers added alongside the framework's built-ins.
+   * Use this seam to plug recorder slices (routing, refPoints, scenario)
+   * or any app-specific state without forking the factory.
+   */
+  extraReducers?: ExtraReducers;
+  /**
+   * Caller-supplied middlewares appended after RTK defaults and the
+   * persistence middleware.
+   */
+  extraMiddleware?: ReadonlyArray<SlamAppMiddleware>;
+  /**
+   * Additional slice prefixes to persist beyond the framework built-ins
+   * (`gpsData`, `recording`). Pass caller-owned slice names derived from
+   * the slice itself — e.g. `slicePrefixOf(addRefPointEntry.type)` or
+   * `refPointsSlice.name` — never a hand-typed literal, so a rename can
+   * never silently drop the slice's actions from recordings.
+   */
+  persistedExtraPrefixes?: readonly string[];
+  /**
+   * Invoked when the persistence middleware fails to durably write an action.
+   */
+  onWriteFailure?: (error: Error) => void;
+  /**
+   * Disables RTK's expensive dev-only middleware (Serializable / Immutable
+   * checks). Default `true`; set `false` for high-throughput replay scenarios.
+   */
+  enableDevChecks?: boolean;
+  /**
+   * License key for the core library. Defaults to the bundled community key.
+   * Apps with a paid license override here. Validation always runs and throws
+   * on invalid / expired / empty keys.
+   *
+   * @see EULA.md §3 — License Key
+   */
+  licenseKey?: string;
+  /**
+   * Optional overrides for the tracking-quality reporter
+   * (matrix-history size, residual window, thresholds, etc.).
+   *
+   * @see docs/2026-05-16-tracking-quality-metrics-plan.md
+   */
+  trackingQualityOptions?: Partial<TrackingQualityOptions>;
+}
+/**
+ * Combined root state: the framework's base state plus any caller-supplied
+ * extras. Generic so consumers get exact typing for the slices they add.
+ */
+type SlamAppCombinedState<ExtraReducers extends ReducersMapObject = Record<never, never>> = SlamAppRootState & { [K in keyof ExtraReducers]: ExtraReducers[K] extends Reducer<infer S> ? S : never };
+/**
+ * The store object returned by {@link createSlamAppStore}.
+ *
+ * Wraps RTK's store and adds storage-delegation helpers so consumers can
+ * issue frame / metadata writes without holding a separate handle to the
+ * `StorageBackend`.
+ */
+interface SlamAppStore<ExtraReducers extends ReducersMapObject = Record<string, never>> {
+  getState: () => SlamAppCombinedState<ExtraReducers>;
+  dispatch: ReturnType<typeof configureStore>['dispatch'];
+  subscribe: (listener: () => void) => () => void;
+  /** Persist a captured camera frame via the configured backend. */
+  writeFrame: (blob: Blob, index: number) => Promise<void>;
+  /** Persist session metadata (`session.json`) via the configured backend. */
+  writeSessionMetadata: (metadata: SessionMetadata) => Promise<void>;
+}
+/**
+ * Build a Redux store wired with library + recording slices, persistence
+ * middleware, and any caller-supplied extras. See module docstring for the
+ * design rationale.
+ */
+declare function createSlamAppStore<ExtraReducers extends ReducersMapObject = Record<string, never>>(options: SlamAppStoreOptions<ExtraReducers>): SlamAppStore<ExtraReducers>;
+//#endregion
+export { resetTrackingQuality as A, computeResidualConsensus as C, firstAgreementReached as D, degradedCountUpdated as E, snapshotsTrimmed as F, trackingQualityReducer as I, CombinedRootState as L, selectRecentAlignments as M, selectTrackingQuality as N, matrixDelta as O, snapshotPushed as P, computeGpsVsFusedDivergence as S, createTrackingQualityListenerMiddleware as T, TrackingQualityState as _, SlamAppStoreOptions as a, computeCoverage as b, CompassAgreementResult as c, DEFAULT_TRACKING_QUALITY_OPTIONS as d, GpsAccuracyResult as f, TrackingQualitySliceState as g, TrackingQualityReport as h, SlamAppStore as i, selectFirstAgreementObservationIndex as j, reportUpdated as k, ConvergenceResult as l, TrackingQualityOptions as m, SlamAppMiddleware as n, createSlamAppStore as o, ResidualConsensusResult as p, SlamAppRootState as r, AlignmentSnapshot as s, SlamAppCombinedState as t, CoverageResult as u, computeCompassAgreement as v, computeTrackingQualityReport as w, computeGpsAccuracy as x, computeConvergence as y };

package/dist/{depth-sampler-BNCtnEoP.d.ts → depth-sampler-CqrkRr2N.d.ts}

@@ -1,4 +1,4 @@
-import { i as DepthSample, t as ARPose } from "./ar-types-B-ORgk6Z.js";
+import { i as DepthSample, t as ARPose } from "./ar-types-isPsQptb.js";
 
 //#region ../src/ar/depth-sampler.d.ts
 /**

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

@@ -0,0 +1,95 @@
+import { t as ArCrashIsolationOptions } from "./recording-options-BSFpBSZH.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-B7AlMPz5.js";
+import { n as PermissionStatus } from "./permission-checker-CfV7INCa.js";
+import { t as SessionFeatureOptions } from "./webxr-session-BnArFCew.js";
+
+//#region ../src/ar/enable-gps-ar.d.ts
+/**
+ * Lifecycle status of the controller. The app maps these onto its button:
+ * - `checking`   — support probe in flight (initial / after `refreshSupport`)
+ * - `unsupported`— WebXR immersive-ar is unavailable; button stays disabled
+ * - `ready`      — supported and idle; button is the live "Enable GPS AR" CTA
+ * - `starting`   — in-gesture orchestration in flight (button shows progress)
+ * - `running`    — AR session started; button reflects the durable end state
+ * - `stopping`   — teardown in flight (watches stopping, session ending)
+ * - `error`      — orchestration failed; button reverts to a retryable CTA
+ */
+type EnableGpsArStatus = 'checking' | 'unsupported' | 'ready' | 'starting' | 'running' | 'stopping' | 'error';
+/** Observable controller state. */
+interface EnableGpsArState {
+  readonly status: EnableGpsArStatus;
+  /** Human-readable failure reason when `status === 'error'`. */
+  readonly error?: string;
+}
+/** Per-`enable()` configuration. */
+interface EnableGpsArConfig {
+  /** DOM element hosting the AR canvas / dom-overlay (passed to `initAR`). */
+  container: HTMLElement;
+  /**
+   * Opt-in to the depth ("3D map") permission probe. Default `false` — the
+   * minimal default set is WebXR + geolocation + orientation only.
+   */
+  requestDepth?: boolean;
+  /**
+   * Forward `requestHitTest` to `initAR` so the session requests the WebXR
+   * `hit-test` feature (the minimal AR example needs this for its reticle).
+   */
+  requestHitTest?: boolean;
+  /** Crash-isolation diagnostic flags forwarded verbatim to `initAR`. */
+  isolationOptions?: Partial<ArCrashIsolationOptions>;
+  /** Receives every GPS fix from the started watch. */
+  onGpsPosition?: (position: GpsPosition) => void;
+  /** Receives every device-orientation sample from the started watch. */
+  onOrientation?: (orientation: RawDeviceOrientation) => void;
+}
+/** Result of a single `enable()` attempt. */
+interface EnableGpsArResult {
+  readonly ok: boolean;
+  /** Failure reason when `ok === false`. */
+  readonly error?: string;
+}
+/** Injectable collaborators (default to the real framework functions). */
+interface EnableGpsArDeps {
+  isWebXRSupported: () => Promise<boolean>;
+  requestGeolocationPermission: () => Promise<PermissionStatus>;
+  requestOrientationPermission: () => Promise<PermissionStatus>;
+  requestWebXRWithDepthPermission: () => Promise<PermissionStatus>;
+  startGpsWatch: (onPosition: (position: GpsPosition) => void, onError?: (error: GeolocationPositionError) => void) => void;
+  startOrientationWatch: (onOrientation: (orientation: RawDeviceOrientation) => void) => void;
+  initAR: (container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions) => Promise<void>;
+  stopGpsWatch: () => void;
+  stopOrientationWatch: () => void;
+  endARSession: () => Promise<void>;
+}
+/** Public controller surface the app drives from its button. */
+interface EnableGpsArController {
+  /** Current observable state (button derives its label/disabled from this). */
+  getState: () => EnableGpsArState;
+  /** Subscribe to state changes; returns an unsubscribe function. */
+  subscribe: (listener: (state: EnableGpsArState) => void) => () => void;
+  /**
+   * Probe WebXR support and move `checking → ready | unsupported`. Call once on
+   * boot (and optionally on resume). No-op effect on permissions.
+   */
+  refreshSupport: () => Promise<void>;
+  /**
+   * In-gesture orchestration: request the configured permissions, start the
+   * sensor watches and `initAR`. Must be called synchronously from a user
+   * gesture so the permission prompts are allowed. Idempotent while
+   * `starting`/`running`/`stopping`.
+   */
+  enable: (config: EnableGpsArConfig) => Promise<EnableGpsArResult>;
+  /**
+   * Tear down the running AR session: stop sensor watches, end the WebXR
+   * session, and transition `running → stopping → ready` so the user can
+   * re-enter AR. No-op when not `running`.
+   */
+  disable: () => Promise<void>;
+}
+/**
+ * Create an "Enable GPS AR" controller. Pass partial `deps` in tests to inject
+ * fakes; production callers use the defaults.
+ */
+declare function createEnableGpsArController(deps?: Partial<EnableGpsArDeps>): EnableGpsArController;
+//#endregion
+export { EnableGpsArState as a, EnableGpsArResult as i, EnableGpsArController as n, EnableGpsArStatus as o, EnableGpsArDeps as r, createEnableGpsArController as s, EnableGpsArConfig as t };

package/dist/{file-system-DD5TczSO.d.ts → file-system-TIsDfamK.d.ts}

@@ -1,4 +1,4 @@
-import { n as SessionMetadata } from "./opfs-storage-Dlq1I_Gb.js";
+import { n as SessionMetadata } from "./opfs-storage-LsLY6VZV.js";
 
 //#region ../src/storage/file-system.d.ts
 /**
@@ -80,5 +80,35 @@ declare function setCurrentScenario(scenarioName: string): Promise<FileSystemDir
  * Legacy: used during OPFS recovery.
  */
 declare function ensureScenarioDirectory(scenarioName: string): Promise<FileSystemDirectoryHandle | null>;
+/**
+ * Result of clearing the reference-point cache across all scenarios.
+ */
+interface ClearRefPointsCacheResult {
+  /** Number of scenarios whose `refPoints/` directory was deleted. */
+  readonly scenariosCleared: number;
+  /** Total number of scenarios scanned (including ones with no cache). */
+  readonly scenariosScanned: number;
+  /** Names of scenarios that failed to clear, with reason. */
+  readonly errors: {
+    scenarioName: string;
+    reason: string;
+  }[];
+}
+/**
+ * Clear the cached `refPoints/` directory for every scenario in OPFS.
+ *
+ * Used by the "Clear Reference Point Cache" maintenance action so that the
+ * next scenario load re-imports ref points from the read folder's `*.zip`
+ * recordings (see ref-point-recovery in the recorder app).
+ *
+ * Failures for individual scenarios are collected in `errors` rather than
+ * aborting the whole operation — partial progress is still useful.
+ *
+ * @throws Error if OPFS storage is unavailable (e.g. `initStorage()` not yet
+ *   called, or browser does not support OPFS). Surfacing this loudly avoids
+ *   reporting a silent "0 scenarios cleared" success that would mask the
+ *   real failure to the user.
+ */
+declare function clearRefPointsCacheForAllScenarios(): Promise<ClearRefPointsCacheResult>;
 //#endregion
-export { listSessions as a, setCurrentScenario as c, writeAction as d, writeFrame as f, initStorage as i, startSession as l, ensureScenarioDirectory as n, resetForNewSession as o, writeSessionMetadata as p, getCurrentScenarioHandle as r, resetStorageState as s, WriteAccessResult as t, verifyWriteAccess as u };
+export { getCurrentScenarioHandle as a, resetForNewSession as c, startSession as d, verifyWriteAccess as f, writeSessionMetadata as h, ensureScenarioDirectory as i, resetStorageState as l, writeFrame as m, WriteAccessResult as n, initStorage as o, writeAction as p, clearRefPointsCacheForAllScenarios as r, listSessions as s, ClearRefPointsCacheResult as t, setCurrentScenario as u };