gps-plus-slam-app-framework 1.4.0 → 1.8.0

package/dist/absolute-orientation-BAxc15J6.d.ts

@@ -0,0 +1,54 @@
+//#region ../src/sensors/absolute-orientation.d.ts
+/**
+ * AbsoluteOrientationSensor capture (Generic Sensor API).
+ *
+ * Phase 1 of the AbsoluteOrientationSensor plan
+ * (GpsPlusSlamJs_Docs/docs/2026-06-25-absolute-orientation-sensor-plan.md §5.1):
+ * passive instrumentation that fuses accelerometer + gyroscope + magnetometer
+ * into an Earth-referenced (ENU) quaternion, captured per GPS event as an
+ * independent north reference. No production behaviour change.
+ *
+ * Platform: Chrome Android only. Safari / Firefox / desktop / iOS lack the
+ * sensor → this module degrades to a clean, reported no-op.
+ *
+ * The raw `'device'` reference frame is recorded together with the screen angle
+ * so either the device- or screen-compensated form can be reconstructed offline
+ * (plan §8 Q1).
+ */
+/** A single absolute-orientation reading, snapshotted into the GPS event payload. */
+interface AbsoluteOrientationReading {
+  /** [x,y,z,w] quaternion mapping device-frame → Earth ENU (+X East, +Y North, +Z Up). */
+  quaternion: [number, number, number, number];
+  /** Reference frame the quaternion is expressed in. We record raw 'device'. */
+  referenceFrame: 'device' | 'screen';
+  /** screen.orientation.angle at sample time — needed to reconstruct the 'device' frame. */
+  screenAngleDeg: number;
+  /** Capture time (epoch ms) — pairs with the GPS event; lets warm-up be detected offline. */
+  timestamp: number;
+}
+/** Lifecycle status surfaced to the caller (HUD/observability). */
+type AbsoluteOrientationStatus = {
+  state: 'active';
+} | {
+  state: 'unavailable';
+  reason: string;
+} | {
+  state: 'error';
+  reason: string;
+};
+/** True when the sensor can plausibly run here (secure context + API present). */
+declare function isAbsoluteOrientationAvailable(): boolean;
+/**
+ * Start capturing absolute orientation. Idempotent (stops any prior watch first).
+ *
+ * On platforms without the sensor — or when permissions are denied — it reports
+ * `unavailable`/`error` via `onStatus` and stays a no-op; the recorder keeps
+ * working unchanged. Never throws.
+ */
+declare function startAbsoluteOrientationWatch(onStatus?: (status: AbsoluteOrientationStatus) => void): Promise<void>;
+/** Latest reading, or null when unavailable/not-yet-warmed-up. Mirrors getLastDeviceOrientation. */
+declare function getLatestAbsoluteOrientation(): AbsoluteOrientationReading | null;
+/** Stop the watch and clear cached state. Idempotent. */
+declare function stopAbsoluteOrientationWatch(): void;
+//#endregion
+export { startAbsoluteOrientationWatch as a, isAbsoluteOrientationAvailable as i, AbsoluteOrientationStatus as n, stopAbsoluteOrientationWatch as o, getLatestAbsoluteOrientation as r, AbsoluteOrientationReading as t };

package/dist/{accuracy-circles-Pi2YeCrM.d.ts → accuracy-circles-DkWBkF5g.d.ts}

@@ -4,9 +4,19 @@ import L from "leaflet";
 /**
  * Style for per-event GPS accuracy circles. Radius comes from the GPS event's
  * horizontal accuracy in meters; larger circles mean lower-quality fixes.
- * Filled and stroked with a highly transparent variant of the path color so
- * overlapping circles remain legible without obscuring the basemap or the
- * polyline drawn on top.
+ *
+ * Circles are drawn **stroke-only** (no fill): Leaflet composites overlapping
+ * semi-transparent SVG fills, so N stacked filled circles reach
+ * `1 − (1 − fillOpacity)^N` opacity and paint the basemap solid on dense
+ * recordings (~90 % at ~18 overlaps with the old 0.12 fill). A fill-free
+ * outline never accumulates an opaque interior, so the basemap shows through at
+ * ANY overlap density while each accuracy radius stays readable.
+ */
+/**
+ * @deprecated Stroke-only since 2026-06-28 (Finding 1) — accuracy circles no
+ * longer render a fill, so this opacity is unused. Retained as an exported
+ * constant only to preserve the published API surface; do not pass it to
+ * `L.circle`. See `2026-06-28-map-rings-transparency-and-view-direction-user-feedback.md`.
  */
 declare const ACCURACY_CIRCLE_FILL_OPACITY = 0.12;
 declare const ACCURACY_CIRCLE_STROKE_OPACITY = 0.5;
