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

package/dist/visualization/leaflet-map-overlay.js

@@ -1,283 +1,2 @@
-import { createLogger } from "../utils/logger.js";
-import { VIS_COLORS } from "./vis-colors.js";
-import { drawMapData } from "./map-overlay-draw.js";
-import { CSS3DObject } from "three/addons/renderers/CSS3DRenderer.js";
-import L from "leaflet";
-//#region ../src/visualization/leaflet-map-overlay.ts
-const log = createLogger("LeafletMapOverlay");
-/** Default pixel size of the Leaflet map container */
-const DEFAULT_LEAFLET_MAP_SIZE_PX = 600;
-/**
-* Diameter (px) of the ref-point markers on the in-AR minimap.
-*
-* Enlarged 12 → 20 px (F5-A, 2026-06-16 user feedback): the field tester
-* reported the minimap "showed the user but not the marker". The markers WERE
-* rendered — they were just too small to notice on the small CSS3D minimap. A
-* bigger dot plus a thicker white halo and a drop shadow makes them the most
-* prominent feature on the minimap (the user-position marker stays 14 px).
-*/
-const REF_POINT_MARKER_SIZE_PX = 20;
-/** Default world-space size in meters (matches old MapOverlay) */
-const DEFAULT_WORLD_SIZE = 10;
-/** Default height offset below camera (negative = below) */
-const DEFAULT_HEIGHT_OFFSET = -4;
-/** Default forward offset from parent (negative = forward in parent-local Z) */
-const DEFAULT_Z_OFFSET = -1;
-/** Default zoom level for the Leaflet map */
-const DEFAULT_ZOOM = 17;
-/** Minimum allowed zoom level */
-const MIN_ZOOM = 0;
-/** Maximum allowed zoom level */
-const MAX_ZOOM = 19;
-var LeafletMapOverlay = class {
-	scene;
-	camera;
-	mapParent;
-	worldSize;
-	heightOffset;
-	mapSizePx;
-	tileServerUrl;
-	onTileError;
-	offscreenRoot;
-	zoomLevel;
-	gpsPosition = null;
-	visible = false;
-	mapContainer = null;
-	leafletMap = null;
-	tileLayer = null;
-	cssObject = null;
-	latestMapData = null;
-	trajectoryLayers = [];
-	namedMarkers = [];
-	constructor(scene, camera, options = {}) {
-		this.scene = scene;
-		this.camera = camera;
-		this.mapParent = options.mapParent ?? camera;
-		this.worldSize = options.worldSize ?? 10;
-		this.heightOffset = options.heightOffset ?? -4;
-		this.mapSizePx = options.mapSizePx ?? 600;
-		this.zoomLevel = options.zoomLevel ?? 17;
-		this.tileServerUrl = options.tileServerUrl ?? "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
-		this.onTileError = options.onTileError;
-		this.offscreenRoot = options.offscreenRoot ?? document.body;
-	}
-	setGpsPosition(lat, lon) {
-		this.gpsPosition = {
-			lat,
-			lon
-		};
-		if (this.leafletMap) this.leafletMap.setView([lat, lon], this.zoomLevel);
-	}
-	getGpsPosition() {
-		return this.gpsPosition;
-	}
-	show() {
-		if (!this.gpsPosition) {
-			log.warn("Cannot show map — no GPS position set");
-			return;
-		}
-		if (this.visible) return;
-		this.createLeafletMap();
-		this.createCssObject();
-		this.applyBufferedOverlays();
-		this.visible = true;
-		log.info("Leaflet map overlay shown");
-	}
-	hide() {
-		if (!this.visible) return;
-		this.removeCssObject();
-		this.visible = false;
-		log.info("Leaflet map overlay hidden");
-	}
-	toggle() {
-		if (this.visible) this.hide();
-		else this.show();
-	}
-	isVisible() {
-		return this.visible;
-	}
-	/**
-	* Render a full trajectory snapshot.
-	*
-	* Replaces the previous incremental `addRawGpsPoint` / `addFusedPoint` /
-	* `addAlignmentSnapshot` API with a single full-snapshot path: the caller
-	* builds a {@link MapData} (via the shared `buildMapData`) from the latest
-	* store slices and hands it here. The trajectory layers are redrawn
-	* wholesale through the shared {@link drawMapData} routine, so the live map
-	* stays pixel-identical to the 2D session-summary map and the fused path
-	* recomputes (D2) as the alignment matrix improves.
-	*
-	* Buffered when the map is not yet shown; applied on `show()`.
-	*/
-	render(data) {
-		this.latestMapData = data;
-		if (this.leafletMap) this.drawTrajectory();
-	}
-	/** Add a "current" named marker (red). Buffered if map is not yet shown. */
-	addCurrentMarker(lat, lon, name) {
-		const marker = this.leafletMap ? this.createNamedMarker(lat, lon, name, false) : null;
-		this.namedMarkers.push({
-			lat,
-			lng: lon,
-			name,
-			isPrior: false,
-			marker
-		});
-	}
-	/** Add a "prior" named marker (green, decorated). Buffered if not shown. */
-	addPriorMarker(lat, lon, name) {
-		const marker = this.leafletMap ? this.createNamedMarker(lat, lon, name, true) : null;
-		this.namedMarkers.push({
-			lat,
-			lng: lon,
-			name,
-			isPrior: true,
-			marker
-		});
-	}
-	/** Bulk add prior markers. */
-	addPriorMarkers(markers) {
-		for (const m of markers) this.addPriorMarker(m.lat, m.lon, m.name);
-	}
-	/** Remove all prior markers; current markers are unaffected. */
-	clearPriorMarkers() {
-		this.namedMarkers = this.namedMarkers.filter((m) => {
-			if (m.isPrior) {
-				m.marker?.remove();
-				return false;
-			}
-			return true;
-		});
-	}
-	setZoomLevel(zoom) {
-		this.zoomLevel = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, zoom));
-		if (this.leafletMap) this.leafletMap.setZoom(this.zoomLevel);
-	}
-	getZoomLevel() {
-		return this.zoomLevel;
-	}
-	/** Increment zoom level by 1 (clamped at MAX_ZOOM). */
-	zoomIn() {
-		this.setZoomLevel(this.zoomLevel + 1);
-	}
-	/** Decrement zoom level by 1 (clamped at MIN_ZOOM). */
-	zoomOut() {
-		this.setZoomLevel(this.zoomLevel - 1);
-	}
-	getWorldSize() {
-		return this.worldSize;
-	}
-	getHeightOffset() {
-		return this.heightOffset;
-	}
-	getMapSizePx() {
-		return this.mapSizePx;
-	}
-	/** Expose the Leaflet map instance for testing and advanced usage. */
-	getLeafletMap() {
-		return this.leafletMap;
-	}
-	/**
-	* No-op — kept for backward compatibility with the frame-loop call
-	* in main.ts. The CSS3DObject is a child of the parent, so Three.js
-	* scene graph propagation handles positioning automatically.
-	*/
-	updatePosition() {}
-	dispose() {
-		this.hide();
-		this.destroyLeafletMap();
-		this.latestMapData = null;
-		this.trajectoryLayers = [];
-		this.namedMarkers = [];
-		this.cssObject = null;
-		log.info("Leaflet map overlay disposed");
-	}
-	createLeafletMap() {
-		if (this.leafletMap) return;
-		this.mapContainer = document.createElement("div");
-		this.mapContainer.style.width = `${this.mapSizePx}px`;
-		this.mapContainer.style.height = `${this.mapSizePx}px`;
-		this.mapContainer.style.background = "white";
-		this.mapContainer.style.position = "fixed";
-		this.mapContainer.style.left = "-9999px";
-		this.mapContainer.style.top = "-9999px";
-		this.mapContainer.style.pointerEvents = "none";
-		this.offscreenRoot.appendChild(this.mapContainer);
-		const pos = this.gpsPosition;
-		this.leafletMap = L.map(this.mapContainer, {
-			center: [pos.lat, pos.lon],
-			zoom: this.zoomLevel,
-			zoomControl: false,
-			attributionControl: false
-		});
-		this.tileLayer = L.tileLayer(this.tileServerUrl, { maxZoom: MAX_ZOOM });
-		this.tileLayer.on("tileerror", (e) => {
-			log.error("Failed to load map tile:", e.error);
-			this.onTileError?.(e.error);
-		});
-		this.tileLayer.addTo(this.leafletMap);
-	}
-	destroyLeafletMap() {
-		for (const layer of this.trajectoryLayers) layer.remove();
-		this.trajectoryLayers = [];
-		for (const m of this.namedMarkers) {
-			m.marker?.remove();
-			m.marker = null;
-		}
-		if (this.leafletMap) {
-			this.leafletMap.remove();
-			this.leafletMap = null;
-		}
-		if (this.mapContainer?.parentElement) this.mapContainer.parentElement.removeChild(this.mapContainer);
-		this.mapContainer = null;
-		this.tileLayer = null;
-	}
-	createCssObject() {
-		if (!this.mapContainer) return;
-		if (this.cssObject) {
-			this.mapParent.add(this.cssObject);
-			return;
-		}
-		this.mapContainer.style.position = "";
-		this.mapContainer.style.left = "";
-		this.mapContainer.style.top = "";
-		this.cssObject = new CSS3DObject(this.mapContainer);
-		const scale = this.worldSize / this.mapSizePx;
-		this.cssObject.scale.set(scale, scale, scale);
-		this.cssObject.position.set(0, this.heightOffset, -1);
-		this.cssObject.rotation.x = -Math.PI / 2;
-		this.mapParent.add(this.cssObject);
-	}
-	removeCssObject() {
-		if (this.cssObject) this.mapParent.remove(this.cssObject);
-	}
-	applyBufferedOverlays() {
-		if (!this.leafletMap) return;
-		this.drawTrajectory();
-		for (const m of this.namedMarkers) if (!m.marker) m.marker = this.createNamedMarker(m.lat, m.lng, m.name, m.isPrior);
-	}
-	/**
-	* Redraw the trajectory layers from {@link latestMapData} via the shared
-	* {@link drawMapData} routine, removing any layers from the previous draw.
-	*/
-	drawTrajectory() {
-		if (!this.leafletMap || !this.latestMapData) return;
-		for (const layer of this.trajectoryLayers) layer.remove();
-		this.trajectoryLayers = drawMapData(this.leafletMap, this.latestMapData, { showUserPosition: true }).layers;
-	}
-	createNamedMarker(lat, lon, name, isPrior) {
-		const color = isPrior ? VIS_COLORS.PRIOR_REF_POINT.css : VIS_COLORS.CURRENT_REF_POINT.css;
-		const opacity = isPrior ? "opacity:0.8;" : "";
-		const label = isPrior ? `📌 ${name} (prior)` : name;
-		const size = REF_POINT_MARKER_SIZE_PX;
-		const anchor = size / 2;
-		return L.marker([lat, lon], { icon: L.divIcon({
-			className: "",
-			html: `<div style="background:${color};width:${size}px;height:${size}px;border-radius:50%;border:3px solid white;box-shadow:0 0 4px rgba(0,0,0,0.7);${opacity}"></div>`,
-			iconSize: [size, size],
-			iconAnchor: [anchor, anchor]
-		}) }).bindPopup(label).addTo(this.leafletMap);
-	}
-};
-//#endregion
+import { a as DEFAULT_Z_OFFSET, i as DEFAULT_ZOOM, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, t as DEFAULT_HEIGHT_OFFSET } from "../leaflet-map-overlay-CBWPvaX9.js";
 export { DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, LeafletMapOverlay };

