gps-plus-slam-app-framework 1.3.0 → 1.7.0

package/dist/qr-size-measurer-DQdAsid1.d.ts

@@ -0,0 +1,165 @@
+import { r as DepthPoint } from "./ar-types-BFX2r1wk.js";
+import { t as DepthUnprojector } from "./depth-unprojection-DjsbJW9L.js";
+import { r as Point2 } from "./qr-pose-D2rfu5DA.js";
+import { Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-size-from-depth.d.ts
+/** Where the size lifecycle currently sits for one marker (Note 3 / Note 4). */
+type QrSizeStatus = /** No size authored and none measured yet — size-dependent features blocked. */'unknown' /** Measurements are accumulating but the estimate has not converged. */ | 'measuring' /** A reliably-estimated (or authored) size — size-dependent features unlock. */ | 'estimated';
+/** Per-marker physical-size estimate (drives the Note 3 size lifecycle). */
+interface QrSizeEstimate {
+  status: QrSizeStatus;
+  /** Running median side length, meters, or `null` while unknown. */
+  estimateM: number | null;
+  /** How many accepted samples back the estimate. */
+  sampleCount: number;
+  /**
+   * Robust confidence half-width of the estimate, meters (`1.4826·MAD/√N`), so
+   * it TIGHTENS as samples accumulate (WS-B) — not the raw max−min. 0 when <2
+   * samples. The HUD renders this as the shrinking `±mm`.
+   */
+  spreadM: number;
+}
+/** One per-observation size read from a single detection's depth samples. */
+interface QrSizeObservation {
+  /** Median of the 4 unprojected edge lengths, meters. */
+  sizeM: number;
+  /** Consistency score in [0,1]; 1 = a perfect planar square facing the camera. */
+  quality: number;
+}
+/**
+ * Estimate a QR's physical side length from one detection's depth samples.
+ *
+ * @param corners - the 4 corner depth samples, ordered TL, TR, BR, BL (matching
+ *   `buildObjectPoints` / the detector corner-order normalization).
+ * @param interiorSamples - a few interior depth samples (may be empty); used
+ *   only to strengthen the planarity check against corner edge depth-bleed.
+ * @param unprojector - built once per depth sample via `createDepthUnprojector`.
+ * @returns `{ sizeM, quality }`, or `null` when a corner cannot be unprojected
+ *   or the quad is degenerate (collinear / zero-area).
+ */
+declare function estimateQrSizeFromDepth(corners: readonly [DepthPoint, DepthPoint, DepthPoint, DepthPoint], interiorSamples: readonly DepthPoint[], unprojector: DepthUnprojector): QrSizeObservation | null;
+interface QrSizeAccumulatorOptions {
+  /** Minimum observation quality to ACCEPT a sample. Default 0.8. */
+  qualityThreshold?: number;
+  /** Accepted samples required before the estimate can be `estimated`. Default 8. */
+  minSamples?: number;
+  /**
+   * Max confidence half-width (`spreadM`, m) allowed for the `estimated` status.
+   * Default 0.01. `spreadM` is a robust standard-error (`1.4826·MAD/√N`) that
+   * TIGHTENS as samples accumulate — not the raw max−min — so it converges
+   * instead of being pinned by one early stray.
+   */
+  maxSpreadM?: number;
+  /**
+   * Optional cap on retained accepted sizes. **Default: unbounded** (lifelong
+   * refinement — WS-B). The QR's physical size never changes, so keeping the
+   * full session history lets the robust median tighten the longer the QR is
+   * seen. Set a finite cap only if memory/perf demands a bounded window; the
+   * estimate then becomes a sliding-window median again.
+   */
+  maxSamples?: number;
+}
+interface QrSizeAccumulator {
+  /**
+   * Offer one observation (or `null` for a failed read). Low-quality / null
+   * observations are ignored. Returns the updated {@link QrSizeEstimate}.
+   */
+  add(observation: QrSizeObservation | null): QrSizeEstimate;
+  /** The current estimate without adding a sample. */
+  current(): QrSizeEstimate;
+  /** Drop all samples back to `unknown`. */
+  reset(): void;
+}
+declare function createQrSizeAccumulator(options?: QrSizeAccumulatorOptions): QrSizeAccumulator;
+//#endregion
+//#region ../src/ar/qr-size-measurer.d.ts
+/**
+ * Robustness knobs for the depth-at-corners stage (on top of the accumulator
+ * options). QR corners sit on a high-contrast print boundary where the coarse
+ * WebXR depth grid often has no near reading; these let a measurement still
+ * succeed instead of returning `null` every frame.
+ */
+interface QrSizeMeasurerOptions extends QrSizeAccumulatorOptions {
+  /**
+   * Points-per-side of the interior depth lattice sampled across the QR quad for
+   * the PRIMARY dense plane-fit estimate (WS-A). `latticeSize × latticeSize`
+   * points are sampled strictly inside the quad; reads with no depth are
+   * skipped. Default `7` (≤49 reads). Set to a small value (or rely on the
+   * corner fallback) to disable dense sampling. See {@link estimateQrSizeFromDepthDense}.
+   */
+  latticeSize?: number;
+  /**
+   * When a corner pixel has no depth, retry at points inset toward the centroid
+   * by these fractions (in order) and borrow the first valid depth — keeping the
+   * TRUE corner screen position so the measured size is not shrunk. Default
+   * `[0.12, 0.25]`. Set to `[]` to disable inset fallback. Used by the corner-
+   * based FALLBACK estimate (when the interior lattice is too sparse for a fit).
+   */
+  cornerInsetFractions?: number[];
+  /**
+   * Max corners whose depth may be reconstructed by a planar fit through the
+   * other three when still missing after the inset fallback. Default `1`
+   * (tolerate one un-sampleable corner); `0` disables reconstruction. Used by
+   * the corner-based FALLBACK estimate.
+   */
+  maxReconstructedCorners?: number;
+}
+/** The per-frame depth access the measurer needs (a subset of the demo's `DepthContext`). */
+interface QrSizeDepthContext {
+  /** Depth (m) at a normalized screen point, or `null` if unavailable there. */
+  depthAt: (screenX: number, screenY: number) => number | null;
+  /** Unprojector for the current depth sample (`createDepthUnprojector`). */
+  unprojector: DepthUnprojector;
+}
+/** Minimal frame dimensions needed to normalize pixel corners to screen coords. */
+interface ImageSize {
+  width: number;
+  height: number;
+}
+/** One measurement: the accumulated estimate plus the raw depth samples used. */
+interface QrSizeMeasurement {
+  /** The per-marker running estimate AFTER folding in this observation. */
+  estimate: QrSizeEstimate;
+  /**
+   * The 4 corner depth samples (detector order, normalized screen coords),
+   * best-effort. `null` when corner depth could not be sampled (e.g. a small QR
+   * whose corners fall between depth nodes) but the dense interior fit still
+   * produced an estimate — the dense path does not need corner depths.
+   */
+  cornerSamples: [DepthPoint, DepthPoint, DepthPoint, DepthPoint] | null;
+  /**
+   * The interior depth reads used for the estimate: the dense lattice on the
+   * primary path, or the single centroid sample on the corner-based fallback
+   * (may be empty).
+   */
+  interiorSamples: DepthPoint[];
+}
+interface QrSizeMeasurer {
+  /**
+   * Measure one detection's size from depth and fold it into the per-`text`
+   * accumulator. The PRIMARY path is the dense plane fit (WS-A): sample an
+   * interior lattice, fit the QR plane, recover the corners by ray-plane
+   * intersection. When the lattice is too sparse for a fit it FALLS BACK to the
+   * corner-based estimate (corner depths + inset/reconstruct robustness).
+   *
+   * Returns `null` only when neither path can run — `corners.length !== 4`, or
+   * the interior lattice yields too few reads AND the corner depths cannot be
+   * sampled (≥2 corners missing). A degenerate quad does not throw: the (null)
+   * observation is simply not accumulated and the prior estimate stands.
+   */
+  measure(text: string, corners: readonly Point2[], image: ImageSize, ctx: QrSizeDepthContext): QrSizeMeasurement | null;
+  /** Current estimate for a marker without adding a sample. */
+  current(text: string): QrSizeEstimate;
+  /** Drop one marker's samples (`text` given) or all of them. */
+  reset(text?: string): void;
+}
+/**
+ * Create a size measurer. Accumulator `options` (quality threshold, min samples,
+ * spread, cap) are forwarded to every per-marker {@link createQrSizeAccumulator};
+ * the depth-at-corners knobs ({@link QrSizeMeasurerOptions.cornerInsetFractions},
+ * {@link QrSizeMeasurerOptions.maxReconstructedCorners}) tune corner sampling.
+ */
+declare function createQrSizeMeasurer(options?: QrSizeMeasurerOptions): QrSizeMeasurer;
+//#endregion
+export { QrSizeMeasurerOptions as a, QrSizeAccumulatorOptions as c, QrSizeStatus as d, createQrSizeAccumulator as f, QrSizeMeasurer as i, QrSizeEstimate as l, QrSizeDepthContext as n, createQrSizeMeasurer as o, estimateQrSizeFromDepth as p, QrSizeMeasurement as r, QrSizeAccumulator as s, ImageSize as t, QrSizeObservation as u };

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

@@ -0,0 +1,514 @@
+import { t as MotionFilterConfig } from "./capture-motion-gate-0Yl2NpQG.js";
+import { a as QualityFilterConfig } from "./image-quality-smCBoFj1.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` actions persist into the recording,
+ * so a replay re-enables them. Record §6a field-calibration sets with
+ * `coldStartOverride` OFF so the captured compass behaviour is unmodified.
+ */
+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: 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;
+  /**
+   * 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.
+ */
+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;
+}
+/**
+ * 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;
+  /** 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: 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 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;
+  };
+};
+/**
+ * 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 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;
+/**
+ * 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 { validateOccupancyOptions as A, saveRecordingOptions as C, validateFrameTileDisplayOptions as D, validateDepthOptions as E, validateQualityFilterOptions as M, validateRecordingOptions as N, validateImageOptions as O, validateVisualizationOptions as P, resetRecordingOptions as S, validateCompassDebugOptions as T, RecordingOptionsInput as _, DepthCaptureOptions as a, cloneRecordingOptions as b, IMAGE_CONSTRAINTS as c, OCCUPANCY_CONSTRAINTS as d, OccupancyOptions as f, RecordingOptions as g, QrCaptureOptions as h, DEPTH_CONSTRAINTS as i, validateQrOptions as j, validateMotionFilterOptions as k, ImageCaptureOptions as l, QUALITY_FILTER_CONSTRAINTS as m, CompassDebugOptions as n, FRAME_TILE_DISPLAY_CONSTRAINTS as o, QR_CONSTRAINTS as p, DEFAULT_RECORDING_OPTIONS as r, FrameTileDisplayOptions as s, ArCrashIsolationOptions as t, MOTION_FILTER_CONSTRAINTS as u, STORAGE_KEY as v, validateArCrashIsolationOptions as w, loadRecordingOptions as x, VisualizationOptions as y };

package/dist/{recording-replayer-r0DZ9ALp.d.ts → recording-replayer-DQKpAGyQ.d.ts}

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