gps-plus-slam-app-framework 1.0.6 → 1.1.0

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-BZ44Dhd3.js";
+import { n as computeFusedPath, r as fusedGpsFromOdom, t as FusedPathInput } from "../fused-path-BdVHmDW9.js";
+import { n as FailureTrackerConfig, r as createFailureTracker, t as FailureTracker } from "../failure-tracker-D7ELffm0.js";
+import { t as mapWithConcurrencyLimit } from "../concurrency-Bsmv53qw.js";
+import { t as formatFileSize } from "../format-file-size-B7gJb3Md.js";
+import { t as listFormatter } from "../list-formatter-CsqcU4v5.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-CsqcU4v5.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-BZ44Dhd3.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-DEKr0Hoh.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-CCZJf-Xb.js";
 export { AlignmentLerper, createAlignmentLerper };

package/dist/visualization/ar-world-group-alignment.d.ts

@@ -0,0 +1,2 @@
+import { n as ArWorldGroupAlignmentOptions, r as enableArWorldGroupAlignment, t as ArWorldGroupAlignmentHandle } from "../ar-world-group-alignment-Dn4rQk_c.js";
+export { ArWorldGroupAlignmentHandle, ArWorldGroupAlignmentOptions, enableArWorldGroupAlignment };

package/dist/visualization/ar-world-group-alignment.js

@@ -0,0 +1,51 @@
+import { registerFrameUpdate } from "../ar/frame-loop.js";
+import { t as registerSessionDisposer } from "../session-disposers-M-oashRH.js";
+import { createAlignmentLerper } from "./alignment-lerper.js";
+import { selectAlignmentMatrix } from "../state/app-selectors.js";
+import { subscribeToSelector } from "../state/subscribe-to-selector.js";
+//#region ../src/visualization/ar-world-group-alignment.ts
+/**
+* Begin applying the store's (lerped) alignment to `arWorldGroup`. Returns a
+* handle whose `dispose()` removes both the store subscription and the
+* per-frame update.
+*
+* Disposal is tied to the AR session lifecycle: the binding registers itself
+* with the session-disposer registry that `resetWebXRState()` flushes on
+* teardown, so a caller can `enableArWorldGroupAlignment(...)` once and never
+* hold the handle — the binding cannot outlive the session (which is what two
+* apps independently leaked: the store subscription survives a teardown because
+* `clearFrameUpdates` only drops the per-frame tick). Because `initAR()` throws
+* while a prior session is live, every restart passes through that flush. The
+* handle is still returned for callers that want to stop alignment mid-session,
+* and is idempotent + self-deregistering so a manual `dispose()` and the
+* teardown flush never double-run. See
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-08-arworldgroup-alignment-session-scoped-disposal.md.
+*
+* Double-drive is still the caller's concern: the recorder owns its own lerper
+* and must NOT also call this (it would double-lerp the same group). It does not
+* call this helper, so flushing the registry on teardown never affects it.
+*/
+function enableArWorldGroupAlignment(options) {
+	const lerper = createAlignmentLerper(options.arWorldGroup, options.lerpRate);
+	const current = selectAlignmentMatrix(options.store.getState());
+	if (current !== null && current !== void 0) lerper.setTarget(current);
+	const unsubscribe = subscribeToSelector(options.store, selectAlignmentMatrix, (matrix) => {
+		if (matrix !== null && matrix !== void 0) lerper.setTarget(matrix);
+	});
+	const unregister = registerFrameUpdate((dt) => {
+		lerper.update(dt);
+	});
+	let disposed = false;
+	const handle = { dispose() {
+		if (disposed) return;
+		disposed = true;
+		unsubscribe();
+		unregister();
+		lerper.dispose();
+		deregisterSessionDisposer();
+	} };
+	const deregisterSessionDisposer = registerSessionDisposer(() => handle.dispose());
+	return handle;
+}
+//#endregion
+export { enableArWorldGroupAlignment };

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-B-nS1sr6.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-EDED3nvg.js";
 export { Css3dRendererManager, createCss3dRendererManager };

package/dist/visualization/frame-conversions.d.ts

@@ -0,0 +1,2 @@
+import { n as worldNueToGps, t as nueToArLocal } from "../frame-conversions-D2EYjeNa.js";
+export { nueToArLocal, worldNueToGps };

package/dist/visualization/frame-conversions.js

