gps-plus-slam-app-framework 1.0.0 → 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-DTApEv_Q.d.ts

@@ -0,0 +1,114 @@
+import { n as SessionMetadata } from "./opfs-storage-DOPkzgeT.js";
+
+//#region ../src/storage/file-system.d.ts
+/**
+ * Reset module state - exported for testing only
+ * @internal
+ */
+declare function resetStorageState(): void;
+/**
+ * Reset session-level state for a new recording.
+ *
+ * Clears scenario/session names and OPFS session handles, but preserves
+ * `storageInitialized` and the OPFS root so `initStorage()` doesn't need
+ * to be called again.
+ */
+declare function resetForNewSession(): void;
+/**
+ * Result of write access verification.
+ */
+interface WriteAccessResult {
+  /** Whether write access was successfully verified */
+  success: boolean;
+  /** Error message if write verification failed */
+  error?: string;
+}
+/**
+ * Verify that we have actual write access to a directory.
+ */
+declare function verifyWriteAccess(dirHandle: FileSystemDirectoryHandle): Promise<WriteAccessResult>;
+/**
+ * Initialize storage using OPFS.
+ *
+ * @returns List of existing scenario folder names
+ * @throws Error if OPFS is not supported
+ */
+declare function initStorage(): Promise<string[]>;
+/**
+ * Create a new session folder.
+ *
+ * When scenarioName is provided, creates under the scenario directory
+ * (legacy scenario layout for the recorder). When omitted, creates under
+ * the flat sessions/ directory.
+ *
+ * @param scenarioName - Optional name of the scenario (omit for flat layout)
+ */
+declare function startSession(scenarioName?: string): Promise<{
+  scenarioPath: string;
+  sessionPath: string;
+}>;
+/**
+ * List all session names.
+ * When scenarioName is provided, lists sessions under that scenario.
+ * Otherwise lists flat sessions.
+ */
+declare function listSessions(scenarioName?: string): Promise<string[]>;
+/**
+ * Write a Redux action to OPFS as a JSON file.
+ */
+declare function writeAction(action: unknown, index: number): Promise<void>;
+/**
+ * Write a captured frame image to OPFS.
+ */
+declare function writeFrame(blob: Blob, index: number): Promise<void>;
+/**
+ * Write session metadata (session.json) to OPFS.
+ */
+declare function writeSessionMetadata(metadata: SessionMetadata): Promise<void>;
+/**
+ * Get the current scenario handle (for loading prior sessions).
+ * Legacy: uses scenario directory layout.
+ */
+declare function getCurrentScenarioHandle(): FileSystemDirectoryHandle | null;
+/**
+ * Set the current scenario handle (when user selects a scenario).
+ * Legacy: uses scenario directory layout.
+ */
+declare function setCurrentScenario(scenarioName: string): Promise<FileSystemDirectoryHandle | null>;
+/**
+ * Ensure a scenario directory exists in OPFS, creating it if necessary.
+ * 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 { 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

@@ -0,0 +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-BhfgNbdW.js";
+export { H3_RESOLUTION, KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };

package/dist/{ref-points/h3-ref-point.js → geo/h3-proximity.js}

@@ -1,12 +1,16 @@
 import { gridDisk, latLngToCell } from "h3-js";
-//#region ../src/ref-points/h3-ref-point.ts
+//#region ../src/geo/h3-proximity.ts
 /**
-* H3 Reference Point Matching
+* H3 Geo-Anchor Proximity Matching
 *
-* Utility for matching GPS positions to known reference points using
-* H3 hexagonal grid indices. Uses gridDisk(cell, 1) to create a ~65m
+* Generic utility for matching GPS positions to known geo-anchored points
+* using H3 hexagonal grid indices. Uses gridDisk(cell, 1) to create a ~65m
 * safe zone that absorbs GPS jitter of 3-10m.
 *
+* Renamed from `ref-points/h3-ref-point.ts` in Iter 4 to drop recorder-only
+* naming. The math is unchanged; only the public type/function names were
+* generalised so the framework can serve any geo-anchored consumer.
+*
 * @see docs/2026-03-08-ref-point-naming-investigation.md §6
 */
 /** H3 resolution 11: ~25m edge, ~65m gridDisk safe zone */
@@ -32,20 +36,20 @@ function approxDistanceMetres(lat1, lon1, lat2, lon2) {
 	return R * Math.sqrt(dLat * dLat + x * x);
 }
 /**
-* Find the known reference point closest to the given GPS position,
+* Find the known geo-anchor closest to the given GPS position,
 * provided it falls within the gridDisk safe zone.
 *
 * The safe zone is the center cell plus its 6 neighbors (~65m radius),
-* which absorbs GPS jitter of 3-10m while keeping ref points >130m apart
+* which absorbs GPS jitter of 3-10m while keeping anchors >130m apart
 * distinguishable.
 *
-* When multiple ref points have overlapping safe zones (65–130 m apart),
+* When multiple anchors have overlapping safe zones (65–130 m apart),
 * the closest one by equirectangular distance is returned.
 */
-function findNearbyRefPoint(lat, lng, knownRefPoints) {
-	if (knownRefPoints.length === 0) return;
+function findNearbyGeoAnchor(lat, lng, knownAnchors) {
+	if (knownAnchors.length === 0) return;
 	const safeZone = gridDisk(latLngToCell(lat, lng, 11), 1);
-	const candidates = knownRefPoints.filter((rp) => safeZone.includes(rp.h3Index));
+	const candidates = knownAnchors.filter((rp) => safeZone.includes(rp.h3Index));
 	if (candidates.length === 0) return void 0;
 	if (candidates.length === 1) return candidates[0];
 	return candidates.reduce((closest, rp) => {
@@ -57,7 +61,7 @@ function findNearbyRefPoint(lat, lng, knownRefPoints) {
 * (i.e., one falls within the other's gridDisk safe zone).
 * This is the canonical cross-session matching check.
 */
-function h3RefsMatch(h3a, h3b) {
+function h3CellsMatch(h3a, h3b) {
 	if (h3a === h3b) return true;
 	return gridDisk(h3a, 1).includes(h3b);
 }
@@ -71,4 +75,4 @@ function isH3Index(id) {
 	return H3_INDEX_PATTERN.test(id);
 }
 //#endregion
-export { H3_RESOLUTION, approxDistanceMetres, findNearbyRefPoint, gpsToH3, h3RefsMatch, isH3Index };
+export { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/index.d.ts

@@ -0,0 +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-BhfgNbdW.js";
+export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };