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

package/dist/visualization/gps-anchor.js

@@ -1,2 +1,217 @@
-import { t as createGpsAnchor } from "../gps-anchor-DjC_3MoT.js";
+import { registerFrameUpdate } from "../ar/frame-loop.js";
+import { isObjectInCameraFrustum } from "./frustum-visibility.js";
+import { calcRelativeCoordsInMeters } from "../core/index.js";
+import { nueToArLocal } from "./frame-conversions.js";
+import * as THREE from "three";
+//#region ../src/visualization/gps-anchor.ts
+/**
+* `createGpsAnchor` — GPS-anchored placement of a single `THREE.Object3D`.
+*
+* See the colocated sidecar (`gps-anchor.ts.md`) and the port plan at
+* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-13-gps-anchor-port-plan.md`
+* for the full design, state machine, and test matrix.
+*
+* This file implements sub-steps 2 (bootstrap phase), 3 (steady-state
+* `'snap-every-tick'` + distance-scaled threshold gate), and 4
+* (`'snap-when-offscreen'` mode gate, with a one-time initial-placement
+* exemption for `skipBootstrap` anchors). Floor-Y correction is sub-step
+* 6 and remains deferred.
+*/
+/**
+* Module-level registry of objects currently owned by a `GpsAnchor`.
+* Used to detect nested anchors (parent + child both anchored) which
+* we explicitly forbid; mirrors the C# invariant.
+*/
+const anchoredObjects = /* @__PURE__ */ new WeakSet();
+function isObjectInAnchoredChain(object) {
+	let cursor = object;
+	while (cursor) {
+		if (anchoredObjects.has(cursor)) return true;
+		cursor = cursor.parent;
+	}
+	return false;
+}
+/**
+* Returns true iff `object` is `arWorldGroup` itself or a descendant of it.
+* The anchor's `object3D` MUST satisfy this: only then does it ride the
+* alignment applied to `arWorldGroup.matrix` (the node the camera also lives
+* under) via scene-graph propagation. An anchor parented to the scene root
+* instead never receives the alignment, so each steady-state re-registration
+* snaps the full alignment delta and the object visibly slides as the user
+* moves — the exact instability the anchor exists to prevent.
+*/
+function isDescendantOf(object, arWorldGroup) {
+	let cursor = object;
+	while (cursor) {
+		if (cursor === arWorldGroup) return true;
+		cursor = cursor.parent;
+	}
+	return false;
+}
+function median(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2;
+	return sorted[mid];
+}
+function medianPoint(samples) {
+	const lat = median(samples.map((s) => s.lat));
+	const lon = median(samples.map((s) => s.lon));
+	const alts = samples.map((s) => "altitude" in s ? s.altitude : void 0).filter((a) => typeof a === "number");
+	if (alts.length > 0) return {
+		lat,
+		lon,
+		altitude: median(alts)
+	};
+	return {
+		lat,
+		lon
+	};
+}
+function createGpsAnchor(options) {
+	if (isObjectInAnchoredChain(options.object3D)) throw new Error("createGpsAnchor: nested GpsAnchors are not supported — the supplied object3D is already inside an anchored parent chain.");
+	if (!isDescendantOf(options.object3D, options.arWorldGroup)) throw new Error("createGpsAnchor: object3D must be a descendant of arWorldGroup (the alignment-bearing node the camera lives under); parenting an anchor to the scene root defeats AR stability.");
+	anchoredObjects.add(options.object3D);
+	const sampleCount = options.secondsToAccumulateGpsPose ?? 7;
+	if (sampleCount < 1) {
+		anchoredObjects.delete(options.object3D);
+		throw new Error("createGpsAnchor: secondsToAccumulateGpsPose must be >= 1 — use skipBootstrap:true to bypass the accumulation phase.");
+	}
+	const settlingSeconds = options.settlingSeconds ?? 0;
+	const distanceThreshold = options.distanceThreshold ?? 2;
+	options.angleThresholdInDegrees;
+	const mode = options.mode ?? "snap-when-offscreen";
+	const scratchTarget = new THREE.Vector3();
+	const scratchCamWorld = new THREE.Vector3();
+	const scratchObjWorld = new THREE.Vector3();
+	let phase = options.skipBootstrap === true ? "anchored" : "bootstrap";
+	let isFullyAnchored = phase === "anchored";
+	let gpsPoint = options.gpsPoint;
+	let phaseEnteredAtElapsed = null;
+	let lastSampleAtElapsed = null;
+	const samples = [];
+	/**
+	* The one-time "initial placement" exemption from the `snap-when-offscreen`
+	* frustum gate. A `skipBootstrap` anchor is `anchored` from frame one but its
+	* `object3D` still sits at the AR origin (local 0,0,0 — "inside the user")
+	* until its first steady-state commit. That first commit MUST land even while
+	* the object is on-screen, otherwise the marker stays stuck at the origin
+	* until the user happens to look away. A fresh appearance is not a "jump", so
+	* it is exempt. Consumed (set false) by the first committed correction; never
+	* re-armed (a re-bootstrap moves an already-placed object, so its later
+	* corrections are normal gated snaps). Anchors that bootstrap are placed at
+	* their seed pose by the host, so they never need this exemption — hence it is
+	* armed only for `skipBootstrap`.
+	*/
+	let firstCommitPending = options.skipBootstrap === true;
+	const enterBootstrap = () => {
+		phase = "bootstrap";
+		isFullyAnchored = false;
+		phaseEnteredAtElapsed = null;
+		lastSampleAtElapsed = null;
+		samples.length = 0;
+	};
+	const commitMedian = () => {
+		gpsPoint = medianPoint(samples);
+		phase = "anchored";
+		isFullyAnchored = true;
+		samples.length = 0;
+		options.onBootstrapComplete?.(gpsPoint);
+	};
+	/**
+	* Steady-state: compute the GPS-world NUE target from the stored
+	* `gpsPoint` and the current `zeroRef`, map it into `arWorldGroup`'s
+	* AR-local frame via the inverse alignment matrix, and commit it to
+	* `object3D.position` iff the (AR-local) position delta exceeds the
+	* distance-scaled threshold AND the mode gate allows it.
+	*
+	* Mode gate: in `'snap-when-offscreen'` a correction is suppressed while the
+	* object is inside the camera frustum — corrections only land when the user
+	* is not looking, so the anchor never visibly jumps. The whole AR frame
+	* (camera + every anchor) rides one lerped `arWorldGroup.matrix`
+	* (`enableArWorldGroupAlignment`), so an on-screen alignment change is
+	* absorbed smoothly for the entire view and never needs a per-anchor
+	* on-screen snap. The one exception is the first placement of a `skipBootstrap`
+	* anchor (see `firstCommitPending`), which must escape the origin even while
+	* on-screen. See
+	* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-06-anchor-starter-cachehit-jump-investigation.md`.
+	*
+	* Frame note: `arWorldGroup.matrix` IS the alignment matrix, which maps
+	* **AR-odometry NUE → GPS-world NUE**. `object3D.position` is a *local*
+	* transform in that AR-odometry frame. To make the object's *world*
+	* position equal the GPS-world `nue`, the local target must be
+	* `alignment⁻¹ · nue` — writing raw `nue` would double-apply the
+	* alignment (world = `alignment · nue`). See
+	* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md`.
+	*
+	* Returns silently on missing inputs (no `zeroRef`, or no alignment
+	* matrix yet — an AR-local object cannot be placed without knowing the
+	* AR↔NUE transform).
+	*/
+	const maybeCommitSteadyState = () => {
+		const zero = options.getGpsZeroRef();
+		if (zero === null || zero === void 0) return;
+		const currentAlignment = options.getAlignmentMatrix();
+		if (currentAlignment === null || currentAlignment === void 0) return;
+		const targetAlt = "altitude" in gpsPoint && typeof gpsPoint.altitude === "number" ? gpsPoint.altitude : 0;
+		const nue = calcRelativeCoordsInMeters(zero, gpsPoint, targetAlt, 0);
+		nueToArLocal(currentAlignment, [
+			nue[0],
+			nue[1],
+			nue[2]
+		], scratchTarget);
+		options.camera.getWorldPosition(scratchCamWorld);
+		options.object3D.getWorldPosition(scratchObjWorld);
+		const scale = 1 + 10 * scratchCamWorld.distanceTo(scratchObjWorld) / 100;
+		if (options.object3D.position.distanceTo(scratchTarget) >= distanceThreshold * scale) {
+			if (!(mode === "snap-when-offscreen" && !firstCommitPending && isObjectInCameraFrustum(options.camera, options.object3D))) {
+				options.object3D.position.copy(scratchTarget);
+				firstCommitPending = false;
+			}
+		}
+	};
+	const tick = (_dt, elapsed) => {
+		if (phase === "anchored") {
+			maybeCommitSteadyState();
+			return;
+		}
+		if (phaseEnteredAtElapsed === null) {
+			phaseEnteredAtElapsed = elapsed;
+			lastSampleAtElapsed = elapsed - 1;
+		}
+		if (elapsed - phaseEnteredAtElapsed < settlingSeconds) return;
+		if (lastSampleAtElapsed !== null && elapsed - lastSampleAtElapsed < 1) return;
+		const sample = options.getCurrentGpsPoint();
+		if (sample === null || sample === void 0) return;
+		samples.push(sample);
+		lastSampleAtElapsed = elapsed;
+		if (samples.length >= sampleCount) commitMedian();
+	};
+	const unregister = registerFrameUpdate(tick);
+	return {
+		get phase() {
+			return phase;
+		},
+		get isFullyAnchored() {
+			return isFullyAnchored;
+		},
+		get gpsPoint() {
+			return gpsPoint;
+		},
+		markMovedExternally() {
+			enterBootstrap();
+		},
+		setGpsPoint(point) {
+			gpsPoint = point;
+		},
+		dispose() {
+			unregister();
+			anchoredObjects.delete(options.object3D);
+		},
+		__tickForTests(dt, elapsed) {
+			tick(dt, elapsed);
+		}
+	};
+}
+//#endregion
 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-CsLtFv4B.js";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-BM1uGiYV.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, r as gpsEventVisualizer, t as GpsEventAccuracy } from "../gps-event-markers-BGr-iLvi.js";