@@ -0,0 +1,88 @@
+import { calcGpsCoords } from "../core/index.js";
+import * as THREE from "three";
+//#region ../src/visualization/frame-conversions.ts
+/**
+* `frame-conversions` — small, pure coordinate-frame helpers for the AR scene
+* graph. Currently a single function, `nueToArLocal`, that converts a
+* GPS-world NUE point into the AR-odometry local frame of `arWorldGroup`.
+*
+* Background: the scene root is GPS-world NUE; `arWorldGroup.matrix` IS the
+* alignment matrix, which maps **AR-odometry NUE → GPS-world NUE**. So a
+* direct child of `arWorldGroup` whose WORLD position must equal a GPS-world
+* point `nue` has to store `alignment⁻¹ · nue` as its LOCAL position —
+* writing raw `nue` double-applies the alignment. Getting this wrong was the
+* alignment-frame bug
+* (gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md);
+* this helper centralises the conversion behind one tested, well-named seam.
+*
+* Design (see the plan
+* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-nue-to-ar-local-helper-plan.md):
+*  - **Takes the explicit alignment matrix array**, NOT `Object3D.worldToLocal`.
+*    `worldToLocal` would read the live, mid-lerp `matrixWorld` and break
+*    replay determinism; the explicit target matrix keeps the result a pure
+*    function of its inputs. Full rationale in the review doc
+*    (gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-worldtolocal-frame-helper-review.md).
+*  - **Positions only.** No pose/quaternion variant exists until a caller
+*    needs one (YAGNI). No caller currently sets a GPS-world rotation.
+*/
+const scratchMatrix = new THREE.Matrix4();
+/**
+* Convert a GPS-world NUE point into the AR-local position to write into a
+* direct child of `arWorldGroup`, given the current alignment matrix.
+*
+* Computes `alignment⁻¹ · nue`. When the result is later composed back by the
+* group's matrix (the same `alignment`), the child's WORLD position equals
+* `nue` exactly.
+*
+* @param alignment - The alignment matrix as a 16-element **column-major**
+*   array (AR-odometry NUE → GPS-world NUE), e.g. from `getAlignmentMatrix()`
+*   or `THREE.Matrix4.toArray()`. Not mutated.
+* @param nue - The GPS-world NUE point `[north, up, east]` in metres. Not
+*   mutated.
+* @param out - Optional target vector to write into and return (pass a reused
+*   scratch to avoid allocation on hot paths). Defaults to a fresh
+*   `THREE.Vector3`.
+* @returns `out`, set to the AR-local position.
+*/
+function nueToArLocal(alignment, nue, out = new THREE.Vector3()) {
+	scratchMatrix.fromArray(alignment).invert();
+	return out.set(nue[0], nue[1], nue[2]).applyMatrix4(scratchMatrix);
+}
+/**
+* Convert an object's **GPS-world NUE world position** back into a GPS
+* coordinate, for the GPS-anchor bootstrap that medians where an object was
+* actually placed (mirrors the C# `DetermineAndStoreGpsWorldPose`, which
+* medians the object's world pose and converts via `zero.CalcGpsCoordsOf`).
+*
+* Precondition: `worldNue` must already be in GPS-world NUE — i.e. the object
+* lives under an `arWorldGroup` whose `.matrix` carries the alignment (see
+* `enableArWorldGroupAlignment`), so `object3D.getWorldPosition()` is the
+* GPS-world position. Sampling a pure-VIO (identity-`arWorldGroup`) world
+* position would yield a wrong GPS coordinate.
+*
+* Altitude round-trip: `calcGpsCoords` returns only `lat`/`lon` (it derives
+* them from the North/East axes and ignores Up). The Up axis (`worldNue.y`,
+* NUE index 1) is carried through verbatim as `altitude`, so a later
+* `calcRelativeCoordsInMeters(zero, result, result.altitude, 0)` reproduces the
+* same Up value — keeping the steady-state vertical target consistent with
+* where the object was sampled.
+*
+* @param worldNue - The object's world position in GPS-world NUE metres
+*   (`x = North`, `y = Up`, `z = East`). A `THREE.Vector3` satisfies this.
+* @param zero - The GPS zero reference (origin for the conversion).
+* @returns The GPS coordinate of `worldNue`, with `altitude = worldNue.y`.
+*/
+function worldNueToGps(worldNue, zero) {
+	const gps = calcGpsCoords(zero, [
+		worldNue.x,
+		worldNue.y,
+		worldNue.z
+	]);
+	return {
+		lat: gps.lat,
+		lon: gps.lon,
+		altitude: worldNue.y
+	};
+}
+//#endregion
+export { nueToArLocal, worldNueToGps };

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-DGnJqls0.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-CISLPQIb.js";
+export { GpsAnchor, GpsAnchorMode, GpsAnchorOptions, GpsAnchorPhase, GpsAnchorSamplePoint, createGpsAnchor };