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

package/dist/qr-derived-pose-CmxTP2m4.d.ts

@@ -0,0 +1,122 @@
+import { i as Pose, r as Point2, s as SolvePnpSquare } from "./qr-pose-D2rfu5DA.js";
+import { a as QrSizeMeasurerOptions, n as QrSizeDepthContext } from "./qr-size-measurer-DQdAsid1.js";
+import { Matrix4 } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-derived-pose.d.ts
+/**
+ * One RAW QR observation — the authoritative recorded shape (D-A). Everything
+ * the derive layer needs to recompute size + pose is here EXCEPT depth (injected
+ * via `resolveDepthAt`). Structural on purpose: the slice's `QrDetectionEntry`
+ * supplies these fields; this module never imports the slice.
+ */
+interface RawQrObservation {
+  /** Decoded payload (text/URL) — also the marker key. */
+  text: string;
+  /** The 4 detected corners in detector-buffer PIXELS, order TL,TR,BR,BL. */
+  corners: readonly Point2[];
+  /** Capturing camera pose in raw-WebXR/odom space (rides `arWorldGroup`). */
+  cameraPose: Pose;
+  /** Column-major GL projection of the detector frame (→ PnP intrinsics). */
+  projectionMatrix: Matrix4;
+  /** Detector-buffer width in pixels (to normalize corners + build intrinsics). */
+  imageWidth: number;
+  /** Detector-buffer height in pixels. */
+  imageHeight: number;
+  /**
+   * Detection time in the producer's injected clock — the depth as-of join key.
+   * MUST share the depth stream's clock, which is EPOCH ms
+   * (`DepthSample.timestamp = performance.timeOrigin + frameTs`); the RAW recorder
+   * path stamps `Date.now()` (epoch), NOT relative `performance.now()`, or the
+   * `≤` join in {@link deriveQrSizeM} never matches. See open topic A.
+   */
+  timestamp: number;
+}
+/** Injected dependencies for the derive-on-read pose. */
+interface DeriveQrPoseDeps {
+  /**
+   * The as-of depth join: the depth-sampling context that was active at
+   * `timestamp`, or `null` when no usable depth covers it. Live wires the
+   * current depth sample; replay wires a lookup over the recorded depth stream.
+   */
+  resolveDepthAt: (timestamp: number) => QrSizeDepthContext | null;
+  /** PnP backend — the pure-JS {@link PlanarPnpSquare} in production. */
+  solver: SolvePnpSquare;
+  /** Size-measurer tuning, forwarded to {@link createQrSizeMeasurer}. */
+  sizeOptions?: QrSizeMeasurerOptions;
+  /** Reprojection-error gate forwarded to {@link solveQrPose} (default 4 px). */
+  maxReprojectionErrorPx?: number;
+}
+/**
+ * Replay a marker's observation history through a fresh size measurer (each
+ * observation sized against its own as-of depth context) and return the running
+ * median size in meters, or `null` if no observation could be sized yet.
+ *
+ * Re-runs the whole history per call — O(history), bounded by the slice ring
+ * buffer. Cheap for v1; memoize if the debug-viz cadence makes it hot.
+ */
+declare function deriveQrSizeM(text: string, observations: readonly RawQrObservation[], resolveDepthAt: DeriveQrPoseDeps['resolveDepthAt'], sizeOptions?: QrSizeMeasurerOptions): number | null;
+/**
+ * Solve the world pose of ONE raw observation given a known metric size. Pure
+ * (no depth): intrinsics come from the observation's projection + frame size,
+ * the corners + camera pose are recorded. Returns `null` when PnP rejects the
+ * quad or exceeds the reprojection gate.
+ */
+declare function solveQrPoseFromObservation(observation: RawQrObservation, sizeM: number, solver: SolvePnpSquare, maxReprojectionErrorPx?: number): Pose | null;
+/** A best-effort derived placement: the solved world pose AND the metric size
+ * that solved it (the size the debug cube needs). */
+interface DerivedQrPlacement {
+  /** Solved QR world pose (rides `arWorldGroup`). */
+  pose: Pose;
+  /** Running-median metric side length used to solve `pose`. */
+  sizeM: number;
+}
+/**
+ * Derive the best-effort {@link DerivedQrPlacement} for a marker: accumulate the
+ * size across the whole observation history (each against its as-of depth), then
+ * solve the LATEST observation with that size — returning BOTH the pose and the
+ * size (the debug cube needs the size; deriving once avoids two history passes).
+ * Returns `null` when there is no history, no observation can be sized, or PnP
+ * rejects the latest quad — callers render nothing (best-effort viz) rather than
+ * throwing.
+ */
+declare function deriveQrPlacement(text: string, observations: readonly RawQrObservation[], deps: DeriveQrPoseDeps): DerivedQrPlacement | null;
+/**
+ * Derive only the best-effort solved WORLD pose for a marker (the size is an
+ * internal of {@link deriveQrPlacement}). Returns `null` under the same
+ * conditions. Kept for callers that need the pose alone.
+ */
+declare function deriveSolvedQrPose(text: string, observations: readonly RawQrObservation[], deps: DeriveQrPoseDeps): Pose | null;
+/**
+ * A stateful, INCREMENTAL placement deriver — the live/replay-hot variant of
+ * {@link deriveQrPlacement}. The stateless `deriveQrPlacement` rebuilds a fresh
+ * measurer and replays the WHOLE observation history on every call; driven by a
+ * store subscriber that fires on every action, that is O(history) per action and
+ * caused an on-device framerate ramp-down once the per-marker ring filled
+ * (perf-degradation follow-up; open topic D). This deriver instead keeps one
+ * persistent size measurer and folds in **only observations newer than the last
+ * fold** — O(1) per new detection, matching the demo's incremental accumulator.
+ *
+ * Equivalence: folding each observation exactly once (in arrival order, against
+ * its as-of depth via `resolveDepthAt`) yields the same running-median size as a
+ * full replay over the same observations, so `update()`'s result equals
+ * {@link deriveQrPlacement} over the same sequence. It runs identically live and
+ * on replay (only reads what it is handed), preserving the re-test guarantee:
+ * the accumulated size is the whole **session** history (the slice ring cap only
+ * bounds what the live store can hand back, not what was already folded), which
+ * is exactly what an offline re-derivation over the full recorded stream sees.
+ */
+interface IncrementalQrPlacement {
+  /**
+   * Fold any observations newer than the last fold for `text`, then return the
+   * current best-effort placement (or `null` when not yet sizeable / PnP-rejected).
+   * **F1 (memo):** if the newest observation's timestamp is unchanged since the
+   * last call, returns the cached placement WITHOUT folding or re-solving — so
+   * unrelated store changes (depth, GPS) cost a `Map` lookup, not a re-derive.
+   */
+  update(text: string, observations: readonly RawQrObservation[]): DerivedQrPlacement | null;
+  /** Drop a marker's accumulated size + memo (e.g. on `clearQrMarker`). */
+  reset(text: string): void;
+}
+declare function createIncrementalQrPlacement(deps: DeriveQrPoseDeps): IncrementalQrPlacement;
+//#endregion
+export { createIncrementalQrPlacement as a, deriveSolvedQrPose as c, RawQrObservation as i, solveQrPoseFromObservation as l, DerivedQrPlacement as n, deriveQrPlacement as o, IncrementalQrPlacement as r, deriveQrSizeM as s, DeriveQrPoseDeps as t };

