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

package/dist/geo/index.js

@@ -0,0 +1,2 @@
+import { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index } from "./h3-proximity.js";
+export { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };

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

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

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

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

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

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

package/dist/gps-anchor-DjC_3MoT.js

@@ -0,0 +1,257 @@
+import { registerFrameUpdate } from "./ar/frame-loop.js";
+import { isObjectInCameraFrustum } from "./visualization/frustum-visibility.js";
+import { calcRelativeCoordsInMeters } from "./core/index.js";
+import * as THREE from "three";
+//#region ../src/visualization/frame-conversions.ts
+/**
+* `frame-conversions` — small, pure coordinate-frame helpers for the AR scene
+* graph. Currently a single function, `nueToArLocal`, that converts a
+* GPS-world NUE point into the AR-odometry local frame of `arWorldGroup`.
+*
+* Background: the scene root is GPS-world NUE; `arWorldGroup.matrix` IS the
+* alignment matrix, which maps **AR-odometry NUE → GPS-world NUE**. So a
+* direct child of `arWorldGroup` whose WORLD position must equal a GPS-world
+* point `nue` has to store `alignment⁻¹ · nue` as its LOCAL position —
+* writing raw `nue` double-applies the alignment. Getting this wrong was the
+* alignment-frame bug
+* (gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md);
+* this helper centralises the conversion behind one tested, well-named seam.
+*
+* Design (see the plan
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-nue-to-ar-local-helper-plan.md):
+*  - **Takes the explicit alignment matrix array**, NOT `Object3D.worldToLocal`.
+*    `worldToLocal` would read the live, mid-lerp `matrixWorld` and break
+*    replay determinism; the explicit target matrix keeps the result a pure
+*    function of its inputs. Full rationale in the review doc
+*    (gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-worldtolocal-frame-helper-review.md).
+*  - **Positions only.** No pose/quaternion variant exists until a caller
+*    needs one (YAGNI). No caller currently sets a GPS-world rotation.
+*/
+const scratchMatrix = new THREE.Matrix4();
+/**
+* Convert a GPS-world NUE point into the AR-local position to write into a
+* direct child of `arWorldGroup`, given the current alignment matrix.
+*
+* Computes `alignment⁻¹ · nue`. When the result is later composed back by the
+* group's matrix (the same `alignment`), the child's WORLD position equals
+* `nue` exactly.
+*
+* @param alignment - The alignment matrix as a 16-element **column-major**
+*   array (AR-odometry NUE → GPS-world NUE), e.g. from `getAlignmentMatrix()`
+*   or `THREE.Matrix4.toArray()`. Not mutated.
+* @param nue - The GPS-world NUE point `[north, up, east]` in metres. Not
+*   mutated.
+* @param out - Optional target vector to write into and return (pass a reused
+*   scratch to avoid allocation on hot paths). Defaults to a fresh
+*   `THREE.Vector3`.
+* @returns `out`, set to the AR-local position.
+*/
+function nueToArLocal(alignment, nue, out = new THREE.Vector3()) {
+	scratchMatrix.fromArray(alignment).invert();
+	return out.set(nue[0], nue[1], nue[2]).applyMatrix4(scratchMatrix);
+}
+//#endregion
+//#region ../src/visualization/gps-anchor.ts
+/**
+* `createGpsAnchor` — GPS-anchored placement of a single `THREE.Object3D`.
+*
+* See the colocated sidecar (`gps-anchor.ts.md`) and the port plan at
+* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-13-gps-anchor-port-plan.md`
+* for the full design, state machine, and test matrix.
+*
+* This file implements sub-steps 2 (bootstrap phase), 3 (steady-state
+* `'snap-every-tick'` + distance-scaled threshold gate), and 4
+* (`'snap-when-offscreen'` mode gate + alignment-matrix large-jump
+* bypass). Floor-Y correction is sub-step 6 and remains deferred.
+*/
+/**
+* Module-level registry of objects currently owned by a `GpsAnchor`.
+* Used to detect nested anchors (parent + child both anchored) which
+* we explicitly forbid; mirrors the C# invariant.
+*/
+const anchoredObjects = /* @__PURE__ */ new WeakSet();
+function isObjectInAnchoredChain(object) {
+	let cursor = object;
+	while (cursor) {
+		if (anchoredObjects.has(cursor)) return true;
+		cursor = cursor.parent;
+	}
+	return false;
+}
+function median(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2;
+	return sorted[mid];
+}
+function medianPoint(samples) {
+	const lat = median(samples.map((s) => s.lat));
+	const lon = median(samples.map((s) => s.lon));
+	const alts = samples.map((s) => "altitude" in s ? s.altitude : void 0).filter((a) => typeof a === "number");
+	if (alts.length > 0) return {
+		lat,
+		lon,
+		altitude: median(alts)
+	};
+	return {
+		lat,
+		lon
+	};
+}
+function createGpsAnchor(options) {
+	if (isObjectInAnchoredChain(options.object3D)) throw new Error("createGpsAnchor: nested GpsAnchors are not supported — the supplied object3D is already inside an anchored parent chain.");
+	anchoredObjects.add(options.object3D);
+	const sampleCount = options.secondsToAccumulateGpsPose ?? 7;
+	if (sampleCount < 1) {
+		anchoredObjects.delete(options.object3D);
+		throw new Error("createGpsAnchor: secondsToAccumulateGpsPose must be >= 1 — use skipBootstrap:true to bypass the accumulation phase.");
+	}
+	const settlingSeconds = options.settlingSeconds ?? 0;
+	const distanceThreshold = options.distanceThreshold ?? 2;
+	options.angleThresholdInDegrees;
+	const mode = options.mode ?? "snap-when-offscreen";
+	const LARGE_JUMP_TRANSLATION_M = 4;
+	const LARGE_JUMP_Y_M = 20;
+	const LARGE_JUMP_ROTATION_DEG = 2;
+	const scratchTarget = new THREE.Vector3();
+	const scratchCamWorld = new THREE.Vector3();
+	const scratchObjWorld = new THREE.Vector3();
+	const scratchPrevMatrix = new THREE.Matrix4();
+	const scratchCurrMatrix = new THREE.Matrix4();
+	const scratchPrevTrans = new THREE.Vector3();
+	const scratchCurrTrans = new THREE.Vector3();
+	const scratchPrevQuat = new THREE.Quaternion();
+	const scratchCurrQuat = new THREE.Quaternion();
+	let phase = options.skipBootstrap === true ? "anchored" : "bootstrap";
+	let isFullyAnchored = phase === "anchored";
+	let gpsPoint = options.gpsPoint;
+	let phaseEnteredAtElapsed = null;
+	let lastSampleAtElapsed = null;
+	const samples = [];
+	/**
+	* Snapshot of the previous tick's alignment matrix. `null` until the
+	* first steady-state tick in which `getAlignmentMatrix()` returned a
+	* non-null value. Used by the large-jump bypass to compare against
+	* the current tick's matrix.
+	*/
+	let prevAlignmentMatrix = null;
+	/**
+	* Returns true iff the alignment matrix has jumped by more than the
+	* configured large-jump thresholds between `prev` and `curr`. A
+	* `null` `prev` (first tick) is treated as "no jump".
+	*/
+	const detectLargeAlignmentJump = (prev, curr) => {
+		if (prev === null || curr === null) return false;
+		scratchPrevMatrix.fromArray(prev);
+		scratchCurrMatrix.fromArray(curr);
+		scratchPrevTrans.setFromMatrixPosition(scratchPrevMatrix);
+		scratchCurrTrans.setFromMatrixPosition(scratchCurrMatrix);
+		const dTrans = scratchPrevTrans.distanceTo(scratchCurrTrans);
+		const dY = Math.abs(scratchCurrTrans.y - scratchPrevTrans.y);
+		scratchPrevQuat.setFromRotationMatrix(scratchPrevMatrix);
+		scratchCurrQuat.setFromRotationMatrix(scratchCurrMatrix);
+		const dRotDeg = scratchPrevQuat.angleTo(scratchCurrQuat) * 180 / Math.PI;
+		return dTrans > LARGE_JUMP_TRANSLATION_M || dY > LARGE_JUMP_Y_M || dRotDeg > LARGE_JUMP_ROTATION_DEG;
+	};
+	const enterBootstrap = () => {
+		phase = "bootstrap";
+		isFullyAnchored = false;
+		phaseEnteredAtElapsed = null;
+		lastSampleAtElapsed = null;
+		samples.length = 0;
+		prevAlignmentMatrix = null;
+	};
+	const commitMedian = () => {
+		gpsPoint = medianPoint(samples);
+		phase = "anchored";
+		isFullyAnchored = true;
+		samples.length = 0;
+	};
+	/**
+	* Steady-state: compute the GPS-world NUE target from the stored
+	* `gpsPoint` and the current `zeroRef`, map it into `arWorldGroup`'s
+	* AR-local frame via the inverse alignment matrix, and commit it to
+	* `object3D.position` iff the (AR-local) position delta exceeds the
+	* distance-scaled threshold AND the mode gate (with optional large-jump
+	* bypass) allows it.
+	*
+	* Frame note: `arWorldGroup.matrix` IS the alignment matrix, which maps
+	* **AR-odometry NUE → GPS-world NUE**. `object3D.position` is a *local*
+	* transform in that AR-odometry frame. To make the object's *world*
+	* position equal the GPS-world `nue`, the local target must be
+	* `alignment⁻¹ · nue` — writing raw `nue` would double-apply the
+	* alignment (world = `alignment · nue`). See
+	* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md`.
+	*
+	* Returns silently on missing inputs (no `zeroRef`, or no alignment
+	* matrix yet — an AR-local object cannot be placed without knowing the
+	* AR↔NUE transform).
+	*/
+	const maybeCommitSteadyState = () => {
+		const zero = options.getGpsZeroRef();
+		if (zero === null || zero === void 0) return;
+		const currentAlignment = options.getAlignmentMatrix();
+		const largeJump = detectLargeAlignmentJump(prevAlignmentMatrix, currentAlignment);
+		prevAlignmentMatrix = currentAlignment;
+		if (currentAlignment === null || currentAlignment === void 0) return;
+		const targetAlt = "altitude" in gpsPoint && typeof gpsPoint.altitude === "number" ? gpsPoint.altitude : 0;
+		const nue = calcRelativeCoordsInMeters(zero, gpsPoint, targetAlt, 0);
+		nueToArLocal(currentAlignment, [
+			nue[0],
+			nue[1],
+			nue[2]
+		], scratchTarget);
+		options.camera.getWorldPosition(scratchCamWorld);
+		options.object3D.getWorldPosition(scratchObjWorld);
+		const scale = 1 + 10 * scratchCamWorld.distanceTo(scratchObjWorld) / 100;
+		if (options.object3D.position.distanceTo(scratchTarget) < distanceThreshold * scale) return;
+		if (mode === "snap-when-offscreen" && !largeJump) {
+			if (isObjectInCameraFrustum(options.camera, options.object3D)) return;
+		}
+		options.object3D.position.copy(scratchTarget);
+	};
+	const tick = (_dt, elapsed) => {
+		if (phase === "anchored") {
+			maybeCommitSteadyState();
+			return;
+		}
+		if (phaseEnteredAtElapsed === null) {
+			phaseEnteredAtElapsed = elapsed;
+			lastSampleAtElapsed = elapsed - 1;
+		}
+		if (elapsed - phaseEnteredAtElapsed < settlingSeconds) return;
+		if (lastSampleAtElapsed !== null && elapsed - lastSampleAtElapsed < 1) return;
+		const sample = options.getCurrentGpsPoint();
+		if (sample === null || sample === void 0) return;
+		samples.push(sample);
+		lastSampleAtElapsed = elapsed;
+		if (samples.length >= sampleCount) commitMedian();
+	};
+	const unregister = registerFrameUpdate(tick);
+	return {
+		get phase() {
+			return phase;
+		},
+		get isFullyAnchored() {
+			return isFullyAnchored;
+		},
+		get gpsPoint() {
+			return gpsPoint;
+		},
+		markMovedExternally() {
+			enterBootstrap();
+		},
+		setGpsPoint(point) {
+			gpsPoint = point;
+		},
+		dispose() {
+			unregister();
+			anchoredObjects.delete(options.object3D);
+		},
+		__tickForTests(dt, elapsed) {
+			tick(dt, elapsed);
+		}
+	};
+}
+//#endregion
+export { nueToArLocal as n, createGpsAnchor as t };

