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

package/dist/ar/xr-camera-texture.d.ts

@@ -1,2 +1,2 @@
-import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-BU5YvKAM.js";
+import { i as acquireCameraTexture, n as RendererLike, r as XRCameraLike, t as CameraTextureResult } from "../xr-camera-texture-DBwCaKTd.js";
 export { CameraTextureResult, RendererLike, XRCameraLike, acquireCameraTexture };

package/dist/ar/xr-error-handler.d.ts

@@ -1,2 +1,2 @@
-import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-DcUFshNF.js";
+import { n as XR_ERROR_MESSAGE_UNKNOWN, r as getXrErrorMessage, t as XR_ERROR_MESSAGES } from "../xr-error-handler-C0AQRmxs.js";
 export { XR_ERROR_MESSAGES, XR_ERROR_MESSAGE_UNKNOWN, getXrErrorMessage };

package/dist/ar/xr-frame-loop.d.ts

@@ -1,2 +1,2 @@
-import { a as runXrFrameUpdates, i as registerXrFrameUpdate, n as XrFrameUpdate, r as clearXrFrameUpdates, t as XrFrameContext } from "../xr-frame-loop-BKckC7xC.js";
+import { a as runXrFrameUpdates, i as registerXrFrameUpdate, n as XrFrameUpdate, r as clearXrFrameUpdates, t as XrFrameContext } from "../xr-frame-loop-BtYytZJg.js";
 export { XrFrameContext, XrFrameUpdate, clearXrFrameUpdates, registerXrFrameUpdate, runXrFrameUpdates };

package/dist/{ar-types-isPsQptb.d.ts → ar-types-Dan1MVTi.d.ts}

@@ -1,4 +1,4 @@
-import { Quaternion, Vector3 } from "gps-plus-slam-js";
+import { Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/types/ar-types.d.ts
 /**
@@ -43,6 +43,11 @@ interface ARPose {
   readonly position: WebXRVec3;
   readonly orientation: WebXRQuaternion;
 }
+/**
+ * An sRGB color triple, 0–255 integers per channel. Kept as plain ints so
+ * persisted JSON stays compact (~3 bytes/point in practice).
+ */
+type RgbTuple = readonly [number, number, number];
 /**
  * A single depth point sample from WebXR Depth API.
  * Used for 3D reconstruction and validating AR tracking accuracy.
@@ -54,6 +59,14 @@ interface DepthPoint {
   readonly screenY: number;
   /** Depth value in meters */
   readonly depthM: number;
+  /**
+   * Camera color at (screenX, screenY), sampled from the same XR frame as
+   * the depth read (occupancy-grid port plan Iter 8). Optional + additive:
+   * recordings made before 2026-06 (or with the RGB recording option off)
+   * carry no color; consumers must fall back (e.g. height-based cube
+   * coloring).
+   */
+  readonly rgb?: RgbTuple;
 }
 /**
  * A complete depth sample with camera pose and grid of depth points.
@@ -66,8 +79,10 @@ interface DepthSample {
   readonly timestamp: number;
   /**
    * Camera position in **raw WebXR** convention [x=East, y=Up, z=South].
-   * NOT in NUE — the recordDepthSample reducer is a no-op, so no
-   * webxrToNUE conversion is applied. Consumers must convert if needed.
+   * NOT in NUE — the recordDepthSample reducer is conversion-free (it only
+   * stores the latest sample for subscribers), so no webxrToNUE conversion
+   * is ever applied. Consumers needing NUE must convert themselves; the
+   * occupancy-grid pipeline works directly in this raw frame.
    */
   readonly cameraPos: Vector3;
   /**
@@ -76,7 +91,15 @@ interface DepthSample {
    */
   readonly cameraRot: Quaternion;
   /** Grid of depth points */
-  readonly points: DepthPoint[];
+  readonly points: readonly DepthPoint[];
+  /**
+   * Projection matrix of the capturing XRView (16 floats, column-major,
+   * serializable tuple — not a THREE.Matrix4). Camera intrinsics needed to
+   * unproject (screenX, screenY, depthM) back into a 3D AR-space point.
+   * Optional: recordings made before 2026-06 do not carry it; consumers
+   * must skip unprojection for such samples.
+   */
+  readonly projectionMatrix?: Matrix4;
 }
 //#endregion
