@fps-games/editor 0.1.5-beta.5 → 0.1.7-beta.1

package/dist/local-editor-harness.js

@@ -1,18 +1,65 @@
-import { createEditorSession, 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, 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 {} from '@fps-games/editor-protocol';
 import { createLocalEditorBrowserUi, toTransformOperationPolicyStatusLabel, } from '@fps-games/editor-browser';
 import { createBabylonEnvironmentTextureController, createBabylonDefaultPostProcessPipelineController, } from '@fps-games/babylon-renderer';
-import { createBabylonEditorProjection, createBabylonEditorWorld, createBabylonProjectionSelectionController, createBabylonSceneCameraPreviewController, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonSceneViewMeasurementController, createBabylonSceneViewSpatialOverlayController, createBabylonEditorShadowPreviewController, createBabylonTransformGizmoController, createBabylonEditorPerformanceMonitor, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
+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';
 import { createPlayableBabylonOutlineInspectorSection, createPlayableBabylonOutlineInspectorSeedPatchValue, isPlayableBabylonOutlineInspectorPatchPath, } from './playable-babylon-outline-inspector.js';
 import { createLocalEditorViewportRenderCoordinator, } from './local-editor-viewport-render-coordinator.js';
 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 { createLocalEditorAgentBridgeCapabilitySources, } from './agent-bridge/capability-sources.js';
+import { createDisabledLocalEditorAgentBridgeTransportStatus, createLocalEditorAgentBridgeWebSocketTransportFromQuery, } from './local-editor-agent-bridge-transport.js';
+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;
 const LARGE_SHADOW_MODE_BATCH_THRESHOLD = 200;
 const EDITOR_PROJECTION_IDLE_BEFORE_RUN_GAME_TIMEOUT_MS = 1500;
 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';
+const PREFAB_STAGE_STUDIO_WORLD_APPEARANCE = {
+    sky: {
+        preset: 'atmospheric',
+        topColor: { r: 0.68, g: 0.82, b: 0.9 },
+        horizonColor: { r: 0.98, g: 0.98, b: 0.93 },
+        bottomColor: { r: 0.44, g: 0.54, b: 0.53 },
+        cloudColor: { r: 1, g: 0.97, b: 0.86 },
+        cloudStrength: 0.1,
+        sunColor: { r: 1, g: 0.93, b: 0.72 },
+        sunDirection: { x: -0.24, y: 0.28, z: -0.93 },
+    },
+};
+const PREFAB_STAGE_STUDIO_ENVIRONMENT = {
+    textureUrl: 'https://assets.babylonjs.com/environments/studio.env',
+    intensity: 1,
+    rotationY: 0,
+};
+const PREFAB_STAGE_COMPARISON_PREVIEW_DEFINITIONS = [{
+        id: 'mesh-clone',
+        label: 'Mesh Clone',
+        mode: 'meshClone',
+        nodeIdSuffix: 'compare-clone',
+    }, {
+        id: 'instanced-mesh',
+        label: 'InstanceMesh',
+        mode: 'instancedMesh',
+        nodeIdSuffix: 'compare-instance',
+    }];
+function createDefaultMarkerGraphVisibilityState() {
+    return {
+        rootVisible: true,
+        hiddenMarkerIds: new Set(),
+    };
+}
+function createEmptyMarkerCreateReservations() {
+    return {
+        ids: new Set(),
+        labels: new Set(),
+    };
+}
 export function createLocalEditorHarness(options) {
     const root = options.root ?? document.body;
     const state = {
@@ -31,6 +78,16 @@ export function createLocalEditorHarness(options) {
         grid: null,
         gridVisible: true,
         projection: null,
+        previewVisibility: {
+            overrides: {},
+            isolatedObjectIds: [],
+        },
+        markerOverlay: null,
+        markerGraphVisibility: createDefaultMarkerGraphVisibilityState(),
+        activeMarkerRelationId: null,
+        markerRelationPick: null,
+        markerRelationHighlightContinuous: false,
+        markerCreateReservations: createEmptyMarkerCreateReservations(),
         shadowPreview: null,
         environmentTexture: null,
         postProcess: null,
@@ -45,6 +102,7 @@ export function createLocalEditorHarness(options) {
         sceneViewMeasurement: null,
         sceneViewSpatialOverlay: null,
         selectionController: null,
+        prefabComparisonPreview: null,
         sceneRenderScheduler: null,
         viewportRenderCoordinator: null,
         sceneFrameStats: null,
@@ -62,6 +120,7 @@ export function createLocalEditorHarness(options) {
         viewportTools: cloneEditorViewportToolState(DEFAULT_EDITOR_VIEWPORT_TOOL_STATE),
         viewportMeasurement: createEmptyViewportMeasurement(),
         viewportSpatialOverlay: createEmptyEditorViewportSpatialOverlayState(),
+        prefabStage: null,
         duplicateDrag: null,
         activeTransformPreview: null,
         armedPlacement: null,
@@ -72,6 +131,10 @@ export function createLocalEditorHarness(options) {
         statusDetails: '',
         renderingAction: null,
         summary: '',
+        agentBridge: createEditorAgentBridge(),
+        unregisterAgentBridgeCapabilities: null,
+        agentBridgeTransport: null,
+        agentBridgeStatus: createDisabledLocalEditorAgentBridgeTransportStatus(),
     };
     let harness;
     const ui = createLocalEditorBrowserUi({
@@ -116,6 +179,14 @@ export function createLocalEditorHarness(options) {
                 if (handleBrowserAssetAction(state, options, input))
                     harness.render();
             },
+            onExitPrefabStage: () => {
+                if (exitPrefabStage(state, options))
+                    harness.render();
+            },
+            onSelectPrefabStageItem: (itemId) => {
+                if (selectPrefabStageItemWithPreviewSync(state, options, itemId))
+                    harness.render();
+            },
             onSelectHierarchyItem: (input) => {
                 selectItem(state, options, input, harness.render);
             },
@@ -123,6 +194,14 @@ export function createLocalEditorHarness(options) {
                 if (patchHierarchyItemEnabled(state, options, input))
                     harness.render();
             },
+            onMarkerTypeAction: (input) => {
+                if (patchMarkerTypeCatalog(state, options, input))
+                    harness.render();
+            },
+            onMarkerRelationAction: (input) => {
+                if (patchMarkerRelation(state, options, input))
+                    harness.render();
+            },
             onSelectionCommand: (command) => {
                 dispatchSelectionCommand(state, options, command, harness.render);
             },
@@ -140,6 +219,12 @@ export function createLocalEditorHarness(options) {
                         harness.render();
                 }
                 : undefined,
+            onSceneGraphCreateMarker: options.documentAdapter.createMarkerGraphPatch
+                ? (intent) => {
+                    if (createSceneGraphMarker(state, options, intent))
+                        harness.render();
+                }
+                : undefined,
             onSceneGraphDelete: (intent) => {
                 if (deleteSceneGraphNodes(state, options, intent))
                     harness.render();
@@ -181,6 +266,10 @@ export function createLocalEditorHarness(options) {
                 if (patched || state.status !== previousStatus)
                     harness.render();
             },
+            onInspectorAction: (input) => {
+                if (handleInspectorAction(state, options, input))
+                    harness.render();
+            },
             onRenderingPropertyChange: options.documentAdapter.onRenderingPropertyChange
                 ? (input) => {
                     void applyRenderingPropertyChange(state, options, input)
@@ -201,7 +290,7 @@ export function createLocalEditorHarness(options) {
                 }
                 : undefined,
             onTransformToolChange: (tool) => {
-                commitEditorStateChange(state, harness.render, 'transform-tool-change', () => {
+                commitEditorStateChange(state, options, harness.render, 'transform-tool-change', () => {
                     state.transformTool = tool;
                     state.transformConstraint = normalizeTransformConstraint(tool, state.transformConstraint);
                 }, {
@@ -209,21 +298,21 @@ export function createLocalEditorHarness(options) {
                 });
             },
             onTransformSpaceChange: (space) => {
-                commitEditorStateChange(state, harness.render, 'transform-space-change', () => {
+                commitEditorStateChange(state, options, harness.render, 'transform-space-change', () => {
                     state.transformSpace = space;
                 }, {
                     syncTransformArtifacts: true,
                 });
             },
             onTransformConstraintChange: (constraint) => {
-                commitEditorStateChange(state, harness.render, 'transform-constraint-change', () => {
+                commitEditorStateChange(state, options, harness.render, 'transform-constraint-change', () => {
                     state.transformConstraint = normalizeTransformConstraint(state.transformTool, constraint);
                 }, {
                     syncTransformArtifacts: true,
                 });
             },
             onTransformSnapEnabledChange: (enabled) => {
-                commitEditorStateChange(state, harness.render, 'transform-operation-settings-change', () => {
+                commitEditorStateChange(state, options, harness.render, 'transform-operation-settings-change', () => {
                     state.transformOperationSettings = updateTransformOperationSettings(state.transformOperationSettings, {
                         snap: {
                             ...state.transformOperationSettings.snap,
@@ -239,7 +328,7 @@ export function createLocalEditorHarness(options) {
                 const value = normalizePositiveStep(input.value);
                 if (value == null)
                     return;
-                commitEditorStateChange(state, harness.render, 'transform-operation-settings-change', () => {
+                commitEditorStateChange(state, options, harness.render, 'transform-operation-settings-change', () => {
                     const snap = { ...state.transformOperationSettings.snap };
                     if (input.kind === 'move')
                         snap.moveStep = value;
@@ -254,7 +343,7 @@ export function createLocalEditorHarness(options) {
                 });
             },
             onPlacementModeChange: (mode) => {
-                commitEditorStateChange(state, harness.render, 'placement-mode-change', () => {
+                commitEditorStateChange(state, options, harness.render, 'placement-mode-change', () => {
                     state.transformOperationSettings = updateTransformOperationSettings(state.transformOperationSettings, {
                         placementMode: normalizePlacementMode(mode),
                     });
@@ -270,7 +359,7 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onViewportViewPresetChange: (preset) => {
-                if (setViewportViewPreset(state, preset))
+                if (setViewportViewPreset(state, options, preset))
                     harness.render();
             },
             onViewportProjectionModeChange: (mode) => {
@@ -281,6 +370,10 @@ export function createLocalEditorHarness(options) {
                 if (setViewportOverlaySettings(state, settings))
                     harness.render();
             },
+            onMarkerViewportVisibilityChange: (visible) => {
+                if (setMarkerViewportVisibility(state, options, visible))
+                    harness.render();
+            },
             onViewportUtilityToolChange: (tool) => {
                 if (setViewportUtilityTool(state, tool))
                     harness.render();
@@ -301,8 +394,20 @@ export function createLocalEditorHarness(options) {
                 setLocalEditorPerformanceMonitorOpen(state, open);
                 updateLocalEditorPerformanceStats(state, stats => ui.updatePerformanceStats?.(stats));
             },
+            ...{
+                onPrefabComparisonPreviewLayoutChange: () => {
+                    harness.render();
+                },
+                onPrefabComparisonPreviewInteraction: (input) => {
+                    if (!state.prefabStage)
+                        return;
+                    if (state.prefabComparisonPreview?.adjustView(input)) {
+                        requestEditorSceneFrame(state, 'prefab-comparison-preview-interaction');
+                    }
+                },
+            },
             onFocusSelection: () => {
-                if (focusSelectedProjection(state))
+                if (focusSelectedProjection(state, options))
                     harness.render();
             },
             onCancelEditorIntent: () => {
@@ -333,11 +438,12 @@ export function createLocalEditorHarness(options) {
     };
     harness = {
         render() {
-            syncSceneCameraPreview(state, options);
             syncViewportCameraState(state);
             syncViewportMeasurementState(state);
-            syncViewportSpatialOverlay(state);
+            syncViewportSpatialOverlay(state, options);
             ui.update(createUiState(state, options));
+            syncPrefabComparisonPreviewSurfaces(state, ui);
+            syncSceneCameraPreview(state, options);
         },
         notifyViewportRevealed(reason = 'viewport-revealed') {
             state.viewportRenderCoordinator?.requestRevealFrame(reason);
@@ -351,6 +457,9 @@ export function createLocalEditorHarness(options) {
         getHostServices() {
             return options.hostServices ?? null;
         },
+        getAgentBridge() {
+            return state.agentBridge;
+        },
         getWorkingDocument() {
             return state.session?.getState().workingDocument ?? null;
         },
@@ -412,6 +521,10 @@ export function createLocalEditorHarness(options) {
             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,
@@ -425,7 +538,8 @@ export function createLocalEditorHarness(options) {
                     ui.updatePreview(previewState);
                 else
                     ui.update(createUiState(state, options));
-            }, stats => ui.updateSceneFrameStats?.(stats), stats => ui.updatePerformanceStats?.(stats));
+                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}`;
@@ -499,11 +613,102 @@ 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();
         },
     };
+    const agentBridgeCapabilitySourceOperations = {
+        createAssetFromAssetId: (assetId, createOptions) => harness.createAssetFromAssetId(assetId, createOptions),
+        getPrefabStage: () => summarizeAgentBridgePrefabStage(state, options),
+        getPrefabStageDetails: () => summarizeAgentBridgePrefabStageDetails(state, options),
+        openPrefabStage: (input) => {
+            const previousStage = summarizeAgentBridgePrefabStage(state, options);
+            const opened = enterPrefabStage(state, options, {
+                actionId: 'asset.edit-prefab',
+                assetId: input.assetId,
+                browserAssetId: input.browserAssetId,
+                assetKind: 'prefab',
+            });
+            const stage = summarizeAgentBridgePrefabStage(state, options);
+            if (!opened || !stage)
+                return null;
+            const alreadyOpen = isSameAgentBridgePrefabStage(previousStage, stage);
+            return {
+                opened: !alreadyOpen,
+                alreadyOpen,
+                prefab: createAgentBridgePrefabSummaryFromStage(stage),
+                stage,
+                status: state.status,
+            };
+        },
+        exitPrefabStage: () => {
+            const previousStage = summarizeAgentBridgePrefabStage(state, options);
+            const exited = 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,
+        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),
+        cancelActiveOperation: () => cancelActiveOperation(state),
+        withProjectionImpact,
+        resolveProjectionImpact,
+        createReprojectProjectionImpact,
+        createTransformProjectionImpact,
+        createKnownCreatedReprojectProjectionImpact,
+        createDeletedNodeProjectionImpact,
+        reprojectProjectionForChangedIds: (document, changedIds) => reprojectProjectionForChangedIds(state, options, document, changedIds),
+        syncProjectionForChangedIds: (document, changedIds) => syncProjectionForChangedIds(state, options, document, changedIds),
+        rebuildProjectionFromDocument: (document, selection) => rebuildProjectionFromDocument(state, options, document, selection),
+        sanitizeSelection: (document, selection) => sanitizeSelection(state, options, document, selection),
+        summarizeDocument: (document, source) => summarizeDocument(options, document, source),
+        invalidateStaticShadowArtifact: () => {
+            if (!state.shadowPreview?.invalidateStaticProjectedArtifact)
+                return false;
+            state.shadowPreview.invalidateStaticProjectedArtifact();
+            requestEditorSceneFrame(state, 'agent-shadow-static-invalidate');
+            return true;
+        },
+        getShadowPreviewDebugInfo: () => state.shadowPreview?.getDebugInfo?.() ?? null,
+        setShadowDebugOverlay: (items) => {
+            const overlayIds = state.projection?.setShadowDebugOverlay?.(items) ?? [];
+            requestEditorSceneFrame(state, 'agent-shadow-debug-overlay-set');
+            return overlayIds;
+        },
+        clearShadowDebugOverlay: () => {
+            const cleared = state.projection?.clearShadowDebugOverlay?.() ?? false;
+            if (cleared)
+                requestEditorSceneFrame(state, 'agent-shadow-debug-overlay-clear');
+            return cleared;
+        },
+        resolvePrefabStageProjectionNodeId: (nodeId) => {
+            const document = state.session?.getState({ cloneDocuments: false }).workingDocument;
+            return document ? resolvePrefabStageProjectionNodeIdForNode(state, options, document, nodeId) : null;
+        },
+        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, {
+        onStatusChange: agentBridgeStatus => {
+            state.agentBridgeStatus = agentBridgeStatus;
+            harness.render();
+        },
+    });
     harness.render();
     return harness;
 }
@@ -533,6 +738,13 @@ export function mergeLocalEditorHarnessInspectorComponentSections(input) {
         }),
     };
 }
+function isAgentBridgeObjectSelectable(options, document, objectId, hierarchyItems) {
+    const inHierarchy = hierarchyItems.some(item => item.id === objectId);
+    const hasProjectionNode = !!options.documentAdapter.getProjectionNode(document, objectId);
+    if (!inHierarchy && !hasProjectionNode)
+        return false;
+    return isNodeSelectableInDocument(options, document, objectId);
+}
 function normalizeTransformConstraint(tool, constraint) {
     return normalizeEditorTransformConstraint(tool, constraint) ?? 'axis';
 }
@@ -568,7 +780,16 @@ function normalizePlacementMode(mode) {
     return mode === 'ground' || mode === 'surface' ? mode : 'off';
 }
 function normalizeViewportViewPreset(preset) {
-    return preset === 'top' || preset === 'front' || preset === 'right' ? preset : 'perspective';
+    return preset === 'top'
+        || preset === 'bottom'
+        || preset === 'front'
+        || preset === 'back'
+        || preset === 'left'
+        || preset === 'right'
+        || preset === 'iso'
+        || preset === 'threeQuarterTop'
+        ? preset
+        : 'perspective';
 }
 function normalizeViewportProjectionMode(mode) {
     return mode === 'orthographic' ? 'orthographic' : 'perspective';
@@ -599,7 +820,7 @@ function cloneViewportMeasurement(measurement) {
         label: measurement.label ? { ...measurement.label } : null,
     };
 }
-function setViewportViewPreset(state, preset) {
+function setViewportViewPreset(state, options, preset) {
     if (state.sceneCameraPreviewEnabled) {
         state.status = 'Viewport view unavailable during Scene Camera preview';
         state.statusTone = 'warning';
@@ -608,8 +829,8 @@ function setViewportViewPreset(state, preset) {
         return true;
     }
     const nextPreset = normalizeViewportViewPreset(preset);
-    const target = resolveViewportPresetTarget(state);
-    const radius = resolveViewportPresetRadius(state);
+    const target = resolveViewportPresetTarget(state, options);
+    const radius = resolveViewportPresetRadius(state, options);
     const changed = state.sceneViewCamera?.setViewPreset(nextPreset, { target, radius }) ?? false;
     if (!changed)
         return false;
@@ -667,6 +888,25 @@ function setViewportOverlaySettings(state, settings) {
     state.statusDetails = '';
     return true;
 }
+function setMarkerViewportVisibility(state, options, visible) {
+    const nextVisible = visible !== false;
+    if ((state.viewportTools.markersVisible ?? true) === nextVisible)
+        return false;
+    state.viewportTools = {
+        ...state.viewportTools,
+        markersVisible: nextVisible,
+    };
+    state.status = nextVisible ? 'Marker view shown' : 'Marker view hidden';
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = nextVisible
+        ? 'Marker overlays and relation lines are visible in the editor viewport.'
+        : 'Marker overlays and relation lines are temporarily hidden in the editor viewport.';
+    state.editorStateRevision += 1;
+    syncCurrentSelectionToSceneArtifacts(state, options, 'marker-viewport-visibility', state.editorStateRevision);
+    requestEditorSceneFrame(state, 'marker-viewport-visibility');
+    return true;
+}
 function setViewportUtilityTool(state, tool) {
     const nextTool = tool === 'measure-distance' ? 'measure-distance' : 'none';
     state.viewportTools = {
@@ -769,18 +1009,18 @@ function formatViewportMeasurementDistance(value) {
     const rounded = Math.abs(value) < 0.005 ? 0 : value;
     return rounded.toFixed(2).replace(/\.?0+$/, '');
 }
-function resolveViewportPresetTarget(state) {
-    const selection = state.session?.getState().selection;
-    const activeId = selection?.activeId ?? null;
-    if (!activeId || selection?.selectedIds.length !== 1)
+function resolveViewportPresetTarget(state, options) {
+    const selection = getCurrentPreviewSelection(state, options);
+    const activeId = selection.activeId;
+    if (!activeId || selection.selectedIds.length !== 1)
         return null;
     const bounds = state.projection?.getSelectionBounds([activeId]) ?? null;
     return bounds?.center ?? null;
 }
-function resolveViewportPresetRadius(state) {
-    const selection = state.session?.getState().selection;
-    const activeId = selection?.activeId ?? null;
-    if (!activeId || selection?.selectedIds.length !== 1)
+function resolveViewportPresetRadius(state, options) {
+    const selection = getCurrentPreviewSelection(state, options);
+    const activeId = selection.activeId;
+    if (!activeId || selection.selectedIds.length !== 1)
         return undefined;
     const bounds = state.projection?.getSelectionBounds([activeId]) ?? null;
     if (!bounds)
@@ -801,7 +1041,7 @@ function validateTransformActionSelection(state, action) {
         ? { ok: true }
         : { ok: false, message: 'Distribute needs at least 3 selected objects' };
 }
-async function createEditorWorld(state, options, renderUi, renderPreviewUi, updateSceneFrameStats, updatePerformanceStats) {
+async function createEditorWorld(state, options, renderUi, renderPreviewUi, updateSceneFrameStats, updatePerformanceStats, getPrefabComparisonPreviewSurfaces) {
     disposeEditorWorld(state);
     const render = (reason = 'editor-world-update') => {
         renderUi();
@@ -816,9 +1056,9 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     const babylon = await options.worldAdapter.loadBabylon();
     const engine = options.worldAdapter.createEngine(babylon, canvas);
     const document = state.session?.getState().workingDocument;
-    const initialAppearance = resolveLocalEditorWorldAppearance(options, document);
+    const initialAppearance = resolveEffectiveLocalEditorWorldAppearance(state, options, document);
     const initialAppearanceKey = serializeLocalEditorWorldAppearance(initialAppearance);
-    const initialRendering = resolveLocalEditorWorldRendering(options, document);
+    const initialRendering = resolveEffectiveLocalEditorWorldRendering(state, options, document);
     const initialRenderingKey = serializeLocalEditorWorldRendering(initialRendering);
     const world = createBabylonEditorWorld({
         engine,
@@ -834,6 +1074,8 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     const performanceMonitor = createBabylonEditorPerformanceMonitor(world.scene);
     const sceneRenderScheduler = createLocalEditorSceneRenderScheduler((frame) => {
         state.sceneViewInteraction?.updateFrame(frame);
+        syncPrefabComparisonPreviewSurfaces(state, { getPrefabComparisonPreviewSurfaces });
+        state.prefabComparisonPreview?.prepareFrame();
         world.render();
     }, {
         onStatsChange(stats) {
@@ -867,19 +1109,46 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         selectionEdgesPrewarm: options.world?.selectionEdgesPrewarm,
         logger: console,
         onProjectionReady(event) {
-            syncCurrentSelectionToSceneArtifacts(state, `projection-${event.nodeId}-ready-selection`);
+            if (state.prefabStage) {
+                syncPrefabStageSelectionToProjection(state, options, `prefab-stage-projection-${event.nodeId}-ready-selection`);
+                focusPrefabStagePreviewProjection(state, `prefab-stage-projection-${event.nodeId}-ready-focus`);
+                scheduleProjectionShadowPreviewRebuild(state, `prefab-stage-projection-${event.nodeId}-ready-shadow`);
+                viewportRenderCoordinator.invalidateScene(`prefab-stage-projection-${event.nodeId}-ready`);
+                renderUi();
+                return;
+            }
+            syncCurrentSelectionToSceneArtifacts(state, options, `projection-${event.nodeId}-ready-selection`);
             scheduleProjectionShadowPreviewRebuild(state, `projection-${event.nodeId}-ready-shadow`);
             viewportRenderCoordinator.invalidateScene(`projection-${event.nodeId}-ready`);
         },
         onProjectionBatchSettled(event) {
-            syncCurrentSelectionToSceneArtifacts(state, `projection-batch-${event.batchId}-settled-selection`);
+            if (state.prefabStage) {
+                syncPrefabStageSelectionToProjection(state, options, `prefab-stage-projection-batch-${event.batchId}-settled-selection`);
+                focusPrefabStagePreviewProjection(state, `prefab-stage-projection-batch-${event.batchId}-settled-focus`);
+                scheduleProjectionShadowPreviewRebuild(state, `prefab-stage-projection-batch-${event.batchId}-settled`);
+                renderUi();
+                return;
+            }
+            syncCurrentSelectionToSceneArtifacts(state, options, `projection-batch-${event.batchId}-settled-selection`);
             scheduleProjectionShadowPreviewRebuild(state, `projection-batch-${event.batchId}-settled`);
         },
     });
-    const gizmo = createBabylonTransformGizmoController({
+    const prefabComparisonPreview = createBabylonPrefabComparisonPreviewController({
         babylon,
         scene: world.scene,
+        editorCamera: world.camera,
         projection,
+        getSkyBackdrop: () => world.skyBackdrop,
+    });
+    const markerOverlay = createBabylonEditorMarkerOverlayController({
+        babylon,
+        scene: world.scene,
+    });
+    const markerAwareProjection = createBabylonMarkerOverlayProjectionAdapter(projection, markerOverlay);
+    const gizmo = createBabylonTransformGizmoController({
+        babylon,
+        scene: world.scene,
+        projection: markerAwareProjection,
         initialTool: state.transformTool,
         initialSpace: state.transformSpace,
         documentCapabilities: options.transformDocumentCapabilities,
@@ -897,6 +1166,8 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         },
         onDragUpdate(event) {
             updateActiveTransformPreview(state, event);
+            syncMarkerOverlayToSceneArtifacts(state, options, state.session?.getState().selection ?? { selectedIds: [], activeId: null });
+            state.gizmo?.refreshSelection();
             preview('gizmo-drag-update');
         },
         onDragEnd(event) {
@@ -931,24 +1202,48 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
             renderUi();
         },
         onDuplicateDragStart(input) {
+            if (state.prefabStage) {
+                state.status = 'Duplicate drag is not available in Prefab Stage';
+                state.statusTone = 'warning';
+                state.statusToneStatus = state.status;
+                state.statusDetails = 'Use prefab.node.createFromAsset or prefab.node.createPrimitive to add prefab nodes.';
+                renderUi();
+                return null;
+            }
             return beginDuplicateDrag(state, options, input);
         },
     });
-    gizmo.setOperationSettings(state.transformOperationSettings);
+    gizmo.setOperationSettings(getScopedTransformOperationSettings(state));
     gizmo.setConstraint(state.transformConstraint);
     const selectionController = createBabylonProjectionSelectionController({
         scene: world.scene,
         canvas,
-        projection,
+        projection: markerAwareProjection,
         getTool: () => state.transformTool,
-        getSelection: () => state.session?.getSelection() ?? { selectedIds: [], activeId: null },
-        isSelectable: (nodeId) => isDocumentNodeSelectable(state, options, nodeId),
-        isLocked: (nodeId) => isDocumentNodeLocked(state, options, nodeId),
+        getSelection: () => state.prefabStage
+            ? getCurrentPrefabStageProjectionSelection(state, options)
+            : state.session?.getSelection() ?? EMPTY_EDITOR_SELECTION,
+        isSelectable: (nodeId) => state.prefabStage
+            ? isPrefabStageProjectionSelectable(state, options, nodeId)
+            : isDocumentNodeSelectable(state, options, nodeId),
+        isLocked: (nodeId) => state.prefabStage
+            ? !isPrefabStageProjectionSelectable(state, options, nodeId)
+            : isDocumentNodeLocked(state, options, nodeId),
         isOperationBlocked: () => state.gizmo?.getState().dragPhase === 'dragging',
         onSelectionCommand(command) {
+            if (state.prefabStage) {
+                if (dispatchPrefabStageProjectionSelectionCommand(state, options, command))
+                    render();
+                return;
+            }
             dispatchSelectionCommand(state, options, command, render);
         },
         onFocusIntent(nodeId) {
+            if (state.prefabStage) {
+                if (focusPrefabStageProjectionNode(state, options, nodeId, 'prefab-stage-preview-focus-intent'))
+                    render();
+                return;
+            }
             if (focusProjectionNode(state, nodeId))
                 render();
         },
@@ -967,7 +1262,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         isGizmoDragCandidate: (event) => gizmo.isGizmoDragCandidate(event),
         isBoxSelectCandidate: (event) => selectionController.isBoxSelectionCandidate(event),
         isViewPlaneMoveCandidate: (event) => gizmo.isViewPlaneMoveCandidate(event),
-        isPlacementCandidate: () => isPlacementArmed(state),
+        isPlacementCandidate: () => !state.prefabStage && isPlacementArmed(state),
         isMeasurementCandidate: () => state.viewportTools.activeUtilityTool === 'measure-distance',
         onPointerIntentStart(event) {
             sceneViewInteraction.beginPointerIntent(event.state.intent);
@@ -1100,6 +1395,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         },
     });
     const environmentTexture = createBabylonEnvironmentTextureController(world.scene, initialRendering.environment ?? null);
+    world.refreshSkyBackdrop();
     const postProcess = createBabylonDefaultPostProcessPipelineController(world.scene, [world.camera], initialRendering.postProcess ?? null, { name: 'editorDefaultPostProcessPipeline' });
     const resize = () => {
         engine.resize?.();
@@ -1110,7 +1406,9 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     state.engine = engine;
     state.world = world;
     state.grid = grid;
-    state.projection = projection;
+    state.projection = markerAwareProjection;
+    state.prefabComparisonPreview = prefabComparisonPreview;
+    state.markerOverlay = markerOverlay;
     state.shadowPreview = shadowPreview;
     state.environmentTexture = environmentTexture;
     state.postProcess = postProcess;
@@ -1130,13 +1428,15 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     state.worldRenderingKey = initialRenderingKey;
     state.resizeHandler = resize;
     if (document) {
-        projection.projectNodes(options.documentAdapter.getProjectionNodes(document));
+        projection.projectNodes(resolveCurrentEditorProjectionNodes(state, options, document));
+        applyPreviewVisibilityStateToProjection(state);
         scheduleProjectionShadowPreviewRebuild(state, 'editor-world-initial-projection-shadow');
     }
-    syncCurrentSelectionToSceneArtifacts(state, 'editor-world-initial-selection');
+    syncCurrentSelectionToSceneArtifacts(state, options, 'editor-world-initial-selection');
     viewportRenderCoordinator.requestFrame('editor-world-created');
 }
 function disposeEditorWorld(state) {
+    clearPrefabStageForEditorTeardown(state);
     state.activeTransformPreview = null;
     state.sceneViewInteraction?.dispose();
     state.sceneViewInteraction = null;
@@ -1157,6 +1457,12 @@ function disposeEditorWorld(state) {
     state.sceneViewInput = null;
     state.selectionController?.dispose();
     state.selectionController = null;
+    state.prefabComparisonPreview?.dispose();
+    state.prefabComparisonPreview = null;
+    if (state.markerRelationHighlightContinuous) {
+        state.viewportRenderCoordinator?.endContinuous(MARKER_RELATION_HIGHLIGHT_RENDER_REASON);
+        state.markerRelationHighlightContinuous = false;
+    }
     if (state.performanceMonitorOpen) {
         state.viewportRenderCoordinator?.endContinuous(LOCAL_EDITOR_PERFORMANCE_MONITOR_REASON);
     }
@@ -1179,6 +1485,8 @@ function disposeEditorWorld(state) {
     };
     state.gizmo?.dispose();
     state.gizmo = null;
+    state.markerOverlay?.dispose();
+    state.markerOverlay = null;
     if (state.projectionShadowPreviewRebuildFrame !== null) {
         window.cancelAnimationFrame(state.projectionShadowPreviewRebuildFrame);
         state.projectionShadowPreviewRebuildFrame = null;
@@ -1204,6 +1512,16 @@ function disposeEditorWorld(state) {
     state.world = null;
     state.engine = null;
 }
+function clearPrefabStageForEditorTeardown(state) {
+    const stage = state.prefabStage;
+    if (!stage)
+        return;
+    state.prefabStage = null;
+    setGridVisibleForEditorContext(state, stage.restoreGridVisible, 'prefab-stage-editor-teardown-grid');
+    state.sceneCameraPreviewEnabled = stage.restoreSceneCameraPreviewEnabled;
+    if (!stage.restoreSceneCameraPreviewEnabled)
+        state.sceneCameraPreview?.setActive(false);
+}
 async function waitForEditorProjectionIdleBeforeRunGame(state) {
     const projection = state.projection;
     if (!projection)
@@ -1267,10 +1585,31 @@ function requestEditorSceneFrame(state, reason) {
 function requestEditorPreviewFrame(state, options, renderPreviewUi, reason) {
     syncViewportCameraState(state);
     syncViewportMeasurementState(state);
-    syncViewportSpatialOverlay(state);
+    syncViewportSpatialOverlay(state, options);
     renderPreviewUi(createUiPreviewState(state, options));
     requestEditorSceneFrame(state, reason);
 }
+function syncPrefabComparisonPreviewSurfaces(state, ui) {
+    const controller = state.prefabComparisonPreview;
+    if (!controller)
+        return;
+    if (!state.prefabStage) {
+        if (controller.clear())
+            requestEditorSceneFrame(state, 'prefab-comparison-preview-clear');
+        return;
+    }
+    const surfaces = ui.getPrefabComparisonPreviewSurfaces?.() ?? [];
+    const changed = controller.sync(surfaces.map(toBabylonPrefabComparisonPreviewSurface));
+    if (changed)
+        requestEditorSceneFrame(state, 'prefab-comparison-preview-sync');
+}
+function toBabylonPrefabComparisonPreviewSurface(surface) {
+    return {
+        previewId: surface.previewId,
+        projectionNodeId: surface.projectionNodeId,
+        rect: surface.rect,
+    };
+}
 function updateActiveTransformPreview(state, event) {
     const activeId = event.activeId ?? event.nodeId ?? event.targetIds[0] ?? null;
     if (!activeId) {
@@ -1351,13 +1690,29 @@ function selectItem(state, options, input, renderUi) {
     return dispatchSelectionCommand(state, options, command, renderUi);
 }
 function createBrowserHierarchyContextActions(state, options) {
-    return (options.hierarchy?.contextActions ?? []).map((registration) => ({
+    return createHierarchyContextActionRegistrations(state, options).map((registration) => ({
         id: registration.id,
         label: registration.label,
         shortcut: registration.shortcut,
         danger: registration.danger,
         placement: registration.placement,
         separatorBefore: registration.separatorBefore,
+        children: (browserContext) => {
+            const context = createHarnessHierarchyContextActionContext(state, options, browserContext);
+            if (!context)
+                return [];
+            const children = typeof registration.children === 'function'
+                ? registration.children(context)
+                : registration.children ?? [];
+            return children.map(child => ({
+                id: child.id,
+                label: child.label,
+                shortcut: child.shortcut,
+                danger: child.danger,
+                disabled: () => child.disabled?.(context) ?? false,
+                payload: () => child.payload?.(context),
+            }));
+        },
         visible: (browserContext) => {
             const context = createHarnessHierarchyContextActionContext(state, options, browserContext);
             if (!context)
@@ -1372,6 +1727,40 @@ function createBrowserHierarchyContextActions(state, options) {
         },
     }));
 }
+function createHierarchyContextActionRegistrations(state, options) {
+    return [
+        createPrefabFromGameObjectHierarchyContextAction(state, options),
+        ...(options.hierarchy?.contextActions ?? []),
+    ];
+}
+function createPrefabFromGameObjectHierarchyContextAction(state, options) {
+    return {
+        id: 'asset.create-prefab-from-game-object',
+        label: 'Create Prefab',
+        placement: 'after-create',
+        visible: (context) => (!state.prefabStage
+            && !!options.documentAdapter.createAssetActionPatch
+            && context.targetIds.length === 1
+            && context.activeId === context.targetIds[0]
+            && !!context.projectionNode?.asset),
+        disabled: (context) => {
+            if (context.targetIds.length !== 1 || !context.activeId)
+                return 'Select exactly one model-backed GameObject.';
+            if (!context.projectionNode?.asset)
+                return 'Only model-backed GameObjects can be converted to Prefab assets.';
+            return false;
+        },
+        run: (context) => patchBrowserAssetAction(state, options, {
+            actionId: 'asset.create-prefab-from-game-object',
+            assetId: undefined,
+            browserAssetId: undefined,
+            assetKind: 'prefab',
+        }, {
+            activeId: context.activeId,
+            selectedIds: context.targetIds,
+        }),
+    };
+}
 function createHarnessHierarchyContextActionContext(state, options, browserContext, payload) {
     const document = state.session?.getState().workingDocument ?? null;
     if (!document)
@@ -1409,17 +1798,22 @@ function createBrowserContextForCustomAction(state, options, action) {
     };
 }
 function runHierarchyCustomContextAction(state, options, action) {
-    const registration = options.hierarchy?.contextActions?.find(candidate => candidate.id === action.id);
-    if (!registration)
-        return false;
     const browserContext = createBrowserContextForCustomAction(state, options, action);
     const context = browserContext
         ? createHarnessHierarchyContextActionContext(state, options, browserContext, action.payload)
         : null;
     if (!context)
         return false;
+    const registration = createHierarchyContextActionRegistrations(state, options)
+        .find(candidate => candidate.id === action.id);
+    if (!registration)
+        return false;
     try {
-        return registration.run(context) === true;
+        const result = registration.run(context);
+        if (isLocalEditorHarnessPatchResult(result)) {
+            return applyHierarchyContextActionPatch(state, options, result, registration.label);
+        }
+        return result === true;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -1431,6 +1825,55 @@ function runHierarchyCustomContextAction(state, options, action) {
         return true;
     }
 }
+function isLocalEditorHarnessPatchResult(value) {
+    return !!value
+        && typeof value === 'object'
+        && 'patch' in value;
+}
+function applyHierarchyContextActionPatch(state, options, patch, fallbackLabel) {
+    const document = state.session?.getState().workingDocument;
+    if (state.mode !== 'editor' || !state.session || !document)
+        return false;
+    cancelActiveOperation(state);
+    const label = patch.label ?? fallbackLabel;
+    const projectionImpact = resolveProjectionImpact(patch, patch.createdId
+        ? createKnownCreatedReprojectProjectionImpact({
+            createdNodeIds: [patch.createdId],
+            reprojectIds: patch.reprojectIds,
+        })
+        : patch.reprojectIds?.length
+            ? createReprojectProjectionImpact(patch.reprojectIds)
+            : patch.changedIds?.length
+                ? createReprojectProjectionImpact(patch.changedIds)
+                : patch.changedId
+                    ? createReprojectProjectionImpact([patch.changedId])
+                    : undefined);
+    const result = state.session.dispatch({
+        type: 'document.patch',
+        label,
+        patch: patch.patch,
+        targetId: patch.createdId ?? patch.changedId ?? undefined,
+        ...withProjectionImpact(projectionImpact),
+    });
+    if (!result.documentChanged) {
+        state.status = `${label} unchanged`;
+        return true;
+    }
+    const selectionId = patch.createdId ?? patch.changedId ?? null;
+    let selection = result.selection;
+    if (selectionId && isNodeSelectableInDocument(options, result.workingDocument, selectionId)) {
+        selection = state.session.dispatch({
+            type: 'selection.replace',
+            selectedIds: [selectionId],
+            activeId: selectionId,
+            label: `Select ${selectionId}`,
+        }).selection;
+    }
+    rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
+    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.status = label;
+    return true;
+}
 function handleContextAction(state, options, action) {
     if (action.region !== 'hierarchy')
         return false;
@@ -1446,7 +1889,7 @@ function handleContextAction(state, options, action) {
                 label: 'Select Context Target',
             })
             : false;
-        return focusSelectedProjection(state) || selectionChanged;
+        return focusSelectedProjection(state, options) || selectionChanged;
     }
     if (action.action === 'rename')
         return false;
@@ -1465,6 +1908,14 @@ function handleContextAction(state, options, action) {
             name: action.name,
         });
     }
+    if (action.action === 'create-marker') {
+        return createSceneGraphMarker(state, options, {
+            parentId: action.parentId ?? null,
+            activeId: action.activeId ?? null,
+            markerType: action.markerType,
+            name: action.name,
+        });
+    }
     if (action.action === 'delete') {
         return deleteSceneGraphNodes(state, options, {
             ids: action.targetIds,
@@ -1488,6 +1939,9 @@ function handleContextAction(state, options, action) {
 function dispatchSelectionCommand(state, options, command, renderUi) {
     if (state.mode !== 'editor')
         return false;
+    if (state.markerRelationPick) {
+        return consumeMarkerRelationPickSelectionCommand(state, options, command, renderUi);
+    }
     cancelActiveOperation(state);
     const session = state.session;
     if (!session)
@@ -1499,16 +1953,109 @@ function dispatchSelectionCommand(state, options, command, renderUi) {
     if (!changed)
         return false;
     if (renderUi) {
-        commitEditorStateChange(state, renderUi, 'selection-command', () => { }, {
+        commitEditorStateChange(state, options, renderUi, 'selection-command', () => { }, {
             syncSelectionArtifacts: selection,
         });
     }
     else {
         state.editorStateRevision += 1;
-        syncSelectionToProjection(state, selection, 'selection-command', state.editorStateRevision);
+        syncSelectionToProjection(state, options, selection, 'selection-command', state.editorStateRevision);
+    }
+    return true;
+}
+function consumeMarkerRelationPickSelectionCommand(state, options, command, renderUi) {
+    const pick = state.markerRelationPick;
+    if (!pick?.active)
+        return false;
+    const document = state.session?.getState().workingDocument ?? null;
+    const graph = document ? options.documentAdapter.getMarkerGraph?.(document) ?? null : null;
+    if (!document || !graph) {
+        updateMarkerRelationPickWarning(state, '当前文档没有 marker graph。');
+        if (renderUi)
+            renderUi();
+        return true;
+    }
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const targetId = readMarkerRelationPickTargetId(command);
+    if (!targetId) {
+        updateMarkerRelationPickWarning(state, '没有拾取到有效端点，请点击标记或场景对象。');
+        if (renderUi)
+            renderUi();
+        return true;
+    }
+    const endpoint = resolveMarkerRelationPickEndpoint(graph, hierarchy, targetId);
+    if (!endpoint) {
+        updateMarkerRelationPickWarning(state, `暂不支持的关系端点：${targetId}`);
+        if (renderUi)
+            renderUi();
+        return true;
+    }
+    if (!pick.from) {
+        const status = `关系拾取中：${formatMarkerRelationPickEndpointLabel(endpoint, graph, hierarchy)} 已作为起点，请点击终点。`;
+        state.markerRelationPick = {
+            ...pick,
+            from: endpoint,
+            status,
+            statusTone: 'success',
+        };
+        state.status = status;
+        state.statusTone = 'success';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '关系拾取会消费下一次有效视口点击，不改变当前选择。';
+        if (renderUi)
+            renderUi();
+        return true;
+    }
+    const handled = patchMarkerRelation(state, options, {
+        action: 'create',
+        type: pick.type ?? '',
+        fromKind: pick.from.kind,
+        fromId: pick.from.id,
+        toKind: endpoint.kind,
+        toId: endpoint.id,
+        directed: pick.directed,
+    });
+    if (handled && state.markerRelationPick) {
+        state.markerRelationPick = {
+            ...state.markerRelationPick,
+            status: state.status,
+            statusTone: state.statusTone,
+        };
     }
+    if (renderUi)
+        renderUi();
     return true;
 }
+function readMarkerRelationPickTargetId(command) {
+    if (command.type === 'selection.clear' || command.type === 'selection.remove')
+        return null;
+    return command.activeId?.trim() || command.selectedIds[command.selectedIds.length - 1]?.trim() || null;
+}
+function resolveMarkerRelationPickEndpoint(graph, hierarchy, targetId) {
+    const markerId = readSpatialMarkerIdFromHierarchySelection(graph, targetId, hierarchy);
+    if (markerId && findSpatialMarkerById(graph, markerId)) {
+        return { kind: 'marker', id: markerId };
+    }
+    const hierarchyItem = hierarchy.find(item => item.id === targetId) ?? null;
+    if (!hierarchyItem)
+        return null;
+    if (hierarchyItem.role === 'marker' || hierarchyItem.role === 'group' || hierarchyItem.role === 'root')
+        return null;
+    return { kind: 'scene-object', id: targetId };
+}
+function updateMarkerRelationPickWarning(state, status) {
+    if (state.markerRelationPick) {
+        state.markerRelationPick = {
+            ...state.markerRelationPick,
+            status,
+            statusTone: 'warning',
+        };
+    }
+    state.status = status;
+    state.statusTone = 'warning';
+    state.statusToneStatus = state.status;
+    state.statusDetails = status;
+}
 function renameSceneGraphNode(state, options, intent) {
     const document = state.session?.getState().workingDocument;
     if (state.mode !== 'editor' || !state.session || !document)
@@ -1524,7 +2071,10 @@ function renameSceneGraphNode(state, options, intent) {
         state.status = `Rename rejected: ${intent.id}`;
         return true;
     }
-    const result = state.session.dispatch({
+    const session = state.session;
+    if (!session)
+        return false;
+    const result = session.dispatch({
         type: 'document.patch',
         label: patch.label ?? `Rename ${intent.id}`,
         patch: patch.patch,
@@ -1536,7 +2086,7 @@ function renameSceneGraphNode(state, options, intent) {
         return true;
     }
     rebuildProjectionFromDocument(state, options, result.workingDocument, result.selection);
-    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
     state.status = patch.label ?? `Renamed ${intent.id}`;
     return true;
 }
@@ -1550,7 +2100,10 @@ function createSceneGraphGroup(state, options, intent) {
         state.status = 'Create empty rejected';
         return true;
     }
-    const result = state.session.dispatch({
+    const session = state.session;
+    if (!session)
+        return false;
+    const result = session.dispatch({
         type: 'document.patch',
         label: patch.label ?? 'Create Empty',
         patch: patch.patch,
@@ -1572,7 +2125,7 @@ function createSceneGraphGroup(state, options, intent) {
         }).selection;
     }
     rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
-    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
     state.status = patch.label ?? (createdId ? `Created empty ${createdId}` : 'Created empty');
     return true;
 }
@@ -1615,6 +2168,182 @@ function createSceneGraphPrimitive(state, options, intent) {
     state.status = patch.label ?? (createdId ? `Created ${intent.shape} ${createdId}` : `Created ${intent.shape}`);
     return true;
 }
+function createSceneGraphMarker(state, options, intent) {
+    const document = state.session?.getState().workingDocument;
+    if (state.mode !== 'editor' || !state.session || !document)
+        return false;
+    cancelActiveOperation(state);
+    const markerType = intent.markerType?.trim() ?? '';
+    const markerTypes = options.documentAdapter.getMarkerTypeCatalog?.(document) ?? [];
+    const markerTypeDefinition = markerType
+        ? markerTypes.find(definition => definition.type === markerType) ?? null
+        : null;
+    if (markerType && !markerTypeDefinition) {
+        state.status = `Create marker rejected: unknown marker type ${markerType}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return true;
+    }
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const parentId = resolveCreateMarkerParentId(hierarchy, intent.parentId ?? null);
+    const marker = createSceneGraphMarkerNode(state, options, document, intent, markerTypeDefinition);
+    state.markerCreateReservations.ids.add(marker.id);
+    state.markerCreateReservations.labels.add(marker.label);
+    const patch = options.documentAdapter.createMarkerGraphPatch?.(document, {
+        type: 'marker.create-box',
+        marker,
+        parentId,
+    });
+    if (!patch) {
+        state.markerCreateReservations.ids.delete(marker.id);
+        state.markerCreateReservations.labels.delete(marker.label);
+        state.status = `Create marker rejected: ${marker.label}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return true;
+    }
+    const result = state.session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `Create marker ${marker.label}`,
+        patch: patch.patch,
+        targetId: patch.createdId ?? patch.changedId ?? marker.id,
+        ...withProjectionImpact(resolveProjectionImpact(patch, createKnownCreatedReprojectProjectionImpact({
+            createdNodeIds: [patch.createdId ?? patch.changedId ?? marker.id],
+            reprojectIds: patch.changedIds,
+        }))),
+    });
+    if (!result.documentChanged) {
+        state.markerCreateReservations.ids.delete(marker.id);
+        state.markerCreateReservations.labels.delete(marker.label);
+        state.status = `Create marker unchanged: ${marker.label}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return true;
+    }
+    const createdId = patch.createdId ?? patch.changedId ?? marker.id;
+    releaseReflectedMarkerCreateReservation(state, options, result.workingDocument, marker, createdId);
+    let selection = result.selection;
+    if (createdId && isNodeSelectableInDocument(options, result.workingDocument, createdId)) {
+        selection = state.session.dispatch({
+            type: 'selection.replace',
+            selectedIds: [createdId],
+            activeId: createdId,
+            label: 'Select Created Marker',
+        }).selection;
+    }
+    rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
+    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.status = patch.label ?? `Created marker ${marker.label}`;
+    state.statusTone = 'success';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function releaseReflectedMarkerCreateReservation(state, options, document, marker, createdId) {
+    const reflectedIds = new Set([
+        marker.id,
+        ...(createdId ? [createdId] : []),
+    ]);
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const markerReflected = hierarchy.some(item => reflectedIds.has(item.id))
+        || (graph?.markers ?? []).some(candidate => reflectedIds.has(candidate.id));
+    if (!markerReflected)
+        return;
+    state.markerCreateReservations.ids.delete(marker.id);
+    state.markerCreateReservations.labels.delete(marker.label);
+}
+function createSceneGraphMarkerNode(state, options, document, intent, markerTypeDefinition) {
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const existingIds = new Set([
+        ...hierarchy.map(item => item.id),
+        ...(graph?.markers ?? []).map(marker => marker.id),
+        ...state.markerCreateReservations.ids,
+    ]);
+    const markerType = markerTypeDefinition?.type ?? intent.markerType?.trim() ?? '';
+    const baseLabel = intent.name?.trim() || markerTypeDefinition?.label || 'Marker';
+    const id = createUniqueMarkerId(existingIds, markerType || baseLabel);
+    const label = createUniqueMarkerLabel(new Set([
+        ...hierarchy.map(item => item.label),
+        ...state.markerCreateReservations.labels,
+    ]), baseLabel, id, markerType);
+    const geometry = createInitialMarkerGeometry(state, markerTypeDefinition?.kind);
+    return {
+        id,
+        kind: normalizeMarkerNodeKind(markerTypeDefinition?.kind),
+        markerType,
+        label,
+        geometry,
+        ...(markerTypeDefinition?.defaultTags?.length ? { tags: [...markerTypeDefinition.defaultTags] } : {}),
+    };
+}
+function createInitialMarkerGeometry(state, markerKind) {
+    const defaultScale = createDefaultMarkerScale(markerKind);
+    const selection = state.session?.getState().selection ?? { selectedIds: [], activeId: null };
+    const bounds = selection.selectedIds.length > 0
+        ? state.projection?.getSelectionBounds(selection.selectedIds) ?? null
+        : null;
+    const center = bounds?.center ?? { x: 0, y: defaultScale.y / 2, z: 0 };
+    if (!isRegionMarkerKind(markerKind)) {
+        return {
+            kind: 'point',
+            coordinateSpace: 'world',
+            position: { ...center },
+        };
+    }
+    const size = bounds && isRegionMarkerKind(markerKind)
+        ? normalizeMarkerBoxSize(bounds.size)
+        : defaultScale;
+    return {
+        kind: 'box',
+        coordinateSpace: 'world',
+        center: { ...center },
+        size: { ...size },
+    };
+}
+function createDefaultMarkerScale(markerKind) {
+    return isRegionMarkerKind(markerKind)
+        ? { x: 4, y: 1, z: 4 }
+        : { x: 0.5, y: 0.5, z: 0.5 };
+}
+function normalizeMarkerNodeKind(kind) {
+    return kind?.trim() || 'point';
+}
+function isRegionMarkerKind(kind) {
+    return (kind?.trim() || 'point') === 'region';
+}
+function createUniqueMarkerId(existingIds, markerType) {
+    const base = sanitizeMarkerIdPart(markerType) || 'marker';
+    if (!existingIds.has(base))
+        return base;
+    let index = 2;
+    while (existingIds.has(`${base}-${index}`))
+        index += 1;
+    return `${base}-${index}`;
+}
+function createUniqueMarkerLabel(existingLabels, baseLabel, id, markerType) {
+    const trimmed = baseLabel.trim() || markerType || id;
+    if (!existingLabels.has(trimmed))
+        return trimmed;
+    let index = 2;
+    while (existingLabels.has(`${trimmed} ${index}`))
+        index += 1;
+    return `${trimmed} ${index}`;
+}
+function sanitizeMarkerIdPart(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function resolveCreateMarkerParentId(hierarchy, parentId) {
+    if (!parentId)
+        return null;
+    const parent = hierarchy.find(item => item.id === parentId) ?? null;
+    return parent?.canHaveChildren === true && parent.role !== 'marker' ? parent.id : null;
+}
 function deleteSceneGraphNodes(state, options, intent) {
     const document = state.session?.getState().workingDocument;
     if (state.mode !== 'editor' || !state.session || !document)
@@ -1866,7 +2595,12 @@ function groupSceneGraphSelection(state, options, intent) {
     return true;
 }
 function sanitizeSelection(state, options, document, selection) {
-    const selectedIds = selection.selectedIds.filter(id => isNodeSelectableInDocument(options, document, id));
+    const documentHierarchy = options.documentAdapter.getHierarchyItems(document);
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const hierarchy = graph
+        ? createMarkerGraphHierarchyItems(documentHierarchy, graph, createMarkerGraphHierarchyVisibility(state))
+        : documentHierarchy;
+    const selectedIds = selection.selectedIds.filter(id => isAgentBridgeObjectSelectable(options, document, id, hierarchy));
     const activeId = selection.activeId && selectedIds.includes(selection.activeId)
         ? selection.activeId
         : selectedIds[selectedIds.length - 1] ?? null;
@@ -1880,7 +2614,7 @@ function sanitizeSelection(state, options, document, selection) {
     });
     return result?.selection ?? { selectedIds, activeId };
 }
-function commitEditorStateChange(state, renderUi, reason, mutate, options = {}) {
+function commitEditorStateChange(state, harnessOptions, renderUi, reason, mutate, options = {}) {
     const beforeRevision = state.editorStateRevision;
     mutate();
     const revision = beforeRevision + 1;
@@ -1890,7 +2624,7 @@ function commitEditorStateChange(state, renderUi, reason, mutate, options = {})
         const selection = typeof options.syncSelectionArtifacts === 'boolean'
             ? state.session?.getState({ cloneDocuments: false }).selection ?? { selectedIds: [], activeId: null }
             : options.syncSelectionArtifacts;
-        syncSelectionToProjection(state, selection, reason, revision);
+        syncSelectionToProjection(state, harnessOptions, selection, reason, revision);
     }
     else if (options.syncTransformOperationArtifacts) {
         syncTransformOperationSettingsToSceneArtifacts(state, reason, revision);
@@ -1900,15 +2634,288 @@ function commitEditorStateChange(state, renderUi, reason, mutate, options = {})
     }
     return revision;
 }
-function syncSelectionToProjection(state, selection, reason = 'projection-selection', revision = state.editorStateRevision) {
+function syncSelectionToProjection(state, options, selection, reason = 'projection-selection', revision = state.editorStateRevision) {
     if (!beginSceneArtifactSync(state, reason, revision))
         return;
-    state.projection?.syncSelection(selection);
-    state.gizmo?.setSelection(selection);
+    const projectedSelection = state.prefabStage ? EMPTY_EDITOR_SELECTION : selection;
+    state.projection?.syncSelection(projectedSelection);
+    syncMarkerOverlayToSceneArtifacts(state, options, projectedSelection);
+    state.gizmo?.setSelection(projectedSelection);
     syncTransformGizmoToSceneArtifacts(state, reason, revision, false);
 }
-function syncCurrentSelectionToSceneArtifacts(state, reason = 'projection-selection-current', revision = state.editorStateRevision) {
-    syncSelectionToProjection(state, state.session?.getState({ cloneDocuments: false }).selection ?? { selectedIds: [], activeId: null }, reason, revision);
+function syncCurrentSelectionToSceneArtifacts(state, options, reason = 'projection-selection-current', revision = state.editorStateRevision) {
+    syncSelectionToProjection(state, options, state.session?.getState({ cloneDocuments: false }).selection ?? { selectedIds: [], activeId: null }, reason, revision);
+}
+function syncMarkerOverlayToSceneArtifacts(state, options, selection) {
+    const overlay = state.markerOverlay;
+    if (!overlay)
+        return;
+    const document = state.session?.getState().workingDocument ?? null;
+    const input = document
+        ? createMarkerOverlayInput(state, options, document, selection, createMarkerGraphHierarchyVisibility(state))
+        : { markers: [] };
+    const changed = overlay.sync(input);
+    syncMarkerRelationHighlightRenderLoop(state, input);
+    if (changed)
+        requestEditorSceneFrame(state, 'marker-overlay-sync');
+}
+function syncMarkerRelationHighlightRenderLoop(state, input) {
+    const shouldRun = (input.relations ?? []).some(relation => relation.active === true);
+    if (shouldRun === state.markerRelationHighlightContinuous)
+        return;
+    state.markerRelationHighlightContinuous = shouldRun;
+    if (shouldRun) {
+        if (canUseContinuousViewportRenderLoop()) {
+            state.viewportRenderCoordinator?.beginContinuous(MARKER_RELATION_HIGHLIGHT_RENDER_REASON);
+        }
+        else {
+            state.viewportRenderCoordinator?.requestFrame(MARKER_RELATION_HIGHLIGHT_RENDER_REASON);
+        }
+    }
+    else {
+        state.viewportRenderCoordinator?.endContinuous(MARKER_RELATION_HIGHLIGHT_RENDER_REASON);
+    }
+}
+function canUseContinuousViewportRenderLoop() {
+    if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function')
+        return true;
+    if (typeof window.cancelAnimationFrame !== 'function')
+        return true;
+    let completedSynchronously = false;
+    const frameId = window.requestAnimationFrame(() => {
+        completedSynchronously = true;
+    });
+    window.cancelAnimationFrame(frameId);
+    return !completedSynchronously;
+}
+function createMarkerOverlayInput(state, options, document, selection, visibility) {
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    if (!graph)
+        return { markers: [] };
+    if (state.viewportTools.markersVisible === false)
+        return { markers: [], relations: [] };
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const fullHierarchy = createMarkerGraphHierarchyItems(hierarchy, graph, visibility);
+    const selectedIds = new Set(selection.selectedIds);
+    const markerTypeLabels = new Map((options.documentAdapter.getMarkerTypeCatalog?.(document) ?? []).map(definition => [definition.type, definition.label]));
+    const activeMarkerId = selection.activeId
+        ? readSpatialMarkerIdFromHierarchySelection(graph, selection.activeId, hierarchy)
+        : null;
+    return {
+        activeMarkerRowId: selection.activeId,
+        selectedMarkerRowIds: selection.selectedIds,
+        markers: fullHierarchy
+            .filter(item => item.role === 'marker')
+            .map((item) => {
+            const markerId = readSpatialMarkerIdFromHierarchySelection(graph, item.id, hierarchy);
+            const marker = markerId ? findSpatialMarkerById(graph, markerId) : null;
+            if (!marker || !isMarkerOverlayRowVisible(graph, item, marker.id, hierarchy, visibility))
+                return null;
+            const overlayMarker = resolveMarkerForOverlay(state, applyMarkerOverlayTransformPreview(state, item.id, marker));
+            return {
+                markerRowId: item.id,
+                marker: overlayMarker,
+                markerTypeLabel: markerTypeLabels.get(marker.markerType),
+                selected: selectedIds.has(item.id),
+                active: selection.activeId === item.id,
+            };
+        })
+            .filter((entry) => !!entry),
+        relations: createSelectedMarkerRelationOverlayEntries(state, resolveMarkerGraphForOverlay(state, graph), activeMarkerId, hierarchy, visibility),
+    };
+}
+function resolveMarkerGraphForOverlay(state, graph) {
+    return {
+        ...graph,
+        markers: graph.markers.map(marker => resolveMarkerForOverlay(state, marker)),
+    };
+}
+function resolveMarkerForOverlay(state, marker) {
+    if (!isObjectBoundMarkerForOverlay(marker))
+        return marker;
+    const target = readSceneObjectMarkerTargetForOverlay(marker);
+    if (!target)
+        return marker;
+    const bounds = state.projection?.getSelectionBounds([target.id]) ?? null;
+    if (!bounds)
+        return marker;
+    return {
+        ...marker,
+        spatial: {
+            status: 'resolved',
+            coordinateSpace: 'world',
+            origin: { ...bounds.center },
+            bounds: {
+                min: { ...bounds.min },
+                max: { ...bounds.max },
+                center: { ...bounds.center },
+                size: { ...bounds.size },
+            },
+            dimensions: { ...bounds.size },
+            localFrame: {
+                origin: { ...bounds.center },
+                forward: marker.semanticFrame?.forward ? { ...marker.semanticFrame.forward } : { x: 0, y: 0, z: 1 },
+                right: marker.semanticFrame?.right ? { ...marker.semanticFrame.right } : { x: 1, y: 0, z: 0 },
+                up: marker.semanticFrame?.up ? { ...marker.semanticFrame.up } : { x: 0, y: 1, z: 0 },
+            },
+            target,
+        },
+    };
+}
+function isObjectBoundMarkerForOverlay(marker) {
+    const markerKind = marker.kind?.trim().toLowerCase();
+    return markerKind === 'object'
+        || markerKind === 'object-bound'
+        || markerKind === 'object-bounds'
+        || marker.geometry.kind === 'object-bounds';
+}
+function readSceneObjectMarkerTargetForOverlay(marker) {
+    if (marker.target?.kind === 'scene-object')
+        return marker.target;
+    if (marker.geometry.kind === 'object-bounds' && marker.geometry.target.kind === 'scene-object') {
+        return marker.geometry.target;
+    }
+    if (marker.geometry.kind === 'point' && marker.geometry.target?.kind === 'scene-object') {
+        return marker.geometry.target;
+    }
+    return null;
+}
+function createSelectedMarkerRelationOverlayEntries(state, graph, activeMarkerId, hierarchy, visibility) {
+    if (!activeMarkerId)
+        return [];
+    if (!findSpatialMarkerById(graph, activeMarkerId))
+        return [];
+    const entries = [];
+    for (const relation of getSpatialMarkerDirectRelations(graph, activeMarkerId)) {
+        const from = resolveRelationOverlayEndpoint(state, graph, activeMarkerId, relation.from, hierarchy, visibility);
+        const to = resolveRelationOverlayEndpoint(state, graph, activeMarkerId, relation.to, hierarchy, visibility);
+        if (!from || !to)
+            continue;
+        entries.push({
+            id: relation.id,
+            type: relation.type,
+            ...(relation.label ? { label: relation.label } : {}),
+            from,
+            to,
+            directed: relation.directed ?? true,
+            active: state.activeMarkerRelationId === relation.id,
+        });
+    }
+    return entries;
+}
+function applyMarkerOverlayTransformPreview(state, markerRowId, marker) {
+    const transform = readActiveTransformPreviewTransform(state, markerRowId)
+        ?? (markerRowId === marker.id ? null : readActiveTransformPreviewTransform(state, marker.id));
+    if (!transform)
+        return marker;
+    const semanticFrame = createMarkerSemanticFrameFromTransform(marker, transform);
+    if (marker.geometry.kind === 'point') {
+        return {
+            ...marker,
+            geometry: {
+                ...marker.geometry,
+                coordinateSpace: 'world',
+                position: { ...transform.position },
+            },
+            semanticFrame,
+        };
+    }
+    if (marker.geometry.kind !== 'box') {
+        return {
+            ...marker,
+            semanticFrame,
+        };
+    }
+    return {
+        ...marker,
+        semanticFrame,
+        geometry: {
+            ...marker.geometry,
+            center: { ...transform.position },
+            rotation: { ...transform.rotation },
+            size: { ...transform.scale },
+        },
+    };
+}
+function resolveRelationOverlayEndpoint(state, graph, activeMarkerId, endpoint, hierarchy, visibility) {
+    if (endpoint.kind === 'marker') {
+        if (!isMarkerVisibleForOverlayRelation(graph, endpoint.id, hierarchy, visibility))
+            return null;
+        const preview = endpoint.id === activeMarkerId ? readActiveTransformPreviewPosition(state) : null;
+        if (preview)
+            return preview;
+        const marker = findSpatialMarkerById(graph, endpoint.id);
+        return marker ? resolveMarkerOverlayEndpoint(marker) : null;
+    }
+    if (endpoint.kind === 'scene-object') {
+        const preview = endpoint.id === state.activeTransformPreview?.activeId ? readActiveTransformPreviewPosition(state) : null;
+        if (preview)
+            return preview;
+        const bounds = state.projection?.getSelectionBounds([endpoint.id]) ?? null;
+        return bounds ? { ...bounds.center } : null;
+    }
+    return null;
+}
+function isMarkerVisibleForOverlayRelation(graph, markerId, hierarchy, visibility) {
+    if (isSpatialMarkerBackedByHierarchyRow(graph, markerId, hierarchy)) {
+        const markerRow = hierarchy.find(item => item.id === markerId);
+        return markerRow?.enabled !== false && !isMarkerHiddenInHierarchyVisibility(markerId, visibility);
+    }
+    const markerRow = hierarchy.find(item => readMarkerGraphHierarchyMarkerIdForGraph(graph, item.id, hierarchy) === markerId);
+    if (markerRow?.enabled === false)
+        return false;
+    return isSpatialMarkerHierarchyVisible(markerId, visibility);
+}
+function isMarkerHiddenInHierarchyVisibility(markerId, visibility) {
+    const hiddenMarkerIds = visibility.hiddenMarkerIds;
+    if (!hiddenMarkerIds)
+        return false;
+    return Array.isArray(hiddenMarkerIds)
+        ? hiddenMarkerIds.includes(markerId)
+        : hiddenMarkerIds.has(markerId);
+}
+function readActiveTransformPreviewPosition(state) {
+    const transform = readActiveTransformPreviewTransform(state);
+    return transform ? { ...transform.position } : null;
+}
+function readActiveTransformPreviewTransform(state, targetId) {
+    const preview = state.activeTransformPreview;
+    const activeId = targetId ?? preview?.activeId ?? null;
+    if (!preview || !activeId)
+        return null;
+    const transform = preview.transforms[activeId] ?? null;
+    return transform && isEditorTransformTrsSnapshot(transform) ? transform : null;
+}
+function resolveMarkerOverlayEndpoint(marker) {
+    if (isObjectBoundMarkerForOverlay(marker) && marker.spatial?.bounds?.center) {
+        return { ...marker.spatial.bounds.center };
+    }
+    if (marker.geometry.kind === 'box')
+        return { ...marker.geometry.center };
+    if (marker.geometry.kind === 'point')
+        return { ...marker.geometry.position };
+    return null;
+}
+function isMarkerOverlayRowVisible(graph, item, markerId, hierarchy, visibility) {
+    if (item.enabled === false)
+        return false;
+    if (readMarkerGraphHierarchyMarkerIdForGraph(graph, item.id, hierarchy)) {
+        return isSpatialMarkerHierarchyVisible(markerId, visibility);
+    }
+    return true;
+}
+function createMarkerGraphHierarchyVisibility(state) {
+    return {
+        rootVisible: state.markerGraphVisibility.rootVisible,
+        hiddenMarkerIds: state.markerGraphVisibility.hiddenMarkerIds,
+    };
+}
+function createMarkerRelationVisibilityOptions(state) {
+    return {
+        markersVisible: state.viewportTools.markersVisible !== false,
+        rootVisible: state.markerGraphVisibility.rootVisible,
+        hiddenMarkerIds: state.markerGraphVisibility.hiddenMarkerIds,
+    };
 }
 function syncTransformGizmoToSceneArtifacts(state, reason, revision = state.editorStateRevision, beginSync = true) {
     if (beginSync && !beginSceneArtifactSync(state, reason, revision))
@@ -1925,9 +2932,20 @@ function syncTransformGizmoToSceneArtifacts(state, reason, revision = state.edit
 function syncTransformOperationSettingsToSceneArtifacts(state, reason, revision = state.editorStateRevision) {
     if (!beginSceneArtifactSync(state, reason, revision))
         return;
-    state.gizmo?.setOperationSettings(state.transformOperationSettings);
+    state.gizmo?.setOperationSettings(getScopedTransformOperationSettings(state));
     requestEditorSceneFrame(state, reason);
 }
+function getScopedTransformOperationSettings(state) {
+    if (!state.prefabStage)
+        return state.transformOperationSettings;
+    return updateTransformOperationSettings(state.transformOperationSettings, {
+        snap: {
+            ...state.transformOperationSettings.snap,
+            enabled: false,
+        },
+        placementMode: 'off',
+    });
+}
 function beginSceneArtifactSync(state, reason, revision) {
     if (revision < state.sceneArtifactRevision) {
         return false;
@@ -1949,7 +2967,7 @@ function requestEditorArtifactRevealFrame(state, reason) {
     coordinator.requestRevealFrame(`${reason}-artifact-reveal`);
 }
 function syncEditorWorldAppearanceFromDocument(state, options, document, reason) {
-    const appearance = resolveLocalEditorWorldAppearance(options, document);
+    const appearance = resolveEffectiveLocalEditorWorldAppearance(state, options, document);
     const key = serializeLocalEditorWorldAppearance(appearance);
     if (key === state.worldAppearanceKey)
         return;
@@ -1962,16 +2980,18 @@ function syncEditorWorldAppearanceFromDocument(state, options, document, reason)
     requestEditorSceneFrame(state, reason);
 }
 function syncEditorWorldRenderingFromDocument(state, options, document, reason, refreshProjection = false) {
-    const rendering = resolveLocalEditorWorldRendering(options, document);
+    const rendering = resolveEffectiveLocalEditorWorldRendering(state, options, document);
     const key = serializeLocalEditorWorldRendering(rendering);
     if (key === state.worldRenderingKey) {
         if (refreshProjection)
             state.shadowPreview?.refresh();
+        state.world?.refreshSkyBackdrop();
         return;
     }
     state.worldRenderingKey = key;
     state.shadowPreview?.setOptions(rendering.shadowPreview);
     state.environmentTexture?.setProfile(rendering.environment);
+    state.world?.refreshSkyBackdrop();
     state.postProcess?.setProfile(rendering.postProcess);
     requestEditorSceneFrame(state, reason);
 }
@@ -1985,6 +3005,14 @@ function resolveLocalEditorWorldAppearance(options, document) {
         grid: documentAppearance?.grid ?? options.world?.grid,
     };
 }
+function resolveEffectiveLocalEditorWorldAppearance(state, options, document) {
+    if (!state.prefabStage)
+        return resolveLocalEditorWorldAppearance(options, document);
+    return {
+        ...resolveLocalEditorWorldAppearance(options, document),
+        ...PREFAB_STAGE_STUDIO_WORLD_APPEARANCE,
+    };
+}
 function resolveLocalEditorWorldRendering(options, document) {
     const documentRendering = document
         ? options.documentAdapter.getWorldRendering?.(document) ?? null
@@ -1995,6 +3023,15 @@ function resolveLocalEditorWorldRendering(options, document) {
         postProcess: documentRendering?.postProcess ?? null,
     };
 }
+function resolveEffectiveLocalEditorWorldRendering(state, options, document) {
+    const rendering = resolveLocalEditorWorldRendering(options, document);
+    if (!state.prefabStage)
+        return rendering;
+    return {
+        ...rendering,
+        environment: PREFAB_STAGE_STUDIO_ENVIRONMENT,
+    };
+}
 function hasEditorWorldAppearanceSky(appearance) {
     return !!appearance && Object.prototype.hasOwnProperty.call(appearance, 'sky');
 }
@@ -2119,6 +3156,9 @@ function selectBrowserAsset(state, assetId) {
 function handleBrowserAssetAction(state, options, input) {
     if (input.browserAssetId)
         state.selectedAssetId = input.browserAssetId;
+    if (input.actionId === 'asset.edit-prefab') {
+        return enterPrefabStage(state, options, input);
+    }
     if (input.actionId === 'asset.add-to-scene') {
         return input.assetId ? addAssetToDocument(state, options, input.assetId).ok : false;
     }
@@ -2141,18 +3181,355 @@ function handleBrowserAssetAction(state, options, input) {
     state.statusToneStatus = state.status;
     return true;
 }
-function patchBrowserAssetAction(state, options, input) {
+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] : []);
+        return patchBrowserAssetAction(state, options, {
+            actionId: input.actionId,
+            fieldPath: input.path,
+            value: input.params,
+        }, { activeId, selectedIds });
+    }
+    const assetId = readInspectorActionParamString(input, 'assetId');
+    const browserAssetId = readInspectorActionParamString(input, 'browserAssetId')
+        ?? (assetId ? resolveBrowserAssetItemId(state, options, assetId) : null)
+        ?? undefined;
+    if (input.actionId === 'prefab.edit-definition') {
+        if (!assetId) {
+            state.status = 'Prefab action unavailable: missing prefab asset id';
+            state.statusTone = 'warning';
+            state.statusToneStatus = state.status;
+            return true;
+        }
+        return enterPrefabStage(state, options, {
+            actionId: 'asset.edit-prefab',
+            assetId,
+            browserAssetId,
+            assetKind: 'prefab',
+        });
+    }
+    if (input.actionId === 'prefab.select-definition' || input.actionId === 'prefab.ping-source') {
+        if (!assetId) {
+            state.status = `Prefab action unavailable: ${input.actionId}`;
+            state.statusTone = 'warning';
+            state.statusToneStatus = state.status;
+            return true;
+        }
+        const selected = browserAssetId ? selectBrowserAsset(state, browserAssetId) : false;
+        if (!selected && browserAssetId) {
+            state.status = `Selected asset ${browserAssetId}`;
+            state.statusTone = 'success';
+            state.statusToneStatus = state.status;
+            return true;
+        }
+        if (!browserAssetId) {
+            state.status = `Asset not visible in browser: ${assetId}`;
+            state.statusTone = 'warning';
+            state.statusToneStatus = state.status;
+            return true;
+        }
+        return selected;
+    }
+    state.status = `Prefab inspector action unavailable: ${input.actionId}`;
+    state.statusTone = 'warning';
+    state.statusToneStatus = state.status;
+    return true;
+}
+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) {
+    if (state.mode !== 'editor')
+        return false;
+    const sessionState = state.session?.getState({ cloneDocuments: false });
+    const document = sessionState?.workingDocument ?? null;
+    const assetId = input.assetId?.trim();
+    if (!document || !assetId)
+        return false;
+    cancelActiveOperation(state);
+    const previousPrefabStage = state.prefabStage;
+    const asset = findAssetByResolvedId(state, options, assetId);
+    const browserItem = findBrowserAssetItemByResolvedId(state, options, document, input.browserAssetId ?? assetId)
+        ?? (input.browserAssetId ? findBrowserAssetItemByResolvedId(state, options, document, assetId) : null);
+    const descriptor = options.documentAdapter.getPrefabStageDescriptor?.(document, {
+        assetId,
+        browserAssetId: input.browserAssetId,
+        asset,
+    }) ?? createFallbackPrefabStageDescriptor(assetId, input.browserAssetId, browserItem);
+    if (!descriptor) {
+        state.status = `Prefab stage unavailable: ${assetId}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return true;
+    }
+    if (previousPrefabStage)
+        state.prefabComparisonPreview?.clear();
+    state.prefabStage = {
+        descriptor,
+        asset,
+        selectedItemId: 'prefab-root',
+        restoreGridVisible: previousPrefabStage?.restoreGridVisible ?? state.gridVisible,
+        restoreSceneCameraPreviewEnabled: previousPrefabStage?.restoreSceneCameraPreviewEnabled ?? state.sceneCameraPreviewEnabled,
+    };
+    setGridVisibleForEditorContext(state, false, 'prefab-stage-enter-grid');
+    state.sceneCameraPreviewEnabled = false;
+    state.sceneCameraPreview?.setActive(false);
+    state.status = `Editing Prefab ${descriptor.label}`;
+    state.statusTone = 'success';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    rebuildProjectionFromDocument(state, options, document, EMPTY_EDITOR_SELECTION);
+    syncTransformOperationSettingsToSceneArtifacts(state, 'prefab-stage-enter-operation-settings');
+    return true;
+}
+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;
+    state.prefabStage = null;
+    setGridVisibleForEditorContext(state, restoreGridVisible, 'prefab-stage-exit-grid');
+    if (sessionState?.workingDocument) {
+        rebuildProjectionFromDocument(state, options, sessionState.workingDocument, sessionState.selection);
+    }
+    syncTransformOperationSettingsToSceneArtifacts(state, 'prefab-stage-exit-operation-settings');
+    state.sceneCameraPreviewEnabled = restoreSceneCameraPreviewEnabled;
+    if (restoreSceneCameraPreviewEnabled)
+        syncSceneCameraPreview(state, options);
+    else
+        state.sceneCameraPreview?.setActive(false);
+    state.status = `Exited Prefab ${label}`;
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function selectPrefabStageItem(state, itemId) {
+    if (!state.prefabStage || state.prefabStage.selectedItemId === itemId)
+        return false;
+    state.prefabStage = {
+        ...state.prefabStage,
+        selectedItemId: itemId,
+    };
+    return true;
+}
+function selectPrefabStageItemWithPreviewSync(state, options, itemId) {
+    const changed = selectPrefabStageItem(state, itemId);
+    if (changed)
+        syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection');
+    return changed;
+}
+function getCurrentPrefabStageProjectionSelection(state, options) {
+    const stage = state.prefabStage;
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    if (!stage || !document || !stage.selectedItemId)
+        return EMPTY_EDITOR_SELECTION;
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document) ?? stage.descriptor;
+    const context = createPrefabStageContext(state, descriptor);
+    const item = findPrefabStageStructureItemById(options.documentAdapter.getPrefabStageStructure?.(document, descriptor, context) ?? createFallbackPrefabStageStructure(descriptor), stage.selectedItemId);
+    if (!item?.nodeId)
+        return EMPTY_EDITOR_SELECTION;
+    const projectionNodeId = resolvePrefabStageProjectionNodeIdForNode(state, options, document, item.nodeId);
+    if (!projectionNodeId)
+        return EMPTY_EDITOR_SELECTION;
+    const target = resolvePrefabStagePreviewTarget(state, options, document, projectionNodeId);
+    if (!target?.selectable)
+        return EMPTY_EDITOR_SELECTION;
+    return {
+        selectedIds: [projectionNodeId],
+        activeId: projectionNodeId,
+    };
+}
+function syncPrefabStageSelectionToProjection(state, options, reason = 'prefab-stage-projection-selection', revision = state.editorStateRevision) {
+    if (!state.prefabStage)
+        return;
+    if (!beginSceneArtifactSync(state, reason, revision))
+        return;
+    const projectionSelection = getCurrentPrefabStageProjectionSelection(state, options);
+    state.projection?.syncSelection(projectionSelection);
+    state.gizmo?.setSelection(getCurrentPrefabStageTransformGizmoSelection(state, options, projectionSelection));
+    syncTransformGizmoToSceneArtifacts(state, reason, revision, false);
+}
+function getCurrentPrefabStageTransformGizmoSelection(state, options, selection = getCurrentPrefabStageProjectionSelection(state, options)) {
+    const activeId = selection.activeId;
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    if (!activeId || !state.prefabStage || !document)
+        return EMPTY_EDITOR_SELECTION;
+    const target = resolvePrefabStagePreviewTarget(state, options, document, activeId);
+    return target?.transformable ? selection : EMPTY_EDITOR_SELECTION;
+}
+function isPrefabStageProjectionSelectable(state, options, projectionNodeId) {
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    if (!state.prefabStage || !document)
+        return false;
+    return resolvePrefabStagePreviewTarget(state, options, document, projectionNodeId)?.selectable === true;
+}
+function dispatchPrefabStageProjectionSelectionCommand(state, options, command) {
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    if (!state.prefabStage || !document)
+        return false;
+    const currentProjectionSelection = getCurrentPrefabStageProjectionSelection(state, options);
+    if (command.type === 'selection.clear') {
+        if (state.prefabStage.selectedItemId === null)
+            return false;
+        state.prefabStage = { ...state.prefabStage, selectedItemId: null };
+        state.editorStateRevision += 1;
+        syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-clear', state.editorStateRevision);
+        return true;
+    }
+    const candidateId = ('activeId' in command ? command.activeId : null)
+        ?? command.selectedIds[command.selectedIds.length - 1]
+        ?? null;
+    if (!candidateId)
+        return false;
+    const target = resolvePrefabStagePreviewTarget(state, options, document, candidateId);
+    if (!target?.selectable)
+        return false;
+    const currentlySelected = currentProjectionSelection.selectedIds.includes(candidateId);
+    if ((command.type === 'selection.toggle' && currentlySelected)
+        || (command.type === 'selection.remove' && currentlySelected)) {
+        state.prefabStage = { ...state.prefabStage, selectedItemId: null };
+        state.editorStateRevision += 1;
+        syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-remove', state.editorStateRevision);
+        return true;
+    }
+    if (command.type === 'selection.remove')
+        return false;
+    const nextItemId = target.itemId ?? `prefab-node:${target.targetId}`;
+    if (state.prefabStage.selectedItemId === nextItemId)
+        return false;
+    state.prefabStage = { ...state.prefabStage, selectedItemId: nextItemId };
+    state.editorStateRevision += 1;
+    syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-command', state.editorStateRevision);
+    return true;
+}
+function resolvePrefabStagePreviewTarget(state, options, document, projectionNodeId) {
+    const stage = state.prefabStage;
+    if (!stage)
+        return null;
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document) ?? stage.descriptor;
+    const context = createPrefabStageContext(state, descriptor);
+    const adapterTarget = options.documentAdapter.resolvePrefabStagePreviewTarget?.(document, descriptor, projectionNodeId, context);
+    if (adapterTarget)
+        return adapterTarget;
+    return resolvePrefabStagePreviewTargetFromStructure(descriptor, projectionNodeId, options.documentAdapter.getPrefabStageStructure?.(document, descriptor, context) ?? createFallbackPrefabStageStructure(descriptor));
+}
+function resolvePrefabStageProjectionNodeIdForNode(state, options, document, nodeId) {
+    const stage = state.prefabStage;
+    if (!stage)
+        return null;
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document) ?? stage.descriptor;
+    const context = createPrefabStageContext(state, descriptor);
+    const adapterProjectionNodeId = options.documentAdapter.getPrefabStageProjectionNodeId?.(document, descriptor, nodeId, context);
+    if (adapterProjectionNodeId)
+        return adapterProjectionNodeId;
+    const target = findPrefabStageStructureNodeByNodeId(options.documentAdapter.getPrefabStageStructure?.(document, descriptor, context) ?? createFallbackPrefabStageStructure(descriptor), nodeId);
+    return target?.nodeId ? createFallbackPrefabStageProjectionNodeId(descriptor, target.nodeId) : null;
+}
+function resolvePrefabStagePreviewTargetFromStructure(descriptor, projectionNodeId, items) {
+    const prefix = descriptor.previewNodeId;
+    if (!prefix || projectionNodeId.includes(':compare-'))
+        return null;
+    for (const item of flattenPrefabStageStructureNodes(items)) {
+        if (!item.nodeId)
+            continue;
+        const expectedProjectionNodeId = createFallbackPrefabStageProjectionNodeId(descriptor, item.nodeId);
+        if (expectedProjectionNodeId !== projectionNodeId)
+            continue;
+        const readonly = descriptor.readonly === true || item.readonly === true;
+        const isRoot = item.kind === 'root';
+        return {
+            scopeId: `prefab-stage:${descriptor.assetId}`,
+            scopeKind: 'prefab-stage',
+            projectionNodeId,
+            targetId: item.nodeId,
+            itemId: item.id,
+            label: item.label,
+            kind: item.kind,
+            selectable: true,
+            transformable: !readonly && !isRoot,
+            readonly,
+            ...(!readonly && !isRoot ? {} : { disabledReason: readonly ? 'Prefab stage is readonly.' : 'Prefab root cannot be transformed from Preview.' }),
+        };
+    }
+    return null;
+}
+function createFallbackPrefabStageProjectionNodeId(descriptor, nodeId) {
+    const prefix = descriptor.previewNodeId;
+    if (!prefix)
+        return null;
+    return nodeId === 'prefab-root' ? prefix : `${prefix}:${nodeId}`;
+}
+function findPrefabStageStructureNodeByNodeId(items, nodeId) {
+    return flattenPrefabStageStructureNodes(items).find(item => item.nodeId === nodeId) ?? null;
+}
+function findPrefabStageStructureItemById(items, itemId) {
+    return flattenPrefabStageStructureNodes(items).find(item => item.id === itemId) ?? null;
+}
+function flattenPrefabStageStructureNodes(items) {
+    const flattened = [];
+    for (const item of items) {
+        if (item.itemType === 'prefab-node' && item.nodeId)
+            flattened.push(item);
+        flattened.push(...flattenPrefabStageStructureNodes(item.children ?? []));
+    }
+    return flattened;
+}
+function createFallbackPrefabStageDescriptor(assetId, browserAssetId, item) {
+    if (!item?.prefab)
+        return null;
+    return {
+        assetId: item.prefab.id || item.assetId || assetId,
+        browserAssetId: browserAssetId ?? item.id,
+        label: item.prefab.name || item.label || item.prefab.id || assetId,
+        sourceAssetId: item.prefab.sourceAssetId,
+        sourceAssetGuid: item.prefab.sourceAssetGuid,
+        readonly: item.prefab.readonly === true,
+        previewNodeId: `prefab-stage:${item.prefab.id || item.assetId || assetId}`,
+    };
+}
+function resolvePrefabStageDescriptorForDocument(state, options, document) {
+    const stage = state.prefabStage;
+    if (!stage)
+        return null;
+    const assetId = stage.descriptor.assetId;
+    const browserAssetId = stage.descriptor.browserAssetId;
+    const descriptor = options.documentAdapter.getPrefabStageDescriptor?.(document, {
+        assetId,
+        browserAssetId,
+        asset: stage.asset,
+    });
+    if (descriptor) {
+        return {
+            ...stage.descriptor,
+            ...descriptor,
+            browserAssetId: descriptor.browserAssetId ?? browserAssetId,
+            previewNodeId: descriptor.previewNodeId ?? stage.descriptor.previewNodeId,
+        };
+    }
+    const browserItem = findBrowserAssetItemByResolvedId(state, options, document, browserAssetId ?? assetId)
+        ?? (browserAssetId ? findBrowserAssetItemByResolvedId(state, options, document, assetId) : null);
+    return createFallbackPrefabStageDescriptor(assetId, browserAssetId, browserItem) ?? stage.descriptor;
+}
+function patchBrowserAssetAction(state, options, input, selectionOverride) {
     const session = state.session;
     const document = session?.getState().workingDocument ?? null;
     if (!session || !document || !options.documentAdapter.createAssetActionPatch)
         return false;
     const asset = input.assetId ? findAssetByResolvedId(state, options, input.assetId) : null;
+    const sessionSelection = session.getState().selection;
     const patch = options.documentAdapter.createAssetActionPatch({
         ...input,
         document,
         asset,
-        activeId: session.getState().selection.activeId,
-        selectedIds: [...session.getState().selection.selectedIds],
+        activeId: selectionOverride?.activeId ?? sessionSelection.activeId,
+        selectedIds: selectionOverride?.selectedIds ?? [...sessionSelection.selectedIds],
     });
     if (!patch)
         return false;
@@ -2175,12 +3552,52 @@ function patchBrowserAssetAction(state, options, input) {
         reprojectProjectionForChangedIds(state, options, result.workingDocument, patch.reprojectIds);
     else if (patch.changedIds)
         syncProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds);
+    else if (state.prefabStage && result.documentChanged) {
+        rebuildProjectionFromDocument(state, options, result.workingDocument, EMPTY_EDITOR_SELECTION);
+    }
+    if (result.documentChanged && isPrefabStageShadowAssetAction(input)) {
+        state.shadowPreview?.invalidateStaticProjectedArtifact?.();
+        scheduleProjectionShadowPreviewRefresh(state, 'prefab-stage-shadow-policy-action');
+    }
+    syncPrefabStageSelectionFromAssetAction(state, options, input, patch.createdId ?? patch.changedId ?? null);
     if (input.actionId === 'asset.delete-material' && input.browserAssetId && state.selectedAssetId === input.browserAssetId) {
         state.selectedAssetId = null;
     }
     selectCreatedBrowserAssetFromPatch(state, options, patch.createdId ?? null, input);
     return true;
 }
+function isPrefabStageShadowAssetAction(input) {
+    if (input.actionId === 'prefab.node.setShadow')
+        return true;
+    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.');
+}
+function syncPrefabStageSelectionFromAssetAction(state, options, input, nodeId) {
+    if (!state.prefabStage)
+        return;
+    const isPrefabNodeAction = input.actionId.startsWith('prefab.node.')
+        || input.actionId === 'asset.add-to-current-prefab';
+    if (!isPrefabNodeAction)
+        return;
+    if (input.actionId === 'prefab.node.delete') {
+        const rootId = typeof nodeId === 'string' && nodeId ? nodeId : 'prefab-root';
+        state.prefabStage = {
+            ...state.prefabStage,
+            selectedItemId: `prefab-node:${rootId}`,
+        };
+        syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-delete');
+        return;
+    }
+    if (!nodeId)
+        return;
+    state.prefabStage = {
+        ...state.prefabStage,
+        selectedItemId: `prefab-node:${nodeId}`,
+    };
+    syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-asset-action');
+}
 function selectCreatedBrowserAssetFromPatch(state, options, createdId, input) {
     if (!createdId)
         return;
@@ -2191,12 +3608,18 @@ function selectCreatedBrowserAssetFromPatch(state, options, createdId, input) {
     else if (input.actionId === 'asset.create-material' || input.actionId === 'asset.duplicate-material') {
         state.selectedAssetId = `material:${createdId}`;
     }
+    else if (input.actionId === 'asset.create-prefab'
+        || input.actionId === 'asset.create-prefab-from-game-object'
+        || input.actionId === 'asset.duplicate-prefab') {
+        state.selectedAssetId = resolveBrowserAssetItemId(state, options, `prefab:${createdId}`) ?? `prefab:${createdId}`;
+    }
 }
 function armAssetPlacement(state, options, assetId) {
     if (state.mode !== 'editor')
         return false;
     cancelActiveOperation(state);
-    const asset = findAssetByResolvedId(state, options, assetId);
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    const asset = findAssetOrDocumentBrowserItemByResolvedId(state, options, document, assetId);
     if (!asset)
         return false;
     state.armedPlacement = { assetId, asset };
@@ -2298,7 +3721,7 @@ function addAssetToDocument(state, options, assetId, createOptions = {}) {
         state.status = 'Asset creation rejected: document is not loaded';
         return { ok: false, assetId, changed: false, status: state.status, error: 'document_not_loaded' };
     }
-    const asset = findAssetByResolvedId(state, options, assetId);
+    const asset = findAssetOrDocumentBrowserItemByResolvedId(state, options, beforeDocument, assetId);
     if (!asset) {
         state.status = `Asset creation rejected: ${assetId} not found`;
         return { ok: false, assetId, changed: false, status: state.status, error: 'asset_not_found' };
@@ -2307,6 +3730,7 @@ function addAssetToDocument(state, options, assetId, createOptions = {}) {
         document: beforeDocument,
         asset,
         assetId,
+        name: createOptions.name,
         placement: createOptions.placement,
     });
     const result = session.dispatch({
@@ -2322,7 +3746,7 @@ function addAssetToDocument(state, options, assetId, createOptions = {}) {
         ?? options.documentAdapter.findCreatedId?.(beforeDocument, result.workingDocument)
         ?? null;
     let selectionResult = null;
-    if (createdId) {
+    if (createdId && createOptions.select !== false) {
         selectionResult = session.dispatch({
             type: 'selection.replace',
             selectedIds: [createdId],
@@ -2340,7 +3764,7 @@ function addAssetToDocument(state, options, assetId, createOptions = {}) {
         if (projectedNode) {
             state.projection?.projectNode(projectedNode);
             if (selectionResult)
-                syncSelectionToProjection(state, selectionResult.selection);
+                syncSelectionToProjection(state, options, selectionResult.selection);
             invalidateEditorScene(state, 'projection-project-node');
         }
     }
@@ -2367,6 +3791,12 @@ function patchSerializedProperty(state, options, input) {
         return false;
     }
     const payload = transaction.payload;
+    if (state.prefabStage) {
+        return patchPrefabStageInspectorProperty(state, options, payload);
+    }
+    const markerGraphPatched = patchMarkerGraphInspectorProperty(state, options, document, payload);
+    if (markerGraphPatched !== null)
+        return markerGraphPatched;
     const shouldReprojectInspectorEdit = shouldReprojectEditorInspectorEditPath(payload.path);
     if (targetIds.length > 1) {
         const patch = options.documentAdapter.createSerializedMultiPropertyPatch?.({
@@ -2385,9 +3815,11 @@ function patchSerializedProperty(state, options, input) {
             return false;
         const changedIds = patch.changedIds ?? targetIds;
         const projectionMetadataPatch = isSerializedProjectionMetadataPath(payload.path);
+        const shadowTopologyMetadataPatch = isSerializedShadowTopologyMetadataPath(payload.path);
         const largeProjectionMetadataPatch = projectionMetadataPatch
+            && !shadowTopologyMetadataPatch
             && changedIds.length >= LARGE_SHADOW_MODE_BATCH_THRESHOLD;
-        const invalidateStaticShadowArtifact = projectionMetadataPatch && payload.path === 'shadowMode';
+        const invalidateStaticShadowArtifact = projectionMetadataPatch && isSerializedShadowMetadataPath(payload.path);
         const result = state.session.dispatch({
             type: 'document.patch',
             label: patch.label ?? `Patch ${payload.path} on ${targetIds.length} objects`,
@@ -2416,6 +3848,9 @@ function patchSerializedProperty(state, options, input) {
             reprojectProjectionForChangedIds(state, options, workingDocument, patch.reprojectIds);
         else if (shouldReprojectInspectorEdit)
             reprojectProjectionForChangedIds(state, options, workingDocument, changedIds);
+        else if (shadowTopologyMetadataPatch) {
+            rebuildProjectionAfterShadowTopologyMetadataPatch(state, options, workingDocument, sessionState.selection);
+        }
         else if (isSerializedProjectionMetadataPath(payload.path)) {
             syncProjectionMetadataForChangedIds(state, options, workingDocument, projectionSyncIds, {
                 deferShadowPreviewRefresh: largeProjectionMetadataPatch,
@@ -2424,6 +3859,10 @@ function patchSerializedProperty(state, options, input) {
         }
         else
             syncProjectionForChangedIds(state, options, workingDocument, projectionSyncIds);
+        if (isMarkerInspectorEditPath(payload.path)) {
+            syncMarkerOverlayToSceneArtifacts(state, options, result.selection);
+            state.gizmo?.refreshSelection();
+        }
         state.summary = summarizeDocument(options, workingDocument, state.session.getSource());
         state.status = patch.label ?? `Patch ${payload.path} on ${targetIds.length} objects`;
         return true;
@@ -2459,9 +3898,13 @@ function patchSerializedProperty(state, options, input) {
     else if (shouldReprojectInspectorEdit) {
         reprojectProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds ?? [patch.changedId ?? payload.targetId]);
     }
+    else if (isSerializedShadowTopologyMetadataPath(payload.path)) {
+        const selection = state.session?.getState({ cloneDocuments: false }).selection ?? EMPTY_EDITOR_SELECTION;
+        rebuildProjectionAfterShadowTopologyMetadataPatch(state, options, result.workingDocument, selection);
+    }
     else if (isSerializedProjectionMetadataPath(payload.path)) {
-        syncProjectionMetadataForChangedIds(state, options, result.workingDocument, [patch.changedId ?? payload.targetId], {
-            invalidateStaticShadowArtifact: payload.path === 'shadowMode',
+        syncProjectionMetadataForChangedIds(state, options, result.workingDocument, patch.changedIds ?? [patch.changedId ?? payload.targetId], {
+            invalidateStaticShadowArtifact: isSerializedShadowMetadataPath(payload.path),
         });
     }
     else if (isSerializedTransformPath(payload.path))
@@ -2470,11 +3913,313 @@ function patchSerializedProperty(state, options, input) {
         syncProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds);
     else
         syncProjectionForDispatchResult(state, options, result, patch.changedId ?? payload.targetId);
+    if (isMarkerInspectorEditPath(payload.path)) {
+        syncMarkerOverlayToSceneArtifacts(state, options, result.selection);
+        state.gizmo?.refreshSelection();
+    }
     state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
     state.status = patch.label ?? `Patched ${payload.path}`;
     return true;
 }
+function patchPrefabStageInspectorProperty(state, options, payload) {
+    if (payload.persistence !== 'document') {
+        state.status = `Prefab field is not document-editable: ${payload.path}.`;
+        return false;
+    }
+    const session = state.session;
+    const document = session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    if (!document)
+        return false;
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document) ?? state.prefabStage?.descriptor ?? null;
+    if (!descriptor) {
+        state.status = 'Prefab stage is not ready.';
+        return false;
+    }
+    return patchBrowserAssetAction(state, options, {
+        actionId: 'asset.edit-prefab-field',
+        assetId: descriptor.assetId,
+        browserAssetId: descriptor.browserAssetId,
+        assetKind: 'prefab',
+        fieldPath: payload.path,
+        value: payload.value,
+    });
+}
+function isMarkerInspectorEditPath(path) {
+    return path === 'name' || path.startsWith('marker.');
+}
+function patchMarkerGraphInspectorProperty(state, options, document, payload) {
+    if (!isMarkerInspectorEditPath(payload.path))
+        return null;
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    if (!readMarkerGraphHierarchyMarkerIdForGraph(graph, payload.targetId, hierarchy))
+        return null;
+    const markerTypes = options.documentAdapter.getMarkerTypeCatalog?.(document) ?? [];
+    const command = createMarkerGraphPatchFromInspectorEdit(graph, payload, hierarchy, markerTypes);
+    if (!command) {
+        state.status = `Marker edit rejected: ${payload.path}`;
+        return false;
+    }
+    const patch = options.documentAdapter.createMarkerGraphPatch?.(document, command);
+    if (!patch) {
+        state.status = `Marker edit rejected: ${payload.targetId}`;
+        return false;
+    }
+    const result = state.session?.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `Patch marker ${payload.path}`,
+        patch: patch.patch,
+        targetId: payload.targetId,
+    });
+    if (!result?.documentChanged)
+        return false;
+    syncProjectionForDispatchResult(state, options, result, patch.changedId ?? payload.targetId);
+    syncMarkerOverlayToSceneArtifacts(state, options, result.selection);
+    state.gizmo?.refreshSelection();
+    state.summary = summarizeDocument(options, result.workingDocument, state.session?.getSource());
+    state.status = patch.label ?? `Patched marker ${payload.path}`;
+    return true;
+}
+function patchMarkerTypeCatalog(state, options, input) {
+    if (state.mode !== 'editor')
+        return false;
+    cancelActiveOperation(state);
+    const document = state.session?.getState().workingDocument ?? null;
+    if (!document)
+        return false;
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    if (!graph || !options.documentAdapter.createMarkerGraphPatch)
+        return false;
+    const command = createMarkerTypeCatalogCommand(input);
+    if (!command) {
+        state.status = 'Marker type edit rejected';
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return false;
+    }
+    const patch = options.documentAdapter.createMarkerGraphPatch(document, command);
+    if (!patch) {
+        state.status = `Marker type edit rejected: ${input.type}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return false;
+    }
+    const session = state.session;
+    if (!session)
+        return false;
+    const result = session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? 'Patch marker type catalog',
+        patch: patch.patch,
+        targetId: session.getState().selection.activeId ?? undefined,
+    });
+    if (!result.documentChanged)
+        return false;
+    syncMarkerOverlayToSceneArtifacts(state, options, result.selection);
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
+    state.status = patch.label ?? 'Patched marker type catalog';
+    state.statusTone = 'success';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function patchMarkerRelation(state, options, input) {
+    if (state.mode !== 'editor')
+        return false;
+    cancelActiveOperation(state);
+    const document = state.session?.getState().workingDocument ?? null;
+    if (!document)
+        return false;
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    if (!graph)
+        return false;
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const activeId = state.session?.getState().selection.activeId ?? null;
+    const activeMarkerId = activeId ? readSpatialMarkerIdFromHierarchySelection(graph, activeId, hierarchy) : null;
+    if (input.action === 'pick-cancel') {
+        state.markerRelationPick = null;
+        state.status = '已取消关系端点拾取。';
+        state.statusTone = 'success';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+        return true;
+    }
+    if (input.action === 'pick-start') {
+        const relationTypes = options.documentAdapter.getRelationTypeCatalog?.(document) ?? [];
+        const type = input.type.trim();
+        if (!type) {
+            state.status = '请选择关系类型。';
+            state.statusTone = 'warning';
+            state.statusToneStatus = state.status;
+            state.statusDetails = state.status;
+            return true;
+        }
+        const typeDefinition = relationTypes.find(definition => definition.type === type);
+        const from = createMarkerRelationPickEndpoint(input.fromKind, input.fromId);
+        const directed = input.directed ?? typeDefinition?.directed ?? true;
+        const typeLabel = typeDefinition?.label ?? type;
+        const status = from
+            ? `关系拾取中：${formatMarkerRelationPickEndpointLabel(from, graph, hierarchy)} ${typeLabel} ... 请在视口点击终点。`
+            : `关系拾取中：请选择 ${typeLabel} 的起点。`;
+        state.markerRelationPick = {
+            active: true,
+            type,
+            typeLabel,
+            directed,
+            from,
+            status,
+            statusTone: 'success',
+        };
+        state.status = status;
+        state.statusTone = 'success';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '关系拾取会消费下一次有效视口点击，不改变当前选择。';
+        return true;
+    }
+    if (input.action === 'select') {
+        const relationId = input.relationId.trim();
+        if (!relationId)
+            return false;
+        const relation = graph.relations.find(candidate => candidate.id === relationId) ?? null;
+        state.activeMarkerRelationId = relationId;
+        state.status = relation ? `高亮关系：${relation.label ?? relation.type}` : `关系不存在：${relationId}`;
+        state.statusTone = relation ? 'success' : 'warning';
+        state.statusToneStatus = state.status;
+        state.statusDetails = relation ? relationId : state.status;
+        syncMarkerOverlayToSceneArtifacts(state, options, state.session?.getState().selection ?? { selectedIds: [], activeId: null });
+        requestEditorSceneFrame(state, 'marker-relation-select');
+        return true;
+    }
+    if (!options.documentAdapter.createMarkerGraphPatch)
+        return false;
+    const relationTypes = options.documentAdapter.getRelationTypeCatalog?.(document) ?? [];
+    const result = input.action === 'reverse'
+        ? createMarkerRelationReverseCommand(input.relationId, graph)
+        : input.action === 'delete-connected'
+            ? createMarkerRelationDeleteConnectedCommand(input.markerId ?? activeMarkerId ?? '', graph)
+            : input.action === 'create' && input.toEndpoints && input.toEndpoints.length > 0
+                ? createMarkerRelationCreateManyCommand({
+                    type: input.type,
+                    fromKind: input.fromKind,
+                    fromId: input.fromId,
+                    toEndpoints: input.toEndpoints,
+                    directed: input.directed,
+                }, graph, relationTypes, hierarchy, activeMarkerId)
+                : createMarkerRelationCommand(input, graph, relationTypes, hierarchy, activeMarkerId);
+    if (!result.command) {
+        state.status = result.status;
+        state.statusTone = result.statusTone;
+        state.statusToneStatus = state.status;
+        state.statusDetails = result.status;
+        return true;
+    }
+    const patch = options.documentAdapter.createMarkerGraphPatch(document, result.command);
+    if (!patch) {
+        state.status = result.status || 'Marker relation edit rejected';
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        state.statusDetails = state.status;
+        return true;
+    }
+    const session = state.session;
+    if (!session)
+        return false;
+    const patchResult = session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? result.status,
+        patch: patch.patch,
+        targetId: session.getState().selection.activeId ?? undefined,
+    });
+    if (!patchResult.documentChanged)
+        return false;
+    if (doesMarkerGraphCommandDeleteRelation(result.command, state.activeMarkerRelationId)) {
+        state.activeMarkerRelationId = null;
+    }
+    if (!isMarkerRelationStillPresent(options, patchResult.workingDocument, state.activeMarkerRelationId)) {
+        state.activeMarkerRelationId = null;
+    }
+    state.markerRelationPick = null;
+    syncMarkerOverlayToSceneArtifacts(state, options, patchResult.selection);
+    state.gizmo?.refreshSelection();
+    state.summary = summarizeDocument(options, patchResult.workingDocument, session.getSource());
+    state.status = patch.label ?? result.status;
+    state.statusTone = result.statusTone;
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function createMarkerRelationPickEndpoint(kind, id) {
+    const endpointKind = kind?.trim();
+    const endpointId = id?.trim();
+    if (!endpointKind || !endpointId)
+        return null;
+    if (endpointKind !== 'marker' && endpointKind !== 'scene-object')
+        return null;
+    return { kind: endpointKind, id: endpointId };
+}
+function formatMarkerRelationPickEndpointLabel(endpoint, graph, hierarchy) {
+    const label = endpoint.kind === 'marker'
+        ? findSpatialMarkerById(graph, endpoint.id)?.label ?? endpoint.id
+        : hierarchy.find(item => item.id === endpoint.id)?.label ?? endpoint.id;
+    const kindLabel = endpoint.kind === 'marker' ? '标记' : '对象';
+    return `${kindLabel} ${label}`;
+}
+function doesMarkerGraphCommandDeleteRelation(command, relationId) {
+    if (!relationId)
+        return false;
+    switch (command.type) {
+        case 'relation.delete':
+            return command.relationId === relationId;
+        case 'relation.delete-many':
+            return command.relationIds.includes(relationId);
+        default:
+            return false;
+    }
+}
+function isMarkerRelationStillPresent(options, document, relationId) {
+    if (!relationId)
+        return true;
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    return !!graph?.relations.some(relation => relation.id === relationId);
+}
+function createMarkerTypeCatalogCommand(input) {
+    const type = input.type.trim();
+    if (!type)
+        return null;
+    if (input.action === 'delete') {
+        return {
+            type: 'marker-type.delete',
+            typeId: type,
+        };
+    }
+    const label = input.label?.trim() || type;
+    const kind = input.kind?.trim() || undefined;
+    const description = 'description' in input ? input.description?.trim() ?? '' : undefined;
+    if (input.action === 'create') {
+        return {
+            type: 'marker-type.create',
+            definition: {
+                type,
+                label,
+                ...(kind ? { kind } : {}),
+                ...(description ? { description } : {}),
+            },
+        };
+    }
+    return {
+        type: 'marker-type.update',
+        typeId: type,
+        patch: {
+            label,
+            ...(kind !== undefined ? { kind } : {}),
+            ...(description !== undefined ? { description } : {}),
+        },
+    };
+}
 function patchHierarchyItemEnabled(state, options, input) {
+    const markerVisibilityResult = patchMarkerGraphHierarchyVisibility(state, options, input);
+    if (markerVisibilityResult !== 'unhandled')
+        return markerVisibilityResult === 'changed';
     return patchSerializedProperty(state, options, {
         targetId: input.id,
         path: 'enabled',
@@ -2486,6 +4231,47 @@ function patchHierarchyItemEnabled(state, options, input) {
         source: 'toggle',
     });
 }
+function patchMarkerGraphHierarchyVisibility(state, options, input) {
+    const document = state.session?.getState().workingDocument ?? null;
+    if (!document)
+        return 'unhandled';
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    if (!graph)
+        return 'unhandled';
+    const hierarchy = options.documentAdapter.getHierarchyItems(document);
+    const visibility = state.markerGraphVisibility;
+    if (isMarkerGraphHierarchyRootRowId(graph, input.id, hierarchy)) {
+        if (visibility.rootVisible === input.enabled)
+            return 'handled';
+        visibility.rootVisible = input.enabled;
+        state.editorStateRevision += 1;
+        syncCurrentSelectionToSceneArtifacts(state, options, 'marker-graph-visibility-toggle', state.editorStateRevision);
+        state.status = input.enabled ? 'Markers shown' : 'Markers hidden';
+        state.statusTone = 'success';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+        return 'changed';
+    }
+    const markerId = readMarkerGraphHierarchyMarkerIdForGraph(graph, input.id, hierarchy)
+        ?? (isSpatialMarkerBackedByHierarchyRow(graph, input.id, hierarchy) ? input.id : null);
+    if (!markerId)
+        return 'unhandled';
+    const changed = input.enabled
+        ? visibility.hiddenMarkerIds.delete(markerId)
+        : !visibility.hiddenMarkerIds.has(markerId);
+    if (!input.enabled)
+        visibility.hiddenMarkerIds.add(markerId);
+    if (!changed)
+        return 'handled';
+    state.editorStateRevision += 1;
+    syncCurrentSelectionToSceneArtifacts(state, options, 'marker-visibility-toggle', state.editorStateRevision);
+    const marker = findSpatialMarkerById(graph, markerId);
+    state.status = `${marker?.label ?? markerId} ${input.enabled ? 'shown' : 'hidden'}`;
+    state.statusTone = 'success';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return 'changed';
+}
 async function applyRenderingPropertyChange(state, options, input) {
     if (state.mode !== 'editor')
         return false;
@@ -2547,17 +4333,26 @@ async function applyRenderingPropertyChange(state, options, input) {
     }
 }
 async function applyRenderingAction(state, options, input, render) {
-    if (state.mode !== 'editor')
-        return false;
-    if (!state.session || !options.documentAdapter.onRenderingAction)
-        return false;
+    if (state.mode !== 'editor') {
+        return { ok: false, changed: false, rendered: false, status: 'Editor is not in edit mode.', statusTone: 'warning' };
+    }
+    if (!state.session || !options.documentAdapter.onRenderingAction) {
+        return { ok: false, changed: false, rendered: false, status: 'Rendering action pipeline is unavailable.', statusTone: 'warning' };
+    }
     if (state.renderingAction) {
         state.status = state.renderingAction.status ?? `Rendering action already running: ${state.renderingAction.actionId}`;
         state.statusTone = state.renderingAction.statusTone ?? 'default';
         state.statusToneStatus = state.status;
         state.statusDetails = state.renderingAction.statusDetails ?? '';
         render();
-        return true;
+        return {
+            ok: false,
+            changed: false,
+            rendered: true,
+            status: state.status,
+            statusTone: state.statusTone,
+            ...(state.statusDetails ? { statusDetails: state.statusDetails } : {}),
+        };
     }
     const document = state.session.getState().workingDocument;
     const progressStartedAt = Date.now();
@@ -2606,6 +4401,7 @@ async function applyRenderingAction(state, options, input, render) {
             || resultObject?.changed === true
             || resultObject?.refreshWorldRendering === true
             || documentPatchResult?.changed === true;
+        const rendered = changed || !!resultObject?.status;
         if (resultObject?.status) {
             state.status = resultObject.status;
             state.statusTone = resultObject.statusTone ?? 'default';
@@ -2629,7 +4425,15 @@ async function applyRenderingAction(state, options, input, render) {
             invalidateEditorScene(state, 'rendering-panel-action', options);
         }
         clearRenderingActionAfterMinimumDuration(state, progressStartedAt, input.actionId, render);
-        return changed || !!resultObject?.status;
+        return {
+            ok: resultObject?.statusTone !== 'error',
+            changed,
+            rendered,
+            ...(state.status ? { status: state.status } : {}),
+            statusTone: state.statusTone,
+            ...(state.statusDetails ? { statusDetails: state.statusDetails } : {}),
+            ...(resultObject?.details ? { details: resultObject.details } : {}),
+        };
     }
     catch (error) {
         state.renderingAction = null;
@@ -2638,7 +4442,15 @@ async function applyRenderingAction(state, options, input, render) {
         state.statusToneStatus = state.status;
         state.statusDetails = state.status;
         console.error('[LocalEditorHarness] rendering action failed', error);
-        return true;
+        return {
+            ok: false,
+            changed: false,
+            rendered: true,
+            status: state.status,
+            statusTone: 'error',
+            statusDetails: state.statusDetails,
+            error: state.status,
+        };
     }
 }
 function clearRenderingActionAfterMinimumDuration(state, startedAt, actionId, render) {
@@ -2735,6 +4547,11 @@ function findInspectorPropertyForEdit(state, options, document, input, targetIds
     return findInspectorPropertyByPath(inspector, input.path);
 }
 function createInspectorObjectForEdit(state, options, document, input, targetIds) {
+    if (targetIds.length === 1 && state.prefabStage) {
+        const inspector = createPrefabStageInspectorObjectForEdit(state, options, document);
+        if (inspector && inspector.targetIds.includes(input.targetId))
+            return inspector;
+    }
     if (targetIds.length > 1) {
         const activeId = state.session?.getState().selection.activeId ?? input.targetId ?? null;
         const inspector = createInspectorMultiObjectBase(state, options, document, targetIds, activeId);
@@ -2742,6 +4559,9 @@ function createInspectorObjectForEdit(state, options, document, input, targetIds
             return withDefaultEditorInspectorSections(state, options, document, inspector);
         return null;
     }
+    const markerInspector = createMarkerInspectorObjectBase(options, document, input.targetId);
+    if (markerInspector)
+        return markerInspector;
     const inspector = options.documentAdapter.getInspectorObject?.(document, input.targetId) ?? null;
     if (inspector)
         return withDefaultEditorInspectorSections(state, options, document, inspector);
@@ -2750,6 +4570,13 @@ function createInspectorObjectForEdit(state, options, document, input, targetIds
         ? withDefaultEditorInspectorSections(state, options, document, serializedObjectToInspectorObject(serializedObject, document))
         : null;
 }
+function createPrefabStageInspectorObjectForEdit(state, options, document) {
+    const stage = state.prefabStage;
+    if (!stage || !options.documentAdapter.getPrefabStageInspectorObject)
+        return null;
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document) ?? stage.descriptor;
+    return options.documentAdapter.getPrefabStageInspectorObject(document, descriptor, stage.selectedItemId, createPrefabStageContext(state, descriptor)) ?? null;
+}
 function findInspectorPropertyByPath(inspector, path) {
     for (const section of inspector.sections) {
         const property = section.properties.find(candidate => candidate.path === path);
@@ -2793,14 +4620,28 @@ function isSerializedTransformPath(path) {
         || path.startsWith('transform.scale.');
 }
 function isSerializedProjectionMetadataPath(path) {
-    return path === 'shadowMode';
+    return isSerializedShadowMetadataPath(path);
+}
+function isSerializedShadowMetadataPath(path) {
+    return path === 'shadowMode' || path.startsWith('shadow.');
+}
+function isSerializedShadowTopologyMetadataPath(path) {
+    return path === 'shadowMode'
+        || path === 'shadow.cast'
+        || path === 'shadow.receive'
+        || path === 'shadow.mode'
+        || path === 'shadow.quality'
+        || path === 'shadow.light.mode'
+        || path === 'shadow.light.lightId'
+        || path.startsWith('shadow.light.');
 }
 function beginDuplicateDrag(state, options, input) {
     if (state.mode !== 'editor' || !state.session)
         return null;
     if (state.duplicateDrag)
         return null;
-    const document = state.session.getState().workingDocument;
+    const session = state.session;
+    const document = session.getState().workingDocument;
     const patch = options.documentAdapter.createDuplicateSelectionPatch?.({
         document,
         targetIds: input.targetIds,
@@ -2811,9 +4652,9 @@ function beginDuplicateDrag(state, options, input) {
         state.status = 'Duplicate drag rejected';
         return null;
     }
-    const originalSelection = state.session.getSelection();
+    const originalSelection = session.getSelection();
     const projectionImpact = resolveProjectionImpact(patch, createDuplicateProjectionImpact(patch));
-    const result = state.session.dispatch({
+    const result = session.dispatch({
         type: 'document.patch',
         label: patch.label ?? `Duplicate ${input.targetIds.length} object(s)`,
         patch: patch.patch,
@@ -2854,7 +4695,7 @@ function beginDuplicateDrag(state, options, input) {
     })) {
         rebuildProjectionFromDocument(state, options, result.workingDocument, selectionResult.selection);
     }
-    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
     state.status = patch.label ?? `Duplicated ${createdIds.length} object(s)`;
     return {
         targetIds: createdIds,
@@ -2883,7 +4724,12 @@ function cancelDuplicateDrag(state, options) {
 function commitGizmoTransform(state, options, event) {
     if (state.mode !== 'editor' || !state.session)
         return false;
+    if (state.prefabStage)
+        return commitPrefabStageGizmoTransform(state, options, event);
     const document = state.session.getState().workingDocument;
+    const markerChanged = commitMarkerGizmoTransform(state, options, document, event);
+    if (markerChanged !== null)
+        return markerChanged;
     if (isTransformBatchCommit(event)) {
         const patch = options.documentAdapter.createTransformBatchPatch?.({
             ...event,
@@ -2933,30 +4779,233 @@ function commitGizmoTransform(state, options, event) {
             state.status = `Ignored ${event.tool} ${targetId}`;
         }
         return false;
-    }
-    const result = state.session.dispatch({
+    }
+    const session = state.session;
+    if (!session)
+        return false;
+    const result = session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `${event.tool} ${targetId}`,
+        patch: patch.patch,
+        targetId,
+        ...withProjectionImpact(resolveProjectionImpact(patch, patch.reprojectIds?.length
+            ? createReprojectProjectionImpact(patch.reprojectIds)
+            : createTransformProjectionImpact([patch.changedId ?? targetId]))),
+    }, {
+        mergeWithPrevious: state.duplicateDrag?.createdIds.includes(targetId) === true,
+    });
+    if (patch.reprojectIds?.length)
+        reprojectProjectionForChangedIds(state, options, result.workingDocument, patch.reprojectIds);
+    else
+        syncProjectionForChangedIds(state, options, result.workingDocument, [patch.changedId ?? targetId]);
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
+    state.status = patch.label ?? `${event.tool} ${targetId}`;
+    state.duplicateDrag = null;
+    return result.documentChanged;
+}
+function commitPrefabStageGizmoTransform(state, options, event) {
+    const session = state.session;
+    const document = session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    if (!state.prefabStage || !session || !document || !options.documentAdapter.createAssetActionPatch)
+        return false;
+    if (isTransformBatchCommit(event)) {
+        restoreBatchTransformPreview(state, event.targets);
+        state.status = 'Ignored Prefab Stage multi-selection transform';
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return false;
+    }
+    const target = resolvePrefabStagePreviewTarget(state, options, document, event.nodeId);
+    if (!target?.selectable || !target.transformable) {
+        state.projection?.setNodeTransformPreview(event.nodeId, event.before);
+        state.status = target?.disabledReason ?? `Ignored ${event.tool} ${event.nodeId}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return false;
+    }
+    const transformActionValue = createPrefabStageTransformActionValue(event.after);
+    if (!transformActionValue) {
+        state.projection?.setNodeTransformPreview(event.nodeId, event.before);
+        state.status = `Ignored ${event.tool} ${target.label ?? target.targetId}: Prefab Stage transform requires TRS data`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return false;
+    }
+    const patch = options.documentAdapter.createAssetActionPatch({
+        actionId: 'prefab.node.setTransform',
+        targetPrefabAssetId: state.prefabStage.descriptor.assetId,
+        nodeId: target.targetId,
+        document,
+        asset: null,
+        activeId: target.targetId,
+        selectedIds: [target.targetId],
+        value: transformActionValue,
+    });
+    if (!patch) {
+        state.projection?.setNodeTransformPreview(event.nodeId, event.before);
+        state.status = `Ignored ${event.tool} ${target.label ?? target.targetId}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        return false;
+    }
+    const result = session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `Set prefab node ${target.targetId} transform`,
+        patch: patch.patch,
+        targetId: target.targetId,
+        ...withProjectionImpact(resolveProjectionImpact(patch, patch.reprojectIds?.length
+            ? createReprojectProjectionImpact(patch.reprojectIds)
+            : createTransformProjectionImpact([patch.changedId ?? target.targetId]))),
+    });
+    syncProjectionForDispatchResult(state, options, result);
+    rebuildProjectionFromDocument(state, options, result.workingDocument, EMPTY_EDITOR_SELECTION);
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
+    state.status = patch.label ?? `Set prefab node ${target.label ?? target.targetId} transform`;
+    state.statusTone = 'success';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    syncPrefabStageSelectionFromAssetAction(state, options, {
+        actionId: 'prefab.node.setTransform',
+    }, patch.changedId ?? target.targetId);
+    return result.documentChanged;
+}
+function createPrefabStageTransformActionValue(transform) {
+    if (!isEditorTransformTrsSnapshot(transform))
+        return null;
+    return {
+        type: 'Transform',
+        position: cloneEditorTransformVec3(transform.position),
+        rotation: cloneEditorTransformVec3(transform.rotation),
+        scale: cloneEditorTransformVec3(transform.scale),
+    };
+}
+function cloneEditorTransformVec3(value) {
+    return { x: value.x, y: value.y, z: value.z };
+}
+function commitMarkerGizmoTransform(state, options, document, event) {
+    if (isTransformBatchCommit(event))
+        return null;
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const hierarchy = graph ? options.documentAdapter.getHierarchyItems(document) : [];
+    const markerId = readSpatialMarkerIdFromHierarchySelection(graph, event.nodeId, hierarchy);
+    if (!markerId)
+        return null;
+    if (markerId === event.nodeId)
+        return null;
+    const marker = findSpatialMarkerById(graph, markerId);
+    if (!marker)
+        return false;
+    if (!isEditorTransformTrsSnapshot(event.after)) {
+        state.status = `Ignored ${event.tool} marker ${marker.label}: transform is not editable as TRS`;
+        return false;
+    }
+    if (editorTransformSnapshotsEqual(event.before, event.after)) {
+        state.status = `Unchanged ${event.tool} ${marker.label}`;
+        return false;
+    }
+    const nextPatch = createMarkerTransformPatchFromGizmo(marker, event.after);
+    const patch = options.documentAdapter.createMarkerGraphPatch?.(document, {
+        type: 'marker.update',
+        markerId,
+        patch: nextPatch,
+    });
+    if (!patch) {
+        state.markerOverlay?.setMarkerTransformPreview(event.nodeId, event.before);
+        state.status = `Ignored ${event.tool} marker ${marker.label}`;
+        return false;
+    }
+    const session = state.session;
+    if (!session)
+        return false;
+    const result = session.dispatch({
         type: 'document.patch',
-        label: patch.label ?? `${event.tool} ${targetId}`,
+        label: patch.label ?? `${event.tool} marker ${marker.label}`,
         patch: patch.patch,
-        targetId,
-        ...withProjectionImpact(resolveProjectionImpact(patch, patch.reprojectIds?.length
-            ? createReprojectProjectionImpact(patch.reprojectIds)
-            : createTransformProjectionImpact([patch.changedId ?? targetId]))),
-    }, {
-        mergeWithPrevious: state.duplicateDrag?.createdIds.includes(targetId) === true,
+        targetId: event.nodeId,
     });
-    if (patch.reprojectIds?.length)
-        reprojectProjectionForChangedIds(state, options, result.workingDocument, patch.reprojectIds);
-    else
-        syncProjectionForChangedIds(state, options, result.workingDocument, [patch.changedId ?? targetId]);
-    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
-    state.status = patch.label ?? `${event.tool} ${targetId}`;
-    state.duplicateDrag = null;
+    syncProjectionForDispatchResult(state, options, result, patch.changedId ?? markerId);
+    state.gizmo?.refreshSelection();
+    requestEditorSceneFrame(state, 'marker-gizmo-transform');
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
+    state.status = patch.label ?? `${event.tool} marker ${marker.label}`;
     return result.documentChanged;
 }
+function createMarkerTransformPatchFromGizmo(marker, transform) {
+    const semanticFrame = createMarkerSemanticFrameFromTransform(marker, transform);
+    if (marker.geometry.kind === 'box') {
+        const nextGeometry = {
+            ...marker.geometry,
+            center: { ...transform.position },
+            size: normalizeMarkerBoxSize(transform.scale),
+        };
+        if (marker.geometry.rotation || !editorVec3Equal(transform.rotation, { x: 0, y: 0, z: 0 })) {
+            nextGeometry.rotation = { ...transform.rotation };
+        }
+        else {
+            delete nextGeometry.rotation;
+        }
+        return {
+            geometry: nextGeometry,
+            semanticFrame,
+        };
+    }
+    if (marker.geometry.kind === 'point') {
+        return {
+            geometry: {
+                ...marker.geometry,
+                coordinateSpace: 'world',
+                position: { ...transform.position },
+            },
+            semanticFrame,
+        };
+    }
+    return {
+        semanticFrame,
+    };
+}
+function createMarkerSemanticFrameFromTransform(marker, transform) {
+    return {
+        ...(marker.semanticFrame ?? {}),
+        origin: { ...transform.position },
+        right: rotateEditorVec3ByEuler({ x: 1, y: 0, z: 0 }, transform.rotation),
+        up: rotateEditorVec3ByEuler({ x: 0, y: 1, z: 0 }, transform.rotation),
+        forward: rotateEditorVec3ByEuler({ x: 0, y: 0, z: 1 }, transform.rotation),
+        label: marker.semanticFrame?.label ?? marker.label,
+    };
+}
+function rotateEditorVec3ByEuler(value, rotation) {
+    const cx = Math.cos(rotation.x);
+    const sx = Math.sin(rotation.x);
+    const cy = Math.cos(rotation.y);
+    const sy = Math.sin(rotation.y);
+    const cz = Math.cos(rotation.z);
+    const sz = Math.sin(rotation.z);
+    const afterX = {
+        x: value.x,
+        y: value.y * cx - value.z * sx,
+        z: value.y * sx + value.z * cx,
+    };
+    const afterY = {
+        x: afterX.x * cy + afterX.z * sy,
+        y: afterX.y,
+        z: -afterX.x * sy + afterX.z * cy,
+    };
+    return {
+        x: afterY.x * cz - afterY.y * sz,
+        y: afterY.x * sz + afterY.y * cz,
+        z: afterY.z,
+    };
+}
 function isTransformBatchCommit(event) {
     return 'targets' in event;
 }
+function normalizeMarkerBoxSize(size) {
+    return {
+        x: Math.max(0.000001, Math.abs(size.x)),
+        y: Math.max(0.000001, Math.abs(size.y)),
+        z: Math.max(0.000001, Math.abs(size.z)),
+    };
+}
 function restoreBatchTransformPreview(state, targets) {
     const transforms = {};
     for (const target of targets)
@@ -2991,11 +5040,38 @@ function cancelActiveOperation(state) {
 function cancelEditorIntent(state, options) {
     if (state.mode !== 'editor')
         return false;
+    if (state.markerRelationPick) {
+        state.markerRelationPick = null;
+        state.status = '已取消关系端点拾取。';
+        state.statusTone = 'success';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+        return true;
+    }
     if (state.viewportTools.activeUtilityTool === 'measure-distance'
         || state.viewportMeasurement.start
         || state.viewportMeasurement.end) {
         return clearViewportMeasurement(state);
     }
+    if (state.prefabStage?.selectedItemId) {
+        cancelActiveOperation(state);
+        state.prefabStage = { ...state.prefabStage, selectedItemId: null };
+        state.editorStateRevision += 1;
+        syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-selection-cancel', state.editorStateRevision);
+        state.status = 'Cleared Prefab Stage selection';
+        state.statusTone = 'default';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+        return true;
+    }
+    if (state.prefabStage) {
+        cancelActiveOperation(state);
+        state.status = 'Canceled Prefab Stage operation';
+        state.statusTone = 'default';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+        return true;
+    }
     const selection = state.session?.getSelection();
     if (selection && selection.selectedIds.length > 0) {
         return dispatchSelectionCommand(state, options, { type: 'selection.clear', label: 'Clear Selection' });
@@ -3003,9 +5079,17 @@ function cancelEditorIntent(state, options) {
     cancelActiveOperation(state);
     return true;
 }
-function focusSelectedProjection(state) {
+function focusSelectedProjection(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 true;
+        }
+        return focusPrefabStageProjectionNode(state, options, activeId, 'prefab-stage-focus-selection');
+    }
     const activeId = state.session?.getState().selection.activeId ?? null;
     if (!activeId) {
         state.status = 'Focus failed: no selection';
@@ -3031,6 +5115,79 @@ function focusProjectionNode(state, nodeId) {
         requestEditorSceneFrame(state, 'viewport-focus-selection');
     return true;
 }
+function frameViewportProjectionNode(state, nodeId) {
+    if (state.mode !== 'editor')
+        return false;
+    const root = state.projection?.getAttachableRoot(nodeId) ?? null;
+    if (!root) {
+        state.status = `Focus failed: missing projection for ${nodeId}`;
+        return false;
+    }
+    const focused = focusEditorViewportSelection(state.world?.camera ?? null, root, {
+        babylon: state.babylon ?? undefined,
+    });
+    state.status = focused
+        ? `Focused ${nodeId} · ${formatEditorStatusTime(Date.now())}`
+        : `Focus failed: camera could not frame ${nodeId}`;
+    if (focused)
+        requestEditorSceneFrame(state, 'viewport-focus-object');
+    return focused;
+}
+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)
+        return false;
+    const target = resolvePrefabStagePreviewTarget(state, options, document, projectionNodeId);
+    if (!target?.selectable) {
+        state.status = `Focus failed: ${projectionNodeId} is not an editable Prefab Stage preview target`;
+        return true;
+    }
+    const root = state.projection?.getAttachableRoot(projectionNodeId) ?? null;
+    if (!root) {
+        state.status = `Focus failed: missing projection for ${projectionNodeId}`;
+        return true;
+    }
+    const focused = focusEditorViewportSelection(state.world?.camera ?? null, root, {
+        babylon: state.babylon ?? undefined,
+    });
+    state.status = focused
+        ? `Focused ${target.label ?? projectionNodeId} · ${formatEditorStatusTime(Date.now())}`
+        : `Focus failed: camera could not frame ${target.label ?? projectionNodeId}`;
+    if (focused)
+        requestEditorSceneFrame(state, reason);
+    return true;
+}
+function focusPrefabStagePreviewProjection(state, reason) {
+    const previewNodeId = state.prefabStage?.descriptor.previewNodeId;
+    if (!previewNodeId)
+        return;
+    const root = state.projection?.getAttachableRoot(previewNodeId) ?? null;
+    if (!root)
+        return;
+    const focused = focusEditorViewportSelection(state.world?.camera ?? null, root, {
+        babylon: state.babylon ?? undefined,
+    });
+    if (focused)
+        requestEditorSceneFrame(state, reason);
+}
 function formatEditorStatusTime(timestamp) {
     const date = new Date(timestamp);
     const pad = (value) => String(value).padStart(2, '0');
@@ -3232,6 +5389,10 @@ function applyIncrementalHistoryProjectionImpact(state, options, result, operati
 function applyIncrementalProjectionImpactToDocument(state, options, input) {
     if (!state.projection)
         return false;
+    if (state.prefabStage) {
+        rebuildProjectionFromDocument(state, options, input.document, EMPTY_EDITOR_SELECTION);
+        return true;
+    }
     const syncTransformIds = uniqueProjectionIds(input.syncTransformIds);
     const reprojectIds = uniqueProjectionIds(input.reprojectIds);
     const projectNodeIds = uniqueProjectionIds(input.projectNodeIds);
@@ -3254,13 +5415,14 @@ function applyIncrementalProjectionImpactToDocument(state, options, input) {
         state.projection.projectNode(projectedNode);
     }
     for (const projectedNode of reprojectNodes) {
-        state.projection.projectNode(projectedNode);
+        syncProjectionNodeTransformOrReprojectRuntime(state, projectedNode, { forceReproject: true });
     }
     for (const projectedNode of syncTransformNodes) {
-        state.projection.syncNodeTransform(projectedNode);
+        syncProjectionNodeTransformOrReprojectRuntime(state, projectedNode);
     }
+    applyPreviewVisibilityStateToProjection(state);
     const sanitized = sanitizeSelection(state, options, input.document, input.selection);
-    syncSelectionToProjection(state, sanitized ?? input.selection);
+    syncSelectionToProjection(state, options, sanitized ?? input.selection);
     syncEditorWorldAppearanceFromDocument(state, options, input.document, `world-appearance-${input.reason}`);
     syncEditorWorldRenderingFromDocument(state, options, input.document, `world-rendering-${input.reason}`, true);
     invalidateEditorScene(state, `projection-${input.reason}`, options);
@@ -3276,27 +5438,53 @@ function resolveProjectionNodes(options, document, ids) {
     }
     return projectedNodes;
 }
+function resolveCurrentEditorProjectionNodes(state, options, document) {
+    if (!state.prefabStage)
+        return options.documentAdapter.getProjectionNodes(document);
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document);
+    if (!descriptor)
+        return [];
+    return options.documentAdapter.getPrefabStageProjectionNodes?.(document, descriptor) ?? [];
+}
 function rebuildProjectionFromDocument(state, options, document, selection) {
-    state.projection?.rebuild(options.documentAdapter.getProjectionNodes(document));
-    const sanitized = sanitizeSelection(state, options, document, selection);
-    syncSelectionToProjection(state, sanitized ?? selection);
+    const nodes = resolveCurrentEditorProjectionNodes(state, options, document);
+    state.projection?.rebuild(nodes);
+    applyPreviewVisibilityStateToProjection(state);
+    if (state.prefabStage) {
+        syncPrefabStageSelectionToProjection(state, options, 'prefab-stage-projection-rebuild');
+    }
+    else {
+        const sanitized = sanitizeSelection(state, options, document, selection);
+        syncSelectionToProjection(state, options, sanitized ?? selection);
+    }
     syncEditorWorldAppearanceFromDocument(state, options, document, 'world-appearance-rebuild');
     syncEditorWorldRenderingFromDocument(state, options, document, 'world-rendering-rebuild', true);
+    if (state.prefabStage && nodes.length === 0) {
+        const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document);
+        state.status = `Prefab preview unavailable: ${descriptor?.label ?? state.prefabStage.descriptor.label}`;
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        state.statusDetails = 'The prefab source model asset could not be resolved for preview.';
+    }
     invalidateEditorScene(state, 'projection-rebuild');
 }
 function syncProjectionForDispatchResult(state, options, result, changedId) {
+    if (state.prefabStage && result.documentChanged && result.workingDocument) {
+        rebuildProjectionFromDocument(state, options, result.workingDocument, EMPTY_EDITOR_SELECTION);
+        return;
+    }
     if (result.documentChanged && changedId && result.workingDocument) {
         const projectedNode = options.documentAdapter.getProjectionNode(result.workingDocument, changedId);
         if (projectedNode)
-            state.projection?.syncNodeTransform(projectedNode);
+            syncProjectionNodeTransformOrReprojectRuntime(state, projectedNode);
     }
     if (result.selectionChanged) {
-        syncSelectionToProjection(state, result.selection ?? { selectedIds: [], activeId: null });
+        syncSelectionToProjection(state, options, result.selection ?? { selectedIds: [], activeId: null });
     }
     else if (result.documentChanged) {
         const selection = state.session?.getState({ cloneDocuments: false }).selection ?? { selectedIds: [], activeId: null };
         const sanitized = result.workingDocument ? sanitizeSelection(state, options, result.workingDocument, selection) : null;
-        syncSelectionToProjection(state, sanitized ?? selection);
+        syncSelectionToProjection(state, options, sanitized ?? selection);
     }
     if (result.documentChanged && result.workingDocument) {
         syncEditorWorldAppearanceFromDocument(state, options, result.workingDocument, 'world-appearance-dispatch-result');
@@ -3307,18 +5495,44 @@ function syncProjectionForDispatchResult(state, options, result, changedId) {
     }
 }
 function syncProjectionForChangedIds(state, options, document, changedIds) {
+    if (state.prefabStage) {
+        rebuildProjectionFromDocument(state, options, document, EMPTY_EDITOR_SELECTION);
+        return;
+    }
     for (const changedId of changedIds) {
         const projectedNode = options.documentAdapter.getProjectionNode(document, changedId);
         if (projectedNode)
-            state.projection?.syncNodeTransform(projectedNode);
+            syncProjectionNodeTransformOrReprojectRuntime(state, projectedNode);
     }
     const selection = state.session?.getState({ cloneDocuments: false }).selection ?? { selectedIds: [], activeId: null };
-    syncSelectionToProjection(state, selection);
+    syncSelectionToProjection(state, options, selection);
     syncEditorWorldAppearanceFromDocument(state, options, document, 'world-appearance-sync-changed-ids');
     syncEditorWorldRenderingFromDocument(state, options, document, 'world-rendering-sync-changed-ids', true);
     invalidateEditorScene(state, 'projection-sync-changed-ids');
 }
+function syncProjectionNodeTransformOrReprojectRuntime(state, projectedNode, options = {}) {
+    if (!state.projection)
+        return;
+    if (projectedNode.runtimeKind === 'light' && state.projection.syncRuntimeNode(projectedNode)) {
+        state.shadowPreview?.refresh();
+        return;
+    }
+    if (options.forceReproject || projectedNode.runtimeKind === 'light' || shouldReprojectRuntimeProjectionNode(projectedNode)) {
+        state.projection.projectNode(projectedNode);
+        if (projectedNode.runtimeKind === 'light')
+            state.shadowPreview?.refresh();
+        return;
+    }
+    state.projection.syncNodeTransform(projectedNode);
+}
+function shouldReprojectRuntimeProjectionNode(projectedNode) {
+    return projectedNode.runtimeKind === 'camera';
+}
 function syncProjectionMetadataForChangedIds(state, options, document, changedIds, syncOptions = {}) {
+    if (state.prefabStage) {
+        rebuildProjectionFromDocument(state, options, document, EMPTY_EDITOR_SELECTION);
+        return;
+    }
     for (const changedId of changedIds) {
         const projectedNode = options.documentAdapter.getProjectionNode(document, changedId);
         if (projectedNode) {
@@ -3326,7 +5540,7 @@ function syncProjectionMetadataForChangedIds(state, options, document, changedId
         }
     }
     const selection = state.session?.getState({ cloneDocuments: false }).selection ?? { selectedIds: [], activeId: null };
-    syncSelectionToProjection(state, selection);
+    syncSelectionToProjection(state, options, selection);
     syncEditorWorldAppearanceFromDocument(state, options, document, 'world-appearance-sync-metadata-ids');
     if (syncOptions.invalidateStaticShadowArtifact) {
         state.shadowPreview?.invalidateStaticProjectedArtifact?.();
@@ -3342,17 +5556,37 @@ function syncProjectionMetadataForChangedIds(state, options, document, changedId
     }
     invalidateEditorScene(state, 'projection-sync-metadata-ids');
 }
+function rebuildProjectionAfterShadowTopologyMetadataPatch(state, options, document, selection) {
+    rebuildProjectionFromDocument(state, options, document, selection);
+    state.shadowPreview?.invalidateStaticProjectedArtifact?.();
+    scheduleProjectionShadowPreviewRebuild(state, 'projection-shadow-topology-metadata-rebuild');
+}
 function reprojectProjectionForChangedIds(state, options, document, changedIds) {
+    if (state.prefabStage) {
+        rebuildProjectionFromDocument(state, options, document, EMPTY_EDITOR_SELECTION);
+        return;
+    }
     for (const changedId of changedIds) {
         const projectedNode = options.documentAdapter.getProjectionNode(document, changedId);
         if (projectedNode)
             state.projection?.projectNode(projectedNode);
     }
-    syncCurrentSelectionToSceneArtifacts(state);
+    applyPreviewVisibilityStateToProjection(state);
+    syncCurrentSelectionToSceneArtifacts(state, options);
     syncEditorWorldAppearanceFromDocument(state, options, document, 'world-appearance-reproject-changed-ids');
     syncEditorWorldRenderingFromDocument(state, options, document, 'world-rendering-reproject-changed-ids', true);
     invalidateEditorScene(state, 'projection-reproject-changed-ids', options);
 }
+function applyPreviewVisibilityStateToProjection(state) {
+    const projection = state.projection;
+    if (!projection?.clearPreviewVisibilityOverrides || !projection.setPreviewVisibilityOverrides)
+        return;
+    projection.clearPreviewVisibilityOverrides();
+    const overrides = state.previewVisibility.overrides;
+    if (Object.keys(overrides).length > 0) {
+        projection.setPreviewVisibilityOverrides(overrides);
+    }
+}
 function setSceneCameraPreviewEnabled(state, options, enabled) {
     if (!enabled) {
         state.sceneCameraPreviewEnabled = false;
@@ -3376,15 +5610,21 @@ function setSceneCameraPreviewEnabled(state, options, enabled) {
 }
 function setGridVisible(state, visible) {
     const nextVisible = visible === true;
-    if (state.gridVisible === nextVisible)
+    if (!setGridVisibleForEditorContext(state, nextVisible, 'grid-visible-change'))
         return false;
-    state.gridVisible = nextVisible;
-    state.grid?.setVisible(nextVisible);
     state.status = nextVisible ? 'Grid visible' : 'Grid hidden';
     state.statusTone = 'default';
     state.statusToneStatus = state.status;
     state.statusDetails = '';
-    requestEditorSceneFrame(state, 'grid-visible-change');
+    return true;
+}
+function setGridVisibleForEditorContext(state, visible, reason) {
+    const nextVisible = visible === true;
+    if (state.gridVisible === nextVisible)
+        return false;
+    state.gridVisible = nextVisible;
+    state.grid?.setVisible(nextVisible);
+    requestEditorSceneFrame(state, reason);
     return true;
 }
 function syncSceneCameraPreview(state, options) {
@@ -3414,16 +5654,16 @@ function syncViewportCameraState(state) {
         projectionMode: cameraState.projectionMode,
     };
 }
-function syncViewportSpatialOverlay(state) {
+function syncViewportSpatialOverlay(state, options) {
     const settings = state.viewportTools.overlay;
     if (!settings.bounds && !settings.dimensions && !settings.edgeLengths && !settings.anchor) {
         state.viewportSpatialOverlay = createEmptyEditorViewportSpatialOverlayState();
         return;
     }
     const overlay = state.sceneViewSpatialOverlay;
-    const selection = state.session?.getState().selection;
-    const activeId = selection?.activeId ?? null;
-    if (state.mode !== 'editor' || !overlay || !activeId || selection?.selectedIds.length !== 1) {
+    const selection = getCurrentPreviewSelection(state, options);
+    const activeId = selection.activeId;
+    if (state.mode !== 'editor' || !overlay || !activeId || selection.selectedIds.length !== 1) {
         state.viewportSpatialOverlay = createEmptyEditorViewportSpatialOverlayState();
         return;
     }
@@ -3523,25 +5763,46 @@ function radiansToInspectorDegrees(value) {
 function createUiState(state, options) {
     const sessionState = state.session?.getState({ cloneDocuments: false });
     const document = sessionState?.workingDocument ?? null;
-    const selectedIds = sessionState?.selection.selectedIds ?? [];
-    const activeId = sessionState?.selection.activeId ?? null;
-    const largeSelection = isLargeSelection(selectedIds);
+    const documentSelectedIds = sessionState?.selection.selectedIds ?? [];
+    const documentActiveId = sessionState?.selection.activeId ?? null;
+    const scopedPreviewSelection = getScopedPreviewSelectionForUiState(state, options, {
+        selectedIds: documentSelectedIds,
+        activeId: documentActiveId,
+    });
+    const selectedIds = scopedPreviewSelection.selectedIds;
+    const activeId = scopedPreviewSelection.activeId;
+    const largeSelection = isLargeSelection(documentSelectedIds);
+    const transformSelectionIsLarge = isLargeSelection(selectedIds);
+    const markerGraph = document ? options.documentAdapter.getMarkerGraph?.(document) ?? null : null;
+    const markerTypes = document ? options.documentAdapter.getMarkerTypeCatalog?.(document) ?? [] : [];
+    const relationTypes = document ? options.documentAdapter.getRelationTypeCatalog?.(document) ?? [] : [];
+    const documentHierarchy = document ? options.documentAdapter.getHierarchyItems(document) : [];
+    const activeMarkerId = activeId ? readSpatialMarkerIdFromHierarchySelection(markerGraph, activeId, documentHierarchy) : null;
+    const markerRelationVisibility = createMarkerRelationVisibilityOptions(state);
+    const markerInspectorObject = document && activeId
+        ? createMarkerInspectorObjectBase(options, document, activeId, markerGraph, documentHierarchy, markerTypes, state.activeMarkerRelationId, state.markerRelationPick, markerRelationVisibility)
+        : null;
     const serializedObject = document && activeId && selectedIds.length === 1
-        ? options.documentAdapter.getSerializedObject(document, activeId)
+        ? markerInspectorObject ? null : options.documentAdapter.getSerializedObject(document, activeId)
         : null;
-    const serializedMultiObject = document && selectedIds.length > 1 && !largeSelection
-        ? options.documentAdapter.getSerializedMultiObject?.(document, selectedIds, activeId) ?? null
+    const serializedMultiObject = document && documentSelectedIds.length > 1 && !largeSelection
+        ? options.documentAdapter.getSerializedMultiObject?.(document, documentSelectedIds, documentActiveId) ?? null
         : null;
-    const inspectorObjectBase = document && activeId && selectedIds.length === 1
-        ? options.documentAdapter.getInspectorObject?.(document, activeId) ?? (serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : null)
+    const inspectorObjectBase = document && activeId && (selectedIds.length === 1 || markerInspectorObject)
+        ? markerInspectorObject
+            ?? options.documentAdapter.getInspectorObject?.(document, activeId)
+            ?? (serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : null)
         : null;
-    const inspectorMultiObjectBase = document && selectedIds.length > 1
-        ? createInspectorMultiObjectBase(state, options, document, selectedIds, activeId, serializedMultiObject, {
+    const inspectorMultiObjectBase = document && documentSelectedIds.length > 1
+        ? createInspectorMultiObjectBase(state, options, document, documentSelectedIds, documentActiveId, serializedMultiObject, {
             largeSelection,
         })
         : null;
-    const inspectorObject = document && inspectorObjectBase
-        ? withRuntimeInspectorSections(state, options, document, inspectorObjectBase)
+    const markerRelationInspectorObjectBase = document && inspectorObjectBase
+        ? withMarkerGraphRelationInspectorSection(options, document, inspectorObjectBase, markerGraph, documentHierarchy, markerTypes, relationTypes, state.activeMarkerRelationId, state.markerRelationPick, markerRelationVisibility)
+        : inspectorObjectBase;
+    const inspectorObject = document && markerRelationInspectorObjectBase
+        ? withRuntimeInspectorSections(state, options, document, markerRelationInspectorObjectBase)
         : inspectorObjectBase;
     const inspectorMultiObject = document && inspectorMultiObjectBase
         ? withRuntimeInspectorSections(state, options, document, inspectorMultiObjectBase)
@@ -3551,8 +5812,10 @@ function createUiState(state, options) {
     const documentAssetItems = document
         ? options.documentAdapter.getBrowserAssetItems?.(document) ?? []
         : [];
-    const hierarchy = document ? options.documentAdapter.getHierarchyItems(document) : [];
-    state.performanceObjectCount = document ? countLocalEditorAuthoredObjects(hierarchy) : null;
+    const hierarchy = document
+        ? createMarkerGraphHierarchyItems(documentHierarchy, markerGraph, createMarkerGraphHierarchyVisibility(state))
+        : [];
+    state.performanceObjectCount = document ? countLocalEditorAuthoredObjects(documentHierarchy) : null;
     state.performanceStats = createLocalEditorPerformanceStats({
         frameStats: state.sceneFrameStats,
         runtimeStats: state.performanceMonitor?.readSnapshot() ?? null,
@@ -3565,6 +5828,7 @@ function createUiState(state, options) {
     return {
         mode: state.mode,
         busy: state.busy,
+        agentBridge: state.agentBridgeStatus,
         status: state.status,
         statusTone: state.statusToneStatus === state.status ? state.statusTone : 'default',
         statusDetails: state.statusToneStatus === state.status ? state.statusDetails : '',
@@ -3591,6 +5855,9 @@ function createUiState(state, options) {
                 renderingAction: state.renderingAction,
             }) ?? null
             : null,
+        markerPanel: document
+            ? createMarkerPanelState(markerGraph, markerTypes, relationTypes, documentHierarchy, activeMarkerId, state.activeMarkerRelationId, state.markerRelationPick, markerRelationVisibility)
+            : null,
         boxSelection: state.boxSelection,
         coordinateAxes: options.world?.coordinateAxes === false
             ? null
@@ -3603,11 +5870,11 @@ function createUiState(state, options) {
             draggingNodeId: state.gizmo?.getState().draggingNodeId ?? null,
         },
         transformOperations: {
-            settings: cloneTransformOperationSettings(state.transformOperationSettings),
+            settings: cloneTransformOperationSettings(getScopedTransformOperationSettings(state)),
             selectedCount: selectedIds.length,
             activeId,
-            canAlign: !largeSelection && selectedIds.length >= 2 && activeId != null,
-            canDistribute: !largeSelection && selectedIds.length >= 3,
+            canAlign: !transformSelectionIsLarge && selectedIds.length >= 2 && activeId != null && !state.prefabStage,
+            canDistribute: !transformSelectionIsLarge && selectedIds.length >= 3 && !state.prefabStage,
         },
         viewportTools: cloneEditorViewportToolState(state.viewportTools),
         viewportMeasurement: cloneViewportMeasurement(state.viewportMeasurement),
@@ -3620,6 +5887,7 @@ function createUiState(state, options) {
             enabled: state.sceneCameraPreviewEnabled,
             available: hasSceneCameraPreviewRig(state, options),
         },
+        prefabStage: createBrowserPrefabStageState(state, options, document),
         grid: {
             visible: state.gridVisible,
             available: !!state.grid,
@@ -3635,18 +5903,196 @@ function createUiState(state, options) {
             : null,
     };
 }
+function createBrowserPrefabStageState(state, options, document) {
+    const stage = state.prefabStage;
+    if (!stage || !document)
+        return null;
+    const descriptor = resolvePrefabStageDescriptorForDocument(state, options, document) ?? stage.descriptor;
+    const context = createPrefabStageContext(state, descriptor);
+    const structureItems = options.documentAdapter.getPrefabStageStructure?.(document, descriptor, context)
+        ?? createFallbackPrefabStageStructure(descriptor);
+    const inspectorObject = options.documentAdapter.getPrefabStageInspectorObject?.(document, descriptor, stage.selectedItemId, context) ?? null;
+    return {
+        assetId: descriptor.assetId,
+        browserAssetId: descriptor.browserAssetId,
+        label: descriptor.label,
+        sourceAssetId: descriptor.sourceAssetId,
+        sourceAssetGuid: descriptor.sourceAssetGuid,
+        readonly: descriptor.readonly,
+        selectedItemId: stage.selectedItemId,
+        structureItems,
+        inspectorObject,
+        importStructureReady: context.importStructureReady,
+        importStats: createPrefabStageImportStats(context),
+        previewNodeId: descriptor.previewNodeId,
+        comparisonPreviews: createPrefabStageComparisonPreviews(state, descriptor),
+    };
+}
+function summarizeAgentBridgePrefabStage(state, options) {
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    const stage = createBrowserPrefabStageState(state, options, document);
+    if (!stage)
+        return null;
+    return createAgentBridgePrefabStageState(stage);
+}
+function summarizeAgentBridgePrefabStageDetails(state, options) {
+    const document = state.session?.getState({ cloneDocuments: false }).workingDocument ?? null;
+    const stage = createBrowserPrefabStageState(state, options, document);
+    if (!stage)
+        return null;
+    return {
+        stage: createAgentBridgePrefabStageState(stage),
+        structureItems: stage.structureItems,
+        inspectorObject: stage.inspectorObject ?? null,
+    };
+}
+function createAgentBridgePrefabStageState(stage) {
+    return {
+        assetId: stage.assetId,
+        ...(stage.browserAssetId ? { browserAssetId: stage.browserAssetId } : {}),
+        label: stage.label,
+        ...(stage.sourceAssetId ? { sourceAssetId: stage.sourceAssetId } : {}),
+        ...(stage.sourceAssetGuid ? { sourceAssetGuid: stage.sourceAssetGuid } : {}),
+        ...(stage.previewNodeId ? { previewNodeId: stage.previewNodeId } : {}),
+        selectedItemId: stage.selectedItemId ?? null,
+        ...(stage.readonly != null ? { readonly: stage.readonly } : {}),
+    };
+}
+function createAgentBridgePrefabSummaryFromStage(stage) {
+    return {
+        assetId: stage.assetId,
+        ...(stage.browserAssetId ? { browserAssetId: stage.browserAssetId } : {}),
+        displayName: stage.label,
+        ...(stage.sourceAssetId ? { sourceAssetId: stage.sourceAssetId } : {}),
+        ...(stage.sourceAssetGuid ? { sourceAssetGuid: stage.sourceAssetGuid } : {}),
+        ...(stage.readonly != null ? { readonly: stage.readonly } : {}),
+        status: 'ready',
+    };
+}
+function isSameAgentBridgePrefabStage(left, right) {
+    if (!left || !right)
+        return false;
+    return left.assetId === right.assetId
+        || (!!left.browserAssetId && left.browserAssetId === right.browserAssetId);
+}
+function createPrefabStageContext(state, descriptor) {
+    const previewNodeId = descriptor.previewNodeId;
+    if (!previewNodeId) {
+        return {
+            importStructure: null,
+            importStructureReady: false,
+        };
+    }
+    const projectedNode = state.projection?.getProjectedNode(previewNodeId) ?? null;
+    return {
+        previewNodeId,
+        importStructure: state.projection?.readNodeImportStructure(previewNodeId) ?? null,
+        importStructureReady: !!projectedNode && !projectedNode.loadPromise,
+    };
+}
+function createPrefabStageImportStats(context) {
+    const snapshot = context.importStructure;
+    if (!context.importStructureReady) {
+        return createEmptyPrefabStageImportStats('loading', snapshot);
+    }
+    if (!snapshot) {
+        return createEmptyPrefabStageImportStats('missing', null);
+    }
+    const nodes = snapshot.nodes ?? [];
+    return {
+        status: 'ready',
+        projectionNodeId: snapshot.projectionNodeId,
+        ...(snapshot.assetId ? { assetId: snapshot.assetId } : {}),
+        ...(snapshot.sourceId ? { sourceId: snapshot.sourceId } : {}),
+        nodeCount: nodes.length,
+        transformCount: nodes.filter(node => node.kind === 'root' || node.kind === 'transform').length,
+        meshCount: nodes.filter(node => node.kind === 'mesh').length,
+        materialCount: snapshot.materials?.length ?? 0,
+        textureCount: snapshot.textures?.length ?? 0,
+        animationCount: snapshot.animations?.length ?? 0,
+    };
+}
+function createEmptyPrefabStageImportStats(status, snapshot) {
+    return {
+        status,
+        ...(snapshot?.projectionNodeId ? { projectionNodeId: snapshot.projectionNodeId } : {}),
+        ...(snapshot?.assetId ? { assetId: snapshot.assetId } : {}),
+        ...(snapshot?.sourceId ? { sourceId: snapshot.sourceId } : {}),
+        nodeCount: 0,
+        transformCount: 0,
+        meshCount: 0,
+        materialCount: 0,
+        textureCount: 0,
+        animationCount: 0,
+    };
+}
+function createPrefabStageComparisonPreviews(state, descriptor) {
+    return PREFAB_STAGE_COMPARISON_PREVIEW_DEFINITIONS.map((definition) => {
+        const projectionNodeId = createPrefabStageComparisonProjectionNodeId(descriptor, definition.nodeIdSuffix);
+        const projectedNode = state.projection?.getProjectedNode(projectionNodeId) ?? null;
+        const status = !descriptor.sourceAssetId || !projectedNode
+            ? 'unavailable'
+            : projectedNode.loadPromise
+                ? 'loading'
+                : 'ready';
+        return {
+            id: definition.id,
+            label: definition.label,
+            mode: definition.mode,
+            projectionNodeId,
+            status,
+        };
+    });
+}
+function createPrefabStageComparisonProjectionNodeId(descriptor, suffix) {
+    const previewNodeId = descriptor.previewNodeId ?? `prefab-stage:${descriptor.assetId}`;
+    return `${previewNodeId}:${suffix}`;
+}
+function createFallbackPrefabStageStructure(descriptor) {
+    return [{
+            id: 'prefab-root',
+            label: descriptor.label,
+            kind: 'root',
+            icon: 'prefab',
+            meta: descriptor.assetId,
+            readonly: descriptor.readonly,
+            children: [{
+                    id: 'prefab-source',
+                    label: 'Source Model',
+                    kind: 'source',
+                    icon: 'asset',
+                    sourceAssetId: descriptor.sourceAssetId,
+                    meta: descriptor.sourceAssetId ?? 'Missing source asset',
+                    readonly: true,
+                }],
+        }];
+}
+function getScopedPreviewSelectionForUiState(state, options, fallbackSelection) {
+    return state.prefabStage
+        ? getCurrentPrefabStageProjectionSelection(state, options)
+        : fallbackSelection;
+}
+function getCurrentPreviewSelection(state, options) {
+    return getScopedPreviewSelectionForUiState(state, options, state.session?.getState({ cloneDocuments: false }).selection ?? EMPTY_EDITOR_SELECTION);
+}
 function createUiPreviewState(state, options) {
     const sessionState = state.session?.getState({ cloneDocuments: false });
     const selection = sessionState?.selection;
     const document = sessionState?.workingDocument ?? null;
-    const selectedIds = selection?.selectedIds ?? [];
-    const activeId = selection?.activeId ?? null;
-    const largeSelection = isLargeSelection(selectedIds);
-    const shouldPreviewInspector = !!state.activeTransformPreview && document && activeId && selectedIds.length === 1;
+    const documentSelectedIds = selection?.selectedIds ?? [];
+    const documentActiveId = selection?.activeId ?? null;
+    const scopedPreviewSelection = getScopedPreviewSelectionForUiState(state, options, {
+        selectedIds: documentSelectedIds,
+        activeId: documentActiveId,
+    });
+    const selectedIds = scopedPreviewSelection.selectedIds;
+    const activeId = scopedPreviewSelection.activeId;
+    const transformSelectionIsLarge = isLargeSelection(selectedIds);
+    const shouldPreviewInspector = !!state.activeTransformPreview && document && documentActiveId && documentSelectedIds.length === 1;
     const inspectorObjectBase = shouldPreviewInspector
-        ? options.documentAdapter.getInspectorObject?.(document, activeId)
+        ? options.documentAdapter.getInspectorObject?.(document, documentActiveId)
             ?? (() => {
-                const serializedObject = options.documentAdapter.getSerializedObject(document, activeId);
+                const serializedObject = options.documentAdapter.getSerializedObject(document, documentActiveId);
                 return serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : null;
             })()
         : null;
@@ -3670,11 +6116,11 @@ function createUiPreviewState(state, options) {
             draggingNodeId: state.gizmo?.getState().draggingNodeId ?? null,
         },
         transformOperations: {
-            settings: cloneTransformOperationSettings(state.transformOperationSettings),
+            settings: cloneTransformOperationSettings(getScopedTransformOperationSettings(state)),
             selectedCount: selectedIds.length,
             activeId,
-            canAlign: !largeSelection && selectedIds.length >= 2 && activeId != null,
-            canDistribute: !largeSelection && selectedIds.length >= 3,
+            canAlign: !transformSelectionIsLarge && selectedIds.length >= 2 && activeId != null && !state.prefabStage,
+            canDistribute: !transformSelectionIsLarge && selectedIds.length >= 3 && !state.prefabStage,
         },
         viewportTools: cloneEditorViewportToolState(state.viewportTools),
         viewportMeasurement: cloneViewportMeasurement(state.viewportMeasurement),
@@ -3891,12 +6337,108 @@ function createAggregatedInspectorMultiObjectBase(_state, options, document, sel
     return aggregatedInspector;
 }
 function createSingleInspectorObjectBase(options, document, targetId) {
+    const markerInspector = createMarkerInspectorObjectBase(options, document, targetId);
+    if (markerInspector)
+        return markerInspector;
     const inspectorObject = options.documentAdapter.getInspectorObject?.(document, targetId) ?? null;
     if (inspectorObject)
-        return inspectorObject;
+        return withMarkerGraphRelationInspectorSection(options, document, inspectorObject);
     const serializedObject = options.documentAdapter.getSerializedObject(document, targetId);
     return serializedObject ? serializedObjectToInspectorObject(serializedObject, document) : 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)
+        return inspectorObject;
+    if (inspectorObject.sections.some(section => section.id === 'markerRelations'))
+        return inspectorObject;
+    if (inspectorObject.sections.some(section => section.properties.some(property => property.path === 'marker.relations.editor'))) {
+        return inspectorObject;
+    }
+    const targetId = inspectorObject.activeId ?? inspectorObject.targetIds[0] ?? null;
+    const markerId = readSpatialMarkerIdFromHierarchySelection(graph, targetId, hierarchy);
+    if (!targetId || !markerId)
+        return inspectorObject;
+    const markerInspector = createMarkerGraphInspectorObject({
+        document,
+        graph,
+        markerId: targetId,
+        hierarchy,
+        markerTypes,
+        relationTypes,
+        activeRelationId,
+        relationPick,
+        relationVisibility,
+    });
+    const relationSection = markerInspector?.sections.find(section => section.id === 'markerRelations') ?? null;
+    if (!relationSection)
+        return inspectorObject;
+    const capabilities = new Set(inspectorObject.selection.capabilities ?? []);
+    capabilities.add('markerGraph');
+    const markerSection = inspectorObject.sections.find(section => section.id === 'marker') ?? null;
+    const sections = markerSection
+        ? inspectorObject.sections.map(section => section.id === 'marker'
+            ? {
+                ...section,
+                properties: [
+                    ...section.properties,
+                    ...createIntegratedMarkerRelationProperties(section.properties, relationSection.properties),
+                ],
+            }
+            : section)
+        : mergeInspectorSections(inspectorObject.sections, [relationSection], { propertyConflict: 'ignore' });
+    return {
+        ...inspectorObject,
+        selection: {
+            ...inspectorObject.selection,
+            targetKind: inspectorObject.selection.targetKind ?? 'marker',
+            capabilities: [...capabilities],
+        },
+        sections,
+    };
+}
+function createIntegratedMarkerRelationProperties(markerProperties, relationProperties) {
+    const existingPaths = new Set(markerProperties.map(property => property.path));
+    const baseOrder = markerProperties.reduce((maxOrder, property, index) => (Math.max(maxOrder, property.order ?? index)), -1);
+    return relationProperties
+        .filter(property => !existingPaths.has(property.path))
+        .map((property, index) => ({
+        ...property,
+        label: formatIntegratedMarkerRelationPropertyLabel(property),
+        order: baseOrder + index + 1,
+    }));
+}
+function formatIntegratedMarkerRelationPropertyLabel(property) {
+    switch (property.path) {
+        case 'marker.relations.count': return '关系数量';
+        case 'marker.relations.status': return '关系状态';
+        case 'marker.relations.editor': return '关系';
+        default: return property.label;
+    }
+}
+function createMarkerInspectorObjectBase(options, document, targetId, graph = options.documentAdapter.getMarkerGraph?.(document) ?? null, hierarchy = options.documentAdapter.getHierarchyItems(document), markerTypes = options.documentAdapter.getMarkerTypeCatalog?.(document) ?? [], activeRelationId = null, relationPick = null, relationVisibility = {}) {
+    const virtualMarkerId = readMarkerGraphHierarchyMarkerIdForGraph(graph, targetId, hierarchy);
+    const isVirtualRoot = isMarkerGraphHierarchyRootRowId(graph, targetId, hierarchy);
+    if (!virtualMarkerId && !isVirtualRoot)
+        return null;
+    return createMarkerGraphInspectorObject({
+        document,
+        graph,
+        markerId: targetId,
+        hierarchy,
+        markerTypes,
+        relationTypes: options.documentAdapter.getRelationTypeCatalog?.(document) ?? [],
+        activeRelationId,
+        relationPick,
+        relationVisibility,
+    }) ?? createMarkerGraphRootInspectorObject({
+        document,
+        graph,
+        rootId: targetId,
+        hierarchy,
+        markerTypes,
+        relationTypes: options.documentAdapter.getRelationTypeCatalog?.(document) ?? [],
+    });
+}
 function applyMultiInspectorBatchCapabilityGate(options, document, inspectorObject) {
     return options.documentAdapter.createSerializedMultiPropertyPatch
         ? applyAggregatedBatchInspectorCapabilityGate(options, document, inspectorObject)
@@ -4225,6 +6767,12 @@ function isDocumentNodeLocked(state, options, id) {
     return options.documentAdapter.isLocked?.(document, id) ?? false;
 }
 function isNodeSelectableInDocument(options, document, id) {
+    const graph = options.documentAdapter.getMarkerGraph?.(document) ?? null;
+    const hierarchy = graph ? options.documentAdapter.getHierarchyItems(document) : [];
+    if (isMarkerGraphHierarchyRootRowId(graph, id, hierarchy))
+        return true;
+    if (isMarkerGraphHierarchyId(graph, id, hierarchy))
+        return true;
     if (options.documentAdapter.isLocked?.(document, id))
         return false;
     return options.documentAdapter.isSelectable?.(document, id) ?? true;
@@ -4246,6 +6794,36 @@ function findAssetByResolvedId(state, options, assetId) {
     }
     return selected?.asset ?? null;
 }
+function findBrowserAssetItemByResolvedId(state, options, document, assetId) {
+    let selected = null;
+    for (const asset of state.assets) {
+        const item = toBrowserAssetItem(options, asset);
+        if (item.id !== assetId && item.assetId !== assetId && resolveAssetId(options, asset) !== assetId)
+            continue;
+        if (!selected || shouldReplaceBrowserAssetItem(selected, item))
+            selected = item;
+    }
+    const documentItem = document ? findDocumentBrowserAssetItemByResolvedId(options, document, assetId) : null;
+    if (documentItem && (!selected || shouldReplaceBrowserAssetItem(selected, documentItem)))
+        selected = documentItem;
+    return selected;
+}
+function findAssetOrDocumentBrowserItemByResolvedId(state, options, document, assetId) {
+    return findAssetByResolvedId(state, options, assetId)
+        ?? (document ? findDocumentBrowserAssetItemByResolvedId(options, document, assetId) : null);
+}
+function findDocumentBrowserAssetItemByResolvedId(options, document, assetId) {
+    let selected = null;
+    for (const item of options.documentAdapter.getBrowserAssetItems?.(document) ?? []) {
+        if (item.id !== assetId && item.assetId !== assetId)
+            continue;
+        if (item.placeable === false || item.disabled === true)
+            continue;
+        if (!selected || shouldReplaceBrowserAssetItem(selected, item))
+            selected = item;
+    }
+    return selected;
+}
 function resolveBrowserAssetItemId(state, options, assetId) {
     let selected = null;
     for (const asset of state.assets) {
@@ -4271,6 +6849,7 @@ function toBrowserAssetItem(options, asset) {
             placeable: asset.placeable,
             preview: asset.preview,
             material: asset.material,
+            prefab: asset.prefab,
             meta: asset.meta,
             disabled: asset.disabled ?? asset.placeable === false,
         };