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

package/dist/tracking-slice-utCNND8t.d.ts

@@ -0,0 +1,86 @@
+import { t as ARPose } from "./ar-types-Ck8LEq8k.js";
+import { OdometryTrackingRestartedPayload, Quaternion, Vector3 } from "gps-plus-slam-js";
+import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
+
+//#region ../src/state/tracking-slice.d.ts
+/**
+ * AR tracking phase. String-literal union (not a TS enum) so action payloads
+ * and replay JSON stay structurally compatible with non-TS consumers.
+ */
+type TrackingPhase = 'initializing' | 'tracking' | 'lost';
+/**
+ * Raw `DeviceOrientationEvent` snapshot captured alongside an AR pose.
+ *
+ * Identical shape to `RawDeviceOrientation` from `gps-plus-slam-js`, but
+ * with non-nullable fields — sensors are required to have resolved for the
+ * AR math that consumes this snapshot.
+ */
+interface DeviceOrientation {
+  /** Compass heading (0–360). */
+  alpha: number;
+  /** Pitch (-180 to 180). */
+  beta: number;
+  /** Roll (-90 to 90). */
+  gamma: number;
+  /** Whether alpha is relative to magnetic north. */
+  absolute: boolean;
+}
+/**
+ * Serialized `XRReferenceSpaceEvent.transform`.
+ *
+ * `null` when the XR runtime cannot determine the delta between old and new
+ * coordinate systems; `undefined` when no transform was captured (older
+ * browsers / no event).
+ */
+interface ResetTransformData {
+  position: Vector3;
+  orientation: Quaternion;
+}
+interface TrackingSliceState {
+  phase: TrackingPhase;
+  lastValidPose: ARPose | null;
+  lastSensorOrientation: DeviceOrientation | null;
+  lostFrameCount: number;
+  originResetDuringLoss: boolean;
+  /**
+   * Distinguishes "reset flagged with no transform yet" from "no reset flagged".
+   * `undefined` is the default; once `originReset(...)` is dispatched the value
+   * is the supplied transform (which may itself be `null`).
+   */
+  resetTransform: ResetTransformData | null | undefined;
+  /**
+   * Transient payload set by the LOST → TRACKING transition when an origin
+   * reset was flagged during the loss. Host consumes it via the matching
+   * selector and then dispatches `clearLastRestartedPayload`.
+   */
+  lastRestartedPayload: OdometryTrackingRestartedPayload | null;
+}
+interface PoseReceivedPayload {
+  pose: ARPose;
+  sensorOrientation: DeviceOrientation;
+}
+declare const poseReceived: _$_reduxjs_toolkit0.ActionCreatorWithPayload<PoseReceivedPayload, "tracking/poseReceived">, poseLost: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"tracking/poseLost">, originReset: _$_reduxjs_toolkit0.ActionCreatorWithPreparedPayload<[transform?: ResetTransformData | null | undefined], ResetTransformData | null | undefined, "tracking/originReset", never, never>, resetTracking: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"tracking/resetTracking">, clearLastRestartedPayload: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"tracking/clearLastRestartedPayload">;
+declare const trackingReducer: _$_reduxjs_toolkit0.Reducer<TrackingSliceState>;
+/**
+ * Minimal root-state shape needed by the selectors. Avoids a hard import
+ * cycle through `SlamAppRootState`.
+ */
+interface RootWithTracking {
+  tracking: TrackingSliceState;
+}
+declare function selectTrackingPhase(state: RootWithTracking): TrackingPhase;
+declare function selectLastValidPose(state: RootWithTracking): ARPose | null;
+declare function selectLostFrameCount(state: RootWithTracking): number;
+declare function selectLastRestartedPayload(state: RootWithTracking): OdometryTrackingRestartedPayload | null;
+/**
+ * Selector for the last `DeviceOrientation` captured alongside a valid
+ * AR pose. Used by the §4.3 compass / alignment heading cross-check in
+ * the tracking-quality reporter (see
+ * docs/2026-05-16-tracking-quality-metrics-plan.md).
+ *
+ * Returns `null` before any pose has been received and after
+ * `resetTracking` clears the slice.
+ */
+declare function selectLastSensorOrientation(state: RootWithTracking): DeviceOrientation | null;
+//#endregion
+export { TrackingSliceState as a, poseLost as c, selectLastRestartedPayload as d, selectLastSensorOrientation as f, trackingReducer as g, selectTrackingPhase as h, TrackingPhase as i, poseReceived as l, selectLostFrameCount as m, PoseReceivedPayload as n, clearLastRestartedPayload as o, selectLastValidPose as p, ResetTransformData as r, originReset as s, DeviceOrientation as t, resetTracking as u };