+import { n as GpsEventVisualizer, r as gpsEventVisualizer, t as GpsEventAccuracy } from "../gps-event-markers-Dc9FT-q1.js";
 export { GpsEventAccuracy, GpsEventVisualizer, gpsEventVisualizer };

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

@@ -1,6 +1,6 @@
 import { createLogger } from "../utils/logger.js";
 import { disposeMeshArray } from "./three-dispose.js";
-import { getArWorldGroup, getScene } from "../ar/webxr-session.js";
+import { c as getArWorldGroup, m as getScene } from "../webxr-session-QhcSSub5.js";
 import { VIS_COLORS } from "./vis-colors.js";
 import * as THREE from "three";
 //#region ../src/visualization/gps-event-markers.ts

package/dist/visualization/hit-test-reticle.d.ts

@@ -0,0 +1,2 @@
+import { n as createReticleMesh, r as updateReticle, t as HitMatrix } from "../hit-test-reticle-BEzEybxZ.js";
+export { HitMatrix, createReticleMesh, updateReticle };

package/dist/visualization/hit-test-reticle.js

@@ -0,0 +1,81 @@
+import { WEBXR_TO_NUE } from "../ar/webxr-nue-basis.js";
+import { Matrix4, Mesh, MeshBasicMaterial, RingGeometry } from "three";
+//#region ../src/visualization/hit-test-reticle.ts
+/**
+* Hit-test reticle — the small, deterministic "reticle view-model" shared by
+* the framework's example/starter apps.
+*
+* A faithful port of the reticle from the stock three.js `webxr_ar_hittest`
+* example: a flat ring laid on whatever real-world surface the WebXR
+* `hit-test` API reports under the screen centre. The framework delta is
+* *where* the mesh is parented and *which frame the hit pose is in*: apps add
+* the mesh under `getArWorldGroup()` (NUE local space) rather than the
+* GPS-aligned scene root, so the reticle rides the same lerped `arWorldGroup`
+* alignment as the camera — but the WebXR hit pose arrives in the WebXR
+* reference space, so `updateReticle` applies the `WEBXR_TO_NUE` basis change
+* to it (see that function for the full rationale).
+*
+* The per-frame XR plumbing (requesting the hit-test source, reading
+* `frame.getHitTestResults(...)`) stays in each app's WebXR glue and is
+* verified manually on-device. The two functions here are the unit-tested core:
+* given the latest hit pose (a column-major 4x4 transform matrix) or `null`,
+* drive the mesh's visibility + transform. They are unit tested because that is
+* the logic a porting developer is most likely to get subtly wrong (e.g.
+* forgetting the basis change so the reticle drifts off-centre, forgetting to
+* hide the reticle when no surface is found, or letting Three.js overwrite the
+* matrix).
+*/
+const hitPoseMatrix = /* @__PURE__ */ new Matrix4();
+/**
+* Build the reticle mesh: a thin ring oriented flat (rotated to lie in the
+* XZ plane) so it reads as a marker on the ground/wall.
+*
+* `matrixAutoUpdate` is disabled because the reticle's world transform is
+* written wholesale from the hit-test pose every frame; letting Three.js
+* recompose it from position/quaternion/scale would discard that pose.
+*
+* The mesh starts hidden (`visible = false`) — there is no surface yet.
+*/
+function createReticleMesh() {
+	const reticle = new Mesh(new RingGeometry(.07, .09, 32).rotateX(-Math.PI / 2), new MeshBasicMaterial({ color: 5213439 }));
+	reticle.matrixAutoUpdate = false;
+	reticle.visible = false;
+	return reticle;
+}
+/**
+* Apply the latest hit-test pose to the reticle.
+*
+* - When `matrix` is a 16-element transform, the reticle adopts it (after the
+*   WebXR→NUE basis change, see below) and becomes visible.
+* - When `matrix` is `null` (no surface under the screen centre, or the
+*   hit-test source is not ready yet), the reticle is hidden.
+*
+* Frame handling — the part a porting developer must not get wrong. The
+* hit-test pose is expressed in the **WebXR reference space** (`X=East, Y=Up,
+* Z=South`), the same frame as the live camera pose. The reticle, however, is
+* parented under `getArWorldGroup()`, whose local space is **NUE** (`X=North,
+* Y=Up, Z=East`) — the camera reaches that frame through the static
+* `basisChangeNode` that holds `WEBXR_TO_NUE`. The reticle has no such
+* intermediate node, so we apply the same basis change here:
+* `reticle.matrix = WEBXR_TO_NUE · hitPose`. The reticle's resulting world pose
+* is then `arWorldGroup.matrix · WEBXR_TO_NUE · hitPose` — identical to the
+* transform chain the camera rides, so it stays pinned under the screen centre.
+*
+* Without the basis change the WebXR coordinates were interpreted as NUE: the
+* Up axis matched (both are Y) but East/North were swapped, so the reticle
+* drifted sideways instead of tracking the screen centre.
+*
+* Works on any `Object3D` (not just the mesh from `createReticleMesh`) so it can
+* be unit tested without a WebGL context.
+*/
+function updateReticle(reticle, matrix) {
+	if (matrix === null) {
+		reticle.visible = false;
+		return;
+	}
+	hitPoseMatrix.fromArray(matrix);
+	reticle.matrix.multiplyMatrices(WEBXR_TO_NUE, hitPoseMatrix);
+	reticle.visible = true;
+}
+//#endregion
+export { createReticleMesh, updateReticle };

