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

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

@@ -0,0 +1,371 @@
+import { t as ARPose } from "./ar-types-Ck8LEq8k.js";
+import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-utCNND8t.js";
+import { t as RecordingState } from "./recording-slice-d6OtCrza.js";
+import { n as SessionMetadata } from "./opfs-storage-DOPkzgeT.js";
+import { n as StorageBackend } from "./storage-backend-CT0Il_AB.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-xg8vna6c.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-Ck8LEq8k.js";
 
 //#region ../src/ar/depth-sampler.d.ts
 /**

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

@@ -1,4 +1,4 @@
-import { n as SessionMetadata } from "./opfs-storage-Dlq1I_Gb.js";
+import { n as SessionMetadata } from "./opfs-storage-DOPkzgeT.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 };

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

@@ -0,0 +1,42 @@
+//#region ../src/ar/frame-loop.d.ts
+/**
+ * Per-frame callback registry. The WebXR session owns the single
+ * `renderer.setAnimationLoop(...)` hook for the page; components that need
+ * a per-frame tick register here and the session's `onXRFrame` invokes
+ * `runFrameUpdates(dt, elapsed)` once per frame.
+ *
+ * Plain functions, not a class: there is exactly one frame loop per session
+ * and singletons-of-singletons add no value. See
+ * `2026-05-13-ecs-migration-plan.md` for the design rationale and the
+ * rules new `FrameUpdate` bodies must follow (pure function of `dt` plus
+ * selectors; no direct Redux dispatch from inside a tick).
+ */
+type FrameUpdate = (dt: number, elapsed: number) => void;
+/**
+ * Register a per-frame callback. Returns an unregister function.
+ *
+ * Registration is idempotent — calling with the same `fn` twice is a no-op
+ * (it remains a single entry in the underlying `Set`).
+ */
+declare function registerFrameUpdate(fn: FrameUpdate): () => void;
+/**
+ * Invoke all registered callbacks. Called by the WebXR session's
+ * `onXRFrame` once per frame with the XR-derived `dt` (seconds since the
+ * previous frame; 0 on the first frame after a reset) and `elapsed`
+ * (seconds since the session started).
+ *
+ * The set is snapshotted before iterating so that
+ * `registerFrameUpdate` / unregister calls made by a handler during the
+ * same frame are deferred to the next tick. Iterating the live `Set`
+ * would otherwise skip a not-yet-visited entry that an earlier handler
+ * unregistered — a hard-to-debug source of non-determinism.
+ */
+declare function runFrameUpdates(dt: number, elapsed: number): void;
+/**
+ * Clear all registrations. Called from `resetWebXRState()` so a fresh
+ * session starts with an empty registry (any callbacks from the previous
+ * session are dropped along with their owning components).
+ */
+declare function clearFrameUpdates(): void;
+//#endregion
+export { runFrameUpdates as i, clearFrameUpdates as n, registerFrameUpdate as r, FrameUpdate as t };

