gps-plus-slam-app-framework 1.10.0 → 1.11.0

package/dist/{webxr-session-DWKUsCN9.js → webxr-session-OyR3YbTq.js}

@@ -1,3 +1,4 @@
+import { DEFAULT_AR_CRASH_ISOLATION, validateArCrashIsolationOptions } from "./ar/ar-crash-isolation.js";
 import { createLogger } from "./utils/logger.js";
 import { CameraBlitCapture, computeAspectFitSize, computeCaptureSize } from "./ar/camera-blit-capture.js";
 import { applyChromiumProjectionLayerWorkaround } from "./ar/chromium-camera-access-workaround.js";
@@ -5,12 +6,11 @@ import { DepthSampler, wrapXRDepthInfo } from "./ar/depth-sampler.js";
 import { WEBXR_TO_NUE } from "./ar/webxr-nue-basis.js";
 import { clearFrameUpdates, runFrameUpdates } from "./ar/frame-loop.js";
 import { clearXrFrameUpdates, runXrFrameUpdates } from "./ar/xr-frame-loop.js";
-import { n as ImageCaptureManager, t as DEFAULT_CAPTURE_CONFIG } from "./image-capture-BUqqsOi3.js";
+import { n as ImageCaptureManager, t as DEFAULT_CAPTURE_CONFIG } from "./image-capture-C4DwxC10.js";
 import { clearLastRestartedPayload, originReset, poseLost, poseReceived, resetTracking, selectLastRestartedPayload, selectTrackingPhase } from "./state/tracking-slice.js";
 import { acquireCameraTexture } from "./ar/xr-camera-texture.js";
-import { n as runSessionDisposers } from "./session-disposers-BZS-hi8u.js";
-import { t as getLastDeviceOrientation } from "./device-orientation-cache-BjEaEAmh.js";
-import { DEFAULT_RECORDING_OPTIONS, validateArCrashIsolationOptions } from "./state/recording-options.js";
+import { n as runSessionDisposers } from "./session-disposers-B7hUN90w.js";
+import { t as getLastDeviceOrientation } from "./device-orientation-cache-j-kLP8he.js";
 import { SCENE_NODE } from "./ar/scene-node-names.js";
 import { createCss3dRendererManager } from "./visualization/css3d-renderer-manager.js";
 import * as THREE from "three";
