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

package/README.md

@@ -108,7 +108,7 @@ startGpsWatch(
 );
 ```
 
-See [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) for a complete, runnable smallest-possible consumer (Three.js scene + status panel, no AR, no recording).
+See [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) for a complete, runnable smallest-possible consumer (Three.js scene + status panel, no AR, no recording). For the next rung up — a readable AR + GPS + persistence demo (a single GPS anchor that survives a page reload) — see [`GpsPlusSlamJs_AnchorStarter`](../GpsPlusSlamJs_AnchorStarter/). The example ladder is **trivial** (MinimalExample) → **starter** (AnchorStarter) → **full** (RecorderApp).
 
 > **Imports.** Prefer subpath imports (`gps-plus-slam-app-framework/ar`, `…/state`, `…/sensors`, `…/storage`, `…/geo`, `…/visualization`, `…/utils`, `…/types`, `…/licensing`). The root barrel re-exports conflict-free names for convenience.
 
@@ -196,32 +196,85 @@ scene                             ← GPS-aligned (NUE) space, the scene root
                                     (waypoints, POIs, navigation arrows, …)
 ```
 
-When the alignment solver produces a new matrix, the framework writes it to `arWorldGroup.matrix`. The camera moves with `arWorldGroup`; objects parented directly to `scene` do not.
+When the alignment solver produces a new matrix, the framework writes it to `arWorldGroup.matrix` (smoothly lerped — see `enableArWorldGroupAlignment` below). The camera moves with `arWorldGroup`; objects parented directly to `scene` do not.
+
+> **Apply alignment to `arWorldGroup` — the framework default.** Call
+> [`enableArWorldGroupAlignment({ store, arWorldGroup })`](src/visualization/ar-world-group-alignment.ts.md)
+> once after AR starts. It subscribes to the store's alignment matrix, lerps it
+> onto `arWorldGroup.matrix` each frame, and thereby **GPS-registers the view**:
+> the camera and every object parented under `arWorldGroup` (including GPS
+> anchors) shift together as alignment refines, so anchors stay stable in the AR
+> overlay and only ever correct a small residual. The recorder wires its own
+> lerper; the simpler apps use this helper. Forgetting it leaves the camera
+> pure-VIO and forces each anchor to absorb the full alignment delta on every
+> re-registration.
 
 **Three options for placing your own `Object3D`:**
 
 1. **Add it to `scene`** (with NUE-meter coordinates from `calcRelativeCoordsInMeters(zeroRef, …)`). The object's world pose stays at the correct latitude/longitude/altitude forever, but every time the alignment matrix is corrected the camera shifts inside `arWorldGroup`, so from the user's AR view the object visually "floats". Cheap and correct, but ugly during corrections — fine for small markers (e.g. ref-point spheres), not great for richer GPS-anchored content.
 2. **Add it to `arWorldGroup`** with a fixed local transform. The object is frozen relative to AR-tracked content and stays visually fixed at the same 3D position for this session. This is a good fit for user-created local content such as a walked path, a temporary marker, a hit-test reticle, or an object the user placed by hand. The tradeoff is that its world / GPS pose drifts every time alignment is corrected, so this mode is not enough when the object must be replayed or shared by GPS coordinate.
-3. **Use `createGpsAnchor` for objects that should stay visually stable at a GPS target.** The anchor owns a single `Object3D` inside `arWorldGroup`, bootstraps from median GPS samples unless `skipBootstrap` is set, and re-derives the object's local pose from the current GPS target and alignment state. In the default `snap-when-offscreen` mode, small corrections are committed while the object is outside the camera frustum, making small alignment corrections hard to notice; larger alignment jumps bypass that gate so the object does not stay in a stale location. Use `snap-every-tick` when correctness is more important than hiding visible position changes.
+3. **Use `createGpsAnchor` for objects that should stay visually stable at a GPS target.** The anchor owns a single `Object3D` **inside `arWorldGroup`** (the factory throws if `object3D` is not a descendant of the `arWorldGroup` you pass — placing an anchor under the scene root defeats AR stability), bootstraps from median samples unless `skipBootstrap` is set, and re-derives the object's local pose from the current GPS target and alignment state each tick. Because the object rides the (lerped) `arWorldGroup` alignment, its motion relative to the camera between re-registrations is small. In the default `snap-when-offscreen` mode an accepted correction is committed **instantly** while the object is outside the camera frustum, making the (now small, residual) correction hard to notice; larger alignment jumps bypass that gate so the object does not stay in a stale location. Use `snap-every-tick` when correctness is more important than hiding visible position changes. Smoothing is **not** per-anchor: it lives once in the lerped `arWorldGroup.matrix` (`enableArWorldGroupAlignment`), so the whole AR world eases together. This is how the MinimalExample and AnchorStarter get the smooth alignment feel.
 
 A pure-function `syncGpsAnchoredMeshes` reconciler (option 1, bulk markers) is shipped by the RecorderApp. Use `createGpsAnchor` when a single visible object, route cue, or POI needs the more careful bootstrap and correction policy.
 
