gps-plus-slam-app-framework 1.0.0

package/dist/utils/logger.js

@@ -0,0 +1,226 @@
+import * as Sentry from "@sentry/browser";
+//#region ../src/utils/logger.ts
+/**
+* Configurable Logger Utility
+*
+* Provides a simple logging API with configurable log levels.
+* This allows disabling verbose logging in production while keeping
+* it available for development and debugging.
+*
+* Also maintains an in-memory ring buffer of recent log entries
+* for display in the expandable log panel UI.
+*
+* Sentry Integration:
+* - All log levels add Sentry breadcrumbs for debugging context
+* - log.error() with Error objects automatically reports to Sentry
+*/
+/**
+* Log levels in order of verbosity (lower = more verbose)
+*/
+let LogLevel = /* @__PURE__ */ function(LogLevel) {
+	LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+	LogLevel[LogLevel["INFO"] = 1] = "INFO";
+	LogLevel[LogLevel["WARN"] = 2] = "WARN";
+	LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+	LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+	return LogLevel;
+}({});
+/**
+* Global log level - controls what gets logged across all loggers
+*/
+let globalLogLevel = 0;
+/**
+* Maximum number of log entries to keep in the ring buffer
+*/
+const LOG_BUFFER_MAX_SIZE = 100;
+/**
+* In-memory ring buffer of recent log entries
+*/
+let logBuffer = [];
+let subscribers = [];
+/**
+* Serialize an Error instance to an object capturing name, message, stack,
+* and any enumerable properties.
+*/
+function serializeError(error) {
+	const result = {
+		name: error.name,
+		message: error.message,
+		stack: error.stack
+	};
+	for (const key of Object.keys(error)) result[key] = error[key];
+	return result;
+}
+/**
+* Safely stringify an object, handling circular references.
+* Uses a WeakSet to track seen objects and replaces cycles with a placeholder.
+*/
+function safeStringify(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const replacer = (_key, val) => {
+		if (typeof val === "bigint") return val.toString();
+		if (val !== null && typeof val === "object") {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+		}
+		return val;
+	};
+	try {
+		return JSON.stringify(value, replacer);
+	} catch {
+		return "[Unserializable]";
+	}
+}
+/**
+* Serialize a single argument to a string for the log buffer.
+* Special-cases Error instances and handles circular/complex objects safely.
+*/
+function serializeArg(arg) {
+	if (arg === null) return "null";
+	if (arg === void 0) return "undefined";
+	if (typeof arg === "string") return arg;
+	if (typeof arg === "number" || typeof arg === "boolean") return String(arg);
+	if (typeof arg === "bigint") return arg.toString();
+	if (typeof arg === "symbol") return arg.toString();
+	if (typeof arg === "function") return arg.name ? `[Function: ${arg.name}]` : "[Function]";
+	if (arg instanceof Error) return safeStringify(serializeError(arg));
+	return safeStringify(arg);
+}
+/**
+* Add an entry to the log buffer and notify subscribers
+*/
+function addToBuffer(level, tag, args) {
+	const message = args.map((arg) => serializeArg(arg)).join(" ");
+	const entry = {
+		timestamp: Date.now(),
+		level,
+		tag,
+		message
+	};
+	logBuffer.push(entry);
+	if (logBuffer.length > LOG_BUFFER_MAX_SIZE) logBuffer.shift();
+	for (const subscriber of subscribers) try {
+		subscriber(entry);
+	} catch (err) {
+		console.error("[Logger] Subscriber threw an error:", err);
+	}
+}
+/**
+* Get a copy of the current log buffer
+* @returns Array of log entries (copy to prevent external mutation)
+*/
+function getLogBuffer() {
+	return [...logBuffer];
+}
+/**
+* Clear all entries from the log buffer
+*/
+function clearLogBuffer() {
+	logBuffer = [];
+}
+/**
+* Subscribe to new log entries
+* @param callback - Function called when a new log entry is added
+* @returns Unsubscribe function
+*/
+function subscribeToLogs(callback) {
+	subscribers.push(callback);
+	return () => {
+		subscribers = subscribers.filter((sub) => sub !== callback);
+	};
+}
+/**
+* Set the global log level
+* @param level - The minimum level to log
+*/
+function setGlobalLogLevel(level) {
+	globalLogLevel = level;
+}
+/**
+* Get the current global log level
+*/
+function getGlobalLogLevel() {
+	return globalLogLevel;
+}
+/**
+* Create a logger with a specific tag prefix
+* @param tag - The tag to prefix all log messages with (e.g., 'GPS', 'Storage')
+* @returns A logger object with debug, info, warn, error methods
+*
+* @example
+* ```typescript
+* const log = createLogger('GPS');
+* log.info('Watch started'); // [GPS] Watch started
+* log.error('Error:', err);  // [GPS] Error: <error details>
+* ```
+*/
+/**
+* Map LogLevel to Sentry breadcrumb severity.
+* Sentry uses 'warning' (not 'warn') for the warning level.
+*/
+function toSentryLevel(level) {
+	switch (level) {
+		case 0: return "debug";
+		case 1: return "info";
+		case 2: return "warning";
+		case 3: return "error";
+		default: return "info";
+	}
+}
+/**
+* Add a Sentry breadcrumb for debugging context.
+* Breadcrumbs are attached to future exceptions, helping trace what happened before an error.
+*/
+function addSentryBreadcrumb(level, tag, args) {
+	const message = `[${tag}] ${args.map((arg) => serializeArg(arg)).join(" ")}`;
+	Sentry.addBreadcrumb({
+		category: "log",
+		level: toSentryLevel(level),
+		message
+	});
+}
+/**
+* Report a warning to Sentry as a standalone message.
+* Called for log.warn() so warnings are independently visible in the
+* Sentry dashboard, not only as breadcrumbs attached to later exceptions.
+*/
+function reportWarningToSentry(tag, args) {
+	const message = `[${tag}] ${args.map((arg) => serializeArg(arg)).join(" ")}`;
+	Sentry.captureMessage(message, "warning");
+}
+/**
+* Report Error objects to Sentry.
+* Only called for log.error() - other levels just add breadcrumbs.
+*/
+function reportErrorsToSentry(args) {
+	for (const arg of args) if (arg instanceof Error) Sentry.captureException(arg);
+}
+function createLogger(tag) {
+	const prefix = `[${tag}]`;
+	return {
+		debug: (...args) => {
+			addToBuffer(0, tag, args);
+			addSentryBreadcrumb(0, tag, args);
+			if (globalLogLevel <= 0) console.log(prefix, ...args);
+		},
+		info: (...args) => {
+			addToBuffer(1, tag, args);
+			addSentryBreadcrumb(1, tag, args);
+			if (globalLogLevel <= 1) console.log(prefix, ...args);
+		},
+		warn: (...args) => {
+			addToBuffer(2, tag, args);
+			addSentryBreadcrumb(2, tag, args);
+			reportWarningToSentry(tag, args);
+			if (globalLogLevel <= 2) console.warn(prefix, ...args);
+		},
+		error: (...args) => {
+			addToBuffer(3, tag, args);
+			addSentryBreadcrumb(3, tag, args);
+			reportErrorsToSentry(args);
+			if (globalLogLevel <= 3) console.error(prefix, ...args);
+		}
+	};
+}
+//#endregion
+export { LogLevel, clearLogBuffer, createLogger, getGlobalLogLevel, getLogBuffer, setGlobalLogLevel, subscribeToLogs };

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

