@openfairygui/backend 0.2.0-alpha.5 → 0.2.0-alpha.7

package/README.md

@@ -12,6 +12,7 @@ It owns:
 - revisioned request handling
 - 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
 - capability discovery
 - transport-neutral bootstrap
@@ -31,8 +32,9 @@ It also provides:
 
 It does **not** redefine transaction grammar or expose `Document`.
 It also does **not** implement MCP or any transport-specific wire protocol.
-The root `@openfairygui/backend` entrypoint is browser-safe: file-backed sessions require an injected
-`BackendFileSystem`, while the default Node filesystem/runtime lives under `@openfairygui/backend/node`.
+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. The default Node filesystem/runtime lives under `@openfairygui/backend/node`.
 
 ## Relationship to other packages
 
@@ -58,6 +60,35 @@ const applied = await runtime.applyTransaction({
 });
 ```
 
+Browser-safe project session with injected storage:
+
+```ts
+import { BackendRuntime, createBackendStorageFileSystem } from '@openfairygui/backend';
+
+const fileSystem = createBackendStorageFileSystem({
+	async readFile(filePath) { return storage.readText(filePath); },
+	async readFileRaw(filePath) { return storage.readBytes(filePath); },
+	async writeFile(filePath, content) { await storage.writeText(filePath, content); },
+	async writeFileRaw(filePath, data) { await storage.writeBytes(filePath, data); },
+	async mkdir(dirPath) { await storage.mkdir(dirPath); },
+	async readdir(dirPath) { return storage.readdir(dirPath); },
+	async exists(filePath) { return storage.exists(filePath); },
+});
+
+const runtime = new BackendRuntime();
+const opened = runtime.openProjectSession({
+	project: uamProject,
+	storage: {
+		fileSystem,
+		fairyPath: 'Project.fairy',
+	},
+});
+if (!opened.ok) throw new Error(opened.error.message);
+
+const saved = await runtime.saveSession({ sessionId: opened.data.sessionId });
+if (!saved.ok) throw new Error(saved.error.message);
+```
+
 Node file-backed session:
 
 ```ts

package/dist/index.cjs

@@ -1,6 +1,151 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runtime = require("./runtime--ytGfQCF.cjs");
+const require_runtime = require("./runtime-YK3ACpuQ.cjs");
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
+};
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	for (const segment of rawSegments) {
+		if (segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	const joined = segments.join("/");
+	if (absolute) return joined ? `/${joined}` : "/";
+	return joined || ".";
+}
+function joinStoragePath(...paths) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === "/" || normalized === ".") return ".";
+	const absolute = normalized.startsWith("/");
+	const parts = normalized.split("/").filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? "/" : ".";
+	return `${absolute ? "/" : ""}${parts.join("/")}`;
+}
+function statFromLike(stat) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	const kind = stat.kind ?? stat.type;
+	if (kind === "file" || kind === "directory") return new StorageFileStat(kind);
+	throw createPathError("EINVAL", "Storage stat must provide kind/type or isFile()/isDirectory().");
+}
+async function inferStat(storage, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat("file");
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat("file");
+		} catch {
+			throw createPathError("ENOENT", `Storage path not found: ${filePath}`);
+		}
+	}
+}
+function createBackendStorageFileSystem(storage) {
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
+		stat(filePath) {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath) {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath) {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath, content) {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath, data) {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath) {
+			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);
+				}
+			};
+		},
+		unlink(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			if (storage.unlink) return storage.unlink(resolved);
+			throw createPathError("ENOTSUP", "Storage adapter does not provide unlink().");
+		},
+		join(...paths) {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath) {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths) {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		}
+	};
+	return fileSystem;
+}
+//#endregion
 exports.BACKEND_CAPABILITY_SCHEMA_VERSION = require_runtime.BACKEND_CAPABILITY_SCHEMA_VERSION;
 exports.BACKEND_COMPATIBILITY_POLICY = require_runtime.BACKEND_COMPATIBILITY_POLICY;
 exports.BACKEND_CONTRACT_VERSION = require_runtime.BACKEND_CONTRACT_VERSION;
 exports.BackendRuntime = require_runtime.BackendRuntime;
