@fps-games/editor 0.1.1-beta.8 → 0.1.2-beta.1

package/dist/local-editor-harness.js

@@ -1,6 +1,8 @@
 import { createEditorSession, createInspectorRegistry, DEFAULT_EDITOR_TRANSFORM_OPERATION_SETTINGS, DEFAULT_EDITOR_VIEWPORT_TOOL_STATE, createEmptyEditorViewportSpatialOverlayState, cloneEditorViewportToolState, cloneEditorViewportSpatialOverlayState, createInspectorEditPayload, computeEditorTransformActionTargets, mergeInspectorSections, normalizeEditorTransformConstraint, resolveEditorSelectionCommand, serializedMultiObjectToInspectorObject, serializedObjectToInspectorObject, validateSceneGraphDelete, validateSceneGraphDrop, validateSceneGraphGroupSelection, validateSceneGraphMove, validateSceneGraphRename, } from '@fps-games/editor-core';
 import { createLocalEditorBrowserUi, } from '@fps-games/editor-browser';
-import { createBabylonEditorProjection, createBabylonEditorWorld, createBabylonProjectionSelectionController, createBabylonSceneCameraPreviewController, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonSceneViewMeasurementController, createBabylonSceneViewSpatialOverlayController, createBabylonTransformGizmoController, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
+import { createBabylonEditorProjection, createBabylonEditorWorld, createBabylonProjectionSelectionController, createBabylonMainCameraPreviewController, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonSceneViewMeasurementController, createBabylonSceneViewSpatialOverlayController, createBabylonTransformGizmoController, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
+import { createLocalEditorSceneRenderScheduler, } from './local-editor-scene-render-scheduler';
+import { createLocalEditorViewportRenderCoordinator, } from './local-editor-viewport-render-coordinator';
 export function createLocalEditorHarness(options) {
     const root = options.root ?? document.body;
     const state = {
@@ -17,8 +19,8 @@ export function createLocalEditorHarness(options) {
         gridVisible: true,
         projection: null,
         gizmo: null,
-        sceneCameraPreview: null,
-        sceneCameraPreviewEnabled: false,
+        mainCameraPreview: null,
+        mainCameraPreviewEnabled: false,
         sceneViewInput: null,
         sceneViewCamera: null,
         sceneViewMeasurement: null,
@@ -34,6 +36,9 @@ export function createLocalEditorHarness(options) {
         viewportSpatialOverlay: createEmptyEditorViewportSpatialOverlayState(),
         duplicateDrag: null,
         armedPlacement: null,
+        sceneRenderScheduler: null,
+        viewportRenderCoordinator: null,
+        sceneFrameStats: null,
         resizeHandler: null,
         status: 'Game running',
         statusTone: 'default',
@@ -47,6 +52,9 @@ export function createLocalEditorHarness(options) {
         theme: options.theme,
         localTestActions: options.localTestActions,
         inspector: options.inspector,
+        hierarchy: {
+            contextActions: createBrowserHierarchyContextActions(state, options),
+        },
         callbacks: {
             onEnterEditor: () => {
                 void runExclusive(state, harness.render, () => harness.enterEditor());
@@ -138,16 +146,19 @@ export function createLocalEditorHarness(options) {
                 state.transformConstraint = normalizeTransformConstraint(tool, state.transformConstraint);
                 state.gizmo?.setTool(tool);
                 state.gizmo?.setConstraint(state.transformConstraint);
+                requestEditorSceneFrame(state, 'transform-tool-change');
                 harness.render();
             },
             onTransformSpaceChange: (space) => {
                 state.transformSpace = space;
                 state.gizmo?.setSpace(space);
+                requestEditorSceneFrame(state, 'transform-space-change');
                 harness.render();
             },
             onTransformConstraintChange: (constraint) => {
                 state.transformConstraint = normalizeTransformConstraint(state.transformTool, constraint);
                 state.gizmo?.setConstraint(state.transformConstraint);
+                requestEditorSceneFrame(state, 'transform-constraint-change');
                 harness.render();
             },
             onTransformSnapEnabledChange: (enabled) => {
@@ -159,6 +170,7 @@ export function createLocalEditorHarness(options) {
                 });
                 state.gizmo?.setOperationSettings(state.transformOperationSettings);
                 state.status = enabled ? 'Transform snap enabled' : 'Transform snap disabled';
+                requestEditorSceneFrame(state, 'transform-operation-settings-change');
                 harness.render();
             },
             onTransformSnapStepChange: (input) => {
@@ -175,6 +187,7 @@ export function createLocalEditorHarness(options) {
                 state.transformOperationSettings = updateTransformOperationSettings(state.transformOperationSettings, { snap });
                 state.gizmo?.setOperationSettings(state.transformOperationSettings);
                 state.status = `Transform snap ${input.kind} step ${value}`;
+                requestEditorSceneFrame(state, 'transform-operation-settings-change');
                 harness.render();
             },
             onPlacementModeChange: (mode) => {
@@ -185,6 +198,7 @@ export function createLocalEditorHarness(options) {
                 if (state.transformOperationSettings.placementMode === 'off')
                     clearArmedPlacement(state);
                 state.status = `Placement mode: ${state.transformOperationSettings.placementMode}`;
+                requestEditorSceneFrame(state, 'placement-mode-change');
                 harness.render();
             },
             onTransformAction: (action) => {
@@ -211,8 +225,8 @@ export function createLocalEditorHarness(options) {
                 if (clearViewportMeasurement(state))
                     harness.render();
             },
-            onSceneCameraPreviewToggle: (enabled) => {
-                if (setSceneCameraPreviewEnabled(state, options, enabled))
+            onMainCameraPreviewToggle: (enabled) => {
+                if (setMainCameraPreviewEnabled(state, options, enabled))
                     harness.render();
             },
             onGridVisibleChange: (visible) => {
@@ -229,17 +243,23 @@ export function createLocalEditorHarness(options) {
             },
             onCancelActiveOperation: () => {
                 cancelActiveOperation(state);
+                requestEditorSceneFrame(state, 'cancel-active-operation');
                 harness.render();
             },
         },
     });
+    const renderUi = () => {
+        syncViewportCameraState(state);
+        syncViewportMeasurementState(state);
+        syncViewportSpatialOverlay(state);
+        ui.update(createUiState(state, options));
+    };
     harness = {
         render() {
-            syncSceneCameraPreview(state, options);
-            syncViewportCameraState(state);
-            syncViewportMeasurementState(state);
-            syncViewportSpatialOverlay(state);
-            ui.update(createUiState(state, options));
+            renderUi();
+        },
+        notifyViewportRevealed(reason = 'viewport-revealed') {
+            state.viewportRenderCoordinator?.requestRevealFrame(reason);
         },
         setTheme(theme) {
             ui.setTheme(theme);
@@ -307,10 +327,12 @@ export function createLocalEditorHarness(options) {
                 reduceDocument: options.documentAdapter.reduceDocument,
             });
             await options.worldAdapter.disposeGameWorld();
-            await createEditorWorld(state, options, harness.render);
+            await createEditorWorld(state, options, harness.render, stats => ui.updateSceneFrameStats?.(stats));
             state.mode = 'editor';
             state.summary = loadedSource?.summary ?? summarizeDocument(options, preparedDocument, source);
             state.status = `GameWorld disposed; EditorWorld active; assets=${assets.length}`;
+            harness.render();
+            harness.notifyViewportRevealed('editor-enter');
         },
         async saveScene() {
             cancelActiveOperation(state);
@@ -485,11 +507,11 @@ function cloneViewportMeasurement(measurement) {
     };
 }
 function setViewportViewPreset(state, preset) {
-    if (state.sceneCameraPreviewEnabled) {
-        state.status = 'Viewport view unavailable during Scene Camera preview';
+    if (state.mainCameraPreviewEnabled) {
+        state.status = 'Viewport view unavailable during Main Camera preview';
         state.statusTone = 'warning';
         state.statusToneStatus = state.status;
-        state.statusDetails = 'Disable Scene Camera preview before switching editor viewport views.';
+        state.statusDetails = 'Disable Main Camera preview before switching editor viewport views.';
         return true;
     }
     const nextPreset = normalizeViewportViewPreset(preset);
@@ -508,14 +530,15 @@ function setViewportViewPreset(state, preset) {
     state.statusTone = 'default';
     state.statusToneStatus = state.status;
     state.statusDetails = '';
+    requestEditorSceneFrame(state, 'viewport-view-preset-change');
     return true;
 }
 function setViewportProjectionMode(state, mode) {
-    if (state.sceneCameraPreviewEnabled) {
-        state.status = 'Viewport projection unavailable during Scene Camera preview';
+    if (state.mainCameraPreviewEnabled) {
+        state.status = 'Viewport projection unavailable during Main Camera preview';
         state.statusTone = 'warning';
         state.statusToneStatus = state.status;
-        state.statusDetails = 'Disable Scene Camera preview before switching editor viewport projection.';
+        state.statusDetails = 'Disable Main Camera preview before switching editor viewport projection.';
         return true;
     }
     const nextMode = normalizeViewportProjectionMode(mode);
@@ -531,6 +554,7 @@ function setViewportProjectionMode(state, mode) {
     state.statusTone = 'default';
     state.statusToneStatus = state.status;
     state.statusDetails = '';
+    requestEditorSceneFrame(state, 'viewport-projection-mode-change');
     return true;
 }
 function setViewportOverlaySettings(state, settings) {
@@ -682,7 +706,7 @@ function validateTransformActionSelection(state, action) {
         ? { ok: true }
         : { ok: false, message: 'Distribute needs at least 3 selected objects' };
 }
-async function createEditorWorld(state, options, render) {
+async function createEditorWorld(state, options, renderUi, updateSceneFrameStats) {
     disposeEditorWorld(state);
     const canvas = options.worldAdapter.getCanvas();
     if (!canvas)
@@ -700,13 +724,27 @@ async function createEditorWorld(state, options, render) {
         useRightHandedSystem: options.world?.useRightHandedSystem,
         enableDefaultCameraControls: false,
     });
-    const grid = options.createGrid?.(babylon, world.scene) ?? null;
+    const sceneRenderScheduler = createLocalEditorSceneRenderScheduler(() => world.render(), {
+        onStatsChange(stats) {
+            state.sceneFrameStats = stats;
+            updateSceneFrameStats(stats);
+        },
+    });
+    const viewportRenderCoordinator = createLocalEditorViewportRenderCoordinator({
+        scheduler: sceneRenderScheduler,
+        getEngine: () => engine,
+        getScene: () => world.scene,
+    });
+    const grid = options.createGrid?.(babylon, world.scene, world.camera) ?? null;
     grid?.setVisible(state.gridVisible);
     const projection = createBabylonEditorProjection({
         babylon,
         scene: world.scene,
         importModel: options.worldAdapter.importProjectionModel,
         logger: console,
+        onProjectionReady(event) {
+            viewportRenderCoordinator.invalidateScene(`projection-${event.nodeId}-ready`);
+        },
     });
     const gizmo = createBabylonTransformGizmoController({
         babylon,
@@ -716,27 +754,33 @@ async function createEditorWorld(state, options, render) {
         initialSpace: state.transformSpace,
         logger: console,
         onDragStart(event) {
+            beginEditorSceneContinuousRender(state, 'gizmo-drag');
             state.status = event.targetIds.length > 1
                 ? `Dragging ${event.duplicate ? 'duplicate ' : ''}${event.tool} ${event.targetIds.length} objects`
                 : `Dragging ${event.duplicate ? 'duplicate ' : ''}${event.tool} ${event.nodeId ?? event.activeId ?? 'selection'}`;
-            render();
+            renderUi();
         },
         onDragUpdate() {
-            render();
+            renderUi();
         },
         onDragEnd(event) {
-            commitGizmoTransform(state, options, event);
-            render();
+            endEditorSceneContinuousRender(state, 'gizmo-drag');
+            const changed = commitGizmoTransform(state, options, event);
+            if (!changed)
+                requestEditorSceneFrame(state, 'gizmo-drag-end');
+            renderUi();
         },
         onDragCancel(event) {
+            endEditorSceneContinuousRender(state, 'gizmo-drag');
             if (event.duplicate && cancelDuplicateDrag(state, options)) {
-                render();
+                renderUi();
                 return;
             }
+            requestEditorSceneFrame(state, 'gizmo-drag-cancel');
             state.status = event.targetIds.length > 1
                 ? `Canceled ${event.tool} ${event.targetIds.length} objects`
                 : `Canceled ${event.tool} ${event.nodeId ?? event.activeId ?? 'selection'}`;
-            render();
+            renderUi();
         },
         onDuplicateDragStart(input) {
             return beginDuplicateDrag(state, options, input);
@@ -755,15 +799,15 @@ async function createEditorWorld(state, options, render) {
         isOperationBlocked: () => state.gizmo?.getState().dragPhase === 'dragging',
         onSelectionCommand(command) {
             if (dispatchSelectionCommand(state, options, command))
-                render();
+                renderUi();
         },
         onFocusIntent(nodeId) {
             if (focusProjectionNode(state, nodeId))
-                render();
+                renderUi();
         },
         onBoxSelectionChange(box) {
             state.boxSelection = box;
-            render();
+            renderUi();
         },
     });
     const sceneViewMeasurement = createBabylonSceneViewMeasurementController({
@@ -779,9 +823,10 @@ async function createEditorWorld(state, options, render) {
         isPlacementCandidate: () => isPlacementArmed(state),
         isMeasurementCandidate: () => state.viewportTools.activeUtilityTool === 'measure-distance',
         onPointerIntentStart(event) {
+            beginContinuousRenderForPointerIntent(state, event.state.intent);
             if (event.state.intent === 'measurement') {
                 if (handleViewportMeasurementStart(state, event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'gizmo-drag') {
@@ -790,88 +835,109 @@ async function createEditorWorld(state, options, render) {
             }
             if (event.state.intent === 'placement') {
                 if (previewArmedPlacement(state, event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'view-plane-move') {
                 if (gizmo.beginViewPlaneMove(event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'selection-click' || event.state.intent === 'box-select') {
                 selectionController.beginPointerSelection(event.originalEvent);
+                requestEditorSceneFrame(state, `pointer-${event.state.intent}-start`);
             }
         },
         onPointerIntentMove(event) {
             if (event.state.intent === 'measurement') {
                 if (handleViewportMeasurementMove(state, event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'placement') {
                 if (previewArmedPlacement(state, event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'view-plane-move') {
                 if (gizmo.updateViewPlaneMove(event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
-            if (!state.sceneCameraPreviewEnabled && state.sceneViewCamera?.handlePointerIntentMove(event)) {
-                render();
+            if (!state.mainCameraPreviewEnabled && state.sceneViewCamera?.handlePointerIntentMove(event)) {
+                renderUi();
                 return;
             }
             if (event.state.intent === 'selection-click' || event.state.intent === 'box-select') {
                 selectionController.updatePointerSelection(event.originalEvent, event.state.intent);
             }
+            requestEditorSceneFrame(state, `pointer-${event.state.intent}`);
         },
         onPointerIntentEnd(event) {
+            endContinuousRenderForPointerIntent(state, event.state.intent);
             if (event.state.intent === 'measurement') {
                 if (handleViewportMeasurementEnd(state))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'placement') {
                 if (commitArmedPlacement(state, options, event.originalEvent))
-                    render();
+                    renderUi();
                 return;
             }
             if (event.state.intent === 'view-plane-move') {
-                if (gizmo.endViewPlaneMove(event.originalEvent))
-                    render();
+                if (gizmo.endViewPlaneMove(event.originalEvent)) {
+                    requestEditorSceneFrame(state, 'view-plane-move-end');
+                    renderUi();
+                }
                 return;
             }
             if (event.state.intent === 'selection-click' || event.state.intent === 'box-select') {
                 selectionController.endPointerSelection(event.originalEvent, event.state.intent);
             }
+            requestEditorSceneFrame(state, `pointer-${event.state.intent}-end`);
         },
         onPointerIntentCancel(event) {
+            endContinuousRenderForPointerIntent(state, event.state.intent);
             if (event.state.intent === 'measurement') {
-                render();
+                renderUi();
                 return;
             }
             if (event.state.intent === 'placement') {
                 state.gizmo?.setPlacementMarker(null);
-                render();
+                requestEditorSceneFrame(state, 'placement-marker-clear');
+                renderUi();
                 return;
             }
             if (event.state.intent === 'view-plane-move') {
                 gizmo.cancelDrag();
-                render();
+                requestEditorSceneFrame(state, 'view-plane-move-cancel');
+                renderUi();
                 return;
             }
             if (event.state.intent === 'selection-click' || event.state.intent === 'box-select') {
                 selectionController.cancelBoxSelection();
-                render();
+                renderUi();
             }
+            requestEditorSceneFrame(state, `pointer-${event.state.intent}-cancel`);
         },
         onDoubleClick(event) {
             selectionController.handleDoubleClick(event);
         },
         onWheel(event) {
-            if (!state.sceneCameraPreviewEnabled && state.sceneViewCamera?.handleWheel(event))
-                render();
+            if (!state.mainCameraPreviewEnabled && state.sceneViewCamera?.handleWheel(event)) {
+                requestEditorSceneFrame(state, 'camera-wheel');
+                renderUi();
+            }
+        },
+        onMovementKeysChange(event) {
+            if (event.pressedMovementKeys.length > 0) {
+                beginEditorSceneContinuousRender(state, 'camera-flythrough-keys');
+            }
+            else {
+                endEditorSceneContinuousRender(state, 'camera-flythrough-keys');
+            }
+            renderUi();
         },
     });
     const sceneViewCamera = createBabylonSceneViewCameraController({
@@ -880,7 +946,7 @@ async function createEditorWorld(state, options, render) {
         camera: world.camera,
         input: sceneViewInput,
     });
-    const sceneCameraPreview = createBabylonSceneCameraPreviewController({
+    const mainCameraPreview = createBabylonMainCameraPreviewController({
         babylon,
         scene: world.scene,
         editorCamera: world.camera,
@@ -896,31 +962,42 @@ async function createEditorWorld(state, options, render) {
         projection.syncSelection(selection);
         gizmo.setSelection(selection);
     }
-    const resize = () => engine.resize?.();
+    const resize = () => {
+        engine.resize?.();
+        viewportRenderCoordinator.requestFrame('resize');
+    };
     window.addEventListener('resize', resize);
-    engine.runRenderLoop?.(() => world.render());
     state.babylon = babylon;
     state.engine = engine;
     state.world = world;
     state.grid = grid;
     state.projection = projection;
     state.gizmo = gizmo;
-    state.sceneCameraPreview = sceneCameraPreview;
+    state.mainCameraPreview = mainCameraPreview;
     state.sceneViewInput = sceneViewInput;
     state.sceneViewCamera = sceneViewCamera;
     state.sceneViewMeasurement = sceneViewMeasurement;
     state.sceneViewSpatialOverlay = sceneViewSpatialOverlay;
     state.selectionController = selectionController;
+    state.sceneRenderScheduler = sceneRenderScheduler;
+    state.viewportRenderCoordinator = viewportRenderCoordinator;
+    state.sceneFrameStats = sceneRenderScheduler.getStats();
     state.resizeHandler = resize;
+    await sceneRenderScheduler.waitForNextFrame('editor-world-created');
 }
 function disposeEditorWorld(state) {
+    state.viewportRenderCoordinator?.dispose();
+    state.viewportRenderCoordinator = null;
+    state.sceneRenderScheduler?.dispose();
+    state.sceneRenderScheduler = null;
+    state.sceneFrameStats = null;
     if (state.resizeHandler) {
         window.removeEventListener('resize', state.resizeHandler);
         state.resizeHandler = null;
     }
-    state.sceneCameraPreview?.dispose();
-    state.sceneCameraPreview = null;
-    state.sceneCameraPreviewEnabled = false;
+    state.mainCameraPreview?.dispose();
+    state.mainCameraPreview = null;
+    state.mainCameraPreviewEnabled = false;
     state.sceneViewCamera?.dispose();
     state.sceneViewCamera = null;
     state.sceneViewMeasurement?.dispose();
@@ -944,18 +1021,55 @@ function disposeEditorWorld(state) {
     state.projection = null;
     state.grid?.dispose();
     state.grid = null;
-    state.engine?.stopRenderLoop?.();
     state.world?.dispose();
     state.engine?.dispose?.();
     state.babylon = null;
     state.world = null;
     state.engine = null;
 }
-async function runExclusive(state, render, action) {
+function requestEditorSceneFrame(state, reason) {
+    state.viewportRenderCoordinator?.requestFrame(reason);
+}
+function beginEditorSceneContinuousRender(state, reason) {
+    state.viewportRenderCoordinator?.beginContinuous(reason);
+}
+function endEditorSceneContinuousRender(state, reason) {
+    state.viewportRenderCoordinator?.endContinuous(reason);
+}
+function beginContinuousRenderForPointerIntent(state, intent) {
+    const reason = continuousRenderReasonForPointerIntent(intent);
+    if (reason)
+        beginEditorSceneContinuousRender(state, reason);
+}
+function endContinuousRenderForPointerIntent(state, intent) {
+    const reason = continuousRenderReasonForPointerIntent(intent);
+    if (reason)
+        endEditorSceneContinuousRender(state, reason);
+    if (intent === 'gizmo-drag')
+        endEditorSceneContinuousRender(state, 'gizmo-drag');
+    if (intent === 'flythrough')
+        endEditorSceneContinuousRender(state, 'camera-flythrough-keys');
+}
+function continuousRenderReasonForPointerIntent(intent) {
+    switch (intent) {
+        case 'gizmo-drag':
+        case 'view-plane-move':
+        case 'placement':
+        case 'measurement':
+        case 'orbit':
+        case 'pan':
+        case 'dolly':
+        case 'flythrough':
+            return `pointer-${intent}`;
+        default:
+            return null;
+    }
+}
+async function runExclusive(state, renderUi, action) {
     if (state.busy)
         return;
     state.busy = true;
-    render();
+    renderUi();
     try {
         await action();
     }
@@ -968,7 +1082,7 @@ async function runExclusive(state, render, action) {
     }
     finally {
         state.busy = false;
-        render();
+        renderUi();
     }
 }
 function selectItem(state, options, input) {
@@ -988,9 +1102,92 @@ function selectItem(state, options, input) {
         return false;
     return dispatchSelectionCommand(state, options, command);
 }
+function createBrowserHierarchyContextActions(state, options) {
+    return (options.hierarchy?.contextActions ?? []).map((registration) => ({
+        id: registration.id,
+        label: registration.label,
+        shortcut: registration.shortcut,
+        danger: registration.danger,
+        placement: registration.placement,
+        separatorBefore: registration.separatorBefore,
+        visible: (browserContext) => {
+            const context = createHarnessHierarchyContextActionContext(state, options, browserContext);
+            if (!context)
+                return false;
+            return registration.visible?.(context) ?? true;
+        },
+        disabled: (browserContext) => {
+            const context = createHarnessHierarchyContextActionContext(state, options, browserContext);
+            if (!context)
+                return 'No editable document is loaded.';
+            return registration.disabled?.(context) ?? false;
+        },
+    }));
+}
+function createHarnessHierarchyContextActionContext(state, options, browserContext, payload) {
+    const document = state.session?.getState().workingDocument ?? null;
+    if (!document)
+        return null;
+    const activeId = browserContext.activeId;
+    return {
+        document,
+        contextNodeId: browserContext.contextNodeId,
+        targetIds: browserContext.targetIds,
+        activeId,
+        hierarchyItem: browserContext.node,
+        projectionNode: browserContext.contextNodeId
+            ? options.documentAdapter.getProjectionNode(document, browserContext.contextNodeId)
+            : null,
+        hostServices: options.hostServices ?? null,
+        payload,
+        browserContext,
+    };
+}
+function createBrowserContextForCustomAction(state, options, action) {
+    const document = state.session?.getState().workingDocument ?? null;
+    if (!document)
+        return null;
+    const uiState = createUiState(state, options);
+    const node = action.contextNodeId
+        ? uiState.hierarchy.find(item => item.id === action.contextNodeId) ?? null
+        : null;
+    return {
+        state: uiState,
+        menuKind: node ? 'node' : 'blank',
+        node,
+        contextNodeId: action.contextNodeId,
+        targetIds: action.targetIds,
+        activeId: action.activeId,
+    };
+}
+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;
+    try {
+        return registration.run(context) === true;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        state.status = `${registration.label} failed`;
+        state.statusTone = 'error';
+        state.statusToneStatus = state.status;
+        state.statusDetails = message;
+        console.error('[LocalEditorHarness] hierarchy context action failed', error);
+        return true;
+    }
+}
 function handleContextAction(state, options, action) {
     if (action.region !== 'hierarchy')
         return false;
+    if (action.action === 'custom')
+        return runHierarchyCustomContextAction(state, options, action);
     if (action.action === 'focus') {
         const activeId = action.activeId ?? action.targetIds[action.targetIds.length - 1] ?? null;
         const selectionChanged = activeId && !state.session?.getState().selection.selectedIds.includes(activeId)
@@ -1399,6 +1596,13 @@ function syncSelectionToProjection(state, selection) {
     state.projection?.syncSelection(selection);
     state.gizmo?.setSelection(selection);
     state.gizmo?.refreshSelection();
+    requestEditorSceneFrame(state, 'projection-selection');
+}
+function invalidateEditorScene(state, reason, options) {
+    if (options && state.mainCameraPreviewEnabled) {
+        syncMainCameraPreview(state, options);
+    }
+    state.viewportRenderCoordinator?.invalidateScene(reason);
 }
 function executeTransformAction(state, options, action) {
     if (state.mode !== 'editor' || !state.session)
@@ -1501,11 +1705,12 @@ function armAssetPlacement(state, options, assetId) {
     if (state.mode !== 'editor')
         return false;
     cancelActiveOperation(state);
-    const asset = state.assets.find(candidate => resolveAssetId(options, candidate) === assetId);
+    const asset = findAssetByResolvedId(state, options, assetId);
     if (!asset)
         return false;
     state.armedPlacement = { assetId, asset };
     state.gizmo?.setPlacementMarker(null);
+    requestEditorSceneFrame(state, 'placement-arm-change');
     state.status = `Placement armed: ${formatAssetLabel(asset, assetId)} (${state.transformOperationSettings.placementMode})`;
     return true;
 }
@@ -1535,6 +1740,7 @@ function commitArmedPlacement(state, options, event) {
     if (!armed || !hit) {
         state.gizmo?.setPlacementMarker(null);
         state.status = 'Placement rejected: no hit';
+        requestEditorSceneFrame(state, 'placement-marker-clear');
         return true;
     }
     const patch = options.documentAdapter.createPlacedAssetPatch?.({
@@ -1584,8 +1790,11 @@ function pickArmedPlacementHit(state, event) {
         : state.gizmo?.pickPlacementHit(event.clientX, event.clientY, mode) ?? null;
 }
 function clearArmedPlacement(state) {
+    const hadArmedPlacement = !!state.armedPlacement;
     state.armedPlacement = null;
     state.gizmo?.setPlacementMarker(null);
+    if (hadArmedPlacement)
+        requestEditorSceneFrame(state, 'placement-clear');
 }
 function addAssetToDocument(state, options, assetId, createOptions = {}) {
     if (state.mode !== 'editor') {
@@ -1599,7 +1808,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 = state.assets.find(candidate => resolveAssetId(options, candidate) === assetId);
+    const asset = findAssetByResolvedId(state, options, assetId);
     if (!asset) {
         state.status = `Asset creation rejected: ${assetId} not found`;
         return { ok: false, assetId, changed: false, status: state.status, error: 'asset_not_found' };
@@ -1636,6 +1845,7 @@ function addAssetToDocument(state, options, assetId, createOptions = {}) {
             state.projection?.projectNode(projectedNode);
             if (selectionResult)
                 syncSelectionToProjection(state, selectionResult.selection);
+            invalidateEditorScene(state, 'projection-project-node', options);
         }
     }
     return {
@@ -1976,6 +2186,8 @@ function focusProjectionNode(state, nodeId) {
     state.status = focused
         ? `Focused ${nodeId} · ${formatEditorStatusTime(Date.now())}`
         : `Focus failed: camera could not frame ${nodeId}`;
+    if (focused)
+        requestEditorSceneFrame(state, 'viewport-focus-selection');
     return true;
 }
 function formatEditorStatusTime(timestamp) {
@@ -2021,6 +2233,7 @@ function rebuildProjectionFromDocument(state, options, document, selection) {
     state.projection?.rebuild(options.documentAdapter.getProjectionNodes(document));
     const sanitized = sanitizeSelection(state, options, document, selection);
     syncSelectionToProjection(state, sanitized ?? selection);
+    invalidateEditorScene(state, 'projection-rebuild', options);
 }
 function syncProjectionForDispatchResult(state, options, result, changedId) {
     if (result.documentChanged && changedId && result.workingDocument) {
@@ -2036,6 +2249,9 @@ function syncProjectionForDispatchResult(state, options, result, changedId) {
         const sanitized = result.workingDocument ? sanitizeSelection(state, options, result.workingDocument, selection) : null;
         syncSelectionToProjection(state, sanitized ?? selection);
     }
+    if (result.documentChanged || result.selectionChanged) {
+        invalidateEditorScene(state, 'projection-dispatch-result', options);
+    }
 }
 function syncProjectionForChangedIds(state, options, document, changedIds) {
     for (const changedId of changedIds) {
@@ -2045,6 +2261,7 @@ function syncProjectionForChangedIds(state, options, document, changedIds) {
     }
     const selection = state.session?.getState().selection ?? { selectedIds: [], activeId: null };
     syncSelectionToProjection(state, selection);
+    invalidateEditorScene(state, 'projection-sync-changed-ids', options);
 }
 function reprojectProjectionForChangedIds(state, options, document, changedIds) {
     for (const changedId of changedIds) {
@@ -2055,24 +2272,28 @@ function reprojectProjectionForChangedIds(state, options, document, changedIds)
     const selection = state.session?.getState().selection ?? { selectedIds: [], activeId: null };
     syncSelectionToProjection(state, selection);
     state.gizmo?.refreshSelection();
+    invalidateEditorScene(state, 'projection-reproject-changed-ids', options);
 }
-function setSceneCameraPreviewEnabled(state, options, enabled) {
+function setMainCameraPreviewEnabled(state, options, enabled) {
     if (!enabled) {
-        state.sceneCameraPreviewEnabled = false;
-        state.sceneCameraPreview?.setActive(false);
-        state.status = 'Scene Camera preview disabled';
+        state.mainCameraPreviewEnabled = false;
+        state.mainCameraPreview?.setActive(false);
+        state.status = 'Main Camera preview disabled';
+        requestEditorSceneFrame(state, 'main-camera-preview-toggle');
         return true;
     }
-    state.sceneCameraPreviewEnabled = true;
-    if (!syncSceneCameraPreview(state, options)) {
-        state.sceneCameraPreviewEnabled = false;
-        state.status = 'Scene Camera preview unavailable';
+    state.mainCameraPreviewEnabled = true;
+    if (!syncMainCameraPreview(state, options)) {
+        state.mainCameraPreviewEnabled = false;
+        state.status = 'Main Camera preview unavailable';
         state.statusTone = 'warning';
         state.statusToneStatus = state.status;
         state.statusDetails = 'The current document did not provide a Main Camera preview rig.';
+        requestEditorSceneFrame(state, 'main-camera-preview-toggle');
         return true;
     }
-    state.status = 'Scene Camera preview enabled';
+    state.status = 'Main Camera preview enabled';
+    requestEditorSceneFrame(state, 'main-camera-preview-toggle');
     return true;
 }
 function setGridVisible(state, visible) {
@@ -2085,18 +2306,19 @@ function setGridVisible(state, visible) {
     state.statusTone = 'default';
     state.statusToneStatus = state.status;
     state.statusDetails = '';
+    requestEditorSceneFrame(state, 'grid-visible-change');
     return true;
 }
-function syncSceneCameraPreview(state, options) {
-    const controller = state.sceneCameraPreview;
+function syncMainCameraPreview(state, options) {
+    const controller = state.mainCameraPreview;
     if (!controller)
         return false;
-    if (!state.sceneCameraPreviewEnabled) {
+    if (!state.mainCameraPreviewEnabled) {
         controller.setActive(false);
         return false;
     }
     const document = state.session?.getState().workingDocument ?? null;
-    const rig = document ? options.documentAdapter.getSceneCameraPreviewRig?.(document) ?? null : null;
+    const rig = document ? options.documentAdapter.getMainCameraPreviewRig?.(document) ?? null : null;
     if (!rig) {
         controller.setActive(false);
         return false;
@@ -2115,6 +2337,11 @@ function syncViewportCameraState(state) {
     };
 }
 function syncViewportSpatialOverlay(state) {
+    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;
@@ -2128,7 +2355,7 @@ function syncViewportSpatialOverlay(state) {
         nodeId: activeId,
         bounds,
         anchor,
-        settings: state.viewportTools.overlay,
+        settings,
     });
 }
 function syncViewportMeasurementState(state) {
@@ -2138,9 +2365,9 @@ function syncViewportMeasurementState(state) {
     if (measurement)
         state.viewportMeasurement = measurement;
 }
-function hasSceneCameraPreviewRig(state, options) {
+function hasMainCameraPreviewRig(state, options) {
     const document = state.session?.getState().workingDocument ?? null;
-    return !!document && !!options.documentAdapter.getSceneCameraPreviewRig?.(document);
+    return !!document && !!options.documentAdapter.getMainCameraPreviewRig?.(document);
 }
 function createUiState(state, options) {
     const sessionState = state.session?.getState();
@@ -2165,6 +2392,8 @@ function createUiState(state, options) {
     const inspectorMultiObject = document && inspectorMultiObjectBase
         ? withRuntimeInspectorSections(state, options, document, inspectorMultiObjectBase)
         : inspectorMultiObjectBase;
+    const assets = dedupeLocalEditorBrowserAssetItems(state.assets
+        .map(asset => toBrowserAssetItem(options, asset)));
     return {
         mode: state.mode,
         busy: state.busy,
@@ -2173,10 +2402,8 @@ function createUiState(state, options) {
         statusDetails: state.statusToneStatus === state.status ? state.statusDetails : '',
         summary: state.summary,
         assetFilter: state.assetFilter,
-        assets: state.assets
-            .filter(asset => asset.placeable !== false)
-            .map(asset => toBrowserAssetItem(options, asset)),
-        assetCountLabel: `${state.assets.length} assets`,
+        assets,
+        assetCountLabel: `${assets.length} assets`,
         hierarchy: document ? options.documentAdapter.getHierarchyItems(document) : [],
         selectedIds,
         activeId,
@@ -2209,9 +2436,12 @@ function createUiState(state, options) {
         viewportTools: cloneEditorViewportToolState(state.viewportTools),
         viewportMeasurement: cloneViewportMeasurement(state.viewportMeasurement),
         viewportSpatialOverlay: cloneEditorViewportSpatialOverlayState(state.viewportSpatialOverlay),
-        sceneCameraPreview: {
-            enabled: state.sceneCameraPreviewEnabled,
-            available: hasSceneCameraPreviewRig(state, options),
+        sceneFrameStats: state.sceneFrameStats
+            ? { ...state.sceneFrameStats, activeReasons: [...state.sceneFrameStats.activeReasons] }
+            : null,
+        mainCameraPreview: {
+            enabled: state.mainCameraPreviewEnabled,
+            available: hasMainCameraPreviewRig(state, options),
         },
         grid: {
             visible: state.gridVisible,
@@ -2242,6 +2472,8 @@ function createSceneViewCoordinateAxesState(state) {
     if (!right || !up || !forward)
         return null;
     return {
+        projectionMode: readSceneViewFreeCameraProjectionMode(state, camera),
+        projectionToggleDisabled: state.mainCameraPreviewEnabled,
         axes: [
             createSceneViewCoordinateAxis('x', 'X', '#ff4b70', { x: 1, y: 0, z: 0 }, right, up, forward),
             createSceneViewCoordinateAxis('y', 'Y', '#75ff42', { x: 0, y: 1, z: 0 }, right, up, forward),
@@ -2249,6 +2481,14 @@ function createSceneViewCoordinateAxesState(state) {
         ],
     };
 }
+function readSceneViewFreeCameraProjectionMode(state, camera) {
+    return state.sceneViewCamera?.getState().projectionMode
+        ?? readSceneViewCameraProjectionMode(state, state.world?.camera ?? camera);
+}
+function readSceneViewCameraProjectionMode(state, camera) {
+    const orthoMode = state.babylon?.Camera?.ORTHOGRAPHIC_CAMERA ?? 1;
+    return camera?.mode === orthoMode ? 'orthographic' : 'perspective';
+}
 function createSceneViewCoordinateAxis(id, label, color, worldAxis, cameraRight, cameraUp, cameraForward) {
     const screenX = dotSceneViewAxisVec3(worldAxis, cameraRight);
     const screenY = -dotSceneViewAxisVec3(worldAxis, cameraUp);
@@ -2382,9 +2622,10 @@ function createDefaultRuntimeInspectorSections(context) {
     const properties = [];
     if (projectionNode) {
         properties.push(createRuntimeInspectorProperty('runtime.projection.nodeId', 'Projected ID', projectionNode.id, properties.length));
-        const assetSource = projectionNode.asset?.sourceId ?? projectionNode.asset?.id ?? '';
-        if (assetSource)
-            properties.push(createRuntimeInspectorProperty('runtime.projection.assetSource', 'Asset Source', assetSource, properties.length));
+        const projectionAsset = projectionNode.asset;
+        const assetId = projectionAsset?.assetId ?? projectionAsset?.id ?? '';
+        if (assetId)
+            properties.push(createRuntimeInspectorProperty('runtime.projection.assetId', 'Asset ID', assetId, properties.length));
     }
     const runtimeClass = readRuntimeClassName(root);
     if (runtimeClass)
@@ -2501,15 +2742,114 @@ function isNodeSelectableInDocument(options, document, id) {
 }
 function resolveAssetId(options, asset) {
     return options.worldAdapter.resolveAssetId?.(asset)
+        ?? asset.assetId
         ?? asset.id;
 }
+function findAssetByResolvedId(state, options, assetId) {
+    let selected = null;
+    for (const asset of state.assets) {
+        if (resolveAssetId(options, asset) !== assetId)
+            continue;
+        const item = toBrowserAssetItem(options, asset);
+        if (!selected || shouldReplaceBrowserAssetItem(selected.item, item)) {
+            selected = { asset, item };
+        }
+    }
+    return selected?.asset;
+}
 function toBrowserAssetItem(options, asset) {
     return options.worldAdapter.toBrowserAssetItem?.(asset)
         ?? {
-            id: asset.id,
-            label: asset.label,
+            id: asset.assetId ?? asset.id,
+            label: asset.displayName ?? asset.label,
+            guid: asset.guid,
+            assetId: asset.assetId,
+            kind: asset.kind,
+            external: asset.external,
+            origin: asset.origin,
+            dedupeKey: asset.dedupeKey,
+            placeable: asset.placeable,
             meta: asset.meta,
-            disabled: asset.placeable === false,
+            disabled: asset.disabled ?? asset.placeable === false,
         };
 }
+export function dedupeLocalEditorBrowserAssetItems(items) {
+    const byKey = new Map();
+    for (const item of items) {
+        const key = getBrowserAssetCanonicalKey(item);
+        const existing = byKey.get(key);
+        if (!existing || shouldReplaceBrowserAssetItem(existing, item)) {
+            byKey.set(key, item);
+        }
+    }
+    const projectDuplicateKeys = new Set();
+    for (const item of byKey.values()) {
+        if (!item.guid || item.origin !== 'project')
+            continue;
+        for (const duplicateKey of getBrowserAssetDuplicateSuppressionKeys(item)) {
+            projectDuplicateKeys.add(duplicateKey);
+        }
+    }
+    return [...byKey.values()].filter((item) => {
+        if (item.guid)
+            return true;
+        return !getBrowserAssetDuplicateSuppressionKeys(item)
+            .some(duplicateKey => projectDuplicateKeys.has(duplicateKey));
+    });
+}
+function getBrowserAssetCanonicalKey(item) {
+    const guid = normalizeBrowserAssetString(item.guid);
+    if (guid)
+        return `guid:${guid}`;
+    const platformAssetId = normalizeBrowserAssetString(item.external?.platformAssetId);
+    if (platformAssetId)
+        return `external:${platformAssetId}`;
+    const dedupeKey = normalizeBrowserAssetString(item.dedupeKey);
+    if (dedupeKey)
+        return `dedupe:${dedupeKey}`;
+    const assetId = normalizeBrowserAssetString(item.assetId);
+    if (assetId)
+        return `asset:${assetId}`;
+    return `id:${normalizeBrowserAssetString(item.id) ?? item.id}`;
+}
+function getBrowserAssetDuplicateSuppressionKeys(item) {
+    const keys = [];
+    pushBrowserAssetDuplicateKey(keys, 'external', item.external?.platformAssetId);
+    pushBrowserAssetDuplicateKey(keys, 'dedupe', item.dedupeKey);
+    pushBrowserAssetDuplicateKey(keys, 'asset', item.assetId);
+    pushBrowserAssetDuplicateKey(keys, 'id', item.id);
+    return keys;
+}
+function pushBrowserAssetDuplicateKey(keys, prefix, value) {
+    const normalized = normalizeBrowserAssetString(value);
+    if (normalized)
+        keys.push(`${prefix}:${normalized}`);
+}
+function shouldReplaceBrowserAssetItem(current, candidate) {
+    const currentScore = getBrowserAssetPreferenceScore(current);
+    const candidateScore = getBrowserAssetPreferenceScore(candidate);
+    if (candidateScore !== currentScore)
+        return candidateScore > currentScore;
+    return getBrowserAssetDetailScore(candidate) > getBrowserAssetDetailScore(current);
+}
+function getBrowserAssetPreferenceScore(item) {
+    return (item.origin === 'project' ? 1000 : 0)
+        + (item.guid ? 100 : 0)
+        + (item.assetId ? 40 : 0)
+        + (item.placeable === false ? 0 : 10)
+        + (item.disabled ? 0 : 5);
+}
+function getBrowserAssetDetailScore(item) {
+    return [
+        item.label,
+        item.meta,
+        item.kind,
+        item.external?.platformAssetId,
+        item.external?.assetPath,
+        item.external?.assetUrl,
+    ].filter(value => typeof value === 'string' && value.trim()).length;
+}
+function normalizeBrowserAssetString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
 //# sourceMappingURL=local-editor-harness.js.map