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

package/dist/geo/h3-proximity.js

@@ -1,4 +1,4 @@
-import { gridDisk, latLngToCell } from "h3-js";
+import { cellToParent, getResolution, gridDisk, isValidCell, latLngToCell } from "h3-js";
 //#region ../src/geo/h3-proximity.ts
 /**
 * H3 Geo-Anchor Proximity Matching
@@ -22,6 +22,65 @@ function gpsToH3(lat, lng) {
 	return latLngToCell(lat, lng, 11);
 }
 /**
+* Reduce a recorded GPS path to the deduplicated set of res-11 H3 cells it
+* crossed — the per-tour "coverage index" stored in `SessionMetadata.h3Cells`.
+*
+* Cells are returned in first-seen (chronological) order and deduplicated, so a
+* tour that dwells in one ~25 m cell contributes a single cell. This keeps the
+* stored index small (see the metadata-size risk in the map-browser feedback
+* doc, §7). Non-finite coordinates are skipped defensively — bad sensor data
+* must not poison the index or throw inside `latLngToCell`.
+*/
+function gpsPathToCoverageCells(path) {
+	const seen = /* @__PURE__ */ new Set();
+	const cells = [];
+	for (const p of path) {
+		if (!Number.isFinite(p.lat) || !Number.isFinite(p.lng)) continue;
+		const cell = gpsToH3(p.lat, p.lng);
+		if (!seen.has(cell)) {
+			seen.add(cell);
+			cells.push(cell);
+		}
+	}
+	return cells;
+}
+/**
+* Coarsen res-11 coverage cells to a target resolution for map zoom-clustering.
+*
+* Uses h3-js `cellToParent` — the ONLY correct way to coarsen an H3 cell. NEVER
+* truncate the hex-string id: resolution is encoded in the high bits with
+* trailing `f` padding, so slicing yields INVALID cells, not parents (verified;
+* see the D1 gotcha in
+* docs/2026-06-14-map-centric-recording-browser-and-h3-index-user-feedback.md).
+*
+* `targetRes` is clamped to `[0, H3_RESOLUTION]` because `cellToParent` throws
+* when asked for a FINER resolution than the cell, and res 11 is the finest
+* data stored — so the highest map zooms render the stored cells unclustered
+* (`cellToParent(cell, 11) === cell`). A non-finite `targetRes` (e.g. a bad
+* zoom→res mapping) degrades to unclustered output rather than throwing.
+* Invalid input cells (corrupt/legacy metadata) are skipped defensively, as are
+* valid cells coarser than `res` (which have no parent at the finer target res
+* and would otherwise throw "incompatible resolutions").
+*
+* Output is deduplicated in first-seen order: sibling cells under one parent
+* collapse to a single tile.
+*/
+function clusterCellsByZoom(cells, targetRes) {
+	const res = Number.isFinite(targetRes) ? Math.max(0, Math.min(11, Math.floor(targetRes))) : 11;
+	const seen = /* @__PURE__ */ new Set();
+	const parents = [];
+	for (const cell of cells) {
+		if (!isValidCell(cell)) continue;
+		if (getResolution(cell) < res) continue;
+		const parent = cellToParent(cell, res);
+		if (!seen.has(parent)) {
+			seen.add(parent);
+			parents.push(parent);
+		}
+	}
+	return parents;
+}
+/**
 * Approximate distance in metres using equirectangular projection.
 * Accurate to < 0.1% for distances under 1 km at mid-latitudes,
 * which is sufficient for ranking ref point candidates within a
@@ -75,4 +134,4 @@ function isH3Index(id) {
 	return H3_INDEX_PATTERN.test(id);
 }
 //#endregion
-export { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+export { H3_RESOLUTION, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/index.d.ts

@@ -1,2 +1,2 @@
-import { a as gpsToH3, i as findNearbyGeoAnchor, n as KnownGeoAnchor, o as h3CellsMatch, r as approxDistanceMetres, s as isH3Index, t as H3_RESOLUTION } from "../h3-proximity-I1msGPgE.js";
-export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+import { a as findNearbyGeoAnchor, c as h3CellsMatch, i as clusterCellsByZoom, l as isH3Index, n as KnownGeoAnchor, o as gpsPathToCoverageCells, r as approxDistanceMetres, s as gpsToH3, t as H3_RESOLUTION } from "../h3-proximity-B57C6rYL.js";
+export { H3_RESOLUTION, type KnownGeoAnchor, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/geo/index.js

@@ -1,2 +1,2 @@
-import { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index } from "./h3-proximity.js";
-export { H3_RESOLUTION, approxDistanceMetres, findNearbyGeoAnchor, gpsToH3, h3CellsMatch, isH3Index };
+import { H3_RESOLUTION, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index } from "./h3-proximity.js";
+export { H3_RESOLUTION, approxDistanceMetres, clusterCellsByZoom, findNearbyGeoAnchor, gpsPathToCoverageCells, gpsToH3, h3CellsMatch, isH3Index };

package/dist/{gps-anchor-dYeCvvp5.d.ts → gps-anchor-C6I9NDHA.d.ts}

@@ -1,4 +1,4 @@
-import { i as LatLongAlt, r as LatLong } from "./index-CF05QV2m.js";
+import { i as LatLongAlt, r as LatLong } from "./index-eaI1Z1KR.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/gps-anchor.d.ts

package/dist/{gps-ar-pose-sampler-DVb96iOy.d.ts → gps-ar-pose-sampler-DaHg2aPZ.d.ts}

@@ -1,4 +1,4 @@
-import { t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { t as ARPose } from "./ar-types-BckI1E-O.js";
 import { Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/state/gps-ar-pose-sampler.d.ts

package/dist/{gps-event-coordinator-BDIQde2x.d.ts → gps-event-coordinator-C7hwHyLA.d.ts}

@@ -1,6 +1,6 @@
-import { t as ARPose } from "./ar-types-Dan1MVTi.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-VuezJWK3.js";
-import { i as SlamAppStore } from "./create-slam-app-store-qNXQ-tq5.js";
+import { t as ARPose } from "./ar-types-BckI1E-O.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-C5inWeNV.js";
+import { i as SlamAppStore } from "./create-slam-app-store-Ce2FMKCp.js";
 import { Quaternion, RawGpsPoint, RecordGpsEventPayload, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
 import { ReducersMapObject } from "@reduxjs/toolkit";
 

package/dist/{gps-event-markers-Dc9FT-q1.d.ts → gps-event-markers-Dd0G2bD0.d.ts}

@@ -24,6 +24,14 @@ declare class GpsEventVisualizer {
   private zeroRef;
   private eventCounter;
   private snapshotCounter;
+  /**
+   * Whether the debug markers are drawn. Toggled by {@link setVisible} for the
+   * recorder's `visualization.gpsAlignmentMarkers` opt-out (Finding B). Applied
+   * to every marker at creation so events spawned later by the live
+   * store-subscriber inherit the current state instead of popping into view.
+   * Default `true` — the markers render exactly as before until opted out.
+   */
+  private markersVisible;
   /**
    * Set the GPS zero reference (origin for coordinate conversion).
    * Must be called before adding GPS events.
@@ -64,6 +72,16 @@ declare class GpsEventVisualizer {
    * Create a sphere marker mesh with the given color and name.
    */
   private createMarkerMesh;
