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

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

@@ -0,0 +1,194 @@
+import { t as GridCell } from "./bresenham3d-DGc4nIb-.js";
+import { f as OccluderDebugStyle } from "./recording-options-vASCFzc5.js";
+import { n as MeshMode, t as Aabb } from "./occupancy-mesher-C2ecWhNp.js";
+import * as THREE from "three";
+import { Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/visualization/occlusion-mesh.d.ts
+/**
+ * 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.
+ */
+declare 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. */
+  readonly FADE_START_M: 0.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). */
+  readonly 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). */
+  readonly FADE_MIN_BRIGHTNESS: 0.3; /** Fresnel exponent — higher hugs the silhouette tighter. */
+  readonly RIM_POWER: 2.5; /** White-rim contribution at a fully grazing view angle. */
+  readonly RIM_STRENGTH: 0.6;
+};
+/**
+ * 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).
+ */
+declare function occluderDepthFade(distanceM: number): number;
+/**
+ * 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].
+ */
+declare function occluderFresnelRim(cosViewAngle: number): number;
+/**
+ * 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}).
+ */
+declare function buildOccluderDepthShadeSnippet(): string;
+interface OcclusionMeshOptions {
+  /**
+   * Merge coplanar faces (fewer triangles, same occluded volume). Default
+   * true — the occluder is invisible, so the coarser triangulation is free.
+   * Ignored when {@link OcclusionMeshOptions.mode} is set.
+   */
+  readonly greedy?: boolean;
+  /**
+   * Mesher strategy (additive opt-in; 2026-06-30 occluder-tuning, F2). When set
+   * it takes precedence over {@link greedy}. `'smooth'` selects the surface-nets
+   * mesher that hugs the measured per-cell centroids — pass a `getCellPoint`
+   * provider to {@link OcclusionMesh.update} for it to read. Left **unset by
+   * default** so existing behaviour (greedy cubes) is byte-for-byte unchanged
+   * until the smooth occluder is confirmed on-device.
+   */
+  readonly mode?: MeshMode;
+  /**
+   * `renderOrder` of the depth-only mesh. Must be below virtual content so the
+   * occluder lays down depth first. Default −1. (The live occluder, when it
+   * exists, sits between this and content — plan §5.)
+   */
+  readonly renderOrder?: number;
+}
+/**
+ * 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.
+ */
+declare class OcclusionMesh {
+  private readonly arSpaceNode;
+  private readonly greedy;
+  private readonly mode;
+  private readonly material;
+  private readonly mesh;
+  private geometry;
+  private lastAabbs;
+  private disposed;
+  private debugStyle;
+  private shadedSkin;
+  private wireframeSkin;
+  private matcapTexture;
+  private matcapMaterial;
+  private depthShadedMaterial;
+  private wireframeMaterial;
+  /**
+   * @param arSpaceNode the AR-odometry-NUE node that receives the alignment
+   *   matrix (`arWorldGroup` live, `replaySceneState.arWorldGroup` in replay).
+   */
+  constructor(arSpaceNode: THREE.Object3D, options?: OcclusionMeshOptions);
+  /** The number of triangles currently drawn. */
+  getTriangleCount(): number;
+  /** The AABB list from the most recent {@link update} (physics export hook). */
+  getAabbs(): readonly Aabb[];
+  /**
+   * 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: Iterable<GridCell>, cellSizeM: number, getCellPoint?: (cell: GridCell) => Vector3 | null): void;
+  /**
+   * 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: Float32Array, indices: Uint32Array): void;
+  /**
+   * 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.
+   */
+  private swapGeometry;
+  /** Point every active debug skin at the (new) shared geometry. */
+  private rebindSkinGeometry;
+  /**
+   * 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: OccluderDebugStyle): void;
+  /** Which matcap-based material the style shades with (null = no shaded skin). */
+  private shadedMaterialFor;
+  /** Add/retarget/remove the single shaded skin node for the desired material. */
+  private applyShadedSkin;
+  /** 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. */
+  private applyWireframeSkin;
+  /**
+   * 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: boolean): void;
+  /** A debug skin mesh sharing the occluder's geometry, transform and culling
+   *  behaviour — only name, renderOrder and material differ per skin. */
+  private createSkinMesh;
+  /** The procedural matcap texture, shared by both matcap-based materials. */
+  private getMatcapTexture;
+  private getMatcapMaterial;
+  private getDepthShadedMaterial;
+  private getWireframeMaterial;
+  /** Empty the mesh (e.g. on store swap); the node stays in the scene. */
+  clear(): void;
+  /** Remove the mesh from its parent and release GPU resources. */
+  dispose(): void;
+}
+//#endregion
+export { occluderDepthFade as a, buildOccluderDepthShadeSnippet as i, OcclusionMesh as n, occluderFresnelRim as o, OcclusionMeshOptions as r, OCCLUDER_DEPTH_SHADE as t };