package/dist/qr-detected-slice-VQssZmQJ.d.ts

@@ -0,0 +1,166 @@
+import { i as Pose, r as Point2 } from "./qr-pose-D2rfu5DA.js";
+import { l as QrSizeEstimate } from "./qr-size-measurer-DQdAsid1.js";
+import { i as RawQrObservation, n as DerivedQrPlacement, t as DeriveQrPoseDeps } from "./qr-derived-pose-CmxTP2m4.js";
+import { a as QrPoseStability, o as QrPoseStabilityOptions } from "./qr-pose-aggregation-B7tWJq7j.js";
+import { Matrix4, Vector3 } from "gps-plus-slam-js";
+import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
+
+//#region ../src/state/qr-detected-slice.d.ts
+/**
+ * Default ring-buffer cap per marker. Bounded so an overlay that never prunes
+ * still cannot leak; large enough to support a robust median over a sliding
+ * window and a short motion path. Override via {@link setQrMaxHistory}.
+ */
+declare const DEFAULT_QR_MAX_HISTORY = 32;
+/**
+ * One detection observation. Detection-agnostic by design (Note 1): `text` is
+ * the label/payload, `reprojectionErrorPx` the confidence proxy, the two poses
+ * the 3D placement. `timestamp` is the producer's injected clock — see the field
+ * note: the RAW recorder path stamps EPOCH ms so the derive-on-read depth as-of
+ * join lines up with the depth stream (clock-domain coupling).
+ */
+interface QrDetectionEntry {
+  /** Decoded payload (text/URL) — also the marker key. */
+  text: string;
+  /**
+   * Detection time in the producer's injected clock. For the RAW recorder path
+   * this MUST be **EPOCH ms** (`Date.now()`), because the depth stream it joins
+   * against is epoch (`DepthSample.timestamp = performance.timeOrigin + frameTs`,
+   * `ar/depth-sampler.ts`) and the size as-of join pairs this with the depth
+   * sample whose timestamp is `≤` this one (`ar/qr-derived-pose`). A relative
+   * `performance.now()` stamp (~1e5) never satisfies that join, so the size — and
+   * the debug cube — never resolve. See the recorder live-QR plan open topic A.
+   */
+  timestamp: number;
+  /** The 4 detected corners in detector-buffer PIXELS, order TL,TR,BR,BL. */
+  corners?: readonly Point2[];
+  /** Capturing camera pose in raw-WebXR/odom space (PnP camera-relative base). */
+  cameraPose?: Pose;
+  /** Column-major GL projection of the detector frame (→ PnP intrinsics). */
+  projectionMatrix?: Matrix4;
+  /** Detector-buffer width in pixels (to normalize corners + build intrinsics). */
+  imageWidth?: number;
+  /** Detector-buffer height in pixels. */
+  imageHeight?: number;
+  /** QR pose in raw-WebXR/odom space (rides `arWorldGroup`). */
+  qrPoseWorld?: Pose;
+  /** QR pose relative to the WebXR camera (pre-composition). */
+  qrPoseInCamera?: Pose;
+  /** RMS reprojection error in pixels (lower = better fit). */
+  reprojectionErrorPx?: number;
+}
+/** Per-marker state: a bounded detection history + the size lifecycle. */
+interface QrMarkerState {
+  text: string;
+  /** Bounded ring buffer, OLDEST first / NEWEST last. */
+  detections: QrDetectionEntry[];
+  size: QrSizeEstimate;
+}
+interface QrDetectedState {
+  /** Ring-buffer cap applied per marker on `recordQrDetection`. */
+  maxHistory: number;
+  /** Markers keyed by decoded payload. */
+  markers: Record<string, QrMarkerState>;
+}
+declare const recordQrDetection: _$_reduxjs_toolkit0.ActionCreatorWithPayload<QrDetectionEntry, "qrDetected/recordQrDetection">, recordQrSizeEstimate: _$_reduxjs_toolkit0.ActionCreatorWithPayload<{
+    text: string;
+    estimate: QrSizeEstimate;
+  }, "qrDetected/recordQrSizeEstimate">, pruneQrDetections: _$_reduxjs_toolkit0.ActionCreatorWithPayload<{
+    text: string;
+    count: number;
+  }, "qrDetected/pruneQrDetections">, clearQrMarker: _$_reduxjs_toolkit0.ActionCreatorWithPayload<{
+    text: string;
+  }, "qrDetected/clearQrMarker">, clearAllQrMarkers: _$_reduxjs_toolkit0.ActionCreatorWithoutPayload<"qrDetected/clearAllQrMarkers">, setQrMaxHistory: _$_reduxjs_toolkit0.ActionCreatorWithPayload<number, "qrDetected/setQrMaxHistory">;
+declare const qrDetectedReducer: _$_reduxjs_toolkit0.Reducer<QrDetectedState>;
+/** Minimal root shape the selectors need (avoids a store import cycle). */
+interface RootWithQrDetected {
+  qrDetected: QrDetectedState;
+}
+declare function selectQrMarkers(state: RootWithQrDetected): Record<string, QrMarkerState>;
+declare function selectQrMarker(state: RootWithQrDetected, text: string): QrMarkerState | undefined;
+/**
+ * The newest detection for a marker (the natural overlay-persistence source —
+ * an overlay reads this and keeps the last pose across detection misses rather
+ * than unmounting/flickering).
+ */
+declare function selectLatestQrDetection(state: RootWithQrDetected, text: string): QrDetectionEntry | undefined;
+declare function selectQrSize(state: RootWithQrDetected, text: string): QrSizeEstimate | undefined;
+/**
+ * Resolve a marker's measured size for the high-weight GPS vote
+ * (framework-wiring-options Part B, Option a). Returns the running-median
+ * `estimateM` ONCE the size lifecycle reports `'estimated'`, else `null` ("keep
+ * scanning"). This is the bridge an app injects as the QR controller's
+ * `resolveSizeM`, so a size-less-but-geo level votes the moment the slice
+ * converges — **without** the `ar` controller ever importing the slice (which
+ * would close the `ar → state` cycle):
+ *
+ * ```ts
+ * resolveSizeM: (text) => selectResolvedQrSizeM(store.getState(), text),
+ * ```
+ *
+ * Per the Note 3 decision (confirmed) a reliably-estimated *measured* size
+ * drives the vote under the *same* gate as an authored size — no extra
+ * size-specific bar — because the §7 occupancy + reprojection + outlier-rejection
+ * backstops already bound a bad read.
+ */
+declare function selectResolvedQrSizeM(state: RootWithQrDetected, text: string): number | null;
+/**
+ * Robust per-axis median of the world positions across a marker's detection
+ * window — the "running estimate" the bounded buffer enables (Note 3). Outliers
+ * in fewer than half the samples cannot move the result outside the inlier
+ * range. Skips RAW-only entries that carry no solved pose (D-A); returns `null`
+ * for an empty window (or one with no solved poses at all).
+ */
+declare function medianQrPosition(entries: readonly QrDetectionEntry[]): Vector3 | null;
+/**
+ * The pose-stability lifecycle for a marker, derived from its raw detection ring
+ * buffer (NOT stored separately — the detections are the source of truth, unlike
+ * the depth-measured size which is accumulated outside the buffer). Mirrors the
+ * size lifecycle's `unknown → measuring → stable` shape so the HUD can show
+ * "converging…" vs "stable". See `ar/qr-pose-aggregation.ts`.
+ */
+declare function selectQrPoseStability(state: RootWithQrDetected, text: string, options?: QrPoseStabilityOptions): QrPoseStability;
+/**
+ * The robust filtered QR world pose, exposed ONLY once the stability gate is
+ * `stable` (else `null` — "keep accumulating"). This is the pose analogue of
+ * {@link selectResolvedQrSizeM}: the `resolveStablePose`-style bridge an app
+ * injects into the QR controller / demo so the `ar` layer never imports the
+ * slice. The high-weight vote and the smooth overlay consume THIS, never the raw
+ * latest pose (which stays available via {@link selectLatestQrDetection} for
+ * scanning feedback / overlay persistence across misses).
+ *
+ * ```ts
+ * resolveStablePose: (text) => selectStableQrPose(store.getState(), text),
+ * ```
+ */
+declare function selectStableQrPose(state: RootWithQrDetected, text: string, options?: QrPoseStabilityOptions): Pose | null;
+/**
+ * Derive the best-effort solved WORLD pose for a marker from its RAW observation
+ * history (decision D-A): accumulate size over the history against the injected
+ * `resolveDepthAt` as-of join, then PnP-solve the latest observation. Returns
+ * `null` when the marker is unknown, has no raw observations, cannot be sized
+ * yet, or PnP rejects the latest quad — the re-test-friendly replacement for the
+ * once-stored solved pose. Runs identically live and on replay (only
+ * `deps.resolveDepthAt` differs). See `ar/qr-derived-pose.ts`.
+ */
+declare function selectSolvedQrPose(state: RootWithQrDetected, text: string, deps: DeriveQrPoseDeps): Pose | null;
+/**
+ * The marker's stored entries narrowed to {@link RawQrObservation}s (entries
+ * carrying the full raw detector output), oldest→newest. Empty for an unknown
+ * marker or one with only solved-pose-only (transitional) entries. This is the
+ * shared mapping the derive-on-read selectors and the incremental deriver
+ * consume — exposed so a stateful consumer (the recorder's debug controller)
+ * can hand raw observations to `createIncrementalQrPlacement` without
+ * re-implementing the `toRawObservation` guard.
+ */
+declare function selectQrRawObservations(state: RootWithQrDetected, text: string): RawQrObservation[];
+/**
+ * Derive the best-effort {@link DerivedQrPlacement} (solved pose AND the metric
+ * size that solved it) for a marker from its RAW observation history. The debug
+ * viz needs the size to draw the cube, so this returns both in one history pass
+ * (decision D-A; see {@link deriveQrPlacement}). `null` under the same
+ * conditions as {@link selectSolvedQrPose}. Runs identically live and on replay.
+ */
+declare function selectDerivedQrPlacement(state: RootWithQrDetected, text: string, deps: DeriveQrPoseDeps): DerivedQrPlacement | null;
+//#endregion
+export { setQrMaxHistory as C, selectStableQrPose as S, selectQrPoseStability as _, RootWithQrDetected as a, selectResolvedQrSizeM as b, medianQrPosition as c, recordQrDetection as d, recordQrSizeEstimate as f, selectQrMarkers as g, selectQrMarker as h, QrMarkerState as i, pruneQrDetections as l, selectLatestQrDetection as m, QrDetectedState as n, clearAllQrMarkers as o, selectDerivedQrPlacement as p, QrDetectionEntry as r, clearQrMarker as s, DEFAULT_QR_MAX_HISTORY as t, qrDetectedReducer as u, selectQrRawObservations as v, selectSolvedQrPose as x, selectQrSize as y };

