@openfairygui/backend 0.2.0 → 0.3.0-alpha.1

package/README.md

@@ -28,6 +28,7 @@ It also provides:
 - polling runtime events with per-runtime monotonic sequence and bounded retention
 - `cache.refresh` in-memory jobs with cooperative cancel and terminal retention
 - revision-bound derived read-only cache snapshots
+- revision-bound project identity outlines for transaction planning
 - explicit Node bridge boundaries for publish/restore
 
 It does **not** redefine transaction grammar or expose `Document`.
@@ -67,6 +68,9 @@ const runtime = new BackendRuntime();
 const opened = runtime.openProjectSession({ project: uamProject });
 if (!opened.ok) throw new Error(opened.error.message);
 
+const outline = runtime.getProjectOutline({ sessionId: opened.data.sessionId });
+if (!outline.ok) throw new Error(outline.error.message);
+
 const applied = await runtime.applyTransaction({
 	sessionId: opened.data.sessionId,
 	expectedRevision: opened.data.revision,

package/dist/index.cjs

@@ -1051,6 +1051,48 @@ var JobService = class {
 };
 //#endregion
 //#region src/services/read-service.ts
+function toProjectOutline(session) {
+	const project = session.project;
+	return {
+		sessionId: session.sessionId,
+		revision: session.revision,
+		projectId: project.projectId,
+		projectType: project.projectType,
+		version: project.version,
+		branches: [...project.branches],
+		packages: project.packages.map((pkg) => ({
+			id: pkg.id,
+			name: pkg.name,
+			branchNames: [...pkg.branchNames],
+			folders: pkg.folders.map((folder) => ({
+				branch: folder.branch,
+				path: folder.path
+			})),
+			resources: pkg.resources.map((resource) => ({
+				id: resource.id,
+				name: resource.name,
+				path: resource.path,
+				kind: resource.kind,
+				branch: resource.branch,
+				...resource.kind === "component" ? { component: {
+					displayList: resource.component.displayList.map((node) => ({
+						id: node.id,
+						name: node.name,
+						kind: node.kind
+					})),
+					controllers: resource.component.controllers.map((controller) => ({
+						name: controller.name,
+						pages: controller.pages.map((page) => ({
+							id: page.id,
+							name: page.name
+						}))
+					})),
+					transitions: resource.component.transitions.map((transition) => ({ name: transition.name }))
+				} } : {}
+			}))
+		}))
+	};
+}
 var ReadService = class {
 	constructor(context) {
 		this.context = context;
@@ -1067,6 +1109,15 @@ var ReadService = class {
 			revision: session.revision
 		});
 	}
+	getProjectOutline(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		return success("read", startedAt, toProjectOutline(session), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
 };
 //#endregion
 //#region src/services/runtime-service.ts
@@ -1380,6 +1431,7 @@ const BACKEND_METHODS = [
 	"openSession",
 	"openProjectSession",
 	"getSession",
+	"getProjectOutline",
 	"applyTransaction",
 	"saveSession",
 	"materializeSession",
@@ -1408,7 +1460,8 @@ function createCapabilities() {
 		methods: BACKEND_METHODS,
 		read: {
 			capabilitySnapshot: true,
-			sessionSnapshot: true
+			sessionSnapshot: true,
+			projectOutline: true
 		},
 		authoring: {
 			applyTransaction: true,
@@ -1548,6 +1601,9 @@ var BackendRuntime = class {
 	getSession(input) {
 		return this.readService.getSession(input);
 	}
+	getProjectOutline(input) {
+		return this.readService.getProjectOutline(input);
+	}
 	async applyTransaction(input) {
 		return this.authoringService.applyTransaction(input);
 	}

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
-import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { UamDisplayNodeKind, UamProject, UamResource, UamTransactionOperation } from "@openfairygui/core/uam";
 import { FileSystem } from "@openfairygui/core/project-io";
 
 //#region src/contracts.d.ts
@@ -130,10 +130,11 @@ interface BackendCapabilities {
   transactionKernelOwner: '@openfairygui/core';
   appSeamOwner: '@openfairygui/functions';
   runtimeOwner: '@openfairygui/backend';
-  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'getProjectOutline', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
   read: {
     capabilitySnapshot: true;
     sessionSnapshot: true;
+    projectOutline: true;
   };
   authoring: {
     applyTransaction: true;
@@ -202,6 +203,49 @@ interface BackendSessionSnapshot {
   lockHeld: boolean;
   capabilities: BackendCapabilities;
 }
+interface BackendProjectOutline {
+  sessionId: string;
+  revision: number;
+  projectId: string;
+  projectType: number;
+  version: string;
+  branches: string[];
+  packages: BackendProjectOutlinePackage[];
+}
+interface BackendProjectOutlinePackage {
+  id: string;
+  name: string;
+  branchNames: string[];
+  folders: Array<{
+    branch: string;
+    path: string;
+  }>;
+  resources: BackendProjectOutlineResource[];
+}
+interface BackendProjectOutlineResource {
+  id: string;
+  name: string;
+  path: string;
+  kind: UamResource['kind'];
+  branch: string;
+  component?: {
+    displayList: Array<{
+      id: string;
+      name: string;
+      kind: UamDisplayNodeKind;
+    }>;
+    controllers: Array<{
+      name: string;
+      pages: Array<{
+        id: string;
+        name: string;
+      }>;
+    }>;
+    transitions: Array<{
+      name: string;
+    }>;
+  };
+}
 interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
   mode: 'fullProject';
   reason?: string;
@@ -427,6 +471,9 @@ interface ApplySessionTransactionInput {
   expectedRevision: number;
   operations: UamTransactionOperation[];
 }
+interface GetProjectOutlineInput {
+  sessionId: string;
+}
 interface OpenProjectSessionInput {
   /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
   project: UamProject;
@@ -490,6 +537,7 @@ declare class BackendRuntime {
   getSession(input: {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
+  getProjectOutline(input: GetProjectOutlineInput): BackendResult<BackendProjectOutline, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
   saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
   materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
@@ -542,4 +590,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 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 };
+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 BackendProjectOutline, type BackendProjectOutlinePackage, type BackendProjectOutlineResource, 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 GetProjectOutlineInput, 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 { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { UamDisplayNodeKind, UamProject, UamResource, UamTransactionOperation } from "@openfairygui/core/uam";
 import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
 import { FileSystem } from "@openfairygui/core/project-io";
 
@@ -130,10 +130,11 @@ interface BackendCapabilities {
   transactionKernelOwner: '@openfairygui/core';
   appSeamOwner: '@openfairygui/functions';
   runtimeOwner: '@openfairygui/backend';
-  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'getProjectOutline', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
   read: {
     capabilitySnapshot: true;
     sessionSnapshot: true;
+    projectOutline: true;
   };
   authoring: {
     applyTransaction: true;
@@ -202,6 +203,49 @@ interface BackendSessionSnapshot {
   lockHeld: boolean;
   capabilities: BackendCapabilities;
 }
+interface BackendProjectOutline {
+  sessionId: string;
+  revision: number;
+  projectId: string;
+  projectType: number;
+  version: string;
+  branches: string[];
+  packages: BackendProjectOutlinePackage[];
+}
+interface BackendProjectOutlinePackage {
+  id: string;
+  name: string;
+  branchNames: string[];
+  folders: Array<{
+    branch: string;
+    path: string;
+  }>;
+  resources: BackendProjectOutlineResource[];
+}
+interface BackendProjectOutlineResource {
+  id: string;
+  name: string;
+  path: string;
+  kind: UamResource['kind'];
+  branch: string;
+  component?: {
+    displayList: Array<{
+      id: string;
+      name: string;
+      kind: UamDisplayNodeKind;
+    }>;
+    controllers: Array<{
+      name: string;
+      pages: Array<{
+        id: string;
+        name: string;
+      }>;
+    }>;
+    transitions: Array<{
+      name: string;
+    }>;
+  };
+}
 interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
   mode: 'fullProject';
   reason?: string;
@@ -427,6 +471,9 @@ interface ApplySessionTransactionInput {
   expectedRevision: number;
   operations: UamTransactionOperation[];
 }
+interface GetProjectOutlineInput {
+  sessionId: string;
+}
 interface OpenProjectSessionInput {
   /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
   project: UamProject;
@@ -490,6 +537,7 @@ declare class BackendRuntime {
   getSession(input: {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
+  getProjectOutline(input: GetProjectOutlineInput): BackendResult<BackendProjectOutline, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
   saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
   materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
@@ -542,4 +590,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 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 };
+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 BackendProjectOutline, type BackendProjectOutlinePackage, type BackendProjectOutlineResource, 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 GetProjectOutlineInput, 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

@@ -1050,6 +1050,48 @@ var JobService = class {
 };
 //#endregion
 //#region src/services/read-service.ts
+function toProjectOutline(session) {
+	const project = session.project;
+	return {
+		sessionId: session.sessionId,
+		revision: session.revision,
+		projectId: project.projectId,
+		projectType: project.projectType,
+		version: project.version,
+		branches: [...project.branches],
+		packages: project.packages.map((pkg) => ({
+			id: pkg.id,
+			name: pkg.name,
+			branchNames: [...pkg.branchNames],
+			folders: pkg.folders.map((folder) => ({
+				branch: folder.branch,
+				path: folder.path
+			})),
+			resources: pkg.resources.map((resource) => ({
+				id: resource.id,
+				name: resource.name,
+				path: resource.path,
+				kind: resource.kind,
+				branch: resource.branch,
+				...resource.kind === "component" ? { component: {
+					displayList: resource.component.displayList.map((node) => ({
+						id: node.id,
+						name: node.name,
+						kind: node.kind
+					})),
+					controllers: resource.component.controllers.map((controller) => ({
+						name: controller.name,
+						pages: controller.pages.map((page) => ({
+							id: page.id,
+							name: page.name
+						}))
+					})),
+					transitions: resource.component.transitions.map((transition) => ({ name: transition.name }))
+				} } : {}
+			}))
+		}))
+	};
+}
 var ReadService = class {
 	constructor(context) {
 		this.context = context;
@@ -1066,6 +1108,15 @@ var ReadService = class {
 			revision: session.revision
 		});
 	}
+	getProjectOutline(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		return success("read", startedAt, toProjectOutline(session), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
 };
 //#endregion
 //#region src/services/runtime-service.ts
@@ -1379,6 +1430,7 @@ const BACKEND_METHODS = [
 	"openSession",
 	"openProjectSession",
 	"getSession",
+	"getProjectOutline",
 	"applyTransaction",
 	"saveSession",
 	"materializeSession",
@@ -1407,7 +1459,8 @@ function createCapabilities() {
 		methods: BACKEND_METHODS,
 		read: {
 			capabilitySnapshot: true,
-			sessionSnapshot: true
+			sessionSnapshot: true,
+			projectOutline: true
 		},
 		authoring: {
 			applyTransaction: true,
@@ -1547,6 +1600,9 @@ var BackendRuntime = class {
 	getSession(input) {
 		return this.readService.getSession(input);
 	}
+	getProjectOutline(input) {
+		return this.readService.getProjectOutline(input);
+	}
 	async applyTransaction(input) {
 		return this.authoringService.applyTransaction(input);
 	}

package/dist/node.cjs

@@ -1076,6 +1076,48 @@ var JobService = class {
 };
 //#endregion
 //#region src/services/read-service.ts
+function toProjectOutline(session) {
+	const project = session.project;
+	return {
+		sessionId: session.sessionId,
+		revision: session.revision,
+		projectId: project.projectId,
+		projectType: project.projectType,
+		version: project.version,
+		branches: [...project.branches],
+		packages: project.packages.map((pkg) => ({
+			id: pkg.id,
+			name: pkg.name,
+			branchNames: [...pkg.branchNames],
+			folders: pkg.folders.map((folder) => ({
+				branch: folder.branch,
+				path: folder.path
+			})),
+			resources: pkg.resources.map((resource) => ({
+				id: resource.id,
+				name: resource.name,
+				path: resource.path,
+				kind: resource.kind,
+				branch: resource.branch,
+				...resource.kind === "component" ? { component: {
+					displayList: resource.component.displayList.map((node) => ({
+						id: node.id,
+						name: node.name,
+						kind: node.kind
+					})),
+					controllers: resource.component.controllers.map((controller) => ({
+						name: controller.name,
+						pages: controller.pages.map((page) => ({
+							id: page.id,
+							name: page.name
+						}))
+					})),
+					transitions: resource.component.transitions.map((transition) => ({ name: transition.name }))
+				} } : {}
+			}))
+		}))
+	};
+}
 var ReadService = class {
 	constructor(context) {
 		this.context = context;
@@ -1092,6 +1134,15 @@ var ReadService = class {
 			revision: session.revision
 		});
 	}
+	getProjectOutline(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		return success("read", startedAt, toProjectOutline(session), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
 };
 //#endregion
 //#region src/services/runtime-service.ts
@@ -1405,6 +1456,7 @@ const BACKEND_METHODS = [
 	"openSession",
 	"openProjectSession",
 	"getSession",
+	"getProjectOutline",
 	"applyTransaction",
 	"saveSession",
 	"materializeSession",
@@ -1433,7 +1485,8 @@ function createCapabilities() {
 		methods: BACKEND_METHODS,
 		read: {
 			capabilitySnapshot: true,
-			sessionSnapshot: true
+			sessionSnapshot: true,
+			projectOutline: true
 		},
 		authoring: {
 			applyTransaction: true,
@@ -1573,6 +1626,9 @@ var BackendRuntime = class {
 	getSession(input) {
 		return this.readService.getSession(input);
 	}
+	getProjectOutline(input) {
+		return this.readService.getProjectOutline(input);
+	}
 	async applyTransaction(input) {
 		return this.authoringService.applyTransaction(input);
 	}

package/dist/node.d.cts

@@ -1,5 +1,5 @@
 import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
-import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { UamDisplayNodeKind, UamProject, UamResource, UamTransactionOperation } from "@openfairygui/core/uam";
 
 //#region src/path-policy.d.ts
 interface PathPolicyViolationError {
@@ -129,10 +129,11 @@ interface BackendCapabilities {
   transactionKernelOwner: '@openfairygui/core';
   appSeamOwner: '@openfairygui/functions';
   runtimeOwner: '@openfairygui/backend';
-  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'getProjectOutline', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
   read: {
     capabilitySnapshot: true;
     sessionSnapshot: true;
+    projectOutline: true;
   };
   authoring: {
     applyTransaction: true;
@@ -201,6 +202,49 @@ interface BackendSessionSnapshot {
   lockHeld: boolean;
   capabilities: BackendCapabilities;
 }
+interface BackendProjectOutline {
+  sessionId: string;
+  revision: number;
+  projectId: string;
+  projectType: number;
+  version: string;
+  branches: string[];
+  packages: BackendProjectOutlinePackage[];
+}
+interface BackendProjectOutlinePackage {
+  id: string;
+  name: string;
+  branchNames: string[];
+  folders: Array<{
+    branch: string;
+    path: string;
+  }>;
+  resources: BackendProjectOutlineResource[];
+}
+interface BackendProjectOutlineResource {
+  id: string;
+  name: string;
+  path: string;
+  kind: UamResource['kind'];
+  branch: string;
+  component?: {
+    displayList: Array<{
+      id: string;
+      name: string;
+      kind: UamDisplayNodeKind;
+    }>;
+    controllers: Array<{
+      name: string;
+      pages: Array<{
+        id: string;
+        name: string;
+      }>;
+    }>;
+    transitions: Array<{
+      name: string;
+    }>;
+  };
+}
 interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
   mode: 'fullProject';
   reason?: string;
@@ -425,6 +469,9 @@ interface ApplySessionTransactionInput {
   expectedRevision: number;
   operations: UamTransactionOperation[];
 }
+interface GetProjectOutlineInput {
+  sessionId: string;
+}
 interface OpenProjectSessionInput {
   /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
   project: UamProject;
@@ -488,6 +535,7 @@ declare class BackendRuntime {
   getSession(input: {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
+  getProjectOutline(input: GetProjectOutlineInput): BackendResult<BackendProjectOutline, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
   saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
   materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { UamDisplayNodeKind, UamProject, UamResource, UamTransactionOperation } from "@openfairygui/core/uam";
 import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
 
 //#region src/path-policy.d.ts
@@ -129,10 +129,11 @@ interface BackendCapabilities {
   transactionKernelOwner: '@openfairygui/core';
   appSeamOwner: '@openfairygui/functions';
   runtimeOwner: '@openfairygui/backend';
-  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'getProjectOutline', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
   read: {
     capabilitySnapshot: true;
     sessionSnapshot: true;
+    projectOutline: true;
   };
   authoring: {
     applyTransaction: true;
@@ -201,6 +202,49 @@ interface BackendSessionSnapshot {
   lockHeld: boolean;
   capabilities: BackendCapabilities;
 }
+interface BackendProjectOutline {
+  sessionId: string;
+  revision: number;
+  projectId: string;
+  projectType: number;
+  version: string;
+  branches: string[];
+  packages: BackendProjectOutlinePackage[];
+}
+interface BackendProjectOutlinePackage {
+  id: string;
+  name: string;
+  branchNames: string[];
+  folders: Array<{
+    branch: string;
+    path: string;
+  }>;
+  resources: BackendProjectOutlineResource[];
+}
+interface BackendProjectOutlineResource {
+  id: string;
+  name: string;
+  path: string;
+  kind: UamResource['kind'];
+  branch: string;
+  component?: {
+    displayList: Array<{
+      id: string;
+      name: string;
+      kind: UamDisplayNodeKind;
+    }>;
+    controllers: Array<{
+      name: string;
+      pages: Array<{
+        id: string;
+        name: string;
+      }>;
+    }>;
+    transitions: Array<{
+      name: string;
+    }>;
+  };
+}
 interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
   mode: 'fullProject';
   reason?: string;
@@ -425,6 +469,9 @@ interface ApplySessionTransactionInput {
   expectedRevision: number;
   operations: UamTransactionOperation[];
 }
+interface GetProjectOutlineInput {
+  sessionId: string;
+}
 interface OpenProjectSessionInput {
   /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
   project: UamProject;
@@ -488,6 +535,7 @@ declare class BackendRuntime {
   getSession(input: {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
+  getProjectOutline(input: GetProjectOutlineInput): BackendResult<BackendProjectOutline, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
   saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
   materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;

package/dist/node.mjs

@@ -1051,6 +1051,48 @@ var JobService = class {
 };
 //#endregion
 //#region src/services/read-service.ts
+function toProjectOutline(session) {
+	const project = session.project;
+	return {
+		sessionId: session.sessionId,
+		revision: session.revision,
+		projectId: project.projectId,
+		projectType: project.projectType,
+		version: project.version,
+		branches: [...project.branches],
+		packages: project.packages.map((pkg) => ({
+			id: pkg.id,
+			name: pkg.name,
+			branchNames: [...pkg.branchNames],
+			folders: pkg.folders.map((folder) => ({
+				branch: folder.branch,
+				path: folder.path
+			})),
+			resources: pkg.resources.map((resource) => ({
+				id: resource.id,
+				name: resource.name,
+				path: resource.path,
+				kind: resource.kind,
+				branch: resource.branch,
+				...resource.kind === "component" ? { component: {
+					displayList: resource.component.displayList.map((node) => ({
+						id: node.id,
+						name: node.name,
+						kind: node.kind
+					})),
+					controllers: resource.component.controllers.map((controller) => ({
+						name: controller.name,
+						pages: controller.pages.map((page) => ({
+							id: page.id,
+							name: page.name
+						}))
+					})),
+					transitions: resource.component.transitions.map((transition) => ({ name: transition.name }))
+				} } : {}
+			}))
+		}))
+	};
+}
 var ReadService = class {
 	constructor(context) {
 		this.context = context;
@@ -1067,6 +1109,15 @@ var ReadService = class {
 			revision: session.revision
 		});
 	}
+	getProjectOutline(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("read", startedAt, createSessionNotFoundError(input.sessionId));
+		return success("read", startedAt, toProjectOutline(session), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+	}
 };
 //#endregion
 //#region src/services/runtime-service.ts
@@ -1380,6 +1431,7 @@ const BACKEND_METHODS = [
 	"openSession",
 	"openProjectSession",
 	"getSession",
+	"getProjectOutline",
 	"applyTransaction",
 	"saveSession",
 	"materializeSession",
@@ -1408,7 +1460,8 @@ function createCapabilities() {
 		methods: BACKEND_METHODS,
 		read: {
 			capabilitySnapshot: true,
-			sessionSnapshot: true
+			sessionSnapshot: true,
+			projectOutline: true
 		},
 		authoring: {
 			applyTransaction: true,
@@ -1548,6 +1601,9 @@ var BackendRuntime = class {
 	getSession(input) {
 		return this.readService.getSession(input);
 	}
+	getProjectOutline(input) {
+		return this.readService.getProjectOutline(input);
+	}
 	async applyTransaction(input) {
 		return this.authoringService.applyTransaction(input);
 	}

package/package.json

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

package/src/index.ts

@@ -32,6 +32,9 @@ export {
 	type BackendJobProgress,
 	type BackendJobSnapshot,
 	type BackendJobStatus,
+	type BackendProjectOutline,
+	type BackendProjectOutlinePackage,
+	type BackendProjectOutlineResource,
 	type BackendProjectSessionStorage,
 	type BackendResult,
 	BackendRuntime,
@@ -46,6 +49,7 @@ export {
 	type GetEventsInput,
 	type GetEventsSnapshot,
 	type GetJobInput,
+	type GetProjectOutlineInput,
 	type InProcessLockConflictError,
 	type ListJobsInput,
 	type MaterializeSessionInput,

package/src/runtime/capabilities.ts

@@ -16,6 +16,7 @@ const BACKEND_METHODS = [
 	'openSession',
 	'openProjectSession',
 	'getSession',
+	'getProjectOutline',
 	'applyTransaction',
 	'saveSession',
 	'materializeSession',
@@ -47,6 +48,7 @@ export function createCapabilities(): BackendCapabilities {
 		read: {
 			capabilitySnapshot: true,
 			sessionSnapshot: true,
+			projectOutline: true,
 		},
 		authoring: {
 			applyTransaction: true,

package/src/runtime/contracts.ts

@@ -1,4 +1,9 @@
-import type { UamProject, UamTransactionOperation } from '@openfairygui/core/uam';
+import type {
+	UamDisplayNodeKind,
+	UamProject,
+	UamResource,
+	UamTransactionOperation,
+} from '@openfairygui/core/uam';
 import type { ApplyUamTransactionAppError } from '@openfairygui/functions/uam';
 import type {
 	BACKEND_CAPABILITY_SCHEMA_VERSION,
@@ -94,6 +99,7 @@ export interface BackendCapabilities {
 		'openSession',
 		'openProjectSession',
 		'getSession',
+		'getProjectOutline',
 		'applyTransaction',
 		'saveSession',
 		'materializeSession',
@@ -108,6 +114,7 @@ export interface BackendCapabilities {
 	read: {
 		capabilitySnapshot: true;
 		sessionSnapshot: true;
+		projectOutline: true;
 	};
 	authoring: {
 		applyTransaction: true;
@@ -178,6 +185,37 @@ export interface BackendSessionSnapshot {
 	capabilities: BackendCapabilities;
 }
 
+export interface BackendProjectOutline {
+	sessionId: string;
+	revision: number;
+	projectId: string;
+	projectType: number;
+	version: string;
+	branches: string[];
+	packages: BackendProjectOutlinePackage[];
+}
+
+export interface BackendProjectOutlinePackage {
+	id: string;
+	name: string;
+	branchNames: string[];
+	folders: Array<{ branch: string; path: string }>;
+	resources: BackendProjectOutlineResource[];
+}
+
+export interface BackendProjectOutlineResource {
+	id: string;
+	name: string;
+	path: string;
+	kind: UamResource['kind'];
+	branch: string;
+	component?: {
+		displayList: Array<{ id: string; name: string; kind: UamDisplayNodeKind }>;
+		controllers: Array<{ name: string; pages: Array<{ id: string; name: string }> }>;
+		transitions: Array<{ name: string }>;
+	};
+}
+
 export interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
 	mode: 'fullProject';
 	reason?: string;
@@ -476,6 +514,10 @@ export interface ApplySessionTransactionInput {
 	operations: UamTransactionOperation[];
 }
 
+export interface GetProjectOutlineInput {
+	sessionId: string;
+}
+
 export interface OpenProjectSessionInput {
 	/** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
 	project: UamProject;

package/src/runtime.ts

@@ -21,6 +21,7 @@ import type {
 	BackendJobNotCancellableError,
 	BackendJobNotFoundError,
 	BackendJobSnapshot,
+	BackendProjectOutline,
 	BackendResult,
 	BackendRuntimeOptions,
 	BackendSessionSnapshot,
@@ -31,6 +32,7 @@ import type {
 	GetEventsInput,
 	GetEventsSnapshot,
 	GetJobInput,
+	GetProjectOutlineInput,
 	InProcessLockConflictError,
 	ListJobsInput,
 	MaterializeSessionInput,
@@ -113,6 +115,12 @@ export class BackendRuntime {
 		return this.readService.getSession(input);
 	}
 
+	public getProjectOutline(
+		input: GetProjectOutlineInput,
+	): BackendResult<BackendProjectOutline, SessionNotFoundError> {
+		return this.readService.getProjectOutline(input);
+	}
+
 	public async applyTransaction(
 		input: ApplySessionTransactionInput,
 	): Promise<

package/src/services/read-service.ts

@@ -1,7 +1,54 @@
-import { failure, success, type BackendContext } from './context.js';
-import type { BackendCapabilities, BackendResult, BackendSessionSnapshot, SessionNotFoundError } from '../runtime.js';
+import { failure, success, type BackendContext, type BackendSessionState } from './context.js';
+import type {
+	BackendCapabilities,
+	BackendProjectOutline,
+	BackendResult,
+	BackendSessionSnapshot,
+	GetProjectOutlineInput,
+	SessionNotFoundError,
+} from '../runtime.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
 
+function toProjectOutline(session: BackendSessionState): BackendProjectOutline {
+	const project = session.project;
+	// ponytail: full outline is O(project size); add filters or pagination only if payload size becomes a measured problem.
+	return {
+		sessionId: session.sessionId,
+		revision: session.revision,
+		projectId: project.projectId,
+		projectType: project.projectType,
+		version: project.version,
+		branches: [...project.branches],
+		packages: project.packages.map((pkg) => ({
+			id: pkg.id,
+			name: pkg.name,
+			branchNames: [...pkg.branchNames],
+			folders: pkg.folders.map((folder) => ({ branch: folder.branch, path: folder.path })),
+			resources: pkg.resources.map((resource) => ({
+				id: resource.id,
+				name: resource.name,
+				path: resource.path,
+				kind: resource.kind,
+				branch: resource.branch,
+				...(resource.kind === 'component' ? {
+					component: {
+						displayList: resource.component.displayList.map((node) => ({
+							id: node.id,
+							name: node.name,
+							kind: node.kind,
+						})),
+						controllers: resource.component.controllers.map((controller) => ({
+							name: controller.name,
+							pages: controller.pages.map((page) => ({ id: page.id, name: page.name })),
+						})),
+						transitions: resource.component.transitions.map((transition) => ({ name: transition.name })),
+					},
+				} : {}),
+			})),
+		})),
+	};
+}
+
 export class ReadService {
 	public constructor(private readonly context: BackendContext) {}
 
@@ -20,4 +67,18 @@ export class ReadService {
 			revision: session.revision,
 		});
 	}
+
+	public getProjectOutline(
+		input: GetProjectOutlineInput,
+	): BackendResult<BackendProjectOutline, SessionNotFoundError> {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) {
+			return failure('read', startedAt, createSessionNotFoundError(input.sessionId));
+		}
+		return success('read', startedAt, toProjectOutline(session), {
+			sessionId: session.sessionId,
+			revision: session.revision,
+		});
+	}
 }