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

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,340 @@ 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. Compose the store. NullStorageBackend keeps everything in memory; swap
+//    to OpfsStorageBackend when you want durable recording.
+const store = createSlamAppStore({
+  storageBackend: new NullStorageBackend(),
+});
 
-// 1. Create store (wraps gps-plus-slam-js store with app-level slices)
-const store = createRecorderStore();
+// 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). For the next rung up — a readable AR + GPS + persistence demo (a single GPS anchor that survives a page reload) — see [`GpsPlusSlamJs_AnchorStarter`](../GpsPlusSlamJs_AnchorStarter/). The example ladder is **trivial** (MinimalExample) → **starter** (AnchorStarter) → **full** (RecorderApp).
+
+> **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.
 
-// 3. Start WebXR AR session
-const container = document.getElementById('app')!;
-await initAR(container);
+## Composing With Your Own Slices
 
-// 4. Wire store → visualization
-wireStoreSubscribers(store, {
-  /* visualization dependencies */
+`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
 });
 ```
 
-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.
+| 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.                                                                    |
 
-## Modules
+## Recording & Replay
 
-### `ar/` — WebXR & 3D Scene
+Out of the box the framework lays out durable storage like this when you use `OpfsStorageBackend`:
 
-WebXR session lifecycle, Three.js renderer setup, image/depth capture, and replay scene management.
+```
+/gps-plus-slam/
+  └── sessions/
+        └── recording-{timestamp}/
+              ├── actions/   (one JSON file per recorded Redux action)
+              ├── frames/    (captured camera/depth frames)
+              └── session.json
+```
 
-| 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                     |
+Key APIs:
 
-### `sensors/` — GPS & Permissions
+- `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.
 
-GPS watch abstraction, device orientation, and permission probing.
+### Adding Your Own ZIP Sections (`ZipExportContributor`)
 
-| 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 |
+Apps that need to ship extra data alongside the standard recording (e.g., the recorder app stores `refPoints/` this way) implement a `ZipExportContributor`:
 
-### `state/` — Store & Recording
+```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));
+  },
+};
 
-Combined Redux store factory, recording coordinator, replay engine, and store subscribers.
+const blob = await exportSessionAsZip(sessionHandle, {
+  contributors: [refPointsContributor],
+});
+```
 
-| 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                 |
+## Scene-Graph Convention
 
-### `storage/` — OPFS, ZIP, File System
+The framework's WebXR scene is laid out so that the **scene root is GPS-aligned (NUE) space**:
 
-Storage abstractions, OPFS implementation, ZIP export/import, and reference point persistence.
+```
+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, …)
+```
 
-| 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           |
+When the alignment solver produces a new matrix, the framework writes it to `arWorldGroup.matrix` (smoothly lerped — see `enableArWorldGroupAlignment` below). The camera moves with `arWorldGroup`; objects parented directly to `scene` do not.
 
-### `visualization/` — Three.js & Maps
+> **Apply alignment to `arWorldGroup` — the framework default.** Call
+> [`enableArWorldGroupAlignment({ store, arWorldGroup })`](src/visualization/ar-world-group-alignment.ts.md)
+> once after AR starts. It subscribes to the store's alignment matrix, lerps it
+> onto `arWorldGroup.matrix` each frame, and thereby **GPS-registers the view**:
+> the camera and every object parented under `arWorldGroup` (including GPS
+> anchors) shift together as alignment refines, so anchors stay stable in the AR
+> overlay and only ever correct a small residual. The recorder wires its own
+> lerper; the simpler apps use this helper. Forgetting it leaves the camera
+> pure-VIO and forces each anchor to absorb the full alignment delta on every
+> re-registration.
+
+**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`** (the factory throws if `object3D` is not a descendant of the `arWorldGroup` you pass — placing an anchor under the scene root defeats AR stability), bootstraps from median samples unless `skipBootstrap` is set, and re-derives the object's local pose from the current GPS target and alignment state each tick. Because the object rides the (lerped) `arWorldGroup` alignment, its motion relative to the camera between re-registrations is small. In the default `snap-when-offscreen` mode an accepted correction is committed **instantly** while the object is outside the camera frustum, making the (now small, residual) correction 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. Smoothing is **not** per-anchor: it lives once in the lerped `arWorldGroup.matrix` (`enableArWorldGroupAlignment`), so the whole AR world eases together. This is how the MinimalExample and AnchorStarter get the smooth alignment feel.
+
+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.
 