package/dist/occupancy-grid-BV7RhB7I.d.ts

@@ -0,0 +1,194 @@
+import { t as GridCell } from "./bresenham3d-DGc4nIb-.js";
+import { a as RgbTuple, i as DepthSample } from "./ar-types-Cc5yvBwn.js";
+import { Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/cell-key.d.ts
+/** Tuple convenience over {@link packCellKey}. */
+declare function cellKey(cell: GridCell): number;
+/**
+ * Exact inverse of {@link cellKey} over the ±{@link CELL_KEY_LIMIT} envelope
+ * (property-tested). Consumers that no longer store coordinate tuples recover
+ * them from the key through this function.
+ */
+declare function unpackCellKey(key: number): GridCell;
+//#endregion
+//#region ../src/ar/occupancy-grid.d.ts
+interface OccupancyGridOptions {
+  /** Edge length of a cubic grid cell in meters. Default 0.15 (Unity parity). */
+  readonly cellSizeM?: number;
+  /**
+   * Dominant-axis steps before a ray's endpoint at which free-space
+   * carving stops, to respect depth noise. Default 2 (Unity parity).
+   */
+  readonly carveStopCells?: number;
+}
+declare class OccupancyGrid {
+  readonly cellSizeM: number;
+  readonly carveStopCells: number;
+  private readonly cells;
+  /**
+   * 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.
+   */
+  private readonly chunks;
+  /**
+   * 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}.
+   */
+  private readonly chunkRevisions;
+  /**
+   * 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`).
+   */
+  private revision;
+  /**
+   * 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}).
+   */
+  private snapshotCache;
+  constructor(options?: OccupancyGridOptions);
+  /** Number of occupied cells. */
+  get size(): number;
+  /**
+   * 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(): number;
+  /**
+   * 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
+   * projectionMatrix on old recordings, invalid depth/coords) are skipped.
+   *
+   * Carving and incrementing run as two separate passes over the sample's
+   * points: all rays are carved first, then every endpoint is incremented.
+   * A single interleaved pass would be order-dependent — a deeper point's
+   * carve could erase the endpoint a nearer point added earlier in the same
+   * sample. Splitting the passes makes the result deterministic and lets an
+   * endpoint observed within a sample survive other rays in that same
+   * sample. (Deeper-carves-nearer still applies ACROSS samples: a later
+   * sample's ray carves an earlier sample's endpoint as before.)
+   *
+   * @returns the number of points actually added.
+   */
+  addSample(sample: DepthSample): number;
+  /**
+   * 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?: number): GridCell[];
+  /**
+   * 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?: number): Int32Array;
+  /**
+   * 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: Vector3, radiusM: number, minObservations?: number): GridCell[];
+  /**
+   * 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: Vector3, radiusM: number, minObservations?: number): Int32Array;
+  /**
+   * 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: GridCell): number;
+  /** Shared sphere-window walk behind the tuple and flat queries. */
+  private forEachOccupiedCellWithin;
+  /** Quantize a raw-WebXR position to its grid cell (round per axis). */
+  cellForPosition(pos: Vector3): GridCell;
+  /** Center of a cell in raw WebXR space (round-consistent: cell · cellSizeM). */
+  getCellCenter(cell: GridCell): Vector3;
+  /**
+   * Running-average of the EXACT unprojected surface points observed in this
+   * cell (raw WebXR space), or null for an unknown cell. Unlike
+   * {@link getCellCenter} (the geometric 15 cm-lattice center) this hugs the
+   * real measured surface and noise-averages across viewpoints — used by the
+   * COLMAP `points3D` export and the debug cubes (follow-up Item A). Being a
+   * centroid of points that fell in the cell, it always lies within
+   * `cellSizeM/2` of the cell center per axis.
+   */
+  getCellPoint(cell: GridCell): Vector3 | null;
+  /**
+   * Running-average color of the cell's colored observations (Iter 8), or
+   * null when the cell is unknown or was only ever observed without color
+   * (rgb option off / pre-Iter-8 recordings) — consumers fall back to
+   * height-based coloring. Channels are rounded and clamped to 0–255.
+   */
+  getCellColor(cell: GridCell): RgbTuple | null;
+  /**
+   * Walk the grid from `startPos` to `endPos` and return the center of the
+   * first cell occupied at least `minObservations` times, or null.
+   * Port of Unity's `TryRaycast` (hook for cursor/floor-detection parity).
+   */
+  raycast(startPos: Vector3, endPos: Vector3, minObservations?: number): Vector3 | null;
+  /** Remove all occupied cells (e.g. on store swap / new session). */
+  clear(): void;
+  /**
+   * Delete occupied cells along the camera→point ray (the space was seen
+   * through, so it must be free), stopping `carveStopCells` dominant-axis
+   * steps before the endpoint. The endpoint cell itself is additionally
+   * protected so a current observation is never erased (relevant for
+   * carveStopCells = 0 and for the unconditional start-cell visit).
+   */
+  private carve;
+  /** Add a newly-occupied cell to its chunk's index set. */
+  private indexCell;
+  /** Remove a carved cell from its chunk (dropping an emptied chunk set). */
+  private unindexCell;
+  /** Mirror of the global revision bump, scoped to one chunk. */
+  private bumpChunkRevision;
+  private increment;
+}
+//#endregion
+export { unpackCellKey as i, OccupancyGridOptions as n, cellKey as r, OccupancyGrid as t };

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

@@ -0,0 +1,100 @@
+import { t as GridCell } from "./bresenham3d-DGc4nIb-.js";
+import { Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/occupancy-mesher.d.ts
+/**
+ * An axis-aligned bounding box for one occupied cell (or, after greedy merge, a
+ * run of cells), in raw-WebXR metres. The neutral form a developer adapts into
+ * their physics engine's box collider — the framework adds no engine dependency.
+ */
+interface Aabb {
+  readonly center: readonly [number, number, number];
+  readonly halfExtents: readonly [number, number, number];
+}
+/**
+ * Output of {@link meshOccupiedCells}: a non-indexed-friendly triangle soup
+ * (`positions`/`indices`, raw-WebXR metres) plus the per-cell AABB list. Typed
+ * arrays so the result is cheap to hand to `THREE.BufferGeometry` or transfer
+ * to a Web Worker.
+ */
+interface OccupancyMeshResult {
+  /** Flat `[x0,y0,z0, x1,y1,z1, …]` vertex positions, 4 verts per emitted quad. */
+  readonly positions: Float32Array;
+  /** Triangle indices into `positions` (2 triangles / 6 indices per quad). */
+  readonly indices: Uint32Array;
+  /** One AABB per unique occupied cell. */
+  readonly aabbs: readonly Aabb[];
+}
+/**
+ * Selectable mesher strategy (2026-06-30 occluder-tuning session). All modes are
+ * simultaneously usable — none replaces another — so they can be perf/quality
+ * compared and a consumer can pick per use-case:
+ * - `'per-face'` — blocky, watertight, exact cell volume; the strict baseline.
+ * - `'greedy'` — fewest triangles, blocky; coplanar-face merge for memory.
+ * - `'smooth'` — standard surface nets (dual contouring): one welded vertex per
+ *   boundary dual cell at the mean of its occupied corners' `getCellPoint`, with
+ *   one quad per occupied↔empty crossing — so coverage matches the cubes.
+ *   Continuous, hugs the measured surface, watertight for closed regions; a thin
+ *   feature (the floor) collapses to a single smooth sheet (the smoothest mode),
+ *   with only its single-occupied-corner dual vertices nudged apart so features
+ *   thin in ≥2 dimensions keep a non-zero area (see SINGLE_CORNER_NUDGE_K).
+ *   Uses `getCellPoint` to hug the surface (falls back to geometric centres).
+ *
+ * - `'corner-fit'` — the per-face cube mesher with each shared lattice corner
+ *   nudged by the mean sub-cell offset (`getCellPoint − cellCentre`) of the cells
+ *   touching it. Surface-hugging like `'smooth'` but **watertight** (identical
+ *   face topology to `'per-face'`) and cube-thickness-preserving, at the per-face
+ *   triangle cost. The "improve the cubes" path; needs `getCellPoint` (falls back
+ *   to plain cubes without it).
+ */
+type MeshMode = 'per-face' | 'greedy' | 'smooth' | 'corner-fit';
+/** Options for {@link meshOccupiedCells}. */
+interface MeshOccupiedCellsOptions {
+  /**
+   * @deprecated Prefer {@link MeshOccupiedCellsOptions.mode}. Back-compat shim:
+   * when `mode` is unset, `greedy:true` → `'greedy'`, otherwise `'per-face'`.
+   * Kept so existing callers/tests keep working unchanged.
+   */
+  readonly greedy?: boolean;
+  /**
+   * The mesher strategy. Takes precedence over {@link greedy}. Default resolves
+   * via the `greedy` shim above (so omitting both ⇒ `'per-face'`).
+   *
+   * Note: every mode still returns one `aabbs` box per cell (a 3-D greedy box
+   * merge for fewer colliders is a separate follow-on — see the plan §3E).
+   */
+  readonly mode?: MeshMode;
+  /**
+   * Per-cell measured surface point (the `OccupancyGrid.getCellPoint` bound
+   * method). Consumed by the surface-hugging modes `'smooth'` (dual vertex at the
+   * mean of its occupied corners' centroids) and `'corner-fit'` (corners nudged
+   * by the mean sub-cell offset) instead of the lattice centre. Ignored by
+   * `'per-face'`/`'greedy'`. When absent, both fall back to geometric positions.
+   * A `null` or non-finite result degrades that cell to its geometric position
+   * too — a NaN/Infinity centroid must not poison welded vertices (and NaN is
+   * the worker wire protocol's "no centroid" sentinel, so both paths agree).
+   *
+   * **Contract:** the `cell` tuple is only valid for the duration of the call —
+   * the meshers pass a reused scratch tuple on their allocation-free hot paths
+   * (PR #161 review), so implementations must read the coordinates and must NOT
+   * retain the tuple (no caching it as a key, no async use). Copy it if needed.
+   */
+  readonly getCellPoint?: (cell: GridCell) => Vector3 | null;
+}
+/**
+ * Mesh a snapshot of occupied cells into a face-culled surface + AABB list.
+ *
+ * Only faces whose neighbour cell is **not** in the occupied set are emitted
+ * (interior faces are dropped), so the triangle count scales with the surface
+ * area of the occupied set. Duplicate cells in `cells` are de-duplicated;
+ * cells with a non-finite or non-integer coordinate are skipped defensively (a
+ * tracking glitch upstream must not poison the mesh, and the packed cell keys
+ * are only collision-safe for integer coordinates).
+ *
+ * @param cells     occupied cells (e.g. `grid.getOccupiedCells(minConfidence)`).
+ * @param cellSizeM cube edge length in metres (must be a positive finite number).
+ * @returns positions/indices (raw-WebXR metres) + one AABB per unique cell.
+ */
+declare function meshOccupiedCells(cells: Iterable<GridCell>, cellSizeM: number, options?: MeshOccupiedCellsOptions): OccupancyMeshResult;
+//#endregion
+export { meshOccupiedCells as a, OccupancyMeshResult as i, MeshMode as n, MeshOccupiedCellsOptions as r, Aabb as t };

package/dist/{opfs-storage-DMtlt57S.d.ts → opfs-storage-CTkxvxN4.d.ts}

@@ -137,6 +137,11 @@ declare function getAppRootHandle(): FileSystemDirectoryHandle | null;
  * - /gps-plus-slam/sessions/recording-{timestamp}/actions/
  * - /gps-plus-slam/sessions/recording-{timestamp}/images/ (legacy: frames/)
  *
+ * The folder name is `recording-{timestamp}` at whole-second resolution; if a
+ * directory with that name already exists (two recordings started in the same
+ * UTC second), a numeric suffix (`-2`, `-3`, …) is appended so the new session
+ * never silently reuses and corrupts the earlier one's directory.
+ *
  * @param timestamp - Session start time (used for folder naming)
  * @param _contextTag - Opaque tag; not used by the flat layout but accepted
  *   for interface compatibility with wrapping backends

package/dist/{opfs-storage-backend-CeQAb0SD.d.ts → opfs-storage-backend-D6Z03fML.d.ts}

@@ -1,5 +1,5 @@
-import { n as SessionMetadata } from "./opfs-storage-DMtlt57S.js";
-import { n as StorageBackend, t as CreateSessionResult } from "./storage-backend-CTJHNdMp.js";
+import { n as SessionMetadata } from "./opfs-storage-CTkxvxN4.js";
+import { n as StorageBackend, t as CreateSessionResult } from "./storage-backend-sEtmM4yW.js";
 
 //#region ../src/storage/opfs-storage-backend.d.ts
 declare class OpfsStorageBackend implements StorageBackend {

package/dist/{persistence-middleware-5eearhSV.d.ts → persistence-middleware-CG-t08X4.d.ts}

@@ -1,4 +1,4 @@
-import { n as StorageBackend } from "./storage-backend-CTJHNdMp.js";
+import { n as StorageBackend } from "./storage-backend-sEtmM4yW.js";
 import { Middleware } from "@reduxjs/toolkit";
 
 //#region ../src/state/persistence-middleware.d.ts

package/dist/{planar-pnp-cjthe7Be.d.ts → planar-pnp-D7bc_rLX.d.ts}

@@ -1,4 +1,4 @@
-import { n as OpenCvPnpResult, r as Point2, s as SolvePnpSquare, t as CameraIntrinsics } from "./qr-pose-Bt2reSw7.js";
+import { n as OpenCvPnpResult, r as Point2, s as SolvePnpSquare, t as CameraIntrinsics } from "./qr-pose-y3vaEd6x.js";
 import { Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/ar/planar-pnp.d.ts

package/dist/{qr-debug-view-B8gTzjMm.d.ts → qr-debug-view-BJooqbiP.d.ts}

@@ -1,4 +1,4 @@
-import { i as Pose } from "./qr-pose-Bt2reSw7.js";
+import { i as Pose } from "./qr-pose-y3vaEd6x.js";
 import { Object3D } from "three";
 
 //#region ../src/ar/qr-debug-view.d.ts

package/dist/{qr-derived-pose-DinKE600.d.ts → qr-derived-pose-BwNWn8oV.d.ts}

@@ -1,5 +1,5 @@
-import { i as Pose, r as Point2, s as SolvePnpSquare } from "./qr-pose-Bt2reSw7.js";
-import { a as QrSizeMeasurerOptions, n as QrSizeDepthContext } from "./qr-size-measurer-D7739ZpB.js";
+import { i as Pose, r as Point2, s as SolvePnpSquare } from "./qr-pose-y3vaEd6x.js";
+import { a as QrSizeMeasurerOptions, n as QrSizeDepthContext } from "./qr-size-measurer-DxiMqRUw.js";
 import { Matrix4 } from "gps-plus-slam-js";
 
 //#region ../src/ar/qr-derived-pose.d.ts

package/dist/{qr-detected-slice-Cpv-dg82.d.ts → qr-detected-slice-TzVb8bij.d.ts}

@@ -1,7 +1,7 @@
-import { i as Pose, r as Point2 } from "./qr-pose-Bt2reSw7.js";
-import { l as QrSizeEstimate } from "./qr-size-measurer-D7739ZpB.js";
-import { i as RawQrObservation, n as DerivedQrPlacement, t as DeriveQrPoseDeps } from "./qr-derived-pose-DinKE600.js";
-import { a as QrPoseStability, o as QrPoseStabilityOptions } from "./qr-pose-aggregation-CFlmLm6w.js";
+import { i as Pose, r as Point2 } from "./qr-pose-y3vaEd6x.js";
+import { l as QrSizeEstimate } from "./qr-size-measurer-DxiMqRUw.js";
+import { i as RawQrObservation, n as DerivedQrPlacement, t as DeriveQrPoseDeps } from "./qr-derived-pose-BwNWn8oV.js";
+import { a as QrPoseStability, o as QrPoseStabilityOptions } from "./qr-pose-aggregation-CypnmjA-.js";
 import { Matrix4, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 

package/dist/{qr-detection-controller-Cd2Ih4cC.d.ts → qr-detection-controller-Bo4XfQTP.d.ts}

@@ -1,6 +1,6 @@
-import { i as Pose } from "./qr-pose-Bt2reSw7.js";
-import { i as QrDetection, o as RgbaImage } from "./qr-frontend-DufZp2xS.js";
-import { i as RawQrObservation } from "./qr-derived-pose-DinKE600.js";
+import { i as Pose } from "./qr-pose-y3vaEd6x.js";
+import { i as QrDetection, o as RgbaImage } from "./qr-frontend-BPURlh3S.js";
+import { i as RawQrObservation } from "./qr-derived-pose-BwNWn8oV.js";
 import { Matrix4 } from "gps-plus-slam-js";
 
 //#region ../src/ar/qr-detection-controller.d.ts

package/dist/{qr-frontend-DufZp2xS.d.ts → qr-frontend-BPURlh3S.d.ts}

@@ -1,4 +1,4 @@
-import { r as Point2 } from "./qr-pose-Bt2reSw7.js";
+import { r as Point2 } from "./qr-pose-y3vaEd6x.js";
 
 //#region ../src/ar/qr-frontend.d.ts
 /** Raw RGBA pixels of the frame fed to detection (top-left origin). */

package/dist/{qr-pose-aggregation-CFlmLm6w.d.ts → qr-pose-aggregation-CypnmjA-.d.ts}

@@ -1,4 +1,4 @@
-import { i as Pose } from "./qr-pose-Bt2reSw7.js";
+import { i as Pose } from "./qr-pose-y3vaEd6x.js";
 import { Quaternion } from "gps-plus-slam-js";
 
 //#region ../src/ar/qr-pose-aggregation.d.ts

package/dist/{qr-pose-aggregation-DXR9STHs.js → qr-pose-aggregation-DBiaLW0O.js}

@@ -1,3 +1,4 @@
+import { t as geodesicAngleRad } from "./geodesic-angle-BTldfFgs.js";
 import { quat } from "gl-matrix";
 //#region ../src/ar/qr-pose-aggregation.ts
 /**
@@ -45,16 +46,6 @@ function toGl(q) {
 	return quat.normalize(g, g);
 }
 /**
-* Geodesic (shortest-arc) angle in radians between two unit quaternions.
-* Double-cover safe: uses `2·dot² − 1 = cos θ`, which is invariant to the sign
-* of either quaternion (`q` ≡ `−q`), and clamps for float error before `acos`.
-*/
-function geodesicAngleRad(a, b) {
-	const d = quat.dot(a, b);
-	const c = Math.min(1, Math.max(-1, 2 * d * d - 1));
-	return Math.acos(c);
-}
-/**
 * Average the samples within `thresholdRad` of `ref`. Each inlier is flipped
 * into `ref`'s hemisphere (sign of the dot) BEFORE the linear average so the
 * double cover cannot cancel the sum; the normalized linear average equals the

package/dist/{qr-size-depth-context-onu36E9s.d.ts → qr-size-depth-context-apAOmbrZ.d.ts}

@@ -1,5 +1,5 @@
-import { i as DepthSample } from "./ar-types-BckI1E-O.js";
-import { n as QrSizeDepthContext } from "./qr-size-measurer-D7739ZpB.js";
+import { i as DepthSample } from "./ar-types-Cc5yvBwn.js";
+import { n as QrSizeDepthContext } from "./qr-size-measurer-DxiMqRUw.js";
 
 //#region ../src/ar/qr-size-depth-context.d.ts
 /**

package/dist/{qr-size-measurer-D7739ZpB.d.ts → qr-size-measurer-DxiMqRUw.d.ts}

@@ -1,6 +1,6 @@
-import { r as DepthPoint } from "./ar-types-BckI1E-O.js";
-import { t as DepthUnprojector } from "./depth-unprojection-CK3b9htH.js";
-import { r as Point2 } from "./qr-pose-Bt2reSw7.js";
+import { r as DepthPoint } from "./ar-types-Cc5yvBwn.js";
+import { t as DepthUnprojector } from "./depth-unprojection-DRdBU90S.js";
+import { r as Point2 } from "./qr-pose-y3vaEd6x.js";
 import { Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/ar/qr-size-from-depth.d.ts