gps-plus-slam-app-framework 1.2.0 → 1.4.0

package/dist/storage/file-system-utils.js

@@ -27,5 +27,21 @@ function formatActionFilename(index) {
 function formatFrameFilename(index) {
 	return `frame-${String(index).padStart(6, "0")}.jpg`;
 }
+/**
+* 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).
+*/
+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.
+*/
+const LEGACY_SESSION_IMAGES_DIR = "frames";
 //#endregion
-export { formatActionFilename, formatFrameFilename, formatTimestamp };
+export { LEGACY_SESSION_IMAGES_DIR, SESSION_IMAGES_DIR, formatActionFilename, formatFrameFilename, formatTimestamp };

package/dist/storage/index.d.ts

@@ -1,9 +1,9 @@
-import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, h as writeSessionMetadata$1, i as createSession, l as listSessions, n as SessionMetadata, o as getSessionHandle, r as checkStorageQuota, s as getSessionsRootHandle, u as resetOpfsStorage } from "../opfs-storage-DYm8WHq7.js";
-import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-C9HLFtgz.js";
-import { a as ZipActionEntry, c as loadEntriesFromSubdir, d as loadSessionMetadataFromBlob, f as readZipEntries, i as RecordedAction, l as loadGpsPathFromBlob, n as GpsPathCoord, o as ZipSubdirEntry, r as MAX_ACTION_FILE_SIZE, s as loadActionsFromZip, t as Entry, u as loadSessionMetadata } from "../zip-reader-DSEXt7K6.js";
-import { t as NullStorageBackend } from "../null-storage-backend-CxEjZHRW.js";
-import { t as OpfsStorageBackend } from "../opfs-storage-backend-CjSAuqg_.js";
-import { a as getCurrentScenarioHandle, c as resetForNewSession, d as startSession, f as verifyWriteAccess, h as writeSessionMetadata, i as ensureScenarioDirectory, l as resetStorageState, m as writeFrame, n as WriteAccessResult, o as initStorage, p as writeAction, s as listSessions$1, u as setCurrentScenario } from "../file-system-C_eqiEA8.js";
-import { n as formatFrameFilename, r as formatTimestamp, t as formatActionFilename } from "../file-system-utils-DyAmcuvX.js";
-import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportAndDownloadSession, r as ZipExportContributor, s as exportSessionAsZip, t as ExportSessionAsZipOptions } from "../zip-export-D_5HAvFz.js";
-export { type CreateSessionResult, type Entry, type ExportSessionAsZipOptions, type GpsPathCoord, MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, type RecordedAction, type SessionMetadata, type StorageBackend, type WriteAccessResult, type ZipActionEntry, type ZipContributorAddFile, type ZipExportContributor, type ZipExportResult, type ZipSubdirEntry, checkStorageQuota, createSession, downloadZip, ensureScenarioDirectory, exportAndDownloadSession, exportSessionAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getCurrentScenarioHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, initStorage, listSessions, listSessions$1 as listSessionsFromFileSystem, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetForNewSession, resetOpfsStorage, resetSessionHandles, resetStorageState, setCurrentScenario, startSession as startStorageSession, syncToExternalZip, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata as writeSessionMeta, writeSessionMetadata$1 as writeSessionMetadata };
+import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, h as writeSessionMetadata, i as createSession, l as listSessions, n as SessionMetadata, o as getSessionHandle, r as checkStorageQuota, s as getSessionsRootHandle, u as resetOpfsStorage } from "../opfs-storage-DMtlt57S.js";
+import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-CTJHNdMp.js";
+import { a as ZipActionEntry, c as loadEntriesFromSubdir, d as loadSessionMetadataFromBlob, f as readZipEntries, i as RecordedAction, l as loadGpsPathFromBlob, n as GpsPathCoord, o as ZipSubdirEntry, r as MAX_ACTION_FILE_SIZE, s as loadActionsFromZip, t as Entry, u as loadSessionMetadata } from "../zip-reader-Q2ue6zlC.js";
+import { t as NullStorageBackend } from "../null-storage-backend-CuSdYFsM.js";
+import { t as OpfsStorageBackend } from "../opfs-storage-backend-CeQAb0SD.js";
+import { a as formatTimestamp, i as formatFrameFilename, r as formatActionFilename } from "../file-system-utils-Bs7lpeVP.js";
+import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportSessionAsZip, r as ZipExportContributor, s as exportSessionHandleAsZip, t as ExportSessionAsZipOptions } from "../zip-export-DDWXInTR.js";
+import { t as embedCoverageInSessionJson } from "../zip-coverage-embed-tFohI2J4.js";
+export { type CreateSessionResult, type Entry, type ExportSessionAsZipOptions, type GpsPathCoord, MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, type RecordedAction, type SessionMetadata, type StorageBackend, type ZipActionEntry, type ZipContributorAddFile, type ZipExportContributor, type ZipExportResult, type ZipSubdirEntry, checkStorageQuota, createSession, downloadZip, embedCoverageInSessionJson, exportSessionAsZip, exportSessionHandleAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetOpfsStorage, resetSessionHandles, syncToExternalZip, writeSessionMetadata };

