gps-plus-slam-app-framework 1.7.0 → 1.9.0

package/dist/leaflet-map-overlay-CBWPvaX9.js

@@ -0,0 +1,452 @@
+import { createLogger } from "./utils/logger.js";
+import { clampedAlpha, lerpAngleDeg } from "./visualization/lerp-utils.js";
+import { VIS_COLORS } from "./visualization/vis-colors.js";
+import { drawMapData } from "./visualization/map-overlay-draw.js";
+import { quat } from "gl-matrix";
+import { CSS3DObject } from "three/addons/renderers/CSS3DRenderer.js";
+import L from "leaflet";
+//#region ../src/visualization/heading-up-rotation.ts
+/**
+* Heading-up minimap rotation helper.
+*
+* The live in-AR minimap is a Leaflet map wrapped in a three.js `CSS3DObject`
+* lying flat below the camera. Its baseline orientation is a single −π/2
+* rotation about the local +X axis (`tilt`), which lays the DOM plane flat so
+* the user looks down on a NORTH-UP map (its plane normal points world +Y).
+*
+* "Heading-up" mode spins that flat map in its own plane so the user's view
+* direction always points up/forward. We do this by composing a yaw about the
+* world up axis (+Y) with the baseline tilt:
+*
+*     quaternion = yaw(−headingDeg about +Y) · tilt(−π/2 about +X)
+*
+* Because the yaw is about +Y and the tilted plane's normal is already +Y, the
+* normal is invariant under the yaw — the map stays flat and merely rotates
+* in-plane. The map's parent (`CameraFollower`) is rotation-identity, so the
+* object-local axes equal world axes; the yaw is therefore about true world up.
+*
+* Sign: the *magnitude* and *axis* of the rotation are pinned by
+* `heading-up-rotation.test.ts`; the *perceived* turn direction was
+* device-verified correct with `YAW_SIGN = -1` (2026-06-29, see
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-29-heading-up-minimap-rotation-plan.md).
+* `YAW_SIGN` remains the one place to flip if a future frame/convention change
+* ever inverts it.
+*/
+/** Baseline tilt: −π/2 about +X (lays the map flat, normal → world +Y). */
+const TILT_X_RAD = -Math.PI / 2;
+/**
+* Sign of the yaw applied for a positive (clockwise-from-north) heading.
+* Isolated as the single knob the on-device sign check would flip.
+*/
+const YAW_SIGN = -1;
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+const TILT = quat.setAxisAngle(quat.create(), [
+	1,
+	0,
+	0
+], TILT_X_RAD);
+/** World-up yaw axis, hoisted so the per-frame call allocates nothing
+*  (`setAxisAngle` only reads it). */
+const UP_AXIS = [
+	0,
+	1,
+	0
+];
+const _yaw = quat.create();
+const _out = quat.create();
+/**
+* Quaternion (`[x, y, z, w]`) for the `CSS3DObject`: the baseline −π/2 tilt plus
+* an in-plane yaw of `azimuthDeg` about world-up.
+*
+* `azimuthDeg` is the yaw to apply, NOT a heading: the consumer passes
+* `viewAzimuth(camera) − userHeading` (camera-relative — see the file header and
+* `viewAzimuthDeg`). `azimuthDeg = 0` returns the baseline tilt-only orientation
+* (north-up); the map's north edge ends up pointing along scene azimuth
+* `azimuthDeg` (atan2(x, −z) convention).
+*
+* @param azimuthDeg In-plane yaw to apply, degrees, atan2(x, −z) convention.
+* @returns A unit quaternion as a 4-tuple `[x, y, z, w]`.
+*/
+function headingUpQuat(azimuthDeg) {
+	quat.setAxisAngle(_yaw, UP_AXIS, YAW_SIGN * azimuthDeg * DEG_TO_RAD);
+	quat.multiply(_out, _yaw, TILT);
+	return [
+		_out[0],
+		_out[1],
+		_out[2],
+		_out[3]
+	];
+}
+/**
+* Azimuth (degrees clockwise, `[0, 360)`) that the camera is looking, measured
+* in the same scene frame and convention as {@link headingUpQuat}'s input
+* (0° = looking along world −Z, +90° = looking along world +X).
+*
+* Why this is needed for heading-up: the minimap is world-locked (its parent is
+* rotation-identity) but it is composited through the **live head-tracked
+* camera**, so the camera already rotates the map's on-screen appearance as the
+* user turns. The map's local heading-up yaw must therefore be expressed
+* RELATIVE to the camera, not in absolute GPS-north terms — otherwise the
+* camera's rotation is double-counted and the result is only correct at a single
+* heading (the difference being the GPS↔scene alignment yaw). The consumer rolls
+* the alignment offset out by feeding `headingUpQuat(viewAzimuth − userHeading)`.
+*
+* @param matrixWorldElements The camera's `matrixWorld.elements` (column-major).
+*   The camera looks down its local −Z, so world-forward = −(3rd column).
+* @returns The camera's horizontal viewing azimuth in `[0, 360)` degrees.
+*/
+function viewAzimuthDeg(matrixWorldElements) {
+	const m8 = matrixWorldElements[8] ?? 0;
+	const m10 = matrixWorldElements[10] ?? 0;
+	return (Math.atan2(-m8, m10) * RAD_TO_DEG % 360 + 360) % 360;
+}
+//#endregion
+//#region ../src/visualization/leaflet-map-overlay.ts
+const log = createLogger("LeafletMapOverlay");
+/** Default pixel size of the Leaflet map container */
+const DEFAULT_LEAFLET_MAP_SIZE_PX = 600;
+/**
+* Diameter (px) of the ref-point markers on the in-AR minimap.
+*
+* Enlarged 12 → 20 px (F5-A, 2026-06-16 user feedback): the field tester
+* reported the minimap "showed the user but not the marker". The markers WERE
+* rendered — they were just too small to notice on the small CSS3D minimap. A
+* bigger dot plus a thicker white halo and a drop shadow makes them the most
+* prominent feature on the minimap (the user-position marker stays 14 px).
+*/
+const REF_POINT_MARKER_SIZE_PX = 20;
+/**
+* Map-plane placement defaults (re-fit 2026-07-04, F1 user feedback).
+*
+* The plane's parent is the CameraFollower — camera POSITION is followed,
+* rotation stays IDENTITY (GPS-world-aligned). CSS3D content crossing the
+* viewer plane (camera-space z ≥ 0) is cut off by the browser (an effective
+* near plane at 0 that camera.near cannot move), so the defaults must keep
+* every plane corner in front of the viewer plane for ALL camera yaws and
+* heading-up rotations at map-viewing pitches. Invariant (tests pin it):
+*
+*   |DEFAULT_Z_OFFSET| + DEFAULT_WORLD_SIZE/√2 + lag ≤ |h|·tan(θ*)
+*
+* with lag = 0.5 m (follower lerp) and design pitch θ* = 51°. Below θ* only
+* the region farther than |h|·tan(pitch) behind the camera is cut, shrinking
+* to nothing at θ*. Values 8 / −5 / 0 give θ* ≈ 51°; zOffset MUST stay 0 —
+* with a world-yaw-locked parent a non-zero offset is a fixed compass
+* direction, not "ahead of the user".
+*/
+/** Default world-space size in meters */
+const DEFAULT_WORLD_SIZE = 8;
+/** Default height offset below camera (negative = below) */
+const DEFAULT_HEIGHT_OFFSET = -5;
+/** Default offset from parent along world Z (keep 0 — see block comment) */
+const DEFAULT_Z_OFFSET = 0;
+/** Default zoom level for the Leaflet map */
+const DEFAULT_ZOOM = 17;
+/** Minimum allowed zoom level */
+const MIN_ZOOM = 0;
+/** Maximum allowed zoom level */
+const MAX_ZOOM = 19;
+var LeafletMapOverlay = class {
+	scene;
+	camera;
+	mapParent;
+	worldSize;
+	heightOffset;
+	mapSizePx;
+	tileServerUrl;
+	onTileError;
+	offscreenRoot;
+	zoomLevel;
+	gpsPosition = null;
+	visible = false;
+	headingUp;
+	targetHeadingDeg = null;
+	currentHeadingDeg = null;
+	mapContainer = null;
+	leafletMap = null;
+	tileLayer = null;
+	cssObject = null;
+	latestMapData = null;
+	trajectoryLayers = [];
+	namedMarkers = [];
+	constructor(scene, camera, options = {}) {
+		this.scene = scene;
+		this.camera = camera;
+		this.mapParent = options.mapParent ?? camera;
+		this.worldSize = options.worldSize ?? 8;
+		this.heightOffset = options.heightOffset ?? -5;
+		this.mapSizePx = options.mapSizePx ?? 600;
+		this.zoomLevel = options.zoomLevel ?? 17;
+		this.tileServerUrl = options.tileServerUrl ?? "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
+		this.onTileError = options.onTileError;
+		this.offscreenRoot = options.offscreenRoot ?? document.body;
+		this.headingUp = options.headingUp ?? false;
+	}
+	setGpsPosition(lat, lon) {
+		this.gpsPosition = {
+			lat,
+			lon
+		};
+		if (this.leafletMap) this.leafletMap.setView([lat, lon], this.zoomLevel);
+	}
+	getGpsPosition() {
+		return this.gpsPosition;
+	}
+	show() {
+		if (!this.gpsPosition) {
+			log.warn("Cannot show map — no GPS position set");
+			return;
+		}
+		if (this.visible) return;
+		this.createLeafletMap();
+		this.createCssObject();
+		this.applyBufferedOverlays();
+		this.visible = true;
+		log.info("Leaflet map overlay shown");
+	}
+	hide() {
+		if (!this.visible) return;
+		this.removeCssObject();
+		this.visible = false;
+		log.info("Leaflet map overlay hidden");
+	}
+	toggle() {
+		if (this.visible) this.hide();
+		else this.show();
+	}
+	isVisible() {
+		return this.visible;
+	}
+	/**
+	* Render a full trajectory snapshot.
+	*
+	* Replaces the previous incremental `addRawGpsPoint` / `addFusedPoint` /
+	* `addAlignmentSnapshot` API with a single full-snapshot path: the caller
+	* builds a {@link MapData} (via the shared `buildMapData`) from the latest
+	* store slices and hands it here. The trajectory layers are redrawn
+	* wholesale through the shared {@link drawMapData} routine, so the live map
+	* stays pixel-identical to the 2D session-summary map and the fused path
+	* recomputes (D2) as the alignment matrix improves.
+	*
+	* Buffered when the map is not yet shown; applied on `show()`.
+	*/
+	render(data) {
+		this.latestMapData = data;
+		this.targetHeadingDeg = typeof data.userHeadingDeg === "number" && Number.isFinite(data.userHeadingDeg) ? data.userHeadingDeg : null;
+		if (this.leafletMap) this.drawTrajectory();
+	}
+	/** Add a "current" named marker (red). Buffered if map is not yet shown. */
+	addCurrentMarker(lat, lon, name) {
+		const marker = this.leafletMap ? this.createNamedMarker(lat, lon, name, false) : null;
+		this.namedMarkers.push({
+			lat,
+			lng: lon,
+			name,
+			isPrior: false,
+			marker
+		});
+	}
+	/** Add a "prior" named marker (green, decorated). Buffered if not shown. */
+	addPriorMarker(lat, lon, name) {
+		const marker = this.leafletMap ? this.createNamedMarker(lat, lon, name, true) : null;
+		this.namedMarkers.push({
+			lat,
+			lng: lon,
+			name,
+			isPrior: true,
+			marker
+		});
+	}
+	/** Bulk add prior markers. */
+	addPriorMarkers(markers) {
+		for (const m of markers) this.addPriorMarker(m.lat, m.lon, m.name);
+	}
+	/** Remove all prior markers; current markers are unaffected. */
+	clearPriorMarkers() {
+		this.namedMarkers = this.namedMarkers.filter((m) => {
+			if (m.isPrior) {
+				m.marker?.remove();
+				return false;
+			}
+			return true;
+		});
+	}
+	setZoomLevel(zoom) {
+		this.zoomLevel = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, zoom));
+		if (this.leafletMap) this.leafletMap.setZoom(this.zoomLevel);
+	}
+	getZoomLevel() {
+		return this.zoomLevel;
+	}
+	/** Increment zoom level by 1 (clamped at MAX_ZOOM). */
+	zoomIn() {
+		this.setZoomLevel(this.zoomLevel + 1);
+	}
+	/** Decrement zoom level by 1 (clamped at MIN_ZOOM). */
+	zoomOut() {
+		this.setZoomLevel(this.zoomLevel - 1);
+	}
+	getWorldSize() {
+		return this.worldSize;
+	}
+	getHeightOffset() {
+		return this.heightOffset;
+	}
+	getMapSizePx() {
+		return this.mapSizePx;
+	}
+	/** Expose the Leaflet map instance for testing and advanced usage. */
+	getLeafletMap() {
+		return this.leafletMap;
+	}
+	/**
+	* Enable/disable heading-up rotation at runtime (e.g. from a settings flag
+	* read at Enter-AR). When disabled, the map snaps back to the north-up
+	* baseline immediately. Position follows the parent via the scene graph, so
+	* this only governs the in-plane yaw.
+	*/
+	setHeadingUpEnabled(enabled) {
+		this.headingUp = enabled;
+		if (!enabled) {
+			this.currentHeadingDeg = null;
+			this.cssObject?.rotation.set(-Math.PI / 2, 0, 0);
+		}
+	}
+	/** Whether heading-up rotation is currently enabled. */
+	isHeadingUpEnabled() {
+		return this.headingUp;
+	}
+	/**
+	* Per-frame update driving the heading-up rotation. Positioning is handled by
+	* Three.js scene-graph propagation (the CSS3DObject is a child of the parent),
+	* so this only sets the in-plane yaw.
+	*
+	* The minimap is world-locked but composited through the **live head-tracked
+	* camera**, so the camera already rotates the map's on-screen appearance as
+	* the user turns. The local yaw must therefore be expressed RELATIVE to the
+	* camera — `headingUpQuat(viewAzimuth − userHeading)` — otherwise the camera's
+	* rotation is double-counted and the GPS↔scene alignment offset leaks in (the
+	* map then only points forward at a single heading). `userHeading` is smoothed
+	* toward the latest ~1 Hz target; `viewAzimuth` is read live from the camera
+	* each frame so the projection cancels exactly (no lag).
+	*
+	* A no-op when heading-up is disabled, the map is not shown, the camera is
+	* absent, or the heading is undefined (the last orientation is held).
+	*
+	* @param dtSeconds Seconds since the previous frame (drives heading smoothing).
+	* @param camera The live render camera (the same one compositing the CSS3D
+	*   overlay). Required for heading-up; omitted callers leave the map as-is.
+	*/
+	updatePosition(dtSeconds = 0, camera) {
+		if (!this.headingUp || !this.visible || !this.cssObject || !camera) return;
+		const target = this.targetHeadingDeg;
+		if (target === null) return;
+		if (this.currentHeadingDeg === null) this.currentHeadingDeg = target;
+		else {
+			const alpha = clampedAlpha(8, dtSeconds);
+			this.currentHeadingDeg = lerpAngleDeg(this.currentHeadingDeg, target, alpha);
+		}
+		camera.updateMatrixWorld();
+		const viewAz = viewAzimuthDeg(camera.matrixWorld.elements);
+		this.cssObject.quaternion.set(...headingUpQuat(viewAz - this.currentHeadingDeg));
+	}
+	dispose() {
+		this.hide();
+		this.destroyLeafletMap();
+		this.latestMapData = null;
+		this.trajectoryLayers = [];
+		this.namedMarkers = [];
+		this.targetHeadingDeg = null;
+		this.currentHeadingDeg = null;
+		this.cssObject = null;
+		log.info("Leaflet map overlay disposed");
+	}
+	createLeafletMap() {
+		if (this.leafletMap) return;
+		this.mapContainer = document.createElement("div");
+		this.mapContainer.style.width = `${this.mapSizePx}px`;
+		this.mapContainer.style.height = `${this.mapSizePx}px`;
+		this.mapContainer.style.background = "white";
+		this.mapContainer.style.position = "fixed";
+		this.mapContainer.style.left = "-9999px";
+		this.mapContainer.style.top = "-9999px";
+		this.mapContainer.style.pointerEvents = "none";
+		this.offscreenRoot.appendChild(this.mapContainer);
+		const pos = this.gpsPosition;
+		this.leafletMap = L.map(this.mapContainer, {
+			center: [pos.lat, pos.lon],
+			zoom: this.zoomLevel,
+			zoomControl: false,
+			attributionControl: false
+		});
+		this.tileLayer = L.tileLayer(this.tileServerUrl, { maxZoom: MAX_ZOOM });
+		this.tileLayer.on("tileerror", (e) => {
+			log.error("Failed to load map tile:", e.error);
+			this.onTileError?.(e.error);
+		});
+		this.tileLayer.addTo(this.leafletMap);
+	}
+	destroyLeafletMap() {
+		for (const layer of this.trajectoryLayers) layer.remove();
+		this.trajectoryLayers = [];
+		for (const m of this.namedMarkers) {
+			m.marker?.remove();
+			m.marker = null;
+		}
+		if (this.leafletMap) {
+			this.leafletMap.remove();
+			this.leafletMap = null;
+		}
+		if (this.mapContainer?.parentElement) this.mapContainer.parentElement.removeChild(this.mapContainer);
+		this.mapContainer = null;
+		this.tileLayer = null;
+	}
+	createCssObject() {
+		if (!this.mapContainer) return;
+		if (this.cssObject) {
+			this.mapParent.add(this.cssObject);
+			return;
+		}
+		this.mapContainer.style.position = "";
+		this.mapContainer.style.left = "";
+		this.mapContainer.style.top = "";
+		this.cssObject = new CSS3DObject(this.mapContainer);
+		const scale = this.worldSize / this.mapSizePx;
+		this.cssObject.scale.set(scale, scale, scale);
+		this.cssObject.position.set(0, this.heightOffset, 0);
+		this.cssObject.rotation.x = -Math.PI / 2;
+		this.mapParent.add(this.cssObject);
+	}
+	removeCssObject() {
+		if (this.cssObject) this.mapParent.remove(this.cssObject);
+	}
+	applyBufferedOverlays() {
+		if (!this.leafletMap) return;
+		this.drawTrajectory();
+		for (const m of this.namedMarkers) if (!m.marker) m.marker = this.createNamedMarker(m.lat, m.lng, m.name, m.isPrior);
+	}
+	/**
+	* Redraw the trajectory layers from {@link latestMapData} via the shared
+	* {@link drawMapData} routine, removing any layers from the previous draw.
+	*/
+	drawTrajectory() {
+		if (!this.leafletMap || !this.latestMapData) return;
+		for (const layer of this.trajectoryLayers) layer.remove();
+		this.trajectoryLayers = drawMapData(this.leafletMap, this.latestMapData, { showUserPosition: true }).layers;
+	}
+	createNamedMarker(lat, lon, name, isPrior) {
+		const color = isPrior ? VIS_COLORS.PRIOR_REF_POINT.css : VIS_COLORS.CURRENT_REF_POINT.css;
+		const opacity = isPrior ? "opacity:0.8;" : "";
+		const label = isPrior ? `📌 ${name} (prior)` : name;
+		const size = REF_POINT_MARKER_SIZE_PX;
+		const anchor = size / 2;
+		return L.marker([lat, lon], { icon: L.divIcon({
+			className: "",
+			html: `<div style="background:${color};width:${size}px;height:${size}px;border-radius:50%;border:3px solid white;box-shadow:0 0 4px rgba(0,0,0,0.7);${opacity}"></div>`,
+			iconSize: [size, size],
+			iconAnchor: [anchor, anchor]
+		}) }).bindPopup(label).addTo(this.leafletMap);
+	}
+};
+//#endregion
+export { DEFAULT_Z_OFFSET as a, DEFAULT_ZOOM as i, DEFAULT_LEAFLET_MAP_SIZE_PX as n, LeafletMapOverlay as o, DEFAULT_WORLD_SIZE as r, DEFAULT_HEIGHT_OFFSET as t };

