gps-plus-slam-app-framework 1.0.0

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

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

package/dist/ar/xr-camera-texture.js

@@ -0,0 +1,39 @@
+import { createLogger } from "../utils/logger.js";
+//#region ../src/ar/xr-camera-texture.ts
+const log = createLogger("XRCameraTexture");
+/**
+* Acquire the camera texture for the current XR frame using Three.js's
+* built-in getCameraTexture() API, paired with native camera dimensions.
+*
+* Three.js internally:
+* 1. Creates XRWebGLBinding (lazy, one per session)
+* 2. Calls glBinding.getCameraImage(camera) each frame
+* 3. Wraps in ExternalTexture (sourceTexture = native WebGLTexture)
+* 4. Caches per xrCamera in cameraAccessTextures map
+*
+* This function adds the native camera dimensions (width/height) needed
+* for dynamic render target sizing in the blit capture pipeline.
+*
+* Must be called within the XR animation frame callback.
+*
+* @param renderer - The Three.js WebGLRenderer
+* @param xrCamera - The XRCamera from XRView.camera, or null if unavailable
+* @returns CameraTextureResult, or null if acquisition fails
+*/
+function acquireCameraTexture(renderer, xrCamera) {
+	if (!xrCamera) return null;
+	try {
+		const texture = renderer.xr.getCameraTexture(xrCamera);
+		if (!texture) return null;
+		return {
+			texture,
+			width: xrCamera.width,
+			height: xrCamera.height
+		};
+	} catch (error) {
+		log.error("Failed to acquire camera texture:", error);
+		return null;
+	}
+}
+//#endregion
+export { acquireCameraTexture };

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

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

package/dist/ar/xr-error-handler.js

@@ -0,0 +1,37 @@
+//#region ../src/ar/xr-error-handler.ts
+/**
+* WebXR Error Handler
+*
+* Provides user-facing error messages for WebXR session failures.
+* Separates error handling logic from AR module for testability.
+*/
+/**
+* Known WebXR error types and their user-friendly messages.
+*/
+const XR_ERROR_MESSAGES = {
+	NotSupportedError: "AR not supported on this device. Please ensure ARCore (Android) or ARKit (iOS) is installed.",
+	SecurityError: "Camera permission denied. Allow camera access to use AR features.",
+	InvalidStateError: "AR session already active. Please close other AR apps and try again.",
+	NotAllowedError: "AR access not allowed. Check browser permissions for this site."
+};
+/**
+* Default message for unknown error types.
+*/
+const XR_ERROR_MESSAGE_UNKNOWN = "Failed to start AR session. Check device compatibility and permissions.";
+/**
+* Get a user-friendly error message from a WebXR session error.
+*
+* @param error - The error thrown by navigator.xr.requestSession
+* @returns A user-friendly error message
+*/
+function getXrErrorMessage(error) {
+	if (error instanceof DOMException) return XR_ERROR_MESSAGES[error.name] ?? "Failed to start AR session. Check device compatibility and permissions.";
+	if (error instanceof Error) {
+		const msg = error.message.toLowerCase();
+		if (msg.includes("not supported")) return XR_ERROR_MESSAGES["NotSupportedError"];
+		if (msg.includes("permission") || msg.includes("denied")) return XR_ERROR_MESSAGES["SecurityError"];
+	}
+	return XR_ERROR_MESSAGE_UNKNOWN;
+}
+//#endregion
+export { XR_ERROR_MESSAGES, XR_ERROR_MESSAGE_UNKNOWN, getXrErrorMessage };

package/dist/ar-types-B-ORgk6Z.d.ts