-Three.js markers, Leaflet map overlay, alignment interpolation, and camera controls.
+> **Worked example.** The [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) ports the stock three.js `webxr_ar_hittest` example onto this convention and ends in a deliberate side-by-side **contrast demo**: a tap co-spawns an option-1 floater under `scene` and an option-3 `createGpsAnchor` marker under `arWorldGroup` at the same world pose, so the drift difference is visible. It is the canonical reference for options 1–3 and for the `registerXrFrameUpdate` + Enable-GPS-AR seams below.
 
-| 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                       |
+## DOM-Overlay / HUD stacking convention
 
-### `ref-points/` — H3 Spatial Indexing
+`initAR(container)` requests the WebXR **`dom-overlay`** feature with
+`domOverlay.root = container` — the **same element you pass in**. During an
+`immersive-ar` session the browser composites **only that element's subtree**
+over the camera feed; everything else on the page is hidden until the session
+ends.
 
-H3-based proximity matching for reference points.
+> **The rule:** every HUD / overlay / button you want visible **in AR** must be
+> a **DOM descendant of the element you pass to `initAR`**. A sibling overlay
+> works in the 2D pre-AR layout but silently disappears the moment AR starts —
+> a failure that only shows up on real AR hardware, never in a headless test.
+
+This is **not** a `z-index` problem; `z-index`/`pointer-events` only govern the
+2D (pre-AR) layout. Nesting is what determines in-AR visibility.
+
+```html
+<!-- ✅ Correct: HUD is inside the initAR container -->
+<div id="app">
+  <!-- three.js canvas is injected here by initAR -->
+  <div id="hud">…</div>
+</div>
+
+<!-- ❌ Wrong: HUD is a sibling — it vanishes once AR starts -->
+<div id="app"></div>
+<div id="hud">…</div>
+```
+
+```js
+await initAR(document.getElementById('app')!); // #app's subtree = the overlay root
+```
+
+A repo-meta guard (`tests/repo-config/hud-overlay-nesting.test.js`) asserts this
+structurally for every app's `index.html`, so a new app that authors its overlay
+as a sibling fails CI instead of failing silently in the field. Add new apps to
+that guard's `APP_OVERLAY_CONTRACTS` list.
+
+## Modules
+
+### `ar/` — WebXR & 3D Scene
 
-| 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) |
+WebXR session lifecycle, Three.js renderer setup, image/depth capture, replay scene management.
+
+| Export                                         | Description                                                                                                                                                                                                                                                             |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initAR(container, isolation?, features?)`     | Start a WebXR AR session with Three.js rendering. `features.requestHitTest` opts the session into the WebXR `hit-test` feature                                                                                                                                          |
+| `endARSession()`                               | End the active XR session                                                                                                                                                                                                                                               |
+| `createEnableGpsArController()`                | Headless "Enable GPS AR" orchestration (support check + permission bundling + sensor watches + `initAR`) with observable state; the app renders its own button over it                                                                                                  |
+| `registerXrFrameUpdate(cb)`                    | Per-frame access to the live `XRFrame` + reference space + session (valid only synchronously inside the callback). Enables app-side hit-test / other WebXR features                                                                                                     |
+| `isFullySupported(s)` / `capabilityMessage(s)` | WebXR + geolocation capability gating + a user-facing message                                                                                                                                                                                                           |
+| `startImageCapture()` / `stopImageCapture()`   | Toggle camera frame capture                                                                                                                                                                                                                                             |
+| `ImageCaptureManager`                          | Configurable camera frame capture pipeline                                                                                                                                                                                                                              |
+| `DepthSampler`                                 | Depth buffer sampling with configurable grids                                                                                                                                                                                                                           |
+| `CameraBlitCapture`                            | GPU blit-based camera capture                                                                                                                                                                                                                                           |
+| `initReplayScene(container)`                   | Create a 3D replay scene with orbit/FPS controls                                                                                                                                                                                                                        |
+| `applyChromiumProjectionLayerWorkaround`       | Chromium camera-access tab-crash workaround. Always deletes projection-layer hooks (forces `XRWebGLLayer`; required on every affected build incl. Chrome 150) and additionally persists `baseLayer` only on the affected Chrome window (148.0.7778.12 up to 149.0.7821) |
+
+### `sensors/` — GPS & Permissions
+
+| 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
+
+| 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
+
+| 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
+
+| 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 +393,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 +407,11 @@ 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 free community license key is bundled with the framework so you can start building right away — no signup or API key required. See the core library's EULA for the full 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 (trivial rung)
+- [`GpsPlusSlamJs_AnchorStarter`](../GpsPlusSlamJs_AnchorStarter/) — Meaningful-minimal starter: a persistent GPS anchor across reload (starter rung)
+- [`GpsPlusSlamJs_RecorderApp`](../GpsPlusSlamJs_RecorderApp/) — Full-featured recording app built on this framework

package/dist/accuracy-circles-DEKr0Hoh.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 };