package/dist/visualization/index.d.ts

@@ -1,17 +1,19 @@
-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 };
+import { n as createCss3dRendererManager, t as Css3dRendererManager } from "../css3d-renderer-manager-ptu_t3B3.js";
+import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-C2mwEn7c.js";
+import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-Dm9G7JJO.js";
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-CkloBxIl.js";
+import { n as ArWorldGroupAlignmentOptions, r as enableArWorldGroupAlignment, t as ArWorldGroupAlignmentHandle } from "../ar-world-group-alignment-ColHB_5A.js";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-BM1uGiYV.js";
+import { i as isSphereInCameraFrustum, n as isObjectInCameraFrustum, r as isPointInCameraFrustum, t as buildCameraFrustum } from "../frustum-visibility-CmI96ESS.js";
+import { n as worldNueToGps, t as nueToArLocal } from "../frame-conversions-BfsafGWR.js";
+import { n as createReticleMesh, r as updateReticle, t as HitMatrix } from "../hit-test-reticle-BEzEybxZ.js";
+import { a as GpsAnchorSamplePoint, i as GpsAnchorPhase, n as GpsAnchorMode, o as createGpsAnchor, r as GpsAnchorOptions, t as GpsAnchor } from "../gps-anchor-dYeCvvp5.js";
+import { n as GpsEventVisualizer, r as gpsEventVisualizer } from "../gps-event-markers-Dc9FT-q1.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-6CJC-E1l.js";
+import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-BpV-0Dtk.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-BpwWAs8G.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-krOKwDAq.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-bcogY5fK.js";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-D950t71B.js";
+import { t as VIS_COLORS } from "../vis-colors-D6omC64K.js";
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, ALIGNMENT_SNAPSHOT_COLOR, type AccuracyCircleSample, type AlignmentLerper, type ArWorldGroupAlignmentHandle, type ArWorldGroupAlignmentOptions, 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 DrawMapDataOptions, type DrawnMapData, FUSED_PATH_COLOR, type GpsAnchor, type GpsAnchorMode, type GpsAnchorOptions, type GpsAnchorPhase, type GpsAnchorSamplePoint, type GpsCompassCubes, GpsEventVisualizer, type HitMatrix, LeafletMapOverlay, type LeafletMapOverlayOptions, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, type MapData, type MapDataInput, MapOverlay, type MapOverlayOptions, RAW_GPS_COLOR, type TextureLoaderInterface, USER_POSITION_COLOR, VIS_COLORS, addAccuracyCircles, buildCameraFrustum, buildMapData, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsAnchor, createGpsCompassCubes, createReticleMesh, disposeMeshArray, disposeObject3D, drawMapData, enableArWorldGroupAlignment, gpsEventVisualizer, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum, latLonToTileXY, nueToArLocal, tileXYToLatLon, updateReticle, worldNueToGps };