package/dist/types/ar-types.d.ts

@@ -1,2 +1,2 @@
-import { a as WebXRQuaternion, i as DepthSample, n as ArPoseTuples, o as WebXRVec3, r as DepthPoint, t as ARPose } from "../ar-types-B-ORgk6Z.js";
+import { a as WebXRQuaternion, i as DepthSample, n as ArPoseTuples, o as WebXRVec3, r as DepthPoint, t as ARPose } from "../ar-types-Ck8LEq8k.js";
 export { ARPose, ArPoseTuples, DepthPoint, DepthSample, WebXRQuaternion, WebXRVec3 };

package/dist/types/geo-types.d.ts

@@ -1,2 +1,2 @@
-import { n as RefPointMarker, t as GpsCoord } from "../geo-types-Xx-LVcnw.js";
-export { GpsCoord, RefPointMarker };
+import { n as RawGpsSample, r as RefPointMarker, t as GpsCoord } from "../geo-types-CTuF23gG.js";
+export { GpsCoord, RawGpsSample, RefPointMarker };

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
-import { a as WebXRQuaternion, i as DepthSample, n as ArPoseTuples, o as WebXRVec3, r as DepthPoint, t as ARPose } from "../ar-types-B-ORgk6Z.js";
-import { n as RefPointMarker, t as GpsCoord } from "../geo-types-Xx-LVcnw.js";
-export { ARPose, ArPoseTuples, DepthPoint, DepthSample, GpsCoord, RefPointMarker, WebXRQuaternion, WebXRVec3 };
+import { a as WebXRQuaternion, i as DepthSample, n as ArPoseTuples, o as WebXRVec3, r as DepthPoint, t as ARPose } from "../ar-types-Ck8LEq8k.js";
+import { n as RawGpsSample, r as RefPointMarker, t as GpsCoord } from "../geo-types-CTuF23gG.js";
+export { ARPose, ArPoseTuples, DepthPoint, DepthSample, GpsCoord, RawGpsSample, RefPointMarker, WebXRQuaternion, WebXRVec3 };

package/dist/utils/concurrency.d.ts

@@ -1,2 +1,2 @@
-import { t as mapWithConcurrencyLimit } from "../concurrency-p6gB30fT.js";
+import { t as mapWithConcurrencyLimit } from "../concurrency-CMw8pSaG.js";
 export { mapWithConcurrencyLimit };

package/dist/utils/failure-tracker.d.ts

@@ -1,2 +1,2 @@
-import { n as FailureTrackerConfig, r as createFailureTracker, t as FailureTracker } from "../failure-tracker-1sQ_Cgyw.js";
+import { n as FailureTrackerConfig, r as createFailureTracker, t as FailureTracker } from "../failure-tracker-DnHXOIRa.js";
 export { FailureTracker, FailureTrackerConfig, createFailureTracker };

package/dist/utils/format-file-size.d.ts

@@ -1,2 +1,2 @@
-import { t as formatFileSize } from "../format-file-size-onGq0k1Q.js";
+import { t as formatFileSize } from "../format-file-size-BTS5H62-.js";
 export { formatFileSize };

package/dist/utils/fused-path.d.ts

@@ -1,2 +1,2 @@
-import { n as computeFusedPath, r as fusedGpsFromOdom, t as FusedPathInput } from "../fused-path-DtqCSqJh.js";
+import { n as computeFusedPath, r as fusedGpsFromOdom, t as FusedPathInput } from "../fused-path-CB4DwWOG.js";
 export { FusedPathInput, computeFusedPath, fusedGpsFromOdom };

package/dist/utils/index.d.ts