package/dist/lerp-utils-Qs8OhumS.d.ts

@@ -0,0 +1,42 @@
+//#region ../src/visualization/lerp-utils.d.ts
+/**
+ * Shared lerp utilities for visualization modules.
+ *
+ * Both alignment-lerper and camera-follower need the same smoothing
+ * rate constant and clamped-alpha formula. Centralised here (R3) to
+ * keep the two modules in sync.
+ */
+/** Default speed multiplier — ~90 % convergence in ~0.3 s at 60 fps. */
+declare const DEFAULT_LERP_RATE = 8;
+/**
+ * Compute a frame-rate-independent lerp/slerp factor clamped to [0, 1].
+ *
+ * Both bounds are clamped: the upper bound caps an overlong frame at a full
+ * (instant) step, and the lower bound rejects a negative `dt` (system clock
+ * adjustment, a frame loop whose timestamp runs backward, or a paused-then-
+ * resumed tab). Without the lower clamp a negative `dt` would yield a negative
+ * alpha and the angle/quaternion lerp would extrapolate BACKWARD, away from the
+ * target — a visible heading/alignment jump.
+ *
+ * @param lerpRate Speed multiplier (higher = faster convergence).
+ * @param dt       Delta time in seconds since last frame.
+ * @returns The interpolation alpha, guaranteed within [0, 1].
+ */
+declare function clampedAlpha(lerpRate: number, dt: number): number;
+/**
+ * Interpolate between two angles (degrees) along the SHORTEST arc.
+ *
+ * Used by the heading-up minimap to smooth the map's yaw toward a ~1 Hz target
+ * heading every frame without spinning the long way across the 0°/360° seam
+ * (e.g. 350° → 10° goes +20° through 0°, not −340° through 180°).
+ *
+ * @param current Current angle in degrees (any range; normalized internally).
+ * @param target  Target angle in degrees (any range).
+ * @param alpha   Interpolation factor — 0 returns `current`, 1 returns `target`.
+ *                Values outside [0, 1] extrapolate; callers should clamp (see
+ *                {@link clampedAlpha}).
+ * @returns The interpolated angle normalized to `[0, 360)`.
+ */
+declare function lerpAngleDeg(current: number, target: number, alpha: number): number;
+//#endregion
+export { clampedAlpha as n, lerpAngleDeg as r, DEFAULT_LERP_RATE as t };