package/dist/gps-ar-pose-sampler-DsM1Kb2N.d.ts

@@ -0,0 +1,43 @@
+import { t as ARPose } from "./ar-types-Ck8LEq8k.js";
+import { Quaternion, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/state/gps-ar-pose-sampler.d.ts
+/**
+ * GPS coordinate captured at observation time. Loosely typed so the recorder
+ * can pass either a `RawGpsPoint` or a plain `{ latitude, longitude,
+ * altitude? }` shape from the fused-path computation.
+ */
+interface GpsAnchorSampleGpsPoint {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly altitude?: number;
+}
+/**
+ * A snapshot pairing the raw GPS reading, the optional fused GPS reading
+ * (computed when an alignment matrix is available), and the AR pose at the
+ * moment of capture. The `odomPosition` and `odomRotation` are pre-extracted
+ * from the AR pose for convenience — callers persisting the snapshot
+ * usually need them in tuple form.
+ */
+interface GpsAnchorSample {
+  readonly gpsPoint: GpsAnchorSampleGpsPoint;
+  readonly fusedGpsPoint?: GpsAnchorSampleGpsPoint;
+  readonly arPose: ARPose;
+  readonly odomPosition: Vector3;
+  readonly odomRotation: Quaternion;
+  readonly timestamp: number;
+}
+interface CaptureGpsAnchorSampleOptions {
+  /** Optional fused GPS point (computed elsewhere from the alignment matrix). */
+  readonly fusedGpsPoint?: GpsAnchorSampleGpsPoint;
+  /** Defaults to `Date.now()` at capture time. */
+  readonly timestamp?: number;
+}
+/**
+ * Capture a GPS-AR pose snapshot. Extracts `odomPosition`/`odomRotation`
+ * from the supplied `arPose`. The supplied `gpsPoint` and optional
+ * `fusedGpsPoint` are stored verbatim.
+ */
+declare function captureGpsAnchorSample(arPose: ARPose, gpsPoint: GpsAnchorSampleGpsPoint, options?: CaptureGpsAnchorSampleOptions): GpsAnchorSample;
+//#endregion
+export { captureGpsAnchorSample as i, GpsAnchorSample as n, GpsAnchorSampleGpsPoint as r, CaptureGpsAnchorSampleOptions as t };

package/dist/{recording-coordinator-DzflP07_.d.ts → gps-event-coordinator-DBx9I1YX.d.ts}

@@ -1,15 +1,16 @@
-import { t as ARPose } from "./ar-types-B-ORgk6Z.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-Ddzr2KlX.js";
-import { c as RecordGpsEventPayload, l as RecorderStore } from "./store-C7PKOj8S.js";
-import { Quaternion, RawGpsPoint, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
+import { t as ARPose } from "./ar-types-Ck8LEq8k.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-DXoQb9Kf.js";
+import { i as SlamAppStore } from "./create-slam-app-store-CNsZ3rcX.js";
+import { Quaternion, RawGpsPoint, RecordGpsEventPayload, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
+import { ReducersMapObject } from "@reduxjs/toolkit";
 
-//#region ../src/state/recording-coordinator.d.ts
+//#region ../src/state/gps-event-coordinator.d.ts
 /**
  * Configuration for the recording coordinator
  */
 interface RecordingCoordinatorConfig {
   /** Redux store to dispatch actions to */
-  store: RecorderStore;
+  store: SlamAppStore<ReducersMapObject>;
   /** Function to get current AR pose (from WebXR module) */
   getArPose: () => ARPose | null;
 }

package/dist/gps-event-markers-BGr-iLvi.d.ts

@@ -0,0 +1,103 @@
+import { LatLong, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/visualization/gps-event-markers.d.ts
+/**
+ * Optional GPS-accuracy hints used by {@link GpsEventVisualizer.addGpsEvent}
+ * to render the raw-GPS marker as a non-uniform-scaled ellipsoid.
+ *
+ * Both fields are optional — missing or non-positive values fall back to the
+ * legacy fixed 8 cm sphere (same defensive policy as `preview-map.ts`).
+ */
+interface GpsEventAccuracy {
+  /** Horizontal 1σ accuracy in metres (applied to both X and Z axes). */
+  horizontal?: number;
+  /** Vertical 1σ accuracy in metres (applied to the Y axis). */
+  vertical?: number;
+}
+/**
+ * Manager for GPS event visualization
+ */
+declare class GpsEventVisualizer {
+  private rawGpsMarkers;
+  private fusedMarkers;
+  private snapshotMarkers;
+  private zeroRef;
+  private eventCounter;
+  private snapshotCounter;
+  /**
+   * Set the GPS zero reference (origin for coordinate conversion).
+   * Must be called before adding GPS events.
+   *
+   * @param zero - GPS coordinates of the origin
+   */
+  setZeroRef(zero: LatLong): void;
+  /**
+   * Get the current zero reference
+   */
+  getZeroRef(): LatLong | null;
+  /**
+   * Add a GPS event to the visualization.
+   * Creates both a raw GPS marker and a fused alignment marker.
+   *
+   * @param gpsCoords - GPS position as [x, y, z] meters from zero reference
+   * @param odomPosition - AR odometry position at the time of GPS reading
+   * @param accuracy - Optional 1σ GPS accuracy. When both fields are positive,
+   *   the raw-GPS marker is rendered as a non-uniform-scaled ellipsoid:
+   *   `mesh.scale.set(horizontal, vertical, horizontal)` over a unit sphere.
+   *   When missing, zero, or negative, the marker falls back to the legacy
+   *   fixed 8 cm sphere (same defensive policy as `preview-map.ts`).
+   *   Cyan fused and red snapshot markers are never affected by this argument.
+   */
+  addGpsEvent(gpsCoords: Vector3, odomPosition: Vector3, accuracy?: GpsEventAccuracy): void;
+  /**
+   * Add an alignment snapshot marker at the given NUE position.
+   * Snapshots represent the system's best GPS estimate at each alignment update.
+   * Added to scene root (GPS world space), not arWorldGroup.
+   */
+  addAlignmentSnapshot(nuePosition: Vector3): void;
+  /**
+   * Get the NUE positions of all alignment snapshot markers.
+   * Used at session end to convert to GPS coordinates for the summary map.
+   */
+  getAlignmentSnapshotPositions(): Vector3[];
+  /**
+   * Create a sphere marker mesh with the given color and name.
+   */
+  private createMarkerMesh;
+  /**
+   * Clear all markers from the scene and reset state.
+   */
+  clearAll(): void;
+  /**
+   * Get count of visible markers.
+   */
+  getCounts(): {
+    raw: number;
+    fused: number;
+    snapshots: number;
+  };
+  /**
+   * Diagnostic accessor: returns the world-space size (`THREE.Box3.setFromObject`)
+   * of each raw-GPS marker, in insertion order.
+   *
+   * Used by the rec31 accuracy-ellipsoid Playwright spec (§3c) to verify the
+   * relative scaling of two events with different `latLongAccuracy`. This is
+   * the size of the rendered ellipsoid in scene units (= metres in replay
+   * mode), not the underlying geometry radius — so it correctly reflects the
+   * `mesh.scale.set(h, v, h)` applied for accuracy-aware markers.
+   *
+   * @returns array of `{ x, y, z }` sizes — empty array if there are no markers.
+   */
+  getRawMarkerWorldSizes(): Array<{
+    x: number;
+    y: number;
+    z: number;
+  }>;
+}
+/**
+ * Singleton instance for global use.
+ * Import this to visualize GPS events.
+ */
+declare const gpsEventVisualizer: GpsEventVisualizer;
+//#endregion
+export { GpsEventVisualizer as n, gpsEventVisualizer as r, GpsEventAccuracy as t };

package/dist/{h3-ref-point-CFhayNSZ.d.ts → h3-proximity-BhfgNbdW.d.ts}

@@ -1,21 +1,25 @@
-//#region ../src/ref-points/h3-ref-point.d.ts
+//#region ../src/geo/h3-proximity.d.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 */
 declare const H3_RESOLUTION = 11;
 /**
- * A known reference point with its H3 cell index and GPS coordinates,
+ * A known geo-anchored point with its H3 cell index and GPS coordinates,
  * used for proximity matching. GPS coordinates are needed to rank
  * multiple candidates by distance when their gridDisk zones overlap.
  */
-interface KnownRefPoint {
+interface KnownGeoAnchor {
   readonly h3Index: string;
   readonly displayName?: string;
   readonly lat: number;
@@ -33,27 +37,27 @@ declare function gpsToH3(lat: number, lng: number): string;
  */
 declare function approxDistanceMetres(lat1: number, lon1: number, lat2: number, lon2: number): number;
 /**
- * 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.
  */
-declare function findNearbyRefPoint(lat: number, lng: number, knownRefPoints: readonly KnownRefPoint[]): KnownRefPoint | undefined;
+declare function findNearbyGeoAnchor(lat: number, lng: number, knownAnchors: readonly KnownGeoAnchor[]): KnownGeoAnchor | undefined;
 /**
  * Check whether two H3 indices refer to the same physical location
  * (i.e., one falls within the other's gridDisk safe zone).
  * This is the canonical cross-session matching check.
  */
-declare function h3RefsMatch(h3a: string, h3b: string): boolean;
+declare function h3CellsMatch(h3a: string, h3b: string): boolean;
 /**
  * Check whether a string looks like a valid H3 resolution-11 index.
  * Used to distinguish H3 IDs from legacy user-typed string IDs.
  */
 declare function isH3Index(id: string): boolean;
 //#endregion
-export { gpsToH3 as a, findNearbyRefPoint as i, KnownRefPoint as n, h3RefsMatch as o, approxDistanceMetres as r, isH3Index as s, H3_RESOLUTION as t };
+export { gpsToH3 as a, findNearbyGeoAnchor as i, KnownGeoAnchor as n, h3CellsMatch as o, approxDistanceMetres as r, isH3Index as s, H3_RESOLUTION as t };

package/dist/{image-capture-2pKjYUS6.d.ts → image-capture-DZLxHDN9.d.ts}

@@ -1,4 +1,4 @@
-import { a as WebXRQuaternion, o as WebXRVec3, t as ARPose } from "./ar-types-B-ORgk6Z.js";
+import { a as WebXRQuaternion, o as WebXRVec3, t as ARPose } from "./ar-types-Ck8LEq8k.js";
 
 //#region ../src/ar/image-capture.d.ts
 /**

package/dist/index-gzWJMVpo.d.ts

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

package/dist/index-pOjUCKEP.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from "three";
+
+//#region ../src/visualization/frame-conversions.d.ts
+/**
+ * Convert a GPS-world NUE point into the AR-local position to write into a
+ * direct child of `arWorldGroup`, given the current alignment matrix.
+ *
+ * Computes `alignment⁻¹ · nue`. When the result is later composed back by the
+ * group's matrix (the same `alignment`), the child's WORLD position equals
+ * `nue` exactly.
+ *
+ * @param alignment - The alignment matrix as a 16-element **column-major**
+ *   array (AR-odometry NUE → GPS-world NUE), e.g. from `getAlignmentMatrix()`
+ *   or `THREE.Matrix4.toArray()`. Not mutated.
+ * @param nue - The GPS-world NUE point `[north, up, east]` in metres. Not
+ *   mutated.
+ * @param out - Optional target vector to write into and return (pass a reused
+ *   scratch to avoid allocation on hot paths). Defaults to a fresh
+ *   `THREE.Vector3`.
+ * @returns `out`, set to the AR-local position.
+ */
+declare function nueToArLocal(alignment: readonly number[], nue: readonly [number, number, number], out?: THREE.Vector3): THREE.Vector3;
+//#endregion
+export { nueToArLocal as t };