+  /**
+   * Show or hide ALL debug markers — raw GPS (yellow), fused (cyan), and
+   * alignment-snapshot (red) — and remember the state so markers added later
+   * inherit it. Used by the recorder's `visualization.gpsAlignmentMarkers`
+   * opt-out, read once at Enter-AR (live only; replay keeps markers visible).
+   *
+   * This only changes rendering: capture, GPS-event recording, counts, and the
+   * snapshot positions read back at session end are all unaffected.
+   */
+  setVisible(visible: boolean): void;
   /**
    * Clear all markers from the scene and reset state.
    */

package/dist/{h3-proximity-I1msGPgE.d.ts → h3-proximity-B57C6rYL.d.ts}

@@ -29,6 +29,44 @@ interface KnownGeoAnchor {
  * Compute the H3 resolution-11 index for a GPS position.
  */
 declare function gpsToH3(lat: number, lng: number): string;
+/** Minimal GPS coordinate shape (Leaflet convention: `lng`, not `lon`). */
+interface LatLngLike {
+  readonly lat: number;
+  readonly lng: number;
+}
+/**
+ * Reduce a recorded GPS path to the deduplicated set of res-11 H3 cells it
+ * crossed — the per-tour "coverage index" stored in `SessionMetadata.h3Cells`.
+ *
+ * Cells are returned in first-seen (chronological) order and deduplicated, so a
+ * tour that dwells in one ~25 m cell contributes a single cell. This keeps the
+ * stored index small (see the metadata-size risk in the map-browser feedback
+ * doc, §7). Non-finite coordinates are skipped defensively — bad sensor data
+ * must not poison the index or throw inside `latLngToCell`.
+ */
+declare function gpsPathToCoverageCells(path: readonly LatLngLike[]): string[];
+/**
+ * Coarsen res-11 coverage cells to a target resolution for map zoom-clustering.
+ *
+ * Uses h3-js `cellToParent` — the ONLY correct way to coarsen an H3 cell. NEVER
+ * truncate the hex-string id: resolution is encoded in the high bits with
+ * trailing `f` padding, so slicing yields INVALID cells, not parents (verified;
+ * see the D1 gotcha in
+ * docs/2026-06-14-map-centric-recording-browser-and-h3-index-user-feedback.md).
+ *
+ * `targetRes` is clamped to `[0, H3_RESOLUTION]` because `cellToParent` throws
+ * when asked for a FINER resolution than the cell, and res 11 is the finest
+ * data stored — so the highest map zooms render the stored cells unclustered
+ * (`cellToParent(cell, 11) === cell`). A non-finite `targetRes` (e.g. a bad
+ * zoom→res mapping) degrades to unclustered output rather than throwing.
+ * Invalid input cells (corrupt/legacy metadata) are skipped defensively, as are
+ * valid cells coarser than `res` (which have no parent at the finer target res
+ * and would otherwise throw "incompatible resolutions").
+ *
+ * Output is deduplicated in first-seen order: sibling cells under one parent
+ * collapse to a single tile.
+ */
+declare function clusterCellsByZoom(cells: readonly string[], targetRes: number): string[];
 /**
  * Approximate distance in metres using equirectangular projection.
  * Accurate to < 0.1% for distances under 1 km at mid-latitudes,
@@ -60,4 +98,4 @@ declare function h3CellsMatch(h3a: string, h3b: string): boolean;
  */
 declare function isH3Index(id: string): boolean;
 //#endregion
-export { gpsToH3 as a, findNearbyGeoAnchor as i, KnownGeoAnchor as n, h3CellsMatch as o, approxDistanceMetres as r, isH3Index as s, H3_RESOLUTION as t };
+export { findNearbyGeoAnchor as a, h3CellsMatch as c, clusterCellsByZoom as i, isH3Index as l, KnownGeoAnchor as n, gpsPathToCoverageCells as o, approxDistanceMetres as r, gpsToH3 as s, H3_RESOLUTION as t };

package/dist/{image-capture-DZ4HFRgS.d.ts → image-capture-C2Feywet.d.ts}

@@ -1,4 +1,4 @@
-import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-BckI1E-O.js";
 
 //#region ../src/ar/image-capture.d.ts
 /**
@@ -54,6 +54,30 @@ interface CapturedImage {
   readonly rotation: WebXRQuaternion;
   /** Device screen orientation (0, 90, 180, 270) */
   readonly screenRotation: number;
+  /**
+   * Width of the encoded JPEG in pixels — the blit/canvas dimensions the blob
+   * was produced from, so it equals the decoded image's width. Persisted as
+   * `ArImageCapture.width` so consumers (the 3D frame-tile visualizer) can
+   * render each frame at its true aspect ratio. Always present from the
+   * capture pipeline; optional so the field can be threaded without forcing
+   * every test/caller to supply it.
+   */
+  readonly width?: number;
+  /** Height of the encoded JPEG in pixels. See {@link CapturedImage.width}. */
+  readonly height?: number;
+}
+/**
+ * A captured frame blob together with the pixel dimensions it was encoded at.
+ * Returned by the optional `captureFrame` (blit) callback so the pose-invariant
+ * image size can be persisted as first-class metadata (frame-tile aspect-ratio
+ * fix, D1 of 2026-06-13-frame-tile-rendering-bugs-user-feedback.md). The
+ * dimensions are the blit render-target size — identical to the JPEG's own
+ * width/height — so no decode is needed to learn the aspect ratio.
+ */
+interface CapturedFrame {
+  readonly blob: Blob;
+  readonly width: number;
+  readonly height: number;
 }
 /**
  * Callbacks for image capture integration
@@ -80,10 +104,12 @@ interface ImageCaptureCallbacks {
    * be read directly via canvas.toBlob() (which returns black pixels).
    *
    * @param quality - JPEG quality 0.0-1.0
-   * @returns Promise resolving to a JPEG Blob, or null if capture fails
+   * @returns Promise resolving to the JPEG blob plus the pixel dimensions it
+   *   was encoded at, or null if capture fails. The dimensions flow into the
+   *   persisted `ArImageCapture.width`/`height` for aspect-correct rendering.
    * @see docs/2026-02-06-bug-camera-frames-black.md
    */