package/dist/visualization/index.js

@@ -6,11 +6,14 @@ 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 { enableArWorldGroupAlignment } from "./ar-world-group-alignment.js";
 import { buildCameraFrustum, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum } from "./frustum-visibility.js";
-import { n as nueToArLocal, t as createGpsAnchor } from "../gps-anchor-DjC_3MoT.js";
+import { nueToArLocal, worldNueToGps } from "./frame-conversions.js";
+import { createReticleMesh, updateReticle } from "./hit-test-reticle.js";
+import { createGpsAnchor } from "./gps-anchor.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";
-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 };
+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, createReticleMesh, disposeMeshArray, disposeObject3D, drawMapData, enableArWorldGroupAlignment, gpsEventVisualizer, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum, latLonToTileXY, nueToArLocal, tileXYToLatLon, updateReticle, worldNueToGps };

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-Cew7XAoO.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-6CJC-E1l.js";
 export { DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, LeafletMapOverlay, LeafletMapOverlayOptions };

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

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

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

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

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

@@ -1,2 +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";
+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-krOKwDAq.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.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-DAmreyA3.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-bcogY5fK.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-C2drkp6f.js";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-D950t71B.js";
 export { DisposeOptions, disposeMeshArray, disposeObject3D };

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

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

package/dist/webxr-nue-basis-CqKQmZzT.d.ts

