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

package/dist/image-quality-smCBoFj1.d.ts

@@ -0,0 +1,158 @@
+//#region ../src/ar/image-quality.d.ts
+/**
+ * Image-quality metrics + the drop/retry verdict policy for the image-content
+ * capture gate (blur + blackness), the increment layered ON TOP of the motion
+ * gate (`capture-motion-gate.ts`).
+ *
+ * Everything here is **pure and deterministic** — plain typed-array math plus a
+ * tiny rolling-history class. There is **no DOM and no Web Worker** in this
+ * module: it is fully unit-testable with synthetic buffers, and the recorder's
+ * `image-quality.worker.ts` is a thin shell that decodes a frame to pixels and
+ * calls into these functions. Keeping the verdict/history policy here (rather
+ * than inside the worker, as the original plan §8 sketched) honours the project
+ * rule that no untested logic ships: the worker is the device layer and is not
+ * unit-built, so the median/threshold decision must live where tests can pin it.
+ *
+ * Metrics:
+ *  - {@link sharpnessScore} — variance of the Laplacian over a grayscale buffer
+ *    (the standard Pech-Pacheco focus measure). Scene-dependent in absolute
+ *    terms, so the gate compares it RELATIVE to a rolling median (§5).
+ *  - {@link meanLuminance} — mean Rec. 601 luma of an RGBA buffer. Near-zero ⇒
+ *    black/empty frame; an absolute cutoff is safe because "black is black"
+ *    regardless of scene texture (§5).
+ *
+ * @see GpsPlusSlamJs_Docs/docs/2026-06-24-image-quality-gate-plan.md
+ * @see ./capture-motion-gate.ts — the motion gate this builds on (same shape:
+ *   a shared config type + a small stateful window + a pure decision).
+ */
+/**
+ * User-/consumer-facing configuration for the image-quality gate. Shared by both
+ * config shapes that carry it — `ImageCaptureConfig` (what `ImageCaptureManager`
+ * consumes) and `ImageCaptureOptions` (the persisted recorder options) — so the
+ * one definition cannot drift between them, exactly as `MotionFilterConfig` is
+ * shared (see `capture-motion-gate.ts` and the motion-gate follow-up §3).
+ */
+interface QualityFilterConfig {
+  /** Master switch for the image-quality gate. Default `false` (see below). */
+  enabled: boolean;
+  /**
+   * Blur cutoff as a fraction `k` of the recent sharpness median: a frame is
+   * judged blurry when its sharpness `< k · median(recent)`. ~0.5 is a sensible
+   * start. Relative (not absolute) because variance-of-Laplacian is
+   * scene-dependent — a correctly-focused blank wall scores low (§5).
+   */
+  blurRelativeThreshold: number;
+  /**
+   * Absolute black cutoff on a 0–255 luma scale: a frame whose mean luminance is
+   * below this is judged black/empty and dropped. Absolute is safe because black
+   * is black regardless of scene (§5). Supersedes the byte-size
+   * `MIN_VALID_IMAGE_BYTES` heuristic for correctness (kept as a cheap
+   * pre-filter).
+   */
+  minMeanLuminance: number;
+  /**
+   * Never-good safety fallback: once a due capture has been retried for this many
+   * ms without an acceptable frame, the next frame is saved regardless of the
+   * image verdict, so a recording interval is never silently lost (mirrors the
+   * motion gate's `maxWaitMs`). A sensible value is ~2× the capture interval.
+   */
+  maxWaitMs: number;
+}
+/**
+ * Default image-quality configuration. **Disabled by default** (plan §10): the
+ * relative blur threshold is unvalidated, and a mis-tuned gate silently dropping
+ * good frames for every consumer app is worse than the motion gate's low-risk
+ * default-on. Flip to `true` once the thresholds are field-tuned. The numeric
+ * values are PLACEHOLDERS pending on-device tuning (record measured values in
+ * implementation-progress.md). `maxWaitMs` of 4000 ms is 2× the default 2000 ms
+ * image interval.
+ */
+declare const DEFAULT_QUALITY_FILTER: QualityFilterConfig;
+/** Default number of recent (non-black) sharpness scores the gate keeps. */
+declare const DEFAULT_SHARPNESS_HISTORY_SIZE = 15;
+/**
+ * Default minimum samples before the relative blur check engages. Below this the
+ * gate is in "cold start" and accepts every non-black frame — the same
+ * "no baseline yet ⇒ don't block" principle the motion gate uses for an empty
+ * window.
+ */
+declare const DEFAULT_SHARPNESS_MIN_SAMPLES = 3;
+/**
+ * Compute the **variance of the Laplacian** of a single-channel grayscale image
+ * — the standard focus measure (higher ⇒ sharper / more in-focus).
+ *
+ * The discrete Laplacian per interior pixel is
+ * `up + down + left + right − 4·centre` (the 4-neighbour kernel); the score is
+ * the variance of that response over all interior pixels. A flat/constant image
+ * yields 0; a focused, textured image yields a large value.
+ *
+ * Defensive: returns `0` (rather than throwing or `NaN`) for any input that has
+ * no interior pixels — non-integer or `< 3` dimensions, or a buffer shorter than
+ * `width · height`. A tiny negative variance from floating-point cancellation is
+ * clamped to 0.
+ *
+ * @param gray  Row-major single-channel intensities, length ≥ `width · height`.
+ * @param width  Image width in pixels.
+ * @param height Image height in pixels.
+ */
+declare function sharpnessScore(gray: Uint8Array | Uint8ClampedArray | readonly number[], width: number, height: number): number;
+/**
+ * Convert an RGBA buffer to a single-channel grayscale (Rec. 601 luma) buffer,
+ * the input {@link sharpnessScore} expects. Pure; ignores the alpha channel. A
+ * partial trailing pixel (length not a multiple of 4) is ignored.
+ */
+declare function rgbaToGrayscale(rgba: Uint8Array | Uint8ClampedArray): Uint8ClampedArray;
+/**
+ * Mean Rec. 601 luma (`0.299R + 0.587G + 0.114B`) over an RGBA buffer, on a
+ * 0–255 scale. Near-zero ⇒ black/empty frame. Alpha is ignored. Returns `0` for
+ * an empty buffer.
+ */
+declare function meanLuminance(rgba: Uint8Array | Uint8ClampedArray): number;
+/** Reason a frame was rejected by the quality gate, or `null` when accepted. */
+type QualityRejectReason = 'black' | 'blurry';
+/** Outcome of evaluating one frame against the quality gate. */
+interface QualityVerdict {
+  /** `true` to save the frame, `false` to drop + retry. */
+  readonly accept: boolean;
+  /** Why it was dropped, or `null` when accepted. */
+  readonly reason: QualityRejectReason | null;
+  /** The frame's variance-of-Laplacian sharpness (for logging/tuning). */
+  readonly sharpness: number;
+  /** The frame's mean luminance (for logging/tuning). */
+  readonly meanLuminance: number;
+}
+/**
+ * The self-calibrating blur+blackness verdict, with the rolling sharpness
+ * history that makes the blur check scene-relative (§5). Stateful but pure (no
+ * DOM/worker): one instance per recording session, fed each analysed frame's
+ * metrics.
+ *
+ * Policy per frame ({@link evaluate}):
+ *  1. **Blackness — absolute.** `meanLuminance < config.minMeanLuminance` ⇒
+ *     reject `'black'`. The score is NOT recorded (a black frame's ~0 sharpness
+ *     must not drag the median down and disarm the blur check).
+ *  2. **Blur — relative.** Once at least `minSamples` non-black frames have been
+ *     seen, reject `'blurry'` when `sharpness < blurRelativeThreshold · median`.
+ *     Before that (cold start) every non-black frame is accepted.
+ *  3. The non-black frame's sharpness is recorded into the rolling window
+ *     (capped at `historySize`) so the median tracks the scene's texture level —
+ *     including a genuinely softening scene, which gradually lowers the bar (the
+ *     §10 "retry storm" regime where the fallback then guarantees progress).
+ */
+declare class ImageQualityGate {
+  private readonly history;
+  private readonly historySize;
+  private readonly minSamples;
+  constructor(historySize?: number, minSamples?: number);
+  /**
+   * Judge one frame from its precomputed metrics + the current config, updating
+   * the rolling history. See the class doc for the policy.
+   */
+  evaluate(sharpness: number, meanLum: number, config: QualityFilterConfig): QualityVerdict;
+  /** Number of (non-black) sharpness samples currently retained. */
+  historyLength(): number;
+  /** Clear the rolling history (e.g. on a new recording session). */
+  reset(): void;
+}
+//#endregion
+export { QualityFilterConfig as a, meanLuminance as c, ImageQualityGate as i, rgbaToGrayscale as l, DEFAULT_SHARPNESS_HISTORY_SIZE as n, QualityRejectReason as o, DEFAULT_SHARPNESS_MIN_SAMPLES as r, QualityVerdict as s, DEFAULT_QUALITY_FILTER as t, sharpnessScore as u };