-export { WebXRQuaternion as a, DepthSample as i, ArPoseTuples as n, WebXRVec3 as o, DepthPoint as r, ARPose as t };
+export { RgbTuple as a, DepthSample as i, ArPoseTuples as n, WebXRQuaternion as o, DepthPoint as r, WebXRVec3 as s, ARPose as t };

package/dist/{ar-world-group-alignment-Dn4rQk_c.d.ts → ar-world-group-alignment-C9lwwIyI.d.ts}

@@ -1,4 +1,4 @@
-import { t as SubscribableStore } from "./subscribe-to-selector--KQpgLXG.js";
+import { t as SubscribableStore } from "./subscribe-to-selector-CZ6k1NFP.js";
 import * as THREE from "three";
 
 //#region ../src/visualization/ar-world-group-alignment.d.ts

package/dist/bresenham3d-CFfd7n6B.d.ts

@@ -0,0 +1,59 @@
+//#region ../src/ar/bresenham3d.d.ts
+/**
+ * 3D Bresenham Line Tracer
+ *
+ * Direct port of the Unity occupancy-grid helper
+ * (`PointCloudHelpers.BresenhamsLineAlgorithm`, after
+ * http://members.chello.at/~easyfilter/bresenham.html): walks integer grid
+ * cells from `start` to `end`, invoking a visitor per cell. Used by the
+ * occupancy grid for free-space carving and raycasting.
+ *
+ * Semantics preserved from the Unity original:
+ * - The visitor runs on the start cell BEFORE the stop-distance check.
+ * - `stopDistance` is measured in dominant-axis (Chebyshev) steps from the
+ *   end cell: tracing stops once the remaining distance reaches it, so the
+ *   end cell and its `stopDistance`-neighborhood are not visited (except
+ *   the unconditional start visit).
+ * - Error offsets use integer division (`floor(dm / 2)`).
+ *
+ * @see bresenham3d.ts.md for detailed documentation
+ */
+/** Integer grid cell coordinate triple. */
+type GridCell = readonly [number, number, number];
+/**
+ * Main-thread safety cap: the maximum dominant-axis (Chebyshev) span a single
+ * trace may cover. The trace runs synchronously, one iteration per
+ * dominant-axis step, so an unbounded span freezes the UI. Finite-but-absurd
+ * coordinates (a tracking glitch, a corrupt projectionMatrix unprojecting to a
+ * huge world point) quantize to safe integers and pass the integer check, so
+ * this is the only thing standing between such input and a multi-second
+ * (potentially multi-billion-iteration) freeze.
+ *
+ * Chosen generously — at the grid's 0.15 m cells this is ~150 km, far beyond
+ * any real AR scene, so it never trips on legitimate carving or raycasting.
+ * It is a circuit breaker against programmer/data error, not a ray-length
+ * policy: exceeding it throws (loud — surfaces the upstream bug) rather than
+ * silently truncating the trace.
+ */
+declare const MAX_TRACE_STEPS = 1000000;
+/**
+ * Trace the line from `start` to `end`, calling `visitCell` per cell.
+ *
+ * @param visitCell - return `false` to stop the trace early.
+ * @param stopDistance - dominant-axis steps before `end` at which to stop
+ *   (default 0 = trace all the way to `end`).
+ * @throws TypeError when a coordinate is not a safe integer (cells must be
+ *   quantized before tracing — programmer error, not a data error).
+ * @throws RangeError when `stopDistance` is not a non-negative safe integer.
+ *   The loop terminates on a counter (`i--`) that decrements unconditionally,
+ *   so a negative or fractional value still terminates (it merely traces past
+ *   `end`); but `NaN`/`-Infinity` never satisfy `i <= stopDistance` and would
+ *   spin forever. Rejecting up front both prevents that freeze and enforces
+ *   the "dominant-axis steps before end" contract.
+ * @throws RangeError when the dominant-axis span exceeds {@link MAX_TRACE_STEPS}
+ *   (circuit breaker against a synchronous main-thread freeze from
+ *   finite-but-absurd coordinates).
+ */
+declare function bresenham3d(start: GridCell, end: GridCell, visitCell: (cell: GridCell) => boolean, stopDistance?: number): void;
+//#endregion
+export { MAX_TRACE_STEPS as n, bresenham3d as r, GridCell as t };

