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

package/dist/{webxr-session-COsOjJwn.d.ts → webxr-session-cRG2SYAQ.d.ts}

@@ -1,11 +1,11 @@
-import { i as DepthSample, t as ARPose } from "./ar-types-BckI1E-O.js";
-import { i as DepthSamplerConfig } from "./depth-sampler-DwfPYzS7.js";
-import { t as ArCrashIsolationOptions } from "./recording-options-D93kksJU.js";
-import { a as ImageCaptureConfig, n as CapturedImage } from "./image-capture-C2Feywet.js";
-import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-DJZ9qeGg.js";
-import { o as RgbaImage } from "./qr-frontend-DufZp2xS.js";
-import { t as Css3dRendererManager } from "./css3d-renderer-manager-m-ab19vp.js";
-import { r as XRCameraLike } from "./xr-camera-texture-BmrP7iNZ.js";
+import { i as DepthSample, t as ARPose } from "./ar-types-Cc5yvBwn.js";
+import { i as DepthSamplerConfig, t as DepthInfo } from "./depth-sampler-CwObAwEA.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-vASCFzc5.js";
+import { i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, t as CapturedFrame } from "./image-capture-Bp6Pd4Md.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-DMkHlbny.js";
+import { o as RgbaImage } from "./qr-frontend-BPURlh3S.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-CPpVtvgs.js";
+import { r as XRCameraLike } from "./xr-camera-texture-q0eIDSRg.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
 
@@ -69,6 +69,16 @@ declare function shouldLogCameraAccessDiagnostic(pose: XRViewerPose | null, alre
  * @internal
  */
 declare function resetWebXRState(): void;
+/**
+ * Info passed to the session-end callback (F3, 2026-07-04 user feedback).
+ * `requestedByApp` discriminates the app's own `endARSession()` from a
+ * system-initiated end (e.g. the Android back gesture, which ends an
+ * immersive XRSession directly — no popstate, no beforeunload, not
+ * cancelable).
+ */
+interface SessionEndInfo {
+  requestedByApp: boolean;
+}
 /**
  * Default longer-edge resolution (px) for the camera-frame blit the QR / CV
  * detector sees. The on-device capture-resolution sweep (2026-06-17, via the
@@ -129,6 +139,18 @@ interface SessionFeatureOptions {
    * existing recorder/anchor sessions are unaffected.
    */
   requestHitTest?: boolean;
+  /**
+   * Request `depth-sensing` (cpu-optimized) for the **live depth occluder**
+   * even when crash-isolation's `enableDepthSensingFeature` is off. Consumer
+   * apps (AnchorStarter / MinimalExample) want occlusion without the recorder's
+   * depth-capture wiring, so the occluder owns its own session-feature switch.
+   * Both flags resolve the **same** cpu-optimized usage — setting both is valid
+   * (no conflict, no throw): the grid sampler and the occluder are two consumers
+   * of one depth read. Default `false`.
+   *
+   * @see GpsPlusSlamJs_Docs/docs/2026-06-14-webxr-depth-occlusion-plan.md §6/§8
+   */
+  requestDepthOcclusion?: boolean;
 }
 /**
  * Build XR session init options.
@@ -138,7 +160,7 @@ interface SessionFeatureOptions {
  * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
  *   depth-sensing, camera-access)
  * @param sessionFeatures - Opt-in standard WebXR features that are independent
- *   of crash isolation (currently `requestHitTest`)
+ *   of crash isolation (`requestHitTest`, `requestDepthOcclusion`)
  * @returns XRSessionInit options
  * @throws Error if rootElement is null
  */