+> **Worked example.** The [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) ports the stock three.js `webxr_ar_hittest` example onto this convention and ends in a deliberate side-by-side **contrast demo**: a tap co-spawns an option-1 floater under `scene` and an option-3 `createGpsAnchor` marker under `arWorldGroup` at the same world pose, so the drift difference is visible. It is the canonical reference for options 1–3 and for the `registerXrFrameUpdate` + Enable-GPS-AR seams below.
+
+## DOM-Overlay / HUD stacking convention
+
+`initAR(container)` requests the WebXR **`dom-overlay`** feature with
+`domOverlay.root = container` — the **same element you pass in**. During an
+`immersive-ar` session the browser composites **only that element's subtree**
+over the camera feed; everything else on the page is hidden until the session
+ends.
+
+> **The rule:** every HUD / overlay / button you want visible **in AR** must be
+> a **DOM descendant of the element you pass to `initAR`**. A sibling overlay
+> works in the 2D pre-AR layout but silently disappears the moment AR starts —
+> a failure that only shows up on real AR hardware, never in a headless test.
+
+This is **not** a `z-index` problem; `z-index`/`pointer-events` only govern the
+2D (pre-AR) layout. Nesting is what determines in-AR visibility.
+
+```html
+<!-- ✅ Correct: HUD is inside the initAR container -->
+<div id="app">
+  <!-- three.js canvas is injected here by initAR -->
+  <div id="hud">…</div>
+</div>
+
+<!-- ❌ Wrong: HUD is a sibling — it vanishes once AR starts -->
+<div id="app"></div>
+<div id="hud">…</div>
+```
+
+```js
+await initAR(document.getElementById('app')!); // #app's subtree = the overlay root
+```
+
+A repo-meta guard (`tests/repo-config/hud-overlay-nesting.test.js`) asserts this
+structurally for every app's `index.html`, so a new app that authors its overlay
+as a sibling fails CI instead of failing silently in the field. Add new apps to
+that guard's `APP_OVERLAY_CONTRACTS` list.
+
 ## Modules
 
 ### `ar/` — WebXR & 3D Scene
 
 WebXR session lifecycle, Three.js renderer setup, image/depth capture, replay scene management.
 
