@openfairygui/backend 0.2.0-alpha.13 → 0.2.0-alpha.14

package/README.md

@@ -34,7 +34,11 @@ 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: 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`.
+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
+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.
 
 ## Relationship to other packages
 
@@ -73,6 +77,7 @@ const fileSystem = createBackendStorageFileSystem({
 	async mkdir(dirPath) { await storage.mkdir(dirPath); },
 	async readdir(dirPath) { return storage.readdir(dirPath); },
 	async exists(filePath) { return storage.exists(filePath); },
+	async unlink(filePath) { await storage.remove(filePath); },
 });
 
 const runtime = new BackendRuntime();

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runtime = require("./runtime-GKzsXJdO.cjs");
+const require_runtime = require("./runtime-DqApG30C.cjs");
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {
@@ -71,6 +71,7 @@ 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.");
 	const lockedPaths = /* @__PURE__ */ new Set();
 	const fileSystem = {
 		stat(filePath) {
@@ -128,8 +129,7 @@ function createBackendStorageFileSystem(storage) {
 		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().");
+			return storage.unlink(resolved);
 		},
 		join(...paths) {
 			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);

package/dist/index.d.cts

@@ -22,7 +22,7 @@ interface BackendAsyncStorageAdapter {
   stat?(filePath: string): Promise<BackendStorageStatLike>;
   resolvePath?(filePath: string): Promise<string>;
   openExclusive?(filePath: string): Promise<BackendFileHandle>;
-  unlink?(filePath: string): Promise<void>;
+  unlink(filePath: string): Promise<void>;
   join?(...paths: string[]): string;
   dirname?(filePath: string): string;
   resolve?(...paths: string[]): string;

package/dist/index.d.mts

@@ -22,7 +22,7 @@ interface BackendAsyncStorageAdapter {
   stat?(filePath: string): Promise<BackendStorageStatLike>;
   resolvePath?(filePath: string): Promise<string>;
   openExclusive?(filePath: string): Promise<BackendFileHandle>;
-  unlink?(filePath: string): Promise<void>;
+  unlink(filePath: string): Promise<void>;
   join?(...paths: string[]): string;
   dirname?(filePath: string): string;
   resolve?(...paths: string[]): string;

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-DFatY9W0.mjs";
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-B9z0n2yF.mjs";
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {
@@ -70,6 +70,7 @@ 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.");
 	const lockedPaths = /* @__PURE__ */ new Set();
 	const fileSystem = {
 		stat(filePath) {
@@ -127,8 +128,7 @@ function createBackendStorageFileSystem(storage) {
 		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().");
+			return storage.unlink(resolved);
 		},
 		join(...paths) {
 			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);

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-GKzsXJdO.cjs");
+const require_runtime = require("./runtime-DqApG30C.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.mjs

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

package/dist/{runtime-DFatY9W0.mjs → runtime-B9z0n2yF.mjs}

@@ -1,4 +1,4 @@
-import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, liftDocumentToUamProject, materializeUamProject, normalizeUamProject, validateUamProject } from "@openfairygui/core/uam";
+import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, commitUamProjectSourcePaths, liftDocumentToUamProject, materializeUamProject, normalizeUamProject, validateUamProject } from "@openfairygui/core/uam";
 import { ProjectReader, ProjectWriter } from "@openfairygui/core/project-io";
 import { applyUamTransactionApp } from "@openfairygui/functions/uam";
 //#region src/contracts.ts
@@ -251,9 +251,45 @@ function createWriterFileSystem(fileSystem, committedPaths, failedPaths) {
 		},
 		dirname(filePath) {
 			return fileSystem.dirname(filePath);
+		},
+		async unlink(filePath) {
+			await trackWrite(filePath, () => fileSystem.unlink(filePath));
 		}
 	};
 }
+function projectAssetSourceFiles(project) {
+	const result = /* @__PURE__ */ new Map();
+	for (const pkg of project.packages) for (const resource of pkg.resources) {
+		if (resource.kind === "component") continue;
+		const fileName = resource.fileName ?? resource.file ?? "";
+		if (!fileName) continue;
+		result.set(`${pkg.id}/${resource.id}`, {
+			packageName: pkg.name,
+			branch: resource.branch,
+			path: resource.path,
+			fileName
+		});
+	}
+	return result;
+}
+function sourceFileKey(source) {
+	return [
+		source.branch,
+		source.packageName,
+		source.path,
+		source.fileName
+	].join("\0");
+}
+function recordStaleResourceSources(session, previousProject, nextProject) {
+	if (!session.fileSystem) return;
+	const previousSources = projectAssetSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectAssetSourceFiles(nextProject).values()].map(sourceFileKey));
+	for (const source of previousSources.values()) {
+		const key = sourceFileKey(source);
+		if (!nextSourceKeys.has(key)) session.pendingStaleSourceFiles.set(key, source);
+	}
+	for (const key of nextSourceKeys) session.pendingStaleSourceFiles.delete(key);
+}
 function toBackendDiagnostics(error) {
 	return error.diagnostics.length > 0 ? error.diagnostics.map((diagnostic) => ({ ...diagnostic })) : [{
 		code: error.code,
@@ -343,6 +379,7 @@ var AuthoringService = class {
 				diagnostics
 			});
 		}
+		recordStaleResourceSources(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -377,7 +414,7 @@ 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));
-		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		const fileSystem = session.fileSystem ?? input.fileSystem ?? this.context.fileSystem;
 		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("saveSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
 			revision: session.revision
@@ -404,7 +441,10 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write(materializeUamProject(session.project), session.fairyPath);
+			await new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write(materializeUamProject(session.project), session.fairyPath, { staleSourceFiles: [...session.pendingStaleSourceFiles.values()] });
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			commitUamProjectSourcePaths(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -528,7 +568,12 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths)).write(document, fairyPath);
+			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths));
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writer.write(document, fairyPath, { staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [] });
+			if (isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (storageTarget && !isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (isSessionStorageTarget || storageTarget) commitUamProjectSourcePaths(session.project);
 			if (storageTarget) {
 				this.context.sessionsByPath.delete(session.canonicalPathKey);
 				session.fileSystem = storageTarget.fileSystem;
@@ -1089,7 +1134,7 @@ var RuntimeService = class {
 				canonicalPathKey
 			}));
 			await advisoryLock.close();
-			const project = liftDocumentToUamProject(await new ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath));
+			const project = liftDocumentToUamProject(await new ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true }));
 			const sessionId = randomId();
 			const session = {
 				sessionId,
@@ -1101,6 +1146,7 @@ var RuntimeService = class {
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false
@@ -1158,6 +1204,7 @@ var RuntimeService = class {
 			project: normalizeUamProject(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false

package/dist/{runtime-GKzsXJdO.cjs → runtime-DqApG30C.cjs}

@@ -252,9 +252,45 @@ function createWriterFileSystem(fileSystem, committedPaths, failedPaths) {
 		},
 		dirname(filePath) {
 			return fileSystem.dirname(filePath);
+		},
+		async unlink(filePath) {
+			await trackWrite(filePath, () => fileSystem.unlink(filePath));
 		}
 	};
 }
+function projectAssetSourceFiles(project) {
+	const result = /* @__PURE__ */ new Map();
+	for (const pkg of project.packages) for (const resource of pkg.resources) {
+		if (resource.kind === "component") continue;
+		const fileName = resource.fileName ?? resource.file ?? "";
+		if (!fileName) continue;
+		result.set(`${pkg.id}/${resource.id}`, {
+			packageName: pkg.name,
+			branch: resource.branch,
+			path: resource.path,
+			fileName
+		});
+	}
+	return result;
+}
+function sourceFileKey(source) {
+	return [
+		source.branch,
+		source.packageName,
+		source.path,
+		source.fileName
+	].join("\0");
+}
+function recordStaleResourceSources(session, previousProject, nextProject) {
+	if (!session.fileSystem) return;
+	const previousSources = projectAssetSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectAssetSourceFiles(nextProject).values()].map(sourceFileKey));
+	for (const source of previousSources.values()) {
+		const key = sourceFileKey(source);
+		if (!nextSourceKeys.has(key)) session.pendingStaleSourceFiles.set(key, source);
+	}
+	for (const key of nextSourceKeys) session.pendingStaleSourceFiles.delete(key);
+}
 function toBackendDiagnostics(error) {
 	return error.diagnostics.length > 0 ? error.diagnostics.map((diagnostic) => ({ ...diagnostic })) : [{
 		code: error.code,
@@ -344,6 +380,7 @@ var AuthoringService = class {
 				diagnostics
 			});
 		}
+		recordStaleResourceSources(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -378,7 +415,7 @@ 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));
-		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		const fileSystem = session.fileSystem ?? input.fileSystem ?? this.context.fileSystem;
 		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("saveSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
 			revision: session.revision
@@ -405,7 +442,10 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write((0, _openfairygui_core_uam.materializeUamProject)(session.project), session.fairyPath);
+			await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write((0, _openfairygui_core_uam.materializeUamProject)(session.project), session.fairyPath, { staleSourceFiles: [...session.pendingStaleSourceFiles.values()] });
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			(0, _openfairygui_core_uam.commitUamProjectSourcePaths)(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -529,7 +569,12 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths)).write(document, fairyPath);
+			const writer = new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths));
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writer.write(document, fairyPath, { staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [] });
+			if (isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (storageTarget && !isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (isSessionStorageTarget || storageTarget) (0, _openfairygui_core_uam.commitUamProjectSourcePaths)(session.project);
 			if (storageTarget) {
 				this.context.sessionsByPath.delete(session.canonicalPathKey);
 				session.fileSystem = storageTarget.fileSystem;
@@ -1090,7 +1135,7 @@ var RuntimeService = class {
 				canonicalPathKey
 			}));
 			await advisoryLock.close();
-			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath));
+			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true }));
 			const sessionId = randomId();
 			const session = {
 				sessionId,
@@ -1102,6 +1147,7 @@ var RuntimeService = class {
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false
@@ -1159,6 +1205,7 @@ var RuntimeService = class {
 			project: (0, _openfairygui_core_uam.normalizeUamProject)(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false

package/package.json

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

package/src/services/authoring-service.ts

@@ -1,5 +1,5 @@
-import { ProjectWriter, type FileSystem } from '@openfairygui/core/project-io';
-import { materializeUamProject, validateUamProject } from '@openfairygui/core/uam';
+import { ProjectWriter, type FileSystem, type ProjectSourceFile } from '@openfairygui/core/project-io';
+import { commitUamProjectSourcePaths, materializeUamProject, validateUamProject, type UamProject } from '@openfairygui/core/uam';
 import { applyUamTransactionApp, type ApplyUamTransactionAppError } from '@openfairygui/functions/uam';
 import type { CacheService } from './cache-service.js';
 import { failure, success, type BackendContext } from './context.js';
@@ -79,9 +79,49 @@ function createWriterFileSystem(
 		dirname(filePath: string): string {
 			return fileSystem.dirname(filePath);
 		},
+		async unlink(filePath: string): Promise<void> {
+			await trackWrite(filePath, () => fileSystem.unlink(filePath));
+		},
 	};
 }
 
+function projectAssetSourceFiles(project: UamProject): Map<string, ProjectSourceFile> {
+	const result = new Map<string, ProjectSourceFile>();
+	for (const pkg of project.packages) {
+		for (const resource of pkg.resources) {
+			if (resource.kind === 'component') continue;
+			const fileName = resource.fileName ?? resource.file ?? '';
+			if (!fileName) continue;
+			result.set(
+				`${pkg.id}/${resource.id}`,
+				{ packageName: pkg.name, branch: resource.branch, path: resource.path, fileName },
+			);
+		}
+	}
+	return result;
+}
+
+function sourceFileKey(source: ProjectSourceFile): string {
+	return [source.branch, source.packageName, source.path, source.fileName].join('\0');
+}
+
+function recordStaleResourceSources(
+	session: Parameters<typeof toSessionSnapshot>[0],
+	previousProject: UamProject,
+	nextProject: UamProject,
+): void {
+	if (!session.fileSystem) return;
+	const previousSources = projectAssetSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectAssetSourceFiles(nextProject).values()].map(sourceFileKey));
+	for (const source of previousSources.values()) {
+		const key = sourceFileKey(source);
+		if (!nextSourceKeys.has(key)) session.pendingStaleSourceFiles.set(key, source);
+	}
+	for (const key of nextSourceKeys) {
+		session.pendingStaleSourceFiles.delete(key);
+	}
+}
+
 function toBackendDiagnostics(error: ApplyUamTransactionAppError): BackendDiagnostic[] {
 	return error.diagnostics.length > 0
 		? error.diagnostics.map((diagnostic) => ({ ...diagnostic }))
@@ -219,6 +259,7 @@ export class AuthoringService {
 			);
 		}
 
+		recordStaleResourceSources(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -271,7 +312,7 @@ export class AuthoringService {
 		if (!session || session.closed) {
 			return failure('authoring', startedAt, createSessionNotFoundError(input.sessionId));
 		}
-		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		const fileSystem = session.fileSystem ?? input.fileSystem ?? this.context.fileSystem;
 		if (!fileSystem) {
 			return failure(
 				'authoring',
@@ -328,7 +369,12 @@ export class AuthoringService {
 		});
 		try {
 			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths));
-			await writer.write(materializeUamProject(session.project), session.fairyPath);
+			await writer.write(materializeUamProject(session.project), session.fairyPath, {
+				staleSourceFiles: [...session.pendingStaleSourceFiles.values()],
+			});
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			commitUamProjectSourcePaths(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -530,7 +576,13 @@ export class AuthoringService {
 		});
 		try {
 			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths));
-			await writer.write(document, fairyPath);
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writer.write(document, fairyPath, {
+				staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [],
+			});
+			if (isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (storageTarget && !isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (isSessionStorageTarget || storageTarget) commitUamProjectSourcePaths(session.project);
 			if (storageTarget) {
 				this.context.sessionsByPath.delete(session.canonicalPathKey);
 				session.fileSystem = storageTarget.fileSystem;

package/src/services/context.ts

@@ -29,6 +29,8 @@ export interface BackendSessionState {
 	project: import('@openfairygui/core/uam').UamProject;
 	revision: number;
 	lastSavedRevision: number;
+	/** Source files deferred until a successful replacement project write. */
+	pendingStaleSourceFiles: Map<string, import('@openfairygui/core/project-io').ProjectSourceFile>;
 	dirty: boolean;
 	lockHeld: boolean;
 	closed: boolean;

package/src/services/runtime-service.ts

@@ -129,7 +129,7 @@ export class RuntimeService {
 			await advisoryLock.close();
 
 			const reader = new ProjectReader(createProjectReaderFileSystem(fileSystem));
-			const project = liftDocumentToUamProject(await reader.read(fairyPath));
+			const project = liftDocumentToUamProject(await reader.read(fairyPath, { hydrateResourceBytes: true }));
 			const sessionId = randomId();
 			const session: BackendSessionState = {
 				sessionId,
@@ -141,6 +141,7 @@ export class RuntimeService {
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false,
@@ -204,6 +205,7 @@ export class RuntimeService {
 			project: normalizeUamProject(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false,

package/src/storage.ts

@@ -21,7 +21,7 @@ export interface BackendAsyncStorageAdapter {
 	stat?(filePath: string): Promise<BackendStorageStatLike>;
 	resolvePath?(filePath: string): Promise<string>;
 	openExclusive?(filePath: string): Promise<BackendFileHandle>;
-	unlink?(filePath: string): Promise<void>;
+	unlink(filePath: string): Promise<void>;
 	join?(...paths: string[]): string;
 	dirname?(filePath: string): string;
 	resolve?(...paths: string[]): string;
@@ -114,6 +114,9 @@ async function inferStat(storage: BackendAsyncStorageAdapter, filePath: string):
 export type BackendStorageFileSystem = BackendFileSystem & CoreProjectFileSystem;
 
 export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem {
+	if (typeof storage.unlink !== 'function') {
+		throw createPathError('ENOTSUP', 'Storage adapter must provide unlink() for project resource lifecycle writes.');
+	}
 	const lockedPaths = new Set<string>();
 
 	const fileSystem: BackendStorageFileSystem = {
@@ -174,8 +177,7 @@ export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapt
 		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().');
+			return storage.unlink(resolved);
 		},
 		join(...paths: string[]): string {
 			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);