gps-plus-slam-app-framework 1.0.0 → 1.0.6

package/dist/storage/file-system.js

@@ -1,15 +1,34 @@
 import { createLogger } from "../utils/logger.js";
 import { setFileSystemState } from "../sensors/permission-checker.js";
-import { createSession, getScenarioHandle, getScenariosRootHandle, initOpfsStorage, listScenarios, resetOpfsStorage, resetSessionHandles, writeAction as writeAction$1, writeFrame as writeFrame$1, writeSessionMetadata as writeSessionMetadata$1 } from "./opfs-storage.js";
+import { formatTimestamp } from "./file-system-utils.js";
+import { createSession, getAppRootHandle, initOpfsStorage, listSessions as listSessions$1, resetOpfsStorage, resetSessionHandles, setSessionHandles, writeAction as writeAction$1, writeFrame as writeFrame$1, writeSessionMetadata as writeSessionMetadata$1 } from "./opfs-storage.js";
 //#region ../src/storage/file-system.ts
+/**
+* File System Storage Module
+*
+* Facade over the OPFS storage module. Provides session lifecycle, write
+* operations, and backwards-compatible scenario management for the recorder.
+*
+* The core OPFS module (opfs-storage.ts) is scenario-free — it manages
+* flat sessions/{timestamp}/ directories. This module bridges the gap by
+* managing scenario directory handles for consumers that still need them
+* (recorder, ref-point loader, etc.) until those are migrated to
+* ScenarioWrappingStorageBackend in later iterations.
+*/
 const log = createLogger("Storage");
+let _currentScenarioName = null;
 let storageInitialized = false;
+let scenariosDir = null;
+let currentScenarioHandle = null;
 /**
 * Reset module state - exported for testing only
 * @internal
 */
 function resetStorageState() {
+	_currentScenarioName = null;
 	storageInitialized = false;
+	scenariosDir = null;
+	currentScenarioHandle = null;
 	resetOpfsStorage();
 }
 /**
@@ -18,25 +37,14 @@ function resetStorageState() {
 * Clears scenario/session names and OPFS session handles, but preserves
 * `storageInitialized` and the OPFS root so `initStorage()` doesn't need
 * to be called again.
-*
-* Used during soft reset for new recordings (Issue 4, 2026-02-06 user feedback).
 */
 function resetForNewSession() {
+	_currentScenarioName = null;
+	currentScenarioHandle = null;
 	resetSessionHandles();
 }
 /**
 * Verify that we have actual write access to a directory.
-*
-* This probes the directory by creating a test file, writing content,
-* and cleaning up. This catches cases where showDirectoryPicker grants
-* a handle but the underlying file system is read-only.
-*
-* User Feedback Issue #1: Even with mode: 'readwrite', Android can
-* return a handle where getFileHandle({create: true}) succeeds but
-* createWritable() fails with NoModificationAllowedError.
-*
-* @param dirHandle - Directory handle to verify
-* @returns Success status and optional error message
 */
 async function verifyWriteAccess(dirHandle) {
 	const testFilename = `.write-test-${Date.now()}`;
@@ -64,12 +72,27 @@ async function verifyWriteAccess(dirHandle) {
 		};
 	}
 }
+async function ensureScenariosDir() {
+	if (scenariosDir) return scenariosDir;
+	const appRoot = getAppRootHandle();
+	if (!appRoot) return null;
+	scenariosDir = await appRoot.getDirectoryHandle("scenarios", { create: true });
+	return scenariosDir;
+}
+/**
+* List all scenario names in OPFS storage.
+* Legacy: scenarios are managed by the recorder, not the framework.
+*/
+async function listScenarios() {
+	const dir = await ensureScenariosDir();
+	if (!dir) return [];
+	const scenarios = [];
+	for await (const entry of dir.values()) if (entry.kind === "directory") scenarios.push(entry.name);
+	return scenarios;
+}
 /**
 * Initialize storage using OPFS.
 *
-* This replaces the old showDirectoryPicker approach which failed on Android Chrome.
-* OPFS is automatically available and doesn't require user folder selection.
-*
 * @returns List of existing scenario folder names
 * @throws Error if OPFS is not supported
 */
@@ -81,6 +104,7 @@ async function initStorage() {
 			folderSelected: true,
 			writeVerified: true
 		});
+		await ensureScenariosDir();
 		const scenarios = await listScenarios();
 		log.info("OPFS storage initialized, found scenarios:", scenarios);
 		return scenarios;