package/dist/map-data-1tF5gcYV.js

@@ -0,0 +1,124 @@
+import { computeFusedPath } from "./utils/fused-path.js";
+import { vec3 } from "gl-matrix";
+//#region ../src/utils/user-heading.ts
+/**
+* True-north user-heading kernel.
+*
+* Turns the latest AR camera rotation into an absolute compass bearing (degrees
+* clockwise from geographic North) so the live/replay map overlay can draw a
+* thin view-direction line from the user-position dot. See Finding 2 of
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-28-map-rings-transparency-and-view-direction-user-feedback.md.
+*
+* Why this lives in the app-framework (NOT the library's `orientation-heading.ts`):
+* that library module is the MAGNETIC path — its bearings come from the
+* AbsoluteOrientationSensor's device→ENU quaternion and are explicitly magnetic
+* (they need WMM declination correction). Finding 2's locked source is the
+* GPS+SLAM **alignment matrix → true geographic north**, which rejects the
+* magnetic sensor. So the math belongs here, alongside `fused-path.ts`, which
+* already converts AR odometry through the same alignment matrix.
+*
+* Frame algebra (pinned by `user-heading.test.ts`):
+* - State stores odometry rotations as NUE quaternions
+*   (`webxrQuaternionToNUE(odomRotation)` in the library reducer). NUE means
+*   X=North, Y=Up, Z=East.
+* - A WebXR camera looks down its own −Z. The basis-change `webxrToNUE` maps
+*   that local forward `[0,0,-1]` to `[1,0,0]`, so the camera-forward basis
+*   vector in the NUE-AR frame is **[1, 0, 0]** (an identity camera looks North).
+* - The alignment matrix maps AR-NUE → world NUE metres (same matrix
+*   `computeFusedPath` applies to positions). Rotating the forward direction by
+*   it yields a world-NUE direction; the geographic bearing is
+*   `atan2(East, North)`.
+*
+* We rotate the *direction* and read the bearing directly rather than
+* round-tripping two points through `calcGpsCoords`: lat/lon scale North and
+* East by different metres-per-degree, so a naive GPS-coord bearing would be
+* anisotropically distorted. The aligned NUE metres already carry the true
+* bearing, so `atan2(East, North)` is both simpler and undistorted.
+*/
+/** Camera-forward basis vector in the NUE-AR frame: `webxrToNUE([0,0,-1]) = [1,0,0]`. */
+const NUE_CAMERA_FORWARD = [
+	1,
+	0,
+	0
+];
+/**
+* Minimum horizontal fraction of the (unit) forward direction below which the
+* heading is treated as undefined. Because `horiz/len = sin(angle from
+* vertical)`, `horiz/len < GUARD` means the camera points within
+* `asin(0.08) ≈ 4.6°` of straight up/down (equivalently, pitched more than ~85°
+* from horizontal), where a 2D map bearing is meaningless and jittery. Mirrors
+* the rationale of the library's `VERTICAL_GUARD` (0.08).
+*/
+const VERTICAL_GUARD = .08;
+const RAD_TO_DEG = 180 / Math.PI;
+const _forward = vec3.create();
+const _origin = vec3.create();
+const _tip = vec3.create();
+const _dir = vec3.create();
+/**
+* Compute the user's absolute view-direction bearing in degrees clockwise from
+* geographic North, in `[0, 360)`, or `null` when undefined.
+*
+* Returns `null` when there is no rotation yet, no alignment matrix yet, or the
+* camera points near-vertically (see {@link VERTICAL_GUARD}). Position is NOT
+* required — the bearing is a pure direction; the consumer only draws the line
+* when it also has a user-position dot to anchor it to.
+*/
+function computeUserHeadingDeg(input) {
+	const { odometryRotation, alignmentMatrix } = input;
+	if (!odometryRotation || !alignmentMatrix) return null;
+	vec3.transformQuat(_forward, NUE_CAMERA_FORWARD, odometryRotation);
+	vec3.set(_origin, 0, 0, 0);
+	vec3.transformMat4(_origin, _origin, alignmentMatrix);
+	vec3.transformMat4(_tip, _forward, alignmentMatrix);
+	vec3.subtract(_dir, _tip, _origin);
+	const north = _dir[0];
+	const east = _dir[2];
+	const len = Math.hypot(_dir[0], _dir[1], _dir[2]);
+	const horiz = Math.hypot(north, east);
+	if (!Number.isFinite(len) || !Number.isFinite(horiz) || len < 1e-9 || horiz / len < VERTICAL_GUARD) return null;
+	return (Math.atan2(east, north) * RAD_TO_DEG % 360 + 360) % 360;
+}
+//#endregion
+//#region ../src/visualization/map-data.ts
+/**
+* Build a {@link MapData} snapshot from store-derived inputs.
+*
+* Pure and free of Leaflet/Three dependencies. The fused path is always
+* derived via {@link computeFusedPath} (D2); when the matrix or zero reference
+* is missing it is an empty array.
+*
+* @param input - Optional trajectory slices (see {@link MapDataInput}).
+* @returns A fully-resolved {@link MapData} with all arrays defensively copied.
+*/
+function buildMapData(input) {
+	const rawGpsPath = input.rawGpsPath ? [...input.rawGpsPath] : [];
+	const alignmentSnapshots = input.alignmentSnapshots ? [...input.alignmentSnapshots] : [];
+	const fusedPath = computeFusedPath({
+		odometryPositions: input.odometryPositions ?? [],
+		alignmentMatrix: input.alignmentMatrix ?? null,
+		zeroRef: input.zeroRef ?? null
+	});
+	const lastFused = fusedPath[fusedPath.length - 1];
+	const lastRaw = rawGpsPath[rawGpsPath.length - 1];
+	const userPosition = input.userPosition !== void 0 ? input.userPosition : lastFused ? {
+		lat: lastFused.lat,
+		lng: lastFused.lng
+	} : lastRaw ? {
+		lat: lastRaw.lat,
+		lng: lastRaw.lng
+	} : null;
+	const rotations = input.odometryRotations ?? [];
+	return {
+		userPosition,
+		rawGpsPath,
+		fusedPath,
+		alignmentSnapshots,
+		userHeadingDeg: computeUserHeadingDeg({
+			odometryRotation: rotations[rotations.length - 1] ?? null,
+			alignmentMatrix: input.alignmentMatrix ?? null
+		})
+	};
+}
+//#endregion
+export { buildMapData as t };