@@ -132,6 +132,7 @@ function createRgbLookup(pixels, width, height) {
 * The camera's WORLD transform is the GPS-aligned world pose.
 */
 const log = createLogger("WebXR");
+/** Runtime guard for `XRView.camera` candidates (finite, positive dimensions). */
 function isXRCameraLike(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const camera = value;
@@ -181,6 +182,67 @@ function getXrCameraFromPose(pose) {
 function shouldLogCameraAccessDiagnostic(pose, alreadyLogged, captureActive) {
 	return pose !== null && !alreadyLogged && captureActive;
 }
+/**
+* Extract the reset transform from an XRReferenceSpaceEvent-like object.
+*
+* Distinguishes three cases per OdometryTrackingRestartedPayload semantics:
+* - Transform property missing (older browsers) → returns `undefined`
+* - Transform property present but null (runtime can't determine delta) → returns `null`
+* - Transform property present with data → returns `ResetTransformData`
+*
+* This is a pure function extracted for testability.
+*
+* @param event - The event object, cast to a record with an optional transform property
+* @returns ResetTransformData, null, or undefined
+*/
+function extractResetTransformData(event) {
+	if (!("transform" in event)) return;
+	const transform = event.transform;
+	if (!transform) return null;
+	const pos = transform.position;
+	const ori = transform.orientation;
+	return {
+		position: [
+			pos.x,
+			pos.y,
+			pos.z
+		],
+		orientation: [
+			ori.x,
+			ori.y,
+			ori.z,
+			ori.w
+		]
+	};
+}
+/**
+* Extract pose data from an XRViewerPose.
+* Returns null if pose or views are unavailable.
+*
+* This is a pure function extracted for testability.
+*
+* @param pose - The XRViewerPose from frame.getViewerPose()
+* @returns ARPose with position and orientation, or null
+*/
+function extractPoseFromViewer(pose) {
+	if (!pose) return null;
+	const view = pose.views[0];
+	if (!view) return null;
+	const { position, orientation } = view.transform;
+	return {
+		position: {
+			x: position.x,
+			y: position.y,
+			z: position.z
+		},
+		orientation: {
+			x: orientation.x,
+			y: orientation.y,
+			z: orientation.z,
+			w: orientation.w
+		}
+	};
+}
 let renderer = null;
 let scene = null;
 let camera = null;
@@ -207,7 +269,6 @@ function resetWebXRState() {
 	camera = null;
 	xrSession = null;
 	arWorldGroup = null;
-	arPoseNode = null;
 	latestArPose = null;
 	lastFrameTime = 0;
 	clearFrameUpdates();
@@ -218,6 +279,7 @@ function resetWebXRState() {
 	getScreenRotation = null;
 	onCaptureFailed = null;
 	onSuspiciousImage = null;
+	imageQualityAnalyzer = null;
 	if (trackingPhaseUnsubscribe) {
 		trackingPhaseUnsubscribe();
 		trackingPhaseUnsubscribe = null;
@@ -251,7 +313,7 @@ function resetWebXRState() {
 	getCameraTextureNullCount = 0;
 	latestCameraWidth = 0;
 	latestCameraHeight = 0;
-	currentArCrashIsolationOptions = { ...DEFAULT_RECORDING_OPTIONS.arCrashIsolation };
+	currentArCrashIsolationOptions = { ...DEFAULT_AR_CRASH_ISOLATION };
 	cleanupBlitResources();
 }
 /**
@@ -261,12 +323,6 @@ function resetWebXRState() {
 */
 let arWorldGroup = null;
 /**
-* The arpose Object3D — intermediate node between arWorldGroup and camera.
-* During recording it stays at identity; during replay it receives recorded
-* odomPosition/odomRotation from the store subscriber.
-*/
-let arPoseNode = null;
-/**
 * Stores the latest raw AR pose from WebXR (updated every frame).
 * This is read by the GPS callback to create paired GPS+AR events.
 */
@@ -276,39 +332,39 @@ let latestArPose = null;
 */
 let imageCaptureManager = null;
 /**
-* Callback for when an image is captured (set via setImageCaptureCallback)
+* Callback for when an image is captured (initAR `callbacks.imageCapture`)
 */
 let onImageCaptured = null;
 /**
-* Callback for when image capture fails (set via setImageCaptureCallback)
+* Callback for when image capture fails (initAR `callbacks.imageCapture`)
 */
 let onCaptureFailed = null;
 /**
 * Callback for when a captured image appears suspicious/black
-* (set via setImageCaptureCallback)
+* (initAR `callbacks.imageCapture`)
 */
 let onSuspiciousImage = null;
 /**
-* Screen rotation getter (set via setImageCaptureCallback)
+* Screen rotation getter (initAR `callbacks.imageCapture`)
 */
 let getScreenRotation = null;
 /**
-* Off-thread image-quality analyzer (set via {@link setImageQualityAnalyzer}).
+* Off-thread image-quality analyzer (initAR `callbacks.imageCapture.qualityAnalyzer`).
 * Device-specific (a Web Worker in the recorder), so it is INJECTED rather than
 * built here. Forwarded to `ImageCaptureManager` as its `analyzeFrame` callback;
 * the manager only invokes it when `config.qualityFilter.enabled`. `null` ⇒ the
-* legacy save-immediately path.
+* legacy save-immediately path. Per-session: cleared by resetWebXRState() like
+* every other init-time callback (the host re-passes it each session).
 */
 let imageQualityAnalyzer = null;
 /**
-* Redux store injected by the host (`setTrackingStore`). When present
-* together with `onTrackingRestarted`, `onXRFrame` dispatches
-* `poseReceived`/`poseLost`, the XR reference-space reset listener
-* dispatches `originReset`, and a `subscribeToSelector` translation
-* surface translates phase transitions back into the existing
-* `onTrackingLost` / `onTrackingRestarted` / `onTrackingRecovered`
-* callbacks. When the store is absent the tracking pipeline simply
-* no-ops.
+* Redux store injected by the host (initAR `callbacks.tracking.store`;
+* swapped mid-session via {@link rebindTrackingStore}). When present,
+* `onXRFrame` dispatches `poseReceived`/`poseLost`, the XR reference-space
+* reset listener dispatches `originReset`, and a subscription translates
+* phase transitions back into the host's `onTrackingLost` /
+* `onTrackingRestarted` / `onTrackingRecovered` callbacks. When the store
+* is absent the tracking pipeline simply no-ops.
 */
 let trackingStore = null;
 /**
@@ -318,22 +374,22 @@ let trackingStore = null;
 */
 let trackingPhaseUnsubscribe = null;
 /**
-* Callback for when tracking restarts (set via setTrackingCallbacks)
+* Callback for when tracking restarts (initAR `callbacks.tracking.onRestarted`)
 */
 let onTrackingRestarted = null;
 /**
-* Callback for when tracking is lost (set via setTrackingLostCallback)
+* Callback for when tracking is lost (initAR `callbacks.tracking.onLost`)
 * Field Test Readiness Issue #3: Provide user feedback when tracking is lost
 */
 let onTrackingLost = null;
 /**
 * Callback for when tracking recovers seamlessly without origin reset (Case 1).
-* Set via setTrackingRecoveredCallback.
+* initAR `callbacks.tracking.onRecovered`.
 */
 let onTrackingRecovered = null;
 /**
 * Host callback fired exactly once whenever the XRSession ends — on BOTH the
-* app-initiated and the system-initiated path (set via setSessionEndCallback).
+* app-initiated and the system-initiated path (initAR `callbacks.onSessionEnd`).
 * Cleared by resetWebXRState() like every other module-level callback.
 */
 let onSessionEnd = null;
@@ -350,7 +406,7 @@ let endRequestedByApp = false;
 */
 let depthSampler = null;
 /**
-* Callback for when a depth sample is captured (set via setDepthCaptureCallback)
+* Callback for when a depth sample is captured (initAR `callbacks.depth`)
 */
 let onDepthCaptured = null;
 /**
@@ -410,7 +466,7 @@ let cameraFrameBlit = null;
 * so 1024 is the safe default. Raise per-consumer via
 * `startCameraFrameCapture({ captureSize })`.
 *
-* @see GpsPlusSlamJs_Docs/docs/2026-06-17-qr-size-accuracy-and-thin-demo-plan.md (WS-C)
+* @see GpsPlusSlamJs_Docs/docs/2026-06-17-1020-qr-size-accuracy-and-thin-demo-plan.md (WS-C)
 */
 const DEFAULT_CAMERA_FRAME_CAPTURE_SIZE = 1024;
 /**
@@ -434,7 +490,7 @@ let cameraFrameCaptureSize = DEFAULT_CAMERA_FRAME_CAPTURE_SIZE;
 * SCOPE note in `camera-frame-source.ts`.
 */
 let cameraFrameSource = null;
-/** Callback for each throttled camera RGBA frame (set via setCameraFrameCallback). */
+/** Callback for each throttled camera RGBA frame (initAR `callbacks.cameraFrame`). */
 let onCameraFrame = null;
 /**
 * Latest WebXR camera texture, updated each frame when camera-access is enabled.
@@ -459,7 +515,7 @@ let cameraAccessLoggedOnce = false;
 */
 let getCameraTextureNullCount = 0;
 const GET_CAMERA_TEXTURE_LOG_THRESHOLD = 5;
-let currentArCrashIsolationOptions = { ...DEFAULT_RECORDING_OPTIONS.arCrashIsolation };
+let currentArCrashIsolationOptions = { ...DEFAULT_AR_CRASH_ISOLATION };
 /**
 * Dispose blit capture resources and clear the cached camera texture.
 * Shared by resetWebXRState() and stopImageCapture() to avoid duplication.
@@ -499,67 +555,6 @@ function acquireCameraFrameRgba() {
 	return cameraFrameBlit.captureToRgba(renderer, latestCameraTexture);
 }
 /**
-* Extract the reset transform from an XRReferenceSpaceEvent-like object.
-*
-* Distinguishes three cases per OdometryTrackingRestartedPayload semantics:
-* - Transform property missing (older browsers) → returns `undefined`
-* - Transform property present but null (runtime can't determine delta) → returns `null`
-* - Transform property present with data → returns `ResetTransformData`
-*
-* This is a pure function extracted for testability.
-*
-* @param event - The event object, cast to a record with an optional transform property
-* @returns ResetTransformData, null, or undefined
-*/
-function extractResetTransformData(event) {
-	if (!("transform" in event)) return;
-	const transform = event.transform;
-	if (!transform) return null;
-	const pos = transform.position;
-	const ori = transform.orientation;
-	return {
-		position: [
-			pos.x,
-			pos.y,
-			pos.z
-		],
-		orientation: [
-			ori.x,
-			ori.y,
-			ori.z,
-			ori.w
-		]
-	};
-}
-/**
-* Extract pose data from an XRViewerPose.
-* Returns null if pose or views are unavailable.
-*
-* This is a pure function extracted for testability.
-*
-* @param pose - The XRViewerPose from frame.getViewerPose()
-* @returns ARPose with position and orientation, or null
-*/
-function extractPoseFromViewer(pose) {
-	if (!pose) return null;
-	const view = pose.views[0];
-	if (!view) return null;
-	const { position, orientation } = view.transform;
-	return {
-		position: {
-			x: position.x,
-			y: position.y,
-			z: position.z
-		},
-		orientation: {
-			x: orientation.x,
-			y: orientation.y,
-			z: orientation.z,
-			w: orientation.w
-		}
-	};
-}
-/**
 * Get the current raw AR pose from the latest XR frame.
 * This is updated every frame and should be called when GPS arrives
 * to get the AR pose at that moment.
@@ -576,6 +571,12 @@ function getCurrentArPose() {
 * Build XR session init options.
 * Extracted as a pure function for testability.
 *
+* Exported for unit testing only (surface-reduction step 3, B-5 precedent):
+* production code reaches this exclusively through {@link initAR}; the export
+* exists so `webxr-session.test.ts` can pin the full session-negotiation
+* matrix (isolation flags × session features) without mocking a renderer and
+* `navigator.xr` for every combination. Not re-exported by the ar/ barrel.
+*
 * @param rootElement - The DOM element for DOM overlay
 * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
 *   depth-sensing, camera-access)
@@ -629,6 +630,10 @@ async function isWebXRSupported() {
 * Note: these apply to WebGL content only. The CSS3D minimap is composited by
 * the browser from the camera fov alone — near/far do not clip it (F1 in the
 * same feedback doc).
+*
+* Module-private since surface-reduction step 3 (no consumer outside this
+* file): the values are pinned observably on the constructed camera by the
+* `createSceneHierarchy` frustum test in `webxr-session.test.ts`.
 */
 const AR_CAMERA_FOV = 70;
 const AR_CAMERA_NEAR = .01;
@@ -681,7 +686,7 @@ function createSceneHierarchy() {
 	const newArPose = new THREE.Object3D();
 	newArPose.name = "ar-pose";
 	newBasisChangeNode.add(newArPose);
-	const newCamera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, AR_CAMERA_NEAR, 200);
+	const newCamera = new THREE.PerspectiveCamera(AR_CAMERA_FOV, window.innerWidth / window.innerHeight, AR_CAMERA_NEAR, AR_CAMERA_FAR);
 	newArPose.add(newCamera);
 	const ambientLight = new THREE.AmbientLight(16777215, .5);
 	newScene.add(ambientLight);
@@ -701,10 +706,27 @@ function createSceneHierarchy() {
 * @param isolationOptions - Crash-isolation diagnostic flags.
 * @param sessionFeatures - Opt-in standard WebXR features (e.g.
 *   `requestHitTest`) forwarded to the session negotiation.
+* @param callbacks - Host callbacks for this session (see
+*   {@link ArSessionCallbacks}); unpacked once into module slots that
+*   `resetWebXRState()` clears at session end.
 */
-async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
+async function initAR(container, isolationOptions = {}, sessionFeatures = {}, callbacks = {}) {
 	if (!navigator.xr) throw new Error("WebXR not available");
 	if (renderer || xrSession) throw new Error("AR session already initialized — call endARSession() before initAR() again");
+	onImageCaptured = callbacks.imageCapture?.onCaptured ?? null;
+	getScreenRotation = callbacks.imageCapture?.getScreenRotation ?? null;
+	onCaptureFailed = callbacks.imageCapture?.onFailed ?? null;
+	onSuspiciousImage = callbacks.imageCapture?.onSuspicious ?? null;
+	imageQualityAnalyzer = callbacks.imageCapture?.qualityAnalyzer ?? null;
+	trackingStore = callbacks.tracking?.store ?? null;
+	onTrackingRestarted = callbacks.tracking?.onRestarted ?? null;
+	onTrackingLost = callbacks.tracking?.onLost ?? null;
+	onTrackingRecovered = callbacks.tracking?.onRecovered ?? null;
+	onDepthCaptured = callbacks.depth?.onCaptured ?? null;
+	onDepthUnavailable = callbacks.depth?.onUnavailable ?? null;
+	onCameraFrame = callbacks.cameraFrame?.onFrame ?? null;
+	onFrameCallback = callbacks.onFrame ?? null;
+	onSessionEnd = callbacks.onSessionEnd ?? null;
 	currentArCrashIsolationOptions = validateArCrashIsolationOptions(isolationOptions);
 	if (currentArCrashIsolationOptions.applyChromiumProjectionLayerWorkaround) applyChromiumProjectionLayerWorkaround();
 	renderer = new THREE.WebGLRenderer({
@@ -719,7 +741,6 @@ async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
 	const hierarchy = createSceneHierarchy();
 	scene = hierarchy.scene;
 	arWorldGroup = hierarchy.arWorldGroup;
-	arPoseNode = hierarchy.arpose;
 	camera = hierarchy.camera;
 	const sessionOptions = buildSessionOptions(container, currentArCrashIsolationOptions, sessionFeatures);
 	xrSession = await navigator.xr.requestSession("immersive-ar", sessionOptions);
@@ -727,8 +748,7 @@ async function initAR(container, isolationOptions = {}, sessionFeatures = {}) {
 		handleSessionEnded();
 	});
 	await renderer.xr.setSession(xrSession);
-	if (onTrackingRestarted !== null !== (trackingStore !== null)) log.warn(trackingStore ? "Tracking pipeline half-wired: setTrackingStore() was called but setTrackingCallbacks() was not — no tracking callbacks will fire. Call both before initAR()." : "Tracking pipeline half-wired: setTrackingCallbacks() was called but setTrackingStore() was not — the tracking slice will not update. Call both before initAR().");
-	if (onTrackingRestarted && trackingStore) {
+	if (trackingStore) {
 		const store = trackingStore;
 		store.dispatch(resetTracking());
 		trackingPhaseUnsubscribe = subscribeToTrackingPhase(store);
@@ -812,11 +832,11 @@ function subscribeToTrackingPhase(store) {
 }
 /**
 * Dispatch the per-frame `poseReceived` / `poseLost` action into the
-* tracking slice. No-op when no store is bound or when tracking wiring
-* was not requested.
+* tracking slice. No-op when no store is bound (tracking wiring was not
+* requested via initAR `callbacks.tracking`).
 */
 function updateTrackingState(arPose) {
-	if (!trackingStore || !onTrackingRestarted) return;
+	if (!trackingStore) return;
 	if (arPose) trackingStore.dispatch(poseReceived({
 		pose: arPose,
 		sensorOrientation: snapshotDeviceOrientation()
@@ -920,48 +940,6 @@ function getCamera() {
 	return camera;
 }
 /**
-* Set the scene externally (for replay mode).
-* Allows non-WebXR code paths to register a scene so that modules
-* calling getScene() receive it.
-* @see docs/2026-02-19-replay-mode.md Risk R1
-*/
-function setScene(s) {
-	scene = s;
-}
-/**
-* Set the AR world group externally (for replay mode).
-* Allows non-WebXR code paths to register an arWorldGroup so that
-* applyAlignmentMatrix() and visualizers work correctly.
-* @see docs/2026-02-19-replay-mode.md Risk R1
-*/
-function setArWorldGroup(g) {
-	arWorldGroup = g;
-}
-/**
-* Set the camera externally (for replay mode).
-* Allows non-WebXR code paths to register a camera so that modules
-* calling getCamera() receive it.
-* @see docs/2026-02-19-replay-mode.md Risk R1
-*/
-function setCamera(c) {
-	camera = c;
-}
-/**
-* Get the arpose Object3D (intermediate node between arWorldGroup and camera).
-* Returns null before scene initialization.
-*/
-function getArPose() {
-	return arPoseNode;
-}
-/**
-* Set the arpose Object3D externally (for replay mode).
-* Allows non-WebXR code paths to register an arpose so that
-* store subscribers can update it with recorded odom data.
-*/
-function setArPose(a) {
-	arPoseNode = a;
-}
-/**
 * Apply an alignment matrix to the AR world group.
 *
 * The alignment matrix maps odometry positions in NUE space
@@ -1021,20 +999,6 @@ function nueQuaternionToWebXR$1(nue) {
 	return nueQuaternionToWebXR(nue);
 }
 /**
-* Register a host callback fired exactly once whenever the XRSession ends —
-* app-initiated ({@link endARSession}) AND system-initiated (e.g. the Android
-* back gesture, which ends an immersive session directly and uncancelably).
-* `info.requestedByApp` discriminates the two. Fired AFTER the full teardown,
-* so the host can immediately start a fresh session from inside the callback.
-*
-* Cleared by resetWebXRState() (i.e. after every session end) like the other
-* module-level callbacks — re-register before/with each new session.
-* Pass `null` to unregister. F3, 2026-07-04 user feedback.
-*/
-function setSessionEndCallback(cb) {
-	onSessionEnd = cb;
-}
-/**
 * The ONE teardown for a session that has ended, shared by both trigger
 * paths via the XRSession 'end' listener. Before F3 the system-initiated
 * path (back gesture) only nulled `xrSession`/`latestArPose`, leaving the
@@ -1077,41 +1041,14 @@ async function endARSession() {
 	}
 }
 /**
-* Set up image capture callbacks.
-* Call this before starting image capture to wire up the callback handlers.
-*
-* @param onCaptured - Called when an image is successfully captured
-* @param screenRotationGetter - Returns current device screen rotation (0, 90, 180, 270)
-* @param onFailed - Optional callback for when image capture fails (e.g., low memory)
-* @param onSuspicious - Optional callback for when a captured image appears black/empty
-*/
-function setImageCaptureCallback(onCaptured, screenRotationGetter, onFailed, onSuspicious) {
-	onImageCaptured = onCaptured;
-	getScreenRotation = screenRotationGetter;
-	onCaptureFailed = onFailed ?? null;
-	onSuspiciousImage = onSuspicious ?? null;
-}
-/**
-* Inject (or clear) the off-thread image-quality analyzer used by the blur/
-* blackness drop+retry gate. Pass the recorder's Web Worker-backed analyzer to
-* enable the gate, or `null` to clear it (legacy save-immediately path). Must be
-* set BEFORE {@link startImageCapture} for the active recording — the manager
-* reads it once when constructed. The analyzer only runs when the capture
-* config's `qualityFilter.enabled` is true, so injecting it is harmless when the
-* gate is off. Ownership/disposal of the worker is the caller's responsibility.
-*/
-function setImageQualityAnalyzer(analyzer) {
-	imageQualityAnalyzer = analyzer;
-}
-/**
 * Start capturing images during recording.
-* Must call setImageCaptureCallback first.
+* Requires the `imageCapture` callbacks group to have been passed to initAR.
 *
 * @param config - Optional capture configuration. Accepts the whole user
 *   image-options section (`intervalMs`, `quality`, `resolutionDivisor`; any
 *   extra keys such as `enabled` are ignored). Passing the section as one
 *   object means a newly-added option flows through without editing this seam
-*   — see `2026-06-12-payload-rebuild-field-drop-audit.md` (F3).
+*   — see `2026-06-12-1130-payload-rebuild-field-drop-audit.md` (F3).
 */
 function startImageCapture(config) {
 	if (!renderer) {
@@ -1188,16 +1125,27 @@ function getImageCaptureFrameCount() {
 	return imageCaptureManager?.getFrameCount() ?? 0;
 }
 /**
-* Inject the Redux store used by the tracking-state slice pipeline.
+* Re-point the tracking pipeline at a NEW store mid-session.
+*
+* This is the ONE mutation that deliberately survived the fold of the
+* pre-init setters into initAR's `callbacks` (surface-reduction step 1):
+* it is a genuine RUNTIME need, not init-time wiring — the recorder swaps
+* its Redux store for every recording started inside a single AR session,
+* and without re-pointing, every per-frame `poseReceived` dispatch would
+* keep flowing into the orphaned previous store, pinning the new store's
+* `tracking.phase` at 'initializing' (Finding #1, 2026-05-23 user
+* feedback). Everything else about a session's callbacks stays fixed from
+* `initAR` until `resetWebXRState()`.
 *
-* MUST be called before `initAR()` whenever the host also wires tracking
-* callbacks via `setTrackingCallbacks`. Without a store the tracking
-* pipeline silently no-ops.
+* Matches the old `setTrackingStore` semantics exactly: an active phase
+* subscription to the previous store is torn down before swapping (the
+* phase subscription itself is only (re)established inside `initAR`).
+* No-op pipeline when tracking was not wired at init (the host callbacks
+* stay whatever `initAR` set).
 *
 * @param store — any store satisfying {@link TrackingSubscribableStore}.
-*   `null` clears the binding (useful for teardown in tests).
 */
-function setTrackingStore(store) {
+function rebindTrackingStore(store) {
 	if (trackingPhaseUnsubscribe) {
 		trackingPhaseUnsubscribe();
 		trackingPhaseUnsubscribe = null;
@@ -1205,47 +1153,9 @@ function setTrackingStore(store) {
 	trackingStore = store;
 }
 /**
-* Set up tracking state callbacks.
-* Call this BEFORE initAR() to enable tracking restart detection.
-*
-* @param onRestarted - Called when tracking restarts after being lost
-*/
-function setTrackingCallbacks(onRestarted) {
-	onTrackingRestarted = onRestarted;
-}
-/**
-* Set a callback for when AR tracking is lost.
-* Call this BEFORE initAR() to enable tracking loss notifications.
-* Field Test Readiness Issue #3: Provide user feedback when tracking is lost.
-*
-* @param callback - Called when tracking is lost (pose becomes null)
-*/
-function setTrackingLostCallback(callback) {
-	onTrackingLost = callback;
-}
-/**
-* Set a callback for when AR tracking recovers seamlessly (Case 1: same coordinate frame).
-* Call this BEFORE initAR() to enable seamless recovery notifications.
-*
-* @param callback - Called when tracking recovers without origin reset
-*/
-function setTrackingRecoveredCallback(callback) {
-	onTrackingRecovered = callback;
-}
-/**
-* Set up depth capture callback.
-* Call this BEFORE initAR() to enable depth sampling.
-*
-* @param onCaptured - Called when a depth sample is captured
-* @param onUnavailable - Called once if depth is unavailable after threshold
-*/
-function setDepthCaptureCallback(onCaptured, onUnavailable) {
-	onDepthCaptured = onCaptured;
-	onDepthUnavailable = onUnavailable ?? null;
-}
-/**
 * Start depth sampling during recording.
-* Must call setDepthCaptureCallback before initAR.
+* Requires the `depth` callbacks group to have been passed to initAR
+* (the sampler is created there).
 *
 * @param config - optional sampler overrides (typically the user's
 *   `depth.intervalMs`/`depth.gridSize` recording options); applied via
@@ -1279,24 +1189,12 @@ function getDepthSampleCount() {
 	return depthSampler?.getSampleCount() ?? 0;
 }
 /**
-* Set the per-frame camera RGBA callback (B2) — the generic CV frame feed (QR
-* detection today, object detection / OpenCV later). Call this BEFORE initAR to
-* enable in-session camera frame capture; `startCameraFrameCapture` then begins
-* delivering frames.
-*
-* The callback receives a **top-left-origin** RGBA image (no JPEG round-trip),
-* captured at the throttled detection cadence — feed it straight to a
-* `BarcodeDetector` / OpenCV front-end. Mirrors `setDepthCaptureCallback`.
-*
-* @param onFrame - Called with each throttled camera frame, or `null` to clear.
-*/
-function setCameraFrameCallback(onFrame) {
-	onCameraFrame = onFrame;
-}
-/**
-* Start camera frame capture during an AR session. Must call
-* setCameraFrameCallback before initAR (the source is created there). No-op if
-* the source was not initialized (callback not set before initAR).
+* Start camera frame capture during an AR session. Requires the
+* `cameraFrame` callbacks group to have been passed to initAR (the source is
+* created there); the callback receives **top-left-origin** RGBA images (no
+* JPEG round-trip) at the throttled detection cadence — feed them straight to
+* a `BarcodeDetector` / OpenCV front-end (B2). No-op if the source was not
+* initialized (group not passed to initAR).
 *
 * The source is the single cadence owner: drive your detection scheduler from
 * the delivered frames with its own `minIntervalMs: 0` (Option A).
@@ -1330,33 +1228,5 @@ function stopCameraFrameCapture() {
 function getCameraFrameCount() {
 	return cameraFrameSource?.getFrameCount() ?? 0;
 }
-/**
-* The current longer-edge resolution (px) of the camera-frame blit — the
-* {@link DEFAULT_CAMERA_FRAME_CAPTURE_SIZE} default unless overridden via
-* `startCameraFrameCapture({ captureSize })`. Exposed for diagnostics and to
-* let tests assert the on-device-tuned default without reaching into module
-* state.
-*/
-function getCameraFrameCaptureSize() {
-	return cameraFrameCaptureSize;
-}
-/**
-* Set a per-frame callback for custom updates.
-* The callback is invoked every XR frame after pose updates but before render.
-* Useful for updating elements that need to follow the camera smoothly
-* (e.g., map overlay position).
-*
-* @param callback - Function to call each frame, or null to clear
-*/
-function setFrameCallback(callback) {
-	onFrameCallback = callback;
-}
-/**
-* Get the CSS3D renderer manager for live AR mode.
-* Returns null if no AR session is active or CSS3D was not created.
-*/
-function getLiveCss3dManager() {
-	return css3dManager;
-}
 //#endregion
-export { setArWorldGroup as A, setTrackingLostCallback as B, initAR as C, nueQuaternionToWebXR$1 as D, nuePositionToWebXR as E, setImageCaptureCallback as F, startDepthCapture as G, setTrackingStore as H, setImageQualityAnalyzer as I, stopDepthCapture as J, startImageCapture as K, setScene as L, setCameraFrameCallback as M, setDepthCaptureCallback as N, resetWebXRState as O, setFrameCallback as P, setSessionEndCallback as R, getXrCameraFromPose as S, isXRCameraLike as T, shouldLogCameraAccessDiagnostic as U, setTrackingRecoveredCallback as V, startCameraFrameCapture as W, CameraFrameSource as X, stopImageCapture as Y, getDepthInfoFromFrame as _, applyAlignmentMatrix as a, getLiveCss3dManager as b, endARSession as c, getArPose as d, getArWorldGroup as f, getCurrentArPose as g, getCameraFrameCount as h, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as i, setCamera as j, setArPose as k, extractPoseFromViewer as l, getCameraFrameCaptureSize as m, AR_CAMERA_FOV as n, buildSessionOptions as o, getCamera as p, stopCameraFrameCapture as q, AR_CAMERA_NEAR as r, createSceneHierarchy as s, AR_CAMERA_FAR as t, extractResetTransformData as u, getDepthSampleCount as v, isWebXRSupported as w, getScene as x, getImageCaptureFrameCount as y, setTrackingCallbacks as z };
+export { stopImageCapture as A, resetWebXRState as C, startImageCapture as D, startDepthCapture as E, stopCameraFrameCapture as O, rebindTrackingStore as S, startCameraFrameCapture as T, initAR as _, endARSession as a, nuePositionToWebXR as b, getArWorldGroup as c, getCurrentArPose as d, getDepthInfoFromFrame as f, getXrCameraFromPose as g, getScene as h, createSceneHierarchy as i, CameraFrameSource as j, stopDepthCapture as k, getCamera as l, getImageCaptureFrameCount as m, applyAlignmentMatrix as n, extractPoseFromViewer as o, getDepthSampleCount as p, buildSessionOptions as r, extractResetTransformData as s, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as t, getCameraFrameCount as u, isWebXRSupported as v, shouldLogCameraAccessDiagnostic as w, nueQuaternionToWebXR$1 as x, isXRCameraLike as y };

package/dist/{xr-frame-loop-25gM4B0K.d.ts → xr-frame-loop-BiZvgqP7.d.ts}

@@ -17,7 +17,7 @@
  * makes correct use the easy path and stashing the awkward one. Do NOT retain
  * `ctx` or its fields beyond the callback's synchronous execution.
  *
- * See `2026-06-03-threejs-arbutton-minimal-ar-example-user-feedback.md`
+ * See `2026-06-03-0553-threejs-arbutton-minimal-ar-example-user-feedback.md`
  * §6.2/§6.3 (option H-A2) for the design rationale.
  */
 /**