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

package/dist/visualization/index.js

@@ -5,8 +5,12 @@ import { createCameraFollower } from "./camera-follower.js";
 import { createAlignmentLerper } from "./alignment-lerper.js";
 import { VIS_COLORS } from "./vis-colors.js";
 import { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, createGpsCompassCubes } from "./gps-compass-cubes.js";
+import { buildMapData } from "./map-data.js";
+import { buildCameraFrustum, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum } from "./frustum-visibility.js";
+import { n as nueToArLocal, t as createGpsAnchor } from "../gps-anchor-DjC_3MoT.js";
 import { GpsEventVisualizer, gpsEventVisualizer } from "./gps-event-markers.js";
+import { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, addAccuracyCircles } from "./accuracy-circles.js";
+import { ALIGNMENT_SNAPSHOT_COLOR, FUSED_PATH_COLOR, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, RAW_GPS_COLOR, USER_POSITION_COLOR, drawMapData } from "./map-overlay-draw.js";
 import { DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_WORLD_SIZE, DEFAULT_Z_OFFSET, LeafletMapOverlay } from "./leaflet-map-overlay.js";
 import { DEFAULT_HEIGHT_OFFSET, DEFAULT_MAP_SIZE, DEFAULT_ZOOM, MapOverlay, latLonToTileXY, tileXYToLatLon } from "./map-overlay.js";
-import { RefPointVisualizer, refPointVisualizer } from "./reference-points.js";
-export { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, GpsEventVisualizer, LeafletMapOverlay, MapOverlay, RefPointVisualizer, VIS_COLORS, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsCompassCubes, disposeMeshArray, disposeObject3D, gpsEventVisualizer, latLonToTileXY, refPointVisualizer, tileXYToLatLon };
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, ALIGNMENT_SNAPSHOT_COLOR, COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, FUSED_PATH_COLOR, GpsEventVisualizer, LeafletMapOverlay, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, MapOverlay, RAW_GPS_COLOR, USER_POSITION_COLOR, VIS_COLORS, addAccuracyCircles, buildCameraFrustum, buildMapData, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsAnchor, createGpsCompassCubes, disposeMeshArray, disposeObject3D, drawMapData, gpsEventVisualizer, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum, latLonToTileXY, nueToArLocal, tileXYToLatLon };

package/dist/visualization/leaflet-map-overlay.d.ts

@@ -1,2 +1,2 @@
-import { a as DEFAULT_Z_OFFSET, i as DEFAULT_ZOOM, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions, t as DEFAULT_HEIGHT_OFFSET } from "../leaflet-map-overlay-CvfQXTye.js";
+import { a as DEFAULT_Z_OFFSET, i as DEFAULT_ZOOM, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions, t as DEFAULT_HEIGHT_OFFSET } from "../leaflet-map-overlay-Cew7XAoO.js";
 export { DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, LeafletMapOverlay, LeafletMapOverlayOptions };

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

@@ -1,5 +1,6 @@
 import { createLogger } from "../utils/logger.js";
 import { VIS_COLORS } from "./vis-colors.js";
+import { drawMapData } from "./map-overlay-draw.js";
 import { CSS3DObject } from "three/addons/renderers/CSS3DRenderer.js";
 import L from "leaflet";
 //#region ../src/visualization/leaflet-map-overlay.ts