@@ -0,0 +1,23 @@
+import { Matrix4 } from "three";
+
+//#region ../src/ar/webxr-nue-basis.d.ts
+/**
+ * Constant matrix converting WebXR local-floor coordinates to the internal
+ * NUE (North-Up-East) convention.
+ *
+ * WebXR: X=East, Y=Up, Z=South (right-handed, toward viewer)
+ * NUE:   X=North, Y=Up, Z=East (right-handed)
+ *
+ * Mapping:  NUE_X = -WebXR_Z,  NUE_Y = WebXR_Y,  NUE_Z = WebXR_X
+ *
+ * Row-major:
+ *   [ 0  0 -1  0 ]
+ *   [ 0  1  0  0 ]
+ *   [ 1  0  0  0 ]
+ *   [ 0  0  0  1 ]
+ *
+ * Stored column-major (Three.js / gl-matrix convention).
+ */
+declare const WEBXR_TO_NUE: Matrix4;
+//#endregion
+export { WEBXR_TO_NUE as t };

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

@@ -1,9 +1,10 @@
-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 { i as DepthSample, t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { i as DepthSamplerConfig } from "./depth-sampler-Bhanfwla.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-DJBXuMxV.js";
+import { i as ImageCaptureConfig, t as CapturedImage } from "./image-capture-DZ4HFRgS.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-CdK8c-8P.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-ptu_t3B3.js";
+import { r as XRCameraLike } from "./xr-camera-texture-DBwCaKTd.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
 
@@ -102,15 +103,33 @@ declare function extractPoseFromViewer(pose: XRViewerPose | null): ARPose | null
  * @returns The latest AR pose, or null if no pose available yet
  */
 declare function getCurrentArPose(): ARPose | null;
+/**
+ * Opt-in standard WebXR session features that are independent of the
+ * crash-isolation diagnostic flags. Kept separate from
+ * `ArCrashIsolationOptions` because requesting `hit-test` is a normal app
+ * capability, not a crash-isolation toggle.
+ */
+interface SessionFeatureOptions {
+  /**
+   * Request the WebXR `hit-test` feature (as an *optional* feature) so app
+   * code can drive a reticle via `registerXrFrameUpdate`. Default `false` —
+   * existing recorder/anchor sessions are unaffected.
+   */
+  requestHitTest?: boolean;
+}
 /**
  * Build XR session init options.
  * Extracted as a pure function for testability.
  *
  * @param rootElement - The DOM element for DOM overlay
+ * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
+ *   depth-sensing, camera-access)
+ * @param sessionFeatures - Opt-in standard WebXR features that are independent
+ *   of crash isolation (currently `requestHitTest`)
  * @returns XRSessionInit options
  * @throws Error if rootElement is null
  */
-declare function buildSessionOptions(rootElement: Element | null, isolationOptions?: Partial<ArCrashIsolationOptions>): XRSessionInit;
+declare function buildSessionOptions(rootElement: Element | null, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions): XRSessionInit;
 /**
  * Check if WebXR immersive-ar is supported
  */
@@ -159,8 +178,11 @@ declare function createSceneHierarchy(): {
 /**
  * Initialize the AR session and Three.js renderer.
  * @param container - DOM element to host the AR canvas and CSS3D overlay.
+ * @param isolationOptions - Crash-isolation diagnostic flags.
+ * @param sessionFeatures - Opt-in standard WebXR features (e.g.
+ *   `requestHitTest`) forwarded to the session negotiation.
  */
-declare function initAR(container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>): Promise<void>;
+declare function initAR(container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions): Promise<void>;
 /**
  * Get the current Three.js scene (for adding objects like map)
  */
@@ -273,10 +295,14 @@ declare function setImageCaptureCallback(onCaptured: (image: CapturedImage) => v
 /**
  * Start capturing images during recording.
  * Must call setImageCaptureCallback first.
- * @param config - Optional capture configuration (intervalMs, quality)
- * @param resolutionDivisor - Resolution divisor: 1 = full, 2 = half, 4 = quarter (default: 1)
+ *
+ * @param config - Optional capture configuration. Accepts the whole user
+ *   image-options section (`intervalMs`, `quality`, `resolutionDivisor`; any
+ *   extra keys such as `enabled` are ignored). Passing the section as one
+ *   object means a newly-added option flows through without editing this seam
+ *   — see `2026-06-12-payload-rebuild-field-drop-audit.md` (F3).
  */
-declare function startImageCapture(config?: Partial<ImageCaptureConfig>, resolutionDivisor?: number): void;
+declare function startImageCapture(config?: Partial<ImageCaptureConfig>): void;
 /**
  * Stop capturing images.
  */
@@ -329,8 +355,14 @@ declare function setDepthCaptureCallback(onCaptured: (sample: DepthSample) => vo
 /**
  * Start depth sampling during recording.
  * Must call setDepthCaptureCallback before initAR.
+ *
+ * @param config - optional sampler overrides (typically the user's
+ *   `depth.intervalMs`/`depth.gridSize` recording options); applied via
+ *   `DepthSampler.updateConfig` before sampling starts. Without this the
+ *   sampler's own defaults apply — the settings knobs were dead before
+ *   this parameter existed (occupancy-grid port plan, Iter 6).
  */
-declare function startDepthCapture(): void;
+declare function startDepthCapture(config?: Partial<DepthSamplerConfig>): void;
 /**
  * Stop depth sampling.
  */
@@ -354,4 +386,4 @@ declare function setFrameCallback(callback: (() => void) | null): void;
  */
 declare function getLiveCss3dManager(): Css3dRendererManager | null;
 //#endregion
-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 };
+export { setScene as A, resetWebXRState as C, setDepthCaptureCallback as D, setCamera as E, shouldLogCameraAccessDiagnostic as F, startDepthCapture as I, startImageCapture as L, setTrackingLostCallback as M, setTrackingRecoveredCallback as N, setFrameCallback as O, setTrackingStore as P, stopDepthCapture as R, nueQuaternionToWebXR$1 as S, setArWorldGroup as T, getXrCameraFromPose as _, createSceneHierarchy as a, isXRCameraLike as b, extractResetTransformData as c, getCamera as d, getCurrentArPose as f, getScene as g, getLiveCss3dManager as h, buildSessionOptions as i, setTrackingCallbacks as j, setImageCaptureCallback as k, getArPose as l, getImageCaptureFrameCount as m, TrackingSubscribableStore as n, endARSession as o, getDepthSampleCount as p, applyAlignmentMatrix as r, extractPoseFromViewer as s, SessionFeatureOptions as t, getArWorldGroup as u, initAR as v, setArPose as w, nuePositionToWebXR as x, isWebXRSupported as y, stopImageCapture as z };