package/dist/index-BAPokxMb.d.ts

@@ -0,0 +1,22 @@
+import { ReadonlyQuat } from "gl-matrix";
+
+//#region ../src/utils/geodesic-angle.d.ts
+/**
+ * Geodesic (shortest-arc) rotation angle in radians between two **unit**
+ * quaternions.
+ *
+ * Uses `cos θ = 2·dot² − 1`, which is invariant to the sign of either input
+ * (`q` ≡ `−q`, the quaternion double cover) because it depends only on `dot²`.
+ * The argument is clamped to `[-1, 1]` before `acos` so float error on a
+ * near-identical pair (where `2·dot² − 1` can drift slightly above 1) returns
+ * `0` rather than `NaN` — this is the guard `matrixDelta` previously applied
+ * explicitly around the raw `quat.getAngle`.
+ *
+ * Precondition: both inputs are (approximately) unit length. Callers that hold
+ * un-normalized quaternions must normalize first (gl-matrix `quat.normalize`).
+ *
+ * @returns angle in radians, in `[0, π]`. Never `NaN` for finite unit inputs.
+ */
+declare function geodesicAngleRad(a: ReadonlyQuat, b: ReadonlyQuat): number;
+//#endregion
+export { geodesicAngleRad as t };

package/dist/{index-BYYUdf9v.d.ts → index-BODDUTvD.d.ts}