@@ -0,0 +1,63 @@
+//#region ../src/visualization/vis-colors.d.ts
+/**
+ * Centralized Visualization Color Palette
+ *
+ * Single source of truth for all semantic colors used across the app's
+ * visualization layers (Three.js 3D scene and Leaflet 2D summary map).
+ *
+ * Each entry provides both hex (number, for Three.js) and css (string,
+ * for Leaflet/CSS) formats. Some entries intentionally use different 3D/2D
+ * shades — see inline comments.
+ *
+ * Tailwind classes in index.html (e.g., bg-yellow-400) cannot be dynamically
+ * generated and must be kept in sync manually — search for "vis-colors" in
+ * the HTML legend to find them.
+ */
+declare const VIS_COLORS: {
+  /** Raw GPS marker — yellow */readonly RAW_GPS: {
+    readonly hex: 16776960;
+    readonly css: "#ffff00";
+  }; /** Fused VIO marker — cyan */
+  readonly FUSED_VIO: {
+    readonly hex: 65535;
+    readonly css: "#00ffff";
+  }; /** Alignment snapshot marker — red */
+  readonly ALIGNMENT_SNAPSHOT: {
+    readonly hex: 16711680;
+    readonly css: "#ff0000";
+  }; /** Prior reference point — green */
+  readonly PRIOR_REF_POINT: {
+    readonly hex: 65280;
+    readonly css: "#00ff00";
+  }; /** Current reference point — bright red in 3D, lighter red (#ff6b6b) in 2D for map visibility */
+  readonly CURRENT_REF_POINT: {
+    readonly hex: 16711680;
+    readonly css: "#ff6b6b";
+  }; /** Compass north indicator — red */
+  readonly COMPASS_NORTH: {
+    readonly hex: 16711680;
+    readonly css: "#ff0000";
+  }; /** Compass east indicator — blue */
+  readonly COMPASS_EAST: {
+    readonly hex: 255;
+    readonly css: "#0000ff";
+  }; /** Compass south indicator — dark red */
+  readonly COMPASS_SOUTH: {
+    readonly hex: 8930372;
+    readonly css: "#884444";
+  }; /** Compass west indicator — dark blue */
+  readonly COMPASS_WEST: {
+    readonly hex: 4473992;
+    readonly css: "#444488";
+  }; /** Compass up indicator — green */
+  readonly COMPASS_UP: {
+    readonly hex: 65280;
+    readonly css: "#00ff00";
+  }; /** User GPS position marker — blue */
+  readonly USER_POSITION: {
+    readonly hex: 3900150;
+    readonly css: "#3b82f6";
+  };
+};
+//#endregion
+export { VIS_COLORS as t };

