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

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

@@ -0,0 +1,81 @@
+import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-BbdqhqY6.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-EDED3nvg.js";
+import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-B-nS1sr6.js";
+import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-CCZJf-Xb.js";
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-BGIBM5rv.js";
+import { n as ArWorldGroupAlignmentOptions, r as enableArWorldGroupAlignment, t as ArWorldGroupAlignmentHandle } from "../ar-world-group-alignment-Dn4rQk_c.js";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-Ys6Hf1nc.js";
+import { i as isSphereInCameraFrustum, n as isObjectInCameraFrustum, r as isPointInCameraFrustum, t as buildCameraFrustum } from "../frustum-visibility-DGnJqls0.js";
+import { n as worldNueToGps, t as nueToArLocal } from "../frame-conversions-D2EYjeNa.js";
+import { n as createReticleMesh, r as updateReticle, t as HitMatrix } from "../hit-test-reticle-BGXOxrUh.js";
+import { a as GpsAnchorSamplePoint, i as GpsAnchorPhase, n as GpsAnchorMode, o as createGpsAnchor, r as GpsAnchorOptions, t as GpsAnchor } from "../gps-anchor-CISLPQIb.js";
+import { n as GpsEventVisualizer, r as gpsEventVisualizer } from "../gps-event-markers-BlHq3jYV.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-jNt-kcUr.js";
+import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-DNcSmKVX.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-DEKr0Hoh.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-DcGs9UV3.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-yrFsUtGv.js";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-WTBAfaWU.js";
+import { t as VIS_COLORS } from "../vis-colors-Djnyg_UH.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-jNt-kcUr.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-DNcSmKVX.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-BGIBM5rv.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-DcGs9UV3.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-yrFsUtGv.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-WTBAfaWU.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-Djnyg_UH.js";
 export { VIS_COLORS };

package/dist/webxr-nue-basis-BbdqhqY6.js

@@ -0,0 +1,54 @@
+import { Matrix4 } from "three";
+//#region ../src/ar/webxr-nue-basis.ts
+/**
+* `webxr-nue-basis` — the single source of truth for the WebXR↔NUE basis
+* change.
+*
+* The framework's scene graph keeps GPS-world content in the **NUE**
+* convention (X=North, Y=Up, Z=East) while WebXR reports poses in its own
+* convention (X=East, Y=Up, Z=South). `WEBXR_TO_NUE` converts a transform
+* expressed in the WebXR reference space into the NUE frame.
+*
+* It lives in its own tiny module (depending only on three) so it can be shared
+* by both `webxr-session.ts` (which parents it permanently as the static
+* `basisChangeNode`) and `visualization/hit-test-reticle.ts` (which applies it
+* to the live hit-test pose) without either pulling the other's heavy
+* transitive dependencies into a unit-test import graph.
+*/
+/**
+* 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).
+*/
+const WEBXR_TO_NUE = /* @__PURE__ */ new Matrix4().fromArray([
+	0,
+	0,
+	1,
+	0,
+	0,
+	1,
+	0,
+	0,
+	-1,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	1
+]);
+//#endregion
+export { WEBXR_TO_NUE as t };

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

@@ -1,8 +1,8 @@
-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 { i as DepthSample, t as ARPose } from "./ar-types-isPsQptb.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-BSFpBSZH.js";
+import { i as ImageCaptureConfig, t as CapturedImage } from "./image-capture-BXZUmj7j.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-CDREeoZ_.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-EDED3nvg.js";
 import { r as XRCameraLike } from "./xr-camera-texture-BU5YvKAM.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
@@ -102,15 +102,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 +177,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)
  */
@@ -354,4 +375,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 };

package/dist/xr-frame-loop-BKckC7xC.d.ts