@@ -1,4 +1,4 @@
-import { L as CombinedRootState, h as TrackingQualityReport } from "./create-slam-app-store-BljusOua.js";
+import { N as CombinedRootState, m as TrackingQualityReport } from "./create-slam-app-store-n_VF63D5.js";
 import { Add2dImagePayload, GpsPoint as GpsPoint$1, LatLong as LatLong$1, RawDeviceOrientation, RawGpsPoint as RawGpsPoint$1, RecordGpsEventPayload as RecordGpsEventPayload$1, add2dImage, calcRelativeCoordsInMeters, recordGpsEvent as recordGpsEvent$1, setZeroPos as setZeroPos$1 } from "gps-plus-slam-js";
 
 //#region ../src/state/onboarding-guidance.d.ts

package/dist/index-BneSj4_5.d.ts

@@ -0,0 +1,399 @@
+import { t as GridCell } from "./bresenham3d-CU1Gv2W4.js";
+import { a as QrPoseSolution, i as Pose, r as Point2, t as CameraIntrinsics } from "./qr-pose-D2rfu5DA.js";
+import { a as QrFrontEnd, o as RgbaImage } from "./qr-frontend--fFX25mV.js";
+import { Quaternion, RecordGpsEventPayload, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-gps-vote.d.ts
+/** Mean meters per degree of latitude (WGS-84 average). */
+declare const METERS_PER_DEG_LAT = 111320;
+/** Absolute geo pose of the printed QR, from the level file. */
+interface QrGeoPose {
+  lat: number;
+  lon: number;
+  /** Altitude of the QR center, meters. */
+  alt: number;
+  /**
+   * Compass bearing (degrees clockwise from true North) that the QR's local +X
+   * axis points toward. The QR is assumed vertical (wall-mounted): local +Y =
+   * world up, local +X = horizontal along the wall at this bearing.
+   */
+  headingDeg: number;
+}
+interface QrGpsVoteInput {
+  /** Solved QR pose in raw-WebXR/odom space (`solveQrPose().qrPoseWorld`). */
+  qrPoseWorld: Pose;
+  /** Printed physical side length, meters. */
+  sizeM: number;
+  /** Absolute geo pose from the level file. */
+  qrGeo: QrGeoPose;
+  /**
+   * Synthetic GPS accuracy in meters. Small → very high weight (the core
+   * library computes `weight = 1/accuracy^gpsAccuracyExponent`). Pick & validate
+   * against the fusion rather than hardcoding blindly (plan §6).
+   */
+  syntheticAccuracyM: number;
+  /**
+   * Device/odom rotation to stamp on each payload. Defaults to the QR's world
+   * rotation; the fusion uses this only for the device-rotation derivation, not
+   * for the positional correspondence.
+   */
+  odomRotation?: Quaternion;
+  /** 4 corner observations (default) vs. a single center observation. */
+  multiCorrespondence?: boolean;
+  /**
+   * WIDE-BASELINE north-stiffness knob (Note 2 of the follow-up plan). When > 0,
+   * synthesize the correspondences on a regular polygon of THIS radius (meters)
+   * in the QR plane instead of using the physical corners. Because the full
+   * 6-DoF pose + geo + heading are known, these virtual points are consistent in
+   * BOTH odom and geo space by construction; a wider baseline gives the single
+   * pose far more lever-arm, so corner-pixel noise maps to a much smaller heading
+   * error. The physical-corner mode is the `baselineM = 0`/undefined special case.
+   *
+   * ⚠️ This adds NO new information — every point derives from the one solved
+   * pose — so it is a pure leverage/reweighting device. Increasing `count`
+   * makes a BAD detection harder for the outlier-rejection step to reject (all
+   * pairs are wrong together); it is only safe because the pre-injection gates (reprojection,
+   * occupancy plausibility, N-consecutive-lock) ensure only good detections vote.
+   * Treat it as a bounded tuning knob, not a free dial (plan §1 "dominates but
+   * does not entirely erase").
+   */
+  baselineM?: number;
+  /**
+   * Number of synthetic correspondences in wide-baseline mode (≥ 3 for a
+   * non-collinear, well-posed rotation constraint). Default 4. Ignored unless
+   * `baselineM > 0`. This is the dominance (vote-count) half of the knob.
+   */
+  count?: number;
+  /** Epoch ms stamped on every synthetic point. Defaults to `Date.now()`. */
+  timestamp?: number;
+  /** Id prefix for the synthetic points. Default `'qr'`. */
+  idPrefix?: string;
+}
+/** East/North/Up offset (meters) of a QR-plane point from the QR center. */
+interface Enu {
+  east: number;
+  north: number;
+  up: number;
+}
+/**
+ * Map a QR-local plane offset (meters; +x right, +y up on the printed face) to
+ * an East/North/Up offset, given the QR's compass heading. Vertical-QR
+ * convention: +y is world up; +x is horizontal at `headingDeg` (clockwise from
+ * North), so east = x·sin(h), north = x·cos(h).
+ */
+declare function localPlaneToEnu(localX: number, localY: number, headingDeg: number): Enu;
+/** Apply an ENU meter offset to a geo pose (equirectangular; exact enough for sub-meter QR corners). */
+declare function offsetGeo(center: QrGeoPose, enu: Enu): {
+  latitude: number;
+  longitude: number;
+  altitude: number;
+};
+/**
+ * Build the synthetic `recordGpsEvent` payload(s) for one QR detection. Returns
+ * 4 corner correspondences by default, or 1 center correspondence when
+ * `multiCorrespondence` is false. Each payload pairs the corner's odom position
+ * (from the solved pose) with its absolute geo position (from the level file),
+ * stamped with the tiny synthetic accuracy.
+ *
+ * @throws RangeError on a non-positive `sizeM` or `syntheticAccuracyM`.
+ */
+declare function buildQrGpsVotes(input: QrGpsVoteInput): RecordGpsEventPayload[];
+//#endregion
+//#region ../src/ar/qr-level.d.ts
+/**
+ * A validated QR level file.
+ *
+ * Both `physicalSizeM` and `geo` are OPTIONAL (Note 3 of the follow-up plan:
+ * flat optionals + a capability model, not a discriminated union). Their
+ * PRESENCE gates which capabilities activate, and the use-cases are combinable:
+ * - `geo` present → the high-weight GPS vote (`buildQrGpsVotes`) runs.
+ * - `physicalSizeM` present → size is authored; otherwise it must be MEASURED
+ *   first (Note 4 depth path) before size-dependent features (PnP solve, vote)
+ *   unlock. See the size lifecycle in `state/qr-detected-slice.ts`.
+ * - neither → a debug/observe or trigger-only level (still keyed by payload).
+ */
+interface QrLevel {
+  /** Schema version for forward-compat. */
+  version: number;
+  qr: {
+    /** Printed physical side length, meters. Optional — may be measured instead. */physicalSizeM?: number; /** Absolute geo pose of the QR center + heading. Optional — geo-less levels skip the vote. */
+    geo?: QrGeoPose;
+  };
+  /** AR content to instantiate (format deferred — plan §12). Opaque here. */
+  content?: unknown;
+}
+/** Thrown when a fetched level file fails validation. */
+declare class QrLevelValidationError extends Error {
+  constructor(message: string);
+}
+/**
+ * Validate an already-parsed value as a {@link QrLevel}. Throws
+ * {@link QrLevelValidationError} with a descriptive message on any violation.
+ */
+declare function parseQrLevel(data: unknown): QrLevel;
+/** Minimal `fetch` slice used by {@link fetchQrLevel}. */
+type FetchLike = (url: string, init?: {
+  signal?: AbortSignal;
+}) => Promise<{
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}>;
+interface FetchQrLevelOptions {
+  /** Injected fetch (defaults to global `fetch`). */
+  fetchImpl?: FetchLike;
+  /** Optional abort signal for cancellation. */
+  signal?: AbortSignal;
+}
+/**
+ * Fetch and validate a level file from `url`. Rejects with
+ * {@link QrLevelValidationError} on a non-OK response, non-JSON body, or a
+ * schema violation.
+ */
+declare function fetchQrLevel(url: string, options?: FetchQrLevelOptions): Promise<QrLevel>;
+//#endregion
+//#region ../src/ar/qr-tracking-controller.d.ts
+type QrTrackingStatus = 'idle' | 'scanning' | 'loading-level' | 'tracking' | 'error';
+/** Inputs to the injected pose solve (so the controller doesn't import OpenCV). */
+interface QrSolvePoseInput {
+  imagePoints: readonly Point2[];
+  sizeM: number;
+  intrinsics: CameraIntrinsics;
+  cameraPose: Pose;
+}
+/**
+ * Emitted on every lock, INDEPENDENTLY of the GPS vote (Note 3). The app maps
+ * this onto `recordQrDetection` of the `qrDetected` slice. Kept structural (no
+ * import of the state slice) so the `ar` layer never depends on `state` — that
+ * would close a cycle (`state/qr-detected-slice` already imports `ar/qr-pose`).
+ */
+interface QrDetectionEvent {
+  /** Decoded payload (text/URL) — the marker key. */
+  text: string;
+  qrPoseWorld: Pose;
+  qrPoseInCamera: Pose;
+  reprojectionErrorPx: number;
+  /** Epoch ms (or the injected clock) when the lock fired. */
+  timestamp: number;
+}
+interface QrTrackingControllerConfig {
+  /** Detect + decode (BarcodeDetector / OpenCV front-end). */
+  frontEnd: QrFrontEnd;
+  /** Solve the QR world pose from corners (production: wraps `solveQrPose`). */
+  solvePose: (input: QrSolvePoseInput) => QrPoseSolution | null;
+  /** Fetch + validate a level file from the decoded URL (cached by the controller). */
+  fetchLevel: (url: string) => Promise<QrLevel>;
+  /** Dispatch the synthetic GPS votes (production: `recordGpsEvent` per payload). */
+  dispatchVotes: (votes: RecordGpsEventPayload[]) => void;
+  /**
+   * Emitted on every lock, independent of the vote (Note 3). Apps wire this to
+   * `dispatch(recordQrDetection(event))`. The vote is conditional on `geo`;
+   * this emission is not.
+   */
+  onDetection?: (event: QrDetectionEvent) => void;
+  /**
+   * Resolve the physical size (m) when the level omits `physicalSizeM` — e.g. a
+   * depth-measured running median (Note 4). Returns `null` while size is still
+   * unknown, which BLOCKS the pose solve (and therefore the vote + detection
+   * emission) until a size is authored or measured-and-locked (the Note 3 size
+   * lifecycle gate). Ignored when the level already carries `physicalSizeM`.
+   */
+  resolveSizeM?: (text: string, level: QrLevel) => number | null;
+  /**
+   * Resolve the STABLE (sliding-window filtered) world pose for the vote — e.g.
+   * `selectStableQrPose(store.getState(), text)`. Returns `null` until the pose
+   * has converged, which GATES the high-weight vote (the detection emission is
+   * unconditional; only the vote waits for stability). When omitted (back-compat)
+   * the raw single-frame solve pose drives the vote.
+   *
+   * Ordering: the `onDetection` emission above feeds this frame's RAW pose into
+   * the slice synchronously, so the window this reads already includes it. See
+   * the sliding-window stabilization design doc.
+   */
+  resolveStablePose?: (text: string) => Pose | null;
+  /** Current camera pose in raw-WebXR/odom space, or `null` if unavailable. */
+  getCameraPose: () => Pose | null;
+  /** Intrinsics for the exact frame buffer, or `null` if unavailable. */
+  getIntrinsics: (image: RgbaImage) => CameraIntrinsics | null;
+  /** Synthetic GPS accuracy (m) → vote weight. */
+  syntheticAccuracyM: number;
+  /**
+   * Optional wide-baseline north-stiffness knob (Note 2), forwarded to
+   * `buildQrGpsVotes`. `voteBaselineM > 0` synthesizes the correspondences on a
+   * polygon of that radius (stiffer rotation fit); `voteCount` (≥3) sets how
+   * many. Leave unset for the default physical-corner mode. Treat as a bounded
+   * tuning knob — a larger count makes a bad detection harder to outlier-reject.
+   */
+  voteBaselineM?: number;
+  voteCount?: number;
+  /** Optional plausibility gate (e.g. occupancy self-check); `false` rejects. */
+  isPlausible?: (solution: QrPoseSolution, cameraPose: Pose) => boolean;
+  /** Status-change notifications for the UI. */
+  onStatus?: (status: QrTrackingStatus) => void;
+  /** Called each time a locked detection dispatches votes. */
+  onLocked?: (solution: QrPoseSolution, level: QrLevel) => void;
+  /** Surfaced failures (level fetch, detect throw). */
+  onError?: (err: unknown) => void;
+  /** Scheduler tuning (see `detection-scheduler.ts`). */
+  minIntervalMs?: number;
+  requiredLockCount?: number;
+  now?: () => number;
+}
+interface QrTrackingController {
+  /** Offer the latest camera frame; throttled/coalesced internally. */
+  offerFrame(image: RgbaImage): void;
+  /** Current status. */
+  readonly status: QrTrackingStatus;
+  /** Stop tracking and reset to `idle` (clears the level cache). */
+  reset(): void;
+}
+declare function createQrTrackingController(config: QrTrackingControllerConfig): QrTrackingController;
+//#endregion
+//#region ../src/ar/camera-frame-source.d.ts
+/** Tuning for the camera frame source. */
+interface CameraFrameSourceConfig {
+  /**
+   * Minimum interval between captures in milliseconds. Default 125 ms (≈ 8 Hz),
+   * the plan §9 5–10 Hz detection target. The capture (and therefore the blit)
+   * fires at most once per `intervalMs`.
+   */
+  intervalMs: number;
+}
+/** Injected I/O for the camera frame source. */
+interface CameraFrameSourceCallbacks {
+  /**
+   * Capture the current XR frame as top-left-origin RGBA, or `null` when no
+   * frame is available (no camera texture yet, GL failure). This is the GPU
+   * blit + readback; the source only invokes it at the throttled cadence so
+   * the cost is bounded. A `null` return does NOT consume the interval slot —
+   * the next frame retries immediately (a missing texture is transient).
+   */
+  capture: () => RgbaImage | null;
+  /** Receive a throttled, successfully-captured frame. */
+  onCapture: (image: RgbaImage) => void;
+}
+/**
+ * Throttled RGBA capturer. Construct with the injected `capture`/`onCapture`
+ * pair, `start()`, then call `onFrame(timestamp)` once per XR frame.
+ */
+declare class CameraFrameSource {
+  private readonly callbacks;
+  private readonly config;
+  private running;
+  private captureCount;
+  private lastCaptureTime;
+  constructor(callbacks: CameraFrameSourceCallbacks, config?: Partial<CameraFrameSourceConfig>);
+  /** Begin throttling. Resets the cadence so the first tick captures. */
+  start(): void;
+  /** Stop capturing. `onFrame` becomes a no-op until `start()` is called again. */
+  stop(): void;
+  isRunning(): boolean;
+  /** Number of frames successfully captured + delivered since `start()`. */
+  getFrameCount(): number;
+  getConfig(): CameraFrameSourceConfig;
+  /**
+   * Apply partial config (e.g. the app's detection cadence). Invalid values
+   * are ignored defensively — `intervalMs` requires a finite positive number.
+   */
+  updateConfig(config: Partial<CameraFrameSourceConfig>): void;
+  /**
+   * Per-XR-frame tick. Captures + delivers a frame at most once per
+   * `intervalMs`; otherwise a cheap no-op so it is safe to call every frame.
+   *
+   * @param timestamp - monotonic frame time in ms (the XR `time` argument).
+   */
+  onFrame(timestamp: number): void;
+  /**
+   * Run the injected capture, guarded so a blit failure (e.g. GL context loss)
+   * can never throw out of the XR frame loop — it degrades to "no frame this
+   * tick", exactly like a missing texture.
+   */
+  private captureSafely;
+}
+//#endregion
+//#region ../src/ar/detection-scheduler.d.ts
+interface DetectionSchedulerConfig<TResult, TImage = RgbaImage> {
+  /** The full detect→solve step; resolves to a result or `null` (no hit / rejected). */
+  detect: (image: TImage) => Promise<TResult | null>;
+  /** Minimum ms between detection STARTS (throttle). 100 ms ≈ 10 Hz. */
+  minIntervalMs: number;
+  /** Consecutive successes required before a lock is reported. Default 3. */
+  requiredLockCount?: number;
+  /** Injectable clock (ms). Defaults to `performance.now()`/`Date.now()`. */
+  now?: () => number;
+  /** Called on each success once locked (consecutiveLocks ≥ requiredLockCount). */
+  onLocked?: (result: TResult) => void;
+  /** Called when a detection completes with no usable result. */
+  onMiss?: () => void;
+  /** Called when `detect` rejects (the counter is reset). */
+  onError?: (err: unknown) => void;
+}
+interface DetectionScheduler<TImage = RgbaImage> {
+  /** Offer the latest camera frame; may or may not start a detection. */
+  offerFrame(image: TImage): void;
+  /** True while a detection is awaiting `detect`. */
+  readonly inFlight: boolean;
+  /** Current consecutive-success count (capped at requiredLockCount). */
+  readonly consecutiveLocks: number;
+  /** True once `consecutiveLocks` has reached `requiredLockCount`. */
+  readonly locked: boolean;
+}
+declare function createDetectionScheduler<TResult, TImage = RgbaImage>(config: DetectionSchedulerConfig<TResult, TImage>): DetectionScheduler<TImage>;
+/** {@link DetectionSchedulerConfig} specialized to the QR pose solution. */
+type QrDetectionSchedulerConfig = DetectionSchedulerConfig<QrPoseSolution>;
+/** {@link DetectionScheduler} specialized to the QR (RGBA) frame. */
+type QrDetectionScheduler = DetectionScheduler<RgbaImage>;
+/** The QR path: a detection scheduler whose result is a {@link QrPoseSolution}. */
+declare function createQrDetectionScheduler(config: QrDetectionSchedulerConfig): QrDetectionScheduler;
+//#endregion
+//#region ../src/ar/qr-occupancy-check.d.ts
+/**
+ * The slice of `OccupancyGrid` this check needs. Declared structurally so the
+ * real grid satisfies it and tests can pass a tiny synthetic stand-in.
+ */
+interface OccupancySurface {
+  readonly cellSizeM: number;
+  getOccupiedCells(minObservations?: number): readonly GridCell[];
+  getCellCenter(cell: GridCell): Vector3;
+}
+type QrPlausibilityVerdict = 'plausible' | 'floating' | 'behind-surface' | 'no-grid';
+interface QrPlausibility {
+  verdict: QrPlausibilityVerdict;
+  /** `false` only for an implausible pose (`floating` / `behind-surface`). */
+  ok: boolean;
+  /** Distance from the QR center to the nearest occupied voxel; `Infinity` when the grid is empty. */
+  nearestSurfaceDistanceM: number;
+}
+interface QrPlausibilityOptions {
+  /**
+   * How far (in `cellSizeM` units) the QR may sit from the nearest occupied
+   * voxel before it counts as "floating". Default 1.5.
+   */
+  surfaceToleranceCells?: number;
+  /** Minimum observation count for a voxel to count as occupied. Default 1. */
+  minObservations?: number;
+  /**
+   * Perpendicular distance (in `cellSizeM` units) within which an occupied
+   * voxel counts as lying ON the camera→QR ray. Default 1.
+   */
+  rayCorridorCells?: number;
+  /**
+   * Margin (in `cellSizeM` units) subtracted from the camera→QR distance so the
+   * QR's own wall voxel is not mistaken for an occluder. Default 2.
+   */
+  occlusionMarginCells?: number;
+}
+/**
+ * Classify a solved QR center against the occupancy grid.
+ *
+ * - `no-grid` (ok): the grid has no occupied voxels — nothing to check against.
+ * - `floating` (not ok): nearest occupied voxel is farther than the tolerance.
+ * - `behind-surface` (not ok): an occupied voxel lies on the camera→QR ray
+ *   clearly in front of the QR (the QR is inside / beyond geometry).
+ * - `plausible` (ok): on a surface with empty space toward the camera.
+ *
+ * All positions are raw-WebXR/odom space (the same frame as `qrPoseWorld`).
+ */
+declare function checkQrPlausibility(qrCenterWorld: Vector3, cameraPosWorld: Vector3, grid: OccupancySurface, options?: QrPlausibilityOptions): QrPlausibility;
+//#endregion
+export { QrGpsVoteInput as A, QrLevel as C, Enu as D, parseQrLevel as E, localPlaneToEnu as M, offsetGeo as N, METERS_PER_DEG_LAT as O, FetchQrLevelOptions as S, fetchQrLevel as T, QrTrackingController as _, checkQrPlausibility as a, createQrTrackingController as b, QrDetectionScheduler as c, createQrDetectionScheduler as d, CameraFrameSource as f, QrSolvePoseInput as g, QrDetectionEvent as h, QrPlausibilityVerdict as i, buildQrGpsVotes as j, QrGeoPose as k, QrDetectionSchedulerConfig as l, CameraFrameSourceConfig as m, QrPlausibility as n, DetectionScheduler as o, CameraFrameSourceCallbacks as p, QrPlausibilityOptions as r, DetectionSchedulerConfig as s, OccupancySurface as t, createDetectionScheduler as u, QrTrackingControllerConfig as v, QrLevelValidationError as w, FetchLike as x, QrTrackingStatus as y };

package/dist/index-_Rhgoqkh.d.ts

@@ -0,0 +1,2 @@
+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, arNorthBearingDeg, bearingDeltaDeg, calcGpsCoords as calcGpsCoords$1, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, magneticHeadingFromEnuQuat, odometryTrackingRestarted, validateLicenseKey as validateLicenseKey$1, webxrToNUE } from "gps-plus-slam-js";
+export { odometryTrackingRestarted as _, LibraryRootState as a, RootState$1 as c, bearingDeltaDeg as d, calcGpsCoords$1 as f, magneticHeadingFromEnuQuat as g, isIdentityMatrix4 as h, LatLongAlt as i, Vector3$1 as l, createGpsSlamStore as m, GpsPoint$1 as n, Matrix4$1 as o, calcRelativeCoordsInMeters as p, LatLong$1 as r, Quaternion$1 as s, ArImageCapture$1 as t, arNorthBearingDeg as u, validateLicenseKey$1 as v, webxrToNUE as y };