@@ -23,8 +33,8 @@ interface AccuracyCircleSample {
   readonly accuracy?: number;
 }
 /**
- * Draw one transparent circle per sample whose `accuracy` is a finite
- * positive number. Samples without a usable accuracy value are skipped so
+ * Draw one stroke-only (un-filled) circle per sample whose `accuracy` is a
+ * finite positive number. Samples without a usable accuracy value are skipped so
  * pre-accuracy recordings still render their polyline.
  *
  * Circles are added to `map` immediately. The caller is responsible for
@@ -34,7 +44,7 @@ interface AccuracyCircleSample {
  * @param map - The Leaflet map to add circles to.
  * @param samples - GPS samples to consider; non-positive / non-finite
  *   `accuracy` values are silently skipped.
- * @param color - CSS color string used for both stroke and fill.
+ * @param color - CSS color string used for the stroke (no fill is drawn).
  * @returns The created `L.Circle` instances, in the order they were added.
  *   Callers that track layers for cleanup can append these to their list.
  */

package/dist/{app-selectors-CrOucL00.d.ts → app-selectors-JqydaUMN.d.ts}

@@ -1,4 +1,4 @@
-import { L as CombinedRootState, r as SlamAppRootState } from "./create-slam-app-store-Ce2FMKCp.js";
+import { N as CombinedRootState, r as SlamAppRootState } from "./create-slam-app-store-D3nzh9Wb.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

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

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

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

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

