castle-web-cli 0.4.10 → 0.4.12

package/kits/basic-3d/editors/SceneEditor.jsx

@@ -0,0 +1,1087 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import * as THREE from 'three';
+import { basename, formatJson, parseJsonFile } from '../engine/files';
+import { TouchControls } from '../engine/TouchControls';
+import {
+  addActor,
+  defaultCameraSpec,
+  duplicateActors,
+  makeScene,
+  removeActorComponent,
+  removeActors,
+  roundUnits,
+  sceneCameraSpec,
+  setActorComponent,
+} from '../engine/scene';
+import {
+  applyCameraSpec,
+  defaultLighting,
+  fitRendererToCanvas,
+  radiansToDegrees,
+} from '../engine/threeUtil';
+import {
+  attachSceneKeys,
+  isEditableTarget,
+  makePlayPointerHandlers,
+  ThreeCanvas,
+} from '../engine/SceneViewport';
+import {
+  cx,
+  CheckboxField,
+  ColorField,
+  EditorBody,
+  EditorHeader,
+  Icon,
+  IconButton,
+  NumberField,
+  Panel,
+  SheetGrabHandle,
+  styles,
+  TextField,
+  useMobileSheet,
+} from '../engine/ui';
+import { AutoFields, AutoInspector } from '../engine/autoInspector';
+import { SceneUI } from '../engine/SceneUI';
+import { behaviorClasses, findBehaviorClass } from './behaviorRegistry';
+import { useEditHistory } from './editorHistory';
+import { applyGizmoSnap, createViewportRig, GIZMO_MODES } from './viewportRig';
+
+const LONG_PRESS_MS = 500;
+const DRAG_THRESHOLD_PX = 5;
+const DEFAULT_GRID_SIZE = 1;
+
+export function SceneEditor({
+  path,
+  text,
+  files,
+  models,
+  onChange,
+  onToggleFiles,
+  filesOpen,
+  selectedActorIds,
+  onSelectActorIds,
+  multiSelectMode,
+  onSetMultiSelectMode,
+}) {
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [navMode, setNavMode] = useState(false);
+  const [gizmoMode, setGizmoMode] = useState('translate');
+  const [marquee, setMarquee] = useState(null);
+  const history = useEditHistory(text, onChange);
+  const showMulti = selectedActorIds.length > 1 || multiSelectMode;
+  const inspectorSheet = useSelectionInspectorSheet(true);
+  const { value: sceneData, error } = parseJsonFile(path, text);
+  const applyScene = (next) => onChange(formatJson(next));
+  const viewport = useSceneViewport({
+    text,
+    sceneData,
+    models,
+    isPlaying,
+    navMode,
+    gizmoMode,
+    selectedActorIds,
+    applyScene,
+    recordSnapshot: history.recordSnapshot,
+  });
+  const getRuntimeKeys = useCallback(
+    () => viewport.playRuntimeRef.current?.keys ?? null,
+    [viewport.playRuntimeRef]
+  );
+  const getPlayRuntime = useCallback(
+    () => viewport.playRuntimeRef.current,
+    [viewport.playRuntimeRef]
+  );
+  useEffect(
+    () => attachSceneKeys(getPlayRuntime, { onSpace: () => setIsPlaying((value) => !value) }),
+    [getPlayRuntime]
+  );
+  const gesture = useSelectionGesture({
+    viewport,
+    sceneData,
+    isPlaying,
+    navMode,
+    selectedActorIds,
+    onSelectActorIds,
+    multiSelectMode,
+    onSetMultiSelectMode,
+    setMarquee,
+    applyScene,
+    recordSceneSnapshot: history.recordSnapshot,
+  });
+  const playPointer = useMemo(() => makePlayPointerHandlers(getPlayRuntime), [getPlayRuntime]);
+  useSelectionKeyboard({
+    sceneData,
+    selectedActorIds,
+    onSelectActorIds,
+    multiSelectMode,
+    onSetMultiSelectMode,
+    isPlaying,
+    commitScene: (next) => history.commit(formatJson(next)),
+  });
+  if (!sceneData && !viewport.hasRuntime()) {
+    return (
+      <>
+        <EditorHeader title={basename(path)} onToggleFiles={onToggleFiles} filesOpen={filesOpen} />
+        <EditorBody>
+          <div className={styles.inspector}>{error}</div>
+        </EditorBody>
+      </>
+    );
+  }
+  const selectedActor =
+    selectedActorIds.length === 1
+      ? sceneData?.actors.find((actor) => actor.id === selectedActorIds[0])
+      : undefined;
+  const actions = makeSceneActions({
+    sceneData,
+    commit: history.commit,
+    selectedActorIds,
+    onSelectActorIds,
+  });
+  const inspectorLabel = showMulti ? 'Multi-select' : selectedActor ? 'Inspector' : 'Scene';
+  const inspectorHint = showMulti
+    ? `${selectedActorIds.length} actor${selectedActorIds.length === 1 ? '' : 's'} selected`
+    : selectedActor
+      ? `actor ${selectedActor.id}`
+      : 'scene settings';
+  const playbackButtons = (
+    <PlaybackButtons
+      isPlaying={isPlaying}
+      setIsPlaying={setIsPlaying}
+      history={history}
+      navMode={navMode}
+      setNavMode={setNavMode}
+    />
+  );
+  const gizmoButtons = (
+    <GizmoModeButtons gizmoMode={gizmoMode} setGizmoMode={setGizmoMode} isPlaying={isPlaying} />
+  );
+  const actorButtons = (
+    <ActorToolButtons
+      sceneData={sceneData}
+      files={files}
+      models={models}
+      selectedActorIds={selectedActorIds}
+      onSelectActorIds={onSelectActorIds}
+      isPlaying={isPlaying}
+      onChange={onChange}
+      history={history}
+    />
+  );
+  return (
+    <>
+      <EditorHeader
+        title={sceneData?.name ?? basename(path)}
+        subtitle={
+          isPlaying ? 'WASD / arrows' : (error ?? `${sceneData?.actors.length ?? 0} actors`)
+        }
+        right={
+          <span className={styles.mobileOnly}>
+            {playbackButtons}
+            {actorButtons}
+          </span>
+        }
+        onToggleFiles={onToggleFiles}
+        filesOpen={filesOpen}
+      />
+      <EditorBody>
+        <div className={styles.sceneWorkspace}>
+          <div className={styles.sceneTools}>
+            <div className={styles.sceneToolsGroup}>{gizmoButtons}</div>
+            <div className={styles.sceneToolsGroup}>{playbackButtons}</div>
+            <div className={styles.sceneToolsGroup}>{actorButtons}</div>
+          </div>
+          <div className={cx(styles.stageWrap, !isPlaying && styles.stageWrapFull)}>
+            <div className={styles.stageCard}>
+              <ThreeCanvas
+                onSetup={viewport.onSetup}
+                onFrame={viewport.onFrame}
+                className={styles.stageCanvas}
+                onContextMenu={(event) => event.preventDefault()}
+                onPointerDown={isPlaying ? playPointer.onPointerDown : gesture.onPointerDown}
+                onPointerMove={isPlaying ? playPointer.onPointerMove : gesture.onPointerMove}
+                onPointerUp={isPlaying ? playPointer.onPointerUp : gesture.onPointerUp}
+                onPointerCancel={isPlaying ? playPointer.onPointerUp : gesture.onPointerUp}
+              />
+              {marquee && !isPlaying ? <MarqueeOverlay rect={marquee} /> : null}
+              {isPlaying && <SceneUI getRuntime={getPlayRuntime} />}
+            </div>
+          </div>
+          <aside {...inspectorSheet.rootProps}>
+            <div {...inspectorSheet.grabProps}>
+              <SheetGrabHandle label={inspectorLabel} hint={inspectorHint} />
+            </div>
+            <div className={cx(styles.sheetBody, styles.inspectorBody)}>
+              {showMulti ? (
+                <MultiSelectInspector
+                  count={selectedActorIds.length}
+                  onDelete={actions.deleteSelection}
+                  onDuplicate={actions.duplicateSelection}
+                  onDeselectAll={() => {
+                    onSelectActorIds([]);
+                    onSetMultiSelectMode(false);
+                  }}
+                />
+              ) : selectedActor ? (
+                <ActorInspector
+                  selectedActor={selectedActor}
+                  files={files}
+                  onSetComponent={actions.updateComponent}
+                  onAddBehavior={actions.addBehavior}
+                  onRemoveBehavior={actions.removeBehavior}
+                />
+              ) : (
+                <SceneInspector
+                  sceneData={sceneData}
+                  commit={(next) => history.commit(formatJson(next))}
+                />
+              )}
+            </div>
+          </aside>
+        </div>
+      </EditorBody>
+      <TouchControls getKeys={getRuntimeKeys} visible={isPlaying} />
+    </>
+  );
+}
+
+function MarqueeOverlay({ rect }) {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: rect.x,
+        top: rect.y,
+        width: rect.width,
+        height: rect.height,
+        border: '1px dashed rgba(255, 255, 255, 0.85)',
+        background: 'rgba(255, 255, 255, 0.12)',
+        pointerEvents: 'none',
+      }}
+    />
+  );
+}
+
+function PlaybackButtons({ isPlaying, setIsPlaying, history, navMode, setNavMode }) {
+  return (
+    <>
+      <IconButton
+        icon={isPlaying ? 'stop' : 'play'}
+        label={isPlaying ? 'Stop' : 'Play'}
+        active={isPlaying}
+        variant={isPlaying ? 'primary' : ''}
+        onClick={() => setIsPlaying(!isPlaying)}
+      />
+      <IconButton
+        icon="undo"
+        label="Undo"
+        onClick={history.undo}
+        disabled={!history.canUndo || isPlaying}
+      />
+      <IconButton
+        icon="redo"
+        label="Redo"
+        onClick={history.redo}
+        disabled={!history.canRedo || isPlaying}
+      />
+      <span style={{ width: 16 }} aria-hidden="true" />
+      <IconButton
+        icon="camera"
+        label="Navigate camera (drag orbits)"
+        active={navMode}
+        onClick={() => setNavMode((value) => !value)}
+        disabled={isPlaying}
+      />
+    </>
+  );
+}
+
+function GizmoModeButtons({ gizmoMode, setGizmoMode, isPlaying }) {
+  return (
+    <>
+      {GIZMO_MODES.map((mode) => (
+        <IconButton
+          key={mode.key}
+          icon={mode.icon}
+          label={mode.label}
+          active={gizmoMode === mode.key}
+          onClick={() => setGizmoMode(mode.key)}
+          disabled={isPlaying}
+        />
+      ))}
+    </>
+  );
+}
+
+function ActorToolButtons({
+  sceneData,
+  files,
+  models,
+  selectedActorIds,
+  onSelectActorIds,
+  isPlaying,
+  onChange,
+  history,
+}) {
+  const applyScene = (next) => onChange(formatJson(next));
+  const onAdd = () => {
+    const { sceneData: next, newId } = addActor(sceneData, files, models);
+    history.recordSnapshot();
+    applyScene(next);
+    onSelectActorIds([newId]);
+  };
+  const onDuplicate = () => {
+    if (selectedActorIds.length === 0) return;
+    const { sceneData: next, newIds } = duplicateActors(sceneData, selectedActorIds);
+    history.recordSnapshot();
+    applyScene(next);
+    if (newIds.length) onSelectActorIds(newIds);
+  };
+  const onRemove = () => {
+    if (selectedActorIds.length === 0) return;
+    history.recordSnapshot();
+    applyScene(removeActors(sceneData, selectedActorIds));
+    onSelectActorIds([]);
+  };
+  const hasSelection = selectedActorIds.length > 0;
+  return (
+    <>
+      <IconButton icon="plus" label="Add actor" onClick={onAdd} disabled={isPlaying} />
+      <IconButton
+        icon="clone"
+        label="Duplicate"
+        onClick={onDuplicate}
+        disabled={!hasSelection || isPlaying}
+      />
+      <IconButton
+        icon="trash"
+        label="Remove"
+        onClick={onRemove}
+        disabled={!hasSelection || isPlaying}
+      />
+    </>
+  );
+}
+
+function makeSceneActions({ sceneData, commit, selectedActorIds, onSelectActorIds }) {
+  function commitScene(next) {
+    commit(formatJson(next));
+  }
+  return {
+    updateComponent: (actorId, behaviorName, nextProps) =>
+      commitScene(setActorComponent(sceneData, actorId, behaviorName, nextProps)),
+    addBehavior: (actorId, behaviorName) => {
+      const Behavior = findBehaviorClass(behaviorName);
+      if (!Behavior) return;
+      commitScene(
+        setActorComponent(sceneData, actorId, behaviorName, { ...Behavior.defaultProps })
+      );
+    },
+    removeBehavior: (actorId, behaviorName) =>
+      commitScene(removeActorComponent(sceneData, actorId, behaviorName)),
+    deleteSelection: () => {
+      if (selectedActorIds.length === 0) return;
+      commitScene(removeActors(sceneData, selectedActorIds));
+      onSelectActorIds([]);
+    },
+    duplicateSelection: () => {
+      if (selectedActorIds.length === 0) return;
+      const { sceneData: next, newIds } = duplicateActors(sceneData, selectedActorIds);
+      commitScene(next);
+      if (newIds.length) onSelectActorIds(newIds);
+    },
+  };
+}
+
+// The viewport: edit runtime lifecycle, play runtime lifecycle, the camera
+// rig, the gizmo write-back, and the per-frame render.
+function useSceneViewport(args) {
+  const argsRef = useRef(args);
+  argsRef.current = args;
+  const editRuntimeRef = useRef(null);
+  const playRuntimeRef = useRef(null);
+  const playCameraRef = useRef(null);
+  const rigRef = useRef(null);
+  const canvasRef = useRef(null);
+  const gizmoDragRef = useRef({ recorded: false });
+  if (!editRuntimeRef.current) {
+    editRuntimeRef.current = makeScene(
+      args.sceneData ?? { actors: [] },
+      behaviorClasses,
+      args.models
+    );
+  }
+  useEffect(() => {
+    return () => {
+      editRuntimeRef.current?.dispose();
+      editRuntimeRef.current = null;
+    };
+  }, []);
+  // Reload the edit runtime when the scene text changes (reconciling load --
+  // groups and caches survive). Invalid JSON keeps the last good state.
+  useEffect(() => {
+    const current = argsRef.current;
+    if (current.sceneData) editRuntimeRef.current?.load(current.sceneData);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [args.text]);
+  useEffect(() => {
+    if (editRuntimeRef.current) editRuntimeRef.current.models = args.models;
+  }, [args.models]);
+  // Play runtime spins up on play and resets when the scene text changes
+  // mid-play, mirroring the 2d kit.
+  useEffect(() => {
+    if (!args.isPlaying) return undefined;
+    const current = argsRef.current;
+    if (!current.sceneData) return undefined;
+    const runtime = makeScene(current.sceneData, behaviorClasses, current.models);
+    playRuntimeRef.current = runtime;
+    return () => {
+      runtime.dispose();
+      playRuntimeRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [args.isPlaying, args.text]);
+  useEffect(() => {
+    rigRef.current?.setNavMode(args.navMode);
+  }, [args.navMode]);
+  useEffect(() => {
+    const rig = rigRef.current;
+    const runtime = editRuntimeRef.current;
+    if (!rig || !runtime) return;
+    const primaryId = args.selectedActorIds[0];
+    const actor = primaryId ? runtime.getActor(primaryId) : null;
+    if (!args.isPlaying && actor?.components.Transform) {
+      rig.gizmo.attach(runtime.actorGroup(primaryId));
+      rig.gizmo.setMode(args.gizmoMode);
+    } else {
+      rig.gizmo.detach();
+    }
+  }, [args.selectedActorIds, args.isPlaying, args.gizmoMode, args.text]);
+  useEffect(() => {
+    if (rigRef.current) applyGizmoSnap(rigRef.current.gizmo, getSnapSettings(args.sceneData));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [args.text]);
+  const onSetup = ({ canvas }) => {
+    canvasRef.current = canvas;
+    playCameraRef.current = new THREE.PerspectiveCamera(50, 1, 0.1, 2000);
+    const rig = createViewportRig({
+      canvas,
+      scene: editRuntimeRef.current.three,
+      onGizmoChange: (gizmo) => writeGizmoTransform(gizmo, argsRef, gizmoDragRef),
+      onGizmoDraggingChanged: (dragging) => {
+        if (dragging) gizmoDragRef.current = { recorded: false };
+      },
+    });
+    rig.setNavMode(argsRef.current.navMode);
+    applyGizmoSnap(rig.gizmo, getSnapSettings(argsRef.current.sceneData));
+    // Open the editor through the scene's own play camera (when it has one)
+    // so editing and playing share the same framing.
+    const playSpec = sceneCameraSpec(argsRef.current.sceneData);
+    if (playSpec) {
+      applyCameraSpec(rig.camera, playSpec);
+      rig.orbit.target.set(playSpec.targetX, playSpec.targetY, playSpec.targetZ);
+      rig.orbit.update();
+    }
+    rigRef.current = rig;
+    return () => {
+      rig.dispose();
+      rigRef.current = null;
+    };
+  };
+  const onFrame = ({ canvas, renderer, dt }) => {
+    const current = argsRef.current;
+    if (current.isPlaying && playRuntimeRef.current) {
+      const runtime = playRuntimeRef.current;
+      runtime.update(dt);
+      runtime.syncFrame(dt, {});
+      const camera = playCameraRef.current;
+      if (!fitRendererToCanvas(renderer, camera, canvas)) return;
+      applyCameraSpec(camera, runtime.camera ?? defaultCameraSpec);
+      runtime.activeCamera = camera;
+      renderer.render(runtime.three, camera);
+    } else if (editRuntimeRef.current && rigRef.current) {
+      const runtime = editRuntimeRef.current;
+      const rig = rigRef.current;
+      runtime.syncFrame(dt, {
+        selectedActorIds: current.selectedActorIds,
+        editPlaceholders: true,
+        showGrid: true,
+      });
+      if (!fitRendererToCanvas(renderer, rig.camera, canvas)) return;
+      rig.orbit.update();
+      runtime.activeCamera = rig.camera;
+      renderer.render(runtime.three, rig.camera);
+    }
+  };
+  return {
+    onSetup,
+    onFrame,
+    editRuntimeRef,
+    playRuntimeRef,
+    rigRef,
+    canvasRef,
+    hasRuntime: () => !!editRuntimeRef.current,
+  };
+}
+
+// Gizmo drag write-back: read the dragged group's transform into the actor's
+// Transform component (degrees, 2-decimal world units).
+function writeGizmoTransform(gizmo, argsRef, gizmoDragRef) {
+  const current = argsRef.current;
+  const group = gizmo.object;
+  const actorId = group?.userData.actorId;
+  if (!group || actorId == null || !current.sceneData) return;
+  if (!gizmoDragRef.current.recorded) {
+    current.recordSnapshot();
+    gizmoDragRef.current.recorded = true;
+  }
+  current.applyScene(
+    setActorComponent(current.sceneData, actorId, 'Transform', {
+      x: roundUnits(group.position.x),
+      y: roundUnits(group.position.y),
+      z: roundUnits(group.position.z),
+      rotationX: roundUnits(radiansToDegrees(group.rotation.x)),
+      rotationY: roundUnits(radiansToDegrees(group.rotation.y)),
+      rotationZ: roundUnits(radiansToDegrees(group.rotation.z)),
+      scaleX: roundUnits(group.scale.x),
+      scaleY: roundUnits(group.scale.y),
+      scaleZ: roundUnits(group.scale.z),
+    })
+  );
+}
+
+function getSnapSettings(sceneData) {
+  const rawSize = sceneData?.editor?.gridSize;
+  return {
+    enabled: sceneData?.editor?.snapToGrid ?? true,
+    gridSize: Number.isFinite(rawSize) && rawSize > 0 ? rawSize : DEFAULT_GRID_SIZE,
+  };
+}
+
+function snapDelta(delta, gridSize, enabled) {
+  if (!enabled) return delta;
+  return Math.round(delta / gridSize) * gridSize;
+}
+
+function collectMoveStarts(sceneData, actorIds) {
+  const starts = {};
+  const movingIds = new Set(actorIds);
+  for (const actor of sceneData.actors) {
+    if (!movingIds.has(actor.id)) continue;
+    const transform = actor.components.Transform;
+    if (!transform) continue;
+    starts[actor.id] = { x: transform.x ?? 0, z: transform.z ?? 0 };
+  }
+  return starts;
+}
+
+function moveActorsFromStarts(sceneData, actorIds, starts, dx, dz) {
+  if (actorIds.length === 0) return sceneData;
+  const movingIds = new Set(actorIds);
+  const next = structuredClone(sceneData);
+  let changed = false;
+  for (const actor of next.actors) {
+    if (!movingIds.has(actor.id)) continue;
+    const start = starts[actor.id];
+    const transform = actor.components.Transform;
+    if (!start || !transform) continue;
+    const nextX = roundUnits(start.x + dx);
+    const nextZ = roundUnits(start.z + dz);
+    if (transform.x === nextX && transform.z === nextZ) continue;
+    actor.components.Transform = { ...transform, x: nextX, z: nextZ };
+    changed = true;
+  }
+  return changed ? next : sceneData;
+}
+
+// Raycast a screen point onto a horizontal plane at `planeY`, in world units.
+function worldOnPlane(runtime, canvas, clientX, clientY, planeY) {
+  const camera = runtime.activeCamera;
+  if (!camera) return null;
+  const rect = canvas.getBoundingClientRect();
+  const ndc = {
+    x: ((clientX - rect.left) / rect.width) * 2 - 1,
+    y: -(((clientY - rect.top) / rect.height) * 2 - 1),
+  };
+  const raycaster = new THREE.Raycaster();
+  raycaster.setFromCamera(ndc, camera);
+  const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -planeY);
+  const hit = new THREE.Vector3();
+  if (!raycaster.ray.intersectPlane(plane, hit)) return null;
+  return { x: hit.x, z: hit.z };
+}
+
+function screenPoint(canvas, clientX, clientY) {
+  const rect = canvas.getBoundingClientRect();
+  return { x: clientX - rect.left, y: clientY - rect.top };
+}
+
+// Edit-mode pointer gestures, the same model as the 2d kit: tap select,
+// drag moves on the ground plane, shift toggles, long-press enters
+// multi-select, drag on empty space (shift or multi mode) marquees.
+function useSelectionGesture(args) {
+  const dragRef = useRef(null);
+  const argsRef = useRef(args);
+  argsRef.current = args;
+  const onPointerDown = useCallback((event) => {
+    const current = argsRef.current;
+    const runtime = current.viewport.editRuntimeRef.current;
+    const rig = current.viewport.rigRef.current;
+    if (current.isPlaying || current.navMode || !runtime || !current.sceneData) return;
+    if (event.button !== 0 || rig?.gizmoBusy()) return;
+    const canvas = event.currentTarget;
+    const screen = screenPoint(canvas, event.clientX, event.clientY);
+    const actor = runtime.actorAtScreen(canvas, event.clientX, event.clientY);
+    const planeY = actor?.components.Transform?.y ?? 0;
+    try {
+      canvas.setPointerCapture(event.pointerId);
+    } catch {
+      // Synthetic / already-released pointers can't be captured.
+    }
+    const drag = {
+      pointerId: event.pointerId,
+      canvas,
+      startScreen: screen,
+      planeY,
+      startWorld: worldOnPlane(runtime, canvas, event.clientX, event.clientY, planeY),
+      startedOnActorId: actor?.id ?? null,
+      modeAtStart: current.multiSelectMode,
+      movedFar: false,
+      longPressTimer: null,
+      longPressFired: false,
+      kind: 'idle',
+      pendingMarquee: false,
+      movingActorIds: [],
+      moveStarts: {},
+      recordedMoveSnapshot: false,
+      selectionBeforeMarquee: [...current.selectedActorIds],
+    };
+    if (event.shiftKey) {
+      handleShiftPointerDown(drag, actor, current);
+    } else if (current.multiSelectMode) {
+      handleModePointerDown(drag, actor, current);
+    } else {
+      handleDefaultPointerDown(drag, actor, screen, current);
+    }
+    drag.moveStarts = collectMoveStarts(current.sceneData, drag.movingActorIds);
+    dragRef.current = drag;
+  }, []);
+  const onPointerMove = useCallback((event) => {
+    const drag = dragRef.current;
+    const current = argsRef.current;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    const runtime = current.viewport.editRuntimeRef.current;
+    if (!runtime || !current.sceneData) return;
+    const screen = screenPoint(drag.canvas, event.clientX, event.clientY);
+    const screenDistance = Math.hypot(
+      screen.x - drag.startScreen.x,
+      screen.y - drag.startScreen.y
+    );
+    if (!drag.movedFar && screenDistance > DRAG_THRESHOLD_PX) {
+      drag.movedFar = true;
+      if (drag.longPressTimer !== null) {
+        window.clearTimeout(drag.longPressTimer);
+        drag.longPressTimer = null;
+      }
+      if (drag.pendingMarquee && drag.kind === 'idle') drag.kind = 'marquee';
+    }
+    if (drag.kind === 'move' && drag.movedFar && drag.startWorld) {
+      const world = worldOnPlane(runtime, drag.canvas, event.clientX, event.clientY, drag.planeY);
+      if (!world) return;
+      const snap = getSnapSettings(current.sceneData);
+      const dx = snapDelta(world.x - drag.startWorld.x, snap.gridSize, snap.enabled);
+      const dz = snapDelta(world.z - drag.startWorld.z, snap.gridSize, snap.enabled);
+      const nextScene = moveActorsFromStarts(
+        current.sceneData,
+        drag.movingActorIds,
+        drag.moveStarts,
+        dx,
+        dz
+      );
+      if (nextScene === current.sceneData) return;
+      if (!drag.recordedMoveSnapshot) {
+        current.recordSceneSnapshot();
+        drag.recordedMoveSnapshot = true;
+      }
+      current.applyScene(nextScene);
+    } else if (drag.kind === 'marquee') {
+      current.setMarquee({
+        x: Math.min(drag.startScreen.x, screen.x),
+        y: Math.min(drag.startScreen.y, screen.y),
+        width: Math.abs(screen.x - drag.startScreen.x),
+        height: Math.abs(screen.y - drag.startScreen.y),
+      });
+    }
+  }, []);
+  const onPointerUp = useCallback((event) => {
+    const drag = dragRef.current;
+    const current = argsRef.current;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    if (drag.longPressTimer !== null) {
+      window.clearTimeout(drag.longPressTimer);
+      drag.longPressTimer = null;
+    }
+    if (drag.kind === 'marquee') {
+      finalizeMarquee(drag, current, event);
+    } else if (drag.kind === 'idle' && !drag.movedFar && !drag.longPressFired) {
+      handleTap(drag, current);
+    }
+    current.setMarquee(null);
+    dragRef.current = null;
+  }, []);
+  return { onPointerDown, onPointerMove, onPointerUp };
+}
+
+function handleShiftPointerDown(drag, actor, current) {
+  if (actor) {
+    const wasSelected = current.selectedActorIds.includes(actor.id);
+    const nextIds = wasSelected
+      ? current.selectedActorIds.filter((id) => id !== actor.id)
+      : [...current.selectedActorIds, actor.id];
+    current.onSelectActorIds(nextIds);
+    if (!wasSelected) {
+      drag.kind = 'move';
+      drag.movingActorIds = nextIds;
+    }
+  } else {
+    drag.pendingMarquee = true;
+  }
+}
+
+function handleModePointerDown(drag, actor, current) {
+  if (actor) {
+    if (current.selectedActorIds.includes(actor.id)) {
+      drag.kind = 'move';
+      drag.movingActorIds = [...current.selectedActorIds];
+    }
+    // else: leave kind='idle' so pointerup triggers the tap-toggle path.
+  } else {
+    // Defer marquee until movement, so a stationary press/release reaches
+    // the tap handler (which exits multi mode on empty tap).
+    drag.pendingMarquee = true;
+  }
+}
+
+function handleDefaultPointerDown(drag, actor, screen, current) {
+  if (actor) {
+    if (!current.selectedActorIds.includes(actor.id)) {
+      current.onSelectActorIds([actor.id]);
+      drag.movingActorIds = [actor.id];
+    } else {
+      drag.movingActorIds = [...current.selectedActorIds];
+    }
+    drag.kind = 'move';
+    drag.longPressTimer = window.setTimeout(() => {
+      if (drag.movedFar) return;
+      drag.longPressFired = true;
+      current.onSetMultiSelectMode(true);
+    }, LONG_PRESS_MS);
+  } else {
+    current.onSelectActorIds([]);
+    drag.longPressTimer = window.setTimeout(() => {
+      if (drag.movedFar) return;
+      drag.longPressFired = true;
+      current.onSetMultiSelectMode(true);
+      drag.kind = 'marquee';
+      current.setMarquee({ x: screen.x, y: screen.y, width: 0, height: 0 });
+    }, LONG_PRESS_MS);
+  }
+}
+
+function finalizeMarquee(drag, current, event) {
+  const runtime = current.viewport.editRuntimeRef.current;
+  if (!runtime || !current.sceneData) return;
+  const screen = screenPoint(drag.canvas, event.clientX, event.clientY);
+  const rect = {
+    x: Math.min(drag.startScreen.x, screen.x),
+    y: Math.min(drag.startScreen.y, screen.y),
+    width: Math.abs(screen.x - drag.startScreen.x),
+    height: Math.abs(screen.y - drag.startScreen.y),
+  };
+  if (rect.width === 0 && rect.height === 0) return;
+  const hits = runtime.actorIdsInScreenRect(drag.canvas, rect);
+  const merged = new Set(drag.selectionBeforeMarquee);
+  for (const id of hits) merged.add(id);
+  current.onSelectActorIds([...merged]);
+}
+
+function handleTap(drag, current) {
+  if (!drag.modeAtStart) return;
+  if (drag.startedOnActorId !== null) {
+    const id = drag.startedOnActorId;
+    const wasSelected = current.selectedActorIds.includes(id);
+    current.onSelectActorIds(
+      wasSelected
+        ? current.selectedActorIds.filter((x) => x !== id)
+        : [...current.selectedActorIds, id]
+    );
+  } else {
+    current.onSetMultiSelectMode(false);
+    current.onSelectActorIds([]);
+  }
+}
+
+function useSelectionKeyboard(args) {
+  const ref = useRef(args);
+  ref.current = args;
+  useEffect(() => {
+    function onKeyDown(event) {
+      const current = ref.current;
+      if (current.isPlaying || isEditableTarget(event.target)) return;
+      if (event.key === 'Escape') {
+        if (current.selectedActorIds.length || current.multiSelectMode) {
+          event.preventDefault();
+          current.onSelectActorIds([]);
+          current.onSetMultiSelectMode(false);
+        }
+        return;
+      }
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'a') {
+        if (!current.sceneData) return;
+        event.preventDefault();
+        current.onSelectActorIds(current.sceneData.actors.map((actor) => actor.id));
+        return;
+      }
+      if (event.key === 'Delete' || event.key === 'Backspace') {
+        if (!current.sceneData || current.selectedActorIds.length === 0) return;
+        event.preventDefault();
+        current.commitScene(removeActors(current.sceneData, current.selectedActorIds));
+        current.onSelectActorIds([]);
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, []);
+}
+
+function useSelectionInspectorSheet(open) {
+  const [snap, setSnap] = useState('high');
+  // Inspector visibility is driven by selection / multi-mode. Snap state
+  // persists across selections so switching keeps the user's chosen snap.
+  const effectiveSnap = open ? snap : 'hidden';
+  return useMobileSheet({
+    snap: effectiveSnap,
+    baseClassName: styles.inspector,
+    onTransition: (direction) => {
+      if (!open) return;
+      if (direction === 'tap') setSnap((prev) => (prev === 'high' ? 'low' : 'high'));
+      else if (direction === 'down') setSnap('low');
+      else if (direction === 'up') setSnap('high');
+    },
+  });
+}
+
+function MultiSelectInspector({ count, onDelete, onDuplicate, onDeselectAll }) {
+  return (
+    <div style={{ padding: '14px 16px', display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <div style={{ fontSize: 13, opacity: 0.8 }}>
+        {count === 0
+          ? 'Multi-select mode -- tap actors to add'
+          : `${count} actor${count === 1 ? '' : 's'} selected`}
+      </div>
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+        <button
+          type="button"
+          onClick={onDuplicate}
+          disabled={count === 0}
+          style={inspectorActionStyle(count === 0)}>
+          <Icon name="clone" /> Duplicate
+        </button>
+        <button
+          type="button"
+          onClick={onDelete}
+          disabled={count === 0}
+          style={inspectorActionStyle(count === 0)}>
+          <Icon name="trash" /> Delete
+        </button>
+        <button type="button" onClick={onDeselectAll} style={inspectorActionStyle(false)}>
+          <Icon name="times" /> Deselect all
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function inspectorActionStyle(disabled) {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 6,
+    padding: '6px 10px',
+    background: 'transparent',
+    color: 'inherit',
+    border: '1px solid var(--castle-inspector-divider)',
+    borderRadius: 6,
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.5 : 1,
+    fontSize: 13,
+  };
+}
+
+function SceneInspector({ sceneData, commit }) {
+  const snapSettings = getSnapSettings(sceneData);
+  const onChangeScene = (nextScene) => commit({ ...sceneData, ...nextScene });
+  const onChangeEditor = (nextEditor) =>
+    commit({ ...sceneData, editor: { ...(sceneData.editor ?? {}), ...nextEditor } });
+  const onChangeLighting = (nextLighting) =>
+    commit({ ...sceneData, lighting: { ...(sceneData.lighting ?? {}), ...nextLighting } });
+  return (
+    <>
+      <Panel title="Scene">
+        <TextField
+          label="Name"
+          value={sceneData.name ?? ''}
+          onChange={(name) => onChangeScene({ name })}
+        />
+        <ColorField
+          label="Background"
+          value={sceneData.background ?? '#10131c'}
+          onChange={(background) => onChangeScene({ background })}
+        />
+        <CheckboxField
+          label="Snap to grid"
+          checked={snapSettings.enabled}
+          onChange={(snapToGrid) => onChangeEditor({ snapToGrid })}
+        />
+        <NumberField
+          label="Grid size"
+          value={snapSettings.gridSize}
+          min={0.25}
+          step={0.25}
+          onChange={(gridSize) => onChangeEditor({ gridSize })}
+        />
+      </Panel>
+      <Panel title="Lighting">
+        <AutoFields
+          defaultProps={defaultLighting}
+          component={sceneData.lighting ?? {}}
+          setComponent={onChangeLighting}
+        />
+      </Panel>
+    </>
+  );
+}
+
+function ActorInspector({ selectedActor, files, onSetComponent, onAddBehavior, onRemoveBehavior }) {
+  const presentNames = new Set(
+    Object.entries(selectedActor.components)
+      .filter(([, component]) => !!component)
+      .map(([behaviorName]) => behaviorName)
+  );
+  const availableBehaviors = behaviorClasses.filter(
+    (candidate) => !presentNames.has(candidate.behaviorName)
+  );
+  const behaviorEntries = Object.entries(selectedActor.components).filter((entry) => !!entry[1]);
+  return (
+    <>
+      <AddBehaviorPicker
+        available={availableBehaviors}
+        onAdd={(behaviorName) => onAddBehavior(selectedActor.id, behaviorName)}
+      />
+      {behaviorEntries.map(([behaviorName, component], index) => {
+        const Behavior = behaviorClasses.find(
+          (candidate) => candidate.behaviorName === behaviorName
+        );
+        const Inspector = Behavior?.Inspector;
+        const body = Inspector ? (
+          <Inspector
+            actor={selectedActor}
+            component={component}
+            files={files}
+            setComponent={(nextProps) => onSetComponent(selectedActor.id, behaviorName, nextProps)}
+          />
+        ) : (
+          <AutoInspector
+            behaviorName={behaviorName}
+            defaultProps={Behavior?.defaultProps ?? component}
+            component={component}
+            setComponent={(nextProps) => onSetComponent(selectedActor.id, behaviorName, nextProps)}
+          />
+        );
+        // Transform is core to every actor -- it cannot be removed.
+        const removable = behaviorName !== 'Transform';
+        const isLast = index === behaviorEntries.length - 1;
+        // Trash renders before the panel so the panel stays the wrapper's
+        // last child -- the panel's own `:last-child` border zeroes out, and
+        // this wrapper owns the divider between panels deterministically.
+        return (
+          <div
+            key={behaviorName}
+            style={{
+              position: 'relative',
+              borderBottom: isLast ? undefined : '1px solid var(--castle-inspector-divider)',
+            }}>
+            {removable ? (
+              <button
+                type="button"
+                aria-label={`Remove ${behaviorName}`}
+                title={`Remove ${behaviorName}`}
+                onClick={() => onRemoveBehavior(selectedActor.id, behaviorName)}
+                style={{
+                  position: 'absolute',
+                  top: 14,
+                  right: 16,
+                  border: 'none',
+                  background: 'transparent',
+                  padding: 0,
+                  margin: 0,
+                  cursor: 'pointer',
+                  color: 'inherit',
+                  fontSize: 16,
+                  lineHeight: 1,
+                }}>
+                <Icon name="trash" />
+              </button>
+            ) : null}
+            {body}
+          </div>
+        );
+      })}
+    </>
+  );
+}
+
+function AddBehaviorPicker({ available, onAdd }) {
+  if (!available.length) return null;
+  return (
+    <div
+      style={{
+        padding: '12px 16px',
+        borderBottom: '1px solid var(--castle-inspector-divider)',
+      }}>
+      <div style={{ position: 'relative' }}>
+        <select
+          className={styles.select}
+          value=""
+          onChange={(event) => {
+            if (event.target.value) onAdd(event.target.value);
+          }}
+          style={{
+            appearance: 'none',
+            WebkitAppearance: 'none',
+            MozAppearance: 'none',
+            paddingRight: 30,
+          }}>
+          <option value="">+ Add behavior</option>
+          {available.map((behavior) => (
+            <option key={behavior.behaviorName} value={behavior.behaviorName}>
+              {behavior.behaviorName}
+            </option>
+          ))}
+        </select>
+        <span
+          style={{
+            position: 'absolute',
+            right: 11,
+            top: '50%',
+            transform: 'translateY(-50%)',
+            pointerEvents: 'none',
+            fontSize: 12,
+            opacity: 0.6,
+          }}>
+          <Icon name="chevron-down" />
+        </span>
+      </div>
+    </div>
+  );
+}