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

package/dist/{webxr-session-Do5L6G3B.d.ts → webxr-session-cRG2SYAQ.d.ts}

@@ -1,11 +1,11 @@
-import { i as DepthSample, t as ARPose } from "./ar-types-BFX2r1wk.js";
-import { i as DepthSamplerConfig } from "./depth-sampler-asc8exHt.js";
-import { t as ArCrashIsolationOptions } from "./recording-options-BPCpMHLK.js";
-import { i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, t as CapturedFrame } from "./image-capture-CNZDrQXG.js";
-import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-BuAZxXZ5.js";
-import { o as RgbaImage } from "./qr-frontend--fFX25mV.js";
-import { t as Css3dRendererManager } from "./css3d-renderer-manager-B3kGNtcn.js";
-import { r as XRCameraLike } from "./xr-camera-texture-Cva1q3Qj.js";
+import { i as DepthSample, t as ARPose } from "./ar-types-Cc5yvBwn.js";
+import { i as DepthSamplerConfig, t as DepthInfo } from "./depth-sampler-CwObAwEA.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-vASCFzc5.js";
+import { i as FrameQualityVerdict, n as CapturedImage, o as ImageCaptureConfig, t as CapturedFrame } from "./image-capture-Bp6Pd4Md.js";
+import { a as TrackingSliceState, r as ResetTransformData } from "./tracking-slice-DMkHlbny.js";
+import { o as RgbaImage } from "./qr-frontend-BPURlh3S.js";
+import { t as Css3dRendererManager } from "./css3d-renderer-manager-CPpVtvgs.js";
+import { r as XRCameraLike } from "./xr-camera-texture-q0eIDSRg.js";
 import * as THREE from "three";
 import { OdometryTrackingRestartedPayload } from "gps-plus-slam-js";
 
@@ -69,6 +69,16 @@ declare function shouldLogCameraAccessDiagnostic(pose: XRViewerPose | null, alre
  * @internal
  */
 declare function resetWebXRState(): void;
+/**
+ * Info passed to the session-end callback (F3, 2026-07-04 user feedback).
+ * `requestedByApp` discriminates the app's own `endARSession()` from a
+ * system-initiated end (e.g. the Android back gesture, which ends an
+ * immersive XRSession directly — no popstate, no beforeunload, not
+ * cancelable).
+ */
+interface SessionEndInfo {
+  requestedByApp: boolean;
+}
 /**
  * Default longer-edge resolution (px) for the camera-frame blit the QR / CV
  * detector sees. The on-device capture-resolution sweep (2026-06-17, via the
@@ -129,6 +139,18 @@ interface SessionFeatureOptions {
    * existing recorder/anchor sessions are unaffected.
    */
   requestHitTest?: boolean;
+  /**
+   * Request `depth-sensing` (cpu-optimized) for the **live depth occluder**
+   * even when crash-isolation's `enableDepthSensingFeature` is off. Consumer
+   * apps (AnchorStarter / MinimalExample) want occlusion without the recorder's
+   * depth-capture wiring, so the occluder owns its own session-feature switch.
+   * Both flags resolve the **same** cpu-optimized usage — setting both is valid
+   * (no conflict, no throw): the grid sampler and the occluder are two consumers
+   * of one depth read. Default `false`.
+   *
+   * @see GpsPlusSlamJs_Docs/docs/2026-06-14-webxr-depth-occlusion-plan.md §6/§8
+   */
+  requestDepthOcclusion?: boolean;
 }
 /**
  * Build XR session init options.
@@ -138,7 +160,7 @@ interface SessionFeatureOptions {
  * @param isolationOptions - Crash-isolation diagnostic flags (DOM overlay,
  *   depth-sensing, camera-access)
  * @param sessionFeatures - Opt-in standard WebXR features that are independent
- *   of crash isolation (currently `requestHitTest`)
+ *   of crash isolation (`requestHitTest`, `requestDepthOcclusion`)
  * @returns XRSessionInit options
  * @throws Error if rootElement is null
  */