@@ -0,0 +1,70 @@
+//#region ../src/ar/xr-frame-loop.d.ts
+/**
+ * Per-frame **XR-access** callback registry — the safe seam that lets app
+ * code run standard WebXR work (hit-test, light estimation, depth, the WebXR
+ * Anchors API, …) without the framework wrapping each capability.
+ *
+ * The framework owns the single `renderer.setAnimationLoop(onXRFrame)` hook,
+ * and the live `XRFrame` never leaves `onXRFrame`. The plain `FrameUpdate`
+ * registry (`frame-loop.ts`) only passes `(dt, elapsed)`, which is enough for
+ * pose-free ticks but cannot drive hit-test. This registry additionally hands
+ * the callback the live `frame`, `referenceSpace`, and `session`.
+ *
+ * SAFETY CONTRACT (non-negotiable): `frame` / `referenceSpace` / `session` are
+ * valid **only synchronously inside the callback**. The `XRFrame` is
+ * use-after-frame-unsafe — storing it and reading it on a later tick throws or
+ * crashes. Passing them as arguments (never a stashable `getXrFrame()` getter)
+ * makes correct use the easy path and stashing the awkward one. Do NOT retain
+ * `ctx` or its fields beyond the callback's synchronous execution.
+ *
+ * See `2026-06-03-threejs-arbutton-minimal-ar-example-user-feedback.md`
+ * §6.2/§6.3 (option H-A2) for the design rationale.
+ */
+/**
+ * Live, frame-scoped WebXR context. Valid only synchronously inside the
+ * `XrFrameUpdate` callback it is passed to.
+ */
+interface XrFrameContext {
+  /** The live `XRFrame` for this animation-frame. Use-after-frame-unsafe. */
+  readonly frame: XRFrame;
+  /** The session's reference space (e.g. for `frame.getPose` / hit-test results). */
+  readonly referenceSpace: XRReferenceSpace;
+  /** The active `XRSession` (e.g. to call `requestHitTestSource` once). */
+  readonly session: XRSession;
+  /** Seconds since the previous frame (0 on the first frame after a reset). */
+  readonly dt: number;
+  /** Seconds since the session started. */
+  readonly elapsed: number;
+}
+/** A per-frame callback that needs live XR access. See the safety contract. */
+type XrFrameUpdate = (ctx: XrFrameContext) => void;
+/**
+ * Register a per-frame XR-access callback. Returns an unregister function.
+ *
+ * Registration is idempotent — registering the same `fn` twice is a no-op
+ * (it remains a single entry in the underlying `Set`).
+ */
+declare function registerXrFrameUpdate(fn: XrFrameUpdate): () => void;
+/**
+ * Invoke all registered XR-access callbacks. Called by the WebXR session's
+ * `onXRFrame` once per frame, only when a live `frame` / `referenceSpace` /
+ * `session` are all available.
+ *
+ * The set is snapshotted before iterating so that
+ * `registerXrFrameUpdate` / unregister calls made by a handler during the
+ * same frame are deferred to the next tick — mirroring `runFrameUpdates`.
+ *
+ * Each callback is invoked in its own `try/catch`: this registry is the public
+ * app seam, so a bug in one app-registered callback (which throws every frame)
+ * must not abort the remaining callbacks nor propagate up through `onXRFrame`
+ * and kill the scene render for the whole session. Failures are logged and the
+ * loop continues — mirroring `runFrameUpdates`.
+ */
+declare function runXrFrameUpdates(ctx: XrFrameContext): void;
+/**
+ * Clear all registrations. Called from `resetWebXRState()` so a fresh
+ * session starts with an empty registry.
+ */
+declare function clearXrFrameUpdates(): void;
+//#endregion
+export { runXrFrameUpdates as a, registerXrFrameUpdate as i, XrFrameUpdate as n, clearXrFrameUpdates as r, XrFrameContext as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gps-plus-slam-app-framework",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Reusable AR+GPS app framework layer — WebXR session management, Three.js visualization, GPS sensors, storage abstractions, replay engine, and store wiring for gps-plus-slam-js.",
   "type": "module",
   "files": [

package/dist/chromium-camera-access-workaround-NvChXsi8.d.ts

@@ -1,61 +0,0 @@
-//#region ../src/ar/chromium-camera-access-workaround.d.ts
-/**
- * Chromium WebXR camera-access tab-crash workaround.
- *
- * Background:
- * Requesting `camera-access` as an optional WebXR feature on recent Android
- * Chrome versions causes a fatal renderer-process crash (`CrRendererMain`)
- * 1–2 seconds after entering AR. The crash reproduces in the upstream
- * three.js `webxr_ar_hittest.html` example with `optionalFeatures:
- * ['camera-access']` added — i.e. it is not specific to this app's session
- * setup. See:
- *
- *   - GpsPlusSlamJs_Docs/docs/2026-04-22-camera-access-reproducer-plan.md
- *   - GpsPlusSlamJs_Docs/docs/2026-04-23-webxr-camera-access-crash-bug-report.html
- *   - https://github.com/mrdoob/three.js/issues/33404
- *
- * Workaround (from the upstream issue thread):
- * Three.js's `WebXRManager` chooses between the newer `XRProjectionLayer`
- * and the older `XRWebGLLayer` based on whether
- * `XRWebGLBinding.prototype.createProjectionLayer` is available. The crash
- * appears to involve the projection-layer + camera-access combination, so
- * removing the prototype method forces three.js to fall back to
- * `XRWebGLLayer`, which sidesteps the bug.
- *
- * `XRRenderState.prototype.layers` is the equivalent capability check used
- * by older three.js (r158-era) and is included for completeness.
- *
- * Caveats:
- * - This is a Chromium-specific hack and the upstream comment explicitly
- *   warns it "might break webxr on other devices" — keep it opt-in.
- * - Must run BEFORE any WebXR session setup. Three.js reads these prototype
- *   members lazily when the first session starts, so calling this at app
- *   bootstrap (before `initAR()`) is sufficient.
- * - Idempotent: safe to call repeatedly. Safe on environments where the
- *   prototypes do not exist (e.g. desktop browsers, jsdom).
- */
-/**
- * Result of {@link applyChromiumProjectionLayerWorkaround}.
- * Useful for logging and tests.
- */
-interface ChromiumProjectionLayerWorkaroundResult {
-  /** True if `XRWebGLBinding.prototype.createProjectionLayer` was deleted on this call. */
-  deletedCreateProjectionLayer: boolean;
-  /** True if `XRRenderState.prototype.layers` was deleted on this call. */
-  deletedRenderStateLayers: boolean;
-}
-/**
- * Apply the Chromium camera-access tab-crash workaround.
- *
- * Removes `XRWebGLBinding.prototype.createProjectionLayer` (three.js r184)
- * and `XRRenderState.prototype.layers` (three.js r158) so three.js falls
- * back to `XRWebGLLayer`, which avoids the renderer-process crash that
- * happens when both projection layers and `camera-access` are enabled.
- *
- * Call once during bootstrap, before any `requestSession()` call.
- *
- * @returns which prototype members were actually deleted on this call.
- */
-declare function applyChromiumProjectionLayerWorkaround(): ChromiumProjectionLayerWorkaroundResult;
-//#endregion
-export { applyChromiumProjectionLayerWorkaround as n, ChromiumProjectionLayerWorkaroundResult as t };