@@ -1,7 +1,7 @@
-import { a as createLogger, c as setGlobalLogLevel, i as clearLogBuffer, l as subscribeToLogs, n as LogLevel, o as getGlobalLogLevel, r as Logger, s as getLogBuffer, t as LogEntry } from "../logger-B81iwxx0.js";
-import { n as computeFusedPath, r as fusedGpsFromOdom, t as FusedPathInput } from "../fused-path-DtqCSqJh.js";
-import { n as FailureTrackerConfig, r as createFailureTracker, t as FailureTracker } from "../failure-tracker-1sQ_Cgyw.js";
-import { t as mapWithConcurrencyLimit } from "../concurrency-p6gB30fT.js";
-import { t as formatFileSize } from "../format-file-size-onGq0k1Q.js";
-import { t as listFormatter } from "../list-formatter-DKQQVLcl.js";
+import { a as createLogger, c as setGlobalLogLevel, i as clearLogBuffer, l as subscribeToLogs, n as LogLevel, o as getGlobalLogLevel, r as Logger, s as getLogBuffer, t as LogEntry } from "../logger-C9vugiQb.js";
+import { n as computeFusedPath, r as fusedGpsFromOdom, t as FusedPathInput } from "../fused-path-CB4DwWOG.js";
+import { n as FailureTrackerConfig, r as createFailureTracker, t as FailureTracker } from "../failure-tracker-DnHXOIRa.js";
+import { t as mapWithConcurrencyLimit } from "../concurrency-CMw8pSaG.js";
+import { t as formatFileSize } from "../format-file-size-BTS5H62-.js";
+import { t as listFormatter } from "../list-formatter-CNqi-E2j.js";
 export { type FailureTracker, type FailureTrackerConfig, type FusedPathInput, type LogEntry, LogLevel, type Logger, clearLogBuffer, computeFusedPath, createFailureTracker, createLogger, formatFileSize, fusedGpsFromOdom, getGlobalLogLevel, getLogBuffer, listFormatter, mapWithConcurrencyLimit, setGlobalLogLevel, subscribeToLogs };

package/dist/utils/list-formatter.d.ts

@@ -1,2 +1,2 @@
-import { t as listFormatter } from "../list-formatter-DKQQVLcl.js";
+import { t as listFormatter } from "../list-formatter-CNqi-E2j.js";
 export { listFormatter };

package/dist/utils/logger.d.ts

@@ -1,2 +1,2 @@
-import { a as createLogger, c as setGlobalLogLevel, i as clearLogBuffer, l as subscribeToLogs, n as LogLevel, o as getGlobalLogLevel, r as Logger, s as getLogBuffer, t as LogEntry } from "../logger-B81iwxx0.js";
+import { a as createLogger, c as setGlobalLogLevel, i as clearLogBuffer, l as subscribeToLogs, n as LogLevel, o as getGlobalLogLevel, r as Logger, s as getLogBuffer, t as LogEntry } from "../logger-C9vugiQb.js";
 export { LogEntry, LogLevel, Logger, clearLogBuffer, createLogger, getGlobalLogLevel, getLogBuffer, setGlobalLogLevel, subscribeToLogs };

package/dist/utils/logger.js

@@ -12,7 +12,13 @@ import * as Sentry from "@sentry/browser";
 *
 * Sentry Integration:
 * - All log levels add Sentry breadcrumbs for debugging context