@@ -35,14 +36,9 @@ var LeafletMapOverlay = class {
 	leafletMap = null;
 	tileLayer = null;
 	cssObject = null;
-	rawGpsPoints = [];
-	fusedPoints = [];
-	snapshotPoints = [];
-	refPoints = [];
-	userMarker = null;
-	rawGpsPolyline = null;
-	fusedPolyline = null;
-	snapshotPolyline = null;
+	latestMapData = null;
+	trajectoryLayers = [];
+	namedMarkers = [];
 	constructor(scene, camera, options = {}) {
 		this.scene = scene;
 		this.camera = camera;
@@ -60,10 +56,7 @@ var LeafletMapOverlay = class {
 			lat,
 			lon
 		};
-		if (this.leafletMap) {
-			this.leafletMap.setView([lat, lon], this.zoomLevel);
-			this.updateUserMarker();
-		}
+		if (this.leafletMap) this.leafletMap.setView([lat, lon], this.zoomLevel);
 	}
 	getGpsPosition() {
 		return this.gpsPosition;
@@ -93,42 +86,27 @@ var LeafletMapOverlay = class {
 	isVisible() {
 		return this.visible;
 	}
-	addRawGpsPoint(lat, lon) {
-		this.rawGpsPoints.push([lat, lon]);
-		if (this.leafletMap) {
-			if (!this.rawGpsPolyline) this.rawGpsPolyline = L.polyline([], {
-				color: VIS_COLORS.RAW_GPS.css,
-				weight: 3,
-				opacity: .8
-			}).addTo(this.leafletMap);
-			this.rawGpsPolyline.addLatLng([lat, lon]);
-		}
-	}
-	addFusedPoint(lat, lon) {
-		this.fusedPoints.push([lat, lon]);
-		if (this.leafletMap) {
-			if (!this.fusedPolyline) this.fusedPolyline = L.polyline([], {
-				color: VIS_COLORS.FUSED_VIO.css,
-				weight: 3,
-				opacity: .8
-			}).addTo(this.leafletMap);
-			this.fusedPolyline.addLatLng([lat, lon]);
-		}
-	}
-	addAlignmentSnapshot(lat, lon) {
-		this.snapshotPoints.push([lat, lon]);
-		if (this.leafletMap) {
-			if (!this.snapshotPolyline) this.snapshotPolyline = L.polyline([], {
-				color: VIS_COLORS.ALIGNMENT_SNAPSHOT.css,
-				weight: 3,
-				opacity: .8
-			}).addTo(this.leafletMap);
-			this.snapshotPolyline.addLatLng([lat, lon]);
-		}
+	/**
+	* 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;
+		if (this.leafletMap) this.drawTrajectory();
 	}
-	addRefPoint(lat, lon, name) {
-		const marker = this.leafletMap ? this.createRefPointMarker(lat, lon, name, false) : null;
-		this.refPoints.push({
+	/** 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,
@@ -136,9 +114,10 @@ var LeafletMapOverlay = class {
 			marker
 		});
 	}
-	addPriorRefPoint(lat, lon, name) {
-		const marker = this.leafletMap ? this.createRefPointMarker(lat, lon, name, true) : null;
-		this.refPoints.push({
+	/** 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,
@@ -146,13 +125,15 @@ var LeafletMapOverlay = class {
 			marker
 		});
 	}
-	addPriorRefPoints(refPoints) {
-		for (const rp of refPoints) this.addPriorRefPoint(rp.lat, rp.lon, rp.name);
+	/** Bulk add prior markers. */
+	addPriorMarkers(markers) {
+		for (const m of markers) this.addPriorMarker(m.lat, m.lon, m.name);
 	}
-	clearPriorRefPoints() {
-		this.refPoints = this.refPoints.filter((rp) => {
-			if (rp.isPrior) {
-				rp.marker?.remove();
+	/** 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;
@@ -195,10 +176,9 @@ var LeafletMapOverlay = class {
 	dispose() {
 		this.hide();
 		this.destroyLeafletMap();
-		this.rawGpsPoints = [];
-		this.fusedPoints = [];
-		this.snapshotPoints = [];
-		this.refPoints = [];
+		this.latestMapData = null;
+		this.trajectoryLayers = [];
+		this.namedMarkers = [];
 		this.cssObject = null;
 		log.info("Leaflet map overlay disposed");
 	}
@@ -228,17 +208,11 @@ var LeafletMapOverlay = class {
 		this.tileLayer.addTo(this.leafletMap);
 	}
 	destroyLeafletMap() {
-		this.userMarker?.remove();
-		this.userMarker = null;
-		this.rawGpsPolyline?.remove();
-		this.rawGpsPolyline = null;
-		this.fusedPolyline?.remove();
-		this.fusedPolyline = null;
-		this.snapshotPolyline?.remove();
-		this.snapshotPolyline = null;
-		for (const rp of this.refPoints) {
-			rp.marker?.remove();
-			rp.marker = null;
+		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();
@@ -269,35 +243,19 @@ var LeafletMapOverlay = class {
 	}
 	applyBufferedOverlays() {
 		if (!this.leafletMap) return;
-		this.updateUserMarker();
-		if (this.rawGpsPoints.length > 0) this.rawGpsPolyline = L.polyline(this.rawGpsPoints, {
-			color: VIS_COLORS.RAW_GPS.css,
-			weight: 3,
-			opacity: .8
-		}).addTo(this.leafletMap);
-		if (this.fusedPoints.length > 0) this.fusedPolyline = L.polyline(this.fusedPoints, {
-			color: VIS_COLORS.FUSED_VIO.css,
-			weight: 3,
-			opacity: .8
-		}).addTo(this.leafletMap);
-		if (this.snapshotPoints.length > 0) this.snapshotPolyline = L.polyline(this.snapshotPoints, {
-			color: VIS_COLORS.ALIGNMENT_SNAPSHOT.css,
-			weight: 3,
-			opacity: .8
-		}).addTo(this.leafletMap);
-		for (const rp of this.refPoints) if (!rp.marker) rp.marker = this.createRefPointMarker(rp.lat, rp.lng, rp.name, rp.isPrior);
+		this.drawTrajectory();
+		for (const m of this.namedMarkers) if (!m.marker) m.marker = this.createNamedMarker(m.lat, m.lng, m.name, m.isPrior);
 	}
-	updateUserMarker() {
-		if (!this.gpsPosition || !this.leafletMap) return;
-		if (this.userMarker) this.userMarker.setLatLng([this.gpsPosition.lat, this.gpsPosition.lon]);
-		else this.userMarker = L.marker([this.gpsPosition.lat, this.gpsPosition.lon], { icon: L.divIcon({
-			className: "",
-			html: `<div style="background:${VIS_COLORS.USER_POSITION.css};width:14px;height:14px;border-radius:50%;border:3px solid white;box-shadow:0 0 6px rgba(59,130,246,0.6);"></div>`,
-			iconSize: [14, 14],
-			iconAnchor: [7, 7]
-		}) }).addTo(this.leafletMap);
+	/**
+	* 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;
 	}
-	createRefPointMarker(lat, lon, name, isPrior) {
+	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;

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

@@ -1,2 +1,2 @@
-import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-87NWjUOD.js";
+import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-B8MM8zCR.js";
 export { DEFAULT_LERP_RATE, clampedAlpha };

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

@@ -0,0 +1,2 @@
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-sih4g64v.js";
+export { MapData, MapDataInput, buildMapData };

package/dist/visualization/map-data.js

@@ -0,0 +1,33 @@
+import { computeFusedPath } from "../utils/fused-path.js";
+//#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 lastRaw = rawGpsPath[rawGpsPath.length - 1];
+	return {
+		userPosition: input.userPosition !== void 0 ? input.userPosition : lastRaw ? {
+			lat: lastRaw.lat,
+			lng: lastRaw.lng
+		} : null,
+		rawGpsPath,
+		fusedPath,
+		alignmentSnapshots
+	};
+}
+//#endregion
+export { buildMapData };

package/dist/visualization/map-overlay-draw.d.ts

@@ -0,0 +1,2 @@
+import { a as MAP_PATH_POLYLINE_OPACITY, c as USER_POSITION_COLOR, i as FUSED_PATH_COLOR, l as drawMapData, n as DrawMapDataOptions, o as MAP_PATH_POLYLINE_WEIGHT, r as DrawnMapData, s as RAW_GPS_COLOR, t as ALIGNMENT_SNAPSHOT_COLOR } from "../map-overlay-draw-B3R1c9Xp.js";
+export { ALIGNMENT_SNAPSHOT_COLOR, DrawMapDataOptions, DrawnMapData, FUSED_PATH_COLOR, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, RAW_GPS_COLOR, USER_POSITION_COLOR, drawMapData };

package/dist/visualization/map-overlay-draw.js

@@ -0,0 +1,107 @@
+import { VIS_COLORS } from "./vis-colors.js";
+import { addAccuracyCircles } from "./accuracy-circles.js";
+import L from "leaflet";
+//#region ../src/visualization/map-overlay-draw.ts
+/**
+* Shared map-overlay-drawing module.
+*
+* `drawMapData` is the SINGLE Leaflet drawing routine rendered by BOTH map
+* consumers — the live/replay 3D overlay (`LeafletMapOverlay`) and the 2D
+* session-summary map (`createSummaryMap`). Centralising the drawing here is
+* Phase 3 of the map-system review and the fix for Findings 1 & 4 of the
+* unified-trajectory-map user feedback: previously each renderer drew the
+* trajectory by hand and the two visibly diverged.
+*
+* It consumes the resolved {@link MapData} produced by `buildMapData` and adds,
+* in this order:
+*   1. per-event accuracy circles for the raw GPS path (drawn first so the
+*      polyline stays on top), then the raw GPS polyline;
+*   2. the fused (SLAM+GPS) polyline;
+*   3. the alignment-snapshot polyline;
+*   4. (optional) a user-position marker.
+*
+* SCOPE: this module draws only the genuinely-shared SLAM/GPS trajectory
+* layers. Reference-point markers are a RECORDER concept and are drawn by the
+* recorder-owned `ui/draw-ref-point-markers.ts` helper (called from both the
+* summary map and the live overlay wiring), so the two maps stay identical
+* while the framework remains ref-point-agnostic. See
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-unified-trajectory-map-phase3-plan.md
+* § Step 5.
+*
+* The caller owns map creation, tile layer, `fitBounds`, resize handling and
+* fullscreen — this module only draws data layers and reports the accumulated
+* bounds so the caller can frame the view.
+*/
+/** Raw GPS polyline + accuracy-circle color (yellow). */
+const RAW_GPS_COLOR = VIS_COLORS.RAW_GPS.css;
+/** Fused SLAM+GPS polyline color (cyan). */
+const FUSED_PATH_COLOR = VIS_COLORS.FUSED_VIO.css;
+/** Alignment-snapshot polyline color (red). */
+const ALIGNMENT_SNAPSHOT_COLOR = VIS_COLORS.ALIGNMENT_SNAPSHOT.css;
+/** User-position marker color (blue). */
+const USER_POSITION_COLOR = VIS_COLORS.USER_POSITION.css;
+/** Polyline weight (px) — matches the recorder's `PATH_POLYLINE_WEIGHT`. */
+const MAP_PATH_POLYLINE_WEIGHT = 3;
+/** Polyline opacity — matches the recorder's `PATH_POLYLINE_OPACITY`. */
+const MAP_PATH_POLYLINE_OPACITY = .8;
+/**
+* Draw a {@link MapData} snapshot onto an existing Leaflet map.
+*
+* @param map - Target map (already created with a tile layer by the caller).
+* @param data - Resolved trajectory data from `buildMapData`.
+* @param options - Optional layer toggles (see {@link DrawMapDataOptions}).
+* @returns The created layers and the bounds spanning every drawn coordinate.
+*/
+function drawMapData(map, data, options = {}) {
+	const layers = [];
+	const bounds = L.latLngBounds([]);
+	if (data.rawGpsPath.length > 0) {
+		const rawLatLngs = data.rawGpsPath.map((p) => [p.lat, p.lng]);
+		const circles = addAccuracyCircles(map, data.rawGpsPath, RAW_GPS_COLOR);
+		layers.push(...circles);
+		const rawPolyline = L.polyline(rawLatLngs, {
+			color: RAW_GPS_COLOR,
+			weight: 3,
+			opacity: MAP_PATH_POLYLINE_OPACITY
+		}).addTo(map);
+		layers.push(rawPolyline);
+		for (const ll of rawLatLngs) bounds.extend(ll);
+	}
+	if (data.fusedPath.length > 0) {
+		const fusedLatLngs = data.fusedPath.map((p) => [p.lat, p.lng]);
+		const fusedPolyline = L.polyline(fusedLatLngs, {
+			color: FUSED_PATH_COLOR,
+			weight: 3,
+			opacity: MAP_PATH_POLYLINE_OPACITY
+		}).addTo(map);
+		layers.push(fusedPolyline);
+		for (const ll of fusedLatLngs) bounds.extend(ll);
+	}
+	if (data.alignmentSnapshots.length > 0) {
+		const snapshotLatLngs = data.alignmentSnapshots.map((p) => [p.lat, p.lng]);
+		const snapshotPolyline = L.polyline(snapshotLatLngs, {
+			color: ALIGNMENT_SNAPSHOT_COLOR,
+			weight: 3,
+			opacity: MAP_PATH_POLYLINE_OPACITY
+		}).addTo(map);
+		layers.push(snapshotPolyline);
+		for (const ll of snapshotLatLngs) bounds.extend(ll);
+	}
+	if (options.showUserPosition && data.userPosition) {
+		const icon = L.divIcon({
+			className: "map-overlay-user-position",
+			html: `<div style="background:${USER_POSITION_COLOR};width:14px;height:14px;border-radius:50%;border:2px solid white;"></div>`,
+			iconSize: [18, 18],
+			iconAnchor: [9, 9]
+		});
+		const marker = L.marker([data.userPosition.lat, data.userPosition.lng], { icon }).addTo(map);
+		layers.push(marker);
+		bounds.extend([data.userPosition.lat, data.userPosition.lng]);
+	}
+	return {
+		layers,
+		bounds
+	};
+}
+//#endregion
+export { ALIGNMENT_SNAPSHOT_COLOR, FUSED_PATH_COLOR, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, RAW_GPS_COLOR, USER_POSITION_COLOR, drawMapData };

package/dist/visualization/map-overlay.d.ts

@@ -1,2 +1,2 @@
-import { a as MapOverlayOptions, c as tileXYToLatLon, i as MapOverlay, n as DEFAULT_MAP_SIZE, o as TextureLoaderInterface, r as DEFAULT_ZOOM, s as latLonToTileXY, t as DEFAULT_HEIGHT_OFFSET } from "../map-overlay-DuiZuCTx.js";
+import { a as MapOverlayOptions, c as tileXYToLatLon, i as MapOverlay, n as DEFAULT_MAP_SIZE, o as TextureLoaderInterface, r as DEFAULT_ZOOM, s as latLonToTileXY, t as DEFAULT_HEIGHT_OFFSET } from "../map-overlay-DAmreyA3.js";
 export { DEFAULT_HEIGHT_OFFSET, DEFAULT_MAP_SIZE, DEFAULT_ZOOM, MapOverlay, MapOverlayOptions, TextureLoaderInterface, latLonToTileXY, tileXYToLatLon };

package/dist/visualization/three-dispose.d.ts

@@ -1,2 +1,2 @@
-import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-CCBHjE_a.js";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-C2drkp6f.js";
 export { DisposeOptions, disposeMeshArray, disposeObject3D };

package/dist/visualization/vis-colors.d.ts

@@ -1,2 +1,2 @@
-import { t as VIS_COLORS } from "../vis-colors-Qi2vlRGt.js";
+import { t as VIS_COLORS } from "../vis-colors-CHQhjal3.js";
 export { VIS_COLORS };

package/dist/{webxr-session-COlSrXdL.d.ts → webxr-session-DB5cIZnN.d.ts}

@@ -1,13 +1,30 @@
-import { i as DepthSample, t as ARPose } from "./ar-types-B-ORgk6Z.js";
-import { i as ImageCaptureConfig, t as CapturedImage } from "./image-capture-2pKjYUS6.js";
-import { t as Css3dRendererManager } from "./css3d-renderer-manager-rgLMVAvd.js";
-import { n as ResetTransformData } from "./tracking-state-B9QfuZCg.js";
-import { t as ArCrashIsolationOptions } from "./recording-options-BYUFX8iU.js";
-import { r as XRCameraLike } from "./xr-camera-texture-BbukNE79.js";
+import { i as DepthSample, t as ARPose } from "./ar-types-Ck8LEq8k.js";
+import { i as ImageCaptureConfig, t as CapturedImage } from "./image-capture-DZLxHDN9.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-CkjCb2HW.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-utCNND8t.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-Dq6IsKAv.js";
+import { r as XRCameraLike } from "./xr-camera-texture-BU5YvKAM.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
 
 //#region ../src/ar/webxr-session.d.ts
+/**
+ * Minimal subscribable-store contract the tracking pipeline needs:
+ * dispatch the slice actions, read the slice for the restart payload, and
+ * subscribe to phase transitions. Structurally compatible with the full
+ * `SlamAppStore` (and any test double) without coupling this module to the
+ * factory's exact generics.
+ */
+interface TrackingSubscribableStore {
+  dispatch: (action: {
+    type: string;
+    payload?: unknown;
+  }) => unknown;
+  getState: () => {
+    tracking: TrackingSliceState;
+  };
+  subscribe: (listener: () => void) => () => void;
+}
 declare function isXRCameraLike(value: unknown): value is XRCameraLike;
 /**
  * Extract a validated XRCameraLike from an XRViewerPose.
@@ -114,8 +131,18 @@ declare function isWebXRSupported(): Promise<boolean>;
  * basisChangeNode is a static scene-graph node that holds the WEBXR_TO_NUE
  * basis-change matrix permanently (matrixAutoUpdate=false). Moving it here
  * instead of composing it in applyAlignmentMatrix() keeps arWorldGroup's
- * local space as NUE: objects added directly to arWorldGroup can be placed
- * at [1,0,0]=North, [0,0,1]=East without any WebXR↔NUE conversion.
+ * local space in the **NUE axis convention** (X=North, Y=Up, Z=East), so no
+ * WebXR↔NUE swizzle is needed for children.
+ *
+ * CAUTION — two NUE frames: arWorldGroup's local space is the *AR-odometry*
+ * NUE frame, i.e. the **domain** of the alignment matrix, NOT the GPS-world
+ * NUE frame of the scene root. Only content authored in AR-odometry
+ * coordinates (e.g. the camera subtree) may be placed with raw local values.
+ * GPS-world content (a lat/lon → NUE point) is expressed in the scene-root
+ * frame and must be pre-multiplied by alignment⁻¹ before being used as a
+ * local position under arWorldGroup — see createGpsAnchor and the
+ * alignment-frame bug doc
+ * (GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md).
  *
  * - Recording: arpose stays at identity; WebXRManager writes to camera.
  * - Replay: arpose receives recorded odomPosition/odomRotation;
@@ -225,9 +252,12 @@ declare function nueQuaternionToWebXR$1(nue: readonly number[]): readonly [numbe
 /**
  * End the current XR session and clean up all resources.
  *
- * Stops the animation loop, disposes the WebGL renderer, removes the
- * canvas from the DOM, and tears down the CSS3D overlay. This is the
- * production cleanup path — call it when the AR experience is finished.
+ * Stops the animation loop, ends the XR session, then delegates the full
+ * teardown to {@link resetWebXRState} so every module-level reference is
+ * cleared (renderer/scene/camera, image-capture, depth, the tracking-phase
+ * subscription, the frame-update registry, diagnostics, blit resources).
+ * This is the production cleanup path — call it when the AR experience is
+ * finished.
  */
 declare function endARSession(): Promise<void>;
 /**
@@ -255,6 +285,17 @@ declare function stopImageCapture(): void;
  * Get the current image capture frame count.
  */
 declare function getImageCaptureFrameCount(): number;
+/**
+ * Inject the Redux store used by the tracking-state slice pipeline.
+ *
+ * MUST be called before `initAR()` whenever the host also wires tracking
+ * callbacks via `setTrackingCallbacks`. Without a store the tracking
+ * pipeline silently no-ops.
+ *
+ * @param store — any store satisfying {@link TrackingSubscribableStore}.
+ *   `null` clears the binding (useful for teardown in tests).
+ */
+declare function setTrackingStore(store: TrackingSubscribableStore | null): void;
 /**
  * Set up tracking state callbacks.
  * Call this BEFORE initAR() to enable tracking restart detection.
@@ -313,4 +354,4 @@ declare function setFrameCallback(callback: (() => void) | null): void;
  */
 declare function getLiveCss3dManager(): Css3dRendererManager | null;
 //#endregion
-export { setTrackingLostCallback as A, setArWorldGroup as C, setImageCaptureCallback as D, setFrameCallback as E, stopDepthCapture as F, stopImageCapture as I, shouldLogCameraAccessDiagnostic as M, startDepthCapture as N, setScene as O, startImageCapture as P, setArPose as S, setDepthCaptureCallback as T, isWebXRSupported as _, extractPoseFromViewer as a, nueQuaternionToWebXR$1 as b, getArWorldGroup as c, getDepthSampleCount as d, getImageCaptureFrameCount as f, initAR as g, getXrCameraFromPose as h, endARSession as i, setTrackingRecoveredCallback as j, setTrackingCallbacks as k, getCamera as l, getScene as m, buildSessionOptions as n, extractResetTransformData as o, getLiveCss3dManager as p, createSceneHierarchy as r, getArPose as s, applyAlignmentMatrix as t, getCurrentArPose as u, isXRCameraLike as v, setCamera as w, resetWebXRState as x, nuePositionToWebXR as y };
+export { setTrackingCallbacks as A, setArPose as C, setFrameCallback as D, setDepthCaptureCallback as E, startDepthCapture as F, startImageCapture as I, stopDepthCapture as L, setTrackingRecoveredCallback as M, setTrackingStore as N, setImageCaptureCallback as O, shouldLogCameraAccessDiagnostic as P, stopImageCapture as R, resetWebXRState as S, setCamera as T, initAR as _, endARSession as a, nuePositionToWebXR as b, getArPose as c, getCurrentArPose as d, getDepthSampleCount as f, getXrCameraFromPose as g, getScene as h, createSceneHierarchy as i, setTrackingLostCallback as j, setScene as k, getArWorldGroup as l, getLiveCss3dManager as m, applyAlignmentMatrix as n, extractPoseFromViewer as o, getImageCaptureFrameCount as p, buildSessionOptions as r, extractResetTransformData as s, TrackingSubscribableStore as t, getCamera as u, isWebXRSupported as v, setArWorldGroup as w, nueQuaternionToWebXR$1 as x, isXRCameraLike as y };

package/dist/{zip-export-Rtpi75JJ.d.ts → zip-export-QO4iLIi7.d.ts}

@@ -28,6 +28,55 @@ interface ZipExportResult {
   /** Number of files packaged in the ZIP */
   readonly fileCount: number;
 }
+/**
+ * Helper passed to a {@link ZipExportContributor.contribute} callback for
+ * appending blobs to the ZIP under a stable, contributor-owned subdirectory.
+ *
+ * The framework prepends the contributor's `subdir` to the supplied
+ * `relativePath` automatically, so contributors only think in terms of paths
+ * relative to their own subdir (e.g. `'42.json'`, not `'refPoints/42.json'`).
+ */
+type ZipContributorAddFile = (relativePath: string, blob: Blob) => Promise<void>;
+/**
+ * Extension contributor that lets a consumer (typically the recorder)
+ * append app-specific files to a session ZIP without forking the
+ * framework's ZIP writer.
+ *
+ * Each contributor declares a top-level subdirectory it owns inside the
+ * ZIP (e.g. the recorder uses `refPoints/`). The framework calls
+ * {@link contribute} after writing all framework-owned sections.
+ *
+ * Contributors must:
+ *  - Only write files under their declared `subdir` (the framework enforces
+ *    this by routing every `addFile` call through the prefix).
+ *  - Tolerate an empty source (e.g. a session with no ref points) by
+ *    returning `0` instead of throwing.
+ *
+ * @see 2026-05-03-appframework-vs-recorderapp-boundary-analysis.md — Iter 2.
+ */
+interface ZipExportContributor {
+  /** Top-level subdirectory inside the ZIP (no leading or trailing `/`). */
+  readonly subdir: string;
+  /**
+   * Append files for this contributor. Implementations call `addFile`
+   * once per file with a path relative to {@link subdir}.
+   *
+   * @returns Number of files added so the framework's `fileCount` total
+   *   stays accurate for download summaries.
+   */
+  contribute(addFile: ZipContributorAddFile): Promise<number>;
+}
+/**
+ * Options for {@link exportSessionAsZip}.
+ */
+interface ExportSessionAsZipOptions {
+  /**
+   * Optional list of {@link ZipExportContributor}s. Each is invoked after
+   * framework-owned sections have been written. Order is preserved in the
+   * resulting ZIP central directory but has no semantic effect.
+   */
+  readonly contributors?: readonly ZipExportContributor[];
+}
 /**
  * Export a session from OPFS as a ZIP blob.
  *
@@ -35,16 +84,18 @@ interface ZipExportResult {
  * - session.json (at root)
  * - actions/000001.json, actions/000002.json, ...
  * - frames/frame-000001.jpg, frames/frame-000002.jpg, ...
- * - refPoints/{h3}.json (only observations from this session)
+ * - refPoints/{h3}.json (only observations from this session, scenario layout only)
  *
  * Uses "store" mode (compression level 0) for fast packaging.
  *
- * @param scenarioName - Name of the scenario
- * @param sessionName - Name of the session folder
+ * Supports both flat and scenario-based layouts:
+ * - `exportSessionAsZip(sessionName)` — flat layout (sessions/)
+ * - `exportSessionAsZip(scenarioName, sessionName)` — scenario layout (scenarios/{name}/)
+ *
  * @returns ZIP export result with blob and file count
- * @throws Error if scenario or session not found
+ * @throws Error if session not found
  */
-declare function exportSessionAsZip(scenarioName: string, sessionName: string): Promise<ZipExportResult>;
+declare function exportSessionAsZip(scenarioNameOrSessionName: string, sessionName?: string, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
 /**
  * Sync current OPFS session data to an external file handle.
  *
@@ -63,7 +114,7 @@ declare function exportSessionAsZip(scenarioName: string, sessionName: string):
  * @returns ZIP export result with blob and file count
  * @throws Error if scenario or session not found
  */
-declare function syncToExternalZip(fileHandle: FileSystemFileHandle, scenarioName: string, sessionName: string): Promise<ZipExportResult>;
+declare function syncToExternalZip(fileHandle: FileSystemFileHandle, scenarioName: string, sessionName: string, options?: ExportSessionAsZipOptions): Promise<ZipExportResult>;
 /**
  * Trigger a file download in the browser.
  *
@@ -84,4 +135,4 @@ declare function downloadZip(blob: Blob, filename: string): Promise<void>;
  */
 declare function exportAndDownloadSession(scenarioName: string, sessionName: string): Promise<void>;
 //#endregion
-export { syncToExternalZip as a, exportSessionAsZip as i, downloadZip as n, exportAndDownloadSession as r, ZipExportResult as t };
+export { downloadZip as a, syncToExternalZip as c, ZipExportResult as i, ZipContributorAddFile as n, exportAndDownloadSession as o, ZipExportContributor as r, exportSessionAsZip as s, ExportSessionAsZipOptions as t };