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

package/dist/local-editor-harness.js

@@ -1,6 +1,9 @@
-import { createEditorSession, createEditorAgentBridge, createInspectorRegistry, DEFAULT_EDITOR_TRANSFORM_OPERATION_SETTINGS, DEFAULT_EDITOR_VIEWPORT_TOOL_STATE, createEmptyEditorViewportSpatialOverlayState, cloneEditorTransformSnapshot as cloneCoreEditorTransformSnapshot, composeEditorTransformMatrix, editorTransformMatricesAlmostEqual, cloneEditorViewportToolState, cloneEditorViewportSpatialOverlayState, aggregateInspectorObjectsToMultiObject, createInspectorEditPayload, compareInspectorSections, computeEditorTransformActionTargets, mergeInspectorSections, isEditorTransformTrsSnapshot, normalizeEditorTransformConstraint, readEditorTransformPosition, resolveEditorSelectionCommand, serializedMultiObjectToInspectorObject, serializedObjectToInspectorObject, validateSceneGraphDelete, validateSceneGraphDrop, validateSceneGraphGroupSelection, validateSceneGraphMove, validateSceneGraphRename, } from '@fps-games/editor-core';
+import { createEditorSession, FPS_EDITOR_ACTIVE_TOOL_CHANGED, FPS_EDITOR_DOCUMENT_CHANGED, FPS_EDITOR_HISTORY_CHANGED, FPS_EDITOR_SELECTION_CHANGED, createEditorAgentBridge, createInspectorRegistry, DEFAULT_EDITOR_TRANSFORM_OPERATION_SETTINGS, DEFAULT_EDITOR_VIEWPORT_TOOL_STATE, createEmptyEditorViewportSpatialOverlayState, cloneEditorTransformSnapshot as cloneCoreEditorTransformSnapshot, composeEditorTransformMatrix, editorTransformMatricesAlmostEqual, cloneEditorViewportToolState, cloneEditorViewportSpatialOverlayState, aggregateInspectorObjectsToMultiObject, createInspectorEditPayload, compareInspectorSections, computeEditorTransformActionTargets, mergeInspectorSections, isEditorTransformTrsSnapshot, normalizeEditorTransformConstraint, readEditorTransformPosition, resolveEditorSelectionCommand, validateSceneGraphDelete, validateSceneGraphDrop, validateSceneGraphGroupSelection, validateSceneGraphMove, validateSceneGraphRename, } from '@fps-games/editor-core';
 import {} from '@fps-games/editor-protocol';
 import { createLocalEditorBrowserUi, toTransformOperationPolicyStatusLabel, } from '@fps-games/editor-browser';
+import { createLocalEditorHarnessPluginInspectorOptions } from './local-editor-plugin-inspector.js';
+import { registerLocalEditorHarnessLifecycleOperations, } from './internal/local-editor-lifecycle-operations.js';
+import { createLocalEditorPluginPanelState } from './local-editor-plugin-panel.js';
 import { createBabylonEnvironmentTextureController, createBabylonDefaultPostProcessPipelineController, } from '@fps-games/babylon-renderer';
 import { createBabylonEditorProjection, createBabylonEditorMarkerOverlayController, createBabylonMarkerOverlayProjectionAdapter, createBabylonEditorWorld, createBabylonPrefabComparisonPreviewController, createBabylonProjectionSelectionController, createBabylonSceneCameraPreviewController, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonSceneViewMeasurementController, createBabylonSceneViewSpatialOverlayController, createBabylonEditorShadowPreviewController, createBabylonTransformGizmoController, createBabylonEditorPerformanceMonitor, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
 import { createLocalEditorSceneRenderScheduler, } from './local-editor-scene-render-scheduler.js';
@@ -9,8 +12,12 @@ import { createLocalEditorViewportRenderCoordinator, } from './local-editor-view
 import { createLocalEditorSceneViewInteractionRuntime, } from './local-editor-scene-view-interaction-runtime.js';
 import { cloneLocalEditorPerformanceStats, countLocalEditorAuthoredObjects, createLocalEditorPerformanceStats, LOCAL_EDITOR_PERFORMANCE_MONITOR_REASON, } from './local-editor-performance-stats.js';
 import { registerLocalEditorAgentBridgeCapabilities } from './local-editor-agent-bridge.js';
+import { registerEditorPluginAgentCapabilities } from './editor-plugin-agent-capabilities.js';
+import { createLocalEditorHarnessPluginHierarchyContextActions } from './editor-plugin-hierarchy-command.js';
 import { createLocalEditorAgentBridgeCapabilitySources, } from './agent-bridge/capability-sources.js';
 import { createDisabledLocalEditorAgentBridgeTransportStatus, createLocalEditorAgentBridgeWebSocketTransportFromQuery, } from './local-editor-agent-bridge-transport.js';
+import { PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID, PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID, PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID, PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID, PLAYABLE_LOCAL_EDITOR_PROJECT_SCOPE_ID, } from '@fps-games/editor-playable-sdk/internal/local-harness';
+import { FPS_EDITOR_LIFECYCLE_TRANSITION_TYPES } from '@fps-games/editor-core/lifecycle';
 import { createMarkerGraphHierarchyItems, createMarkerGraphInspectorObject, createMarkerGraphRootInspectorObject, createMarkerPanelState, createMarkerRelationCommand, createMarkerRelationCreateManyCommand, createMarkerRelationDeleteConnectedCommand, createMarkerRelationReverseCommand, createMarkerGraphPatchFromInspectorEdit, findSpatialMarkerById, getSpatialMarkerDirectRelations, isMarkerGraphHierarchyId, isMarkerGraphHierarchyRootRowId, isSpatialMarkerBackedByHierarchyRow, isSpatialMarkerHierarchyVisible, readMarkerGraphHierarchyMarkerIdForGraph, readSpatialMarkerIdFromHierarchySelection, } from './local-editor-marker-graph.js';
 const BATCH_EDIT_REQUIRES_MULTI_PATCH_REASON = 'Batch edit requires multi-property patch support.';
 const LARGE_SELECTION_THRESHOLD = 200;
@@ -60,6 +67,39 @@ function createEmptyMarkerCreateReservations() {
         labels: new Set(),
     };
 }
