gps-plus-slam-app-framework 1.7.0 → 1.9.0

package/dist/visualization/occluder-mesh-driver.js

@@ -0,0 +1,219 @@
+import { packMeshRequest, runMeshRequest } from "../ar/occlusion-mesh-worker.js";
+//#region ../src/visualization/occluder-mesh-driver.ts
+/**
+* Occluder mesh driver — main-thread orchestration for the Web Worker offload.
+*
+* Drives {@link packMeshRequest} / {@link runMeshRequest} (see
+* `2026-07-01-occluder-worker-and-chunked-remesh-plan.md`): the occluder wiring
+* calls {@link OccluderMeshDriver.request} on each refresh with the occupied-cell
+* snapshot; the driver packs it, posts it to a worker, and invokes a callback
+* with the meshed geometry when it returns — so the expensive mesh runs
+* off-thread and never stalls the render.
+*
+* Policy (locked 2026-07-01):
+* - **Coalesce to latest** — at most one job in flight; a request made while busy
+*   is remembered (newest wins) and posted when the current one returns, so work
+*   never queues up behind a growing grid.
+* - **Synchronous fallback** — constructed with `poster = null` (no worker
+*   support), it meshes inline and calls back immediately (today's behaviour).
+* - **Error recovery (2026-07-01 Phase 1 gap fix)** — a worker that never replies
+*   (an uncaught throw in `runMeshRequest`, or a module that fails to load) must
+*   not wedge the in-flight slot forever. On a worker error the driver clears the
+*   slot and re-posts the pending snapshot (or lets the next refresh post) so the
+*   occluder never silently freezes. If the worker errors **before ever producing
+*   a mesh** — almost always a load failure — the driver declares it unusable
+*   ({@link OccluderMeshDriverOptions.onWorkerUnusable}) and switches to
+*   synchronous main-thread meshing, since further posts would vanish into a dead
+*   worker.
+*
+* Framework-owned + THREE-free: a consumer supplies a {@link MeshWorkerPoster}
+* adapting a real `Worker`, and applies the result (e.g. `OcclusionMesh.applyMeshData`).
+*/
+/** Cell count of a snapshot in either representation. */
+function cellCountOf(cells) {
+	return cells instanceof Int32Array ? cells.length / 3 : cells.length;
+}
+var OccluderMeshDriver = class {
+	poster;
+	onWorkerUnusable;
+	onError;
+	onMeshStats;
+	now;
+	nextId = 1;
+	inFlightId = null;
+	inFlightCallback = null;
+	/** Timing/size context of the in-flight job; cleared on completion/failure. */
+	inFlightStats = null;
+	pending = null;
+	disposed = false;
+	/** True ⇒ mesh inline (no worker, or the worker was declared unusable). */
+	syncMode;
+	/** Set once the worker returns a mesh — distinguishes a transient error from a load failure. */
+	hasSucceeded = false;
+	/**
+	* @param poster a worker adapter, or `null` for synchronous main-thread meshing.
+	* @param options optional {@link OccluderMeshDriverOptions.onWorkerUnusable} /
+	*   {@link OccluderMeshDriverOptions.onError} callbacks.
+	*/
+	constructor(poster, options = {}) {
+		this.poster = poster;
+		this.syncMode = poster === null;
+		this.onWorkerUnusable = options.onWorkerUnusable;
+		this.onError = options.onError;
+		this.onMeshStats = options.onMeshStats;
+		this.now = options.now ?? (() => performance.now());
+		if (poster) {
+			poster.onmessage = (event) => this.handleResponse(event.data);
+			poster.onerror = (error) => this.handleWorkerError(error);
+		}
+	}
+	/** True while a mesh job is being computed (worker path only). */
+	get busy() {
+		return this.inFlightId !== null;
+	}
+	/**
+	* Request a mesh of `cells` (tuple array, or a flat Int32Array snapshot —
+	* see `packMeshRequest`; a flat snapshot's buffer is transferred/detached,
+	* so pass a fresh array). If a job is already in flight, this becomes the
+	* (single) pending job — the newest request wins; intermediates are dropped.
+	* `getCellPoint` is invoked with a transient cell tuple that may be a reused
+	* scratch — it must not retain the tuple beyond the call (see
+	* `MeshOccupiedCellsOptions.getCellPoint`).
+	*/
+	request(cells, cellSizeM, mode, getCellPoint, onMesh) {
+		if (this.disposed) return;
+		const job = {
+			cells,
+			cellSizeM,
+			mode,
+			getCellPoint,
+			onMesh
+		};
+		if (this.inFlightId !== null) {
+			this.pending = job;
+			return;
+		}
+		this.post(job);
+	}
+	post(job) {
+		const id = this.nextId++;
+		this.inFlightId = id;
+		this.inFlightCallback = job.onMesh;
+		this.inFlightStats = {
+			startedMs: this.now(),
+			cellCount: cellCountOf(job.cells),
+			mode: job.mode,
+			synchronous: this.syncMode || this.poster === null
+		};
+		let packed;
+		try {
+			packed = packMeshRequest(id, job.cells, job.cellSizeM, job.mode, job.getCellPoint);
+		} catch (error) {
+			this.failInFlight(id, error, { workerAtFault: false });
+			return;
+		}
+		const { request, transfer } = packed;
+		if (this.poster && !this.syncMode) try {
+			this.poster.postMessage(request, transfer);
+		} catch (error) {
+			this.failInFlight(id, error);
+		}
+		else try {
+			const { response } = runMeshRequest(request);
+			this.handleResponse(response);
+		} catch (error) {
+			if (this.inFlightId === id) this.failInFlight(id, error);
+			else this.onError?.(error);
+		}
+	}
+	handleResponse(response) {
+		if (this.disposed || response.id !== this.inFlightId) return;
+		this.hasSucceeded = true;
+		const callback = this.inFlightCallback;
+		const stats = this.inFlightStats;
+		try {
+			if (stats && this.onMeshStats) {
+				const { startedMs, ...rest } = stats;
+				this.onMeshStats({
+					...rest,
+					durationMs: this.now() - startedMs
+				});
+			}
+			callback?.(response.positions, response.indices);
+		} finally {
+			this.inFlightId = null;
+			this.inFlightCallback = null;
+			this.inFlightStats = null;
+			if (!this.disposed && this.pending) {
+				const next = this.pending;
+				this.pending = null;
+				this.post(next);
+			}
+		}
+	}
+	/**
+	* A worker error event. If a job is in flight, recover it (only one ever is).
+	* If none is — the realistic ordering for a **module-load failure**, which
+	* errors within a few ms of construction, before the first (throttled)
+	* `request` posts anything — the worker is dead: posting to it would be
+	* silently dropped (no second error) and wedge the in-flight slot forever. So
+	* a pre-first-post error on a worker that has **never** succeeded is treated as
+	* a load failure right here — declare it unusable and switch to synchronous
+	* meshing so the first `request` never touches the dead worker. A stray/late
+	* error on a worker that has already meshed once is transient — kept, ignored.
+	*/
+	handleWorkerError(error) {
+		if (this.disposed) return;
+		if (this.inFlightId !== null) {
+			this.failInFlight(this.inFlightId, error);
+			return;
+		}
+		if (!this.syncMode && !this.hasSucceeded) {
+			if (error !== void 0) this.onError?.(error);
+			this.syncMode = true;
+			this.onWorkerUnusable?.();
+		}
+	}
+	/**
+	* Clear a failed in-flight job so the driver never wedges. If the worker had
+	* never produced a mesh (almost always a module load failure) fall back to
+	* synchronous meshing — unless `workerAtFault` is false (a pack-time error in
+	* the caller's `getCellPoint`, which never reached the worker). Then re-post
+	* the pending snapshot if one is queued. We deliberately do NOT re-post the
+	* *failed* job: if it failed on deterministic bad data, re-posting would
+	* loop — the next refresh brings a fresh snapshot.
+	*/
+	failInFlight(id, error, options = {}) {
+		if (this.disposed || id !== this.inFlightId) return;
+		try {
+			if (error !== void 0) this.onError?.(error);
+		} finally {
+			this.inFlightId = null;
+			this.inFlightCallback = null;
+			this.inFlightStats = null;
+			if ((options.workerAtFault ?? true) && !this.syncMode && !this.hasSucceeded) {
+				this.syncMode = true;
+				this.onWorkerUnusable?.();
+			}
+			if (this.pending) {
+				const next = this.pending;
+				this.pending = null;
+				this.post(next);
+			}
+		}
+	}
+	/** Stop delivering results (detaches the worker handlers; drops any pending). */
+	dispose() {
+		this.disposed = true;
+		this.pending = null;
+		this.inFlightCallback = null;
+		this.inFlightId = null;
+		this.inFlightStats = null;
+		if (this.poster) {
+			this.poster.onmessage = null;
+			this.poster.onerror = null;
+		}
+	}
+};
+//#endregion
+export { OccluderMeshDriver };

package/dist/visualization/occlusion-mesh.d.ts

@@ -0,0 +1,2 @@
+import { a as occluderDepthFade, i as buildOccluderDepthShadeSnippet, n as OcclusionMesh, o as occluderFresnelRim, r as OcclusionMeshOptions, t as OCCLUDER_DEPTH_SHADE } from "../occlusion-mesh-kXCQ2FM1.js";
+export { OCCLUDER_DEPTH_SHADE, OcclusionMesh, OcclusionMeshOptions, buildOccluderDepthShadeSnippet, occluderDepthFade, occluderFresnelRim };

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-Bt1k7WKh.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-Obw2pLqT.js";
+import { t as VIS_COLORS } from "../vis-colors-C7HI0u9_.js";
 export { VIS_COLORS };