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

package/dist/local-editor-harness.js

@@ -1,6 +1,6 @@
 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 { createLocalEditorBrowserUi, createLocalEditorActiveHierarchyScope, createLocalEditorHierarchyProjection, isLocalEditorHierarchyCommandPreconditionCurrent, resolveLocalEditorStatusDiagnostics, createLocalEditorSceneHierarchyScope, createLocalEditorPrefabStageHierarchyScope, 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';
@@ -27,6 +27,70 @@ const EDITOR_WORLD_DISPOSE_BOUNDARY_DELAY_MS = 500;
 const RENDERING_ACTION_PROGRESS_MIN_VISIBLE_MS = 1000;
 const EMPTY_EDITOR_SELECTION = { selectedIds: [], activeId: null };
 const MARKER_RELATION_HIGHLIGHT_RENDER_REASON = 'marker-relation-highlight';
+export function assertLocalEditorUpdatedAssetSnapshotFreshness(snapshot, input) {
+    if (snapshot?.assetId === input.assetId && snapshot.contentHash === input.expectedContentHash)
+        return;
+    const error = new Error('asset_update_snapshot_stale');
+    Object.assign(error, {
+        code: 'asset_update_snapshot_stale',
+        details: {
+            assetId: input.assetId,
+            expectedContentHash: input.expectedContentHash,
+            actualAssetId: snapshot?.assetId ?? null,
+            actualContentHash: snapshot?.contentHash ?? null,
+        },
+    });
+    throw error;
+}
+export function syncLocalEditorUpdatedAssetProjection(state, documentChanged, rebuild) {
+    if (!documentChanged && !state.pending)
+        return false;
+    state.pending = true;
+    rebuild();
+    state.pending = false;
+    return true;
+}
+export function applyLocalEditorUpdatedAssetRefresh(session, input) {
+    const sessionState = session.getState();
+    const callbackState = session.getState();
+    const persistedDocument = input.hydrateDocumentAssets(callbackState.persistedDocument, input.assets);
+    const workingDocument = input.hydrateDocumentAssets(callbackState.workingDocument, input.assets);
+    const compareDocuments = input.compareDocuments
+        ?? ((left, right) => JSON.stringify(left) === JSON.stringify(right));
+    const projectionChanged = !compareDocuments(sessionState.persistedDocument, persistedDocument)
+        || !compareDocuments(sessionState.workingDocument, workingDocument);
+    // Re-run diagnostics even for a document no-op so retries preserve unresolved
+    // binding warnings. The callback only receives cloned snapshots; its document
+    // output is ignored unless the asset projection itself changed.
+    const reconciliation = input.reconcileUpdatedAsset?.(workingDocument, { assetId: input.assetId }) ?? { document: workingDocument };
+    if (!projectionChanged) {
+        return {
+            changed: false,
+            workingDocument: sessionState.workingDocument,
+            selection: sessionState.selection,
+            reconciledBindingCount: 0,
+            warnings: reconciliation.warnings ?? [],
+        };
+    }
+    // Finish all fallible project-owned calculation before mutating the session.
+    session.rebaseExternalDocuments({ persistedDocument, workingDocument });
+    const result = session.dispatch({
+        type: 'document.replace',
+        label: 'Reconcile updated asset',
+        document: reconciliation.document,
+        projectionImpact: {
+            type: 'rebuild',
+            reason: 'asset-update',
+        },
+    });
+    return {
+        changed: true,
+        workingDocument: result.workingDocument,
+        selection: result.selection,
+        reconciledBindingCount: reconciliation.reconciledBindingCount ?? 0,
+        warnings: reconciliation.warnings ?? [],
+    };
+}
 const PREFAB_STAGE_STUDIO_WORLD_APPEARANCE = {
     sky: {
         preset: 'atmospheric',
@@ -195,12 +259,16 @@ function createLocalEditorHarnessImplementation(options, construction) {
         scopeOperations: null,
         nextPrefabScopeRevision: 0,
         editorStateRevision: 0,
+        hierarchyProjectionRevision: 0,
+        hierarchyCommandDiagnostics: [],
+        hierarchyReconcileDiagnostics: [],
         sceneArtifactRevision: 0,
         busy: false,
         session: null,
         source: null,
         assets: [],
         assetFilter: '',
+        updatedAssetProjection: { pending: false },
         selectedAssetId: null,
         babylon: null,
         engine: null,
@@ -213,6 +281,8 @@ function createLocalEditorHarnessImplementation(options, construction) {
             overrides: {},
             isolatedObjectIds: [],
         },
+        previewVisibilityScopeId: 'scene',
+        previewVisibilityByScope: new Map(),
         markerOverlay: null,
         markerGraphVisibility: createDefaultMarkerGraphVisibilityState(),
         activeMarkerRelationId: null,
@@ -267,7 +337,10 @@ function createLocalEditorHarnessImplementation(options, construction) {
         agentBridgeTransport: null,
         agentBridgeStatus: createDisabledLocalEditorAgentBridgeTransportStatus(),
     };
+    state.previewVisibilityByScope.set(state.previewVisibilityScopeId, state.previewVisibility);
     const handleEditorSessionChange = (change) => {
+        if (change.documentChanged || change.selectionChanged)
+            advanceHierarchyProjectionRevision(state);
         void lifecycleController?.synchronizeDocumentState(change.dirty).catch(error => {
             console.error('[LocalEditorHarness] lifecycle document synchronization failed', error);
         });
@@ -324,6 +397,13 @@ function createLocalEditorHarnessImplementation(options, construction) {
     };
     let harness;
     let agentLifecycleController;
+    const acceptBrowserHierarchyCommandPrecondition = (precondition) => {
+        const hadCommandDiagnostics = state.hierarchyCommandDiagnostics.length > 0;
+        const accepted = acceptHierarchyCommandPrecondition(state, precondition);
+        if (accepted && hadCommandDiagnostics)
+            harness.render();
+        return accepted;
+    };
     const pluginInspector = createLocalEditorHarnessPluginInspectorOptions(options.pluginHost, options.inspector);
     const ui = createLocalEditorBrowserUi({
         root,
@@ -364,6 +444,12 @@ function createLocalEditorHarnessImplementation(options, construction) {
                     harness.render();
             },
             onAssetAction: (input) => {
+                const hierarchyAction = input.actionId.startsWith('prefab.node.')
+                    || input.hierarchyPrecondition !== undefined;
+                if (hierarchyAction && !acceptBrowserHierarchyCommandPrecondition(input.hierarchyPrecondition)) {
+                    harness.render();
+                    return;
+                }
                 void runExclusive(state, harness.render, async () => {
                     if (await handleBrowserAssetAction(state, options, input))
                         harness.render();
@@ -375,14 +461,26 @@ function createLocalEditorHarnessImplementation(options, construction) {
                         harness.render();
                 });
             },
-            onSelectPrefabStageItem: (itemId) => {
+            onSelectPrefabStageItem: (itemId, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (selectPrefabStageItemWithPreviewSync(state, options, itemId))
                     harness.render();
             },
-            onSelectHierarchyItem: (input) => {
+            onSelectHierarchyItem: (input, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 selectItem(state, options, input, harness.render);
             },
-            onHierarchyItemEnabledChange: (input) => {
+            onHierarchyItemEnabledChange: (input, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (patchHierarchyItemEnabled(state, options, input))
                     harness.render();
             },
@@ -394,35 +492,63 @@ function createLocalEditorHarnessImplementation(options, construction) {
                 if (patchMarkerRelation(state, options, input))
                     harness.render();
             },
-            onSelectionCommand: (command) => {
+            onSelectionCommand: (command, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 dispatchSelectionCommand(state, options, command, harness.render);
             },
-            onSceneGraphRename: (intent) => {
+            onSceneGraphRename: (intent, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (renameSceneGraphNode(state, options, intent))
                     harness.render();
             },
-            onSceneGraphCreateGroup: (intent) => {
+            onSceneGraphCreateGroup: (intent, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (createSceneGraphGroup(state, options, intent))
                     harness.render();
             },
             onSceneGraphCreatePrimitive: options.documentAdapter.createSceneGraphCreatePrimitivePatch
-                ? (intent) => {
+                ? (intent, precondition) => {
+                    if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                        harness.render();
+                        return;
+                    }
                     if (createSceneGraphPrimitive(state, options, intent))
                         harness.render();
                 }
                 : undefined,
             onSceneGraphCreateMarker: options.documentAdapter.createMarkerGraphPatch
-                ? (intent) => {
+                ? (intent, precondition) => {
+                    if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                        harness.render();
+                        return;
+                    }
                     if (createSceneGraphMarker(state, options, intent))
                         harness.render();
                 }
                 : undefined,
-            onSceneGraphDelete: (intent) => {
+            onSceneGraphDelete: (intent, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (deleteSceneGraphNodes(state, options, intent))
                     harness.render();
             },
             onSceneGraphDuplicate: options.documentAdapter.createDuplicateSelectionPatch
-                ? (intent) => {
+                ? (intent, precondition) => {
+                    if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                        harness.render();
+                        return;
+                    }
                     if (duplicateSceneGraphNodes(state, options, {
                         targetIds: intent.targetIds,
                         activeId: intent.activeId ?? null,
@@ -430,23 +556,41 @@ function createLocalEditorHarnessImplementation(options, construction) {
                         harness.render();
                 }
                 : undefined,
-            onSceneGraphDrop: (intent) => {
+            onSceneGraphDrop: (intent, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (dropSceneGraphNode(state, options, intent))
                     harness.render();
             },
-            onSceneGraphMove: (intent) => {
+            onSceneGraphMove: (intent, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return { ok: false, reason: 'Hierarchy projection is stale.' };
+                }
                 const result = moveSceneGraphNodes(state, options, intent);
                 if (result)
                     harness.render();
                 return result ?? { ok: false, reason: 'Editor is not ready.' };
             },
-            onSceneGraphGroupSelection: (intent) => {
+            onSceneGraphGroupSelection: (intent, precondition) => {
+                if (!acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (groupSceneGraphSelection(state, options, intent))
                     harness.render();
             },
-            onContextAction: (action) => {
+            onContextAction: (action, precondition) => {
+                if (action.region === 'hierarchy' && !acceptBrowserHierarchyCommandPrecondition(precondition)) {
+                    harness.render();
+                    return;
+                }
                 if (action.region === 'hierarchy' && action.action === 'custom') {
-                    const result = runHierarchyCustomContextAction(state, options, action);
+                    if (!precondition)
+                        return;
+                    const result = runHierarchyCustomContextAction(state, options, action, precondition);
                     if (isLocalEditorPromiseLike(result)) {
                         void result.then(changed => {
                             if (changed)
@@ -691,6 +835,7 @@ function createLocalEditorHarnessImplementation(options, construction) {
             onChange: handleEditorSessionChange,
             onChangeError: handleEditorSessionObserverError,
         });
+        advanceHierarchyProjectionRevision(state);
         try {
             attachLifecycleOwnedSessionAuthority();
         }
@@ -789,6 +934,7 @@ function createLocalEditorHarnessImplementation(options, construction) {
     };
     harness = {
         render() {
+            reconcileHierarchySelectionBeforeRender(state, options);
             syncViewportCameraState(state);
             syncViewportMeasurementState(state);
             syncViewportSpatialOverlay(state, options);
@@ -863,6 +1009,70 @@ function createLocalEditorHarnessImplementation(options, construction) {
                 };
             }
         },
+        async refreshUpdatedAsset(input) {
+            try {
+                if (!state.session)
+                    throw new Error('editor_document_unavailable');
+                if (!options.documentAdapter.hydrateDocumentAssets) {
+                    throw new Error('asset_update_hydration_unavailable');
+                }
+                if (!options.documentAdapter.resolveUpdatedAssetSnapshot) {
+                    throw new Error('asset_update_snapshot_verification_unavailable');
+                }
+                const assets = await options.persistenceAdapter.loadAssets();
+                assertLocalEditorUpdatedAssetSnapshotFreshness(options.documentAdapter.resolveUpdatedAssetSnapshot(assets, { assetId: input.assetId }), input);
+                const result = applyLocalEditorUpdatedAssetRefresh(state.session, {
+                    assetId: input.assetId,
+                    assets,
+                    hydrateDocumentAssets: options.documentAdapter.hydrateDocumentAssets,
+                    ...(options.documentAdapter.reconcileUpdatedAsset
+                        ? { reconcileUpdatedAsset: options.documentAdapter.reconcileUpdatedAsset }
+                        : {}),
+                    ...(options.documentAdapter.compareDocuments
+                        ? { compareDocuments: options.documentAdapter.compareDocuments }
+                        : {}),
+                });
+                state.assets = assets;
+                clearArmedPlacement(state);
+                syncLocalEditorUpdatedAssetProjection(state.updatedAssetProjection, result.changed, () => {
+                    rebuildProjectionFromDocument(state, options, result.workingDocument, result.selection);
+                });
+                state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+                const warnings = result.warnings;
+                const reconciledBindingCount = result.reconciledBindingCount;
+                state.status = warnings.length > 0
+                    ? `Asset updated with ${warnings.length} warning${warnings.length === 1 ? '' : 's'}`
+                    : result.changed ? 'Asset updated' : 'Asset metadata already current';
+                state.statusTone = warnings.length > 0 ? 'warning' : 'success';
+                state.statusToneStatus = state.status;
+                state.statusDetails = warnings.map(warning => warning.code).join(', ');
+                harness.render();
+                return {
+                    ok: true,
+                    assetId: input.assetId,
+                    assetCount: assets.length,
+                    reconciledBindingCount,
+                    warnings,
+                    status: state.status,
+                };
+            }
+            catch (error) {
+                state.status = 'Asset update refresh failed';
+                state.statusTone = 'error';
+                state.statusToneStatus = state.status;
+                state.statusDetails = error instanceof Error ? error.message : String(error);
+                harness.render();
+                return {
+                    ok: false,
+                    assetId: input.assetId,
+                    assetCount: state.assets.length,
+                    reconciledBindingCount: 0,
+                    warnings: [],
+                    status: state.status,
+                    error: state.statusDetails,
+                };
+            }
+        },
         createAssetFromAssetId(assetId, createOptions) {
             const result = addAssetToDocument(state, options, assetId, createOptions);
             harness.render();
@@ -935,6 +1145,7 @@ function createLocalEditorHarnessImplementation(options, construction) {
                         onChange: handleEditorSessionChange,
                         onChangeError: handleEditorSessionObserverError,
                     });
+                    advanceHierarchyProjectionRevision(state);
                     try {
                         attachLifecycleOwnedSessionAuthority();
                     }
@@ -1028,10 +1239,10 @@ function createLocalEditorHarnessImplementation(options, construction) {
         }),
         selectPrefabStageItem: itemId => selectPrefabStageItemWithPreviewSync(state, options, itemId),
         runPrefabStageAssetAction: input => patchBrowserAssetAction(state, options, input),
-        getHierarchy: () => createUiState(state, options).hierarchy,
+        getHierarchyProjection: () => createUiState(state, options).hierarchyProjection ?? null,
+        getStatusDiagnostics: () => createUiState(state, options).statusDiagnostics ?? [],
         dispatchSelectionCommand: (command, shouldRenderUi = false) => dispatchSelectionCommand(state, options, command, shouldRenderUi ? () => harness.render() : undefined),
         focusProjectionNode: objectId => frameViewportProjectionNode(state, objectId),
-        focusSelectedProjection: () => frameSelectedViewportProjection(state, options),
         syncViewportCameraState: () => syncViewportCameraState(state),
         requestSceneFrame: reason => requestEditorSceneFrame(state, reason),
         cloneTransformSnapshot: transform => cloneEditorTransformSnapshot(transform),
@@ -2109,7 +2320,9 @@ function clearPrefabStageForEditorTeardown(state) {
     const stage = state.prefabStage;
     if (!stage)
         return;
+    switchPreviewVisibilityScope(state, 'scene');
     state.prefabStage = null;
+    advanceHierarchyProjectionRevision(state);
     setGridVisibleForEditorContext(state, stage.restoreGridVisible, 'prefab-stage-editor-teardown-grid');
     state.sceneCameraPreviewEnabled = stage.restoreSceneCameraPreviewEnabled;
     if (!stage.restoreSceneCameraPreviewEnabled)
@@ -2404,7 +2617,7 @@ function createBrowserContextForCustomAction(state, options, action) {
         activeId: action.activeId,
     };
 }
-function runHierarchyCustomContextAction(state, options, action) {
+function runHierarchyCustomContextAction(state, options, action, precondition) {
     const browserContext = createBrowserContextForCustomAction(state, options, action);
     const context = browserContext
         ? createHarnessHierarchyContextActionContext(state, options, browserContext, action.payload)
@@ -2415,14 +2628,21 @@ function runHierarchyCustomContextAction(state, options, action) {
         .find(candidate => candidate.id === action.id);
     if (!registration)
         return false;
+    const applyIfCurrent = (value) => {
+        const hadCommandDiagnostics = state.hierarchyCommandDiagnostics.length > 0;
+        if (!acceptHierarchyCommandPrecondition(state, precondition))
+            return true;
+        return applyHierarchyContextActionResult(state, options, value, registration.label)
+            || hadCommandDiagnostics;
+    };
     try {
         const result = registration.run(context);
         if (isLocalEditorPromiseLike(result)) {
             return Promise.resolve(result)
-                .then(value => applyHierarchyContextActionResult(state, options, value, registration.label))
+                .then(applyIfCurrent)
                 .catch(error => reportHierarchyContextActionError(state, registration.label, error));
         }
-        return applyHierarchyContextActionResult(state, options, result, registration.label);
+        return applyIfCurrent(result);
     }
     catch (error) {
         return reportHierarchyContextActionError(state, registration.label, error);
@@ -2584,6 +2804,64 @@ function dispatchSelectionCommand(state, options, command, renderUi) {
     }
     return true;
 }
+function acceptHierarchyCommandPrecondition(state, precondition) {
+    const documentRevision = state.session?.getState({ cloneDocuments: false }).documentRevision ?? 0;
+    const scopeId = state.prefabStage
+        ? `prefab-stage:${state.prefabStage.descriptor.assetId}`
+        : 'scene';
+    const expected = {
+        scopeId,
+        documentRevision,
+        projectionRevision: state.hierarchyProjectionRevision,
+    };
+    if (!precondition) {
+        state.hierarchyCommandDiagnostics = [{
+                code: 'hierarchy-command-precondition-missing',
+                severity: 'error',
+                source: 'hierarchy-command',
+                message: `Hierarchy command rejected because no projection revision was provided (expected ${formatHierarchyRevision(expected)}).`,
+                ...expected,
+                details: {
+                    expectedScopeId: expected.scopeId,
+                    expectedDocumentRevision: expected.documentRevision,
+                    expectedProjectionRevision: expected.projectionRevision,
+                },
+            }];
+        return false;
+    }
+    const accepted = isLocalEditorHierarchyCommandPreconditionCurrent(precondition, expected);
+    if (accepted) {
+        state.hierarchyCommandDiagnostics = [];
+        return true;
+    }
+    const message = `Hierarchy command rejected because its projection is stale (expected ${formatHierarchyRevision(expected)}, received ${formatHierarchyRevision(precondition)}).`;
+    state.hierarchyCommandDiagnostics = [{
+            code: 'hierarchy-command-stale',
+            severity: 'error',
+            source: 'hierarchy-command',
+            message,
+            scopeId,
+            documentRevision,
+            projectionRevision: state.hierarchyProjectionRevision,
+            details: {
+                expectedScopeId: expected.scopeId,
+                expectedDocumentRevision: expected.documentRevision,
+                expectedProjectionRevision: expected.projectionRevision,
+                receivedScopeId: precondition.scopeId,
+                receivedDocumentRevision: precondition.documentRevision,
+                receivedProjectionRevision: precondition.projectionRevision,
+            },
+        }];
+    return false;
+}
+function formatHierarchyRevision(precondition) {
+    return `${precondition.scopeId}@document:${precondition.documentRevision}/projection:${precondition.projectionRevision}`;
+}
+function advanceHierarchyProjectionRevision(state) {
+    state.hierarchyProjectionRevision += 1;
+    state.hierarchyCommandDiagnostics = [];
+    state.hierarchyReconcileDiagnostics = [];
+}
 function consumeMarkerRelationPickSelectionCommand(state, options, command, renderUi) {
     const pick = state.markerRelationPick;
     if (!pick?.active)
@@ -3927,6 +4205,7 @@ async function enterPrefabStage(state, options, input) {
             return true;
         }
     }
+    switchPreviewVisibilityScope(state, `prefab-stage:${descriptor.assetId}`);
     state.prefabStage = {
         descriptor,
         asset,
@@ -3936,6 +4215,7 @@ async function enterPrefabStage(state, options, input) {
         restoreGridVisible: previousPrefabStage?.restoreGridVisible ?? state.gridVisible,
         restoreSceneCameraPreviewEnabled: previousPrefabStage?.restoreSceneCameraPreviewEnabled ?? state.sceneCameraPreviewEnabled,
     };
+    advanceHierarchyProjectionRevision(state);
     setGridVisibleForEditorContext(state, false, 'prefab-stage-enter-grid');
     state.sceneCameraPreviewEnabled = false;
     state.sceneCameraPreview?.setActive(false);
@@ -3958,7 +4238,9 @@ async function exitPrefabStage(state, options) {
     const restoreGridVisible = prefabStage.restoreGridVisible;
     const restoreSceneCameraPreviewEnabled = prefabStage.restoreSceneCameraPreviewEnabled;
     await closePrefabStageLifecycleScopes(state, prefabStage);
+    switchPreviewVisibilityScope(state, 'scene');
     state.prefabStage = null;
+    advanceHierarchyProjectionRevision(state);
     setGridVisibleForEditorContext(state, restoreGridVisible, 'prefab-stage-exit-grid');
     if (sessionState?.workingDocument) {
         rebuildProjectionFromDocument(state, options, sessionState.workingDocument, sessionState.selection);
@@ -3983,6 +4265,7 @@ async function closePrefabStageLifecycleScopes(state, stage) {
 function selectPrefabStageItem(state, itemId) {
     if (!state.prefabStage || state.prefabStage.selectedItemId === itemId)
         return false;
+    advanceHierarchyProjectionRevision(state);
     state.prefabStage = {
         ...state.prefabStage,
         selectedItemId: itemId,
@@ -4048,6 +4331,7 @@ function dispatchPrefabStageProjectionSelectionCommand(state, options, command)
     if (command.type === 'selection.clear') {
         if (state.prefabStage.selectedItemId === null)
             return false;
+        advanceHierarchyProjectionRevision(state);
         state.prefabStage = { ...state.prefabStage, selectedItemId: null };
         state.editorStateRevision += 1;
         syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-clear', state.editorStateRevision);
@@ -4064,6 +4348,7 @@ function dispatchPrefabStageProjectionSelectionCommand(state, options, command)
     const currentlySelected = currentProjectionSelection.selectedIds.includes(candidateId);
     if ((command.type === 'selection.toggle' && currentlySelected)
         || (command.type === 'selection.remove' && currentlySelected)) {
+        advanceHierarchyProjectionRevision(state);
         state.prefabStage = { ...state.prefabStage, selectedItemId: null };
         state.editorStateRevision += 1;
         syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-remove', state.editorStateRevision);
@@ -4074,6 +4359,7 @@ function dispatchPrefabStageProjectionSelectionCommand(state, options, command)
     const nextItemId = target.itemId ?? `prefab-node:${target.targetId}`;
     if (state.prefabStage.selectedItemId === nextItemId)
         return false;
+    advanceHierarchyProjectionRevision(state);
     state.prefabStage = { ...state.prefabStage, selectedItemId: nextItemId };
     state.editorStateRevision += 1;
     syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-command', state.editorStateRevision);
@@ -5721,6 +6007,7 @@ function cancelEditorIntent(state, options) {
     }
     if (state.prefabStage?.selectedItemId) {
         cancelActiveOperation(state);
+        advanceHierarchyProjectionRevision(state);
         state.prefabStage = { ...state.prefabStage, selectedItemId: null };
         state.editorStateRevision += 1;
         syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-cancel', state.editorStateRevision);
@@ -5829,24 +6116,6 @@ function createProjectionBoundsFocusFrame(bounds) {
         radius,
     };
 }
-function frameSelectedViewportProjection(state, options) {
-    if (state.mode !== 'editor')
-        return false;
-    if (state.prefabStage) {
-        const activeId = getCurrentPrefabStageProjectionSelection(state, options).activeId;
-        if (!activeId) {
-            state.status = 'Focus failed: no Prefab Stage selection';
-            return false;
-        }
-        return focusPrefabStageProjectionNode(state, options, activeId, 'prefab-stage-frame-selection');
-    }
-    const activeId = state.session?.getState({ cloneDocuments: false }).selection.activeId ?? null;
-    if (!activeId) {
-        state.status = 'Focus failed: no selection';
-        return false;
-    }
-    return frameViewportProjectionNode(state, activeId);
-}
 function focusPrefabStageProjectionNode(state, options, projectionNodeId, reason) {
     const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
     if (!state.prefabStage || !document)
@@ -6283,6 +6552,18 @@ function applyPreviewVisibilityStateToProjection(state) {
         projection.setPreviewVisibilityOverrides(overrides);
     }
 }
+function switchPreviewVisibilityScope(state, nextScopeId) {
+    if (state.previewVisibilityScopeId === nextScopeId)
+        return;
+    state.previewVisibilityByScope.set(state.previewVisibilityScopeId, state.previewVisibility);
+    const next = state.previewVisibilityByScope.get(nextScopeId) ?? {
+        overrides: {},
+        isolatedObjectIds: [],
+    };
+    state.previewVisibilityByScope.set(nextScopeId, next);
+    state.previewVisibilityScopeId = nextScopeId;
+    state.previewVisibility = next;
+}
 function setSceneCameraPreviewEnabled(state, options, enabled) {
     if (!enabled) {
         state.sceneCameraPreviewEnabled = false;
@@ -6505,6 +6786,7 @@ function createUiState(state, options) {
     const hierarchy = document
         ? createMarkerGraphHierarchyItems(documentHierarchy, markerGraph, createMarkerGraphHierarchyVisibility(state))
         : [];
+    const prefabStage = createBrowserPrefabStageState(state, options, document);
     state.performanceObjectCount = document ? countLocalEditorAuthoredObjects(documentHierarchy) : null;
     state.performanceStats = createLocalEditorPerformanceStats({
         frameStats: state.sceneFrameStats,
@@ -6515,7 +6797,7 @@ function createUiState(state, options) {
         ...state.assets.map(asset => toBrowserAssetItem(options, asset)),
         ...documentAssetItems,
     ]);
-    return {
+    const uiState = {
         mode: state.mode,
         busy: state.busy,
         agentBridge: state.agentBridgeStatus,
@@ -6530,6 +6812,8 @@ function createUiState(state, options) {
         hierarchy,
         selectedIds,
         activeId,
+        documentRevision: sessionState?.documentRevision ?? 0,
+        hierarchyProjectionRevision: state.hierarchyProjectionRevision,
         selectionSummary: {
             count: selectedIds.length,
             activeId,
@@ -6576,7 +6860,7 @@ function createUiState(state, options) {
             enabled: state.sceneCameraPreviewEnabled,
             available: hasSceneCameraPreviewRig(state, options),
         },
-        prefabStage: createBrowserPrefabStageState(state, options, document),
+        prefabStage,
         grid: {
             visible: state.gridVisible,
             available: !!state.grid,
@@ -6591,6 +6875,74 @@ function createUiState(state, options) {
             }
             : null,
     };
+    const hierarchyProjection = createLocalEditorHierarchyProjection(createLocalEditorActiveHierarchyScope(uiState));
+    uiState.hierarchyProjection = hierarchyProjection;
+    uiState.statusDiagnostics = [
+        ...hierarchyProjection.diagnostics,
+        ...state.hierarchyReconcileDiagnostics,
+        ...state.hierarchyCommandDiagnostics,
+    ];
+    uiState.statusDiagnostics = resolveLocalEditorStatusDiagnostics(uiState);
+    if (!state.prefabStage) {
+        uiState.selectedIds = hierarchyProjection.selectedIds;
+        uiState.activeId = hierarchyProjection.activeId;
+        uiState.selectionSummary = {
+            count: hierarchyProjection.selectedIds.length,
+            activeId: hierarchyProjection.activeId,
+        };
+        if (activeId !== hierarchyProjection.activeId) {
+            uiState.inspectorObject = null;
+            uiState.inspectorMultiObject = null;
+        }
+    }
+    return uiState;
+}
+function reconcileHierarchySelectionBeforeRender(state, options) {
+    const sessionState = state.session?.getState({ cloneDocuments: false });
+    const document = sessionState?.workingDocument ?? null;
+    if (!sessionState || !document)
+        return;
+    if (state.prefabStage) {
+        const stage = createBrowserPrefabStageState(state, options, document);
+        if (!stage)
+            return;
+        const projection = createLocalEditorHierarchyProjection(createLocalEditorPrefabStageHierarchyScope(stage, sessionState.documentRevision, state.hierarchyProjectionRevision));
+        if (stage.selectedItemId === projection.activeId)
+            return;
+        const reconcileDiagnostics = projection.diagnostics.filter(diagnostic => diagnostic.code === 'hierarchy-selection-stale');
+        advanceHierarchyProjectionRevision(state);
+        state.hierarchyReconcileDiagnostics = reconcileDiagnostics;
+        state.prefabStage.selectedItemId = projection.activeId;
+        state.editorStateRevision += 1;
+        syncPrefabStageSelectionToProjection(state, options, 'hierarchy-projection-selection-sanitize', state.editorStateRevision);
+        return;
+    }
+    const documentHierarchy = options.documentAdapter.getHierarchyItems(document);
+    const markerGraph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const hierarchy = markerGraph
+        ? createMarkerGraphHierarchyItems(documentHierarchy, markerGraph, createMarkerGraphHierarchyVisibility(state))
+        : documentHierarchy;
+    const projection = createLocalEditorHierarchyProjection(createLocalEditorSceneHierarchyScope({
+        hierarchy,
+        selectedIds: sessionState.selection.selectedIds,
+        activeId: sessionState.selection.activeId,
+        documentRevision: sessionState.documentRevision,
+        hierarchyProjectionRevision: state.hierarchyProjectionRevision,
+    }));
+    if (projection.activeId === sessionState.selection.activeId
+        && projection.selectedIds.length === sessionState.selection.selectedIds.length
+        && projection.selectedIds.every((id, index) => id === sessionState.selection.selectedIds[index]))
+        return;
+    const reconcileDiagnostics = projection.diagnostics.filter(diagnostic => diagnostic.code === 'hierarchy-selection-stale');
+    state.session?.dispatch({
+        type: 'selection.replace',
+        selectedIds: projection.selectedIds,
+        activeId: projection.activeId,
+        label: 'Sanitize Hierarchy Projection Selection',
+    });
+    state.hierarchyReconcileDiagnostics = reconcileDiagnostics;
+    state.editorStateRevision += 1;
+    syncSelectionToProjection(state, options, { selectedIds: projection.selectedIds, activeId: projection.activeId }, 'hierarchy-projection-selection-sanitize', state.editorStateRevision);
 }
 function createBrowserPrefabStageState(state, options, document) {
     const stage = state.prefabStage;