package/dist/qr-detection-controller-B-tLVd-S.js

@@ -0,0 +1,119 @@
+import { createLogger } from "./utils/logger.js";
+import { validateQuad } from "./ar/qr-pose.js";
+//#region ../src/ar/detection-scheduler.ts
+const log = createLogger("DetectionScheduler");
+const defaultNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+function createDetectionScheduler(config) {
+	const { detect, minIntervalMs, requiredLockCount = 3, now = defaultNow, onLocked, onMiss, onError } = config;
+	let inFlight = false;
+	let consecutiveLocks = 0;
+	let lastStart = -Infinity;
+	return {
+		get inFlight() {
+			return inFlight;
+		},
+		get consecutiveLocks() {
+			return consecutiveLocks;
+		},
+		get locked() {
+			return consecutiveLocks >= requiredLockCount;
+		},
+		offerFrame(image) {
+			if (inFlight) return;
+			const t = now();
+			if (t - lastStart < minIntervalMs) return;
+			lastStart = t;
+			inFlight = true;
+			(async () => detect(image))().then((result) => {
+				if (result) {
+					consecutiveLocks = Math.min(consecutiveLocks + 1, requiredLockCount);
+					if (consecutiveLocks >= requiredLockCount) try {
+						onLocked?.(result);
+					} catch (err) {
+						log.error("onLocked callback threw:", err);
+					}
+				} else {
+					consecutiveLocks = 0;
+					try {
+						onMiss?.();
+					} catch (err) {
+						log.error("onMiss callback threw:", err);
+					}
+				}
+			}).catch((err) => {
+				consecutiveLocks = 0;
+				try {
+					onError?.(err);
+				} catch (callbackErr) {
+					log.error("onError callback threw:", callbackErr);
+				}
+			}).finally(() => {
+				inFlight = false;
+			});
+		}
+	};
+}
+/** The QR path: a detection scheduler whose result is a {@link QrPoseSolution}. */
+function createQrDetectionScheduler(config) {
+	return createDetectionScheduler(config);
+}
+//#endregion
+//#region ../src/ar/qr-detection-controller.ts
+/**
+* Create the thin RAW producer. On each accepted decode it emits a
+* {@link RawQrObservation} via `recordDetection`; it does not size or solve.
+*/
+function createQrDetectionController(deps) {
+	const { detect, getCameraPose, getProjectionMatrix, recordDetection, now, minIntervalMs = 0, requiredLockCount = 2, onStatus } = deps;
+	const timestampNow = now ?? (() => Date.now());
+	let status = "idle";
+	function setStatus(next) {
+		if (status === next) return;
+		status = next;
+		onStatus?.(next);
+	}
+	async function runDetect(image) {
+		if (status === "idle") setStatus("scanning");
+		const detection = await detect(image);
+		if (!detection) return null;
+		if (!validateQuad(detection.corners).ok) return null;
+		const cameraPose = getCameraPose();
+		const projectionMatrix = getProjectionMatrix();
+		if (!cameraPose || !projectionMatrix) return null;
+		return {
+			text: detection.text,
+			corners: detection.corners,
+			cameraPose,
+			projectionMatrix,
+			imageWidth: image.width,
+			imageHeight: image.height,
+			timestamp: timestampNow()
+		};
+	}
+	const scheduler = createDetectionScheduler({
+		detect: runDetect,
+		minIntervalMs,
+		requiredLockCount,
+		...now ? { now } : {},
+		onLocked: (observation) => {
+			recordDetection(observation);
+			setStatus("tracking");
+		},
+		onMiss: () => {
+			if (status === "tracking") setStatus("scanning");
+		}
+	});
+	return {
+		offerFrame(image) {
+			scheduler.offerFrame(image);
+		},
+		get status() {
+			return status;
+		},
+		reset() {
+			setStatus("idle");
+		}
+	};
+}
+//#endregion
+export { createDetectionScheduler as n, createQrDetectionScheduler as r, createQrDetectionController as t };