package/dist/frustum-visibility-BHnFrSKQ.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from "three";
+
+//#region ../src/visualization/frustum-visibility.d.ts
+/**
+ * Build (or refresh) a Three.js `Frustum` from `camera`'s current world
+ * transform and projection matrix. If `out` is provided, the frustum is
+ * written into it and returned; otherwise the module-level scratch frustum
+ * is used. Callers MUST treat the returned frustum as immutable until they
+ * next call this function or use one of the predicates without an injected
+ * frustum (both reuse the same scratch).
+ */
+declare function buildCameraFrustum(camera: THREE.Camera, out?: THREE.Frustum): THREE.Frustum;
+/**
+ * Strictly check whether a single world-space point lies inside all six
+ * frustum planes. Useful for HUD/follow logic where the caller already has
+ * the target world position and wants the cheapest possible check.
+ */
+declare function isPointInCameraFrustum(camera: THREE.Camera, point: THREE.Vector3, frustum?: THREE.Frustum): boolean;
+/**
+ * Check whether a world-space bounding sphere intersects the camera frustum
+ * (returns true even for partial overlap). Useful for callers that maintain
+ * a precomputed bounding sphere (LOD systems, instanced meshes, future
+ * `ArPowerSaver`).
+ */
+declare function isSphereInCameraFrustum(camera: THREE.Camera, sphere: THREE.Sphere, frustum?: THREE.Frustum): boolean;
+/**
+ * Check whether an `Object3D` is currently (at least partially) inside the
+ * camera frustum. The world bounding volume is resolved in tiers, cheapest
+ * first, so each common Three.js object type is gated by where it actually
+ * draws:
+ *
+ *  1. **Sprites** (`isSprite`) are screen-space billboards with no meaningful
+ *     world geometry, so their world-space origin is tested as a point.
+ *  2. **Objects carrying an object-level `boundingSphere`** (`InstancedMesh`,
+ *     `SkinnedMesh`, or any caller that pre-populates one) use that sphere,
+ *     which reflects the instance spread / posed extent — unlike the base
+ *     geometry sphere. It is computed lazily via `computeBoundingSphere()`
+ *     when missing.
+ *  3. **Single renderables carrying a `geometry`** (`Mesh`, `Points`, `Line`,
+ *     …) use the geometry's local bounding sphere × `matrixWorld`.
+ *  4. **Containers with children** (`Group`, `LOD`, …) use the world-space
+ *     union of their descendants' bounding boxes (`Box3.setFromObject`),
+ *     converted to a sphere.
+ *  5. **Truly empty / geometry-less objects** have no bounding volume and are
+ *     treated as visible (`true`) — the conservative default for visibility
+ *     gating.
+ *
+ * This deliberately avoids `Frustum.intersectsObject`, which unconditionally
+ * dereferences `object.geometry.boundingSphere` and therefore throws a
+ * `TypeError` for geometry-less objects such as `Group`s.
+ *
+ * Callers should ensure `object.updateMatrixWorld()` (with descendants, for
+ * containers: `updateMatrixWorld(true)`) has already run this frame (it
+ * normally has, via `renderer.render`).
+ */
+declare function isObjectInCameraFrustum(camera: THREE.Camera, object: THREE.Object3D, frustum?: THREE.Frustum): boolean;
+//#endregion
+export { isSphereInCameraFrustum as i, isObjectInCameraFrustum as n, isPointInCameraFrustum as r, buildCameraFrustum as t };

package/dist/{fused-path-DtqCSqJh.d.ts → fused-path-CB4DwWOG.d.ts}

@@ -1,4 +1,4 @@
-import { t as GpsCoord } from "./geo-types-Xx-LVcnw.js";
+import { t as GpsCoord } from "./geo-types-CTuF23gG.js";
 import { LatLong, Matrix4, Vector3, fusedGpsFromOdom } from "gps-plus-slam-js";
 
 //#region ../src/utils/fused-path.d.ts

package/dist/geo/h3-proximity.d.ts