+const LOCAL_EDITOR_MATERIAL_PROFILE_DIAGNOSTIC_LIMIT = 100;
+const LOCAL_EDITOR_PROJECTION_MATERIAL_PROFILE_WARNING = '[BabylonEditorProjection] Material profile diagnostic warning';
+function createLocalEditorProjectionLogger() {
+    return {
+        warn(...args) {
+            if (args[0] === LOCAL_EDITOR_PROJECTION_MATERIAL_PROFILE_WARNING)
+                return;
+            console.warn(...args);
+        },
+    };
+}
+function recordLocalEditorMaterialProfileDiagnostic(state, diagnostic) {
+    state.materialProfileDiagnostics.push(diagnostic);
+    if (state.materialProfileDiagnostics.length > LOCAL_EDITOR_MATERIAL_PROFILE_DIAGNOSTIC_LIMIT) {
+        state.materialProfileDiagnostics.splice(0, state.materialProfileDiagnostics.length - LOCAL_EDITOR_MATERIAL_PROFILE_DIAGNOSTIC_LIMIT);
+    }
+    if (!diagnostic.warningMessage || !isLocalEditorMaterialProfileDiagnosticConsoleEnabled())
+        return;
+    console.warn(LOCAL_EDITOR_PROJECTION_MATERIAL_PROFILE_WARNING, {
+        projectionNodeId: diagnostic.projectionNodeId,
+        source: diagnostic.source,
+        slotId: diagnostic.slotId,
+        ownerNodePath: diagnostic.ownerNodePath,
+        meshOwnerNodePath: diagnostic.meshOwnerNodePath,
+        matchKind: diagnostic.matchKind,
+        targetMaterialStatus: diagnostic.targetMaterialStatus,
+        warningMessage: diagnostic.warningMessage,
+    });
+}
+function isLocalEditorMaterialProfileDiagnosticConsoleEnabled() {
+    return globalThis
+        .__FPS_EDITOR_DEBUG_MATERIAL_PROFILE_DIAGNOSTICS === true;
+}
 function createLocalEditorDataSafetyInteractionPolicy(ui) {
     return {
         confirmDiscardUnsavedChanges() {
@@ -97,9 +137,63 @@ function stringifyLocalEditorError(error) {
     return String(error);
 }
 export function createLocalEditorHarness(options) {
+    let cleanupResources = null;
+    let releasePluginHostConsumer = options.pluginHost?.acquireConsumer('local-editor-harness') ?? null;
+    const releaseConsumer = () => {
+        if (!releasePluginHostConsumer)
+            return;
+        const release = releasePluginHostConsumer;
+        release();
+        releasePluginHostConsumer = null;
+    };
+    const cleanupAndRelease = () => {
+        cleanupResources?.();
+        releaseConsumer();
+    };
+    const construction = {
+        setCleanup(cleanup) {
+            cleanupResources = cleanup;
+        },
+        dispose: cleanupAndRelease,
+    };
+    try {
+        return createLocalEditorHarnessImplementation(options, construction);
+    }
+    catch (constructionError) {
+        const nestedRetryCleanup = readRetryCleanup(constructionError);
+        if (!cleanupResources && nestedRetryCleanup)
+            cleanupResources = nestedRetryCleanup;
+        try {
+            cleanupAndRelease();
+        }
+        catch (cleanupError) {
+            throw createLocalEditorHarnessConstructionError(constructionError, cleanupError, cleanupAndRelease);
+        }
+        throw constructionError;
+    }
+}
+function createLocalEditorHarnessImplementation(options, construction) {
     const root = options.root ?? document.body;
+    let lifecycleController = null;
+    let releaseApplicationAuthorityScopeResource = null;
+    let releaseLifecycleRenderScopeResource = null;
+    let unsubscribeLifecycleRender = null;
+    let unregisterAgentBridgeLifecycleParticipant = null;
+    const agentBridgeLifecycleTransports = new Map();
+    let releaseMainSessionScopeResource = null;
+    let releaseMainPreviewScopeResource = null;
     const state = {
-        mode: 'game',
+        get mode() {
+            const lifecycleMode = lifecycleController?.lifecycle.getSnapshot().mode;
+            if (lifecycleMode)
+                return lifecycleMode === 'edit' ? 'editor' : 'game';
+            return state.world ? 'editor' : 'game';
+        },
+        get lifecycle() {
+            return lifecycleController?.lifecycle ?? null;
+        },
+        scopeOperations: null,
+        nextPrefabScopeRevision: 0,
         editorStateRevision: 0,
         sceneArtifactRevision: 0,
         busy: false,
@@ -114,6 +208,7 @@ export function createLocalEditorHarness(options) {
         grid: null,
         gridVisible: true,
         projection: null,
+        materialProfileDiagnostics: [],
         previewVisibility: {
             overrides: {},
             isolatedObjectIds: [],
@@ -172,7 +267,64 @@ export function createLocalEditorHarness(options) {
         agentBridgeTransport: null,
         agentBridgeStatus: createDisabledLocalEditorAgentBridgeTransportStatus(),
     };
+    const handleEditorSessionChange = (change) => {
+        void lifecycleController?.synchronizeDocumentState(change.dirty).catch(error => {
+            console.error('[LocalEditorHarness] lifecycle document synchronization failed', error);
+        });
+        const eventPublisher = options.pluginHost?.eventPublisher;
+        const session = state.session;
+        if (!eventPublisher || !session)
+            return;
+        const sessionState = session.getState({ cloneDocuments: false });
+        if (change.documentChanged) {
+            void eventPublisher.publish(FPS_EDITOR_DOCUMENT_CHANGED, Object.freeze({
+                reason: change.reason,
+                dirty: change.dirty,
+                documentChanged: true,
+            }), {
+                scope: 'document',
+                scopeId: PLAYABLE_LOCAL_EDITOR_MAIN_DOCUMENT_SCOPE_ID,
+            });
+        }
+        if (change.selectionChanged) {
+            void eventPublisher.publish(FPS_EDITOR_SELECTION_CHANGED, Object.freeze({
+                selectedIds: Object.freeze([...sessionState.selection.selectedIds]),
+                activeId: sessionState.selection.activeId,
+            }), {
+                scope: 'session',
+                scopeId: PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID,
+            });
+        }
+        if (change.historyChanged) {
+            void eventPublisher.publish(FPS_EDITOR_HISTORY_CHANGED, Object.freeze({
+                reason: change.reason === 'reset' ? 'reset' : change.reason === 'history' ? 'history' : 'document',
+                canUndo: sessionState.canUndo,
+                canRedo: sessionState.canRedo,
+                entryCount: sessionState.history.entries.length,
+            }), {
+                scope: 'session',
+                scopeId: PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID,
+            });
+        }
+    };
+    const handleEditorSessionObserverError = (error) => {
+        const diagnostic = {
+            code: 'editor.session.observerFailed',
+            message: error instanceof Error ? error.message : String(error),
+            severity: 'error',
+        };
+        if (options.pluginHost) {
+            options.pluginHost.reportDiagnostic(diagnostic, {
+                scope: 'session',
+                scopeId: PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID,
+            });
+            return;
+        }
+        console.error('[LocalEditorHarness] session observer failed', error);
+    };
     let harness;
+    let agentLifecycleController;
+    const pluginInspector = createLocalEditorHarnessPluginInspectorOptions(options.pluginHost, options.inspector);
     const ui = createLocalEditorBrowserUi({
         root,
         theme: options.theme,
@@ -180,22 +332,22 @@ export function createLocalEditorHarness(options) {
         input: {
             isShortcutReserved: (event) => state.sceneViewInput?.ownsKeyboardEvent(event) ?? false,
         },
-        inspector: options.inspector,
+        inspector: pluginInspector,
         hierarchy: {
             contextActions: createBrowserHierarchyContextActions(state, options),
         },
         callbacks: {
             onEnterEditor: () => {
-                void runExclusive(state, harness.render, () => harness.enterEditor());
+                void runExclusive(state, harness.render, () => agentLifecycleController.enterEditor());
             },
             onSaveScene: () => {
-                void runExclusive(state, harness.render, () => harness.saveScene());
+                void runExclusive(state, harness.render, () => agentLifecycleController.saveScene());
             },
             onSaveAndRunGame: () => {
-                void runExclusive(state, harness.render, () => harness.saveAndRunGame());
+                void runExclusive(state, harness.render, () => agentLifecycleController.saveAndRunGame());
             },
             onDiscardAndRunGame: () => {
-                void runExclusive(state, harness.render, () => harness.discardAndRunGame());
+                void runExclusive(state, harness.render, () => agentLifecycleController.discardAndRunGame());
             },
             onUndo: () => {
                 void harness.undo({ origin: 'user', waitForProjection: 'none' });
@@ -212,12 +364,16 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onAssetAction: (input) => {
-                if (handleBrowserAssetAction(state, options, input))
-                    harness.render();
+                void runExclusive(state, harness.render, async () => {
+                    if (await handleBrowserAssetAction(state, options, input))
+                        harness.render();
+                });
             },
             onExitPrefabStage: () => {
-                if (exitPrefabStage(state, options))
-                    harness.render();
+                void runExclusive(state, harness.render, async () => {
+                    if (await exitPrefabStage(state, options))
+                        harness.render();
+                });
             },
             onSelectPrefabStageItem: (itemId) => {
                 if (selectPrefabStageItemWithPreviewSync(state, options, itemId))
@@ -289,6 +445,19 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onContextAction: (action) => {
+                if (action.region === 'hierarchy' && action.action === 'custom') {
+                    const result = runHierarchyCustomContextAction(state, options, action);
+                    if (isLocalEditorPromiseLike(result)) {
+                        void result.then(changed => {
+                            if (changed)
+                                harness.render();
+                        });
+                    }
+                    else if (result) {
+                        harness.render();
+                    }
+                    return;
+                }
                 if (handleContextAction(state, options, action))
                     harness.render();
             },
@@ -303,8 +472,10 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onInspectorAction: (input) => {
-                if (handleInspectorAction(state, options, input))
-                    harness.render();
+                void runExclusive(state, harness.render, async () => {
+                    if (await handleInspectorAction(state, options, input))
+                        harness.render();
+                });
             },
             onRenderingPropertyChange: options.documentAdapter.onRenderingPropertyChange
                 ? (input) => {
@@ -326,12 +497,22 @@ export function createLocalEditorHarness(options) {
                 }
                 : undefined,
             onTransformToolChange: (tool) => {
+                const previous = state.transformTool;
                 commitEditorStateChange(state, options, harness.render, 'transform-tool-change', () => {
                     state.transformTool = tool;
                     state.transformConstraint = normalizeTransformConstraint(tool, state.transformConstraint);
                 }, {
                     syncTransformArtifacts: true,
                 });
+                if (previous !== state.transformTool) {
+                    void options.pluginHost?.eventPublisher.publish(FPS_EDITOR_ACTIVE_TOOL_CHANGED, Object.freeze({
+                        previous,
+                        current: state.transformTool,
+                    }), {
+                        scope: 'session',
+                        scopeId: PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID,
+                    });
+                }
             },
             onTransformSpaceChange: (space) => {
                 commitEditorStateChange(state, options, harness.render, 'transform-space-change', () => {
@@ -456,12 +637,27 @@ export function createLocalEditorHarness(options) {
             },
         },
     });
+    construction.setCleanup(() => {
+        unregisterAgentBridgeLifecycleParticipant?.();
+        unregisterAgentBridgeLifecycleParticipant = null;
+        agentBridgeLifecycleTransports.clear();
+        releaseApplicationAuthorityScopeResource?.();
+        releaseApplicationAuthorityScopeResource = null;
+        releaseMainSessionScopeResource?.();
+        releaseMainSessionScopeResource = null;
+        releaseMainPreviewScopeResource?.();
+        releaseMainPreviewScopeResource = null;
+        disposeLocalEditorHarnessResources(state, ui);
+    });
     const runGameFromEditor = async (reason) => {
         cancelActiveOperation(state);
         await waitForEditorProjectionIdleBeforeRunGame(state);
-        disposeEditorWorld(state);
+        if (!lifecycleController)
+            disposeEditorWorld(state);
         await waitForEditorWorldDisposeBoundary();
-        state.mode = 'game';
+        await options.persistenceAdapter.runGame({ reason });
+        // The lifecycle-owned Session Scope clears these before runGame. Keep the
+        // assignment idempotent for direct harness consumers without a coordinator.
         state.session = null;
         state.source = null;
         state.status = reason === 'save' ? 'Saved scene; starting game' : 'Discarded editor changes; starting game';
@@ -469,9 +665,128 @@ export function createLocalEditorHarness(options) {
         state.statusToneStatus = state.status;
         state.statusDetails = '';
         harness.render();
-        await options.persistenceAdapter.runGame({ reason });
         harness.render();
     };
+    const loadEditorDocument = async () => {
+        const loadedSource = options.persistenceAdapter.loadAuthoringSource
+            ? await options.persistenceAdapter.loadAuthoringSource()
+            : null;
+        const [document, assets] = loadedSource
+            ? [loadedSource.document, loadedSource.assets ?? await options.persistenceAdapter.loadAssets()]
+            : [await loadDocumentFallback(options), await options.persistenceAdapter.loadAssets()];
+        const source = loadedSource?.source ?? null;
+        const preparedDocument = options.documentAdapter.prepareDocument?.(document, assets) ?? document;
+        state.assets = assets;
+        state.source = source;
+        state.markerGraphVisibility = createDefaultMarkerGraphVisibilityState();
+        state.activeMarkerRelationId = null;
+        state.markerRelationHighlightContinuous = false;
+        state.markerCreateReservations = createEmptyMarkerCreateReservations();
+        state.session = createEditorSession({
+            source: source ?? undefined,
+            persistedDocument: preparedDocument,
+            cloneDocument: options.documentAdapter.cloneDocument,
+            compareDocuments: options.documentAdapter.compareDocuments,
+            reduceDocument: options.documentAdapter.reduceDocument,
+            onChange: handleEditorSessionChange,
+            onChangeError: handleEditorSessionObserverError,
+        });
+        try {
+            attachLifecycleOwnedSessionAuthority();
+        }
+        catch (error) {
+            state.session = null;
+            state.source = null;
+            throw error;
+        }
+        state.summary = loadedSource?.summary ?? summarizeDocument(options, preparedDocument, source);
+    };
+    const enterEditorWorld = async () => {
+        if (!state.session)
+            throw new Error('Editor document must be loaded before entering the editor world.');
+        attachLifecycleOwnedApplicationAuthority();
+        attachLifecycleOwnedSessionAuthority();
+        await options.worldAdapter.disposeGameWorld();
+        releaseMainPreviewScopeResource?.();
+        releaseMainPreviewScopeResource = null;
+        if (lifecycleController) {
+            releaseMainPreviewScopeResource = lifecycleController.addScopeResource(PLAYABLE_LOCAL_EDITOR_MAIN_PREVIEW_SCOPE_ID, async () => {
+                releaseMainPreviewScopeResource = null;
+                const prefabStage = state.prefabStage;
+                if (prefabStage) {
+                    await closePrefabStageLifecycleScopes(state, prefabStage);
+                    if (state.prefabStage === prefabStage)
+                        clearPrefabStageForEditorTeardown(state);
+                }
+                disposeEditorWorld(state);
+            });
+        }
+        try {
+            await createEditorWorld(state, options, harness.render, previewState => {
+                if (ui.updatePreview)
+                    ui.updatePreview(previewState);
+                else
+                    ui.update(createUiState(state, options));
+                syncPrefabComparisonPreviewSurfaces(state, ui);
+            }, stats => ui.updateSceneFrameStats?.(stats), stats => ui.updatePerformanceStats?.(stats), () => ui.getPrefabComparisonPreviewSurfaces?.() ?? []);
+        }
+        catch (error) {
+            if (!lifecycleController)
+                disposeEditorWorld(state);
+            throw error;
+        }
+        state.status = `GameWorld disposed; EditorWorld active; assets=${state.assets.length}`;
+        harness.render();
+        harness.notifyViewportRevealed('editor-enter');
+    };
+    const restoreEditorDocument = async () => {
+        const sessionState = state.session?.getState({ cloneDocuments: false });
+        if (!state.session || !sessionState)
+            throw new Error('Cannot discard an unloaded editor document.');
+        state.session.reset(sessionState.persistedDocument, sessionState.source);
+        state.source = sessionState.source ?? null;
+        state.summary = summarizeDocument(options, sessionState.persistedDocument, state.source);
+        state.status = 'Editor changes discarded';
+        state.statusTone = 'default';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+    };
+    const markDocumentCommitted = async (expectedDocumentFingerprint) => {
+        const sessionState = state.session?.getState({ cloneDocuments: false });
+        if (!state.session || !sessionState)
+            throw new Error('Cannot commit an unloaded editor document.');
+        if (createLocalEditorDocumentFingerprint(sessionState.workingDocument) !== expectedDocumentFingerprint) {
+            throw new Error('Editor document changed after export; refusing to commit a stale snapshot.');
+        }
+        state.session.markSaved(sessionState.workingDocument, sessionState.source);
+        state.source = sessionState.source ?? null;
+        state.status = 'Platform save committed';
+        state.statusTone = 'success';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+    };
+    const scheduleEditorLifecycleExit = (exitEditor) => {
+        if (state.busy)
+            throw new Error('Local editor host is busy.');
+        state.busy = true;
+        harness.render();
+        globalThis.setTimeout(() => {
+            void exitEditor()
+                .then(() => new Promise(resolve => globalThis.setTimeout(resolve, 0)))
+                .catch(error => {
+                state.status = error instanceof Error ? error.message : String(error);
+                state.statusTone = 'error';
+                state.statusToneStatus = state.status;
+                state.statusDetails = state.status;
+                console.error('[LocalEditorHarness] scheduled run failed', error);
+            })
+                .finally(() => {
+                state.busy = false;
+                if (state.session)
+                    harness.render();
+            });
+        }, 0);
+    };
     harness = {
         render() {
             syncViewportCameraState(state);
@@ -515,6 +830,9 @@ export function createLocalEditorHarness(options) {
         getDefaultInteractionPolicy() {
             return createLocalEditorDataSafetyInteractionPolicy(ui);
         },
+        getLifecycleService() {
+            return lifecycleController?.lifecycle ?? null;
+        },
         async reloadAssets() {
             try {
                 const assets = await options.persistenceAdapter.loadAssets();
@@ -563,40 +881,8 @@ export function createLocalEditorHarness(options) {
             return waitForHistoryOperationProjection(state, result);
         },
         async enterEditor() {
-            const loadedSource = options.persistenceAdapter.loadAuthoringSource
-                ? await options.persistenceAdapter.loadAuthoringSource()
-                : null;
-            const [document, assets] = loadedSource
-                ? [loadedSource.document, loadedSource.assets ?? await options.persistenceAdapter.loadAssets()]
-                : [await loadDocumentFallback(options), await options.persistenceAdapter.loadAssets()];
-            const source = loadedSource?.source ?? null;
-            const preparedDocument = options.documentAdapter.prepareDocument?.(document, assets) ?? document;
-            state.assets = assets;
-            state.source = source;
-            state.markerGraphVisibility = createDefaultMarkerGraphVisibilityState();
-            state.activeMarkerRelationId = null;
-            state.markerRelationHighlightContinuous = false;
-            state.markerCreateReservations = createEmptyMarkerCreateReservations();
-            state.session = createEditorSession({
-                source: source ?? undefined,
-                persistedDocument: preparedDocument,
-                cloneDocument: options.documentAdapter.cloneDocument,
-                compareDocuments: options.documentAdapter.compareDocuments,
-                reduceDocument: options.documentAdapter.reduceDocument,
-            });
-            await options.worldAdapter.disposeGameWorld();
-            await createEditorWorld(state, options, harness.render, previewState => {
-                if (ui.updatePreview)
-                    ui.updatePreview(previewState);
-                else
-                    ui.update(createUiState(state, options));
-                syncPrefabComparisonPreviewSurfaces(state, ui);
-            }, stats => ui.updateSceneFrameStats?.(stats), stats => ui.updatePerformanceStats?.(stats), () => ui.getPrefabComparisonPreviewSurfaces?.() ?? []);
-            state.mode = 'editor';
-            state.summary = loadedSource?.summary ?? summarizeDocument(options, preparedDocument, source);
-            state.status = `GameWorld disposed; EditorWorld active; assets=${assets.length}`;
-            harness.render();
-            harness.notifyViewportRevealed('editor-enter');
+            await loadEditorDocument();
+            await enterEditorWorld();
         },
         async saveScene() {
             cancelActiveOperation(state);
@@ -646,7 +932,17 @@ export function createLocalEditorHarness(options) {
                         cloneDocument: options.documentAdapter.cloneDocument,
                         compareDocuments: options.documentAdapter.compareDocuments,
                         reduceDocument: options.documentAdapter.reduceDocument,
+                        onChange: handleEditorSessionChange,
+                        onChangeError: handleEditorSessionObserverError,
                     });
+                    try {
+                        attachLifecycleOwnedSessionAuthority();
+                    }
+                    catch (error) {
+                        state.session = null;
+                        state.source = null;
+                        throw error;
+                    }
                 }
                 state.summary = result.summary ?? summarizeDocument(options, preparedDocument, savedSource ?? null);
                 state.status = 'Scene saved';
@@ -675,22 +971,34 @@ export function createLocalEditorHarness(options) {
             await runGameFromEditor('discard');
         },
         dispose() {
-            state.agentBridgeTransport?.dispose();
-            state.agentBridgeTransport = null;
-            state.unregisterAgentBridgeCapabilities?.();
-            state.unregisterAgentBridgeCapabilities = null;
-            disposeEditorWorld(state);
-            state.session = null;
-            ui.dispose();
+            construction.dispose();
+        },
+    };
+    agentLifecycleController = {
+        enterEditor: () => harness.enterEditor(),
+        saveScene: () => harness.saveScene(),
+        saveAndRunGame: () => harness.saveAndRunGame(),
+        async discardAndRunGame() {
+            await harness.discardAndRunGame();
+            return true;
+        },
+        async prepareSaveAndRunGame() {
+            const saved = await harness.saveScene();
+            return saved
+                ? { accepted: true, run: () => runGameFromEditor('save') }
+                : { accepted: false };
+        },
+        async prepareDiscardAndRunGame() {
+            return { accepted: true, run: () => runGameFromEditor('discard') };
         },
     };
     const agentBridgeCapabilitySourceOperations = {
         createAssetFromAssetId: (assetId, createOptions) => harness.createAssetFromAssetId(assetId, createOptions),
         getPrefabStage: () => summarizeAgentBridgePrefabStage(state, options),
         getPrefabStageDetails: () => summarizeAgentBridgePrefabStageDetails(state, options),
-        openPrefabStage: (input) => {
+        openPrefabStage: input => runExclusiveResult(state, harness.render, async () => {
             const previousStage = summarizeAgentBridgePrefabStage(state, options);
-            const opened = enterPrefabStage(state, options, {
+            const opened = await enterPrefabStage(state, options, {
                 actionId: 'asset.edit-prefab',
                 assetId: input.assetId,
                 browserAssetId: input.browserAssetId,
@@ -707,17 +1015,17 @@ export function createLocalEditorHarness(options) {
                 stage,
                 status: state.status,
             };
-        },
-        exitPrefabStage: () => {
+        }),
+        exitPrefabStage: () => runExclusiveResult(state, harness.render, async () => {
             const previousStage = summarizeAgentBridgePrefabStage(state, options);
-            const exited = exitPrefabStage(state, options);
+            const exited = await exitPrefabStage(state, options);
             return {
                 exited,
                 wasOpen: !!previousStage,
                 ...(previousStage ? { previousStage } : {}),
                 status: exited ? state.status : 'No Prefab stage is open.',
             };
-        },
+        }),
         selectPrefabStageItem: itemId => selectPrefabStageItemWithPreviewSync(state, options, itemId),
         runPrefabStageAssetAction: input => patchBrowserAssetAction(state, options, input),
         getHierarchy: () => createUiState(state, options).hierarchy,
@@ -764,17 +1072,230 @@ export function createLocalEditorHarness(options) {
         },
         runRenderingAction: actionId => applyRenderingAction(state, options, { actionId }, () => harness.render()),
     };
-    state.unregisterAgentBridgeCapabilities = registerLocalEditorAgentBridgeCapabilities(state.agentBridge, createLocalEditorAgentBridgeCapabilitySources(state, options, () => harness.render(), () => runExclusive(state, harness.render, () => harness.enterEditor()), agentBridgeCapabilitySourceOperations));
-    state.agentBridgeTransport = createLocalEditorAgentBridgeWebSocketTransportFromQuery(state.agentBridge, {
-        metadata: options.agentBridge?.sessionMetadata,
-        onStatusChange: agentBridgeStatus => {
-            state.agentBridgeStatus = agentBridgeStatus;
-            harness.render();
+    const registerAgentBridgeCapabilities = () => {
+        if (state.unregisterAgentBridgeCapabilities)
+            return;
+        const unregisterStandardAgentCapabilities = registerLocalEditorAgentBridgeCapabilities(state.agentBridge, createLocalEditorAgentBridgeCapabilitySources(state, options, () => harness.render(), context => runExclusive(state, harness.render, () => agentLifecycleController.enterEditor(context)), async (context) => {
+            const prepared = await runExclusiveResult(state, harness.render, () => agentLifecycleController.prepareSaveAndRunGame(context));
+            if (prepared.accepted)
+                scheduleEditorLifecycleExit(prepared.run);
+            return prepared.accepted;
+        }, async (context) => {
+            const prepared = await runExclusiveResult(state, harness.render, () => agentLifecycleController.prepareDiscardAndRunGame(context));
+            if (prepared.accepted)
+                scheduleEditorLifecycleExit(prepared.run);
+            return prepared.accepted;
+        }, agentBridgeCapabilitySourceOperations));
+        try {
+            const unregisterPluginAgentCapabilities = registerEditorPluginAgentCapabilities(state.agentBridge, options.pluginHost);
+            state.unregisterAgentBridgeCapabilities = () => {
+                const errors = [];
+                try {
+                    unregisterPluginAgentCapabilities();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+                try {
+                    unregisterStandardAgentCapabilities();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+                if (errors.length > 0) {
+                    const error = new Error('Local Editor Agent capability cleanup failed.');
+                    error.errors = errors;
+                    throw error;
+                }
+            };
+        }
+        catch (error) {
+            try {
+                unregisterStandardAgentCapabilities();
+            }
+            catch (cleanupError) {
+                const combined = new Error('Plugin Agent capability registration failed and standard capability rollback reported errors.');
+                combined.errors = [error, cleanupError];
+                throw combined;
+            }
+            throw error;
+        }
+    };
+    const activateAgentBridgeAuthority = () => {
+        registerAgentBridgeCapabilities();
+        if (state.agentBridgeTransport)
+            return;
+        state.agentBridgeTransport = createLocalEditorAgentBridgeWebSocketTransportFromQuery(state.agentBridge, {
+            metadata: options.agentBridge?.sessionMetadata,
+            onStatusChange: agentBridgeStatus => {
+                state.agentBridgeStatus = agentBridgeStatus;
+                harness.render();
+            },
+        });
+    };
+    const disposeAgentBridgeAuthority = () => {
+        if (state.agentBridgeTransport) {
+            state.agentBridgeTransport.dispose();
+            state.agentBridgeTransport = null;
+        }
+        if (state.unregisterAgentBridgeCapabilities) {
+            state.unregisterAgentBridgeCapabilities();
+            state.unregisterAgentBridgeCapabilities = null;
+        }
+    };
+    const attachLifecycleOwnedApplicationAuthority = () => {
+        if (!lifecycleController)
+            return;
+        if (!unsubscribeLifecycleRender)
+            attachLifecycleRenderSubscription();
+        activateAgentBridgeAuthority();
+        attachAgentBridgeLifecycleParticipant();
+        if (!releaseApplicationAuthorityScopeResource) {
+            releaseApplicationAuthorityScopeResource = lifecycleController.addScopeResource(PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID, () => {
+                disposeAgentBridgeAuthority();
+                releaseApplicationAuthorityScopeResource = null;
+            });
+        }
+    };
+    const reportAgentBridgeLifecycleTransition = (event) => {
+        const transitionId = event.transition.id;
+        const transport = agentBridgeLifecycleTransports.get(transitionId)
+            ?? state.agentBridgeTransport;
+        transport?.reportLifecycleTransition(event);
+        if (event.status !== 'started')
+            agentBridgeLifecycleTransports.delete(transitionId);
+    };
+    const attachAgentBridgeLifecycleParticipant = () => {
+        unregisterAgentBridgeLifecycleParticipant?.();
+        unregisterAgentBridgeLifecycleParticipant = null;
+        if (!lifecycleController)
+            return;
+        unregisterAgentBridgeLifecycleParticipant = lifecycleController.registerParticipant({
+            id: 'fps.editor.agent-bridge.lifecycle-trace',
+            transitions: FPS_EDITOR_LIFECYCLE_TRANSITION_TYPES,
+            prepare(context) {
+                const transport = state.agentBridgeTransport;
+                if (transport)
+                    agentBridgeLifecycleTransports.set(context.transition.id, transport);
+                reportAgentBridgeLifecycleTransition({
+                    status: 'started',
+                    transition: context.transition,
+                    previous: context.before,
+                    current: context.getSnapshot(),
+                });
+            },
+            settled: reportAgentBridgeLifecycleTransition,
+            failed: reportAgentBridgeLifecycleTransition,
+        });
+    };
+    const attachLifecycleRenderSubscription = () => {
+        releaseLifecycleRenderScopeResource?.();
+        releaseLifecycleRenderScopeResource = null;
+        unsubscribeLifecycleRender?.();
+        unsubscribeLifecycleRender = null;
+        if (!lifecycleController)
+            return;
+        const lifecycle = lifecycleController.lifecycle;
+        const unsubscribe = lifecycle.subscribe(() => harness.render());
+        unsubscribeLifecycleRender = unsubscribe;
+        releaseLifecycleRenderScopeResource = lifecycleController.addScopeResource(PLAYABLE_LOCAL_EDITOR_APPLICATION_SCOPE_ID, () => {
+            unsubscribe();
+            if (unsubscribeLifecycleRender === unsubscribe)
+                unsubscribeLifecycleRender = null;
+            releaseLifecycleRenderScopeResource = null;
+        });
+    };
+    const attachLifecycleOwnedSessionAuthority = () => {
+        if (!lifecycleController || !state.session)
+            return;
+        if (!releaseMainSessionScopeResource) {
+            releaseMainSessionScopeResource = lifecycleController.addScopeResource(PLAYABLE_LOCAL_EDITOR_MAIN_SESSION_SCOPE_ID, () => {
+                state.session = null;
+                state.source = null;
+                releaseMainSessionScopeResource = null;
+            });
+        }
+    };
+    activateAgentBridgeAuthority();
+    registerLocalEditorHarnessLifecycleOperations(harness, {
+        runGame: runGameFromEditor,
+        attachApplicationAuthority: attachLifecycleOwnedApplicationAuthority,
+        attachSessionAuthority: attachLifecycleOwnedSessionAuthority,
+        loadDocument: loadEditorDocument,
+        enterWorld: enterEditorWorld,
+        restoreDocument: restoreEditorDocument,
+        markDocumentCommitted,
+        setLifecycleController(controller) {
+            agentLifecycleController = controller;
+            lifecycleController = controller.lifecycle
+                && controller.synchronizeDocumentState
+                && controller.registerParticipant
+                && controller.openScope
+                && controller.addScopeResource
+                && controller.closeScope
+                ? controller
+                : null;
+            state.scopeOperations = lifecycleController;
+            attachLifecycleRenderSubscription();
+            attachLifecycleOwnedApplicationAuthority();
+            if (lifecycleController && state.session) {
+                attachLifecycleOwnedSessionAuthority();
+                void lifecycleController.synchronizeDocumentState(state.session.isDirty()).catch(error => {
+                    console.error('[LocalEditorHarness] lifecycle document synchronization failed', error);
+                });
+            }
         },
     });
     harness.render();
     return harness;
 }
+function createLocalEditorDocumentFingerprint(document) {
+    if (document == null)
+        return null;
+    try {
+        return JSON.stringify(document);
+    }
+    catch {
+        return null;
+    }
+}
+function disposeLocalEditorHarnessResources(state, ui) {
+    const errors = [];
+    const dispose = (operation, onSuccess) => {
+        try {
+            operation();
+            onSuccess?.();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    };
+    dispose(() => state.agentBridgeTransport?.dispose(), () => { state.agentBridgeTransport = null; });
+    dispose(() => state.unregisterAgentBridgeCapabilities?.(), () => {
+        state.unregisterAgentBridgeCapabilities = null;
+    });
+    dispose(() => disposeEditorWorld(state), () => { state.session = null; });
+    dispose(() => ui.dispose());
+    if (errors.length > 0) {
+        const error = new Error('Local Editor Harness cleanup failed.');
+        error.errors = errors;
+        throw error;
+    }
+}
+function createLocalEditorHarnessConstructionError(constructionError, cleanupError, retryCleanup) {
+    const error = new Error('Local Editor Harness construction and rollback failed.');
+    Object.defineProperties(error, {
+        errors: { value: [constructionError, cleanupError], enumerable: true },
+        retryCleanup: { value: retryCleanup, enumerable: false },
+    });
+    return error;
+}
+function readRetryCleanup(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const retryCleanup = error.retryCleanup;
+    return typeof retryCleanup === 'function' ? retryCleanup : null;
+}
 export function mergeLocalEditorHarnessInspectorComponentSections(input) {
     const components = input.components;
     if (!components)
@@ -1117,7 +1638,9 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     if (!canvas)
         throw new Error('Editor canvas not found');
     const babylon = await options.worldAdapter.loadBabylon();
+    state.babylon = babylon;
     const engine = options.worldAdapter.createEngine(babylon, canvas);
+    state.engine = engine;
     const document = state.session?.getState().workingDocument;
     const initialAppearance = resolveEffectiveLocalEditorWorldAppearance(state, options, document);
     const initialAppearanceKey = serializeLocalEditorWorldAppearance(initialAppearance);
@@ -1134,7 +1657,9 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         useRightHandedSystem: options.world?.useRightHandedSystem,
         enableDefaultCameraControls: false,
     });
+    state.world = world;
     const performanceMonitor = createBabylonEditorPerformanceMonitor(world.scene);
+    state.performanceMonitor = performanceMonitor;
     const sceneRenderScheduler = createLocalEditorSceneRenderScheduler((frame) => {
         state.sceneViewInteraction?.updateFrame(frame);
         syncPrefabComparisonPreviewSurfaces(state, { getPrefabComparisonPreviewSurfaces });
@@ -1147,11 +1672,13 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             updateLocalEditorPerformanceStats(state, updatePerformanceStats);
         },
     });
+    state.sceneRenderScheduler = sceneRenderScheduler;
     const viewportRenderCoordinator = createLocalEditorViewportRenderCoordinator({
         scheduler: sceneRenderScheduler,
         getEngine: () => engine,
         getScene: () => world.scene,
     });
+    state.viewportRenderCoordinator = viewportRenderCoordinator;
     const sceneViewInteraction = createLocalEditorSceneViewInteractionRuntime({
         coordinator: viewportRenderCoordinator,
         getCamera: () => state.sceneViewCamera,
@@ -1161,6 +1688,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         getCamera: () => world.scene?.activeCamera ?? world.camera ?? null,
         getEditorCamera: () => world.camera ?? null,
     }) ?? null;
+    state.grid = grid;
     if (initialAppearance.grid)
         grid?.setColors(initialAppearance.grid);
     grid?.setVisible(state.gridVisible);
@@ -1170,7 +1698,10 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         importModel: options.worldAdapter.importProjectionModel,
         resolveTextureUrl: options.worldAdapter.resolveMaterialTextureUrl,
         selectionEdgesPrewarm: options.world?.selectionEdgesPrewarm,
-        logger: console,
+        logger: createLocalEditorProjectionLogger(),
+        onMaterialProfileDiagnostic(diagnostic) {
+            recordLocalEditorMaterialProfileDiagnostic(state, diagnostic);
+        },
         onProjectionReady(event) {
             if (state.prefabStage) {
                 syncPrefabStageSelectionToProjection(state, options, `prefab-stage-projection-${event.nodeId}-ready-selection`);
@@ -1196,6 +1727,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             scheduleProjectionShadowPreviewRebuild(state, `projection-batch-${event.batchId}-settled`);
         },
     });
+    state.projection = projection;
     const prefabComparisonPreview = createBabylonPrefabComparisonPreviewController({
         babylon,
         scene: world.scene,
@@ -1203,11 +1735,14 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         projection,
         getSkyBackdrop: () => world.skyBackdrop,
     });
+    state.prefabComparisonPreview = prefabComparisonPreview;
     const markerOverlay = createBabylonEditorMarkerOverlayController({
         babylon,
         scene: world.scene,
     });
+    state.markerOverlay = markerOverlay;
     const markerAwareProjection = createBabylonMarkerOverlayProjectionAdapter(projection, markerOverlay);
+    state.projection = markerAwareProjection;
     const gizmo = createBabylonTransformGizmoController({
         babylon,
         scene: world.scene,
@@ -1276,6 +1811,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             return beginDuplicateDrag(state, options, input);
         },
     });
+    state.gizmo = gizmo;
     gizmo.setOperationSettings(getScopedTransformOperationSettings(state));
     gizmo.setConstraint(state.transformConstraint);
     const selectionController = createBabylonProjectionSelectionController({
@@ -1315,10 +1851,12 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             preview('viewport-box-selection-preview');
         },
     });
+    state.selectionController = selectionController;
     const sceneViewMeasurement = createBabylonSceneViewMeasurementController({
         babylon,
         scene: world.scene,
     });
+    state.sceneViewMeasurement = sceneViewMeasurement;
     const sceneViewInput = createBabylonSceneViewInputController({
         canvas,
         isEnabled: () => state.mode === 'editor',
@@ -1434,21 +1972,25 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             renderUi();
         },
     });
+    state.sceneViewInput = sceneViewInput;
     const sceneViewCamera = createBabylonSceneViewCameraController({
         babylon,
         scene: world.scene,
         camera: world.camera,
         input: sceneViewInput,
     });
+    state.sceneViewCamera = sceneViewCamera;
     const sceneCameraPreview = createBabylonSceneCameraPreviewController({
         babylon,
         scene: world.scene,
         editorCamera: world.camera,
     });
+    state.sceneCameraPreview = sceneCameraPreview;
     const sceneViewSpatialOverlay = createBabylonSceneViewSpatialOverlayController({
         babylon,
         scene: world.scene,
     });
+    state.sceneViewSpatialOverlay = sceneViewSpatialOverlay;
     const shadowPreview = createBabylonEditorShadowPreviewController({
         scene: world.scene,
         projection,
@@ -1457,39 +1999,22 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             viewportRenderCoordinator.invalidateScene(`static-shadow-texture-ready-${event.chunkId}`);
         },
     });
+    state.shadowPreview = shadowPreview;
     const environmentTexture = createBabylonEnvironmentTextureController(world.scene, initialRendering.environment ?? null);
+    state.environmentTexture = environmentTexture;
     world.refreshSkyBackdrop();
     const postProcess = createBabylonDefaultPostProcessPipelineController(world.scene, [world.camera], initialRendering.postProcess ?? null, { name: 'editorDefaultPostProcessPipeline' });
+    state.postProcess = postProcess;
     const resize = () => {
         engine.resize?.();
         viewportRenderCoordinator.requestFrame('resize');
     };
     window.addEventListener('resize', resize);
-    state.babylon = babylon;
-    state.engine = engine;
-    state.world = world;
-    state.grid = grid;
-    state.projection = markerAwareProjection;
-    state.prefabComparisonPreview = prefabComparisonPreview;
-    state.markerOverlay = markerOverlay;
-    state.shadowPreview = shadowPreview;
-    state.environmentTexture = environmentTexture;
-    state.postProcess = postProcess;
-    state.gizmo = gizmo;
-    state.sceneCameraPreview = sceneCameraPreview;
-    state.sceneViewInput = sceneViewInput;
-    state.sceneViewCamera = sceneViewCamera;
-    state.sceneViewMeasurement = sceneViewMeasurement;
-    state.sceneViewSpatialOverlay = sceneViewSpatialOverlay;
-    state.selectionController = selectionController;
-    state.sceneRenderScheduler = sceneRenderScheduler;
-    state.viewportRenderCoordinator = viewportRenderCoordinator;
+    state.resizeHandler = resize;
     state.sceneFrameStats = sceneRenderScheduler.getStats();
-    state.performanceMonitor = performanceMonitor;
     updateLocalEditorPerformanceStats(state, updatePerformanceStats);
     state.worldAppearanceKey = initialAppearanceKey;
     state.worldRenderingKey = initialRenderingKey;
-    state.resizeHandler = resize;
     if (document) {
         projection.projectNodes(resolveCurrentEditorProjectionNodes(state, options, document));
         applyPreviewVisibilityStateToProjection(state);
@@ -1499,45 +2024,52 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     viewportRenderCoordinator.requestFrame('editor-world-created');
 }
 function disposeEditorWorld(state) {
-    clearPrefabStageForEditorTeardown(state);
+    const run = (operation) => {
+        try {
+            operation();
+        }
+        catch (cause) {
+            const error = new Error('Local Editor world cleanup failed.');
+            error.cause = cause;
+            throw error;
+        }
+    };
+    const disposeField = (read, clear) => run(() => {
+        read()?.dispose();
+        clear();
+    });
+    run(() => clearPrefabStageForEditorTeardown(state));
     state.activeTransformPreview = null;
-    state.sceneViewInteraction?.dispose();
-    state.sceneViewInteraction = null;
+    disposeField(() => state.sceneViewInteraction, () => { state.sceneViewInteraction = null; });
     if (state.resizeHandler) {
-        window.removeEventListener('resize', state.resizeHandler);
-        state.resizeHandler = null;
+        run(() => {
+            window.removeEventListener('resize', state.resizeHandler);
+            state.resizeHandler = null;
+        });
     }
-    state.sceneCameraPreview?.dispose();
-    state.sceneCameraPreview = null;
+    disposeField(() => state.sceneCameraPreview, () => { state.sceneCameraPreview = null; });
     state.sceneCameraPreviewEnabled = false;
-    state.sceneViewCamera?.dispose();
-    state.sceneViewCamera = null;
-    state.sceneViewMeasurement?.dispose();
-    state.sceneViewMeasurement = null;
-    state.sceneViewSpatialOverlay?.dispose();
-    state.sceneViewSpatialOverlay = null;
-    state.sceneViewInput?.dispose();
-    state.sceneViewInput = null;
-    state.selectionController?.dispose();
-    state.selectionController = null;
-    state.prefabComparisonPreview?.dispose();
-    state.prefabComparisonPreview = null;
+    disposeField(() => state.sceneViewCamera, () => { state.sceneViewCamera = null; });
+    disposeField(() => state.sceneViewMeasurement, () => { state.sceneViewMeasurement = null; });
+    disposeField(() => state.sceneViewSpatialOverlay, () => { state.sceneViewSpatialOverlay = null; });
+    disposeField(() => state.sceneViewInput, () => { state.sceneViewInput = null; });
+    disposeField(() => state.selectionController, () => { state.selectionController = null; });
+    disposeField(() => state.prefabComparisonPreview, () => { state.prefabComparisonPreview = null; });
     if (state.markerRelationHighlightContinuous) {
-        state.viewportRenderCoordinator?.endContinuous(MARKER_RELATION_HIGHLIGHT_RENDER_REASON);
-        state.markerRelationHighlightContinuous = false;
+        run(() => {
+            state.viewportRenderCoordinator?.endContinuous(MARKER_RELATION_HIGHLIGHT_RENDER_REASON);
+            state.markerRelationHighlightContinuous = false;
+        });
     }
     if (state.performanceMonitorOpen) {
-        state.viewportRenderCoordinator?.endContinuous(LOCAL_EDITOR_PERFORMANCE_MONITOR_REASON);
+        run(() => state.viewportRenderCoordinator?.endContinuous(LOCAL_EDITOR_PERFORMANCE_MONITOR_REASON));
     }
     state.performanceMonitorOpen = false;
-    state.performanceMonitor?.dispose();
-    state.performanceMonitor = null;
+    disposeField(() => state.performanceMonitor, () => { state.performanceMonitor = null; });
     state.performanceStats = null;
     state.performanceObjectCount = null;
-    state.viewportRenderCoordinator?.dispose();
-    state.viewportRenderCoordinator = null;
-    state.sceneRenderScheduler?.dispose();
-    state.sceneRenderScheduler = null;
+    disposeField(() => state.viewportRenderCoordinator, () => { state.viewportRenderCoordinator = null; });
+    disposeField(() => state.sceneRenderScheduler, () => { state.sceneRenderScheduler = null; });
     state.sceneFrameStats = null;
     state.boxSelection = null;
     state.viewportSpatialOverlay = createEmptyEditorViewportSpatialOverlayState();
@@ -1546,34 +2078,32 @@ function disposeEditorWorld(state) {
         ...state.viewportTools,
         activeUtilityTool: 'none',
     };
-    state.gizmo?.dispose();
-    state.gizmo = null;
-    state.markerOverlay?.dispose();
-    state.markerOverlay = null;
+    disposeField(() => state.gizmo, () => { state.gizmo = null; });
+    disposeField(() => state.markerOverlay, () => { state.markerOverlay = null; });
     if (state.projectionShadowPreviewRebuildFrame !== null) {
-        window.cancelAnimationFrame(state.projectionShadowPreviewRebuildFrame);
-        state.projectionShadowPreviewRebuildFrame = null;
+        run(() => {
+            window.cancelAnimationFrame(state.projectionShadowPreviewRebuildFrame);
+            state.projectionShadowPreviewRebuildFrame = null;
+        });
     }
     if (state.projectionShadowPreviewRefreshFrame !== null) {
-        window.cancelAnimationFrame(state.projectionShadowPreviewRefreshFrame);
-        state.projectionShadowPreviewRefreshFrame = null;
+        run(() => {
+            window.cancelAnimationFrame(state.projectionShadowPreviewRefreshFrame);
+            state.projectionShadowPreviewRefreshFrame = null;
+        });
     }
-    state.shadowPreview?.dispose();
-    state.shadowPreview = null;
-    state.environmentTexture?.dispose();
-    state.environmentTexture = null;
-    state.postProcess?.dispose();
-    state.postProcess = null;
-    state.projection?.dispose();
-    state.projection = null;
-    state.grid?.dispose();
-    state.grid = null;
-    state.engine?.stopRenderLoop?.();
-    state.world?.dispose();
-    state.engine?.dispose?.();
+    disposeField(() => state.shadowPreview, () => { state.shadowPreview = null; });
+    disposeField(() => state.environmentTexture, () => { state.environmentTexture = null; });
+    disposeField(() => state.postProcess, () => { state.postProcess = null; });
+    disposeField(() => state.projection, () => { state.projection = null; });
+    disposeField(() => state.grid, () => { state.grid = null; });
+    run(() => state.engine?.stopRenderLoop?.());
+    disposeField(() => state.world, () => { state.world = null; });
+    run(() => {
+        state.engine?.dispose?.();
+        state.engine = null;
+    });
     state.babylon = null;
-    state.world = null;
-    state.engine = null;
 }
 function clearPrefabStageForEditorTeardown(state) {
     const stage = state.prefabStage;
@@ -1718,10 +2248,8 @@ function scheduleProjectionShadowPreviewRefresh(state, reason) {
 async function runExclusive(state, render, action) {
     if (state.busy)
         return;
-    state.busy = true;
-    render();
     try {
-        await action();
+        await runExclusiveResult(state, render, action);
     }
     catch (error) {
         state.status = error instanceof Error ? error.message : String(error);
@@ -1729,6 +2257,16 @@ async function runExclusive(state, render, action) {
         state.statusToneStatus = state.status;
         state.statusDetails = state.status;
         console.error('[LocalEditorHarness] action failed', error);
+        render();
+    }
+}
+async function runExclusiveResult(state, render, action) {
+    if (state.busy)
+        throw new Error('Local editor host is busy.');
+    state.busy = true;
+    render();
+    try {
+        return await action();
     }
     finally {
         state.busy = false;
@@ -1791,10 +2329,16 @@ function createBrowserHierarchyContextActions(state, options) {
     }));
 }
 function createHierarchyContextActionRegistrations(state, options) {
-    return [
+    const local = [
         createPrefabFromGameObjectHierarchyContextAction(state, options),
         ...(options.hierarchy?.contextActions ?? []),
     ];
+    const plugins = createLocalEditorHarnessPluginHierarchyContextActions(options.pluginHost);
+    const localIds = new Set(local.map(action => action.id));
+    const conflict = plugins.find(action => localIds.has(action.id));
+    if (conflict)
+        throw new Error(`Project and Plugin Hierarchy actions share id: ${conflict.id}`);
+    return [...local, ...plugins];
 }
 function createPrefabFromGameObjectHierarchyContextAction(state, options) {
     return {
@@ -1873,20 +2417,34 @@ function runHierarchyCustomContextAction(state, options, action) {
         return false;
     try {
         const result = registration.run(context);
-        if (isLocalEditorHarnessPatchResult(result)) {
-            return applyHierarchyContextActionPatch(state, options, result, registration.label);
+        if (isLocalEditorPromiseLike(result)) {
+            return Promise.resolve(result)
+                .then(value => applyHierarchyContextActionResult(state, options, value, registration.label))
+                .catch(error => reportHierarchyContextActionError(state, registration.label, error));
         }
-        return result === true;
+        return applyHierarchyContextActionResult(state, options, result, registration.label);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        state.status = `${registration.label} failed`;
-        state.statusTone = 'error';
-        state.statusToneStatus = state.status;
-        state.statusDetails = message;
-        console.error('[LocalEditorHarness] hierarchy context action failed', error);
-        return true;
+        return reportHierarchyContextActionError(state, registration.label, error);
+    }
+}
+function isLocalEditorPromiseLike(value) {
+    return !!value && typeof value.then === 'function';
+}
+function applyHierarchyContextActionResult(state, options, result, label) {
+    if (isLocalEditorHarnessPatchResult(result)) {
+        return applyHierarchyContextActionPatch(state, options, result, label);
     }
+    return result === true;
+}
+function reportHierarchyContextActionError(state, label, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    state.status = `${label} failed`;
+    state.statusTone = 'error';
+    state.statusToneStatus = state.status;
+    state.statusDetails = message;
+    console.error('[LocalEditorHarness] hierarchy context action failed', error);
+    return true;
 }
 function isLocalEditorHarnessPatchResult(value) {
     return !!value
@@ -1941,7 +2499,7 @@ function handleContextAction(state, options, action) {
     if (action.region !== 'hierarchy')
         return false;
     if (action.action === 'custom')
-        return runHierarchyCustomContextAction(state, options, action);
+        return false;
     if (action.action === 'focus') {
         const activeId = action.activeId ?? action.targetIds[action.targetIds.length - 1] ?? null;
         const selectionChanged = activeId && !state.session?.getState({ cloneDocuments: false }).selection.selectedIds.includes(activeId)
@@ -2713,7 +3271,7 @@ function syncMarkerOverlayToSceneArtifacts(state, options, selection) {
     const overlay = state.markerOverlay;
     if (!overlay)
         return;
-    const document = state.session?.getState().workingDocument ?? null;
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
     const input = document
         ? createMarkerOverlayInput(state, options, document, selection, createMarkerGraphHierarchyVisibility(state))
         : { markers: [] };
@@ -3216,7 +3774,7 @@ function selectBrowserAsset(state, assetId) {
     state.status = `Selected asset ${assetId}`;
     return true;
 }
-function handleBrowserAssetAction(state, options, input) {
+async function handleBrowserAssetAction(state, options, input) {
     if (input.browserAssetId)
         state.selectedAssetId = input.browserAssetId;
     if (input.actionId === 'asset.edit-prefab') {
@@ -3244,7 +3802,7 @@ function handleBrowserAssetAction(state, options, input) {
     state.statusToneStatus = state.status;
     return true;
 }
-function handleInspectorAction(state, options, input) {
+async function handleInspectorAction(state, options, input) {
     if (!input.actionId.startsWith('prefab.')) {
         const activeId = input.targetId ?? state.session?.getState().selection.activeId ?? null;
         const selectedIds = input.targetIds ?? (activeId ? [activeId] : []);
@@ -3303,7 +3861,7 @@ function readInspectorActionParamString(input, key) {
     const value = input.params?.[key];
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
-function enterPrefabStage(state, options, input) {
+async function enterPrefabStage(state, options, input) {
     if (state.mode !== 'editor')
         return false;
     const sessionState = state.session?.getState({ cloneDocuments: false });
@@ -3328,10 +3886,52 @@ function enterPrefabStage(state, options, input) {
         return true;
     }
     if (previousPrefabStage)
-        state.prefabComparisonPreview?.clear();
+        await exitPrefabStage(state, options);
+    const prefabScopeRevision = ++state.nextPrefabScopeRevision;
+    const documentScopeId = state.scopeOperations
+        ? `editor:document:prefab:${prefabScopeRevision}`
+        : null;
+    const previewScopeId = documentScopeId
+        ? `editor:preview:prefab:${prefabScopeRevision}`
+        : null;
+    if (state.scopeOperations && documentScopeId && previewScopeId) {
+        try {
+            await state.scopeOperations.openScope({
+                id: documentScopeId,
+                scope: 'document',
+                parentId: PLAYABLE_LOCAL_EDITOR_PROJECT_SCOPE_ID,
+            });
+            await state.scopeOperations.openScope({
+                id: previewScopeId,
+                scope: 'preview',
+                parentId: documentScopeId,
+            });
+            state.scopeOperations.addScopeResource(previewScopeId, () => {
+                state.prefabComparisonPreview?.clear();
+                state.activeTransformPreview = null;
+            });
+        }
+        catch (error) {
+            try {
+                await state.scopeOperations.closeScope(documentScopeId);
+            }
+            catch (cleanupError) {
+                const combined = new Error('Prefab lifecycle scope open and rollback failed.');
+                combined.errors = [error, cleanupError];
+                throw combined;
+            }
+            state.status = `Prefab stage lifecycle unavailable: ${descriptor.label}`;
+            state.statusTone = 'error';
+            state.statusToneStatus = state.status;
+            state.statusDetails = stringifyLocalEditorError(error) ?? 'Unknown lifecycle scope error';
+            return true;
+        }
+    }
     state.prefabStage = {
         descriptor,
         asset,
+        documentScopeId,
+        previewScopeId,
         selectedItemId: 'prefab-root',
         restoreGridVisible: previousPrefabStage?.restoreGridVisible ?? state.gridVisible,
         restoreSceneCameraPreviewEnabled: previousPrefabStage?.restoreSceneCameraPreviewEnabled ?? state.sceneCameraPreviewEnabled,
@@ -3347,15 +3947,17 @@ function enterPrefabStage(state, options, input) {
     syncTransformOperationSettingsToSceneArtifacts(state, 'prefab-stage-enter-operation-settings');
     return true;
 }
-function exitPrefabStage(state, options) {
+async function exitPrefabStage(state, options) {
     if (!state.prefabStage)
         return false;
     const sessionState = state.session?.getState({ cloneDocuments: false });
     const label = sessionState?.workingDocument
         ? resolvePrefabStageDescriptorForDocument(state, options, sessionState.workingDocument)?.label ?? state.prefabStage.descriptor.label
         : state.prefabStage.descriptor.label;
-    const restoreGridVisible = state.prefabStage.restoreGridVisible;
-    const restoreSceneCameraPreviewEnabled = state.prefabStage.restoreSceneCameraPreviewEnabled;
+    const prefabStage = state.prefabStage;
+    const restoreGridVisible = prefabStage.restoreGridVisible;
+    const restoreSceneCameraPreviewEnabled = prefabStage.restoreSceneCameraPreviewEnabled;
+    await closePrefabStageLifecycleScopes(state, prefabStage);
     state.prefabStage = null;
     setGridVisibleForEditorContext(state, restoreGridVisible, 'prefab-stage-exit-grid');
     if (sessionState?.workingDocument) {
@@ -3373,6 +3975,11 @@ function exitPrefabStage(state, options) {
     state.statusDetails = '';
     return true;
 }
+async function closePrefabStageLifecycleScopes(state, stage) {
+    if (!stage.documentScopeId)
+        return;
+    await state.scopeOperations?.closeScope(stage.documentScopeId);
+}
 function selectPrefabStageItem(state, itemId) {
     if (!state.prefabStage || state.prefabStage.selectedItemId === itemId)
         return false;
@@ -3635,7 +4242,7 @@ function isPrefabStageShadowAssetAction(input) {
     if (input.actionId !== 'asset.edit-prefab-field')
         return false;
     const fieldPath = typeof input.fieldPath === 'string' ? input.fieldPath.trim() : '';
-    return fieldPath === 'prefab.defaults.shadowMode' || fieldPath.startsWith('prefab.defaults.shadow.');
+    return fieldPath.startsWith('prefab.defaults.shadow.');
 }
 function syncPrefabStageSelectionFromAssetAction(state, options, input, nodeId) {
     if (!state.prefabStage)
@@ -4628,10 +5235,7 @@ function createInspectorObjectForEdit(state, options, document, input, targetIds
     const inspector = options.documentAdapter.getInspectorObject?.(document, input.targetId) ?? null;
     if (inspector)
         return withDefaultEditorInspectorSections(state, options, document, inspector);
-    const serializedObject = options.documentAdapter.getSerializedObject(document, input.targetId);
-    return serializedObject
-        ? withDefaultEditorInspectorSections(state, options, document, serializedObjectToInspectorObject(serializedObject, document))
-        : null;
+    return null;
 }
 function createPrefabStageInspectorObjectForEdit(state, options, document) {
     const stage = state.prefabStage;
@@ -4686,11 +5290,10 @@ function isSerializedProjectionMetadataPath(path) {
     return isSerializedShadowMetadataPath(path);
 }
 function isSerializedShadowMetadataPath(path) {
-    return path === 'shadowMode' || path.startsWith('shadow.');
+    return path.startsWith('shadow.');
 }
 function isSerializedShadowTopologyMetadataPath(path) {
-    return path === 'shadowMode'
-        || path === 'shadow.cast'
+    return path === 'shadow.cast'
         || path === 'shadow.receive'
         || path === 'shadow.mode'
         || path === 'shadow.quality'
@@ -5875,19 +6478,13 @@ function createUiState(state, options) {
     const markerInspectorObject = document && activeId
         ? createMarkerInspectorObjectBase(options, document, activeId, markerGraph, documentHierarchy, markerTypes, state.activeMarkerRelationId, state.markerRelationPick, markerRelationVisibility)
         : null;
-    const serializedObject = document && activeId && selectedIds.length === 1
-        ? markerInspectorObject ? null : options.documentAdapter.getSerializedObject(document, activeId)
-        : null;
-    const serializedMultiObject = document && documentSelectedIds.length > 1 && !largeSelection
-        ? options.documentAdapter.getSerializedMultiObject?.(document, documentSelectedIds, documentActiveId) ?? null
-        : null;
     const inspectorObjectBase = document && activeId && (selectedIds.length === 1 || markerInspectorObject)
         ? markerInspectorObject
             ?? options.documentAdapter.getInspectorObject?.(document, activeId)
-            ?? (serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : null)
+            ?? null
         : null;
     const inspectorMultiObjectBase = document && documentSelectedIds.length > 1
-        ? createInspectorMultiObjectBase(state, options, document, documentSelectedIds, documentActiveId, serializedMultiObject, {
+        ? createInspectorMultiObjectBase(state, options, document, documentSelectedIds, documentActiveId, {
             largeSelection,
         })
         : null;
@@ -5937,8 +6534,6 @@ function createUiState(state, options) {
             count: selectedIds.length,
             activeId,
         },
-        serializedObject,
-        serializedMultiObject,
         inspectorObject: previewInspectorObject,
         inspectorMultiObject: previewInspectorMultiObject,
         renderingPanel: document
@@ -5951,6 +6546,7 @@ function createUiState(state, options) {
         markerPanel: document
             ? createMarkerPanelState(markerGraph, markerTypes, relationTypes, documentHierarchy, activeMarkerId, state.activeMarkerRelationId, state.markerRelationPick, markerRelationVisibility)
             : null,
+        pluginPanel: createLocalEditorPluginPanelState(options.pluginHost, state.lifecycle),
         boxSelection: state.boxSelection,
         coordinateAxes: options.world?.coordinateAxes === false
             ? null
@@ -6183,11 +6779,7 @@ function createUiPreviewState(state, options) {
     const transformSelectionIsLarge = isLargeSelection(selectedIds);
     const shouldPreviewInspector = !!state.activeTransformPreview && document && documentActiveId && documentSelectedIds.length === 1;
     const inspectorObjectBase = shouldPreviewInspector
-        ? options.documentAdapter.getInspectorObject?.(document, documentActiveId)
-            ?? (() => {
-                const serializedObject = options.documentAdapter.getSerializedObject(document, documentActiveId);
-                return serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : null;
-            })()
+        ? options.documentAdapter.getInspectorObject?.(document, documentActiveId) ?? null
         : null;
     const inspectorObject = shouldPreviewInspector && document && inspectorObjectBase
         ? applyActiveTransformPreviewToInspectorObject(state, options, document, withRuntimeInspectorSections(state, options, document, inspectorObjectBase))
@@ -6339,7 +6931,7 @@ function clampNumber(value, min, max) {
 function isLargeSelection(selectedIds) {
     return selectedIds.length > LARGE_SELECTION_THRESHOLD;
 }
-function createInspectorMultiObjectBase(state, options, document, selectedIds, activeId, serializedMultiObject, multiOptions = {}) {
+function createInspectorMultiObjectBase(state, options, document, selectedIds, activeId, multiOptions = {}) {
     const targetIds = [...selectedIds];
     if (targetIds.length <= 1)
         return null;
@@ -6347,11 +6939,7 @@ function createInspectorMultiObjectBase(state, options, document, selectedIds, a
     if (multiOptions.largeSelection) {
         return applyMultiInspectorBatchCapabilityGate(options, document, adapterMultiObject ?? createLargeSelectionInspectorObject(document, targetIds, activeId));
     }
-    const serializedMulti = serializedMultiObject !== undefined
-        ? serializedMultiObject
-        : options.documentAdapter.getSerializedMultiObject?.(document, targetIds, activeId) ?? null;
-    const serializedInspector = serializedMulti ? serializedMultiObjectToInspectorObject(serializedMulti, document) : null;
-    const baseInspector = adapterMultiObject ?? serializedInspector;
+    const baseInspector = adapterMultiObject;
     const aggregatedInspector = createAggregatedInspectorMultiObjectBase(state, options, document, targetIds, activeId);
     let inspectorObject = baseInspector ?? aggregatedInspector;
     if (baseInspector && aggregatedInspector) {
@@ -6436,8 +7024,7 @@ function createSingleInspectorObjectBase(options, document, targetId) {
     const inspectorObject = options.documentAdapter.getInspectorObject?.(document, targetId) ?? null;
     if (inspectorObject)
         return withMarkerGraphRelationInspectorSection(options, document, inspectorObject);
-    const serializedObject = options.documentAdapter.getSerializedObject(document, targetId);
-    return serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : null;
+    return null;
 }
 function withMarkerGraphRelationInspectorSection(options, document, inspectorObject, graph = options.documentAdapter.getMarkerGraph?.(document) ?? null, hierarchy = options.documentAdapter.getHierarchyItems(document), markerTypes = options.documentAdapter.getMarkerTypeCatalog?.(document) ?? [], relationTypes = options.documentAdapter.getRelationTypeCatalog?.(document) ?? [], activeRelationId = null, relationPick = null, relationVisibility = {}) {
     if (inspectorObject.targetIds.length !== 1)