gps-plus-slam-app-framework 1.0.7 → 1.2.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-CcZ5UV-8.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-qNXQ-tq5.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/bresenham3d.d.ts

@@ -0,0 +1,2 @@
+import { n as MAX_TRACE_STEPS, r as bresenham3d, t as GridCell } from "../bresenham3d-CFfd7n6B.js";
+export { GridCell, MAX_TRACE_STEPS, bresenham3d };

package/dist/ar/bresenham3d.js

@@ -0,0 +1,81 @@
+//#region ../src/ar/bresenham3d.ts
+/**
+* Main-thread safety cap: the maximum dominant-axis (Chebyshev) span a single
+* trace may cover. The trace runs synchronously, one iteration per
+* dominant-axis step, so an unbounded span freezes the UI. Finite-but-absurd
+* coordinates (a tracking glitch, a corrupt projectionMatrix unprojecting to a
+* huge world point) quantize to safe integers and pass the integer check, so
+* this is the only thing standing between such input and a multi-second
+* (potentially multi-billion-iteration) freeze.
+*
+* Chosen generously — at the grid's 0.15 m cells this is ~150 km, far beyond
+* any real AR scene, so it never trips on legitimate carving or raycasting.
+* It is a circuit breaker against programmer/data error, not a ray-length
+* policy: exceeding it throws (loud — surfaces the upstream bug) rather than
+* silently truncating the trace.
+*/
+const MAX_TRACE_STEPS = 1e6;
+/**
+* Trace the line from `start` to `end`, calling `visitCell` per cell.
+*
+* @param visitCell - return `false` to stop the trace early.
+* @param stopDistance - dominant-axis steps before `end` at which to stop
+*   (default 0 = trace all the way to `end`).
+* @throws TypeError when a coordinate is not a safe integer (cells must be
+*   quantized before tracing — programmer error, not a data error).
+* @throws RangeError when `stopDistance` is not a non-negative safe integer.
+*   The loop terminates on a counter (`i--`) that decrements unconditionally,
+*   so a negative or fractional value still terminates (it merely traces past
+*   `end`); but `NaN`/`-Infinity` never satisfy `i <= stopDistance` and would
+*   spin forever. Rejecting up front both prevents that freeze and enforces
+*   the "dominant-axis steps before end" contract.
+* @throws RangeError when the dominant-axis span exceeds {@link MAX_TRACE_STEPS}
+*   (circuit breaker against a synchronous main-thread freeze from
+*   finite-but-absurd coordinates).
+*/
+function bresenham3d(start, end, visitCell, stopDistance = 0) {
+	assertIntegerCell(start);
+	assertIntegerCell(end);
+	if (!Number.isSafeInteger(stopDistance) || stopDistance < 0) throw new RangeError(`bresenham3d stopDistance must be a non-negative safe integer, got ${stopDistance}`);
+	let [x, y, z] = start;
+	const dx = Math.abs(end[0] - x);
+	const sx = x < end[0] ? 1 : -1;
+	const dy = Math.abs(end[1] - y);
+	const sy = y < end[1] ? 1 : -1;
+	const dz = Math.abs(end[2] - z);
+	const sz = z < end[2] ? 1 : -1;
+	const dm = Math.max(dx, dy, dz);
+	if (dm > 1e6) throw new RangeError(`bresenham3d dominant-axis span ${dm} exceeds MAX_TRACE_STEPS ${MAX_TRACE_STEPS}; cells [${start.join(", ")}]→[${end.join(", ")}] are too far apart to trace synchronously`);
+	let i = dm;
+	let errX = Math.floor(dm / 2);
+	let errY = errX;
+	let errZ = errX;
+	for (;;) {
+		if (!visitCell([
+			x,
+			y,
+			z
+		])) return;
+		if (i-- <= stopDistance) return;
+		errX -= dx;
+		if (errX < 0) {
+			errX += dm;
+			x += sx;
+		}
+		errY -= dy;
+		if (errY < 0) {
+			errY += dm;
+			y += sy;
+		}
+		errZ -= dz;
+		if (errZ < 0) {
+			errZ += dm;
+			z += sz;
+		}
+	}
+}
+function assertIntegerCell(cell) {
+	if (!cell.every((v) => Number.isSafeInteger(v))) throw new TypeError(`bresenham3d requires integer cell coordinates, got [${cell.join(", ")}]`);
+}
+//#endregion
+export { MAX_TRACE_STEPS, bresenham3d };

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-D5_mNhla.js";
 export { CameraBlitCapture, CameraBlitCaptureConfig, DEFAULT_BLIT_CONFIG, computeCaptureSize };

package/dist/ar/camera-blit-capture.js

@@ -118,8 +118,32 @@ var CameraBlitCapture = class {
 	* @returns JPEG Blob, or null if capture fails
 	*/
 	async captureToBlob(renderer, cameraTexture, quality) {
+		if (!this.captureToPixels(renderer, cameraTexture)) return null;
+		try {
+			return await this.pixelsToJpegBlob(quality);
+		} catch (error) {
+			log.error("Blit capture failed:", error);
+			return null;
+		}
+	}
+	/**
+	* Run the blit + readback (steps A+B of {@link captureToBlob}) and return
+	* the raw RGBA pixel buffer without JPEG encoding — the cheap path for
+	* per-point color sampling (occupancy-grid port plan Iter 8).
+	*
+	* IMPORTANT: Must be called within the XR animation frame callback, while
+	* the camera texture is valid. The returned `pixels` is the INTERNAL
+	* buffer — valid only until the next capture or `resizeIfNeeded`; consume
+	* it synchronously (e.g. via `createRgbLookup`) or copy it.
+	*
+	* Note: the buffer is in WebGL readback order (bottom-row-first / RGBA);
+	* `createRgbLookup` handles the y-flip.
+	*
+	* @returns the buffer with its dimensions, or null on failure/dispose.
+	*/
+	captureToPixels(renderer, cameraTexture) {
 		if (this.disposed) {
-			log.warn("captureToBlob called after dispose");
+			log.warn("captureToPixels called after dispose");
 			return null;
 		}
 		try {
@@ -133,7 +157,11 @@ var CameraBlitCapture = class {
 			renderer.setRenderTarget(currentRenderTarget);
 			renderer.xr.enabled = currentXrEnabled;
 			this.blitMaterial.uniforms.tDiffuse.value = null;
-			return await this.pixelsToJpegBlob(quality);
+			return {
+				pixels: this.pixelBuffer,
+				width: this.width,
+				height: this.height
+			};
 		} catch (error) {
 			log.error("Blit capture failed:", error);
 			return null;

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-CQXJHxXg.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-CUeU3L_M.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-Jqbn0apH.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";
-export { DepthInfo, DepthSample, DepthSampler, DepthSamplerCallbacks, DepthSamplerConfig };
+import { i as DepthSample } from "../ar-types-Dan1MVTi.js";
+import { a as wrapXRDepthInfo, i as DepthSamplerConfig, n as DepthSampler, r as DepthSamplerCallbacks, t as DepthInfo } from "../depth-sampler-Bhanfwla.js";
+export { DepthInfo, DepthSample, DepthSampler, DepthSamplerCallbacks, DepthSamplerConfig, wrapXRDepthInfo };