package/dist/visualization/lerp-utils.d.ts

@@ -1,2 +1,2 @@
-import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-BLmHhkVe.js";
-export { DEFAULT_LERP_RATE, clampedAlpha };
+import { n as clampedAlpha, r as lerpAngleDeg, t as DEFAULT_LERP_RATE } from "../lerp-utils-Qs8OhumS.js";
+export { DEFAULT_LERP_RATE, clampedAlpha, lerpAngleDeg };

package/dist/visualization/lerp-utils.js

@@ -11,12 +11,36 @@ const DEFAULT_LERP_RATE = 8;
 /**
 * Compute a frame-rate-independent lerp/slerp factor clamped to [0, 1].
 *
+* Both bounds are clamped: the upper bound caps an overlong frame at a full
+* (instant) step, and the lower bound rejects a negative `dt` (system clock
+* adjustment, a frame loop whose timestamp runs backward, or a paused-then-
+* resumed tab). Without the lower clamp a negative `dt` would yield a negative
+* alpha and the angle/quaternion lerp would extrapolate BACKWARD, away from the
+* target — a visible heading/alignment jump.
+*
 * @param lerpRate Speed multiplier (higher = faster convergence).
 * @param dt       Delta time in seconds since last frame.
-* @returns The interpolation alpha, guaranteed ≤ 1.0.
+* @returns The interpolation alpha, guaranteed within [0, 1].
 */
 function clampedAlpha(lerpRate, dt) {
-	return Math.min(lerpRate * dt, 1);
+	return Math.min(Math.max(lerpRate * dt, 0), 1);
+}
+/**
+* Interpolate between two angles (degrees) along the SHORTEST arc.
+*
+* Used by the heading-up minimap to smooth the map's yaw toward a ~1 Hz target
+* heading every frame without spinning the long way across the 0°/360° seam
+* (e.g. 350° → 10° goes +20° through 0°, not −340° through 180°).
+*
+* @param current Current angle in degrees (any range; normalized internally).
+* @param target  Target angle in degrees (any range).
+* @param alpha   Interpolation factor — 0 returns `current`, 1 returns `target`.
+*                Values outside [0, 1] extrapolate; callers should clamp (see
+*                {@link clampedAlpha}).
+* @returns The interpolated angle normalized to `[0, 360)`.
+*/
+function lerpAngleDeg(current, target, alpha) {
+	return ((current + (((target - current) % 360 + 540) % 360 - 180) * alpha) % 360 + 360) % 360;
 }
 //#endregion
