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

package/dist/ar/occupancy-grid.js

@@ -1,10 +1,56 @@
 import { createDepthUnprojector } from "./depth-unprojection.js";
 import { bresenham3d } from "./bresenham3d.js";
+import { i as cellKey, o as unpackCellCoord, r as cellCoordsInKeyRange, s as unpackCellKey, t as CELL_KEY_LIMIT } from "../cell-key-DIB4rOTV.js";
 //#region ../src/ar/occupancy-grid.ts
+/**
+* Highest `minConfidence` a consumer can ask for (mirrors
+* `OCCUPANCY_CONSTRAINTS.minConfidence.max`). Once a cell's count exceeds this,
+* further observations can no longer change ANY consumer's occupied set, so they
+* do not bump {@link OccupancyGrid.getRevision} — letting a settled scene skip
+* redundant re-meshing.
+*/
+const MAX_RELEVANT_COUNT = 10;
 var OccupancyGrid = class {
 	cellSizeM;
 	carveStopCells;
 	cells = /* @__PURE__ */ new Map();
+	/**
+	* Chunk index (Step 2 of the 2026-07-03 long-session fps plan): cell keys
+	* grouped by {@link CHUNK_EDGE_CELLS}³ chunk, maintained incrementally on
+	* add/carve/clear (O(1) per mutation). Lets {@link getOccupiedCellsWithin}
+	* visit only the chunks a query sphere touches — cost independent of total
+	* explored area. Empty chunk sets are dropped.
+	*/
+	chunks = /* @__PURE__ */ new Map();
+	/**
+	* Per-chunk dirty revision, bumped whenever a mutation inside the chunk
+	* could change some consumer's occupied set (same semantics as the global
+	* {@link revision}). This is the bookkeeping a future dirty-chunk remesh
+	* needs (2026-07-01 worker plan, Phase-2 sketch) — landed with the index so
+	* that plan becomes a consumer-side change only. Entries survive a chunk
+	* emptying (a consumer must still see "changed"); reset by {@link clear}.
+	*/
+	chunkRevisions = /* @__PURE__ */ new Map();
+	/**
+	* Monotonic counter bumped whenever the **occupied set** (at any
+	* `minConfidence ≤ MAX_RELEVANT_COUNT`) could have changed: a cell added, a
+	* cell removed by carving, a cell's count rising while still `≤
+	* MAX_RELEVANT_COUNT` (a possible threshold crossing), or `clear`. Re-observing
+	* an already-settled cell (count `> MAX_RELEVANT_COUNT`) does NOT bump it, so a
+	* consumer can cheaply skip a full re-derive (cube refresh / occluder re-mesh)
+	* when the revision is unchanged — the dominant idle-time saving over a long
+	* session (see `2026-06-30-occluder-tuning-followups.md`).
+	*/
+	revision = 0;
+	/**
+	* Memo of the last {@link getOccupiedCells} walk (Step 1.2 of the
+	* 2026-07-03 long-session fps plan): with cubes + occluder both on, every
+	* throttled refresh triggers two identical full-grid walks with the same
+	* minConfidence floor — the second is answered from here. Valid only while
+	* `revision` is unchanged, so it is only used for floors the revision
+	* counter actually tracks (≤ {@link MAX_RELEVANT_COUNT}).
+	*/
+	snapshotCache = null;
 	constructor(options) {
 		const cellSizeM = options?.cellSizeM ?? .15;
 		const carveStopCells = options?.carveStopCells ?? 2;
@@ -18,6 +64,16 @@ var OccupancyGrid = class {
 		return this.cells.size;
 	}
 	/**
+	* A monotonic version that changes only when the occupied set (at any
+	* `minConfidence ≤ 10`) could have changed. A consumer caches the value it
+	* last meshed/rendered and skips its full re-derive when it is unchanged — so
+	* a settled scene (already-observed cells being re-observed) costs nothing.
+	* See {@link revision}.
+	*/
+	getRevision() {
+		return this.revision;
+	}
+	/**
 	* Fold one depth sample into the grid: unproject each point, carve free
 	* space from the camera cell to the point cell, then count the point's
 	* cell as occupied. Points that cannot be unprojected (no
@@ -39,12 +95,21 @@ var OccupancyGrid = class {
 		const unprojector = createDepthUnprojector(sample.cameraPos, sample.cameraRot, sample.projectionMatrix);
 		if (!unprojector) return 0;
 		const cameraCell = this.cellForPosition(sample.cameraPos);
+		const cameraInRange = cellInKeyRange(cameraCell);
+		const carvedEndpointKeys = /* @__PURE__ */ new Set();
 		const endpoints = [];
 		for (const point of sample.points) {
 			const world = unprojector.unproject(point);
 			if (!world) continue;
 			const cell = this.cellForPosition(world);
-			if (!cellsEqual(cameraCell, cell)) this.carve(cameraCell, cell);
+			if (!cellInKeyRange(cell)) continue;
+			if (cameraInRange && !cellsEqual(cameraCell, cell)) {
+				const key = cellKey(cell);
+				if (!carvedEndpointKeys.has(key)) {
+					carvedEndpointKeys.add(key);
+					this.carve(cameraCell, cell);
+				}
+			}
 			endpoints.push({
 				cell,
 				world,
@@ -54,12 +119,152 @@ var OccupancyGrid = class {
 		for (const endpoint of endpoints) this.increment(endpoint.cell, endpoint.world, endpoint.rgb);
 		return endpoints.length;
 	}
-	/** Occupied cells observed at least `minObservations` times (default 1). */
+	/**
+	* Occupied cells observed at least `minObservations` times (default 1).
+	*
+	* The result is a **shared immutable snapshot**: a repeated call with the
+	* same floor on an unchanged grid returns the SAME array instance (the
+	* memo above), so callers must never mutate it. Floors above
+	* {@link MAX_RELEVANT_COUNT} bypass the memo — the revision counter does
+	* not track their threshold crossings, so a cached result could go stale.
+	*/
 	getOccupiedCells(minObservations = 1) {
+		const cache = this.snapshotCache;
+		if (cache && cache.revision === this.revision && cache.minObservations === minObservations) return cache.cells;
+		const result = [];
+		for (const [key, record] of this.cells) if (record.count >= minObservations) result.push(unpackCellKey(key));
+		if (minObservations <= MAX_RELEVANT_COUNT) this.snapshotCache = {
+			revision: this.revision,
+			minObservations,
+			cells: result
+		};
+		return result;
+	}
+	/**
+	* Flat `[x0,y0,z0, x1,y1,z1, …]` variant of {@link getOccupiedCells} for the
+	* mesh-worker pack path (Step 1.3 of the 2026-07-03 long-session fps plan):
+	* `packMeshRequest` ships the snapshot to the worker as a transferable
+	* Int32Array, so handing it over flat deletes the tuple-array intermediate
+	* it used to re-flatten. Same cells, same order as the tuple API.
+	*
+	* Unlike {@link getOccupiedCells} this returns a **fresh array every call**
+	* — the pack path TRANSFERS the buffer to the worker (detaching it), so a
+	* shared/cached array would be destroyed under the grid. When the tuple
+	* memo is warm (the cubes refresh just snapshotted the same floor) the
+	* fresh array is flattened from it in O(matching cells) without a re-walk.
+	*/
+	getOccupiedCellsFlat(minObservations = 1) {
+		const cache = this.snapshotCache;
+		if (cache && cache.revision === this.revision && cache.minObservations === minObservations) {
+			const cells = cache.cells;
+			const flat = new Int32Array(cells.length * 3);
+			for (let i = 0; i < cells.length; i++) {
+				const c = cells[i];
+				flat[i * 3] = c[0];
+				flat[i * 3 + 1] = c[1];
+				flat[i * 3 + 2] = c[2];
+			}
+			return flat;
+		}
+		const flat = new Int32Array(this.cells.size * 3);
+		let used = 0;
+		for (const [key, record] of this.cells) if (record.count >= minObservations) {
+			flat[used] = unpackCellCoord(key, 0);
+			flat[used + 1] = unpackCellCoord(key, 1);
+			flat[used + 2] = unpackCellCoord(key, 2);
+			used += 3;
+		}
+		return used === flat.length ? flat : flat.slice(0, used);
+	}
+	/**
+	* Occupied cells (≥ `minObservations`) whose **centers** lie within
+	* `radiusM` of `centerPos` — the viewer-local window that keeps consumer
+	* refresh cost independent of total explored area (Step 2 of the
+	* 2026-07-03 long-session fps plan). Walks only the chunks whose
+	* cell-center AABB intersects the query sphere; chunks entirely inside it
+	* skip the per-cell distance test. Result set ≡ the brute-force radius
+	* filter of {@link getOccupiedCells} (property-tested; iteration order may
+	* differ). Fresh array per call (no memo — the camera moves every frame).
+	*
+	* @throws RangeError for a non-finite or non-positive `radiusM` (a
+	*   windowed query without a window is an upstream bug). A non-finite
+	*   `centerPos` (tracking glitch) returns `[]` instead — mirrors
+	*   {@link raycast}'s non-finite policy.
+	*/
+	getOccupiedCellsWithin(centerPos, radiusM, minObservations = 1) {
 		const result = [];
-		for (const record of this.cells.values()) if (record.count >= minObservations) result.push(record.cell);
+		this.forEachOccupiedCellWithin(centerPos, radiusM, minObservations, (x, y, z) => {
+			result.push([
+				x,
+				y,
+				z
+			]);
+		});
 		return result;
 	}
+	/**
+	* Flat `[x0,y0,z0, …]` variant of {@link getOccupiedCellsWithin} for the
+	* mesh-worker pack path (same contract as {@link getOccupiedCellsFlat}:
+	* fresh array every call — packing transfers/detaches the buffer).
+	*/
+	getOccupiedCellsWithinFlat(centerPos, radiusM, minObservations = 1) {
+		const coords = [];
+		this.forEachOccupiedCellWithin(centerPos, radiusM, minObservations, (x, y, z) => {
+			coords.push(x, y, z);
+		});
+		return Int32Array.from(coords);
+	}
+	/**
+	* Per-chunk dirty revision (see the field docs): 0 for a never-touched
+	* chunk. `chunk` is in chunk coordinates (`floor(cell / 16)` per axis).
+	*/
+	getChunkRevision(chunk) {
+		return this.chunkRevisions.get(chunkKeyOf(chunk[0], chunk[1], chunk[2])) ?? 0;
+	}
+	/** Shared sphere-window walk behind the tuple and flat queries. */
+	forEachOccupiedCellWithin(centerPos, radiusM, minObservations, visit) {
+		if (!Number.isFinite(radiusM) || radiusM <= 0) throw new RangeError(`radiusM must be a positive finite number, got ${radiusM}`);
+		if (!isFiniteTriple(centerPos)) return;
+		const cs = this.cellSizeM;
+		const r2 = radiusM * radiusM;
+		const skipBeyond = (radiusM + cs * 1e-9) ** 2;
+		const wholeInsideR2 = (radiusM - cs * 1e-9) ** 2;
+		for (const [chunkKey, cellKeys] of this.chunks) {
+			const bx = unpackChunkCoord(chunkKey, 0) * CHUNK_EDGE_CELLS * cs;
+			const by = unpackChunkCoord(chunkKey, 1) * CHUNK_EDGE_CELLS * cs;
+			const bz = unpackChunkCoord(chunkKey, 2) * CHUNK_EDGE_CELLS * cs;
+			const extent = (CHUNK_EDGE_CELLS - 1) * cs;
+			let dMin2 = 0;
+			let dMax2 = 0;
+			for (let axis = 0; axis < 3; axis++) {
+				const lo = axis === 0 ? bx : axis === 1 ? by : bz;
+				const hi = lo + extent;
+				const v = centerPos[axis];
+				const below = lo - v;
+				const above = v - hi;
+				const dMin = Math.max(below, above, 0);
+				dMin2 += dMin * dMin;
+				const dMax = Math.max(Math.abs(v - lo), Math.abs(hi - v));
+				dMax2 += dMax * dMax;
+			}
+			if (dMin2 > skipBeyond) continue;
+			const wholeInside = dMax2 <= wholeInsideR2;
+			for (const key of cellKeys) {
+				const record = this.cells.get(key);
+				if (!record || record.count < minObservations) continue;
+				const x = unpackCellCoord(key, 0);
+				const y = unpackCellCoord(key, 1);
+				const z = unpackCellCoord(key, 2);
+				if (!wholeInside) {
+					const dx = x * cs - centerPos[0];
+					const dy = y * cs - centerPos[1];
+					const dz = z * cs - centerPos[2];
+					if (dx * dx + dy * dy + dz * dz > r2) continue;
+				}
+				visit(x, y, z);
+			}
+		}
+	}
 	/** Quantize a raw-WebXR position to its grid cell (round per axis). */
 	cellForPosition(pos) {
 		return [
@@ -86,12 +291,13 @@ var OccupancyGrid = class {
 	* `cellSizeM/2` of the cell center per axis.
 	*/
 	getCellPoint(cell) {
+		if (!cellInKeyRange(cell)) return null;
 		const record = this.cells.get(cellKey(cell));
 		if (!record || record.count === 0) return null;
 		return [
-			record.posSum[0] / record.count,
-			record.posSum[1] / record.count,
-			record.posSum[2] / record.count
+			record.posSumX / record.count,
+			record.posSumY / record.count,
+			record.posSumZ / record.count
 		];
 	}
 	/**
@@ -101,13 +307,14 @@ var OccupancyGrid = class {
 	* height-based coloring. Channels are rounded and clamped to 0–255.
 	*/
 	getCellColor(cell) {
+		if (!cellInKeyRange(cell)) return null;
 		const record = this.cells.get(cellKey(cell));
 		if (!record || record.colorCount === 0) return null;
 		const average = (sum) => Math.min(255, Math.max(0, Math.round(sum / record.colorCount)));
 		return [
-			average(record.colorSum[0]),
-			average(record.colorSum[1]),
-			average(record.colorSum[2])
+			average(record.colorSumR),
+			average(record.colorSumG),
+			average(record.colorSumB)
 		];
 	}
 	/**
@@ -117,8 +324,11 @@ var OccupancyGrid = class {
 	*/
 	raycast(startPos, endPos, minObservations = 1) {
 		if (!isFiniteTriple(startPos) || !isFiniteTriple(endPos)) return null;
+		const startCell = this.cellForPosition(startPos);
+		const endCell = this.cellForPosition(endPos);
+		if (!cellInKeyRange(startCell) || !cellInKeyRange(endCell)) return null;
 		let hit = null;
-		bresenham3d(this.cellForPosition(startPos), this.cellForPosition(endPos), (cell) => {
+		bresenham3d(startCell, endCell, (cell) => {
 			const record = this.cells.get(cellKey(cell));
 			if (record && record.count >= minObservations) {
 				hit = cell;
@@ -130,7 +340,10 @@ var OccupancyGrid = class {
 	}
 	/** Remove all occupied cells (e.g. on store swap / new session). */
 	clear() {
+		if (this.cells.size > 0) this.revision++;
 		this.cells.clear();
+		this.chunks.clear();
+		this.chunkRevisions.clear();
 	}
 	/**
 	* Delete occupied cells along the camera→point ray (the space was seen
@@ -141,45 +354,88 @@ var OccupancyGrid = class {
 	*/
 	carve(cameraCell, pointCell) {
 		bresenham3d(cameraCell, pointCell, (cell) => {
-			if (!cellsEqual(cell, pointCell)) this.cells.delete(cellKey(cell));
+			if (!cellsEqual(cell, pointCell)) {
+				const key = cellKey(cell);
+				if (this.cells.delete(key)) {
+					this.revision++;
+					this.unindexCell(cell, key);
+				}
+			}
 			return true;
 		}, this.carveStopCells);
 	}
+	/** Add a newly-occupied cell to its chunk's index set. */
+	indexCell(cell, key) {
+		const ck = chunkKeyOf(Math.floor(cell[0] / CHUNK_EDGE_CELLS), Math.floor(cell[1] / CHUNK_EDGE_CELLS), Math.floor(cell[2] / CHUNK_EDGE_CELLS));
+		let set = this.chunks.get(ck);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.chunks.set(ck, set);
+		}
+		set.add(key);
+	}
+	/** Remove a carved cell from its chunk (dropping an emptied chunk set). */
+	unindexCell(cell, key) {
+		const ck = chunkKeyOf(Math.floor(cell[0] / CHUNK_EDGE_CELLS), Math.floor(cell[1] / CHUNK_EDGE_CELLS), Math.floor(cell[2] / CHUNK_EDGE_CELLS));
+		const set = this.chunks.get(ck);
+		if (set) {
+			set.delete(key);
+			if (set.size === 0) this.chunks.delete(ck);
+		}
+		this.bumpChunkRevision(ck);
+	}
+	/** Mirror of the global revision bump, scoped to one chunk. */
+	bumpChunkRevision(chunkKey) {
+		this.chunkRevisions.set(chunkKey, (this.chunkRevisions.get(chunkKey) ?? 0) + 1);
+	}
 	increment(cell, world, rgb) {
 		const key = cellKey(cell);
 		let record = this.cells.get(key);
 		if (!record) {
 			record = {
-				cell,
 				count: 0,
-				posSum: [
-					0,
-					0,
-					0
-				],
+				posSumX: 0,
+				posSumY: 0,
+				posSumZ: 0,
 				colorCount: 0,
-				colorSum: [
-					0,
-					0,
-					0
-				]
+				colorSumR: 0,
+				colorSumG: 0,
+				colorSumB: 0
 			};
 			this.cells.set(key, record);
+			this.indexCell(cell, key);
 		}
 		record.count++;
-		record.posSum[0] += world[0];
-		record.posSum[1] += world[1];
-		record.posSum[2] += world[2];
+		if (record.count <= MAX_RELEVANT_COUNT) {
+			this.revision++;
+			this.bumpChunkRevision(chunkKeyOf(Math.floor(cell[0] / CHUNK_EDGE_CELLS), Math.floor(cell[1] / CHUNK_EDGE_CELLS), Math.floor(cell[2] / CHUNK_EDGE_CELLS)));
+		}
+		record.posSumX += world[0];
+		record.posSumY += world[1];
+		record.posSumZ += world[2];
 		if (rgb && isFiniteTriple(rgb)) {
 			record.colorCount++;
-			record.colorSum[0] += rgb[0];
-			record.colorSum[1] += rgb[1];
-			record.colorSum[2] += rgb[2];
+			record.colorSumR += rgb[0];
+			record.colorSumG += rgb[1];
+			record.colorSumB += rgb[2];
 		}
 	}
 };
-function cellKey(cell) {
-	return `${cell[0]},${cell[1]},${cell[2]}`;
+function cellInKeyRange(cell) {
+	return cellCoordsInKeyRange(cell, CELL_KEY_LIMIT);
+}
+const CHUNK_EDGE_CELLS = 16;
+const CHUNK_KEY_OFFSET = 4096;
+const CHUNK_KEY_FIELD = 8192;
+const CHUNK_KEY_FIELD_SQ = CHUNK_KEY_FIELD * CHUNK_KEY_FIELD;
+function chunkKeyOf(cx, cy, cz) {
+	return (cx + CHUNK_KEY_OFFSET) * CHUNK_KEY_FIELD_SQ + (cy + CHUNK_KEY_OFFSET) * CHUNK_KEY_FIELD + (cz + CHUNK_KEY_OFFSET);
+}
+/** Inverse of {@link chunkKeyOf} for one axis (0 = x, 1 = y, 2 = z). */
+function unpackChunkCoord(key, axis) {
+	if (axis === 0) return Math.floor(key / CHUNK_KEY_FIELD_SQ) - CHUNK_KEY_OFFSET;
+	if (axis === 1) return Math.floor(key / CHUNK_KEY_FIELD) % CHUNK_KEY_FIELD - CHUNK_KEY_OFFSET;
+	return key % CHUNK_KEY_FIELD - CHUNK_KEY_OFFSET;
 }
 function cellsEqual(a, b) {
 	return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
@@ -188,4 +444,4 @@ function isFiniteTriple(v) {
 	return Number.isFinite(v[0]) && Number.isFinite(v[1]) && Number.isFinite(v[2]);
 }
 //#endregion
-export { OccupancyGrid };
+export { OccupancyGrid, cellKey, unpackCellKey };

package/dist/ar/occupancy-mesher.d.ts

@@ -0,0 +1,2 @@
+import { a as meshOccupiedCells, i as OccupancyMeshResult, n as MeshMode, r as MeshOccupiedCellsOptions, t as Aabb } from "../occupancy-mesher-C2ecWhNp.js";
+export { Aabb, MeshMode, MeshOccupiedCellsOptions, OccupancyMeshResult, meshOccupiedCells };