package/dist/qr-detection-controller-CDurHv8E.d.ts

@@ -0,0 +1,48 @@
+import { i as Pose } from "./qr-pose-D2rfu5DA.js";
+import { i as QrDetection, o as RgbaImage } from "./qr-frontend--fFX25mV.js";
+import { i as RawQrObservation } from "./qr-derived-pose-CmxTP2m4.js";
+import { Matrix4 } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-detection-controller.d.ts
+/** Minimal scan-status machine (NO QR detail — per the recorder scope). */
+type QrScanStatus = 'idle' | 'scanning' | 'tracking';
+/** Sink for one recorded RAW observation — e.g. dispatch `recordQrDetection`. */
+type RawObservationSink = (observation: RawQrObservation) => void;
+interface QrDetectionControllerDeps {
+  /** Detect + decode one frame (BarcodeDetector front-end fed by the capture). */
+  detect: (image: RgbaImage) => Promise<QrDetection | null>;
+  /**
+   * Capturing camera pose in raw-WebXR/odom space, read when a detection
+   * resolves (mirrors the demo's post-detect depth read). `null` → skip record.
+   */
+  getCameraPose: () => Pose | null;
+  /**
+   * Column-major GL projection matrix of the detector-frame buffer the corners
+   * are in (→ PnP intrinsics on read). `null` → skip record.
+   */
+  getProjectionMatrix: () => Matrix4 | null;
+  /** Record one RAW observation — e.g. `(o) => store.dispatch(recordQrDetection(o))`. */
+  recordDetection: RawObservationSink;
+  /** Injectable clock (ms) for the detection timestamp + scheduler. */
+  now?: () => number;
+  /** Throttle: start a detection at most once per this many ms. Default 0. */
+  minIntervalMs?: number;
+  /** Consecutive successes before a lock is recorded. Default 2. */
+  requiredLockCount?: number;
+  /** Status-change notifications (idle → scanning → tracking). */
+  onStatus?: (status: QrScanStatus) => void;
+}
+interface QrDetectionController {
+  /** Offer the latest camera frame; throttled/coalesced internally. */
+  offerFrame(image: RgbaImage): void;
+  readonly status: QrScanStatus;
+  /** Return to idle (e.g. on session end). */
+  reset(): void;
+}
+/**
+ * Create the thin RAW producer. On each accepted decode it emits a
+ * {@link RawQrObservation} via `recordDetection`; it does not size or solve.
+ */
+declare function createQrDetectionController(deps: QrDetectionControllerDeps): QrDetectionController;
+//#endregion
+export { createQrDetectionController as a, RawObservationSink as i, QrDetectionControllerDeps as n, QrScanStatus as r, QrDetectionController as t };

