gps-plus-slam-app-framework 1.0.7 → 1.2.0

package/dist/ar/xr-camera-texture.d.ts

@@ -1,2 +1,2 @@
-import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-BU5YvKAM.js";
+import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-DBwCaKTd.js";
 export { CameraTextureResult, RendererLike, XRCameraLike, acquireCameraTexture };

package/dist/ar/xr-error-handler.d.ts

@@ -1,2 +1,2 @@
-import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-CDY5QxGb.js";
+import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-C0AQRmxs.js";
 export { XR_ERROR_MESSAGES, XR_ERROR_MESSAGE_UNKNOWN, getXrErrorMessage };

package/dist/ar/xr-frame-loop.d.ts

@@ -0,0 +1,2 @@
+import { a as runXrFrameUpdates, i as registerXrFrameUpdate, n as XrFrameUpdate, r as clearXrFrameUpdates, t as XrFrameContext } from "../xr-frame-loop-BtYytZJg.js";
+export { XrFrameContext, XrFrameUpdate, clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

package/dist/ar/xr-frame-loop.js

@@ -0,0 +1,69 @@
+import { createLogger } from "../utils/logger.js";
+//#region ../src/ar/xr-frame-loop.ts
+/**
+* Per-frame **XR-access** callback registry — the safe seam that lets app
+* code run standard WebXR work (hit-test, light estimation, depth, the WebXR
+* Anchors API, …) without the framework wrapping each capability.
+*
+* The framework owns the single `renderer.setAnimationLoop(onXRFrame)` hook,
+* and the live `XRFrame` never leaves `onXRFrame`. The plain `FrameUpdate`
+* registry (`frame-loop.ts`) only passes `(dt, elapsed)`, which is enough for
+* pose-free ticks but cannot drive hit-test. This registry additionally hands
+* the callback the live `frame`, `referenceSpace`, and `session`.
+*
+* SAFETY CONTRACT (non-negotiable): `frame` / `referenceSpace` / `session` are
+* valid **only synchronously inside the callback**. The `XRFrame` is
+* use-after-frame-unsafe — storing it and reading it on a later tick throws or
+* crashes. Passing them as arguments (never a stashable `getXrFrame()` getter)
+* makes correct use the easy path and stashing the awkward one. Do NOT retain
+* `ctx` or its fields beyond the callback's synchronous execution.
+*
+* See `2026-06-03-threejs-arbutton-minimal-ar-example-user-feedback.md`
+* §6.2/§6.3 (option H-A2) for the design rationale.
+*/
+const log = createLogger("XrFrameLoop");
+const updates = /* @__PURE__ */ new Set();
+/**
+* Register a per-frame XR-access callback. Returns an unregister function.
+*
+* Registration is idempotent — registering the same `fn` twice is a no-op
+* (it remains a single entry in the underlying `Set`).
+*/
+function registerXrFrameUpdate(fn) {
+	updates.add(fn);
+	return () => {
+		updates.delete(fn);
+	};
+}
+/**
+* Invoke all registered XR-access callbacks. Called by the WebXR session's
+* `onXRFrame` once per frame, only when a live `frame` / `referenceSpace` /
+* `session` are all available.
+*
+* The set is snapshotted before iterating so that
+* `registerXrFrameUpdate` / unregister calls made by a handler during the
+* same frame are deferred to the next tick — mirroring `runFrameUpdates`.
+*
+* Each callback is invoked in its own `try/catch`: this registry is the public
+* app seam, so a bug in one app-registered callback (which throws every frame)
+* must not abort the remaining callbacks nor propagate up through `onXRFrame`
+* and kill the scene render for the whole session. Failures are logged and the
+* loop continues — mirroring `runFrameUpdates`.
+*/
+function runXrFrameUpdates(ctx) {
+	const snapshot = Array.from(updates);
+	for (const fn of snapshot) try {
+		fn(ctx);
+	} catch (error) {
+		log.error("A registered XrFrameUpdate threw; continuing the loop", error);
+	}
+}
+/**
+* Clear all registrations. Called from `resetWebXRState()` so a fresh
+* session starts with an empty registry.
+*/
+function clearXrFrameUpdates() {
+	updates.clear();
+}
+//#endregion
+export { clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

package/dist/{ar-types-Ck8LEq8k.d.ts → ar-types-Dan1MVTi.d.ts}

@@ -1,4 +1,4 @@
-import { Quaternion, Vector3 } from "gps-plus-slam-js";
+import { Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/types/ar-types.d.ts
 /**
@@ -43,6 +43,11 @@ interface ARPose {
   readonly position: WebXRVec3;
   readonly orientation: WebXRQuaternion;
 }
+/**
+ * An sRGB color triple, 0–255 integers per channel. Kept as plain ints so
+ * persisted JSON stays compact (~3 bytes/point in practice).
+ */
+type RgbTuple = readonly [number, number, number];
 /**
  * A single depth point sample from WebXR Depth API.
  * Used for 3D reconstruction and validating AR tracking accuracy.
@@ -54,6 +59,14 @@ interface DepthPoint {
   readonly screenY: number;
   /** Depth value in meters */
   readonly depthM: number;
+  /**
+   * Camera color at (screenX, screenY), sampled from the same XR frame as
+   * the depth read (occupancy-grid port plan Iter 8). Optional + additive:
+   * recordings made before 2026-06 (or with the RGB recording option off)
+   * carry no color; consumers must fall back (e.g. height-based cube
+   * coloring).
+   */
+  readonly rgb?: RgbTuple;
 }
 /**
  * A complete depth sample with camera pose and grid of depth points.
@@ -66,8 +79,10 @@ interface DepthSample {
   readonly timestamp: number;
   /**
    * Camera position in **raw WebXR** convention [x=East, y=Up, z=South].
-   * NOT in NUE — the recordDepthSample reducer is a no-op, so no
-   * webxrToNUE conversion is applied. Consumers must convert if needed.
+   * NOT in NUE — the recordDepthSample reducer is conversion-free (it only
+   * stores the latest sample for subscribers), so no webxrToNUE conversion
+   * is ever applied. Consumers needing NUE must convert themselves; the
+   * occupancy-grid pipeline works directly in this raw frame.
    */
   readonly cameraPos: Vector3;
   /**
@@ -76,7 +91,15 @@ interface DepthSample {
    */
   readonly cameraRot: Quaternion;
   /** Grid of depth points */
-  readonly points: DepthPoint[];
+  readonly points: readonly DepthPoint[];
+  /**
+   * Projection matrix of the capturing XRView (16 floats, column-major,
+   * serializable tuple — not a THREE.Matrix4). Camera intrinsics needed to
+   * unproject (screenX, screenY, depthM) back into a 3D AR-space point.
+   * Optional: recordings made before 2026-06 do not carry it; consumers
+   * must skip unprojection for such samples.
+   */
+  readonly projectionMatrix?: Matrix4;
 }
 //#endregion
-export { WebXRQuaternion as a, DepthSample as i, ArPoseTuples as n, WebXRVec3 as o, DepthPoint as r, ARPose as t };
+export { RgbTuple as a, DepthSample as i, ArPoseTuples as n, WebXRQuaternion as o, DepthPoint as r, WebXRVec3 as s, ARPose as t };

package/dist/ar-world-group-alignment-ColHB_5A.d.ts

@@ -0,0 +1,43 @@
+import { t as SubscribableStore } from "./subscribe-to-selector-CP3BKSbF.js";
+import * as THREE from "three";
+
+//#region ../src/visualization/ar-world-group-alignment.d.ts
+interface ArWorldGroupAlignmentOptions {
+  /** The store whose alignment selector drives the lerper. */
+  readonly store: SubscribableStore;
+  /** The AR world group whose `.matrix` is lerped toward each alignment. */
+  readonly arWorldGroup: THREE.Object3D;
+  /**
+   * Lerp speed multiplier forwarded to {@link createAlignmentLerper}
+   * (default matches the lerper's own `DEFAULT_LERP_RATE`).
+   */
+  readonly lerpRate?: number;
+}
+interface ArWorldGroupAlignmentHandle {
+  /** Stop the subscription and the per-frame update. */
+  dispose(): void;
+}
+/**
+ * Begin applying the store's (lerped) alignment to `arWorldGroup`. Returns a
+ * handle whose `dispose()` removes both the store subscription and the
+ * per-frame update.
+ *
+ * Disposal is tied to the AR session lifecycle: the binding registers itself
+ * with the session-disposer registry that `resetWebXRState()` flushes on
+ * teardown, so a caller can `enableArWorldGroupAlignment(...)` once and never
+ * hold the handle — the binding cannot outlive the session (which is what two
+ * apps independently leaked: the store subscription survives a teardown because
+ * `clearFrameUpdates` only drops the per-frame tick). Because `initAR()` throws
+ * while a prior session is live, every restart passes through that flush. The
+ * handle is still returned for callers that want to stop alignment mid-session,
+ * and is idempotent + self-deregistering so a manual `dispose()` and the
+ * teardown flush never double-run. See
+ * gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-08-arworldgroup-alignment-session-scoped-disposal.md.
+ *
+ * Double-drive is still the caller's concern: the recorder owns its own lerper
+ * and must NOT also call this (it would double-lerp the same group). It does not
+ * call this helper, so flushing the registry on teardown never affects it.
+ */
+declare function enableArWorldGroupAlignment(options: ArWorldGroupAlignmentOptions): ArWorldGroupAlignmentHandle;
+//#endregion
+export { ArWorldGroupAlignmentOptions as n, enableArWorldGroupAlignment as r, ArWorldGroupAlignmentHandle as t };

package/dist/bresenham3d-CFfd7n6B.d.ts

@@ -0,0 +1,59 @@
+//#region ../src/ar/bresenham3d.d.ts
+/**
+ * 3D Bresenham Line Tracer
+ *
+ * Direct port of the Unity occupancy-grid helper
+ * (`PointCloudHelpers.BresenhamsLineAlgorithm`, after
+ * http://members.chello.at/~easyfilter/bresenham.html): walks integer grid
+ * cells from `start` to `end`, invoking a visitor per cell. Used by the
+ * occupancy grid for free-space carving and raycasting.
+ *
+ * Semantics preserved from the Unity original:
+ * - The visitor runs on the start cell BEFORE the stop-distance check.
+ * - `stopDistance` is measured in dominant-axis (Chebyshev) steps from the
+ *   end cell: tracing stops once the remaining distance reaches it, so the
+ *   end cell and its `stopDistance`-neighborhood are not visited (except
+ *   the unconditional start visit).
+ * - Error offsets use integer division (`floor(dm / 2)`).
+ *
+ * @see bresenham3d.ts.md for detailed documentation
+ */
+/** Integer grid cell coordinate triple. */
+type GridCell = readonly [number, number, number];
+/**
+ * Main-thread safety cap: the maximum dominant-axis (Chebyshev) span a single
+ * trace may cover. The trace runs synchronously, one iteration per
+ * dominant-axis step, so an unbounded span freezes the UI. Finite-but-absurd
+ * coordinates (a tracking glitch, a corrupt projectionMatrix unprojecting to a
+ * huge world point) quantize to safe integers and pass the integer check, so
+ * this is the only thing standing between such input and a multi-second
+ * (potentially multi-billion-iteration) freeze.
+ *
+ * Chosen generously — at the grid's 0.15 m cells this is ~150 km, far beyond
+ * any real AR scene, so it never trips on legitimate carving or raycasting.
+ * It is a circuit breaker against programmer/data error, not a ray-length
+ * policy: exceeding it throws (loud — surfaces the upstream bug) rather than
+ * silently truncating the trace.
+ */
+declare const MAX_TRACE_STEPS = 1000000;
+/**
+ * Trace the line from `start` to `end`, calling `visitCell` per cell.
+ *
+ * @param visitCell - return `false` to stop the trace early.
+ * @param stopDistance - dominant-axis steps before `end` at which to stop
+ *   (default 0 = trace all the way to `end`).
+ * @throws TypeError when a coordinate is not a safe integer (cells must be
+ *   quantized before tracing — programmer error, not a data error).
+ * @throws RangeError when `stopDistance` is not a non-negative safe integer.
+ *   The loop terminates on a counter (`i--`) that decrements unconditionally,
+ *   so a negative or fractional value still terminates (it merely traces past
+ *   `end`); but `NaN`/`-Infinity` never satisfy `i <= stopDistance` and would
+ *   spin forever. Rejecting up front both prevents that freeze and enforces
+ *   the "dominant-axis steps before end" contract.
+ * @throws RangeError when the dominant-axis span exceeds {@link MAX_TRACE_STEPS}
+ *   (circuit breaker against a synchronous main-thread freeze from
+ *   finite-but-absurd coordinates).
+ */
+declare function bresenham3d(start: GridCell, end: GridCell, visitCell: (cell: GridCell) => boolean, stopDistance?: number): void;
+//#endregion
+export { MAX_TRACE_STEPS as n, bresenham3d as r, GridCell as t };

package/dist/{camera-blit-capture-C1V9I1Z6.d.ts → camera-blit-capture-D5_mNhla.d.ts}

@@ -63,6 +63,26 @@ declare class CameraBlitCapture {
    * @returns JPEG Blob, or null if capture fails
    */
   captureToBlob(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture, quality: number): Promise<Blob | null>;
+  /**
+   * Run the blit + readback (steps A+B of {@link captureToBlob}) and return
+   * the raw RGBA pixel buffer without JPEG encoding — the cheap path for
+   * per-point color sampling (occupancy-grid port plan Iter 8).
+   *
+   * IMPORTANT: Must be called within the XR animation frame callback, while
+   * the camera texture is valid. The returned `pixels` is the INTERNAL
+   * buffer — valid only until the next capture or `resizeIfNeeded`; consume
+   * it synchronously (e.g. via `createRgbLookup`) or copy it.
+   *
+   * Note: the buffer is in WebGL readback order (bottom-row-first / RGBA);
+   * `createRgbLookup` handles the y-flip.
+   *
+   * @returns the buffer with its dimensions, or null on failure/dispose.
+   */
+  captureToPixels(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture): {
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+  } | null;
   /**
    * Check if a pixel buffer is entirely black (all zeros).
    * Uses sampling for performance (checks BLACK_CHECK_SAMPLE_COUNT evenly-spaced pixels).

package/dist/capability-checker-CQXJHxXg.d.ts

@@ -0,0 +1,43 @@
+//#region ../src/ar/capability-checker.d.ts
+/**
+ * Pure capability-gating helpers, promoted from the AnchorStarter app so the
+ * minimal AR example and AnchorStarter share the *decision* and *message*
+ * without sharing app-specific copy.
+ *
+ * The async feature probing (`isWebXRSupported()` / geolocation availability)
+ * stays in each app's `main.ts`; only the browser-free decision and the
+ * user-facing message live here so they can be unit-tested without a browser.
+ *
+ * See `2026-06-03-threejs-arbutton-minimal-ar-example-user-feedback.md` §6.4.
+ */
+/** The two capabilities every GPS+AR demo requires to run. */
+interface CapabilitySupport {
+  /** Browser supports a WebXR `immersive-ar` session. */
+  readonly webxr: boolean;
+  /** Geolocation API is available. */
+  readonly geolocation: boolean;
+}
+/** Options that let an app flavour the otherwise-neutral gating message. */
+interface CapabilityMessageOptions {
+  /**
+   * App-specific "what this demo lets you do" phrase, appended as
+   * `…outdoors, to try ${contextLabel}.`. Omit for a neutral message that
+   * ends at `…outdoors.`. Example: `'the persistent-anchor flow'`.
+   */
+  readonly contextLabel?: string;
+}
+/** True only when both AR and GPS are available — the demo can run. */
+declare function isFullySupported(support: CapabilitySupport): boolean;
+/**
+ * Build the capability-gated message shown when the demo cannot run. Names
+ * exactly which capabilities are missing so the user understands *why*, and
+ * always points them at the supported environment (an AR phone, outdoors).
+ * Returns `null` when everything is supported (no message needed).
+ *
+ * The trailing "to try …" clause is app-specific and supplied via
+ * `options.contextLabel`; without it the message ends neutrally at
+ * "…outdoors.".
+ */
+declare function capabilityMessage(support: CapabilitySupport, options?: CapabilityMessageOptions): string | null;
+//#endregion
+export { isFullySupported as i, CapabilitySupport as n, capabilityMessage as r, CapabilityMessageOptions as t };

package/dist/chromium-camera-access-workaround-Jqbn0apH.d.ts

@@ -0,0 +1,137 @@
+//#region ../src/ar/chromium-camera-access-workaround.d.ts
+/**
+ * Chromium WebXR camera-access tab-crash workaround.
+ *
+ * Background:
+ * Requesting `camera-access` as an optional WebXR feature on Android Chrome
+ * 147+ causes a fatal renderer-process crash (`CrRendererMain`) 1–2 seconds
+ * after entering AR. The crash reproduces in the upstream three.js
+ * `webxr_ar_hittest.html` example with `optionalFeatures: ['camera-access']`
+ * added — i.e. it is not specific to this app's session setup. See:
+ *
+ *   - GpsPlusSlamJs_Docs/docs/2026-04-22-camera-access-reproducer-plan.md
+ *   - GpsPlusSlamJs_Docs/docs/2026-06-04-camera-access-crash-regression-chrome-148.md
+ *   - https://github.com/mrdoob/three.js/issues/33404
+ *   - https://issues.chromium.org/issues/507508099 (root-cause, marked Fixed)
+ *
+ * There is NOT a single crash here — the Chromium tracker notes the crash on
+ * Chrome 147 is different from the crash on 148+, and the simple workaround
+ * below only helped on a subset of versions. The empirically-verified
+ * (on-device) timeline is:
+ *
+ *   - 147 : deleting `createProjectionLayer` / `layers` forces three.js onto
+ *       `XRWebGLLayer` and sidesteps the crash (deletes-only is sufficient).
+ *   - 148.0.7778.12 .. 149.0.7821 : the delete-only trick is NOT sufficient on
+ *       its own. An ADDITIONAL patch is needed: persist the `baseLayer`
+ *       reference across `XRSession.prototype.updateRenderState` so three.js's
+ *       later `depthNear`/`depthFar` update does not drop the active
+ *       `glBaseLayer`. (Confirmed on-device on `148.0.7778.215`: BOTH the
+ *       deletes and the baseLayer patch are required for the page not to
+ *       crash. Earlier 148 builds (`< .7778.12`) are below the window per the
+ *       tracker, which reported delete-only worked there.)
+ *   - > 149.0.7821 (incl. Chrome 150) : the delete-only path is STILL required
+ *       (confirmed on-device: Chrome 150 only stops crashing when the deletes
+ *       are applied), but the extra baseLayer-persistence patch is NOT needed.
+ *       The earlier assumption that Chromium fully fixed this on patched
+ *       builds did not hold on real devices, so we no longer skip the
+ *       workaround on "patched" Chrome.
+ *
+ * Resulting policy (see {@link applyChromiumProjectionLayerWorkaround}):
+ *   - ALWAYS apply the deletes (every Chrome build, and unknown/non-Chromium
+ *     environments — restoring the original always-on behavior).
+ *   - Apply the baseLayer-persistence patch ONLY when a detected Chrome build
+ *     falls inside the affected window
+ *     [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}].
+ *
+ * Caveats:
+ * - This is a Chromium-specific hack and the upstream comment explicitly
+ *   warns it "might break webxr on other devices" — keep it opt-in.
+ * - Must run BEFORE any WebXR session setup. Three.js reads these prototype
+ *   members lazily when the first session starts, so calling this at app
+ *   bootstrap (before `initAR()`) is sufficient.
+ * - Idempotent: safe to call repeatedly. Safe on environments where the
+ *   prototypes do not exist (e.g. desktop browsers, jsdom).
+ */
+/**
+ * Parsed Chrome version as `[major, minor, build, patch]`.
+ */
+type ChromeVersion = [number, number, number, number];
+/**
+ * Inclusive lower bound of the Chrome window that additionally needs the
+ * `baseLayer`-persistence patch (on top of the deletes).
+ *
+ * Set to `148.0.7778.12`, the issue tracker's figure for when the delete-only
+ * trick stopped being sufficient. On-device confirmation: `148.0.7778.215`
+ * (well inside this window) crashes with deletes-only and needs BOTH patches.
+ * Earlier 148 builds (`< .7778.12`) and all of Chrome 147 stay below this
+ * bound (deletes-only) per the documented timeline — we have no on-device
+ * evidence that they need the baseLayer patch, so we do not apply it there.
+ */
+declare const BASELAYER_WINDOW_MIN: ChromeVersion;
+/**
+ * Inclusive upper bound of the Chrome window that additionally needs the
+ * `baseLayer`-persistence patch. The crash is fixed after `149.0.7819.0` and
+ * the camera image is correctly populated after `149.0.7821.0`; above this
+ * build the extra patch is no longer required (the deletes still are — see
+ * the module header and the on-device matrix for Chrome 150).
+ *
+ * @see https://github.com/mrdoob/three.js/issues/33404
+ */
+declare const BASELAYER_WINDOW_MAX: ChromeVersion;
+/**
+ * Result of {@link applyChromiumProjectionLayerWorkaround}.
+ * Useful for logging and tests.
+ */
+interface ChromiumProjectionLayerWorkaroundResult {
+  /** True if `XRWebGLBinding.prototype.createProjectionLayer` was deleted on this call. */
+  deletedCreateProjectionLayer: boolean;
+  /** True if `XRRenderState.prototype.layers` was deleted on this call. */
+  deletedRenderStateLayers: boolean;
+  /** True if `XRSession.prototype.updateRenderState` was wrapped on this call. */
+  patchedUpdateRenderState: boolean;
+  /** The detected Chrome version (`"major.minor.build.patch"`), or null. */
+  detectedChromeVersion: string | null;
+}
+/**
+ * Parse a Chrome/Chromium version from a user-agent string.
+ *
+ * Matches the `Chrome/<major>.<minor>.<build>.<patch>` token (and the iOS
+ * `CriOS/...` variant). Returns null for non-Chromium user agents.
+ */
+declare function parseChromeVersion(userAgent: string): ChromeVersion | null;
+/**
+ * True when the detected Chrome build falls inside the affected window
+ * [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}] (inclusive)
+ * and therefore additionally needs the `baseLayer`-persistence patch. Outside
+ * the window (including non-Chromium user agents) returns false — only the
+ * deletes are needed there.
+ */
+declare function needsBaseLayerPersistence(userAgent: string): boolean;
+/**
+ * Apply the Chromium camera-access tab-crash workaround.
+ *
+ * Policy (derived from on-device testing — see the module header):
+ *
+ *  - ALWAYS removes `XRWebGLBinding.prototype.createProjectionLayer`
+ *    (three.js r184) and `XRRenderState.prototype.layers` (three.js r158) so
+ *    three.js falls back to `XRWebGLLayer`. This is required on every affected
+ *    Chrome build observed so far, including Chrome 150, and is also applied
+ *    on unknown/non-Chromium environments (restoring the original always-on
+ *    behavior).
+ *  - ADDITIONALLY persists the `baseLayer` across
+ *    `XRSession.prototype.updateRenderState`, but ONLY when a detected Chrome
+ *    build falls inside the affected window
+ *    [{@link BASELAYER_WINDOW_MIN} .. {@link BASELAYER_WINDOW_MAX}]. Outside
+ *    that window the extra patch is unnecessary (and is skipped on unknown
+ *    environments to avoid touching projection-layer devices like Quest).
+ *
+ * Call once during bootstrap, before any `requestSession()` call.
+ *
+ * @param options.userAgent override the detected user agent (for testing).
+ * @returns which prototype members were actually changed on this call.
+ */
+declare function applyChromiumProjectionLayerWorkaround(options?: {
+  userAgent?: string;
+}): ChromiumProjectionLayerWorkaroundResult;
+//#endregion
+export { applyChromiumProjectionLayerWorkaround as a, ChromiumProjectionLayerWorkaroundResult as i, BASELAYER_WINDOW_MIN as n, needsBaseLayerPersistence as o, ChromeVersion as r, parseChromeVersion as s, BASELAYER_WINDOW_MAX as t };

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-import { a as LibraryRootState, c as RootState, d as calcRelativeCoordsInMeters, f as createGpsSlamStore, g as webxrToNUE, h as validateLicenseKey, i as LatLongAlt, l as Vector3, m as odometryTrackingRestarted, n as GpsPoint, o as Matrix4, p as isIdentityMatrix4, r as LatLong, s as Quaternion, t as ArImageCapture, u as calcGpsCoords } from "../index-gzWJMVpo.js";
+import { a as LibraryRootState, c as RootState, d as calcRelativeCoordsInMeters, f as createGpsSlamStore, g as webxrToNUE, h as validateLicenseKey, i as LatLongAlt, l as Vector3, m as odometryTrackingRestarted, n as GpsPoint, o as Matrix4, p as isIdentityMatrix4, r as LatLong, s as Quaternion, t as ArImageCapture, u as calcGpsCoords } from "../index-CF05QV2m.js";
 export { ArImageCapture, GpsPoint, LatLong, LatLongAlt, LibraryRootState, Matrix4, Quaternion, RootState, Vector3, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };

package/dist/{create-slam-app-store-CNsZ3rcX.d.ts → create-slam-app-store-qNXQ-tq5.d.ts}

@@ -1,8 +1,8 @@
-import { t as ARPose } from "./ar-types-Ck8LEq8k.js";
-import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-utCNND8t.js";
-import { t as RecordingState } from "./recording-slice-d6OtCrza.js";
-import { n as SessionMetadata } from "./opfs-storage-DOPkzgeT.js";
-import { n as StorageBackend } from "./storage-backend-CT0Il_AB.js";
+import { t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-CdK8c-8P.js";
+import { t as RecordingState } from "./recording-slice-89O07ebs.js";
+import { n as SessionMetadata } from "./opfs-storage-DYm8WHq7.js";
+import { n as StorageBackend } from "./storage-backend-C9HLFtgz.js";
 import { GpsPoint, LatLong, Matrix4, RootState, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 import { Middleware, Reducer, ReducersMapObject, configureStore } from "@reduxjs/toolkit";

package/dist/depth-sampler-Bhanfwla.d.ts

@@ -0,0 +1,169 @@
+import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { Matrix4 } from "gps-plus-slam-js";
+
+//#region ../src/ar/depth-rgb-lookup.d.ts
+/**
+ * Sample the camera color at normalized view coordinates (0–1, y=0 top).
+ * Returns null for out-of-range or non-finite coordinates.
+ */
+type RgbLookup = (screenX: number, screenY: number) => RgbTuple | null;
+//#endregion
+//#region ../src/ar/depth-sampler.d.ts
+/**
+ * Configuration for depth sampling behavior.
+ */
+interface DepthSamplerConfig {
+  /** Interval between samples in milliseconds. Default: 1000ms */
+  intervalMs: number;
+  /**
+   * Number of points per dimension (gridSize x gridSize). Default: 16
+   * (256 pts at 1 Hz — dense enough to populate the AR-space occupancy
+   * grid for on-device verification, see the 2026-06-11 port plan §1).
+   */
+  gridSize: number;
+  /** Time in ms to wait before declaring depth unavailable. Default: 5000ms */
+  unavailabilityThresholdMs: number;
+  /**
+   * Whether to enrich each sampled point with the camera color at its view
+   * coordinates (occupancy-grid port plan Iter 8). Requires the
+   * `acquireRgbLookup` callback; gates the per-sample GPU blit+readback.
+   * Default: true.
+   */
+  rgb: boolean;
+}
+/**
+ * Callbacks for depth sampler events.
+ */
+interface DepthSamplerCallbacks {
+  /** Called when a depth sample is captured */
+  onSampleCaptured: (sample: DepthSample) => void;
+  /** Returns the current AR pose, or null if not available */
+  getCurrentPose: () => ARPose | null;
+  /**
+   * Called once when depth is determined to be unavailable.
+   * Triggered after unavailabilityThresholdMs with no depth data.
+   * Field Test Readiness Issue #8.
+   */
+  onDepthUnavailable?: () => void;
+  /**
+   * Lazily acquire a camera-color lookup for the CURRENT XR frame
+   * (occupancy-grid port plan Iter 8). Invoked at most once per *emitted*
+   * sample (never per frame or per point — acquisition is a GPU-stall
+   * blit+readback) and only while `config.rgb` is true. Returning `null`
+   * (or throwing) yields color-less points; the returned lookup is used
+   * synchronously within the same frame callback.
+   */
+  acquireRgbLookup?: () => RgbLookup | null;
+}
+/**
+ * WebXR depth info interface (subset of XRDepthInformation), extended with
+ * the capturing view's projection matrix so each emitted DepthSample carries
+ * the intrinsics needed for unprojection. Build via {@link wrapXRDepthInfo}.
+ */
+interface DepthInfo {
+  width: number;
+  height: number;
+  getDepthInMeters: (x: number, y: number) => number;
+  /** Column-major projection matrix of the capturing XRView, if known. */
+  projectionMatrix?: Matrix4;
+}
+/**
+ * Wrap a raw browser XRDepthInformation object into a {@link DepthInfo}.
+ *
+ * - `getDepthInMeters` is bound to the source object (browser
+ *   implementations are this-sensitive).
+ * - `projectionMatrix` (typically `XRView.projectionMatrix`, a Float32Array
+ *   the UA may reuse across frames) is defensively validated and copied into
+ *   a plain serializable 16-tuple; invalid input (wrong length, non-finite
+ *   entries) yields a DepthInfo without a matrix rather than an error.
+ */
+declare function wrapXRDepthInfo(raw: {
+  width: number;
+  height: number;
+  getDepthInMeters: (x: number, y: number) => number;
+}, projectionMatrix: ArrayLike<number> | undefined): DepthInfo;
+/**
+ * Samples sparse depth points from WebXR depth sensing.
+ *
+ * Usage:
+ * ```ts
+ * const sampler = new DepthSampler({
+ *   onSampleCaptured: (sample) => saveSample(sample),
+ *   getCurrentPose: () => arSession.getCurrentPose(),
+ * });
+ * sampler.start();
+ * // In frame loop:
+ * sampler.onFrame(timestamp, depthInfo);
+ * ```
+ */
+declare class DepthSampler {
+  private readonly callbacks;
+  private readonly config;
+  private running;
+  private sampleCount;
+  private lastSampleTime;
+  /** Timestamp when sampling started (for unavailability detection) */
+  private startTime;
+  /** Whether we've ever received valid depth data */
+  private depthReceived;
+  /** Whether we've already fired the unavailable callback */
+  private unavailableCallbackFired;
+  constructor(callbacks: DepthSamplerCallbacks, config?: Partial<DepthSamplerConfig>);
+  /**
+   * Start depth sampling.
+   */
+  start(): void;
+  /**
+   * Stop depth sampling.
+   */
+  stop(): void;
+  /**
+   * Check if sampler is currently running.
+   */
+  isRunning(): boolean;
+  /**
+   * Get the number of samples captured since start.
+   */
+  getSampleCount(): number;
+  /**
+   * Get the current configuration.
+   */
+  getConfig(): DepthSamplerConfig;
+  /**
+   * Apply partial configuration overrides (e.g. the user's recording
+   * options, plumbed in by `startDepthCapture` just before sampling
+   * starts). Invalid values are ignored defensively: every key requires a
+   * finite positive number, and `gridSize` additionally an integer.
+   */
+  updateConfig(config: Partial<DepthSamplerConfig>): void;
+  /**
+   * Called each frame with depth information.
+   *
+   * @param timestamp - Current frame timestamp in milliseconds
+   * @param depthInfo - WebXR depth information, or null if unavailable
+   */
+  onFrame(timestamp: number, depthInfo: DepthInfo | null): void;
+  /**
+   * Acquire the per-sample RGB lookup, gated by `config.rgb` and guarded so
+   * a failing acquisition (e.g. GL context loss during the blit) can never
+   * break the sample emission in the XR frame loop.
+   */
+  private acquireRgbLookupSafely;
+  /**
+   * Sample a grid of depth points from the depth buffer, attaching the
+   * camera color per point when a lookup is available.
+   */
+  private sampleGrid;
+  /**
+   * Check if depth has been unavailable for longer than the threshold.
+   * If so, fire the onDepthUnavailable callback (once).
+   */
+  private checkDepthUnavailability;
+  /**
+   * Check if depth data has ever been received.
+   * Useful for testing and status display.
+   */
+  hasReceivedDepth(): boolean;
+}
+//#endregion
+export { wrapXRDepthInfo as a, DepthSamplerConfig as i, DepthSampler as n, DepthSamplerCallbacks as r, DepthInfo as t };