@fps-games/editor 0.1.8 → 0.2.0-beta.2

package/node_modules/@fps-games/editor-playable-sdk/dist/local-harness/lifecycle.js

@@ -1,16 +1,439 @@
+import { createFpsEditorLifecycleCoordinator, } from '@fps-games/editor-core/lifecycle';
 import { waitForPlayableLocalEditorPaint, waitForPlayableMilliseconds, } from './timing.js';
+export const PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID = 'editor:application';
+export const PLAYABLE_LOCAL_EDITOR_PROJECT_SCOPE_ID = 'editor:project';
+export const PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID = 'editor:document:main';
+export const PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID = 'editor:session:main';
+export const PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID = 'editor:preview:main';
+class PlayableLocalEditorSaveRejectedError extends Error {
+    constructor() {
+        super('Local editor save was rejected.');
+        this.name = 'PlayableLocalEditorSaveRejectedError';
+    }
+}
 export function createPlayableLocalEditorLifecycleController(options) {
     const waitForPaint = options.waitForPaint ?? waitForPlayableLocalEditorPaint;
     const waitForMilliseconds = options.waitForMilliseconds ?? waitForPlayableMilliseconds;
     const now = options.now ?? (() => Date.now());
     const minAssetLoadingOverlayMs = options.minAssetLoadingOverlayMs ?? 500;
     const viewportRevealReason = options.viewportRevealReason ?? 'editor-loading-overlay-hidden';
+    const renderAfterEnter = options.renderAfterEnter ?? true;
+    const initialUnsavedChanges = options.harness.getUnsavedChangesState?.();
+    const initialCoordinatorProfile = options.initialMode === 'edit'
+        && initialUnsavedChanges?.hasWorkingDocument === true
+        ? initialUnsavedChanges.dirty ? 'editing-dirty' : 'editing-clean'
+        : 'created';
+    const coordinator = createFpsEditorLifecycleCoordinator({
+        now,
+        initialState: initialCoordinatorProfile,
+        eventPublisher: options.eventPublisher,
+        report: options.reportDiagnostic,
+    });
+    const lifecycle = Object.freeze({
+        getSnapshot: coordinator.getSnapshot,
+        subscribe: coordinator.subscribe,
+    });
+    const scopes = new Map();
+    const pendingScopeResources = new Map();
+    const assertScopeCanOpen = (input) => {
+        const lifecycleSnapshot = coordinator.getSnapshot();
+        if (lifecycleSnapshot.transitioning || lifecycleSnapshot.application !== 'ready') {
+            throw new Error(`Editor lifecycle cannot open a scope while application is ${lifecycleSnapshot.application}.`);
+        }
+        let parentId = input.parentId;
+        while (parentId) {
+            const parent = scopes.get(parentId);
+            if (!parent || parent.closing || parent.failed) {
+                throw new Error(`Editor lifecycle scope parent is not open: ${parentId}`);
+            }
+            parentId = parent.input.parentId;
+        }
+    };
+    const openScope = async (input) => {
+        assertScopeCanOpen(input);
+        const existing = scopes.get(input.id);
+        if (existing) {
+            if (existing.input.scope !== input.scope || existing.input.parentId !== input.parentId) {
+                throw new Error(`Editor lifecycle scope identity conflicts with the existing scope: ${input.id}`);
+            }
+            if (existing.closing)
+                throw new Error(`Editor lifecycle scope is closing: ${input.id}`);
+            if (existing.failed) {
+                await closeScope(input.id);
+                return openScope(input);
+            }
+            return existing.ready;
+        }
+        const record = {
+            input: Object.freeze({ ...input }),
+            disposers: pendingScopeResources.get(input.id) ?? new Set(),
+            ready: Promise.resolve(),
+            closing: null,
+            failed: false,
+            backingOpened: false,
+            lifecycleOpened: false,
+            closeRequested: false,
+            closeEventRoute: null,
+        };
+        pendingScopeResources.delete(input.id);
+        scopes.set(input.id, record);
+        record.ready = (async () => {
+            if (input.parentId) {
+                const parent = scopes.get(input.parentId);
+                if (!parent)
+                    throw new Error(`Editor lifecycle scope parent is not open: ${input.parentId}`);
+                await parent.ready;
+                assertScopeCanOpen(input);
+            }
+            if (record.closeRequested)
+                return;
+            // A backing host may retain a partially-started scope when its rollback
+            // cleanup fails. Reserve that ownership before awaiting so closeScope can
+            // retry cleanup even when openScope rejects.
+            record.backingOpened = options.scopeHost !== undefined;
+            await options.scopeHost?.openScope(input);
+            if (record.closeRequested)
+                return;
+            coordinator.openScope(input);
+            record.lifecycleOpened = true;
+        })();
+        try {
+            await record.ready;
+        }
+        catch (error) {
+            let cleanupError;
+            try {
+                await closeScope(input.id);
+            }
+            catch (caught) {
+                cleanupError = caught;
+            }
+            if (cleanupError) {
+                const combined = new Error(`Editor lifecycle scope open and cleanup failed: ${input.id}`);
+                combined.errors = [error, cleanupError];
+                throw combined;
+            }
+            throw error;
+        }
+    };
+    const addScopeResource = (scopeId, disposer) => {
+        const record = scopes.get(scopeId);
+        if (record?.closing || record?.failed)
+            throw new Error(`Editor lifecycle scope is not open: ${scopeId}`);
+        if (!record && scopeId !== PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID) {
+            throw new Error(`Editor lifecycle scope is not open: ${scopeId}`);
+        }
+        const resources = record?.disposers ?? pendingScopeResources.get(scopeId) ?? new Set();
+        if (!record)
+            pendingScopeResources.set(scopeId, resources);
+        resources.add(disposer);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            resources.delete(disposer);
+            if (!record && resources.size === 0)
+                pendingScopeResources.delete(scopeId);
+        };
+    };
+    const closeScope = async (scopeId) => {
+        const record = scopes.get(scopeId);
+        if (!record) {
+            const pendingResources = pendingScopeResources.get(scopeId);
+            if (!pendingResources)
+                return;
+            for (const disposer of [...pendingResources].reverse()) {
+                await disposer();
+                pendingResources.delete(disposer);
+            }
+            pendingScopeResources.delete(scopeId);
+            return;
+        }
+        if (record.closing)
+            return record.closing;
+        record.closeEventRoute ?? (record.closeEventRoute = options.eventPublisher?.captureRoute({
+            scope: record.input.scope,
+            scopeId,
+        }) ?? null);
+        record.closeRequested = true;
+        let backingReservationError;
+        if (record.backingOpened) {
+            try {
+                options.scopeHost?.reserveScopeClose(scopeId);
+            }
+            catch (error) {
+                backingReservationError = error;
+            }
+        }
+        record.closing = (async () => {
+            const errors = [];
+            try {
+                await record.ready;
+            }
+            catch { /* The open caller owns and reports setup failures. */ }
+            if (backingReservationError)
+                errors.push(backingReservationError);
+            if (errors.length === 0) {
+                const children = [...scopes.values()]
+                    .filter(candidate => candidate.input.parentId === scopeId)
+                    .reverse();
+                for (const child of children) {
+                    try {
+                        await closeScope(child.input.id);
+                    }
+                    catch (error) {
+                        errors.push(error);
+                        break;
+                    }
+                }
+            }
+            const remainingChildren = [...scopes.values()].filter(candidate => candidate.input.parentId === scopeId);
+            if (errors.length === 0 && remainingChildren.length > 0) {
+                errors.push(new Error(`Editor lifecycle scope still has open children: ${scopeId}`));
+            }
+            if (errors.length === 0 && record.backingOpened) {
+                try {
+                    await options.scopeHost?.closeScope(scopeId);
+                    record.backingOpened = false;
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length === 0 && remainingChildren.length === 0) {
+                for (const disposer of [...record.disposers].reverse()) {
+                    try {
+                        await disposer();
+                        record.disposers.delete(disposer);
+                    }
+                    catch (error) {
+                        // Preserve dependency order: untouched earlier resources stay owned
+                        // until the failed later resource can be released on a retry.
+                        errors.push(error);
+                        break;
+                    }
+                }
+            }
+            if (errors.length === 0 && record.lifecycleOpened) {
+                try {
+                    coordinator.closeScope(scopeId, record.closeEventRoute ?? undefined);
+                    record.lifecycleOpened = false;
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                record.failed = true;
+                coordinator.failScope(scopeId);
+                const error = new Error(`Editor lifecycle scope cleanup failed: ${scopeId}`);
+                error.errors = errors;
+                throw error;
+            }
+            scopes.delete(scopeId);
+        })().finally(() => {
+            if (scopes.get(scopeId) === record)
+                record.closing = null;
+        });
+        return record.closing;
+    };
     let assetLoadingCount = 0;
     let assetLoadingOverlayOwned = false;
+    let assetLoadingOverlayWaiting = false;
     let assetLoadingOverlayShownAt = 0;
-    const showLoadingOverlayIfNeeded = (content) => {
-        if (!options.loadingOverlay.isVisible())
-            options.loadingOverlay.show(content);
+    let preparationEpoch = 0;
+    let lifecycleOverlayOwner = null;
+    let pendingLifecycleOverlay = null;
+    let pendingDocumentDirty;
+    let documentSynchronization = null;
+    const readLifecycleRevision = () => coordinator.getSnapshot().revision;
+    const ensureApplicationAndProject = async (context) => {
+        let current = coordinator.getSnapshot();
+        if (current.transitioning)
+            throw new Error('Editor lifecycle transition already in progress.');
+        if (current.application === 'created') {
+            await coordinator.transition({ type: 'application.start', ...context });
+            current = coordinator.getSnapshot();
+        }
+        if (current.application !== 'ready') {
+            throw new Error(`Editor application is not ready: ${current.application}.`);
+        }
+        await openScope({ id: PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID, scope: 'application' });
+        options.operations.attachApplicationAuthority?.();
+        if (current.project === 'closed') {
+            await coordinator.transition({ type: 'project.open', ...context });
+        }
+        await openScope({
+            id: PLAYABLE_LOCAL_EDITOR_PROJECT_SCOPE_ID,
+            scope: 'project',
+            parentId: PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID,
+        });
+    };
+    const ensureEditingState = async (load = options.operations.loadDocument, enter = options.operations.enterWorld, context) => {
+        await ensureApplicationAndProject(context);
+        let current = coordinator.getSnapshot();
+        const workingDocumentAvailable = readUnsavedChangesState().hasWorkingDocument;
+        await openScope({
+            id: PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID,
+            scope: 'document',
+            parentId: PLAYABLE_LOCAL_EDITOR_PROJECT_SCOPE_ID,
+        });
+        await openScope({
+            id: PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID,
+            scope: 'session',
+            parentId: PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID,
+        });
+        if (current.document === 'unloaded' || (current.document === 'failed' && !workingDocumentAvailable)) {
+            try {
+                await coordinator.transition({ type: 'document.load', ...context, ...(load ? { operation: load } : {}) });
+                options.operations.attachSessionAuthority?.();
+                current = coordinator.getSnapshot();
+            }
+            catch (error) {
+                await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID);
+                await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID);
+                throw error;
+            }
+        }
+        else {
+            options.operations.attachSessionAuthority?.();
+        }
+        try {
+            await openScope({
+                id: PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID,
+                scope: 'preview',
+                parentId: PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID,
+            });
+        }
+        catch (error) {
+            // A failed Preview rollback remains a child of Session and owns the
+            // loaded document graph. Do not retry that same cleanup indirectly by
+            // tearing down its ancestors in the same enter attempt.
+            if (scopes.has(PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID))
+                throw error;
+            await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID);
+            await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID);
+            throw error;
+        }
+        if (current.mode === 'failed') {
+            try {
+                if (current.preview === 'failed')
+                    await disposePreview(context);
+                await coordinator.transition({ type: 'mode.recoverEdit', ...context, ...(enter ? { operation: enter } : {}) });
+            }
+            catch (error) {
+                await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID);
+                await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID);
+                throw error;
+            }
+            current = coordinator.getSnapshot();
+        }
+        if (current.mode === 'play') {
+            try {
+                await coordinator.transition({ type: 'mode.enterEdit', ...context, ...(enter ? { operation: enter } : {}) });
+            }
+            catch (error) {
+                await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID);
+                await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID);
+                throw error;
+            }
+            current = coordinator.getSnapshot();
+        }
+        if (current.mode !== 'edit')
+            throw new Error(`Editor mode is not ready: ${current.mode}.`);
+        if (current.preview === 'absent') {
+            await coordinator.transition({ type: 'preview.create', ...context });
+            current = coordinator.getSnapshot();
+        }
+        if (current.document === 'failed') {
+            await coordinator.transition({
+                type: readUnsavedChangesState().dirty ? 'document.markDirty' : 'document.markClean',
+                ...context,
+            });
+        }
+    };
+    const disposePreview = async (context) => {
+        const current = coordinator.getSnapshot();
+        if (current.preview === 'active' || current.preview === 'failed') {
+            await coordinator.transition({
+                type: 'preview.dispose',
+                ...context,
+                operation: () => closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID),
+            });
+            return;
+        }
+        await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID);
+    };
+    const closeEditingScopes = async () => {
+        await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID);
+        await closeScope(PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID);
+    };
+    const runGameAfterReleasingPluginScopes = async (reason) => {
+        // Replacement runtimes use the same stable Plugin scope ids. Release the
+        // complete old scope tree before restart can mount the replacement editor.
+        await closeScope(PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID);
+        await options.operations.runGame(reason);
+    };
+    const waitForLifecycleIdle = async () => {
+        if (!coordinator.getSnapshot().transitioning)
+            return;
+        await new Promise(resolve => {
+            const dispose = coordinator.subscribe(snapshot => {
+                if (snapshot.transitioning)
+                    return;
+                dispose();
+                resolve();
+            });
+            if (!coordinator.getSnapshot().transitioning) {
+                dispose();
+                resolve();
+            }
+        });
+    };
+    const reconcileDocumentState = async (dirty) => {
+        await waitForLifecycleIdle();
+        const current = coordinator.getSnapshot();
+        if (current.project !== 'open' || current.mode !== 'edit')
+            return;
+        if (dirty && current.document !== 'dirty') {
+            if (current.document === 'clean' || current.document === 'committing') {
+                await coordinator.transition({ type: 'document.markDirty' });
+            }
+            return;
+        }
+        if (!dirty && current.document === 'dirty') {
+            await coordinator.transition({ type: 'document.markClean' });
+        }
+    };
+    const drainDocumentSynchronization = async () => {
+        while (pendingDocumentDirty !== undefined) {
+            const dirty = pendingDocumentDirty;
+            pendingDocumentDirty = undefined;
+            try {
+                await reconcileDocumentState(dirty);
+            }
+            catch (error) {
+                if (!coordinator.getSnapshot().transitioning)
+                    throw error;
+                pendingDocumentDirty = dirty;
+            }
+        }
+    };
+    const synchronizeDocumentState = (dirty) => {
+        pendingDocumentDirty = dirty;
+        if (!documentSynchronization) {
+            documentSynchronization = drainDocumentSynchronization().finally(() => {
+                documentSynchronization = null;
+                if (pendingDocumentDirty !== undefined)
+                    void synchronizeDocumentState(pendingDocumentDirty);
+            });
+        }
+        return documentSynchronization;
+    };
+    const waitForDocumentSynchronization = async () => {
+        if (documentSynchronization)
+            await documentSynchronization;
     };
     const notifySaveFailed = async (operation, error) => {
         const notify = options.interactions?.notifySaveFailed;
@@ -36,14 +459,31 @@ export function createPlayableLocalEditorLifecycleController(options) {
             console.error('[PlayableLocalEditorLifecycle] save failure notification failed', notifyError);
         }
     };
