@openfairygui/backend 0.2.0-alpha.37 → 0.2.0-alpha.38

package/README.md

@@ -13,7 +13,7 @@ It owns:
 - coordinated but non-atomic save semantics
 - browser-safe project sessions
 - browser-safe async project storage adapter
-- adapter-backed file sessions and backend-local advisory locking
+- adapter-backed file sessions and backend-local session locking
 - capability discovery
 - transport-neutral bootstrap
 
@@ -35,13 +35,20 @@ It also does **not** implement MCP or any transport-specific wire protocol.
 The root `@openfairygui/backend` entrypoint is browser-safe: pure authoring sessions can run in memory,
 and browser editors can inject an async storage adapter for OPFS, IndexedDB, ZIP-backed virtual filesystems,
 or File System Access API bridges. Storage adapters must implement `unlink()` so resource rename/move/remove
-can clean up stale source files. The default Node filesystem/runtime lives under `@openfairygui/backend/node`.
-File-backed `openSession` hydrates primary resource bytes so browser-safe transactions can rename/move
+can clean up stale source files. Existing browser projects use a session-lifetime Web Lock: a live peer tab
+receives `lock_conflict`, while reload or abrupt document termination releases ownership without leaving a
+persistent `.openfairygui.backend.lock` marker. When Web Locks are unavailable, the storage adapter must
+provide `acquireSessionLock()` with the same atomic cross-context and owner-termination semantics. The default
+Node filesystem/runtime lives under `@openfairygui/backend/node` and retains its advisory lock file behavior.
+Adapter-backed `openSession` hydrates primary resource bytes so browser-safe transactions can rename/move
 assets or add/replace/remove binary resources. `saveSession` writes replacement bytes before it removes
 stale source files, preserving the prior file when a write fails.
 It also compares the source project with a UAM round trip through `ProjectWriter`; sessions with
 unrepresented persisted properties expose `uamFidelity: 'unsupported'`, and write attempts fail with
-`uam_fidelity_unsupported`. Transactions, saves, and materialization are serialized per session.
+`uam_fidelity_unsupported`. Existing projects in browser storage must be opened through this path by
+injecting `createBackendStorageFileSystem(storage)` into `BackendRuntime`; `openProjectSession` is only
+for sessions whose supplied UAM project is authoritative. Transactions, saves, and materialization are
+serialized per session.
 
 ## Relationship to other packages
 
@@ -51,7 +58,7 @@ unrepresented persisted properties expose `uamFidelity: 'unsupported'`, and writ
 
 ## Example
 
-Browser-safe project session:
+Browser-safe authoritative UAM project session:
 
 ```ts
 import { BackendRuntime } from '@openfairygui/backend';
@@ -67,7 +74,7 @@ const applied = await runtime.applyTransaction({
 });
 ```
 
