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

package/dist/visualization/occlusion-mesh.js

@@ -0,0 +1,437 @@
+import { WEBXR_TO_NUE } from "../ar/webxr-nue-basis.js";
+import { meshOccupiedCells } from "../ar/occupancy-mesher.js";
+import * as THREE from "three";
+//#region ../src/visualization/occlusion-mesh.ts
+/**
+* Persistent occlusion mesh — a depth-only `THREE.Mesh` of the occupancy grid.
+*
+* Wraps the pure {@link meshOccupiedCells} (face-culled voxel surface) into a
+* THREE object that **writes depth but no color** (`colorWrite = false`,
+* `depthWrite = true`), drawn before virtual content (low `renderOrder`) so real
+* geometry the camera saw earlier hides virtual objects placed behind it —
+* including out-of-view surfaces a single-frame live depth occluder cannot
+* remember (2026-06-13-occupancy-mesh-options-plan.md §4; complements the live
+* occluder in 2026-06-14-webxr-depth-occlusion-plan.md).
+*
+* Reusable across consumer apps (AnchorStarter / MinimalExample want occlusion
+* too); the recorder only owns the off-by-default toggle + scene wiring.
+*
+* Coordinate space: the grid cells (and therefore the mesh positions) are **raw
+* WebXR**, but the parent `arWorldGroup` is AR-odometry NUE. The mesh carries
+* the constant `WEBXR_TO_NUE` basis change as its own local matrix — identical
+* to `OccupancyCubesVisualizer` — so it rides the `alignment × WEBXR_TO_NUE`
+* chain. The parent node is injected (no `getArWorldGroup()`) to stay testable.
+*
+* Scope: this is a full-rebuild occluder (re-mesh the whole snapshot on
+* `update`). The chunked dirty-remesh perf layer (plan §7) is a follow-on.
+*
+* @see occlusion-mesh.ts.md for detailed documentation
+*/
+const MESH_NAME = "occupancy-occluder";
+const DEBUG_MESH_NAME = "occupancy-occluder-debug";
+const DEBUG_WIREFRAME_MESH_NAME = "occupancy-occluder-debug-wireframe";
+/** Default render order — well before virtual content (which is ≥ 0). */
+const DEFAULT_RENDER_ORDER = -1;
+/** Opacity of the matcap debug skin — see-through enough to read the real scene
+*  behind it while the shape stays legible. */
+const DEBUG_SKIN_OPACITY = .6;
+/** Light-cyan GL lines of the wireframe skin — faint enough not to swamp the
+*  shaded skin in the combined style, visible enough to read triangle density. */
+const WIREFRAME_COLOR = 11202303;
+const WIREFRAME_OPACITY = .35;
+/** Which styles shade with the matcap (and therefore need vertex normals —
+*  pure 'wireframe' is unlit and keeps the remesh path normal-free). */
+function styleNeedsNormals(style) {
+	return style === "matcap" || style === "depth-shaded" || style === "depth-shaded-wireframe";
+}
+/**
+* Depth-shaded debug-skin constants — **module constants, not user settings**
+* (tune in code after the first on-device look; 2026-07-02 debug-viz-styles
+* plan). Exported so the unit/property tests of the GLSL-mirror curves below
+* pin the same numbers the shader bakes in.
+*/
+const OCCLUDER_DEPTH_SHADE = {
+	/** Distance (m) where the fade starts — nearer stays full-bright cyan.
+	*  Indoor-scale since the 2026-07-03 field pass (finding F1): the original
+	*  1.5 → 10 m range kept a whole room in the "near" band (94% brightness at
+	*  3 m), making depth-shaded indistinguishable from matcap on device. */
+	FADE_START_M: .75,
+	/** Distance (m) where the fade bottoms out at {@link FADE_MIN_BRIGHTNESS}.
+	*  ~Room depth, so indoor scenes span the full near→far gradient; beyond it
+	*  everything sits uniformly at the floor (still separated from near). */
+	FADE_END_M: 4.5,
+	/** Brightness floor far away — never fades to black, so distant mesh stays
+	*  inspectable (the reason the fog-to-background idea was rejected). */
+	FADE_MIN_BRIGHTNESS: .3,
+	/** Fresnel exponent — higher hugs the silhouette tighter. */
+	RIM_POWER: 2.5,
+	/** White-rim contribution at a fully grazing view angle. */
+	RIM_STRENGTH: .6
+};
+/** Far-distance fade target (dark desaturated blue) — keeps the occluder's
+*  single-color cyan identity while clearly separating far from near. */
+const FADE_TARGET_RGB = [
+	.03,
+	.07,
+	.12
+];
+/** GLSL `smoothstep` (clamped Hermite), mirrored exactly for the TS curves. */
+function smoothstep(edge0, edge1, x) {
+	const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
+	return t * t * (3 - 2 * t);
+}
+/**
+* Pure TS mirror of the shader's **distance fade**: 1 at/inside FADE_START_M,
+* smoothly down to FADE_MIN_BRIGHTNESS at/after FADE_END_M. The fragment color
+* is `mix(darkBlue, matcapColor, fade)` — near = bright cyan, far = dark blue.
+* Mirrored so the curve is unit-testable without a GPU (the
+* `buildFullscreenOcclusionShader` GLSL-mirror precedent).
+*/
+function occluderDepthFade(distanceM) {
+	const { FADE_START_M, FADE_END_M, FADE_MIN_BRIGHTNESS } = OCCLUDER_DEPTH_SHADE;
+	return 1 - (1 - FADE_MIN_BRIGHTNESS) * smoothstep(FADE_START_M, FADE_END_M, distanceM);
+}
+/**
+* Pure TS mirror of the shader's **fresnel rim**: 0 where the surface faces
+* the camera head-on (|cos| = 1), RIM_STRENGTH at a fully grazing angle
+* (cos = 0) — silhouettes brighten, so overlapping shells read as separate.
+*
+* @param cosViewAngle `dot(normal, viewDir)` — cosine of the angle between the
+*   surface normal and the view direction, in [-1, 1].
+*/
+function occluderFresnelRim(cosViewAngle) {
+	const { RIM_POWER, RIM_STRENGTH } = OCCLUDER_DEPTH_SHADE;
+	return RIM_STRENGTH * Math.pow(1 - Math.abs(cosViewAngle), RIM_POWER);
+}
+/** A number as a GLSL float literal (fixed decimals so it never reads as int). */
+function glslFloat(value) {
+	return value.toFixed(4);
+}
+/**
+* The fragment-shader snippet the depth-shaded material injects before
+* `#include <opaque_fragment>` in three.js's matcap fragment shader — the
+* point where `outgoingLight` (matcap-lit color), `normal` and `viewDir` /
+* `vViewPosition` are all in scope. Exported so tests can pin the exact
+* injected code. Constants are baked as literals (no uniforms — they are
+* module constants by design, see {@link OCCLUDER_DEPTH_SHADE}).
+*/
+function buildOccluderDepthShadeSnippet() {
+	const { FADE_START_M, FADE_END_M, FADE_MIN_BRIGHTNESS, RIM_POWER } = OCCLUDER_DEPTH_SHADE;
+	const { RIM_STRENGTH } = OCCLUDER_DEPTH_SHADE;
+	const [r, g, b] = FADE_TARGET_RGB;
+	return [
+		"// Occluder debug depth-shading: distance fade + fresnel rim (2026-07-02).",
+		`float dbgDistance = length( vViewPosition );`,
+		`float dbgFade = 1.0 - ( 1.0 - ${glslFloat(FADE_MIN_BRIGHTNESS)} ) * smoothstep( ${glslFloat(FADE_START_M)}, ${glslFloat(FADE_END_M)}, dbgDistance );`,
+		`outgoingLight = mix( vec3( ${glslFloat(r)}, ${glslFloat(g)}, ${glslFloat(b)} ), outgoingLight, dbgFade );`,
+		`float dbgRim = ${glslFloat(RIM_STRENGTH)} * pow( 1.0 - abs( dot( normal, viewDir ) ), ${glslFloat(RIM_POWER)} );`,
+		`outgoingLight += vec3( 1.0 ) * dbgRim;`
+	].join("\n	");
+}
+/**
+* Build a tiny procedural matcap texture (a shaded sphere with a specular
+* highlight) so the debug skin reads as a **shiny** surface with **no scene
+* lights** — `MeshMatcapMaterial` bakes the lighting into this lookup. Generated
+* from a typed array (no canvas/WebGL), so it works headless in tests too.
+*/
+function createOccluderDebugMatcap() {
+	const size = 64;
+	const data = new Uint8Array(size * size * 4);
+	const lx = .4;
+	const ly = .5;
+	const lz = .75;
+	const llen = Math.hypot(lx, ly, lz);
+	for (let j = 0; j < size; j++) for (let i = 0; i < size; i++) {
+		const idx = (j * size + i) * 4;
+		const nx = (i + .5) / size * 2 - 1;
+		const ny = (j + .5) / size * 2 - 1;
+		const r2 = nx * nx + ny * ny;
+		let r = 12;
+		let g = 12;
+		let b = 14;
+		if (r2 <= 1) {
+			const nz = Math.sqrt(1 - r2);
+			const ndl = Math.max(0, (nx * lx + ny * ly + nz * lz) / llen);
+			const diff = .25 + .75 * ndl;
+			const spec = Math.pow(ndl, 32);
+			r = Math.min(255, 255 * (.15 * diff + spec));
+			g = Math.min(255, 255 * (.55 * diff + spec));
+			b = Math.min(255, 255 * (.78 * diff + spec));
+		}
+		data[idx] = r;
+		data[idx + 1] = g;
+		data[idx + 2] = b;
+		data[idx + 3] = 255;
+	}
+	const tex = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+	tex.needsUpdate = true;
+	return tex;
+}
+/**
+* A depth-only occlusion mesh that rebuilds from an occupancy-grid snapshot.
+* Mirrors {@link OccupancyCubesVisualizer}'s lifecycle (inject parent, `update`,
+* `clear`, `dispose`) so the recorder can wire it the same way as the cubes.
+*/
+var OcclusionMesh = class {
+	arSpaceNode;
+	greedy;
+	mode;
+	material;
+	mesh;
+	geometry;
+	lastAabbs = [];
+	disposed = false;
+	debugStyle = "off";
+	shadedSkin = null;
+	wireframeSkin = null;
+	matcapTexture = null;
+	matcapMaterial = null;
+	depthShadedMaterial = null;
+	wireframeMaterial = null;
+	/**
+	* @param arSpaceNode the AR-odometry-NUE node that receives the alignment
+	*   matrix (`arWorldGroup` live, `replaySceneState.arWorldGroup` in replay).
+	*/
+	constructor(arSpaceNode, options = {}) {
+		this.arSpaceNode = arSpaceNode;
+		this.greedy = options.greedy ?? true;
+		this.mode = options.mode;
+		this.geometry = new THREE.BufferGeometry();
+		this.material = new THREE.MeshBasicMaterial({
+			colorWrite: false,
+			depthWrite: true
+		});
+		this.mesh = new THREE.Mesh(this.geometry, this.material);
+		this.mesh.name = MESH_NAME;
+		this.mesh.renderOrder = options.renderOrder ?? DEFAULT_RENDER_ORDER;
+		this.mesh.frustumCulled = false;
+		this.mesh.matrixAutoUpdate = false;
+		this.mesh.matrix.copy(WEBXR_TO_NUE);
+		this.arSpaceNode.add(this.mesh);
+	}
+	/** The number of triangles currently drawn. */
+	getTriangleCount() {
+		const index = this.geometry.getIndex();
+		return index ? index.count / 3 : 0;
+	}
+	/** The AABB list from the most recent {@link update} (physics export hook). */
+	getAabbs() {
+		return this.lastAabbs;
+	}
+	/**
+	* Re-mesh from a fresh occupied-cell snapshot. Pass
+	* `grid.getOccupiedCells(occupancy.minConfidence)` so the occluder shares the
+	* same noise floor as the cubes and the COLMAP export.
+	*
+	* @param getCellPoint optional per-cell measured-centroid provider
+	*   (`grid.getCellPoint`); only consumed when this occluder was constructed
+	*   with `mode: 'smooth'` (otherwise ignored). When omitted under `'smooth'`,
+	*   the surface nets falls back to cell centres.
+	*/
+	update(cells, cellSizeM, getCellPoint) {
+		if (this.disposed) return;
+		const { positions, indices, aabbs } = meshOccupiedCells(cells, cellSizeM, this.mode ? {
+			mode: this.mode,
+			getCellPoint
+		} : { greedy: this.greedy });
+		this.lastAabbs = aabbs;
+		this.swapGeometry(positions, indices);
+	}
+	/**
+	* Apply **precomputed** geometry (positions/indices) without meshing — the
+	* entry point for the Web Worker offload: the driver posts the occupied-cell
+	* snapshot to a worker (`packMeshRequest`/`runMeshRequest`), and this swaps in
+	* the returned typed arrays off the render-critical path. Byte-identical result
+	* to {@link update} for the same input.
+	*
+	* The AABB physics hook is NOT populated on this path (the worker returns
+	* geometry only; AABBs are an export hook unused by rendering) — {@link getAabbs}
+	* returns empty here. Use the synchronous {@link update} if AABBs are needed.
+	*/
+	applyMeshData(positions, indices) {
+		if (this.disposed) return;
+		this.lastAabbs = [];
+		this.swapGeometry(positions, indices);
+	}
+	/**
+	* Replace the geometry wholesale from typed arrays — a full rebuild is the
+	* simple first cut; dispose the old buffers to avoid leaking GPU memory across
+	* refreshes.
+	*/
+	swapGeometry(positions, indices) {
+		const next = new THREE.BufferGeometry();
+		next.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+		next.setIndex(new THREE.BufferAttribute(indices, 1));
+		if (styleNeedsNormals(this.debugStyle)) next.computeVertexNormals();
+		this.geometry.dispose();
+		this.geometry = next;
+		this.mesh.geometry = next;
+		this.rebindSkinGeometry(next);
+	}
+	/** Point every active debug skin at the (new) shared geometry. */
+	rebindSkinGeometry(geometry) {
+		if (this.shadedSkin) this.shadedSkin.geometry = geometry;
+		if (this.wireframeSkin) this.wireframeSkin.geometry = geometry;
+	}
+	/**
+	* Select which **visible debug skin(s)** render the occluder mesh so its
+	* shape and structure can be judged on-device (2026-07-02 debug-viz-styles
+	* plan): the original `'matcap'` skin, a `'depth-shaded'` variant (distance
+	* fade + fresnel rim, separates overlapping layers), a `'wireframe'` overlay
+	* (the raw triangulation as GL lines), the combined
+	* `'depth-shaded-wireframe'`, or `'off'`.
+	*
+	* Additive by design: every style adds/removes separate skin meshes sharing
+	* the occluder's geometry and **never touches the invisible depth-only
+	* mesh**, so occlusion is byte-for-byte unchanged whichever style is active.
+	* The skins are `transparent` with `depthWrite:false` (the depth-only mesh
+	* already wrote the occluding depth), so they just paint where the occluder
+	* is the nearest geometry; the wireframe draws at renderOrder 1 so its lines
+	* overlay the shaded surface in the combined style.
+	*
+	* Vertex normals (the mesher emits none) are computed only for the
+	* matcap-based styles — `'wireframe'` is unlit, so like `'off'` it keeps the
+	* remesh path normal-free.
+	*
+	* Only meaningful when this occluder is actually meshing the grid (it is the
+	* persistent occluder's mesh); setting a style on an empty/disabled occluder
+	* is a harmless no-op until {@link update} feeds geometry.
+	*/
+	setDebugStyle(style) {
+		if (this.disposed || style === this.debugStyle) return;
+		this.debugStyle = style;
+		this.applyShadedSkin(this.shadedMaterialFor(style));
+		this.applyWireframeSkin(style === "wireframe" || style === "depth-shaded-wireframe");
+	}
+	/** Which matcap-based material the style shades with (null = no shaded skin). */
+	shadedMaterialFor(style) {
+		if (style === "matcap") return this.getMatcapMaterial();
+		if (style === "depth-shaded" || style === "depth-shaded-wireframe") return this.getDepthShadedMaterial();
+		return null;
+	}
+	/** Add/retarget/remove the single shaded skin node for the desired material. */
+	applyShadedSkin(material) {
+		if (material) {
+			this.geometry.computeVertexNormals();
+			if (this.shadedSkin) this.shadedSkin.material = material;
+			else {
+				this.shadedSkin = this.createSkinMesh(DEBUG_MESH_NAME, 0, material);
+				this.arSpaceNode.add(this.shadedSkin);
+			}
+		} else if (this.shadedSkin) {
+			this.arSpaceNode.remove(this.shadedSkin);
+			this.shadedSkin = null;
+		}
+	}
+	/** Add/remove the wireframe skin — drawn after the shaded skin (renderOrder
+	*  1) so its lines sit on top of the surface in the combined style. */
+	applyWireframeSkin(want) {
+		if (want) {
+			if (!this.wireframeSkin) {
+				this.wireframeSkin = this.createSkinMesh(DEBUG_WIREFRAME_MESH_NAME, 1, this.getWireframeMaterial());
+				this.arSpaceNode.add(this.wireframeSkin);
+			}
+		} else if (this.wireframeSkin) {
+			this.arSpaceNode.remove(this.wireframeSkin);
+			this.wireframeSkin = null;
+		}
+	}
+	/**
+	* Toggle the matcap debug rendering of the occluder mesh.
+	*
+	* @deprecated Superseded by {@link setDebugStyle} (2026-07-02) — this is a
+	* thin wrapper mapping `enabled ? 'matcap' : 'off'`, kept so existing
+	* consumers of the boolean API keep working unchanged.
+	*/
+	setDebugVisualization(enabled) {
+		this.setDebugStyle(enabled ? "matcap" : "off");
+	}
+	/** A debug skin mesh sharing the occluder's geometry, transform and culling
+	*  behaviour — only name, renderOrder and material differ per skin. */
+	createSkinMesh(name, renderOrder, material) {
+		const skin = new THREE.Mesh(this.geometry, material);
+		skin.name = name;
+		skin.renderOrder = renderOrder;
+		skin.frustumCulled = false;
+		skin.matrixAutoUpdate = false;
+		skin.matrix.copy(WEBXR_TO_NUE);
+		return skin;
+	}
+	/** The procedural matcap texture, shared by both matcap-based materials. */
+	getMatcapTexture() {
+		if (!this.matcapTexture) this.matcapTexture = createOccluderDebugMatcap();
+		return this.matcapTexture;
+	}
+	getMatcapMaterial() {
+		if (!this.matcapMaterial) this.matcapMaterial = new THREE.MeshMatcapMaterial({
+			matcap: this.getMatcapTexture(),
+			transparent: true,
+			opacity: DEBUG_SKIN_OPACITY,
+			depthWrite: false
+		});
+		return this.matcapMaterial;
+	}
+	getDepthShadedMaterial() {
+		if (!this.depthShadedMaterial) {
+			const material = new THREE.MeshMatcapMaterial({
+				matcap: this.getMatcapTexture(),
+				transparent: true,
+				opacity: DEBUG_SKIN_OPACITY,
+				depthWrite: false
+			});
+			material.onBeforeCompile = (shader) => {
+				shader.fragmentShader = shader.fragmentShader.replace("#include <opaque_fragment>", `${buildOccluderDepthShadeSnippet()}\n\t#include <opaque_fragment>`);
+			};
+			material.customProgramCacheKey = () => "occluder-depth-shaded";
+			this.depthShadedMaterial = material;
+		}
+		return this.depthShadedMaterial;
+	}
+	getWireframeMaterial() {
+		if (!this.wireframeMaterial) this.wireframeMaterial = new THREE.MeshBasicMaterial({
+			wireframe: true,
+			color: WIREFRAME_COLOR,
+			transparent: true,
+			opacity: WIREFRAME_OPACITY,
+			depthWrite: false
+		});
+		return this.wireframeMaterial;
+	}
+	/** Empty the mesh (e.g. on store swap); the node stays in the scene. */
+	clear() {
+		if (this.disposed) return;
+		const next = new THREE.BufferGeometry();
+		this.geometry.dispose();
+		this.geometry = next;
+		this.mesh.geometry = next;
+		this.rebindSkinGeometry(next);
+		this.lastAabbs = [];
+	}
+	/** Remove the mesh from its parent and release GPU resources. */
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.arSpaceNode.remove(this.mesh);
+		if (this.shadedSkin) {
+			this.arSpaceNode.remove(this.shadedSkin);
+			this.shadedSkin = null;
+		}
+		if (this.wireframeSkin) {
+			this.arSpaceNode.remove(this.wireframeSkin);
+			this.wireframeSkin = null;
+		}
+		this.matcapTexture?.dispose();
+		this.matcapTexture = null;
+		this.matcapMaterial?.dispose();
+		this.matcapMaterial = null;
+		this.depthShadedMaterial?.dispose();
+		this.depthShadedMaterial = null;
+		this.wireframeMaterial?.dispose();
+		this.wireframeMaterial = null;
+		this.geometry.dispose();
+		this.material.dispose();
+		this.lastAabbs = [];
+	}
+};
+//#endregion
+export { OCCLUDER_DEPTH_SHADE, OcclusionMesh, buildOccluderDepthShadeSnippet, occluderDepthFade, occluderFresnelRim };

