gps-plus-slam-app-framework 1.0.0

package/dist/test-utils/browser-mocks.js

@@ -0,0 +1,568 @@
+import { vi } from "vitest";
+//#region ../src/test-utils/browser-mocks.ts
+/**
+* Browser API Mocks for Testing
+*
+* Provides mock implementations for browser APIs that aren't available in Node.js:
+* - WebXR (navigator.xr, XRSession, XRFrame, XRViewerPose)
+* - Geolocation (navigator.geolocation)
+* - Device Orientation (DeviceOrientationEvent)
+* - File System Access API (showDirectoryPicker, FileSystemDirectoryHandle)
+*
+* @see browser-mocks.md for usage examples
+*/
+/**
+* Create a mock XRViewerPose with specified position and orientation.
+*/
+function createMockPose(position, orientation) {
+	const viewTransform = {
+		position: {
+			...position,
+			w: 1
+		},
+		orientation: { ...orientation }
+	};
+	return {
+		views: [{ transform: viewTransform }],
+		transform: {
+			matrix: new Float32Array(16),
+			position: viewTransform.position,
+			orientation: viewTransform.orientation,
+			inverse: null
+		},
+		emulatedPosition: false
+	};
+}
+/**
+* Create a mock XRFrame that returns the specified pose.
+*/
+function createMockFrame(pose) {
+	return {
+		getViewerPose: vi.fn(() => pose),
+		getDepthInformation: vi.fn(() => null)
+	};
+}
+/**
+* Create a mock depth info object with configurable depth function.
+*/
+function createMockDepthInfo(depthFn = () => 1.5) {
+	return {
+		width: 256,
+		height: 256,
+		getDepthInMeters: depthFn
+	};
+}
+/**
+* Create a mock XRSession.
+*/
+function createMockXRSession() {
+	const listeners = /* @__PURE__ */ new Map();
+	return {
+		addEventListener: vi.fn((type, listener) => {
+			if (!listeners.has(type)) listeners.set(type, /* @__PURE__ */ new Set());
+			listeners.get(type).add(listener);
+		}),
+		removeEventListener: vi.fn((type, listener) => {
+			listeners.get(type)?.delete(listener);
+		}),
+		end: vi.fn(() => Promise.resolve()),
+		requestReferenceSpace: vi.fn(() => Promise.resolve({}))
+	};
+}
+/**
+* Create a mock navigator.xr object.
+*/
+function createMockXR(supported = true) {
+	const session = createMockXRSession();
+	return {
+		isSessionSupported: vi.fn(() => Promise.resolve(supported)),
+		requestSession: vi.fn(() => Promise.resolve(session))
+	};
+}
+/**
+* Install WebXR mocks on the global navigator object.
+* Returns cleanup function.
+*/
+function installWebXRMocks(supported = true) {
+	const mockXR = createMockXR(supported);
+	const existingNavigator = typeof navigator !== "undefined" ? navigator : {};
+	vi.stubGlobal("navigator", {
+		...existingNavigator,
+		xr: mockXR
+	});
+	return () => vi.unstubAllGlobals();
+}
+/**
+* Create a mock geolocation position.
+*/
+function createMockGeoPosition(lat, lon, altitude = null, accuracy = 10) {
+	const coordsData = {
+		latitude: lat,
+		longitude: lon,
+		altitude,
+		accuracy,
+		altitudeAccuracy: altitude !== null ? 5 : null,
+		heading: null,
+		speed: null
+	};
+	const coords = {
+		...coordsData,
+		toJSON: () => ({ ...coordsData })
+	};
+	const timestamp = Date.now();
+	return {
+		coords,
+		timestamp,
+		toJSON: () => ({
+			coords: { ...coordsData },
+			timestamp
+		})
+	};
+}
+/**
+* Create a mock geolocation object.
+*/
+function createMockGeolocation() {
+	let watchId = 0;
+	const watchers = /* @__PURE__ */ new Map();
+	const mock = {
+		watchPosition: vi.fn((success, _error, _options) => {
+			const id = ++watchId;
+			watchers.set(id, success);
+			return id;
+		}),
+		clearWatch: vi.fn((id) => {
+			watchers.delete(id);
+		}),
+		getCurrentPosition: vi.fn((success, _error, _options) => {
+			success(createMockGeoPosition(50, 8));
+		})
+	};
+	const mockWithHelpers = mock;
+	mockWithHelpers.simulatePosition = (pos) => {
+		for (const callback of watchers.values()) callback(pos);
+	};
+	return mock;
+}
+/**
+* Install geolocation mocks on the global navigator object.
+* Returns cleanup function.
+*/
+function installGeolocationMocks() {
+	const mockGeo = createMockGeolocation();
+	const existingNavigator = typeof navigator !== "undefined" ? navigator : {};
+	vi.stubGlobal("navigator", {
+		...existingNavigator,
+		geolocation: mockGeo
+	});
+	return () => vi.unstubAllGlobals();
+}
+/**
+* Create a mock DeviceOrientationEvent.
+*/
+function createMockOrientationEvent(alpha, beta, gamma, absolute = false) {
+	return {
+		alpha,
+		beta,
+		gamma,
+		absolute
+	};
+}
+/**
+* Create a mock DeviceOrientationEvent class with requestPermission support.
+*/
+function createMockDeviceOrientationEventClass(permissionGranted = true) {
+	return class MockDeviceOrientationEvent {
+		alpha;
+		beta;
+		gamma;
+		absolute;
+		constructor(type, init) {
+			this.alpha = init?.alpha ?? null;
+			this.beta = init?.beta ?? null;
+			this.gamma = init?.gamma ?? null;
+			this.absolute = init?.absolute ?? false;
+		}
+		static requestPermission = vi.fn(() => Promise.resolve(permissionGranted ? "granted" : "denied"));
+	};
+}
+/**
+* Create a mock file handle.
+*/
+function createMockFileHandle(name, content = "") {
+	const file = new File([content], name, { type: "application/json" });
+	const writable = {
+		write: vi.fn(() => Promise.resolve()),
+		close: vi.fn(() => Promise.resolve())
+	};
+	return {
+		kind: "file",
+		name,
+		getFile: vi.fn(() => Promise.resolve(file)),
+		createWritable: vi.fn(() => Promise.resolve(writable))
+	};
+}
+/**
+* Create a mock directory handle with specified files.
+*/
+function createMockDirectoryHandle(name, files = /* @__PURE__ */ new Map(), subdirs = /* @__PURE__ */ new Map()) {
+	return {
+		kind: "directory",
+		name,
+		entries: vi.fn(function* () {
+			for (const [fileName, content] of files) yield [fileName, createMockFileHandle(fileName, content)];
+			for (const [dirName, dirHandle] of subdirs) yield [dirName, dirHandle];
+		}),
+		getFileHandle: vi.fn((fileName, options) => {
+			if (files.has(fileName)) return Promise.resolve(createMockFileHandle(fileName, files.get(fileName)));
+			if (options?.create) {
+				files.set(fileName, "");
+				return Promise.resolve(createMockFileHandle(fileName, ""));
+			}
+			return Promise.reject(new DOMException(`File ${fileName} not found`, "NotFoundError"));
+		}),
+		getDirectoryHandle: vi.fn((dirName, options) => {
+			if (subdirs.has(dirName)) return Promise.resolve(subdirs.get(dirName));
+			if (options?.create) {
+				const newDir = createMockDirectoryHandle(dirName);
+				subdirs.set(dirName, newDir);
+				return Promise.resolve(newDir);
+			}
+			return Promise.reject(new DOMException(`Directory ${dirName} not found`, "NotFoundError"));
+		}),
+		removeEntry: vi.fn((entryName) => {
+			files.delete(entryName);
+			subdirs.delete(entryName);
+			return Promise.resolve();
+		})
+	};
+}
+/**
+* Class-based mock FileSystemFileHandle for tests requiring mutable state.
+* Use this when you need to modify file contents during tests.
+*/
+var MockFSFileHandle = class {
+	kind = "file";
+	name;
+	content;
+	constructor(name, content = "") {
+		this.name = name;
+		this.content = content;
+	}
+	getFile() {
+		const type = this.name.endsWith(".zip") ? "application/zip" : "application/json";
+		const blobPart = typeof this.content === "string" ? this.content : this.content.buffer;
+		return Promise.resolve(new File([blobPart], this.name, { type }));
+	}
+	createWritable() {
+		const writable = {
+			write: vi.fn((data) => {
+				this.content = data;
+				return Promise.resolve();
+			}),
+			close: vi.fn(() => Promise.resolve())
+		};
+		return Promise.resolve(writable);
+	}
+	createSyncAccessHandle() {
+		throw new Error("Not implemented");
+	}
+	isSameEntry() {
+		throw new Error("Not implemented");
+	}
+};
+/**
+* Class-based mock FileSystemDirectoryHandle for tests requiring addFile/addDirectory.
+* Implements the full FileSystemDirectoryHandle interface.
+*/
+var MockFSDirectoryHandle = class MockFSDirectoryHandle {
+	kind = "directory";
+	name;
+	contents = /* @__PURE__ */ new Map();
+	constructor(name) {
+		this.name = name;
+	}
+	/**
+	* Add a file to this directory.
+	* Accepts string content (for JSON etc) or Uint8Array (for zip bytes).
+	*/
+	addFile(name, content) {
+		this.contents.set(name, new MockFSFileHandle(name, content));
+	}
+	/**
+	* Add a subdirectory to this directory.
+	*/
+	addDirectory(name, handle) {
+		this.contents.set(name, handle);
+	}
+	async *entries() {
+		await Promise.resolve();
+		for (const entry of this.contents) yield entry;
+		return void 0;
+	}
+	async *[Symbol.asyncIterator]() {
+		await Promise.resolve();
+		for (const entry of this.contents) yield entry;
+		return void 0;
+	}
+	getDirectoryHandle(name, options) {
+		const handle = this.contents.get(name);
+		if (handle && handle.kind === "directory") return Promise.resolve(handle);
+		if (options?.create) {
+			const newHandle = new MockFSDirectoryHandle(name);
+			this.contents.set(name, newHandle);
+			return Promise.resolve(newHandle);
+		}
+		return Promise.reject(new DOMException(`Directory ${name} not found`, "NotFoundError"));
+	}
+	getFileHandle(name, options) {
+		const handle = this.contents.get(name);
+		if (handle && handle.kind === "file") return Promise.resolve(handle);
+		if (options?.create) {
+			const newHandle = new MockFSFileHandle(name, "");
+			this.contents.set(name, newHandle);
+			return Promise.resolve(newHandle);
+		}
+		return Promise.reject(new DOMException(`File ${name} not found`, "NotFoundError"));
+	}
+	removeEntry(name) {
+		this.contents.delete(name);
+		return Promise.resolve();
+	}
+	resolve() {
+		throw new Error("Not implemented");
+	}
+	isSameEntry() {
+		throw new Error("Not implemented");
+	}
+	async *values() {
+		await Promise.resolve();
+		for (const handle of this.contents.values()) yield handle;
+		return void 0;
+	}
+	async *keys() {
+		await Promise.resolve();
+		for (const name of this.contents.keys()) yield name;
+		return void 0;
+	}
+	queryPermission(_descriptor) {
+		return Promise.resolve("granted");
+	}
+};
+/**
+* Install File System Access API mocks on the global window object.
+* Returns cleanup function.
+*/
+function installFileSystemMocks(rootDir) {
+	const mockRoot = rootDir ?? createMockDirectoryHandle("root");
+	const showDirectoryPicker = vi.fn(() => Promise.resolve(mockRoot));
+	vi.stubGlobal("showDirectoryPicker", showDirectoryPicker);
+	return () => vi.unstubAllGlobals();
+}
+/**
+* Install all browser mocks at once.
+* Returns cleanup function.
+*/
+function installAllBrowserMocks(options) {
+	const cleanups = [];
+	if (options?.webxrSupported !== false) cleanups.push(installWebXRMocks(options?.webxrSupported ?? true));
+	if (options?.geolocation !== false) cleanups.push(installGeolocationMocks());
+	if (options?.fileSystem !== false) cleanups.push(installFileSystemMocks(options?.rootDir));
+	return () => {
+		for (const cleanup of cleanups) cleanup();
+	};
+}
+/**
+* In-memory file system for OPFS mocking.
+* Stores file contents as ArrayBuffer for binary compatibility.
+*/
+var MockOPFSDirectoryHandle = class MockOPFSDirectoryHandle {
+	kind = "directory";
+	name;
+	contents = /* @__PURE__ */ new Map();
+	fileContents = /* @__PURE__ */ new Map();
+	constructor(name) {
+		this.name = name;
+	}
+	/**
+	* Get stored file content (for test assertions).
+	*/
+	getStoredContent(fileName) {
+		return this.fileContents.get(fileName);
+	}
+	/**
+	* Get stored file content as string (for test assertions).
+	*/
+	getStoredContentAsString(fileName) {
+		const content = this.fileContents.get(fileName);
+		if (!content) return;
+		return new TextDecoder().decode(content);
+	}
+	/**
+	* Set file content directly (for test setup).
+	* Also ensures a corresponding file handle exists in contents map
+	* so that getFileHandle() and iterators work correctly.
+	*/
+	setStoredContent(fileName, content) {
+		if (typeof content === "string") this.fileContents.set(fileName, new TextEncoder().encode(content).buffer);
+		else this.fileContents.set(fileName, content);
+		if (!this.contents.has(fileName)) this.contents.set(fileName, new MockOPFSFileHandle(fileName, this, fileName));
+	}
+	async *entries() {
+		await Promise.resolve();
+		for (const entry of this.contents) yield entry;
+		return void 0;
+	}
+	async *[Symbol.asyncIterator]() {
+		await Promise.resolve();
+		for (const entry of this.contents) yield entry;
+		return void 0;
+	}
+	getDirectoryHandle(name, options) {
+		const handle = this.contents.get(name);
+		if (handle && handle.kind === "directory") return Promise.resolve(handle);
+		if (options?.create) {
+			const newHandle = new MockOPFSDirectoryHandle(name);
+			this.contents.set(name, newHandle);
+			return Promise.resolve(newHandle);
+		}
+		return Promise.reject(new DOMException(`Directory ${name} not found`, "NotFoundError"));
+	}
+	getFileHandle(name, options) {
+		const handle = this.contents.get(name);
+		if (handle && handle.kind === "file") return Promise.resolve(handle);
+		if (options?.create) {
+			const newHandle = new MockOPFSFileHandle(name, this, name);
+			this.contents.set(name, newHandle);
+			return Promise.resolve(newHandle);
+		}
+		return Promise.reject(new DOMException(`File ${name} not found`, "NotFoundError"));
+	}
+	removeEntry(name) {
+		this.contents.delete(name);
+		this.fileContents.delete(name);
+		return Promise.resolve();
+	}
+	resolve() {
+		throw new Error("Not implemented");
+	}
+	isSameEntry() {
+		throw new Error("Not implemented");
+	}
+	async *values() {
+		await Promise.resolve();
+		for (const handle of this.contents.values()) yield handle;
+		return void 0;
+	}
+	async *keys() {
+		await Promise.resolve();
+		for (const name of this.contents.keys()) yield name;
+		return void 0;
+	}
+	queryPermission(_descriptor) {
+		return Promise.resolve("granted");
+	}
+};
+/**
+* Mock OPFS file handle with writable stream support.
+*/
+var MockOPFSFileHandle = class {
+	kind = "file";
+	name;
+	parentDir;
+	storageKey;
+	constructor(name, parentDir, storageKey) {
+		this.name = name;
+		this.parentDir = parentDir;
+		this.storageKey = storageKey;
+	}
+	getFile() {
+		const content = this.parentDir.getStoredContent(this.storageKey);
+		const contentArray = content ? new Uint8Array(content) : new Uint8Array(0);
+		const file = new File([contentArray], this.name, { type: "application/octet-stream" });
+		if (typeof file.text !== "function") file.text = () => Promise.resolve(new TextDecoder().decode(contentArray));
+		if (typeof file.arrayBuffer !== "function") file.arrayBuffer = () => Promise.resolve(contentArray.buffer.slice(0));
+		return Promise.resolve(file);
+	}
+	createWritable() {
+		const chunks = [];
+		const parentDir = this.parentDir;
+		const storageKey = this.storageKey;
+		const writable = {
+			write: vi.fn(async (data) => {
+				if (typeof data === "string") chunks.push(new TextEncoder().encode(data).buffer);
+				else if (data instanceof Blob) if (typeof data.arrayBuffer === "function") {
+					const buffer = await data.arrayBuffer();
+					chunks.push(buffer);
+				} else {
+					const text = await new Promise((resolve, reject) => {
+						const reader = new FileReader();
+						reader.onload = () => resolve(reader.result);
+						reader.onerror = reject;
+						reader.readAsText(data);
+					});
+					chunks.push(new TextEncoder().encode(text).buffer);
+				}
+				else if (data instanceof ArrayBuffer) chunks.push(data);
+				else if (ArrayBuffer.isView(data)) chunks.push(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+			}),
+			close: vi.fn(() => {
+				const totalLength = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+				const combined = new Uint8Array(totalLength);
+				let offset = 0;
+				for (const chunk of chunks) {
+					combined.set(new Uint8Array(chunk), offset);
+					offset += chunk.byteLength;
+				}
+				parentDir.setStoredContent(storageKey, combined.buffer);
+				return Promise.resolve();
+			}),
+			seek: vi.fn(),
+			truncate: vi.fn(),
+			abort: vi.fn(() => Promise.resolve()),
+			locked: false,
+			getWriter: vi.fn()
+		};
+		return Promise.resolve(writable);
+	}
+	createSyncAccessHandle() {
+		throw new Error("Not implemented in mock");
+	}
+	isSameEntry() {
+		throw new Error("Not implemented");
+	}
+};
+/**
+* Create a mock StorageManager with OPFS support.
+*/
+function createMockStorageManager(opfsRoot) {
+	const root = opfsRoot ?? new MockOPFSDirectoryHandle("");
+	return {
+		getDirectory: vi.fn(() => Promise.resolve(root)),
+		estimate: vi.fn(() => Promise.resolve({
+			quota: 1024 * 1024 * 1024,
+			usage: 0
+		})),
+		persist: vi.fn(() => Promise.resolve(true)),
+		persisted: vi.fn(() => Promise.resolve(true))
+	};
+}
+/**
+* Install OPFS mocks on the global navigator object.
+* Returns the mock OPFS root directory for test assertions and cleanup function.
+*/
+function installOPFSMocks(opfsRoot) {
+	const root = opfsRoot ?? new MockOPFSDirectoryHandle("");
+	const mockStorage = createMockStorageManager(root);
+	const existingNavigator = typeof navigator !== "undefined" ? navigator : {};
+	vi.stubGlobal("navigator", {
+		...existingNavigator,
+		storage: mockStorage
+	});
+	return {
+		root,
+		cleanup: () => vi.unstubAllGlobals()
+	};
+}
+//#endregion
+export { MockFSDirectoryHandle, MockFSFileHandle, MockOPFSDirectoryHandle, MockOPFSFileHandle, createMockDepthInfo, createMockDeviceOrientationEventClass, createMockDirectoryHandle, createMockFileHandle, createMockFrame, createMockGeoPosition, createMockGeolocation, createMockOrientationEvent, createMockPose, createMockStorageManager, createMockXR, createMockXRSession, installAllBrowserMocks, installFileSystemMocks, installGeolocationMocks, installOPFSMocks, installWebXRMocks };

package/dist/test-utils/zip-round-trip-helpers.d.ts

@@ -0,0 +1,60 @@
+import { i as RecordedAction } from "../zip-reader-D7pkpX8K.js";
+import { LatLong } from "gps-plus-slam-js";
+
+//#region ../src/test-utils/zip-round-trip-helpers.d.ts
+/** Configuration for producing a test zip. All fields have sensible defaults. */
+interface ProduceTestZipOptions {
+  scenarioName: string;
+  sessionTimestamp: Date;
+  gpsEventCount: number;
+  imagesBeforeSetZero: number;
+  imagesAfterSetZero: number;
+  frameCount: number;
+  deviceInfo: string;
+  zeroPos: LatLong;
+}
+/** Result of producing a test zip, with all metadata needed for assertions. */
+interface TestZipResult {
+  /** The zip file as a Uint8Array, ready for loadActionsFromZip / readZipEntries */
+  zipData: Uint8Array;
+  /** Total number of Redux action files in the zip */
+  totalActionCount: number;
+  /** Number of gpsData/recordGpsEvent actions */
+  gpsEventCount: number;
+  /** Breakdown of gpsData/add2dImage actions */
+  imageActions: {
+    totalCount: number;
+    beforeSetZero: number;
+    afterSetZero: number;
+  };
+  scenarioName: string;
+  sessionName: string;
+  startTime: number;
+  deviceInfo: string;
+  /** Whether session.json is present in the zip */
+  hasSessionJson: boolean;
+  /** The zero reference position used for GPS events */
+  zeroPos: LatLong;
+  /** All actions as written, in order, for assertion comparisons */
+  actions: RecordedAction[];
+  /** Number of frame files in the zip */
+  frameCount: number;
+}
+/**
+ * Produce a realistic recording zip using the real OPFS mock + export pipeline.
+ *
+ * Action sequence produced (with defaults):
+ *   1. recorder/startSession        (index 1)
+ *   2. gpsData/add2dImage × 2       (indices 2-3, before setZeroPos — dropped on replay)
+ *   3. gpsData/setZeroPos            (index 4)
+ *   4. gpsData/recordGpsEvent × 10   (indices 5-14)
+ *   5. gpsData/add2dImage × 5        (indices 15-19, after setZeroPos — kept on replay)
+ *
+ * GPS events use varied odom/GPS positions that produce a non-identity
+ * alignment matrix when replayed through the library store.
+ *
+ * OPFS mocks are installed and cleaned up within this function.
+ */
+declare function produceTestZip(opts?: Partial<ProduceTestZipOptions>): Promise<TestZipResult>;
+//#endregion
+export { ProduceTestZipOptions, type RecordedAction, TestZipResult, produceTestZip };