@@ -1,2 +1,2 @@
-import { i as isFullySupported, n as CapabilitySupport, r as capabilityMessage, t as CapabilityMessageOptions } from "../capability-checker-CXqoJYtb.js";
+import { i as isFullySupported, n as CapabilitySupport, r as capabilityMessage, t as CapabilityMessageOptions } from "../capability-checker-BTTpygvZ.js";
 export { CapabilityMessageOptions, CapabilitySupport, 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-BL5SoG2a.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-_BVfhpxv.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 { 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-BNK189P0.js";
+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-C6yJLXz9.js";
 export { BASELAYER_WINDOW_MAX, BASELAYER_WINDOW_MIN, ChromeVersion, ChromiumProjectionLayerWorkaroundResult, applyChromiumProjectionLayerWorkaround, needsBaseLayerPersistence, parseChromeVersion };

package/dist/ar/depth-grid-lookup.d.ts

@@ -1,2 +1,2 @@
-import { n as createDepthGridLookup, t as DepthGridLookup } from "../depth-grid-lookup-vMDrGTk_.js";
+import { n as createDepthGridLookup, t as DepthGridLookup } from "../depth-grid-lookup-D5atpNZ3.js";
 export { DepthGridLookup, createDepthGridLookup };

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

@@ -0,0 +1,127 @@
+import { t as DepthInfo } from "../depth-sampler-CwObAwEA.js";
+import * as THREE from "three";
+
+//#region ../src/ar/depth-occluder.d.ts
+/** Render order of the full-screen depth writer — before virtual content
+ *  (≥ 0) and at/after the persistent mesh (−2), so it composes with the mesh
+ *  (nearer depth wins) and lays depth before content draws (plan §5). */
+declare const OCCLUDER_RENDER_ORDER = -1;
+/** The two upload formats `XRCPUDepthInformation` resolves to (plan §3a/§10). */
+type DepthTextureFormat = 'r32f' | 'luminance-alpha';
+/**
+ * Convert a **view-space perpendicular depth** `d` (metres in front of the camera)
+ * to a window-space depth in `[0, 1]` using the WebXR `XRView.projectionMatrix`
+ * `P` (column-major 16-tuple). This is the conversion both the per-material and
+ * the full-screen techniques need to compare the real surface against a virtual
+ * fragment's depth (plan §3b):
+ *
+ * ```
+ * z_clip = -d·P[10] + P[14]
+ * w_clip = -d·P[11] + P[15]
+ * z_ndc  = z_clip / w_clip
+ * window = 0.5·z_ndc + 0.5
+ * ```
+ *
+ * Assumes the sampled value is the perpendicular z-distance (WebXR/ARCore depth
+ * semantics). Monotonic in `d` for a standard perspective `P`, and lands in
+ * `[0, 1]` for `d ∈ [near, far]` — both pinned by the property tests.
+ */
+declare function metricDepthToWindowDepth(viewSpaceDepthMeters: number, projectionMatrix: ArrayLike<number>): number;
+/**
+ * Map a normalized **screen** UV (`[0,1]²`, origin bottom-left) to the normalized
+ * **depth-buffer** UV via `XRDepthInformation.normDepthBufferFromNormView`'s
+ * `.matrix` (column-major 16-tuple). The depth texture is not 1:1 with the
+ * framebuffer (it is low-res and may be rotated), so the shader must apply this
+ * transform before sampling (plan §3c). Returns `[u, v]` after the perspective
+ * divide. The identity matrix is a fixed point (verified in tests).
+ */
+declare function screenUvToDepthUv(u: number, v: number, matrix: ArrayLike<number>): [number, number];
+/**
+ * Reconstruct metres from a 16-bit depth value packed across the `luminance`
+ * (low byte) + `alpha` (high byte) channels of an `RG8` texel, then scale by
+ * `XRCPUDepthInformation.rawValueToMeters` (plan §3a/§9). `lo`/`hi` are the two
+ * `0–255` bytes; round-trips a known raw value (property-tested).
+ */
+declare function unpackLuminanceAlphaToMeters(lo: number, hi: number, rawValueToMeters: number): number;
+/**
+ * Pick the `DataTexture` upload format from the resolved depth buffer's byte
+ * count (plan §3a). `float32` raw depth is 4 bytes/texel → `r32f`; the
+ * `luminance-alpha` 16-bit packing is 2 bytes/texel. We read the actual
+ * resolved layout at runtime rather than assuming the `dataFormatPreference`
+ * order, because the UA chooses (plan §3a "read it at runtime").
+ */
+declare function selectDepthTextureFormat(width: number, height: number, byteLength: number): DepthTextureFormat;
+/**
+ * GLSL for the **full-screen depth-write occluder** (v1 — the "do what the
+ * persistent mesh does" path). A clip-space quad whose fragment shader samples
+ * the live depth map and writes `gl_FragDepth` from the real surface depth, so
+ * the normal depth test then hides ALL virtual content behind real surfaces —
+ * no per-material patching (2026-06-29-occlusion-debug-viz-and-live-occluder
+ * user-feedback Finding 2).
+ *
+ * The fragment math **mirrors the CI-tested pure functions**:
+ * `screenUvToDepthUv` (the `uDepthUvFromScreenUv` transform + perspective
+ * divide), the `luminance-alpha`→metres unpack, the holes policy (no/invalid
+ * depth ⇒ `discard` ⇒ never occlude, so the persistent mesh shows through), and
+ * `metricDepthToWindowDepth` (the projection-matrix metres→window-depth step).
+ *
+ * The vertex shader maps the quad's NDC position to a `[0,1]` screen UV varying,
+ * so the shader needs **no resolution uniform** (the interpolated UV *is* the
+ * normalized screen coordinate). Mono AR (one `XRView`) — plan §3c.
+ *
+ * **Device-gated tuning** (the on-device gate, not CI): the depth-UV Y
+ * orientation, the float-vs-packed default, and that `gl_FragDepth` is writable
+ * on the target (it may need an extension/`glslVersion` on some renderers).
+ */
+declare function buildFullscreenOcclusionShader(): {
+  vertexShader: string;
+  fragmentShader: string;
+};
+/**
+ * Manages the live occluder's GPU side: one small per-frame depth `DataTexture`,
+ * the shared uniform block, and the full-screen depth-write mesh. Construct once
+ * per AR session, `update(depthInfo)` each frame from the wrapped
+ * `XRCPUDepthInformation`, mount {@link getOcclusionMesh} in the AR scene, and
+ * `dispose()` on session end.
+ *
+ * The GLSL is a **device-gated first-light draft** (see the file header): its
+ * CPU-observable effects are unit-tested, but the on-device occlusion must be
+ * verified and tuned (plan §8 Iter 2–3) before `liveOcclusion` ships on.
+ */
+declare class DepthOccluder {
+  private readonly uniforms;
+  private fullscreenMesh;
+  private texture;
+  private textureFormat;
+  private textureWidth;
+  private textureHeight;
+  private disposed;
+  constructor();
+  /** Whether a usable depth texture has been uploaded (occlusion is live). */
+  isEnabled(): boolean;
+  /** The current upload format, or null before the first {@link update}. */
+  getTextureFormat(): DepthTextureFormat | null;
+  /**
+   * The **full-screen depth-write occluder** mesh (v1 path) — lazily created and
+   * cached. Add it to the AR scene (its vertex shader ignores transforms, so the
+   * parent node is irrelevant; the recorder adds it under `arWorldGroup`). It is
+   * `colorWrite:false` / `depthWrite:true` / `depthTest:true` at
+   * {@link OCCLUDER_RENDER_ORDER}, so it lays the real-surface depth before
+   * virtual content draws and composes with the persistent mesh (nearer wins).
+   * Shares the live uniform block, so each {@link update} reaches it.
+   */
+  getOcclusionMesh(): THREE.Mesh;
+  /**
+   * Upload this frame's depth + metadata. No-op (and disables occlusion) when the
+   * depth info lacks the occluder fields (`data` / `rawValueToMeters` /
+   * `normDepthBufferFromNormView` / `projectionMatrix`) — e.g. a sparse-only
+   * frame — so a degraded frame can never occlude with stale or absent depth.
+   */
+  update(depthInfo: DepthInfo): void;
+  /** (Re)create the DataTexture on a size/format change, else refresh its data. */
+  private ensureTexture;
+  /** Release the depth texture and the full-screen mesh. */
+  dispose(): void;
+}
+//#endregion
+export { DepthOccluder, DepthTextureFormat, OCCLUDER_RENDER_ORDER, buildFullscreenOcclusionShader, metricDepthToWindowDepth, screenUvToDepthUv, selectDepthTextureFormat, unpackLuminanceAlphaToMeters };

package/dist/ar/depth-occluder.js

@@ -0,0 +1,299 @@
+import * as THREE from "three";
+//#region ../src/ar/depth-occluder.ts
+/**
+* Live CPU-depth occluder — hides virtual fragments behind the real surface the
+* camera sees *this frame*.
+*
+* Companion to the **persistent** `OcclusionMesh` (`visualization/occlusion-mesh.ts`):
+* that one meshes the accumulated occupancy grid (remembers out-of-view geometry,
+* blocky, lagging); this one reads the per-frame `XRCPUDepthInformation` and
+* occludes per-pixel against the surface currently in view (sharp, registration-
+* free, no memory). They **compose** — both depth-only under `arWorldGroup`, the
+* live occluder wins where this frame has depth, the mesh fills out-of-view / depth
+* holes (2026-06-14-webxr-depth-occlusion-plan.md §5).
+*
+* **Two layers, two confidence levels:**
+*  - The **pure occlusion math** (this file's exported functions) is the CI-tested
+*    core (plan §9): the metric-depth→window-depth conversion, the screen-UV→depth-UV
+*    transform, the `luminance-alpha`→metres unpack, the depth-texture format
+*    selection, and the soft-margin / holes occlusion-strength policy. These are
+*    deterministic and property-tested.
+*  - The **{@link DepthOccluder} class** owns the per-frame `THREE.DataTexture`
+*    upload, the shared uniform block, the lifecycle (enable / dispose), and the
+*    **full-screen depth-write render path** ({@link DepthOccluder.getOcclusionMesh}):
+*    a clip-space quad that writes `gl_FragDepth` from the live depth map, so the
+*    normal depth test hides **all** virtual content behind real surfaces — the
+*    "do what the persistent mesh does" path the recorder uses (2026-06-29
+*    occlusion-debug-viz-and-live-occluder feedback Finding 2). Hard-edged.
+*    The JS-observable behaviour (texture (re)creation, uniform updates, mesh
+*    construction, disposal) is unit-tested in jsdom, but the **actual GLSL occlusion
+*    is device-gated** (plan §8 Iter 2–3): no headless GL renders it, so the shader is
+*    a first-light draft to verify/tune on-device (the `gl_FragDepth` sanity check,
+*    the depth-UV Y orientation, the float-vs-packed default). Keep
+*    `occupancy.liveOcclusion` OFF by default until that verification lands.
+*
+*    (A second render path — a per-material soft-margin `onBeforeCompile`
+*    injection, "Phase B" — existed here as a never-wired draft until 2026-07-04
+*    and was deleted: dead code that review bots kept re-flagging. Recover it
+*    from git history if a per-material fade is ever actually built.)
+*
+* @see depth-occluder.ts.md for detailed documentation
+* @see ar/depth-sampler.ts — `DepthInfo` / `wrapXRDepthInfo` (the per-frame source)
+*/
+/** Render order of the full-screen depth writer — before virtual content
+*  (≥ 0) and at/after the persistent mesh (−2), so it composes with the mesh
+*  (nearer depth wins) and lays depth before content draws (plan §5). */
+const OCCLUDER_RENDER_ORDER = -1;
+/**
+* Convert a **view-space perpendicular depth** `d` (metres in front of the camera)
+* to a window-space depth in `[0, 1]` using the WebXR `XRView.projectionMatrix`
+* `P` (column-major 16-tuple). This is the conversion both the per-material and
+* the full-screen techniques need to compare the real surface against a virtual
+* fragment's depth (plan §3b):
+*
+* ```
+* z_clip = -d·P[10] + P[14]
+* w_clip = -d·P[11] + P[15]
+* z_ndc  = z_clip / w_clip
+* window = 0.5·z_ndc + 0.5
+* ```
+*
+* Assumes the sampled value is the perpendicular z-distance (WebXR/ARCore depth
+* semantics). Monotonic in `d` for a standard perspective `P`, and lands in
+* `[0, 1]` for `d ∈ [near, far]` — both pinned by the property tests.
+*/
+function metricDepthToWindowDepth(viewSpaceDepthMeters, projectionMatrix) {
+	const d = viewSpaceDepthMeters;
+	const p10 = projectionMatrix[10] ?? 0;
+	const p11 = projectionMatrix[11] ?? 0;
+	const p14 = projectionMatrix[14] ?? 0;
+	const p15 = projectionMatrix[15] ?? 0;
+	return .5 * ((-d * p10 + p14) / (-d * p11 + p15)) + .5;
+}
+/**
+* Map a normalized **screen** UV (`[0,1]²`, origin bottom-left) to the normalized
+* **depth-buffer** UV via `XRDepthInformation.normDepthBufferFromNormView`'s
+* `.matrix` (column-major 16-tuple). The depth texture is not 1:1 with the
+* framebuffer (it is low-res and may be rotated), so the shader must apply this
+* transform before sampling (plan §3c). Returns `[u, v]` after the perspective
+* divide. The identity matrix is a fixed point (verified in tests).
+*/
+function screenUvToDepthUv(u, v, matrix) {
+	const at = (i) => matrix[i] ?? 0;
+	const x = at(0) * u + at(4) * v + at(12);
+	const y = at(1) * u + at(5) * v + at(13);
+	const w = at(3) * u + at(7) * v + at(15);
+	if (w !== 0 && Number.isFinite(w)) return [x / w, y / w];
+	return [x, y];
+}
+/**
+* Reconstruct metres from a 16-bit depth value packed across the `luminance`
+* (low byte) + `alpha` (high byte) channels of an `RG8` texel, then scale by
+* `XRCPUDepthInformation.rawValueToMeters` (plan §3a/§9). `lo`/`hi` are the two
+* `0–255` bytes; round-trips a known raw value (property-tested).
+*/
+function unpackLuminanceAlphaToMeters(lo, hi, rawValueToMeters) {
+	return ((lo & 255) + (hi & 255) * 256) * rawValueToMeters;
+}
+/**
+* Pick the `DataTexture` upload format from the resolved depth buffer's byte
+* count (plan §3a). `float32` raw depth is 4 bytes/texel → `r32f`; the
+* `luminance-alpha` 16-bit packing is 2 bytes/texel. We read the actual
+* resolved layout at runtime rather than assuming the `dataFormatPreference`
+* order, because the UA chooses (plan §3a "read it at runtime").
+*/
+function selectDepthTextureFormat(width, height, byteLength) {
+	const texels = width * height;
+	if (texels > 0 && byteLength >= texels * 4) return "r32f";
+	return "luminance-alpha";
+}
+/**
+* GLSL for the **full-screen depth-write occluder** (v1 — the "do what the
+* persistent mesh does" path). A clip-space quad whose fragment shader samples
+* the live depth map and writes `gl_FragDepth` from the real surface depth, so
+* the normal depth test then hides ALL virtual content behind real surfaces —
+* no per-material patching (2026-06-29-occlusion-debug-viz-and-live-occluder
+* user-feedback Finding 2).
+*
+* The fragment math **mirrors the CI-tested pure functions**:
+* `screenUvToDepthUv` (the `uDepthUvFromScreenUv` transform + perspective
+* divide), the `luminance-alpha`→metres unpack, the holes policy (no/invalid
+* depth ⇒ `discard` ⇒ never occlude, so the persistent mesh shows through), and
+* `metricDepthToWindowDepth` (the projection-matrix metres→window-depth step).
+*
+* The vertex shader maps the quad's NDC position to a `[0,1]` screen UV varying,
+* so the shader needs **no resolution uniform** (the interpolated UV *is* the
+* normalized screen coordinate). Mono AR (one `XRView`) — plan §3c.
+*
+* **Device-gated tuning** (the on-device gate, not CI): the depth-UV Y
+* orientation, the float-vs-packed default, and that `gl_FragDepth` is writable
+* on the target (it may need an extension/`glslVersion` on some renderers).
+*/
+function buildFullscreenOcclusionShader() {
+	return {
+		vertexShader: `
+varying vec2 vScreenUv;
+void main() {
+  // Fullscreen clip-space quad: 'position' (PlaneGeometry(2,2)) is already in
+  // NDC [-1,1]; the interpolated [0,1] uv is the normalized screen coordinate,
+  // so no resolution uniform is needed. View/projection are intentionally
+  // ignored — this writes gl_FragDepth, not geometry depth.
+  vScreenUv = position.xy * 0.5 + 0.5;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`,
+		fragmentShader: `
+precision highp float;
+uniform sampler2D uDepthTexture;
+uniform float uRawValueToMeters;
+uniform mat4 uDepthUvFromScreenUv;
+uniform mat4 uProjectionMatrix;
+uniform float uOccluderEnabled;
+uniform float uPackedDepth;
+varying vec2 vScreenUv;
+void main() {
+  // No valid depth this frame → write nothing (frame-level holes policy).
+  if (uOccluderEnabled < 0.5) { discard; }
+  // Normalized screen UV → depth-buffer UV (low-res / possibly rotated), then
+  // perspective divide — mirrors screenUvToDepthUv.
+  vec4 duv = uDepthUvFromScreenUv * vec4(vScreenUv, 0.0, 1.0);
+  vec2 depthUv = duv.xy / duv.w;
+  vec4 texel = texture2D(uDepthTexture, depthUv);
+  // Reconstruct metres: packed luminance-alpha (lo + hi*256) or float R32F.
+  float realDepthMeters = uPackedDepth > 0.5
+    ? (texel.r * 255.0 + texel.g * 255.0 * 256.0) * uRawValueToMeters
+    : texel.r * uRawValueToMeters;
+  // Hole / invalid texel → never occlude (per-texel holes policy).
+  if (!(realDepthMeters > 0.0)) { discard; }
+  // metres → window depth via the WebXR projection matrix (column-major
+  // [col][row]) — mirrors metricDepthToWindowDepth.
+  float zClip = -realDepthMeters * uProjectionMatrix[2][2] + uProjectionMatrix[3][2];
+  float wClip = -realDepthMeters * uProjectionMatrix[2][3] + uProjectionMatrix[3][3];
+  gl_FragDepth = 0.5 * (zClip / wClip) + 0.5;
+  // colorWrite is off on the material; this is only here to satisfy GLSL1.
+  gl_FragColor = vec4(0.0);
+}
+`
+	};
+}
+/**
+* Manages the live occluder's GPU side: one small per-frame depth `DataTexture`,
+* the shared uniform block, and the full-screen depth-write mesh. Construct once
+* per AR session, `update(depthInfo)` each frame from the wrapped
+* `XRCPUDepthInformation`, mount {@link getOcclusionMesh} in the AR scene, and
+* `dispose()` on session end.
+*
+* The GLSL is a **device-gated first-light draft** (see the file header): its
+* CPU-observable effects are unit-tested, but the on-device occlusion must be
+* verified and tuned (plan §8 Iter 2–3) before `liveOcclusion` ships on.
+*/
+var DepthOccluder = class {
+	uniforms;
+	fullscreenMesh = null;
+	texture = null;
+	textureFormat = null;
+	textureWidth = 0;
+	textureHeight = 0;
+	disposed = false;
+	constructor() {
+		this.uniforms = {
+			uDepthTexture: { value: null },
+			uRawValueToMeters: { value: 1 },
+			uDepthUvFromScreenUv: { value: new THREE.Matrix4() },
+			uProjectionMatrix: { value: new THREE.Matrix4() },
+			uOccluderEnabled: { value: 0 },
+			uPackedDepth: { value: 0 }
+		};
+	}
+	/** Whether a usable depth texture has been uploaded (occlusion is live). */
+	isEnabled() {
+		return this.uniforms.uOccluderEnabled.value === 1;
+	}
+	/** The current upload format, or null before the first {@link update}. */
+	getTextureFormat() {
+		return this.textureFormat;
+	}
+	/**
+	* The **full-screen depth-write occluder** mesh (v1 path) — lazily created and
+	* cached. Add it to the AR scene (its vertex shader ignores transforms, so the
+	* parent node is irrelevant; the recorder adds it under `arWorldGroup`). It is
+	* `colorWrite:false` / `depthWrite:true` / `depthTest:true` at
+	* {@link OCCLUDER_RENDER_ORDER}, so it lays the real-surface depth before
+	* virtual content draws and composes with the persistent mesh (nearer wins).
+	* Shares the live uniform block, so each {@link update} reaches it.
+	*/
+	getOcclusionMesh() {
+		if (!this.fullscreenMesh) {
+			const { vertexShader, fragmentShader } = buildFullscreenOcclusionShader();
+			const material = new THREE.ShaderMaterial({
+				uniforms: this.uniforms,
+				vertexShader,
+				fragmentShader,
+				colorWrite: false,
+				depthWrite: true,
+				depthTest: true
+			});
+			const mesh = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), material);
+			mesh.name = "live-depth-occluder";
+			mesh.frustumCulled = false;
+			mesh.renderOrder = -1;
+			this.fullscreenMesh = mesh;
+		}
+		return this.fullscreenMesh;
+	}
+	/**
+	* Upload this frame's depth + metadata. No-op (and disables occlusion) when the
+	* depth info lacks the occluder fields (`data` / `rawValueToMeters` /
+	* `normDepthBufferFromNormView` / `projectionMatrix`) — e.g. a sparse-only
+	* frame — so a degraded frame can never occlude with stale or absent depth.
+	*/
+	update(depthInfo) {
+		if (this.disposed) return;
+		const { data, rawValueToMeters, normDepthBufferFromNormView } = depthInfo;
+		if (!data || typeof rawValueToMeters !== "number" || !normDepthBufferFromNormView || !depthInfo.projectionMatrix) {
+			this.uniforms.uOccluderEnabled.value = 0;
+			return;
+		}
+		const { width, height } = depthInfo;
+		const format = selectDepthTextureFormat(width, height, data.byteLength);
+		this.ensureTexture(width, height, format, data);
+		this.uniforms.uPackedDepth.value = format === "luminance-alpha" ? 1 : 0;
+		this.uniforms.uRawValueToMeters.value = rawValueToMeters;
+		this.uniforms.uDepthUvFromScreenUv.value.fromArray(normDepthBufferFromNormView);
+		this.uniforms.uProjectionMatrix.value.fromArray(depthInfo.projectionMatrix);
+		this.uniforms.uOccluderEnabled.value = 1;
+	}
+	/** (Re)create the DataTexture on a size/format change, else refresh its data. */
+	ensureTexture(width, height, format, data) {
+		if (this.texture === null || this.textureWidth !== width || this.textureHeight !== height || this.textureFormat !== format) {
+			this.texture?.dispose();
+			this.texture = format === "r32f" ? new THREE.DataTexture(new Float32Array(data), width, height, THREE.RedFormat, THREE.FloatType) : new THREE.DataTexture(new Uint8Array(data), width, height, THREE.RGFormat, THREE.UnsignedByteType);
+			this.texture.needsUpdate = true;
+			this.textureWidth = width;
+			this.textureHeight = height;
+			this.textureFormat = format;
+			this.uniforms.uDepthTexture.value = this.texture;
+		} else if (this.texture) {
+			const image = this.texture.image;
+			image.data = format === "r32f" ? new Float32Array(data) : new Uint8Array(data);
+			this.texture.needsUpdate = true;
+		}
+	}
+	/** Release the depth texture and the full-screen mesh. */
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.uniforms.uOccluderEnabled.value = 0;
+		this.uniforms.uDepthTexture.value = null;
+		this.texture?.dispose();
+		this.texture = null;
+		if (this.fullscreenMesh) {
+			this.fullscreenMesh.removeFromParent();
+			this.fullscreenMesh.geometry.dispose();
+			this.fullscreenMesh.material.dispose();
+			this.fullscreenMesh = null;
+		}
+	}
+};
+//#endregion
+export { DepthOccluder, OCCLUDER_RENDER_ORDER, buildFullscreenOcclusionShader, metricDepthToWindowDepth, screenUvToDepthUv, selectDepthTextureFormat, unpackLuminanceAlphaToMeters };

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