package/dist/map-data-CUnTzRIC.d.ts

@@ -0,0 +1,78 @@
+import { n as RawGpsSample, t as GpsCoord } from "./geo-types-DrGVu8nS.js";
+import { LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/visualization/map-data.d.ts
+/** Fully-resolved trajectory data ready to be drawn onto a Leaflet map. */
+interface MapData {
+  /**
+   * User position for the blue dot, or null when unknown/hidden. Unless the
+   * caller provided an explicit value, this is the latest FUSED pose
+   * (GPS-converted tip of `fusedPath`), so the dot keeps moving indoors where
+   * the raw fix freezes; the last raw GPS fix is only the pre-alignment
+   * fallback. See
+   * gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-07-06-recorder-live-map-user-dot-fused-pose-user-feedback.md.
+   */
+  userPosition: GpsCoord | null;
+  /** Raw GPS samples (yellow polyline + per-event accuracy circles). */
+  rawGpsPath: RawGpsSample[];
+  /** Fused SLAM+GPS positions (cyan polyline), recomputed from latest matrix. */
+  fusedPath: GpsCoord[];
+  /** Alignment-snapshot GPS positions (red). */
+  alignmentSnapshots: GpsCoord[];
+  /**
+   * Absolute view-direction bearing (degrees clockwise from true geographic
+   * north, `[0, 360)`) for the user-position heading line, or null when
+   * undefined (no rotation/alignment yet, or camera near-vertical). See
+   * Finding 2 of
+   * gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-28-map-rings-transparency-and-view-direction-user-feedback.md.
+   *
+   * Optional only so pre-existing direct `MapData` literals (e.g. the static
+   * summary map, which is out of scope and draws no heading line) keep
+   * compiling. `buildMapData` ALWAYS sets it (to a bearing or null); a missing
+   * value is treated by `drawMapData` exactly like null (no line).
+   */
+  userHeadingDeg?: number | null;
+}
+/**
+ * Inputs to {@link buildMapData}, all optional so callers can supply only the
+ * slices they have. Array inputs are read-only and defensively copied.
+ */
+interface MapDataInput {
+  /** Raw GPS samples in chronological order. */
+  rawGpsPath?: readonly RawGpsSample[];
+  /** Odometry positions (AR-local) used to derive the fused path. */
+  odometryPositions?: ReadonlyArray<Vector3>;
+  /**
+   * Odometry rotations (NUE quaternions, as stored in
+   * `gpsEvents.odometryRotations`). The LATEST entry drives the user heading
+   * line; earlier entries are ignored here. Pass the `selectOdometryRotations`
+   * value directly.
+   */
+  odometryRotations?: ReadonlyArray<Quaternion>;
+  /** Latest alignment matrix from the solver (null until first solve). */
+  alignmentMatrix?: Matrix4 | null;
+  /** GPS origin for ENU→GPS conversion (null when no GPS yet). */
+  zeroRef?: LatLong | null;
+  /** Alignment-snapshot GPS positions. */
+  alignmentSnapshots?: readonly GpsCoord[];
+  /**
+   * Explicit user position — including `null` to hide the dot (summary map).
+   * When omitted, defaults to the last `fusedPath` point when the fused path
+   * is non-empty, else the last `rawGpsPath` entry, else null (2026-07-06
+   * fused-dot feedback).
+   */
+  userPosition?: GpsCoord | null;
+}
+/**
+ * Build a {@link MapData} snapshot from store-derived inputs.
+ *
+ * Pure and free of Leaflet/Three dependencies. The fused path is always
+ * derived via {@link computeFusedPath} (D2); when the matrix or zero reference
+ * is missing it is an empty array.
+ *
+ * @param input - Optional trajectory slices (see {@link MapDataInput}).
+ * @returns A fully-resolved {@link MapData} with all arrays defensively copied.
+ */
+declare function buildMapData(input: MapDataInput): MapData;
+//#endregion
+export { MapDataInput as n, buildMapData as r, MapData as t };