-export { DEFAULT_LERP_RATE, clampedAlpha };
+export { DEFAULT_LERP_RATE, clampedAlpha, lerpAngleDeg };

package/dist/visualization/map-data.d.ts

@@ -1,2 +1,2 @@
-import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-B4oEehUh.js";
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-CUnTzRIC.js";
 export { MapData, MapDataInput, buildMapData };

package/dist/visualization/map-data.js

@@ -1,33 +1,2 @@
-import { computeFusedPath } from "../utils/fused-path.js";
-//#region ../src/visualization/map-data.ts
-/**
-* Build a {@link MapData} snapshot from store-derived inputs.
-*
-* Pure and free of Leaflet/Three dependencies. The fused path is always
-* derived via {@link computeFusedPath} (D2); when the matrix or zero reference
-* is missing it is an empty array.
-*
-* @param input - Optional trajectory slices (see {@link MapDataInput}).
-* @returns A fully-resolved {@link MapData} with all arrays defensively copied.
-*/
-function buildMapData(input) {
-	const rawGpsPath = input.rawGpsPath ? [...input.rawGpsPath] : [];
-	const alignmentSnapshots = input.alignmentSnapshots ? [...input.alignmentSnapshots] : [];
-	const fusedPath = computeFusedPath({
-		odometryPositions: input.odometryPositions ?? [],
-		alignmentMatrix: input.alignmentMatrix ?? null,
-		zeroRef: input.zeroRef ?? null
-	});
-	const lastRaw = rawGpsPath[rawGpsPath.length - 1];
-	return {
-		userPosition: input.userPosition !== void 0 ? input.userPosition : lastRaw ? {
-			lat: lastRaw.lat,
-			lng: lastRaw.lng
-		} : null,
-		rawGpsPath,
-		fusedPath,
-		alignmentSnapshots
-	};
-}
-//#endregion
+import { t as buildMapData } from "../map-data-1tF5gcYV.js";
 export { buildMapData };