package/dist/visualization/three-dispose.d.ts

@@ -1,2 +1,2 @@
-import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-BCZkSJp2.js";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-BMOAmPhb.js";
 export { DisposeOptions, disposeMeshArray, disposeObject3D };

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

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

package/dist/{webxr-session-CJF9Nijp.js → webxr-session-BCP2XK7k.js}

@@ -5,10 +5,10 @@ import { DepthSampler, wrapXRDepthInfo } from "./ar/depth-sampler.js";
 import { WEBXR_TO_NUE } from "./ar/webxr-nue-basis.js";
 import { clearFrameUpdates, runFrameUpdates } from "./ar/frame-loop.js";
 import { clearXrFrameUpdates, runXrFrameUpdates } from "./ar/xr-frame-loop.js";
-import { DEFAULT_CAPTURE_CONFIG, ImageCaptureManager } from "./ar/image-capture.js";
+import { n as ImageCaptureManager, t as DEFAULT_CAPTURE_CONFIG } from "./image-capture-DVcuqMtX.js";
 import { clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectTrackingPhase } from "./state/tracking-slice.js";
 import { acquireCameraTexture } from "./ar/xr-camera-texture.js";
-import { n as runSessionDisposers } from "./session-disposers-D8wnO-uW.js";
+import { n as runSessionDisposers } from "./session-disposers-BPrMplIC.js";
 import { DEFAULT_RECORDING_OPTIONS, validateArCrashIsolationOptions } from "./state/recording-options.js";
 import { SCENE_NODE } from "./ar/scene-node-names.js";
 import { createCss3dRendererManager } from "./visualization/css3d-renderer-manager.js";