@@ -96,24 +120,61 @@ async function initStorage() {
 	}
 }
 /**
-* Create or open a scenario folder, then create a new session folder.
+* Create a new session folder.
 *
-* Now uses OPFS backend instead of showDirectoryPicker.
+* When scenarioName is provided, creates under the scenario directory
+* (legacy scenario layout for the recorder). When omitted, creates under
+* the flat sessions/ directory.
 *
-* @param scenarioName - Name of the scenario
+* @param scenarioName - Optional name of the scenario (omit for flat layout)
 */
 async function startSession(scenarioName) {
 	if (!storageInitialized) throw new Error("Storage not initialized. Call initStorage first.");
-	const result = await createSession(scenarioName, /* @__PURE__ */ new Date());
-	result.scenarioName;
+	if (scenarioName) {
+		const dir = await ensureScenariosDir();
+		if (!dir) throw new Error("Failed to access scenarios directory.");
+		const scenarioHandle = await dir.getDirectoryHandle(scenarioName, { create: true });
+		currentScenarioHandle = scenarioHandle;
+		const sessionName = `recording-${formatTimestamp(/* @__PURE__ */ new Date())}`;
+		const sessionHandle = await scenarioHandle.getDirectoryHandle(sessionName, { create: true });
+		setSessionHandles(sessionHandle, await sessionHandle.getDirectoryHandle("actions", { create: true }), await sessionHandle.getDirectoryHandle("frames", { create: true }));
+		_currentScenarioName = scenarioName;
+		log.info("Session started:", `${scenarioName}/${sessionName}`);
+		return {
+			scenarioPath: scenarioName,
+			sessionPath: sessionName
+		};
+	}
+	const result = await createSession(/* @__PURE__ */ new Date());
+	_currentScenarioName = "";
 	result.sessionName;
-	log.info("Session started:", `${result.scenarioName}/${result.sessionName}`);
+	log.info("Session started:", result.sessionName);
 	return {
-		scenarioPath: result.scenarioName,
+		scenarioPath: "",
 		sessionPath: result.sessionName
 	};
 }
 /**
+* List all session names.
+* When scenarioName is provided, lists sessions under that scenario.
+* Otherwise lists flat sessions.
+*/
+async function listSessions(scenarioName) {
+	if (scenarioName) {
+		const dir = await ensureScenariosDir();
+		if (!dir) return [];
+		try {
+			const scenarioHandle = await dir.getDirectoryHandle(scenarioName);
+			const sessions = [];
+			for await (const entry of scenarioHandle.values()) if (entry.kind === "directory") sessions.push(entry.name);
+			return sessions;
+		} catch {
+			return [];
+		}
+	}
+	return listSessions$1();
+}
+/**
 * Write a Redux action to OPFS as a JSON file.
 */
 async function writeAction(action, index) {
@@ -127,82 +188,30 @@ async function writeFrame(blob, index) {
 }
 /**
 * Write session metadata (session.json) to OPFS.
-* Contains timing, counts, and user agent for the recording session.
 */
 async function writeSessionMetadata(metadata) {
 	await writeSessionMetadata$1(metadata);
 }
 /**
-* Type guard for reference point actions
-* Exported for testing
-*/
-function isRefPointAction(action) {
-	if (typeof action !== "object" || action === null) return false;
-	const obj = action;
-	const payload = obj.payload;
-	return obj.type === "recorder/markRefPoint" && typeof payload === "object" && payload !== null && !Array.isArray(payload);
-}
-/**
-* Parse action files from a session's actions directory
-*/
-async function parseSessionRefPoints(actionsDir, sessionName) {
-	const refPoints = [];
-	for await (const actionEntry of actionsDir.values()) {
-		if (actionEntry.kind !== "file" || !actionEntry.name.endsWith(".json")) continue;
-		const text = await (await (await actionsDir.getFileHandle(actionEntry.name)).getFile()).text();
-		try {
-			const action = JSON.parse(text);
-			if (isRefPointAction(action)) refPoints.push({
-				id: action.payload.id,
-				sessionName,
-				gpsPosition: action.payload.gpsPosition,
-				arPose: action.payload.arPose
-			});
-		} catch {}
-	}
-	return refPoints;
-}
-/**
-* Load existing reference points from a scenario (across all sessions).
-* Now uses OPFS storage backend.
-*/
-async function loadScenarioRefPoints(scenarioName) {
-	const scenariosRoot = getScenariosRootHandle();
-	if (!scenariosRoot) return [];
-	const refPoints = [];
-	try {
-		const scenarioHandle = await scenariosRoot.getDirectoryHandle(scenarioName);
-		for await (const sessionEntry of scenarioHandle.values()) {
-			if (sessionEntry.kind !== "directory") continue;
-			const sessionHandle = await scenarioHandle.getDirectoryHandle(sessionEntry.name);
-			let actionsDir;
-			try {
-				actionsDir = await sessionHandle.getDirectoryHandle("actions");
-			} catch {
-				continue;
-			}
-			const sessionRefPoints = await parseSessionRefPoints(actionsDir, sessionEntry.name);
-			refPoints.push(...sessionRefPoints);
-		}
-	} catch {}
-	return refPoints;
-}
-/**
 * Get the current scenario handle (for loading prior sessions).
-* Now delegates to OPFS storage backend.
+* Legacy: uses scenario directory layout.
 */
 function getCurrentScenarioHandle() {
-	return getScenarioHandle();
+	if (!_currentScenarioName) return null;
+	return currentScenarioHandle;
 }
 /**
 * Set the current scenario handle (when user selects a scenario).
-* With OPFS, we just store the name - the actual handle is retrieved when needed.
+* Legacy: uses scenario directory layout.
 */
 async function setCurrentScenario(scenarioName) {
-	const scenariosRoot = getScenariosRootHandle();
-	if (!scenariosRoot) return null;
+	const scenRoot = await ensureScenariosDir();
+	if (!scenRoot) return null;
 	try {
-		return await scenariosRoot.getDirectoryHandle(scenarioName);
+		const handle = await scenRoot.getDirectoryHandle(scenarioName);
+		_currentScenarioName = scenarioName;
+		currentScenarioHandle = handle;
+		return handle;
 	} catch {
 		log.warn("Scenario not found:", scenarioName);
 		return null;
@@ -210,20 +219,20 @@ async function setCurrentScenario(scenarioName) {
 }
 /**
 * Ensure a scenario directory exists in OPFS, creating it if necessary.
-* Used during OPFS recovery when the scenario directory was lost but ZIP
-* data is available for restoration.
-*
-* Unlike setCurrentScenario() which only reads, this creates on demand.
+* Legacy: used during OPFS recovery.
 */
 async function ensureScenarioDirectory(scenarioName) {
-	const scenariosRoot = getScenariosRootHandle();
-	if (!scenariosRoot) return null;
+	const scenRoot = await ensureScenariosDir();
+	if (!scenRoot) return null;
 	try {
-		return await scenariosRoot.getDirectoryHandle(scenarioName, { create: true });
+		const handle = await scenRoot.getDirectoryHandle(scenarioName, { create: true });
+		_currentScenarioName = scenarioName;
+		currentScenarioHandle = handle;
+		return handle;
 	} catch (err) {
 		log.error("Failed to create scenario directory:", err);
 		return null;
 	}
 }
 //#endregion
-export { ensureScenarioDirectory, getCurrentScenarioHandle, initStorage, isRefPointAction, loadScenarioRefPoints, resetForNewSession, resetStorageState, setCurrentScenario, startSession, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata };
+export { ensureScenarioDirectory, getCurrentScenarioHandle, initStorage, listSessions, resetForNewSession, resetStorageState, setCurrentScenario, startSession, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata };

package/dist/storage/index.d.ts

@@ -1,11 +1,9 @@
-import { a as getScenarioHandle, c as initOpfsStorage, d as resetOpfsStorage, f as resetSessionHandles, h as writeSessionMetadata$1, i as createSession, n as SessionMetadata, o as getScenariosRootHandle, r as checkStorageQuota, s as getSessionHandle, t as CreateSessionResult, u as listSessions } from "../opfs-storage-ChOzF_Wp.js";
-import { t as StorageBackend } from "../storage-backend-BcEItnFr.js";
-import { n as RefPointImportResult, r as importRefPointsFromFolder, t as ImportedRefPoint } from "../ref-point-importer-B_wn5ABk.js";
-import { a as flattenRefPointsToMarks, c as loadRefPoint, i as averageGpsPerRefPoint, l as saveRefPointObservation, n as RefPointMark, o as listRefPointIds, r as RefPointObservation, s as loadAllRefPoints, t as RefPointDefinition } from "../ref-point-loader-Pt1smgHS.js";
-import { a as ZipActionEntry, c as loadSessionMetadata, i as RecordedAction, l as loadSessionMetadataFromBlob, n as GpsPathCoord, o as loadActionsFromZip, r as MAX_ACTION_FILE_SIZE, s as loadGpsPathFromBlob, t as Entry, u as readZipEntries } from "../zip-reader-D7pkpX8K.js";
-import { t as NullStorageBackend } from "../null-storage-backend-CsWvQwN8.js";
-import { t as OpfsStorageBackend } from "../opfs-storage-backend-CVcmfJHN.js";
-import { a as initStorage, c as resetForNewSession, d as startSession, f as verifyWriteAccess, h as writeSessionMetadata, i as getCurrentScenarioHandle, l as resetStorageState, m as writeFrame, n as WriteAccessResult, o as isRefPointAction, p as writeAction, s as loadScenarioRefPoints, u as setCurrentScenario } from "../file-system-BsQgYCU3.js";
-import { n as formatFrameFilename, r as formatTimestamp, t as formatActionFilename } from "../file-system-utils-5cWO8Xyv.js";
-import { a as syncToExternalZip, i as exportSessionAsZip, n as downloadZip, r as exportAndDownloadSession, t as ZipExportResult } from "../zip-export-Rtpi75JJ.js";
-export { type CreateSessionResult, type Entry, type GpsPathCoord, type ImportedRefPoint, MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, type RecordedAction, type RefPointDefinition, type RefPointImportResult, type RefPointMark, type RefPointObservation, type SessionMetadata, type StorageBackend, type WriteAccessResult, type ZipActionEntry, type ZipExportResult, averageGpsPerRefPoint, checkStorageQuota, createSession, downloadZip, exportAndDownloadSession, exportSessionAsZip, flattenRefPointsToMarks, formatActionFilename, formatFrameFilename, formatTimestamp, getCurrentScenarioHandle, getScenarioHandle, getScenariosRootHandle, getSessionHandle, importRefPointsFromFolder, initOpfsStorage, initStorage, isRefPointAction, listRefPointIds, listSessions, loadActionsFromZip, loadAllRefPoints, loadGpsPathFromBlob, loadRefPoint, loadScenarioRefPoints, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetForNewSession, resetOpfsStorage, resetSessionHandles, resetStorageState, saveRefPointObservation, 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$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-Dlq1I_Gb.js";
+import { n as StorageBackend, t as CreateSessionResult } from "../storage-backend-yVnuWGTr.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-KgJEXbca.js";
+import { t as NullStorageBackend } from "../null-storage-backend-C0TiwwzQ.js";
+import { t as OpfsStorageBackend } from "../opfs-storage-backend-Gt3rd76D.js";
+import { a as listSessions$1, c as setCurrentScenario, d as writeAction, f as writeFrame, i as initStorage, l as startSession, n as ensureScenarioDirectory, o as resetForNewSession, p as writeSessionMetadata, r as getCurrentScenarioHandle, s as resetStorageState, t as WriteAccessResult, u as verifyWriteAccess } from "../file-system-DD5TczSO.js";
+import { n as formatFrameFilename, r as formatTimestamp, t as formatActionFilename } from "../file-system-utils-BH8FdyIu.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-BjrQPv0X.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 };

package/dist/storage/index.js

@@ -1,10 +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 { checkStorageQuota, createSession, getScenarioHandle, getScenariosRootHandle, getSessionHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, writeSessionMetadata as writeSessionMetadata$1 } from "./opfs-storage.js";
-import { getCurrentScenarioHandle, initStorage, isRefPointAction, loadScenarioRefPoints, resetForNewSession, resetStorageState, setCurrentScenario, startSession, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata } from "./file-system.js";
-import { OpfsStorageBackend } from "./opfs-storage-backend.js";
-import { MAX_ACTION_FILE_SIZE, loadActionsFromZip, loadGpsPathFromBlob, loadSessionMetadata, loadSessionMetadataFromBlob, readZipEntries } from "./zip-reader.js";
 import { NullStorageBackend } from "./null-storage-backend.js";
-import { importRefPointsFromFolder } from "./ref-point-importer.js";
-import { averageGpsPerRefPoint, flattenRefPointsToMarks, listRefPointIds, loadAllRefPoints, loadRefPoint, saveRefPointObservation } from "./ref-point-loader.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 { OpfsStorageBackend } from "./opfs-storage-backend.js";
 import { downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip } from "./zip-export.js";
-export { MAX_ACTION_FILE_SIZE, NullStorageBackend, OpfsStorageBackend, averageGpsPerRefPoint, checkStorageQuota, createSession, downloadZip, exportAndDownloadSession, exportSessionAsZip, flattenRefPointsToMarks, formatActionFilename, formatFrameFilename, formatTimestamp, getCurrentScenarioHandle, getScenarioHandle, getScenariosRootHandle, getSessionHandle, importRefPointsFromFolder, initOpfsStorage, initStorage, isRefPointAction, listRefPointIds, listSessions, loadActionsFromZip, loadAllRefPoints, loadGpsPathFromBlob, loadRefPoint, loadScenarioRefPoints, loadSessionMetadataFromBlob, loadSessionMetadata as loadSessionMetadataFromZip, readZipEntries, resetForNewSession, resetOpfsStorage, resetSessionHandles, resetStorageState, saveRefPointObservation, setCurrentScenario, startSession as startStorageSession, syncToExternalZip, verifyWriteAccess, writeAction, writeFrame, writeSessionMetadata as writeSessionMeta, writeSessionMetadata$1 as writeSessionMetadata };
+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 };

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

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

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

@@ -1,5 +1,12 @@
+import { formatTimestamp } from "./file-system-utils.js";
 //#region ../src/storage/null-storage-backend.ts
 var NullStorageBackend = class {
+	createSession(timestamp, _contextTag) {
+		return Promise.resolve({ sessionName: `recording-${formatTimestamp(timestamp)}` });
+	}
+	listSessions() {
+		return Promise.resolve([]);
+	}
 	async writeAction(_action, _index) {}
 	async writeFrame(_blob, _index) {}
 	async writeSessionMetadata(_metadata) {}

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

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

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

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

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

@@ -1,2 +1,2 @@
-import { a as getScenarioHandle, c as initOpfsStorage, d as resetOpfsStorage, f as resetSessionHandles, h as writeSessionMetadata, i as createSession, l as listScenarios, m as writeFrame, n as SessionMetadata, o as getScenariosRootHandle, p as writeAction, r as checkStorageQuota, s as getSessionHandle, t as CreateSessionResult, u as listSessions } from "../opfs-storage-ChOzF_Wp.js";
-export { CreateSessionResult, SessionMetadata, checkStorageQuota, createSession, getScenarioHandle, getScenariosRootHandle, getSessionHandle, initOpfsStorage, listScenarios, listSessions, resetOpfsStorage, resetSessionHandles, writeAction, writeFrame, writeSessionMetadata };
+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-Dlq1I_Gb.js";
+export { CreateSessionResult, SessionMetadata, checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, setSessionHandles, writeAction, writeFrame, writeSessionMetadata };

package/dist/storage/opfs-storage.js

@@ -8,26 +8,26 @@ import { formatActionFilename, formatFrameFilename, formatTimestamp } from "./fi
 * OPFS works consistently on Desktop Chrome, Android Chrome, and iOS Safari,
 * unlike showDirectoryPicker which has write restrictions on Android.
 *
-* Directory structure:
-* /gps-recorder/
-*   └── scenarios/
-*       ├── {scenario-name}/
-*       │   ├── recording-YYYY-MM-DD_HH-MM-SSutc/
-*       │   │   ├── session.json
-*       │   │   ├── actions/
-*       │   │   │   ├── 000001.json
-*       │   │   │   └── ...
-*       │   │   └── frames/
-*       │   │       ├── frame-000001.jpg
-*       │   │       └── ...
-*       │   └── ...
+* Directory structure (flat sessions — no scenario hierarchy):
+* /gps-plus-slam/
+*   └── sessions/
+*       ├── recording-YYYY-MM-DD_HH-MM-SSutc/
+*       │   ├── session.json
+*       │   ├── actions/
+*       │   │   ├── 000001.json
+*       │   │   └── ...
+*       │   └── frames/
+*       │       ├── frame-000001.jpg
+*       │       └── ...
 *       └── ...
+*
+* Scenario grouping (scenarios/{name}/recording-…) is a recorder-only concern,
+* handled by ScenarioWrappingStorageBackend in the recorder app.
 */
 const log = createLogger("OPFS");
 let opfsRoot = null;
-let gpsRecorderDir = null;
-let scenariosDir = null;
-let currentScenarioHandle = null;
+let gpsPlusSlamDir = null;
+let sessionsDir = null;
 let currentSessionHandle = null;
 let actionsHandle = null;
 let framesHandle = null;
@@ -37,9 +37,8 @@ let framesHandle = null;
 */
 function resetOpfsStorage() {
 	opfsRoot = null;
-	gpsRecorderDir = null;
-	scenariosDir = null;
-	currentScenarioHandle = null;
+	gpsPlusSlamDir = null;
+	sessionsDir = null;
 	currentSessionHandle = null;
 	actionsHandle = null;
 	framesHandle = null;
@@ -47,14 +46,11 @@ function resetOpfsStorage() {
 /**
 * Reset session-level handles only.
 *
-* Preserves opfsRoot/gpsRecorderDir/scenariosDir (OPFS stays initialized)
-* but clears current scenario/session/actions/frames handles so a new
-* session can be started fresh.
-*
-* Used during soft reset for new recordings (Issue 4, 2026-02-06 user feedback).
+* Preserves opfsRoot/gpsPlusSlamDir/sessionsDir (OPFS stays initialized)
+* but clears current session/actions/frames handles so a new session can
+* be started fresh.
 */
 function resetSessionHandles() {
-	currentScenarioHandle = null;
 	currentSessionHandle = null;
 	actionsHandle = null;
 	framesHandle = null;
@@ -63,8 +59,8 @@ function resetSessionHandles() {
 * Initialize OPFS storage by creating the required directory structure.
 *
 * Creates:
-* - /gps-recorder/
-* - /gps-recorder/scenarios/
+* - /gps-plus-slam/
+* - /gps-plus-slam/sessions/
 *
 * This is idempotent - calling multiple times is safe.
 *
@@ -74,65 +70,74 @@ async function initOpfsStorage() {
 	if (typeof navigator === "undefined" || !navigator.storage || typeof navigator.storage.getDirectory !== "function") throw new Error("OPFS (Origin Private File System) is not supported in this browser. Please use Chrome 86+, Safari 15.2+, or Firefox 111+.");
 	opfsRoot = await navigator.storage.getDirectory();
 	log.info("OPFS root obtained");
-	gpsRecorderDir = await opfsRoot.getDirectoryHandle("gps-recorder", { create: true });
-	scenariosDir = await gpsRecorderDir.getDirectoryHandle("scenarios", { create: true });
+	gpsPlusSlamDir = await opfsRoot.getDirectoryHandle("gps-plus-slam", { create: true });
+	sessionsDir = await gpsPlusSlamDir.getDirectoryHandle("sessions", { create: true });
 	log.info("OPFS storage initialized");
 }
 /**
-* Create a new recording session within a scenario.
+* Get the sessions root directory handle.
+* Used by consumers that need direct OPFS access (e.g. ZIP export).
+*/
+function getSessionsRootHandle() {
+	return sessionsDir;
+}
+/**
+* Get the app root directory handle (gps-plus-slam/).
+* Used by consumers that need to create additional directories alongside sessions/.
+*/
+function getAppRootHandle() {
+	return gpsPlusSlamDir;
+}
+/**
+* Create a new recording session.
 *
 * Creates the directory structure:
-* - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/
-* - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/actions/
-* - /gps-recorder/scenarios/{scenarioName}/recording-{timestamp}/frames/
+* - /gps-plus-slam/sessions/recording-{timestamp}/
+* - /gps-plus-slam/sessions/recording-{timestamp}/actions/
+* - /gps-plus-slam/sessions/recording-{timestamp}/frames/
 *
-* @param scenarioName - Name of the scenario (creates if doesn't exist)
 * @param timestamp - Session start time (used for folder naming)
+* @param _contextTag - Opaque tag; not used by the flat layout but accepted
+*   for interface compatibility with wrapping backends
 * @returns Session information
 * @throws Error if storage not initialized
 */
-async function createSession(scenarioName, timestamp) {
-	if (!scenariosDir) throw new Error("OPFS storage not initialized. Call initOpfsStorage first.");
-	currentScenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName, { create: true });
+async function createSession(timestamp, _contextTag) {
+	if (!sessionsDir) throw new Error("OPFS storage not initialized. Call initOpfsStorage first.");
 	const sessionName = `recording-${formatTimestamp(timestamp)}`;
-	currentSessionHandle = await currentScenarioHandle.getDirectoryHandle(sessionName, { create: true });
+	currentSessionHandle = await sessionsDir.getDirectoryHandle(sessionName, { create: true });
 	actionsHandle = await currentSessionHandle.getDirectoryHandle("actions", { create: true });
 	framesHandle = await currentSessionHandle.getDirectoryHandle("frames", { create: true });
-	log.info("Session created:", `${scenarioName}/${sessionName}`);
-	return {
-		scenarioName,
-		sessionName
-	};
+	log.info("Session created:", sessionName);
+	return { sessionName };
 }
 /**
 * Get the current session directory handle.
-* Useful for test assertions.
 * @internal
 */
 function getSessionHandle() {
 	return currentSessionHandle;
 }
 /**
-* Get the current scenario directory handle.
-*/
-function getScenarioHandle() {
-	return currentScenarioHandle;
-}
-/**
-* Get the scenarios root directory handle.
-* Used for loading reference points across scenarios.
+* 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.
+*
+* @internal
 */
-function getScenariosRootHandle() {
-	return scenariosDir;
+function setSessionHandles(session, actions, frames) {
+	currentSessionHandle = session;
+	actionsHandle = actions;
+	framesHandle = frames;
 }
 /**
 * Safely write data to a file handle with proper cleanup.
 *
 * Uses try/finally to ensure the writable stream is always cleaned up,
 * calling abort() on errors to prevent resource leaks and file locks.
-*
-* @param fileHandle - The file handle to write to
-* @param data - The data to write (string or Blob)
 */
 async function safeWriteToFile(fileHandle, data) {
 	const writable = await fileHandle.createWritable();
@@ -188,40 +193,19 @@ async function writeSessionMetadata(metadata) {
 	log.info("Session metadata written");
 }
 /**
-* List all scenario names in OPFS storage.
-*
-* @returns Array of scenario folder names
-*/
-async function listScenarios() {
-	if (!scenariosDir) return [];
-	const scenarios = [];
-	for await (const entry of scenariosDir.values()) if (entry.kind === "directory") scenarios.push(entry.name);
-	return scenarios;
-}
-/**
-* List all session names within a scenario.
+* List all session names in OPFS storage.
 *
-* @param scenarioName - Name of the scenario
 * @returns Array of session folder names
 */
-async function listSessions(scenarioName) {
-	if (!scenariosDir) return [];
-	try {
-		const scenarioHandle = await scenariosDir.getDirectoryHandle(scenarioName);
-		const sessions = [];
-		for await (const entry of scenarioHandle.values()) if (entry.kind === "directory") sessions.push(entry.name);
-		return sessions;
-	} catch {
-		return [];
-	}
+async function listSessions() {
+	if (!sessionsDir) return [];
+	const sessions = [];
+	for await (const entry of sessionsDir.values()) if (entry.kind === "directory") sessions.push(entry.name);
+	return sessions;
 }
 /**
 * Check storage quota.
 *
-* Note: Prefer calling `initOpfsStorage()` before this function to ensure
-* the Storage API is available. If the Storage Manager API is not supported,
-* returns a safe default of `{ available: 0, used: 0 }`.
-*
 * @returns Available and used storage in bytes
 */
 async function checkStorageQuota() {
@@ -239,4 +223,4 @@ async function checkStorageQuota() {
 	};
 }
 //#endregion
-export { checkStorageQuota, createSession, getScenarioHandle, getScenariosRootHandle, getSessionHandle, initOpfsStorage, listScenarios, listSessions, resetOpfsStorage, resetSessionHandles, writeAction, writeFrame, writeSessionMetadata };
+export { checkStorageQuota, createSession, getAppRootHandle, getSessionHandle, getSessionsRootHandle, initOpfsStorage, listSessions, resetOpfsStorage, resetSessionHandles, setSessionHandles, writeAction, writeFrame, writeSessionMetadata };

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

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

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

@@ -1,2 +1,2 @@
-import { a as syncToExternalZip, i as exportSessionAsZip, n as downloadZip, r as exportAndDownloadSession, t as ZipExportResult } from "../zip-export-Rtpi75JJ.js";
-export { ZipExportResult, downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };
+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-BjrQPv0X.js";
+export { ExportSessionAsZipOptions, ZipContributorAddFile, ZipExportContributor, ZipExportResult, downloadZip, exportAndDownloadSession, exportSessionAsZip, syncToExternalZip };