package/dist/{camera-blit-capture-75WWa9Xb.d.ts → camera-blit-capture-CnxUDbKx.d.ts}

@@ -63,6 +63,26 @@ declare class CameraBlitCapture {
    * @returns JPEG Blob, or null if capture fails
    */
   captureToBlob(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture, quality: number): Promise<Blob | null>;
+  /**
+   * Run the blit + readback (steps A+B of {@link captureToBlob}) and return
+   * the raw RGBA pixel buffer without JPEG encoding — the cheap path for
+   * per-point color sampling (occupancy-grid port plan Iter 8).
+   *
+   * IMPORTANT: Must be called within the XR animation frame callback, while
+   * the camera texture is valid. The returned `pixels` is the INTERNAL
+   * buffer — valid only until the next capture or `resizeIfNeeded`; consume
+   * it synchronously (e.g. via `createRgbLookup`) or copy it.
+   *
+   * Note: the buffer is in WebGL readback order (bottom-row-first / RGBA);
+   * `createRgbLookup` handles the y-flip.
+   *
+   * @returns the buffer with its dimensions, or null on failure/dispose.
+   */
+  captureToPixels(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture): {
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+  } | null;
   /**
    * Check if a pixel buffer is entirely black (all zeros).
    * Uses sampling for performance (checks BLACK_CHECK_SAMPLE_COUNT evenly-spaced pixels).
@@ -99,6 +119,15 @@ declare class CameraBlitCapture {
    * @returns true if resources were actually resized
    */
   resizeIfNeeded(newWidth: number, newHeight: number): boolean;
+  /**
+   * Current render-target width in pixels. This is exactly the width of the
+   * JPEG produced by {@link captureToBlob} (the encode canvas is sized to the
+   * render target), so callers can persist it as the captured image's true
+   * pixel width without decoding the blob.
+   */
+  getWidth(): number;
+  /** Current render-target height in pixels. See {@link getWidth}. */
+  getHeight(): number;
   /**
    * Dispose GPU resources. Call when AR session ends.
    */

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-import { a as LibraryRootState, c as RootState, d as calcRelativeCoordsInMeters, f as createGpsSlamStore, g as webxrToNUE, h as validateLicenseKey, i as LatLongAlt, l as Vector3, m as odometryTrackingRestarted, n as GpsPoint, o as Matrix4, p as isIdentityMatrix4, r as LatLong, s as Quaternion, t as ArImageCapture, u as calcGpsCoords } from "../index--ldLph4V.js";
+import { a as LibraryRootState, c as RootState, d as calcRelativeCoordsInMeters, f as createGpsSlamStore, g as webxrToNUE, h as validateLicenseKey, i as LatLongAlt, l as Vector3, m as odometryTrackingRestarted, n as GpsPoint, o as Matrix4, p as isIdentityMatrix4, r as LatLong, s as Quaternion, t as ArImageCapture, u as calcGpsCoords } from "../index-CF05QV2m.js";
 export { ArImageCapture, GpsPoint, LatLong, LatLongAlt, LibraryRootState, Matrix4, Quaternion, RootState, Vector3, calcGpsCoords, calcRelativeCoordsInMeters, createGpsSlamStore, isIdentityMatrix4, odometryTrackingRestarted, validateLicenseKey, webxrToNUE };

package/dist/{create-slam-app-store-B76AGaI0.d.ts → create-slam-app-store-BljusOua.d.ts}

@@ -1,8 +1,8 @@
-import { t as ARPose } from "./ar-types-isPsQptb.js";
-import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-CDREeoZ_.js";
-import { t as RecordingState } from "./recording-slice-Cb888P6d.js";
-import { n as SessionMetadata } from "./opfs-storage-LsLY6VZV.js";
-import { n as StorageBackend } from "./storage-backend-yDSKafAQ.js";
+import { t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { a as TrackingSliceState, t as DeviceOrientation } from "./tracking-slice-CdK8c-8P.js";
+import { t as RecordingState } from "./recording-slice-89O07ebs.js";
+import { n as SessionMetadata } from "./opfs-storage-D5zAn_lx.js";
+import { n as StorageBackend } from "./storage-backend-Do6YDpNo.js";
 import { GpsPoint, LatLong, Matrix4, RootState, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 import { Middleware, Reducer, ReducersMapObject, configureStore } from "@reduxjs/toolkit";

package/dist/depth-sampler-Bhanfwla.d.ts

@@ -0,0 +1,169 @@
+import { a as RgbTuple, i as DepthSample, t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { Matrix4 } from "gps-plus-slam-js";
+
+//#region ../src/ar/depth-rgb-lookup.d.ts
+/**
+ * Sample the camera color at normalized view coordinates (0–1, y=0 top).
+ * Returns null for out-of-range or non-finite coordinates.
+ */
+type RgbLookup = (screenX: number, screenY: number) => RgbTuple | null;
+//#endregion
+//#region ../src/ar/depth-sampler.d.ts
+/**
+ * Configuration for depth sampling behavior.
+ */
+interface DepthSamplerConfig {
+  /** Interval between samples in milliseconds. Default: 1000ms */
+  intervalMs: number;
+  /**
+   * Number of points per dimension (gridSize x gridSize). Default: 16
+   * (256 pts at 1 Hz — dense enough to populate the AR-space occupancy
+   * grid for on-device verification, see the 2026-06-11 port plan §1).
+   */
+  gridSize: number;
+  /** Time in ms to wait before declaring depth unavailable. Default: 5000ms */
+  unavailabilityThresholdMs: number;
+  /**
+   * Whether to enrich each sampled point with the camera color at its view
+   * coordinates (occupancy-grid port plan Iter 8). Requires the
+   * `acquireRgbLookup` callback; gates the per-sample GPU blit+readback.
+   * Default: true.
+   */
+  rgb: boolean;
+}
+/**
+ * Callbacks for depth sampler events.
+ */
+interface DepthSamplerCallbacks {
+  /** Called when a depth sample is captured */
+  onSampleCaptured: (sample: DepthSample) => void;
+  /** Returns the current AR pose, or null if not available */
+  getCurrentPose: () => ARPose | null;
+  /**
+   * Called once when depth is determined to be unavailable.
+   * Triggered after unavailabilityThresholdMs with no depth data.
+   * Field Test Readiness Issue #8.
+   */
+  onDepthUnavailable?: () => void;
+  /**
+   * Lazily acquire a camera-color lookup for the CURRENT XR frame
+   * (occupancy-grid port plan Iter 8). Invoked at most once per *emitted*
+   * sample (never per frame or per point — acquisition is a GPU-stall
+   * blit+readback) and only while `config.rgb` is true. Returning `null`
+   * (or throwing) yields color-less points; the returned lookup is used
+   * synchronously within the same frame callback.
+   */
+  acquireRgbLookup?: () => RgbLookup | null;
+}
+/**
+ * WebXR depth info interface (subset of XRDepthInformation), extended with
+ * the capturing view's projection matrix so each emitted DepthSample carries
+ * the intrinsics needed for unprojection. Build via {@link wrapXRDepthInfo}.
+ */
+interface DepthInfo {
+  width: number;
+  height: number;
+  getDepthInMeters: (x: number, y: number) => number;
+  /** Column-major projection matrix of the capturing XRView, if known. */
+  projectionMatrix?: Matrix4;
+}
+/**
+ * Wrap a raw browser XRDepthInformation object into a {@link DepthInfo}.
+ *
+ * - `getDepthInMeters` is bound to the source object (browser
+ *   implementations are this-sensitive).
+ * - `projectionMatrix` (typically `XRView.projectionMatrix`, a Float32Array
+ *   the UA may reuse across frames) is defensively validated and copied into
+ *   a plain serializable 16-tuple; invalid input (wrong length, non-finite
+ *   entries) yields a DepthInfo without a matrix rather than an error.
+ */
+declare function wrapXRDepthInfo(raw: {
+  width: number;
+  height: number;
+  getDepthInMeters: (x: number, y: number) => number;
+}, projectionMatrix: ArrayLike<number> | undefined): DepthInfo;
+/**
+ * Samples sparse depth points from WebXR depth sensing.
+ *
+ * Usage:
+ * ```ts
+ * const sampler = new DepthSampler({
+ *   onSampleCaptured: (sample) => saveSample(sample),
+ *   getCurrentPose: () => arSession.getCurrentPose(),
+ * });
+ * sampler.start();
+ * // In frame loop:
+ * sampler.onFrame(timestamp, depthInfo);
+ * ```
+ */
+declare class DepthSampler {
+  private readonly callbacks;
+  private readonly config;
+  private running;
+  private sampleCount;
+  private lastSampleTime;
+  /** Timestamp when sampling started (for unavailability detection) */
+  private startTime;
+  /** Whether we've ever received valid depth data */
+  private depthReceived;
+  /** Whether we've already fired the unavailable callback */
+  private unavailableCallbackFired;
+  constructor(callbacks: DepthSamplerCallbacks, config?: Partial<DepthSamplerConfig>);
+  /**
+   * Start depth sampling.
+   */
+  start(): void;
+  /**
+   * Stop depth sampling.
+   */
+  stop(): void;
+  /**
+   * Check if sampler is currently running.
+   */
+  isRunning(): boolean;
+  /**
+   * Get the number of samples captured since start.
+   */
+  getSampleCount(): number;
+  /**
+   * Get the current configuration.
+   */
+  getConfig(): DepthSamplerConfig;
+  /**
+   * Apply partial configuration overrides (e.g. the user's recording
+   * options, plumbed in by `startDepthCapture` just before sampling
+   * starts). Invalid values are ignored defensively: every key requires a
+   * finite positive number, and `gridSize` additionally an integer.
+   */
+  updateConfig(config: Partial<DepthSamplerConfig>): void;
+  /**
+   * Called each frame with depth information.
+   *
+   * @param timestamp - Current frame timestamp in milliseconds
+   * @param depthInfo - WebXR depth information, or null if unavailable
+   */
+  onFrame(timestamp: number, depthInfo: DepthInfo | null): void;
+  /**
+   * Acquire the per-sample RGB lookup, gated by `config.rgb` and guarded so
+   * a failing acquisition (e.g. GL context loss during the blit) can never
+   * break the sample emission in the XR frame loop.
+   */
+  private acquireRgbLookupSafely;
+  /**
+   * Sample a grid of depth points from the depth buffer, attaching the
+   * camera color per point when a lookup is available.
+   */
+  private sampleGrid;
+  /**
+   * Check if depth has been unavailable for longer than the threshold.
+   * If so, fire the onDepthUnavailable callback (once).
+   */
+  private checkDepthUnavailability;
+  /**
+   * Check if depth data has ever been received.
+   * Useful for testing and status display.
+   */
+  hasReceivedDepth(): boolean;
+}
+//#endregion
+export { wrapXRDepthInfo as a, DepthSamplerConfig as i, DepthSampler as n, DepthSamplerCallbacks as r, DepthInfo as t };

package/dist/depth-unprojection-Y6i_mJuT.d.ts

@@ -0,0 +1,52 @@
+import { r as DepthPoint } from "./ar-types-Dan1MVTi.js";
+import { Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/depth-unprojection.d.ts
+/**
+ * A sample-scoped unprojector: the camera pose and (inverse) projection are
+ * computed once, then reused for every point in the same `DepthSample`. See
+ * {@link createDepthUnprojector}.
+ */
+interface DepthUnprojector {
+  /**
+   * Unproject one point into raw WebXR space, or `null` when the input is not
+   * usable (non-positive/non-finite depth, out-of-range screen coordinates,
+   * degenerate ray).
+   */
+  unproject(point: DepthPoint): Vector3 | null;
+}
+/**
+ * Build a {@link DepthUnprojector} for one depth sample. The projection
+ * inverse and camera quaternion/position are sample-invariant, so they are
+ * computed once here instead of per point (the per-point hot path then only
+ * does the cheap NDC→view→world transform). Callers that fold many points
+ * from the same sample — e.g. `OccupancyGrid.addSample` — should build the
+ * unprojector once and reuse it for all points.
+ *
+ * @param cameraPos - camera position, raw WebXR (`DepthSample.cameraPos`)
+ * @param cameraRot - camera quaternion [x,y,z,w], raw WebXR (`DepthSample.cameraRot`)
+ * @param projectionMatrix - column-major projection matrix of the capturing
+ *   view (`DepthSample.projectionMatrix`). `undefined` for recordings made
+ *   before intrinsics capture — those points cannot be unprojected.
+ * @returns an unprojector, or `null` when the sample cannot be unprojected at
+ *   all (missing or singular projection matrix).
+ */
+declare function createDepthUnprojector(cameraPos: Vector3, cameraRot: Quaternion, projectionMatrix: Matrix4 | undefined): DepthUnprojector | null;
+/**
+ * Unproject a single depth point into raw WebXR space. Convenience wrapper
+ * over {@link createDepthUnprojector} for one-off callers; when unprojecting
+ * many points from the same sample, build the unprojector once instead.
+ *
+ * @param point - normalized view coordinates + depth in meters
+ * @param cameraPos - camera position, raw WebXR (`DepthSample.cameraPos`)
+ * @param cameraRot - camera quaternion [x,y,z,w], raw WebXR (`DepthSample.cameraRot`)
+ * @param projectionMatrix - column-major projection matrix of the capturing
+ *   view (`DepthSample.projectionMatrix`). `undefined` for recordings made
+ *   before intrinsics capture — those points cannot be unprojected.
+ * @returns the 3D point in raw WebXR space, or `null` when the input is not
+ *   usable (missing/singular matrix, non-positive or non-finite depth,
+ *   out-of-range screen coordinates).
+ */
+declare function unprojectDepthPoint(point: DepthPoint, cameraPos: Vector3, cameraRot: Quaternion, projectionMatrix: Matrix4 | undefined): Vector3 | null;
+//#endregion
+export { createDepthUnprojector as n, unprojectDepthPoint as r, DepthUnprojector as t };

package/dist/{enable-gps-ar-DNbO0zbg.d.ts → enable-gps-ar-BfUJOgpW.d.ts}

@@ -1,7 +1,7 @@
-import { t as ArCrashIsolationOptions } from "./recording-options-BSFpBSZH.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-B7AlMPz5.js";
-import { n as PermissionStatus } from "./permission-checker-CfV7INCa.js";
-import { t as SessionFeatureOptions } from "./webxr-session-BnArFCew.js";
+import { t as ArCrashIsolationOptions } from "./recording-options-DJBXuMxV.js";
+import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-VuezJWK3.js";
+import { n as PermissionStatus } from "./permission-checker-GpAiSCwd.js";
+import { t as SessionFeatureOptions } from "./webxr-session-GjZ2BIpS.js";
 
 //#region ../src/ar/enable-gps-ar.d.ts
 /**

package/dist/{file-system-TIsDfamK.d.ts → file-system-CwXTNHmB.d.ts}

@@ -1,4 +1,4 @@
-import { n as SessionMetadata } from "./opfs-storage-LsLY6VZV.js";
+import { n as SessionMetadata } from "./opfs-storage-D5zAn_lx.js";
 
 //#region ../src/storage/file-system.d.ts
 /**

package/dist/file-system-utils-CXIoL-DM.d.ts

@@ -0,0 +1,40 @@
+//#region ../src/storage/file-system-utils.d.ts
+/**
+ * File System Utilities - Pure Functions
+ *
+ * These are extracted from file-system.ts so they can be tested
+ * without mocking browser APIs.
+ */
+/**
+ * Format a Date as a timestamp string for folder names
+ * @example "2025-02-28_14-30-11utc"
+ */
+declare function formatTimestamp(date: Date): string;
+/**
+ * Format an action file index as a zero-padded filename
+ * @example 42 -> "000042.json"
+ */
+declare function formatActionFilename(index: number): string;
+/**
+ * Format a frame index as a zero-padded filename
+ * @example 42 -> "frame-000042.jpg"
+ */
+declare function formatFrameFilename(index: number): string;
+/**
+ * Canonical session subdirectory for captured camera images, written by new
+ * recordings. Renamed from {@link LEGACY_SESSION_IMAGES_DIR} so an exported ZIP
+ * is a textbook COLMAP tree (`images/frame-NNNNNN.jpg` next to `sparse/0/`).
+ * Both the OPFS write path and the recorder's persisted `imageFile` value must
+ * use THIS constant so a recording stays self-consistent (COLMAP export plan
+ * Q5, gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-13-colmap-export-plan.md).
+ */
+declare const SESSION_IMAGES_DIR = "images";
+/**
+ * The pre-2026-06 session image subdirectory. Recordings made before the
+ * {@link SESSION_IMAGES_DIR} rename store frames under `frames/` (in both the
+ * on-disk dir and the persisted `imageFile`); readers fall back to this prefix
+ * so old recordings still replay.
+ */
+declare const LEGACY_SESSION_IMAGES_DIR = "frames";
+//#endregion
+export { formatTimestamp as a, formatFrameFilename as i, SESSION_IMAGES_DIR as n, formatActionFilename as r, LEGACY_SESSION_IMAGES_DIR as t };

package/dist/{frame-conversions-D2EYjeNa.d.ts → frame-conversions-BfsafGWR.d.ts}

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

package/dist/{fused-path-BdVHmDW9.d.ts → fused-path-DJoVu98b.d.ts}

@@ -1,4 +1,4 @@
-import { t as GpsCoord } from "./geo-types-clgzl8b5.js";
+import { t as GpsCoord } from "./geo-types-SaPnIEUM.js";
 import { LatLong, Matrix4, Vector3, fusedGpsFromOdom } from "gps-plus-slam-js";
 
 //#region ../src/utils/fused-path.d.ts

package/dist/geo/h3-proximity.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-DJnghtir.js";
+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, KnownGeoAnchor, approxDistanceMetres, findNearbyGeoAnchor, 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-DJnghtir.js";
+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 };

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

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

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

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

package/dist/{gps-event-coordinator-BKVZbS1M.d.ts → gps-event-coordinator-CWIDOk4U.d.ts}

@@ -1,6 +1,6 @@
-import { t as ARPose } from "./ar-types-isPsQptb.js";
-import { n as RawDeviceOrientation, t as GpsPosition } from "./gps-B7AlMPz5.js";
-import { i as SlamAppStore } from "./create-slam-app-store-B76AGaI0.js";
+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-BljusOua.js";
 import { Quaternion, RawGpsPoint, RecordGpsEventPayload, Vector3, eulerToQuaternion } from "gps-plus-slam-js";
 import { ReducersMapObject } from "@reduxjs/toolkit";
 

package/dist/{image-capture-BXZUmj7j.d.ts → image-capture-qAZ5Fh5X.d.ts}

@@ -1,4 +1,4 @@
-import { a as WebXRQuaternion, o as WebXRVec3, t as ARPose } from "./ar-types-isPsQptb.js";
+import { o as WebXRQuaternion, s as WebXRVec3, t as ARPose } from "./ar-types-Dan1MVTi.js";
 
 //#region ../src/ar/image-capture.d.ts
 /**
@@ -20,13 +20,26 @@ interface ImageCaptureConfig {
    *  If a capture promise doesn't resolve within this duration, the flag is
    *  force-reset to prevent permanent pipeline deadlock. */
   captureTimeoutMs: number;
+  /** Resolution divisor for the captured frame: 1 = full native resolution,
+   *  2 = half, 4 = quarter (default: 1). Consumed by the blit pipeline in
+   *  `startImageCapture`, not by ImageCaptureManager's timing loop. Folded
+   *  into this config so the whole user options section can flow through the
+   *  capture seam as one object (see the field-drop audit, F3). */
+  resolutionDivisor: number;
 }
 /**
  * Default capture configuration
  */
 declare const DEFAULT_CAPTURE_CONFIG: ImageCaptureConfig;
 /**
- * Data returned when an image is captured
+ * Data returned when an image is captured.
+ *
+ * NOTE: every persistable field here is forwarded into the `add2dImage`
+ * action by the RecorderApp's `handleImageCaptured`, which rebuilds the
+ * payload field-by-field. A new field added here is therefore NOT persisted
+ * until it is threaded through that handler — see
+ * `2026-06-12-payload-rebuild-field-drop-audit.md` (F1/F2) and the forwarding
+ * test in `main.occupancy-cubes-wiring.test.ts`.
  */
 interface CapturedImage {
   /** The captured image as a Blob */
@@ -41,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
@@ -67,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.
@@ -127,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-BB2KEWbN2.d.ts → index-BYYUdf9v.d.ts}

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