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

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

@@ -0,0 +1,667 @@
+import { t as MotionFilterConfig } from "./capture-motion-gate-BGoAMkmf.js";
+import { a as QualityFilterConfig } from "./image-quality-BMx2ko9-.js";
+
+//#region ../src/state/recording-options.d.ts
+/**
+ * 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>;
+  compassDebug?: Partial<CompassDebugOptions>;
+}
+/**
+ * Toggles for the library's Phase-4 compass alignment features (closed/internal
+ * `AlignmentConfig` flags exposed via narrow boolean actions). They change how
+ * the LIVE alignment is computed, so they sit with the other capture groups.
+ * **Stage 0 (`coldStartOverride`) defaults ON** (a field-validated production
+ * feature); Stage C + the WebXR-consistency gate stay experimental (default
+ * OFF) until the §6a field-data matrix is in.
+ *
+ * On-device caveat: the resulting `gpsData` opt-in actions persist into the
+ * recording, so the DEFAULT `replayAll` re-enables them. This does NOT modify the
+ * raw recorded stream (`rawAbsoluteOrientation`, GPS, odometry) — only the
+ * *derived* alignment — so an investigation that re-solves from the raw
+ * observations under a chosen `AlignmentConfig` (`recomputeAlignment`) is
+ * unaffected by the capture-time flag state. Turning the flags off during capture
+ * only matters if you want the LIVE app to behave as the GPS-only baseline; it is
+ * not required for clean §6a analysis data. See
+ * `GpsPlusSlamJs_Docs/docs/2026-06-26-stage0-field-collection-and-enablement.md`
+ * (2026-07-01 update).
+ */
+interface CompassDebugOptions {
+  /** Stage 0 — cold-start compass yaw override (`setColdStartOverrideEnabled`). Default ON. */
+  coldStartOverride: boolean;
+  /** Stage C — trust-gated compass rotation prior (`setCompassRotationPriorEnabled`). */
+  rotationPrior: boolean;
+  /** GPS-free compass↔WebXR consistency gate (`setCompassWebXRConsistencyEnabled`). */
+  webXRConsistency: boolean;
+}
+/**
+ * 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: 500 (FAST-reconstruction tuning, 2026-07-01). */
+  intervalMs: number;
+  /**
+   * Grid size (N×N points per sample). Default: 32 (FAST-reconstruction
+   * tuning, 2026-07-01) — 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;
+  /**
+   * Motion gate — skip motion-blurred frames by deferring a due capture until
+   * device motion settles. Mirrors `ImageCaptureConfig.motionFilter` (the type
+   * the capture manager consumes); the recorder destructures `images` and flows
+   * the rest, including this group, through the capture seam. Default: enabled.
+   * See `ar/capture-motion-gate.ts` and
+   * `GpsPlusSlamJs_Docs/docs/2026-06-23-blurry-frame-motion-gating-plan.md`.
+   */
+  motionFilter: MotionFilterConfig;
+  /**
+   * Image-quality gate — drop a blurry/black frame (judged off-thread) and retry
+   * the next acceptable frame. Mirrors `ImageCaptureConfig.qualityFilter`; flows
+   * through the same capture seam as `motionFilter`. **Default: disabled**
+   * pending field tuning of the relative blur threshold (a mis-tuned gate
+   * silently dropping good frames is worse than the motion gate's default-on).
+   * See `ar/image-quality.ts` and
+   * `GpsPlusSlamJs_Docs/docs/2026-06-24-image-quality-gate-plan.md`.
+   */
+  qualityFilter: QualityFilterConfig;
+}
+/**
+ * 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.
+ */
+/**
+ * Mesher strategy for the **persistent occluder** mesh, exposed as a recorder
+ * setting (2026-06-30 occluder-tuning, F2/F2b) so the two surface-hugging
+ * approaches can be A/B-tested on-device against the blocky baseline:
+ * - `'greedy'` — blocky greedy cubes (the existing default; fewest triangles).
+ * - `'corner-fit'` — cubes with corners pulled to the measured centroids
+ *   (surface-hugging **and** watertight).
+ * - `'smooth'` — surface nets: smoothest, hugs the measured surface, but an open
+ *   sheet over thin features.
+ *
+ * Maps directly onto `meshOccupiedCells` / `OcclusionMesh` `MeshMode` (a subset).
+ * `'per-face'` is intentionally not offered (same shape as `'greedy'`, more
+ * triangles — no on-device value).
+ */
+declare const OCCLUDER_MESH_MODES: readonly ["greedy", "corner-fit", "smooth"];
+type OccluderMeshMode = (typeof OCCLUDER_MESH_MODES)[number];
+/**
+ * Debug-visualization style for the **persistent occluder** mesh (2026-07-02
+ * debug-viz-styles plan) — which visible debug skin(s) `OcclusionMesh` renders
+ * on top of the invisible depth-only occluder:
+ * - `'off'` — no debug rendering (the shipped default; occlusion is invisible).
+ * - `'matcap'` — the original shiny semi-transparent cyan skin.
+ * - `'depth-shaded'` — matcap + camera-distance fade + white fresnel rim, so
+ *   overlapping near/far surfaces read as separate shells.
+ * - `'wireframe'` — the raw triangulation as GL lines (mesh-structure
+ *   inspection: triangle density, mesher seams, degenerate spots).
+ * - `'depth-shaded-wireframe'` — both of the above composed.
+ *
+ * Values array module-private (validation only; the settings `<select>`
+ * options are hardcoded in the recorder's `index.html`), type exported —
+ * mirroring `OCCLUDER_MESH_MODES` / {@link OccluderMeshMode}.
+ */
+declare const OCCLUDER_DEBUG_STYLES: readonly ["off", "matcap", "depth-shaded", "wireframe", "depth-shaded-wireframe"];
+type OccluderDebugStyle = (typeof OCCLUDER_DEBUG_STYLES)[number];
+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;
+  /**
+   * Minimum observation count for a voxel to be trusted as occupied (the
+   * grid's `getOccupiedCells(minObservations)` floor, promoted to a user
+   * setting). A cell is marked occupied the instant one noisy depth point
+   * lands in it; raising this filters single-frame depth noise — in
+   * particular the **behind-surface** phantoms (e.g. below the floor) that
+   * free-space carving can never clear because no ray passes through occluded
+   * space. Default 3 (1 = unfiltered/legacy). Higher = less noise but
+   * briefly-glimpsed real surfaces may be dropped, so it is exposed for
+   * on-device tuning. Read once when the visualizer is constructed (Enter-AR
+   * / replay load). See
+   * `GpsPlusSlamJs_Docs/docs/2026-06-22-occupancy-grid-behind-surface-noise-plan.md`.
+   */
+  minConfidence: number;
+  /**
+   * Render a **persistent depth-only occlusion mesh** of the occupancy grid:
+   * the grid's occupied cells are meshed (`meshOccupiedCells`) and drawn
+   * invisible-but-depth-writing under `arWorldGroup`, so real geometry the
+   * camera saw earlier hides virtual objects placed behind it — including
+   * out-of-view surfaces a live depth occluder cannot remember. Default
+   * **true** (since 2026-07-01): the Web-Worker mesh offload removed the
+   * per-refresh render stall that was the reason to keep it opt-in, so the
+   * remembered occluder ships on by the default `'smooth'` mesher. Read once when
+   * the mesh is wired (Enter-AR / replay load), like the other occupancy knobs.
+   * See `GpsPlusSlamJs_Docs/docs/2026-06-13-occupancy-mesh-options-plan.md` and
+   * `GpsPlusSlamJs_Docs/docs/2026-07-01-occluder-worker-and-chunked-remesh-plan.md`.
+   *
+   * **Migration:** this field replaces the former `occlusionMeshEnabled`
+   * boolean — `validateOccupancyOptions` maps a persisted
+   * `occlusionMeshEnabled === true` onto `persistentOcclusion` (see that
+   * function and `2026-06-29-occupancy-mesh-followups.md`).
+   */
+  persistentOcclusion: boolean;
+  /**
+   * Enable the **live CPU-depth occluder** — a per-frame depth occluder that
+   * hides virtual content behind the real surface the camera sees *right now*,
+   * sharp and registration-free (no out-of-view memory). It composes with
+   * {@link persistentOcclusion}: both can be on (the live occluder wins where
+   * this frame has depth, the persistent mesh fills out-of-view / depth holes —
+   * `2026-06-14-webxr-depth-occlusion-plan.md` §5). Requires the
+   * `requestDepthOcclusion` session feature so `cpu-optimized` depth is
+   * negotiated even without depth recording. **Live-AR only** — replay has no
+   * live depth stream, so this flag is a no-op there (persistent still applies).
+   * Default **false**: the live occluder's on-device occlusion quality is still
+   * device-gated/unverified. Read once when the AR session is wired (Enter-AR).
+   */
+  liveOcclusion: boolean;
+  /**
+   * Which **visible debug skin(s)** render the persistent occluder mesh (see
+   * {@link OccluderDebugStyle}) so its shape/structure can be judged on-device.
+   * All styles are additive overlays — the invisible depth-only mesh keeps
+   * writing depth unchanged, so occlusion is identical in every style. Only has
+   * a visible effect when {@link persistentOcclusion} is on (it is that
+   * occluder's mesh); any other value is a harmless no-op. Default **`'off'`**.
+   * Read once when the mesh is wired (Enter-AR / replay load), like the other
+   * occupancy knobs. See
+   * `GpsPlusSlamJs_Docs/docs/2026-07-02-occluder-debug-viz-styles-plan.md` and
+   * `GpsPlusSlamJs_Docs/docs/2026-06-29-occlusion-debug-viz-and-live-occluder-user-feedback.md`.
+   *
+   * **Migration:** this field replaces the former `occluderDebugViz` boolean —
+   * `validateOccupancyOptions` maps a persisted `occluderDebugViz: true` onto
+   * `'matcap'` (the skin the boolean used to enable) when this field is absent,
+   * mirroring the `occlusionMeshEnabled` → {@link persistentOcclusion}
+   * migration.
+   */
+  occluderDebugStyle: OccluderDebugStyle;
+  /**
+   * Which mesher builds the **persistent occluder** mesh (see
+   * {@link OccluderMeshMode}). Default `'smooth'` (since 2026-07-01) — Naive
+   * Surface Nets, the smoothest and lightest mesh. Switch to `'greedy'` (blocky
+   * cubes, watertight) or `'corner-fit'` (surface-hugging + watertight) if the
+   * smooth mesh's open concave seams leak occlusion in practice (combine with
+   * {@link occluderDebugStyle} to actually *see* the mesh shape). Only has an
+   * effect when {@link persistentOcclusion} is on. Read once when the mesh is
+   * wired (Enter-AR / replay load), like the other occupancy knobs. See
+   * `GpsPlusSlamJs_Docs/docs/2026-06-30-occluder-tuning-followups.md`.
+   */
+  occluderMeshMode: OccluderMeshMode;
+  /**
+   * Camera-local window for the **persistent occluder** snapshot (Step 2 of
+   * the 2026-07-03 long-session fps plan): each re-mesh reads only the
+   * occupied cells within this many meters of the camera
+   * (`OccupancyGrid.getOccupiedCellsWithinFlat`), so snapshot/pack/mesh cost
+   * is bounded by the neighbourhood instead of the whole session. Default
+   * **25 m** — a 15 cm voxel at 25 m subtends ~0.3°, so occlusion errors
+   * beyond that are imperceptible. `0` = unbounded (the pre-Step-2
+   * behaviour, the safe fallback). The grid forgets nothing: walking back
+   * re-meshes far geometry from memory — exactly the persistent-grid intent.
+   * Only has an effect when {@link persistentOcclusion} is on. Read once at
+   * Enter-AR / replay load like the other occupancy knobs.
+   */
+  occluderRadiusM: 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;
+  /**
+   * FIFO cap on the **live** frame-tile planes (Step 4 of the 2026-07-03
+   * long-session fps plan): adding a tile over the cap removes + disposes the
+   * oldest, bounding draw calls / GPU texture memory / scene-graph size for
+   * arbitrarily long sessions while keeping the recent-path breadcrumb.
+   * `0` = unlimited. Default 100 (a ~5-min walk captures 112–145 frames, so
+   * the cap binds on real walks). **Live only** (2026-07-03 interview): in
+   * replay the tiles audit coverage of the full recorded path, so the replay
+   * wiring stays uncapped regardless of this value.
+   */
+  maxTiles: 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, with one exception, 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.
+ *
+ * The debug overlays default ON, so the group is purely additive — every
+ * overlay still renders until the operator opts out. The exception on both
+ * counts is {@link VisualizationOptions.statsOverlay}: a perf-measurement tool
+ * that defaults OFF and, when on, also runs in replay (see its docs).
+ */
+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;
+  /**
+   * Rotate the live in-AR minimap so the user's view direction always points
+   * up/forward (heading-up) instead of fixed north-up. Unlike the other flags
+   * in this group this is a map-orientation preference, not a show/hide — but it
+   * shares their live-only semantics (read at Enter-AR, never affects replay).
+   * Default: true. See the 2026-06-29 heading-up plan.
+   */
+  headingUpMap: boolean;
+  /**
+   * Performance stats overlay (Stats.js: FPS / frame ms / MB panels) for
+   * long-session fps attribution (2026-07-03 long-session fps plan §0).
+   * Two exceptions to this group's rules: it is a debug tool, so it defaults
+   * **OFF** (must not cost the default path), and unlike the live-only
+   * overlays it also runs in **replay** (frame time matters there too).
+   * In immersive AR it composites via the dom-overlay feature, so it is
+   * invisible when `arCrashIsolation.enableDomOverlay` is off.
+   */
+  statsOverlay: 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;
+  /** Compass alignment debug toggles (Stage 0 / Stage C / consistency gate) */
+  compassDebug: CompassDebugOptions;
+}
+/**
+ * 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: 64;
+    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 the motion-filter (blurry-frame gate) thresholds.
+ *
+ * The velocity ranges (0.05–5) bracket the plausible scanning regime: below
+ * ~0.05 the gate would reject almost everything; above ~5 rad/s ≈ 286°/s (or
+ * 5 m/s) it would never reject, so the gate would be inert. `maxWaitMs` is
+ * clamped to 0.5–20 s — the never-calm fallback must always be able to fire.
+ * All three back a (currently advanced/hidden) settings slider, so a corrupt
+ * stored value can never disable capture. The default thresholds themselves are
+ * placeholders pending on-device field tuning (plan §7).
+ */
+declare const MOTION_FILTER_CONSTRAINTS: {
+  readonly maxAngularVelocity: {
+    readonly min: 0.05;
+    readonly max: 5;
+    readonly step: 0.05;
+  };
+  readonly maxLinearVelocity: {
+    readonly min: 0.05;
+    readonly max: 5;
+    readonly step: 0.05;
+  };
+  readonly maxWaitMs: {
+    readonly min: 500;
+    readonly max: 20000;
+    readonly step: 500;
+  };
+};
+/**
+ * Validation constraints for the image-quality (blur/blackness) gate thresholds.
+ *
+ * `blurRelativeThreshold` (`k` in `sharpness < k·median`) is clamped to
+ * 0.05–0.95: it is a fraction of the recent sharpness median, so values must sit
+ * strictly inside (0, 1) — at ~0 the blur check never rejects, near 1 it rejects
+ * almost everything. `minMeanLuminance` (the absolute black cutoff on a 0–255
+ * luma scale) is clamped to 0–128: 0 disables the black check, and a cutoff
+ * above mid-grey would reject normally-lit frames. `maxWaitMs` mirrors the motion
+ * gate's range (0.5–20 s) so the never-good fallback can always fire. All back a
+ * (currently advanced/hidden) settings slider, so a corrupt stored value can
+ * never disable capture. The default thresholds are placeholders pending
+ * on-device field tuning (plan §5, §10).
+ */
+declare const QUALITY_FILTER_CONSTRAINTS: {
+  readonly blurRelativeThreshold: {
+    readonly min: 0.05;
+    readonly max: 0.95;
+    readonly step: 0.05;
+  };
+  readonly minMeanLuminance: {
+    readonly min: 0;
+    readonly max: 128;
+    readonly step: 1;
+  };
+  readonly maxWaitMs: {
+    readonly min: 500;
+    readonly max: 20000;
+    readonly step: 500;
+  };
+};
+/**
+ * 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).
+ *
+ * `minConfidence` is clamped to 1–10 (integer). 1 disables the filter (legacy
+ * behaviour: a single observation counts as occupied); the ceiling exists
+ * because real surfaces accumulate only a handful of observations per second
+ * of dwell, so a floor above ~10 would start hiding genuine geometry.
+ */
+declare const OCCUPANCY_CONSTRAINTS: {
+  readonly cellSizeM: {
+    readonly min: 0.01;
+    readonly max: 0.2;
+    readonly step: 0.01;
+  };
+  readonly minConfidence: {
+    readonly min: 1;
+    readonly max: 10;
+    readonly step: 1;
+  };
+  readonly occluderRadiusM: {
+    readonly min: 0;
+    readonly max: 200;
+    readonly step: 5;
+  };
+};
+/**
+ * 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;
+  };
+  readonly maxTiles: {
+    readonly min: 0;
+    readonly max: 2000;
+    readonly step: 10;
+  };
+};
+/**
+ * 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 compass alignment debug toggles. Boolean-or-default
+ * per field; a missing/corrupted/pre-feature value falls back to the OFF default
+ * so a bad persisted value can never silently turn an alignment override ON.
+ */
+declare function validateCompassDebugOptions(options: Partial<CompassDebugOptions>): CompassDebugOptions;
+/**
+ * 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 the motion-filter (blurry-frame gate) options.
+ * `enabled` is boolean-or-default; the three numeric thresholds are clamped to
+ * {@link MOTION_FILTER_CONSTRAINTS} with a `Number.isFinite` guard (a stored
+ * `NaN` is `typeof 'number'` and would survive `clamp`). A missing group
+ * default-fills entirely — a pre-feature persisted options object that lacks
+ * `motionFilter` therefore loads with the gate enabled rather than crashing.
+ */
+declare function validateMotionFilterOptions(options: Partial<MotionFilterConfig>): MotionFilterConfig;
+/**
+ * Validate and normalize the image-quality (blur/blackness gate) options. Same
+ * policy as {@link validateMotionFilterOptions}: `enabled` is boolean-or-default;
+ * the three numeric thresholds are clamped to {@link QUALITY_FILTER_CONSTRAINTS}
+ * with a `Number.isFinite` guard (a stored `NaN` is `typeof 'number'` and would
+ * survive `clamp`). A missing group default-fills entirely — a pre-feature
+ * persisted options object that lacks `qualityFilter` loads with the gate
+ * disabled (the safe default) rather than crashing.
+ */
+declare function validateQualityFilterOptions(options: Partial<QualityFilterConfig>): QualityFilterConfig;
+/**
+ * Validate and normalize image options.
+ * Invalid values are clamped to valid ranges.
+ */
+declare function validateImageOptions(options: Partial<ImageCaptureOptions>): ImageCaptureOptions;
+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 { validateImageOptions as A, loadRecordingOptions as C, validateCompassDebugOptions as D, validateArCrashIsolationOptions as E, validateRecordingOptions as F, validateVisualizationOptions as I, validateOccupancyOptions as M, validateQrOptions as N, validateDepthOptions as O, validateQualityFilterOptions as P, cloneRecordingOptions as S, saveRecordingOptions as T, QrCaptureOptions as _, DepthCaptureOptions as a, STORAGE_KEY as b, IMAGE_CONSTRAINTS as c, OCCUPANCY_CONSTRAINTS as d, OccluderDebugStyle as f, QUALITY_FILTER_CONSTRAINTS as g, QR_CONSTRAINTS as h, DEPTH_CONSTRAINTS as i, validateMotionFilterOptions as j, validateFrameTileDisplayOptions as k, ImageCaptureOptions as l, OccupancyOptions as m, CompassDebugOptions as n, FRAME_TILE_DISPLAY_CONSTRAINTS as o, OccluderMeshMode as p, DEFAULT_RECORDING_OPTIONS as r, FrameTileDisplayOptions as s, ArCrashIsolationOptions as t, MOTION_FILTER_CONSTRAINTS as u, RecordingOptions as v, resetRecordingOptions as w, VisualizationOptions as x, RecordingOptionsInput as y };

package/dist/{recording-replayer-CUEK82tM.d.ts → recording-replayer-D0V9WkmY.d.ts}

@@ -1,5 +1,5 @@
-import { L as CombinedRootState } from "./create-slam-app-store-Ce2FMKCp.js";
-import { i as RecordedAction } from "./zip-reader-Q2ue6zlC.js";
+import { N as CombinedRootState } from "./create-slam-app-store-D3nzh9Wb.js";
+import { i as RecordedAction } from "./zip-reader-CvruaGvD.js";
 
 //#region ../src/state/recording-replayer.d.ts
 /**

package/dist/{recording-slice-B-uCgGoh.d.ts → recording-slice-DTUtSVgd.d.ts}

@@ -1,5 +1,5 @@
-import { i as DepthSample } from "./ar-types-BckI1E-O.js";
-import { p as RecordingOptions } from "./recording-options-D93kksJU.js";
+import { i as DepthSample } from "./ar-types-Cc5yvBwn.js";
+import { v as RecordingOptions } from "./recording-options-vASCFzc5.js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 
 //#region ../src/state/recording-slice.d.ts