gps-plus-slam-app-framework 1.11.0 → 1.13.0

package/dist/{occupancy-grid-CYBdmMOo.d.ts → occupancy-grid-DKzIdCSZ.d.ts}

@@ -1,5 +1,5 @@
-import { t as GridCell } from "./bresenham3d-D-t9i_b5.js";
-import { a as RgbTuple, i as DepthSample } from "./ar-types-D6PYS4bc.js";
+import { t as GridCell } from "./bresenham3d-bt61R-Qa.js";
+import { a as RgbTuple, i as DepthSample } from "./ar-types-BprL3nKv.js";
 import { Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/ar/cell-key.d.ts
@@ -21,10 +21,65 @@ interface OccupancyGridOptions {
    * carving stops, to respect depth noise. Default 2 (Unity parity).
    */
   readonly carveStopCells?: number;
+  /**
+   * Confidence-guarded carving (2026-07-16 synthetic-scene investigation):
+   * when set, a carve ray reaching a cell whose observation count is at or
+   * above this threshold DECAYS the cell (count − 1, measured point/color
+   * means preserved) and stops the trace — an established surface can no
+   * longer be erased by a single deeper reading (silhouette-grazing churn
+   * under a perfect sensor, or a noisy/bled too-far endpoint sweeping
+   * through a confirmed wall into the occluded background), while REPEATED
+   * contradicting rays still drain and eventually delete confidently-wrong
+   * cells (the 2026-07-16-1547 fossilization field regression: a HARD block
+   * made noise meshes immortal — mesh built while the grid was uncertain
+   * could never be un-built by better data). Once below the threshold, the
+   * legacy delete applies. Default undefined = legacy unguarded carving.
+   * Must be a positive safe integer when set.
+   */
+  readonly carveConfidenceThreshold?: number;
 }
+/**
+ * Recommended reconstruction defaults for apps that build AND render an occupancy
+ * mesh (the Recorder, the PhysicsDemo). These are the single framework-level source
+ * of truth so every consumer inherits the same tuning — change them here and both
+ * apps follow.
+ *
+ * They are DELIBERATELY separate from {@link OccupancyGrid}'s constructor fallback
+ * (`cellSizeM ?? 0.15`, Unity parity): that primitive fallback stays 0.15 because a
+ * pile of low-level tests build `new OccupancyGrid()` with no args and assume 0.15
+ * quantization. Both apps always pass an explicit `cellSizeM`, so the app-facing
+ * recommended default and the primitive fallback can differ without conflict.
+ *
+ * Tuning (2026-07-16 EVENING, maintainer's on-device framerate/mesh trade-off
+ * pass — supersedes the same-day corpus-sweep values 0.18/3): voxel 16 cm,
+ * noise floor 2. The sweep's argument for floor 3 (floaters = phantom
+ * colliders: mc 3 ≈ 1.9% vs mc 2 ≈ 3.5%) was measured under LEGACY carving;
+ * with the decay carve guard the floater gap largely disappears (real
+ * pillar-orbit A/B: guarded mc 2 isolates 2.12% vs guarded mc 3 2.19%), so
+ * the faster floor is affordable now. `0.16` stays within
+ * `OCCUPANCY_CONSTRAINTS.cellSizeM.max` (0.20); `2` within `minConfidence`
+ * 1–10. History: 2026-07-16-0557 corpus sweep (0.18/3),
+ * 2026-07-15-1640 device-impression change (0.18/2). See the recorder's
+ * recording-options.ts.md for the full tuning timeline.
+ */
+declare const DEFAULT_OCCUPANCY_CELL_SIZE_M = 0.16;
+/**
+ * Recommended occupancy noise floor — the minimum observation count before a cell
+ * is rendered/meshed (the Recorder's `minConfidence`, the demo's `minObservations`,
+ * and — since the decay guard — both apps' `carveConfidenceThreshold`).
+ * See {@link DEFAULT_OCCUPANCY_CELL_SIZE_M} for the rationale and the tuning note.
+ */
+declare const DEFAULT_OCCUPANCY_MIN_OBSERVATIONS = 2;
 declare class OccupancyGrid {
   readonly cellSizeM: number;
   readonly carveStopCells: number;
+  /**
+   * Carve-blocking observation-count threshold, or undefined for legacy
+   * unguarded carving (see {@link OccupancyGridOptions}). Public + always
+   * present on instances so consumers built against a newer source can
+   * feature-detect the guard on an installed build at runtime.
+   */
+  readonly carveConfidenceThreshold: number | undefined;
   private readonly cells;
   /**
    * Chunk index (Step 2 of the 2026-07-03 long-session fps plan): cell keys
@@ -180,8 +235,63 @@ declare class OccupancyGrid {
    * 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).
+   *
+   * With `carveConfidenceThreshold` set, the trace additionally stops at the
+   * first cell whose count has reached the threshold, DECAYING it by one
+   * observation (means preserved) — soft contradiction instead of deletion,
+   * so nothing behind an established surface is carved but repeated
+   * contradictions still un-build it (see the option docs). Note this makes
+   * a repeated identical carve NOT a no-op — the per-sample unique-endpoint
+   * dedupe in `addSample` is therefore semantically load-bearing under the
+   * guard (one decay per contradicting ray per sample).
+   *
+   * PERFORMANCE — fused walk (2026-07-17 perf loop, iteration 1): this is
+   * the framework's hottest non-render loop (hundreds of rays per depth
+   * sample at the 200 ms reconstruction cadence), and the generic
+   * `bresenham3d(callback)` shape dominated the fold profile: a fresh
+   * `[x, y, z]` tuple + callback dispatch + full `cellKey` repack +
+   * `cellsEqual` per visited cell. The Bresenham walk (identical integer
+   * stepping, `bresenham3d` stays the reference — see the fold-oracle
+   * property test) is therefore fused in here with two key tricks:
+   *
+   * - The packed cell key is maintained INCREMENTALLY: stepping one cell
+   *   along an axis moves the key by that axis' constant field stride
+   *   (base-2^17 positional packing), replacing the 3-term repack.
+   * - The endpoint guard compares packed keys (`key === endpointKey`).
+   *   Every walked cell lies inside the camera→point AABB whose corners the
+   *   caller range-checked, so packing is bijective on the whole walk and
+   *   the compare is exactly `cellsEqual` — and key aliasing is impossible.
+   *
+   * The cell tuple is materialized only on an actual delete/decay hit (rare
+   * per trace, handled in {@link carveCellAt}). Measured on the
+   * occupancy-fold bench (devbox-win11, Node 24, 50 samples × 576 pts,
+   * production config): 37.05 → 25.71 ms median of 5, −30.6%.
+   * Input safety: cameraCell/pointCell are integer cells from
+   * `cellForPosition` (finite-checked upstream) and both range-checked by
+   * `addSample`, so dm ≤ 2·CELL_KEY_LIMIT « MAX_TRACE_STEPS and the generic
+   * tracer's integer/span guards are structurally satisfied here.
    */
   private carve;
+  /**
+   * Per-cell action of the fused carve walk (extracted so both it and the
+   * walk stay under the lint complexity budget; a monomorphic private-method
+   * call per visited cell measured within noise of the fully-inlined form).
+   *
+   * @returns `false` when the trace must stop: the cell is an established
+   *   surface (count ≥ threshold) that was decayed instead of deleted.
+   */
+  private carveCellAt;
+  /**
+   * Soft contradiction of an established cell (confidence-guarded carving):
+   * remove one observation while preserving the measured point/color MEANS
+   * (sums are scaled with the count — decrementing the divisor alone would
+   * silently shift `getCellPoint`/`getCellColor`). Deletes outright when the
+   * count would reach 0 (threshold 1). Bumps revisions like any mutation
+   * that can change a consumer's occupied set (counts above
+   * MAX_RELEVANT_COUNT cannot cross any selectable floor, so those decays
+   * stay revision-silent).
+   */
+  private decayCell;
   /** 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). */
@@ -191,4 +301,4 @@ declare class OccupancyGrid {
   private increment;
 }
 //#endregion
-export { unpackCellKey as i, OccupancyGridOptions as n, cellKey as r, OccupancyGrid as t };
+export { cellKey as a, OccupancyGridOptions as i, DEFAULT_OCCUPANCY_MIN_OBSERVATIONS as n, unpackCellKey as o, OccupancyGrid as r, DEFAULT_OCCUPANCY_CELL_SIZE_M as t };

package/dist/{occupancy-mesher-B4Bv4BTk.d.ts → occupancy-mesher-Co80tOpl.d.ts}

@@ -1,4 +1,4 @@
-import { t as GridCell } from "./bresenham3d-D-t9i_b5.js";
+import { t as GridCell } from "./bresenham3d-bt61R-Qa.js";
 import { Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/ar/occupancy-mesher.d.ts
@@ -75,6 +75,27 @@ interface MeshOccupiedCellsOptions {
    * retain the tuple (no caching it as a key, no async use). Copy it if needed.
    */
   readonly getCellPoint?: (cell: GridCell) => Vector3 | null;
+  /**
+   * Pre-packed per-cell centroids for `'smooth'`, aligned with the **input
+   * `cells` order** (3 numbers per input cell; a non-finite triple — the
+   * worker wire protocol packs NaN for "no centroid" — falls back to that
+   * cell's geometric centre, exactly like a null/non-finite `getCellPoint`
+   * result). This is the mesh-worker fast path (2026-07-17 perf loop,
+   * iteration 2): `runMeshRequest` receives exactly this array over the wire,
+   * so consuming it directly deletes the per-cell key-map + callback + tuple
+   * plumbing from the hottest re-mesh loop. When set, `'smooth'` ignores
+   * `getCellPoint`; other modes ignore `centroids` entirely (`'corner-fit'`
+   * still needs the callback).
+   */
+  readonly centroids?: Float64Array | null;
+  /**
+   * Set `false` to skip building the per-cell AABB list (`result.aabbs` is
+   * then empty). The occlusion-mesh worker path consumes only
+   * positions/indices, and at the ~100k-cell regime the discarded AABB
+   * objects (~2 allocations per cell, every re-mesh) were pure GC pressure
+   * (2026-07-17 perf loop, iteration 2). Default `true`.
+   */
+  readonly includeAabbs?: boolean;
 }
 /**
  * Mesh a snapshot of occupied cells into a face-culled surface + AABB list.