@@ -147,6 +169,23 @@ declare function buildSessionOptions(rootElement: Element | null, isolationOptio
  * Check if WebXR immersive-ar is supported
  */
 declare function isWebXRSupported(): Promise<boolean>;
+/**
+ * AR camera frustum constants — the single source of truth for live AR and
+ * replay (both build their camera via {@link createSceneHierarchy}).
+ *
+ * F2 (2026-07-04 user feedback): far raised 100 → 200 m so objects in the
+ * reported 100–200 m range are no longer frustum-culled. The far-plane
+ * distance itself is essentially free at this app's object counts; the real
+ * constraint is depth precision — far/near = 2×10⁴ is comfortable for a
+ * 24-bit depth buffer. Revisit the ratio if AR_CAMERA_NEAR ever shrinks.
+ *
+ * Note: these apply to WebGL content only. The CSS3D minimap is composited by
+ * the browser from the camera fov alone — near/far do not clip it (F1 in the
+ * same feedback doc).
+ */
+declare const AR_CAMERA_FOV = 70;
+declare const AR_CAMERA_NEAR = 0.01;
+declare const AR_CAMERA_FAR = 200;
 /**
  * Create the scene hierarchy with proper AR/GPS frame separation.
  * This is a pure function for testability.
@@ -196,6 +235,18 @@ declare function createSceneHierarchy(): {
  *   `requestHitTest`) forwarded to the session negotiation.
  */
 declare function initAR(container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions): Promise<void>;
+/**
+ * Extract depth information from an XR frame. Returns `null` if depth sensing is
+ * not available (no pose/view, no `getDepthInformation`, or the call throws).
+ *
+ * Exported so a consumer can feed the **live depth occluder** from a
+ * `registerXrFrameUpdate` callback — the callback has the live `frame` +
+ * `referenceSpace`, computes `pose = frame.getViewerPose(referenceSpace)`, and
+ * passes both here to obtain the per-frame {@link DepthInfo} (with the widened
+ * `data` / `rawValueToMeters` / `normDepthBufferFromNormView` / `projectionMatrix`
+ * the occluder needs). The same wrapped depth the sparse grid sampler consumes.
+ */
+declare function getDepthInfoFromFrame(frame: XRFrame, pose: XRViewerPose | null): DepthInfo | null;
 /**
  * Get the current Three.js scene (for adding objects like map)
  */
@@ -284,6 +335,18 @@ declare function nuePositionToWebXR(nue: readonly number[]): readonly [number, n
  * NUE [x, y, z, w] → WebXR [z, y, -x, w]
  */
 declare function nueQuaternionToWebXR$1(nue: readonly number[]): readonly [number, number, number, number];
+/**
+ * Register a host callback fired exactly once whenever the XRSession ends —
+ * app-initiated ({@link endARSession}) AND system-initiated (e.g. the Android
+ * back gesture, which ends an immersive session directly and uncancelably).
+ * `info.requestedByApp` discriminates the two. Fired AFTER the full teardown,
+ * so the host can immediately start a fresh session from inside the callback.
+ *
+ * Cleared by resetWebXRState() (i.e. after every session end) like the other
+ * module-level callbacks — re-register before/with each new session.
+ * Pass `null` to unregister. F3, 2026-07-04 user feedback.
+ */
+declare function setSessionEndCallback(cb: ((info: SessionEndInfo) => void) | null): void;
 /**
  * End the current XR session and clean up all resources.
  *
@@ -305,6 +368,16 @@ declare function endARSession(): Promise<void>;
  * @param onSuspicious - Optional callback for when a captured image appears black/empty
  */
 declare function setImageCaptureCallback(onCaptured: (image: CapturedImage) => void, screenRotationGetter: () => number, onFailed?: () => void, onSuspicious?: (blobSize: number, frameIndex: number) => void): void;
+/**
+ * Inject (or clear) the off-thread image-quality analyzer used by the blur/
+ * blackness drop+retry gate. Pass the recorder's Web Worker-backed analyzer to
+ * enable the gate, or `null` to clear it (legacy save-immediately path). Must be
+ * set BEFORE {@link startImageCapture} for the active recording — the manager
+ * reads it once when constructed. The analyzer only runs when the capture
+ * config's `qualityFilter.enabled` is true, so injecting it is harmless when the
+ * gate is off. Ownership/disposal of the worker is the caller's responsibility.
+ */
+declare function setImageQualityAnalyzer(analyzer: ((frame: CapturedFrame) => Promise<FrameQualityVerdict>) | null): void;
 /**
  * Start capturing images during recording.
  * Must call setImageCaptureCallback first.
@@ -454,4 +527,4 @@ declare function setFrameCallback(callback: (() => void) | null): void;
  */
 declare function getLiveCss3dManager(): Css3dRendererManager | null;
 //#endregion
-export { setCamera as A, shouldLogCameraAccessDiagnostic as B, isWebXRSupported as C, resetWebXRState as D, nueQuaternionToWebXR$1 as E, setScene as F, stopDepthCapture as G, startDepthCapture as H, setTrackingCallbacks as I, stopImageCapture as K, setTrackingLostCallback as L, setDepthCaptureCallback as M, setFrameCallback as N, setArPose as O, setImageCaptureCallback as P, setTrackingRecoveredCallback as R, initAR as S, nuePositionToWebXR as T, startImageCapture as U, startCameraFrameCapture as V, stopCameraFrameCapture as W, getDepthSampleCount as _, applyAlignmentMatrix as a, getScene as b, endARSession as c, getArPose as d, getArWorldGroup as f, getCurrentArPose as g, getCameraFrameCount as h, TrackingSubscribableStore as i, setCameraFrameCallback as j, setArWorldGroup as k, extractPoseFromViewer as l, getCameraFrameCaptureSize as m, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as n, buildSessionOptions as o, getCamera as p, SessionFeatureOptions as r, createSceneHierarchy as s, CameraFrameCaptureConfig as t, extractResetTransformData as u, getImageCaptureFrameCount as v, isXRCameraLike as w, getXrCameraFromPose as x, getLiveCss3dManager as y, setTrackingStore as z };
+export { stopImageCapture as $, nuePositionToWebXR as A, setImageQualityAnalyzer as B, getImageCaptureFrameCount as C, initAR as D, getXrCameraFromPose as E, setCamera as F, setTrackingRecoveredCallback as G, setSessionEndCallback as H, setCameraFrameCallback as I, startCameraFrameCapture as J, setTrackingStore as K, setDepthCaptureCallback as L, resetWebXRState as M, setArPose as N, isWebXRSupported as O, setArWorldGroup as P, stopDepthCapture as Q, setFrameCallback as R, getDepthSampleCount as S, getScene as T, setTrackingCallbacks as U, setScene as V, setTrackingLostCallback as W, startImageCapture as X, startDepthCapture as Y, stopCameraFrameCapture as Z, getCamera as _, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as a, getCurrentArPose as b, TrackingSubscribableStore as c, createSceneHierarchy as d, endARSession as f, getArWorldGroup as g, getArPose as h, CameraFrameCaptureConfig as i, nueQuaternionToWebXR$1 as j, isXRCameraLike as k, applyAlignmentMatrix as l, extractResetTransformData as m, AR_CAMERA_FOV as n, SessionEndInfo as o, extractPoseFromViewer as p, shouldLogCameraAccessDiagnostic as q, AR_CAMERA_NEAR as r, SessionFeatureOptions as s, AR_CAMERA_FAR as t, buildSessionOptions as u, getCameraFrameCaptureSize as v, getLiveCss3dManager as w, getDepthInfoFromFrame as x, getCameraFrameCount as y, setImageCaptureCallback as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gps-plus-slam-app-framework",
-  "version": "1.4.0",
+  "version": "1.8.0",
   "description": "Reusable AR+GPS app framework layer — WebXR session management, Three.js visualization, GPS sensors, storage abstractions, replay engine, and store wiring for gps-plus-slam-js.",
   "type": "module",
   "files": [
@@ -36,7 +36,7 @@
   "dependencies": {
     "@reduxjs/toolkit": "^2.11.2",
     "gl-matrix": "3.4.4",
-    "gps-plus-slam-js": "^1.4.0"
+    "gps-plus-slam-js": "^1.8.0"
   },
   "peerDependencies": {
     "@sentry/browser": ">=10.0.0",
@@ -104,10 +104,10 @@
     "build": "tsdown --config config/tsdown.config.ts",
     "verify:pack": "pnpm pack --dry-run",
     "verify:community-key-lifetime": "node scripts/verify-community-key-lifetime.mjs",
-    "test:unit": "vitest run --coverage --config config/vitest.config.ts",
+    "test:unit": "node ../scripts/run-vitest-scoped.mjs run --coverage --config=config/vitest.config.ts",
     "typecheck": "tsc -p tsconfig.app.json --noEmit",
     "typecheck:tests": "tsc -p tsconfig.vitest.json --noEmit",
-    "lint": "eslint . --config config/eslint.config.mjs",
+    "lint": "eslint . --config config/eslint.config.mjs --max-warnings 37",
     "test:watch": "vitest --config config/vitest.config.ts",
     "check:cycles": "dpdm -T --exit-code circular:1 --no-warning --no-tree ./src/index.ts",
     "setup": "bash ./scripts/setup.sh"

package/dist/index-eaI1Z1KR.d.ts

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

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

@@ -1,20 +0,0 @@
-//#region ../src/visualization/lerp-utils.d.ts
-/**
- * Shared lerp utilities for visualization modules.
- *
- * Both alignment-lerper and camera-follower need the same smoothing
- * rate constant and clamped-alpha formula. Centralised here (R3) to
- * keep the two modules in sync.
- */
-/** Default speed multiplier — ~90 % convergence in ~0.3 s at 60 fps. */
-declare const DEFAULT_LERP_RATE = 8;
-/**
- * Compute a frame-rate-independent lerp/slerp factor clamped to [0, 1].
- *
- * @param lerpRate Speed multiplier (higher = faster convergence).
- * @param dt       Delta time in seconds since last frame.
- * @returns The interpolation alpha, guaranteed ≤ 1.0.
- */
-declare function clampedAlpha(lerpRate: number, dt: number): number;
-//#endregion
-export { clampedAlpha as n, DEFAULT_LERP_RATE as t };

package/dist/occupancy-grid-Bvi2Gw1U.d.ts

@@ -1,82 +0,0 @@
-import { t as GridCell } from "./bresenham3d-ByjcmEgM.js";
-import { a as RgbTuple, i as DepthSample } from "./ar-types-BckI1E-O.js";
-import { Vector3 } from "gps-plus-slam-js";
-
-//#region ../src/ar/occupancy-grid.d.ts
-interface OccupancyGridOptions {
-  /** Edge length of a cubic grid cell in meters. Default 0.15 (Unity parity). */
-  readonly cellSizeM?: number;
-  /**
-   * Dominant-axis steps before a ray's endpoint at which free-space
-   * carving stops, to respect depth noise. Default 2 (Unity parity).
-   */
-  readonly carveStopCells?: number;
-}
-declare class OccupancyGrid {
-  readonly cellSizeM: number;
-  readonly carveStopCells: number;
-  private readonly cells;
-  constructor(options?: OccupancyGridOptions);
-  /** Number of occupied cells. */
-  get size(): number;
-  /**
-   * Fold one depth sample into the grid: unproject each point, carve free
-   * space from the camera cell to the point cell, then count the point's
-   * cell as occupied. Points that cannot be unprojected (no
-   * projectionMatrix on old recordings, invalid depth/coords) are skipped.
-   *
-   * Carving and incrementing run as two separate passes over the sample's
-   * points: all rays are carved first, then every endpoint is incremented.
-   * A single interleaved pass would be order-dependent — a deeper point's
-   * carve could erase the endpoint a nearer point added earlier in the same
-   * sample. Splitting the passes makes the result deterministic and lets an
-   * endpoint observed within a sample survive other rays in that same
-   * sample. (Deeper-carves-nearer still applies ACROSS samples: a later
-   * sample's ray carves an earlier sample's endpoint as before.)
-   *
-   * @returns the number of points actually added.
-   */
-  addSample(sample: DepthSample): number;
-  /** Occupied cells observed at least `minObservations` times (default 1). */
-  getOccupiedCells(minObservations?: number): GridCell[];
-  /** Quantize a raw-WebXR position to its grid cell (round per axis). */
-  cellForPosition(pos: Vector3): GridCell;
-  /** Center of a cell in raw WebXR space (round-consistent: cell · cellSizeM). */
-  getCellCenter(cell: GridCell): Vector3;
-  /**
-   * Running-average of the EXACT unprojected surface points observed in this
-   * cell (raw WebXR space), or null for an unknown cell. Unlike
-   * {@link getCellCenter} (the geometric 15 cm-lattice center) this hugs the
-   * real measured surface and noise-averages across viewpoints — used by the
-   * COLMAP `points3D` export and the debug cubes (follow-up Item A). Being a
-   * centroid of points that fell in the cell, it always lies within
-   * `cellSizeM/2` of the cell center per axis.
-   */
-  getCellPoint(cell: GridCell): Vector3 | null;
-  /**
-   * Running-average color of the cell's colored observations (Iter 8), or
-   * null when the cell is unknown or was only ever observed without color
-   * (rgb option off / pre-Iter-8 recordings) — consumers fall back to
-   * height-based coloring. Channels are rounded and clamped to 0–255.
-   */
-  getCellColor(cell: GridCell): RgbTuple | null;
-  /**
-   * Walk the grid from `startPos` to `endPos` and return the center of the
-   * first cell occupied at least `minObservations` times, or null.
-   * Port of Unity's `TryRaycast` (hook for cursor/floor-detection parity).
-   */
-  raycast(startPos: Vector3, endPos: Vector3, minObservations?: number): Vector3 | null;
-  /** Remove all occupied cells (e.g. on store swap / new session). */
-  clear(): void;
-  /**
-   * Delete occupied cells along the camera→point ray (the space was seen
-   * through, so it must be free), stopping `carveStopCells` dominant-axis
-   * steps before the endpoint. The endpoint cell itself is additionally
-   * protected so a current observation is never erased (relevant for
-   * carveStopCells = 0 and for the unconditional start-cell visit).
-   */
-  private carve;
-  private increment;
-}
-//#endregion
-export { OccupancyGridOptions as n, OccupancyGrid as t };

package/dist/recording-options-D93kksJU.d.ts

@@ -1,369 +0,0 @@
-//#region ../src/state/recording-options.d.ts
-/**
- * Recording Options - User-configurable settings for data capture.
- *
- * Allows users to disable/configure high-frequency data streams
- * (depth sampling, image capture) to improve performance on lower-end devices.
- *
- * Options persist in localStorage across sessions.
- */
-/**
- * Input type for validateRecordingOptions allowing partial nested objects.
- * This allows passing incomplete objects that will be merged with defaults.
- */
-interface RecordingOptionsInput {
-  depth?: Partial<DepthCaptureOptions>;
-  images?: Partial<ImageCaptureOptions>;
-  arCrashIsolation?: Partial<ArCrashIsolationOptions>;
-  occupancy?: Partial<OccupancyOptions>;
-  frameTileDisplay?: Partial<FrameTileDisplayOptions>;
-  visualization?: Partial<VisualizationOptions>;
-  qr?: Partial<QrCaptureOptions>;
-}
-/**
- * Diagnostic flags for isolating pre-recording AR startup crashes.
- * These gates affect XR session negotiation and frame-loop behavior,
- * independently of recording-time image/depth capture.
- */
-interface ArCrashIsolationOptions {
-  enableDomOverlay: boolean;
-  enableCameraAccess: boolean;
-  enableDepthSensingFeature: boolean;
-  enableCss3dRenderer: boolean;
-  enableCameraTextureAcquisition: boolean;
-  /**
-   * Apply the Chromium WebXR camera-access tab-crash workaround at app
-   * bootstrap. The workaround always deletes
-   * `XRWebGLBinding.prototype.createProjectionLayer` /
-   * `XRRenderState.prototype.layers` (forcing `XRWebGLLayer`) — required on
-   * every affected Chrome build observed on-device, including Chrome 150 — and
-   * additionally persists the `baseLayer` across
-   * `XRSession.prototype.updateRenderState` only for Chrome builds inside the
-   * affected window (148.0.7778.12 up to 149.0.7821).
-   *
-   * Default `true`. Opt-out is offered because forcing `XRWebGLLayer` may break
-   * WebXR on unaffected (e.g. Quest) devices.
-   *
-   * @see GpsPlusSlamJs_AppFramework/src/ar/chromium-camera-access-workaround.ts
-   * @see https://github.com/mrdoob/three.js/issues/33404
-   */
-  applyChromiumProjectionLayerWorkaround: boolean;
-}
-/**
- * Configuration for depth sampling during recording.
- */
-interface DepthCaptureOptions {
-  /** Whether to capture depth samples. Default: true */
-  enabled: boolean;
-  /** Interval between samples in milliseconds. Default: 1000 */
-  intervalMs: number;
-  /**
-   * Grid size (N×N points per sample). Default: 16 — dense enough to
-   * populate the AR-space occupancy grid (2026-06-11 port plan §1).
-   */
-  gridSize: number;
-  /**
-   * Whether to enrich each depth point with the camera color at its view
-   * coordinates (RGB voxel coloring, occupancy-grid port plan Iter 8).
-   * Costs one small GPU blit+readback per sample (~1 Hz); when off, the
-   * occupancy cubes keep the height-based coloring. Default: true.
-   */
-  rgb: boolean;
-}
-/**
- * Configuration for image capture during recording.
- */
-interface ImageCaptureOptions {
-  /** Whether to capture images. Default: true */
-  enabled: boolean;
-  /** Interval between captures in milliseconds. Default: 2000 */
-  intervalMs: number;
-  /** JPEG quality (0.0 - 1.0). Default: 0.7 */
-  quality: number;
-  /** Resolution divisor: 1 = full native resolution, 2 = half, 4 = quarter. Default: 1 */
-  resolutionDivisor: number;
-}
-/**
- * Configuration for the derived AR-space occupancy grid (the voxelization of
- * the depth samples, port plan 2026-06-11). These settings do NOT change what
- * is recorded — they govern the grid derived from the recorded depth points,
- * so they also apply when replaying an existing recording, letting the same
- * session be re-quantized at a different resolution.
- */
-interface OccupancyOptions {
-  /**
-   * Voxel edge length in metres. Drives the occupancy-grid quantization, the
-   * debug cubes, and the COLMAP `points3D` density. Default 0.15 (15 cm, Unity
-   * parity). Smaller = finer detail but cell count scales as 1/cellSize³, so the
-   * range is deliberately clamped (see `OCCUPANCY_CONSTRAINTS`). Read once when
-   * the grid is constructed (Enter-AR / replay load), so a change takes effect
-   * on the next session rather than mid-session.
-   */
-  cellSizeM: number;
-}
-/**
- * Configuration for how captured frame tiles are DISPLAYED in AR (D7-resolution,
- * 2026-06-16 RecorderApp user feedback / Q3). This is **distinct from** the
- * capture setting `images.resolutionDivisor`: capture quality (the JPEG written
- * to the recording) is unchanged — this only downscales the in-AR/replay display
- * texture built from each captured frame, cutting per-tile GPU texture memory.
- *
- * Like {@link OccupancyOptions} it does NOT change what is recorded, so it
- * applies to **both live and replay** (the tile texture is decoded in both). A
- * partial memory mitigation for the OOM/crash track (the tile *count* still
- * grows unbounded — capping/recycling is the separate Track-S fix).
- */
-interface FrameTileDisplayOptions {
-  /**
-   * Display-texture resolution divisor: 1 = full captured resolution, 2 = half
-   * (each dimension), 4 = quarter, 8 = eighth. Default 2 (half). Higher = less
-   * GPU memory per tile but a blurrier in-AR preview. Independent of the capture
-   * `images.resolutionDivisor`.
-   */
-  divisor: number;
-}
-/**
- * Visibility toggles for the live AR debug overlays (Finding B / DB-2 of
- * 2026-06-14-followup-frame-tile-legacy-aspect-and-live-toggle.md).
- *
- * These gate **only what is drawn live during recording** — they never change
- * what is captured (frame blobs, depth samples, occupancy data, GPS events all
- * continue regardless) and they never affect replay (where reviewing the
- * captured overlays is the whole point). Read once at Enter-AR: toggling
- * mid-session applies on the next Enter-AR, not retroactively.
- *
- * All four default ON, so adding this group is purely additive — every overlay
- * still renders until the operator opts out.
- */
-interface VisualizationOptions {
-  /** Live frame-tile planes (`FrameTileVisualizer`). Default: true */
-  frameTiles: boolean;
-  /** Voxel depth cubes (`OccupancyCubesVisualizer`). Default: true */
-  occupancyCubes: boolean;
-  /** Raw/fused/snapshot GPS+VIO alignment spheres (`GpsEventVisualizer`). Default: true */
-  gpsAlignmentMarkers: boolean;
-  /** N/E/S/W compass orientation cubes (`createGpsCompassCubes`). Default: true */
-  compassCubes: boolean;
-}
-/**
- * Configuration for live QR detection + RAW recording (decision §0 of the
- * recorder live-QR follow-up,
- * `2026-06-17-followup-recorder-live-qr-next-steps.md`).
- *
- * OPT-IN (`enabled` defaults to `false`): turning it on adds per-frame RGBA
- * capture + a `BarcodeDetector` decode to the session, so it is operator-gated
- * exactly like the heavy `depth`/`images` streams — an existing recording pays
- * nothing. When on, the producer dispatches one RAW `qrDetected/recordQrDetection`
- * action per accepted decode (size + pose are DERIVED on read, never recorded).
- */
-interface QrCaptureOptions {
-  /** Whether live QR detection + recording runs. Default: false (opt-in). */
-  enabled: boolean;
-  /**
-   * Capture / detection cadence in ms — the SINGLE cadence owner (the producer
-   * runs `minIntervalMs: 0`; this throttles the camera-frame source). Default
-   * 125 (~8 Hz), matching the QR demo's `DETECT_INTERVAL_MS`.
-   */
-  intervalMs: number;
-  /**
-   * RGBA capture long-edge in px. Larger = more decode range on a small/distant
-   * QR but a costlier blit + detect. Default 1024 (the on-device sweep settled
-   * here; 512 only decoded small QRs at very close range).
-   */
-  captureSize: number;
-}
-/**
- * User-configurable recording options.
- * Persisted to localStorage for cross-session consistency.
- */
-interface RecordingOptions {
-  /** Depth sampling configuration */
-  depth: DepthCaptureOptions;
-  /** Image capture configuration */
-  images: ImageCaptureOptions;
-  /** Diagnostic flags for pre-recording AR crash isolation */
-  arCrashIsolation: ArCrashIsolationOptions;
-  /** Derived occupancy-grid configuration (voxel size) */
-  occupancy: OccupancyOptions;
-  /** Frame-tile display-texture resolution (live + replay; capture unchanged) */
-  frameTileDisplay: FrameTileDisplayOptions;
-  /** Live AR debug-overlay visibility toggles (live-only; replay unaffected) */
-  visualization: VisualizationOptions;
-  /** Live QR detection + RAW recording configuration (opt-in) */
-  qr: QrCaptureOptions;
-}
-/**
- * localStorage key for persisted options.
- *
- * **Multi-tab caveat:** All tabs/instances sharing the same origin will
- * read and write this key. In multi-tab or embedded scenarios, concurrent
- * saves can silently overwrite each other. Use a custom `storageKey`
- * parameter in `loadRecordingOptions` / `saveRecordingOptions` to isolate
- * instances when needed.
- */
-declare const STORAGE_KEY = "gps-plus-slam-recorder-options";
-/** Default recording options (all streams enabled) */
-declare const DEFAULT_RECORDING_OPTIONS: RecordingOptions;
-/** Validation constraints for depth options */
-declare const DEPTH_CONSTRAINTS: {
-  readonly intervalMs: {
-    readonly min: 500;
-    readonly max: 5000;
-    readonly step: 100;
-  };
-  readonly gridSize: {
-    readonly min: 2;
-    readonly max: 32;
-    readonly step: 1;
-  };
-};
-/** Validation constraints for image options */
-declare const IMAGE_CONSTRAINTS: {
-  readonly intervalMs: {
-    readonly min: 1000;
-    readonly max: 10000;
-    readonly step: 500;
-  };
-  readonly quality: {
-    readonly min: 0.3;
-    readonly max: 1;
-    readonly step: 0.1;
-  };
-  readonly resolutionDivisor: {
-    readonly min: 1;
-    readonly max: 8;
-    readonly step: 1;
-  };
-};
-/**
- * Validation constraints for occupancy options.
- *
- * `cellSizeM` is clamped to 1–20 cm. The floor exists because cell count (and
- * therefore the cube `InstancedMesh`, the grid `Map`, and the COLMAP
- * `points3D` row count) scales as 1/cellSize³ — sub-centimetre voxels are both
- * a memory/perf cliff on a phone and below the depth sensor's noise floor.
- * Step is 1 cm (the settings slider operates in cm).
- */
-declare const OCCUPANCY_CONSTRAINTS: {
-  readonly cellSizeM: {
-    readonly min: 0.01;
-    readonly max: 0.2;
-    readonly step: 0.01;
-  };
-};
-/**
- * Validation constraints for the frame-tile display-resolution divisor.
- *
- * Clamped to 1–8 (full down to one-eighth per dimension), mirroring the capture
- * `IMAGE_CONSTRAINTS.resolutionDivisor` range so the settings slider behaves the
- * same. The intended stops are 1, 2, 4, 8 (full / half / quarter / eighth); the
- * divisor is rounded to an integer so the resize target dimensions stay clean.
- */
-declare const FRAME_TILE_DISPLAY_CONSTRAINTS: {
-  readonly divisor: {
-    readonly min: 1;
-    readonly max: 8;
-    readonly step: 1;
-  };
-};
-/**
- * Validation constraints for QR-capture options.
- *
- * `intervalMs` is clamped to 50–1000 ms (20 Hz down to 1 Hz): below ~50 ms the
- * detector cannot keep up and frames just queue; above 1 s tracking feels dead.
- * `captureSize` is clamped to 256–2048 px: under 256 even a near QR loses its
- * modules; over 2048 the blit + decode cost is not worth it on a phone. Both
- * back a settings slider so a corrupt stored value can never break capture.
- */
-declare const QR_CONSTRAINTS: {
-  readonly intervalMs: {
-    readonly min: 50;
-    readonly max: 1000;
-    readonly step: 25;
-  };
-  readonly captureSize: {
-    readonly min: 256;
-    readonly max: 2048;
-    readonly step: 128;
-  };
-};
-/**
- * Validate and normalize AR crash isolation flags.
- * Missing or invalid values fall back to defaults.
- */
-declare function validateArCrashIsolationOptions(options: Partial<ArCrashIsolationOptions>): ArCrashIsolationOptions;
-/**
- * Validate and normalize the live debug-overlay visibility toggles.
- * Each field is boolean-or-default (same policy as the AR-crash-isolation
- * flags): a missing, corrupted, or pre-feature persisted value falls back to
- * the ON default so an overlay is never silently disabled by bad input.
- */
-declare function validateVisualizationOptions(options: Partial<VisualizationOptions>): VisualizationOptions;
-/**
- * Validate and normalize QR-capture options. `enabled` is boolean-or-default
- * (a corrupt/pre-feature value falls back to the OFF default so QR never
- * silently turns ON); `intervalMs`/`captureSize` are clamped to
- * {@link QR_CONSTRAINTS}, with a `Number.isFinite` guard so a stored `NaN`
- * (which is `typeof 'number'` and survives `clamp`) falls back to the default
- * rather than breaking the camera-frame source.
- */
-declare function validateQrOptions(options: Partial<QrCaptureOptions>): QrCaptureOptions;
-/**
- * Validate and normalize depth options.
- * Invalid values are clamped to valid ranges.
- */
-declare function validateDepthOptions(options: Partial<DepthCaptureOptions>): DepthCaptureOptions;
-/**
- * Validate and normalize image options.
- * Invalid values are clamped to valid ranges.
- */
-declare function validateImageOptions(options: Partial<ImageCaptureOptions>): ImageCaptureOptions;
-/**
- * Validate and normalize occupancy options.
- * Invalid values are clamped to valid ranges.
- *
- * Note the explicit `Number.isFinite` guard: `OccupancyGrid` throws a
- * `RangeError` on a non-finite cell size, and `clamp(NaN, …)` would otherwise
- * pass `NaN` straight through (it is `typeof 'number'`). Falling back to the
- * default keeps a corrupted stored value from crashing grid construction.
- */
-declare function validateOccupancyOptions(options: Partial<OccupancyOptions>): OccupancyOptions;
-/**
- * Validate and normalize frame-tile display options. `divisor` is clamped to
- * {@link FRAME_TILE_DISPLAY_CONSTRAINTS} and rounded to an integer, with a
- * `Number.isFinite` guard so a stored `NaN` (which is `typeof 'number'` and
- * survives `clamp`) falls back to the default rather than producing a broken
- * resize target.
- */
-declare function validateFrameTileDisplayOptions(options: Partial<FrameTileDisplayOptions>): FrameTileDisplayOptions;
-/**
- * Validate and normalize a full RecordingOptions object.
- * Merges with defaults and clamps invalid values.
- */
-declare function validateRecordingOptions(options: RecordingOptionsInput): RecordingOptions;
-/**
- * Load recording options from localStorage.
- * Returns defaults if no saved options exist or parsing fails.
- * Validates and merges with defaults to handle schema evolution.
- * @param storageKey - Optional custom localStorage key (defaults to STORAGE_KEY).
- */
-declare function loadRecordingOptions(storageKey?: string): RecordingOptions;
-/**
- * Save recording options to localStorage.
- * Options are validated before saving.
- * @param storageKey - Optional custom localStorage key (defaults to STORAGE_KEY).
- */
-declare function saveRecordingOptions(options: RecordingOptions, storageKey?: string): void;
-/**
- * Reset recording options to defaults.
- * Clears localStorage and returns default options.
- * @param storageKey - Optional custom localStorage key (defaults to STORAGE_KEY).
- */
-declare function resetRecordingOptions(storageKey?: string): RecordingOptions;
-/**
- * Create a deep copy of recording options.
- * Useful for creating mutable copies of the frozen defaults.
- */
-declare function cloneRecordingOptions(options: RecordingOptions): RecordingOptions;
-//#endregion
-export { validateFrameTileDisplayOptions as C, validateRecordingOptions as D, validateQrOptions as E, validateVisualizationOptions as O, validateDepthOptions as S, validateOccupancyOptions as T, cloneRecordingOptions as _, FRAME_TILE_DISPLAY_CONSTRAINTS as a, saveRecordingOptions as b, ImageCaptureOptions as c, QR_CONSTRAINTS as d, QrCaptureOptions as f, VisualizationOptions as g, STORAGE_KEY as h, DepthCaptureOptions as i, OCCUPANCY_CONSTRAINTS as l, RecordingOptionsInput as m, DEFAULT_RECORDING_OPTIONS as n, FrameTileDisplayOptions as o, RecordingOptions as p, DEPTH_CONSTRAINTS as r, IMAGE_CONSTRAINTS as s, ArCrashIsolationOptions as t, OccupancyOptions as u, loadRecordingOptions as v, validateImageOptions as w, validateArCrashIsolationOptions as x, resetRecordingOptions as y };