@fps-games/editor 0.1.1-beta.1 → 0.1.1-beta.10

package/dist/local-editor-harness.js

@@ -1,6 +1,6 @@
-import { createEditorSession, createInspectorRegistry, createInspectorEditPayload, mergeInspectorSections, serializedMultiObjectToInspectorObject, serializedObjectToInspectorObject, validateSceneGraphDelete, validateSceneGraphDrop, validateSceneGraphGroupSelection, validateSceneGraphMove, validateSceneGraphRename, } from '@fps-games/editor-core';
+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, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonTransformGizmoController, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
+import { createBabylonEditorProjection, createBabylonEditorWorld, createBabylonProjectionSelectionController, createBabylonSceneCameraPreviewController, createBabylonSceneViewCameraController, createBabylonSceneViewInputController, createBabylonSceneViewMeasurementController, createBabylonSceneViewSpatialOverlayController, createBabylonTransformGizmoController, focusEditorViewportSelection, } from '@fps-games/editor-babylon';
 export function createLocalEditorHarness(options) {
     const root = options.root ?? document.body;
     const state = {
@@ -13,15 +13,27 @@ export function createLocalEditorHarness(options) {
         babylon: null,
         engine: null,
         world: null,
+        grid: null,
+        gridVisible: true,
         projection: null,
         gizmo: null,
+        sceneCameraPreview: null,
+        sceneCameraPreviewEnabled: false,
         sceneViewInput: null,
         sceneViewCamera: null,
+        sceneViewMeasurement: null,
+        sceneViewSpatialOverlay: null,
         selectionController: null,
         boxSelection: null,
         transformTool: 'select',
         transformSpace: 'world',
         transformConstraint: 'axis',
+        transformOperationSettings: cloneTransformOperationSettings(DEFAULT_EDITOR_TRANSFORM_OPERATION_SETTINGS),
+        viewportTools: cloneEditorViewportToolState(DEFAULT_EDITOR_VIEWPORT_TOOL_STATE),
+        viewportMeasurement: createEmptyViewportMeasurement(),
+        viewportSpatialOverlay: createEmptyEditorViewportSpatialOverlayState(),
+        duplicateDrag: null,
+        armedPlacement: null,
         resizeHandler: null,
         status: 'Game running',
         statusTone: 'default',
@@ -32,7 +44,12 @@ export function createLocalEditorHarness(options) {
     let harness;
     const ui = createLocalEditorBrowserUi({
         root,
+        theme: options.theme,
+        localTestActions: options.localTestActions,
         inspector: options.inspector,
+        hierarchy: {
+            contextActions: createBrowserHierarchyContextActions(state, options),
+        },
         callbacks: {
             onEnterEditor: () => {
                 void runExclusive(state, harness.render, () => harness.enterEditor());
@@ -55,13 +72,17 @@ export function createLocalEditorHarness(options) {
                     harness.render();
             },
             onCreateFromAsset: (assetId) => {
-                if (addAssetToDocument(state, options, assetId))
+                if (createAssetFromBrowserIntent(state, options, assetId))
                     harness.render();
             },
             onSelectHierarchyItem: (input) => {
                 if (selectItem(state, options, input))
                     harness.render();
             },
+            onSelectionCommand: (command) => {
+                if (dispatchSelectionCommand(state, options, command))
+                    harness.render();
+            },
             onSceneGraphRename: (intent) => {
                 if (renameSceneGraphNode(state, options, intent))
                     harness.render();
@@ -70,10 +91,25 @@ export function createLocalEditorHarness(options) {
                 if (createSceneGraphGroup(state, options, intent))
                     harness.render();
             },
+            onSceneGraphCreatePrimitive: options.documentAdapter.createSceneGraphCreatePrimitivePatch
+                ? (intent) => {
+                    if (createSceneGraphPrimitive(state, options, intent))
+                        harness.render();
+                }
+                : undefined,
             onSceneGraphDelete: (intent) => {
                 if (deleteSceneGraphNodes(state, options, intent))
                     harness.render();
             },
+            onSceneGraphDuplicate: options.documentAdapter.createDuplicateSelectionPatch
+                ? (intent) => {
+                    if (duplicateSceneGraphNodes(state, options, {
+                        targetIds: intent.targetIds,
+                        activeId: intent.activeId ?? null,
+                    }))
+                        harness.render();
+                }
+                : undefined,
             onSceneGraphDrop: (intent) => {
                 if (dropSceneGraphNode(state, options, intent))
                     harness.render();
@@ -102,7 +138,9 @@ export function createLocalEditorHarness(options) {
             },
             onTransformToolChange: (tool) => {
                 state.transformTool = tool;
+                state.transformConstraint = normalizeTransformConstraint(tool, state.transformConstraint);
                 state.gizmo?.setTool(tool);
+                state.gizmo?.setConstraint(state.transformConstraint);
                 harness.render();
             },
             onTransformSpaceChange: (space) => {
@@ -111,14 +149,87 @@ export function createLocalEditorHarness(options) {
                 harness.render();
             },
             onTransformConstraintChange: (constraint) => {
-                state.transformConstraint = constraint;
-                state.gizmo?.setConstraint(constraint);
+                state.transformConstraint = normalizeTransformConstraint(state.transformTool, constraint);
+                state.gizmo?.setConstraint(state.transformConstraint);
+                harness.render();
+            },
+            onTransformSnapEnabledChange: (enabled) => {
+                state.transformOperationSettings = updateTransformOperationSettings(state.transformOperationSettings, {
+                    snap: {
+                        ...state.transformOperationSettings.snap,
+                        enabled,
+                    },
+                });
+                state.gizmo?.setOperationSettings(state.transformOperationSettings);
+                state.status = enabled ? 'Transform snap enabled' : 'Transform snap disabled';
                 harness.render();
             },
+            onTransformSnapStepChange: (input) => {
+                const value = normalizePositiveStep(input.value);
+                if (value == null)
+                    return;
+                const snap = { ...state.transformOperationSettings.snap };
+                if (input.kind === 'move')
+                    snap.moveStep = value;
+                else if (input.kind === 'rotate')
+                    snap.rotateStepDegrees = value;
+                else
+                    snap.scaleStep = value;
+                state.transformOperationSettings = updateTransformOperationSettings(state.transformOperationSettings, { snap });
+                state.gizmo?.setOperationSettings(state.transformOperationSettings);
+                state.status = `Transform snap ${input.kind} step ${value}`;
+                harness.render();
+            },
+            onPlacementModeChange: (mode) => {
+                state.transformOperationSettings = updateTransformOperationSettings(state.transformOperationSettings, {
+                    placementMode: normalizePlacementMode(mode),
+                });
+                state.gizmo?.setOperationSettings(state.transformOperationSettings);
+                if (state.transformOperationSettings.placementMode === 'off')
+                    clearArmedPlacement(state);
+                state.status = `Placement mode: ${state.transformOperationSettings.placementMode}`;
+                harness.render();
+            },
+            onTransformAction: (action) => {
+                if (executeTransformAction(state, options, action))
+                    harness.render();
+            },
+            onViewportViewPresetChange: (preset) => {
+                if (setViewportViewPreset(state, preset))
+                    harness.render();
+            },
+            onViewportProjectionModeChange: (mode) => {
+                if (setViewportProjectionMode(state, mode))
+                    harness.render();
+            },
+            onViewportOverlaySettingsChange: (settings) => {
+                if (setViewportOverlaySettings(state, settings))
+                    harness.render();
+            },
+            onViewportUtilityToolChange: (tool) => {
+                if (setViewportUtilityTool(state, tool))
+                    harness.render();
+            },
+            onViewportMeasurementClear: () => {
+                if (clearViewportMeasurement(state))
+                    harness.render();
+            },
+            onSceneCameraPreviewToggle: (enabled) => {
+                if (setSceneCameraPreviewEnabled(state, options, enabled))
+                    harness.render();
+            },
+            onGridVisibleChange: (visible) => {
+                if (setGridVisible(state, visible))
+                    harness.render();
+            },
             onFocusSelection: () => {
                 if (focusSelectedProjection(state))
                     harness.render();
             },
+            onCancelEditorIntent: () => {
+                if (cancelEditorIntent(state, options))
+                    harness.render();
+            },
             onCancelActiveOperation: () => {
                 cancelActiveOperation(state);
                 harness.render();
@@ -127,14 +238,59 @@ export function createLocalEditorHarness(options) {
     });
     harness = {
         render() {
+            syncSceneCameraPreview(state, options);
+            syncViewportCameraState(state);
+            syncViewportMeasurementState(state);
+            syncViewportSpatialOverlay(state);
             ui.update(createUiState(state, options));
         },
+        setTheme(theme) {
+            ui.setTheme(theme);
+        },
+        getTheme() {
+            return ui.getTheme();
+        },
         getHostServices() {
             return options.hostServices ?? null;
         },
         getWorkingDocument() {
             return state.session?.getState().workingDocument ?? null;
         },
+        async reloadAssets() {
+            try {
+                const assets = await options.persistenceAdapter.loadAssets();
+                state.assets = assets;
+                clearArmedPlacement(state);
+                state.status = `Assets reloaded; assets=${assets.length}`;
+                state.statusTone = 'success';
+                state.statusToneStatus = state.status;
+                state.statusDetails = '';
+                harness.render();
+                return {
+                    ok: true,
+                    assetCount: assets.length,
+                    status: state.status,
+                };
+            }
+            catch (error) {
+                state.status = 'Asset reload failed';
+                state.statusTone = 'error';
+                state.statusToneStatus = state.status;
+                state.statusDetails = error instanceof Error ? error.message : String(error);
+                harness.render();
+                return {
+                    ok: false,
+                    assetCount: state.assets.length,
+                    status: state.status,
+                    error: state.statusDetails,
+                };
+            }
+        },
+        createAssetFromAssetId(assetId, createOptions) {
+            const result = addAssetToDocument(state, options, assetId, createOptions);
+            harness.render();
+            return result;
+        },
         async enterEditor() {
             const loadedSource = options.persistenceAdapter.loadAuthoringSource
                 ? await options.persistenceAdapter.loadAuthoringSource()
@@ -268,6 +424,267 @@ export function mergeLocalEditorHarnessInspectorComponentSections(input) {
         }),
     };
 }
+function normalizeTransformConstraint(tool, constraint) {
+    return normalizeEditorTransformConstraint(tool, constraint) ?? 'axis';
+}
+function cloneTransformOperationSettings(settings) {
+    return {
+        snap: {
+            enabled: settings.snap.enabled,
+            moveStep: settings.snap.moveStep,
+            rotateStepDegrees: settings.snap.rotateStepDegrees,
+            scaleStep: settings.snap.scaleStep,
+        },
+        placementMode: settings.placementMode,
+    };
+}
+function updateTransformOperationSettings(current, patch) {
+    return {
+        ...current,
+        ...patch,
+        snap: patch.snap
+            ? { ...current.snap, ...patch.snap }
+            : { ...current.snap },
+    };
+}
+function normalizePositiveStep(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    return Number(value.toFixed(4));
+}
+function normalizePlacementMode(mode) {
+    return mode === 'ground' || mode === 'surface' ? mode : 'off';
+}
+function normalizeViewportViewPreset(preset) {
+    return preset === 'top' || preset === 'front' || preset === 'right' ? preset : 'perspective';
+}
+function normalizeViewportProjectionMode(mode) {
+    return mode === 'orthographic' ? 'orthographic' : 'perspective';
+}
+function createEmptyViewportMeasurement() {
+    return {
+        active: false,
+        start: null,
+        end: null,
+        preview: null,
+        distance: null,
+        screenStart: null,
+        screenEnd: null,
+        screenPreview: null,
+        label: null,
+    };
+}
+function cloneViewportMeasurement(measurement) {
+    return {
+        active: measurement.active,
+        start: measurement.start ? { ...measurement.start } : null,
+        end: measurement.end ? { ...measurement.end } : null,
+        preview: measurement.preview ? { ...measurement.preview } : null,
+        distance: measurement.distance,
+        screenStart: measurement.screenStart ? { ...measurement.screenStart } : null,
+        screenEnd: measurement.screenEnd ? { ...measurement.screenEnd } : null,
+        screenPreview: measurement.screenPreview ? { ...measurement.screenPreview } : null,
+        label: measurement.label ? { ...measurement.label } : null,
+    };
+}
+function setViewportViewPreset(state, preset) {
+    if (state.sceneCameraPreviewEnabled) {
+        state.status = 'Viewport view unavailable during Scene Camera preview';
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        state.statusDetails = 'Disable Scene Camera preview before switching editor viewport views.';
+        return true;
+    }
+    const nextPreset = normalizeViewportViewPreset(preset);
+    const target = resolveViewportPresetTarget(state);
+    const radius = resolveViewportPresetRadius(state);
+    const changed = state.sceneViewCamera?.setViewPreset(nextPreset, { target, radius }) ?? false;
+    if (!changed)
+        return false;
+    const cameraState = state.sceneViewCamera?.getState();
+    state.viewportTools = {
+        ...state.viewportTools,
+        viewPreset: cameraState?.viewPreset ?? nextPreset,
+        projectionMode: cameraState?.projectionMode ?? (nextPreset === 'perspective' ? 'perspective' : 'orthographic'),
+    };
+    state.status = `Viewport view: ${state.viewportTools.viewPreset}`;
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function setViewportProjectionMode(state, mode) {
+    if (state.sceneCameraPreviewEnabled) {
+        state.status = 'Viewport projection unavailable during Scene Camera preview';
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        state.statusDetails = 'Disable Scene Camera preview before switching editor viewport projection.';
+        return true;
+    }
+    const nextMode = normalizeViewportProjectionMode(mode);
+    const changed = state.sceneViewCamera?.setProjectionMode(nextMode) ?? false;
+    if (!changed)
+        return false;
+    const cameraState = state.sceneViewCamera?.getState();
+    state.viewportTools = {
+        ...state.viewportTools,
+        projectionMode: cameraState?.projectionMode ?? nextMode,
+    };
+    state.status = `Viewport projection: ${state.viewportTools.projectionMode}`;
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function setViewportOverlaySettings(state, settings) {
+    state.viewportTools = {
+        ...state.viewportTools,
+        overlay: {
+            ...state.viewportTools.overlay,
+            bounds: settings.bounds ?? state.viewportTools.overlay.bounds,
+            dimensions: settings.dimensions ?? state.viewportTools.overlay.dimensions,
+            edgeLengths: settings.edgeLengths ?? state.viewportTools.overlay.edgeLengths,
+            anchor: settings.anchor ?? state.viewportTools.overlay.anchor,
+        },
+    };
+    state.status = 'Viewport overlay settings updated';
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function setViewportUtilityTool(state, tool) {
+    const nextTool = tool === 'measure-distance' ? 'measure-distance' : 'none';
+    state.viewportTools = {
+        ...state.viewportTools,
+        activeUtilityTool: nextTool,
+    };
+    if (nextTool === 'measure-distance') {
+        state.viewportMeasurement = {
+            ...cloneViewportMeasurement(state.viewportMeasurement),
+            active: !!state.viewportMeasurement.start && !state.viewportMeasurement.end,
+        };
+        state.status = 'Measure distance: pick first XZ ground point';
+    }
+    else {
+        const unfinishedMeasurement = state.viewportMeasurement.active
+            || (!!state.viewportMeasurement.start && !state.viewportMeasurement.end);
+        state.viewportMeasurement = unfinishedMeasurement
+            ? state.sceneViewMeasurement?.clear() ?? createEmptyViewportMeasurement()
+            : {
+                ...cloneViewportMeasurement(state.viewportMeasurement),
+                active: false,
+                preview: null,
+                screenPreview: null,
+            };
+        state.status = 'Viewport utility: none';
+    }
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function clearViewportMeasurement(state) {
+    state.viewportMeasurement = state.sceneViewMeasurement?.clear() ?? createEmptyViewportMeasurement();
+    state.viewportTools = {
+        ...state.viewportTools,
+        activeUtilityTool: 'none',
+    };
+    state.status = 'Measurement cleared';
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+export function applyLocalEditorHarnessViewportMeasurementPointerStart(state, event) {
+    if (state.viewportTools.activeUtilityTool !== 'measure-distance')
+        return false;
+    if (!state.viewportMeasurement.start || state.viewportMeasurement.end) {
+        const next = state.sceneViewMeasurement?.beginAt(event.clientX, event.clientY) ?? null;
+        if (!next)
+            return false;
+        state.viewportMeasurement = next;
+        state.status = 'Measure distance: pick second XZ ground point';
+        state.statusTone = 'default';
+        state.statusToneStatus = state.status;
+        state.statusDetails = '';
+        return true;
+    }
+    const next = state.sceneViewMeasurement?.completeAt(event.clientX, event.clientY) ?? null;
+    if (!next)
+        return false;
+    state.viewportMeasurement = next;
+    state.viewportTools = {
+        ...state.viewportTools,
+        activeUtilityTool: 'none',
+    };
+    state.status = `Measured distance: ${formatViewportMeasurementDistance(next.distance)} units`;
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = next.start && next.end
+        ? `A (${formatViewportMeasurementDistance(next.start.x)}, ${formatViewportMeasurementDistance(next.start.z)}) · B (${formatViewportMeasurementDistance(next.end.x)}, ${formatViewportMeasurementDistance(next.end.z)})`
+        : '';
+    return true;
+}
+export function applyLocalEditorHarnessViewportMeasurementPointerMove(state, event) {
+    if (state.viewportTools.activeUtilityTool !== 'measure-distance')
+        return false;
+    const next = state.sceneViewMeasurement?.previewAt(event.clientX, event.clientY) ?? null;
+    if (!next)
+        return false;
+    state.viewportMeasurement = next;
+    return true;
+}
+export function applyLocalEditorHarnessViewportMeasurementPointerEnd(_state) {
+    return false;
+}
+function handleViewportMeasurementStart(state, event) {
+    return applyLocalEditorHarnessViewportMeasurementPointerStart(state, event);
+}
+function handleViewportMeasurementMove(state, event) {
+    return applyLocalEditorHarnessViewportMeasurementPointerMove(state, event);
+}
+function handleViewportMeasurementEnd(state) {
+    return applyLocalEditorHarnessViewportMeasurementPointerEnd(state);
+}
+function formatViewportMeasurementDistance(value) {
+    if (!Number.isFinite(value))
+        return '0';
+    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)
+        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)
+        return undefined;
+    const bounds = state.projection?.getSelectionBounds([activeId]) ?? null;
+    if (!bounds)
+        return undefined;
+    const size = bounds.size;
+    const radius = Math.hypot(size.x, size.y, size.z);
+    return Number.isFinite(radius) && radius > 0 ? Math.max(radius * 1.5, 2) : undefined;
+}
+function validateTransformActionSelection(state, action) {
+    const selection = state.session?.getState().selection;
+    const selectedCount = selection?.selectedIds.length ?? 0;
+    if (action.startsWith('align-')) {
+        return selectedCount >= 2 && selection?.activeId
+            ? { ok: true }
+            : { ok: false, message: 'Align needs at least 2 selected objects and an active object' };
+    }
+    return selectedCount >= 3
+        ? { ok: true }
+        : { ok: false, message: 'Distribute needs at least 3 selected objects' };
+}
 async function createEditorWorld(state, options, render) {
     disposeEditorWorld(state);
     const canvas = options.worldAdapter.getCanvas();
@@ -282,10 +699,12 @@ async function createEditorWorld(state, options, render) {
         cameraTarget: options.world?.cameraTarget,
         cameraRadius: options.world?.cameraRadius,
         clearColor: options.world?.clearColor,
+        sky: options.world?.sky,
         useRightHandedSystem: options.world?.useRightHandedSystem,
         enableDefaultCameraControls: false,
     });
-    options.createGrid?.(babylon, world.scene);
+    const grid = options.createGrid?.(babylon, world.scene) ?? null;
+    grid?.setVisible(state.gridVisible);
     const projection = createBabylonEditorProjection({
         babylon,
         scene: world.scene,
@@ -301,8 +720,8 @@ async function createEditorWorld(state, options, render) {
         logger: console,
         onDragStart(event) {
             state.status = event.targetIds.length > 1
-                ? `Dragging ${event.tool} ${event.targetIds.length} objects`
-                : `Dragging ${event.tool} ${event.nodeId ?? event.activeId ?? 'selection'}`;
+                ? `Dragging ${event.duplicate ? 'duplicate ' : ''}${event.tool} ${event.targetIds.length} objects`
+                : `Dragging ${event.duplicate ? 'duplicate ' : ''}${event.tool} ${event.nodeId ?? event.activeId ?? 'selection'}`;
             render();
         },
         onDragUpdate() {
@@ -313,12 +732,20 @@ async function createEditorWorld(state, options, render) {
             render();
         },
         onDragCancel(event) {
+            if (event.duplicate && cancelDuplicateDrag(state, options)) {
+                render();
+                return;
+            }
             state.status = event.targetIds.length > 1
                 ? `Canceled ${event.tool} ${event.targetIds.length} objects`
                 : `Canceled ${event.tool} ${event.nodeId ?? event.activeId ?? 'selection'}`;
             render();
         },
+        onDuplicateDragStart(input) {
+            return beginDuplicateDrag(state, options, input);
+        },
     });
+    gizmo.setOperationSettings(state.transformOperationSettings);
     gizmo.setConstraint(state.transformConstraint);
     const selectionController = createBabylonProjectionSelectionController({
         scene: world.scene,
@@ -342,13 +769,33 @@ async function createEditorWorld(state, options, render) {
             render();
         },
     });
+    const sceneViewMeasurement = createBabylonSceneViewMeasurementController({
+        babylon,
+        scene: world.scene,
+    });
     const sceneViewInput = createBabylonSceneViewInputController({
         canvas,
         isEnabled: () => state.mode === 'editor',
         isGizmoDragCandidate: (event) => gizmo.isGizmoDragCandidate(event),
         isBoxSelectCandidate: (event) => selectionController.isBoxSelectionCandidate(event),
         isViewPlaneMoveCandidate: (event) => gizmo.isViewPlaneMoveCandidate(event),
+        isPlacementCandidate: () => isPlacementArmed(state),
+        isMeasurementCandidate: () => state.viewportTools.activeUtilityTool === 'measure-distance',
         onPointerIntentStart(event) {
+            if (event.state.intent === 'measurement') {
+                if (handleViewportMeasurementStart(state, event.originalEvent))
+                    render();
+                return;
+            }
+            if (event.state.intent === 'gizmo-drag') {
+                gizmo.preparePointerDrag(event.originalEvent);
+                return;
+            }
+            if (event.state.intent === 'placement') {
+                if (previewArmedPlacement(state, event.originalEvent))
+                    render();
+                return;
+            }
             if (event.state.intent === 'view-plane-move') {
                 if (gizmo.beginViewPlaneMove(event.originalEvent))
                     render();
@@ -359,12 +806,22 @@ async function createEditorWorld(state, options, render) {
             }
         },
         onPointerIntentMove(event) {
+            if (event.state.intent === 'measurement') {
+                if (handleViewportMeasurementMove(state, event.originalEvent))
+                    render();
+                return;
+            }
+            if (event.state.intent === 'placement') {
+                if (previewArmedPlacement(state, event.originalEvent))
+                    render();
+                return;
+            }
             if (event.state.intent === 'view-plane-move') {
                 if (gizmo.updateViewPlaneMove(event.originalEvent))
                     render();
                 return;
             }
-            if (state.sceneViewCamera?.handlePointerIntentMove(event)) {
+            if (!state.sceneCameraPreviewEnabled && state.sceneViewCamera?.handlePointerIntentMove(event)) {
                 render();
                 return;
             }
@@ -373,6 +830,16 @@ async function createEditorWorld(state, options, render) {
             }
         },
         onPointerIntentEnd(event) {
+            if (event.state.intent === 'measurement') {
+                if (handleViewportMeasurementEnd(state))
+                    render();
+                return;
+            }
+            if (event.state.intent === 'placement') {
+                if (commitArmedPlacement(state, options, event.originalEvent))
+                    render();
+                return;
+            }
             if (event.state.intent === 'view-plane-move') {
                 if (gizmo.endViewPlaneMove(event.originalEvent))
                     render();
@@ -383,6 +850,15 @@ async function createEditorWorld(state, options, render) {
             }
         },
         onPointerIntentCancel(event) {
+            if (event.state.intent === 'measurement') {
+                render();
+                return;
+            }
+            if (event.state.intent === 'placement') {
+                state.gizmo?.setPlacementMarker(null);
+                render();
+                return;
+            }
             if (event.state.intent === 'view-plane-move') {
                 gizmo.cancelDrag();
                 render();
@@ -397,7 +873,7 @@ async function createEditorWorld(state, options, render) {
             selectionController.handleDoubleClick(event);
         },
         onWheel(event) {
-            if (state.sceneViewCamera?.handleWheel(event))
+            if (!state.sceneCameraPreviewEnabled && state.sceneViewCamera?.handleWheel(event))
                 render();
         },
     });
@@ -407,6 +883,15 @@ async function createEditorWorld(state, options, render) {
         camera: world.camera,
         input: sceneViewInput,
     });
+    const sceneCameraPreview = createBabylonSceneCameraPreviewController({
+        babylon,
+        scene: world.scene,
+        editorCamera: world.camera,
+    });
+    const sceneViewSpatialOverlay = createBabylonSceneViewSpatialOverlayController({
+        babylon,
+        scene: world.scene,
+    });
     const document = state.session?.getState().workingDocument;
     if (document) {
         projection.projectNodes(options.documentAdapter.getProjectionNodes(document));
@@ -420,10 +905,14 @@ async function createEditorWorld(state, options, render) {
     state.babylon = babylon;
     state.engine = engine;
     state.world = world;
+    state.grid = grid;
     state.projection = projection;
     state.gizmo = gizmo;
+    state.sceneCameraPreview = sceneCameraPreview;
     state.sceneViewInput = sceneViewInput;
     state.sceneViewCamera = sceneViewCamera;
+    state.sceneViewMeasurement = sceneViewMeasurement;
+    state.sceneViewSpatialOverlay = sceneViewSpatialOverlay;
     state.selectionController = selectionController;
     state.resizeHandler = resize;
 }
@@ -432,17 +921,32 @@ function disposeEditorWorld(state) {
         window.removeEventListener('resize', state.resizeHandler);
         state.resizeHandler = null;
     }
+    state.sceneCameraPreview?.dispose();
+    state.sceneCameraPreview = null;
+    state.sceneCameraPreviewEnabled = false;
     state.sceneViewCamera?.dispose();
     state.sceneViewCamera = null;
+    state.sceneViewMeasurement?.dispose();
+    state.sceneViewMeasurement = null;
+    state.sceneViewSpatialOverlay?.dispose();
+    state.sceneViewSpatialOverlay = null;
     state.sceneViewInput?.dispose();
     state.sceneViewInput = null;
     state.selectionController?.dispose();
     state.selectionController = null;
     state.boxSelection = null;
+    state.viewportSpatialOverlay = createEmptyEditorViewportSpatialOverlayState();
+    state.viewportMeasurement = createEmptyViewportMeasurement();
+    state.viewportTools = {
+        ...state.viewportTools,
+        activeUtilityTool: 'none',
+    };
     state.gizmo?.dispose();
     state.gizmo = null;
     state.projection?.dispose();
     state.projection = null;
+    state.grid?.dispose();
+    state.grid = null;
     state.engine?.stopRenderLoop?.();
     state.world?.dispose();
     state.engine?.dispose?.();
@@ -475,31 +979,104 @@ function selectItem(state, options, input) {
         return false;
     if (!isDocumentNodeSelectable(state, options, input.id))
         return false;
-    const command = input.toggle
-        ? {
-            type: 'selection.toggle',
-            selectedIds: [input.id],
-            activeId: input.id,
-            label: 'Toggle Selection',
-        }
-        : input.additive
-            ? {
-                type: 'selection.add',
-                selectedIds: [input.id],
-                activeId: input.id,
-                label: 'Add Selection',
-            }
-            : {
-                type: 'selection.replace',
-                selectedIds: [input.id],
-                activeId: input.id,
-                label: 'Select Item',
-            };
+    const selection = state.session?.getState().selection ?? { selectedIds: [], activeId: null };
+    const command = resolveEditorSelectionCommand({
+        selection,
+        targetIds: [input.id],
+        activeId: input.id,
+        gesture: 'click',
+        modifier: input.toggle ? 'toggle' : input.additive ? 'additive' : 'replace',
+    });
+    if (!command)
+        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)
@@ -518,7 +1095,15 @@ function handleContextAction(state, options, action) {
         return createSceneGraphGroup(state, options, {
             parentId: action.parentId ?? null,
             activeId: action.activeId ?? null,
-            name: 'Group',
+            name: 'Empty',
+        });
+    }
+    if (action.action === 'create-primitive') {
+        return createSceneGraphPrimitive(state, options, {
+            parentId: action.parentId ?? null,
+            activeId: action.activeId ?? null,
+            shape: action.shape,
+            name: action.name,
         });
     }
     if (action.action === 'delete') {
@@ -527,6 +1112,18 @@ function handleContextAction(state, options, action) {
             activeId: action.activeId ?? null,
         });
     }
+    if (action.action === 'duplicate') {
+        return duplicateSceneGraphNodes(state, options, {
+            targetIds: action.targetIds,
+            activeId: action.activeId ?? null,
+        });
+    }
+    if (action.action === 'paste') {
+        return duplicateSceneGraphNodes(state, options, {
+            targetIds: action.sourceIds,
+            activeId: action.activeId ?? null,
+        });
+    }
     return false;
 }
 function dispatchSelectionCommand(state, options, command) {
@@ -579,17 +1176,52 @@ function createSceneGraphGroup(state, options, intent) {
     cancelActiveOperation(state);
     const patch = options.documentAdapter.createSceneGraphCreateGroupPatch?.(document, intent);
     if (!patch) {
-        state.status = 'Create group rejected';
+        state.status = 'Create empty rejected';
+        return true;
+    }
+    const result = state.session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? 'Create Empty',
+        patch: patch.patch,
+        targetId: patch.createdId ?? undefined,
+    });
+    if (!result.documentChanged) {
+        state.status = 'Create empty unchanged';
+        return true;
+    }
+    const createdId = patch.createdId ?? null;
+    let selection = result.selection;
+    if (createdId && isNodeSelectableInDocument(options, result.workingDocument, createdId)) {
+        selection = state.session.dispatch({
+            type: 'selection.replace',
+            selectedIds: [createdId],
+            activeId: createdId,
+            label: 'Select Created Empty',
+        }).selection;
+    }
+    rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
+    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.status = patch.label ?? (createdId ? `Created empty ${createdId}` : 'Created empty');
+    return true;
+}
+function createSceneGraphPrimitive(state, options, intent) {
+    const document = state.session?.getState().workingDocument;
+    if (state.mode !== 'editor' || !state.session || !document)
+        return false;
+    cancelActiveOperation(state);
+    const patch = options.documentAdapter.createSceneGraphCreatePrimitivePatch?.(document, intent);
+    if (!patch) {
+        state.status = `Create ${intent.shape} rejected`;
         return true;
     }
     const result = state.session.dispatch({
         type: 'document.patch',
-        label: patch.label ?? 'Create Empty Group',
+        label: patch.label ?? `Create ${intent.shape}`,
         patch: patch.patch,
         targetId: patch.createdId ?? undefined,
     });
     if (!result.documentChanged) {
-        state.status = 'Create group unchanged';
+        state.status = `Create ${intent.shape} unchanged`;
         return true;
     }
     const createdId = patch.createdId ?? null;
@@ -599,12 +1231,12 @@ function createSceneGraphGroup(state, options, intent) {
             type: 'selection.replace',
             selectedIds: [createdId],
             activeId: createdId,
-            label: 'Select Created Group',
+            label: 'Select Created Primitive',
         }).selection;
     }
     rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
     state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
-    state.status = patch.label ?? (createdId ? `Created group ${createdId}` : 'Created group');
+    state.status = patch.label ?? (createdId ? `Created ${intent.shape} ${createdId}` : `Created ${intent.shape}`);
     return true;
 }
 function deleteSceneGraphNodes(state, options, intent) {
@@ -650,6 +1282,57 @@ function deleteSceneGraphNodes(state, options, intent) {
     state.status = patch.label ?? `Deleted ${patch.deletedIds?.length ?? intent.ids.length} node(s)`;
     return true;
 }
+function duplicateSceneGraphNodes(state, options, intent) {
+    const document = state.session?.getState().workingDocument;
+    if (state.mode !== 'editor' || !state.session || !document)
+        return false;
+    cancelActiveOperation(state);
+    const targetIds = Array.from(new Set(intent.targetIds.filter(Boolean)));
+    if (targetIds.length === 0) {
+        state.status = 'Duplicate rejected: empty selection';
+        return true;
+    }
+    const patch = options.documentAdapter.createDuplicateSelectionPatch?.({
+        document,
+        targetIds,
+        activeId: intent.activeId && targetIds.includes(intent.activeId) ? intent.activeId : targetIds[targetIds.length - 1] ?? null,
+        transforms: {},
+    });
+    if (!patch || patch.createdIds.length === 0) {
+        state.status = 'Duplicate rejected';
+        return true;
+    }
+    const result = state.session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `Duplicate ${targetIds.length} object(s)`,
+        patch: patch.patch,
+        targetId: patch.activeId ?? patch.createdIds[patch.createdIds.length - 1] ?? undefined,
+    });
+    if (!result.documentChanged) {
+        state.status = 'Duplicate unchanged';
+        return true;
+    }
+    const createdIds = patch.createdIds.filter(id => isNodeSelectableInDocument(options, result.workingDocument, id));
+    const activeId = patch.activeId && createdIds.includes(patch.activeId)
+        ? patch.activeId
+        : createdIds[createdIds.length - 1] ?? null;
+    const selection = createdIds.length > 0
+        ? state.session.dispatch({
+            type: 'selection.replace',
+            selectedIds: createdIds,
+            activeId,
+            label: 'Select Duplicated Nodes',
+        }).selection
+        : sanitizeSelection(state, options, result.workingDocument, result.selection) ?? result.selection;
+    rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
+    if (patch.reprojectIds?.length)
+        reprojectProjectionForChangedIds(state, options, result.workingDocument, patch.reprojectIds);
+    else
+        syncProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds ?? createdIds);
+    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.status = patch.label ?? `Duplicated ${createdIds.length} object(s)`;
+    return true;
+}
 function dropSceneGraphNode(state, options, intent) {
     const document = state.session?.getState().workingDocument;
     if (state.mode !== 'editor' || !state.session || !document)
@@ -743,27 +1426,27 @@ function groupSceneGraphSelection(state, options, intent) {
     const hierarchy = options.documentAdapter.getHierarchyItems(document);
     const coreValidation = validateSceneGraphGroupSelection(hierarchy, intent);
     if (!coreValidation.ok) {
-        state.status = `Group selection rejected: ${coreValidation.reason ?? 'invalid scene graph group selection'}`;
+        state.status = `Parent selection rejected: ${coreValidation.reason ?? 'invalid scene graph parent selection'}`;
         return true;
     }
     const projectValidation = options.documentAdapter.validateSceneGraphGroupSelection?.(document, intent);
     if (projectValidation && !projectValidation.ok) {
-        state.status = `Group selection rejected: ${projectValidation.reason ?? 'project validation failed'}`;
+        state.status = `Parent selection rejected: ${projectValidation.reason ?? 'project validation failed'}`;
         return true;
     }
     const patch = options.documentAdapter.createSceneGraphGroupSelectionPatch?.(document, intent);
     if (!patch) {
-        state.status = 'Group selection rejected';
+        state.status = 'Parent selection rejected';
         return true;
     }
     const result = state.session.dispatch({
         type: 'document.patch',
-        label: patch.label ?? 'Group Selection',
+        label: patch.label ?? 'Parent Selection',
         patch: patch.patch,
         targetId: patch.createdId,
     });
     if (!result.documentChanged) {
-        state.status = 'Group selection unchanged';
+        state.status = 'Parent selection unchanged';
         return true;
     }
     let selection = result.selection;
@@ -772,7 +1455,7 @@ function groupSceneGraphSelection(state, options, intent) {
             type: 'selection.replace',
             selectedIds: [patch.createdId],
             activeId: patch.createdId,
-            label: 'Select Created Group',
+            label: 'Select Created Parent',
         }).selection;
     }
     else {
@@ -780,7 +1463,7 @@ function groupSceneGraphSelection(state, options, intent) {
     }
     rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
     state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
-    state.status = patch.label ?? `Grouped ${patch.changedIds?.length ?? intent.ids.length} node(s)`;
+    state.status = patch.label ?? `Parented ${patch.changedIds?.length ?? intent.ids.length} node(s)`;
     return true;
 }
 function sanitizeSelection(state, options, document, selection) {
@@ -803,18 +1486,216 @@ function syncSelectionToProjection(state, selection) {
     state.gizmo?.setSelection(selection);
     state.gizmo?.refreshSelection();
 }
-function addAssetToDocument(state, options, assetId) {
-    if (state.mode !== 'editor')
+function executeTransformAction(state, options, action) {
+    if (state.mode !== 'editor' || !state.session)
         return false;
+    const document = state.session.getState().workingDocument;
+    const selection = state.session.getState().selection;
     cancelActiveOperation(state);
-    const session = state.session;
-    const beforeDocument = session?.getState().workingDocument;
-    if (!session || !beforeDocument)
+    const validation = validateTransformActionSelection(state, action);
+    if (!validation.ok) {
+        state.status = validation.message;
+        return true;
+    }
+    const beforeTransforms = state.projection?.readNodeTransforms(selection.selectedIds) ?? {};
+    const transformTargets = selection.selectedIds
+        .map((id) => {
+        const transform = beforeTransforms[id];
+        return transform ? { id, transform } : null;
+    })
+        .filter((target) => !!target);
+    const targets = computeEditorTransformActionTargets({
+        action,
+        activeId: selection.activeId,
+        targets: transformTargets,
+    });
+    if (targets.length === 0) {
+        state.status = `Transform action rejected: ${action}`;
+        return true;
+    }
+    const changedTargets = targets.filter(target => !editorTransformSnapshotsEqual(target.before, target.after));
+    if (changedTargets.length === 0) {
+        state.status = `Transform action unchanged: ${action}`;
+        return true;
+    }
+    const patch = options.documentAdapter.createTransformBatchPatch?.({
+        document,
+        targetIds: changedTargets.map(target => target.id),
+        activeId: selection.activeId,
+        tool: 'move',
+        space: 'world',
+        constraint: action === 'align-all' ? 'free' : 'axis',
+        pivot: createTransformActionPivot(targets),
+        targets: changedTargets,
+    });
+    if (!patch) {
+        state.status = `Transform action ignored: ${action}`;
+        return true;
+    }
+    const result = state.session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? formatTransformActionStatus(action, changedTargets.length),
+        patch: patch.patch,
+        targetId: selection.activeId ?? changedTargets[0]?.id,
+    });
+    if (!result.documentChanged) {
+        state.status = `Transform action unchanged: ${action}`;
+        return true;
+    }
+    const changedIds = patch.changedIds ?? changedTargets.map(target => target.id);
+    syncProjectionForChangedIds(state, options, result.workingDocument, changedIds);
+    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.status = patch.label ?? formatTransformActionStatus(action, changedTargets.length);
+    return true;
+}
+function createTransformActionPivot(targets) {
+    const center = averageTransformTargetPositions(targets);
+    return {
+        mode: 'selection-center',
+        position: center,
+    };
+}
+function averageTransformTargetPositions(targets) {
+    if (targets.length === 0)
+        return { x: 0, y: 0, z: 0 };
+    return {
+        x: targets.reduce((sum, target) => sum + target.before.position.x, 0) / targets.length,
+        y: targets.reduce((sum, target) => sum + target.before.position.y, 0) / targets.length,
+        z: targets.reduce((sum, target) => sum + target.before.position.z, 0) / targets.length,
+    };
+}
+function editorTransformSnapshotsEqual(left, right) {
+    return editorVec3Equal(left.position, right.position)
+        && editorVec3Equal(left.rotation, right.rotation)
+        && editorVec3Equal(left.scale, right.scale);
+}
+function editorVec3Equal(left, right) {
+    return Math.abs(left.x - right.x) < 0.000000001
+        && Math.abs(left.y - right.y) < 0.000000001
+        && Math.abs(left.z - right.z) < 0.000000001;
+}
+function formatTransformActionStatus(action, count) {
+    return `${action} ${count} object${count === 1 ? '' : 's'}`;
+}
+function createAssetFromBrowserIntent(state, options, assetId) {
+    if (state.transformOperationSettings.placementMode === 'off') {
+        return addAssetToDocument(state, options, assetId).ok;
+    }
+    return armAssetPlacement(state, options, assetId);
+}
+function armAssetPlacement(state, options, assetId) {
+    if (state.mode !== 'editor')
         return false;
+    cancelActiveOperation(state);
     const asset = state.assets.find(candidate => resolveAssetId(options, candidate) === assetId);
     if (!asset)
         return false;
-    const patch = options.documentAdapter.createPatchFromAsset(asset);
+    state.armedPlacement = { assetId, asset };
+    state.gizmo?.setPlacementMarker(null);
+    state.status = `Placement armed: ${formatAssetLabel(asset, assetId)} (${state.transformOperationSettings.placementMode})`;
+    return true;
+}
+function isPlacementArmed(state) {
+    return state.mode === 'editor'
+        && !!state.armedPlacement
+        && state.transformOperationSettings.placementMode !== 'off';
+}
+function previewArmedPlacement(state, event) {
+    if (!isPlacementArmed(state))
+        return false;
+    const hit = pickArmedPlacementHit(state, event);
+    state.gizmo?.setPlacementMarker(hit);
+    const mode = state.transformOperationSettings.placementMode;
+    state.status = hit
+        ? `Placement ${mode}: ${formatVec3(hit.position)}`
+        : `Placement ${mode}: no hit`;
+    return true;
+}
+function commitArmedPlacement(state, options, event) {
+    if (!isPlacementArmed(state) || !state.session)
+        return false;
+    const armed = state.armedPlacement;
+    const session = state.session;
+    const beforeDocument = session.getState().workingDocument;
+    const hit = pickArmedPlacementHit(state, event);
+    if (!armed || !hit) {
+        state.gizmo?.setPlacementMarker(null);
+        state.status = 'Placement rejected: no hit';
+        return true;
+    }
+    const patch = options.documentAdapter.createPlacedAssetPatch?.({
+        document: beforeDocument,
+        asset: armed.asset,
+        hit,
+    });
+    if (!patch) {
+        state.status = 'Placement rejected: document adapter does not support placed assets';
+        return true;
+    }
+    const result = session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `Place ${armed.assetId}`,
+        patch: patch.patch,
+        targetId: patch.createdId ?? undefined,
+    });
+    if (!result.documentChanged) {
+        state.status = 'Placement unchanged';
+        return true;
+    }
+    const createdId = patch.createdId
+        ?? options.documentAdapter.findCreatedId?.(beforeDocument, result.workingDocument)
+        ?? null;
+    let selection = result.selection;
+    if (createdId && isNodeSelectableInDocument(options, result.workingDocument, createdId)) {
+        selection = session.dispatch({
+            type: 'selection.replace',
+            selectedIds: [createdId],
+            activeId: createdId,
+            label: 'Select Placed Item',
+        }).selection;
+    }
+    else {
+        selection = sanitizeSelection(state, options, result.workingDocument, selection) ?? selection;
+    }
+    clearArmedPlacement(state);
+    rebuildProjectionFromDocument(state, options, result.workingDocument, selection);
+    state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
+    state.status = patch.label ?? `Placed ${formatAssetLabel(armed.asset, armed.assetId)} at ${formatVec3(hit.position)}`;
+    return true;
+}
+function pickArmedPlacementHit(state, event) {
+    const mode = state.transformOperationSettings.placementMode;
+    return mode === 'off'
+        ? null
+        : state.gizmo?.pickPlacementHit(event.clientX, event.clientY, mode) ?? null;
+}
+function clearArmedPlacement(state) {
+    state.armedPlacement = null;
+    state.gizmo?.setPlacementMarker(null);
+}
+function addAssetToDocument(state, options, assetId, createOptions = {}) {
+    if (state.mode !== 'editor') {
+        state.status = 'Asset creation rejected: editor is not active';
+        return { ok: false, assetId, changed: false, status: state.status, error: 'editor_not_active' };
+    }
+    cancelActiveOperation(state);
+    const session = state.session;
+    const beforeDocument = session?.getState().workingDocument;
+    if (!session || !beforeDocument) {
+        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);
+    if (!asset) {
+        state.status = `Asset creation rejected: ${assetId} not found`;
+        return { ok: false, assetId, changed: false, status: state.status, error: 'asset_not_found' };
+    }
+    const patch = options.documentAdapter.createPatchFromAsset(asset, {
+        document: beforeDocument,
+        asset,
+        assetId,
+        placement: createOptions.placement,
+    });
     const result = session.dispatch({
         type: 'document.patch',
         label: patch.label ?? 'Create Object From Asset',
@@ -832,6 +1713,9 @@ function addAssetToDocument(state, options, assetId) {
     }
     state.summary = summarizeDocument(options, result.workingDocument, session.getSource());
     state.status = `Added ${assetId}`;
+    state.statusTone = 'success';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
     if (createdId) {
         const projectedNode = options.documentAdapter.getProjectionNode(result.workingDocument, createdId);
         if (projectedNode) {
@@ -840,7 +1724,13 @@ function addAssetToDocument(state, options, assetId) {
                 syncSelectionToProjection(state, selectionResult.selection);
         }
     }
-    return true;
+    return {
+        ok: true,
+        assetId,
+        changed: result.documentChanged,
+        status: state.status,
+        createdId: createdId ?? null,
+    };
 }
 function patchSerializedProperty(state, options, input) {
     if (state.mode !== 'editor')
@@ -971,6 +1861,86 @@ function findInspectorPropertyByPath(inspector, path) {
     }
     return null;
 }
+function beginDuplicateDrag(state, options, input) {
+    if (state.mode !== 'editor' || !state.session)
+        return null;
+    if (state.duplicateDrag)
+        return null;
+    const document = state.session.getState().workingDocument;
+    const patch = options.documentAdapter.createDuplicateSelectionPatch?.({
+        document,
+        targetIds: input.targetIds,
+        activeId: input.activeId,
+        transforms: input.beforeTransforms,
+    });
+    if (!patch || patch.createdIds.length === 0) {
+        state.status = 'Duplicate drag rejected';
+        return null;
+    }
+    const originalSelection = state.session.getSelection();
+    const result = state.session.dispatch({
+        type: 'document.patch',
+        label: patch.label ?? `Duplicate ${input.targetIds.length} object(s)`,
+        patch: patch.patch,
+        targetId: patch.activeId ?? patch.createdIds[patch.createdIds.length - 1] ?? undefined,
+    });
+    if (!result.documentChanged) {
+        state.status = 'Duplicate drag unchanged';
+        return null;
+    }
+    const createdIds = patch.createdIds.filter(id => isNodeSelectableInDocument(options, result.workingDocument, id));
+    if (createdIds.length === 0) {
+        const undone = state.session.undo();
+        if (undone)
+            rebuildProjectionFromDocument(state, options, undone.workingDocument, originalSelection);
+        state.status = 'Duplicate drag rejected: duplicated selection is not selectable';
+        return null;
+    }
+    const activeId = patch.activeId && createdIds.includes(patch.activeId)
+        ? patch.activeId
+        : createdIds[createdIds.length - 1] ?? null;
+    const selectionResult = state.session.dispatch({
+        type: 'selection.replace',
+        selectedIds: createdIds,
+        activeId,
+        label: 'Select Duplicate Drag Targets',
+    });
+    state.duplicateDrag = {
+        originalSelection,
+        createdIds,
+        activeId,
+    };
+    rebuildProjectionFromDocument(state, options, result.workingDocument, selectionResult.selection);
+    if (patch.reprojectIds?.length)
+        reprojectProjectionForChangedIds(state, options, result.workingDocument, patch.reprojectIds);
+    else
+        syncProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds ?? createdIds);
+    state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
+    state.status = patch.label ?? `Duplicated ${createdIds.length} object(s)`;
+    return {
+        targetIds: createdIds,
+        activeId,
+    };
+}
+function cancelDuplicateDrag(state, options) {
+    const duplicate = state.duplicateDrag;
+    if (!duplicate || !state.session)
+        return false;
+    state.duplicateDrag = null;
+    const undone = state.session.undo();
+    if (!undone)
+        return false;
+    const selectionResult = state.session.dispatch({
+        type: 'selection.replace',
+        selectedIds: duplicate.originalSelection.selectedIds,
+        activeId: duplicate.originalSelection.activeId,
+        label: 'Restore Duplicate Drag Selection',
+    });
+    rebuildProjectionFromDocument(state, options, undone.workingDocument, selectionResult.selection);
+    state.summary = summarizeDocument(options, undone.workingDocument, state.session.getSource());
+    state.status = `Canceled duplicate drag ${duplicate.createdIds.length} object(s)`;
+    return true;
+}
 function commitGizmoTransform(state, options, event) {
     if (state.mode !== 'editor' || !state.session)
         return false;
@@ -981,8 +1951,10 @@ function commitGizmoTransform(state, options, event) {
             document,
         });
         if (!patch) {
-            restoreBatchTransformPreview(state, event.targets);
-            state.status = `Ignored ${event.tool} ${event.targetIds.length} objects`;
+            if (!cancelDuplicateDrag(state, options)) {
+                restoreBatchTransformPreview(state, event.targets);
+                state.status = `Ignored ${event.tool} ${event.targetIds.length} objects`;
+            }
             return false;
         }
         const result = state.session.dispatch({
@@ -990,11 +1962,14 @@ function commitGizmoTransform(state, options, event) {
             label: patch.label ?? `${event.tool} ${event.targetIds.length} objects`,
             patch: patch.patch,
             targetId: event.activeId ?? undefined,
+        }, {
+            mergeWithPrevious: event.targetIds.some(id => state.duplicateDrag?.createdIds.includes(id)) === true,
         });
         syncProjectionForDispatchResult(state, options, result);
         syncProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds ?? event.targetIds);
         state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
         state.status = patch.label ?? `${event.tool} ${event.targetIds.length} objects`;
+        state.duplicateDrag = null;
         return result.documentChanged;
     }
     const patch = options.documentAdapter.createTransformPatch?.({
@@ -1002,12 +1977,15 @@ function commitGizmoTransform(state, options, event) {
         targetId: event.nodeId,
         tool: event.tool,
         space: event.space,
+        constraint: event.constraint,
         before: event.before,
         after: event.after,
     });
     if (!patch) {
-        state.projection?.setNodeTransformPreview(event.nodeId, event.before);
-        state.status = `Ignored ${event.tool} ${event.nodeId}`;
+        if (!cancelDuplicateDrag(state, options)) {
+            state.projection?.setNodeTransformPreview(event.nodeId, event.before);
+            state.status = `Ignored ${event.tool} ${event.nodeId}`;
+        }
         return false;
     }
     const result = state.session.dispatch({
@@ -1015,6 +1993,8 @@ function commitGizmoTransform(state, options, event) {
         label: patch.label ?? `${event.tool} ${event.nodeId}`,
         patch: patch.patch,
         targetId: event.nodeId,
+    }, {
+        mergeWithPrevious: state.duplicateDrag?.createdIds.includes(event.nodeId) === true,
     });
     if (patch.changedIds)
         syncProjectionForChangedIds(state, options, result.workingDocument, patch.changedIds);
@@ -1022,6 +2002,7 @@ function commitGizmoTransform(state, options, event) {
         syncProjectionForDispatchResult(state, options, result, patch.changedId ?? event.nodeId);
     state.summary = summarizeDocument(options, result.workingDocument, state.session.getSource());
     state.status = patch.label ?? `${event.tool} ${event.nodeId}`;
+    state.duplicateDrag = null;
     return result.documentChanged;
 }
 function isTransformBatchCommit(event) {
@@ -1040,6 +2021,22 @@ function cancelActiveOperation(state) {
     state.sceneViewInput?.cancelActiveIntent();
     state.selectionController?.cancelBoxSelection();
     cancelActiveGizmoDrag(state);
+    clearArmedPlacement(state);
+}
+function cancelEditorIntent(state, options) {
+    if (state.mode !== 'editor')
+        return false;
+    if (state.viewportTools.activeUtilityTool === 'measure-distance'
+        || state.viewportMeasurement.start
+        || state.viewportMeasurement.end) {
+        return clearViewportMeasurement(state);
+    }
+    const selection = state.session?.getSelection();
+    if (selection && selection.selectedIds.length > 0) {
+        return dispatchSelectionCommand(state, options, { type: 'selection.clear', label: 'Clear Selection' });
+    }
+    cancelActiveOperation(state);
+    return true;
 }
 function focusSelectedProjection(state) {
     if (state.mode !== 'editor')
@@ -1072,6 +2069,17 @@ function formatEditorStatusTime(timestamp) {
     const pad = (value) => String(value).padStart(2, '0');
     return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
 }
+function formatVec3(value) {
+    return `${formatPlacementNumber(value.x)}, ${formatPlacementNumber(value.y)}, ${formatPlacementNumber(value.z)}`;
+}
+function formatPlacementNumber(value) {
+    return Number.isFinite(value) ? Number(value.toFixed(3)).toString() : String(value);
+}
+function formatAssetLabel(asset, fallback) {
+    const record = isObjectRecord(asset) ? asset : null;
+    const label = record?.label ?? record?.displayName ?? record?.name;
+    return typeof label === 'string' && label.trim() ? label : fallback;
+}
 function undoSessionChange(state, options) {
     cancelActiveOperation(state);
     const result = state.session?.undo();
@@ -1083,7 +2091,7 @@ function undoSessionChange(state, options) {
     return true;
 }
 function redoSessionChange(state, options) {
-    cancelActiveGizmoDrag(state);
+    cancelActiveOperation(state);
     const result = state.session?.redo();
     if (!result)
         return false;
@@ -1134,6 +2142,92 @@ function reprojectProjectionForChangedIds(state, options, document, changedIds)
     syncSelectionToProjection(state, selection);
     state.gizmo?.refreshSelection();
 }
+function setSceneCameraPreviewEnabled(state, options, enabled) {
+    if (!enabled) {
+        state.sceneCameraPreviewEnabled = false;
+        state.sceneCameraPreview?.setActive(false);
+        state.status = 'Scene Camera preview disabled';
+        return true;
+    }
+    state.sceneCameraPreviewEnabled = true;
+    if (!syncSceneCameraPreview(state, options)) {
+        state.sceneCameraPreviewEnabled = false;
+        state.status = 'Scene Camera preview unavailable';
+        state.statusTone = 'warning';
+        state.statusToneStatus = state.status;
+        state.statusDetails = 'The current document did not provide a Main Camera preview rig.';
+        return true;
+    }
+    state.status = 'Scene Camera preview enabled';
+    return true;
+}
+function setGridVisible(state, visible) {
+    const nextVisible = visible === true;
+    if (state.gridVisible === nextVisible)
+        return false;
+    state.gridVisible = nextVisible;
+    state.grid?.setVisible(nextVisible);
+    state.status = nextVisible ? 'Grid visible' : 'Grid hidden';
+    state.statusTone = 'default';
+    state.statusToneStatus = state.status;
+    state.statusDetails = '';
+    return true;
+}
+function syncSceneCameraPreview(state, options) {
+    const controller = state.sceneCameraPreview;
+    if (!controller)
+        return false;
+    if (!state.sceneCameraPreviewEnabled) {
+        controller.setActive(false);
+        return false;
+    }
+    const document = state.session?.getState().workingDocument ?? null;
+    const rig = document ? options.documentAdapter.getSceneCameraPreviewRig?.(document) ?? null : null;
+    if (!rig) {
+        controller.setActive(false);
+        return false;
+    }
+    controller.setActive(true, rig);
+    return controller.isActive();
+}
+function syncViewportCameraState(state) {
+    const cameraState = state.sceneViewCamera?.getState();
+    if (!cameraState)
+        return;
+    state.viewportTools = {
+        ...state.viewportTools,
+        viewPreset: cameraState.viewPreset,
+        projectionMode: cameraState.projectionMode,
+    };
+}
+function syncViewportSpatialOverlay(state) {
+    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) {
+        state.viewportSpatialOverlay = createEmptyEditorViewportSpatialOverlayState();
+        return;
+    }
+    const bounds = state.projection?.getSelectionBounds([activeId]) ?? null;
+    const anchor = state.projection?.readNodeTransform(activeId)?.position ?? bounds?.center ?? null;
+    state.viewportSpatialOverlay = overlay.compute({
+        nodeId: activeId,
+        bounds,
+        anchor,
+        settings: state.viewportTools.overlay,
+    });
+}
+function syncViewportMeasurementState(state) {
+    if (state.mode !== 'editor')
+        return;
+    const measurement = state.sceneViewMeasurement?.getState();
+    if (measurement)
+        state.viewportMeasurement = measurement;
+}
+function hasSceneCameraPreviewRig(state, options) {
+    const document = state.session?.getState().workingDocument ?? null;
+    return !!document && !!options.documentAdapter.getSceneCameraPreviewRig?.(document);
+}
 function createUiState(state, options) {
     const sessionState = state.session?.getState();
     const document = sessionState?.workingDocument ?? null;
@@ -1181,6 +2275,9 @@ function createUiState(state, options) {
         inspectorObject,
         inspectorMultiObject,
         boxSelection: state.boxSelection,
+        coordinateAxes: options.world?.coordinateAxes === false
+            ? null
+            : createSceneViewCoordinateAxesState(state),
         transformTool: {
             activeTool: state.gizmo?.getState().tool ?? state.transformTool,
             activeSpace: state.gizmo?.getState().space ?? state.transformSpace,
@@ -1188,6 +2285,24 @@ function createUiState(state, options) {
             dragPhase: state.gizmo?.getState().dragPhase ?? 'idle',
             draggingNodeId: state.gizmo?.getState().draggingNodeId ?? null,
         },
+        transformOperations: {
+            settings: cloneTransformOperationSettings(state.transformOperationSettings),
+            selectedCount: selectedIds.length,
+            activeId,
+            canAlign: selectedIds.length >= 2 && activeId != null,
+            canDistribute: selectedIds.length >= 3,
+        },
+        viewportTools: cloneEditorViewportToolState(state.viewportTools),
+        viewportMeasurement: cloneViewportMeasurement(state.viewportMeasurement),
+        viewportSpatialOverlay: cloneEditorViewportSpatialOverlayState(state.viewportSpatialOverlay),
+        sceneCameraPreview: {
+            enabled: state.sceneCameraPreviewEnabled,
+            available: hasSceneCameraPreviewRig(state, options),
+        },
+        grid: {
+            visible: state.gridVisible,
+            available: !!state.grid,
+        },
         session: sessionState
             ? {
                 source: sessionState.source,
@@ -1199,6 +2314,89 @@ function createUiState(state, options) {
             : null,
     };
 }
+function createSceneViewCoordinateAxesState(state) {
+    if (state.mode !== 'editor')
+        return null;
+    const scene = state.world?.scene ?? null;
+    const camera = scene?.activeCamera ?? state.world?.camera ?? null;
+    const Vector3 = state.babylon?.Vector3;
+    if (!scene || !camera || !Vector3)
+        return null;
+    const right = readSceneViewCameraDirection(camera, Vector3, { x: 1, y: 0, z: 0 });
+    const up = readSceneViewCameraDirection(camera, Vector3, { x: 0, y: 1, z: 0 });
+    const forward = readSceneViewCameraForward(scene, camera, Vector3);
+    if (!right || !up || !forward)
+        return null;
+    return {
+        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),
+            createSceneViewCoordinateAxis('z', 'Z', '#4f86ff', { x: 0, y: 0, z: 1 }, right, up, forward),
+        ],
+    };
+}
+function createSceneViewCoordinateAxis(id, label, color, worldAxis, cameraRight, cameraUp, cameraForward) {
+    const screenX = dotSceneViewAxisVec3(worldAxis, cameraRight);
+    const screenY = -dotSceneViewAxisVec3(worldAxis, cameraUp);
+    const projectedLength = Math.hypot(screenX, screenY);
+    const fallback = getSceneViewAxisFallbackDirection(id);
+    const direction = projectedLength > 0.0001
+        ? { x: screenX / projectedLength, y: screenY / projectedLength }
+        : fallback;
+    return {
+        id,
+        label,
+        color,
+        x: direction.x,
+        y: direction.y,
+        depth: dotSceneViewAxisVec3(worldAxis, cameraForward),
+        scale: clampNumber(projectedLength, 0.36, 1),
+    };
+}
+function readSceneViewCameraDirection(camera, Vector3, local) {
+    if (!camera?.getDirection)
+        return null;
+    try {
+        return normalizeSceneViewAxisVec3(camera.getDirection(new Vector3(local.x, local.y, local.z)));
+    }
+    catch {
+        return null;
+    }
+}
+function readSceneViewCameraForward(scene, camera, Vector3) {
+    const rayDirection = normalizeSceneViewAxisVec3(camera?.getForwardRay?.()?.direction);
+    if (rayDirection)
+        return rayDirection;
+    return readSceneViewCameraDirection(camera, Vector3, {
+        x: 0,
+        y: 0,
+        z: scene?.useRightHandedSystem ? -1 : 1,
+    });
+}
+function normalizeSceneViewAxisVec3(value) {
+    const x = Number(value?.x) || 0;
+    const y = Number(value?.y) || 0;
+    const z = Number(value?.z) || 0;
+    const length = Math.hypot(x, y, z);
+    if (!Number.isFinite(length) || length <= 0.000001)
+        return null;
+    return { x: x / length, y: y / length, z: z / length };
+}
+function dotSceneViewAxisVec3(left, right) {
+    return left.x * right.x + left.y * right.y + left.z * right.z;
+}
+function getSceneViewAxisFallbackDirection(id) {
+    if (id === 'x')
+        return { x: 1, y: 0 };
+    if (id === 'y')
+        return { x: 0, y: -1 };
+    return { x: -1, y: 0 };
+}
+function clampNumber(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, value));
+}
 function withRuntimeInspectorSections(state, options, document, inspectorObject) {
     const baseInspectorObject = withInspectorComponentSections(state, options, document, inspectorObject);
     const activeId = inspectorObject.activeId;