+exports.createBackendStorageFileSystem = createBackendStorageFileSystem;

package/dist/index.d.cts

@@ -1,2 +1,33 @@
-import { A as BackendSuccess, B as OpenProjectSessionInput, C as BackendJobProgress, D as BackendRuntime, E as BackendResult, F as GetEventsInput, G as BACKEND_CAPABILITY_SCHEMA_VERSION, H as SavePartialFailureError, I as GetEventsSnapshot, J as BackendDiagnostic, K as BACKEND_COMPATIBILITY_POLICY, L as GetJobInput, M as CancelJobInput, N as EventCursorInvalidError, O as BackendRuntimeOptions, P as GetCacheSnapshotInput, R as InProcessLockConflictError, S as BackendJobNotFoundError, T as BackendJobStatus, U as SessionNotFoundError, V as RefreshCacheInput, W as SessionStaleWriteError, X as BackendResponseMeta, Y as BackendMessage, Z as BackendStage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as CacheRefreshFailedError, k as BackendSessionSnapshot, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CONTRACT_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as ListJobsInput } from "./runtime-DlM27Izm.cjs";
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, 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 BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError };
+import { $ as BackendStage, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as SessionNotFoundError, H as RefreshCacheInput, I as GetEventsInput, J as BACKEND_COMPATIBILITY_POLICY, K as SessionStaleWriteError, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BackendResponseMeta, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as SavePartialFailureError, V as OpenProjectSessionInput, W as SaveSessionInput, X as BackendDiagnostic, Y as BACKEND_CONTRACT_VERSION, Z as BackendMessage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-DziTGugy.cjs";
+import { FileSystem } from "@openfairygui/core/project-io";
+
+//#region src/storage.d.ts
+type StorageStatKind = 'file' | 'directory';
+interface BackendStorageStatLike {
+  kind?: StorageStatKind;
+  type?: StorageStatKind;
+  isFile?(): boolean;
+  isDirectory?(): boolean;
+}
+interface BackendAsyncStorageAdapter {
+  readFile(filePath: string): Promise<string>;
+  readFileRaw(filePath: string): Promise<Uint8Array>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+  mkdir(dirPath: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  readdir(dirPath: string): Promise<string[]>;
+  exists?(filePath: string): Promise<boolean>;
+  stat?(filePath: string): Promise<BackendStorageStatLike>;
+  resolvePath?(filePath: string): Promise<string>;
+  openExclusive?(filePath: string): Promise<BackendFileHandle>;
+  unlink?(filePath: string): Promise<void>;
+  join?(...paths: string[]): string;
+  dirname?(filePath: string): string;
+  resolve?(...paths: string[]): string;
+}
+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 OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };

package/dist/index.d.mts

@@ -1,2 +1,33 @@
-import { A as BackendSuccess, B as OpenProjectSessionInput, C as BackendJobProgress, D as BackendRuntime, E as BackendResult, F as GetEventsInput, G as BACKEND_CAPABILITY_SCHEMA_VERSION, H as SavePartialFailureError, I as GetEventsSnapshot, J as BackendDiagnostic, K as BACKEND_COMPATIBILITY_POLICY, L as GetJobInput, M as CancelJobInput, N as EventCursorInvalidError, O as BackendRuntimeOptions, P as GetCacheSnapshotInput, R as InProcessLockConflictError, S as BackendJobNotFoundError, T as BackendJobStatus, U as SessionNotFoundError, V as RefreshCacheInput, W as SessionStaleWriteError, X as BackendResponseMeta, Y as BackendMessage, Z as BackendStage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as CacheRefreshFailedError, k as BackendSessionSnapshot, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CONTRACT_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as ListJobsInput } from "./runtime-BPuZITUC.mjs";
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, 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 BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SessionNotFoundError, type SessionStaleWriteError };
+import { $ as BackendStage, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as SessionNotFoundError, H as RefreshCacheInput, I as GetEventsInput, J as BACKEND_COMPATIBILITY_POLICY, K as SessionStaleWriteError, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BackendResponseMeta, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as SavePartialFailureError, V as OpenProjectSessionInput, W as SaveSessionInput, X as BackendDiagnostic, Y as BACKEND_CONTRACT_VERSION, Z as BackendMessage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-Bydxr_SN.mjs";
+import { FileSystem } from "@openfairygui/core/project-io";
+
+//#region src/storage.d.ts
+type StorageStatKind = 'file' | 'directory';
+interface BackendStorageStatLike {
+  kind?: StorageStatKind;
+  type?: StorageStatKind;
+  isFile?(): boolean;
+  isDirectory?(): boolean;
+}
+interface BackendAsyncStorageAdapter {
+  readFile(filePath: string): Promise<string>;
+  readFileRaw(filePath: string): Promise<Uint8Array>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+  mkdir(dirPath: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  readdir(dirPath: string): Promise<string[]>;
+  exists?(filePath: string): Promise<boolean>;
+  stat?(filePath: string): Promise<BackendStorageStatLike>;
+  resolvePath?(filePath: string): Promise<string>;
+  openExclusive?(filePath: string): Promise<BackendFileHandle>;
+  unlink?(filePath: string): Promise<void>;
+  join?(...paths: string[]): string;
+  dirname?(filePath: string): string;
+  resolve?(...paths: string[]): string;
+}
+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 OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };

package/dist/index.mjs

@@ -1,2 +1,146 @@
-import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-CqARWlcn.mjs";
-export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime };
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-Cn0O-wZt.mjs";
+//#region src/storage.ts
+var StorageFileStat = class {
+	constructor(kind) {
+		this.kind = kind;
+	}
+	isFile() {
+		return this.kind === "file";
+	}
+	isDirectory() {
+		return this.kind === "directory";
+	}
+};
+function createPathError(code, message) {
+	const error = new Error(message);
+	error.code = code;
+	return error;
+}
+function normalizeStoragePath(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+	const absolute = normalized.startsWith("/");
+	const rawSegments = normalized.split("/").filter((segment) => segment.length > 0);
+	const segments = [];
+	for (const segment of rawSegments) {
+		if (segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	const joined = segments.join("/");
+	if (absolute) return joined ? `/${joined}` : "/";
+	return joined || ".";
+}
+function joinStoragePath(...paths) {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join("/"));
+}
+function dirnameStoragePath(filePath) {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === "/" || normalized === ".") return ".";
+	const absolute = normalized.startsWith("/");
+	const parts = normalized.split("/").filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? "/" : ".";
+	return `${absolute ? "/" : ""}${parts.join("/")}`;
+}
+function statFromLike(stat) {
+	if (typeof stat.isFile === "function" && typeof stat.isDirectory === "function") return stat;
+	const kind = stat.kind ?? stat.type;
+	if (kind === "file" || kind === "directory") return new StorageFileStat(kind);
+	throw createPathError("EINVAL", "Storage stat must provide kind/type or isFile()/isDirectory().");
+}
+async function inferStat(storage, filePath) {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat("directory");
+	} catch {}
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat("file");
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat("file");
+		} catch {
+			throw createPathError("ENOENT", `Storage path not found: ${filePath}`);
+		}
+	}
+}
+function createBackendStorageFileSystem(storage) {
+	const lockedPaths = /* @__PURE__ */ new Set();
+	const fileSystem = {
+		stat(filePath) {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath) {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath) {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath) {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath, content) {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath, data) {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath, options) {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath) {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath) {
+			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);
+				}
+			};
+		},
+		unlink(filePath) {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			if (storage.unlink) return storage.unlink(resolved);
+			throw createPathError("ENOTSUP", "Storage adapter does not provide unlink().");
+		},
+		join(...paths) {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath) {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths) {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		}
+	};
+	return fileSystem;
+}
+//#endregion
+export { BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, BackendRuntime, createBackendStorageFileSystem };

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--ytGfQCF.cjs");
+const require_runtime = require("./runtime-YK3ACpuQ.cjs");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_path = require("node:path");