@@ -225,6 +225,8 @@ function resetWebXRState() {
 	onTrackingRestarted = null;
 	onTrackingLost = null;
 	onTrackingRecovered = null;
+	onSessionEnd = null;
+	endRequestedByApp = false;
 	depthSampler = null;
 	onDepthCaptured = null;
 	onDepthUnavailable = null;
@@ -290,6 +292,14 @@ let onSuspiciousImage = null;
 */
 let getScreenRotation = null;
 /**
+* Off-thread image-quality analyzer (set via {@link setImageQualityAnalyzer}).
+* Device-specific (a Web Worker in the recorder), so it is INJECTED rather than
+* built here. Forwarded to `ImageCaptureManager` as its `analyzeFrame` callback;
+* the manager only invokes it when `config.qualityFilter.enabled`. `null` ⇒ the
+* legacy save-immediately path.
+*/
+let imageQualityAnalyzer = null;
+/**
 * Redux store injected by the host (`setTrackingStore`). When present
 * together with `onTrackingRestarted`, `onXRFrame` dispatches
 * `poseReceived`/`poseLost`, the XR reference-space reset listener
@@ -321,6 +331,20 @@ let onTrackingLost = null;
 */
 let onTrackingRecovered = null;
 /**
+* Host callback fired exactly once whenever the XRSession ends — on BOTH the
+* app-initiated and the system-initiated path (set via setSessionEndCallback).
+* Cleared by resetWebXRState() like every other module-level callback.
+*/
+let onSessionEnd = null;
+/**
+* Set by endARSession() immediately before its `xrSession.end()` so the
+* shared 'end' listener can tell the two trigger paths apart (the app's own
+* end() fires the same 'end' event the system path does). Consumed (reset to
+* false) by handleSessionEnded(); also cleared defensively in
+* resetWebXRState() in case end() rejects without the event ever firing.
+*/
+let endRequestedByApp = false;
+/**
 * Depth sampler instance (created when AR session starts with depth callbacks)
 */
 let depthSampler = null;
@@ -555,7 +579,7 @@ function getCurrentArPose() {
 * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
 *   depth-sensing, camera-access)
 * @param sessionFeatures - Opt-in standard WebXR features that are independent
-*   of crash isolation (currently `requestHitTest`)
+*   of crash isolation (`requestHitTest`, `requestDepthOcclusion`)
 * @returns XRSessionInit options
 * @throws Error if rootElement is null
 */
@@ -568,7 +592,7 @@ function buildSessionOptions(rootElement, isolationOptions = {}, sessionFeatures
 		optionalFeatures.push("dom-overlay");
 		sessionOptions.domOverlay = { root: rootElement };
 	}
-	if (normalizedOptions.enableDepthSensingFeature) {
+	if (normalizedOptions.enableDepthSensingFeature || sessionFeatures.requestDepthOcclusion) {
 		optionalFeatures.push("depth-sensing");
 		Object.assign(sessionOptions, { depthSensing: {
 			usagePreference: ["cpu-optimized"],
@@ -592,6 +616,23 @@ async function isWebXRSupported() {
 	}
 }
 /**
+* AR camera frustum constants — the single source of truth for live AR and
+* replay (both build their camera via {@link createSceneHierarchy}).
+*
+* F2 (2026-07-04 user feedback): far raised 100 → 200 m so objects in the
+* reported 100–200 m range are no longer frustum-culled. The far-plane
+* distance itself is essentially free at this app's object counts; the real
+* constraint is depth precision — far/near = 2×10⁴ is comfortable for a
+* 24-bit depth buffer. Revisit the ratio if AR_CAMERA_NEAR ever shrinks.
+*
+* Note: these apply to WebGL content only. The CSS3D minimap is composited by
+* the browser from the camera fov alone — near/far do not clip it (F1 in the
+* same feedback doc).
+*/
+const AR_CAMERA_FOV = 70;
+const AR_CAMERA_NEAR = .01;
+const AR_CAMERA_FAR = 200;
+/**
 * Create the scene hierarchy with proper AR/GPS frame separation.
 * This is a pure function for testability.
 *
@@ -639,7 +680,7 @@ function createSceneHierarchy() {
 	const newArPose = new THREE.Object3D();
 	newArPose.name = "ar-pose";
 	newBasisChangeNode.add(newArPose);
-	const newCamera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, .01, 100);
+	const newCamera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, AR_CAMERA_NEAR, 200);
 	newArPose.add(newCamera);
 	const ambientLight = new THREE.AmbientLight(16777215, .5);
 	newScene.add(ambientLight);
@@ -681,10 +722,7 @@ async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
 	const sessionOptions = buildSessionOptions(container, currentArCrashIsolationOptions, sessionFeatures);
 	xrSession = await navigator.xr.requestSession("immersive-ar", sessionOptions);
 	xrSession.addEventListener("end", () => {
-		log.info("Session ended");
-		if (trackingStore) trackingStore.dispatch(resetTracking());
-		xrSession = null;
-		latestArPose = null;
+		handleSessionEnded();
 	});
 	await renderer.xr.setSession(xrSession);
 	if (onTrackingRestarted && trackingStore) {
@@ -839,8 +877,15 @@ function onXRFrame(time, frame) {
 	if (currentArCrashIsolationOptions.enableCss3dRenderer && css3dManager) css3dManager.render(scene, camera);
 }
 /**
-* Extract depth information from an XR frame.
-* Returns null if depth sensing is not available.
+* Extract depth information from an XR frame. Returns `null` if depth sensing is
+* not available (no pose/view, no `getDepthInformation`, or the call throws).
+*
+* Exported so a consumer can feed the **live depth occluder** from a
+* `registerXrFrameUpdate` callback — the callback has the live `frame` +
+* `referenceSpace`, computes `pose = frame.getViewerPose(referenceSpace)`, and
+* passes both here to obtain the per-frame {@link DepthInfo} (with the widened
+* `data` / `rawValueToMeters` / `normDepthBufferFromNormView` / `projectionMatrix`
+* the occluder needs). The same wrapped depth the sparse grid sampler consumes.
 */
 function getDepthInfoFromFrame(frame, pose) {
 	const view = pose?.views[0];
@@ -976,6 +1021,41 @@ function nueQuaternionToWebXR$1(nue) {
 	return nueQuaternionToWebXR(nue);
 }
 /**
+* Register a host callback fired exactly once whenever the XRSession ends —
+* app-initiated ({@link endARSession}) AND system-initiated (e.g. the Android
+* back gesture, which ends an immersive session directly and uncancelably).
+* `info.requestedByApp` discriminates the two. Fired AFTER the full teardown,
+* so the host can immediately start a fresh session from inside the callback.
+*
+* Cleared by resetWebXRState() (i.e. after every session end) like the other
+* module-level callbacks — re-register before/with each new session.
+* Pass `null` to unregister. F3, 2026-07-04 user feedback.
+*/
+function setSessionEndCallback(cb) {
+	onSessionEnd = cb;
+}
+/**
+* The ONE teardown for a session that has ended, shared by both trigger
+* paths via the XRSession 'end' listener. Before F3 the system-initiated
+* path (back gesture) only nulled `xrSession`/`latestArPose`, leaving the
+* renderer compositing the 3D scene over a black camera background and the
+* host app never notified — the "haunted scene" from
+* docs/2026-02-15-lifecycle-orphans.md §1.
+*/
+function handleSessionEnded() {
+	log.info("Session ended");
+	const callback = onSessionEnd;
+	const requestedByApp = endRequestedByApp;
+	endRequestedByApp = false;
+	if (trackingStore) trackingStore.dispatch(resetTracking());
+	resetWebXRState();
+	if (callback) try {
+		callback({ requestedByApp });
+	} catch (err) {
+		log.error("Session-end callback threw:", err);
+	}
+}
+/**
 * End the current XR session and clean up all resources.
 *
 * Stops the animation loop, ends the XR session, then delegates the full
@@ -988,7 +1068,10 @@ function nueQuaternionToWebXR$1(nue) {
 async function endARSession() {
 	if (renderer) renderer.setAnimationLoop(null);
 	try {
-		if (xrSession) await xrSession.end();
+		if (xrSession) {
+			endRequestedByApp = true;
+			await xrSession.end();
+		}
 	} finally {
 		resetWebXRState();
 	}
@@ -1009,6 +1092,18 @@ function setImageCaptureCallback(onCaptured, screenRotationGetter, onFailed, onS
 	onSuspiciousImage = onSuspicious ?? null;
 }
 /**
+* Inject (or clear) the off-thread image-quality analyzer used by the blur/
+* blackness drop+retry gate. Pass the recorder's Web Worker-backed analyzer to
+* enable the gate, or `null` to clear it (legacy save-immediately path). Must be
+* set BEFORE {@link startImageCapture} for the active recording — the manager
+* reads it once when constructed. The analyzer only runs when the capture
+* config's `qualityFilter.enabled` is true, so injecting it is harmless when the
+* gate is off. Ownership/disposal of the worker is the caller's responsibility.
+*/
+function setImageQualityAnalyzer(analyzer) {
+	imageQualityAnalyzer = analyzer;
+}
+/**
 * Start capturing images during recording.
 * Must call setImageCaptureCallback first.
 *
@@ -1036,7 +1131,8 @@ function startImageCapture(config) {
 		getScreenRotation,
 		onCaptured: onImageCaptured,
 		onCaptureFailed: onCaptureFailed ?? void 0,
-		onSuspiciousImage: onSuspiciousImage ?? void 0
+		onSuspiciousImage: onSuspiciousImage ?? void 0,
+		analyzeFrame: imageQualityAnalyzer ?? void 0
 	};
 	const mergedConfig = {
 		...DEFAULT_CAPTURE_CONFIG,
@@ -1263,4 +1359,4 @@ function getLiveCss3dManager() {
 	return css3dManager;
 }
 //#endregion
-export { setFrameCallback as A, startImageCapture as B, nueQuaternionToWebXR$1 as C, setCamera as D, setArWorldGroup as E, setTrackingRecoveredCallback as F, stopDepthCapture as H, setTrackingStore as I, shouldLogCameraAccessDiagnostic as L, setScene as M, setTrackingCallbacks as N, setCameraFrameCallback as O, setTrackingLostCallback as P, startCameraFrameCapture as R, nuePositionToWebXR as S, setArPose as T, stopImageCapture as U, stopCameraFrameCapture as V, CameraFrameSource as W, getScene as _, endARSession as a, isWebXRSupported as b, getArPose as c, getCameraFrameCaptureSize as d, getCameraFrameCount as f, getLiveCss3dManager as g, getImageCaptureFrameCount as h, createSceneHierarchy as i, setImageCaptureCallback as j, setDepthCaptureCallback as k, getArWorldGroup as l, getDepthSampleCount as m, applyAlignmentMatrix as n, extractPoseFromViewer as o, getCurrentArPose as p, buildSessionOptions as r, extractResetTransformData as s, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as t, getCamera as u, getXrCameraFromPose as v, resetWebXRState as w, isXRCameraLike as x, initAR as y, startDepthCapture as z };
+export { setArWorldGroup as A, setTrackingLostCallback as B, initAR as C, nueQuaternionToWebXR$1 as D, nuePositionToWebXR as E, setImageCaptureCallback as F, startDepthCapture as G, setTrackingStore as H, setImageQualityAnalyzer as I, stopDepthCapture as J, startImageCapture as K, setScene as L, setCameraFrameCallback as M, setDepthCaptureCallback as N, resetWebXRState as O, setFrameCallback as P, setSessionEndCallback as R, getXrCameraFromPose as S, isXRCameraLike as T, shouldLogCameraAccessDiagnostic as U, setTrackingRecoveredCallback as V, startCameraFrameCapture as W, CameraFrameSource as X, stopImageCapture as Y, getDepthInfoFromFrame as _, applyAlignmentMatrix as a, getLiveCss3dManager as b, endARSession as c, getArPose as d, getArWorldGroup as f, getCurrentArPose as g, getCameraFrameCount as h, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as i, setCamera as j, setArPose as k, extractPoseFromViewer as l, getCameraFrameCaptureSize as m, AR_CAMERA_FOV as n, buildSessionOptions as o, getCamera as p, stopCameraFrameCapture as q, AR_CAMERA_NEAR as r, createSceneHierarchy as s, AR_CAMERA_FAR as t, extractResetTransformData as u, getDepthSampleCount as v, isWebXRSupported as w, getScene as x, getImageCaptureFrameCount as y, setTrackingCallbacks as z };