@@ -0,0 +1,82 @@
+import { Quaternion, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/types/ar-types.d.ts
+/**
+ * Tuple-form AR pose for storage/serialization.
+ *
+ * The tuple equivalent of ARPose — uses the library's readonly Vector3/Quaternion
+ * tuples instead of object-form { x, y, z }. Used in storage interfaces where
+ * poses are persisted as plain number arrays in JSON.
+ *
+ * @see ARPose for the object-form variant used in live AR tracking
+ * @see 2026-03-03-code-review-inline-type-duplication.md Finding #6
+ */
+interface ArPoseTuples {
+  readonly position: Vector3;
+  readonly rotation: Quaternion;
+}
+/**
+ * 3D position in object-form as returned by the WebXR API (XRViewerPose).
+ * Distinct from the library's tuple-form `Vector3` (`readonly [number, number, number]`).
+ */
+interface WebXRVec3 {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+}
+/**
+ * Quaternion orientation in object-form as returned by the WebXR API (XRViewerPose).
+ * Distinct from the library's tuple-form `Quaternion` (`readonly [number, number, number, number]`).
+ */
+interface WebXRQuaternion {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  readonly w: number;
+}
+/**
+ * Device pose in AR space.
+ * Position and orientation are in the local-floor reference space.
+ * This is the RAW pose, NOT transformed by any alignment matrix.
+ */
+interface ARPose {
+  readonly position: WebXRVec3;
+  readonly orientation: WebXRQuaternion;
+}
+/**
+ * A single depth point sample from WebXR Depth API.
+ * Used for 3D reconstruction and validating AR tracking accuracy.
+ */
+interface DepthPoint {
+  /** Normalized screen X coordinate (0-1) */
+  readonly screenX: number;
+  /** Normalized screen Y coordinate (0-1) */
+  readonly screenY: number;
+  /** Depth value in meters */
+  readonly depthM: number;
+}
+/**
+ * A complete depth sample with camera pose and grid of depth points.
+ * Produced by the depth sampler at ~1 Hz, consumed by the store for
+ * persistence and replay. This is the single canonical type, re-exported
+ * by `store.ts` for dispatch convenience.
+ */
+interface DepthSample {
+  /** Timestamp in milliseconds */
+  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.
+   */
+  readonly cameraPos: Vector3;
+  /**
+   * Camera rotation quaternion in **raw WebXR** convention [x, y, z, w].
+   * NOT in NUE — same reasoning as cameraPos.
+   */
+  readonly cameraRot: Quaternion;
+  /** Grid of depth points */
+  readonly points: DepthPoint[];
+}
+//#endregion
+export { WebXRQuaternion as a, DepthSample as i, ArPoseTuples as n, WebXRVec3 as o, DepthPoint as r, ARPose as t };

package/dist/camera-blit-capture-DHuyrrxr.d.ts

@@ -0,0 +1,108 @@
+import * as THREE from "three";
+
+//#region ../src/ar/camera-blit-capture.d.ts
+/**
+ * Configuration for the blit capture render target dimensions.
+ * Smaller = faster readPixels (less GPU stall), but lower resolution.
+ */
+interface CameraBlitCaptureConfig {
+  /** Width of the intermediate render target in pixels */
+  width: number;
+  /** Height of the intermediate render target in pixels */
+  height: number;
+}
+/**
+ * Default blit capture config.
+ * 512×512 is a good balance between quality and readPixels performance on mobile.
+ */
+declare const DEFAULT_BLIT_CONFIG: CameraBlitCaptureConfig;
+/**
+ * Compute the capture dimensions from the native camera resolution
+ * and a user-configurable resolution divisor.
+ *
+ * @param cameraWidth  - Native camera width in pixels (from XRCamera)
+ * @param cameraHeight - Native camera height in pixels (from XRCamera)
+ * @param divisor      - Resolution divisor: 1 = full, 2 = half, 4 = quarter, etc.
+ *                        Values ≤ 0 are treated as 1. Fractional values < 1 are treated as 1.
+ * @returns Integer pixel dimensions, clamped to at least 1×1.
+ *          Falls back to DEFAULT_BLIT_CONFIG when inputs are invalid (≤ 0).
+ */
+declare function computeCaptureSize(cameraWidth: number, cameraHeight: number, divisor: number): {
+  width: number;
+  height: number;
+};
+/**
+ * Captures readable pixel data from WebXR opaque camera textures
+ * using the intermediate render target "blit" technique.
+ *
+ * Usage:
+ * 1. Create once when AR session starts
+ * 2. Call captureToBlob() when a frame needs to be captured
+ * 3. Call dispose() when AR session ends
+ */
+declare class CameraBlitCapture {
+  private renderTarget;
+  private blitScene;
+  private blitCamera;
+  private blitMaterial;
+  private quad;
+  private pixelBuffer;
+  private width;
+  private height;
+  private disposed;
+  constructor(config?: CameraBlitCaptureConfig);
+  /**
+   * Capture the WebXR camera texture to a JPEG Blob via the blit technique.
+   *
+   * IMPORTANT: Must be called within the XR animation frame callback,
+   * while the camera texture is valid.
+   *
+   * @param renderer - The Three.js WebGL renderer
+   * @param cameraTexture - The opaque camera texture from renderer.xr.getCameraTexture()
+   * @param quality - JPEG quality 0.0-1.0
+   * @returns JPEG Blob, or null if capture fails
+   */
+  captureToBlob(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture, quality: number): Promise<Blob | null>;
+  /**
+   * Check if a pixel buffer is entirely black (all zeros).
+   * Uses sampling for performance (checks BLACK_CHECK_SAMPLE_COUNT evenly-spaced pixels).
+   *
+   * This is useful to detect if the blit technique failed to convert
+   * the opaque texture (different from a legitimately dark scene).
+   *
+   * @param pixels - RGBA pixel buffer
+   * @returns true if all sampled pixels are zero
+   */
+  static isBlackFrame(pixels: Uint8Array): boolean;
+  /**
+   * Convert the internal pixel buffer to a JPEG Blob using OffscreenCanvas
+   * (or fallback to regular Canvas).
+   */
+  private pixelsToJpegBlob;
+  private getFlippedImageData;
+  private pixelsToJpegViaOffscreenCanvas;
+  private pixelsToJpegViaCanvas;
+  /**
+   * Flip ImageData vertically in-place.
+   * WebGL readPixels returns bottom-row-first; canvas expects top-row-first.
+   */
+  private flipImageDataVertically;
+  /**
+   * Resize the render target and pixel buffer to match new dimensions.
+   * Call this when the camera resolution is first known or changes.
+   *
+   * No-op when dimensions already match (avoids per-frame reallocation).
+   * Returns false if disposed, dimensions unchanged, or dimensions invalid.
+   *
+   * @param newWidth  - Desired capture width in pixels
+   * @param newHeight - Desired capture height in pixels
+   * @returns true if resources were actually resized
+   */
+  resizeIfNeeded(newWidth: number, newHeight: number): boolean;
+  /**
+   * Dispose GPU resources. Call when AR session ends.
+   */
+  dispose(): void;
+}
+//#endregion
+export { computeCaptureSize as i, CameraBlitCaptureConfig as n, DEFAULT_BLIT_CONFIG as r, CameraBlitCapture as t };

package/dist/camera-follower-BMqPddxx.d.ts

@@ -0,0 +1,29 @@
+import * as THREE from "three";
+
+//#region ../src/visualization/camera-follower.d.ts
+interface CameraFollower {
+  /** The underlying Object3D — add children (map, cubes) here. */
+  readonly object3D: THREE.Object3D;
+  /**
+   * Update the follower position. Call once per frame before render.
+   *
+   * @param camera The active camera (its world position is read).
+   * @param dt     Delta time in seconds since last frame.
+   */
+  update(camera: THREE.Camera, dt: number): void;
+  /** Remove the follower from the scene graph. */
+  dispose(): void;
+}
+/**
+ * Create a CameraFollower and attach it as a child of the given parent.
+ *
+ * The parent should be the scene root (not arWorldGroup) so that the
+ * follower's world rotation stays identity — ensuring compass directions
+ * align with the NUE GPS frame regardless of alignment matrix changes.
+ *
+ * @param parent   Parent node — should be the scene root.
+ * @param lerpRate Lerp speed multiplier (default 8).
+ */
+declare function createCameraFollower(parent: THREE.Object3D, lerpRate?: number): CameraFollower;
+//#endregion
+export { createCameraFollower as n, CameraFollower as t };

package/dist/capture-failure-tracker-2Q6oI2uQ.d.ts

@@ -0,0 +1,52 @@
+//#region ../src/ar/capture-failure-tracker.d.ts
+/**
+ * Capture Failure Tracker
+ *
+ * Tracks consecutive image capture failures and notifies users when
+ * multiple frames fail to capture (e.g., low memory on mobile devices).
+ *
+ * Field Test Readiness Issue #11: Silent image capture failures
+ *
+ * Thin wrapper around the generic failure tracker factory.
+ */
+/**
+ * Configuration for the capture failure tracker.
+ */
+interface CaptureFailureTrackerConfig {
+  /**
+   * Number of consecutive failures before warning the user.
+   * Default: 5 (higher than write failures since capture failures are less critical)
+   */
+  failureThreshold: number;
+  /**
+   * Callback to show error to user.
+   */
+  onWarning: (message: string) => void;
+}
+/**
+ * Default configuration values.
+ */
+declare const DEFAULT_CAPTURE_TRACKER_CONFIG: Omit<CaptureFailureTrackerConfig, 'onWarning'>;
+/**
+ * User-facing warning message when threshold is exceeded.
+ */
+declare const CAPTURE_FAILURE_WARNING = "Multiple image captures failed. Device may be low on memory.";
+/**
+ * Tracks consecutive capture failures and warns user when threshold is exceeded.
+ */
+interface CaptureFailureTracker {
+  recordSuccess(): void;
+  recordFailure(): void;
+  getFailureCount(): number;
+  hasWarned(): boolean;
+  reset(): void;
+}
+/**
+ * Create a new capture failure tracker.
+ *
+ * @param config - Configuration with warning callback and optional threshold
+ * @returns CaptureFailureTracker instance
+ */
+declare function createCaptureFailureTracker(config: Partial<CaptureFailureTrackerConfig> & Pick<CaptureFailureTrackerConfig, 'onWarning'>): CaptureFailureTracker;
+//#endregion
+export { createCaptureFailureTracker as a, DEFAULT_CAPTURE_TRACKER_CONFIG as i, CaptureFailureTracker as n, CaptureFailureTrackerConfig as r, CAPTURE_FAILURE_WARNING as t };

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

@@ -0,0 +1,61 @@
+//#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 recent Android
+ * Chrome versions 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-04-23-webxr-camera-access-crash-bug-report.html
+ *   - https://github.com/mrdoob/three.js/issues/33404
+ *
+ * Workaround (from the upstream issue thread):
+ * Three.js's `WebXRManager` chooses between the newer `XRProjectionLayer`
+ * and the older `XRWebGLLayer` based on whether
+ * `XRWebGLBinding.prototype.createProjectionLayer` is available. The crash
+ * appears to involve the projection-layer + camera-access combination, so
+ * removing the prototype method forces three.js to fall back to
+ * `XRWebGLLayer`, which sidesteps the bug.
+ *
+ * `XRRenderState.prototype.layers` is the equivalent capability check used
+ * by older three.js (r158-era) and is included for completeness.
+ *
+ * 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).
+ */
+/**
+ * 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;
+}
+/**
+ * Apply the Chromium camera-access tab-crash workaround.
+ *
+ * Removes `XRWebGLBinding.prototype.createProjectionLayer` (three.js r184)
+ * and `XRRenderState.prototype.layers` (three.js r158) so three.js falls
+ * back to `XRWebGLLayer`, which avoids the renderer-process crash that
+ * happens when both projection layers and `camera-access` are enabled.
+ *
+ * Call once during bootstrap, before any `requestSession()` call.
+ *
+ * @returns which prototype members were actually deleted on this call.
+ */
+declare function applyChromiumProjectionLayerWorkaround(): ChromiumProjectionLayerWorkaroundResult;
+//#endregion
+export { applyChromiumProjectionLayerWorkaround as n, ChromiumProjectionLayerWorkaroundResult as t };

