@fps-games/editor 0.1.6-beta.1 → 0.1.7-beta.1

package/dist/local-editor-harness.js

@@ -1,4 +1,5 @@
-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, createBabylonEditorMarkerOverlayController, createBabylonMarkerOverlayProjectionAdapter, createBabylonEditorWorld, createBabylonPrefabComparisonPreviewController, createBabylonProjectionSelectionController, createBabylonSceneCameraPreviewController, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonSceneViewMeasurementController, createBabylonSceneViewSpatialOverlayController, createBabylonEditorShadowPreviewController, createBabylonTransformGizmoController, createBabylonEditorPerformanceMonitor, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
@@ -7,6 +8,9 @@ import { createPlayableBabylonOutlineInspectorSection, createPlayableBabylonOutl
 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;
@@ -74,6 +78,10 @@ export function createLocalEditorHarness(options) {
         grid: null,
         gridVisible: true,
         projection: null,
+        previewVisibility: {
+            overrides: {},
+            isolatedObjectIds: [],
+        },
         markerOverlay: null,
         markerGraphVisibility: createDefaultMarkerGraphVisibilityState(),
         activeMarkerRelationId: null,
@@ -123,6 +131,10 @@ export function createLocalEditorHarness(options) {
         statusDetails: '',
         renderingAction: null,
         summary: '',
+        agentBridge: createEditorAgentBridge(),
+        unregisterAgentBridgeCapabilities: null,
+        agentBridgeTransport: null,
+        agentBridgeStatus: createDisabledLocalEditorAgentBridgeTransportStatus(),
     };
     let harness;
     const ui = createLocalEditorBrowserUi({
@@ -172,7 +184,7 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onSelectPrefabStageItem: (itemId) => {
-                if (selectPrefabStageItem(state, itemId))
+                if (selectPrefabStageItemWithPreviewSync(state, options, itemId))
                     harness.render();
             },
             onSelectHierarchyItem: (input) => {
@@ -347,7 +359,7 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onViewportViewPresetChange: (preset) => {
-                if (setViewportViewPreset(state, preset))
+                if (setViewportViewPreset(state, options, preset))
                     harness.render();
             },
             onViewportProjectionModeChange: (mode) => {
@@ -395,7 +407,7 @@ export function createLocalEditorHarness(options) {
                 },
             },
             onFocusSelection: () => {
-                if (focusSelectedProjection(state))
+                if (focusSelectedProjection(state, options))
                     harness.render();
             },
             onCancelEditorIntent: () => {
@@ -428,7 +440,7 @@ export function createLocalEditorHarness(options) {
         render() {
             syncViewportCameraState(state);
             syncViewportMeasurementState(state);
-            syncViewportSpatialOverlay(state);
+            syncViewportSpatialOverlay(state, options);
             ui.update(createUiState(state, options));
             syncPrefabComparisonPreviewSurfaces(state, ui);
             syncSceneCameraPreview(state, options);
@@ -445,6 +457,9 @@ export function createLocalEditorHarness(options) {
         getHostServices() {
             return options.hostServices ?? null;
         },
+        getAgentBridge() {
+            return state.agentBridge;
+        },
         getWorkingDocument() {
             return state.session?.getState().workingDocument ?? null;
         },
@@ -598,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;
 }
@@ -632,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';
 }
@@ -667,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';
@@ -698,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';
@@ -707,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;
@@ -887,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)
@@ -988,7 +1110,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         logger: console,
         onProjectionReady(event) {
             if (state.prefabStage) {
-                syncCurrentSelectionToSceneArtifacts(state, options, `prefab-stage-projection-${event.nodeId}-ready-selection`);
+                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`);
@@ -1001,7 +1123,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
         },
         onProjectionBatchSettled(event) {
             if (state.prefabStage) {
-                syncCurrentSelectionToSceneArtifacts(state, options, `prefab-stage-projection-batch-${event.batchId}-settled-selection`);
+                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();
@@ -1080,26 +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: markerAwareProjection,
         getTool: () => state.transformTool,
-        getSelection: () => state.prefabStage ? EMPTY_EDITOR_SELECTION : state.session?.getSelection() ?? EMPTY_EDITOR_SELECTION,
-        isSelectable: (nodeId) => !state.prefabStage && isDocumentNodeSelectable(state, options, nodeId),
-        isLocked: (nodeId) => state.prefabStage ? true : 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 (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();
         },
@@ -1285,6 +1429,7 @@ async function createEditorWorld(state, options, renderUi, renderPreviewUi, upda
     state.resizeHandler = resize;
     if (document) {
         projection.projectNodes(resolveCurrentEditorProjectionNodes(state, options, document));
+        applyPreviewVisibilityStateToProjection(state);
         scheduleProjectionShadowPreviewRebuild(state, 'editor-world-initial-projection-shadow');
     }
     syncCurrentSelectionToSceneArtifacts(state, options, 'editor-world-initial-selection');
@@ -1440,7 +1585,7 @@ 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);
 }
@@ -1744,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;
@@ -2450,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;
@@ -2782,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;
@@ -3021,8 +3182,15 @@ function handleBrowserAssetAction(state, options, input) {
     return true;
 }
 function handleInspectorAction(state, options, input) {
-    if (!input.actionId.startsWith('prefab.'))
-        return false;
+    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)
@@ -3083,7 +3251,8 @@ function enterPrefabStage(state, options, input) {
     cancelActiveOperation(state);
     const previousPrefabStage = state.prefabStage;
     const asset = findAssetByResolvedId(state, options, assetId);
-    const browserItem = findBrowserAssetItemByResolvedId(state, options, document, input.browserAssetId ?? 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,
@@ -3112,6 +3281,7 @@ function enterPrefabStage(state, options, input) {
     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) {
@@ -3128,6 +3298,7 @@ function exitPrefabStage(state, options) {
     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);
@@ -3148,6 +3319,168 @@ function selectPrefabStageItem(state, 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;
@@ -3180,7 +3513,8 @@ function resolvePrefabStageDescriptorForDocument(state, options, document) {
             previewNodeId: descriptor.previewNodeId ?? stage.descriptor.previewNodeId,
         };
     }
-    const browserItem = findBrowserAssetItemByResolvedId(state, options, document, browserAssetId ?? assetId);
+    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) {
@@ -3221,12 +3555,49 @@ function patchBrowserAssetAction(state, options, input, selectionOverride) {
     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;
@@ -3359,6 +3730,7 @@ function addAssetToDocument(state, options, assetId, createOptions = {}) {
         document: beforeDocument,
         asset,
         assetId,
+        name: createOptions.name,
         placement: createOptions.placement,
     });
     const result = session.dispatch({
@@ -3374,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],
@@ -3443,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`,
@@ -3474,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,
@@ -3521,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.changedIds ?? [patch.changedId ?? payload.targetId], {
-            invalidateStaticShadowArtifact: payload.path === 'shadowMode',
+            invalidateStaticShadowArtifact: isSerializedShadowMetadataPath(payload.path),
         });
     }
     else if (isSerializedTransformPath(payload.path))
@@ -3952,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();
@@ -4011,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';
@@ -4034,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;
@@ -4043,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) {
@@ -4213,7 +4620,20 @@ 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)
@@ -4304,6 +4724,8 @@ 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)
@@ -4381,6 +4803,85 @@ function commitGizmoTransform(state, options, event) {
     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;
@@ -4552,6 +5053,25 @@ function cancelEditorIntent(state, options) {
         || 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' });
@@ -4559,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';
@@ -4587,6 +5115,66 @@ 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)
@@ -4827,11 +5415,12 @@ 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, options, sanitized ?? input.selection);
     syncEditorWorldAppearanceFromDocument(state, options, input.document, `world-appearance-${input.reason}`);
@@ -4860,8 +5449,14 @@ function resolveCurrentEditorProjectionNodes(state, options, document) {
 function rebuildProjectionFromDocument(state, options, document, selection) {
     const nodes = resolveCurrentEditorProjectionNodes(state, options, document);
     state.projection?.rebuild(nodes);
-    const sanitized = state.prefabStage ? EMPTY_EDITOR_SELECTION : sanitizeSelection(state, options, document, selection);
-    syncSelectionToProjection(state, options, sanitized ?? selection);
+    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) {
@@ -4881,7 +5476,7 @@ function syncProjectionForDispatchResult(state, options, result, changedId) {
     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, options, result.selection ?? { selectedIds: [], activeId: null });
@@ -4907,7 +5502,7 @@ function syncProjectionForChangedIds(state, options, document, changedIds) {
     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, options, selection);
@@ -4915,6 +5510,24 @@ function syncProjectionForChangedIds(state, options, document, changedIds) {
     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);
@@ -4943,6 +5556,11 @@ 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);
@@ -4953,11 +5571,22 @@ function reprojectProjectionForChangedIds(state, options, document, changedIds)
         if (projectedNode)
             state.projection?.projectNode(projectedNode);
     }
+    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;
@@ -5025,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;
     }
@@ -5134,31 +5763,38 @@ 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 && selectedIds.length === 1
+    const markerInspectorObject = document && activeId
         ? createMarkerInspectorObjectBase(options, document, activeId, markerGraph, documentHierarchy, markerTypes, state.activeMarkerRelationId, state.markerRelationPick, markerRelationVisibility)
         : null;
     const serializedObject = document && activeId && selectedIds.length === 1
         ? markerInspectorObject ? null : options.documentAdapter.getSerializedObject(document, activeId)
         : null;
-    const serializedMultiObject = document && 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
+    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;
@@ -5192,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 : '',
@@ -5233,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),
@@ -5291,6 +5928,53 @@ function createBrowserPrefabStageState(state, options, document) {
         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) {
@@ -5383,18 +6067,32 @@ function createFallbackPrefabStageStructure(descriptor) {
                 }],
         }];
 }
+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;
@@ -5418,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),