package/dist/node.d.cts

@@ -1,4 +1,4 @@
-import { D as BackendRuntime, O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, m as BackendFileStat, p as BackendFileHandle } from "./runtime-DlM27Izm.cjs";
+import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-DziTGugy.cjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { D as BackendRuntime, O as BackendRuntimeOptions, g as BackendHostAdapter, h as BackendFileSystem, m as BackendFileStat, p as BackendFileHandle } from "./runtime-BPuZITUC.mjs";
+import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-Bydxr_SN.mjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { t as BackendRuntime } from "./runtime-CqARWlcn.mjs";
+import { t as BackendRuntime } from "./runtime-Cn0O-wZt.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/node.ts

package/dist/{runtime-BPuZITUC.d.mts → runtime-Bydxr_SN.d.mts}

@@ -97,6 +97,12 @@ interface BackendCapabilityManifest {
       injected: true;
       requiredFor: readonly ['openSession', 'saveSession'];
     };
+    projectStorage: {
+      injected: true;
+      browserSafe: true;
+      requiredFor: readonly ['openProjectSession.writeback', 'saveSession'];
+      adapterFactory: 'createBackendStorageFileSystem';
+    };
     host: {
       injected: true;
       requiredFor: readonly ['advisoryLockMetadata'];
@@ -384,6 +390,19 @@ interface OpenProjectSessionInput {
   sessionId?: string;
   canonicalProjectPath?: string;
   canonicalPathKey?: string;
+  storage?: BackendProjectSessionStorage;
+}
+interface BackendProjectSessionStorage {
+  fileSystem: BackendFileSystem;
+  fairyPath: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface SaveSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
 }
 interface BackendRuntimeOptions {
   fileSystem?: BackendFileSystem;
@@ -415,11 +434,7 @@ declare class BackendRuntime {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
-  saveSession(input: {
-    sessionId: string;
-    expectedRevision?: number;
-    targetPath?: string;
-  }): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
+  saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
   closeSession(input: {
     sessionId: string;
   }): Promise<BackendResult<{
@@ -434,4 +449,4 @@ declare class BackendRuntime {
   refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
 }
 //#endregion
-export { BackendSuccess as A, OpenProjectSessionInput as B, BackendJobProgress as C, BackendRuntime as D, BackendResult as E, GetEventsInput as F, BACKEND_CAPABILITY_SCHEMA_VERSION as G, SavePartialFailureError as H, GetEventsSnapshot as I, BackendDiagnostic as J, BACKEND_COMPATIBILITY_POLICY as K, GetJobInput as L, CancelJobInput as M, EventCursorInvalidError as N, BackendRuntimeOptions as O, GetCacheSnapshotInput as P, InProcessLockConflictError as R, BackendJobNotFoundError as S, BackendJobStatus as T, SessionNotFoundError as U, RefreshCacheInput as V, SessionStaleWriteError as W, BackendResponseMeta as X, BackendMessage as Y, BackendStage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, CacheRefreshFailedError as j, BackendSessionSnapshot as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CONTRACT_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, ListJobsInput as z };
+export { BackendStage as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobProgress as C, BackendResult as D, BackendProjectSessionStorage as E, GetCacheSnapshotInput as F, SessionNotFoundError as G, RefreshCacheInput as H, GetEventsInput as I, BACKEND_COMPATIBILITY_POLICY as J, SessionStaleWriteError as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendRuntime as O, EventCursorInvalidError as P, BackendResponseMeta as Q, GetJobInput as R, BackendJobNotFoundError as S, BackendJobStatus as T, SavePartialFailureError as U, OpenProjectSessionInput as V, SaveSessionInput as W, BackendDiagnostic as X, BACKEND_CONTRACT_VERSION as Y, BackendMessage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, BackendSuccess as j, BackendRuntimeOptions as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CAPABILITY_SCHEMA_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, InProcessLockConflictError as z };

package/dist/{runtime-CqARWlcn.mjs → runtime-Cn0O-wZt.mjs}

@@ -331,7 +331,8 @@ var AuthoringService = class {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
-		if (!this.context.fileSystem) return failure("authoring", startedAt, {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, {
 			code: "capability_unavailable",
 			message: "saveSession requires an injected BackendFileSystem adapter.",
 			capability: "fileSystem",
@@ -344,7 +345,6 @@ var AuthoringService = class {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
@@ -908,6 +908,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -946,8 +947,10 @@ var RuntimeService = class {
 	openProjectSession(input) {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
-		const canonicalProjectPath = input.canonicalProjectPath ?? `memory://${sessionId}`;
-		const canonicalPathKey = input.canonicalPathKey ?? canonicalProjectPath.toLowerCase();
+		const storage = input.storage;
+		const memoryProjectPath = `memory://${sessionId}`;
+		const canonicalProjectPath = storage?.canonicalProjectPath ?? input.canonicalProjectPath ?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || "." : memoryProjectPath);
+		const canonicalPathKey = storage?.canonicalPathKey ?? input.canonicalPathKey ?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) return failure("runtime", startedAt, {
 			code: "lock_conflict",
@@ -958,10 +961,11 @@ var RuntimeService = class {
 		});
 		const session = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
+			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
@@ -1075,6 +1079,12 @@ function createCapabilities() {
 					injected: true,
 					requiredFor: ["openSession", "saveSession"]
 				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: ["openProjectSession.writeback", "saveSession"],
+					adapterFactory: "createBackendStorageFileSystem"
+				},
 				host: {
 					injected: true,
 					requiredFor: ["advisoryLockMetadata"]

package/dist/{runtime-DlM27Izm.d.cts → runtime-DziTGugy.d.cts}

@@ -97,6 +97,12 @@ interface BackendCapabilityManifest {
       injected: true;
       requiredFor: readonly ['openSession', 'saveSession'];
     };
+    projectStorage: {
+      injected: true;
+      browserSafe: true;
+      requiredFor: readonly ['openProjectSession.writeback', 'saveSession'];
+      adapterFactory: 'createBackendStorageFileSystem';
+    };
     host: {
       injected: true;
       requiredFor: readonly ['advisoryLockMetadata'];
@@ -384,6 +390,19 @@ interface OpenProjectSessionInput {
   sessionId?: string;
   canonicalProjectPath?: string;
   canonicalPathKey?: string;
+  storage?: BackendProjectSessionStorage;
+}
+interface BackendProjectSessionStorage {
+  fileSystem: BackendFileSystem;
+  fairyPath: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface SaveSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
 }
 interface BackendRuntimeOptions {
   fileSystem?: BackendFileSystem;
@@ -415,11 +434,7 @@ declare class BackendRuntime {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
-  saveSession(input: {
-    sessionId: string;
-    expectedRevision?: number;
-    targetPath?: string;
-  }): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
+  saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
   closeSession(input: {
     sessionId: string;
   }): Promise<BackendResult<{
@@ -434,4 +449,4 @@ declare class BackendRuntime {
   refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
 }
 //#endregion
-export { BackendSuccess as A, OpenProjectSessionInput as B, BackendJobProgress as C, BackendRuntime as D, BackendResult as E, GetEventsInput as F, BACKEND_CAPABILITY_SCHEMA_VERSION as G, SavePartialFailureError as H, GetEventsSnapshot as I, BackendDiagnostic as J, BACKEND_COMPATIBILITY_POLICY as K, GetJobInput as L, CancelJobInput as M, EventCursorInvalidError as N, BackendRuntimeOptions as O, GetCacheSnapshotInput as P, InProcessLockConflictError as R, BackendJobNotFoundError as S, BackendJobStatus as T, SessionNotFoundError as U, RefreshCacheInput as V, SessionStaleWriteError as W, BackendResponseMeta as X, BackendMessage as Y, BackendStage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, CacheRefreshFailedError as j, BackendSessionSnapshot as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CONTRACT_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, ListJobsInput as z };
+export { BackendStage as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobProgress as C, BackendResult as D, BackendProjectSessionStorage as E, GetCacheSnapshotInput as F, SessionNotFoundError as G, RefreshCacheInput as H, GetEventsInput as I, BACKEND_COMPATIBILITY_POLICY as J, SessionStaleWriteError as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendRuntime as O, EventCursorInvalidError as P, BackendResponseMeta as Q, GetJobInput as R, BackendJobNotFoundError as S, BackendJobStatus as T, SavePartialFailureError as U, OpenProjectSessionInput as V, SaveSessionInput as W, BackendDiagnostic as X, BACKEND_CONTRACT_VERSION as Y, BackendMessage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, BackendSuccess as j, BackendRuntimeOptions as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CAPABILITY_SCHEMA_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, InProcessLockConflictError as z };

package/dist/{runtime--ytGfQCF.cjs → runtime-YK3ACpuQ.cjs}

@@ -332,7 +332,8 @@ var AuthoringService = class {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
-		if (!this.context.fileSystem) return failure("authoring", startedAt, {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, {
 			code: "capability_unavailable",
 			message: "saveSession requires an injected BackendFileSystem adapter.",
 			capability: "fileSystem",
@@ -345,7 +346,6 @@ var AuthoringService = class {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
@@ -909,6 +909,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -947,8 +948,10 @@ var RuntimeService = class {
 	openProjectSession(input) {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
-		const canonicalProjectPath = input.canonicalProjectPath ?? `memory://${sessionId}`;
-		const canonicalPathKey = input.canonicalPathKey ?? canonicalProjectPath.toLowerCase();
+		const storage = input.storage;
+		const memoryProjectPath = `memory://${sessionId}`;
+		const canonicalProjectPath = storage?.canonicalProjectPath ?? input.canonicalProjectPath ?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || "." : memoryProjectPath);
+		const canonicalPathKey = storage?.canonicalPathKey ?? input.canonicalPathKey ?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) return failure("runtime", startedAt, {
 			code: "lock_conflict",
@@ -959,10 +962,11 @@ var RuntimeService = class {
 		});
 		const session = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
+			fileSystem: storage?.fileSystem,
 			project: (0, _openfairygui_core_uam.normalizeUamProject)(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
@@ -1076,6 +1080,12 @@ function createCapabilities() {
 					injected: true,
 					requiredFor: ["openSession", "saveSession"]
 				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: ["openProjectSession.writeback", "saveSession"],
+					adapterFactory: "createBackendStorageFileSystem"
+				},
 				host: {
 					injected: true,
 					requiredFor: ["advisoryLockMetadata"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.7",
   "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.5",
-    "@openfairygui/functions": "0.2.0-alpha.5"
+    "@openfairygui/core": "0.2.0-alpha.7",
+    "@openfairygui/functions": "0.2.0-alpha.7"
   },
   "devDependencies": {
     "ava": "^7.0.0",

package/src/index.ts

@@ -39,11 +39,19 @@ export {
 	type InProcessLockConflictError,
 	type ListJobsInput,
 	type OpenProjectSessionInput,
+	type BackendProjectSessionStorage,
 	type RefreshCacheInput,
+	type SaveSessionInput,
 	type SavePartialFailureError,
 	type SessionNotFoundError,
 	type SessionStaleWriteError,
 } from './runtime.js';
+export {
+	createBackendStorageFileSystem,
+	type BackendAsyncStorageAdapter,
+	type BackendStorageFileSystem,
+	type BackendStorageStatLike,
+} from './storage.js';
 export {
 	type BackendDiagnostic,
 	type BackendMessage,

package/src/runtime.ts

@@ -68,6 +68,12 @@ export interface BackendCapabilityManifest {
 			injected: true;
 			requiredFor: readonly ['openSession', 'saveSession'];
 		};
+		projectStorage: {
+			injected: true;
+			browserSafe: true;
+			requiredFor: readonly ['openProjectSession.writeback', 'saveSession'];
+			adapterFactory: 'createBackendStorageFileSystem';
+		};
 		host: {
 			injected: true;
 			requiredFor: readonly ['advisoryLockMetadata'];
@@ -438,6 +444,21 @@ export interface OpenProjectSessionInput {
 	sessionId?: string;
 	canonicalProjectPath?: string;
 	canonicalPathKey?: string;
+	storage?: BackendProjectSessionStorage;
+}
+
+export interface BackendProjectSessionStorage {
+	fileSystem: BackendFileSystem;
+	fairyPath: string;
+	canonicalProjectPath?: string;
+	canonicalPathKey?: string;
+}
+
+export interface SaveSessionInput {
+	sessionId: string;
+	expectedRevision?: number;
+	targetPath?: string;
+	fileSystem?: BackendFileSystem;
 }
 
 export interface BackendRuntimeOptions {
@@ -504,6 +525,12 @@ function createCapabilities(): BackendCapabilities {
 					injected: true,
 					requiredFor: ['openSession', 'saveSession'],
 				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: ['openProjectSession.writeback', 'saveSession'],
+					adapterFactory: 'createBackendStorageFileSystem',
+				},
 				host: {
 					injected: true,
 					requiredFor: ['advisoryLockMetadata'],
@@ -628,11 +655,7 @@ export class BackendRuntime {
 		return this.authoringService.applyTransaction(input);
 	}
 
-	public async saveSession(input: {
-		sessionId: string;
-		expectedRevision?: number;
-		targetPath?: string;
-	}): Promise<
+	public async saveSession(input: SaveSessionInput): Promise<
 		BackendResult<
 			BackendSessionSnapshot,
 			| SessionNotFoundError

package/src/services/authoring-service.ts

@@ -10,6 +10,7 @@ import type {
 	BackendFileSystem,
 	BackendResult,
 	BackendSessionSnapshot,
+	SaveSessionInput,
 	SavePartialFailureError,
 	SessionNotFoundError,
 	SessionStaleWriteError,
@@ -180,11 +181,7 @@ export class AuthoringService {
 		});
 	}
 
-	public async saveSession(input: {
-		sessionId: string;
-		expectedRevision?: number;
-		targetPath?: string;
-	}): Promise<
+	public async saveSession(input: SaveSessionInput): Promise<
 		BackendResult<
 			BackendSessionSnapshot,
 			| SessionNotFoundError
@@ -199,7 +196,8 @@ export class AuthoringService {
 		if (!session || session.closed) {
 			return failure('authoring', startedAt, createSessionNotFoundError(input.sessionId));
 		}
-		if (!this.context.fileSystem) {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) {
 			return failure(
 				'authoring',
 				startedAt,
@@ -228,7 +226,6 @@ export class AuthoringService {
 				},
 			);
 		}
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) {
 			return failure(

package/src/services/context.ts

@@ -25,6 +25,7 @@ export interface BackendSessionState {
 	canonicalProjectPath: string;
 	canonicalPathKey: string;
 	lockFilePath: string;
+	fileSystem?: BackendFileSystem;
 	project: import('@openfairygui/core/uam').UamProject;
 	revision: number;
 	lastSavedRevision: number;

package/src/services/runtime-service.ts

@@ -14,7 +14,7 @@ import type {
 	OpenProjectSessionInput,
 	SessionNotFoundError,
 } from '../runtime.js';
-import { resolveCanonicalProjectRoot } from '../path-policy.js';
+import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
 
 function randomId(): string {
@@ -137,6 +137,7 @@ export class RuntimeService {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -174,8 +175,14 @@ export class RuntimeService {
 	public openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot> {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
-		const canonicalProjectPath = input.canonicalProjectPath ?? `memory://${sessionId}`;
-		const canonicalPathKey = input.canonicalPathKey ?? canonicalProjectPath.toLowerCase();
+		const storage = input.storage;
+		const memoryProjectPath = `memory://${sessionId}`;
+		const canonicalProjectPath = storage?.canonicalProjectPath
+			?? input.canonicalProjectPath
+			?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || '.' : memoryProjectPath);
+		const canonicalPathKey = storage?.canonicalPathKey
+			?? input.canonicalPathKey
+			?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) {
 			return failure('runtime', startedAt, {
@@ -189,10 +196,11 @@ export class RuntimeService {
 
 		const session: BackendSessionState = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: '',
+			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
 			revision: 0,
 			lastSavedRevision: 0,

package/src/storage.ts

@@ -0,0 +1,192 @@
+import type { FileSystem as CoreProjectFileSystem } from '@openfairygui/core/project-io';
+import type { BackendFileHandle, BackendFileStat, BackendFileSystem } from './runtime.js';
+
+type StorageStatKind = 'file' | 'directory';
+
+export interface BackendStorageStatLike {
+	kind?: StorageStatKind;
+	type?: StorageStatKind;
+	isFile?(): boolean;
+	isDirectory?(): boolean;
+}
+
+export interface BackendAsyncStorageAdapter {
+	readFile(filePath: string): Promise<string>;
+	readFileRaw(filePath: string): Promise<Uint8Array>;
+	writeFile(filePath: string, content: string): Promise<void>;
+	writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+	mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void>;
+	readdir(dirPath: string): Promise<string[]>;
+	exists?(filePath: string): Promise<boolean>;
+	stat?(filePath: string): Promise<BackendStorageStatLike>;
+	resolvePath?(filePath: string): Promise<string>;
+	openExclusive?(filePath: string): Promise<BackendFileHandle>;
+	unlink?(filePath: string): Promise<void>;
+	join?(...paths: string[]): string;
+	dirname?(filePath: string): string;
+	resolve?(...paths: string[]): string;
+}
+
+class StorageFileStat implements BackendFileStat {
+	public constructor(private readonly kind: StorageStatKind) {}
+
+	public isFile(): boolean {
+		return this.kind === 'file';
+	}
+
+	public isDirectory(): boolean {
+		return this.kind === 'directory';
+	}
+}
+
+function createPathError(code: string, message: string): Error & { code: string } {
+	const error = new Error(message) as Error & { code: string };
+	error.code = code;
+	return error;
+}
+
+function normalizeStoragePath(value: string): string {
+	const normalized = value.replace(/\\/g, '/').replace(/\/+/g, '/');
+	const absolute = normalized.startsWith('/');
+	const rawSegments = normalized.split('/').filter((segment) => segment.length > 0);
+	const segments: string[] = [];
+
+	for (const segment of rawSegments) {
+		if (segment === '.') continue;
+		if (segment === '..') {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+
+	const joined = segments.join('/');
+	if (absolute) return joined ? `/${joined}` : '/';
+	return joined || '.';
+}
+
+function joinStoragePath(...paths: string[]): string {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join('/'));
+}
+
+function dirnameStoragePath(filePath: string): string {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === '/' || normalized === '.') return '.';
+	const absolute = normalized.startsWith('/');
+	const parts = normalized.split('/').filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? '/' : '.';
+	return `${absolute ? '/' : ''}${parts.join('/')}`;
+}
+
+function statFromLike(stat: BackendStorageStatLike): BackendFileStat {
+	if (typeof stat.isFile === 'function' && typeof stat.isDirectory === 'function') {
+		return stat as BackendFileStat;
+	}
+	const kind = stat.kind ?? stat.type;
+	if (kind === 'file' || kind === 'directory') return new StorageFileStat(kind);
+	throw createPathError('EINVAL', 'Storage stat must provide kind/type or isFile()/isDirectory().');
+}
+
+async function inferStat(storage: BackendAsyncStorageAdapter, filePath: string): Promise<BackendFileStat> {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat('directory');
+	} catch {
+		// Try file probes below.
+	}
+
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat('file');
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat('file');
+		} catch {
+			throw createPathError('ENOENT', `Storage path not found: ${filePath}`);
+		}
+	}
+}
+
+export type BackendStorageFileSystem = BackendFileSystem & CoreProjectFileSystem;
+
+export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem {
+	const lockedPaths = new Set<string>();
+
+	const fileSystem: BackendStorageFileSystem = {
+		stat(filePath: string): Promise<BackendFileStat> {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath: string): Promise<string[]> {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath: string): Promise<string> {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath: string): Promise<Uint8Array> {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath: string, content: string): Promise<void> {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath: string): Promise<boolean> {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath: string): Promise<string> {
+			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}`);
+			}
+			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);
+				},
+			};
+		},
+		unlink(filePath: string): Promise<void> {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			if (storage.unlink) return storage.unlink(resolved);
+			throw createPathError('ENOTSUP', 'Storage adapter does not provide unlink().');
+		},
+		join(...paths: string[]): string {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath: string): string {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths: string[]): string {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		},
+	};
+
+	return fileSystem;
+}