-* - log.error() with Error objects automatically reports to Sentry
+* - log.warn() reports a standalone Sentry Issue (captureMessage)
+* - log.error() reports a standalone Sentry Issue: captureException for Error
+*   arguments, or a captureMessage fallback for string-only errors
+* - warn/error Issues are grouped by a normalized message template
+*   (['log', level, tag, template]) so dynamic values (frame indices, sizes,
+*   filenames) collapse into one Issue per message kind without merging
+*   genuinely different messages that share a tag
 */
 /**
 * Log levels in order of verbosity (lower = more verbose)
@@ -180,20 +186,74 @@ function addSentryBreadcrumb(level, tag, args) {
 	});
 }
 /**
+* Normalize a log message body into a stable "template" for Sentry grouping.
+*
+* Replaces the dynamic tokens that typically vary between otherwise-identical
+* log lines (numbers, UUIDs, quoted strings) with placeholders. This makes the
+* fingerprint depend on the *kind* of message rather than its concrete values,
+* so that:
+* - the same message with different dynamic values collapses into one Issue
+*   (e.g. `frame 12` / `frame 87` -> `frame {n}`), and
+* - two genuinely different messages under the same tag stay as separate
+*   Issues (because their templates differ).
+*
+* Order matters: UUIDs are replaced before bare numbers, otherwise the number
+* rule would shred the digit groups inside a UUID first.
+*/
+function toFingerprintTemplate(body) {
+	return body.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "{uuid}").replace(/-?\d+(?:\.\d+)?(?:e[+-]?\d+)?/gi, "{n}").replace(/"[^"]*"/g, "\"{str}\"").replace(/'[^']*'/g, "'{str}'");
+}
+/**
+* Capture a log line as a standalone Sentry Issue (message event).
+*
+* Shared by `reportWarningToSentry` and the string-only branch of
+* `reportErrorsToSentry`. The fingerprint is
+* `['log', level, tag, <normalized template>]` so that dynamic values in the
+* message do not fragment one logical problem into many Issues, while distinct
+* messages from the same tag remain distinct Issues (see
+* {@link toFingerprintTemplate}).
+*/
+function captureLogMessage(level, tag, args) {
+	const body = args.map((arg) => serializeArg(arg)).join(" ");
+	const message = `[${tag}] ${body}`;
+	Sentry.captureMessage(message, {
+		level,
+		fingerprint: [
+			"log",
+			level,
+			tag,
+			toFingerprintTemplate(body)
+		]
+	});
+}
+/**
 * 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");
+	captureLogMessage("warning", tag, args);
 }
 /**
-* Report Error objects to Sentry.
-* Only called for log.error() - other levels just add breadcrumbs.
+* Report log.error() arguments to Sentry as standalone Issues.
+*
+* - For every argument that is an `Error`, calls `captureException` so the
+*   Issue carries a full stack trace.
+* - If NO argument is an `Error` (a string-only `log.error(...)`), falls back
+*   to a message event so the error still surfaces as an Issue instead of only
+*   a breadcrumb/Log.
+*
+* The fallback is mutually exclusive with `captureException` to avoid duplicate
+* Issues when an Error is present, and groups via the same normalized template
+* fingerprint as warnings (see {@link captureLogMessage}).
 */
-function reportErrorsToSentry(args) {
-	for (const arg of args) if (arg instanceof Error) Sentry.captureException(arg);
+function reportErrorsToSentry(tag, args) {
+	let capturedError = false;
+	for (const arg of args) if (arg instanceof Error) {
+		Sentry.captureException(arg);
+		capturedError = true;
+	}
+	if (!capturedError) captureLogMessage("error", tag, args);
 }
 function createLogger(tag) {
 	const prefix = `[${tag}]`;
@@ -217,7 +277,7 @@ function createLogger(tag) {
 		error: (...args) => {
 			addToBuffer(3, tag, args);
 			addSentryBreadcrumb(3, tag, args);
-			reportErrorsToSentry(args);
+			reportErrorsToSentry(tag, args);
 			if (globalLogLevel <= 3) console.error(prefix, ...args);
 		}
 	};

package/dist/visualization/accuracy-circles.d.ts

@@ -0,0 +1,2 @@
+import { a as addAccuracyCircles, i as AccuracyCircleSample, n as ACCURACY_CIRCLE_STROKE_OPACITY, r as ACCURACY_CIRCLE_WEIGHT, t as ACCURACY_CIRCLE_FILL_OPACITY } from "../accuracy-circles-CsxE_7x1.js";
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, AccuracyCircleSample, addAccuracyCircles };

package/dist/visualization/accuracy-circles.js

@@ -0,0 +1,57 @@
+import L from "leaflet";
+//#region ../src/visualization/accuracy-circles.ts
+/**
+* Shared helper for drawing per-event GPS accuracy circles on a Leaflet map.
+*
+* Lives in the app-framework (D4 of the unified-map plan,
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-unified-trajectory-map-phase3-plan.md)
+* so BOTH the framework's shared map-overlay-draw module AND the recorder
+* app's preview/summary maps can reuse it. The recorder's
+* `ui/accuracy-circles.ts` now re-exports from here.
+*
+* Future style changes only need to happen in one place.
+*/
+/**
+* Style for per-event GPS accuracy circles. Radius comes from the GPS event's
+* horizontal accuracy in meters; larger circles mean lower-quality fixes.
+* Filled and stroked with a highly transparent variant of the path color so
+* overlapping circles remain legible without obscuring the basemap or the
+* polyline drawn on top.
+*/
+const ACCURACY_CIRCLE_FILL_OPACITY = .12;
+const ACCURACY_CIRCLE_STROKE_OPACITY = .5;
+const ACCURACY_CIRCLE_WEIGHT = 1;
+/**
+* Draw one transparent circle per sample whose `accuracy` is a finite
+* positive number. Samples without a usable accuracy value are skipped so
+* pre-accuracy recordings still render their polyline.
+*
+* Circles are added to `map` immediately. The caller is responsible for
+* draw-order: invoke this BEFORE adding the polyline so the line stays
+* visually on top of the circles.
+*
+* @param map - The Leaflet map to add circles to.
+* @param samples - GPS samples to consider; non-positive / non-finite
+*   `accuracy` values are silently skipped.
+* @param color - CSS color string used for both stroke and fill.
+* @returns The created `L.Circle` instances, in the order they were added.
+*   Callers that track layers for cleanup can append these to their list.
+*/
+function addAccuracyCircles(map, samples, color) {
+	const circles = [];
+	for (const sample of samples) {
+		if (typeof sample.accuracy !== "number" || !Number.isFinite(sample.accuracy) || sample.accuracy <= 0) continue;
+		const circle = L.circle([sample.lat, sample.lng], {
+			radius: sample.accuracy,
+			color,
+			weight: 1,
+			opacity: ACCURACY_CIRCLE_STROKE_OPACITY,
+			fillColor: color,
+			fillOpacity: ACCURACY_CIRCLE_FILL_OPACITY
+		}).addTo(map);
+		circles.push(circle);
+	}
+	return circles;
+}
+//#endregion
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, addAccuracyCircles };

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

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

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

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

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

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