-| Export                                       | Description                                      |
-| -------------------------------------------- | ------------------------------------------------ |
-| `initAR(container)`                          | Start a WebXR AR session with Three.js rendering |
-| `endARSession()`                             | End the active XR session                        |
-| `startImageCapture()` / `stopImageCapture()` | Toggle camera frame capture                      |
-| `ImageCaptureManager`                        | Configurable camera frame capture pipeline       |
-| `DepthSampler`                               | Depth buffer sampling with configurable grids    |
-| `CameraBlitCapture`                          | GPU blit-based camera capture                    |
-| `initReplayScene(container)`                 | Create a 3D replay scene with orbit/FPS controls |
-| `applyChromiumProjectionLayerWorkaround`     | Workaround for Chromium camera-access edge cases |
+| Export                                         | Description                                                                                                                                                                                                                                                             |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initAR(container, isolation?, features?)`     | Start a WebXR AR session with Three.js rendering. `features.requestHitTest` opts the session into the WebXR `hit-test` feature                                                                                                                                          |
+| `endARSession()`                               | End the active XR session                                                                                                                                                                                                                                               |
+| `createEnableGpsArController()`                | Headless "Enable GPS AR" orchestration (support check + permission bundling + sensor watches + `initAR`) with observable state; the app renders its own button over it                                                                                                  |
+| `registerXrFrameUpdate(cb)`                    | Per-frame access to the live `XRFrame` + reference space + session (valid only synchronously inside the callback). Enables app-side hit-test / other WebXR features                                                                                                     |
+| `isFullySupported(s)` / `capabilityMessage(s)` | WebXR + geolocation capability gating + a user-facing message                                                                                                                                                                                                           |
+| `startImageCapture()` / `stopImageCapture()`   | Toggle camera frame capture                                                                                                                                                                                                                                             |
+| `ImageCaptureManager`                          | Configurable camera frame capture pipeline                                                                                                                                                                                                                              |
+| `DepthSampler`                                 | Depth buffer sampling with configurable grids                                                                                                                                                                                                                           |
+| `CameraBlitCapture`                            | GPU blit-based camera capture                                                                                                                                                                                                                                           |
+| `initReplayScene(container)`                   | Create a 3D replay scene with orbit/FPS controls                                                                                                                                                                                                                        |
+| `applyChromiumProjectionLayerWorkaround`       | Chromium camera-access tab-crash workaround. Always deletes projection-layer hooks (forces `XRWebGLLayer`; required on every affected build incl. Chrome 150) and additionally persists `baseLayer` only on the affected Chrome window (148.0.7778.12 up to 149.0.7821) |
 
 ### `sensors/` — GPS & Permissions
 
@@ -354,10 +407,11 @@ src/
 
 This framework is licensed under **Apache 2.0** — see [LICENSE](LICENSE).
 
-> **Note:** This package depends on [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js), which is a **closed-source, proprietary** library distributed via npm under a separate license. A community license key is bundled with the framework for frictionless evaluation. See the core library's EULA for usage terms.
+> **Note:** This package depends on [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js), which is a **closed-source, proprietary** library distributed via npm under a separate license. A free community license key is bundled with the framework so you can start building right away — no signup or API key required. See the core library's EULA for the full terms.
 
 ## See Also
 
 - [gps-plus-slam-js](https://www.npmjs.com/package/gps-plus-slam-js) — Core alignment algorithms (closed-source)
-- [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) — Smallest possible consumer of this framework
+- [`GpsPlusSlamJs_MinimalExample`](../GpsPlusSlamJs_MinimalExample/) — Smallest possible consumer of this framework (trivial rung)
+- [`GpsPlusSlamJs_AnchorStarter`](../GpsPlusSlamJs_AnchorStarter/) — Meaningful-minimal starter: a persistent GPS anchor across reload (starter rung)
 - [`GpsPlusSlamJs_RecorderApp`](../GpsPlusSlamJs_RecorderApp/) — Full-featured recording app built on this framework

package/dist/{app-selectors-BeU0_ab8.d.ts → app-selectors-CR9OWodf.d.ts}

@@ -1,4 +1,4 @@
-import { L as CombinedRootState, r as SlamAppRootState } from "./create-slam-app-store-CNsZ3rcX.js";
+import { L as CombinedRootState, r as SlamAppRootState } from "./create-slam-app-store-B76AGaI0.js";
 import * as _$gps_plus_slam_js0 from "gps-plus-slam-js";
 import { ArImageCapture, GpsPoint, LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";

package/dist/ar/camera-blit-capture.d.ts

@@ -1,2 +1,2 @@
-import { i as computeCaptureSize, n as CameraBlitCaptureConfig, r as DEFAULT_BLIT_CONFIG, t as CameraBlitCapture } from "../camera-blit-capture-C1V9I1Z6.js";
+import { i as computeCaptureSize, n as CameraBlitCaptureConfig, r as DEFAULT_BLIT_CONFIG, t as CameraBlitCapture } from "../camera-blit-capture-75WWa9Xb.js";
 export { CameraBlitCapture, CameraBlitCaptureConfig, DEFAULT_BLIT_CONFIG, computeCaptureSize };

package/dist/ar/capability-checker.d.ts

@@ -0,0 +1,2 @@
+import { i as isFullySupported, n as CapabilitySupport, r as capabilityMessage, t as CapabilityMessageOptions } from "../capability-checker-BTCmZRL4.js";
+export { CapabilityMessageOptions, CapabilitySupport, capabilityMessage, isFullySupported };

package/dist/ar/capability-checker.js

@@ -0,0 +1,25 @@
+//#region ../src/ar/capability-checker.ts
+/** True only when both AR and GPS are available — the demo can run. */
+function isFullySupported(support) {
+	return support.webxr && support.geolocation;
+}
+/**
+* Build the capability-gated message shown when the demo cannot run. Names
+* exactly which capabilities are missing so the user understands *why*, and
+* always points them at the supported environment (an AR phone, outdoors).
+* Returns `null` when everything is supported (no message needed).
+*
+* The trailing "to try …" clause is app-specific and supplied via
+* `options.contextLabel`; without it the message ends neutrally at
+* "…outdoors.".
+*/
+function capabilityMessage(support, options = {}) {
+	if (isFullySupported(support)) return null;
+	const missing = [];
+	if (!support.webxr) missing.push("WebXR augmented reality");
+	if (!support.geolocation) missing.push("GPS / geolocation");
+	const suffix = options.contextLabel ? `, to try ${options.contextLabel}` : "";
+	return `This demo needs ${missing.join(" and ")}, which this device or browser does not provide. Open it on an AR-capable phone (e.g. Chrome on Android with ARCore), outdoors${suffix}.`;
+}
+//#endregion
+export { capabilityMessage, isFullySupported };

package/dist/ar/capture-failure-tracker.d.ts

@@ -1,2 +1,2 @@
-import { a as createCaptureFailureTracker, i as DEFAULT_CAPTURE_TRACKER_CONFIG, n as CaptureFailureTracker, r as CaptureFailureTrackerConfig, t as CAPTURE_FAILURE_WARNING } from "../capture-failure-tracker-JKb1ST8E.js";
+import { a as createCaptureFailureTracker, i as DEFAULT_CAPTURE_TRACKER_CONFIG, n as CaptureFailureTracker, r as CaptureFailureTrackerConfig, t as CAPTURE_FAILURE_WARNING } from "../capture-failure-tracker-D4HYJNOj.js";
 export { CAPTURE_FAILURE_WARNING, CaptureFailureTracker, CaptureFailureTrackerConfig, DEFAULT_CAPTURE_TRACKER_CONFIG, createCaptureFailureTracker };

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

@@ -1,2 +1,2 @@
-import { n as applyChromiumProjectionLayerWorkaround, t as ChromiumProjectionLayerWorkaroundResult } from "../chromium-camera-access-workaround-NvChXsi8.js";
-export { ChromiumProjectionLayerWorkaroundResult, applyChromiumProjectionLayerWorkaround };
+import { a as applyChromiumProjectionLayerWorkaround, i as ChromiumProjectionLayerWorkaroundResult, n as BASELAYER_WINDOW_MIN, o as needsBaseLayerPersistence, r as ChromeVersion, s as parseChromeVersion, t as BASELAYER_WINDOW_MAX } from "../chromium-camera-access-workaround-MifIwK9x.js";
+export { BASELAYER_WINDOW_MAX, BASELAYER_WINDOW_MIN, ChromeVersion, ChromiumProjectionLayerWorkaroundResult, applyChromiumProjectionLayerWorkaround, needsBaseLayerPersistence, parseChromeVersion };

package/dist/ar/chromium-camera-access-workaround.js

@@ -1,20 +1,207 @@
+import { createLogger } from "../utils/logger.js";
 //#region ../src/ar/chromium-camera-access-workaround.ts
 /**
+* Chromium WebXR camera-access tab-crash workaround.
+*
+* Background:
+* Requesting `camera-access` as an optional WebXR feature on Android Chrome
+* 147+ 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-06-04-camera-access-crash-regression-chrome-148.md
+*   - https://github.com/mrdoob/three.js/issues/33404
+*   - https://issues.chromium.org/issues/507508099 (root-cause, marked Fixed)
+*
+* There is NOT a single crash here — the Chromium tracker notes the crash on
+* Chrome 147 is different from the crash on 148+, and the simple workaround
+* below only helped on a subset of versions. The empirically-verified
+* (on-device) timeline is:
+*
+*   - 147 : deleting `createProjectionLayer` / `layers` forces three.js onto
+*       `XRWebGLLayer` and sidesteps the crash (deletes-only is sufficient).
+*   - 148.0.7778.12 .. 149.0.7821 : the delete-only trick is NOT sufficient on
+*       its own. An ADDITIONAL patch is needed: persist the `baseLayer`
+*       reference across `XRSession.prototype.updateRenderState` so three.js's
+*       later `depthNear`/`depthFar` update does not drop the active
+*       `glBaseLayer`. (Confirmed on-device on `148.0.7778.215`: BOTH the
+*       deletes and the baseLayer patch are required for the page not to
+*       crash. Earlier 148 builds (`< .7778.12`) are below the window per the
+*       tracker, which reported delete-only worked there.)
+*   - > 149.0.7821 (incl. Chrome 150) : the delete-only path is STILL required
+*       (confirmed on-device: Chrome 150 only stops crashing when the deletes
+*       are applied), but the extra baseLayer-persistence patch is NOT needed.
+*       The earlier assumption that Chromium fully fixed this on patched
+*       builds did not hold on real devices, so we no longer skip the
+*       workaround on "patched" Chrome.
+*
+* Resulting policy (see {@link applyChromiumProjectionLayerWorkaround}):
+*   - ALWAYS apply the deletes (every Chrome build, and unknown/non-Chromium
+*     environments — restoring the original always-on behavior).
+*   - Apply the baseLayer-persistence patch ONLY when a detected Chrome build
+*     falls inside the affected window
+*     [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}].
+*
+* 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).
+*/
+const log = createLogger("chromium-camera-access");
+/** Marker set on our patched `updateRenderState` so we never double-wrap it. */
+const BASE_LAYER_PATCH_MARKER = "__gpsBaseLayerPersistencePatch";
+/**
+* Inclusive lower bound of the Chrome window that additionally needs the
+* `baseLayer`-persistence patch (on top of the deletes).
+*
+* Set to `148.0.7778.12`, the issue tracker's figure for when the delete-only
+* trick stopped being sufficient. On-device confirmation: `148.0.7778.215`
+* (well inside this window) crashes with deletes-only and needs BOTH patches.
+* Earlier 148 builds (`< .7778.12`) and all of Chrome 147 stay below this
+* bound (deletes-only) per the documented timeline — we have no on-device
+* evidence that they need the baseLayer patch, so we do not apply it there.
+*/
+const BASELAYER_WINDOW_MIN = [
+	148,
+	0,
+	7778,
+	12
+];
+/**
+* Inclusive upper bound of the Chrome window that additionally needs the
+* `baseLayer`-persistence patch. The crash is fixed after `149.0.7819.0` and
+* the camera image is correctly populated after `149.0.7821.0`; above this
+* build the extra patch is no longer required (the deletes still are — see
+* the module header and the on-device matrix for Chrome 150).
+*
+* @see https://github.com/mrdoob/three.js/issues/33404
+*/
+const BASELAYER_WINDOW_MAX = [
+	149,
+	0,
+	7821,
+	0
+];
+/**
+* Parse a Chrome/Chromium version from a user-agent string.
+*
+* Matches the `Chrome/<major>.<minor>.<build>.<patch>` token (and the iOS
+* `CriOS/...` variant). Returns null for non-Chromium user agents.
+*/
+function parseChromeVersion(userAgent) {
+	const match = /(?:Chrome|CriOS)\/(\d+)\.(\d+)\.(\d+)\.(\d+)/.exec(userAgent);
+	if (!match) return null;
+	return [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3]),
+		Number(match[4])
+	];
+}
+/** Lexicographically compare two version tuples: returns true if `a` > `b`. */
+function isVersionAfter(a, b) {
+	for (let i = 0; i < a.length; i++) {
+		const av = a[i] ?? 0;
+		const bv = b[i] ?? 0;
+		if (av !== bv) return av > bv;
+	}
+	return false;
+}
+/** True if `a` >= `b` (lexicographic). */
+function isVersionAtLeast(a, b) {
+	return !isVersionAfter(b, a);
+}
+/**
+* True when the detected Chrome build falls inside the affected window
+* [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}] (inclusive)
+* and therefore additionally needs the `baseLayer`-persistence patch. Outside
+* the window (including non-Chromium user agents) returns false — only the
+* deletes are needed there.
+*/
+function needsBaseLayerPersistence(userAgent) {
+	const version = parseChromeVersion(userAgent);
+	if (version === null) return false;
+	return isVersionAtLeast(version, BASELAYER_WINDOW_MIN) && isVersionAtLeast(BASELAYER_WINDOW_MAX, version);
+}
+function getUserAgent() {
+	return globalThis.navigator?.userAgent ?? "";
+}
+/**
+* Wrap `XRSession.prototype.updateRenderState` so the `baseLayer` reference is
+* persisted across calls. Three.js calls `updateRenderState({ depthNear,
+* depthFar })` after the base layer was set; on affected Chrome builds that
+* second call drops the active `glBaseLayer`, which leads to the crash on
+* camera-texture access. Re-supplying the last-seen `baseLayer` keeps it
+* alive.
+*
+* The last-seen `baseLayer` is tracked **per `XRSession` instance** via a
+* `WeakMap` keyed on the call's `this`. A single shared variable would leak a
+* previous session's `baseLayer` into a later session: an `XRWebGLLayer` is
+* bound to the session it was created for, so re-supplying a stale layer to a
+* different session throws `InvalidStateError`. Keying per session also lets
+* the entries be garbage-collected with their sessions.
+*
+* Idempotent: a marker on the wrapper prevents double-wrapping.
+*
+* @returns true if the prototype was wrapped on this call.
+*/
+function patchUpdateRenderStateForBaseLayerPersistence() {
+	const session = globalThis.XRSession;
+	const original = session?.prototype.updateRenderState;
+	if (!session || typeof original !== "function") return false;
+	if (original[BASE_LAYER_PATCH_MARKER]) return false;
+	const lastBaseLayerBySession = /* @__PURE__ */ new WeakMap();
+	const patched = function(rawInit) {
+		const init = typeof rawInit === "object" && rawInit !== null ? rawInit : {};
+		if (typeof this !== "object" || this === null) return original.call(this, init);
+		if (init.baseLayer !== void 0) lastBaseLayerBySession.set(this, init.baseLayer);
+		const remembered = lastBaseLayerBySession.get(this);
+		return original.call(this, remembered !== void 0 ? {
+			...init,
+			baseLayer: remembered
+		} : init);
+	};
+	patched[BASE_LAYER_PATCH_MARKER] = true;
+	session.prototype.updateRenderState = patched;
+	return true;
+}
+/**
 * 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.
+* Policy (derived from on-device testing — see the module header):
+*
+*  - ALWAYS removes `XRWebGLBinding.prototype.createProjectionLayer`
+*    (three.js r184) and `XRRenderState.prototype.layers` (three.js r158) so
+*    three.js falls back to `XRWebGLLayer`. This is required on every affected
+*    Chrome build observed so far, including Chrome 150, and is also applied
+*    on unknown/non-Chromium environments (restoring the original always-on
+*    behavior).
+*  - ADDITIONALLY persists the `baseLayer` across
+*    `XRSession.prototype.updateRenderState`, but ONLY when a detected Chrome
+*    build falls inside the affected window
+*    [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}]. Outside
+*    that window the extra patch is unnecessary (and is skipped on unknown
+*    environments to avoid touching projection-layer devices like Quest).
 *
 * Call once during bootstrap, before any `requestSession()` call.
 *
-* @returns which prototype members were actually deleted on this call.
+* @param options.userAgent override the detected user agent (for testing).
+* @returns which prototype members were actually changed on this call.
 */
-function applyChromiumProjectionLayerWorkaround() {
+function applyChromiumProjectionLayerWorkaround(options) {
+	const userAgent = options?.userAgent ?? getUserAgent();
+	const version = parseChromeVersion(userAgent);
 	const result = {
 		deletedCreateProjectionLayer: false,
-		deletedRenderStateLayers: false
+		deletedRenderStateLayers: false,
+		patchedUpdateRenderState: false,
+		detectedChromeVersion: version ? version.join(".") : null
 	};
 	const binding = globalThis.XRWebGLBinding;
 	if (binding && "createProjectionLayer" in binding.prototype) {
@@ -26,7 +213,9 @@ function applyChromiumProjectionLayerWorkaround() {
 		delete renderState.prototype.layers;
 		result.deletedRenderStateLayers = true;
 	}
+	if (needsBaseLayerPersistence(userAgent)) result.patchedUpdateRenderState = patchUpdateRenderStateForBaseLayerPersistence();
+	log.info("applied workaround", result);
 	return result;
 }
 //#endregion
-export { applyChromiumProjectionLayerWorkaround };
+export { BASELAYER_WINDOW_MAX, BASELAYER_WINDOW_MIN, applyChromiumProjectionLayerWorkaround, needsBaseLayerPersistence, parseChromeVersion };

package/dist/ar/depth-sampler.d.ts

@@ -1,3 +1,3 @@
-import { i as DepthSample } from "../ar-types-Ck8LEq8k.js";
-import { i as DepthSamplerConfig, n as DepthSampler, r as DepthSamplerCallbacks, t as DepthInfo } from "../depth-sampler-xg8vna6c.js";
+import { i as DepthSample } from "../ar-types-isPsQptb.js";
+import { i as DepthSamplerConfig, n as DepthSampler, r as DepthSamplerCallbacks, t as DepthInfo } from "../depth-sampler-CqrkRr2N.js";
 export { DepthInfo, DepthSample, DepthSampler, DepthSamplerCallbacks, DepthSamplerConfig };

package/dist/ar/enable-gps-ar.d.ts

@@ -0,0 +1,2 @@
+import { a as EnableGpsArState, i as EnableGpsArResult, n as EnableGpsArController, o as EnableGpsArStatus, r as EnableGpsArDeps, s as createEnableGpsArController, t as EnableGpsArConfig } from "../enable-gps-ar-DNbO0zbg.js";
+export { EnableGpsArConfig, EnableGpsArController, EnableGpsArDeps, EnableGpsArResult, EnableGpsArState, EnableGpsArStatus, createEnableGpsArController };

package/dist/ar/enable-gps-ar.js

@@ -0,0 +1,137 @@
+import { createLogger } from "../utils/logger.js";
+import { requestGeolocationPermission, requestOrientationPermission, requestWebXRWithDepthPermission } from "../sensors/permission-checker.js";
+import { startGpsWatch, startOrientationWatch, stopGpsWatch, stopOrientationWatch } from "../sensors/gps.js";
+import { endARSession, initAR, isWebXRSupported } from "./webxr-session.js";
+//#region ../src/ar/enable-gps-ar.ts
+const log = createLogger("EnableGpsAr");
+const defaultDeps = {
+	isWebXRSupported,
+	requestGeolocationPermission,
+	requestOrientationPermission,
+	requestWebXRWithDepthPermission,
+	startGpsWatch,
+	startOrientationWatch,
+	initAR,
+	stopGpsWatch,
+	stopOrientationWatch,
+	endARSession
+};
+/**
+* Create an "Enable GPS AR" controller. Pass partial `deps` in tests to inject
+* fakes; production callers use the defaults.
+*/
+function createEnableGpsArController(deps = {}) {
+	const resolved = {
+		...defaultDeps,
+		...deps
+	};
+	let state = { status: "checking" };
+	const listeners = /* @__PURE__ */ new Set();
+	let gpsWatchActive = false;
+	let orientationWatchActive = false;
+	function setState(next) {
+		state = next;
+		for (const listener of [...listeners]) try {
+			listener(state);
+		} catch (err) {
+			log.error("State listener threw; continuing dispatch:", err);
+		}
+	}
+	async function refreshSupport() {
+		if (state.status === "starting" || state.status === "running" || state.status === "stopping") return;
+		setState({ status: "checking" });
+		const supported = await probeSupport();
+		if (state.status !== "checking") return;
+		setState({ status: supported ? "ready" : "unsupported" });
+	}
+	async function probeSupport() {
+		try {
+			return await resolved.isWebXRSupported();
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Request the configured permissions. Returns an error message when a
+	* *blocking* permission (geolocation, or depth when opted in) is not granted,
+	* or `null` on success. Orientation is best-effort and never blocks.
+	*/
+	async function requestPermissions(config) {
+		const geolocation = await resolved.requestGeolocationPermission();
+		if (geolocation.granted !== true) return geolocation.error ?? "Location permission is required for GPS AR.";
+		try {
+			await resolved.requestOrientationPermission();
+		} catch {}
+		if (config.requestDepth) {
+			const depth = await resolved.requestWebXRWithDepthPermission();
+			if (depth.granted !== true) return depth.error ?? "Depth (3D map) permission was denied.";
+		}
+		return null;
+	}
+	async function enable(config) {
+		if (state.status === "starting" || state.status === "running" || state.status === "stopping") return {
+			ok: false,
+			error: "AR is already starting, running or stopping."
+		};
+		setState({ status: "starting" });
+		try {
+			const permissionError = await requestPermissions(config);
+			if (permissionError !== null) return fail(permissionError);
+			await resolved.initAR(config.container, config.isolationOptions, { requestHitTest: config.requestHitTest });
+			if (config.onGpsPosition) {
+				resolved.startGpsWatch(config.onGpsPosition);
+				gpsWatchActive = true;
+			}
+			if (config.onOrientation) {
+				resolved.startOrientationWatch(config.onOrientation);
+				orientationWatchActive = true;
+			}
+			setState({ status: "running" });
+			return { ok: true };
+		} catch (err) {
+			return fail(err instanceof Error ? err.message : String(err));
+		}
+	}
+	function fail(error) {
+		setState({
+			status: "error",
+			error
+		});
+		return {
+			ok: false,
+			error
+		};
+	}
+	async function disable() {
+		if (state.status !== "running") return;
+		setState({ status: "stopping" });
+		if (gpsWatchActive) {
+			resolved.stopGpsWatch();
+			gpsWatchActive = false;
+		}
+		if (orientationWatchActive) {
+			resolved.stopOrientationWatch();
+			orientationWatchActive = false;
+		}
+		try {
+			await resolved.endARSession();
+		} catch (err) {
+			log.error("endARSession threw during disable; continuing teardown:", err);
+		}
+		setState({ status: "ready" });
+	}
+	return {
+		getState: () => state,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		refreshSupport,
+		enable,
+		disable
+	};
+}
+//#endregion
+export { createEnableGpsArController };

package/dist/ar/frame-loop.d.ts

@@ -1,2 +1,2 @@
-import { i as runFrameUpdates, n as clearFrameUpdates, r as registerFrameUpdate, t as FrameUpdate } from "../frame-loop-QJIxLin0.js";
+import { i as runFrameUpdates, n as clearFrameUpdates, r as registerFrameUpdate, t as FrameUpdate } from "../frame-loop-BTeRpDm4.js";
 export { FrameUpdate, clearFrameUpdates, registerFrameUpdate, runFrameUpdates };

package/dist/ar/frame-loop.js

@@ -1,4 +1,18 @@
+import { createLogger } from "../utils/logger.js";
 //#region ../src/ar/frame-loop.ts
+/**
+* Per-frame callback registry. The WebXR session owns the single
+* `renderer.setAnimationLoop(...)` hook for the page; components that need
+* a per-frame tick register here and the session's `onXRFrame` invokes
+* `runFrameUpdates(dt, elapsed)` once per frame.
+*
+* Plain functions, not a class: there is exactly one frame loop per session
+* and singletons-of-singletons add no value. See
+* `2026-05-13-ecs-migration-plan.md` for the design rationale and the
+* rules new `FrameUpdate` bodies must follow (pure function of `dt` plus
+* selectors; no direct Redux dispatch from inside a tick).
+*/
+const log = createLogger("FrameLoop");
 const updates = /* @__PURE__ */ new Set();
 /**
 * Register a per-frame callback. Returns an unregister function.
@@ -23,10 +37,19 @@ function registerFrameUpdate(fn) {
 * same frame are deferred to the next tick. Iterating the live `Set`
 * would otherwise skip a not-yet-visited entry that an earlier handler
 * unregistered — a hard-to-debug source of non-determinism.
+*
+* Each callback is invoked in its own `try/catch` so a throwing handler is
+* isolated: it cannot abort the remaining callbacks nor propagate up through
+* `onXRFrame` and kill the scene render for the whole frame. Failures are
+* logged and the loop continues — mirrored by `runXrFrameUpdates`.
 */
 function runFrameUpdates(dt, elapsed) {
 	const snapshot = Array.from(updates);
-	for (const fn of snapshot) fn(dt, elapsed);
+	for (const fn of snapshot) try {
+		fn(dt, elapsed);
+	} catch (error) {
+		log.error("A registered FrameUpdate threw; continuing the loop", error);
+	}
 }
 /**
 * Clear all registrations. Called from `resetWebXRState()` so a fresh

package/dist/ar/image-capture.d.ts

@@ -1,2 +1,2 @@
-import { a as ImageCaptureManager, i as ImageCaptureConfig, n as DEFAULT_CAPTURE_CONFIG, o as MIN_VALID_IMAGE_BYTES, r as ImageCaptureCallbacks, t as CapturedImage } from "../image-capture-DZLxHDN9.js";
+import { a as ImageCaptureManager, i as ImageCaptureConfig, n as DEFAULT_CAPTURE_CONFIG, o as MIN_VALID_IMAGE_BYTES, r as ImageCaptureCallbacks, t as CapturedImage } from "../image-capture-BXZUmj7j.js";
 export { CapturedImage, DEFAULT_CAPTURE_CONFIG, ImageCaptureCallbacks, ImageCaptureConfig, ImageCaptureManager, MIN_VALID_IMAGE_BYTES };