@@ -147,6 +169,23 @@ declare function buildSessionOptions(rootElement: Element | null, isolationOptio
  * Check if WebXR immersive-ar is supported
  */
 declare function isWebXRSupported(): Promise<boolean>;
+/**
+ * AR camera frustum constants — the single source of truth for live AR and
+ * replay (both build their camera via {@link createSceneHierarchy}).
+ *
+ * F2 (2026-07-04 user feedback): far raised 100 → 200 m so objects in the
+ * reported 100–200 m range are no longer frustum-culled. The far-plane
+ * distance itself is essentially free at this app's object counts; the real
+ * constraint is depth precision — far/near = 2×10⁴ is comfortable for a
+ * 24-bit depth buffer. Revisit the ratio if AR_CAMERA_NEAR ever shrinks.
+ *
+ * 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).
+ */
+declare const AR_CAMERA_FOV = 70;
+declare const AR_CAMERA_NEAR = 0.01;
+declare const AR_CAMERA_FAR = 200;
 /**
  * Create the scene hierarchy with proper AR/GPS frame separation.
  * This is a pure function for testability.
@@ -196,6 +235,18 @@ declare function createSceneHierarchy(): {
  *   `requestHitTest`) forwarded to the session negotiation.
  */
 declare function initAR(container: HTMLElement, isolationOptions?: Partial<ArCrashIsolationOptions>, sessionFeatures?: SessionFeatureOptions): Promise<void>;
+/**
+ * Extract depth information from an XR frame. Returns `null` if depth sensing is
+ * not available (no pose/view, no `getDepthInformation`, or the call throws).
+ *
+ * Exported so a consumer can feed the **live depth occluder** from a
+ * `registerXrFrameUpdate` callback — the callback has the live `frame` +
+ * `referenceSpace`, computes `pose = frame.getViewerPose(referenceSpace)`, and
+ * passes both here to obtain the per-frame {@link DepthInfo} (with the widened
+ * `data` / `rawValueToMeters` / `normDepthBufferFromNormView` / `projectionMatrix`
+ * the occluder needs). The same wrapped depth the sparse grid sampler consumes.
+ */
+declare function getDepthInfoFromFrame(frame: XRFrame, pose: XRViewerPose | null): DepthInfo | null;
 /**
  * Get the current Three.js scene (for adding objects like map)
  */
@@ -284,6 +335,18 @@ declare function nuePositionToWebXR(nue: readonly number[]): readonly [number, n
  * NUE [x, y, z, w] → WebXR [z, y, -x, w]
  */
 declare function nueQuaternionToWebXR$1(nue: readonly number[]): readonly [number, number, number, number];
+/**
+ * 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.
+ */
+declare function setSessionEndCallback(cb: ((info: SessionEndInfo) => void) | null): void;
 /**
  * End the current XR session and clean up all resources.
  *
@@ -464,4 +527,4 @@ declare function setFrameCallback(callback: (() => void) | null): void;
  */
 declare function getLiveCss3dManager(): Css3dRendererManager | null;
 //#endregion
-export { setCamera as A, setTrackingStore as B, isWebXRSupported as C, resetWebXRState as D, nueQuaternionToWebXR$1 as E, setImageQualityAnalyzer as F, stopCameraFrameCapture as G, startCameraFrameCapture as H, setScene as I, stopDepthCapture as K, setTrackingCallbacks as L, setDepthCaptureCallback as M, setFrameCallback as N, setArPose as O, setImageCaptureCallback as P, setTrackingLostCallback as R, initAR as S, nuePositionToWebXR as T, startDepthCapture as U, shouldLogCameraAccessDiagnostic as V, startImageCapture as W, getDepthSampleCount as _, applyAlignmentMatrix as a, getScene as b, endARSession as c, getArPose as d, getArWorldGroup as f, getCurrentArPose as g, getCameraFrameCount as h, TrackingSubscribableStore as i, setCameraFrameCallback as j, setArWorldGroup as k, extractPoseFromViewer as l, getCameraFrameCaptureSize as m, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as n, buildSessionOptions as o, getCamera as p, stopImageCapture as q, SessionFeatureOptions as r, createSceneHierarchy as s, CameraFrameCaptureConfig as t, extractResetTransformData as u, getImageCaptureFrameCount as v, isXRCameraLike as w, getXrCameraFromPose as x, getLiveCss3dManager as y, setTrackingRecoveredCallback as z };
+export { stopImageCapture as $, nuePositionToWebXR as A, setImageQualityAnalyzer as B, getImageCaptureFrameCount as C, initAR as D, getXrCameraFromPose as E, setCamera as F, setTrackingRecoveredCallback as G, setSessionEndCallback as H, setCameraFrameCallback as I, startCameraFrameCapture as J, setTrackingStore as K, setDepthCaptureCallback as L, resetWebXRState as M, setArPose as N, isWebXRSupported as O, setArWorldGroup as P, stopDepthCapture as Q, setFrameCallback as R, getDepthSampleCount as S, getScene as T, setTrackingCallbacks as U, setScene as V, setTrackingLostCallback as W, startImageCapture as X, startDepthCapture as Y, stopCameraFrameCapture as Z, getCamera as _, DEFAULT_CAMERA_FRAME_CAPTURE_SIZE as a, getCurrentArPose as b, TrackingSubscribableStore as c, createSceneHierarchy as d, endARSession as f, getArWorldGroup as g, getArPose as h, CameraFrameCaptureConfig as i, nueQuaternionToWebXR$1 as j, isXRCameraLike as k, applyAlignmentMatrix as l, extractResetTransformData as m, AR_CAMERA_FOV as n, SessionEndInfo as o, extractPoseFromViewer as p, shouldLogCameraAccessDiagnostic as q, AR_CAMERA_NEAR as r, SessionFeatureOptions as s, AR_CAMERA_FAR as t, buildSessionOptions as u, getCameraFrameCaptureSize as v, getLiveCss3dManager as w, getDepthInfoFromFrame as x, getCameraFrameCount as y, setImageCaptureCallback as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gps-plus-slam-app-framework",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Reusable AR+GPS app framework layer — WebXR session management, Three.js visualization, GPS sensors, storage abstractions, replay engine, and store wiring for gps-plus-slam-js.",
   "type": "module",
   "files": [
@@ -36,7 +36,7 @@
   "dependencies": {
     "@reduxjs/toolkit": "^2.11.2",
     "gl-matrix": "3.4.4",
-    "gps-plus-slam-js": "^1.7.0"
+    "gps-plus-slam-js": "^1.8.0"
   },
   "peerDependencies": {
     "@sentry/browser": ">=10.0.0",
@@ -104,10 +104,10 @@
     "build": "tsdown --config config/tsdown.config.ts",
     "verify:pack": "pnpm pack --dry-run",
     "verify:community-key-lifetime": "node scripts/verify-community-key-lifetime.mjs",
-    "test:unit": "vitest run --coverage --config config/vitest.config.ts",
+    "test:unit": "node ../scripts/run-vitest-scoped.mjs run --coverage --config=config/vitest.config.ts",
     "typecheck": "tsc -p tsconfig.app.json --noEmit",
     "typecheck:tests": "tsc -p tsconfig.vitest.json --noEmit",
-    "lint": "eslint . --config config/eslint.config.mjs",
+    "lint": "eslint . --config config/eslint.config.mjs --max-warnings 37",
     "test:watch": "vitest --config config/vitest.config.ts",
     "check:cycles": "dpdm -T --exit-code circular:1 --no-warning --no-tree ./src/index.ts",
     "setup": "bash ./scripts/setup.sh"

package/dist/lerp-utils-BLmHhkVe.d.ts

@@ -1,20 +0,0 @@
-//#region ../src/visualization/lerp-utils.d.ts
-/**
- * Shared lerp utilities for visualization modules.
- *
- * Both alignment-lerper and camera-follower need the same smoothing
- * rate constant and clamped-alpha formula. Centralised here (R3) to
- * keep the two modules in sync.
- */
-/** Default speed multiplier — ~90 % convergence in ~0.3 s at 60 fps. */
-declare const DEFAULT_LERP_RATE = 8;
-/**
- * Compute a frame-rate-independent lerp/slerp factor clamped to [0, 1].
- *
- * @param lerpRate Speed multiplier (higher = faster convergence).
- * @param dt       Delta time in seconds since last frame.
- * @returns The interpolation alpha, guaranteed ≤ 1.0.
- */
-declare function clampedAlpha(lerpRate: number, dt: number): number;
-//#endregion
-export { clampedAlpha as n, DEFAULT_LERP_RATE as t };

package/dist/occupancy-grid-DnOc-6PU.d.ts

@@ -1,82 +0,0 @@
-import { t as GridCell } from "./bresenham3d-CU1Gv2W4.js";
-import { a as RgbTuple, i as DepthSample } from "./ar-types-BFX2r1wk.js";
-import { Vector3 } from "gps-plus-slam-js";
-
-//#region ../src/ar/occupancy-grid.d.ts
-interface OccupancyGridOptions {
-  /** Edge length of a cubic grid cell in meters. Default 0.15 (Unity parity). */
-  readonly cellSizeM?: number;
-  /**
-   * Dominant-axis steps before a ray's endpoint at which free-space
-   * carving stops, to respect depth noise. Default 2 (Unity parity).
-   */
-  readonly carveStopCells?: number;
-}
-declare class OccupancyGrid {
-  readonly cellSizeM: number;
-  readonly carveStopCells: number;
-  private readonly cells;
-  constructor(options?: OccupancyGridOptions);
-  /** Number of occupied cells. */
-  get size(): number;
-  /**
-   * Fold one depth sample into the grid: unproject each point, carve free
-   * space from the camera cell to the point cell, then count the point's
-   * cell as occupied. Points that cannot be unprojected (no
-   * projectionMatrix on old recordings, invalid depth/coords) are skipped.
-   *
-   * Carving and incrementing run as two separate passes over the sample's
-   * points: all rays are carved first, then every endpoint is incremented.
-   * A single interleaved pass would be order-dependent — a deeper point's
-   * carve could erase the endpoint a nearer point added earlier in the same
-   * sample. Splitting the passes makes the result deterministic and lets an
-   * endpoint observed within a sample survive other rays in that same
-   * sample. (Deeper-carves-nearer still applies ACROSS samples: a later
-   * sample's ray carves an earlier sample's endpoint as before.)
-   *
-   * @returns the number of points actually added.
-   */
-  addSample(sample: DepthSample): number;
-  /** Occupied cells observed at least `minObservations` times (default 1). */
-  getOccupiedCells(minObservations?: number): GridCell[];
-  /** Quantize a raw-WebXR position to its grid cell (round per axis). */
-  cellForPosition(pos: Vector3): GridCell;
-  /** Center of a cell in raw WebXR space (round-consistent: cell · cellSizeM). */
-  getCellCenter(cell: GridCell): Vector3;
-  /**
-   * Running-average of the EXACT unprojected surface points observed in this
-   * cell (raw WebXR space), or null for an unknown cell. Unlike
-   * {@link getCellCenter} (the geometric 15 cm-lattice center) this hugs the
-   * real measured surface and noise-averages across viewpoints — used by the
-   * COLMAP `points3D` export and the debug cubes (follow-up Item A). Being a
-   * centroid of points that fell in the cell, it always lies within
-   * `cellSizeM/2` of the cell center per axis.
-   */
-  getCellPoint(cell: GridCell): Vector3 | null;
-  /**
-   * Running-average color of the cell's colored observations (Iter 8), or
-   * null when the cell is unknown or was only ever observed without color
-   * (rgb option off / pre-Iter-8 recordings) — consumers fall back to
-   * height-based coloring. Channels are rounded and clamped to 0–255.
-   */
-  getCellColor(cell: GridCell): RgbTuple | null;
-  /**
-   * Walk the grid from `startPos` to `endPos` and return the center of the
-   * first cell occupied at least `minObservations` times, or null.
-   * Port of Unity's `TryRaycast` (hook for cursor/floor-detection parity).
-   */
-  raycast(startPos: Vector3, endPos: Vector3, minObservations?: number): Vector3 | null;
-  /** Remove all occupied cells (e.g. on store swap / new session). */
-  clear(): void;
-  /**
-   * Delete occupied cells along the camera→point ray (the space was seen
-   * through, so it must be free), stopping `carveStopCells` dominant-axis
-   * steps before the endpoint. The endpoint cell itself is additionally
-   * protected so a current observation is never erased (relevant for
-   * carveStopCells = 0 and for the unconditional start-cell visit).
-   */
-  private carve;
-  private increment;
-}
-//#endregion
-export { OccupancyGridOptions as n, OccupancyGrid as t };