package/dist/visualization/frustum-visibility.d.ts

@@ -0,0 +1,2 @@
+import { i as isSphereInCameraFrustum, n as isObjectInCameraFrustum, r as isPointInCameraFrustum, t as buildCameraFrustum } from "../frustum-visibility-BHnFrSKQ.js";
+export { buildCameraFrustum, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum };

package/dist/visualization/frustum-visibility.js

@@ -0,0 +1,139 @@
+import * as THREE from "three";
+//#region ../src/visualization/frustum-visibility.ts
+/**
+* Frustum-visibility predicates used by GPS-anchored components and any other
+* caller that needs to know whether a world-space point/sphere/object is
+* currently visible to a camera. Three.js's `Frustum` has the primitives we
+* need; this module wraps them so:
+*
+*  - All three predicates share a module-level scratch `Frustum`/`Matrix4`
+*    so a single frame's worth of checks pays the matrix multiply once.
+*  - Each predicate accepts an optional `frustum` parameter for callers that
+*    already have one built (e.g. via `buildCameraFrustum`) and want to
+*    keep doing many checks against it without rebuilding.
+*
+* The Three.js convention here is that `Frustum.containsPoint` is strict
+* (point must be inside all six planes) while `intersectsSphere`/
+* `intersectsObject` accept overlap with any plane, which is the right
+* notion for "is this object at least partially on screen".
+*/
+const scratchMatrix = new THREE.Matrix4();
+const scratchFrustum = new THREE.Frustum();
+/**
+* Build (or refresh) a Three.js `Frustum` from `camera`'s current world
+* transform and projection matrix. If `out` is provided, the frustum is
+* written into it and returned; otherwise the module-level scratch frustum
+* is used. Callers MUST treat the returned frustum as immutable until they
+* next call this function or use one of the predicates without an injected
+* frustum (both reuse the same scratch).
+*/
+function buildCameraFrustum(camera, out) {
+	scratchMatrix.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+	const target = out ?? scratchFrustum;
+	target.setFromProjectionMatrix(scratchMatrix);
+	return target;
+}
+/**
+* Strictly check whether a single world-space point lies inside all six
+* frustum planes. Useful for HUD/follow logic where the caller already has
+* the target world position and wants the cheapest possible check.
+*/
+function isPointInCameraFrustum(camera, point, frustum) {
+	return (frustum ?? buildCameraFrustum(camera)).containsPoint(point);
+}
+/**
+* Check whether a world-space bounding sphere intersects the camera frustum
+* (returns true even for partial overlap). Useful for callers that maintain
+* a precomputed bounding sphere (LOD systems, instanced meshes, future
+* `ArPowerSaver`).
+*/
+function isSphereInCameraFrustum(camera, sphere, frustum) {
+	return (frustum ?? buildCameraFrustum(camera)).intersectsSphere(sphere);
+}
+const objectScratchSphere = new THREE.Sphere();
+const objectScratchBox = new THREE.Box3();
+const objectScratchVec = new THREE.Vector3();
+/**
+* Check whether an `Object3D` is currently (at least partially) inside the
+* camera frustum. The world bounding volume is resolved in tiers, cheapest
+* first, so each common Three.js object type is gated by where it actually
+* draws:
+*
+*  1. **Sprites** (`isSprite`) are screen-space billboards with no meaningful
+*     world geometry, so their world-space origin is tested as a point.
+*  2. **Objects carrying an object-level `boundingSphere`** (`InstancedMesh`,
+*     `SkinnedMesh`, or any caller that pre-populates one) use that sphere,
+*     which reflects the instance spread / posed extent — unlike the base
+*     geometry sphere. It is computed lazily via `computeBoundingSphere()`
+*     when missing.
+*  3. **Single renderables carrying a `geometry`** (`Mesh`, `Points`, `Line`,
+*     …) use the geometry's local bounding sphere × `matrixWorld`.
+*  4. **Containers with children** (`Group`, `LOD`, …) use the world-space
+*     union of their descendants' bounding boxes (`Box3.setFromObject`),
+*     converted to a sphere.
+*  5. **Truly empty / geometry-less objects** have no bounding volume and are
+*     treated as visible (`true`) — the conservative default for visibility
+*     gating.
+*
+* This deliberately avoids `Frustum.intersectsObject`, which unconditionally
+* dereferences `object.geometry.boundingSphere` and therefore throws a
+* `TypeError` for geometry-less objects such as `Group`s.
+*
+* Callers should ensure `object.updateMatrixWorld()` (with descendants, for
+* containers: `updateMatrixWorld(true)`) has already run this frame (it
+* normally has, via `renderer.render`).
+*/
+function isObjectInCameraFrustum(camera, object, frustum) {
+	const f = frustum ?? buildCameraFrustum(camera);
+	if (object.isSprite) {
+		object.getWorldPosition(objectScratchVec);
+		return f.containsPoint(objectScratchVec);
+	}
+	if (!resolveObjectWorldSphere(object, objectScratchSphere)) return true;
+	return f.intersectsSphere(objectScratchSphere);
+}
+/**
+* Resolve the world-space bounding sphere for `object` into `out`, returning
+* `true` when a bounding volume was found and `false` for objects that have
+* none (e.g. an empty `Group`). Resolution order mirrors the tiers documented
+* on {@link isObjectInCameraFrustum}: object-level `boundingSphere`
+* (`InstancedMesh`/`SkinnedMesh`), then geometry bounding sphere, then the
+* world-space union of descendant bounding boxes.
+*/
+function resolveObjectWorldSphere(object, out) {
+	if (tryObjectLevelSphere(object, out)) return true;
+	const geometry = object.geometry;
+	if (geometry) {
+		if (!geometry.boundingSphere) geometry.computeBoundingSphere();
+		if (geometry.boundingSphere) {
+			out.copy(geometry.boundingSphere).applyMatrix4(object.matrixWorld);
+			return true;
+		}
+	}
+	if (object.children.length > 0) {
+		objectScratchBox.setFromObject(object);
+		if (!objectScratchBox.isEmpty()) {
+			objectScratchBox.getBoundingSphere(out);
+			return true;
+		}
+	}
+	return false;
+}
+/**
+* Tier 2 of {@link resolveObjectWorldSphere}: use an object-level
+* `boundingSphere` when the object is an `InstancedMesh`/`SkinnedMesh` (whose
+* sphere reflects instance spread / posed extent) or already carries a
+* populated sphere. Computes it lazily via `computeBoundingSphere()` when
+* missing. Writes the world-space sphere into `out` and returns `true` on
+* success, `false` when no object-level sphere applies.
+*/
+function tryObjectLevelSphere(object, out) {
+	const withSphere = object;
+	if (!(withSphere.isInstancedMesh || withSphere.isSkinnedMesh || withSphere.boundingSphere)) return false;
+	if (!withSphere.boundingSphere && typeof withSphere.computeBoundingSphere === "function") withSphere.computeBoundingSphere();
+	if (!withSphere.boundingSphere) return false;
+	out.copy(withSphere.boundingSphere).applyMatrix4(object.matrixWorld);
+	return true;
+}
+//#endregion
+export { buildCameraFrustum, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum };

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

