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

package/LICENSE

@@ -181,10 +181,10 @@ APPENDIX: How to apply the Apache License to your work.
       boilerplate notice, with the fields enclosed by brackets "[]"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. Please also get an
-      "Alarm" or "alarm" from Alarm.com or its original author
-      of this boilerplate, which can be obtained from
-      http://www.apache.org/licenses/.
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
 
 Copyright 2026 cs-util-com
 

package/README.md

@@ -1,18 +1,45 @@
 # GPS+SLAM App Framework
 
-Reusable building blocks for AR+GPS applications built on [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js).
+[![npm version](https://img.shields.io/npm/v/gps-plus-slam-app-framework.svg)](https://www.npmjs.com/package/gps-plus-slam-app-framework)
+[![npm downloads](https://img.shields.io/npm/dm/gps-plus-slam-app-framework.svg)](https://www.npmjs.com/package/gps-plus-slam-app-framework)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/node/v/gps-plus-slam-app-framework.svg)](https://nodejs.org/)
 
-This library provides WebXR session management, Three.js visualization, GPS sensor coordination, storage abstractions, a replay engine, and store wiring — everything a web-based AR+GPS app needs beyond the core alignment algorithms.
+Reusable building blocks for AR+GPS web apps, built on top of the closed-source [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js) alignment core.
+
+It is part toolkit, part fusion engine: the toolkit covers the AR + GPS plumbing every app needs anyway, and the fusion engine lifts location accuracy to the point where ideas that previously sat on the "someday, on native" shelf become reachable in a browser:
+
+- A **WebXR + Three.js scene** with image and depth capture, replay rendering, and tracking-state monitoring.
+- **GPS, orientation, and permission wiring** ready to plug into the store.
+- **OPFS + ZIP record & replay** with a `StorageBackend` interface you can swap.
+- A **composable Redux store factory** (`createSlamAppStore`) that combines the core library's reducers with your own slices.
+
+## Why use GPS+SLAM? (Visual Stability Beyond Raw GPS)
+
+Raw GPS is useful for getting near a place, but it still jitters by meters and altitude is usually the hardest channel to trust. Most location-based AR apps work around that with broad proximity zones, floating beacons, or oversized highlights — fine as a fallback, but limiting if you want content that sits exactly on a path, a wall, or a specific spot on the ground.
+
+GPS+SLAM fuses GPS observations with the device's AR odometry, so as the user moves the alignment between the AR world and real-world coordinates gets more stable. On top of that, the framework gives you placement helpers for objects that should stay tied to a real location:
+
+- **Alignment improves with motion:** Once the user has walked for roughly 15 seconds in representative outdoor conditions, the solver has enough baseline that visible drift drops well below raw GPS. How stable it actually feels still depends on the device, the environment, and how clean the GPS track is — but in our own outdoor tests it consistently held up well enough for content that needs to sit on a specific spot.
+- **VPS-like benefits without a VPS dependency:** Cloud visual-positioning systems can work well, but they usually require network access and a provider-maintained scan of the place where the user stands. GPS+SLAM localizes from the device's own GPS, camera tracking, motion, and orientation sensors, so the same alignment approach works in rural areas, woods, mountains, and private sites that no VPS provider has pre-scanned.
+- **Just a URL, no app install:** The whole experience runs in the mobile browser through WebXR, so end users open a link and are in AR within seconds. There is no app-store gate, no native build per platform, and authors can iterate on the live URL while users keep using the same link.
+- **Heading does not depend only on the compass:** Phone compass data can be noisy, biased, or temporarily wrong enough to make a naive AR overlay rotate in the wrong direction. GPS+SLAM can infer the world heading from how the user actually moves through space, so after the user has walked a few meters the overlay no longer has to trust the device-orientation readings.
+- **Session-local objects stay fixed:** Objects created directly in the AR scene can stay at the same 3D position for the current session, independent of later GPS alignment updates. This is ideal for content the user creates live, such as a 3D trail of the path they walked, temporary markers, or objects they place by hand in the world.
+- **Anchors make placed content shareable:** When an object should also be tied to a GPS coordinate for replay, persistence, or sharing with other users, `createGpsAnchor` bootstraps from median GPS samples, keeps the Three.js object positioned from its GPS target inside `arWorldGroup`, and can defer small corrections until the object is off-screen. Large alignment jumps still force a correction so content does not remain in a stale location.
+- **Use exact paths and POIs, not only blobs:** Proximity zones remain a good UX for letting users enter an experience from any direction, but they do not have to be the only interaction model. The framework is designed for route-following cues, authored POI objects, precise areas of interest, and other content that benefits from being visibly tied to a real-world path or location.
+
+Don't take any of this on trust. Because everything runs in the browser, the fastest review is to open one of the example URLs on your own phone, step outside, drop an object, walk around it, and judge for yourself whether the stability holds up for your use case.
 
 ## Architecture
 
 ```
 ┌──────────────────────────────────────────────────┐
 │  Your App                                        │
-│  (UI, screen flow, app-specific logic)           │
+│  (UI, screen flow, app-specific reducers)        │
 ├──────────────────────────────────────────────────┤
 │  gps-plus-slam-app-framework  ← this package     │
-│  (WebXR, Three.js, sensors, storage, replay)     │
+│  (WebXR, Three.js, sensors, storage, replay,     │
+│   composable store factory)                      │
 ├──────────────────────────────────────────────────┤
 │  gps-plus-slam-js  (core algorithms)             │
 │  (GPS/AR alignment, outlier rejection, GPS math) │
@@ -24,175 +51,287 @@ The framework never imports from your app. Your app imports from the framework a
 ## Installation
 
 ```bash
-npm install gps-plus-slam-app-framework gps-plus-slam-js
+pnpm add gps-plus-slam-app-framework gps-plus-slam-js
 ```
 
+### Runtime Dependencies
+
+These are pulled in automatically — you do not need to install them yourself:
+
+- `@reduxjs/toolkit`
+- `gl-matrix`
+- `gps-plus-slam-js`
+
 ### Peer Dependencies
 
-Required:
+Required (install in your app):
 
 - `three` (>= 0.170.0)
 - `@zip.js/zip.js` (>= 2.7.0)
 - `h3-js` (>= 4.0.0)
-- `@reduxjs/toolkit` (>= 2.9.0)
 
 Optional:
 
-- `leaflet` (>= 1.9.0) — only needed if using `LeafletMapOverlay`
-- `@sentry/browser` (>= 10.0.0) — only needed for error reporting integration
+- `leaflet` (>= 1.9.0) — only needed if you use `LeafletMapOverlay`
+- `@sentry/browser` (>= 10.0.0) — only needed if you wire Sentry error reporting
 
 ## Quick Start
 
 ```typescript
-import { createRecorderStore } from 'gps-plus-slam-app-framework/state';
+import { createSlamAppStore } from 'gps-plus-slam-app-framework/state';
 import { initAR } from 'gps-plus-slam-app-framework/ar';
 import { startGpsWatch } from 'gps-plus-slam-app-framework/sensors';
-import { wireStoreSubscribers } from 'gps-plus-slam-app-framework/state';
-import { LeafletMapOverlay } from 'gps-plus-slam-app-framework/visualization';
+import { NullStorageBackend } from 'gps-plus-slam-app-framework/storage';
+import { recordGpsEvent } from 'gps-plus-slam-app-framework/state';
 
-// 1. Create store (wraps gps-plus-slam-js store with app-level slices)
-const store = createRecorderStore();
+// 1. Compose the store. NullStorageBackend keeps everything in memory; swap
+//    to OpfsStorageBackend when you want durable recording.
+const store = createSlamAppStore({
+  storageBackend: new NullStorageBackend(),
+});
+
+// 2. Start the WebXR AR session.
+await initAR(document.getElementById('app')!);
 
-// 2. Start GPS
+// 3. Wire GPS into the store.
 startGpsWatch(
   (pos) => {
-    /* feed position to recording coordinator */
+    store.dispatch(
+      recordGpsEvent({
+        /* build the payload from `pos` */
+      })
+    );
   },
   (err) => {
-    /* handle error */
+    console.error('GPS error', err);
   }
 );
+```
+
+See [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) for a complete, runnable smallest-possible consumer (Three.js scene + status panel, no AR, no recording).
+
+> **Imports.** Prefer subpath imports (`gps-plus-slam-app-framework/ar`, `…/state`, `…/sensors`, `…/storage`, `…/geo`, `…/visualization`, `…/utils`, `…/types`, `…/licensing`). The root barrel re-exports conflict-free names for convenience.
+
+## Composing With Your Own Slices
+
+`createSlamAppStore` is the headline composability seam. Your app plugs in its own reducers, middleware, and storage backend without forking the factory:
+
+```typescript
+import { createSlamAppStore } from 'gps-plus-slam-app-framework/state';
+import { OpfsStorageBackend } from 'gps-plus-slam-app-framework/storage';
+import { myUiReducer } from './state/ui-slice';
+import { myAnalyticsMiddleware } from './state/analytics-middleware';
+
+const store = createSlamAppStore({
+  storageBackend: new OpfsStorageBackend(),
+  extraReducers: { ui: myUiReducer },
+  extraMiddleware: [myAnalyticsMiddleware],
+  onWriteFailure: (err) => myErrorReporter(err),
+  enableDevChecks: import.meta.env.DEV,
+  // licenseKey: 'paid-key-here'  // omit to use the bundled community key
+});
+```
+
+| Option            | Purpose                                                                                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `storageBackend`  | **Required.** Bridge from Redux actions to durable storage. Use `NullStorageBackend` for tests/replay, `OpfsStorageBackend` for browser recording. |
+| `extraReducers`   | Caller-supplied reducers added alongside the framework's built-ins (`gpsData`, `gpsElements`, `arElements`, `recording`).                          |
+| `extraMiddleware` | Caller-supplied middlewares appended after RTK defaults and the persistence middleware.                                                            |
+| `onWriteFailure`  | Invoked when the persistence middleware fails to durably write an action.                                                                          |
+| `enableDevChecks` | Toggle RTK's expensive dev-only Serializable / Immutable checks. Default `true`; set `false` for high-throughput replay.                           |
+| `licenseKey`      | Override the bundled community key with a paid license. Validation always runs.                                                                    |
+
+## Recording & Replay
+
+Out of the box the framework lays out durable storage like this when you use `OpfsStorageBackend`:
+
+```
+/gps-plus-slam/
+  └── sessions/
+        └── recording-{timestamp}/
+              ├── actions/   (one JSON file per recorded Redux action)
+              ├── frames/    (captured camera/depth frames)
+              └── session.json
+```
+
+Key APIs:
+
+- `exportSessionAsZip(sessionHandle, { contributors? })` — bundle a recorded session into a ZIP blob.
+- `replayRecording(store, blob)` — feed a ZIP recording back into a store.
+- `loadActionsFromZip(blob)` / `loadEntriesFromSubdir(blob, subdir)` — read recorded actions or any contributor-defined ZIP subdirectory.
+
+### Adding Your Own ZIP Sections (`ZipExportContributor`)
 
-// 3. Start WebXR AR session
-const container = document.getElementById('app')!;
-await initAR(container);
+Apps that need to ship extra data alongside the standard recording (e.g., the recorder app stores `refPoints/` this way) implement a `ZipExportContributor`:
+
+```typescript
+import {
+  exportSessionAsZip,
+  type ZipExportContributor,
+} from 'gps-plus-slam-app-framework/storage';
+
+const refPointsContributor: ZipExportContributor = {
+  subdir: 'refPoints',
+  contribute: async (addFile) => {
+    addFile('points.json', JSON.stringify(myRefPoints));
+  },
+};
 
-// 4. Wire store → visualization
-wireStoreSubscribers(store, {
-  /* visualization dependencies */
+const blob = await exportSessionAsZip(sessionHandle, {
+  contributors: [refPointsContributor],
 });
 ```
 
-Import from **subpaths** (e.g., `gps-plus-slam-app-framework/ar`) for clarity. The root barrel re-exports most symbols but some names overlap across modules.
+## Scene-Graph Convention
+
+The framework's WebXR scene is laid out so that the **scene root is GPS-aligned (NUE) space**:
+
+```
+scene                             ← GPS-aligned (NUE) space, the scene root
+├── arWorldGroup                  ← carries the alignment matrix (GPS → AR)
+│   ├── camera                    ← WebXR XRViewerPose (raw AR pose)
+│   └── ar-content                ← anything fixed in AR space
+│                                   (planes, point clouds, hit-test reticles, …)
+└── ..objects with gps coords..   ← anything anchored to GPS coordinates
+                                    (waypoints, POIs, navigation arrows, …)
+```
+
+When the alignment solver produces a new matrix, the framework writes it to `arWorldGroup.matrix`. The camera moves with `arWorldGroup`; objects parented directly to `scene` do not.
+
+**Three options for placing your own `Object3D`:**
+
+1. **Add it to `scene`** (with NUE-meter coordinates from `calcRelativeCoordsInMeters(zeroRef, …)`). The object's world pose stays at the correct latitude/longitude/altitude forever, but every time the alignment matrix is corrected the camera shifts inside `arWorldGroup`, so from the user's AR view the object visually "floats". Cheap and correct, but ugly during corrections — fine for small markers (e.g. ref-point spheres), not great for richer GPS-anchored content.
+2. **Add it to `arWorldGroup`** with a fixed local transform. The object is frozen relative to AR-tracked content and stays visually fixed at the same 3D position for this session. This is a good fit for user-created local content such as a walked path, a temporary marker, a hit-test reticle, or an object the user placed by hand. The tradeoff is that its world / GPS pose drifts every time alignment is corrected, so this mode is not enough when the object must be replayed or shared by GPS coordinate.
+3. **Use `createGpsAnchor` for objects that should stay visually stable at a GPS target.** The anchor owns a single `Object3D` inside `arWorldGroup`, bootstraps from median GPS samples unless `skipBootstrap` is set, and re-derives the object's local pose from the current GPS target and alignment state. In the default `snap-when-offscreen` mode, small corrections are committed while the object is outside the camera frustum, making small alignment corrections hard to notice; larger alignment jumps bypass that gate so the object does not stay in a stale location. Use `snap-every-tick` when correctness is more important than hiding visible position changes.
+
+A pure-function `syncGpsAnchoredMeshes` reconciler (option 1, bulk markers) is shipped by the RecorderApp. Use `createGpsAnchor` when a single visible object, route cue, or POI needs the more careful bootstrap and correction policy.
 
 ## Modules
 
 ### `ar/` — WebXR & 3D Scene
 
-WebXR session lifecycle, Three.js renderer setup, image/depth capture, and replay scene management.
+WebXR session lifecycle, Three.js renderer setup, image/depth capture, replay scene management.
 
 | Export                                       | Description                                      |
 | -------------------------------------------- | ------------------------------------------------ |
 | `initAR(container)`                          | Start a WebXR AR session with Three.js rendering |
 | `endARSession()`                             | End the active XR session                        |
 | `startImageCapture()` / `stopImageCapture()` | Toggle camera frame capture                      |
-| `startDepthCapture()` / `stopDepthCapture()` | Toggle depth sampling                            |
-| `initReplayScene(container)`                 | Create a 3D replay scene with orbit/FPS controls |
 | `ImageCaptureManager`                        | Configurable camera frame capture pipeline       |
 | `DepthSampler`                               | Depth buffer sampling with configurable grids    |
 | `CameraBlitCapture`                          | GPU blit-based camera capture                    |
-| `TrackingStateManager`                       | AR tracking state monitoring                     |
+| `initReplayScene(container)`                 | Create a 3D replay scene with orbit/FPS controls |
+| `applyChromiumProjectionLayerWorkaround`     | Workaround for Chromium camera-access edge cases |
 
 ### `sensors/` — GPS & Permissions
 
-GPS watch abstraction, device orientation, and permission probing.
-
-| Export                        | Description                       |
-| ----------------------------- | --------------------------------- |
-| `startGpsWatch(onPos, onErr)` | Start watching GPS position       |
-| `stopGpsWatch()`              | Stop GPS watch                    |
-| `startOrientationWatch(cb)`   | Start device orientation events   |
-| `checkAllPermissions()`       | Probe camera, GPS, XR permissions |
-| `requestAllPermissions()`     | Request all needed permissions    |
-| `getGpsErrorMessage(code)`    | Human-readable GPS error messages |
+| Export                              | Description                               |
+| ----------------------------------- | ----------------------------------------- |
+| `startGpsWatch(onPos, onErr)`       | Start watching GPS position               |
+| `stopGpsWatch()`                    | Stop GPS watch                            |
+| `startOrientationWatch(cb)`         | Start device orientation events           |
+| `checkAllPermissions()`             | Probe camera, GPS, XR permissions         |
+| `requestAllPermissions()`           | Request all needed permissions            |
+| `getGpsErrorMessage(code)`          | Human-readable GPS error messages         |
+| `createGpsErrorHandler()`           | GPS error callback with deduplicated logs |
+| `requestWebXRWithDepthPermission()` | Combined XR + depth permission prompt     |
 
 ### `state/` — Store & Recording
 
-Combined Redux store factory, recording coordinator, replay engine, and store subscribers.
-
-| Export                              | Description                                   |
-| ----------------------------------- | --------------------------------------------- |
-| `createRecorderStore(options?)`     | Create a combined store (core + app slices)   |
-| `startSession()` / `endSession()`   | Session lifecycle actions                     |
-| `recordGpsEvent(payload)`           | Record a paired AR+GPS observation            |
-| `createGpsPositionHandler(config)`  | Factory for GPS→store wiring                  |
-| `ReplayEngine`                      | Timed action playback with pause/resume/speed |
-| `replayRecording(store, blob)`      | Replay a ZIP recording into a store           |
-| `wireStoreSubscribers(store, deps)` | Bridge store state → visualization updates    |
-| `loadRecordingOptions()`            | Load persisted recording settings             |
-| `refPointsReducer`                  | Reference point state reducer                 |
+| Export                                              | Description                                                    |
+| --------------------------------------------------- | -------------------------------------------------------------- |
+| `createSlamAppStore(options)`                       | Composable store factory (see options table above).            |
+| `recordingReducer`                                  | Recording lifecycle slice (built into the factory).            |
+| `startSession()` / `endSession()`                   | Recording lifecycle actions.                                   |
+| `recordGpsEvent(payload)`                           | Record a paired AR+GPS observation.                            |
+| `createGpsPositionHandler(config)`                  | Factory that adapts `GeolocationPosition` to a store dispatch. |
+| `captureGpsAnchorSample(options)`                   | Sample a paired AR pose + GPS point for anchoring.             |
+| `loadRecordingOptions()` / `saveRecordingOptions()` | Persist user-controlled recording settings.                    |
+| `replayRecording(store, blob)`                      | Replay a ZIP recording into a store.                           |
+| `ReplayEngine`                                      | Lower-level timed action playback with pause/resume/speed.     |
+| `createPersistenceMiddleware(options)`              | Middleware factory used internally by `createSlamAppStore`.    |
+| `wireStoreSubscribers(store, deps)`                 | Bridge store state → visualization updates.                    |
 
 ### `storage/` — OPFS, ZIP, File System
 
-Storage abstractions, OPFS implementation, ZIP export/import, and reference point persistence.
-
-| Export                                 | Description                                     |
-| -------------------------------------- | ----------------------------------------------- |
-| `StorageBackend`                       | Abstract storage interface (implement your own) |
-| `OpfsStorageBackend`                   | OPFS-based `StorageBackend` implementation      |
-| `NullStorageBackend`                   | No-op backend for testing                       |
-| `initOpfsStorage()`                    | Initialize OPFS directory structure             |
-| `initStorage(backend)`                 | Initialize the file-system layer                |
-| `exportSessionAsZip(handle)`           | Export a recording session as a ZIP blob        |
-| `loadActionsFromZip(blob)`             | Parse recorded actions from a ZIP file          |
-| `importRefPointsFromFolder(handle)`    | Import reference points from prior sessions     |
-| `saveRefPointObservation(handle, obs)` | Persist a reference point observation           |
+| Export                                         | Description                                             |
+| ---------------------------------------------- | ------------------------------------------------------- |
+| `StorageBackend`                               | Abstract storage interface (implement your own).        |
+| `OpfsStorageBackend`                           | OPFS-based `StorageBackend`.                            |
+| `NullStorageBackend`                           | No-op backend for tests and replay.                     |
+| `initOpfsStorage()` / `initStorage(backend)`   | Initialize the file-system layer.                       |
+| `createSession()` / `listSessions()`           | Session lifecycle on disk.                              |
+| `exportSessionAsZip(handle, { contributors })` | Export a recording session as a ZIP blob.               |
+| `ZipExportContributor`                         | Hook for adding your own ZIP subdirectories on export.  |
+| `loadActionsFromZip(blob)`                     | Parse recorded actions from a ZIP file.                 |
+| `loadEntriesFromSubdir(blob, subdir)`          | Read entries written by a contributor on import/replay. |
+| `loadSessionMetadataFromBlob(blob)`            | Read `session.json` from a ZIP.                         |
+| `loadGpsPathFromBlob(blob)`                    | Read the recorded GPS path.                             |
+| `checkStorageQuota()`                          | Check OPFS quota usage.                                 |
+
+### `geo/` — H3 Spatial Indexing
+
+H3-based proximity matching for GPS-anchored points (renamed from `ref-points/` in the boundary migration).
+
+| Export                           | Description                                                   |
+| -------------------------------- | ------------------------------------------------------------- |
+| `gpsToH3(lat, lon)`              | Convert GPS coordinates to an H3 cell index.                  |
+| `findNearbyGeoAnchor(h3, known)` | Find a known geo-anchored point near an H3 cell.              |
+| `h3CellsMatch(a, b)`             | Compare two H3 indices.                                       |
+| `approxDistanceMetres(a, b)`     | Approximate distance between two `LatLong`s.                  |
+| `isH3Index(value)`               | Type guard for H3 index strings.                              |
+| `H3_RESOLUTION`                  | The H3 resolution used (default: 12, ~10 m cells).            |
+| `KnownGeoAnchor` (type)          | Shape of a known anchor with H3 index, lat/lon, and metadata. |
 
 ### `visualization/` — Three.js & Maps
 
-Three.js markers, Leaflet map overlay, alignment interpolation, and camera controls.
-
-| Export                         | Description                                         |
-| ------------------------------ | --------------------------------------------------- |
-| `LeafletMapOverlay`            | 2D Leaflet map integrated via CSS3D into a 3D scene |
-| `MapOverlay`                   | Tile-based 3D map overlay (no Leaflet dependency)   |
-| `GpsEventVisualizer`           | Three.js spheres for GPS event positions            |
-| `RefPointVisualizer`           | Three.js spheres for reference points               |
-| `createAlignmentLerper()`      | Smooth alignment matrix interpolation               |
-| `createCameraFollower()`       | Camera that tracks a moving target                  |
-| `createCss3dRendererManager()` | CSS3D renderer for HTML-in-3D overlays              |
-| `createGpsCompassCubes()`      | Cardinal direction indicator cubes                  |
-| `VIS_COLORS`                   | Consistent color palette for visualizations         |
-| `disposeObject3D(obj)`         | Safe Three.js object disposal                       |
-
-### `ref-points/` — H3 Spatial Indexing
-
-H3-based proximity matching for reference points.
-
-| Export                          | Description                                      |
-| ------------------------------- | ------------------------------------------------ |
-| `gpsToH3(lat, lon)`             | Convert GPS coordinates to an H3 cell index      |
-| `findNearbyRefPoint(h3, known)` | Find a known reference point near an H3 cell     |
-| `H3_RESOLUTION`                 | The H3 resolution used (default: 12, ~10m cells) |
+| Export                         | Description                                            |
+| ------------------------------ | ------------------------------------------------------ |
+| `LeafletMapOverlay`            | 2D Leaflet map integrated via CSS3D into a 3D scene.   |
+| `MapOverlay`                   | Tile-based 3D map overlay (no Leaflet dependency).     |
+| `GpsEventVisualizer`           | Three.js spheres for GPS event positions.              |
+| `createAlignmentLerper()`      | Smooth alignment matrix interpolation.                 |
+| `createCameraFollower()`       | Camera that tracks a moving target.                    |
+| `createCss3dRendererManager()` | CSS3D renderer for HTML-in-3D overlays.                |
+| `createGpsCompassCubes()`      | Cardinal direction indicator cubes.                    |
+| `createGpsAnchor()`            | GPS-anchored placement helper for one Three.js object. |
+| `VIS_COLORS`                   | Consistent color palette for visualizations.           |
+| `disposeObject3D(obj)`         | Safe Three.js object disposal.                         |
 
 ### `utils/` — Logging & Helpers
 
-| Export                                      | Description                                      |
-| ------------------------------------------- | ------------------------------------------------ |
-| `createLogger(channel)`                     | Create a channeled logger with level control     |
-| `computeFusedPath(inputs)`                  | Compute a fused GPS+odometry path                |
-| `createFailureTracker(config)`              | Track failure rates with configurable thresholds |
-| `mapWithConcurrencyLimit(items, fn, limit)` | Async map with bounded concurrency               |
-| `formatFileSize(bytes)`                     | Human-readable file sizes                        |
+| Export                                      | Description                                       |
+| ------------------------------------------- | ------------------------------------------------- |
+| `createLogger(channel)`                     | Channeled logger with level control.              |
+| `getLogBuffer()` / `subscribeToLogs()`      | Inspect or subscribe to the in-memory log ring.   |
+| `computeFusedPath(inputs)`                  | Compute a fused GPS+odometry path.                |
+| `createFailureTracker(config)`              | Track failure rates with configurable thresholds. |
+| `mapWithConcurrencyLimit(items, fn, limit)` | Async map with bounded concurrency.               |
+| `formatFileSize(bytes)`                     | Human-readable file sizes.                        |
+| `listFormatter(items)`                      | Human-friendly comma/and list formatting.         |
 
 ### `types/` — Shared Type Definitions
 
-AR and GPS type definitions (`DepthPoint`, `DepthSample`, etc.) used across modules.
+AR and geo type definitions (`DepthPoint`, `DepthSample`, `LatLong`, `KnownGeoAnchor`, …) used across modules.
+
+### `licensing/` — Bundled Community Key
+
+Re-exports `COMMUNITY_LICENSE_KEY` from the core library so that consumers can pass it explicitly if they need to. `createSlamAppStore` already uses it as the default.
 
 ## Design Principles
 
 1. **No global singletons.** Everything is created via factories and passed explicitly.
-2. **Store is the integration point.** All modules communicate through Redux state.
+2. **Store is the integration point.** Modules communicate through Redux state.
 3. **Modules are optional.** Use `initAR` without `LeafletMapOverlay`. No forced coupling.
-4. **Swappable implementations.** The `StorageBackend` interface lets you replace OPFS with IndexedDB or a custom backend.
+4. **Swappable implementations.** The `StorageBackend` interface lets you replace OPFS with IndexedDB or anything else.
 
 ## Development
 
 ```bash
 cd GpsPlusSlamJs_AppFramework
-npm install
-npm test          # format + lint + typecheck + unit tests
-npm run build     # build with tsdown
+pnpm install
+pnpm test          # format + lint + typecheck + unit tests
+pnpm run build     # build with tsdown
 ```
 
 ### Project Structure
@@ -201,12 +340,13 @@ npm run build     # build with tsdown
 src/
 ├── ar/             # WebXR session, capture, replay scene
 ├── sensors/        # GPS, orientation, permissions
-├── state/          # Redux store, recording coordinator, replay
-├── storage/        # OPFS, ZIP, file system, ref-point persistence
-├── ref-points/     # H3 spatial indexing
+├── state/          # createSlamAppStore, recording, replay, persistence middleware
+├── storage/        # OPFS, ZIP export/import, StorageBackend
+├── geo/            # H3 spatial indexing
 ├── visualization/  # Three.js markers, maps, camera helpers
-├── utils/          # Logger, concurrency, formatters
+├── utils/          # Logger, fused-path, concurrency, formatters
 ├── types/          # Shared type definitions
+├── licensing/      # Bundled community license key
 └── test-utils/     # Test helpers (browser mocks, ZIP helpers)
 ```
 
@@ -214,9 +354,10 @@ src/
 
 This framework is licensed under **Apache 2.0** — see [LICENSE](LICENSE).
 
-> **Note:** This package depends on [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js), which is a **closed-source, proprietary** library distributed via npm under a separate license. A community license key is included in the open-source apps for frictionless development. See the core library's EULA for usage terms.
+> **Note:** This package depends on [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js), which is a **closed-source, proprietary** library distributed via npm under a separate license. A community license key is bundled with the framework for frictionless evaluation. See the core library's EULA for usage terms.
 
 ## See Also
 
-- [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js) — Core alignment algorithms (closed-source, UNLICENSED)
-- [Recorder App](../GpsPlusSlamJs_RecorderApp/) — Full-featured recording app built on this framework
+- [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js) — Core alignment algorithms (closed-source)
+- [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) — Smallest possible consumer of this framework
+- [`GpsPlusSlamJs_RecorderApp`](../GpsPlusSlamJs_RecorderApp/) — Full-featured recording app built on this framework

package/dist/accuracy-circles-CsxE_7x1.d.ts

@@ -0,0 +1,43 @@
+import L from "leaflet";
+
+//#region ../src/visualization/accuracy-circles.d.ts
+/**
+ * Style for per-event GPS accuracy circles. Radius comes from the GPS event's
+ * horizontal accuracy in meters; larger circles mean lower-quality fixes.
+ * Filled and stroked with a highly transparent variant of the path color so
+ * overlapping circles remain legible without obscuring the basemap or the
+ * polyline drawn on top.
+ */
+declare const ACCURACY_CIRCLE_FILL_OPACITY = 0.12;
+declare const ACCURACY_CIRCLE_STROKE_OPACITY = 0.5;
+declare const ACCURACY_CIRCLE_WEIGHT = 1;
+/**
+ * Minimal shape required to render an accuracy circle. Intentionally narrower
+ * than `RawGpsSample` so any caller with `lat`/`lng` and an optional
+ * `accuracy` (meters) can use this helper without coupling to a specific
+ * GPS-sample type.
+ */
+interface AccuracyCircleSample {
+  readonly lat: number;
+  readonly lng: number;
+  readonly accuracy?: number;
+}
+/**
+ * Draw one transparent circle per sample whose `accuracy` is a finite
+ * positive number. Samples without a usable accuracy value are skipped so
+ * pre-accuracy recordings still render their polyline.
+ *
+ * Circles are added to `map` immediately. The caller is responsible for
+ * draw-order: invoke this BEFORE adding the polyline so the line stays
+ * visually on top of the circles.
+ *
+ * @param map - The Leaflet map to add circles to.
+ * @param samples - GPS samples to consider; non-positive / non-finite
+ *   `accuracy` values are silently skipped.
+ * @param color - CSS color string used for both stroke and fill.
+ * @returns The created `L.Circle` instances, in the order they were added.
+ *   Callers that track layers for cleanup can append these to their list.
+ */
+declare function addAccuracyCircles(map: L.Map, samples: readonly AccuracyCircleSample[], color: string): L.Circle[];
+//#endregion
+export { addAccuracyCircles as a, AccuracyCircleSample as i, ACCURACY_CIRCLE_STROKE_OPACITY as n, ACCURACY_CIRCLE_WEIGHT as r, ACCURACY_CIRCLE_FILL_OPACITY as t };

package/dist/{app-selectors-DyMzxCEC.d.ts → app-selectors-BeU0_ab8.d.ts}

@@ -1,11 +1,11 @@
-import { n as CombinedRootState } from "./store-C7PKOj8S.js";
-import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
+import { L as CombinedRootState, r as SlamAppRootState } from "./create-slam-app-store-CNsZ3rcX.js";
 import * as _$gps_plus_slam_js0 from "gps-plus-slam-js";
-import { GpsPoint, LatLong, Matrix4, Quaternion, ReferencePoint, Vector3 } from "gps-plus-slam-js";
+import { ArImageCapture, GpsPoint, LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
+import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 
 //#region ../src/state/app-selectors.d.ts
 /** Alignment matrix (4×4), or null if not yet computed. */
-declare const selectAlignmentMatrix: ((state: CombinedRootState) => Matrix4 | null) & {
+declare const selectAlignmentMatrix: ((state: SlamAppRootState & {}) => Matrix4 | null) & {
   clearCache: () => void;
   resultsCount: () => number;
   resetResultsCount: () => void;
@@ -27,7 +27,7 @@ declare const selectAlignmentMatrix: ((state: CombinedRootState) => Matrix4 | nu
   argsMemoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
 };
 /** Recorded GPS positions with metadata. */
-declare const selectGpsPositions: ((state: CombinedRootState) => readonly GpsPoint[]) & {
+declare const selectGpsPositions: ((state: SlamAppRootState & {}) => readonly GpsPoint[]) & {
   clearCache: () => void;
   resultsCount: () => number;
   resetResultsCount: () => void;
@@ -49,7 +49,7 @@ declare const selectGpsPositions: ((state: CombinedRootState) => readonly GpsPoi
   argsMemoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
 };
 /** Recorded odometry positions (AR-local space). */
-declare const selectOdometryPositions: ((state: CombinedRootState) => readonly Vector3[]) & {
+declare const selectOdometryPositions: ((state: SlamAppRootState & {}) => readonly Vector3[]) & {
   clearCache: () => void;
   resultsCount: () => number;
   resetResultsCount: () => void;
@@ -71,7 +71,7 @@ declare const selectOdometryPositions: ((state: CombinedRootState) => readonly V
   argsMemoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
 };
 /** Recorded odometry rotations (AR-local space). */
-declare const selectOdometryRotations: ((state: CombinedRootState) => readonly Quaternion[]) & {
+declare const selectOdometryRotations: ((state: SlamAppRootState & {}) => readonly Quaternion[]) & {
   clearCache: () => void;
   resultsCount: () => number;
   resetResultsCount: () => void;
@@ -93,7 +93,7 @@ declare const selectOdometryRotations: ((state: CombinedRootState) => readonly Q
   argsMemoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
 };
 /** GPS zero reference (origin for coordinate conversion), or null. */
-declare const selectZeroReference: ((state: CombinedRootState) => LatLong | null) & {
+declare const selectZeroReference: ((state: SlamAppRootState & {}) => LatLong | null) & {
   clearCache: () => void;
   resultsCount: () => number;
   resetResultsCount: () => void;
@@ -114,20 +114,19 @@ declare const selectZeroReference: ((state: CombinedRootState) => LatLong | null
   memoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
   argsMemoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
 };
-/** User-defined reference points for ground truth validation. */
-declare const selectReferencePoints: ((state: CombinedRootState) => readonly ReferencePoint[]) & {
+declare const selectFrameTilesInWebXR: ((state: SlamAppRootState & {}) => readonly ArImageCapture[]) & {
   clearCache: () => void;
   resultsCount: () => number;
   resetResultsCount: () => void;
 } & {
-  resultFunc: (resultFuncArgs_0: _$gps_plus_slam_js0.GpsModel | null) => readonly ReferencePoint[];
-  memoizedResultFunc: ((resultFuncArgs_0: _$gps_plus_slam_js0.GpsModel | null) => readonly ReferencePoint[]) & {
+  resultFunc: (resultFuncArgs_0: ArImageCapture[] | undefined) => readonly ArImageCapture[];
+  memoizedResultFunc: ((resultFuncArgs_0: ArImageCapture[] | undefined) => readonly ArImageCapture[]) & {
     clearCache: () => void;
     resultsCount: () => number;
     resetResultsCount: () => void;
   };
-  lastResult: () => readonly ReferencePoint[];
-  dependencies: [(state: CombinedRootState) => _$gps_plus_slam_js0.GpsModel | null];
+  lastResult: () => readonly ArImageCapture[];
+  dependencies: [(state: CombinedRootState) => ArImageCapture[] | undefined];
   recomputations: () => number;
   resetRecomputations: () => void;
   dependencyRecomputations: () => number;
@@ -137,4 +136,4 @@ declare const selectReferencePoints: ((state: CombinedRootState) => readonly Ref
   argsMemoize: typeof _$_reduxjs_toolkit0.weakMapMemoize;
 };
 //#endregion
-export { selectReferencePoints as a, selectOdometryRotations as i, selectGpsPositions as n, selectZeroReference as o, selectOdometryPositions as r, selectAlignmentMatrix as t };
+export { selectOdometryRotations as a, selectOdometryPositions as i, selectFrameTilesInWebXR as n, selectZeroReference as o, selectGpsPositions as r, selectAlignmentMatrix as t };