package/dist/community-license-key-ChZLCJyO.d.ts

@@ -0,0 +1,21 @@
+//#region ../src/licensing/community-license-key.d.ts
+/**
+ * Community license key for the gps-plus-slam-js core library.
+ *
+ * Generated by the core library maintainers and bundled with the open-source
+ * `gps-plus-slam-app-framework` package so that every example app (and any
+ * downstream app built on the framework) automatically uses a valid license
+ * without per-developer registration.
+ *
+ * The key has a rolling expiration of 12 months. Each release of the
+ * open-source packages renews it. Active users who regularly update their
+ * dependencies will never be affected by the expiration.
+ *
+ * For licenses with extended validity beyond the community key's scope,
+ * contact support@csutil.com.
+ *
+ * @see GpsPlusSlamJs/EULA.md §3 — License Key
+ */
+declare const COMMUNITY_LICENSE_KEY = "eyJ0eXBlIjoiY29tbXVuaXR5IiwiZXhwIjoxODA4NzcyNDI3fQ.YYNf0IdqniZdMzRXCuvewxsQQ01XNywrKsfL5IpiJotfFJfqtrGg4u9z0QFhXeszPtUhnvgC8_oOnbOkbXPuAw";
+//#endregion
+export { COMMUNITY_LICENSE_KEY as t };

