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

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 };

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-b28lRJ6S.js";
+export { OCCLUDER_DEPTH_SHADE, OcclusionMesh, OcclusionMeshOptions, buildOccluderDepthShadeSnippet, occluderDepthFade, occluderFresnelRim };