package/dist/qr-frontend--fFX25mV.d.ts

@@ -0,0 +1,58 @@
+import { r as Point2 } from "./qr-pose-D2rfu5DA.js";
+
+//#region ../src/ar/qr-frontend.d.ts
+/** Raw RGBA pixels of the frame fed to detection (top-left origin). */
+interface RgbaImage {
+  data: Uint8ClampedArray;
+  width: number;
+  height: number;
+}
+/** One decoded QR: its 4 corner pixels and the decoded text (the level URL). */
+interface QrDetection {
+  corners: [Point2, Point2, Point2, Point2];
+  text: string;
+}
+/** Front-agnostic detect+decode contract. */
+interface QrFrontEnd {
+  readonly kind: 'barcode-detector';
+  /** Detect the first QR in the frame, or `null` if none. */
+  detect(image: RgbaImage): Promise<QrDetection | null>;
+  /** Free any native resources. */
+  dispose?(): void;
+}
+/** The native-`BarcodeDetector` result shape we consume. */
+interface DetectedBarcodeLike {
+  rawValue: string;
+  cornerPoints: ReadonlyArray<{
+    x: number;
+    y: number;
+  }>;
+  format?: string;
+}
+/** The slice of `BarcodeDetector` we depend on. */
+interface BarcodeDetectorLike {
+  detect(image: unknown): Promise<DetectedBarcodeLike[]>;
+}
+/**
+ * Convert our `RgbaImage` into something `BarcodeDetector.detect` accepts
+ * (`ImageData` is a valid `ImageBitmapSource`). Injected so tests need no DOM.
+ */
+type ToImageBitmapSource = (image: RgbaImage) => unknown;
+declare class BarcodeDetectorFrontEnd implements QrFrontEnd {
+  readonly kind = "barcode-detector";
+  private readonly detector;
+  private readonly toSource;
+  constructor(detector: BarcodeDetectorLike, toSource?: ToImageBitmapSource);
+  detect(image: RgbaImage): Promise<QrDetection | null>;
+}
+/**
+ * Build a {@link BarcodeDetectorFrontEnd} if the runtime exposes a
+ * `BarcodeDetector` constructor; otherwise `null` (→ the caller must handle the
+ * unsupported-browser case; there is no OpenCV fallback). `ctor` is injectable
+ * for tests.
+ */
+declare function createBarcodeDetectorFrontEnd(ctor?: new (opts: {
+  formats: string[];
+}) => BarcodeDetectorLike): BarcodeDetectorFrontEnd | null;
+//#endregion
+export { QrFrontEnd as a, createBarcodeDetectorFrontEnd as c, QrDetection as i, BarcodeDetectorLike as n, RgbaImage as o, DetectedBarcodeLike as r, ToImageBitmapSource as s, BarcodeDetectorFrontEnd as t };