package/dist/visualization/alignment-lerper.d.ts

@@ -0,0 +1,2 @@
+import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-D9BeDwZX.js";
+export { AlignmentLerper, createAlignmentLerper };

package/dist/visualization/alignment-lerper.js

@@ -0,0 +1,68 @@
+import { clampedAlpha } from "./lerp-utils.js";
+import * as THREE from "three";
+//#region ../src/visualization/alignment-lerper.ts
+/**
+* Alignment Lerper Module
+*
+* Smoothly interpolates arWorldGroup.matrix toward a target alignment
+* matrix each frame, eliminating visual jumps when the alignment solver
+* produces a new alignment (~1 Hz).
+*
+* Pattern: decompose → lerp position / slerp quaternion → compose.
+* Same lerpRate convention as camera-follower.ts (default 8 → ~90%
+* convergence in ~0.3 s at 60 fps).
+*
+* The first target is applied instantly (no animation from identity).
+*
+* @see docs/2026-03-21-user-feedback.md Issue 4
+*/
+const _currentPos = new THREE.Vector3();
+const _currentQuat = new THREE.Quaternion();
+const _currentScale = new THREE.Vector3();
+new THREE.Vector3();
+new THREE.Quaternion();
+new THREE.Vector3();
+/**
+* Create an AlignmentLerper that drives arWorldGroup.matrix smoothly.
+*
+* @param arWorldGroup The group whose matrix is interpolated.
+* @param lerpRate     Lerp speed multiplier (default 8).
+*/
+function createAlignmentLerper(arWorldGroup, lerpRate = 8) {
+	let hasTarget = false;
+	let isFirstTarget = true;
+	const storedTargetPos = new THREE.Vector3();
+	const storedTargetQuat = new THREE.Quaternion();
+	const storedTargetScale = new THREE.Vector3(1, 1, 1);
+	const _matrix = new THREE.Matrix4();
+	return {
+		setTarget(matrix) {
+			_matrix.fromArray(matrix);
+			_matrix.decompose(storedTargetPos, storedTargetQuat, storedTargetScale);
+			hasTarget = true;
+		},
+		update(dt) {
+			if (!hasTarget) return;
+			if (isFirstTarget) {
+				_matrix.compose(storedTargetPos, storedTargetQuat, storedTargetScale);
+				arWorldGroup.matrix.copy(_matrix);
+				arWorldGroup.matrixAutoUpdate = false;
+				arWorldGroup.updateMatrixWorld(true);
+				isFirstTarget = false;
+				return;
+			}
+			arWorldGroup.matrix.decompose(_currentPos, _currentQuat, _currentScale);
+			const alpha = clampedAlpha(lerpRate, dt);
+			_currentPos.lerp(storedTargetPos, alpha);
+			_currentQuat.slerp(storedTargetQuat, alpha);
+			_currentScale.lerp(storedTargetScale, alpha);
+			_matrix.compose(_currentPos, _currentQuat, _currentScale);
+			arWorldGroup.matrix.copy(_matrix);
+			arWorldGroup.matrixAutoUpdate = false;
+			arWorldGroup.updateMatrixWorld(true);
+		},
+		dispose() {}
+	};
+}
+//#endregion
+export { createAlignmentLerper };