package/dist/concurrency-p6gB30fT.d.ts

@@ -0,0 +1,24 @@
+//#region ../src/utils/concurrency.d.ts
+/**
+ * Concurrency Utilities
+ *
+ * Provides helpers for limiting the number of concurrent async operations.
+ * Used to prevent excessive memory consumption when scanning many files
+ * in parallel (e.g., reading zip metadata during scenario discovery).
+ */
+/**
+ * Map over an array with a concurrency limit on the async mapper function.
+ *
+ * Behaves like `Promise.all(items.map(fn))` but limits how many mapper
+ * invocations run simultaneously. Results are returned in the same order
+ * as the input items.
+ *
+ * @param items - Array of items to process
+ * @param limit - Maximum number of concurrent mapper invocations
+ * @param mapper - Async function to apply to each item
+ * @returns Array of results in the same order as input items
+ * @throws Re-throws the first error from any mapper invocation (fail-fast)
+ */
+declare function mapWithConcurrencyLimit<T, R>(items: T[], limit: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//#endregion
+export { mapWithConcurrencyLimit as t };

package/dist/css3d-renderer-manager-rgLMVAvd.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+
+//#region ../src/visualization/css3d-renderer-manager.d.ts
+interface Css3dRendererManager {
+  render(scene: THREE.Scene, camera: THREE.Camera): void;
+  setSize(width: number, height: number): void;
+  dispose(): void;
+}
+/**
+ * Create and configure a CSS3DRenderer overlay for the given container.
+ *
+ * The CSS3D layer is positioned absolutely over the container with
+ * `pointer-events: none` so it does not intercept clicks intended
+ * for the WebGL canvas underneath.
+ *
+ * **Requirement:** The `container` element must have `position: relative`,
+ * `absolute`, `fixed`, or `sticky`. If the container is `position: static`
+ * (the CSS default), the overlay will float to the nearest positioned
+ * ancestor instead of aligning with the container.
+ */
+declare function createCss3dRendererManager(container: HTMLElement, width: number, height: number): Css3dRendererManager;
+//#endregion
+export { createCss3dRendererManager as n, Css3dRendererManager as t };

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

@@ -0,0 +1,108 @@
+import { i as DepthSample, t as ARPose } from "./ar-types-B-ORgk6Z.js";
+
+//#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: 3 */
+  gridSize: number;
+  /** Time in ms to wait before declaring depth unavailable. Default: 5000ms */
+  unavailabilityThresholdMs: number;
+}
+/**
+ * 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;
+}
+/**
+ * WebXR depth info interface (subset of XRDepthInformation).
+ */
+interface DepthInfo {
+  width: number;
+  height: number;
+  getDepthInMeters: (x: number, y: number) => number;
+}
+/**
+ * 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;
+  /**
+   * 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;
+  /**
+   * Sample a grid of depth points from the depth buffer.
+   */
+  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 { DepthSamplerConfig as i, DepthSampler as n, DepthSamplerCallbacks as r, DepthInfo as t };