-Browser-safe project session with injected storage:
+Open an existing project from browser async storage with source-fidelity checks:
 
 ```ts
 import { BackendRuntime, createBackendStorageFileSystem } from '@openfairygui/backend';
@@ -81,15 +88,21 @@ const fileSystem = createBackendStorageFileSystem({
 	async readdir(dirPath) { return storage.readdir(dirPath); },
 	async exists(filePath) { return storage.exists(filePath); },
 	async unlink(filePath) { await storage.remove(filePath); },
+	async rmdir(dirPath) { await storage.rmdir(dirPath); },
 });
 
+const runtime = new BackendRuntime({ fileSystem });
+const opened = await runtime.openSession({ projectPath: 'ExistingProject' });
+if (!opened.ok) throw new Error(opened.error.message);
+```
+
+Materialize an authoritative UAM project into browser async storage:
+
+```ts
 const runtime = new BackendRuntime();
 const opened = runtime.openProjectSession({
 	project: uamProject,
-	storage: {
-		fileSystem,
-		fairyPath: 'Project.fairy',
-	},
+	storage: { fileSystem, fairyPath: 'NewProject/Project.fairy' },
 });
 if (!opened.ok) throw new Error(opened.error.message);
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runtime = require("./runtime-CQQmzsxV.cjs");
+const require_runtime = require("./runtime-BtavZ2ku.cjs");
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {
@@ -17,6 +17,42 @@ function createPathError(code, message) {
 	error.code = code;
 	return error;
 }
+function getWebLockManager() {
+	if (typeof navigator === "undefined") return null;
+	const lockManager = navigator.locks;
+	return lockManager && typeof lockManager.request === "function" ? lockManager : null;
+}
+function acquireWebSessionLock(lockManager, lockName) {
+	return new Promise((resolve, reject) => {
+		let releasePlatformLock = () => void 0;
+		const held = new Promise((release) => {
+			releasePlatformLock = release;
+		});
+		lockManager.request(lockName, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, async (lock) => {
+			if (!lock) {
+				reject(createPathError("EEXIST", `Browser session lock is already held: ${lockName}`));
+				return;
+			}
+			let released = false;
+			resolve({
+				writeMetadata() {
+					return Promise.resolve();
+				},
+				release() {
+					if (!released) {
+						released = true;
+						releasePlatformLock();
+					}
+					return Promise.resolve();
+				}
+			});
+			await held;
+		}).catch(reject);
+	});
+}
 function normalizeStoragePath(value) {
 	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
 	const absolute = normalized.startsWith("/");
@@ -73,7 +109,6 @@ async function inferStat(storage, filePath) {
 function createBackendStorageFileSystem(storage) {
 	if (typeof storage.unlink !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide unlink() for project resource lifecycle writes.");
 	if (typeof storage.rmdir !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide rmdir() for project resource folder lifecycle writes.");
-	const lockedPaths = /* @__PURE__ */ new Set();
 	const fileSystem = {
 		stat(filePath) {
 			return inferStat(storage, fileSystem.resolve(filePath));
@@ -109,28 +144,15 @@ function createBackendStorageFileSystem(storage) {
 			const resolved = fileSystem.resolve(filePath);
 			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
 		},
-		async openExclusive(filePath) {
-			const resolved = fileSystem.resolve(filePath);
-			if (storage.openExclusive) return storage.openExclusive(resolved);
-			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) throw createPathError("EEXIST", `Storage path already exists: ${resolved}`);
-			lockedPaths.add(resolved);
-			let closed = false;
-			return {
-				async writeFile(content) {
-					if (closed) throw createPathError("EBADF", `Storage lock handle is closed: ${resolved}`);
-					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
-					await storage.writeFile(resolved, content);
-				},
-				async close() {
-					closed = true;
-					lockedPaths.delete(resolved);
-				}
-			};
+		async acquireSessionLock(lockPath) {
+			const resolved = fileSystem.resolve(lockPath);
+			if (storage.acquireSessionLock) return storage.acquireSessionLock(resolved);
+			const lockManager = getWebLockManager();
+			if (!lockManager) throw createPathError("ENOTSUP", "Browser openSession requires Web Locks or BackendAsyncStorageAdapter.acquireSessionLock().");
+			return acquireWebSessionLock(lockManager, `@openfairygui/backend:${resolved}`);
 		},
 		unlink(filePath) {
-			const resolved = fileSystem.resolve(filePath);
-			lockedPaths.delete(resolved);
-			return storage.unlink(resolved);
+			return storage.unlink(fileSystem.resolve(filePath));
 		},
 		rmdir(dirPath) {
 			return storage.rmdir(fileSystem.resolve(dirPath));

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { $ as BACKEND_COMPATIBILITY_POLICY, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobNotFoundError, D as BackendProjectSessionStorage, E as BackendJobStatus, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendResult, P as EventCursorInvalidError, Q as BACKEND_CAPABILITY_SCHEMA_VERSION, R as GetJobInput, S as BackendJobNotCancellableError, T as BackendJobSnapshot, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as UamFidelityUnsupportedError, _ as BackendHostAdapter, a as BackendCacheEntry, b as BackendJobListSnapshot, c as BackendCapabilityManifest, d as BackendEvent, et as BACKEND_CONTRACT_VERSION, f as BackendEventKind, g as BackendFileSystem, h as BackendFileStat, i as BackendArtifactBridgeCapability, it as BackendStage, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendCapabilityUnavailableError, m as BackendFileHandle, n as AdvisoryLockConflictError, nt as BackendMessage, o as BackendCacheSnapshot, p as BackendFailure, q as SavePartialFailureError, r as ApplySessionTransactionInput, rt as BackendResponseMeta, s as BackendCapabilities, t as BackendRuntime, tt as BackendDiagnostic, u as BackendError, v as BackendJobErrors, w as BackendJobProgress, x as BackendJobListStatusFilter, y as BackendJobKind, z as InProcessLockConflictError } from "./runtime-Wu6vGZ-j.cjs";
+import { $ as BACKEND_COMPATIBILITY_POLICY, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntimeOptions, P as EventCursorInvalidError, Q as BACKEND_CAPABILITY_SCHEMA_VERSION, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as UamFidelityUnsupportedError, _ as BackendJobErrors, a as BackendCacheEntry, b as BackendJobListStatusFilter, c as BackendCapabilityManifest, d as BackendEvent, et as BACKEND_CONTRACT_VERSION, f as BackendEventKind, g as BackendHostAdapter, h as BackendFileSystem, i as BackendArtifactBridgeCapability, it as BackendStage, j as BackendSuccess, k as BackendSessionLock, l as BackendCapabilityUnavailableError, m as BackendFileStat, n as AdvisoryLockConflictError, nt as BackendMessage, o as BackendCacheSnapshot, p as BackendFailure, q as SavePartialFailureError, r as ApplySessionTransactionInput, rt as BackendResponseMeta, s as BackendCapabilities, t as BackendRuntime, tt as BackendDiagnostic, u as BackendError, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-B7rLrkcR.cjs";
 import { FileSystem } from "@openfairygui/core/project-io";
 
 //#region src/storage.d.ts
@@ -20,8 +20,13 @@ interface BackendAsyncStorageAdapter {
   readdir(dirPath: string): Promise<string[]>;
   exists?(filePath: string): Promise<boolean>;
   stat?(filePath: string): Promise<BackendStorageStatLike>;
+  /** Stable cross-context path identity; also scopes the default Web Lock name. */
   resolvePath?(filePath: string): Promise<string>;
-  openExclusive?(filePath: string): Promise<BackendFileHandle>;
+  /**
+   * Optional replacement for Web Locks. Acquisition must be atomic across browser contexts, remain held
+   * until release(), and recover automatically when the owning document terminates.
+   */
+  acquireSessionLock?(lockPath: string): Promise<BackendSessionLock>;
   unlink(filePath: string): Promise<void>;
   rmdir(dirPath: string): Promise<void>;
   join?(...paths: string[]): string;
@@ -31,4 +36,4 @@ interface BackendAsyncStorageAdapter {
 type BackendStorageFileSystem = BackendFileSystem & FileSystem;
 declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
 //#endregion
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, createBackendStorageFileSystem };
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, createBackendStorageFileSystem };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as BACKEND_COMPATIBILITY_POLICY, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobNotFoundError, D as BackendProjectSessionStorage, E as BackendJobStatus, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendResult, P as EventCursorInvalidError, Q as BACKEND_CAPABILITY_SCHEMA_VERSION, R as GetJobInput, S as BackendJobNotCancellableError, T as BackendJobSnapshot, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as UamFidelityUnsupportedError, _ as BackendHostAdapter, a as BackendCacheEntry, b as BackendJobListSnapshot, c as BackendCapabilityManifest, d as BackendEvent, et as BACKEND_CONTRACT_VERSION, f as BackendEventKind, g as BackendFileSystem, h as BackendFileStat, i as BackendArtifactBridgeCapability, it as BackendStage, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendCapabilityUnavailableError, m as BackendFileHandle, n as AdvisoryLockConflictError, nt as BackendMessage, o as BackendCacheSnapshot, p as BackendFailure, q as SavePartialFailureError, r as ApplySessionTransactionInput, rt as BackendResponseMeta, s as BackendCapabilities, t as BackendRuntime, tt as BackendDiagnostic, u as BackendError, v as BackendJobErrors, w as BackendJobProgress, x as BackendJobListStatusFilter, y as BackendJobKind, z as InProcessLockConflictError } from "./runtime-BQOEw22M.mjs";
+import { $ as BACKEND_COMPATIBILITY_POLICY, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntimeOptions, P as EventCursorInvalidError, Q as BACKEND_CAPABILITY_SCHEMA_VERSION, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as UamFidelityUnsupportedError, _ as BackendJobErrors, a as BackendCacheEntry, b as BackendJobListStatusFilter, c as BackendCapabilityManifest, d as BackendEvent, et as BACKEND_CONTRACT_VERSION, f as BackendEventKind, g as BackendHostAdapter, h as BackendFileSystem, i as BackendArtifactBridgeCapability, it as BackendStage, j as BackendSuccess, k as BackendSessionLock, l as BackendCapabilityUnavailableError, m as BackendFileStat, n as AdvisoryLockConflictError, nt as BackendMessage, o as BackendCacheSnapshot, p as BackendFailure, q as SavePartialFailureError, r as ApplySessionTransactionInput, rt as BackendResponseMeta, s as BackendCapabilities, t as BackendRuntime, tt as BackendDiagnostic, u as BackendError, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-CJnoedTA.mjs";
 import { FileSystem } from "@openfairygui/core/project-io";
 
 //#region src/storage.d.ts
@@ -20,8 +20,13 @@ interface BackendAsyncStorageAdapter {
   readdir(dirPath: string): Promise<string[]>;
   exists?(filePath: string): Promise<boolean>;
   stat?(filePath: string): Promise<BackendStorageStatLike>;
+  /** Stable cross-context path identity; also scopes the default Web Lock name. */
   resolvePath?(filePath: string): Promise<string>;
-  openExclusive?(filePath: string): Promise<BackendFileHandle>;
+  /**
+   * Optional replacement for Web Locks. Acquisition must be atomic across browser contexts, remain held
+   * until release(), and recover automatically when the owning document terminates.
+   */
+  acquireSessionLock?(lockPath: string): Promise<BackendSessionLock>;
   unlink(filePath: string): Promise<void>;
   rmdir(dirPath: string): Promise<void>;
   join?(...paths: string[]): string;
@@ -31,4 +36,4 @@ interface BackendAsyncStorageAdapter {
 type BackendStorageFileSystem = BackendFileSystem & FileSystem;
 declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
 //#endregion
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, createBackendStorageFileSystem };
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, type UamFidelityUnsupportedError, createBackendStorageFileSystem };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-DtCn0Y44.mjs";
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-CNTJCi6P.mjs";
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {
@@ -16,6 +16,42 @@ function createPathError(code, message) {
 	error.code = code;
 	return error;
 }
+function getWebLockManager() {
+	if (typeof navigator === "undefined") return null;
+	const lockManager = navigator.locks;
+	return lockManager && typeof lockManager.request === "function" ? lockManager : null;
+}
+function acquireWebSessionLock(lockManager, lockName) {
+	return new Promise((resolve, reject) => {
+		let releasePlatformLock = () => void 0;
+		const held = new Promise((release) => {
+			releasePlatformLock = release;
+		});
+		lockManager.request(lockName, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, async (lock) => {
+			if (!lock) {
+				reject(createPathError("EEXIST", `Browser session lock is already held: ${lockName}`));
+				return;
+			}
+			let released = false;
+			resolve({
+				writeMetadata() {
+					return Promise.resolve();
+				},
+				release() {
+					if (!released) {
+						released = true;
+						releasePlatformLock();
+					}
+					return Promise.resolve();
+				}
+			});
+			await held;
+		}).catch(reject);
+	});
+}
 function normalizeStoragePath(value) {
 	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
 	const absolute = normalized.startsWith("/");
@@ -72,7 +108,6 @@ async function inferStat(storage, filePath) {
 function createBackendStorageFileSystem(storage) {
 	if (typeof storage.unlink !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide unlink() for project resource lifecycle writes.");
 	if (typeof storage.rmdir !== "function") throw createPathError("ENOTSUP", "Storage adapter must provide rmdir() for project resource folder lifecycle writes.");
-	const lockedPaths = /* @__PURE__ */ new Set();
 	const fileSystem = {
 		stat(filePath) {
 			return inferStat(storage, fileSystem.resolve(filePath));
@@ -108,28 +143,15 @@ function createBackendStorageFileSystem(storage) {
 			const resolved = fileSystem.resolve(filePath);
 			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
 		},
-		async openExclusive(filePath) {
-			const resolved = fileSystem.resolve(filePath);
-			if (storage.openExclusive) return storage.openExclusive(resolved);
-			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) throw createPathError("EEXIST", `Storage path already exists: ${resolved}`);
-			lockedPaths.add(resolved);
-			let closed = false;
-			return {
-				async writeFile(content) {
-					if (closed) throw createPathError("EBADF", `Storage lock handle is closed: ${resolved}`);
-					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
-					await storage.writeFile(resolved, content);
-				},
-				async close() {
-					closed = true;
-					lockedPaths.delete(resolved);
-				}
-			};
+		async acquireSessionLock(lockPath) {
+			const resolved = fileSystem.resolve(lockPath);
+			if (storage.acquireSessionLock) return storage.acquireSessionLock(resolved);
+			const lockManager = getWebLockManager();
+			if (!lockManager) throw createPathError("ENOTSUP", "Browser openSession requires Web Locks or BackendAsyncStorageAdapter.acquireSessionLock().");
+			return acquireWebSessionLock(lockManager, `@openfairygui/backend:${resolved}`);
 		},
 		unlink(filePath) {
-			const resolved = fileSystem.resolve(filePath);
-			lockedPaths.delete(resolved);
-			return storage.unlink(resolved);
+			return storage.unlink(fileSystem.resolve(filePath));
 		},
 		rmdir(dirPath) {
 			return storage.rmdir(fileSystem.resolve(dirPath));

package/dist/node.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_runtime = require("./runtime-CQQmzsxV.cjs");
+const require_runtime = require("./runtime-BtavZ2ku.cjs");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_path = require("node:path");
@@ -58,14 +58,27 @@ function createNodeBackendFileSystem() {
 				return node_path.default.resolve(filePath);
 			}
 		},
-		async openExclusive(filePath) {
+		async acquireSessionLock(filePath) {
 			const handle = await node_fs_promises.default.open(filePath, "wx");
+			let closed = false;
+			let released = false;
+			const closeHandle = async () => {
+				if (closed) return;
+				await handle.close();
+				closed = true;
+			};
 			return {
-				writeFile(content) {
-					return handle.writeFile(content, "utf-8");
+				async writeMetadata(content) {
+					await handle.writeFile(content, "utf-8");
+					await closeHandle();
 				},
-				close() {
-					return handle.close();
+				async release() {
+					if (released) return;
+					await closeHandle();
+					await node_fs_promises.default.unlink(filePath).catch((error) => {
+						if (error.code !== "ENOENT") throw error;
+					});
+					released = true;
 				}
 			};
 		},

package/dist/node.d.cts

@@ -1,8 +1,8 @@
-import { _ as BackendHostAdapter, g as BackendFileSystem, h as BackendFileStat, k as BackendRuntimeOptions, m as BackendFileHandle, t as BackendRuntime } from "./runtime-Wu6vGZ-j.cjs";
+import { O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, k as BackendSessionLock, m as BackendFileStat, t as BackendRuntime } from "./runtime-B7rLrkcR.cjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;
 declare function createNodeBackendHostAdapter(): BackendHostAdapter;
 declare function createNodeBackendRuntime(options?: BackendRuntimeOptions): BackendRuntime;
 //#endregion
-export { type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, BackendRuntime, type BackendRuntimeOptions, createNodeBackendFileSystem, createNodeBackendHostAdapter, createNodeBackendRuntime };
+export { type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, createNodeBackendFileSystem, createNodeBackendHostAdapter, createNodeBackendRuntime };

package/dist/node.d.mts

@@ -1,8 +1,8 @@
-import { _ as BackendHostAdapter, g as BackendFileSystem, h as BackendFileStat, k as BackendRuntimeOptions, m as BackendFileHandle, t as BackendRuntime } from "./runtime-BQOEw22M.mjs";
+import { O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, k as BackendSessionLock, m as BackendFileStat, t as BackendRuntime } from "./runtime-CJnoedTA.mjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;
 declare function createNodeBackendHostAdapter(): BackendHostAdapter;
 declare function createNodeBackendRuntime(options?: BackendRuntimeOptions): BackendRuntime;
 //#endregion
-export { type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, BackendRuntime, type BackendRuntimeOptions, createNodeBackendFileSystem, createNodeBackendHostAdapter, createNodeBackendRuntime };
+export { type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, createNodeBackendFileSystem, createNodeBackendHostAdapter, createNodeBackendRuntime };

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { t as BackendRuntime } from "./runtime-DtCn0Y44.mjs";
+import { t as BackendRuntime } from "./runtime-CNTJCi6P.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/node.ts
@@ -33,14 +33,27 @@ function createNodeBackendFileSystem() {
 				return path.resolve(filePath);
 			}
 		},
-		async openExclusive(filePath) {
+		async acquireSessionLock(filePath) {
 			const handle = await fs.open(filePath, "wx");
+			let closed = false;
+			let released = false;
+			const closeHandle = async () => {
+				if (closed) return;
+				await handle.close();
+				closed = true;
+			};
 			return {
-				writeFile(content) {
-					return handle.writeFile(content, "utf-8");
+				async writeMetadata(content) {
+					await handle.writeFile(content, "utf-8");
+					await closeHandle();
 				},
-				close() {
-					return handle.close();
+				async release() {
+					if (released) return;
+					await closeHandle();
+					await fs.unlink(filePath).catch((error) => {
+						if (error.code !== "ENOENT") throw error;
+					});
+					released = true;
 				}
 			};
 		},

package/dist/{runtime-BQOEw22M.d.mts → runtime-B7rLrkcR.d.cts}

@@ -1,5 +1,5 @@
-import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
 import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
+import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
 
 //#region src/contracts.d.ts
 declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
@@ -49,9 +49,12 @@ interface PathPolicyViolationError {
 }
 //#endregion
 //#region src/runtime/contracts.d.ts
-interface BackendFileHandle {
-  writeFile(content: string): Promise<void>;
-  close(): Promise<void>;
+/** An exclusive lock owned for the lifetime of one backend session. */
+interface BackendSessionLock {
+  /** Persist optional host metadata without changing lock ownership. */
+  writeMetadata(content: string): Promise<void>;
+  /** Release ownership. Browser implementations must also release when their document terminates. */
+  release(): Promise<void>;
 }
 interface BackendFileStat {
   isFile(): boolean;
@@ -68,7 +71,7 @@ interface BackendFileSystem {
     recursive?: boolean;
   }): Promise<void>;
   resolvePath(filePath: string): Promise<string>;
-  openExclusive(filePath: string): Promise<BackendFileHandle>;
+  acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
   unlink(filePath: string): Promise<void>;
   rmdir(dirPath: string): Promise<void>;
   join(...paths: string[]): string;
@@ -424,10 +427,12 @@ interface ApplySessionTransactionInput {
   operations: UamTransactionOperation[];
 }
 interface OpenProjectSessionInput {
+  /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
   project: UamProject;
   sessionId?: string;
   canonicalProjectPath?: string;
   canonicalPathKey?: string;
+  /** Optional writeback target for the authoritative UAM project; this is not an import source. */
   storage?: BackendProjectSessionStorage;
 }
 interface BackendProjectSessionStorage {
@@ -501,4 +506,4 @@ declare class BackendRuntime {
   refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
 }
 //#endregion
-export { BACKEND_COMPATIBILITY_POLICY as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobNotFoundError as C, BackendProjectSessionStorage as D, BackendJobStatus as E, GetCacheSnapshotInput as F, OpenProjectSessionInput as G, MaterializeSessionSnapshot as H, GetEventsInput as I, SaveSessionInput as J, RefreshCacheInput as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendResult as O, EventCursorInvalidError as P, BACKEND_CAPABILITY_SCHEMA_VERSION as Q, GetJobInput as R, BackendJobNotCancellableError as S, BackendJobSnapshot as T, MaterializeValidationFailedError as U, MaterializeSessionInput as V, MaterializeWriteFailedError as W, SessionStaleWriteError as X, SessionNotFoundError as Y, UamFidelityUnsupportedError as Z, BackendHostAdapter as _, BackendCacheEntry as a, BackendJobListSnapshot as b, BackendCapabilityManifest as c, BackendEvent as d, BACKEND_CONTRACT_VERSION as et, BackendEventKind as f, BackendFileSystem as g, BackendFileStat as h, BackendArtifactBridgeCapability as i, BackendStage as it, BackendSuccess as j, BackendRuntimeOptions as k, BackendCapabilityUnavailableError as l, BackendFileHandle as m, AdvisoryLockConflictError as n, BackendMessage as nt, BackendCacheSnapshot as o, BackendFailure as p, SavePartialFailureError as q, ApplySessionTransactionInput as r, BackendResponseMeta as rt, BackendCapabilities as s, BackendRuntime as t, BackendDiagnostic as tt, BackendError as u, BackendJobErrors as v, BackendJobProgress as w, BackendJobListStatusFilter as x, BackendJobKind as y, InProcessLockConflictError as z };
+export { BACKEND_COMPATIBILITY_POLICY as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobProgress as C, BackendResult as D, BackendProjectSessionStorage as E, GetCacheSnapshotInput as F, OpenProjectSessionInput as G, MaterializeSessionSnapshot as H, GetEventsInput as I, SaveSessionInput as J, RefreshCacheInput as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendRuntimeOptions as O, EventCursorInvalidError as P, BACKEND_CAPABILITY_SCHEMA_VERSION as Q, GetJobInput as R, BackendJobNotFoundError as S, BackendJobStatus as T, MaterializeValidationFailedError as U, MaterializeSessionInput as V, MaterializeWriteFailedError as W, SessionStaleWriteError as X, SessionNotFoundError as Y, UamFidelityUnsupportedError as Z, BackendJobErrors as _, BackendCacheEntry as a, BackendJobListStatusFilter as b, BackendCapabilityManifest as c, BackendEvent as d, BACKEND_CONTRACT_VERSION as et, BackendEventKind as f, BackendHostAdapter as g, BackendFileSystem as h, BackendArtifactBridgeCapability as i, BackendStage as it, BackendSuccess as j, BackendSessionLock as k, BackendCapabilityUnavailableError as l, BackendFileStat as m, AdvisoryLockConflictError as n, BackendMessage as nt, BackendCacheSnapshot as o, BackendFailure as p, SavePartialFailureError as q, ApplySessionTransactionInput as r, BackendResponseMeta as rt, BackendCapabilities as s, BackendRuntime as t, BackendDiagnostic as tt, BackendError as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, InProcessLockConflictError as z };

package/dist/{runtime-CQQmzsxV.cjs → runtime-BtavZ2ku.cjs}

@@ -1211,10 +1211,10 @@ var RuntimeService = class {
 			holderSessionId: existingSessionId,
 			lockFilePath
 		});
-		let advisoryLock = null;
+		let sessionLock = null;
 		try {
-			advisoryLock = await fileSystem.openExclusive(lockFilePath);
-			await advisoryLock.writeFile(JSON.stringify(this.context.host?.lockMetadata?.({
+			sessionLock = await fileSystem.acquireSessionLock(lockFilePath);
+			await sessionLock.writeMetadata(JSON.stringify(this.context.host?.lockMetadata?.({
 				canonicalPathKey,
 				canonicalProjectPath,
 				lockFilePath
@@ -1222,7 +1222,6 @@ var RuntimeService = class {
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 				canonicalPathKey
 			}));
-			await advisoryLock.close();
 			const document = await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true });
 			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(document);
 			const sessionId = randomId();
@@ -1232,6 +1231,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				sessionLock,
 				fileSystem,
 				project,
 				uamFidelity: await hasFullUamFidelity(document, project) ? "full" : "unsupported",
@@ -1258,6 +1258,7 @@ var RuntimeService = class {
 				revision: session.revision
 			});
 		} catch (error) {
+			if (sessionLock) await sessionLock.release().catch(() => void 0);
 			if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") return failure("runtime", startedAt, {
 				code: "lock_conflict",
 				kind: "advisory_lock_conflict",
@@ -1265,10 +1266,10 @@ var RuntimeService = class {
 				canonicalPathKey,
 				lockFilePath
 			});
-			if (advisoryLock) {
-				await advisoryLock.close().catch(() => void 0);
-				await fileSystem.unlink(lockFilePath).catch(() => void 0);
-			}
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOTSUP") return failure("runtime", startedAt, {
+				...createCapabilityUnavailableError("fileSystem"),
+				message: error instanceof Error ? error.message : String(error)
+			});
 			throw error;
 		}
 	}
@@ -1293,6 +1294,7 @@ var RuntimeService = class {
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
+			sessionLock: null,
 			fileSystem: storage?.fileSystem,
 			project: (0, _openfairygui_core_uam.normalizeUamProject)(input.project),
 			uamFidelity: "full",
@@ -1329,7 +1331,8 @@ var RuntimeService = class {
 			canonicalPathKey: session.canonicalPathKey,
 			revision: session.revision
 		});
-		if (this.context.fileSystem && session.lockFilePath) await this.context.fileSystem.unlink(session.lockFilePath).catch(() => void 0);
+		await session.sessionLock?.release().catch(() => void 0);
+		session.sessionLock = null;
 		session.lockHeld = false;
 		session.closed = true;
 		this.context.sessions.delete(session.sessionId);

package/dist/{runtime-Wu6vGZ-j.d.cts → runtime-CJnoedTA.d.mts}

@@ -1,5 +1,5 @@
-import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
 import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
 
 //#region src/contracts.d.ts
 declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
@@ -49,9 +49,12 @@ interface PathPolicyViolationError {
 }
 //#endregion
 //#region src/runtime/contracts.d.ts
-interface BackendFileHandle {
-  writeFile(content: string): Promise<void>;
-  close(): Promise<void>;
+/** An exclusive lock owned for the lifetime of one backend session. */
+interface BackendSessionLock {
+  /** Persist optional host metadata without changing lock ownership. */
+  writeMetadata(content: string): Promise<void>;
+  /** Release ownership. Browser implementations must also release when their document terminates. */
+  release(): Promise<void>;
 }
 interface BackendFileStat {
   isFile(): boolean;
@@ -68,7 +71,7 @@ interface BackendFileSystem {
     recursive?: boolean;
   }): Promise<void>;
   resolvePath(filePath: string): Promise<string>;
-  openExclusive(filePath: string): Promise<BackendFileHandle>;
+  acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
   unlink(filePath: string): Promise<void>;
   rmdir(dirPath: string): Promise<void>;
   join(...paths: string[]): string;
@@ -424,10 +427,12 @@ interface ApplySessionTransactionInput {
   operations: UamTransactionOperation[];
 }
 interface OpenProjectSessionInput {
+  /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
   project: UamProject;
   sessionId?: string;
   canonicalProjectPath?: string;
   canonicalPathKey?: string;
+  /** Optional writeback target for the authoritative UAM project; this is not an import source. */
   storage?: BackendProjectSessionStorage;
 }
 interface BackendProjectSessionStorage {
@@ -501,4 +506,4 @@ declare class BackendRuntime {
   refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
 }
 //#endregion
-export { BACKEND_COMPATIBILITY_POLICY as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobNotFoundError as C, BackendProjectSessionStorage as D, BackendJobStatus as E, GetCacheSnapshotInput as F, OpenProjectSessionInput as G, MaterializeSessionSnapshot as H, GetEventsInput as I, SaveSessionInput as J, RefreshCacheInput as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendResult as O, EventCursorInvalidError as P, BACKEND_CAPABILITY_SCHEMA_VERSION as Q, GetJobInput as R, BackendJobNotCancellableError as S, BackendJobSnapshot as T, MaterializeValidationFailedError as U, MaterializeSessionInput as V, MaterializeWriteFailedError as W, SessionStaleWriteError as X, SessionNotFoundError as Y, UamFidelityUnsupportedError as Z, BackendHostAdapter as _, BackendCacheEntry as a, BackendJobListSnapshot as b, BackendCapabilityManifest as c, BackendEvent as d, BACKEND_CONTRACT_VERSION as et, BackendEventKind as f, BackendFileSystem as g, BackendFileStat as h, BackendArtifactBridgeCapability as i, BackendStage as it, BackendSuccess as j, BackendRuntimeOptions as k, BackendCapabilityUnavailableError as l, BackendFileHandle as m, AdvisoryLockConflictError as n, BackendMessage as nt, BackendCacheSnapshot as o, BackendFailure as p, SavePartialFailureError as q, ApplySessionTransactionInput as r, BackendResponseMeta as rt, BackendCapabilities as s, BackendRuntime as t, BackendDiagnostic as tt, BackendError as u, BackendJobErrors as v, BackendJobProgress as w, BackendJobListStatusFilter as x, BackendJobKind as y, InProcessLockConflictError as z };
+export { BACKEND_COMPATIBILITY_POLICY as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobProgress as C, BackendResult as D, BackendProjectSessionStorage as E, GetCacheSnapshotInput as F, OpenProjectSessionInput as G, MaterializeSessionSnapshot as H, GetEventsInput as I, SaveSessionInput as J, RefreshCacheInput as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendRuntimeOptions as O, EventCursorInvalidError as P, BACKEND_CAPABILITY_SCHEMA_VERSION as Q, GetJobInput as R, BackendJobNotFoundError as S, BackendJobStatus as T, MaterializeValidationFailedError as U, MaterializeSessionInput as V, MaterializeWriteFailedError as W, SessionStaleWriteError as X, SessionNotFoundError as Y, UamFidelityUnsupportedError as Z, BackendJobErrors as _, BackendCacheEntry as a, BackendJobListStatusFilter as b, BackendCapabilityManifest as c, BackendEvent as d, BACKEND_CONTRACT_VERSION as et, BackendEventKind as f, BackendHostAdapter as g, BackendFileSystem as h, BackendArtifactBridgeCapability as i, BackendStage as it, BackendSuccess as j, BackendSessionLock as k, BackendCapabilityUnavailableError as l, BackendFileStat as m, AdvisoryLockConflictError as n, BackendMessage as nt, BackendCacheSnapshot as o, BackendFailure as p, SavePartialFailureError as q, ApplySessionTransactionInput as r, BackendResponseMeta as rt, BackendCapabilities as s, BackendRuntime as t, BackendDiagnostic as tt, BackendError as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, InProcessLockConflictError as z };

package/dist/{runtime-DtCn0Y44.mjs → runtime-CNTJCi6P.mjs}

@@ -1210,10 +1210,10 @@ var RuntimeService = class {
 			holderSessionId: existingSessionId,
 			lockFilePath
 		});
-		let advisoryLock = null;
+		let sessionLock = null;
 		try {
-			advisoryLock = await fileSystem.openExclusive(lockFilePath);
-			await advisoryLock.writeFile(JSON.stringify(this.context.host?.lockMetadata?.({
+			sessionLock = await fileSystem.acquireSessionLock(lockFilePath);
+			await sessionLock.writeMetadata(JSON.stringify(this.context.host?.lockMetadata?.({
 				canonicalPathKey,
 				canonicalProjectPath,
 				lockFilePath
@@ -1221,7 +1221,6 @@ var RuntimeService = class {
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 				canonicalPathKey
 			}));
-			await advisoryLock.close();
 			const document = await new ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true });
 			const project = liftDocumentToUamProject(document);
 			const sessionId = randomId();
@@ -1231,6 +1230,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				sessionLock,
 				fileSystem,
 				project,
 				uamFidelity: await hasFullUamFidelity(document, project) ? "full" : "unsupported",
@@ -1257,6 +1257,7 @@ var RuntimeService = class {
 				revision: session.revision
 			});
 		} catch (error) {
+			if (sessionLock) await sessionLock.release().catch(() => void 0);
 			if (typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST") return failure("runtime", startedAt, {
 				code: "lock_conflict",
 				kind: "advisory_lock_conflict",
@@ -1264,10 +1265,10 @@ var RuntimeService = class {
 				canonicalPathKey,
 				lockFilePath
 			});
-			if (advisoryLock) {
-				await advisoryLock.close().catch(() => void 0);
-				await fileSystem.unlink(lockFilePath).catch(() => void 0);
-			}
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOTSUP") return failure("runtime", startedAt, {
+				...createCapabilityUnavailableError("fileSystem"),
+				message: error instanceof Error ? error.message : String(error)
+			});
 			throw error;
 		}
 	}
@@ -1292,6 +1293,7 @@ var RuntimeService = class {
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
+			sessionLock: null,
 			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
 			uamFidelity: "full",
@@ -1328,7 +1330,8 @@ var RuntimeService = class {
 			canonicalPathKey: session.canonicalPathKey,
 			revision: session.revision
 		});
-		if (this.context.fileSystem && session.lockFilePath) await this.context.fileSystem.unlink(session.lockFilePath).catch(() => void 0);
+		await session.sessionLock?.release().catch(() => void 0);
+		session.sessionLock = null;
 		session.lockHeld = false;
 		session.closed = true;
 		this.context.sessions.delete(session.sessionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.37",
+  "version": "0.2.0-alpha.38",
   "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -52,8 +52,8 @@
     "runtime"
   ],
   "dependencies": {
-    "@openfairygui/core": "0.2.0-alpha.37",
-    "@openfairygui/functions": "0.2.0-alpha.37"
+    "@openfairygui/core": "0.2.0-alpha.38",
+    "@openfairygui/functions": "0.2.0-alpha.38"
   },
   "devDependencies": {
     "ava": "^7.0.0",

package/src/index.ts

@@ -20,7 +20,6 @@ export {
 	type BackendEvent,
 	type BackendEventKind,
 	type BackendFailure,
-	type BackendFileHandle,
 	type BackendFileStat,
 	type BackendFileSystem,
 	type BackendHostAdapter,
@@ -37,6 +36,7 @@ export {
 	type BackendResult,
 	BackendRuntime,
 	type BackendRuntimeOptions,
+	type BackendSessionLock,
 	type BackendSessionSnapshot,
 	type BackendSuccess,
 	type CacheRefreshFailedError,

package/src/node.ts

@@ -2,11 +2,11 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
 	BackendRuntime,
-	type BackendFileHandle,
 	type BackendFileStat,
 	type BackendFileSystem,
 	type BackendHostAdapter,
 	type BackendRuntimeOptions,
+	type BackendSessionLock,
 } from './runtime.js';
 
 export function createNodeBackendFileSystem(): BackendFileSystem {
@@ -40,14 +40,27 @@ export function createNodeBackendFileSystem(): BackendFileSystem {
 				return path.resolve(filePath);
 			}
 		},
-		async openExclusive(filePath: string): Promise<BackendFileHandle> {
+		async acquireSessionLock(filePath: string): Promise<BackendSessionLock> {
 			const handle = await fs.open(filePath, 'wx');
+			let closed = false;
+			let released = false;
+			const closeHandle = async (): Promise<void> => {
+				if (closed) return;
+				await handle.close();
+				closed = true;
+			};
 			return {
-				writeFile(content: string): Promise<void> {
-					return handle.writeFile(content, 'utf-8');
+				async writeMetadata(content: string): Promise<void> {
+					await handle.writeFile(content, 'utf-8');
+					await closeHandle();
 				},
-				close(): Promise<void> {
-					return handle.close();
+				async release(): Promise<void> {
+					if (released) return;
+					await closeHandle();
+					await fs.unlink(filePath).catch((error: NodeJS.ErrnoException) => {
+						if (error.code !== 'ENOENT') throw error;
+					});
+					released = true;
 				},
 			};
 		},
@@ -89,11 +102,11 @@ export function createNodeBackendRuntime(options: BackendRuntimeOptions = {}): B
 	});
 }
 
-export { BackendRuntime };
 export type {
-	BackendFileHandle,
 	BackendFileStat,
 	BackendFileSystem,
 	BackendHostAdapter,
 	BackendRuntimeOptions,
+	BackendSessionLock,
 } from './runtime.js';
+export { BackendRuntime };

package/src/runtime/contracts.ts

@@ -9,9 +9,12 @@ import type {
 } from '../contracts.js';
 import type { PathPolicyViolationError } from '../path-policy.js';
 
-export interface BackendFileHandle {
-	writeFile(content: string): Promise<void>;
-	close(): Promise<void>;
+/** An exclusive lock owned for the lifetime of one backend session. */
+export interface BackendSessionLock {
+	/** Persist optional host metadata without changing lock ownership. */
+	writeMetadata(content: string): Promise<void>;
+	/** Release ownership. Browser implementations must also release when their document terminates. */
+	release(): Promise<void>;
 }
 
 export interface BackendFileStat {
@@ -28,7 +31,7 @@ export interface BackendFileSystem {
 	writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
 	mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void>;
 	resolvePath(filePath: string): Promise<string>;
-	openExclusive(filePath: string): Promise<BackendFileHandle>;
+	acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
 	unlink(filePath: string): Promise<void>;
 	rmdir(dirPath: string): Promise<void>;
 	join(...paths: string[]): string;
@@ -474,10 +477,12 @@ export interface ApplySessionTransactionInput {
 }
 
 export interface OpenProjectSessionInput {
+	/** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
 	project: UamProject;
 	sessionId?: string;
 	canonicalProjectPath?: string;
 	canonicalPathKey?: string;
+	/** Optional writeback target for the authoritative UAM project; this is not an import source. */
 	storage?: BackendProjectSessionStorage;
 }
 

package/src/services/context.ts

@@ -15,6 +15,7 @@ import type {
 	BackendFileSystem,
 	BackendHostAdapter,
 	BackendJobSnapshot,
+	BackendSessionLock,
 	BackendSessionSnapshot,
 	BackendSuccess,
 } from '../runtime.js';
@@ -25,6 +26,7 @@ export interface BackendSessionState {
 	canonicalProjectPath: string;
 	canonicalPathKey: string;
 	lockFilePath: string;
+	sessionLock: BackendSessionLock | null;
 	fileSystem?: BackendFileSystem;
 	project: import('@openfairygui/core/uam').UamProject;
 	uamFidelity: 'full' | 'unsupported';

package/src/services/runtime-service.ts

@@ -9,8 +9,8 @@ import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-po
 import type {
 	AdvisoryLockConflictError,
 	BackendCapabilityUnavailableError,
-	BackendFileHandle,
 	BackendResult,
+	BackendSessionLock,
 	BackendSessionSnapshot,
 	InProcessLockConflictError,
 	OpenProjectSessionInput,
@@ -204,10 +204,10 @@ export class RuntimeService {
 			});
 		}
 
-		let advisoryLock: BackendFileHandle | null = null;
+		let sessionLock: BackendSessionLock | null = null;
 		try {
-			advisoryLock = await fileSystem.openExclusive(lockFilePath);
-			await advisoryLock.writeFile(
+			sessionLock = await fileSystem.acquireSessionLock(lockFilePath);
+			await sessionLock.writeMetadata(
 				JSON.stringify(
 					this.context.host?.lockMetadata?.({
 						canonicalPathKey,
@@ -219,8 +219,6 @@ export class RuntimeService {
 					},
 				),
 			);
-			await advisoryLock.close();
-
 			const reader = new ProjectReader(createProjectReaderFileSystem(fileSystem));
 			const document = await reader.read(fairyPath, { hydrateResourceBytes: true });
 			const project = liftDocumentToUamProject(document);
@@ -231,6 +229,7 @@ export class RuntimeService {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				sessionLock,
 				fileSystem,
 				project,
 				uamFidelity: (await hasFullUamFidelity(document, project)) ? 'full' : 'unsupported',
@@ -253,6 +252,7 @@ export class RuntimeService {
 				revision: session.revision,
 			});
 		} catch (error) {
+			if (sessionLock) await sessionLock.release().catch(() => undefined);
 			if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST') {
 				return failure('runtime', startedAt, {
 					code: 'lock_conflict',
@@ -262,9 +262,11 @@ export class RuntimeService {
 					lockFilePath,
 				});
 			}
-			if (advisoryLock) {
-				await advisoryLock.close().catch(() => undefined);
-				await fileSystem.unlink(lockFilePath).catch(() => undefined);
+			if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOTSUP') {
+				return failure('runtime', startedAt, {
+					...createCapabilityUnavailableError('fileSystem'),
+					message: error instanceof Error ? error.message : String(error),
+				});
 			}
 			throw error;
 		}
@@ -300,6 +302,7 @@ export class RuntimeService {
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: '',
+			sessionLock: null,
 			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
 			uamFidelity: 'full',
@@ -338,9 +341,8 @@ export class RuntimeService {
 			canonicalPathKey: session.canonicalPathKey,
 			revision: session.revision,
 		});
-		if (this.context.fileSystem && session.lockFilePath) {
-			await this.context.fileSystem.unlink(session.lockFilePath).catch(() => undefined);
-		}
+		await session.sessionLock?.release().catch(() => undefined);
+		session.sessionLock = null;
 		session.lockHeld = false;
 		session.closed = true;
 		this.context.sessions.delete(session.sessionId);

package/src/storage.ts

@@ -1,5 +1,5 @@
 import type { FileSystem as CoreProjectFileSystem } from '@openfairygui/core/project-io';
-import type { BackendFileHandle, BackendFileStat, BackendFileSystem } from './runtime.js';
+import type { BackendFileStat, BackendFileSystem, BackendSessionLock } from './runtime.js';
 
 type StorageStatKind = 'file' | 'directory';
 
@@ -19,8 +19,13 @@ export interface BackendAsyncStorageAdapter {
 	readdir(dirPath: string): Promise<string[]>;
 	exists?(filePath: string): Promise<boolean>;
 	stat?(filePath: string): Promise<BackendStorageStatLike>;
+	/** Stable cross-context path identity; also scopes the default Web Lock name. */
 	resolvePath?(filePath: string): Promise<string>;
-	openExclusive?(filePath: string): Promise<BackendFileHandle>;
+	/**
+	 * Optional replacement for Web Locks. Acquisition must be atomic across browser contexts, remain held
+	 * until release(), and recover automatically when the owning document terminates.
+	 */
+	acquireSessionLock?(lockPath: string): Promise<BackendSessionLock>;
 	unlink(filePath: string): Promise<void>;
 	rmdir(dirPath: string): Promise<void>;
 	join?(...paths: string[]): string;
@@ -46,6 +51,44 @@ function createPathError(code: string, message: string): Error & { code: string
 	return error;
 }
 
+function getWebLockManager(): LockManager | null {
+	if (typeof navigator === 'undefined') return null;
+	const lockManager = (navigator as Navigator & { locks?: LockManager }).locks;
+	return lockManager && typeof lockManager.request === 'function' ? lockManager : null;
+}
+
+function acquireWebSessionLock(lockManager: LockManager, lockName: string): Promise<BackendSessionLock> {
+	return new Promise((resolve, reject) => {
+		let releasePlatformLock = (): void => undefined;
+		const held = new Promise<void>((release) => {
+			releasePlatformLock = release;
+		});
+		void lockManager
+			.request(lockName, { mode: 'exclusive', ifAvailable: true }, async (lock) => {
+				if (!lock) {
+					reject(createPathError('EEXIST', `Browser session lock is already held: ${lockName}`));
+					return;
+				}
+				let released = false;
+				resolve({
+					// Web Locks are the authority; a persisted marker would survive abrupt document termination.
+					writeMetadata(): Promise<void> {
+						return Promise.resolve();
+					},
+					release(): Promise<void> {
+						if (!released) {
+							released = true;
+							releasePlatformLock();
+						}
+						return Promise.resolve();
+					},
+				});
+				await held;
+			})
+			.catch(reject);
+	});
+}
+
 function normalizeStoragePath(value: string): string {
 	const normalized = value.replace(/\\/g, '/').replace(/\/+/g, '/');
 	const absolute = normalized.startsWith('/');
@@ -121,8 +164,6 @@ export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapt
 	if (typeof storage.rmdir !== 'function') {
 		throw createPathError('ENOTSUP', 'Storage adapter must provide rmdir() for project resource folder lifecycle writes.');
 	}
-	const lockedPaths = new Set<string>();
-
 	const fileSystem: BackendStorageFileSystem = {
 		stat(filePath: string): Promise<BackendFileStat> {
 			return inferStat(storage, fileSystem.resolve(filePath));
@@ -158,30 +199,20 @@ export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapt
 			const resolved = fileSystem.resolve(filePath);
 			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
 		},
-		async openExclusive(filePath: string): Promise<BackendFileHandle> {
-			const resolved = fileSystem.resolve(filePath);
-			if (storage.openExclusive) return storage.openExclusive(resolved);
-			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) {
-				throw createPathError('EEXIST', `Storage path already exists: ${resolved}`);
+		async acquireSessionLock(lockPath: string): Promise<BackendSessionLock> {
+			const resolved = fileSystem.resolve(lockPath);
+			if (storage.acquireSessionLock) return storage.acquireSessionLock(resolved);
+			const lockManager = getWebLockManager();
+			if (!lockManager) {
+				throw createPathError(
+					'ENOTSUP',
+					'Browser openSession requires Web Locks or BackendAsyncStorageAdapter.acquireSessionLock().',
+				);
 			}
-			lockedPaths.add(resolved);
-			let closed = false;
-			return {
-				async writeFile(content: string): Promise<void> {
-					if (closed) throw createPathError('EBADF', `Storage lock handle is closed: ${resolved}`);
-					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
-					await storage.writeFile(resolved, content);
-				},
-				async close(): Promise<void> {
-					closed = true;
-					lockedPaths.delete(resolved);
-				},
-			};
+			return acquireWebSessionLock(lockManager, `@openfairygui/backend:${resolved}`);
 		},
 		unlink(filePath: string): Promise<void> {
-			const resolved = fileSystem.resolve(filePath);
-			lockedPaths.delete(resolved);
-			return storage.unlink(resolved);
+			return storage.unlink(fileSystem.resolve(filePath));
 		},
 		rmdir(dirPath: string): Promise<void> {
 			return storage.rmdir(fileSystem.resolve(dirPath));