@vgai/editor 0.2.0

package/src/editor-viewport.ts

@@ -0,0 +1,1924 @@
+import { resolveUrl } from '@engine/loader';
+import { tickCustomMaterials } from '@engine/scene/material-registry';
+import type { SceneEntity } from '@engine/scene/scene-types';
+import { getUserData, setUserData } from '@engine/scene/user-data';
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { TransformControls } from 'three/addons/controls/TransformControls.js';
+import { BatchedRenderer } from 'three.quarks';
+import { getActiveAuthoring } from './authoring/active-adapter';
+import { pickTopmost } from './authoring/layered-pick';
+import { setViewportPickContext } from './authoring/viewport-pick-context';
+import { downloadOnlineAsset, getDownloadedAssetPath, getOnlineAssetFiles } from './editor-api';
+import { EDITOR_LAYER } from './editor-layers';
+import type { EditorStore } from './editor-store';
+import { applyEntityGizmos } from './gizmo-registry';
+import {
+  createHandleDefs,
+  createHandleMesh,
+  type HandleMesh,
+  scaleHandle,
+  setHandleHovered,
+} from './handle-system';
+
+/** A BoxHelper or LineSegments wireframe tagged with its source entity object. */
+interface TaggedHelper extends THREE.BoxHelper {
+  isBoxHelper: boolean;
+  _entityObj?: THREE.Object3D;
+}
+
+/** View directions indexed by click-target userData. */
+const VC_DIRS: THREE.Vector3[] = [
+  /* 0 +X */ new THREE.Vector3(1, 0, 0),
+  /* 1 -X */ new THREE.Vector3(-1, 0, 0),
+  /* 2 +Y */ new THREE.Vector3(0, 1, 0),
+  /* 3 -Y */ new THREE.Vector3(0, -1, 0),
+  /* 4 +Z */ new THREE.Vector3(0, 0, 1),
+  /* 5 -Z */ new THREE.Vector3(0, 0, -1),
+];
+
+export class EditorViewport {
+  readonly camera: THREE.PerspectiveCamera;
+  readonly orbitControls: OrbitControls;
+  readonly transformControls: TransformControls;
+  readonly raycaster = (() => {
+    const r = new THREE.Raycaster();
+    r.layers.enableAll();
+    return r;
+  })();
+  readonly grid: THREE.GridHelper;
+  private _boxHelpers = new Map<string, THREE.BoxHelper>();
+  private _gizmoHelper: THREE.Object3D;
+  private _editorAmbient: THREE.AmbientLight;
+  private _editorDirLight: THREE.DirectionalLight;
+
+  private _scene: THREE.Scene;
+  /** Editor infrastructure objects that must move with the active scene. */
+  private _editorObjects: THREE.Object3D[] = [];
+  private _store: EditorStore;
+  private _objectMap = new Map<string, THREE.Object3D>();
+  private _canvas: HTMLCanvasElement;
+  private _pointerDownPos = new THREE.Vector2();
+  private _skipNextSync = false;
+
+  // -- Marquee select --
+  private _marqueeActive = false;
+  private _marqueeDiv: HTMLDivElement | null = null;
+  private _pointerDownButton = -1;
+  private _altDragOrbit = false;
+
+  // -- Orientation gizmo --
+  private _vcScene = new THREE.Scene();
+  private _vcCamera: THREE.OrthographicCamera;
+  private _vcClickTargets: THREE.Mesh[] = [];
+  private _vcSize = 110;
+  private _vcMarginRight = 16;
+  private _vcMarginTop = 36 + 16;
+  /** Scratch dir vector reused each frame by renderViewCube (avoids per-frame alloc). */
+  private _vcDir = new THREE.Vector3();
+  /** Scratch color reused by renderCameraPreview (avoids per-frame alloc). */
+  private _previewClearColor = new THREE.Color();
+  /** Last objectMap + visibility signature applied by syncFromStore's gizmo/helper
+   *  passes — lets those O(scene) loops skip when their inputs are unchanged (e.g.
+   *  during a transform drag, which notifies per frame but changes none of them). */
+  private _lastGizmoObjectMap: Map<string, THREE.Object3D> | null = null;
+  private _lastGizmoSig = '';
+  private _vcRaycaster = new THREE.Raycaster();
+
+  // -- Asset drop --
+  private _dropOverlay: HTMLDivElement | null = null;
+  private _groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+
+  // -- Multi-drag: track primary object's transform at drag start --
+  private _dragStartPos = new THREE.Vector3();
+  private _dragStartQuat = new THREE.Quaternion();
+  private _dragStartScale = new THREE.Vector3();
+  private _otherDragObjects: {
+    obj: THREE.Object3D;
+    startPos: THREE.Vector3;
+    startQuat: THREE.Quaternion;
+    startScale: THREE.Vector3;
+  }[] = [];
+  private _allDragObjects: {
+    obj: THREE.Object3D;
+    startPos: THREE.Vector3;
+    startQuat: THREE.Quaternion;
+    startScale: THREE.Vector3;
+  }[] = [];
+  private _pivotDummy = new THREE.Object3D();
+  private _pivotPos = new THREE.Vector3();
+
+  // -- Surface snap --
+  private _surfaceSnapRaycaster = new THREE.Raycaster();
+  private _surfaceSnapIndicator: THREE.Mesh;
+
+  // -- Vertex snap --
+  private _vertexSnapTargets: THREE.Vector3[] = [];
+  private _vertexSnapIndicator!: THREE.Mesh;
+  private _vertexSnapThreshold = 20; // pixels
+
+  // -- Component handles (interactive gizmos for light range, audio distance, etc.) --
+  private _handles: HandleMesh[] = [];
+  private _handleRaycaster = new THREE.Raycaster();
+  private _handleDragActive = false;
+  private _activeHandle: HandleMesh | null = null;
+  private _handleDragPlane = new THREE.Plane();
+  private _handleDragOffset = new THREE.Vector3();
+  private _hoveredHandle: HandleMesh | null = null;
+
+  // -- Particles --
+  readonly batchedRenderer: BatchedRenderer;
+
+  // -- NavMesh helper (scene-root, toggled separately) --
+  private _navMeshHelper: THREE.Object3D | null = null;
+
+  // -- Snap-to-view animation --
+  private _snapAnimating = false;
+  private _snapStartTime = 0;
+  private _snapDuration = 400;
+  private _snapQ1 = new THREE.Quaternion();
+  private _snapQ2 = new THREE.Quaternion();
+  private _snapDist = 0;
+
+  // -- Fly camera (right-click + WASD) --
+  private _flyActive = false;
+  private _flyKeys = new Set<string>();
+  private _flySpeed = 5;
+  private _flyEuler = new THREE.Euler(0, 0, 0, 'YXZ');
+  private _rightMouseDown = false;
+
+  constructor(canvas: HTMLCanvasElement, scene: THREE.Scene, store: EditorStore) {
+    this._canvas = canvas;
+    this._scene = scene;
+    this._store = store;
+
+    // Camera — enableAll so editor sees both game content (layer 0) and editor objects (layer 31)
+    this.camera = new THREE.PerspectiveCamera(
+      60,
+      canvas.clientWidth / canvas.clientHeight,
+      0.1,
+      1000,
+    );
+    this.camera.position.set(10, 10, 10);
+    this.camera.lookAt(0, 0, 0);
+    this.camera.layers.enableAll();
+
+    // Grid
+    this.grid = new THREE.GridHelper(50, 50, 0x999999, 0x999999);
+    this.grid.layers.set(EDITOR_LAYER);
+    scene.add(this.grid);
+
+    // Editor lighting (on EDITOR_LAYER so game camera doesn't see them)
+    this._editorAmbient = new THREE.AmbientLight(0xffffff, 0.5);
+    this._editorAmbient.layers.set(EDITOR_LAYER);
+    scene.add(this._editorAmbient);
+    this._editorDirLight = new THREE.DirectionalLight(0xffffff, 1.0);
+    this._editorDirLight.position.set(10, 20, 10);
+    this._editorDirLight.layers.set(EDITOR_LAYER);
+    scene.add(this._editorDirLight);
+
+    // Particle BatchedRenderer
+    this.batchedRenderer = new BatchedRenderer();
+    this.batchedRenderer.layers.set(EDITOR_LAYER);
+    scene.add(this.batchedRenderer);
+
+    // OrbitControls – Unity-style: right-drag = orbit, middle-drag = pan, scroll = zoom
+    this.orbitControls = new OrbitControls(this.camera, canvas);
+    this.orbitControls.enableDamping = true;
+    this.orbitControls.dampingFactor = 0.1;
+    this.orbitControls.mouseButtons = {
+      LEFT: -1 as THREE.MOUSE,
+      MIDDLE: THREE.MOUSE.PAN,
+      RIGHT: THREE.MOUSE.ROTATE,
+    };
+
+    // TransformControls
+    this.transformControls = new TransformControls(this.camera, canvas);
+    // Enable all layers on the internal raycaster so it can pick gizmo parts on EDITOR_LAYER
+    this.transformControls.getRaycaster().layers.enableAll();
+    this.transformControls.addEventListener('dragging-changed', (event) => {
+      const dragging = (event as unknown as { value: boolean }).value;
+      this.orbitControls.enabled = !dragging;
+      if (dragging) {
+        const gizmoObj = this.transformControls.object;
+        const primaryDragId =
+          (gizmoObj && (getUserData(gizmoObj, 'entityId') as string | undefined)) || '';
+        // Gizmo-commit routes through the AuthoringAdapter: beginEdit snapshots
+        // for undo and is the hook where a physics-owned object gets frozen for a
+        // stable edit (ingest / Phase E); endEdit commits at drag-end.
+        getActiveAuthoring(this._store).transforms?.beginEdit(primaryDragId);
+        if (gizmoObj) {
+          this._dragStartPos.copy(gizmoObj.position);
+          this._dragStartQuat.copy(gizmoObj.quaternion);
+          this._dragStartScale.copy(gizmoObj.scale);
+          this._otherDragObjects = [];
+          this._allDragObjects = [];
+          this._pivotPos.copy(gizmoObj.position);
+          const primaryId = getUserData(gizmoObj, 'entityId') as string | undefined;
+          if (!primaryId) {
+            // Gizmo on pivot dummy (median-point mode or per-entity pivot)
+            for (const id of this._store.selectedEntityIds) {
+              const obj = this._objectMap.get(id);
+              if (!obj) continue;
+              this._allDragObjects.push({
+                obj,
+                startPos: obj.position.clone(),
+                startQuat: obj.quaternion.clone(),
+                startScale: obj.scale.clone(),
+              });
+            }
+          } else {
+            for (const id of this._store.selectedEntityIds) {
+              if (id === primaryId) continue;
+              const obj = this._objectMap.get(id);
+              if (!obj) continue;
+              this._otherDragObjects.push({
+                obj,
+                startPos: obj.position.clone(),
+                startQuat: obj.quaternion.clone(),
+                startScale: obj.scale.clone(),
+              });
+            }
+          }
+        }
+      } else {
+        // Hide snap indicators when drag ends
+        this._surfaceSnapIndicator.visible = false;
+        this._vertexSnapIndicator.visible = false;
+        // After drag ends, re-sync for median-point pivot repositioning
+        this.syncFromStore();
+      }
+    });
+    this.transformControls.addEventListener('objectChange', () => {
+      const gizmoObj = this.transformControls.object;
+      if (!gizmoObj) return;
+      const mode = this.transformControls.mode;
+      const isIndividual = this._store.pivotMode === 'individual-origins';
+      const isMedian = this._allDragObjects.length > 0;
+      const targets = isMedian ? this._allDragObjects : this._otherDragObjects;
+      if (targets.length > 0) {
+        if (mode === 'translate') {
+          const delta = gizmoObj.position.clone().sub(this._dragStartPos);
+          for (const { obj, startPos } of targets) {
+            obj.position.copy(startPos).add(delta);
+          }
+        } else if (mode === 'rotate') {
+          const deltaQuat = gizmoObj.quaternion
+            .clone()
+            .multiply(this._dragStartQuat.clone().invert());
+          if (isIndividual) {
+            // Individual origins: only rotate, no position orbiting
+            for (const { obj, startQuat } of targets) {
+              obj.quaternion.copy(deltaQuat).multiply(startQuat);
+            }
+          } else {
+            // Active element / Median: orbit positions around pivot + rotate
+            for (const { obj, startPos, startQuat } of targets) {
+              const offset = startPos.clone().sub(this._pivotPos);
+              offset.applyQuaternion(deltaQuat);
+              obj.position.copy(this._pivotPos).add(offset);
+              obj.quaternion.copy(deltaQuat).multiply(startQuat);
+            }
+          }
+        } else if (mode === 'scale') {
+          const deltaScale = new THREE.Vector3(
+            this._dragStartScale.x !== 0 ? gizmoObj.scale.x / this._dragStartScale.x : 1,
+            this._dragStartScale.y !== 0 ? gizmoObj.scale.y / this._dragStartScale.y : 1,
+            this._dragStartScale.z !== 0 ? gizmoObj.scale.z / this._dragStartScale.z : 1,
+          );
+          if (isIndividual) {
+            // Individual origins: only scale, no position change
+            for (const { obj, startScale } of targets) {
+              obj.scale.copy(startScale).multiply(deltaScale);
+            }
+          } else {
+            // Active element / Median: scale from pivot + scale objects
+            for (const { obj, startPos, startScale } of targets) {
+              const offset = startPos.clone().sub(this._pivotPos);
+              offset.multiply(deltaScale);
+              obj.position.copy(this._pivotPos).add(offset);
+              obj.scale.copy(startScale).multiply(deltaScale);
+            }
+          }
+        }
+      }
+      // Vertex snap takes priority over surface snap
+      if (
+        mode === 'translate' &&
+        this._store.vertexSnapActive &&
+        this._vertexSnapTargets.length > 0
+      ) {
+        this._applyVertexSnap(gizmoObj, targets);
+      } else if (mode === 'translate' && this._store.snapToSurface) {
+        this._applySurfaceSnap(gizmoObj, targets);
+      }
+
+      for (const helper of this._boxHelpers.values()) {
+        if ('update' in helper) (helper as THREE.BoxHelper).update();
+      }
+      this._flushGizmoToStoreLive();
+    });
+    this.transformControls.addEventListener('mouseUp', () => {
+      // Final flush (with skip flag so viewport doesn't rebuild)
+      this._flushGizmoToStore();
+    });
+    this._gizmoHelper = this.transformControls.getHelper();
+    this._gizmoHelper.traverse((child) => child.layers.set(EDITOR_LAYER));
+    scene.add(this._gizmoHelper);
+
+    // Pivot dummy for median-point mode (invisible, just a transform target)
+    this._pivotDummy.layers.set(EDITOR_LAYER);
+    scene.add(this._pivotDummy);
+
+    // Surface snap indicator (small ring shown at snap point)
+    this._surfaceSnapIndicator = new THREE.Mesh(
+      new THREE.RingGeometry(0.08, 0.12, 16),
+      new THREE.MeshBasicMaterial({ color: 0x00ff88, side: THREE.DoubleSide, depthTest: false }),
+    );
+    this._surfaceSnapIndicator.rotation.x = -Math.PI / 2;
+    this._surfaceSnapIndicator.visible = false;
+    this._surfaceSnapIndicator.renderOrder = 999;
+    this._surfaceSnapIndicator.layers.set(EDITOR_LAYER);
+    scene.add(this._surfaceSnapIndicator);
+
+    // Vertex snap indicator (small green sphere shown at snap target vertex)
+    this._vertexSnapIndicator = new THREE.Mesh(
+      new THREE.SphereGeometry(1, 8, 8),
+      new THREE.MeshBasicMaterial({ color: 0x00ffaa, depthTest: false }),
+    );
+    this._vertexSnapIndicator.visible = false;
+    this._vertexSnapIndicator.renderOrder = 999;
+    this._vertexSnapIndicator.layers.set(EDITOR_LAYER);
+    scene.add(this._vertexSnapIndicator);
+
+    // Patch gizmo: recolor handles to Godot axis colors and fix plane geometry.
+    this._patchGizmo(this._gizmoHelper);
+
+    // Orientation gizmo (axis arrows overlay)
+    this._vcCamera = new THREE.OrthographicCamera(-1.5, 1.5, 1.5, -1.5, 0.1, 10);
+    this._initOrientationGizmo();
+
+    // -- Fly camera input (right-click + WASD) --
+    window.addEventListener('keydown', this._onFlyKeyDown);
+    window.addEventListener('keyup', this._onFlyKeyUp);
+    canvas.addEventListener('pointerdown', this._onFlyPointerDown);
+    canvas.addEventListener('pointerup', this._onFlyPointerUp);
+    canvas.addEventListener('pointermove', this._onFlyPointerMove);
+    canvas.addEventListener('wheel', this._onFlyWheel, { passive: false });
+
+    // Alt+Left-drag = orbit (Unity-style), via capture phase so it fires before OrbitControls
+    canvas.addEventListener(
+      'pointerdown',
+      (e) => {
+        if (e.altKey && e.button === 0) {
+          this._altDragOrbit = true;
+          this.orbitControls.mouseButtons.LEFT = THREE.MOUSE.ROTATE;
+        }
+      },
+      { capture: true },
+    );
+    canvas.addEventListener(
+      'pointerup',
+      () => {
+        if (this._altDragOrbit) {
+          this._altDragOrbit = false;
+          this.orbitControls.mouseButtons.LEFT = -1 as THREE.MOUSE;
+        }
+      },
+      { capture: true },
+    );
+
+    // Click to select + marquee
+    canvas.addEventListener('pointerdown', this._onPointerDown);
+    canvas.addEventListener('pointermove', this._onPointerMove);
+    canvas.addEventListener('pointerup', this._onPointerUp);
+
+    // Asset drag-and-drop onto viewport
+    canvas.addEventListener('dragover', this._onDragOver);
+    canvas.addEventListener('dragleave', this._onDragLeave);
+    canvas.addEventListener('drop', this._onDrop);
+
+    // Collect editor infrastructure objects so they can be moved between scenes
+    this._editorObjects = [
+      this.grid,
+      this._editorAmbient,
+      this._editorDirLight,
+      this.batchedRenderer,
+      this._gizmoHelper,
+      this._pivotDummy,
+      this._surfaceSnapIndicator,
+      this._vertexSnapIndicator,
+    ];
+
+    // D12 (B4) — publish the camera/canvas seam `VgaiSceneAuthoringAdapter.pickable`
+    // needs (it has no other way to reach them). Cleared in `dispose()`.
+    setViewportPickContext({ camera: this.camera, canvas: this._canvas });
+  }
+
+  /** Swap the scene the viewport renders. Moves editor infrastructure objects to the new scene. */
+  setScene(newScene: THREE.Scene): void {
+    if (newScene === this._scene) return;
+    // Move editor infrastructure to new scene
+    for (const obj of this._editorObjects) {
+      obj.removeFromParent();
+      newScene.add(obj);
+    }
+    // Move any active handles
+    for (const h of this._handles) {
+      h.removeFromParent();
+      newScene.add(h);
+    }
+    // Move box helpers
+    for (const helper of this._boxHelpers.values()) {
+      helper.removeFromParent();
+      newScene.add(helper);
+    }
+    this._scene = newScene;
+  }
+
+  get currentScene(): THREE.Scene {
+    return this._scene;
+  }
+
+  get objectMap(): Map<string, THREE.Object3D> {
+    return this._objectMap;
+  }
+  set objectMap(map: Map<string, THREE.Object3D>) {
+    this._objectMap = map;
+  }
+
+  /** Attach gizmo to entity by id. */
+  attach(id: string): void {
+    const obj = this._objectMap.get(id);
+    if (!obj) return;
+    this.transformControls.attach(obj);
+  }
+
+  /** Detach gizmo. */
+  detach(): void {
+    this.transformControls.detach();
+  }
+
+  /** Clear and rebuild box helpers for all selected entities. */
+  private _syncBoxHelpers(): void {
+    // Remove old + dispose geometry/materials on rebuild (LK6).
+    for (const helper of this._boxHelpers.values()) {
+      this._scene.remove(helper);
+      helper.geometry.dispose();
+      (helper.material as THREE.Material).dispose();
+    }
+    this._boxHelpers.clear();
+
+    const MIN = 0.5;
+    const color = new THREE.Color(0x579eff);
+
+    // Add new
+    for (const id of this._store.selectedEntityIds) {
+      const obj = this._objectMap.get(id);
+      if (!obj) continue;
+
+      // Check if the entity has enough non-helper geometry for BoxHelper to work.
+      // Cameras, lights, and audio sources only have editorHelper children
+      // whose geometry BoxHelper ignores or produces a degenerate box.
+      let hasVisibleGeometry = false;
+      obj.traverse((child) => {
+        if (getUserData(child, 'editorHelper')) return;
+        if ((child as THREE.Mesh).isMesh || ((child as THREE.Line).isLine && child !== obj)) {
+          hasVisibleGeometry = true;
+        }
+      });
+
+      if (hasVisibleGeometry) {
+        const helper = new THREE.BoxHelper(obj, 0x579eff);
+        helper.layers.set(EDITOR_LAYER);
+        this._scene.add(helper);
+        this._boxHelpers.set(id, helper);
+      } else {
+        // Create a fixed-size wireframe cube for non-mesh entities
+        const geo = new THREE.BoxGeometry(MIN, MIN, MIN);
+        const edges = new THREE.EdgesGeometry(geo);
+        geo.dispose();
+        const mat = new THREE.LineBasicMaterial({ color, toneMapped: false });
+        const wire = new THREE.LineSegments(edges, mat) as unknown as TaggedHelper;
+        wire.layers.set(EDITOR_LAYER);
+        obj.getWorldPosition(wire.position);
+        // Tag so we can update/dispose like BoxHelper
+        wire.isBoxHelper = true;
+        wire._entityObj = obj;
+        this._scene.add(wire);
+        this._boxHelpers.set(id, wire);
+      }
+    }
+  }
+
+  /** Sync mode/space/snap from store. */
+  syncFromStore(): void {
+    // Ensure all gizmo children stay on EDITOR_LAYER (TransformControls rebuilds internally)
+    this._gizmoHelper.traverse((child) => child.layers.set(EDITOR_LAYER));
+
+    const mode = this._store.transformMode;
+    if (this.transformControls.mode !== mode) {
+      this.transformControls.setMode(mode);
+    }
+    this.transformControls.setSpace(this._store.transformSpace);
+    const snap = this._store.snapEnabled;
+    const vals = this._store.snapValues;
+    this.transformControls.setTranslationSnap(snap ? vals.translate : null);
+    this.transformControls.setRotationSnap(snap ? THREE.MathUtils.degToRad(vals.rotate) : null);
+    this.transformControls.setScaleSnap(snap ? vals.scale : null);
+
+    // Grid visibility
+    this.grid.visible = this._store.showGrid;
+
+    // The two passes below (apply gizmos + per-type helper/icon visibility) are
+    // idempotent and O(total scene nodes). Their only inputs are the objectMap
+    // membership and the visibility toggles — none of which change during a
+    // transform drag/scrub (which still fires syncFromStore every frame). Gate
+    // them on a cheap signature so a drag doesn't re-walk the whole graph 60×/s.
+    const vis = this._store.helperVisibility;
+    const gizmoSig = `${this._objectMap.size}|${this._store.showHelpers}|${JSON.stringify(vis)}`;
+    if (this._objectMap !== this._lastGizmoObjectMap || gizmoSig !== this._lastGizmoSig) {
+      this._lastGizmoObjectMap = this._objectMap;
+      this._lastGizmoSig = gizmoSig;
+
+      // Ensure gizmos (icon billboards + wireframe helpers) exist on all objects.
+      // Idempotent — needed for game scene objects created by the runtime without gizmos.
+      for (const obj of this._objectMap.values()) {
+        applyEntityGizmos(obj);
+      }
+
+      // Helper + icon visibility — per-type filtering
+      for (const obj of this._objectMap.values()) {
+        obj.traverse((child) => {
+          if (getUserData(child, 'editorIcon')) {
+            // Icon billboards follow the global helpers toggle
+            child.visible = this._store.showHelpers;
+            return;
+          }
+          if (!getUserData(child, 'editorHelper')) return;
+          const type = getUserData(child, 'editorHelperType') as string | undefined;
+          if (type && type in vis) {
+            child.visible = vis[type as keyof typeof vis];
+          } else {
+            child.visible = this._store.showHelpers;
+          }
+        });
+      }
+      // NavMesh helper is a scene-root object, toggle separately
+      if (this._navMeshHelper) {
+        this._navMeshHelper.visible = vis.navmesh;
+      }
+    }
+
+    // Attach gizmo based on pivot mode
+    const selectedId = this._store.selectedEntityId;
+    if (selectedId) {
+      if (!this.transformControls.dragging) {
+        if (this._store.pivotMode === 'median-point' && this._store.selectedEntityIds.size > 1) {
+          const median = new THREE.Vector3();
+          let count = 0;
+          for (const id of this._store.selectedEntityIds) {
+            const obj = this._objectMap.get(id);
+            if (obj) {
+              median.add(obj.position);
+              count++;
+            }
+          }
+          if (count > 0) median.divideScalar(count);
+          this._pivotDummy.position.copy(median);
+          this._pivotDummy.quaternion.identity();
+          this._pivotDummy.scale.set(1, 1, 1);
+          this.transformControls.attach(this._pivotDummy);
+        } else {
+          // Check for per-entity pivot
+          const obj = this._objectMap.get(selectedId);
+          const entityPivot = getUserData(obj, 'pivot') as [number, number, number] | undefined;
+          const hasPivot =
+            entityPivot && (entityPivot[0] !== 0 || entityPivot[1] !== 0 || entityPivot[2] !== 0);
+
+          if (hasPivot && obj) {
+            // Position dummy at pivot's world location
+            const pivotLocal = new THREE.Vector3(entityPivot[0], entityPivot[1], entityPivot[2]);
+            pivotLocal.applyQuaternion(obj.quaternion);
+            this._pivotDummy.position.copy(obj.position).add(pivotLocal);
+            this._pivotDummy.quaternion.copy(obj.quaternion);
+            this._pivotDummy.scale.copy(obj.scale);
+            this.transformControls.attach(this._pivotDummy);
+          } else {
+            this.attach(selectedId);
+          }
+        }
+      }
+    } else {
+      this.detach();
+    }
+
+    // Box helpers for all selected
+    this._syncBoxHelpers();
+
+    // Component handles for selected entities
+    if (!this._handleDragActive) {
+      this._syncHandles();
+    }
+  }
+
+  /**
+   * Re-add editor infrastructure objects to the scene after play mode
+   * has cleared all scene children. Call this after loadDocument restores
+   * entities so the grid, lights, gizmos, and particle renderer are present.
+   */
+  /** Move all editor gizmos from the editor scene into a target scene (e.g. the live game scene). */
+  moveGizmosTo(target: THREE.Scene): void {
+    const objs = this._gizmoObjects();
+    for (const obj of objs) target.add(obj);
+  }
+
+  /** Move all editor gizmos back to the editor scene. */
+  restoreGizmos(): void {
+    const objs = this._gizmoObjects();
+    for (const obj of objs) this._scene.add(obj);
+  }
+
+  /** All editor-layer objects that should travel with the gizmos. */
+  private _gizmoObjects(): THREE.Object3D[] {
+    return [
+      this.grid,
+      this._editorAmbient,
+      this._editorDirLight,
+      this.batchedRenderer,
+      this._gizmoHelper,
+      this._pivotDummy,
+      this._surfaceSnapIndicator,
+    ];
+  }
+
+  /** Focus camera on a given object. */
+  focusOn(obj: THREE.Object3D): void {
+    const box = new THREE.Box3().setFromObject(obj);
+    const center = box.getCenter(new THREE.Vector3());
+    const size = box.getSize(new THREE.Vector3()).length();
+    // Ensure a minimum zoom distance for entities without visible geometry
+    const distance = Math.max(size * 2, 3);
+
+    const dir = this.camera.position.clone().sub(this.orbitControls.target).normalize();
+    this.camera.position.copy(center).add(dir.multiplyScalar(distance));
+    this.orbitControls.target.copy(center);
+  }
+
+  /** Activate vertex snap: collect target vertices from non-selected entities. */
+  activateVertexSnap(): void {
+    this._vertexSnapTargets = this._collectVertices(this._store.selectedEntityIds);
+  }
+
+  /** Deactivate vertex snap: clear collected vertices and hide indicator. */
+  deactivateVertexSnap(): void {
+    this._vertexSnapTargets = [];
+    this._vertexSnapIndicator.visible = false;
+  }
+
+  /** Focus camera on multiple objects. */
+  focusOnMultiple(objects: THREE.Object3D[]): void {
+    if (objects.length === 0) return;
+    if (objects.length === 1) {
+      this.focusOn(objects[0]!);
+      return;
+    }
+    const box = new THREE.Box3();
+    for (const obj of objects) box.expandByObject(obj);
+    const center = box.getCenter(new THREE.Vector3());
+    const size = box.getSize(new THREE.Vector3()).length();
+    const distance = size * 2;
+
+    const dir = this.camera.position.clone().sub(this.orbitControls.target).normalize();
+    this.camera.position.copy(center).add(dir.multiplyScalar(distance));
+    this.orbitControls.target.copy(center);
+  }
+
+  /** Set or clear the navmesh debug helper (managed by editor main). */
+  setNavMeshHelper(helper: THREE.Object3D | null): void {
+    if (this._navMeshHelper) {
+      this._scene.remove(this._navMeshHelper);
+    }
+    this._navMeshHelper = helper;
+    if (helper) {
+      setUserData(helper, 'editorHelper', true);
+      setUserData(helper, 'editorHelperType', 'navmesh');
+      this._scene.add(helper);
+    }
+  }
+
+  /** Snap camera to a preset view direction, preserving current zoom distance. */
+  setViewPreset(preset: 'top' | 'front' | 'right' | 'perspective'): void {
+    const target = this.orbitControls.target.clone();
+    const distance = this.camera.position.distanceTo(target);
+
+    const dir = new THREE.Vector3();
+    switch (preset) {
+      case 'top':
+        dir.set(0, 1, 0);
+        break;
+      case 'front':
+        dir.set(0, 0, 1);
+        break;
+      case 'right':
+        dir.set(1, 0, 0);
+        break;
+      case 'perspective':
+        dir.set(1, 1, 1).normalize();
+        break;
+    }
+
+    this.camera.position.copy(target).add(dir.multiplyScalar(distance));
+    this.camera.lookAt(target);
+    this.orbitControls.update();
+  }
+
+  /**
+   * Move the camera to an arbitrary position/target/fov pose — the general
+   * case `setViewPreset`/`focusOn` don't cover (an exact xyz position, not a
+   * preset direction or a computed frame-to-fit). Backs the `set-camera`
+   * relay command (`editor.viewport.camera.set`'s free-pose mode).
+   */
+  setPose(
+    position: { x: number; y: number; z: number },
+    target: { x: number; y: number; z: number },
+    fov?: number,
+  ): void {
+    this.camera.position.set(position.x, position.y, position.z);
+    this.orbitControls.target.set(target.x, target.y, target.z);
+    this.camera.lookAt(this.orbitControls.target);
+    if (fov !== undefined) {
+      this.camera.fov = fov;
+      this.camera.updateProjectionMatrix();
+    }
+    this.orbitControls.update();
+  }
+
+  /** Handle resize. */
+  resize(width: number, height: number): void {
+    this.camera.aspect = Math.max(1, width) / Math.max(1, height);
+    this.camera.updateProjectionMatrix();
+  }
+
+  update(dt = 0): void {
+    // Animate custom (shader) materials in edit mode — same tick the runtime
+    // preRender phase runs, so authored shaders preview live in the viewport.
+    tickCustomMaterials(this._scene, dt);
+
+    // Fly camera movement (before orbit so it takes priority)
+    this._updateFlyCamera(dt);
+
+    this.orbitControls.update();
+
+    // Snap-to-view animation (runs after orbit update so we have final say on position)
+    if (this._snapAnimating) {
+      const elapsed = performance.now() - this._snapStartTime;
+      let t = Math.min(elapsed / this._snapDuration, 1);
+      // easeInOutCubic
+      t = t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+
+      const qt = new THREE.Quaternion().slerpQuaternions(this._snapQ1, this._snapQ2, t);
+      const dir = new THREE.Vector3(0, 0, 1).applyQuaternion(qt);
+      this.camera.position.copy(this.orbitControls.target).add(dir.multiplyScalar(this._snapDist));
+      this.camera.lookAt(this.orbitControls.target);
+
+      if (t >= 1) this._snapAnimating = false;
+    }
+
+    for (const helper of this._boxHelpers.values()) {
+      const tagged = helper as TaggedHelper;
+      if (tagged._entityObj) {
+        // Fixed-size wireframe cube — follow the entity's world position
+        tagged._entityObj.getWorldPosition(helper.position);
+      } else {
+        helper.update();
+      }
+    }
+
+    // Keep handles at constant screen size
+    for (const handle of this._handles) {
+      scaleHandle(handle, this.camera);
+    }
+  }
+
+  /** Render the orientation gizmo overlaid in the top-right corner. */
+  renderViewCube(renderer: THREE.WebGLRenderer): void {
+    const w = renderer.domElement.clientWidth;
+    const h = renderer.domElement.clientHeight;
+    const size = this._vcSize;
+
+    // Sync gizmo camera with main camera orientation (reuse scratch — runs every frame)
+    const dir = this._vcDir.subVectors(this.camera.position, this.orbitControls.target).normalize();
+    this._vcCamera.position.copy(dir.multiplyScalar(4));
+    this._vcCamera.up.copy(this.camera.up);
+    this._vcCamera.lookAt(0, 0, 0);
+
+    // GL viewport coords (origin bottom-left)
+    const px = w - size - this._vcMarginRight;
+    const py = h - size - this._vcMarginTop;
+
+    renderer.setScissorTest(true);
+    renderer.setViewport(px, py, size, size);
+    renderer.setScissor(px, py, size, size);
+    // Only clear depth so main scene shows through; disable autoClear so
+    // renderer.render() doesn't wipe the color buffer.
+    renderer.clear(false, true, false);
+    renderer.autoClear = false;
+    renderer.render(this._vcScene, this._vcCamera);
+    renderer.autoClear = true;
+
+    renderer.setScissorTest(false);
+    renderer.setViewport(0, 0, w, h);
+  }
+
+  /** Render a small camera preview in the bottom-right corner if a camera entity is selected. */
+  renderCameraPreview(renderer: THREE.WebGLRenderer): void {
+    const selectedEntity = this._store.selectedEntity;
+    if (!selectedEntity?.camera) return;
+
+    const entityObj = this._objectMap.get(selectedEntity.id!);
+    if (!entityObj) return;
+    const entityCamera = getUserData(entityObj, '_camera') as THREE.Camera | undefined;
+    if (!entityCamera) return;
+
+    const w = renderer.domElement.clientWidth;
+    const h = renderer.domElement.clientHeight;
+    const camW = selectedEntity.camera.width ?? 1920;
+    const camH = selectedEntity.camera.height ?? 1080;
+    const pw = Math.floor(w * 0.25);
+    const ph = Math.floor(pw * (camH / camW));
+    const marginRight = 12;
+    const marginBottom = 26 + 12;
+    const border = 2;
+
+    // Hide editor-only objects for the preview
+    this.grid.visible = false;
+    this._gizmoHelper.visible = false;
+    for (const helper of this._boxHelpers.values()) helper.visible = false;
+    // Hide the frustum helper lines so they don't appear in the camera's own view
+    const hiddenHelpers: THREE.Object3D[] = [];
+    entityObj.traverse((child) => {
+      if (child instanceof THREE.LineSegments && child.visible) {
+        child.visible = false;
+        hiddenHelpers.push(child);
+      }
+    });
+
+    // Save and override clear color for border
+    const prevClearColor = renderer.getClearColor(this._previewClearColor);
+    const prevClearAlpha = renderer.getClearAlpha();
+
+    renderer.setScissorTest(true);
+
+    // Draw border area
+    const px = w - pw - marginRight;
+    const py = marginBottom;
+    renderer.setViewport(px - border, py - border, pw + border * 2, ph + border * 2);
+    renderer.setScissor(px - border, py - border, pw + border * 2, ph + border * 2);
+    renderer.setClearColor(0x666666, 1);
+    renderer.clear();
+
+    // Render preview
+    renderer.setViewport(px, py, pw, ph);
+    renderer.setScissor(px, py, pw, ph);
+    renderer.render(this._scene, entityCamera);
+
+    // Restore
+    renderer.setScissorTest(false);
+    renderer.setViewport(0, 0, w, h);
+    renderer.setClearColor(prevClearColor, prevClearAlpha);
+
+    // Restore visibility
+    this.grid.visible = true;
+    this._gizmoHelper.visible = true;
+    for (const helper of this._boxHelpers.values()) helper.visible = true;
+    for (const helper of hiddenHelpers) helper.visible = true;
+  }
+
+  /** True when the fly camera is active (right-click + movement key held). */
+  get isFlying(): boolean {
+    return this._flyActive;
+  }
+
+  dispose(): void {
+    setViewportPickContext(null);
+    window.removeEventListener('keydown', this._onFlyKeyDown);
+    window.removeEventListener('keyup', this._onFlyKeyUp);
+    this._canvas.removeEventListener('pointerdown', this._onFlyPointerDown);
+    this._canvas.removeEventListener('pointerup', this._onFlyPointerUp);
+    this._canvas.removeEventListener('pointermove', this._onFlyPointerMove);
+    this._canvas.removeEventListener('wheel', this._onFlyWheel);
+    this._canvas.removeEventListener('pointerdown', this._onPointerDown);
+    this._canvas.removeEventListener('pointermove', this._onPointerMove);
+    this._canvas.removeEventListener('pointerup', this._onPointerUp);
+    this._canvas.removeEventListener('dragover', this._onDragOver);
+    this._canvas.removeEventListener('dragleave', this._onDragLeave);
+    this._canvas.removeEventListener('drop', this._onDrop);
+    this._hideDropOverlay();
+    for (const h of this._handles) {
+      this._scene.remove(h);
+      (h.material as THREE.Material).dispose();
+    }
+    this._handles = [];
+    for (const helper of this._boxHelpers.values()) {
+      this._scene.remove(helper);
+      helper.geometry.dispose();
+      (helper.material as THREE.Material).dispose();
+    }
+    this._boxHelpers.clear();
+    this.orbitControls.dispose();
+    this.transformControls.dispose();
+  }
+
+  // --- Private ---
+
+  /** Build the orientation gizmo: colored axis arrows with cone tips, labels, and click targets. */
+  private _initOrientationGizmo(): void {
+    this._vcScene.add(new THREE.AmbientLight(0xffffff, 0.8));
+    const light = new THREE.DirectionalLight(0xffffff, 0.5);
+    light.position.set(1, 2, 3);
+    this._vcScene.add(light);
+
+    // Godot axis colors
+    const colors = [
+      new THREE.Color(0.96, 0.2, 0.32), // X
+      new THREE.Color(0.53, 0.84, 0.01), // Y
+      new THREE.Color(0.16, 0.55, 0.96), // Z
+    ];
+    const axes = [
+      new THREE.Vector3(1, 0, 0),
+      new THREE.Vector3(0, 1, 0),
+      new THREE.Vector3(0, 0, 1),
+    ];
+    const names = ['X', 'Y', 'Z'];
+    const shaft = 0.9;
+    const tip = 0.15;
+    const targetGeo = new THREE.SphereGeometry(0.2, 8, 8);
+    const targetMat = new THREE.MeshBasicMaterial({ visible: false });
+
+    for (let i = 0; i < 3; i++) {
+      const c = colors[i]!;
+      const a = axes[i]!;
+
+      // --- Positive axis ---
+
+      // Shaft line
+      this._vcScene.add(
+        new THREE.Line(
+          new THREE.BufferGeometry().setFromPoints([
+            new THREE.Vector3(),
+            a.clone().multiplyScalar(shaft),
+          ]),
+          new THREE.LineBasicMaterial({ color: c }),
+        ),
+      );
+
+      // Cone arrowhead
+      const cone = new THREE.Mesh(
+        new THREE.ConeGeometry(0.055, tip, 8),
+        new THREE.MeshBasicMaterial({ color: c }),
+      );
+      cone.position.copy(a.clone().multiplyScalar(shaft + tip / 2));
+      if (i === 0) cone.rotation.z = -Math.PI / 2;
+      if (i === 2) cone.rotation.x = Math.PI / 2;
+      this._vcScene.add(cone);
+
+      // Label sprite
+      this._vcScene.add(
+        this._makeAxisLabel(names[i]!, c, a.clone().multiplyScalar(shaft + tip + 0.15)),
+      );
+
+      // Click target (invisible sphere)
+      const posTarget = new THREE.Mesh(targetGeo, targetMat);
+      posTarget.position.copy(a.clone().multiplyScalar(shaft * 0.6));
+      setUserData(posTarget, 'vcDirIdx', i * 2); // 0=+X, 2=+Y, 4=+Z
+      this._vcScene.add(posTarget);
+      this._vcClickTargets.push(posTarget);
+
+      // --- Negative axis ---
+
+      // Faint line for negative direction
+      this._vcScene.add(
+        new THREE.Line(
+          new THREE.BufferGeometry().setFromPoints([
+            new THREE.Vector3(),
+            a.clone().multiplyScalar(-0.45),
+          ]),
+          new THREE.LineBasicMaterial({ color: c, transparent: true, opacity: 0.3 }),
+        ),
+      );
+
+      // Small dot at negative end
+      const negDot = new THREE.Mesh(
+        new THREE.SphereGeometry(0.06, 8, 8),
+        new THREE.MeshBasicMaterial({ color: c, transparent: true, opacity: 0.4 }),
+      );
+      negDot.position.copy(a.clone().multiplyScalar(-0.5));
+      this._vcScene.add(negDot);
+
+      // Click target for negative axis
+      const negTarget = new THREE.Mesh(targetGeo, targetMat);
+      negTarget.position.copy(a.clone().multiplyScalar(-0.45));
+      setUserData(negTarget, 'vcDirIdx', i * 2 + 1); // 1=-X, 3=-Y, 5=-Z
+      this._vcScene.add(negTarget);
+      this._vcClickTargets.push(negTarget);
+    }
+
+    // Center dot
+    this._vcScene.add(
+      new THREE.Mesh(
+        new THREE.SphereGeometry(0.05, 8, 8),
+        new THREE.MeshBasicMaterial({ color: 0x888888 }),
+      ),
+    );
+  }
+
+  /** Create a sprite with a single axis letter. */
+  private _makeAxisLabel(text: string, color: THREE.Color, position: THREE.Vector3): THREE.Sprite {
+    const size = 64;
+    const c = document.createElement('canvas');
+    c.width = size;
+    c.height = size;
+    const ctx = c.getContext('2d')!;
+    ctx.fillStyle = `#${color.getHexString()}`;
+    ctx.font = 'bold 44px system-ui, -apple-system, sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(text, size / 2, size / 2);
+
+    const texture = new THREE.CanvasTexture(c);
+    const mat = new THREE.SpriteMaterial({ map: texture, transparent: true, depthTest: false });
+    const sprite = new THREE.Sprite(mat);
+    sprite.position.copy(position);
+    sprite.scale.set(0.25, 0.25, 0.25);
+    return sprite;
+  }
+
+  /** Returns true if the click was inside the gizmo area (consumed). */
+  private _handleViewCubeClick(e: PointerEvent): boolean {
+    const rect = this._canvas.getBoundingClientRect();
+    const x = e.clientX - rect.left;
+    const y = e.clientY - rect.top;
+    const w = rect.width;
+
+    // Screen-space gizmo rect
+    const vcLeft = w - this._vcSize - this._vcMarginRight;
+    const vcTop = this._vcMarginTop;
+
+    if (x < vcLeft || x > vcLeft + this._vcSize || y < vcTop || y > vcTop + this._vcSize) {
+      return false;
+    }
+
+    // Convert to NDC for the gizmo camera
+    const ndcX = ((x - vcLeft) / this._vcSize) * 2 - 1;
+    const ndcY = -(((y - vcTop) / this._vcSize) * 2 - 1);
+
+    this._vcRaycaster.setFromCamera(new THREE.Vector2(ndcX, ndcY), this._vcCamera);
+    const hits = this._vcRaycaster.intersectObjects(this._vcClickTargets);
+    if (hits.length === 0) return true; // In gizmo area but missed — still consume
+
+    const dirIdx = getUserData(hits[0]!.object, 'vcDirIdx') as number;
+    const targetDir = VC_DIRS[dirIdx]!;
+
+    // Set up slerp animation
+    const startDir = new THREE.Vector3()
+      .subVectors(this.camera.position, this.orbitControls.target)
+      .normalize();
+
+    this._snapDist = this.camera.position.distanceTo(this.orbitControls.target);
+    this._snapQ1.setFromUnitVectors(new THREE.Vector3(0, 0, 1), startDir);
+    this._snapQ2.setFromUnitVectors(new THREE.Vector3(0, 0, 1), targetDir);
+    this._snapStartTime = performance.now();
+    this._snapAnimating = true;
+
+    return true;
+  }
+
+  /** Live flush during drag — updates inspector without undo or scene rebuild. */
+  private _flushGizmoToStoreLive(): void {
+    this._skipNextSync = true;
+    // Live transform edits flow through the AuthoringAdapter (the gizmo already
+    // moved the Object3D; apply syncs the descriptor without pushing undo).
+    const transforms = getActiveAuthoring(this._store).transforms;
+    const applyLive = (o: THREE.Object3D): void => {
+      const id = getUserData(o, 'entityId') as string | undefined;
+      if (!id) return;
+      transforms?.apply(id, {
+        position: o.position.toArray() as [number, number, number],
+        rotation: o.quaternion.toArray() as [number, number, number, number],
+        scale: o.scale.toArray() as [number, number, number],
+      });
+    };
+    // Primary (if it's a real entity, not pivot dummy)
+    const obj = this.transformControls.object;
+    if (obj) applyLive(obj);
+    // Other selected objects (active-element / individual-origins)
+    for (const { obj: other } of this._otherDragObjects) applyLive(other);
+    // All selected objects (median-point mode — gizmo is on dummy)
+    for (const { obj: mo } of this._allDragObjects) applyLive(mo);
+  }
+
+  /**
+   * Surface snap: raycast downward from the primary object to find
+   * a surface and adjust Y positions accordingly.
+   */
+  private _applySurfaceSnap(
+    gizmoObj: THREE.Object3D,
+    targets: {
+      obj: THREE.Object3D;
+      startPos: THREE.Vector3;
+      startQuat: THREE.Quaternion;
+      startScale: THREE.Vector3;
+    }[],
+  ): void {
+    // Collect all dragged entity IDs to exclude from raycast
+    const draggedIds = new Set<string>();
+    const gizmoId = getUserData(gizmoObj, 'entityId') as string | undefined;
+    if (gizmoId) draggedIds.add(gizmoId);
+    for (const { obj } of targets) {
+      const id = getUserData(obj, 'entityId') as string | undefined;
+      if (id) draggedIds.add(id);
+    }
+
+    // Collect scene objects that are NOT being dragged
+    const sceneTargets: THREE.Object3D[] = [];
+    for (const [id, obj] of this._objectMap) {
+      if (!draggedIds.has(id)) sceneTargets.push(obj);
+    }
+    // Also include the grid as a snap target
+    sceneTargets.push(this.grid);
+
+    if (sceneTargets.length === 0) {
+      this._surfaceSnapIndicator.visible = false;
+      return;
+    }
+
+    // Raycast downward from the gizmo object position
+    const origin = gizmoObj.position.clone();
+    origin.y += 50; // Start high above
+    this._surfaceSnapRaycaster.set(origin, new THREE.Vector3(0, -1, 0));
+    this._surfaceSnapRaycaster.far = 200;
+
+    const hits = this._surfaceSnapRaycaster.intersectObjects(sceneTargets, true);
+    if (hits.length > 0) {
+      const hitPoint = hits[0]!.point;
+      const snapY = hitPoint.y;
+      const deltaY = snapY - gizmoObj.position.y;
+
+      gizmoObj.position.y = snapY;
+      for (const { obj } of targets) {
+        obj.position.y += deltaY;
+      }
+
+      // Show snap indicator at hit point
+      this._surfaceSnapIndicator.position.copy(hitPoint);
+      this._surfaceSnapIndicator.position.y += 0.01; // Slight offset to avoid z-fighting
+      // Orient ring to match surface normal
+      const normal = hits[0]!.face?.normal;
+      if (normal) {
+        const worldNormal = normal.clone().transformDirection(hits[0]!.object.matrixWorld);
+        this._surfaceSnapIndicator.quaternion.setFromUnitVectors(
+          new THREE.Vector3(0, 1, 0),
+          worldNormal,
+        );
+      }
+      this._surfaceSnapIndicator.visible = true;
+    } else {
+      this._surfaceSnapIndicator.visible = false;
+    }
+  }
+
+  /**
+   * Collect world-space vertex positions from entity meshes.
+   * Excludes entities in `excludeIds` and editor helper children.
+   */
+  private _collectVertices(excludeIds: ReadonlySet<string>): THREE.Vector3[] {
+    const vertices: THREE.Vector3[] = [];
+    const MAX_PER_MESH = 1000;
+    for (const [id, obj] of this._objectMap) {
+      if (excludeIds.has(id)) continue;
+      obj.traverse((child) => {
+        if (getUserData(child, 'editorHelper')) return;
+        const mesh = child as THREE.Mesh;
+        if (!mesh.isMesh || !mesh.geometry) return;
+        const posAttr = mesh.geometry.getAttribute('position') as THREE.BufferAttribute | undefined;
+        if (!posAttr) return;
+        const count = Math.min(posAttr.count, MAX_PER_MESH);
+        const worldMatrix = mesh.matrixWorld;
+        for (let i = 0; i < count; i++) {
+          const v = new THREE.Vector3(posAttr.getX(i), posAttr.getY(i), posAttr.getZ(i));
+          v.applyMatrix4(worldMatrix);
+          vertices.push(v);
+        }
+      });
+    }
+    return vertices;
+  }
+
+  /**
+   * Vertex snap: snap the gizmo object to the nearest vertex on non-selected geometry.
+   */
+  private _applyVertexSnap(
+    gizmoObj: THREE.Object3D,
+    targets: { obj: THREE.Object3D; startPos: THREE.Vector3 }[],
+  ): void {
+    const entityPos = gizmoObj.position;
+    const projected = entityPos.clone().project(this.camera);
+    const rect = this._canvas.getBoundingClientRect();
+    const entityScreenX = ((projected.x + 1) / 2) * rect.width;
+    const entityScreenY = ((-projected.y + 1) / 2) * rect.height;
+
+    let bestDist = this._vertexSnapThreshold;
+    let bestVertex: THREE.Vector3 | null = null;
+
+    for (const vert of this._vertexSnapTargets) {
+      const vs = vert.clone().project(this.camera);
+      // Skip vertices behind camera
+      if (vs.z > 1) continue;
+      const vertScreenX = ((vs.x + 1) / 2) * rect.width;
+      const vertScreenY = ((-vs.y + 1) / 2) * rect.height;
+      const dx = entityScreenX - vertScreenX;
+      const dy = entityScreenY - vertScreenY;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestVertex = vert;
+      }
+    }
+
+    if (bestVertex) {
+      const delta = bestVertex.clone().sub(entityPos);
+      gizmoObj.position.copy(bestVertex);
+      for (const { obj } of targets) {
+        obj.position.add(delta);
+      }
+      this._vertexSnapIndicator.position.copy(bestVertex);
+      this._vertexSnapIndicator.visible = true;
+      // Constant screen size for indicator
+      const dist = bestVertex.distanceTo(this.camera.position);
+      this._vertexSnapIndicator.scale.setScalar(dist * 0.008);
+    } else {
+      this._vertexSnapIndicator.visible = false;
+    }
+  }
+
+  /** Final flush on drag end — no undo push (already pushed on drag start). */
+  private _flushGizmoToStore(): void {
+    this._flushGizmoToStoreLive();
+    this._otherDragObjects = [];
+    this._allDragObjects = [];
+    // Persist the final transform + mark dirty (ED2). A mid-drag autosave may
+    // have already fired and cleared dirty; this re-schedules the final write.
+    getActiveAuthoring(this._store).transforms?.endEdit('');
+  }
+
+  /** Check if we should skip a sync (gizmo already moved the object). */
+  consumeSkipSync(): boolean {
+    if (this._skipNextSync) {
+      this._skipNextSync = false;
+      return true;
+    }
+    return false;
+  }
+
+  /** Recolor gizmo handles to Godot axis colors & shift plane geometry to meet at center. */
+  private _patchGizmo(gizmoHelper: THREE.Object3D): void {
+    // Godot axis colors: Color(0.96,0.20,0.32), Color(0.53,0.84,0.01), Color(0.16,0.55,0.96)
+    const axisX = new THREE.Color(0.96, 0.2, 0.32);
+    const axisY = new THREE.Color(0.53, 0.84, 0.01);
+    const axisZ = new THREE.Color(0.16, 0.55, 0.96);
+
+    // Handle color: axis handles use axis color, plane handles use normal-axis color
+    const colorMap: Record<string, THREE.Color> = {
+      X: axisX,
+      Y: axisY,
+      Z: axisZ,
+      XY: axisZ,
+      YZ: axisX,
+      XZ: axisY,
+    };
+
+    // Plane geometry offsets to bring inner corners to object center
+    const planeOffsets: Record<string, [number, number, number]> = {
+      XY: [-0.075, -0.075, 0],
+      YZ: [0, -0.075, -0.075],
+      XZ: [-0.075, 0, -0.075],
+    };
+
+    gizmoHelper.traverse((child) => {
+      const mesh = child as THREE.Mesh;
+
+      // Recolor handle materials
+      const newColor = colorMap[child.name];
+      if (newColor && mesh.material) {
+        const mat = mesh.material as THREE.MeshBasicMaterial | THREE.LineBasicMaterial;
+        if (mat.color) mat.color.copy(newColor);
+      }
+
+      // Shift plane handle geometry
+      const offset = planeOffsets[child.name];
+      if (offset && mesh.geometry) {
+        mesh.geometry.translate(offset[0], offset[1], offset[2]);
+      }
+    });
+  }
+
+  /** Raycast against component handles and return the hit handle, or null. */
+  private _raycastHandle(e: PointerEvent): HandleMesh | null {
+    if (this._handles.length === 0) return null;
+    const rect = this._canvas.getBoundingClientRect();
+    const mouse = new THREE.Vector2(
+      ((e.clientX - rect.left) / rect.width) * 2 - 1,
+      -((e.clientY - rect.top) / rect.height) * 2 + 1,
+    );
+    this._handleRaycaster.setFromCamera(mouse, this.camera);
+    const intersects = this._handleRaycaster.intersectObjects(this._handles);
+    return intersects.length > 0 ? (intersects[0]!.object as HandleMesh) : null;
+  }
+
+  /** Rebuild component handles for the current selection. */
+  private _syncHandles(): void {
+    // Remove old handles + dispose their materials (LK6). The geometry is a
+    // shared module-level sphere, so it must NOT be disposed.
+    for (const h of this._handles) {
+      this._scene.remove(h);
+      (h.material as THREE.Material).dispose();
+    }
+    this._handles = [];
+
+    // Create new handles for selected entities
+    for (const id of this._store.selectedEntityIds) {
+      const obj = this._objectMap.get(id);
+      const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+      if (!obj || !entity) continue;
+
+      const defs = createHandleDefs(entity);
+      for (const def of defs) {
+        const mesh = createHandleMesh(def);
+        mesh.position.copy(def.getWorldPosition(obj, entity));
+        scaleHandle(mesh, this.camera);
+        this._scene.add(mesh);
+        this._handles.push(mesh);
+      }
+    }
+  }
+
+  /** Project entity center to screen coords. */
+  private _projectToScreen(obj: THREE.Object3D): THREE.Vector2 {
+    const pos = new THREE.Vector3();
+    obj.getWorldPosition(pos);
+    pos.project(this.camera);
+    const rect = this._canvas.getBoundingClientRect();
+    return new THREE.Vector2(
+      ((pos.x + 1) / 2) * rect.width + rect.left,
+      ((-pos.y + 1) / 2) * rect.height + rect.top,
+    );
+  }
+
+  // -- Fly camera handlers --
+
+  private static _FLY_KEYS = new Set(['w', 'a', 's', 'd', 'q', 'e']);
+
+  private _enterFlyMode(): void {
+    if (this._flyActive) return;
+    this._flyActive = true;
+    this._snapAnimating = false; // cancel any view snap
+    this.orbitControls.enabled = false;
+    // Sync euler from current camera orientation
+    this._flyEuler.setFromQuaternion(this.camera.quaternion, 'YXZ');
+    this._canvas.requestPointerLock?.();
+  }
+
+  private _exitFlyMode(): void {
+    if (!this._flyActive) return;
+    this._flyActive = false;
+    this._flyKeys.clear();
+    this.orbitControls.enabled = true;
+    document.exitPointerLock();
+    // Sync orbit target to a point in front of the camera
+    const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(this.camera.quaternion);
+    const dist = this.camera.position.distanceTo(this.orbitControls.target);
+    this.orbitControls.target
+      .copy(this.camera.position)
+      .add(forward.multiplyScalar(Math.max(dist, 5)));
+  }
+
+  /** Apply fly camera movement each frame. Called from update(). */
+  private _updateFlyCamera(dt: number): void {
+    if (!this._flyActive || this._flyKeys.size === 0) return;
+
+    const speed = this._flySpeed * (this._flyKeys.has('shift') ? 3 : 1);
+    const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(this.camera.quaternion);
+    const right = new THREE.Vector3(1, 0, 0).applyQuaternion(this.camera.quaternion);
+    const move = new THREE.Vector3();
+
+    if (this._flyKeys.has('w')) move.add(forward);
+    if (this._flyKeys.has('s')) move.sub(forward);
+    if (this._flyKeys.has('d')) move.add(right);
+    if (this._flyKeys.has('a')) move.sub(right);
+    if (this._flyKeys.has('e')) move.y += 1;
+    if (this._flyKeys.has('q')) move.y -= 1;
+
+    if (move.lengthSq() > 0) {
+      move.normalize().multiplyScalar(speed * dt);
+      this.camera.position.add(move);
+    }
+  }
+
+  private _onFlyKeyDown = (e: KeyboardEvent): void => {
+    if (!this._rightMouseDown) return;
+    // Skip when typing in form inputs
+    if (
+      e.target instanceof HTMLInputElement ||
+      e.target instanceof HTMLTextAreaElement ||
+      e.target instanceof HTMLSelectElement
+    )
+      return;
+
+    const key = e.key.toLowerCase();
+    if (key === 'shift') {
+      this._flyKeys.add('shift');
+      return;
+    }
+    if (!EditorViewport._FLY_KEYS.has(key)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    this._flyKeys.add(key);
+    if (!this._flyActive) this._enterFlyMode();
+  };
+
+  private _onFlyKeyUp = (e: KeyboardEvent): void => {
+    const key = e.key.toLowerCase();
+    if (key === 'shift') {
+      this._flyKeys.delete('shift');
+      return;
+    }
+    this._flyKeys.delete(key);
+  };
+
+  private _onFlyPointerDown = (e: PointerEvent): void => {
+    if (e.button === 2) this._rightMouseDown = true;
+  };
+
+  private _onFlyPointerUp = (e: PointerEvent): void => {
+    if (e.button === 2) {
+      this._rightMouseDown = false;
+      if (this._flyActive) this._exitFlyMode();
+    }
+  };
+
+  private _onFlyPointerMove = (e: PointerEvent): void => {
+    if (!this._flyActive) return;
+    const sensitivity = 0.002;
+    this._flyEuler.y -= e.movementX * sensitivity;
+    this._flyEuler.x -= e.movementY * sensitivity;
+    // Clamp pitch to avoid gimbal flip
+    this._flyEuler.x = Math.max(
+      -Math.PI / 2 + 0.01,
+      Math.min(Math.PI / 2 - 0.01, this._flyEuler.x),
+    );
+    this.camera.quaternion.setFromEuler(this._flyEuler);
+  };
+
+  private _onFlyWheel = (e: WheelEvent): void => {
+    if (!this._flyActive) return;
+    e.preventDefault();
+    // Scroll adjusts fly speed (multiplicative, Godot-style)
+    const factor = e.deltaY > 0 ? 0.85 : 1.18;
+    this._flySpeed = Math.max(0.5, Math.min(100, this._flySpeed * factor));
+  };
+
+  private _onPointerDown = (e: PointerEvent): void => {
+    this._pointerDownPos.set(e.clientX, e.clientY);
+    this._pointerDownButton = e.button;
+    this._marqueeActive = false;
+
+    // Check for handle click (left-button only)
+    if (e.button === 0 && this._handles.length > 0 && !e.altKey) {
+      const hit = this._raycastHandle(e);
+      if (hit) {
+        e.stopPropagation();
+        this._handleDragActive = true;
+        this._activeHandle = hit;
+        this.orbitControls.enabled = false;
+        this.transformControls.enabled = false;
+        getActiveAuthoring(this._store).transforms?.beginEdit('');
+
+        // Compute constraint plane perpendicular to camera through handle position
+        const camDir = this.camera.getWorldDirection(new THREE.Vector3());
+        this._handleDragPlane.setFromNormalAndCoplanarPoint(camDir, hit.position);
+
+        // Compute offset so handle doesn't jump
+        const rect = this._canvas.getBoundingClientRect();
+        const mouse = new THREE.Vector2(
+          ((e.clientX - rect.left) / rect.width) * 2 - 1,
+          -((e.clientY - rect.top) / rect.height) * 2 + 1,
+        );
+        this._handleRaycaster.setFromCamera(mouse, this.camera);
+        const target = new THREE.Vector3();
+        this._handleRaycaster.ray.intersectPlane(this._handleDragPlane, target);
+        this._handleDragOffset.subVectors(hit.position, target);
+        this._canvas.style.cursor = 'grabbing';
+      }
+    }
+  };
+
+  private _onPointerMove = (e: PointerEvent): void => {
+    // Handle drag
+    if (this._handleDragActive && this._activeHandle) {
+      const rect = this._canvas.getBoundingClientRect();
+      const mouse = new THREE.Vector2(
+        ((e.clientX - rect.left) / rect.width) * 2 - 1,
+        -((e.clientY - rect.top) / rect.height) * 2 + 1,
+      );
+      this._handleRaycaster.setFromCamera(mouse, this.camera);
+      const target = new THREE.Vector3();
+      if (this._handleRaycaster.ray.intersectPlane(this._handleDragPlane, target)) {
+        const newPos = target.add(this._handleDragOffset);
+        const def = this._activeHandle.userData.handleDef;
+        const entityObj = this._objectMap.get(def.entityId);
+        const entity = getUserData(entityObj, 'entity') as SceneEntity | undefined;
+        if (entityObj && entity) {
+          def.onDrag(newPos, entityObj, entity);
+          // Rebuild the entity helpers to reflect the new value
+          this._store.rebuildEntityLive(def.entityId);
+          // Re-sync handle positions (helpers were rebuilt)
+          this._syncHandles();
+        }
+      }
+      return;
+    }
+
+    // Handle hover detection (when not dragging anything)
+    if (!(e.buttons & 1) && this._handles.length > 0) {
+      const hit = this._raycastHandle(e);
+      if (hit !== this._hoveredHandle) {
+        if (this._hoveredHandle) setHandleHovered(this._hoveredHandle, false);
+        this._hoveredHandle = hit;
+        if (hit) {
+          setHandleHovered(hit, true);
+          this._canvas.style.cursor = 'grab';
+        } else {
+          this._canvas.style.cursor = '';
+        }
+      }
+    }
+
+    // Only left button drag starts marquee (skip if Alt-orbiting)
+    if (!(e.buttons & 1) || this._pointerDownButton !== 0) return;
+    if (this.transformControls.dragging) return;
+    if (this._altDragOrbit) return;
+
+    const dx = e.clientX - this._pointerDownPos.x;
+    const dy = e.clientY - this._pointerDownPos.y;
+    if (!this._marqueeActive && Math.sqrt(dx * dx + dy * dy) > 5) {
+      // Check we're not dragging from the viewcube area
+      const rect = this._canvas.getBoundingClientRect();
+      const sx = this._pointerDownPos.x - rect.left;
+      const sy = this._pointerDownPos.y - rect.top;
+      const vcLeft = rect.width - this._vcSize - this._vcMarginRight;
+      if (
+        sx >= vcLeft &&
+        sx <= vcLeft + this._vcSize &&
+        sy >= this._vcMarginTop &&
+        sy <= this._vcMarginTop + this._vcSize
+      )
+        return;
+
+      this._marqueeActive = true;
+      // Disable orbit controls while marquee is active
+      this.orbitControls.enabled = false;
+
+      if (!this._marqueeDiv) {
+        this._marqueeDiv = document.createElement('div');
+        Object.assign(this._marqueeDiv.style, {
+          position: 'fixed',
+          border: '1px solid #579EFF',
+          background: 'rgba(87, 158, 255, 0.15)',
+          pointerEvents: 'none',
+          zIndex: '999',
+        });
+        document.body.appendChild(this._marqueeDiv);
+      }
+    }
+
+    if (this._marqueeActive && this._marqueeDiv) {
+      const left = Math.min(this._pointerDownPos.x, e.clientX);
+      const top = Math.min(this._pointerDownPos.y, e.clientY);
+      const w = Math.abs(e.clientX - this._pointerDownPos.x);
+      const h = Math.abs(e.clientY - this._pointerDownPos.y);
+      Object.assign(this._marqueeDiv.style, {
+        left: `${left}px`,
+        top: `${top}px`,
+        width: `${w}px`,
+        height: `${h}px`,
+        display: 'block',
+      });
+    }
+  };
+
+  private _onPointerUp = (e: PointerEvent): void => {
+    // Handle drag end
+    if (this._handleDragActive) {
+      this._handleDragActive = false;
+      this._activeHandle = null;
+      this.orbitControls.enabled = true;
+      this.transformControls.enabled = true;
+      this._canvas.style.cursor = '';
+      // Persist the final handle-driven edit + mark dirty (ED2).
+      getActiveAuthoring(this._store).transforms?.endEdit('');
+      return;
+    }
+
+    // Handle marquee select. D12 (B4) scope note: marquee stays THREEJS-ONLY —
+    // it only ever scans `this._objectMap` (the focused threejs world's live
+    // objects), never the composite's other (react/pixi) layered children. A
+    // layered/rect-based marquee across every visible layer is out of scope
+    // for this task (D12) — single-click picking is layered (below), marquee
+    // is not.
+    if (this._marqueeActive) {
+      this._marqueeActive = false;
+      this.orbitControls.enabled = true;
+      if (this._marqueeDiv) {
+        this._marqueeDiv.style.display = 'none';
+      }
+
+      // Find all entities whose screen projection falls within the marquee
+      const left = Math.min(this._pointerDownPos.x, e.clientX);
+      const right = Math.max(this._pointerDownPos.x, e.clientX);
+      const top = Math.min(this._pointerDownPos.y, e.clientY);
+      const bottom = Math.max(this._pointerDownPos.y, e.clientY);
+
+      const hitIds: string[] = [];
+      for (const [id, obj] of this._objectMap) {
+        // Skip locked entities in marquee selection
+        if (this._store.isEntityLocked(id)) continue;
+        const screen = this._projectToScreen(obj);
+        if (screen.x >= left && screen.x <= right && screen.y >= top && screen.y <= bottom) {
+          hitIds.push(id);
+        }
+      }
+
+      if (e.shiftKey) {
+        // Add to existing selection (additive modifier — SelectionProvider
+        // extension is Phase-F; first-party store op for now).
+        for (const id of hitIds) this._store.addToSelection(id);
+      } else {
+        getActiveAuthoring(this._store).selection?.set(hitIds);
+      }
+      return;
+    }
+
+    // Only left-click triggers selection (right-drag = orbit, not select)
+    if (e.button !== 0) return;
+
+    // Only treat as click if pointer didn't move much (not a drag)
+    const dx = e.clientX - this._pointerDownPos.x;
+    const dy = e.clientY - this._pointerDownPos.y;
+    if (Math.sqrt(dx * dx + dy * dy) > 5) return;
+
+    // Don't interfere with gizmo clicks
+    if (this.transformControls.dragging) return;
+
+    // Check orientation gizmo click first
+    if (this._handleViewCubeClick(e)) return;
+
+    // D12 (B4) — topmost-first layered pick: the composite's non-threejs
+    // children (react/pixi design-time layers) are tried topmost-first before
+    // falling through to the threejs raycast (now `VgaiSceneAuthoringAdapter
+    // .pickable`) — see `pickTopmost`'s doc comment. Note: an INTERACTIVE
+    // layer (session `interactive` toggle, B1) is mutually exclusive with this
+    // walk running at all, by construction — its `pointer-events:auto` DOM
+    // intercepts the event before it ever reaches this canvas listener, so
+    // there is no special-case here for it.
+    const entityId = pickTopmost(this._store, e.clientX, e.clientY);
+
+    if (e.shiftKey && entityId) {
+      this._store.addToSelection(entityId);
+    } else if ((e.metaKey || e.ctrlKey) && entityId) {
+      this._store.toggleSelection(entityId);
+    } else {
+      getActiveAuthoring(this._store).selection?.set(entityId ? [entityId] : []);
+    }
+  };
+
+  // --- Asset drag-and-drop onto viewport ---
+
+  /** Raycast from screen coordinates to the ground plane (y=0). Returns world position or null. */
+  private _raycastGroundPlane(e: DragEvent): THREE.Vector3 | null {
+    const rect = this._canvas.getBoundingClientRect();
+    const mouse = new THREE.Vector2(
+      ((e.clientX - rect.left) / rect.width) * 2 - 1,
+      -((e.clientY - rect.top) / rect.height) * 2 + 1,
+    );
+    this.raycaster.setFromCamera(mouse, this.camera);
+    const target = new THREE.Vector3();
+    const hit = this.raycaster.ray.intersectPlane(this._groundPlane, target);
+    return hit;
+  }
+
+  private _showDropOverlay(): void {
+    if (this._dropOverlay) return;
+    const overlay = document.createElement('div');
+    Object.assign(overlay.style, {
+      position: 'fixed',
+      inset: '0',
+      pointerEvents: 'none',
+      border: '2px dashed #579EFF',
+      background: 'rgba(87, 158, 255, 0.08)',
+      zIndex: '5',
+    });
+    document.body.appendChild(overlay);
+    this._dropOverlay = overlay;
+  }
+
+  private _hideDropOverlay(): void {
+    if (this._dropOverlay) {
+      this._dropOverlay.remove();
+      this._dropOverlay = null;
+    }
+  }
+
+  private _onDragOver = (e: DragEvent): void => {
+    if (!e.dataTransfer?.types.includes('application/x-editor-asset')) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = 'copy';
+    this._showDropOverlay();
+  };
+
+  private _onDragLeave = (_e: DragEvent): void => {
+    this._hideDropOverlay();
+  };
+
+  private _onDrop = (e: DragEvent): void => {
+    this._hideDropOverlay();
+    const raw = e.dataTransfer?.getData('application/x-editor-asset');
+    if (!raw) return;
+    e.preventDefault();
+
+    let data: {
+      path: string;
+      kind: string;
+      name: string;
+      online?: {
+        source: string;
+        id: string;
+        name: string;
+        url?: string;
+        format?: string;
+        includes?: { relativePath: string; url: string; size: number }[];
+      };
+    };
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      return;
+    }
+
+    // Find drop position via ground-plane raycast, fallback to origin
+    const worldPos = this._raycastGroundPlane(e);
+    const pos: [number, number, number] = worldPos
+      ? [Math.round(worldPos.x * 100) / 100, 0, Math.round(worldPos.z * 100) / 100]
+      : [0, 0, 0];
+
+    // Online asset: check cache first, otherwise show placeholder and download
+    if (data.online) {
+      const online = data.online;
+      const baseName = online.name.replace(/\.[^.]+$/, '');
+
+      // Already downloaded? Create entity instantly, no placeholder needed.
+      const cachedPath = getDownloadedAssetPath(online.source, online.name);
+      if (cachedPath) {
+        this._store.addEntity(null, {
+          id: crypto.randomUUID(),
+          name: baseName,
+          mesh: { type: 'gltf', src: cachedPath },
+          transform: { position: pos },
+        });
+        return;
+      }
+
+      const placeholderId = crypto.randomUUID();
+
+      // Create a visible placeholder box at the drop position
+      this._store.addEntity(null, {
+        id: placeholderId,
+        name: `${baseName} (downloading...)`,
+        mesh: { type: 'box' },
+        transform: { position: pos, scale: [0.5, 0.5, 0.5] },
+        material: { type: 'standard', color: '#579EFF', opacity: 0.4, transparent: true },
+      });
+
+      const resolveEntity = (localPath: string) => {
+        // Replace placeholder with the real GLTF entity
+        this._store.removeEntity(placeholderId);
+        this._store.addEntity(null, {
+          id: crypto.randomUUID(),
+          name: baseName,
+          mesh: { type: 'gltf', src: `/${localPath}` },
+          transform: { position: pos },
+        });
+      };
+
+      const doDownload = (dlParams: Parameters<typeof downloadOnlineAsset>[0]) => {
+        downloadOnlineAsset(dlParams)
+          .then((result) => {
+            if (result.ok && result.path) {
+              resolveEntity(result.path);
+            } else {
+              // Download failed — update name to indicate error
+              this._store.updateEntity(placeholderId, {
+                name: `${baseName} (download failed)`,
+              });
+            }
+          })
+          .catch(() => {
+            // Browser mode (no Node dev server) throws instead of resolving
+            // { ok: false } — same "download failed" placeholder update as
+            // the resolved-failure branch above, no unhandled rejection.
+            this._store.updateEntity(placeholderId, {
+              name: `${baseName} (download failed)`,
+            });
+          });
+      };
+
+      if (online.url) {
+        const dlParams: Parameters<typeof downloadOnlineAsset>[0] = {
+          source: online.source,
+          id: online.id,
+          name: online.name,
+          url: online.url,
+          format: online.format ?? 'gltf',
+        };
+        if (online.includes) dlParams.includes = online.includes;
+        doDownload(dlParams);
+      } else {
+        // Fetch file options, pick first, then download
+        getOnlineAssetFiles(online.source, online.id).then((files) => {
+          const file = files[0];
+          if (!file) {
+            this._store.updateEntity(placeholderId, {
+              name: `${baseName} (no files available)`,
+            });
+            return;
+          }
+          const params: Parameters<typeof downloadOnlineAsset>[0] = {
+            source: online.source,
+            id: online.id,
+            name: online.name,
+            url: file.url,
+            format: file.format,
+          };
+          if (file.includes) params.includes = file.includes;
+          doDownload(params);
+        });
+      }
+      return;
+    }
+
+    const baseName = data.name.replace(/\.[^.]+$/, '');
+
+    if (data.kind === 'model') {
+      this._store.addEntity(null, {
+        id: crypto.randomUUID(),
+        name: baseName,
+        mesh: { type: 'gltf', src: data.path },
+        transform: { position: pos },
+      });
+    } else if (data.kind === 'image') {
+      this._store.addEntity(null, {
+        id: crypto.randomUUID(),
+        name: baseName,
+        mesh: { type: 'plane', args: [2, 2] },
+        material: { type: 'standard', map: data.path },
+        transform: {
+          position: [pos[0], pos[1] + 1, pos[2]],
+          rotation: [0, 0, 0, 1],
+        },
+      });
+    } else if (data.kind === 'scene') {
+      fetch(resolveUrl(data.path))
+        .then((r) => r.json())
+        .then((doc: { entities?: SceneEntity[] }) => {
+          if (doc.entities) {
+            for (const entity of doc.entities) {
+              const e: SceneEntity = { ...entity, id: crypto.randomUUID() };
+              // Offset root entities to drop position
+              if (!e.transform) e.transform = {};
+              const ep = e.transform.position ?? [0, 0, 0];
+              e.transform.position = [ep[0] + pos[0], ep[1] + pos[1], ep[2] + pos[2]];
+              this._store.addEntity(null, e);
+            }
+          }
+        });
+    } else if (data.kind === 'audio') {
+      const baseName = data.name.replace(/\.[^.]+$/, '');
+      this._store.addEntity(null, {
+        id: crypto.randomUUID(),
+        name: baseName,
+        audio: { src: data.path, spatial: true, volume: 1 },
+        transform: { position: pos },
+      });
+    }
+  };
+}