package/dist/visualization/camera-follower.d.ts

@@ -0,0 +1,2 @@
+import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-BMqPddxx.js";
+export { CameraFollower, createCameraFollower };

package/dist/visualization/camera-follower.js

@@ -0,0 +1,51 @@
+import { SCENE_NODE } from "../ar/scene-node-names.js";
+import { clampedAlpha } from "./lerp-utils.js";
+import * as THREE from "three";
+//#region ../src/visualization/camera-follower.ts
+/**
+* Camera Follower Module
+*
+* Creates an Object3D that tracks the camera's world position
+* every frame via lerp, while keeping its own rotation at identity
+* (GPS-world-aligned).
+*
+* The follower is placed at the scene root (outside arWorldGroup)
+* so its world rotation stays identity regardless of the alignment
+* matrix applied to arWorldGroup. This ensures compass cubes and
+* the map mesh point to true N/E/S/W in the NUE GPS frame.
+*
+* Children of the follower (map mesh, compass cubes) stay
+* flat / world-oriented regardless of camera rotation or
+* orbit / FPS controls.
+*
+* @see docs/2026-03-12-user-feedback.md Issue 8
+*/
+const _worldPos = new THREE.Vector3();
+/**
+* Create a CameraFollower and attach it as a child of the given parent.
+*
+* The parent should be the scene root (not arWorldGroup) so that the
+* follower's world rotation stays identity — ensuring compass directions
+* align with the NUE GPS frame regardless of alignment matrix changes.
+*
+* @param parent   Parent node — should be the scene root.
+* @param lerpRate Lerp speed multiplier (default 8).
+*/
+function createCameraFollower(parent, lerpRate = 8) {
+	const node = new THREE.Object3D();
+	node.name = SCENE_NODE.CAMERA_FOLLOWER;
+	parent.add(node);
+	return {
+		object3D: node,
+		update(camera, dt) {
+			camera.getWorldPosition(_worldPos);
+			const alpha = clampedAlpha(lerpRate, dt);
+			node.position.lerp(_worldPos, alpha);
+		},
+		dispose() {
+			if (node.parent) node.parent.remove(node);
+		}
+	};
+}
+//#endregion
+export { createCameraFollower };

package/dist/visualization/css3d-renderer-manager.d.ts

@@ -0,0 +1,2 @@
+import { n as createCss3dRendererManager, t as Css3dRendererManager } from "../css3d-renderer-manager-rgLMVAvd.js";
+export { Css3dRendererManager, createCss3dRendererManager };

package/dist/visualization/css3d-renderer-manager.js

@@ -0,0 +1,41 @@
+import { CSS3DRenderer } from "three/addons/renderers/CSS3DRenderer.js";
+//#region ../src/visualization/css3d-renderer-manager.ts
+/**
+* Create and configure a CSS3DRenderer overlay for the given container.
+*
+* The CSS3D layer is positioned absolutely over the container with
+* `pointer-events: none` so it does not intercept clicks intended
+* for the WebGL canvas underneath.
+*
+* **Requirement:** The `container` element must have `position: relative`,
+* `absolute`, `fixed`, or `sticky`. If the container is `position: static`
+* (the CSS default), the overlay will float to the nearest positioned
+* ancestor instead of aligning with the container.
+*/
+function createCss3dRendererManager(container, width, height) {
+	const cssRenderer = new CSS3DRenderer();
+	cssRenderer.setSize(width, height);
+	const el = cssRenderer.domElement;
+	el.style.position = "absolute";
+	el.style.top = "0px";
+	el.style.left = "0px";
+	el.style.pointerEvents = "none";
+	container.appendChild(el);
+	let disposed = false;
+	return {
+		render(scene, camera) {
+			if (disposed) return;
+			cssRenderer.render(scene, camera);
+		},
+		setSize(w, h) {
+			cssRenderer.setSize(w, h);
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (el.parentElement) el.parentElement.removeChild(el);
+		}
+	};
+}
+//#endregion
+export { createCss3dRendererManager };

package/dist/visualization/gps-compass-cubes.d.ts

@@ -0,0 +1,2 @@
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-C-6JEnpR.js";
+export { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, GpsCompassCubes, createGpsCompassCubes };

package/dist/visualization/gps-compass-cubes.js