@@ -1,2 +1,2 @@
-import { a as gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-GwesPTFT.js";
+import { a as gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-BhfgNbdW.js";
 export { H3_RESOLUTION, KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/index.d.ts

@@ -1,2 +1,2 @@
-import { a as gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-GwesPTFT.js";
+import { a as gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-BhfgNbdW.js";
 export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };

package/dist/{geo-types-Xx-LVcnw.d.ts → geo-types-CTuF23gG.d.ts}

@@ -18,6 +18,21 @@ interface GpsCoord {
   readonly lat: number;
   readonly lng: number;
 }
+/**
+ * A raw GPS sample with optional accuracy (1σ horizontal radius in meters,
+ * mirroring the browser's `GeolocationCoordinates.accuracy`).
+ *
+ * Used for 2D map visualizations that draw a per-event accuracy circle
+ * alongside the GPS polyline so that low-quality fixes (large radius) are
+ * visually distinguishable from accurate fixes (small radius).
+ */
+interface RawGpsSample extends GpsCoord {
+  /**
+   * Horizontal accuracy in meters (1σ / 68% confidence).
+   * `undefined` when the source GPS event lacked the field.
+   */
+  readonly accuracy?: number;
+}
 /**
  * A reference point with GPS location and a human-readable name.
  * Extends GpsCoord so it is usable wherever GpsCoord is expected.
@@ -26,4 +41,4 @@ interface RefPointMarker extends GpsCoord {
   readonly name: string;
 }
 //#endregion
-export { RefPointMarker as n, GpsCoord as t };
+export { RawGpsSample as n, RefPointMarker as r, GpsCoord as t };

package/dist/{gps-GKc6_Cly.d.ts → gps-DXoQb9Kf.d.ts}

@@ -17,7 +17,7 @@ interface GpsPosition {
 /**
  * Raw device orientation from the browser's DeviceOrientationEvent API.
  * Fields are nullable because sensors may be unavailable on some devices.
- * See also: DeviceOrientation in ar/tracking-state.ts (resolved, non-nullable).
+ * See also: DeviceOrientation in state/tracking-slice.ts (resolved, non-nullable).
  */
 interface RawDeviceOrientation {
   alpha: number | null;

package/dist/gps-anchor-CnWY61XK.d.ts

@@ -0,0 +1,48 @@
+import { i as LatLongAlt, r as LatLong } from "./index-gzWJMVpo.js";
+import * as THREE from "three";
+
+//#region ../src/visualization/gps-anchor.d.ts
+type GpsAnchorMode = 'snap-when-offscreen' | 'snap-every-tick';
+type GpsAnchorPhase = 'bootstrap' | 'anchored';
+/**
+ * The minimum shape needed for the bootstrap median — a `LatLong` with
+ * optional altitude. Re-exported as a named alias so the sidecar and
+ * tests can refer to "the kind of point the anchor samples" without
+ * importing core types.
+ */
+type GpsAnchorSamplePoint = LatLong | LatLongAlt;
+interface GpsAnchorOptions {
+  readonly object3D: THREE.Object3D;
+  readonly arWorldGroup: THREE.Object3D;
+  readonly camera: THREE.Camera;
+  readonly gpsPoint: LatLong | LatLongAlt;
+  readonly skipBootstrap?: boolean;
+  readonly getAlignmentMatrix: () => readonly number[] | null;
+  readonly getGpsZeroRef: () => LatLong | null;
+  /** Returns the current GPS reading at "now", or null when no fix yet. */
+  readonly getCurrentGpsPoint: () => GpsAnchorSamplePoint | null;
+  readonly mode?: GpsAnchorMode;
+  readonly floorY?: () => number | null;
+  readonly distanceThreshold?: number;
+  readonly angleThresholdInDegrees?: number;
+  readonly targetPosRefreshRateInSec?: number;
+  /** Number of 1 Hz samples collected during bootstrap. Default 7. */
+  readonly secondsToAccumulateGpsPose?: number;
+  /** Wait window (seconds) at phase entry during which no samples are taken. Default 0. */
+  readonly settlingSeconds?: number;
+  readonly heightAboveGround?: number | null;
+}
+interface GpsAnchor {
+  readonly phase: GpsAnchorPhase;
+  readonly isFullyAnchored: boolean;
+  /** Current target GPS pose; during `bootstrap` this is the seed, post-bootstrap the median. */
+  readonly gpsPoint: LatLong | LatLongAlt;
+  markMovedExternally(): void;
+  setGpsPoint(point: LatLong | LatLongAlt): void;
+  dispose(): void;
+  /** @internal — testing seam; exposed in lieu of pumping `runFrameUpdates`. */
+  __tickForTests(dt: number, elapsed: number): void;
+}
+declare function createGpsAnchor(options: GpsAnchorOptions): GpsAnchor;
+//#endregion
+export { GpsAnchorSamplePoint as a, GpsAnchorPhase as i, GpsAnchorMode as n, createGpsAnchor as o, GpsAnchorOptions as r, GpsAnchor as t };