package/dist/visualization/map-overlay-draw.d.ts

@@ -1,2 +1,2 @@
-import { a as MAP_PATH_POLYLINE_OPACITY, c as USER_POSITION_COLOR, i as FUSED_PATH_COLOR, l as drawMapData, n as DrawMapDataOptions, o as MAP_PATH_POLYLINE_WEIGHT, r as DrawnMapData, s as RAW_GPS_COLOR, t as ALIGNMENT_SNAPSHOT_COLOR } from "../map-overlay-draw-ymz1s7fG.js";
+import { a as MAP_PATH_POLYLINE_OPACITY, c as USER_POSITION_COLOR, i as FUSED_PATH_COLOR, l as drawMapData, n as DrawMapDataOptions, o as MAP_PATH_POLYLINE_WEIGHT, r as DrawnMapData, s as RAW_GPS_COLOR, t as ALIGNMENT_SNAPSHOT_COLOR } from "../map-overlay-draw-6WJeq0Kg.js";
 export { ALIGNMENT_SNAPSHOT_COLOR, DrawMapDataOptions, DrawnMapData, FUSED_PATH_COLOR, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, RAW_GPS_COLOR, USER_POSITION_COLOR, drawMapData };

package/dist/visualization/map-overlay-draw.js

@@ -18,7 +18,8 @@ import L from "leaflet";
 *      polyline stays on top), then the raw GPS polyline;
 *   2. the fused (SLAM+GPS) polyline;
 *   3. the alignment-snapshot polyline;