package/dist/qr-pose-D2rfu5DA.d.ts

@@ -0,0 +1,138 @@
+import { Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-pose.d.ts
+/** A 2D point in image/pixel space (top-left origin, x right, y down). */
+interface Point2 {
+  x: number;
+  y: number;
+}
+/** Pinhole intrinsics in pixels for the exact buffer fed to the detector. */
+interface CameraIntrinsics {
+  fx: number;
+  fy: number;
+  cx: number;
+  cy: number;
+}
+/** A rigid pose: rotation quaternion [x,y,z,w] + position [x,y,z]. */
+interface Pose {
+  position: Vector3;
+  rotation: Quaternion;
+}
+/** Raw OpenCV `solvePnP` output: Rodrigues rotation vector + translation. */
+interface OpenCvPnpResult {
+  /** Rodrigues rotation vector (axis · angle), OpenCV camera frame. */
+  rvec: Vector3;
+  /** Translation (object origin in OpenCV camera frame), meters. */
+  tvec: Vector3;
+}
+/**
+ * Injected planar-PnP solver. The production implementation is the pure-JS
+ * {@link PlanarPnpSquare} (planar-pnp.ts, IPPE); tests inject a stub. Returns `null`
+ * when the solve fails (degenerate input, no convergence).
+ */
+interface SolvePnpSquare {
+  solve(objectPoints: readonly Vector3[], imagePoints: readonly Point2[], intrinsics: CameraIntrinsics): OpenCvPnpResult | null;
+}
+/** Inputs for {@link solveQrPose}. */
+interface SolveQrPoseInput {
+  /** The 4 detected corners, ordered TL, TR, BR, BL (symbol reading order). */
+  imagePoints: readonly Point2[];
+  /** Printed physical side length of the QR, meters (from the level file). */
+  sizeM: number;
+  /** Intrinsics for the exact pixel buffer the corners came from. */
+  intrinsics: CameraIntrinsics;
+  /** Capturing camera pose in raw-WebXR/odom space (`DepthSample.cameraPos/Rot`). */
+  cameraPose: Pose;
+  /** The PnP backend. */
+  solver: SolvePnpSquare;
+  /**
+   * Reject the detection when the RMS reprojection error exceeds this many
+   * pixels. Default 4 px (research2's runtime-stability heuristic).
+   */
+  maxReprojectionErrorPx?: number;
+}
+/** Result of {@link solveQrPose}. */
+interface QrPoseSolution {
+  /** QR pose in raw-WebXR/odom space, ready to hang off `arWorldGroup`. */
+  qrPoseWorld: Pose;
+  /** QR pose relative to the WebXR camera (pre-composition). */
+  qrPoseInCamera: Pose;
+  /** RMS reprojection error in pixels (lower = better intrinsics/pose fit). */
+  reprojectionErrorPx: number;
+}
+/**
+ * Build the 4 object points of a centered planar square of side `sizeM`, in
+ * the QR-local frame (+x right, +y up, z = 0), ordered TL, TR, BR, BL to match
+ * the detector's symbol reading order.
+ */
+declare function buildObjectPoints(sizeM: number): [Vector3, Vector3, Vector3, Vector3];
+/**
+ * Derive pinhole intrinsics (pixels) from a column-major GL projection matrix
+ * for a detector frame of `width`×`height`. Valid for an axis-aligned frustum
+ * (no skew); principal point uses the TOP-LEFT-origin pixel convention.
+ *
+ * Derivation (see qr-pose.ts.md): for clip = P·v_view and pixel
+ * px = (ndc.x+1)·W/2, py = (1−ndc.y)·H/2 with ndc = clip.xy / (−Z):
+ *   fx = P[0]·W/2, fy = P[5]·H/2, cx = (1−P[8])·W/2, cy = (1+P[9])·H/2.
+ */
+declare function intrinsicsFromProjection(projection: Matrix4, width: number, height: number): CameraIntrinsics;
+/**
+ * Project a point given in the WebXR camera frame (+x right, +y up, −z forward)
+ * to a pixel (top-left origin). Returns `null` for points not strictly in front
+ * of the camera (z ≥ 0) or non-finite results.
+ */
+declare function projectViewPoint(pointInCamera: Vector3, intrinsics: CameraIntrinsics): Point2 | null;
+/**
+ * Convert a solved OpenCV pose (object→OpenCV-camera) into the QR pose in the
+ * WebXR camera frame. Left-multiply by Rx(π): rotation = Rx(π)·R, position =
+ * Rx(π)·t = (t0, −t1, −t2).
+ */
+declare function qrInCameraFromOpenCv(pnp: OpenCvPnpResult): Pose;
+/** Compose two rigid poses: result = parent ∘ child (child expressed in parent). */
+declare function composePose(parent: Pose, child: Pose): Pose;
+/** Invert a rigid pose: if pose maps A→B, the result maps B→A. */
+declare function invertPose(pose: Pose): Pose;
+/**
+ * Signed area of the quad TL→TR→BR→BL via the shoelace formula, in image
+ * pixels (top-left origin, y down). A front-facing QR imaged in symbol order is
+ * clockwise on screen → POSITIVE signed area in this y-down convention. A
+ * negative value means the winding is reversed (mirrored / wrong corner order)
+ * — the #1 pose bug the briefs warn about.
+ */
+declare function signedQuadArea(corners: readonly Point2[]): number;
+/** Result of {@link validateQuad}. */
+interface QuadValidation {
+  ok: boolean;
+  /** True when the quad winding is reversed (mirrored corner order). */
+  mirrored: boolean;
+  /** True when the quad is too small or too thin to trust. */
+  degenerate: boolean;
+  /** |signed area| in px² — useful for a "too small" threshold. */
+  areaPx2: number;
+}
+/**
+ * Validate the 4 detected corners (assumed ordered TL, TR, BR, BL). Rejects a
+ * mirrored winding and degenerate (tiny / collinear) quads. This does NOT
+ * re-sort by image position — that would destroy the reading orientation the
+ * detector encodes; it only guards the known failure modes.
+ */
+declare function validateQuad(corners: readonly Point2[], options?: {
+  minAreaPx2?: number;
+}): QuadValidation;
+/**
+ * RMS reprojection error (pixels): project the object points through
+ * `qrPoseInCamera` (WebXR frame) and the pinhole model, compare to the detected
+ * image points. `Infinity` if any point falls behind the camera.
+ */
+declare function reprojectionErrorPx(objectPoints: readonly Vector3[], imagePoints: readonly Point2[], qrPoseInCamera: Pose, intrinsics: CameraIntrinsics): number;
+/** Apply a rigid pose to a point: result = rotation·p + position. */
+declare function transformPoint(point: Vector3, pose: Pose): Vector3;
+/**
+ * Full pipeline: detected corners → QR pose in raw-WebXR/odom space. Validates
+ * the quad, solves PnP (injected), converts OpenCV→WebXR, composes with the
+ * camera pose, and gates on reprojection error. Returns `null` when the
+ * detection is rejected at any stage.
+ */
+declare function solveQrPose(input: SolveQrPoseInput): QrPoseSolution | null;
+//#endregion
+export { solveQrPose as _, QrPoseSolution as a, SolveQrPoseInput as c, intrinsicsFromProjection as d, invertPose as f, signedQuadArea as g, reprojectionErrorPx as h, Pose as i, buildObjectPoints as l, qrInCameraFromOpenCv as m, OpenCvPnpResult as n, QuadValidation as o, projectViewPoint as p, Point2 as r, SolvePnpSquare as s, CameraIntrinsics as t, composePose as u, transformPoint as v, validateQuad as y };