@@ -1,3 +1,3 @@
-import { i as DepthSample } from "../ar-types-BckI1E-O.js";
-import { a as wrapXRDepthInfo, i as DepthSamplerConfig, n as DepthSampler, r as DepthSamplerCallbacks, t as DepthInfo } from "../depth-sampler-DwfPYzS7.js";
+import { i as DepthSample } from "../ar-types-Cc5yvBwn.js";
+import { a as wrapXRDepthInfo, i as DepthSamplerConfig, n as DepthSampler, r as DepthSamplerCallbacks, t as DepthInfo } from "../depth-sampler-CwObAwEA.js";
 export { DepthInfo, DepthSample, DepthSampler, DepthSamplerCallbacks, DepthSamplerConfig, wrapXRDepthInfo };

package/dist/ar/depth-sampler.js

@@ -1,6 +1,18 @@
 import { extractOdomPosition } from "../state/gps-event-coordinator.js";
 //#region ../src/ar/depth-sampler.ts
 /**
+* Defensively copy a 16-element column-major matrix into a plain serializable
+* tuple. Returns undefined for missing input, the wrong length, or any
+* non-finite entry — so an invalid (or UA-reused/garbage) source degrades to
+* "absent" rather than poisoning downstream maths. The copy also de-aliases
+* Float32Arrays the UA reuses across frames.
+*/
+function copyValidMatrix16(src) {
+	if (!src || src.length !== 16) return;
+	const copy = Array.from(src);
+	return copy.every((v) => Number.isFinite(v)) ? copy : void 0;
+}
+/**
 * Wrap a raw browser XRDepthInformation object into a {@link DepthInfo}.
 *
 * - `getDepthInMeters` is bound to the source object (browser
@@ -9,6 +21,12 @@ import { extractOdomPosition } from "../state/gps-event-coordinator.js";
 *   the UA may reuse across frames) is defensively validated and copied into
 *   a plain serializable 16-tuple; invalid input (wrong length, non-finite
 *   entries) yields a DepthInfo without a matrix rather than an error.
+* - The live-occluder metadata (`data`, `rawValueToMeters`,
+*   `normDepthBufferFromNormView`) is preserved when present and valid: `data`
+*   by live reference (no clone — see {@link DepthInfo.data}), the scale only
+*   when finite, and the UV transform's `.matrix` copied like
+*   `projectionMatrix`. The sparse grid sampler ignores all three; a source
+*   lacking them (e.g. the existing test doubles) wraps exactly as before.
 */
 function wrapXRDepthInfo(raw, projectionMatrix) {
 	const wrapped = {
@@ -16,10 +34,12 @@ function wrapXRDepthInfo(raw, projectionMatrix) {
 		height: raw.height,
 		getDepthInMeters: raw.getDepthInMeters.bind(raw)
 	};
-	if (projectionMatrix && projectionMatrix.length === 16) {
-		const copy = Array.from(projectionMatrix);
-		if (copy.every((v) => Number.isFinite(v))) wrapped.projectionMatrix = copy;
-	}
+	const projection = copyValidMatrix16(projectionMatrix);
+	if (projection) wrapped.projectionMatrix = projection;
+	if (raw.data instanceof ArrayBuffer) wrapped.data = raw.data;
+	if (typeof raw.rawValueToMeters === "number" && Number.isFinite(raw.rawValueToMeters)) wrapped.rawValueToMeters = raw.rawValueToMeters;
+	const uvTransform = copyValidMatrix16(raw.normDepthBufferFromNormView?.matrix);
+	if (uvTransform) wrapped.normDepthBufferFromNormView = uvTransform;
 	return wrapped;
 }
 const DEFAULT_CONFIG = {

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

@@ -1,2 +1,2 @@
-import { n as createDepthUnprojector, r as unprojectDepthPoint, t as DepthUnprojector } from "../depth-unprojection-CK3b9htH.js";
+import { n as createDepthUnprojector, r as unprojectDepthPoint, t as DepthUnprojector } from "../depth-unprojection-DRdBU90S.js";
 export { DepthUnprojector, createDepthUnprojector, unprojectDepthPoint };