@@ -0,0 +1,129 @@
+import { disposeObject3D } from "./three-dispose.js";
+import { VIS_COLORS } from "./vis-colors.js";
+import * as THREE from "three";
+//#region ../src/visualization/gps-compass-cubes.ts
+/**
+* GPS Compass Cubes Module
+*
+* Creates colored cubes at ±1 m along each axis with text labels
+* (N, E, S, W) to visualize GPS/NUE orientation in the 3D scene.
+*
+* NUE convention: X = North, Y = Up, Z = East.
+*
+* Designed to be added as children of a CameraFollower so they
+* stay near the camera but always GPS-world-aligned.
+*
+* @see docs/2026-03-12-user-feedback.md Issue 8
+*/
+/** Side length of each compass cube in metres. */
+const COMPASS_CUBE_SIZE = .1;
+/** Distance from origin to each compass cube in metres. */
+const COMPASS_CUBE_DISTANCE = 1;
+const CUBE_SPECS = [
+	{
+		name: "compass-north",
+		color: VIS_COLORS.COMPASS_NORTH.hex,
+		position: [
+			1,
+			0,
+			0
+		],
+		label: "N"
+	},
+	{
+		name: "compass-east",
+		color: VIS_COLORS.COMPASS_EAST.hex,
+		position: [
+			0,
+			0,
+			1
+		],
+		label: "E"
+	},
+	{
+		name: "compass-south",
+		color: VIS_COLORS.COMPASS_SOUTH.hex,
+		position: [
+			-1,
+			0,
+			0
+		],
+		label: "S"
+	},
+	{
+		name: "compass-west",
+		color: VIS_COLORS.COMPASS_WEST.hex,
+		position: [
+			0,
+			0,
+			-1
+		],
+		label: "W"
+	},
+	{
+		name: "compass-up",
+		color: VIS_COLORS.COMPASS_UP.hex,
+		position: [
+			0,
+			1,
+			0
+		]
+	}
+];
+/**
+* Create a text sprite from a canvas texture.
+* Uses a 64×64 canvas with centered white text on transparent background.
+*/
+function createTextSprite(text) {
+	const canvas = document.createElement("canvas");
+	canvas.width = 64;
+	canvas.height = 64;
+	const ctx = canvas.getContext("2d");
+	if (ctx) {
+		ctx.clearRect(0, 0, 64, 64);
+		ctx.fillStyle = "#ffffff";
+		ctx.font = "bold 48px sans-serif";
+		ctx.textAlign = "center";
+		ctx.textBaseline = "middle";
+		ctx.fillText(text, 32, 32);
+	}
+	const texture = new THREE.CanvasTexture(canvas);
+	const material = new THREE.SpriteMaterial({
+		map: texture,
+		depthTest: false
+	});
+	const sprite = new THREE.Sprite(material);
+	sprite.name = `label-${text}`;
+	sprite.position.set(0, COMPASS_CUBE_SIZE * 1.5, 0);
+	sprite.scale.set(.4, .4, .4);
+	return sprite;
+}
+/**
+* Create compass cubes and attach them to a parent Object3D.
+*
+* @param parent The Object3D to anchor the compass group to
+*               (typically the CameraFollower).
+*/
+function createGpsCompassCubes(parent) {
+	const group = new THREE.Group();
+	group.name = "gps-compass-cubes";
+	const geometry = new THREE.BoxGeometry(COMPASS_CUBE_SIZE, COMPASS_CUBE_SIZE, COMPASS_CUBE_SIZE);
+	for (const spec of CUBE_SPECS) {
+		const material = new THREE.MeshBasicMaterial({ color: spec.color });
+		const mesh = new THREE.Mesh(geometry, material);
+		mesh.name = spec.name;
+		mesh.position.set(...spec.position);
+		if (spec.label) mesh.add(createTextSprite(spec.label));
+		group.add(mesh);
+	}
+	parent.add(group);
+	return {
+		group,
+		dispose() {
+			if (group.parent) group.parent.remove(group);
+			disposeObject3D(group);
+		}
+	};
+}
+//#endregion
+export { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, createGpsCompassCubes };

package/dist/visualization/gps-event-markers.d.ts

@@ -0,0 +1,2 @@
+import { n as gpsEventVisualizer, t as GpsEventVisualizer } from "../gps-event-markers-DpEy2qRd.js";
+export { GpsEventVisualizer, gpsEventVisualizer };