package/dist/storage/index.js

@@ -1,8 +1,8 @@
 import { MAX_ACTION_FILE_SIZE, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries } from "./zip-reader.js";
 import { formatActionFilename, formatFrameFilename, formatTimestamp } from "./file-system-utils.js";
 import { NullStorageBackend } from "./null-storage-backend.js";
-import { checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, writeSessionMetadata as writeSessionMetadata$1 } from "./opfs-storage.js";
-import { ensureScenarioDirectory, getCurrentScenarioHandle, initStorage, listSessions as listSessions$1, resetForNewSession, resetStorageState, setCurrentScenario, startSession, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata } from "./file-system.js";
+import { checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, writeSessionMetadata } from "./opfs-storage.js";
 import { OpfsStorageBackend } from "./opfs-storage-backend.js";
-import { downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip } from "./zip-export.js";
-export { MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, checkStorageQuota, createSession, downloadZip, ensureScenarioDirectory, exportAndDownloadSession, exportSessionAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getCurrentScenarioHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, initStorage, listSessions, listSessions$1 as listSessionsFromFileSystem, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetForNewSession, resetOpfsStorage, resetSessionHandles, resetStorageState, setCurrentScenario, startSession as startStorageSession, syncToExternalZip, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata as writeSessionMeta, writeSessionMetadata$1 as writeSessionMetadata };
+import { downloadZip, exportSessionAsZip, exportSessionHandleAsZip, syncToExternalZip } from "./zip-export.js";
+import { embedCoverageInSessionJson } from "./zip-coverage-embed.js";
+export { MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, checkStorageQuota, createSession, downloadZip, embedCoverageInSessionJson, exportSessionAsZip, exportSessionHandleAsZip, formatActionFilename, formatFrameFilename, formatTimestamp, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetOpfsStorage, resetSessionHandles, syncToExternalZip, writeSessionMetadata };

package/dist/storage/null-storage-backend.d.ts

@@ -1,2 +1,2 @@
-import { t as NullStorageBackend } from "../null-storage-backend-CxEjZHRW.js";
+import { t as NullStorageBackend } from "../null-storage-backend-CuSdYFsM.js";
 export { NullStorageBackend };

package/dist/storage/opfs-storage-backend.d.ts

@@ -1,2 +1,2 @@
-import { t as OpfsStorageBackend } from "../opfs-storage-backend-CjSAuqg_.js";
+import { t as OpfsStorageBackend } from "../opfs-storage-backend-CeQAb0SD.js";
 export { OpfsStorageBackend };

package/dist/storage/opfs-storage-backend.js