package/dist/failure-tracker-1sQ_Cgyw.d.ts

@@ -0,0 +1,49 @@
+//#region ../src/utils/failure-tracker.d.ts
+/**
+ * Generic Failure Tracker Factory
+ *
+ * Shared pattern extracted from capture-failure-tracker and write-failure-tracker.
+ * Tracks consecutive failures, warns the user once when a threshold is exceeded,
+ * and supports session-level reset.
+ */
+/**
+ * Configuration for creating a failure tracker.
+ */
+interface FailureTrackerConfig {
+  /** Human-readable label used for log messages (e.g., 'CaptureFailure'). */
+  label: string;
+  /** Message passed to `onWarning` when the threshold is reached. */
+  warningMessage: string;
+  /** Default threshold used when `failureThreshold` is not provided. */
+  defaultThreshold: number;
+  /** Callback invoked once when consecutive failures reach the threshold. */
+  onWarning: (message: string) => void;
+  /** Optional override for the failure threshold. */
+  failureThreshold?: number;
+  /** Log level for each failure: 'warn' (default) or 'error'. */
+  logLevel?: 'warn' | 'error';
+}
+/**
+ * A failure tracker instance returned by `createFailureTracker`.
+ */
+interface FailureTracker {
+  /** Record a success — resets the consecutive failure counter. */
+  recordSuccess(): void;
+  /** Record a failure (optionally with an error for logging). */
+  recordFailure(error?: unknown): void;
+  /** Current number of consecutive failures. */
+  getFailureCount(): number;
+  /** Whether the warning has already been shown this session. */
+  hasWarned(): boolean;
+  /** Reset all state (for new sessions). */
+  reset(): void;
+}
+/**
+ * Create a generic failure tracker.
+ *
+ * @param config - Tracker configuration
+ * @returns A FailureTracker instance
+ */
+declare function createFailureTracker(config: FailureTrackerConfig): FailureTracker;
+//#endregion
+export { FailureTrackerConfig as n, createFailureTracker as r, FailureTracker as t };