-    const saveScene = async (operation = 'save-scene') => {
+    const prepareDocumentSave = async (save, context) => {
+        await waitForDocumentSynchronization();
+        await ensureEditingState(undefined, undefined, context);
+        await synchronizeDocumentState(readUnsavedChangesState().dirty);
+        await coordinator.transition({ type: 'document.prepareSave', ...context, operation: save });
+    };
+    const commitDocumentSave = async (commit, context) => {
+        await coordinator.transition({ type: 'document.commit', ...context, ...(commit ? { operation: commit } : {}) });
+    };
+    const saveScene = async (operation = 'save-scene', context) => {
+        let saved = false;
         try {
-            const saved = await options.harness.saveScene();
-            if (!saved)
-                await notifySaveFailed(operation);
-            return saved;
+            await prepareDocumentSave(async () => {
+                saved = await options.harness.saveScene();
+                if (!saved)
+                    throw new PlayableLocalEditorSaveRejectedError();
+            }, context);
+            await commitDocumentSave(undefined, context);
+            return true;
         }
         catch (error) {
+            if (error instanceof PlayableLocalEditorSaveRejectedError) {
+                await notifySaveFailed(operation);
+                return false;
+            }
             await notifySaveFailed(operation, error);
             throw error;
         }
@@ -67,49 +507,216 @@ export function createPlayableLocalEditorLifecycleController(options) {
             return false;
         }
     };
+    const beginPreparation = () => {
+        pendingLifecycleOverlay = null;
+        if (lifecycleOverlayOwner !== null) {
+            lifecycleOverlayOwner = null;
+            const ownsOverlay = options.loadingOverlay.isOwned?.() !== false;
+            if (ownsOverlay && assetLoadingCount > 0 && assetLoadingOverlayWaiting) {
+                assetLoadingOverlayWaiting = false;
+                assetLoadingOverlayOwned = true;
+                assetLoadingOverlayShownAt = now();
+                options.loadingOverlay.show(options.content.assetImport);
+            }
+            else if (ownsOverlay) {
+                options.loadingOverlay.hide();
+            }
+        }
+        return { epoch: ++preparationEpoch, revision: readLifecycleRevision() };
+    };
+    const showLifecycleOverlay = (preparation, content) => {
+        if (options.loadingOverlay.isVisible()) {
+            if (options.loadingOverlay.isOwned?.() !== false) {
+                pendingLifecycleOverlay = { epoch: preparation.epoch, content };
+            }
+            return;
+        }
+        options.loadingOverlay.show(content);
+        lifecycleOverlayOwner = preparation.epoch;
+    };
+    const hideLifecycleOverlay = (epoch) => {
+        if (pendingLifecycleOverlay?.epoch === epoch)
+            pendingLifecycleOverlay = null;
+        if (lifecycleOverlayOwner !== epoch)
+            return;
+        lifecycleOverlayOwner = null;
+        if (options.loadingOverlay.isOwned?.() === false)
+            return;
+        if (assetLoadingCount > 0 && assetLoadingOverlayWaiting) {
+            assetLoadingOverlayWaiting = false;
+            assetLoadingOverlayOwned = true;
+            assetLoadingOverlayShownAt = now();
+            options.loadingOverlay.show(options.content.assetImport);
+            return;
+        }
+        options.loadingOverlay.hide();
+    };
+    const isPreparationCurrent = (preparation) => (preparation.epoch === preparationEpoch
+        && preparation.revision === readLifecycleRevision());
+    const createPreparedRun = (preparation, run) => {
+        let consumed = false;
+        return {
+            accepted: true,
+            async run() {
+                if (consumed)
+                    throw new Error('Prepared editor lifecycle operation was already consumed.');
+                if (!isPreparationCurrent(preparation)) {
+                    consumed = true;
+                    hideLifecycleOverlay(preparation.epoch);
+                    throw new Error('Prepared editor lifecycle operation is stale.');
+                }
+                consumed = true;
+                await run();
+            },
+        };
+    };
+    const prepareSaveAndRunGame = async (context) => {
+        const preparation = beginPreparation();
+        showLifecycleOverlay(preparation, options.content.saveAndRunGame);
+        try {
+            await waitForPaint();
+            const saved = await saveScene('save-and-run-game', context);
+            if (!saved || preparation.epoch !== preparationEpoch) {
+                hideLifecycleOverlay(preparation.epoch);
+                return { accepted: false };
+            }
+            preparation.revision = readLifecycleRevision();
+            return createPreparedRun(preparation, async () => {
+                try {
+                    await disposePreview(context);
+                    await coordinator.transition({
+                        type: 'mode.exitEdit',
+                        ...context,
+                        operation: () => runGameAfterReleasingPluginScopes('save'),
+                    });
+                    await closeEditingScopes();
+                }
+                finally {
+                    hideLifecycleOverlay(preparation.epoch);
+                }
+            });
+        }
+        catch (error) {
+            hideLifecycleOverlay(preparation.epoch);
+            throw error;
+        }
+    };
+    const prepareDiscardAndRunGame = async (context) => {
+        await waitForDocumentSynchronization();
+        await ensureEditingState(undefined, undefined, context);
+        await synchronizeDocumentState(readUnsavedChangesState().dirty);
+        const preparation = beginPreparation();
+        if (!await confirmDiscardIfNeeded('discard-and-run-game')
+            || !isPreparationCurrent(preparation))
+            return { accepted: false };
+        showLifecycleOverlay(preparation, options.content.discardAndRunGame);
+        try {
+            await waitForPaint();
+            if (!isPreparationCurrent(preparation)) {
+                hideLifecycleOverlay(preparation.epoch);
+                return { accepted: false };
+            }
+            return createPreparedRun(preparation, async () => {
+                try {
+                    await coordinator.transition({
+                        type: 'document.discard',
+                        ...context,
+                        ...(options.operations?.restoreDocument
+                            ? { operation: options.operations.restoreDocument }
+                            : {}),
+                    });
+                    await disposePreview(context);
+                    await coordinator.transition({
+                        type: 'mode.exitEdit',
+                        ...context,
+                        operation: () => runGameAfterReleasingPluginScopes('discard'),
+                    });
+                    await closeEditingScopes();
+                }
+                finally {
+                    hideLifecycleOverlay(preparation.epoch);
+                }
+            });
+        }
+        catch (error) {
+            hideLifecycleOverlay(preparation.epoch);
+            throw error;
+        }
+    };
     return {
-        async enterEditor() {
-            options.loadingOverlay.show(options.content.enter);
+        lifecycle,
+        registerParticipant: coordinator.registerParticipant,
+        async enterEditor(context) {
+            const preparation = beginPreparation();
+            showLifecycleOverlay(preparation, {
+                ...options.content.enter,
+                presentation: 'editor-shell',
+            });
             let entered = false;
             try {
                 await waitForPaint();
-                await options.harness.enterEditor();
-                entered = true;
-                options.harness.render();
+                const before = coordinator.getSnapshot();
+                const load = options.operations.loadDocument;
+                const enter = options.operations.enterWorld
+                    ?? options.harness.enterEditor.bind(options.harness);
+                await ensureEditingState(load, enter, context);
+                entered = before.mode !== 'edit';
+                if (renderAfterEnter)
+                    options.harness.render();
                 await waitForPaint();
             }
             finally {
-                options.loadingOverlay.hide();
+                hideLifecycleOverlay(preparation.epoch);
                 if (entered)
                     options.harness.notifyViewportRevealed?.(viewportRevealReason);
             }
         },
         saveScene,
-        async saveAndRunGame() {
-            showLoadingOverlayIfNeeded(options.content.saveAndRunGame);
-            try {
-                await waitForPaint();
-                const saved = await saveScene('save-and-run-game');
-                if (!saved)
-                    return false;
-                await options.harness.discardAndRunGame();
-                return true;
+        synchronizeDocumentState,
+        prepareDocumentSave,
+        commitDocumentSave,
+        async runCommittedDocument(context) {
+            await ensureEditingState(undefined, undefined, context);
+            await synchronizeDocumentState(readUnsavedChangesState().dirty);
+            const current = coordinator.getSnapshot();
+            if (current.document !== 'clean') {
+                throw new Error(`Cannot run an uncommitted editor document: ${current.document}.`);
             }
-            finally {
-                options.loadingOverlay.hide();
+            await disposePreview(context);
+            await coordinator.transition({
+                type: 'mode.exitEdit',
+                ...context,
+                operation: () => runGameAfterReleasingPluginScopes('save'),
+            });
+            await closeEditingScopes();
+        },
+        prepareSaveAndRunGame,
+        prepareDiscardAndRunGame,
+        async saveAndRunGame(context) {
+            const prepared = await prepareSaveAndRunGame(context);
+            if (!prepared.accepted)
+                return false;
+            await prepared.run();
+            return true;
+        },
+        async discardAndRunGame(context) {
+            const prepared = await prepareDiscardAndRunGame(context);
+            if (prepared.accepted) {
+                await prepared.run();
             }
+            return prepared.accepted;
         },
-        async discardAndRunGame() {
-            if (!await confirmDiscardIfNeeded('discard-and-run-game'))
+        openScope,
+        addScopeResource,
+        closeScope,
+        async dispose(context) {
+            if (coordinator.getSnapshot().application === 'disposed')
                 return;
-            showLoadingOverlayIfNeeded(options.content.discardAndRunGame);
-            try {
-                await waitForPaint();
-                await options.harness.discardAndRunGame();
-            }
-            finally {
-                options.loadingOverlay.hide();
-            }
+            await coordinator.transition({
+                type: 'application.dispose',
+                ...context,
+                operation: () => closeScope(PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID),
+            });
         },
         async runWithAssetLoadingOverlay(operation) {
             const shouldShowAssetLoading = !options.loadingOverlay.isVisible() && !assetLoadingOverlayOwned;
@@ -120,6 +727,9 @@ export function createPlayableLocalEditorLifecycleController(options) {
                 options.loadingOverlay.show(options.content.assetImport);
                 await waitForPaint();
             }
+            else if (options.loadingOverlay.isVisible() && !assetLoadingOverlayOwned) {
+                assetLoadingOverlayWaiting = true;
+            }
             try {
                 return await operation();
             }
@@ -131,9 +741,22 @@ export function createPlayableLocalEditorLifecycleController(options) {
                         await waitForMilliseconds(remaining);
                     if (assetLoadingCount === 0 && assetLoadingOverlayOwned) {
                         assetLoadingOverlayOwned = false;
-                        options.loadingOverlay.hide();
+                        if (options.loadingOverlay.isOwned?.() === false) {
+                            pendingLifecycleOverlay = null;
+                        }
+                        else if (pendingLifecycleOverlay) {
+                            const pending = pendingLifecycleOverlay;
+                            pendingLifecycleOverlay = null;
+                            lifecycleOverlayOwner = pending.epoch;
+                            options.loadingOverlay.show(pending.content);
+                        }
+                        else {
+                            options.loadingOverlay.hide();
+                        }
                     }
                 }
+                if (assetLoadingCount === 0)
+                    assetLoadingOverlayWaiting = false;
             }
         },
     };