-*   4. (optional) a user-position marker.
+*   4. (optional) a user-position marker — a dot plus, when `userHeadingDeg`
+*      is set, a thin view-direction line rotated to that true-north bearing.
 *
 * SCOPE: this module draws only the genuinely-shared SLAM/GPS trajectory
 * layers. Reference-point markers are a RECORDER concept and are drawn by the
@@ -45,6 +46,27 @@ const MAP_PATH_POLYLINE_WEIGHT = 3;
 /** Polyline opacity — matches the recorder's `PATH_POLYLINE_OPACITY`. */
 const MAP_PATH_POLYLINE_OPACITY = .8;
 /**
+* Length (px) of the user view-direction line. A FIXED pixel length (not a
+* metric distance): the line is a direction-only indicator drawn inside the
+* user-position divIcon, so it stays the same size at every zoom level.
+* Module-private — internal styling detail, not part of the public surface.
+*/
+const USER_HEADING_LINE_LENGTH_PX = 28;
+/**
+* Build the inner HTML for the user-position divIcon: a centered dot, plus —
+* when `headingDeg` is a finite bearing — a thin line rotated to that absolute
+* (true-north) heading. The line lives in a zero-size wrapper centered on the
+* dot and rotated by CSS, so North (0°) points up and the line keeps a fixed
+* pixel length regardless of map zoom. A null/undefined/non-finite heading
+* yields the dot alone (Finding 2: fallback when the camera is near-vertical or
+* before the first alignment solve).
+*/
+function buildUserMarkerHtml(headingDeg) {
+	const dot = `<div style="position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);background:${USER_POSITION_COLOR};width:14px;height:14px;border-radius:50%;border:2px solid white;"></div>`;
+	if (typeof headingDeg !== "number" || !Number.isFinite(headingDeg)) return dot;
+	return `${`<div style="position:absolute;left:50%;top:50%;transform:rotate(${headingDeg}deg);"><div class="map-overlay-user-heading" style="position:absolute;left:-1px;bottom:0;width:2px;height:${USER_HEADING_LINE_LENGTH_PX}px;background:${USER_POSITION_COLOR};"></div></div>`}${dot}`;
+}
+/**
 * Draw a {@link MapData} snapshot onto an existing Leaflet map.
 *
 * @param map - Target map (already created with a tile layer by the caller).
@@ -90,7 +112,7 @@ function drawMapData(map, data, options = {}) {
 	if (options.showUserPosition && data.userPosition) {
 		const icon = L.divIcon({
 			className: "map-overlay-user-position",
-			html: `<div style="background:${USER_POSITION_COLOR};width:14px;height:14px;border-radius:50%;border:2px solid white;"></div>`,
+			html: buildUserMarkerHtml(data.userHeadingDeg),
 			iconSize: [18, 18],
 			iconAnchor: [9, 9]
 		});

package/dist/visualization/map-overlay.d.ts

@@ -1,2 +1,2 @@
-import { a as MapOverlayOptions, c as tileXYToLatLon, i as MapOverlay, n as DEFAULT_MAP_SIZE, o as TextureLoaderInterface, r as DEFAULT_ZOOM, s as latLonToTileXY, t as DEFAULT_HEIGHT_OFFSET } from "../map-overlay-Dh2B97MP.js";
+import { a as MapOverlayOptions, c as tileXYToLatLon, i as MapOverlay, n as DEFAULT_MAP_SIZE, o as TextureLoaderInterface, r as DEFAULT_ZOOM, s as latLonToTileXY, t as DEFAULT_HEIGHT_OFFSET } from "../map-overlay-BCQgvIgU.js";
 export { DEFAULT_HEIGHT_OFFSET, DEFAULT_MAP_SIZE, DEFAULT_ZOOM, MapOverlay, MapOverlayOptions, TextureLoaderInterface, latLonToTileXY, tileXYToLatLon };

package/dist/visualization/occluder-mesh-driver.d.ts

@@ -0,0 +1,130 @@
+import { t as GridCell } from "../bresenham3d-DGc4nIb-.js";
+import { n as MeshMode } from "../occupancy-mesher-C2ecWhNp.js";
+import { MeshWorkerRequest, MeshWorkerResponse } from "../ar/occlusion-mesh-worker.js";
+import { Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/visualization/occluder-mesh-driver.d.ts
+/** Called with the meshed geometry (typed arrays) when a job completes. */
+type OnMesh = (positions: Float32Array, indices: Uint32Array) => void;
+/**
+ * Timing/size stats for one completed mesh job — the freshness instrumentation
+ * for the Phase-2 gate (see the plan's §"Next step"): `durationMs` is the
+ * wall-clock time from posting the job (including packing already done by then)
+ * to receiving its geometry, i.e. the occluder's current refresh latency.
+ * Failed jobs report nothing (they surface via
+ * {@link OccluderMeshDriverOptions.onError}).
+ */
+interface OccluderMeshStats {
+  /** Wall-clock ms from post to delivered geometry (inline time on the sync path). */
+  readonly durationMs: number;
+  /** Number of occupied cells the mesh was built from. */
+  readonly cellCount: number;
+  readonly mode: MeshMode;
+  /** True when meshed inline on the main thread (fallback), false when off-thread. */
+  readonly synchronous: boolean;
+}
+/**
+ * The minimal `Worker`-like surface the driver needs. A consumer adapts a real
+ * `Worker`: forwards `worker.onmessage` → `poster.onmessage` and
+ * `worker.onerror` / `worker.onmessageerror` → `poster.onerror` (so the driver
+ * can recover from a worker that never replies).
+ */
+interface MeshWorkerPoster {
+  postMessage(message: MeshWorkerRequest, transfer: ArrayBufferLike[]): void;
+  onmessage: ((event: {
+    data: MeshWorkerResponse;
+  }) => void) | null;
+  /** Fired when the worker errors (uncaught throw or module load failure). */
+  onerror: ((error?: unknown) => void) | null;
+}
+/** Optional driver callbacks (logging + worker-teardown seams). */
+interface OccluderMeshDriverOptions {
+  /**
+   * Called once when the driver gives up on the worker and switches to
+   * synchronous meshing (the worker errored before ever producing a mesh —
+   * almost always a module that failed to load). The consumer should terminate
+   * the now-dead worker.
+   */
+  onWorkerUnusable?: () => void;
+  /**
+   * Called with any error that aborts a job — a worker error event, or a throw
+   * from synchronous meshing — so the consumer can log it. Optional; if absent
+   * the error is swallowed (the frame is dropped, the driver stays healthy).
+   */
+  onError?: (error: unknown) => void;
+  /**
+   * Called with {@link OccluderMeshStats} each time a job completes (fires just
+   * before the job's geometry callback). Optional logging seam so the consumer
+   * can surface mesh duration + input size per refresh.
+   */
+  onMeshStats?: (stats: OccluderMeshStats) => void;
+  /**
+   * Injectable monotonic clock in ms for {@link OccluderMeshStats.durationMs}
+   * (tests); defaults to `performance.now()`.
+   */
+  now?: () => number;
+}
+declare class OccluderMeshDriver {
+  private readonly poster;
+  private readonly onWorkerUnusable?;
+  private readonly onError?;
+  private readonly onMeshStats?;
+  private readonly now;
+  private nextId;
+  private inFlightId;
+  private inFlightCallback;
+  /** Timing/size context of the in-flight job; cleared on completion/failure. */
+  private inFlightStats;
+  private pending;
+  private disposed;
+  /** True ⇒ mesh inline (no worker, or the worker was declared unusable). */
+  private syncMode;
+  /** Set once the worker returns a mesh — distinguishes a transient error from a load failure. */
+  private hasSucceeded;
+  /**
+   * @param poster a worker adapter, or `null` for synchronous main-thread meshing.
+   * @param options optional {@link OccluderMeshDriverOptions.onWorkerUnusable} /
+   *   {@link OccluderMeshDriverOptions.onError} callbacks.
+   */
+  constructor(poster: MeshWorkerPoster | null, options?: OccluderMeshDriverOptions);
+  /** True while a mesh job is being computed (worker path only). */
+  get busy(): boolean;
+  /**
+   * 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: readonly GridCell[] | Int32Array, cellSizeM: number, mode: MeshMode, getCellPoint: ((cell: GridCell) => Vector3 | null) | undefined, onMesh: OnMesh): void;
+  private post;
+  private handleResponse;
+  /**
+   * 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.
+   */
+  private handleWorkerError;
+  /**
+   * 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.
+   */
+  private failInFlight;
+  /** Stop delivering results (detaches the worker handlers; drops any pending). */
+  dispose(): void;
+}
+//#endregion
+export { MeshWorkerPoster, OccluderMeshDriver, OccluderMeshDriverOptions, OccluderMeshStats, OnMesh };