@@ -0,0 +1,2 @@
+import { a as GpsAnchorSamplePoint, i as GpsAnchorPhase, n as GpsAnchorMode, o as createGpsAnchor, r as GpsAnchorOptions, t as GpsAnchor } from "../gps-anchor-CnWY61XK.js";
+export { GpsAnchor, GpsAnchorMode, GpsAnchorOptions, GpsAnchorPhase, GpsAnchorSamplePoint, createGpsAnchor };

package/dist/visualization/gps-anchor.js

@@ -0,0 +1,2 @@
+import { t as createGpsAnchor } from "../gps-anchor-DjC_3MoT.js";
+export { createGpsAnchor };

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

@@ -1,2 +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";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-CsLtFv4B.js";
 export { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, GpsCompassCubes, createGpsCompassCubes };

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

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

package/dist/visualization/gps-event-markers.js

@@ -25,6 +25,38 @@ const GPS_MARKER_RADIUS = .08;
 /** Slightly larger radius for alignment snapshots to stand out */
 const SNAPSHOT_MARKER_RADIUS = .1;
 /**
+* Default opacity for the yellow raw-GPS sphere when it is rendered at the
+* legacy fixed 8 cm radius (no accuracy passed). Matches the original 30 %
+* value so live recording sessions look unchanged.
+*/
+const RAW_GPS_FIXED_OPACITY = .3;
+/**
+* Reduced opacity for the yellow raw-GPS sphere when it is scaled by GPS
+* accuracy (replay mode). At metre-scale ellipsoids the sphere can land on
+* top of the cyan fused / red snapshot markers; a lower alpha keeps those
+* smaller markers visible inside the ellipsoid.
+*/
+const RAW_GPS_ACCURACY_OPACITY = .13;
+/**
+* Validate a {@link GpsEventAccuracy} hint and return the concrete
+* {horizontal, vertical} scale when both axes are usable, or `null` to signal
+* "fall back to the legacy fixed 8 cm sphere". A half-populated, non-positive,
+* or non-finite (`NaN`/`Infinity`) accuracy must NOT produce an ellipsoid:
+* a degenerate or infinite axis would corrupt the mesh transform and can
+* crash Three.js rendering.
+*/
+function resolveEllipsoidScale(accuracy) {
+	if (accuracy == null) return null;
+	const { horizontal, vertical } = accuracy;
+	if (typeof horizontal !== "number" || typeof vertical !== "number") return null;
+	if (!Number.isFinite(horizontal) || !Number.isFinite(vertical)) return null;
+	if (horizontal <= 0 || vertical <= 0) return null;
+	return {
+		horizontal,
+		vertical
+	};
+}
+/**
 * Manager for GPS event visualization
 */
 var GpsEventVisualizer = class {
@@ -55,8 +87,14 @@ var GpsEventVisualizer = class {
 	*
 	* @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, odomPosition) {
+	addGpsEvent(gpsCoords, odomPosition, accuracy) {
 		if (!this.zeroRef) {
 			log.warn("No zero reference set");
 			return;
@@ -67,8 +105,13 @@ var GpsEventVisualizer = class {
 			return;
 		}
 		const eventId = this.eventCounter++;
-		const rawMesh = this.createMarkerMesh(VIS_COLORS.RAW_GPS.hex, "raw-gps", eventId);
+		const ellipsoidScale = resolveEllipsoidScale(accuracy);
+		const rawMesh = this.createMarkerMesh(VIS_COLORS.RAW_GPS.hex, "raw-gps", eventId, ellipsoidScale ? 1 : GPS_MARKER_RADIUS, ellipsoidScale ? RAW_GPS_ACCURACY_OPACITY : RAW_GPS_FIXED_OPACITY);
 		rawMesh.position.set(gpsCoords[0], gpsCoords[1], gpsCoords[2]);
+		if (ellipsoidScale) {
+			rawMesh.scale.set(ellipsoidScale.horizontal, ellipsoidScale.vertical, ellipsoidScale.horizontal);
+			rawMesh.renderOrder = -1;
+		}
 		scene.add(rawMesh);
 		this.rawGpsMarkers.push(rawMesh);
 		const arWorldGroup = getArWorldGroup();
@@ -149,6 +192,30 @@ var GpsEventVisualizer = class {
 			snapshots: this.snapshotMarkers.length
 		};
 	}
+	/**
+	* 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() {
+		const tmpBox = new THREE.Box3();
+		return this.rawGpsMarkers.map((mesh) => {
+			tmpBox.setFromObject(mesh);
+			const size = tmpBox.getSize(new THREE.Vector3());
+			return {
+				x: size.x,
+				y: size.y,
+				z: size.z
+			};
+		});
+	}
 };
 /**
 * Singleton instance for global use.

package/dist/visualization/index.d.ts

@@ -1,12 +1,17 @@
-import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-BMqPddxx.js";
-import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-D9BeDwZX.js";
-import { n as createCss3dRendererManager, t as Css3dRendererManager } from "../css3d-renderer-manager-rgLMVAvd.js";
-import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-C-6JEnpR.js";
-import { n as gpsEventVisualizer, t as GpsEventVisualizer } from "../gps-event-markers-DpEy2qRd.js";
-import { a as DEFAULT_Z_OFFSET, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions } from "../leaflet-map-overlay-CvfQXTye.js";
-import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-87NWjUOD.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-DuiZuCTx.js";
-import { n as refPointVisualizer, t as RefPointVisualizer } from "../reference-points-CFWy8_wj.js";
-import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-CCBHjE_a.js";
-import { t as VIS_COLORS } from "../vis-colors-Qi2vlRGt.js";
-export { type AlignmentLerper, COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, type CameraFollower, type Css3dRendererManager, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, type DisposeOptions, type GpsCompassCubes, GpsEventVisualizer, LeafletMapOverlay, type LeafletMapOverlayOptions, MapOverlay, type MapOverlayOptions, RefPointVisualizer, type TextureLoaderInterface, VIS_COLORS, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsCompassCubes, disposeMeshArray, disposeObject3D, gpsEventVisualizer, latLonToTileXY, refPointVisualizer, tileXYToLatLon };
+import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-1k8mnw5J.js";
+import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-L1RbWHQ4.js";
+import { n as createCss3dRendererManager, t as Css3dRendererManager } from "../css3d-renderer-manager-CkjCb2HW.js";
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-sih4g64v.js";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-CsLtFv4B.js";
+import { i as isSphereInCameraFrustum, n as isObjectInCameraFrustum, r as isPointInCameraFrustum, t as buildCameraFrustum } from "../frustum-visibility-BHnFrSKQ.js";
+import { t as nueToArLocal } from "../index-pOjUCKEP.js";
+import { a as GpsAnchorSamplePoint, i as GpsAnchorPhase, n as GpsAnchorMode, o as createGpsAnchor, r as GpsAnchorOptions, t as GpsAnchor } from "../gps-anchor-CnWY61XK.js";
+import { n as GpsEventVisualizer, r as gpsEventVisualizer } from "../gps-event-markers-BGr-iLvi.js";
+import { a as DEFAULT_Z_OFFSET, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions } from "../leaflet-map-overlay-Cew7XAoO.js";
+import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-B8MM8zCR.js";
+import { a as addAccuracyCircles, i as AccuracyCircleSample, n as ACCURACY_CIRCLE_STROKE_OPACITY, r as ACCURACY_CIRCLE_WEIGHT, t as ACCURACY_CIRCLE_FILL_OPACITY } from "../accuracy-circles-CsxE_7x1.js";
+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";
+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";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-C2drkp6f.js";
+import { t as VIS_COLORS } from "../vis-colors-CHQhjal3.js";
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, ALIGNMENT_SNAPSHOT_COLOR, AccuracyCircleSample, AlignmentLerper, COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, CameraFollower, Css3dRendererManager, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, DisposeOptions, DrawMapDataOptions, DrawnMapData, FUSED_PATH_COLOR, GpsAnchor, GpsAnchorMode, GpsAnchorOptions, GpsAnchorPhase, GpsAnchorSamplePoint, GpsCompassCubes, GpsEventVisualizer, LeafletMapOverlay, LeafletMapOverlayOptions, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, MapData, MapDataInput, MapOverlay, MapOverlayOptions, RAW_GPS_COLOR, TextureLoaderInterface, USER_POSITION_COLOR, VIS_COLORS, addAccuracyCircles, buildCameraFrustum, buildMapData, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsAnchor, createGpsCompassCubes, disposeMeshArray, disposeObject3D, drawMapData, gpsEventVisualizer, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum, latLonToTileXY, nueToArLocal, tileXYToLatLon };