-  captureFrame?: (quality: number) => Promise<Blob | null>;
+  captureFrame?: (quality: number) => Promise<CapturedFrame | null>;
 }
 /**
  * Manages periodic image capture from a canvas.
@@ -140,4 +166,4 @@ declare class ImageCaptureManager {
   private handleCapturedBlob;
 }
 //#endregion
-export { ImageCaptureManager as a, ImageCaptureConfig as i, DEFAULT_CAPTURE_CONFIG as n, MIN_VALID_IMAGE_BYTES as o, ImageCaptureCallbacks as r, CapturedImage as t };
+export { ImageCaptureConfig as a, ImageCaptureCallbacks as i, CapturedImage as n, ImageCaptureManager as o, DEFAULT_CAPTURE_CONFIG as r, MIN_VALID_IMAGE_BYTES as s, CapturedFrame as t };

package/dist/index-BvLo2poy.d.ts

@@ -0,0 +1,399 @@
+import { t as GridCell } from "./bresenham3d-ByjcmEgM.js";
+import { a as QrPoseSolution, i as Pose, r as Point2, t as CameraIntrinsics } from "./qr-pose-Bt2reSw7.js";
+import { a as QrFrontEnd, o as RgbaImage } from "./qr-frontend-DufZp2xS.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-KJq2amHF.d.ts → index-m_LneUSi.d.ts}

@@ -1,4 +1,4 @@
-import { L as CombinedRootState, h as TrackingQualityReport } from "./create-slam-app-store-qNXQ-tq5.js";
+import { L as CombinedRootState, h as TrackingQualityReport } from "./create-slam-app-store-Ce2FMKCp.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