@@ -1,8 +1,8 @@
-import { listSessions, startSession, writeAction, writeFrame, writeSessionMetadata } from "./file-system.js";
+import { createSession, listSessions, writeAction, writeFrame, writeSessionMetadata } from "./opfs-storage.js";
 //#region ../src/storage/opfs-storage-backend.ts
 var OpfsStorageBackend = class {
-	async createSession(_timestamp, _contextTag) {
-		return { sessionName: (await startSession()).sessionPath };
+	async createSession(timestamp, _contextTag) {
+		return { sessionName: (await createSession(timestamp)).sessionName };
 	}
 	async listSessions() {
 		return listSessions();

package/dist/storage/opfs-storage.d.ts

@@ -1,2 +1,2 @@
-import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, f as setSessionHandles, h as writeSessionMetadata, i as createSession, l as listSessions, m as writeFrame, n as SessionMetadata, o as getSessionHandle, p as writeAction, r as checkStorageQuota, s as getSessionsRootHandle, t as CreateSessionResult, u as resetOpfsStorage } from "../opfs-storage-DYm8WHq7.js";
+import { a as getAppRootHandle, c as initOpfsStorage, d as resetSessionHandles, f as setSessionHandles, h as writeSessionMetadata, i as createSession, l as listSessions, m as writeFrame, n as SessionMetadata, o as getSessionHandle, p as writeAction, r as checkStorageQuota, s as getSessionsRootHandle, t as CreateSessionResult, u as resetOpfsStorage } from "../opfs-storage-DMtlt57S.js";
 export { CreateSessionResult, SessionMetadata, checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, setSessionHandles, writeAction, writeFrame, writeSessionMetadata };

package/dist/storage/opfs-storage.js

@@ -1,5 +1,5 @@
 import { createLogger } from "../utils/logger.js";
-import { formatActionFilename, formatFrameFilename, formatTimestamp } from "./file-system-utils.js";
+import { SESSION_IMAGES_DIR, formatActionFilename, formatFrameFilename, formatTimestamp } from "./file-system-utils.js";
 //#region ../src/storage/opfs-storage.ts
 /**
 * OPFS Storage Module
@@ -16,7 +16,7 @@ import { formatActionFilename, formatFrameFilename, formatTimestamp } from "./fi
 *       │   ├── actions/
 *       │   │   ├── 000001.json
 *       │   │   └── ...
-*       │   └── frames/
+*       │   └── images/        (legacy recordings: frames/)
 *       │       ├── frame-000001.jpg
 *       │       └── ...
 *       └── ...
@@ -94,7 +94,7 @@ function getAppRootHandle() {
 * Creates the directory structure:
 * - /gps-plus-slam/sessions/recording-{timestamp}/
 * - /gps-plus-slam/sessions/recording-{timestamp}/actions/
-* - /gps-plus-slam/sessions/recording-{timestamp}/frames/
+* - /gps-plus-slam/sessions/recording-{timestamp}/images/ (legacy: frames/)
 *
 * @param timestamp - Session start time (used for folder naming)
 * @param _contextTag - Opaque tag; not used by the flat layout but accepted
@@ -107,7 +107,7 @@ async function createSession(timestamp, _contextTag) {
 	const sessionName = `recording-${formatTimestamp(timestamp)}`;
 	currentSessionHandle = await sessionsDir.getDirectoryHandle(sessionName, { create: true });
 	actionsHandle = await currentSessionHandle.getDirectoryHandle("actions", { create: true });
-	framesHandle = await currentSessionHandle.getDirectoryHandle("frames", { create: true });
+	framesHandle = await currentSessionHandle.getDirectoryHandle(SESSION_IMAGES_DIR, { create: true });
 	log.info("Session created:", sessionName);
 	return { sessionName };
 }
@@ -121,10 +121,11 @@ function getSessionHandle() {
 /**
 * Set the active session handles externally.
 *
-* Used by file-system.ts's scenario-based path to reuse opfs-storage's
-* write infrastructure for sessions created outside the flat layout.
-* This is a temporary bridge until the recorder migrates to
-* ScenarioWrappingStorageBackend.
+* Lets a wrapping StorageBackend that creates sessions outside the flat layout
+* (e.g. the recorder's `ScenarioWrappingStorageBackend`, which nests sessions
+* under a named bucket) reuse opfs-storage's write infrastructure: it creates
+* the session directory itself, then hands the handles here so subsequent
+* `writeAction` / `writeFrame` / `writeSessionMetadata` calls target them.
 *
 * @internal
 */

package/dist/storage/storage-backend.d.ts

@@ -1,2 +1,2 @@
-import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-C9HLFtgz.js";
+import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-CTJHNdMp.js";
 export { CreateSessionResult, StorageBackend };

package/dist/storage/zip-coverage-embed.d.ts

@@ -0,0 +1,2 @@
+import { t as embedCoverageInSessionJson } from "../zip-coverage-embed-tFohI2J4.js";
+export { embedCoverageInSessionJson };

package/dist/storage/zip-coverage-embed.js

@@ -0,0 +1,88 @@
+import { createLogger } from "../utils/logger.js";
+import { BlobReader, BlobWriter, TextReader, TextWriter, Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.js/zip.js";
+//#region ../src/storage/zip-coverage-embed.ts
+/**
+* Zip Coverage Embed — write a recording's H3 coverage into its `session.json`.
+*
+* The map-centric browser indexes legacy recordings (those predating the
+* `h3Cells` field) by reading their full GPS path — slow, and repeated on every
+* folder open. This primitive lets a one-time "upgrade" embed the derived
+* coverage **inside the recording's own `session.json`**, so the recording
+* indexes instantly on every future open in this app *and any other reader*
+* (the portability the user asked for; O3 — in-zip rewrite).
+*
+* It is a pure transform `(zip, cells, resolution) -> zip`: it reads every entry
+* and re-emits a new zip identical to the input except that `session.json` gains
+* `h3Cells` + `h3Resolution`. It never mutates anything in place — the caller
+* (the RecorderApp backfill) owns the safe write-then-verify-then-overwrite
+* protocol around it.
+*
+* @see ./zip-coverage-embed.ts.md
+* @see GpsPlusSlamJs_Docs/docs/2026-06-14-followup-progressive-map-browser-indexing-and-backfill.md (B3)
+*/
+const log = createLogger("ZipCoverageEmbed");
+/**
+* Return a new zip blob identical to `zip` except its `session.json` gains
+* `h3Cells` + `h3Resolution`.
+*
+* **Skips (returns the input blob unchanged, by reference) when:**
+*   - the zip has no `session.json` (nothing to embed into);
+*   - `session.json` is present but unparseable (never write over a broken one);
+*   - `session.json` already carries `h3Cells` (idempotent — re-running the
+*     upgrade is a no-op, and new recordings are skipped).
+*
+* On any unexpected read/write failure it also returns the input untouched —
+* it never emits a partial zip. Callers can detect a skip via reference
+* equality (`result === zip`).
+*
+* Built on `@zip.js/zip.js` (the same library as the exporter) in store mode, so
+* every non-`session.json` entry is re-emitted with byte-identical uncompressed
+* content.
+*/
+async function embedCoverageInSessionJson(zip, h3Cells, h3Resolution) {
+	const reader = new ZipReader(new BlobReader(zip));
+	try {
+		const entries = await reader.getEntries();
+		const sessionEntry = entries.find((e) => !e.directory && e.filename.endsWith("session.json"));
+		if (!sessionEntry) {
+			log.warn("No session.json found; leaving zip untouched");
+			return zip;
+		}
+		let session;
+		try {
+			const text = await sessionEntry.getData(new TextWriter());
+			session = JSON.parse(text);
+		} catch (err) {
+			log.warn("session.json unparseable; leaving zip untouched", err);
+			return zip;
+		}
+		if (session.h3Cells !== void 0) return zip;
+		const merged = {
+			...session,
+			h3Cells,
+			h3Resolution
+		};
+		const writer = new ZipWriter(new BlobWriter("application/zip"), { level: 0 });
+		try {
+			for (const entry of entries) {
+				if (entry.directory || !entry.getData) continue;
+				if (entry === sessionEntry) await writer.add(entry.filename, new TextReader(JSON.stringify(merged)));
+				else {
+					const bytes = await entry.getData(new Uint8ArrayWriter());
+					await writer.add(entry.filename, new Uint8ArrayReader(bytes));
+				}
+			}
+			return await writer.close();
+		} catch (err) {
+			log.warn("Failed to re-emit zip; leaving original untouched", err);
+			return zip;
+		}
+	} catch (err) {
+		log.warn("Failed to read zip for coverage embed; leaving untouched", err);
+		return zip;
+	} finally {
+		await reader.close();
+	}
+}
+//#endregion
+export { embedCoverageInSessionJson };

package/dist/storage/zip-export.d.ts

@@ -1,2 +1,2 @@
-import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportAndDownloadSession, r as ZipExportContributor, s as exportSessionAsZip, t as ExportSessionAsZipOptions } from "../zip-export-D_5HAvFz.js";
-export { ExportSessionAsZipOptions, ZipContributorAddFile, ZipExportContributor, ZipExportResult, downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };
+import { a as downloadZip, c as syncToExternalZip, i as ZipExportResult, n as ZipContributorAddFile, o as exportSessionAsZip, r as ZipExportContributor, s as exportSessionHandleAsZip, t as ExportSessionAsZipOptions } from "../zip-export-DDWXInTR.js";
+export { ExportSessionAsZipOptions, ZipContributorAddFile, ZipExportContributor, ZipExportResult, downloadZip, exportSessionAsZip, exportSessionHandleAsZip, syncToExternalZip };

package/dist/storage/zip-export.js

@@ -20,14 +20,6 @@ import { BlobReader, BlobWriter, ZipWriter } from "@zip.js/zip.js";
 */
 const log = createLogger("ZipExport");
 /**
-* Get the OPFS scenarios directory handle.
-* Re-acquires from navigator.storage to avoid holding stale references.
-* Creates on demand so it works even when initOpfsStorage only creates sessions/.
-*/
-async function getScenariosHandle() {
-	return (await (await navigator.storage.getDirectory()).getDirectoryHandle("gps-plus-slam")).getDirectoryHandle("scenarios", { create: true });
-}
-/**
 * Get the OPFS sessions directory handle (flat layout).
 */
 async function getSessionsHandle() {
@@ -56,49 +48,48 @@ async function streamDirectoryToZip(dirHandle, zipWriter, basePath = "") {
 	return count;
 }
 /**
-* Export a session from OPFS as a ZIP blob.
+* Export a flat-layout session from OPFS as a ZIP blob.
 *
 * The ZIP structure mirrors the OPFS session structure:
 * - session.json (at root)
 * - actions/000001.json, actions/000002.json, ...
-* - frames/frame-000001.jpg, frames/frame-000002.jpg, ...
-* - refPoints/{h3}.json (only observations from this session, scenario layout only)
+* - images/frame-000001.jpg, images/frame-000002.jpg, ... (legacy: frames/)
 *
-* Uses "store" mode (compression level 0) for fast packaging.
-*
-* Supports both flat and scenario-based layouts:
-* - `exportSessionAsZip(sessionName)` — flat layout (sessions/)
-* - `exportSessionAsZip(scenarioName, sessionName)` — scenario layout (scenarios/{name}/)
+* Uses "store" mode (compression level 0) for fast packaging. Consumers with a
+* different on-disk layout (one that nests sessions under a named bucket)
+* resolve their own session handle and call {@link exportSessionHandleAsZip}.
 *
+* @param sessionName - Name of the session folder under `sessions/`.
 * @returns ZIP export result with blob and file count
-* @throws Error if session not found
+* @throws Error if the session is not found
 */
-async function exportSessionAsZip(scenarioNameOrSessionName, sessionName, options) {
+async function exportSessionAsZip(sessionName, options) {
+	log.info(`Exporting session: ${sessionName}`);
+	const sessionsDir = await getSessionsHandle();
 	let sessionHandle;
-	if (sessionName) {
-		const scenarioName = scenarioNameOrSessionName;
-		log.info(`Exporting session: ${scenarioName}/${sessionName}`);
-		const scenariosDir = await getScenariosHandle();
-		let scenarioHandle;
-		try {
-			scenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName);
-		} catch {
-			throw new Error(`Scenario "${scenarioName}" not found in OPFS storage`);
-		}
-		try {
-			sessionHandle = await scenarioHandle.getDirectoryHandle(sessionName);
-		} catch {
-			throw new Error(`Session "${sessionName}" not found in scenario "${scenarioName}"`);
-		}
-	} else {
-		log.info(`Exporting session: ${scenarioNameOrSessionName}`);
-		const sessionsDir = await getSessionsHandle();
-		try {
-			sessionHandle = await sessionsDir.getDirectoryHandle(scenarioNameOrSessionName);
-		} catch {
-			throw new Error(`Session "${scenarioNameOrSessionName}" not found in OPFS storage`);
-		}
+	try {
+		sessionHandle = await sessionsDir.getDirectoryHandle(sessionName);
+	} catch {
+		throw new Error(`Session "${sessionName}" not found in OPFS storage`);
 	}
+	return exportSessionHandleAsZip(sessionHandle, options);
+}
+/**
+* Stream an already-resolved session directory handle to a ZIP blob, running
+* any caller-supplied extension {@link ZipExportContributor}s after the
+* framework-owned files.
+*
+* This is the layout-agnostic core of {@link exportSessionAsZip}: consumers
+* that resolve a session directory handle themselves (e.g. an app that nests
+* sessions under its own grouping layer) call this directly so the framework's
+* ZIP schema stays the single source of truth without the framework needing to
+* know how the handle was located.
+*
+* @param sessionHandle - The session directory to package (must contain the
+*   framework-owned `session.json` / `actions/` / `images/` tree).
+* @returns ZIP export result with blob and file count.
+*/
+async function exportSessionHandleAsZip(sessionHandle, options) {
 	const zipWriter = new ZipWriter(new BlobWriter("application/zip"), { level: 0 });
 	let fileCount = await streamDirectoryToZip(sessionHandle, zipWriter);
 	const contributors = options?.contributors ?? [];
@@ -136,14 +127,13 @@ async function exportSessionAsZip(scenarioNameOrSessionName, sessionName, option
 * the last synced ZIP contains all data up to that point.
 *
 * @param fileHandle - File handle from showSaveFilePicker
-* @param scenarioName - Name of the scenario
-* @param sessionName - Name of the session folder
+* @param sessionName - Name of the session folder under `sessions/`
 * @returns ZIP export result with blob and file count
-* @throws Error if scenario or session not found
+* @throws Error if the session is not found
 */
-async function syncToExternalZip(fileHandle, scenarioName, sessionName, options) {
-	log.info(`Syncing to external ZIP: ${scenarioName}/${sessionName}`);
-	const result = await exportSessionAsZip(scenarioName, sessionName, options);
+async function syncToExternalZip(fileHandle, sessionName, options) {
+	log.info(`Syncing to external ZIP: ${sessionName}`);
+	const result = await exportSessionAsZip(sessionName, options);
 	const writable = await fileHandle.createWritable();
 	await writable.write(result.blob);
 	await writable.close();
@@ -191,17 +181,5 @@ async function downloadZip(blob, filename) {
 	setTimeout(() => URL.revokeObjectURL(url), 1e3);
 	log.info(`Download triggered via <a download>: ${filename}`);
 }
-/**
-* Export and download a session in one step.
-*
-* Convenience function combining exportSessionAsZip and downloadZip.
-*
-* @param scenarioName - Name of the scenario
-* @param sessionName - Name of the session folder
-*/
-async function exportAndDownloadSession(scenarioName, sessionName) {
-	const { blob } = await exportSessionAsZip(scenarioName, sessionName);
-	await downloadZip(blob, `${scenarioName}-${sessionName}.zip`);
-}
 //#endregion
-export { downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };
+export { downloadZip, exportSessionAsZip, exportSessionHandleAsZip, syncToExternalZip };

package/dist/storage/zip-reader.d.ts

@@ -1,2 +1,2 @@
-import { a as ZipActionEntry, c as loadEntriesFromSubdir, d as loadSessionMetadataFromBlob, f as readZipEntries, i as RecordedAction, l as loadGpsPathFromBlob, n as GpsPathCoord, o as ZipSubdirEntry, r as MAX_ACTION_FILE_SIZE, s as loadActionsFromZip, t as Entry, u as loadSessionMetadata } from "../zip-reader-DSEXt7K6.js";
+import { a as ZipActionEntry, c as loadEntriesFromSubdir, d as loadSessionMetadataFromBlob, f as readZipEntries, i as RecordedAction, l as loadGpsPathFromBlob, n as GpsPathCoord, o as ZipSubdirEntry, r as MAX_ACTION_FILE_SIZE, s as loadActionsFromZip, t as Entry, u as loadSessionMetadata } from "../zip-reader-Q2ue6zlC.js";
 export { Entry, GpsPathCoord, MAX_ACTION_FILE_SIZE, RecordedAction, ZipActionEntry, ZipSubdirEntry, loadActionsFromZip, loadEntriesFromSubdir, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries };

package/dist/storage/zip-reader.js

@@ -13,7 +13,7 @@ import { BlobReader, TextWriter, Uint8ArrayReader, ZipReader } from "@zip.js/zip
 *   actions/000001.json  — Redux action JSON files (1-based, zero-padded)
 *   actions/000002.json
 *   ...
-*   frames/frame-000001.jpg  — captured image frames (optional)
+*   images/frame-000001.jpg  — captured image frames (optional; legacy: frames/)
 *   session.json             — session metadata (optional, see F1 bug)
 */
 const log = createLogger("ZipReader");

package/dist/{storage-backend-C9HLFtgz.d.ts → storage-backend-CTJHNdMp.d.ts}

@@ -1,4 +1,4 @@
-import { n as SessionMetadata } from "./opfs-storage-DYm8WHq7.js";
+import { n as SessionMetadata } from "./opfs-storage-DMtlt57S.js";
 
 //#region ../src/storage/storage-backend.d.ts
 interface CreateSessionResult {

package/dist/{store-subscribers-rrkLkFTt.d.ts → store-subscribers-BZP81hjh.d.ts}

@@ -1,5 +1,5 @@
-import { t as MapData } from "./map-data-CkloBxIl.js";
-import { t as SubscribableStore } from "./subscribe-to-selector-CP3BKSbF.js";
+import { t as MapData } from "./map-data-DdjPiSav.js";
+import { t as SubscribableStore } from "./subscribe-to-selector-Bp3sLx8L.js";
 import { LatLong, Matrix4, Quaternion, Vector3 } from "gps-plus-slam-js";
 
 //#region ../src/state/store-subscribers.d.ts

package/dist/{subscribe-to-selector-CP3BKSbF.d.ts → subscribe-to-selector-Bp3sLx8L.d.ts}

@@ -1,4 +1,4 @@
-import { L as CombinedRootState } from "./create-slam-app-store-qNXQ-tq5.js";
+import { L as CombinedRootState } from "./create-slam-app-store-Ce2FMKCp.js";
 
 //#region ../src/state/subscribe-to-selector.d.ts
 /**

package/dist/test-utils/browser-mocks.d.ts

@@ -1,4 +1,4 @@
-import { o as WebXRQuaternion, s as WebXRVec3 } from "../ar-types-Dan1MVTi.js";
+import { o as WebXRQuaternion, s as WebXRVec3 } from "../ar-types-BckI1E-O.js";
 import { Mock } from "vitest";
 
 //#region ../src/test-utils/browser-mocks.d.ts
@@ -195,6 +195,9 @@ declare class MockFSDirectoryHandle implements FileSystemDirectoryHandle {
   queryPermission(_descriptor?: {
     mode?: 'read' | 'readwrite';
   }): Promise<PermissionState>;
+  requestPermission(_descriptor?: {
+    mode?: 'read' | 'readwrite';
+  }): Promise<PermissionState>;
 }
 /**
  * Install File System Access API mocks on the global window object.
@@ -251,6 +254,9 @@ declare class MockOPFSDirectoryHandle implements FileSystemDirectoryHandle {
   queryPermission(_descriptor?: {
     mode?: 'read' | 'readwrite';
   }): Promise<PermissionState>;
+  requestPermission(_descriptor?: {
+    mode?: 'read' | 'readwrite';
+  }): Promise<PermissionState>;
 }
 /**
  * Mock OPFS file handle with writable stream support.

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

@@ -348,6 +348,9 @@ var MockFSDirectoryHandle = class MockFSDirectoryHandle {
 	queryPermission(_descriptor) {
 		return Promise.resolve("granted");
 	}
+	requestPermission(_descriptor) {
+		return Promise.resolve("granted");
+	}
 };
 /**
 * Install File System Access API mocks on the global window object.
@@ -462,6 +465,9 @@ var MockOPFSDirectoryHandle = class MockOPFSDirectoryHandle {
 	queryPermission(_descriptor) {
 		return Promise.resolve("granted");
 	}
+	requestPermission(_descriptor) {
+		return Promise.resolve("granted");
+	}
 };
 /**
 * Mock OPFS file handle with writable stream support.

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

@@ -1,4 +1,4 @@
-import { i as RecordedAction } from "../zip-reader-DSEXt7K6.js";
+import { i as RecordedAction } from "../zip-reader-Q2ue6zlC.js";
 import { LatLong } from "gps-plus-slam-js";
 
 //#region ../src/test-utils/zip-round-trip-helpers.d.ts
@@ -18,6 +18,14 @@ interface ProduceTestZipOptions {
    * the field is left off — matching pre-accuracy recordings.
    */
   gpsAccuracy?: number;
+  /**
+   * Optional per-tour H3 coverage index written into `session.json`. When
+   * omitted, the fields are left off — matching legacy recordings that predate
+   * the coverage index (so the browser must backfill from the GPS path).
+   * When provided, `h3Resolution` defaults to 11.
+   */
+  h3Cells?: string[];
+  h3Resolution?: number;
 }
 /** Result of producing a test zip, with all metadata needed for assertions. */
 interface TestZipResult {

package/dist/test-utils/zip-round-trip-helpers.js

@@ -1,3 +1,4 @@
+import { SESSION_IMAGES_DIR } from "../storage/file-system-utils.js";
 import { createSession, initOpfsStorage, resetOpfsStorage, writeAction, writeFrame, writeSessionMetadata } from "../storage/opfs-storage.js";
 import { exportSessionAsZip } from "../storage/zip-export.js";
 import { installOPFSMocks } from "./browser-mocks.js";
@@ -86,7 +87,7 @@ async function produceTestZip(opts) {
 		for (let i = 0; i < options.imagesBeforeSetZero; i++) await writeAndRecordAction({
 			type: "gpsData/add2dImage",
 			payload: {
-				imageFile: `frames/frame-${String(actionIndex + 1).padStart(6, "0")}.jpg`,
+				imageFile: `${SESSION_IMAGES_DIR}/frame-${String(actionIndex + 1).padStart(6, "0")}.jpg`,
 				position: [
 					i * .5,
 					0,
@@ -143,7 +144,7 @@ async function produceTestZip(opts) {
 			await writeAndRecordAction({
 				type: "gpsData/add2dImage",
 				payload: {
-					imageFile: `frames/frame-${String(imgIdx).padStart(6, "0")}.jpg`,
+					imageFile: `${SESSION_IMAGES_DIR}/frame-${String(imgIdx).padStart(6, "0")}.jpg`,
 					position: [
 						(i + 1) * 1,
 						(i + 1) * .5,
@@ -178,7 +179,11 @@ async function produceTestZip(opts) {
 			contextTag: options.scenarioName,
 			actionCount: actionIndex,
 			frameCount: options.frameCount,
-			userAgent: options.deviceInfo
+			userAgent: options.deviceInfo,
+			...options.h3Cells ? {
+				h3Cells: options.h3Cells,
+				h3Resolution: options.h3Resolution ?? 11
+			} : {}
 		});
 		const { blob } = await exportSessionAsZip(sessionName);
 		return {

package/dist/{tracking-slice-CdK8c-8P.d.ts → tracking-slice-DJZ9qeGg.d.ts}

@@ -1,4 +1,4 @@
-import { t as ARPose } from "./ar-types-Dan1MVTi.js";
+import { t as ARPose } from "./ar-types-BckI1E-O.js";
 import { OdometryTrackingRestartedPayload, Quaternion, Vector3 } from "gps-plus-slam-js";
 import * as _$_reduxjs_toolkit0 from "@reduxjs/toolkit";
 

package/dist/types/ar-types.d.ts

@@ -1,2 +1,2 @@
-import { a as RgbTuple, i as DepthSample, n as ArPoseTuples, o as WebXRQuaternion, r as DepthPoint, s as WebXRVec3, t as ARPose } from "../ar-types-Dan1MVTi.js";
+import { a as RgbTuple, i as DepthSample, n as ArPoseTuples, o as WebXRQuaternion, r as DepthPoint, s as WebXRVec3, t as ARPose } from "../ar-types-BckI1E-O.js";
 export { ARPose, ArPoseTuples, DepthPoint, DepthSample, RgbTuple, WebXRQuaternion, WebXRVec3 };

package/dist/types/geo-types.d.ts

@@ -1,2 +1,2 @@
-import { n as RawGpsSample, r as RefPointMarker, t as GpsCoord } from "../geo-types-SaPnIEUM.js";
+import { n as RawGpsSample, r as RefPointMarker, t as GpsCoord } from "../geo-types-DqiBzPO9.js";
 export { GpsCoord, RawGpsSample, RefPointMarker };

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
-import { a as RgbTuple, i as DepthSample, n as ArPoseTuples, o as WebXRQuaternion, r as DepthPoint, s as WebXRVec3, t as ARPose } from "../ar-types-Dan1MVTi.js";
-import { n as RawGpsSample, r as RefPointMarker, t as GpsCoord } from "../geo-types-SaPnIEUM.js";
+import { a as RgbTuple, i as DepthSample, n as ArPoseTuples, o as WebXRQuaternion, r as DepthPoint, s as WebXRVec3, t as ARPose } from "../ar-types-BckI1E-O.js";
+import { n as RawGpsSample, r as RefPointMarker, t as GpsCoord } from "../geo-types-DqiBzPO9.js";
 export { ARPose, ArPoseTuples, DepthPoint, DepthSample, GpsCoord, RawGpsSample, RefPointMarker, RgbTuple, WebXRQuaternion, WebXRVec3 };

package/dist/utils/concurrency.d.ts

@@ -1,2 +1,2 @@
-import { t as mapWithConcurrencyLimit } from "../concurrency-CO1FQvs3.js";
-export { mapWithConcurrencyLimit };
+import { n as mapWithConcurrencyLimit, t as forEachWithConcurrencyLimit } from "../concurrency-DqAlKX4j.js";
+export { forEachWithConcurrencyLimit, mapWithConcurrencyLimit };